postgres-adopt

Postgres への移行

エンジンは脳の土台です。PGLite は設定不要で始められる基盤であり、 Postgres は並行処理、複数マシンからのアクセス、1000 ページ以上の運用を支えます。 このスキルでは「今どちらを使っているか」を確認し、 オペレーターが希望する場合は Postgres を優先して、安全にデータを移行します。設定の切り替えだけで移行することはありません。

契約

このスキルでは、次のことを保証します。

• 検出処理はエンジンに依存せず、読み取り専用です。gbrain engine status --json はデータベースが停止していても応答します（このコマンドの目的はそこにあります）。
• エンジンの変更で設定を編集することは決してありません。PGLite の脳は gbrain migrate --to postgres（エイリアス --to supabase）で移行します。これにより昇格させます。 まず計画を作成し（終了コード 3）、ユーザーが --yes --expect <plan_hash> を指定した場合に限り実行し、 すべてのテーブルを検証してから、ルーティングを切り替えます。このスキルは移行処理をラップしますが、再実装はしません。
• 接続先 URL がコマンド、トランスクリプト、出力に現れることはありません。URL は GBRAIN_TARGET_URL に保存し、すべてのコマンドで --url-env GBRAIN_TARGET_URL を使用します。
• プロビジョニングへの同意は明示的に必要です。docker の段階では --allow-docker が必要で、 ローカルサーバー上にデータベースを作成するには --allow-create-db が必要です。オペレーターが許可していないインフラストラクチャを、ヘッドレスで変更することは決してありません。

ステップ 1 — 検出

gbrain engine status --json

出力に応じて分岐します。

• effective_engine: "postgres" で、（任意の）--probe が ok を示す場合 → 正常であると報告し、完了です。
• effective_engine: "postgres" だがプローブに失敗する場合 → これはアクセスの 問題であり、移行の問題ではありません。db-repair に案内します。
• config_file_engine と effective_engine が異なる場合 → env URL が 設定ファイルを上書きしています。どちらが優先されるかをオペレーターに伝えます。判断の 手がかりは db_url_source です（env:GBRAIN_DATABASE_URL / env:DATABASE_URL は env が優先されることを示します。両方の env URL が設定されている場合、または cwd の .env シャドウガードによって一方が除外された場合は、さらに env.note が出力されます）。
• thin_client: true の場合 → 脳はリモートサーバー上で動作しています。エンジンの選択は そのホスト側で行います。ここで終了します。
• effective_engine: null（脳がない）の場合 → ステップ 2。
• データがあり、effective_engine: "pglite" の場合 → ステップ 3。
• 出力に graduation ブロックがあり、その state が none 以外（進行中、 中断、昇格済み、分割済み）の場合 → ステップ 4。

ステップ 2 — 新規インストール、Postgres を優先

gbrain init --prefer-postgres

この手順では、次の順に試します。env URL → Supabase Management-API による検出 （SUPABASE_ACCESS_TOKEN、複数プロジェクトのアカウントでは SUPABASE_PROJECT_REF、 接続文字列には SUPABASE_DB_PASSWORD）→ ローカル Postgres（PGHOST／PGPORT／PGUSER／PGPASSWORD が 設定されている場合、または --local-postgres が渡された場合のみ）→ docker → PGLite。使用できない段階ではそれぞれ 1 行のメモを出力して次に進み、無言で処理されることはありません。

• --allow-docker を追加する前に、必ずオペレーターに確認してください（再起動後も 稼働する gbrain-postgres コンテナを作成して所有します）。また、--allow-create-db を 追加する前にも確認してください（オペレーターのローカルサーバー上で CREATE DATABASE を実行します）。
• --json は {engine, ladder_rung, url_source} を報告します。どの段階が選ばれたかを伝えてください。
• この手順で PGLite が選ばれた場合も問題ありません。その旨を伝え、希望すればいつでも 以下のアップグレード手順を利用できることを説明してください。

ステップ 3 — 既存の PGLite ブレイン：計画、確認、実行

完全なリファレンス：PGLite ブレインを Postgres に移行する。

1. 接続先 URL。 接続文字列を会話に貼り付けず、環境変数に設定するようユーザーに依頼します （read -rs GBRAIN_TARGET_URL && export GBRAIN_TARGET_URL）。Supabase では トランザクションプーラーを使用します。IPv4 のみのホストでは、 GBRAIN_DIRECT_DATABASE_URL にセッションプーラーも設定します。
2. 計画。 これは何も変更せず、confirmation_required ドキュメントとともに終了コード 3 で終了します：

   gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --json
   

   user_message、移行されるもの、このコンピューターに残るもの、ブロッカー、 見積もりを伝えます。停止してユーザーの返答を待ちます。専用の fix があるブロッカーは、 先に解消します（ask_user と記載されている場合はユーザーに確認します）。
