How to use the Postgres Adopt agent skill for gbrain

What the postgres-adopt skill makes the agent do

The skill covers four jobs: detecting the current engine, installing Postgres for a fresh brain, moving an existing PGLite brain to Postgres with its history, and handling a move that is already underway. Detection is read-only and runs one engine-free command, so it works even when the database is down.

The skill never switches engines by editing config files. Engine changes go through gbrain's own migrate command, which makes a plan first, waits for your approval, runs the move, verifies every table, and then changes routing.

• Reports whether a brain is on PGLite or Postgres and which setting wins if both are configured
• Sets up Postgres for a new brain, trying an environment URL, Supabase discovery, a local Postgres server, Docker, and finally PGLite
• Moves a PGLite brain to Postgres or Supabase using gbrain's planned, confirmed migration
• Explains the tradeoffs and recommends Postgres only when it fits

Install the postgres-adopt skill

Download the skill ZIP from the page where you found this guide. You can install it in one of two ways. For Claude Code, unzip it into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

The skill ships as a single file, SKILL.md. Check that the folder contains that file after unzipping. The skill also needs the gbrain CLI installed and on your PATH before it can do anything.

• Claude Code, all projects: unzip into ~/.claude/skills/
• Claude Code, one project: unzip into the project's .claude/skills/
• Claude apps: Settings, Capabilities, Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need to name the skill. The skill responds to phrases such as the ones below. Ask in your own words; the agent will match the request to the skill's triggers.

If you want to check your engine yourself first, the detection command is gbrain engine status --json. It is safe to run because it only reads state.

• Which gbrain engine am I on?
• PGLite or Postgres for my brain?
• Upgrade my gbrain to Postgres
• Move my brain to Supabase
• Set up Postgres for the brain

Example: check and move a PGLite brain

Suppose you ask, "Move my brain to Supabase." The agent first detects the engine. For an existing PGLite brain it asks you to put the connection string in an environment variable instead of pasting it into the chat. The skill points to the transaction pooler on Supabase, and to a session pooler through GBRAIN_DIRECT_DATABASE_URL if your host only supports IPv4.

Next the agent runs a plan. The plan changes nothing and reports what will move, what stays on this computer, any blockers, and an estimate. Read it, then decide. Only after you agree does the agent run the move, using the plan hash from the plan so that the approved plan is the one that runs.

• Put the URL in GBRAIN_TARGET_URL with read -rs so it does not appear in the conversation
• Review the plan output before agreeing
• If the plan changes before you approve, the agent makes a new plan

Understand the consent and safety steps

The skill asks before it creates anything. Adding Docker support creates and owns a gbrain-postgres container that survives reboots, so it needs the --allow-docker flag. Creating a database on a local server needs --allow-create-db. The agent should ask you before adding either flag.

The skill's scripts run commands on your machine and talk to the database server and, for Supabase, its Management API. The database URL and password should stay out of command lines, and the skill uses --url-env GBRAIN_TARGET_URL for that reason. Plans, moves, and rollbacks that discard data need your explicit go-ahead.

• Docker container: requires --allow-docker and your agreement
• Local database creation: requires --allow-create-db and your agreement
• Migration run: requires --yes with the plan hash from the plan you saw
• Forced operations: only if the plan lists what gets wiped and you agree
• The old PGLite data folder is kept, and deleting it is your decision

Check or resume a move already in progress

If a migration was started earlier, ask the agent to check its status. The status command is read-only and names the next step. If a move was interrupted, the agent can resume it. If you want to stay on PGLite, the skill can roll back, but a rollback that lists data loss runs only with your explicit approval.

• Status: gbrain migrate --status --json
• Resume an interrupted move: gbrain migrate --resume
• Return to PGLite: gbrain migrate --rollback-to-source

Tips for a smooth setup

Recommend Postgres when several agents write to the brain at once, when you use more than one machine, or when the brain has 1000 or more pages. The skill's notes say gbrain doctor warns at that size and points to the plan command. For a single-user, small brain, PGLite is a fine choice.

If the probe fails while the config says Postgres, the problem is access rather than migration, and the skill hands off to its db-repair skill. Keep in mind that the bootstrap hook that injects context on each turn works only on PGLite, so on Postgres context comes through MCP and the pull protocol.

• Run gbrain engine status --probe to test a Postgres connection
• Setting the engine with gbrain config set engine is refused by design; use the migrate path
• For other machines, follow the gbrain mcp expose step after migrating
• Restart your MCP client after a move if a serve process handed over the brain