Postgres Adopt

Postgres Adopt

The engine is the brain's foundation: PGLite is the zero-config floor, Postgres is where concurrency, multi-machine access, and 1000+ pages live. This skill answers "which one am I on?", prefers Postgres when the operator wants it, and moves data safely — never by flipping config.

Contract

This skill guarantees:

• Detection is engine-free and read-only: gbrain engine status --json answers with the database down (that is the point of the command).
• Engine changes NEVER happen by editing config. A PGLite brain moves with gbrain migrate --to postgres (alias --to supabase), which graduates it: plan first (exit 3), run only with the user's --yes --expect <plan_hash>, verify every table, then flip routing. This skill wraps it; it never reimplements it.
• The target URL never appears in a command, transcript or output: it lives in GBRAIN_TARGET_URL and every command uses --url-env GBRAIN_TARGET_URL.
• Provisioning consent is explicit: the docker rung needs --allow-docker, creating a database on a local server needs --allow-create-db. Headless mutation of infrastructure the operator didn't opt into never happens.

Step 1 — Detect

gbrain engine status --json

Branch on the output:

• effective_engine: "postgres" and (optionally) --probe says ok → report healthy, done.
• effective_engine: "postgres" but the probe fails → this is an ACCESS problem, not an adoption problem: route to db-repair.
• config_file_engine differs from effective_engine → an env URL is overriding the config file; tell the operator which one wins — the signal is db_url_source (env:GBRAIN_DATABASE_URL / env:DATABASE_URL means env wins; env.note additionally fires when both env URLs are set or the cwd-.env shadow guard excluded one).
• thin_client: true → the brain lives on a remote server; engine choices belong to that host. Stop.
• effective_engine: null (no brain) → Step 2.
• effective_engine: "pglite" with data → Step 3.
• The output has a graduation block whose state is not none (in progress, interrupted, graduated or split) → Step 4.

Step 2 — Fresh install, Postgres-first

gbrain init --prefer-postgres

The ladder tries, in order: an env URL → Supabase Management-API discovery (SUPABASE_ACCESS_TOKEN, plus SUPABASE_PROJECT_REF on multi-project accounts and SUPABASE_DB_PASSWORD for the connection string) → a local Postgres (only when PGHOST/PGPORT/PGUSER/PGPASSWORD are set or --local-postgres is passed) → docker → PGLite. Each unusable rung prints a one-line note and falls through; nothing is silent.

• Ask the operator BEFORE adding --allow-docker (it creates and owns a gbrain-postgres container that survives reboots) or --allow-create-db (it runs CREATE DATABASE on their local server).
• --json reports {engine, ladder_rung, url_source} — relay which rung won.
• If the ladder lands on PGLite, that is a fine outcome: say so, and note the upgrade path below is available whenever they want it.

Step 3 — Existing PGLite brain: plan, ask, run

Full reference: Move a PGLite brain to Postgres.

1. Target URL. Ask the user to put the connection string in an environment variable without pasting it into the conversation (read -rs GBRAIN_TARGET_URL && export GBRAIN_TARGET_URL). On Supabase use the transaction pooler; on an IPv4-only host also set GBRAIN_DIRECT_DATABASE_URL to the session pooler.
2. Plan. This changes nothing and exits 3 with the confirmation_required document:

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

   Relay user_message, what moves, what stays on this computer, blockers and the estimate. Stop and wait for the user. A blocker with its own fix gets cleared first (ask when it says ask_user).
3. Run, after the user agrees. Use fix.command from the document:

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

   preview_changed means the plan changed: go back to step 2. For thousands of pages run it in the background and poll gbrain migrate --status --json.
4. Report. Relay the target doctor verdict from the run's output, that existing tokens, OAuth clients and local writers stay valid, the gbrain mcp expose follow-up for other machines, and, if a serve handed the brain over, that the user restarts the MCP client.

• A gbrain serve holding the brain hands it over on its own; never ask the user to stop it first. graduation_source_writer_held names the process to stop when one does not.
• The old data dir is kept as <path>.graduated-<run_id> (doctor's pglite_leftovers reports it). Deleting it is the user's call.
• gbrain doctor's pglite_scale check warns at 1000+ pages and points at the plan command — that warning is this skill's cue.