sqlmind

<div align="center"> <img src="docs/logo.svg" width="80" height="80" alt="SQLMind logo" /><br/> # SQLMind **LLM 智能层** *by [VeloceAI.in](https://veloceai.in/)* [](https://python.org) [](https://github.com/Veloce-AI/sqlmind/actions) [](LICENSE) [](https://pypi.org/project/sqlmind) [](#dialects) [](#mcp-server) 停止编写 SQL 提示。开始按执行顺序推理。<br/> SQLMind 为智能体提供 **属性图模式**、**7 阶段生成协议** 和 **5 层验证门控**，适用于 10 种 SQL 引擎和任意框架。 [快速开始](#quick-start) · [文档](https://github.com/Veloce-AI/sqlmind/wiki) · [贡献](CONTRIBUTING.md) </div> <div align="center"> <img src="docs/sqlmind_hero.svg" width="100%" alt="SQLMind hero" /> </div> --- ## 工作原理 | 阶段 | 发生情况 | 需要 API 密钥？ | |---|---|---| | **01 属性图** | DSL / live DB / DDL → 表节点、列节点、FK 边 | 否 | | **02 模式链接** | 自然语言问题 → 匹配的表、列、BFS 连接路径 | 否 | | **03 分阶段锁定 SQL** | LLM 推理 FROM→WHERE→GROUP BY→HAVING→SELECT→ORDER BY→LIMIT | 是（仅限 LLM） | | **04 验证门控** | 5 层：阶段 · JOIN · 模式 · 方言 · 语法 | 否 | API 密钥仅在第 3 阶段使用 - 即决定调用哪个工具的 LLM。 所有工具、图引擎、验证和方言规则都是纯 Python 实现。 --- ## 为什么选择 SQLMind | 功能 | SQLMind | 原始 LLM | LangChain SQL 代理 | |---|---|---|---| | 分阶段锁定推理 | ✅ 内置 7 阶段协议 | ❌ 仅写入顺序 | ❌ 单个提示 | | 模式作为属性图 | ✅ 表节点 + FK 边 | ❌ 仅原始文本 | ⚠️ DDL 字符串注入 | | 连接路径发现 | ✅ FK 图上的 BFS | ❌ 从文本中猜测 | ❌ 不可用 | | 执行前验证 | ✅ 5 个独立层 | ❌ 无 | ⚠️ 仅基本语法 | | 自我纠正循环 | ✅ 有针对性，最多 2 次重试 | ❌ 无 | ⚠️ 执行错误重试 | | 多方言支持 | ✅ 10 种方言，可编辑 YAML | ❌ 临时每提示 | ⚠️ 方言参数仅限 | | MCP 服务器 | ✅ 8 种工具，编辑器就绪 | ❌ 无 | ❌ 无 | | 工具需要 API 密钥 | ✅ 纯 Python - 无密钥 | ❌ 始终 | ❌ 始终 | --- ## 快速开始 ### 安装 SQLMind 尚未在 PyPI 上发布。直接从源代码安装： ```bash # 克隆仓库 git clone https://github.com/Veloce-AI/sqlmind.git cd sqlmind # 创建并激活虚拟环境（推荐） python -m venv .venv source .venv/bin/activate # Linux / Mac .venv\Scripts\activate # Windows # 安装所有额外功能 pip install -e ".[all]" # 或仅安装核心 + 数据库 + 图 pip install -e ".[db,graph]" ``` > **PyPI 版本即将发布。** 发布后，可以使用 `pip install sqlmind` 命令安装。 ### 设置 API 密钥 ```bash cp .env.example .env # 编辑 .env - 添加您的密钥： # ANTHROPIC_API_KEY=sk-ant-... ``` ### 5 个命令生成 SQL ```bash # 1. 检查模式文件 python sqlmind_graph.py inspect examples/schema.sqlmind.yaml # 2. 在两个表之间查找连接路径 python sqlmind_graph.py join-path examples/schema.sqlmind.yaml orders products # 3. 将自然语言问题链接到模式 python sqlmind_graph.py link examples/schema.sqlmind.yaml "按客户区域划分的收入" # 4. 导出 Mermaid ERD python sqlmind_graph.py erd examples/schema.sqlmind.yaml > schema.mmd # 5. 从自然语言生成 SQL（调用 Anthropic API） python sqlmind_graph.py generate examples/schema.sqlmind.yaml \ "上个月按总收入排名前 10 的客户" \ --dialect postgresql ``` --- ## 仓库结构 ``` sqlmind/ ├── sqlmind_graph.py ← 属性图引擎（SchemaGraph、DialectRegistry、CLI） ├── sqlmind_mcp_server.py ← MCP 服务器（8 种工具） ├── sqlmind.py ← 独立 Python ADK 代理 ├── dialects.yaml ← 用户可编辑的方言配置（10 种引擎） ├── SKILL.md ← Claude Code 技能（分阶段协议） ├── CLAUDE.md ← 放入项目根目录以激活技能 ├── docs/ │ ├── sqlmind_hero.svg ← 宽英雄图像（1360×680）用于 GitHub README 顶部 │ └── logo.svg ← 独立图标（200×200）用于 favicon / 社交预览 ├── integrations/ │ ├── sqlmind_google_adk.py ← Google ADK 代理 │ ├── sqlmind_openai_agents.py ← OpenAI Agents SDK 代理 │ └── sqlmind_langgraph.py ← LangGraph 代理 + FastAPI 服务器 ├── tests/ │ ├── test_graph.py ← 图引擎测试（14 个测试） │ └── test_dialects.py ← 方言注册表测试 ├── examples/ │ └── schema.sqlmind.yaml ← 示例模式（orders/customers/products） ├── pyproject.toml ├── .env.example ├── CONTRIBUTING.md └── .github/workflows/ci.yml ← GitHub Actions CI（推送时 pytest） ``` --- ## 属性图工作原理 ```python from sqlmind_graph import SchemaGraph # 从 .sqlmind.yaml 加载 graph = SchemaGraph().load_from_yaml("examples/schema.sqlmind.yaml") # 从实时数据库加载（需要 sqlalchemy） graph = SchemaGraph().load_from_db("postgresql://user:pass@localhost/mydb") # 从 DDL 加载 graph = SchemaGraph().load_from_ddl(""" CREATE TABLE orders ( id SERIAL PRIMARY KEY, customer_id INTEGER REFERENCES customers(id), amount NUMERIC(10,2) ); """) # BFS 连接路径发现 path = graph.find_join_path("orders", "products") print(path.to_sql()) # orders # INNER JOIN order_items ON orders.id = order_items.order_id # INNER JOIN products ON order_items.product_id = products.id # 别名感知列验证 errors = graph.validate_sql_columns("SELECT o.bad_col FROM orders o") # → [{"type": "COLUMN_NOT_FOUND", "table": "orders", "column": "bad_col", ...}] ``` --- ## 模式 DSL 格式 `.sqlmind.yaml` 文件是规范的模式格式： ```yaml tables: orders: name: orders description: "客户购买订单" row_count: 2500000 columns: - { name: id, type: INT, pk: true } - { name: customer_id, type: INT, fk: true, references: customers.id, indexed: true } - { name: amount, type: DECIMAL } - { name: status, type: VARCHAR, enum: [pending, confirmed, shipped, cancelled] } - { name: created_at, type: TIMESTAMP, indexed: true } edges: - { from_table: orders, from_col: customer_id, to_table: customers, to_col: id } ``` 您也可以使用紧凑的 DSL 表示法编写模式（支持 `load_from_dsl`）： ``` TABLE orders ( id INT PK customer_id INT FK→customers.id IDX amount DECIMAL status VARCHAR [pending, confirmed, shipped, cancelled] created_at TIMESTAMP IDX ) ``` --- ## 方言 10 种 SQL 引擎开箱即用 - 所有规则都存放在 `dialects.yaml` 中： | ID | 引擎 | 关键区别 | |---|---|---| | `postgresql` | PostgreSQL | `ILIKE`, `::` 强制转换，`STRING_AGG`，`RETURNING` | | `mysql` | MySQL / MariaDB | 反引号，`GROUP_CONCAT`，无 `DATE_TRUNC` | | `sqlite` | SQLite | 无 `RIGHT JOIN`，`strftime()`，宽容的 `GROUP BY` | | `mssql` | SQL Server (T-SQL) | `TOP`，`GETDATE()`，`OFFSET/FETCH`，`[]` 标识符 | | `bigquery` | Google BigQuery | 反引号表，`QUALIFY`，`ARRAY_AGG`，`EXCEPT DISTINCT` | | `snowflake` | Snowflake | `QUALIFY`，`ILIKE`，`LISTAGG`，`TRY_CAST` | | `redshift` | Amazon Redshift | `LISTAGG`，`GETDATE()`，`ILIKE`，有限数组 | | `databricks` | Databricks SQL | `COLLECT_LIST`，`LATERAL VIEW EXPLODE`，时间旅行 | | `spark_sql` | Apache Spark SQL | `RLIKE`，`LATERAL VIEW EXPLODE`，`COLLECT_LIST` | | `oracle` | Oracle 数据库 | `FETCH FIRST`，`SYSDATE`，`NVL`，`CONNECT BY`，`MINUS` | 添加您自己的 - 复制 `dialects.yaml` 中的任何块并覆盖不同的字段。 --- ## MCP 服务器 ### Claude Code ```bash # 添加到 Claude Code（stdio 模式 - 适用于任何目录） claude mcp add sqlmind --command python --args /path/to/sqlmind_mcp_server.py # 或将 CLAUDE.md 放入项目根目录 - Claude Code 自动发现它 ``` 连接后，可使用 8 种工具： | 工具 | 功能 | |---|---| | `sqlmind_introspect` | 连接到实时数据库 → 返回 SQLMind DSL 模式 | | `sqlmind_link_schema` | 将 NL 实体映射到表、列和连接路径 | | `sqlmind_validate` | 对任何 SQL 字符串进行 7 阶段 + 模式列检查 | | `sqlmind_build_prompt` | 构建分阶段生成提示 | | `sqlmind_generate` | 通过 Anthropic API 从 NL 生成 SQL，自动验证 | | `sqlmind_explain` | 运行 `EXPLAIN ANALYZE` 并总结计划 | | `sqlmind_transpile` | 通过 sqlglot 在方言之间转换 SQL | | `sqlmind_score_complexity` | L1–L4 复杂度评分 + 生成策略 | 示例提示，连接后输入 Claude Code： ``` 在 postgresql://localhost/mydb 上运行 sqlmind_introspect，然后使用 sqlmind_generate 编写 SQL 以获取“按客户层级划分的每月收入”。 ``` ### Cursor 1. 打开 **Cursor 设置 → MCP → 添加服务器** 2. 名称：`sqlmind` | 命令：`python` | 参数：`["/absolute/path/sqlmind_mcp_server.py"]` 3. 重启 Cursor。工具出现在 Agent 面板中（Cmd+I / Ctrl+I）。 ### Windsurf (Codeium) 在项目根目录中将以下内容添加到 `.windsurf/config.json` 中： ```json { "mcp": { "servers": { "sqlmind": { "command": "python", "args": ["sqlmind_mcp_server.py"], "cwd": "/path/to/sqlmind" } } } } ``` 重新加载 Windsurf。 Cascade 代理现在可以调用所有 8 个 sqlmind 工具。 ### Codex / OpenAI 插件 / HTTP 客户端 ```bash # 以 HTTP 模式启动 python sqlmind_mcp_server.py --transport http --port 8765 # 将任何基于 HTTP 的 MCP 客户端指向： # http://localhost:8765 ``` ### Antispace / 任何支持 MCP 协议的客户端 任何支持 MCP 协议的工具都可以通过 stdio 或 HTTP 模式连接。使用上面的命令行。 --- ## 代理框架集成 ### Google ADK ```python from integrations.sqlmind_google_adk import create_sqlmind_agent agent = create_sqlmind_agent( schema_path="examples/schema.sqlmind.yaml", dialect="bigquery", ) result = await agent.run("last quarter top 5 products by revenue") print(result.sql) ``` 部署到 Vertex AI 代理引擎： ```bash gcloud ai agents deploy sqlmind-agent \ --region=us-central1 \ --source=integrations/sqlmind_google_adk.py ``` ### OpenAI 代理 SDK ```python from integrations.sqlmind_openai_agents import build_sql_agent agent = build_sql_agent(schema_yaml="examples/schema.sqlmind.yaml") result = agent.run("monthly revenue by region") print(result.final_output) ``` ### LangGraph + FastAPI ```bash # 启动流式 FastAPI 服务器 uvicorn integrations.sqlmind_langgraph:app --reload --port 8000 # POST 查询 curl -X POST http://localhost:8000/generate \ -H "Content-Type: application/json" \ -d '{"query": "orders placed last week", "dialect": "postgresql"}' ``` --- ## 运行测试 ```bash # 安装开发依赖 pip install -e ".[db,graph,dev]" # 运行所有测试 pytest tests/ -v # 运行覆盖率报告 pytest tests/ --cov=sqlmind_graph --cov-report=term-missing ``` 当前套件：**18 个测试，全都通过**（14 图 + 4 方言）。 --- ## 部署 MCP 服务器 ### Docker ```dockerfile FROM python:3.11-slim WORKDIR /app COPY . . RUN pip install -e ".[db,graph]" EXPOSE 8765 CMD ["python", "sqlmind_mcp_server.py", "--transport", "http", "--port", "8765"] ``` ```bash docker build -t sqlmind-mcp . docker run -p 8765:8765 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY sqlmind-mcp ``` ### Railway ```toml # railway.toml [build] builder = "NIXPACKS" [deploy] startCommand = "python sqlmind_mcp_server.py --transport http --port $PORT" healthcheckPath = "/" restartPolicyType = "ON_FAILURE" ``` --- ## CLI 参考 ``` python sqlmind_graph.py <command> [options] Commands: inspect <file> 打印模式统计 + DSL join-path <file> <t1> <t2> 在两个表之间查找最短连接路径 link <file> <query> 链接自然语言查询到模式 erd <file> 将 Mermaid ERD 导出到 stdout generate <file> <query> 通过 Anthropic API 从 NL 生成 SQL --dialect 目标 SQL 方言（默认为 postgresql） --model 模型 ID（默认为 claude-sonnet-4-6） ``` --- ## 贡献者 感谢所有为 SQLMind 做出贡献的人！ <a href="https://github.com/Veloce-AI/sqlmind/graphs/contributors"> <img src="https://contrib.rocks/image?repo=Veloce-AI/sqlmind" /> </a> 贡献欢迎！参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何： - 在 `dialects.yaml` 中添加新的 SQL 方言 - 编写新的验证规则 - 添加代理框架集成 - 运行测试套件并打开 PR --- <div align="center"> **SQLMind** · LLM 智能层 由 [VeloceAI.in](https://veloceai.in/) 开发 - 为社区开源 [GitHub](https://github.com/Veloce-AI/sqlmind) · [Discord](https://discord.gg/veloceai) · [MIT License](LICENSE) </div>