db-toolkit（数据库工具包）

Database Toolkit

轻量级数据库操作工具，支持 MySQL、PostgreSQL、SQLite 三大主流数据库。

核心原则

1. 智能发现优先 - 先尝试从项目中自动发现连接信息，找不到再询问
2. 每次操作都传入连接信息 - 不持久化存储，会话结束后自动遗忘
3. 安全第一 - 连接信息仅在当前会话有效，不写入任何文件
4. 必须查询真实数据库 - 见下方【重要】章节

⚠️ 重要：必须查询真实数据库

禁止行为：

• ❌ 读取项目中的 schema.sql、init.sql 等文件来回答表结构
• ❌ 读取 ORM 的 model/entity 文件来推断表结构
• ❌ 基于代码或配置文件假设数据库状态

必须行为：

• ✅ 使用 scripts/list-tables.ts 查询实际数据库中的表列表
• ✅ 使用 scripts/describe-table.ts 查询实际数据库中的表结构
• ✅ 通过实际连接获取真实、实时的数据库信息

原因：

1. 项目文件可能不是最新的（代码与数据库可能不同步）
2. 数据库可能有手动修改（未反映在代码中）
3. 用户需要的是实际数据库的状态，不是代码中的定义
4. schema.sql 只是模板，不包含实际数据

正确示例：

用户问："查看 users 表有哪些字段"
❌ 错误：读取 schema.sql 或 User.java 来回答
✅ 正确：运行 describe-table.ts 脚本查询实际数据库

唯一例外：

• 用户明确要求"查看 schema.sql 文件"或"查看代码中的表定义"时，才读取项目文件

工作流程

用户请求
    │
    ▼
检查是否已有连接信息
    │
    ├──▶ 有 ──▶ 直接使用
    │
    └──▶ 无 ──▶ 智能探索项目（见下方）
                    │
                    ├──▶ 找到一个 ──▶ 直接使用
                    │
                    ├──▶ 找到多个 ──▶ 询问用户选择哪个
                    │
                    └──▶ 未找到 ──▶ 询问用户提供连接信息

智能探索连接信息

当用户未提供连接信息时，先尝试从项目中自动发现：

探索策略

使用 glob 和 read 工具，按优先级搜索：

1. 环境变量文件
   - .env, .env.local, .env.development, .env.production

2. 应用配置文件（常见框架）
   - **Spring Boot**: application.yml, application.yaml, application.properties
     （注意：可能在 backend/, server/, api/ 等子目录）
   - **Node.js**: config/database.yml, config/database.yaml, knexfile.*, drizzle.config.*
   - **Django**: settings.py
   - **Rails**: config/database.yml, config/database.yaml
   - **Laravel**: .env, config/database.php

3. ORM 配置
   - **Prisma**: prisma/schema.prisma
   - **Drizzle**: drizzle.config.ts, drizzle.config.js

探索命令示例

# 查找环境变量文件
glob pattern=".env*"

# 查找 Spring Boot 配置（支持 monorepo）
glob pattern="**/application*.yml"
glob pattern="**/application*.yaml"
glob pattern="**/application*.properties"

# 查找 Node.js 配置
glob pattern="**/database.{yml,yaml,json,js,ts}"
glob pattern="**/knexfile.{js,ts}"

# 查找 Prisma/Drizzle
glob pattern="**/schema.prisma"
glob pattern="**/drizzle.config.{js,ts}"

解析配置文件

找到配置文件后，读取并提取连接信息：

关键变量名：

• URL 形式：DATABASE_URL, DB_URL, MYSQL_URL, POSTGRES_URL, spring.datasource.url
• 分开形式：DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_DATABASE

示例解析：

# Spring Boot application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret

# .env
DATABASE_URL=mysql://root:secret@localhost:3306/mydb

// drizzle.config.ts
export default {
  connection: 'mysql://root:secret@localhost:3306/mydb'
}

处理环境变量占位符

配置文件可能包含占位符，需要解析：

# 带默认值的占位符
url: jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:mydb}

解析规则：

1. 如果 ${VAR_NAME:default} 格式，优先读取环境变量
2. 如果环境变量不存在，使用默认值
3. 提取最终的连接信息

找到多个连接时的处理

如果发现多个数据库连接配置，使用 ask-user-question 询问用户：

发现以下数据库连接：
1. MySQL - localhost:3306/mydb (来自 application.yml)
2. PostgreSQL - localhost:5432/app ( 来自 .env)

请问要使用哪个？

连接信息格式

收集到的连接信息统一转换为以下格式：

数据库类型: mysql / postgresql / sqlite
主机: localhost
端口: 3306
用户名: root
密码: secret
数据库名: mydb

# 或 URL 形式
mysql://root:secret@localhost:3306/mydb

脚本使用

首次使用（安装依赖）

技能脚本依赖 TypeScript 运行时和数据库驱动，需要全局安装：

npm install -g tsx mysql2 pg better-sqlite3

注意：better-sqlite3 需要编译本地模块，确保系统有 make 和 gcc 工具。

⚠️ 重要：运行脚本前的准备

为什么需要 NODE_PATH？ Node.js 有两种模块系统： - CommonJS (require)： 支持 NODE_PATH，可以找到全局安装的包 - ESM (import)： 不支持 NODE_PATH，这是 Node.js 的设计决策 本技能的脚本使用 require（而非 import）来加载全局依赖，因此需要设置 NODE_PATH。

第一步：设置 NODE_PATH 环境变量

export NODE_PATH=$(npm root -g)

第二步：获取技能目录路径

所有脚本使用相对于技能根目录的路径。获取技能目录：

# 方法 1：通过 SKILL.md 位置推断（推荐）
SKILL_DIR=$(dirname $(grep -rl "name: db-toolkit" ~/.config/opencode/skills 2>/dev/null | head -1))

# 方法 2：直接使用本文件所在目录
# SKILL_DIR=/path/to/db-toolkit

第三步：运行脚本

使用 $SKILL_DIR/scripts/ 前缀执行脚本：

tsx $SKILL_DIR/scripts/test-connection.ts --url "mysql://..."

测试连接

tsx $SKILL_DIR/scripts/test-connection.ts --url "mysql://root:secret@localhost:3306/mydb"

# 或分开参数
tsx $SKILL_DIR/scripts/test-connection.ts \
  --db-type mysql \
  --host localhost \
  --port 3306 \
  --user root \
  --password secret \
  --database mydb

列出所有表

tsx $SKILL_DIR/scripts/list-tables.ts --url "mysql://root:secret@localhost:3306/mydb"

查看表结构

tsx $SKILL_DIR/scripts/describe-table.ts --url "mysql://root:secret@localhost:3306/mydb" --table users

DDL/DML 操作

对于 DDL 和 DML 操作，根据数据库类型读取对应的参考文档：

安全注意事项

1. 不记录连接信息 - 脚本输出中不应包含密码等敏感信息
2. 使用参数化查询 - 防止 SQL 注入
3. 连接超时 - 建议设置合理的连接超时时间
4. 操作确认 - 危险操作（DROP、TRUNCATE）前应确认

Resources

scripts/

references/

按数据库类型组织，每个数据库包含：

• connection.md - 连接配置详解
• ddl.md - DDL 操作模板（CREATE/ALTER/DROP）
• dml.md - DML 操作模板（SELECT/INSERT/UPDATE/DELETE）