pgbot

环境要求

• 一个可连接的 PostgreSQL 实例（本地、容器或 RDS/Neon/Supabase 等托管库均可）
• 一个持有 pg_monitor 的只读登录角色（不能用超级用户）
• 执行 pgbot init 生成的 SQL 时需要 psql 客户端
• 使用脚本安装并强制验签时需要 PATH 中有 cosign（可选）
• Linux/macOS/Windows 均可，官方提供多平台预编译包

安装与启动步骤

1. 1安装 pgbot

   官方脚本方式最通用，会下载对应平台二进制并校验 SHA256 校验和；也可改用 Homebrew、go install 或 npx。

   curl -fsSL https://pgbot.dev/install | sh

   复制

2. 2生成只读角色 SQL

   pgbot init 只输出建角色与授权 SQL，自己不执行任何写操作，需你人工审阅后通过管道交给 psql 执行。

   pgbot init "postgres://admin@host:5432/db" | psql "postgres://admin@host:5432/db"

   复制

3. 3验证角色可用

   用刚创建的只读角色连接，确认它具有 pg_monitor 权限、能读取统计视图，避免后续报告数据不全。

   pgbot init --verify "postgres://pgbot_ro:password@host:5432/db"

   复制

4. 4执行健康检查

   传入连接串即可读取 Postgres 自带统计视图，输出 findings 优先的健康报告以及与上次相比的变化。

   pgbot inspect "postgres://pgbot_ro:password@host:5432/db"

   复制

5. 5用环境变量传连接串

   连接串优先取参数，其次 DATABASE_URL、PGBOT_DATABASE_URL、PGSERVICE；用环境变量可避免密码进入 ps 和历史记录。

   export DATABASE_URL="postgres://pgbot_ro:password@host:5432/db?sslmode=require"
   pgbot inspect

   复制

6. 6用 Docker 运行

   镜像为公开多架构（amd64/arm64）且免登录；连远程库无需特殊网络，建议通过环境变量传入 DSN。

   export DATABASE_URL="postgres://pgbot_ro:password@yourdb.example.com:5432/db?sslmode=require"
   docker run --rm -e DATABASE_URL ghcr.io/pgrundev/pgbot inspect

   复制

7. 7手动建只读角色

   若不想用 pgbot init，可自行以管理员身份执行这段 SQL 创建 pg_monitor 角色；只读边界来自这个角色而非命令行参数。

   CREATE ROLE pgbot_ro LOGIN PASSWORD 'your_password';
   GRANT pg_monitor TO pgbot_ro;
   GRANT CONNECT ON DATABASE yourdb TO pgbot_ro;

   复制

8. 8容器互连排查

   pgbot 在主机、库在容器时用 127.0.0.1 加 docker ps 里的宿主端口；pgbot 也在容器时改用容器名加内部 5432 端口。

   docker port mypg 5432
   pgbot inspect "postgres://postgres:pw@127.0.0.1:6433/postgres?sslmode=disable"

   复制

关键配置

如何确认成功

pgbot inspect 能输出健康报告即连接与权限正常；pgbot init --verify 无报错说明只读角色配置可用。

常见问题

注意事项

• 只读边界是数据库角色，pgbot 只是在此基础上再加 default_transaction_read_only、statement_timeout=15s、lock_timeout=2s 等纵深防御。
• 连接串优先取命令行参数，其次 DATABASE_URL、PGBOT_DATABASE_URL，最后 PGSERVICE。
• 托管数据库或 CI 场景建议用环境变量传 DSN，让密码不出现在 ps 输出和 shell 历史里。
• 卸载只需删除 pgbot 可执行文件与本地基线目录 ${XDG_STATE_HOME:-$HOME/.local/state}/pgbot，没有守护进程或数据库残留。