# 保存基盤のスキーマ変更・反映手順 2026-09-27。保存基盤の段階移行に関する運用メモ。 本書の作成時点では開発用の一時 DB で検証しており、本番 DB への適用を意味しない。 詳細は [保存基盤の設計](../design/storage-portability-and-operations.md) を参照。 ## 今回の変更と別の DB 操作との関係 別の DB 修正、復旧、import、DB-only CLI 書き込みと同時に適用しない。 先に使用するバイナリ・スキーマ・保存先の組み合わせを決め、整合バックアップを取得する。 ソースの実装完了と、本番への migration 適用完了は別の状態である。 アプリケーションを新しいコードで起動すると、以下を実行する。 1. `schema_migration_steps` に component/version/name/checksum/適用時刻を記録する。 2. `document_backfills` と保存先の `.document-store-id` により、本文移行の進捗を管理する。 3. プレビューのメタデータ、リソース履歴、アナウンス、ブラウザナビゲーション、 アダプタセッション、インポート履歴、イベントキュー/ログを migration 管理下へ取り込む。 4. 古い DB で不足していれば `browser_navigation_links.is_directory`、 `adapter_sessions.root_path` / `principal_uuid`、`import_journal.completed` を追加する。 `event_jobs` の既知の追加列も存在を検査してから追加し、ALTER の失敗を握りつぶさない。 5. イベントキューのスキーマ検証後、通常起動時のみ中断ジョブを再キューイングする。 読み取り専用の事前チェックではこの復旧処理を呼ばない。 現在の既存コードですでに追加済みの列は重複して追加しない。 対象テーブルの再作成、既存行の削除、本文の一括書き換えは行わない。 旧式の `schema_migrations` は削除/リネームしない。 認証・ACL、City、タスク、カレンダーを今回の 7 component に含めない。 別に `document-store` component が本文移行の進捗テーブルを管理する(合計 8 component)。 これらの既存起動時処理まで無変更になる、という意味ではない。 ## 反映前の確認 - SQLite の整合バックアップと Document / calendar 正本 / 鍵を同じ復旧点として保全する。 稼働中の DB ファイルだけをコピーして完了としない。 - DB とファイルを隔離したコピーを作り、新しいバイナリで起動試験する。 本番の FQDN、外部同期先、通知送信先へ接続しない環境で実施する。 - 新旧スキーマからの採用テストと全体回帰テストの結果を確認する。 - migration 定義の checksum 不一致、必要な列/索引/一意性制約の欠落があれば、 適用履歴を削除して回避せず、定義の変更か既存 DB の不整合かを調べる。 - 長い SQL transaction、DB-only writer、旧プロセスによる保守操作を停止してから反映する。 SQLite の `BEGIN IMMEDIATE` による短時間の排他が必要で、ロック競合はエラーになり得る。 - 初回 backfill は保存先内の未移行データを検証するため時間がかかることがある。 起動前に完了させ、通常の配信を先に始めない。完了後の起動では全 Revision を走査しない。 ## 読み取り専用で確認できる情報 ### schema CLI 新しいバイナリを用意した段階で、Web サーバーを起動せず実行できる。 ```sh ./pageswiki schema status --data-dir /path/to/data ./pageswiki schema check --db /path/to/data/pages.db --json --timeout 30s ``` `--data-dir` を省略した場合は `PAGESWIKI_DATA_DIR`、未設定なら `./data` を使う。 `--db` と明示的な `--data-dir` は同時指定しない。 - `status`:管理対象 component の適用済み/最新 version、未適用 step、契約検査結果を表示する。 読み取りに成功すれば終了コード 0。監視などで判定する場合は `check` を使う。 - `check`:管理対象すべてが current なら 0、pending があれば 2、 blocked/unknown があれば 1。DB 読み取り失敗や不正な引数も 1。 - `blocked`:履歴の欠落・checksum 不一致・対応 version より新しい履歴、 または適用済みスキーマが最新契約を満たしていない。 - `unknown`:DB に記録された component をこのバイナリが認識しない。 - `pending`:未適用の定義がある。まだ作られていない列/テーブルによる assertion の失敗も 併記するが、DDL の実行成功・失敗を予測した結果ではない。 `mode=ro` と `query_only` による読み取り専用接続、一つの読み取り transaction を使う。 DB/データディレクトリの作成、通常起動処理、鍵生成、本文 backfill、ジョブ復旧を実行しない。 稼働中 DB の committed WAL も参照する。SQLite の WAL/SHM ファイルのアクセス要件は必要で、 ファイルシステム上の一切のメタデータ変更がないことまで保証するモードではない。 **このコマンドは完全な移行リハーサルでも、全 DB の健全性検査でもない。** 出力の `coverage=managed-components-only` と `legacy_areas` を確認する。 終了コード 0 でも、未移行の従来初期化処理、正本ファイル、データ依存の移行、 外部接続の正常性は証明しない。隔離コピー上での起動試験を省略しない。 ### SQL による補助確認 DB のパスは実際の起動設定で確認し、SQLite クライアントを read-only モードで使用する。 次の SQL は状態確認用で、テーブルを作成しない。 ```sql SELECT name FROM sqlite_master WHERE type='table' AND name IN ('schema_migration_steps', 'document_backfills'); ``` テーブルが存在する場合のみ、続けて確認する。 ```sql SELECT component, version, name, checksum, applied_at_ms FROM schema_migration_steps ORDER BY component, version; SELECT store_id, last_uuid, processed, completed, updated_at_ms FROM document_backfills ORDER BY updated_at_ms DESC; ``` `completed=1` は「その保存先への初回移行が完了した」ことを示す。 すべての正本の現在の健全性を証明する値ではない。欠落や破損は verify/repair の対象とする。 `.document-store-id` は復旧対象に含める。空の保存先へ入れ替えた場合に、このファイルだけを コピーして完了状態を引き継がせない。 ## ロールバック・失敗時 DDL と migration 履歴の記録は同じ transaction で rollback する。 Document backfill はバッチ単位で進捗を確定し、失敗したバッチは次回再実行する。 すでに保存した不変 Document が残っていても、検証して再利用する。 起動失敗時には component/version とエラーを保存し、旧バイナリへの切り戻しを 無条件に行わない。旧バイナリが新しい migration 履歴を理解しない可能性があるため、 DB と正本のバックアップからの復旧か、互換性を検証済みの切り戻しを選ぶ。 DR standby ではこれらの schema 作成・採用を実行しない。 ## 残件 - 全 Ensure*Schema の集約と、型/CHECK/照合順序/外部キーまで含む schema 契約の拡充。 - DB ごとの差異を切り分け、PostgreSQL / MySQL の共通機能テストを整備。 - 本文の健全性/backfill 状態の専用診断、保守 CLI、進捗 UI と event queue の接続。 - 初回 backfill の非同期化に先立つ、未移行データの配信と readiness の設計。 外部 DB への接続や、本番 DB の移行は上記を完了・検証した段階で別途実施する。