mcpField
P
postgres-adopt

postgres-adopt

github.com/garrytan数据与数据库31.3k56 次安装今天更新
代码仓库

关于 postgres-adopt

Postgres Adopt 是帮助 gbrain 操作者判断数据库引擎并迁移到 Postgres 的技能。它通过只读检测、迁移计划和确认步骤处理迁移，避免仅改配置导致数据分裂。

主要功能

  1. 01只读检测当前数据库引擎
  2. 02按优先级尝试 Postgres 初始化
  3. 03先规划再执行数据迁移
  4. 04迁移期间查看状态并恢复或回滚
  5. 05明确请求基础设施配置许可

适用场景

  1. 01检查 gbrain 当前使用的引擎
  2. 02为新安装选择 Postgres 或 PGLite
  3. 03将已有 PGLite 脑迁移到 Postgres
  4. 04查看并恢复进行中或中断的迁移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/garrytan/gbrain --skill postgres-adopt

安装后在 Claude Code 中输入/postgres-adopt确认已加载。

附带文件routing-eval.jsonl

详细介绍

Postgres 采用

引擎是大脑的基础：PGLite 是零配置的起点， Postgres 则适用于并发、多机器访问和 1000+ 个页面。 此技能会回答“我当前使用的是哪种引擎？”，在运维人员希望使用 Postgres 时优先选择它，并安全迁移数据——绝不会通过切换配置来实现。

约定

此技能保证：

  • 检测不依赖引擎且只读：即使数据库已关闭，gbrain engine status --json 也会返回结果（这正是此命令的目的）。
  • 绝不会通过编辑配置来更改引擎。PGLite 大脑通过 gbrain migrate --to postgres（别名为 --to supabase）迁移，从而升级：先规划（退出码为 3），仅在用户提供 --yes --expect <plan_hash> 时运行，验证每张表，然后切换路由。此技能会封装该流程，不会重新实现它。
  • 目标 URL 绝不会出现在命令、记录或输出中：它存放在 GBRAIN_TARGET_URL 中，每条命令都会使用 --url-env GBRAIN_TARGET_URL。
  • 资源配置需要明确同意：Docker 步骤需要 --allow-docker，在本地服务上创建数据库需要 --allow-create-db。绝不会在无交互模式下修改运维人员未明确同意修改的基础设施。

步骤 1 — 检测

gbrain engine status --json

根据输出选择分支：

  • effective_engine: "postgres"，且（可选的）--probe 返回正常 → 报告状态正常，完成。
  • effective_engine: "postgres"，但探测失败 → 这是访问问题，而非采用问题：转至 db-repair。
  • config_file_engine 与 effective_engine 不同 → 环境变量 URL 覆盖了配置文件；告知运维人员哪个设置生效——依据是 db_url_source（env:GBRAIN_DATABASE_URL / env:DATABASE_URL 表示环境变量生效；若两个环境变量 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

按以下顺序尝试：环境变量 URL → Supabase Management API 发现（SUPABASE_ACCESS_TOKEN，多项目账户还需 SUPABASE_PROJECT_REF，连接字符串还需 SUPABASE_DB_PASSWORD）→ 本地 Postgres（仅当设置了 PGHOST/PGPORT/PGUSER/PGPASSWORD 或传入 --local-postgres 时）→ Docker → PGLite。每个不可用的步骤都会打印一行说明，然后继续尝试下一步；不会静默处理。

  • 添加 --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. 规划。 此操作不会更改任何内容，并以退出码 3 退出，同时提供 confirmation_required 文档： 
    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 和拉取协议传递。若操作者有多个并发 Agent、多台计算机， 或大脑包含 1000 个以上页面，建议使用 Postgres； 否则，PGLite 确实完全够用。

失败时

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循 Agent 操作者协议。此技能特有的情况：

  • effective_engine: "postgres"，但探测失败：这是访问问题；运行 gbrain engine status --probe，然后使用数据库修复技能。
  • 配置步骤（Docker、安装 Postgres）和迁移本身都需要用户明确同意；Docker 阶段需要 --allow-docker，迁移则需要用户查看计划后提供 --yes --expect <plan_hash>。
  • 按设计，gbrain config set engine … 会被拒绝：必须通过 migrate 流程切换引擎，绝不能通过编辑配置来切换。

反模式

  • 绝不要执行 gbrain config set engine ... — 按设计，此操作会被拒绝；不迁移数据就切换引擎 会使大脑分散在两个存储中。
  • 绝不要绕过 migrate 流程，将健康的 PGLite 大脑迁移到 Postgres。
  • 用户查看计划之前，绝不要添加 --yes；除非计划列明将被清除的内容且用户已同意，否则绝不要使用 --force。
  • 绝不要将数据库 URL 或密码放在命令行中；请使用 --url-env GBRAIN_TARGET_URL。
  • 未获得操作者明确同意，绝不要运行 Docker 阶段。
  • 绝不要将 SUPABASE_ACCESS_TOKEN 或密码粘贴到输出中或回显。

输出格式

检测报告用一行；变更报告用 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 判定结果。

评论

支持 Markdown