mssql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MSSQL Read-Only Query Skill

MSSQL 只读查询技能

Execute safe, read-only queries against configured Microsoft SQL Server databases.

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

Requirements

要求

Python 3.8+
pymssql:
```
pip install -r requirements.txt
```

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

Setup

配置

Create

connections.json

in the skill directory or

~/.config/claude/mssql-connections.json

Security: Set file permissions to

since it contains credentials:

bash

chmod 600 connections.json

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"
    }
  ]
}

在技能目录或

~/.config/claude/mssql-connections.json

中创建

connections.json

文件。

安全提示：由于文件包含凭据，请将文件权限设置为

：

bash

chmod 600 connections.json

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"
    }
  ]
}

Config Fields

配置字段

Field	Required	Description
name	Yes	Identifier for the database (case-insensitive)
description	Yes	What data this database contains (used for auto-selection)
host	Yes	Database hostname
port	No	Port number (default: 1433)
database	Yes	Database name
user	Yes	Username
password	Yes	Password
encrypt	No	Enable TLS encryption (default: false)
tds_version	No	TDS protocol version: 7.0, 7.1, 7.2, 7.3, 7.4 (default: auto)

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

Usage

使用方法

List configured databases

列出已配置的数据库

bash

python3 scripts/query.py --list

bash

python3 scripts/query.py --list

Query a database

查询数据库

bash

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

bash

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

List tables

列出表

bash

python3 scripts/query.py --db production --tables

bash

python3 scripts/query.py --db production --tables

Show schema

查看架构

bash

python3 scripts/query.py --db production --schema

bash

python3 scripts/query.py --db production --schema

Limit results

限制结果数量

bash

python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

Note: MSSQL uses

TOP N

instead of

LIMIT

. The

--limit

flag automatically inserts

TOP N

after SELECT.

bash

python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

注意：MSSQL使用

TOP N

而非

LIMIT

。

--limit

标志会自动在SELECT后插入

TOP N

。

Database Selection

数据库选择

Match user intent to database

description

User asks about	Look for description containing
users, accounts	users, accounts, customers
orders, sales	orders, transactions, sales
analytics, metrics	analytics, metrics, reports
logs, events	logs, events, audit

If unclear, run

--list

and ask user which database.

根据用户意图匹配数据库

description

：

用户询问内容	查找包含以下关键词的描述
用户、账户	users、accounts、customers
订单、销售	orders、transactions、sales
分析、指标	analytics、metrics、reports
日志、事件	logs、events、audit

如果意图不明确，运行

--list

并询问用户要使用哪个数据库。

Safety Features

安全特性

Read-only enforcement: Query validation blocks write operations (use a
```
db_datareader
```
role user for server-side protection)
Query validation: Only SELECT, SHOW, EXPLAIN, WITH, SP_HELP queries allowed
Single statement: Multiple statements per query rejected
TLS support: Configurable encryption for secure connections
Query timeout: 30-second timeout enforced via pymssql
Connection timeout: 10-second login timeout
Memory protection: Max 10,000 rows per query to prevent OOM
Column width cap: 100 char max per column for readable output
Credential sanitization: Error messages don't leak passwords

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

Troubleshooting

故障排除

Error	Solution
Config not found	Create `connections.json` in skill directory
Authentication failed	Check username/password in config
Connection timeout	Verify host/port, check firewall/VPN
TDS version error	Try `"tds_version": "7.3"` or `"7.4"`
Encryption error	Set `"encrypt": true` for Azure SQL
Permission warning	Run `chmod 600 connections.json`

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

Exit Codes

退出码

0: Success
1: Error (config missing, auth failed, invalid query, database error)

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

Workflow

工作流程

Run
```
--list
```
to show available databases
Match user intent to database description
Run
```
--tables
```
or
```
--schema
```
to explore structure
Execute query with appropriate
```
--limit
```
(auto-converts to TOP N)

运行
```
--list
```
查看可用数据库
根据用户意图匹配数据库描述
运行
```
--tables
```
或
```
--schema
```
探索数据库结构
使用合适的
```
--limit
```
执行查询（自动转换为TOP N）