DBA

技能文档

---
name: dba
description: DBA工具。支持 MySQL 和 PostgreSQL，支持数据查询、增删改、事务控制、表结构查看、SQL 执行、JSON 输出、表名语义缓存。触发词：MySQL、PostgreSQL、数据库查询、SQL 执行、查表、数据增删改、查看表结构、EXPLAIN 分析、数据库连接、表名搜索、表缓存
title: DBA
category: 开发工具
---

# DBA

通过 `db_cli.py` 脚本直接执行 SQL，支持 **MySQL** 和 **PostgreSQL**。

## 技能工作流

**核心原则：先定位表 → 再确认字段 → 后执行 → 出错自愈。**

### 步骤 1：定位表（缓存优先）

用户说「查XX数据」但未给出准确表名时：

1. **先用业务关键词搜索表名缓存**：

```bash
python3 <SKILL目录>/scripts/db_cli.py --cache-search 订单
```

缓存匹配 表名/中文名/用途，只包含**历史用过的表**（输出会标注「仅含 N 张表」），未命中属正常。

2. **缓存未命中 → 回退查询表列表**：

```bash
# MySQL 查看所有表
python3 <SKILL目录>/scripts/db_cli.py "SHOW TABLES;"

# PostgreSQL 查看所有表（psql 的 \dt 不支持，需用 SQL）
python3 <SKILL目录>/scripts/db_cli.py "SELECT tablename FROM pg_tables WHERE schemaname NOT IN ('pg_catalog','information_schema') ORDER BY tablename;"
```

3. 确定表名后进入步骤 2。第一次操作某张表时，SQL 成功执行后该表会**自动加入缓存**。

### 步骤 2：确认字段

不确定字段名时，先查表结构（不要凭猜测拼字段名）：

```bash
# MySQL 查看表结构
python3 <SKILL目录>/scripts/db_cli.py "DESCRIBE 表名;"

# MySQL 查看完整建表语句
python3 <SKILL目录>/scripts/db_cli.py "SHOW CREATE TABLE 表名;"

# PostgreSQL 查看表结构（psql 的 \d 不支持，需用 SQL）
python3 <SKILL目录>/scripts/db_cli.py "SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name = '表名' ORDER BY ordinal_position;"
```

> 这些语句成功执行后，对应表也会被自动缓存。

### 步骤 3：执行 SQL

```bash
# 查询数据（优先 SELECT *，见下方原则）
python3 <SKILL目录>/scripts/db_cli.py "SELECT * FROM 表名 LIMIT 10;"

# 修改数据（UPDATE/DELETE 必须带 WHERE）
python3 <SKILL目录>/scripts/db_cli.py "UPDATE 表名 SET status = 'active' WHERE id = 1;"
python3 <SKILL目录>/scripts/db_cli.py "DELETE FROM 表名 WHERE id = 1;"

# 事务操作（多条 SQL 全部成功才提交，任一失败回滚）
python3 <SKILL目录>/scripts/db_cli.py -t \
  "INSERT INTO 表名 (name) VALUES ('张三');" \
  "UPDATE accounts SET balance = balance - 100 WHERE id = 1;"

# JSON 格式输出
python3 <SKILL目录>/scripts/db_cli.py -j "SELECT * FROM 表名;"
```

**SELECT 字段选择原则**：优先使用 `SELECT *`，避免指定字段名。

- 执行前无法 100% 确认字段名，硬编码字段极易出现 `Unknown column` 错误
- `SELECT *` 可以直观看到表中所有字段及数据样例，确认后再按需改用指定字段（数据量极大、字段极多的场景）

**正确流程示例**：

```bash
# ❌ 错误：直接执行（字段名可能不存在）
python3 <SKILL目录>/scripts/db_cli.py "SELECT * FROM wms_inbound_order WHERE order_no = 'IB123';"

# ✅ 正确：先查表结构（发现字段是 inbound_no），再执行
python3 <SKILL目录>/scripts/db_cli.py "DESCRIBE wms_inbound_order;"
python3 <SKILL目录>/scripts/db_cli.py "SELECT * FROM wms_inbound_order WHERE inbound_no = 'IB123';"
```

### 步骤 4：错误自愈

**SQL 报错后根据错误信息调整，不要盲目重试。**

