pgbrake

pgbrake

AI Agent 操作数据库时的撤销按钮。

pgbrake 是一个本地 MCP 服务，位于 Claude Code / Codex / Cursor 与你的 Postgres 之间。 Agent 执行的每次写入都会获得一个更改 ID，你可以用一条命令撤销。高风险 SQL 会等待人工审批。所有操作都会记录日志。数据不会离开你的设备。

agent> DELETE FROM users WHERE created_at < '2025-01-01'
pgbrake> held: DELETE would touch 4,812 rows (limit 100) — approval apv_3f9c21aa

agent> DELETE FROM users WHERE id = 42
pgbrake> 1 row affected; undo with change id chg_8e01b7d2

you$ pgbrake undo chg_8e01b7d2
undid delete on "users": 1 row(s) restored

原因

Claude Code 检查点可以回退文件，却不能回退数据库。客户端权限提示和钩子可能被跳过，也可能在 MCP 调用时误触发，而工具自身的“破坏性”标签也只是一种提示。 pgbrake 在服务内部执行规则，因此无论哪个 Agent 或客户端发起调用，规则都会生效。

功能（免费，MIT）

• 真正的 SQL 解析（通过 pglast 使用 Postgres 解析器），而不是正则表达式。
• 等待审批： DDL（DROP、ALTER、TRUNCATE……）、没有 WHERE 的 UPDATE/DELETE、影响行数超过限制（默认为 100）的任何写入、upsert 和 MERGE。
• 绝不允许： ALTER SYSTEM、创建和删除角色或数据库、COPY ... PROGRAM、DO 块。
• 一条命令即可撤销： 每次 UPDATE/DELETE 执行前，受影响的行都会保存到本地；插入操作则按主键跟踪。若行在此后发生更改，撤销操作会拒绝执行，除非使用 --force。
• 仅限人工审批： 通过客户端自身的提示词（MCP elicitation）或在交互式终端中运行 pgbrake approve <id>。审批仅可使用一次，15 分钟后过期，并且与确切的 SQL 绑定。
• 每条语句、决策和行数的审计日志都保存在 ~/.pgbrake/journal.db。
• 多语句调用在同一个事务中运行：要么全部成功，要么全部失败。

安装

pip install pgbrake      # or: uvx pgbrake serve

Claude Code：

claude mcp add pgbrake --env PGBRAKE_DSN="postgresql://me@localhost/app" -- uvx pgbrake serve

Codex（~/.codex/config.toml）：

[mcp_servers.pgbrake]
command = "uvx"
args = ["pgbrake", "serve"]
env = { PGBRAKE_DSN = "postgresql://me@localhost/app" }

然后从 Agent 中移除所有其他数据库 MCP / psql 访问方式，确保 pgbrake 是唯一的访问入口。 在 Claude Code 中，将 "Bash(psql:*)" 和 "Bash(pgbrake approve:*)" 添加到 permissions.deny。

命令

pgbrake pending            # SQL waiting for you
pgbrake approve <id>       # approve (interactive terminal only)
pgbrake deny <id>
pgbrake changes            # undoable changes
pgbrake undo <change-id>   # reverse one
pgbrake log                # audit log

设置（环境变量）

变量	默认值
PGBRAKE_DSN	—	连接字符串（未设置时使用 DATABASE_URL）
PGBRAKE_MAX_ROWS	100	影响行数超过此值的写入需要审批
PGBRAKE_ALLOW_DDL	0	设为 1 以允许执行架构更改（仍会记录日志）
PGBRAKE_READ_ONLY	0	设为 1 以拒绝所有写入
PGBRAKE_STATEMENT_TIMEOUT_MS	15000
PGBRAKE_JOURNAL	~/.pgbrake/journal.db

限制

• 撤销功能仅适用于通过 pgbrake 更改的行。它不是备份：请保留真正的备份。
• TRUNCATE、DDL、upsert 和 MERGE 需要审批，但无法撤销。
• 更新没有主键的表需要审批，且无法撤销。
• 免费版本保留最近 20 条可撤销的更改。

专业版（即将推出）

无限撤销历史记录、针对 Agent 终端命令的迁移防护 （prisma migrate reset --force、drizzle-kit push --force、alembic downgrade base……：先创建快照， 再请求审批）、按项目配置的策略文件，以及审计日志导出。一次性许可。