Upgrade and compatibility

NYXDB currently has no rolling-upgrade or mixed-version cluster contract. An upgrade of the only node is an offline restart and creates an outage.

Do not assume a new binary can open an old data directory, or that an old binary can reopen a directory after a new revision has written it. Proceed only when the target release notes explicitly support the on-disk transition you intend.

Compatibility dimensions

Review each dimension independently:

Dimension	Required evidence
SQL	Parser/binder conformance and application query smoke tests
Catalog/on-disk data	Release-specific migration/compatibility statement and restart test on a copy
WAL/checkpoints/parts	Recovery test from a production-like pre-upgrade copy
Wire/client	Matching-revision smoke tests for every deployed driver
Experimental features	Feature-specific migration notes and correctness tests
Native function modules	Exact ABI/build compatibility and module load tests
Backup format	New tool lists/restores the retained pre-upgrade manifest

Pre-upgrade gate

Pin the target artifact by digest/revision and archive --capabilities, --readiness, and --help output.
Read all release notes between current and target revisions.
Run the target against a disposable restored copy of current production data.
Exercise representative DDL, DML, reads, streams/transforms in use, restart recovery, and native backup.
Create a fresh production backup and record its manifest, frontier, checksum evidence, and repository location.
Restore that backup into an empty drill target and validate data before the maintenance window.
Freeze schema/storage-topology changes and stop application traffic.
Confirm enough outage time for clean shutdown, recovery, validation, and the chosen rollback procedure.

Backup creation alone is not the gate; a successful restore is.

Offline procedure

Send SIGTERM to the existing process.
Wait for clean exit and confirm the supervisor did not force-kill it.
Preserve the old artifact, complete command line, logs, and data-volume identity.
Replace the image/binary with the pinned target.
Start it against the same data directory only when the release-specific on-disk transition is supported.
Wait for recovery and listener-ready completion.
Confirm the build revision in logs and compare capabilities.
Run protocol ping, SELECT 1, catalog/SHOW CREATE checks, and representative reads/writes.
Inspect system.events, system.metrics, system.parts, system.queries, system.subscriptions, and any transforms in use.
Create and list a post-upgrade backup before ending heightened monitoring.

Rollback decision

Binary reversal is safe only when release notes explicitly state that the old revision can reopen every on-disk structure written by the new one. A successful startup is not sufficient proof.

The safest general rollback is:

stop the target revision cleanly;
select the verified pre-upgrade manifest;
restore it into a new empty data directory;
require a successful command and RESTORE_READY;
start the old pinned artifact against that restored directory; and
validate build identity, catalog, data, protocol, and application behavior.

This discards writes accepted after the pre-upgrade frontier. Make that data-loss boundary explicit before reopening traffic.

Never use a live recursive copy of --data-dir as an ad hoc rollback image, and never start a target that contains only RESTORE_IN_PROGRESS.

Post-upgrade observation

For at least one normal workload cycle, compare:

connection and admission saturation;
query failures, latency, memory, and output-limit events;
committed-tail drain, part count, compaction, and disk use;
stream lag/overflow and transform terminal errors;
recovery/startup duration;
backup fence, lag, throughput, and restore validation; and
application-level data invariants.

Keep the pre-upgrade manifest until this observation period and a post-upgrade restore drill are complete.