# db-query **Repository Path**: liliangzi/db-query ## Basic Information - **Project Name**: db-query - **Description**: 通过ai助手使用自然语言查询数据库并导出数据，支持多种数据库类型mysql、postgres、达梦等。 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: 001-database-query-tool - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-02-02 - **Last Updated**: 2026-04-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: speckit, aicoding, Python, postgres, Postgresql ## README # Database Query Tool 一个支持多种数据库的自然语言查询工具，允许用户通过自然语言或 SQL 查询数据库，并支持结果导出。 ## 功能特性 ### 多数据库支持 支持以下数据库类型的连接和查询： | 数据库 | URL 格式 | 状态 | |--------|----------|------| | PostgreSQL | `postgresql://user:pass@host:5432/db` | ✅ 已测试 | | MySQL | `mysql://user:pass@host:3306/db` | ✅ 已测试 | | Oracle | `oracle://user:pass@host:1521/SID` | ✅ 支持 | | 达梦 (DM) | `dameng://user:pass@host:5236` | ✅ 支持 | ### 核心功能 - **数据库连接管理**: 添加、查看、删除数据库连接 - **元数据提取**: 自动提取表、视图、列信息 - **SQL 查询执行**: 执行 SELECT 查询，自动添加 LIMIT 保护 - **自然语言查询**: 使用 AI 将自然语言转换为 SQL - **结果导出**: 支持 CSV 和 JSON 格式导出 - **智能查询**: 带导出建议的查询功能 ### LLM 支持 支持多种 LLM 提供商： - OpenAI (GPT-4) - DeepSeek ## 技术架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend │ │ React 18 + TypeScript + Refine + Ant Design + Monaco Editor │ └─────────────────────────────────────────────────────────────┘ │ │ REST API (JSON camelCase) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend │ │ Python 3.11+ / FastAPI / Pydantic │ ├─────────────────────────────────────────────────────────────┤ │ Services: │ │ ├── DatabaseService - 数据库连接管理 │ │ ├── MetadataService - 元数据提取 │ │ ├── QueryService - SQL 查询执行 │ │ ├── NLService - 自然语言转 SQL (OpenAI/DeepSeek) │ │ └── StorageService - SQLite 本地存储 │ ├─────────────────────────────────────────────────────────────┤ │ Adapters: │ │ ├── PostgreSQLAdapter - PostgreSQL 适配器 │ │ ├── MySQLAdapter - MySQL 适配器 │ │ ├── OracleAdapter - Oracle 适配器 │ │ └── DamengAdapter - 达梦数据库适配器 │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ SQLite │ │ Target │ │ LLM │ │ (本地存储)│ │ Database │ │ API │ └──────────┘ └──────────┘ └──────────┘ ``` ## 工程结构 ``` db-query/ ├── backend/ # Python 后端 │ ├── src/ │ │ ├── main.py # FastAPI 应用入口 │ │ ├── config.py # 配置管理 │ │ ├── adapters/ # 数据库适配器 │ │ │ ├── base.py # 适配器基类 │ │ │ ├── factory.py # 适配器工厂 │ │ │ ├── postgresql_adapter.py │ │ │ ├── mysql_adapter.py │ │ │ ├── oracle_adapter.py │ │ │ └── dameng_adapter.py │ │ ├── models/ # Pydantic 数据模型 │ │ ├── services/ # 业务逻辑服务 │ │ ├── api/ # API 路由 │ │ └── utils/ # 工具函数 (SQL 解析等) │ ├── tests/ # 测试 │ ├── exports/ # 导出文件目录 │ └── pyproject.toml # 项目配置 │ ├── frontend/ # React 前端 │ ├── src/ │ │ ├── App.tsx # 主应用组件 │ │ ├── components/ # React 组件 │ │ │ ├── DatabaseList.tsx │ │ │ ├── MetadataViewer.tsx │ │ │ ├── SqlEditor.tsx │ │ │ ├── NaturalQuery.tsx │ │ │ └── ResultTable.tsx │ │ ├── pages/ # 页面组件 │ │ ├── services/ # API 客户端 │ │ └── types/ # TypeScript 类型 │ ├── package.json │ └── tsconfig.json │ ├── data/ # SQLite 数据库存储 ├── fixtures/ # 测试数据和 API 测试文件 │ └── test.rest # REST Client 测试文件 ├── specs/ # 功能规范文档 │ └── 001-database-query-tool/ │ ├── spec.md # 功能规范 │ ├── plan.md # 实施计划 │ ├── tasks.md # 任务清单 │ └── quickstart.md # 快速入门 └── Makefile # 项目命令 ``` ## 快速开始 ### 前置要求 - Python 3.11+ - Node.js 18+ - uv (Python 包管理器) - 目标数据库 (PostgreSQL/MySQL/Oracle/达梦) ### 1. 安装依赖 ```bash # 使用 Makefile 一键安装 make install # 或分别安装 make install-backend # 安装后端依赖 make install-frontend # 安装前端依赖 ``` ### 2. 配置环境变量 ```bash # 后端配置 cd backend cp .env.example .env # 编辑 .env 文件，设置以下变量： # - LLM_PROVIDER: openai 或 deepseek # - OPENAI_API_KEY: OpenAI API 密钥 (如使用 OpenAI) # - DEEPSEEK_API_KEY: DeepSeek API 密钥 (如使用 DeepSeek) # 前端配置 (可选，默认配置已可用) cd ../frontend cp .env.example .env # 默认 VITE_API_BASE_URL=/api/v1 ``` ### 3. 启动服务 ```bash # 同时启动前后端 make dev # 或分别启动 make dev-backend # 后端: http://localhost:8000 make dev-frontend # 前端: http://localhost:5173 ``` ### 4. 访问应用 - 前端界面: http://localhost:5173 - API 文档: http://localhost:8000/docs - API 测试: 使用 VS Code REST Client 打开 `fixtures/test.rest` ## API 使用示例 ### 添加数据库连接 ```bash # PostgreSQL curl -X PUT http://localhost:8000/api/v1/dbs/my-postgres \ -H "Content-Type: application/json" \ -d '{"url": "postgresql://user:pass@localhost:5432/mydb", "dbType": "postgresql"}' # MySQL curl -X PUT http://localhost:8000/api/v1/dbs/my-mysql \ -H "Content-Type: application/json" \ -d '{"url": "mysql://root:pass@localhost:3306/mydb", "dbType": "mysql"}' ``` ### 执行 SQL 查询 ```bash curl -X POST http://localhost:8000/api/v1/dbs/my-postgres/query \ -H "Content-Type: application/json" \ -d '{"sql": "SELECT * FROM users LIMIT 10"}' ``` ### 自然语言查询 ```bash curl -X POST http://localhost:8000/api/v1/dbs/my-postgres/query/natural \ -H "Content-Type: application/json" \ -d '{"prompt": "查询所有活跃用户的邮箱"}' ``` ### 导出查询结果 ```bash curl -X POST http://localhost:8000/api/v1/dbs/my-postgres/query/export \ -H "Content-Type: application/json" \ -d '{"sql": "SELECT * FROM users", "format": "csv"}' ``` ## 常用命令 ```bash make help # 查看所有可用命令 make dev # 启动开发服务器 make stop # 停止所有服务器 make test # 运行所有测试 make lint # 代码检查 make format # 代码格式化 make typecheck # 类型检查 make clean # 清理构建产物 make docker-db # 启动测试 PostgreSQL 容器 ``` ## 安全说明 - 仅支持 SELECT 查询，拒绝 INSERT/UPDATE/DELETE/DROP 等修改性语句 - 查询结果自动限制为 1000 行（如无 LIMIT 子句） - 数据库连接信息存储在本地 SQLite 中 ## 相关文档 - [后端 README](./backend/README.md) - 后端详细文档 - [前端 README](./frontend/README.md) - 前端详细文档 - [功能规范](./specs/001-database-query-tool/spec.md) - 详细功能规范 - [实施计划](./specs/001-database-query-tool/plan.md) - 技术实施计划 - [快速入门](./specs/001-database-query-tool/quickstart.md) - 开发快速入门 ## 更新日志 - **v1.1.0** - 增加多种数据库类型适配 (MySQL, Oracle, 达梦)，添加导出功能 - **v1.0.0** - 初始版本，支持 PostgreSQL，自然语言查询