postgres

PostgreSQL Read-Only Query Skill 用于对已配置的 PostgreSQL 数据库执行安全、只读的查询。

用途该技能主要用于：(1) 查询 PostgreSQL 数据库；(2) 探索数据库架构与数据表；(3) 列出库表结构与 schema；(4) 限制查询结果数量等数据库只读探查任务。

主要能力

列出已配置的数据库：python3 scripts/query.py --list
对指定数据库执行查询：python3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"
列出数据表：python3 scripts/query.py --db production --tables
查看架构（schema）：python3 scripts/query.py --db production --schema
限制结果行数：python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

环境要求

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

数据库选择逻辑根据用户意图匹配数据库 description 中的关键词。例如用户询问 users、accounts 时，匹配 description 中含 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 秒语句超时
内存保护：每次查询最多 10000 行，防止 OOM
列宽限制：每列最大 100 字符，保证输出可读
凭据脱敏：错误信息不会泄露密码

故障排查

Config not found：在技能目录创建 connections.json
Authentication failed：检查配置中的用户名与密码
Connection timeout：确认 host/port，检查防火墙或 VPN
SSL error：本地数据库可尝试 "sslmode": "disable"
Permission warning：运行 chmod 600 connections.json

退出码

0：成功
1：错误（配置缺失、认证失败、无效查询、数据库错误）

工作流程

运行 --list 展示可用数据库
将用户意图与数据库 description 匹配
运行 --tables 或 --schema 探索结构
使用合适的 LIMIT 执行查询

技能介绍