用 CLI 安全查询 PostgreSQL

---
name: query-postgres-workflow
description: "使用只读角色，以非交互方式运行 psql，并限制查询范围和输出格式。"
---

# 查询 PostgreSQL

## 适用目标

回答数据库问题，不暴露凭证，也不修改数据。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **PostgreSQL psql**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 18.1）
  - 安装：`brew install libpq`
  - 认证：connection URI, password file, service file, peer authentication
  - 最小权限：使用只读数据库角色、TLS，并把数据库与 schema 搜索路径限制在任务范围内。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- 环境中的连接标识
- 只读数据库角色
- 问题与行数上限
- 预期字段

## 输出合同

- 限定范围的查询结果
- 查询文本
- 耗时或错误信息
- 带限制说明的解释

## 安全工作流

1. **安全确认目标** — 使用环境中的连接设置，打印数据库身份但不打印密码。
   - 输入: 连接环境和只读角色
   - 输出: 已确认的主机、数据库与用户
   - 风险: `read-only`
   - 命令: `psql -X -v ON_ERROR_STOP=1 -c "select current_database(), current_user"`
2. **执行有限只读查询** — 把 SELECT 放在只读事务中，并请求可解析格式。
   - 输入: 已审查的 SELECT
   - 输出: CSV 或无对齐文本行
   - 风险: `read-only`
   - 命令: `psql -X --csv -v ON_ERROR_STOP=1 -c "begin read only; select * from example limit 100; commit;"`
3. **报告查询与限制** — 返回查询、行数、输出形状和假设，不回显凭证。
   - 输入: 结果与错误流
   - 输出: 带来源的数据库答案
   - 风险: `read-only`

## 必须先确认

- 任何 INSERT、UPDATE、DELETE、DDL、迁移或有副作用的函数
- 使用 owner 或 superuser 连接
- 导出敏感或大量数据

## 回滚

- 默认使用只读事务，因此无需回滚
- 批准写入时用事务包裹并在 commit 前核对
- 无法事务回退的变更应从经过测试的备份恢复

## 官方来源

- [PostgreSQL psql documentation](https://www.postgresql.org/docs/current/app-psql.html) — 用于核对当前命令、认证、输出和操作边界。