3.0 KiB
保存schema変更の開発規則
公開またはドッグフーディングで使用したmigrationは、対応する保存データを更新できる限り保持する。新しいmigrationを追加したことだけを理由に、直前のmigrationを削除しない。
schema変更では、既存の順序付きmigrationへ新しい処理を追加し、新規DBの作成結果も同じschemaへ揃える。適用済みmigrationの名前や内容を、語彙を統一するだけの目的で書き換えない。schema一覧はコードを正本とし、文書へ複製しない。
検証には、最古の対応schemaからの更新、保存値と制約の維持、新規作成結果との一致、失敗時のrollbackを含める。途中まで完了した更新の再開や、元DBを変更しないdry-runを提供する場合は、その保証も実装経路で確認する。schema番号だけのassertionでは不足する。
古いbaselineの対応終了は、対象となる保存データを移行または明示的に破棄する判断を含め、独立にレビューする。残す最古のschema、移行・破棄の責任、影響するテストを明記する。所有storeのmigration経路と検証を共用し、起動・管理操作ごとに別のDDL判定を増やさない。
Session履歴の移行
旧Host compactionのoriginはSession storeのversioned migrationで永続的に更新する。通常復元やpublic readerでは文字列markerによる読み替えを行わない。本文・logical entry ID・derivationを維持し、位置由来のRun boundary IDは書換え前のoffsetから保存する。StandaloneのSessionも同じ変換を使う。
Runtimeの移行はowner lock下のstaging treeで停止中Worker・orphan・移行可能な既存Session archiveを更新し、成功したtreeだけを公開する。全treeのコピーに必要な空き容量が必要。書込み失敗時は元treeを維持し、切替中の中断は既存のstaging/backup回復経路で扱う。履歴archiveの読取り・検証・変換不能はServer全体の起動条件にせず、書込み前のpreflightでそのarchiveだけを除外する。除外した原本と取り込み証拠は変更せず、警告と利用時の利用不能応答で示す。Runtime・Workerの正本や削除権限の異常、移行結果の公開失敗まで握り潰さない。
Archiveのmanifest.jsonはBackend catalogと完了receiptにも保存された取り込み時の証拠なので変更しない。移行前のchecksumを検証したうえでpayloadを現行形式に置換し、元manifest全体と現行payloadのchecksum/bytes/file countを結ぶsession-storage.jsonを同じtree切替で公開する。移行に成功した旧payloadは読取り用に残さず、移行不能で保持した旧payloadも現行readerでは受理しない。通常のarchive検証では現行payloadを検証し、APIとoperation replayには元の取り込みreceiptを返す。移行後の削除再試行では、現行原本とarchiveの現行storage summaryが一致することを要求する。