# TextToSQL **Repository Path**: li-xu-289/text-to-sql ## Basic Information - **Project Name**: TextToSQL - **Description**: TextToSQL是一个开源工具，允许用户使用自然语言查询数据库。它通过模型上下文协议(MCP)利用AI能力来解释用户查询，生成适当的SQL语句，并在数据库上执行它们。 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 53 - **Forks**: 8 - **Created**: 2025-08-13 - **Last Updated**: 2026-02-04 ## Categories & Tags **Categories**: database-dev **Tags**: None ## README

TextToSQL v2.0.0

基于MCP协议的多数据库自然语言查询工具，直接用对话方式获取数据库信息，无需编写SQL！

[English](README.md) | [中文简体](README_CN.md) ## 官网：TextToSQL ## v2.0 新特性 - **多数据库支持**：同时连接和查询多个数据库 - **YAML配置**：简洁清晰的配置文件格式 - **连接池管理**：使用DBUtils高效管理数据库连接 - **双层缓存**：内存(L1) + 文件(L2)缓存，优化性能 - **安全增强**：SQL校验防止危险操作 - **分层架构**：清晰的关注点分离，便于维护 ## 概述 TextToSQL是一个开源工具，允许用户使用自然语言查询数据库。它通过模型上下文协议(MCP)利用AI能力来解释用户查询，生成适当的SQL语句，并在多个数据库上执行。 ## 特性 - **自然语言查询**：使用普通中文或英文查询您的数据库 - **多数据库支持**：配置并在多个数据库之间切换 - **SQL生成**：自动将自然语言转换为优化的SQL查询 - **智能缓存**：双层缓存（内存+文件），自动刷新 - **连接池管理**：为每个数据库高效管理连接 - **支持复杂查询**：处理JOIN、子查询、聚合等 - **安全优先**：仅允许SELECT查询，阻止危险操作 ## 架构 ``` texttosql/ ├── main.py # MCP服务入口 ├── config.yaml # 数据库配置（从示例创建） ├── config.yaml.example # 配置模板 ├── requirements.txt # Python依赖 │ ├── config/ # 配置管理 │ └── settings.py # YAML配置加载器 │ ├── services/ # 业务逻辑层 │ ├── database_manager.py # 多数据库连接管理 │ ├── schema_service.py # 表结构与缓存 │ └── query_service.py # SQL查询执行 │ ├── repositories/ # 数据访问层 │ └── mysql_repository.py # MySQL连接池 │ └── utils/ # 工具函数 ├── sql_validator.py # SQL安全校验 └── response_formatter.py # 响应格式化 ``` ## 安装 ### 前提条件 - Python 3.8或更高版本 - 访问MySQL/MariaDB数据库的权限 ### 设置 1. 克隆仓库： ```bash git clone https://gitee.com/li-xu-289/text-to-sql.git cd text-to-sql ``` 2. 安装依赖： ```bash pip install -r requirements.txt ``` 3. 创建配置文件： ```bash cp config.yaml.example config.yaml ``` 4. 编辑 `config.yaml` 填写您的数据库凭据： ```yaml databases: - name: "生产库" alias: "prod" host: "your-host" port: 3306 database: "your_database" username: "your_username" password: "your_password" default_database: "prod" ``` ## 使用方法 ### 启动MCP服务器 ```bash python main.py ``` ### 在Claude Desktop或其他MCP客户端中配置： ```json { "mcpServers": { "TextToSQL Bot": { "command": "python", "args": ["/path/to/texttosql/main.py"], "transport": "stdio" } } } ``` ### 查询示例 - "显示IT部门的所有员工" - "按部门统计平均薪资是多少？" - "查找过去3个月内下单的客户" - "列出销售量前5的产品" - "切换到测试数据库，显示所有表" ## MCP工具 系统通过MCP接口提供三个工具： ### list_databases 列出所有配置的数据库及连接状态。 ```python # 返回可用数据库列表 list_databases() # 响应: {"databases": [{"name": "生产库", "alias": "prod", ...}], "count": 2} ``` ### get_table_schema 获取数据库结构信息，带智能缓存。 ```python # 获取默认数据库的所有表 get_table_schema() # 获取指定数据库的所有表 get_table_schema(database="prod") # 获取指定表的字段信息 get_table_schema(table_name="employees") # 获取指定数据库中某张表的字段 get_table_schema(database="test", table_name="orders") ``` ### query_database 执行SQL SELECT查询（INSERT/UPDATE/DELETE被阻止）。 ```python # 简单查询 query_database("SELECT * FROM employees WHERE department = 'IT'") # 带限制的查询 query_database("SELECT * FROM logs", database="logs", limit=50) # 复杂JOIN查询 query_database(""" SELECT e.name, d.department_name, e.salary FROM employees e JOIN departments d ON e.dept_id = d.id WHERE e.salary > 50000 """, limit=20) ``` ## 配置说明 ### config.yaml 结构 ```yaml # 数据库配置列表 databases: - name: "生产库" # 显示名称 alias: "prod" # 别名（API调用使用） host: "192.168.1.100" # 数据库主机 port: 3306 # 端口号 database: "business_db" # 数据库名 username: "app_user" # 用户名 password: "secure_password" # 密码 charset: "utf8mb4" # 字符集 max_connections: 10 # 连接池大小 - name: "测试库" alias: "test" host: "192.168.1.101" # ... 其他配置 # 默认数据库（未指定时使用） default_database: "prod" # 缓存配置 cache: ttl_seconds: 3600 # 内存缓存过期时间（1小时） file_ttl_seconds: 86400 # 文件缓存过期时间（24小时） cache_dir: "cache" # 缓存目录 cache_file: "schema_cache.json" # 缓存文件名 ``` ## 安全特性 - **仅限SELECT**：只允许SELECT查询 - **SQL注入防护**：参数化查询和校验 - **危险关键字拦截**：DROP、DELETE、INSERT、UPDATE、TRUNCATE、ALTER等 - **注释拦截**：不允许SQL注释（-- 和 /* */） - **多语句拦截**：只允许单条语句 ## 许可证 该项目采用MIT许可证 - 详情请参阅LICENSE文件。 ## 贡献 欢迎贡献！请随时提交Pull Request。 ## 联系与支持 ### 联系我 微信二维码 ### 支持本项目 赞赏码