# Rehearsing an alpha upgrade and rollback

The archived 0.1.0-alpha executable (d5b5e56) created the 32 MiB v1 test image in tests/fixtures/alpha-d5b5e56.ratdb.gz. Its decompressed SHA-256 is d6fc2263fa2f34f8355ee893369ce6d1499c0c1b533934aafc9d4452fff16b57. It has generation 4, a legacy default-warren document, a named-warren document using the same ID, an explicit empty den, nested values, Unicode, booleans and null. The fixture contains no credentials.

For an offline upgrade, stop the old server, keep its executable and instance directory, run the candidate executable's backup command against the old file, and restore the backup to a fresh candidate path. Check that path, set its credentials separately, start it and exercise representative reads before switching clients. Keep the original and verified backup through acceptance. For rollback before accepting new writes, restore the backup with the old executable to another unused path and start it with freshly configured credentials. After accepting new writes, restoring this older backup discards later commits; reconcile those writes before switching back.

Run `python -B scripts/upgrade_test.py PATH_TO_CURRENT_RATDB` on Windows or Linux x86-64 with the matching original archive under target/overnight-alpha-d5b5e56. The harness verifies the binary archive digest, decompresses the frozen fixture, and kills the upgrade coordinator at three explicit boundaries, after backup completion, candidate restoration, and candidate-only mutation. Every rollback starts an actual alpha server, compares catalog and typed values and checks its generation. Each scenario preserves the original file byte-for-byte. The Windows development build passed all three. These boundaries cover operator interruption between completed commands. Core and subprocess crash tests cover separate storage failure scenarios.

The only distributed release tested here is alpha d5b5e56. Production still uses format v1. The experimental page format has no migration or downgrade path in this rehearsal.