pi-db

English | 中文

pi 编程智能体的统一数据库扩展。一套 db_* 工具覆盖所有已配置数据库——用 connection 参数选目标。初版双后端：

• SQL Server 2008——零依赖 sqlcmd CLI 后端（Windows 集成认证、GBK 解码）
• MySQL 8——mysql2 连接池后端

更多方言（PostgreSQL / Oracle / …）通过同一工具面扩展，工具零改动。

特性

• 统一 db_* 工具：查询、执行、列库、列表、看表结构、连接状态
• 一份配置、一个注册表；加库 = 加配置项，加方言 = 实现一个接口
• MySQL 懒连接池 / SQL Server 每次 spawn，无长连接状态
• 安全闸：DML 直行，DDL 弹确认框，无 UI 模式（print / json / rpc）DDL 一律阻断
• 密码支持 ${ENV_VAR} 引用，配置无需明文
• /db 命令一键体检全部连接

安装

pi install npm:@fanchaozz/pi-db

随后新建配置文件 ~/.pi/agent/pi-db-config.json（见下），在 pi 里 /reload 即可。扩展从 ~/.pi/agent/extensions/ 自动发现，全局与项目本地的放置规则参考 pi 扩展文档。

SQL Server 注意： sqlserver 方言调用 sqlcmd，需 SQL Server Client Tools 在 PATH 上。mysql 方言无系统级依赖。

配置

新建 ~/.pi/agent/pi-db-config.json：

{
  "connections": {
    "sqlserver08": {
      "dialect": "sqlserver",
      "server": "localhost",          // 默认 localhost
      "database": "master",           // 默认数据库
      "auth": "integrated"            // Windows 集成认证 (-E)
      // 或 SQL 认证: "auth": { "username": "sa", "password": "${SQLSERVER_PASSWORD}" }
    },
    "mysql8": {
      "dialect": "mysql",
      "host": "127.0.0.1",
      "port": 3306,
      "user": "root",
      "password": "${MYSQL8_PASSWORD}",  // 明文也支持；env 引用更安全
      "database": null                   // 默认库；null 时跨库必须传 database 参数
    }
  }
}

修改后 /reload 生效。连接名可自由起，即 db_* 工具 connection 参数的取值。

工具

| 工具 | 用途 | |------|------| | db_list_connections | 列出已配置连接（不含密码） | | db_query | SELECT 查询，返回 JSON 结构化结果 | | db_execute | DML（直行）或 DDL（确认） | | db_list_databases | 列出连接上的在线数据库 | | db_list_tables | 列出表/视图（行数估计、注释） | | db_describe_table | 列结构：类型、可空、默认值、键、注释 | | db_status | 健康检查 + 服务器版本 |

公共参数：connection（连接名）、database（可选，跨库用）、sql / table。

命令：/db —— 一条通知内体检全部连接。

MySQL 后端 db_query 单次返回最多 500 行，超出会提示加 WHERE / LIMIT。

安全模型

• db_execute 的 DML（INSERT / UPDATE / DELETE）直接执行
• DDL（CREATE / ALTER / DROP / TRUNCATE / RENAME / GRANT / REVOKE / DENY，按第一条语句判定）弹确认框
• 无 UI 模式（print / json / rpc）DDL 一律阻断
• 建议用 ${ENV_VAR} 引用密码；配置文件本身位于扩展目录之外

扩展新方言

1. 在 src/<dialect>.ts 实现 src/base.ts 的 DbDialect 接口
2. 在 src/config.ts 注册工厂
3. 配置文件加条目，/reload。工具面零改动

已知 SQL Server 后端边界：sqlcmd 文本输出按 CSV 解析，字段值含逗号 / 换行时列位会错位——必要时在 SQL 里用 CONVERT(varchar, ...) 规整字段。

许可

MIT