agent-database-cli 使用说明

agent-database-cli 是一个基于本地配置的多数据库命令行工具，用于让 AI 或用户安全地操作数据库。

它能做的事：

• 列出支持的数据库类型和本地已配置数据库连接
• 测试指定数据库连接
• 执行 SQL、Redis 命令或 MongoDB JSON 命令
• 查询表、列、集合、Redis keys 等元信息
• 按单个数据库配置执行命令黑名单和只读模式
• 普通命令会按需自动启动本地 daemon，daemon 默认空闲 1800 秒后自动退出
• 通过本地 daemon 短时间保持连接，单个数据库连接默认空闲 180 秒释放
• daemon 在 Windows 使用 named pipe，在 macOS/Linux 使用 Unix socket
• 预编译二进制支持 macOS x64/arm64、Linux x64/arm64、Windows x64
• Oracle 默认使用 SQLcl；显式配置 oracleDriver: "oracle" 或 "oracledb" 时使用原生 Oracle 驱动
• 用本地页面可视化编辑配置文件：editor start 启动、editor stop 关闭、editor status 查看状态

它不做的事：

• 不扫描网络或发现数据库，只使用配置文件中的连接
• 不绕过配置中的黑名单和只读模式
• 不输出未脱敏的密码、token、secret
• 不默认执行写入、删除、DDL 或其它危险命令

安全确认

执行任何可能写入、删除、修改结构或影响数据完整性的命令前，必须先确认目标数据库配置是否启用了 readonly 和 blacklist。

危险操作包括：

• DDL：drop、truncate、alter、create
• DML 写入：insert、update、delete、merge
• Redis 清空或写入：flushall、flushdb、set、del
• MongoDB 写入或删除：insertOne、updateOne、deleteMany、drop、dropDatabase
• 任何不可逆、影响生产数据、影响结构或权限的命令

如果用户明确要求执行危险命令，先说明目标数据库名、命令、可能影响，并等待用户明确同意。即使用户同意，也不能绕过本项目配置中的黑名单和只读模式。

黑名单优先级高于只读模式。命令执行前先检查 blacklist，命中后直接拒绝；未命中时再检查 readonly。

读取配置文件json前需要用户确认，防止密钥泄露。

环境校验

调用前优先检查 CLI 是否可用：

agent-database-cli --help

如果上面的命令失败，检查基础环境：

node --version
npm --version

如果依赖或构建产物缺失，在项目目录中执行：

npm install
npm run build

默认配置文件：

~/.agent-database-cli/config.json

指定其它配置文件：

AGENT_DATABASE_CLI_CONFIG=/path/to/config.json agent-database-cli list

配置格式

配置文件是 JSON 对象，根字段为 databases：

{
  "databases": {
    "local-mysql": {
      "type": "mysql",
      "url": "mysql://user:password@localhost:3306/app",
      "readonly": true,
      "blacklist": ["drop", "truncate", "delete"],
      "keepAliveSeconds": 180
    }
  }
}

字段：

• type: mysql、postgres、redis、oracle、mongodb
• group: 可选单层分组名
• tags: 可选标签字符串数组，去空白、去重并保留大小写
• url: 数据库连接 URL
• passwordRef: 数据库 URL 密码的本地密文引用，首次使用明文 URL 密码时自动生成
• database: MongoDB 默认数据库名，可选
• readonly: 是否启用只读模式
• blacklist: 命令黑名单数组，大小写不敏感
• keepAliveSeconds: daemon 连接空闲释放秒数，默认 180
• oracleDriver: Oracle 驱动，可选 oracledb 或 sqlcl
• sqlclPath: SQLcl 可执行文件路径
• javaHome: SQLcl 使用的 JAVA_HOME
• sshTunnel.passwordRef: SSH 密码的本地密文引用，首次使用明文 sshTunnel.password 时自动生成
• sshTunnel.passphraseRef: SSH 私钥口令的本地密文引用，首次使用明文 sshTunnel.passphrase 时自动生成

首次使用连接时，CLI 会把数据库 URL 明文密码、sshTunnel.password、sshTunnel.passphrase 加密保存到配置目录的 secrets.json，生成本地 secret.key，并把配置文件改写为对应 *Ref。后续只在内存中解密使用；改密码时重新填入明文字段即可覆盖旧密文。

全局参数

• --format <format>: 输出格式，支持 json 或 table，默认 json
• --help, -h: 输出帮助
• --version, -V: 输出版本

配置路径通过环境变量传递：

AGENT_DATABASE_CLI_CONFIG=/path/to/config.json

list

列出支持的数据库类型、已配置连接和配置文件路径。

agent-database-cli list
agent-database-cli --format table list
agent-database-cli list --group 生产环境 --tag 应用

--group 与 --tag 区分大小写精确匹配，同时指定时取交集；无匹配时 configured 与 connections 均为空数组。

返回值：

• 成功时 stdout 输出 JSON 或表格
• 输出包含 supported、configured、connections、configPath；configured 保持连接名数组，connections 含 name、type、group、tags
• 配置文件不存在时仍会输出支持列表，configured 为空
• 退出码为 0

test

测试指定数据库连接。

agent-database-cli test --db "<databaseName>"

返回值：

• 成功时 stdout 输出 { "ok": true }
• 连接失败、配置缺失或认证失败时 stderr 输出错误，退出码为 1

exec

统一执行 SQL、Redis 命令或 MongoDB JSON 命令。

agent-database-cli exec --db "<databaseName>" --command "<command>"

示例：

agent-database-cli exec --db local-mysql --command "select 1"
agent-database-cli exec --db cache --command "GET user:1"
agent-database-cli exec --db local-mongodb --command '{"find":{"collection":"users","filter":{},"limit":1}}'

返回值：