3. ユーザーの同意を得てから実行します。 ドキュメントの fix.command を使用します：

   gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --yes --expect <plan_hash>
   

   preview_changed は計画が変更されたことを意味します。ステップ 2 に戻ります。数千ページある場合は バックグラウンドで実行し、gbrain migrate --status --json をポーリングします。
4. 報告。 実行結果にある接続先の doctor 判定、既存のトークン、OAuth クライアント、 ローカルの書き込み処理は引き続き有効であること、ほかのマシン向けの gbrain mcp expose の後続手順、さらに serve がブレインを引き継いだ場合は ユーザーが MCP クライアントを再起動する必要があることを伝えます。

• ブレインを保持している gbrain serve は自動で引き継ぎます。先に停止するようユーザーに依頼してはいけません。 引き継ぎが行われない場合は、graduation_source_writer_held に停止すべきプロセスが示されます。
• 古いデータディレクトリは <path>.graduated-<run_id> として保持されます（doctor の pglite_leftovers に表示されます）。削除するかどうかはユーザーが決めます。
• gbrain doctor の pglite_scale チェックは、ページ数が 1000 以上の場合に警告し、 計画コマンドを示します。この警告がこのスキルを使う合図です。

ステップ 4 — すでに移行が進行中の場合

gbrain migrate --status --json

これは読み取り専用で、状態に応じた次のコマンドを示します。終了コード 75 または 実行中の場合は、待機してポーリングします。中断された場合は、gbrain migrate --resume を実行します（PGLite を使い続けたい場合は gbrain migrate --rollback-to-source）。 拒否された場合は、いずれも修正方法が示されます。復旧手順の表はガイドにあります。 データ損失が示されるロールバックは、ユーザーの --rollback-to-source --yes --expect <hash> がある場合にのみ実行します。

トレードオフ（推奨する際に説明してください）

Postgres は同時実行、複数マシンからのアクセス、スケーラビリティに優れています。PGLite では ターンごとのブートストラップフックの仕組みを維持できます（現在、フックの挿入に対応しているのは PGLite のみです — docs/guides/bootstrap.md）。Postgres では、代わりにセッションごとの MCP と プルプロトコルを通じて周辺コンテキストを利用します。同時に動作するエージェントがいる場合、 複数のマシンを使う場合、またはブレインが 1000 ページ以上ある場合は Postgres を推奨します。 それ以外の場合、PGLite で問題ありません。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、 エージェント運用者プロトコルに従ってください。このスキル固有の注意事項：

• effective_engine: "postgres" なのにプローブに失敗する場合：これはアクセスの問題です。gbrain engine status --probe を実行し、 次に db-repair スキルを使います。
• プロビジョニングの手順（Docker、Postgres のインストール）と移行そのものには、ユーザーの明示的な同意が必要です。 Docker の段階では --allow-docker が必要です。移行には、ユーザーが計画を確認した後で --yes --expect <plan_hash> が必要です。
• gbrain config set engine … は設計上拒否されます。エンジンは移行の手順で切り替え、設定を直接編集してはいけません。

アンチパターン

• gbrain config set engine ... は絶対に実行しないでください。設計上拒否されます。データを移行せずにエンジンを 切り替えると、ブレインが 2 つのストアに分散します。
• 正常な PGLite ブレインから Postgres へ、移行の手順を使わずに切り替えてはいけません。
• ユーザーが計画を確認する前に --yes を追加してはいけません。また、計画に消去する内容が示され、 ユーザーが同意していない限り、--force を使ってはいけません。
• データベース URL やパスワードをコマンドラインに指定してはいけません。--url-env GBRAIN_TARGET_URL を使います。
• 運用者の明示的な同意なしに Docker の段階を実行してはいけません。
• SUPABASE_ACCESS_TOKEN やパスワードを出力に貼り付けたり、表示したりしてはいけません。

出力形式

検出レポートは1行で、変更レポートは2～4行で出力します。

Engine: <pglite|postgres> (source: <db_url_source>)   [probe: ok, 42ms]
Action: <none | init rung that won | migrate --to postgres result>
Next:   <upgrade note, or "healthy — nothing to do">

gbrain engine status の出力はそのまま引用してください（すでに秘匿化されています）。インストールが実行された場合は、優先順位で採用された段階を明記してください。移行後は、移行先の gbrain doctor の判定を含めてください。