sqlsense (Raj8github)

🛡️ SQLSense

通过MCP为AI代理提供安全、经过审计的SQL。

AI代理正在与您的数据库进行对话。SQLSense确保他们不会破坏它。

pip install sqlsense
sqlsense serve --dsn "postgresql://user:pass@localhost/mydb"

](https://pypi.org/project/sqlsense/)   ](https://pypi.org/project/sqlsense/)

______________________________________________________________________

问题

您正在让AI代理访问您的数据库。它生成SQL，执行它。可能会出什么问题？

-- Agent confidently generates this
DELETE FROM users;

-- Or this
SELECT password, ssn, credit_card FROM customers;

-- Or this  
DROP TABLE orders;

没有现有的MCP数据库工具阻止这些。SQLSense确实如此。

______________________________________________________________________

SQLSense做什么

SQLSense是一个 MCP服务器 它将数据库连接包装为：

• 🚫 护栏 --在危险查询到达数据库之前阻止它们
• 🔒 只读模式 --默认情况下仅选择，写入opt-in
• 📋 审计日志 --代理运行的每个查询都记录到JSONL
• 🔢 自动限制 --自动为SELECT查询加上限以防止全表扫描
• 🙈 立柱堵塞 --块列表敏感列(password, ssn, api_key...)
• 💉 注射防护装置 --解析时阻止多语句查询
• 🗄️ 多数据库 --SQLite、PostgreSQL、MySQL、SQL Server、Snowflake、DuckDB、BigQuery

______________________________________________________________________

快速入门

安装

pip install sqlsense

# With your database driver
pip install "sqlsense[postgres]"    # PostgreSQL
pip install "sqlsense[mysql]"       # MySQL / MariaDB (AWS RDS, Azure MySQL)
pip install "sqlsense[sqlserver]"   # SQL Server
pip install "sqlsense[snowflake]"  # Snowflake
pip install "sqlsense[duckdb]"     # DuckDB (local analytics, Python-native)
pip install "sqlsense[bigquery]"   # Google BigQuery (auth via ADC)
pip install "sqlsense[all]"        # Everything

SQL Server--需要额外步骤

pyodbc （由安装 sqlsense[sqlserver])需要 Microsoft ODBC驱动程序17 安装在操作系统级别。 pip 不能做这部分。

macOS：

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql17

Ubuntu/Debian：

curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list \
  | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17

窗户： 下载自 微软的ODBC驱动程序页面 并运行安装程序。

启动MCP服务器

# PostgreSQL (readonly by default)
sqlsense serve --dsn "postgresql://user:pass@localhost/mydb"

# SQL Server (common in enterprise/fintech)
sqlsense serve --dsn "mssql://user:pass@server:1433/mydb"

# MySQL / MariaDB (AWS RDS, Aurora, Azure Database for MySQL)
sqlsense serve --dsn "mysql://user:pass@host:3306/mydb"

# Snowflake
sqlsense serve --dsn "snowflake://user:pass@account/warehouse/database"

# BigQuery (auth via GOOGLE_APPLICATION_CREDENTIALS or ADC)
sqlsense serve --dsn "bigquery://my_project/my_dataset"

# SQLite (great for local dev)
sqlsense serve --dsn "sqlite:///./myapp.db"

# DuckDB (local analytics, dbt-style workflows)
sqlsense serve --dsn "duckdb:///./analytics.duckdb"
# or in-memory: duckdb://:memory:

连接到克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sqlsense": {
      "command": "sqlsense",
      "args": ["serve", "--dsn", "postgresql://user:pass@localhost/mydb"]
    }
  }
}

Claude现在拥有安全、经过审核的数据库访问权限。问它：

*“按订单价值显示本月前10名客户”*

SQLSense拦截每个查询，对照护栏检查它，记录它，然后安全地执行它或以明确的理由阻止它。

连接到克劳德代码

# In your project
claude mcp add sqlsense -- sqlsense serve --dsn "postgresql://..."

______________________________________________________________________

凭证——永远不要硬编码

切勿将数据库凭据直接放入MCP配置或shell历史记录中。请改用这些模式之一。

选项1--包装脚本（推荐）

创建一个脚本，在运行时从您的秘密存储中提取凭据：

# ~/scripts/sqlsense-mydb.sh
#!/bin/bash
sqlsense serve \
  --dsn "postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/${DB_NAME}" \
  --max-rows 1000 \
  --audit-log ~/.sqlsense/audit.jsonl

chmod +x ~/scripts/sqlsense-mydb.sh

然后，您的Claude Desktop配置保持干净——任何地方都没有凭据：

{
  "mcpServers": {
    "mydb": {
      "command": "/Users/you/scripts/sqlsense-mydb.sh"
    }
  }
}

选项2-macOS钥匙扣

# Store once
security add-generic-password -a sqlsense -s db-password -w "your_password"

# Retrieve in your wrapper script
DB_PASS=$(security find-generic-password -a sqlsense -s db-password -w)

选项3——通过 env 块

Claude Desktop支持 env 配置中的块--凭据不在其中 args:

{
  "mcpServers": {
    "mydb": {
      "command": "sqlsense",
      "args": ["serve", "--dsn", "postgresql://$(DB_USER):$(DB_PASS)@$(DB_HOST)/$(DB_NAME)"],
      "env": {
        "DB_USER": "myuser",
        "DB_PASS": "mypassword",
        "DB_HOST": "localhost",
        "DB_NAME": "mydb"
      }
    }
  }
}

选项4-- .env 带有加载器的文件

# .env (never commit this)
DB_USER=myuser
DB_PASS=mypassword
DB_HOST=localhost
DB_NAME=mydb

