Upgrade and Migration

Ключевой операторский контракт pre-v1 по on-disk формату и процедурам migration.

Goal

Зафиксировать fail-closed правила:

layout данных и WAL;
форматные version/magic;
startup guards;
обязательные действия при изменении on-disk формата.

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 (бинарный AVR1, CRC32C)

MVCC history хранится в .atl; отдельный mvcc_history.v1.bin больше не создаётся.

Startup behavior (fail-closed)

non-dev запуск без VERSION → reject.
Текстовый legacy VERSION не поддерживается.
format_version выше/ниже поддерживаемого → reject.
page_size из VERSION не совпадает с compiled PAGE_SIZE → reject.

Format identifiers

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

Единый source of truth для magic/version:

crates/angarabase/src/on_disk.rs

Offline migration baseline

Рекомендуемый общий путь:

Backup старого состояния.
--init в новом формате.
Restore данных.
Пост-проверки startup и recovery.

In-place migration pre-v1 ограничена и должна выполняться только по документированному runbook-пути.

Upgrade rehearsal

Перед production rollout:

прогон репетиции обновления на staging;
фиксация артефактов в evidence;
проверка rollback-плана.

Подробные процедуры:

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

Дальше

Backup and restore (operator-level) — обязательный шаг до старта апгрейда.
Disaster recovery playbook — сценарии rollback и восстановления при неудачном апгрейде.
Replication v2 operations guide — апгрейд в схеме с активной репликацией.