Upgrade and Migration

Key pre-v1 operator contract for on-disk format and migration procedures.

Goal

Pin fail-closed rules:

• data and WAL layout;
• format version/magic;
• startup guards;
• required actions when the on-disk format changes.

Current on-disk layout (as implemented)

• System DB data: base.adb
• System DB WAL: base.atl
• User DB data: <db_name>.adb
• User DB WAL: <db_name>.atl
• Init marker: VERSION (binary AVR1, CRC32C)

MVCC history is stored in .atl; separate mvcc_history.v1.bin is no longer created.

Startup behavior (fail-closed)

• non-dev startup without VERSION → reject.
• Text legacy VERSION is not supported.
• format_version above/below supported → reject.
• page_size from VERSION does not match compiled PAGE_SIZE → reject.

Format identifiers

• Storage page magic/version: APG1 / v3
• WAL record magic/version: ADB1 / v2 (v3 planned)

Single source of truth for magic/version:

• crates/angarabase/src/on_disk.rs

Offline migration baseline

Recommended general path:

1. Back up the old state.
2. Run --init in the new format.
3. Restore data.
4. Post-check startup and recovery.

In-place migration pre-v1 is limited and must be performed only through a documented runbook path.

Upgrade rehearsal

Before production rollout:

• run an upgrade rehearsal on staging;
• record artifacts in evidence;
• verify the rollback plan.

Detailed procedures:

• src/operations/testing-validation.md
• src/operations/backup-restore.md

Next

• Backup and restore (operator-level) — required step before starting the upgrade.
• Disaster recovery playbook — rollback and recovery scenarios for a failed upgrade.
• Replication v2 operations guide — upgrade in an active replication setup.