Files
pages/docs/operations/storage-schema-rollout.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

125 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 保存基盤のスキーマ変更・反映手順
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 の移行は上記を完了・検証した段階で別途実施する。