Refactor architecture into eight components and consolidate reliability work
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s

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.
This commit is contained in:
Anya Tokugawa committed 2026-11-01 15:23:31 +09:00
1 parent 9dd425f765
commit d5d21b7841
302 files changed
+20037 -3492

No files matched your search

+124
View File
@@ -0,0 +1,124 @@
# 保存基盤のスキーマ変更・反映手順
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 の移行は上記を完了・検証した段階で別途実施する。