postgres-adopt

Detects the gbrain engine and migrates PGLite brains to Postgres or Supabase.

29.4k|4.4k|Updated Apr 5, 2026
One-click install
npx skills add https://github.com/garrytan/gbrain --skill postgres-adopt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: postgres-adopt
Source: https://github.com/garrytan/gbrain/tree/main/plugin/skills/postgres-adopt
Command: npx skills add https://github.com/garrytan/gbrain --skill postgres-adopt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Operators running gbrain often don't know whether their brain is backed by PGLite or Postgres, and switching engines by hand risks splitting data across two stores. This Skill detects the active engine, provisions Postgres when wanted, and migrates existing PGLite data through the guarded migration path.

Core Features & Use Cases

  • Engine Detection: Runs gbrain engine status --json to report the effective engine, config source, and probe health without needing the database up.
  • Postgres-First Provisioning: Uses gbrain init --prefer-postgres to walk an install ladder covering env URLs, Supabase Management API discovery, local Postgres, opt-in Docker, and PGLite fallback.
  • Guarded Migration: Moves an existing PGLite brain with gbrain migrate --to supabase, which resumes partial runs from a manifest and only flips config after a fully clean run.
  • Use Case: A team with three concurrent agents and a 5000-page PGLite brain asks to upgrade; the Skill confirms consent, provisions a Supabase database, migrates all pages, and verifies the result with gbrain doctor.

Quick Start

Ask the agent to check which gbrain engine is running and upgrade the brain to Postgres if it is still on PGLite.

Frequently Asked Questions about postgres-adopt

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check which gbrain engine my brain is using?

Run `gbrain engine status --json` to see the effective engine, its config source, and probe health. The command works even when the database is down, which is the point of the detection step.

How do I migrate a PGLite brain to Postgres or Supabase?

Use `gbrain migrate --to supabase --url <postgres-connection-string>` after confirming with the operator. A partial run leaves you on PGLite and resumes from its manifest when re-run; config only flips after a fully clean run.

PGLite vs Postgres for gbrain: which should I choose?

Postgres wins on concurrency, multi-machine access, and brains over 1000 pages. PGLite keeps the per-turn bootstrap hook lane, which is PGLite-only, so it remains a fine choice for single-machine setups.

Can I switch the gbrain engine by editing the config file?

No. `gbrain config set engine` is refused by design because flipping the engine without migrating data splits the brain across two stores. Always use the migrate command, which brings its own guardrails.

Does gbrain support Supabase for Postgres provisioning?

Yes. Set SUPABASE_ACCESS_TOKEN for Management API discovery, plus SUPABASE_PROJECT_REF on multi-project accounts and SUPABASE_DB_PASSWORD for the connection string. The init ladder tries this rung before local Postgres and Docker.

Why does gbrain engine status show a different engine than my config file?

An environment URL is overriding the config file. Check the `db_url_source` field: `env:GBRAIN_DATABASE_URL` or `env:DATABASE_URL` means the env value wins over the file setting.