dbskill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# DBSkill

[中文](#中文) | [English](#english)

---

<a name="中文"></a>

## 中文

为 AI Agent 提供数据库访问能力的 Skill 工具包。Agent 可通过它查询表结构、执行只读 SQL、执行写操作（需相应权限），支持 **Direct**（直连数据库）与 **API**（通过 HTTP API 调用数据库）两种使用方式。

### Direct 模式 vs API 模式

| 项目 | Direct 模式 | API 模式 |
|------|-------------|----------|
| 含义 | Skill 脚本直接连数据库 | Skill 通过 API中转 连接数据库 |
| 适用场景 | Agent 与数据库在同一环境、可直连 | 数据库在远端，或需集中鉴权、审计 |
| 是否需要启动 Web 服务 | **否** | **是**（需先部署并运行 DBSkill API 服务） |
| 权限与审计 | 本地 `config.yaml` 中按库配置 `permission`；本地文件记录审计日志 | 服务端按 API Key 关联账号权限；服务端记录审计日志；支持多用户 |

- **能用 Direct 就用 Direct**：配置简单，无需额外服务。
- **用 API 时**：数据库在远程、多端共用同一套库，或需要统一管理账号/API Key 与审计时。

### 安装

1. 复制本项目下的 **dbskill** 目录到应用的 skills 目录。
2. 安装 Python 依赖：进入复制后的 **dbskill** 目录，执行：
   ```bash
   pip install -r requirements.txt
   ```
3. 在 dbskill 目录内，将 config.example.yaml 重命名为 config.yaml，并修改其中配置信息：
   - **permission**：`readonly` 仅查；`write` 可 INSERT/UPDATE；`full` 还可 DELETE。
   - **default_db**（可选）：调用时不指定使用哪个库时，默认使用的库（填 `databases` 里某个名称）。若 **只有一个库** 且未配置 `default_db`，会自动使用该库；多库时建议配置，否则调用时需显式传库名。
4. 在 AI 应用中测试使用。

### API 安装

如果上一步 config.yaml 中全部使用直连数据库，则无需部署 API；若有数据库无法直连或希望集中管控，则需要部署 API，Skill 通过 API 中转访问数据库。

1. 将本项目代码复制到服务器中，并安装依赖
```bash
pip install -e .
# 或
uv sync
```
2. 复制 server.example.yaml 为 server.yaml 并修改其配置
- **admin_db.path**：管理后台与 API 元数据存储（SQLite），默认 `./admin.db`。
- **logging**：应用日志文件路径与切分。`file` 为路径（不写则仅控制台）；`rotation.type` 为 `size`（按大小，需 `max_bytes`、`backup_count`）或 `time`（按天，需 `when`、`interval`、`backup_count`）。
- **api_audit**：API 请求审计（存 admin.db）的开关与 `retention_days`。

**3. 启动 Web 服务**

```bash
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

生产环境建议在 `server.yaml` 中设置 `session_secret`（用于管理后台会话）。

**4. 使用 Docker 部署（可选）**

构建镜像后，可用脚本一键启动（默认挂载当前目录 `data/` 持久化 admin.db，若存在则挂载 `config.yaml`，端口 8000；可通过环境变量 `PORT`、`SESSION_SECRET`、`CONFIG_PATH`、`DATA_PATH` 覆盖）：

```bash
docker build -t dbskill .
chmod +x scripts/docker-run.sh
./scripts/docker-run.sh
```

需自定义时可通过环境变量覆盖再执行脚本，例如：

```bash
PORT=9000 ./scripts/docker-run.sh
```

或直接运行容器（挂载的 `server.yaml` 中可设置 `session_secret`；未设置时使用默认值，生产环境勿用默认值）：

```bash
docker run -d -p 8000:8000 -v $(pwd)/server.yaml:/app/server.yaml -v $(pwd)/data:/app/data dbskill
```

需保证容器内能访问数据库；`data/` 用于持久化 admin.db；`server.yaml` 中可设置 `admin_db.path: /app/data/admin.db` 使数据落盘到挂载卷。

**5. 登录后台配置**

登录后台，默认账号：admin admin123。在后台，可配置数据库连接、api key、查看审计日志。

## 支持数据库列表

| 类型（config 中 type） | 默认端口 | 说明 |
|------------------------|----------|------|
| sqlite | — | 文件库，`database` 填文件路径；无需额外驱动 |
| postgres | 5432 | 需安装 `psycopg2-binary`（已含于 dbskill/requirements.txt） |
| mysql | 3306 | 需安装 `pymysql`（已含于 dbskill/requirements.txt） |
| mariadb | 3306 | 同 mysql，使用 pymysql |
| oracle | 1521 | 需自行安装驱动，如 `oracledb` 或 `cx_Oracle` |
| mssql | 1433 | 需自行安装驱动，如 `pyodbc` 或 `pymssql` |
| db2 | 50000 | 需自行安装 IBM DB2 驱动 |
| dm | 5236 | 达梦，需自行安装达梦驱动 |
| kingbase | 54321 | 人大金仓，需自行安装金仓驱动 |

SQLite、PostgreSQL、MySQL/MariaDB 的依赖已包含在 `dbskill/requirements.txt` 中，执行 `pip install -r requirements.txt` 即可。使用上表其他数据库时，需在 **dbskill 目录下** 按需安装对应驱动：

| 数据库 | 安装命令 |
|--------|----------|
| Oracle | `pip install oracledb` |
| SQL Server (MSSQL) | `pip install pyodbc` 或 `pip install pymssql`（pyodbc 需系统已安装 ODBC 驱动） |
| IBM DB2 | `pip install ibm-db`（SQLAlchemy 需另装 `ibm_db_sa`） |
| 达梦 (DM) | `pip install dmPython`（部分环境需配置 `DM_HOME`、`LD_LIBRARY_PATH` 等） |
| 人大金仓 (Kingbase) | `pip install ksycopg2` |

---

<a name="english"></a>

## English

DBSkill is a Skill toolkit that gives AI Agents database access. Agents can query table schemas, run read-only SQL, and run write operations (with appropriate permissions). It supports **Direct** (connect to the database directly) and **API** (call the database via HTTP API) modes.

### Direct vs API mode

| Item | Direct mode | API mode |
|------|-------------|----------|
| Meaning | Skill scripts connect to the DB directly | Skill connects via API proxy |
| Use case | Agent and DB in same environment, direct access | DB remote, or need central auth/audit |
| Web server required | **No** | **Yes** (deploy and run DBSkill API service first) |
| Permissions & audit | Configure `permission` per DB in local `config.yaml`; audit logs to local files | Server maps API Key to account permissions; server-side audit logs; multi-user |

- **Prefer Direct** when possible: simple config, no extra service.
- **Use API** when the DB is remote, multiple clients share the same DB set, or you need centralized API Key and audit management.

### Installation

1. Copy the **dbskill** directory from this project into your application’s skills directory.
2. Install Python dependencies: enter the copied **dbskill** directory and run:
   ```bash
   pip install -r requirements.txt
   ```
3. Inside the dbskill directory, rename `config.example.yaml` to `config.yaml` and edit:
   - **permission**: `readonly` (query only); `write` (INSERT/UPDATE); `full` (also DELETE).
   - **default_db** (optional): default database when none is specified (must be one of the names under `databases`). If there is **only one** database and `default_db` is not set, that database is used automatically; with multiple databases, set `default_db` or pass the database name explicitly when calling.
4. Test from your AI application.

### API installation

If all databases in `config.yaml` use direct connection, you do not need to deploy the API. Deploy the API when some databases cannot be reached directly or you want central control; the Skill will access the database through the API.

1. Copy this project to the server and install dependencies:
```bash
pip install -e .
# or
uv sync
```
2. Copy `server.example.yaml` to `server.yaml` and adjust:
- **admin_db.path**: Path for admin UI and API metadata (SQLite), default `./admin.db`.
- **logging**: App log file path and rotation. `file` is the path (omit for console only); `rotation.type` is `size` (by size, needs `max_bytes`, `backup_count`) or `time` (by day, needs `when`, `interval`, `backup_count`).
- **api_audit**: Toggle and `retention_days` for API request audit (stored in admin.db).

**3. Start the web service**

```bash
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

For production, set `session_secret` in `server.yaml` (used for admin session).

**4. Docker deployment (optional)**

After building the image, you can start with the script (default: mount current `data/` for admin.db persistence; mount `config.yaml` if present; port 8000; override with env vars `PORT`, `SESSION_SECRET`, `CONFIG_PATH`, `DATA_PATH`):

```bash
docker build -t dbskill .
chmod +x scripts/docker-run.sh
./scripts/docker-run.sh
```

Override with environment variables as needed, e.g.:

```bash
PORT=9000 ./scripts/docker-run.sh
```

Or run the container directly (you can set `session_secret` in the mounted `server.yaml`; if unset, a default is used—do not use the default in production):

```bash
docker run -d -p 8000:8000 -v $(pwd)/server.yaml:/app/server.yaml -v $(pwd)/data:/app/data dbskill
```

Ensure the container can reach the database; use `data/` for admin.db persistence; in `server.yaml` you can set `admin_db.path: /app/data/admin.db` so data is stored on the mounted volume.

**5. Admin UI**

Log in to the admin UI; default credentials: admin / admin123. There you can configure database connections, API keys, and view audit logs.

### Supported databases

| type (in config) | Default port | Notes |
|------------------|--------------|-------|
| sqlite | — | File-based; `database` is file path; no extra driver |
| postgres | 5432 | Use `psycopg2-binary` (in dbskill/requirements.txt) |
| mysql | 3306 | Use `pymysql` (in dbskill/requirements.txt) |
| mariadb | 3306 | Same as mysql, use pymysql |
| oracle | 1521 | Install driver separately (see below) |
| mssql | 1433 | Install driver separately (see below) |
| db2 | 50000 | Install IBM DB2 driver separately |
| dm | 5236 | DM (DaMeng); install driver separately |
| kingbase | 54321 | Kingbase; install driver separately |

SQLite, PostgreSQL, and MySQL/MariaDB are covered by `dbskill/requirements.txt`. For other databases, install the driver **inside the dbskill directory** as needed:

| Database | Install command |
|----------|-----------------|
| Oracle | `pip install oracledb` |
| SQL Server (MSSQL) | `pip install pyodbc` or `pip install pymssql` (pyodbc may require system ODBC driver) |
| IBM DB2 | `pip install ibm-db` (for SQLAlchemy also install `ibm_db_sa`) |
| DM (DaMeng) | `pip install dmPython` (some environments need `DM_HOME`, `LD_LIBRARY_PATH`, etc.) |
| Kingbase | `pip install ksycopg2` |

DBSkill

中文 | English

中文

为 AI Agent 提供数据库访问能力的 Skill 工具包。Agent 可通过它查询表结构、执行只读 SQL、执行写操作（需相应权限），支持 Direct（直连数据库）与 API（通过 HTTP API 调用数据库）两种使用方式。

Direct 模式 vs API 模式

项目	Direct 模式	API 模式
含义	Skill 脚本直接连数据库	Skill 通过 API中转连接数据库
适用场景	Agent 与数据库在同一环境、可直连	数据库在远端，或需集中鉴权、审计
是否需要启动 Web 服务	否	是（需先部署并运行 DBSkill API 服务）
权限与审计	本地 `config.yaml` 中按库配置 `permission`；本地文件记录审计日志	服务端按 API Key 关联账号权限；服务端记录审计日志；支持多用户

能用 Direct 就用 Direct：配置简单，无需额外服务。
用 API 时：数据库在远程、多端共用同一套库，或需要统一管理账号/API Key 与审计时。

安装

复制本项目下的 dbskill 目录到应用的 skills 目录。
安装 Python 依赖：进入复制后的 dbskill 目录，执行：
```
pip install -r requirements.txt
```
在 dbskill 目录内，将 config.example.yaml 重命名为 config.yaml，并修改其中配置信息：
- permission：readonly 仅查；write 可 INSERT/UPDATE；full 还可 DELETE。
- default_db（可选）：调用时不指定使用哪个库时，默认使用的库（填 databases 里某个名称）。若 只有一个库 且未配置 default_db，会自动使用该库；多库时建议配置，否则调用时需显式传库名。
在 AI 应用中测试使用。

API 安装

如果上一步 config.yaml 中全部使用直连数据库，则无需部署 API；若有数据库无法直连或希望集中管控，则需要部署 API，Skill 通过 API 中转访问数据库。

将本项目代码复制到服务器中，并安装依赖

pip install -e .
# 或
uv sync

复制 server.example.yaml 为 server.yaml 并修改其配置

admin_db.path：管理后台与 API 元数据存储（SQLite），默认 ./admin.db。
logging：应用日志文件路径与切分。file 为路径（不写则仅控制台）；rotation.type 为 size（按大小，需 max_bytes、backup_count）或 time（按天，需 when、interval、backup_count）。
api_audit：API 请求审计（存 admin.db）的开关与 retention_days。

3. 启动 Web 服务

uvicorn api.main:app --host 0.0.0.0 --port 8000

生产环境建议在 server.yaml 中设置 session_secret（用于管理后台会话）。

4. 使用 Docker 部署（可选）

构建镜像后，可用脚本一键启动（默认挂载当前目录 data/ 持久化 admin.db，若存在则挂载 config.yaml，端口 8000；可通过环境变量 PORT、SESSION_SECRET、CONFIG_PATH、DATA_PATH 覆盖）：

docker build -t dbskill .
chmod +x scripts/docker-run.sh
./scripts/docker-run.sh

需自定义时可通过环境变量覆盖再执行脚本，例如：

PORT=9000 ./scripts/docker-run.sh

或直接运行容器（挂载的 server.yaml 中可设置 session_secret；未设置时使用默认值，生产环境勿用默认值）：

docker run -d -p 8000:8000 -v $(pwd)/server.yaml:/app/server.yaml -v $(pwd)/data:/app/data dbskill

需保证容器内能访问数据库；data/ 用于持久化 admin.db；server.yaml 中可设置 admin_db.path: /app/data/admin.db 使数据落盘到挂载卷。

5. 登录后台配置

登录后台，默认账号：admin admin123。在后台，可配置数据库连接、api key、查看审计日志。

支持数据库列表

类型（config 中 type）	默认端口	说明
sqlite	—	文件库，`database` 填文件路径；无需额外驱动
postgres	5432	需安装 `psycopg2-binary`（已含于 dbskill/requirements.txt）
mysql	3306	需安装 `pymysql`（已含于 dbskill/requirements.txt）
mariadb	3306	同 mysql，使用 pymysql
oracle	1521	需自行安装驱动，如 `oracledb` 或 `cx_Oracle`
mssql	1433	需自行安装驱动，如 `pyodbc` 或 `pymssql`
db2	50000	需自行安装 IBM DB2 驱动
dm	5236	达梦，需自行安装达梦驱动
kingbase	54321	人大金仓，需自行安装金仓驱动

SQLite、PostgreSQL、MySQL/MariaDB 的依赖已包含在 dbskill/requirements.txt 中，执行 pip install -r requirements.txt 即可。使用上表其他数据库时，需在 dbskill 目录下 按需安装对应驱动：

数据库	安装命令
Oracle	`pip install oracledb`
SQL Server (MSSQL)	`pip install pyodbc` 或 `pip install pymssql`（pyodbc 需系统已安装 ODBC 驱动）
IBM DB2	`pip install ibm-db`（SQLAlchemy 需另装 `ibm_db_sa`）
达梦 (DM)	`pip install dmPython`（部分环境需配置 `DM_HOME`、`LD_LIBRARY_PATH` 等）
人大金仓 (Kingbase)	`pip install ksycopg2`

English

DBSkill is a Skill toolkit that gives AI Agents database access. Agents can query table schemas, run read-only SQL, and run write operations (with appropriate permissions). It supports Direct (connect to the database directly) and API (call the database via HTTP API) modes.

Direct vs API mode

Item	Direct mode	API mode
Meaning	Skill scripts connect to the DB directly	Skill connects via API proxy
Use case	Agent and DB in same environment, direct access	DB remote, or need central auth/audit
Web server required	No	Yes (deploy and run DBSkill API service first)
Permissions & audit	Configure `permission` per DB in local `config.yaml`; audit logs to local files	Server maps API Key to account permissions; server-side audit logs; multi-user

Prefer Direct when possible: simple config, no extra service.
Use API when the DB is remote, multiple clients share the same DB set, or you need centralized API Key and audit management.

Installation

Copy the dbskill directory from this project into your application’s skills directory.
Install Python dependencies: enter the copied dbskill directory and run:
```
pip install -r requirements.txt
```
Inside the dbskill directory, rename config.example.yaml to config.yaml and edit:
- permission: readonly (query only); write (INSERT/UPDATE); full (also DELETE).
- default_db (optional): default database when none is specified (must be one of the names under databases). If there is only one database and default_db is not set, that database is used automatically; with multiple databases, set default_db or pass the database name explicitly when calling.
Test from your AI application.

API installation

If all databases in config.yaml use direct connection, you do not need to deploy the API. Deploy the API when some databases cannot be reached directly or you want central control; the Skill will access the database through the API.

Copy this project to the server and install dependencies:

pip install -e .
# or
uv sync

Copy server.example.yaml to server.yaml and adjust:

admin_db.path: Path for admin UI and API metadata (SQLite), default ./admin.db.
logging: App log file path and rotation. file is the path (omit for console only); rotation.type is size (by size, needs max_bytes, backup_count) or time (by day, needs when, interval, backup_count).
api_audit: Toggle and retention_days for API request audit (stored in admin.db).

3. Start the web service

uvicorn api.main:app --host 0.0.0.0 --port 8000

For production, set session_secret in server.yaml (used for admin session).

4. Docker deployment (optional)

After building the image, you can start with the script (default: mount current data/ for admin.db persistence; mount config.yaml if present; port 8000; override with env vars PORT, SESSION_SECRET, CONFIG_PATH, DATA_PATH):

docker build -t dbskill .
chmod +x scripts/docker-run.sh
./scripts/docker-run.sh

Override with environment variables as needed, e.g.:

PORT=9000 ./scripts/docker-run.sh

Or run the container directly (you can set session_secret in the mounted server.yaml; if unset, a default is used—do not use the default in production):

docker run -d -p 8000:8000 -v $(pwd)/server.yaml:/app/server.yaml -v $(pwd)/data:/app/data dbskill

Ensure the container can reach the database; use data/ for admin.db persistence; in server.yaml you can set admin_db.path: /app/data/admin.db so data is stored on the mounted volume.

5. Admin UI

Log in to the admin UI; default credentials: admin / admin123. There you can configure database connections, API keys, and view audit logs.

Supported databases

type (in config)	Default port	Notes
sqlite	—	File-based; `database` is file path; no extra driver
postgres	5432	Use `psycopg2-binary` (in dbskill/requirements.txt)
mysql	3306	Use `pymysql` (in dbskill/requirements.txt)
mariadb	3306	Same as mysql, use pymysql
oracle	1521	Install driver separately (see below)
mssql	1433	Install driver separately (see below)
db2	50000	Install IBM DB2 driver separately
dm	5236	DM (DaMeng); install driver separately
kingbase	54321	Kingbase; install driver separately

SQLite, PostgreSQL, and MySQL/MariaDB are covered by dbskill/requirements.txt. For other databases, install the driver inside the dbskill directory as needed:

Database	Install command
Oracle	`pip install oracledb`
SQL Server (MSSQL)	`pip install pyodbc` or `pip install pymssql` (pyodbc may require system ODBC driver)
IBM DB2	`pip install ibm-db` (for SQLAlchemy also install `ibm_db_sa`)
DM (DaMeng)	`pip install dmPython` (some environments need `DM_HOME`, `LD_LIBRARY_PATH`, etc.)
Kingbase	`pip install ksycopg2`