mssql

MSSQL 只读查询技能

针对已配置的 Microsoft SQL Server 数据库执行安全的只读查询。

要求

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

设置

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

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

chmod 600 connections.json

{
  "databases": [
    {
      "name": "production",
      "description": "Main app database - users, orders, transactions",
      "host": "db.example.com",
      "port": 1433,
      "database": "app_prod",
      "user": "readonly_user",
      "password": "your-password",
      "encrypt": true,
      "tds_version": "7.3"
    }
  ]
}

配置字段

字段	必填	说明
name	是	数据库标识符（不区分大小写）
description	是	此数据库包含的数据（用于自动选择）
host	是	数据库主机名
port	否	端口号（默认值：1433）
database	是	数据库名称
user	是	用户名
password	是	密码
encrypt	否	启用 TLS 加密（默认值：false）
tds_version	否	TDS 协议版本：7.0、7.1、7.2、7.3、7.4（默认值：自动）

用法

列出已配置的数据库

python3 scripts/query.py --list

查询数据库

python3 scripts/query.py --db production --query "SELECT TOP 10 * FROM users"

列出表

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

注意：MSSQL 使用 TOP N，而不是 LIMIT。--limit 标志会自动在 SELECT 后插入 TOP N。

数据库选择

根据用户意图匹配数据库 description：

用户询问内容	查找说明中包含的内容
用户、账户	users、accounts、customers
订单、销售	orders、transactions、sales
分析、指标	analytics、metrics、reports
日志、事件	logs、events、audit

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

安全功能

• 只读限制：查询验证会阻止写入操作（使用 db_datareader 角色用户提供服务器端保护）
• 查询验证：仅允许 SELECT、SHOW、EXPLAIN、WITH、SP_HELP 查询
• 单条语句：拒绝每个查询包含多条语句的情况
• TLS 支持：可配置加密以建立安全连接
• 查询超时：通过 pymssql 强制执行 30 秒超时
• 连接超时：10 秒登录超时
• 内存保护：每个查询最多返回 10,000 行，以防止内存溢出
• 列宽上限：每列最多显示 100 个字符，便于阅读
• 凭据清理：错误消息不会泄露密码

故障排除

错误	解决方案
找不到配置	在技能目录中创建 connections.json
身份验证失败	检查配置中的用户名和密码
连接超时	检查主机和端口，并确认防火墙或 VPN 设置
TDS 版本错误	尝试使用 "tds_version": "7.3" 或 "7.4"
加密错误	为 Azure SQL 设置 "encrypt": true
权限警告	运行 chmod 600 connections.json

退出代码

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

工作流

1. 运行 --list 以显示可用数据库
2. 根据数据库说明匹配用户意图
3. 运行 --tables 或 --schema 以探索结构
4. 使用适当的 --limit 执行查询（自动转换为 TOP N）