用途
PostgreSQL 只读查询技能用于对已配置的多个 PostgreSQL 数据库执行安全、只读的查询。它适合在需要查询 PostgreSQL 数据库、探索数据库架构或表结构等场景中使用。
主要能力
- 对配置好的 PostgreSQL 数据库执行只读 SQL 查询。
- 列出已配置的数据库。
- 列出数据库中的表。
- 查看数据库架构（schema）。
- 限制查询返回的结果条数。
- 根据用户意图与数据库描述进行数据库自动匹配。
使用方式
环境要求
- Python 3.8+
- psycopg2-binary：
pip install -r requirements.txt
配置
在技能目录或 ~/.config/claude/postgres-connections.json 创建 connections.json。由于文件包含凭据，需设置权限为 600：
chmod 600 connections.json
配置示例：
{
"databases": [
{
"name": "production",
"description": "Main app database - users, orders, transactions",
"host": "db.example.com",
"port": 5432,
"database": "app_prod",
"user": "readonly_user",
"password": "your-password",
"sslmode": "require"
}
]
}
配置字段说明：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| name | 是 | 数据库标识符（不区分大小写） |
| description | 是 | 该数据库包含的数据说明（用于自动选择） |
| host | 是 | 数据库主机名 |
| port | 否 | 端口号（默认：5432） |
| database | 是 | 数据库名 |
| user | 是 | 用户名 |
| password | 是 | 密码 |
| sslmode | 否 | SSL 模式：disable、allow、prefer（默认）、require、verify-ca、verify-full |
常用命令
列出已配置的数据库：
python3 scripts/query.py --list
查询数据库：
python3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"
列出表：
python3 scripts/query.py --db production --tables
查看架构：
python3 scripts/query.py --db production --schema
限制结果条数：
python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100
数据库选择
将用户意图与数据库描述进行匹配：
| 用户询问 | 查找描述中包含 |
|---|---|
| users、accounts | users、accounts、customers |
| orders、sales | orders、transactions、sales |
| analytics、metrics | analytics、metrics、reports |
| logs、events | logs、events、audit |
如果不明确，运行 --list 并询问用户选择哪个数据库。
安全特性
- 只读会话：连接使用 PostgreSQL
readonly=True模式（主要保护）。 - 查询校验：仅允许 SELECT、SHOW、EXPLAIN、WITH 查询。
- 单语句：拒绝每次查询中的多条语句。
- SSL 支持：可配置 SSL 模式以加密连接。
- 查询超时：强制 30 秒语句超时。
- 内存保护：每次查询最多 10,000 行，防止 OOM。
- 列宽上限：每列最大 100 字符，保证输出可读。
- 凭据脱敏：错误消息不会泄露密码。
故障排查
| 错误 | 解决方案 |
|---|---|
| 找不到配置 | 在技能目录创建 connections.json |
| 认证失败 | 检查配置中的用户名/密码 |
| 连接超时 | 验证主机/端口，检查防火墙/VPN |
| SSL 错误 | 本地数据库可尝试 "sslmode": "disable" |
| 权限警告 | 运行 chmod 600 connections.json |
退出码
- 0：成功
- 1：错误（配置缺失、认证失败、无效查询、数据库错误）
工作流
- 运行
--list显示可用数据库。 - 将用户意图与数据库描述匹配。
- 运行
--tables或--schema探索结构。 - 使用适当的 LIMIT 执行查询。
适用场景与限制
适用于需要对 PostgreSQL 数据库进行只读查询、结构探索和结果限制的场景。限制包括：仅支持只读查询，不允许写入或修改操作；仅允许 SELECT、SHOW、EXPLAIN、WITH 语句；每次查询只能包含单条语句；查询超时 30 秒；每次查询最多返回 10,000 行；每列最大宽度 100 字符。