[DB] PGliteでpgvectorを有効化し起動経路を共通化する

[hmjn023]

Parent: #612

背景

lock上のPGlite 0.5.3はPostgreSQL 18.3ベースだが、現在の起動方法ではvector extensionが登録されておらず、CREATE EXTENSION vector は失敗する。また new PGlite(...) がruntime、migration、E2E、integration setupへ分散し、PGLITE_DATA_DIR の扱いも一致していない。

スコープ

• @electric-sql/pglite-pgvector を導入する
• vector extensionを登録する共通 createPglite() factoryを作る
• runtime、migration、fresh migration、E2E、integration setupをfactoryへ統一する
• PGLITE_DATA_DIR をすべての起動・migration経路で尊重する
• Nitro buildへvector extension assetが正しく含まれることを検証する
• CREATE EXTENSION IF NOT EXISTS vector を含むmigrationを適用できるようにする
• vector columnのCRUD・cosine検索・migration testを追加する

非スコープ

• Docker PostgreSQLのmajor upgrade（[DB] Docker PostgreSQLを18 + pgvectorへ安全に移行する #613）
• CCIPのLanceDBデータ移行

受け入れ条件

• factory以外の直接的なPGlite生成を原則廃止する
• pg_extension でvectorが有効である
• runtimeとmigrationが同じdata directory・extension構成を使う
• fresh DBと既存PGlite DBの両方で全migrationが成功する
• integration/E2Eでvector queryを実行する実テストがある
• production build後もextension assetを読み込める

主な参照

• apps/server/package.json:38
• apps/server/src/infrastructure/db/index.ts:43
• apps/server/src/infrastructure/db/connection.ts:10
• apps/server/scripts/migrate-pglite.ts:8
• apps/server/scripts/isolated-runtime.ts:75
• apps/server/nitro.config.ts:18

評価反映（2026-07-18）

vector extensionの追加だけでなく、PGlite本体とのpeer dependency、既存2.4GBデータ、production bundleの自己完結性を移行契約に含める。以下を追加の決定事項・受け入れ条件とする。

Version互換性

現在のlockは @electric-sql/pglite 0.5.3を解決している。確認できる互換pairは次のとおり。

• @electric-sql/pglite 0.5.3 + @electric-sql/pglite-pgvector 0.0.4
• @electric-sql/pglite 0.5.4 + @electric-sql/pglite-pgvector 0.0.5

実装時にどちらか一組を選び、両packageをcaretなしのexact versionで固定する。PGliteとextensionを独立に更新してpeer dependencyがずれる状態を許容しない。変更は bun add --cwd apps/server ... で行い、package.json と bun.lock を同時に更新する。

既存PGliteデータの保護

apps/server/.data/pglite には約2.4GBの既存データがある。extension導入・PGlite更新の初回検証を元directoryへ直接行ってはならない。

• PGliteを停止して整合したcloneまたはbackupを作成する
• cloneに対して新factoryでopen、全migration、vector extension有効化、vector CRUD・cosine queryを実行する
• close/reopen後にも既存データ件数とvector queryを確認する
• 失敗時に元directoryが変更されていないことを確認する
• PGlite 0.5.4を選ぶ場合は、0.5.3で作成済みのcloneを0.5.4で開くupgrade/restart testを必須とする

createPglite()への統一

現時点の直接生成箇所は次のとおり。いずれもfactory利用へ移行するか、不要な補助scriptなら削除する。

• apps/server/src/infrastructure/db/index.ts
• apps/server/src/infrastructure/db/connection.ts
• apps/server/scripts/migrate-pglite.ts
• apps/server/scripts/migrate-pglite-fresh.ts
• apps/server/scripts/isolated-runtime.ts
• apps/server/src/tests/setup.ts
• apps/server/src/tests/setup-integration.ts
• apps/server/scripts/test-pglite.ts
• apps/server/scripts/test-pglite-dir.ts
• apps/server/get-media-ids.ts

直接的な new PGlite(...) を許可する例外は、原則として createPglite() factoryの実装本体だけとする。extension未登録時の失敗を意図的に確認するlow-level negative testが必要な場合に限り、ファイル名と理由をallowlistへ明記する。runtime、migration、E2E、integration、運用scriptは例外にしない。

Production bundle検証

現在のNitro設定はPGlite本体の pglite.data と pglite.wasm を個別copyしている。vector extensionに必要なassetも出力へ含め、asset欠落をwarningだけで通さずbuild failureにする。

production testはworkspaceの node_modules、symlink、source treeへのfallbackに依存してはならない。build出力だけを一時directoryへ配置し、そのdirectoryをworking directoryとして次を実行するhermetic testを追加する。

1. PGliteを起動する
2. CREATE EXTENSION IF NOT EXISTS vector を実行する
3. pg_extensionでvectorを確認する
4. vector columnを作成してinsert/read/cosine queryを実行する
5. processを終了・再起動し、同じdata directoryを再度openしてqueryを実行する

追加受け入れ条件

• 採用したPGlite・pgvector extensionの互換pairがexact versionで固定され、lockfileでも同じversionを解決している
• 元の2.4GB data directoryを変更せず、cloneを使ったmigration・CRUD・再起動テストが成功している
• PGLITE_DATA_DIRの解決をfactoryへ集約し、runtime・migration・testで同一規則を使用している
• rg 'new PGlite' apps/server の結果がfactory本体と文書化されたallowlistだけになる
• 上記の既存直接生成箇所がすべて移行・削除・明示的例外のいずれかに分類されている
• production build出力だけでvector extensionの登録、migration、CRUD、cosine query、再起動が成功する
• vector extension assetが欠落した場合、CIが確実に失敗する

[hmjn023]

完了。PR #622 で @electric-sql/pglite-pgvector の導入、createPglite() への共通化、runtime/migration/test への適用、vector CRUD/search の検証まで develop に取り込み済みです。関連: #622