• 成功时 stdout 输出 rows、fields、rowCount
• 命中黑名单、违反只读模式、命令执行失败时 stderr 输出错误，退出码为 1
• SQLcl Oracle 模式会解析 SQLcl JSON 输出，成功时同样返回统一的 rows、fields、rowCount；仅在无法解析为 JSON 时才以 output 字段返回原始文本

meta

查询数据库元信息。

agent-database-cli meta --db "<databaseName>" --type tables
agent-database-cli meta --db "<databaseName>" --type columns --table users
agent-database-cli meta --db "<databaseName>" --type collections
agent-database-cli meta --db "<databaseName>" --type keys --pattern "user:*"

参数：

• --db <name>: 数据库配置名
• --type <type>: tables、columns、collections、keys
• --table <table>: columns 查询所需表名
• --pattern <pattern>: Redis keys 匹配模式

返回值：

• 成功时 stdout 输出查询结果
• 当前数据库不支持的元信息类型会失败并返回错误

daemon

管理本地连接守护进程。普通 test、exec、meta、reset 命令会在 daemon 未运行时自动启动 daemon，已运行时直接复用，不会重复启动。daemon 使用 Unix socket，不暴露网络端口，默认空闲 1800 秒后自动退出。

agent-database-cli daemon start
agent-database-cli daemon status
agent-database-cli daemon stop

查询响应默认限时 60 秒，通过 AGENT_DB_QUERY_TIMEOUT_SECS 配置；daemon 空闲退出通过 AGENT_DB_DAEMON_IDLE_SECS 配置，默认 1800 秒。两者只接受正整数，无效值使用默认值。修改后需 daemon stop，下次调用自动按新环境启动；单库 keepAliveSeconds 仍默认 180 秒。

MySQL 同库请求通过连接池并发执行；缺省 pool_max 为 max(4, 显式 pool_min)，保留其他 URL 池参数，冲突约束报错。超时只关闭当前连接。命令可能使用不同会话，不要依赖跨命令事务/会话变量。daemon status 的 busy 和 inFlight 反映执行和排队中的请求；请求从接收到响应写完都禁止空闲退出。

SQLcl 超时终止子进程；原生 Oracle 请求 OCI 取消，仅在 Client ≥ 18.1 时按剩余期限限制每次往返；Client 11.2/12.1/12.2 保留外层期限与 OCI 取消（建立连接时尚无句柄，无法用 OCI 取消登录）。其他驱动的响应超时不保证服务端立即停止；写操作超时后先核实数据库状态再决定是否重试。

返回值：

• start 成功时输出 socket 路径
• status 成功时输出当前连接列表
• stop 成功时输出停止结果

reset

重置指定数据库连接。

agent-database-cli reset --db "<databaseName>"

如果 daemon 正在运行，会断开并清理该数据库连接；下一次命令会重新连接。

editor

在本机启动配置编辑服务，用页面可视化修改配置文件。

agent-database-cli editor start
agent-database-cli editor start --no-open
agent-database-cli editor status
agent-database-cli editor stop

返回值：

• start 成功时输出 started、running、url、port、pid、configPath、browserOpened；服务已在运行时 started 为 false
• status 未运行时输出 { "running": false }，状态文件残留时额外返回 stale
• stop 未运行时不报错，输出 { "stopped": false, "running": false }

约束：

• 服务只监听 127.0.0.1，端口默认随机，可用 --port 指定
• 访问令牌每次启动重新生成，随 URL fragment 交给页面，/api/* 请求必须携带
• 状态文件 ~/.agent-database-cli/editor.json 权限为 0600
• 超过 10 分钟没有任何操作，编辑服务会自动退出；页面在有操作时定期打点保活
• 保存前先校验 JSON 结构和配置规则，通过后备份 config.json.bak 再原子替换，并保留原文件权限
• 页面只读写配置文件原文，不触发明文密码迁移；密文默认不展示，点眼睛才会按需解密，且只接受当前配置引用到的 ref，解密结果不写回配置文件
• 右侧 JSON 面板可切「当前连接 / 全局」范围，并按磁盘内容做行级 diff（边栏 + 新增、~ 修改）
• 这是给人用的页面；Agent 自己改配置仍应直接编辑配置文件，并在修改前确认目标连接

Oracle SQLcl

当 Oracle oracledb Thin mode 不支持目标库版本时，可以改用 SQLcl。

{
  "type": "oracle",
  "url": "oracle://USER:password@192.0.2.20:1521/qftest201",
  "oracleDriver": "sqlcl",
  "sqlclPath": "/opt/homebrew/Caskroom/sqlcl/26.1.0.086.1709/sqlcl/bin/sql",
  "javaHome": "/Applications/IntelliJ IDEA Ultimate.app/Contents/jbr/Contents/Home",
  "readonly": true,
  "blacklist": ["drop", "truncate", "delete", "update", "insert", "merge", "alter", "create"]
}

SQLcl 模式通过 stdin 传入连接脚本，避免密码出现在命令行参数列表中。执行前仍会先走本地黑名单和只读检查；输出会按内部标记截取 SQLcl 查询结果并解析为统一结果结构。

错误规则

• 配置文件 JSON 无效时失败
• databases 缺失或数据库配置名不存在时失败
• 未知 type、未知 oracleDriver 或非法 keepAliveSeconds 会失败
• exec 缺少 --db 或 --command 会失败
• meta columns 缺少 --table 会失败
• 命中黑名单时失败，错误中包含 黑名单拒绝执行命令
• 违反只读模式时失败，错误中包含 只读模式拒绝执行命令
• 编辑页面保存时 JSON 结构或配置规则不合法会失败，错误里带上具体规则
• editor start 在端口被占用或服务启动超时时失败
• 所有失败统一在 stderr 输出错误信息，退出码为 1