Files
pages/docs/operations/postgresql-migration.md
T
2026-11-15 05:47:14 +09:00

104 lines
8.0 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.
# PostgreSQL への停止移行
SQLite から PostgreSQL への片方向移行を、単一インスタンス・ローカルの正本ファイル配置で行う。
全 writer を停止し、空の専用 PostgreSQL database/schema へ転送する。既存 DB への merge、
オンライン差分同期、PostgreSQL から SQLite への逆移行は提供しない。
## 対応範囲と制限
検証対象は PostgreSQL 17。通常起動の既定値は引き続き SQLite である。
PostgreSQL 起動は verified TLS、全件 import の完了記録、既存の鍵と同じ絶対 Document root を必須とする。
DB 接続障害や検査失敗で SQLite に自動 fallback しない。
- native 検索は権限付きの Path・ファイル名・City メタデータ検索。本文全文検索は後続対応。
- hosted editor、Web Push 配信、zombie GC、ログの自動保持期限処理は native の停止ゲート対象。
設定・受付記録・既存データは保全する。内蔵エディタと Inbox を使用し、ログ・ファイル容量を監視する。
- DR/HA 構成への移行は拒否する。`pageswiki dr` と旧 `schema` コマンドは PostgreSQL 設定時に拒否する。
- DB 直結の `data/pageswiki-cli` は SQLite 専用。PostgreSQL では HTTP の `pages-cli` を使用する。
すべてのプロセスに backend 設定を統一し、旧 SQLite 用 CLI を起動しない。
- 外部カレンダーの実データを使った検査・再取得は行わない。検証用の予定・連絡先・タスクは合成データを使う。
## 移行前の準備
1. HTTP、CalDAV/CardDAV、CLI、scheduler、federation、外部の直接 DB writer を停止する。
コマンドは data directory の排他ロックを取るが、旧バイナリや直接 SQLite client の停止を代替しない。
2. 停止状態の data directory 全体を別の場所に保全する。SQLite と WAL、`documents`、カレンダー・タスク等の
正本ファイル、設定、`auth.key`、instance identity を同じ時点で保全する。
`PAGESWIKI_AUTH_KEY` を使用していた場合はその secret も別途保全し、移行時・起動時に同じ値を渡す。
3. 専用 PostgreSQL database/schema と、それを所有する移行ユーザーを用意する。
schema/table/trigger/identity の作成・変更権限が必要。共有アプリ DB を移行先にしない。
4. PostgreSQL の CA とホスト名を検証できる DSN を secret として用意する。
`PAGESWIKI_POSTGRES_DSN` に `sslmode=verify-full` と必要な `sslrootcert` を設定する。
DSN はコマンドラインやログに出さない。移行先の管理者による同時 schema 変更も停止する。
## コマンド
以下は、稼働時にも `/data` を使う場合の例。移行と起動で data directory の絶対パスを一致させる。
Docker では同じ `/data` マウントを使用する。別のホスト側絶対パスで import してから
コンテナ内 `/data` に切り替えると、root 検査により起動を拒否する。
```sh
# schema の読取り検査。移行先への接続・データコピーは行わない。
./pageswiki migrate-postgres --data-dir /data
# DSN は保護された環境設定から注入済みとする。
./pageswiki migrate-postgres --data-dir /data --apply --timeout 30m
# import 成功・保全確認後、同じ正本 root と鍵で起動する。
PAGESWIKI_DB_BACKEND=postgresql PAGESWIKI_DATA_DIR=/data ./pageswiki
```
`--apply` がない場合は schema preflight のみで、payload の検証成功を意味しない。
`--allow-insecure` は隔離試験専用の移行オプションであり、通常起動の TLS 検証は緩和しない。
未知のテーブル・列・trigger/view がある場合は処理を止め、保全分類と schema を修正して再試行する。
不明なデータを削除して検査を通さない。
## 転送と照合
保全対象は `internal/store/application_import_catalog.go` に列挙する。
SQLite 専用 FTS 索引・派生 latest revision index・SQLite migration ledger は除外するが、
設定、鍵への参照、認証、ACL、タスク、連絡先、同期番号、受付履歴、ジョブ・ログ等は保持する。
正本ファイルは同じ場所に残す。ファイル自体を別の volume へコピーするコマンドではない。
転送は単一 transaction。転送前に移行先の空状態を検査し、型を区別した各行の内容指紋・件数、
参照される Document の SHA-256、namespace の参照整合性を commit 前に検査する。
タスク DAV の内部索引だけは backend 形式の違いを明示的に変換する。変換後の内容指紋を照合し、
クライアント用 href・正本 JSON は保持する。削除履歴と削除済み最大採番も保全する。
JSON report は対象テーブルの件数と指紋、除外一覧、変換内容、Document 数、採番情報を返す。
本文や資格情報は含まない。成功時の report をバックアップと一緒に保管する。
失敗時はデータ転送を rollback する。準備済み schema は残り得るが、既定行だけの状態なら再試行できる。
完了済み import や既存データへの上書きは拒否する。
## 起動確認と復旧
書き込み再開前に、同じバイナリと設定で起動し、ログイン・既存 session・権限・本文・内蔵編集・
タスクのプロジェクト所属・DAV discovery/条件付き更新・連絡先・管理画面を確認する。
外部送信や取得を伴う worker の再開対象は事前に点検する。
この実装は import 済み DB を開くためのもので、空の PostgreSQL から既定 Campus を新規生成しない。
移行前 SQLite は凍結したまま保管する。書き込み再開後の新しい更新は PostgreSQL 側にしか存在しない。
旧 SQLite へ接続を戻すことはデータを引き継ぐ切り戻しではない。
PostgreSQL 運用のバックアップは、writer を停止した同じ時点の `pg_dump -Fc` と data directory 全体、
鍵・secret を組にする。復元先は空の専用 database/schema とし、`pg_restore --exit-on-error` で復元する。
ファイルを元と同じ絶対 mount path に復元し、接続先 DSN のみ変更する。
import 完了記録も dump に含める。DB 単独や正本ファイル単独のバックアップでは復元条件を満たさない。
復元後は停止状態で本文・参照・認証・DAV 同期の検証を実施してから writer を再開する。
## 検証とリリース前チェック
- 合成データで全件移行、途中失敗の rollback、再試行、上書き拒否、schema drift 拒否を検証する。
- 日本語本文・タグ、バイナリ画像、認証 session、プロジェクト別 DAV、削除 tombstone、連絡先 sync-token を照合する。
- 隔離した PostgreSQL 17 に対し schema 単位の dump/restore と、同じ正本 root の読み戻しを検証する。
- `go test ./...`、対象 race test、`go vet ./...`、通常バイナリ build を通す。
- 実インスタンスの停止バックアップと import 結果は、合成データ試験とは別に確認する。
- image build workflow は `tools/ci/test-postgres.sh` で PostgreSQL 17 の全 Go テストを実行してから publish する。
DB container は外部ネットワーク・公開 port を持たず、テスト container がその network namespace を共有する。
DSN 未設定で実行したローカルテストの skip を移植検証の成功として扱わない。
任意のテスト DSN に本番を指定しない。`PAGESWIKI_TEST_POSTGRES_DSN` は使い捨て DB に限定する。
CLI と verified TLS の試験は `PAGESWIKI_TEST_POSTGRES_TLS_DSN` を指定する。
`PAGESWIKI_TEST_POSTGRES_CONTAINER` を追加指定すると、同じ隔離 DB を持つ Docker container 内の
`pg_dump`/`pg_restore` でテスト専用 schema の復元試験を実行する。