| 错误信息 | 原因 | 解决方法 |
|---------|------|----------|
| `Unknown column 'xxx'` (MySQL) | 字段名错误 | `DESCRIBE 表名;` 查看正确字段 |
| `Table 'xxx' doesn't exist` (MySQL) | 表名错误 | `SHOW TABLES;` 查找（缓存中失效条目已自动移除） |
| `column "xxx" does not exist` (PostgreSQL) | 字段名错误 | 查询 `information_schema.columns` 查看正确字段 |
| `relation "xxx" does not exist` (PostgreSQL) | 表名错误 | 查询 `pg_tables` 查找（缓存中失效条目已自动移除） |

**连接类错误**：

- MySQL：`OperationalError (1045)` 密码错误、`(1049)` 库不存在、`(2003)` 连接失败
- PostgreSQL：`password authentication failed` 密码错误、`database does not exist` 库不存在、`could not connect to server` 连接失败

**Unknown database 'xxx' 错误：不要盲目尝试其他 SQL**：

1. 读取 `~/.config/dba/config.json`，确认当前环境指向的数据库
2. 与用户确认：切换到已配置的其他环境（`--env` 参数）或新增配置（`--init` 参数）

**脚本自动处理（无需手动操作）**：依赖缺失自动安装（`pymysql` / `psycopg2-binary`）、配置不存在自动启动配置向导、SQL 语法错误回滚事务。

**执行前自检清单**：

- [ ] 表名是否正确？（不确定先 `--cache-search`，未命中再 `SHOW TABLES;`）
- [ ] 字段名是否正确？（不确定就 `DESCRIBE 表名;`）
- [ ] WHERE 条件字段是否存在？
- [ ] UPDATE/DELETE 是否带 WHERE 条件？（防止全表更新/删除）

## 表名缓存

缓存**用过的表**的表名、中文名（数据库注释）、用途，便于用业务关键词直接定位表，减少逐表翻查。

### 工作方式

- 位置：`~/.config/dba/cache.json`，按「环境 + 数据库」隔离；某环境配置的库变更后，该环境缓存自动失效
- 捕获：任意 SQL 成功执行后**自动**缓存语句涉及的新表；不依赖 `information_schema` 权限，只用单表查询抓注释（MySQL `SHOW TABLE STATUS` / PG `obj_description`）
- 失效：DDL（CREATE/ALTER/RENAME/DROP TABLE）成功后自动刷新或移除对应条目；报「表不存在」时自动移除
- 合并：注释以数据库为准，AI 回写的用途/中文名不会被覆盖
- 注意：未用过的表**不会**提前缓存，缓存完整性随时间增长；未命中时回退 `SHOW TABLES`
- 任何缓存读写失败都不影响 SQL 执行本身（静默降级）

### 命令

```bash
# 搜索表（匹配 表名 / 中文名 / 用途）
python3 <SKILL目录>/scripts/db_cli.py --cache-search 订单

# 查看缓存概览（各环境、表数量、最近更新时间）
python3 <SKILL目录>/scripts/db_cli.py --cache-status

# 回写表用途/中文名（AI 维护用）
python3 <SKILL目录>/scripts/db_cli.py --cache-set 表名 --purpose "订单主表，含状态/金额" --label "订单表"

# 清空当前环境的缓存
python3 <SKILL目录>/scripts/db_cli.py --reset-cache
```

### AI 回写约定

当你**首次充分了解某张表**（执行过 DESCRIBE 或查看过数据）且缓存中该表 `purpose` 为空时，顺手回写一句用途（不超过 30 字）：

```bash
python3 <SKILL目录>/scripts/db_cli.py --cache-set 表名 --purpose "一句话用途"
```

数据库注释缺失时，可同时用 `--label` 补充中文名。

## 快速使用

**脚本路径**：`<SKILL目录>/scripts/db_cli.py`（`<SKILL目录>` 会被自动替换为当前技能的实际路径）

```bash
# 查询数据
python3 <SKILL目录>/scripts/db_cli.py "SELECT * FROM users LIMIT 10;"

# 插入/更新/删除
python3 <SKILL目录>/scripts/db_cli.py "INSERT INTO users (name, email) VALUES ('张三', 'zhangsan@example.com');"
python3 <SKILL目录>/scripts/db_cli.py "UPDATE users SET status = 'active' WHERE id = 1;"
python3 <SKILL目录>/scripts/db_cli.py "DELETE FROM users WHERE id = 1;"

# 事务操作（单条或多条 SQL 在同一事务中执行，全部成功才提交）
python3 <SKILL目录>/scripts/db_cli.py -t \
  "INSERT INTO users (name) VALUES ('张三');" \
  "UPDATE accounts SET balance = balance - 100 WHERE user_id = 1;" \
  "UPDATE accounts SET balance = balance + 100 WHERE user_id = 2;"

# JSON 格式输出
python3 <SKILL目录>/scripts/db_cli.py -j "SELECT * FROM users;"

# 切换环境执行
python3 <SKILL目录>/scripts/db_cli.py --env prod "SELECT * FROM users LIMIT 10;"

# 显示所有结果（默认仅显示前 10 条）
python3 <SKILL目录>/scripts/db_cli.py --all "SELECT * FROM users;"
```

> 详细参数说明见下方 [db_cli.py 参数说明](#db_cli-参数说明)

## 首次使用配置

首次执行 SQL 时，如果检测到配置不存在，会自动启动交互式配置向导；也可手动运行：

```bash
python3 <SKILL目录>/scripts/db_cli.py --init
```

配置文件位置：`~/.config/dba/config.json`（可通过 `AGENT_MYSQL_CONFIG` 环境变量覆盖）

```json
{
  "current": "local",
  "local": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "pwd",
    "database": "db"
  }
}
```

- `type` 支持 `mysql` / `postgresql`（PostgreSQL 默认端口 5432、默认用户 postgres）
- 多环境：并列配置多个环境键（如 `dev`、`prod`），`current` 指定默认环境，用 `--env 环境名` 切换

## 数据库管理

```bash
# MySQL：查看所有数据库 / 当前库的表 / 建库
python3 <SKILL目录>/scripts/db_cli.py "SHOW DATABASES;"
python3 <SKILL目录>/scripts/db_cli.py "SHOW TABLES;"
python3 <SKILL目录>/scripts/db_cli.py "CREATE DATABASE IF NOT EXISTS mydb CHARACTER SET utf8mb4;"

# PostgreSQL：查看所有数据库 / 当前库的表 / 建库
python3 <SKILL目录>/scripts/db_cli.py "SELECT datname FROM pg_database;"
python3 <SKILL目录>/scripts/db_cli.py "SELECT tablename FROM pg_tables WHERE schemaname NOT IN ('pg_catalog','information_schema') ORDER BY tablename;"
python3 <SKILL目录>/scripts/db_cli.py "CREATE DATABASE mydb;"
```

## 数据库导出与 DDL 对比（仅 MySQL）

### 导出 DDL / DML

```bash
# 导出所有表结构（默认排除 schema_migrations）
python3 <SKILL目录>/scripts/db_cli.py --export-ddl sql/dbmate_scm_dev \
  --exclude-tables schema_migrations dbmate_scm

# 导出指定表的数据（空表自动跳过）
python3 <SKILL目录>/scripts/db_cli.py --export-dml sql/dbmate_scm_dev \
  --tables sys_menu sys_config

# 指定输出文件名（默认自动生成时间戳命名）
python3 <SKILL目录>/scripts/db_cli.py --export-ddl sql/dbmate_scm_dev \
  --output-file 20260512120000_DDL_init.sql
```

> 导出功能目前仅支持 MySQL；导出的文件不含 dbmate 的 migrate 标记，需手动添加。

### DDL 差异对比（生成升级脚本）

```bash
# 对比 test 环境（源）与 dev 环境（目标），生成升级脚本到指定目录
python3 <SKILL目录>/scripts/db_cli.py --env test --diff-ddl dev \
  --output-dir sql/dbmate_scm
```

- 生成内容：`migrate:up`（新增表 CREATE + 修改表 ALTER，**不含 DROP TABLE**，确保升级安全）+ `migrate:down`（预留注释，手动补充回滚 SQL）
- 两个环境表结构完全一致时不生成脚本

### 典型迁移流程

```bash
# 1. 导出 DDL/DML 到目录
# 2. 手动在文件头/尾添加 -- migrate:up 和 -- migrate:down 标记
# 3. 交由 dbmate 执行迁移（见 dbmate 技能）
```

## db_cli.py 参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `sql` | 要执行的 SQL 语句（支持多条） | `"SELECT * FROM users;"` |
| `--file, -f` | SQL 文件路径 | `--file query.sql` |
| `--env, -e` | 数据库环境 | `--env dev` |
| `--config, -c` | 配置文件路径 | `--config /path/to/config.json` |
| `--max-rows, -m` | 最大返回行数 | `-m 100` |
| `--json, -j` | JSON 格式输出 | `-j` |
| `--all` | 显示所有查询结果（不截断） | `--all` |
| `--transaction, -t` | 事务模式（单条或多条SQL在同一事务中执行） | `-t "UPDATE..."` |
| `--init` | 初始化配置（交互式配置数据库） | `--init` |
| `--export-ddl` | 导出DDL（导出所有表结构到指定目录） | `--export-ddl sql/dbmate_xxx` |
| `--export-dml` | 导出DML（导出指定表数据到指定目录） | `--export-dml sql/dbmate_xxx --tables sys_menu` |
| `--tables` | 导出DML时指定表名列表 | `--tables table1 table2` |
| `--exclude-tables` | 导出DDL时排除的表（默认排除schema_migrations） | `--exclude-tables schema_migrations` |
| `--output-file, -o` | 指定输出文件名（可选） | `-o init.sql` |
| `--diff-ddl` | 对比DDL差异（对比两个环境生成升级脚本） | `--diff-ddl dev` |
| `--output-dir, -d` | diff-ddl输出目录（默认: sql/dbmate_scm） | `-d sql/dbmate_scm` |
| `--cache-search` | 按关键词搜索表名缓存（匹配表名/中文名/用途） | `--cache-search 订单` |
| `--cache-status` | 查看各环境表名缓存概览 | `--cache-status` |
| `--cache-set` | 回写单表元数据到缓存（配合`--purpose`/`--label`） | `--cache-set users --purpose "用户表"` |
| `--purpose` | 配合 `--cache-set`：回写表用途 | `--purpose "订单主表"` |
| `--label` | 配合 `--cache-set`：回写表中文名 | `--label "订单表"` |
| `--reset-cache` | 清空当前环境的表名缓存 | `--reset-cache` |

**使用示例**：

```bash
# 单条查询
python3 <SKILL目录>/scripts/db_cli.py "SELECT * FROM users LIMIT 10;"

# 多条 SQL（逐条执行，各自独立提交）
python3 <SKILL目录>/scripts/db_cli.py "INSERT INTO..." "UPDATE..."

# 事务模式（单条或多条SQL，全部成功才提交，任一失败则回滚）
python3 <SKILL目录>/scripts/db_cli.py -t \
  "INSERT INTO users (name) VALUES ('张三');" \
  "UPDATE accounts SET balance = balance - 100 WHERE id = 1;"

# JSON 输出（方便程序处理）
python3 <SKILL目录>/scripts/db_cli.py -j "SELECT * FROM users;"

# DDL差异对比（生成升级脚本）
python3 <SKILL目录>/scripts/db_cli.py --env test --diff-ddl dev --output-dir sql/dbmate_scm
```

## 安全建议

1. **禁止**在代码中硬编码密码，使用配置文件或环境变量
2. **使用**参数化查询防止 SQL 注入（拼接 SQL 时注意转义）
3. 生产环境**建议**使用只读账号执行查询
4. 修改操作建议使用事务，确保数据一致性

使用说明

# DBA技能

通过自然语言直接操作 MySQL / PostgreSQL，推荐用 `/dba` 显式调用。

## 使用方法

```
/dba 连接本地数据库
/dba 查询最近7天的订单
/dba 看看用户表有哪些字段
/dba 把订单状态改为已完成
/dba 导出上个月的销售数据
```

## 能做什么

| 场景 | 示例 |
|------|------|
| 连接配置 | `/dba 连接本地`、`/dba 切换到生产环境` |
| 数据查询 | `/dba 查用户表前10条`、`/dba 订单号 O123 的详情` |
| 修改数据 | `/dba 把用户 1001 的状态改为已激活` |
| 查看结构 | `/dba 看看订单表有哪些字段`、`/dba 显示所有表` |
| 表名缓存 | `/dba 查订单相关的表`（匹配表名/中文名/用途，用过的表自动缓存）|
| 批量操作 | `/dba 批量更新订单状态` |
| 性能分析 | `/dba EXPLAIN 这个查询` |
| 导出DDL | `/dba 导出DDL到 sql/dbmate_scm` |
| 导出DML | `/dba 导出DML到 sql/dbmate_scm --tables sys_menu sys_config` |
| DDL对比 | `/dba 对比test和dev环境生成升级脚本`（生成CREATE+ALTER，不含DROP） |

## 首次使用

首次执行时会自动引导配置数据库连接信息，配置文件保存在 `~/.config/dba/config.json`，支持多环境切换。

用过的表会自动缓存到 `~/.config/dba/cache.json`（表名/中文名/用途），下次可用 `--cache-search` 按业务关键词快速定位表。

```json
{"current": "local", "local": {"type": "mysql", "host": "localhost", "port": 3306, "user": "root", "password": "pwd", "database": "db"}}
```

支持多环境：
```
/dba 切换到 test 环境
/dba --env prod 查询今日订单
```

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。