Skip to content
ChronactaChronactaChronacta Docs

Upgrade guide

How to upgrade Chronacta between versions without losing committed events. Read compatibility policy first.

Before any upgrade

Section titled “Before any upgrade”
  1. Backup — ./bin/chronacta backup create -archive ./backups/pre-upgrade-$(date +%Y%m%d).tar.gz
  2. Verify — ./bin/chronacta verify (server running) or chronacta-admin verify-db (offline)
  3. Record versions — server tag/commit, go version, config (config.yaml or env)
  4. Note cluster role — standalone vs cluster; leader id if HA (cluster status)

Single-node upgrade

Section titled “Single-node upgrade”
  1. Read the target release notes for breaking changes and migration requirements.
  2. Create a backup and verify the current data directory.
  3. Stop the server gracefully and replace the binary.
  4. If the release notes explicitly require a storage migration, follow that release-specific procedure before the first append.
  5. Start the server and run health, verify, and an append/read smoke test.
  6. Rebuild projections only when the release notes require it.

Major upgrades

Section titled “Major upgrades”

Follow the target release notes. A major release may require export/import, an offline storage migration, projection rebuild, or backup restore. Do not start the new binary against production data until the documented procedure is complete.

HA cluster upgrade

Section titled “HA cluster upgrade”

Use HA rolling upgrade in addition to steps below.

Preconditions

Section titled “Preconditions”
  • Quorum healthy; replication_lag near zero on leader.
  • All nodes should use the same minor release before rolling; any temporary version skew must be explicitly supported by the target release notes.

Order

Section titled “Order”
  1. Backup from leader.
  2. Upgrade followers one at a time; wait for lag = 0.
  3. Optional: chronacta cluster promote to move leadership before upgrading old leader.
  4. Upgrade leader last (or former leader after promote).
  5. chronacta cluster status — epoch, leader, membership unchanged except expected promote bump.

Version skew during roll

Section titled “Version skew during roll”
  • Allowed: patch skew between nodes for short window during rolling upgrade.
  • Not allowed: different major or incompatible disk format without snapshot/restore plan.

After cluster upgrade

Section titled “After cluster upgrade”
Terminal window
./bin/chronacta cluster status
./bin/chronacta append -stream upgrade-smoke -type Smoke -data '{}' -expected-version -2

Confirm follower catch-up via read on follower address (eventual consistency).

Downgrade

Section titled “Downgrade”

Not supported after a release that bumped on-disk format_version.

If upgrade failed before new writes:

  1. Stop new binary.
  2. Restore previous binary and same data/ snapshot from pre-upgrade backup if any WAL was written by new version.

If new version wrote data with higher format version, restore from backup or export taken before upgrade.

Recovery options by subsystem

Section titled “Recovery options by subsystem”
Subsystem Safe upgrade If incompatible
WAL / segments Same record FormatVersion Restore backup or export/import
Projections Rebuild from stream projection rebuild
Schemas Additive registry Re-register schemas if needed
Subscriptions Same store version Replay from checkpoint
Idempotency keys Same store version Keys file portable within minor
Cluster metadata Rolling upgrade doc Restore data/cluster/ from backup
NATS bridge Checkpoint replay integration nats replay

Export/import for environment changes

Section titled “Export/import for environment changes”

When direct upgrade is unclear:

  1. Export all events to JSONL or binary.
  2. Deploy the target release with an empty data directory.
  3. Import with -duplicate-policy reject_existing_stream.

Use for cross-environment moves and major jumps when documented.

Configuration changes

Section titled “Configuration changes”
  • New env vars in release notes default to old behavior when unset.
  • Review config.yaml against release notes; merge new keys before start.
  • Auth enabled mid-upgrade: plan token distribution before restart.

Troubleshooting

Section titled “Troubleshooting”
Symptom Likely cause Action
unsupported record version Binary newer than data migrated Restore backup or run migration
backup archive is incompatible Backup from newer server Use matching server or export/import
version mismatch on append Wrong -expected-version Use -1 or exact version from stream-info
not cluster leader Writing to follower Use leader address or cluster status
Projections stalled after upgrade Checkpoint format Rebuild projection

Checklist (printable)

Section titled “Checklist (printable)”
[ ] Backup created and stored off-node
[ ] Release notes read for target version
[ ] Pre-release smoke tests understood
[ ] Single-node OR cluster rolling plan written
[ ] Projections/subscriptions/NATS impact reviewed
[ ] Rollback = previous binary + backup identified
[ ] Post-upgrade verify + smoke append completed
Section titled “Related”