Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
7.8 KiB
保存基盤のスキーマ変更・反映手順
2026-09-27。保存基盤の段階移行に関する運用メモ。 本書の作成時点では開発用の一時 DB で検証しており、本番 DB への適用を意味しない。 詳細は 保存基盤の設計 を参照。
今回の変更と別の DB 操作との関係
別の DB 修正、復旧、import、DB-only CLI 書き込みと同時に適用しない。 先に使用するバイナリ・スキーマ・保存先の組み合わせを決め、整合バックアップを取得する。 ソースの実装完了と、本番への migration 適用完了は別の状態である。
アプリケーションを新しいコードで起動すると、以下を実行する。
schema_migration_stepsに component/version/name/checksum/適用時刻を記録する。document_backfillsと保存先の.document-store-idにより、本文移行の進捗を管理する。- プレビューのメタデータ、リソース履歴、アナウンス、ブラウザナビゲーション、 アダプタセッション、インポート履歴、イベントキュー/ログを migration 管理下へ取り込む。
- 古い DB で不足していれば
browser_navigation_links.is_directory、adapter_sessions.root_path/principal_uuid、import_journal.completedを追加する。event_jobsの既知の追加列も存在を検査してから追加し、ALTER の失敗を握りつぶさない。 - イベントキューのスキーマ検証後、通常起動時のみ中断ジョブを再キューイングする。 読み取り専用の事前チェックではこの復旧処理を呼ばない。
現在の既存コードですでに追加済みの列は重複して追加しない。
対象テーブルの再作成、既存行の削除、本文の一括書き換えは行わない。
旧式の 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 サーバーを起動せず実行できる。
./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 は状態確認用で、テーブルを作成しない。
SELECT name FROM sqlite_master
WHERE type='table'
AND name IN ('schema_migration_steps', 'document_backfills');
テーブルが存在する場合のみ、続けて確認する。
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 の移行は上記を完了・検証した段階で別途実施する。