BigeSQL
Officialby bigedev
README.md
# BigeSQL — 开源多数据库管理工具 & MCP Server
一站式数据库管理工具 + AI MCP Server，支持 **MySQL/MariaDB、PostgreSQL、SQLite、达梦 DM8、SQL Server、Oracle**。
既是 **VS Code 插件**（图形化界面），也是 **MCP Server**（AI 助手可通过协议直接访问数据库），支持 stdio 和 HTTP 双模式。
---
## ✨ 功能特性
| 特性 | 说明 |
| ------------------- | ---------------------------------------------------------------------- |
| 🗄️ **多数据库支持** | MySQL / MariaDB / PostgreSQL / SQLite / 达梦 DM8 / SQL Server / Oracle |
| 🎨 **图形界面** | VS Code 侧边栏管理连接，Webview SQL 编辑器 |
| 🤖 **MCP 协议** | 支持 stdio + HTTP 双模式 |
| 🔌 **连接管理** | 添加/编辑/删除/测试数据库连接 |
| 📋 **表浏览器** | 树形展示表、视图、列结构 |
| ⌨️ **SQL 编辑器** | 语法高亮、执行查询、结果表格展示 |
| 📦 **批量执行** | 多语句脚本一次运行（事务保护）+ 参数化批量 DML |
| 🚦 **服务管理** | 扩展内一键启动/停止 MCP Server，状态栏指示 |
| 🔒 **安全** | 密码不硬编码，支持 `.gitignore` 排除 |
## 支持的数据库
| 数据库 | 驱动 | 方式 |
| ------------------- | ---------------------- | --------------------- |
| **MySQL / MariaDB** | `mysql2` | TCP 直连 |
| **PostgreSQL** | `pg` | TCP 直连 |
| **SQLite** | `node:sqlite`（内置） | 本地文件 |
| **达梦 DM8** | `dmdb`（官方驱动） | TCP 直连，无需 ODBC |
| **SQL Server** | `mssql` + `tedious` | TCP 直连 |
| **Oracle** | `oracledb`（官方驱动） | TCP 直连（Thin 模式） |
---
## 🚀 快速开始
### 前置要求
- **Node.js** ≥ 22.5（`node:sqlite` 内置模块要求；独立运行 MCP Server 时）
- **VS Code** ≥ 1.101（内置 Node ≥ 22.5，含 `node:sqlite`）
- **npm** ≥ 9.x
### 方式一：从 VSIX 安装（推荐）
从 [Releases](https://github.com/bigedev/bige-sql/releases) 下载 `.vsix` 文件，然后在 VS Code 中：
```
扩展 → 右上角 `...` → Install from VSIX...
```
### 方式二：从源码构建
```bash
git clone https://github.com/bigedev/bige-sql.git
cd bige-sql
npm install
npm run compile
```
然后在 VS Code 中按 `F5` 启动调试窗口，或自行打包安装。
### 打包为 VSIX
项目内置了打包脚本，方便发布或分发：
```bash
# 完整打包（先编译，再打包）
npm run package
# 如果已编译，跳过编译步骤
npm run package:no-compile
```
执行后会在项目根目录生成 `bige-sql-<version>.vsix` 文件，可直接用于安装或分发。
> **💡 提示**: VSIX 已通过 `.vscodeignore` 自动排除源代码、测试文件、文档等无用文件，减小体积。
### 配置数据库连接
编辑项目根目录的 `connections.json` 添加您的数据库连接：
```json
{
"connections": {
"my-mysql": {
"type": "mysql",
"host": "192.168.1.100",
"port": 3306,
"user": "root",
"password": "your_password",
"database": "mydb"
},
"my-postgres": {
"type": "postgresql",
"host": "127.0.0.1",
"port": 5432,
"user": "postgres",
"password": "",
"database": "mydb"
},
"my-sqlite": {
"type": "sqlite",
"path": "/data/mydb.db"
},
"my-dameng": {
"type": "dameng",
"host": "192.168.1.23",
"port": 5236,
"user": "SYSDBA",
"password": "SYSDBA"
},
"my-sqlserver": {
"type": "sqlserver",
"host": "192.168.1.50",
"port": 1433,
"user": "sa",
"password": "your_password",
"database": "mydb"
},
"my-oracle": {
"type": "oracle",
"host": "192.168.1.60",
"port": 1521,
"user": "system",
"password": "your_password",
"database": "ORCLCDB"
}
}
}
```
> **⚠️ 注意**: `connections.json` 已加入 `.gitignore`，避免误提交凭据到 Git。
>
> 也可在 VS Code 设置中配置 `bigeSql.connectionsFilePath` 指定自定义路径（支持绝对路径）。
> **💡 参考**: 查看 `connections.example.json` 获取更多配置项示例。
---
## 🎯 使用方式一：VS Code 插件（图形界面）
### 安装插件
在 VS Code 中按 `F5` 启动调试，或从 `.vsix` 安装。
### 使用界面
1. **侧边栏** — 点击活动栏的 🗄️ **BigeSQL** 图标
2. **添加连接** — 点击侧边栏顶部的 **+** 按钮，填写表单
3. **浏览表** — 展开连接节点，查看表和列结构
4. **执行查询** — 右键连接或表，选择 **打开 SQL 查询编辑器**
5. **MCP Server** — 点击底部状态栏 **BigeSQL MCP** 启动，运行中可点击停止
6. **快捷键** — 在 SQL 编辑器中按 `Cmd+Enter` / `Ctrl+Enter` 执行
### 命令列表
| 命令 | 说明 |
| ------------------------------ | ------------------- | --- | ------------------------------ | ------------------------- |
| `BigeSQL: 添加数据库连接` | 打开添加连接表单 |
| `BigeSQL: 打开 SQL 查询编辑器` | 打开 SQL 编辑器 |
| `BigeSQL: 刷新连接列表` | 从文件重新加载连接 |
| `BigeSQL: 测试连接` | 测试连接是否正常 |
| `BigeSQL: 编辑连接` | 修改连接配置 |
| `BigeSQL: 删除连接` | 删除数据库连接 |
| `BigeSQL: Start MCP Server` | 启动 MCP 服务 |
| `BigeSQL: Stop MCP Server` | 停止 MCP 服务 | | `BigeSQL: 复制 MCP 服务器地址` | 复制 MCP 服务地址到剪贴板 |
| `BigeSQL: 配置 MCP 服务器端口` | 设置 MCP 服务端口号 |
---
## 🤖 使用方式二：MCP Server（AI 助手）
让 AI 助手（GitHub Copilot、Claude 等）通过 MCP 协议直接访问您的数据库。
### 方式 A：VS Code 扩展管理（推荐）
安装扩展后，通过以下任一方式启动：
- **状态栏** — 点击底部 **BigeSQL MCP** 图标
- **命令面板** — 执行 `BigeSQL: Start MCP Server`
启动后自动运行 HTTP 模式，状态栏显示 **BigeSQL MCP • 运行中**，点击可停止。
> **💡 更新扩展后看不到新工具？**
> MCP 客户端（Copilot、Cursor 等）在会话建立时拉取并**缓存**工具列表（`tools/list`），
> 只有运行时响应走实时通道。所以更新扩展后仍可能看到旧的工具列表（新工具报 not found、描述未变）。
> 请在 MCP 面板重启该 server，或执行 `Developer: Reload Window` 重载窗口。
### 方式 B：配置 VS Code MCP（stdio）
在项目 `.vscode/mcp.json` 中添加：
```json
{
"servers": {
"bige-sql": {
"type": "command",
"command": "node",
"args": ["/path/to/bige-sql/out/src/server.js"],
"description": "BigeSQL 多数据库 MCP Server"
}
}
}
```
重启 VS Code 后，Copilot 即可自动识别并使用数据库工具。
### 方式 C：独立 HTTP 服务
```bash
# stdio + HTTP 双模式（默认端口 5237）
node out/src/server.js --http
# 仅 HTTP 模式
node out/src/server.js --http-only
# 自定义端口
node out/src/server.js --http --port 8080
```
HTTP 端点：`http://127.0.0.1:5237/mcp`
支持标准 MCP Streamable HTTP 传输，可与任意兼容的 MCP 客户端（其他 IDE、自定义 Agent 等）配合使用。
### MCP 工具列表
| 工具 | 参数 | 说明 |
| -------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
| `list-tools` | — | 按场景分组列出全部工具 + "该用哪个"指引 |
| `list-connections` | — | 列出所有已配置的连接 |
| `test-connection` | `connection` (可选) | 测试数据库连接 |
| `list-databases` | `connection` (可选) | 列出所有数据库（MySQL/PG/SQL Server） |
| `list-schemas` | `connection` (可选) | 列出 schema（PG）/ 数据库列表（MySQL）/ 用户（达梦） |
| `list-tables` | `connection` (可选), `database` (可选), `schema` (可选) | 列出所有表和视图 |
| `list-views` | `connection` (可选) | 列出视图及其定义 |
| `describe-table` | `connection` (可选), `tableName` (必填), `database` (可选), `schema` (可选) | 查看表字段结构 |
| `get-table-info` | `connection` (可选), `tableName` (必填) | 表详细信息（行数、大小、引擎） |
| `get-schema` | `connection` (可选), `tableName` (必填) | 获取表 DDL/建表语句 |
| `search-tables` | `connection` (可选), `keyword` (必填) | 按名称模糊搜索表 |
| `list-indexes` | `connection` (可选), `tableName` (必填) | 列出表索引 |
| `get-primary-keys` | `connection` (可选), `tableName` (必填), `database` (可选), `schema` (可选) | 获取主键信息 |
| `get-foreign-keys` | `connection` (可选), `tableName` (必填), `database` (可选), `schema` (可选) | 获取外键关系 |
| `get-triggers` | `connection` (可选), `tableName` (必填), `database` (可选), `schema` (可选) | 获取指定表的所有触发器信息 |
| `list-procedures` | `connection` (可选), `database` (可选), `schema` (可选) | 列出存储过程和函数 |
| `get-procedure` | `connection` (可选), `name` (必填) | 获取存储过程/函数源码 |
| `get-procedure-parameters` | `connection` (可选), `name` (必填), `database` (可选), `schema` (可选) | 获取存储过程/函数的参数列表 |
| `query` | `connection`, `sql` (必填), `database`, `schema`, `maxRows` | 执行单条 SELECT 查询（最多 maxRows 行，默认 1000） |
| `execute` | `connection`, `sql` (必填), `database`, `schema` | 执行单条 INSERT/UPDATE/DELETE |
| `execute-batch` | `connection`, `sql` (必填), `useTransaction`/`stopOnError`/`maxRows`, `database`, `schema` | 【多语句脚本】批量执行多条不同 SQL，事务保护 |
| `execute-script` | 同 `execute-batch` | 别名，语义更明确（script = 多条 SQL） |
| `execute-many` | `connection`, `sql`, `params` (必填), `useTransaction`/`batchSize`, `database`, `schema` | 【多参数批量】同一 SQL + `?` 占位符 + 多组参数 |
| `execute-params` | 同 `execute-many` | 别名，语义更明确（params = 多组参数） |
| `explain-query` | `connection`, `sql` (必填), `database`, `schema` | 获取执行计划 |
> 所有工具的 `connection` 参数默认使用第一个配置的连接。
> `database` 和 `schema` 参数可用于跨数据库/跨 schema 查询，不传则使用连接默认值。
>
> 支持 `database` / `schema` 的工具：`query`、`execute`、`execute-batch`、`execute-many`、`explain-query`、`list-tables`、`list-views`、`describe-table`、`get-primary-keys`、`get-foreign-keys`、`list-procedures`、`get-procedure-parameters`、`get-triggers` 等。
> 对于连接配置未指定默认库的连接（如 `mini-site` 的 `database` 为空），必须显式传 `database`，否则会报 "No database selected"。
### 标识符引用规则（重要）
不同数据库引用**标识符**（库名 / 表名 / 列名）的符号不同，生成 SQL 时必须按目标数据库选择：
| 数据库 | 引用符 | 示例 |
| ---------------------------------- | ------------------ | ----------- |
| MySQL / MariaDB | 反引号 `` ` `` | `` `order` `` |
| PostgreSQL / SQLite / 达梦 DM8 / Oracle | 双引号 `"` | `"order"` |
| SQL Server | 方括号 `[]`（双引号亦可） | `[order]` |
> ⚠️ **单引号 `'name'` 是字符串字面量，不能用于标识符** —— `SELECT * FROM 'users'` 在 PostgreSQL 是语法错误。
>
> 名称属于保留字（`order`、`user`、`key`、`index`、`desc`、`select`、`in`、`and` 等）、含空格或中文、或大小写敏感时，必须加引用符，否则 SQL 报错或查错对象。
调用方可通过两种方式获取正确引用符：
1. **工具描述**：`query`、`execute`、`execute-batch`、`execute-many`、`explain-query` 的 description 已内置完整规则；返回表名/列名的元数据工具（`list-tables`、`describe-table`、`get-schema` 等）带有引用提示
2. **程序化获取**：`list-connections` 为每条连接返回 `quote`（如 `` `name` `` / `"name"` / `[name]`）、`quoteStyle`（`backtick` / `double-quote` / `bracket`）与 `quoteNote`
```json
[
{
"name": "mini-site",
"type": "mysql",
"database": "all-in-one",
"quote": "`name`",
"quoteStyle": "backtick",
"quoteNote": "MySQL/MariaDB 使用反引号；开启 ANSI_QUOTES 时才可用双引号"
}
]
```
### 批量操作
#### 0. 该用哪个工具？
| 场景 | 工具 |
| --- | --- |
| 单条 SELECT | `query` |
| 单条 INSERT/UPDATE/DELETE/DDL | `execute` |
| **多条不同的 SQL**（含分号 / `DELIMITER` / `GO` / PL/SQL 块） | `execute-batch`（别名 `execute-script`） |
| **同一条 SQL 配多组参数**（批量插入/更新大量行） | `execute-many`（别名 `execute-params`） |
| 不确定用哪个 | `list-tools`（返回按场景分组的清单 + 选择指引） |
> **命名消歧**：`batch` / `script` = 多条**不同** SQL；`many` / `params` = **一条** SQL 配多组参数。
> 两者极易对调理解，故额外提供 `execute-script`、`execute-params` 两个语义别名（与主名完全等价）。
> `query` / `execute` **只支持单条语句**，传入多语句会报语法错误并在错误后追加提示"检测到 N 条语句，请改用 execute-batch"。
> 反向亦然：`execute-batch` 用于多条不同 SQL，`execute-many` 用于同一 SQL 多组参数，两者描述中已互相指引。
#### 1. 多语句批量执行（SQL 编辑器 / `execute-batch`）
SQL 编辑器中可直接粘贴多条语句一次运行，工具栏提供 **Transaction**（事务）与 **Stop on error**（遇错停止）开关，结果区按语句分页签展示，状态栏显示 `已执行条数/总条数 · 影响行数 · 耗时`。
MCP 侧对应 `execute-batch`：
```json
{
"connection": "mini-site",
"sql": "UPDATE t SET a = 1 WHERE id = 1; UPDATE t SET a = 2 WHERE id = 2;",
"useTransaction": true,
"stopOnError": true
}
```
语句拆分由词法扫描器完成（`src/sqlSplitter.ts`），支持：
| 数据库 | 支持的写法 |
| --------------------- | -------------------------------------------------------------- |
| 通用 | 分号分隔；跳过字符串字面量、`'...'`/`"..."`/`` `...` ``/`[...]`、行注释与块注释 |
| MySQL / MariaDB | `DELIMITER $$ ... $$`（存储过程体） |
| SQL Server | `GO` 批处理分隔符 |
| Oracle / 达梦 DM8 | `BEGIN ... END;` PL/SQL 块、`CREATE [OR REPLACE] PROCEDURE`、独立 `/` 行 |
| PostgreSQL | dollar-quoted 字符串 `$$ ... $$` / `$tag$ ... $tag$` |
事务语义：语句数 > 1 且包含写操作时默认开启事务，任一条失败即整体回滚；关闭事务则逐条提交，`stopOnError: false` 时遇错继续。
#### 2. 参数化批量执行（`execute-many`）
同一条 SQL 配多组参数，SQL 中统一使用 `?` 占位符，内部自动转换为目标数据库风格（PostgreSQL `$1`、Oracle `:1`、SQL Server `@p1`）：
```json
{
"connection": "mini-site",
"sql": "INSERT INTO users (name, age) VALUES (?, ?)",
"params": [["张三", 20], ["李四", 25], ["王五", 30]],
"useTransaction": true,
"batchSize": 500
}
```
- Oracle / 达梦：走驱动原生 `executeMany`，一次网络往返执行整批
- 其他数据库：分批循环执行（同一事务内具备原子性）
- PostgreSQL 会自动按 65535 个绑定参数上限下调 `batchSize`
---
## 🏗️ 项目架构
```text
bige-sql/
├── package.json # 依赖 & VS Code 扩展清单
├── package.nls.json # 扩展清单本地化（命令名、视图名等）
├── package.nls.zh-cn.json # 中文简体本地化
├── package.nls.zh-tw.json # 中文繁体本地化
├── tsconfig.json # TypeScript 编译配置（strict 模式）
├── .vscodeignore # VSIX 打包排除规则
├── .gitignore # Git 忽略规则
├── connections.example.json # 连接配置示例
├── test-mcp-http.mjs # HTTP MCP 测试脚本
├── LICENSE # MIT 许可证
├── src/
│ ├── extension.ts # VS Code 插件入口（注册命令、视图、Webview）
│ ├── server.ts # MCP Server（stdio + HTTP 双模式入口）
│ ├── mcpServerProvider.ts # MCP 服务提供者（状态栏管理、生命周期）
│ ├── dbTypes.ts # 数据库类型常量与工具函数
│ ├── sqlSplitter.ts # SQL 脚本拆分器（多语句/方言分隔符）
│ ├── batchTypes.ts # 批量执行公共类型（扩展端与 MCP 共用）
│ ├── connectionManager.ts # 连接配置读写管理
│ ├── databaseService.ts # 数据库查询引擎（MySQL/PG/SQLite/达梦/SQL Server/Oracle）
│ ├── connectionTreeProvider.ts # 侧边栏连接树视图
│ └── queryEditorProvider.ts # SQL 编辑器 Webview 提供者
├── l10n/
│ ├── bundle.l10n.json # 运行时本地化（默认英文）
│ ├── bundle.l10n.zh-cn.json # 中文简体
│ └── bundle.l10n.zh-tw.json # 中文繁体
├── media/
│ ├── database.svg # 活动栏图标
│ ├── addConnection.js # 添加/编辑连接 Webview 前端
│ ├── icon.png # 扩展市场图标（PNG）
│ └── icon.svg # 扩展市场图标（SVG）
├── .vscode/
│ ├── launch.json # VS Code 调试配置（Run Extension / Attach）
│ └── settings.json # 工作区设置
└── out/ # 编译输出（自动生成，已 gitignore）
```
---
## 🛠️ 开发
```bash
# 安装依赖
npm install
# 编译 TypeScript
npm run compile
# 监听模式（开发时使用）
npm run watch
# 打包 VSIX
npm run package
# 在 VS Code 中按 F5 启动调试
```
### 调试插件
1. 在 VS Code 中打开本项目
2. 按 `F5` 或运行 **Run Extension** 调试配置
3. 新窗口会加载扩展
4. 点击活动栏的 BigeSQL 图标开始使用
### 调试 MCP Server
```bash
# 单独运行 MCP Server（stdio）
node out/src/server.js
# HTTP 模式
node out/src/server.js --http
```
VS Code 提供了 **Run MCP Server** 调试配置，可直接附加调试器。
---
## 📄 License
MIT
## 示例
在 VS Code Copilot Chat 中直接提问：
```text
@bige-sql 查询 idcloud-mysql 中的 ac_user 表前10条记录
@bige-sql 列出 my-postgres 中所有表
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues