内容
# hepta_dbcli
适用于 MySQL/PolarDB-X/Oracle/GaussDB 数据库的 CLI 和 MCP 服务器。
## 功能特点
- **MCP 服务器** — 作为模型上下文协议服务器，供 AI 工具（如 Claude、Cursor 等）查询数据库，并强制执行只读安全。
- **多数据库支持** — 支持 MySQL、PolarDB-X、Oracle 和 GaussDB（功能特性：`oracle`、`gaussdb`）。
- **单次 CLI 命令** — 从命令行、文件或标准输入执行 SQL，并支持多种输出格式。
- **交互式 REPL** — 数据库感知的 SQL 提示，支持多行编辑、历史记录和点命令。
- **多连接管理** — 管理多个数据库连接，并为每个连接配置超时时间。
- **操作系统密钥链** — 在 macOS 密钥链或 Linux 秘密服务中存储密码，并自动从纯文本配置文件迁移。
## 安装
### 下载二进制文件
从 [GitHub Releases](https://github.com/YOUR_ORG/dbcli/releases) 下载适用于 Linux（x86_64、arm64）和 Windows（x86_64）的预编译二进制文件。
### 从源代码构建
```bash
git clone https://github.com/YOUR_ORG/dbcli.git
cd dbcli
cargo build --release -p polar-mysql
# 二进制文件位于：target/release/hepta_dbcli
```
## 配置
### 配置文件
创建 `~/.hepta-dbcli.toml`（同时读取旧的 `~/.polardb-mysql.toml`）：
```toml
# 单个连接（以下部分为默认值）
host = "127.0.0.1"
port = 3306
user = "root"
password = "your-password"
database = "mysql"
```
首次成功连接后，密码会自动迁移到操作系统密钥链，并重写配置文件为 `password = "keyring"`。
### 多连接配置
```toml
default_connection = "dev"
[connections.prod]
host = "prod-db.example.com"
user = "readonly"
password = "keyring"
[connections.dev]
host = "127.0.0.1"
user = "root"
password = "keyring"
# Oracle 连接
[connections.ora]
driver = "oracle"
host = "oracle.internal"
port = 1521
user = "scott"
password = "keyring"
database = "FREEPDB1"
```
### 环境变量
```bash
export HEPTA_DBCLI_URL="mysql://user:password@host:port/database"
# Oracle 通过 URL
export HEPTA_DBCLI_URL="oracle://scott:tiger@host:1521/FREEPDB1"
```
### 超时设置
```toml
# 全局默认值（每个连接的重写在 [connections.NAME] 中）
statement_timeout = "30s" # 查询最大执行时间
connection_max_lifetime = "1h" # 连接在此持续时间后回收
```
支持的单位：`ms`、`s`、`min`、`h` 或纯秒数。
## 使用
### MCP 服务器（默认）
```bash
hepta_dbcli
hepta_dbcli --config /path/to/config.toml
```
在标准输入/输出上运行。旨在由 MCP 客户端启动。所有查询均为只读（仅限 SELECT、EXPLAIN、SHOW、DESCRIBE/DESC）。
### 单次 SQL 命令
```bash
# 命令行
hepta_dbcli cli --sql "SELECT version()"
# 文件
hepta_dbcli cli --file query.sql
# 标准输入
echo "SHOW TABLES" | hepta_dbcli cli
# 自定义输出格式
hepta_dbcli cli --sql "SELECT * FROM users" --format json
hepta_dbcli cli --sql "SELECT * FROM users" --format csv
hepta_dbcli cli --sql "SELECT * FROM users" --format vertical
# 指定连接
hepta_dbcli cli --name prod --sql "SELECT count(*) FROM orders"
```
### 交互式 REPL
```bash
hepta_dbcli cli --interactive
hepta_dbcli cli -i --name dev
```
REPL 命令：
- `.help` / `?` — 显示帮助
- `.connect [name]` — 切换连接
- `.history` — 显示 SQL 执行历史
- `.output [file]` — 将 SQL 输出重定向到文件
- `.save <file> [format]` — 保存最后的结果
- `.clear` / `.cls` — 清空屏幕
- `.exit` / `.quit` — 退出
输出格式：`table`（默认）、`json`、`vertical`、`csv`。
以 `;` + 回车结束 SQL 语句以执行。多行不完整的语句支持。
### 测试连接
```bash
# 基本连接检查
hepta_dbcli check
# 詳細信息：显示服务器版本、用户、字符集、TLS 模式
hepta_dbcli check --verbose
# 检查特定连接
hepta_dbcli check --name prod
```
### 存储密码
```bash
hepta_dbcli store-password
hepta_dbcli store-password --name prod
```
提示输入密码并将其存储在操作系统密钥链中。
## MCP 工具
作为 MCP 服务器运行时，可用以下工具：
| 工具 | 描述 |
|------|-------------|
| `get_database_info` | 服务器版本、当前用户、字符集、操作系统 |
| `list_tables` | 所有用户表/视图，包含引擎、行数、大小 |
| `get_table_metadata` | 列类型、是否可为空、默认值、索引 |
| `execute_query` | 只读 SELECT/EXPLAIN/SHOW/DESCRIBE（追加 `LIMIT N` 或 `FETCH FIRST N ROWS ONLY`；Oracle 支持 SELECT/EXPLAIN/WITH） |
| `get_execution_plan` | EXPLAIN 或 EXPLAIN ANALYZE，支持 TEXT/JSON 格式（Oracle：EXPLAIN PLAN + DBMS_XPLAN） |
| `list_connections` | 列出所有已配置的连接及其状态 |
## 开发
```bash
# 构建（仅限 MySQL）
cargo build
# 构建并启用 Oracle 支持
cargo build --features oracle
# 发布版本（包含 Oracle）
cargo build --release -p polar-mysql --features "oracle,gaussdb"
# 格式检查
cargo fmt --all -- --check
# lint（Ubuntu：apt-get install libdbus-1-dev pkg-config）
cargo clippy --all --all-targets
# 单元测试
cargo test --all
# 集成测试（需要运行的 MySQL 实例）
HEPTA_DBCLI_TEST_URL=mysql://mcp:testpass@127.0.0.1:3306/testdb cargo test --all --features integration
# Oracle 单元测试
cargo test --features oracle
# Oracle 集成测试（需要运行的 Oracle）
POLARDB_ORACLE_TEST_URL=oracle://system:testpass@127.0.0.1:1521/FREEPDB1 cargo test --features "oracle,integration" -- oracle
```
CI 强制执行：`cargo fmt --check` → `cargo clippy` → `cargo test`（按此顺序）。
### 运行集成测试的 MySQL
```bash
docker run -d --name mysql-test \
-e MYSQL_ROOT_PASSWORD=testpass \
-e MYSQL_DATABASE=testdb \
-p 3306:3306 \
mysql:8
# 创建测试用户
docker exec mysql-test mysql -u root -ptestpass -e "
CREATE USER 'mcp'@'%' IDENTIFIED WITH caching_sha2_password BY 'testpass';
GRANT ALL PRIVILEGES ON *.* TO 'mcp'@'%';
FLUSH PRIVILEGES;
"
# 运行测试
HEPTA_DBCLI_TEST_URL=mysql://mcp:testpass@127.0.0.1:3306/testdb cargo test --all --features integration
```
### 运行集成测试的 Oracle
```bash
docker run -d --name oracle-test -p 1521:1521 \
-e ORACLE_PASSWORD=testpass \
gvenzl/oracle-free:23-slim
# 等待 Oracle 准备就绪（可能需要 ~30s）
docker logs -f oracle-test
# 运行测试
POLARDB_ORACLE_TEST_URL=oracle://system:testpass@127.0.0.1:1521/FREEPDB1 \
cargo test --features "oracle,integration" -- oracle
```
## 许可证
MIT OR Apache-2.0
