garrytan/gbrain

postgres-adopt

Detect which gbrain engine is in use (PGLite vs Postgres), prefer Postgres for agent-harness installs, install/provision Postgres (Supabase discovery via SUPABASEACCESSTOKEN, local Postgres, opt-in Docker), and move an existing PGLite brain to Postgres with…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/garrytan/gbrain --skill postgres-adopt

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

bash
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

bash
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.

  1. Plan. This changes nothing and exits 3 with the

confirmation_required document:

bash
   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).

  1. Run, after the user agrees. Use fix.command from the document:
bash
   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.

  1. 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.

Step 4 — A move already underway

bash
gbrain migrate --status --json

It is read-only and names the next command for the state. Exit 75 or a run in progress → wait and poll. Interrupted → gbrain migrate --resume (or gbrain migrate --rollback-to-source if the user wants to stay on PGLite). Every refusal names its fix; the recovery table is in the guide. A rollback that lists data loss runs only with the user's --rollback-to-source --yes --expect <hash>.

The tradeoff (say it when recommending)

Postgres wins on concurrency, multi-machine access, and scale. PGLite keeps the per-turn bootstrap hook lane (hook injection is PGLite-only today — docs/guides/bootstrap.md); on Postgres, ambient context rides MCP-every-session and the pull protocol instead. Recommend Postgres when the operator has concurrent agents, multiple machines, or a 1000+ page brain; otherwise PGLite is genuinely fine.

When it fails

Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:

  • effective_engine: "postgres" but the probe fails: this is an access problem; run gbrain engine status --probe, then the db-repair skill.
  • Provisioning steps (Docker, installing Postgres) and the move itself need the user's explicit agreement; the docker rung needs --allow-docker, the move needs --yes --expect <plan_hash> after the user saw the plan.
  • gbrain config set engine … is refused by design: switch engines through the migrate path, never by editing config.

Anti-Patterns

  • NEVER gbrain config set engine ... — it is refused by design; an engine

flip without a data migration splits the brain across two stores.

  • NEVER pick Postgres over a healthy PGLite brain without the migrate path.
  • NEVER add --yes before the user has seen the plan, and never use

--force unless the plan listed what it wipes and the user agreed.

  • NEVER put the database URL or password in a command line; use

--url-env GBRAIN_TARGET_URL.

  • NEVER run the docker rung without the operator's explicit yes.
  • NEVER paste or echo SUPABASE_ACCESS_TOKEN / passwords into output.

Output Format

Detection reports in one line; changes report in 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">

Quote gbrain engine status output as-is (it is already redacted); name the winning ladder rung when an install ran; after a migration, include the target's gbrain doctor verdict.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
garrytan
커뮤니티

academic-verify

Verify a research claim or academic citation by tracing it through publication → methodology → raw data → independent replication. Routes through perplexity-research for the actual web lookup, then formats results as a citation-checked brain page. Use when a book/article/conversation cites a study and you want to confirm the claim is real, replicated, and accurately characterized.

1시간 설치 수
1
GitHub Stars
3.3만
업데이트
11월 11일
garrytan
커뮤니티

ask-user

Reusable pattern for presenting the user with explicit choices and gating execution until they respond. Used by other skills when a decision point requires human input before proceeding. Platform-agnostic — works on Telegram (inline buttons), Discord, CLI, or any agent with a message tool.

1시간 설치 수
1
GitHub Stars
3.3만
업데이트
11월 11일
garrytan
커뮤니티

brain-ingest-gate

Pre-write quality gate for content entering the brain. No raw copies: a bare cp/mv into the brain repo is a bug. Before any new page lands, resolve named entities registry-first (a vector score is a floor for prose, never a gate for named things), then run the read-the-top-hit dedup decision tree (clear-dup / plausible-dup / clear). Owns dedup; delegates enrichment to the shipped ingestion skills. Routing convention, not an operation-boundary enforcement.

1시간 설치 수
1
GitHub Stars
3.3만
업데이트
11월 11일
garrytan
커뮤니티

brain-ops

Brain knowledge base operations. The core read/write cycle: brain-first lookup, read-enrich-write loop, source attribution, ambient enrichment, back-linking. Read this before any brain interaction.

1시간 설치 수
1
GitHub Stars
3.3만
업데이트
11월 11일