xsql

xsql

让 AI 安全地查询你的数据库 🤖🔒

xsql 是专为 AI Agent 设计的跨数据库 CLI 工具。默认只读、结构化输出、开箱即用。

# AI 可以这样查询你的数据库
xsql query "SELECT * FROM users WHERE created_at > '2024-01-01'" -p prod -f json

✨ 为什么选择 xsql？

🚀 30 秒上手

1. 安装

# macOS
brew install zx06/tap/xsql

# Windows
scoop bucket add zx06 https://github.com/zx06/scoop-bucket && scoop install xsql

# 或直接下载: https://github.com/zx06/xsql/releases

2. 配置

mkdir -p ~/.config/xsql
cat > ~/.config/xsql/xsql.yaml << 'EOF'
profiles:
  dev:
    db: mysql
    host: 127.0.0.1
    port: 3306
    user: root
    password: your_password
    database: mydb
    allow_plaintext: true  # 生产环境建议用 keyring
EOF

3. 使用

xsql query "SELECT 1" -p dev -f json
# {"ok":true,"schema_version":1,"data":{"columns":["1"],"rows":[{"1":1}]}}

🤖 让 AI 使用 xsql

方式一：Claude Code Plugin（推荐）

# 1. 添加 marketplace
/plugin marketplace add zx06/xsql

# 2. 安装插件
/plugin install xsql@xsql

安装后 Claude 自动获得 xsql 技能，可直接查询数据库。

方式二：复制 Skill 给任意 AI

将以下内容发送给你的 AI 助手（ChatGPT/Claude/Cursor 等）：

你现在可以使用 xsql 工具查询数据库。

## 基本用法
xsql query "<SQL>" -p <profile> -f json

## 可用命令
- xsql query "SQL" -p <profile> -f json  # 执行查询
- xsql profile list -f json               # 列出所有 profile
- xsql profile show <name> -f json        # 查看 profile 详情

## 输出格式
成功: {"ok":true,"schema_version":1,"data":{"columns":[...],"rows":[...]}}
失败: {"ok":false,"schema_version":1,"error":{"code":"XSQL_...","message":"..."}}

## 重要规则
1. 默认只读模式，无法执行 INSERT/UPDATE/DELETE
2. 始终使用 -f json 获取结构化输出
3. 先用 profile list 查看可用的数据库配置
4. 检查 ok 字段判断执行是否成功

## 退出码
0=成功, 2=配置错误, 3=连接错误, 4=只读拦截, 5=SQL执行错误

方式三：MCP Server（Claude Desktop 等）

在 Claude Desktop 配置中添加 xsql MCP server：

{
  "mcpServers": {
    "xsql": {
      "command": "xsql",
      "args": ["mcp", "server", "--config", "/path/to/xsql.yaml"]
    }
  }
}

启动后，Claude 可以直接通过 MCP 协议查询数据库。

方式四：AGENTS.md / Rules（Cursor/Windsurf）

在项目根目录创建 .cursor/rules 或编辑 AGENTS.md：

## 数据库查询

使用 xsql 工具查询数据库：
- 查询: `xsql query "SELECT ..." -p <profile> -f json`
- 列出配置: `xsql profile list -f json`

注意: 默认只读模式，写操作需要 --unsafe-allow-write 标志。

📖 功能详情

命令一览

输出格式

# JSON（AI/程序）
xsql query "SELECT id, name FROM users" -p dev -f json
{"ok":true,"schema_version":1,"data":{"columns":["id","name"],"rows":[{"id":1,"name":"Alice"}]}}

# Table（终端）
xsql query "SELECT id, name FROM users" -p dev -f table
id  name
--  -----
1   Alice

(1 rows)

SSH 隧道连接

ssh_proxies:
  bastion:
    host: jump.example.com
    user: admin
    identity_file: ~/.ssh/id_ed25519

profiles:
  prod:
    db: pg
    host: db.internal  # 内网地址
    port: 5432
    user: readonly
    password: "keyring:prod/password"
    database: mydb
    ssh_proxy: bastion  # 引用 SSH 代理

安全特性

• 双重只读保护：SQL 静态分析 + 数据库事务级只读
• Keyring 集成：password: "keyring:prod/password"
• 密码脱敏：profile show 不泄露密码
• SSH 安全：默认验证 known_hosts

📚 文档

License

MIT