# wrapper script
#!/bin/bash
set -a && source ~/.sqlsense/.env && set +a
sqlsense serve --dsn "postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}/${DB_NAME}"

______________________________________________________________________

护栏正在运行

# Test any query before running it
$ sqlsense check "DELETE FROM users"
🚫 BLOCKED  (risk: HIGH)
Reason: DELETE is blocked. Set allow_delete=True to enable.

$ sqlsense check "SELECT * FROM orders"
✅ ALLOWED  (risk: MEDIUM)
Warnings:
  • SELECT * detected — prefer explicit column names.
  • No WHERE clause — query may scan the full table.
  • LIMIT 1000 automatically added to protect against full-table scans.

$ sqlsense check "SELECT id FROM users WHERE id = 1"
✅ ALLOWED  (risk: LOW)
Hash: a3f9c2d1b8e4

______________________________________________________________________

配置

所有护栏均可配置。违约是故意保守的。

# Allow writes (careful!)
sqlsense serve --dsn "..." --allow-writes

# Increase row limit
sqlsense serve --dsn "..." --max-rows 5000

# Block specific tables
sqlsense serve --dsn "..." \
  --block-table audit_log \
  --block-table internal_config

# Disable auto-LIMIT (not recommended)
sqlsense serve --dsn "..." --no-auto-limit

或者以编程方式配置：

from sqlsense import SQLSenseMCPServer
from sqlsense.guardrails import GuardrailConfig

config = GuardrailConfig(
    max_rows=2000,
    readonly_mode=True,           # default: True
    auto_add_limit=True,          # default: True
    blocked_tables=["secrets"],
    blocked_columns=["password", "token", "ssn", "credit_card"],
    require_where_on_writes=True, # default: True
)

server = SQLSenseMCPServer(dsn="postgresql://...", config=config)
server.run()

______________________________________________________________________

审计日志

代理运行的每个查询都会写入JSONL文件：

# View recent queries
sqlsense audit --tail 20

# Output
TIME                   ALLOWED  RISK    ROWS   MS     SQL
────────────────────────────────────────────────────────────────────────────────────────────
2025-02-26T14:22:01Z   ✅       low     42     12.3   SELECT id, name FROM customers WHE...
2025-02-26T14:22:15Z   🚫       high    —      —      DELETE FROM users
2025-02-26T14:22:31Z   ✅       medium  1000   891.2  SELECT * FROM orders

# JSON output for piping to your observability stack
sqlsense audit --tail 100 --json | jq '.[] | select(.allowed == false)'

每个条目都是一个自包含的JSON对象，Splunk、Datadog、CloudWatch或 grep.

______________________________________________________________________

MCP工具

SQLSense向AI代理公开了4个工具：

代理人打电话来 get_schema 首先了解数据库，然后 explain_query 在执行之前进行验证——SQLSense将代理推向更安全的模式。

______________________________________________________________________

支持的数据库

______________________________________________________________________

与其他AI框架一起使用

SQLSense是一个MCP服务器，因此它适用于任何讲MCP的东西：

• ✅ 克劳德桌面版
• ✅ 克劳德代码
• ✅ 任何与MCP兼容的代理框架
• ✅ 自定义代理（通过stdio JSON-RPC）

______________________________________________________________________

Python API

如果不需要MCP层，请使用SQLSense作为库：

from sqlsense.guardrails import GuardrailsEngine, GuardrailConfig
from sqlsense.connectors import create_connector
from sqlsense.audit import AuditLogger

# Guardrails only
engine = GuardrailsEngine(GuardrailConfig())
result = engine.check("SELECT * FROM users")
if not result.allowed:
    raise PermissionError(result.reason)

# Full stack
db = create_connector("postgresql://user:pass@localhost/mydb")
logger = AuditLogger("./audit.jsonl")

guard = engine.check(sql)
if guard.allowed:
    safe_sql = guard.rewritten_sql or sql
    query_result = db.execute(safe_sql)
    logger.record(sql, guard, rows_returned=query_result.row_count)

______________________________________________________________________

路线图

• \[\]HTTP/SSE传输（除了stdio）
• \[\]MySQL连接器
• \[\]BigQuery连接器
• \[\]DuckDB连接器
• \[\]用于审计日志的Web仪表板
• \[\]查询成本估算（EXPLAIN集成）
• \[\]每个代理/会话的速率限制
• \[\]行级安全策略
• \[\]对被阻止的查询发出Slack/webhook警报
• \[\]Docker镜像

______________________________________________________________________

贡献

非常欢迎捐款。现在最有用的东西：

1. 新的数据库连接器 --MySQL、BigQuery、DuckDB（参见 sqlsense/connectors.py)
2. 护栏改进 --边缘情况，方言特定规则
3. HTTP传输 --用于远程部署的SSE服务器
4. 测试 --更多边缘情况 tests/test_sqlsense.py

git clone https://github.com/raj8github/sqlsense
cd sqlsense
pip install -e ".[dev]"
pytest tests/ -v

看 贡献.md 了解详情。

______________________________________________________________________

为什么存在

具有数据库访问权限的AI代理功能强大。它们也是一个糟糕的提示 DELETE FROM production_users 没有WHERE子句。

MCP数据库工具（sqlite-MCP、postgres-MCP等）的当前生态系统为代理提供了原始访问，没有护栏、没有审计跟踪，也没有断路器。SQLSense填补了这一空白——它是用生产金融科技环境中的模式构建的，在这些环境中，数据库安全不是可选的。

______________________________________________________________________

许可证

麻省理工学院——见 许可证