read-only-postgres

PostgreSQL 只读查询技能

对已配置的 PostgreSQL 数据库执行安全的只读查询。

要求

• Python 3.8+
• psycopg2-binary：pip install -r requirements.txt

设置

在技能目录或 ~/.config/claude/read-only-postgres-connections.json 中创建 connections.json。

安全性：由于文件包含凭据，请将文件权限设为 600：

chmod 600 connections.json

{
  "databases": [
    {
      "name": "app-db-dev",
      "description": "Primary app database (public schema: users, organizations, orders, order_items, events)",
      "host": "localhost",
      "port": 5432,
      "database": "app_dev",
      "user": "app_user",
      "password": "app_password",
      "sslmode": "disable"
    },
    {
      "name": "app-db-staging",
      "description": "Staging database (same schema as primary app)",
      "host": "localhost",
      "port": 5432,
      "database": "app_staging",
      "user": "app_user",
      "password": "app_password",
      "sslmode": "disable"
    }
  ]
}

配置字段

字段	必填	描述
name	是	数据库标识符（不区分大小写）
description	是	此数据库包含的数据（用于自动选择）
host	是	数据库主机名
port	否	端口号（默认值：5432）
database	是	数据库名称
user	是	用户名
password	是	密码
sslmode	否	SSL 模式：disable、allow、prefer（默认值）、require、verify-ca、verify-full
pii_masking	否	将表名映射到要屏蔽的列名数组的对象

PII 屏蔽

在任意数据库配置中添加 pii_masking 字段，即可屏蔽查询结果中的敏感数据。中间字符会替换为 *，仅保留首尾字符。

{
  "name": "app-db-dev",
  "host": "localhost",
  "database": "app_dev",
  "user": "readonly",
  "password": "secret",
  "pii_masking": {
    "users": ["email", "phone", "first_name", "last_name"],
    "orders": ["shipping_address"]
  }
}

工作原理：

• [email protected] → j************m
• 555-1234 → 5******4
• Jo → Jo（字符数不超过 2 的内容不会被屏蔽）

查询匹配的表时会自动应用屏蔽。页脚说明会指出哪些列已被屏蔽。

用法

列出已配置的数据库

python3 scripts/query.py --list

查询数据库

python3 scripts/query.py --db app-db-dev --query "SELECT id, email, created_at FROM users LIMIT 10"

列出表

python3 scripts/query.py --db app-db-dev --tables

显示架构

python3 scripts/query.py --db app-db-dev --schema

限制结果数量

python3 scripts/query.py --db app-db-dev --query "SELECT id, status, total_amount FROM orders" --limit 100

数据库选择

将用户意图与数据库的 description 匹配：

用户询问的内容	查找描述中包含的词语
用户、账户	users、accounts
组织、团队	organizations、teams
订单、付款	orders、payments
事件、审计日志	events、audit、logs
分析或报告	analytics、reporting
后台任务或队列	jobs、queue、outbox

如果不确定，请运行 --list 并询问用户要使用哪个数据库。

安全功能

• 只读会话：连接使用 PostgreSQL 的 readonly=True 模式（主要防护措施）
• 查询验证：仅允许 SELECT、SHOW、EXPLAIN、WITH 查询（会移除注释和字面量；会阻止 DDL/DML 关键字、数据修改型 CTE、SELECT INTO 以及序列修改函数）
• 单条语句：拒绝每个查询包含多条语句的情况
• SSL 支持：可配置 SSL 模式以建立加密连接
• 查询超时：强制执行 30 秒语句超时
• 内存保护：每个查询最多返回 10,000 行，以防止内存溢出
• 列宽上限：每列最多 100 个字符，以便于阅读输出
• 凭据清理：错误消息不会泄露密码
• PII 屏蔽：可按表配置列屏蔽，以保护查询输出中的敏感数据

故障排除

错误	解决方案
找不到配置	在技能目录中创建 connections.json
身份验证失败	检查配置中的用户名和密码
连接超时	验证主机/端口，并检查防火墙/VPN
SSL 错误	对于本地数据库，尝试设置 "sslmode": "disable"
权限警告	运行 chmod 600 connections.json

退出代码

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

工作流

1. 运行 --list 以显示可用数据库
2. 将用户意图与数据库描述匹配
3. 运行 --tables 或 --schema 以查看结构
4. 执行带有适当 LIMIT 的查询