[DB] Docker PostgreSQLを18 + pgvectorへ安全に移行する

[hmjn023]

Parent: #612

背景

現在の compose.yml は postgres:17 と ./db-data:/var/lib/postgresql/data を使用している。PostgreSQL 18ではDocker公式イメージのデータ配置が変わるため、単純なtag差し替えでは既存クラスタを起動できない。既存のdump/restore scriptも、途中のSQLエラーを確実に検出する移行手順としては不足している。

スコープ

• pgvector同梱のPostgreSQL 18 imageを固定version（可能ならdigest）で採用する
• PG18向けにvolume mountを /var/lib/postgresql へ変更する
• PG17の既存データを保持したまま、新規PG18 volumeへdump/restoreする移行script/runbookを用意する
• custom-format dump、strict restore、version・件数・主要制約の検証、rollback手順を実装する
• DB healthcheckと、アプリ起動前のreadinessを整備する
• 実PostgreSQL 18環境でmigration smoke testを追加する

非スコープ

• CCIP vector tableの追加
• LanceDBからのCCIPデータ移行
• crop機能

受け入れ条件

• PG17の既存data directoryを直接上書き・再利用しない
• SELECT version() でPostgreSQL 18、pg_available_extensions でvector利用可能を確認できる
• restore失敗を成功扱いせず、再実行可能である
• schema migration、row count、FK/unique constraintを検証できる
• 切り戻し手順と運用手順が文書化されている
• 実PG18 + pgvectorの自動テストがある

主な参照

• compose.yml:3
• compose.yml:9
• compose.production.yml:20
• apps/server/scripts/dump-db.ts:25
• apps/server/scripts/restore-db.ts:79

評価反映（2026-07-18）

方向性は妥当。ただし、確認済みdumpの位置付け、最終cutover入力の鮮度、rollback可能な境界を明示しないまま本番移行してはならない。以下を追加の決定事項・受け入れ条件とする。

追加決定事項

• backup-2026-07-18T16-07-36+09-00.sql は、作成後にPG17への書き込みが一切なかったと証明できない限り、restoreリハーサル用入力として扱う
• 本番cutoverでは、アプリ・worker・管理scriptを停止してPG17をwrite-freezeし、その後にfresh final dumpを取得する
• write-freeze開始、dump開始・終了、restore開始・終了、migration終了、検証終了、cutover時刻を記録する
• PG18 + pgvector imageは可変tagだけで参照せず、採用する正確なtagとimmutable digest（sha256:...）をcomposeとrunbookへ記録する
• PG18が新規writeを受け付けた時点をrollback boundaryとする。それ以降に旧PG17へ戻す場合は、write-freezeまたは逆方向同期なしではデータを保持できないことをrunbookへ明記する

Restore要件

• 現在のplain SQL dumpを使うリハーサルでは、空の新規PG18 clusterに対して psql -X -v ON_ERROR_STOP=1 を使用し、SQLまたはsubprocessの非zero終了を必ず移行失敗として伝播する
• 将来のfinal backupはTTYなしのcustom format（pg_dump -Fc）で取得し、pg_restore --exit-on-error を使用する
• 中途半端にrestoreされたvolumeへ上書き再実行せず、新規または明示的に再初期化した移行先へ再実行する
• restoreリハーサルでは、dump容量、必要空き容量、dump・restore・migration・ANALYZEの各所要時間を記録し、想定停止時間とgo/no-go期限を決める
• restoreとschema migration完了後、性能確認やcutover前に ANALYZE を実行する

追加受け入れ条件

• 現在の確認済みdumpを使用したPG18へのtimed rehearsalが完了し、各工程の所要時間・必要容量・失敗時の停止点が記録されている
• write-freeze後に取得したfresh final dumpだけを本番cutoverへ使用している
• restore中のSQLエラー、pipe内エラー、subprocess異常終了のいずれも成功扱いにならない
• source PG17とtarget PG18の同一snapshotについて、主要テーブルのexact row count、Drizzle migration状態、FK・unique・check constraintを比較できる
• restore後に SELECT version()、pg_extension.extversion を記録し、PostgreSQL 18と期待するvector extension versionを確認できる
• 採用imageの正確なtagとdigestがcompose、CI、runbookで一致している
• ANALYZE完了後にread/write smoke testとアプリreadiness確認が成功する
• cutover前後それぞれのrollback手順、rollback可能期限、PG18で発生した新規writeの扱い、旧volumeを破棄できる条件が文書化されている

[hmjn023]

Migration input confirmed

PG17実データの移行入力として backup-2026-07-18T16-07-36+09-00.sql を確認した。PostgreSQL 17.7のplain SQL logical dumpで、完了マーカーと media / jobs のschema・dataを含む。

実施時の前提を以下に固定する。

• 既存 db-data は残す。PG18は新規 db-data-18 volumeで初期化する
• dumpは --clean 付きのため、空の移行先DBだけへ psql -X --set ON_ERROR_STOP=on でrestoreする
• role/database作成はdumpに含まれないため、composeの POSTGRES_USER / POSTGRES_DB を移行先でも揃える
• dumpに CREATE EXTENSION はない。restore成功後に vector extensionを有効化し、その後にvector schema migrationを適用する
• 旧・新DBのrow count、制約、Drizzle migration状態を比較してcutoverする

将来のbackup scriptはTTYなしのcustom-format（pg_dump -Fc）へ変更し、pg_restore --exit-on-error を使う。