agent-database-cli

基于 CLI 的多数据库操作工具，将常见数据库连接、查询、元信息读取和连接复用能力封装为 Agent 可调用的本地命令。

MySQL · PostgreSQL · Redis · Oracle · MongoDB · 只读模式 · 命令黑名单 · SQLcl Oracle · 本地 daemon

AI 一键安装 · 安装 · 配置 · 权限配置 · Oracle SQLcl · 许可证 · 友情链接

中文 | English

简介

agent-database-cli 参考 Anarkh-Lee/universal-db-mcp 的数据库适配器、配置加载、安全检查和连接管理分层，改写为独立 CLI 形式，不包含 MCP/HTTP/SSE 服务。

它能做的事：

列出当前支持的数据库类型和本地已配置连接
对指定数据库执行 SQL、Redis 命令或 MongoDB JSON 命令
查询数据库元信息，例如表、列、集合、Redis keys
按单个数据库配置启用只读模式和命令黑名单
Oracle 默认使用 SQLcl；需要 Oracle Instant Client 时可显式切换到 oracle/oracledb 原生驱动
不保存或输出脱敏前的密码、token、secret

驱动配置表：

数据库	`type`	默认驱动	驱动切换配置
MySQL	`mysql`	Rust 原生驱动 `mysql_async`	暂不支持切换
PostgreSQL	`postgres`	Rust 原生驱动 `tokio-postgres`	暂不支持切换
Redis 单机	`redis`	Rust 原生驱动 `redis`	仅配置 `url`
Redis 集群	`redis`	Rust 原生驱动 `redis`	同时配置 `url` 和 `redisCluster.nodes`
Oracle	`oracle`	SQLcl	支持两种驱动：默认 SQLcl （需要自行安装）；可切换oracledb（需要 Oracle Instant Client）
MongoDB	`mongodb`	Rust 原生驱动 `mongodb`	暂不支持切换；可配 `database` 指定默认库

安装

环境要求

Node.js >= 20
npm >= 10
系统支持 Windows / macOS / Linux
安装时会自动拉取对应平台的 Rust 二进制子包，当前支持 macOS x64/arm64、Linux x64/arm64、Windows x64
本机网络可访问目标数据库
如使用 Docker 集成测试，需要 Docker 和 Docker Compose
如 Oracle 使用 SQLcl，需要本机可运行 SQLcl 和 Java21

AI 一键安装

安装请阅读 https://github.com/sleepinginsummer/agent-database-cli/blob/main/AI_INSTALL.md，按说明安装 CLI 并添加 `SKILL.md`。

手动全局安装

npm install -g agent-database-cli
agent-database-cli --help

如果 npm 包安装受限，使用等价的源码安装方式：

git clone https://github.com/sleepinginsummer/agent-database-cli.git
cd agent-database-cli
npm install
npm run build
npm link
agent-database-cli --help

添加skiil.md到需要使用的agent中

配置

默认配置文件：

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

可以通过环境变量修改配置位置：

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

配置文件是一个对象，databases 中每个 key 是一个数据库连接名。

连接配置：

字段	适用范围	默认值	说明
`type`	全部数据库	无	数据库类型，支持 `mysql`、`postgres`、`redis`、`oracle`、`mongodb`
`url`	全部数据库	无	数据库连接 URL；Redis 单机模式直接连接该地址，Redis 集群模式下作为入口节点 URL
`database`	MongoDB	无	MongoDB 默认数据库名
`oracleDriver`	Oracle	`sqlcl`	Oracle 驱动：`sqlcl` 或原生驱动
`sqlclPath`	Oracle SQLcl	无	SQLcl 可执行文件路径，仅 `oracleDriver: "sqlcl"` 时使用
`javaHome`	Oracle SQLcl	无	SQLcl 使用的 `JAVA_HOME`
`redisCluster`	Redis	无	Redis 集群配置，配置后会使用 Redis Cluster 模式
`sshTunnel`	全部数据库	无	SSH 隧道配置；单机模式转发数据库 URL 的 host/port，Redis 集群模式为每个节点分别建立本地转发
`readonly`	全部数据库	`true`	是否启用只读模式；仅在明确需要写入时才建议显式设为 `false`
`blacklist`	全部数据库	无	命令黑名单数组，大小写不敏感
`keepAliveSeconds`	全部数据库	`180`	单个数据库连接空闲释放秒数

Redis 集群配置：

字段	默认值	说明
`nodes`	无	Redis 集群节点 URL 数组，至少配置一个，支持 `redis://` 和 `rediss://`

Redis 集群使用规则：

场景	要求
启用集群模式	必须同时配置 `url` 和 `redisCluster.nodes`
`url`	用作集群入口节点，建议填写任意一个稳定可达的集群节点 URL
`redisCluster.nodes`	用作集群节点清单；如走 SSH 隧道，也用于为每个节点建立本地转发和地址映射
同时配置 `sshTunnel`	程序会给每个集群节点分别建立本地端口转发，并通过地址映射接管集群节点跳转
通过 SSH 隧道访问集群	`redisCluster.nodes` 需要覆盖客户端实际可能访问到的集群节点地址

SSH 隧道配置支持密码、私钥、密码加私钥、带通行短语的私钥认证。

字段	默认值	说明
`host`	无	SSH 跳板机地址
`port`	`22`	SSH 端口
`username`	无	SSH 用户名
`password`	无	SSH 密码，可选
`privateKeyPath`	无	私钥文件路径，可选，支持 `~`
`privateKey`	无	私钥内容，可选，和 `privateKeyPath` 二选一
`passphrase`	无	私钥通行短语，可选，仅配置私钥时允许使用
`readyTimeout`	无	SSH 连接超时时间，单位毫秒，可选

安全策略：

策略	说明
检查优先级	先检查黑名单，命中直接拒绝；未命中再检查只读模式
只读默认值	默认启用只读模式，未显式配置 `readonly` 时也会拒绝写操作
推荐用法	所有数据库连接默认保持只读，需要变更数据时，让 AI 先给出对应 SQL 或命令，再由你确认后执行
写入配置	某个连接确实需要写入时，再单独将该连接配置为 `readonly: false`

参考配置：

{
  "databases": {
    "local-mysql": {
      "type": "mysql",
      "url": "mysql://user:password@localhost:3306/app",
      "readonly": true,
      "blacklist": ["drop", "truncate", "delete"],
      "keepAliveSeconds": 180
    },
    "remote-mysql": {
      "type": "mysql",
      "url": "mysql://user:[email protected]:3306/app",
      "sshTunnel": {
        "host": "jump.example.com",
        "port": 22,
        "username": "deploy",
        "privateKeyPath": "~/.ssh/id_rsa",
        "passphrase": "key-passphrase"
      },
      "readonly": true,
      "keepAliveSeconds": 180
    },
    "redis-standalone": {
      "type": "redis",
      "url": "redis://localhost:6379",
      "readonly": false,
      "blacklist": ["flushall", "flushdb"],
      "keepAliveSeconds": 180
    },
    "redis-cluster": {
      "type": "redis",
      "url": "redis://10.0.0.11:7001",
      "redisCluster": {
        "nodes": [
          "redis://10.0.0.11:7001",
          "redis://10.0.0.12:7001",
          "redis://10.0.0.13:7001"
        ]
      },
      "readonly": true,
      "blacklist": ["flushall", "flushdb"],
      "keepAliveSeconds": 180
    },
    "redis-cluster-via-ssh": {
      "type": "redis",
      "url": "redis://10.0.0.11:7001",
      "redisCluster": {
        "nodes": [
          "redis://10.0.0.11:7001",
          "redis://10.0.0.12:7001",
          "redis://10.0.0.13:7001"
        ]
      },
      "sshTunnel": {
        "host": "jump.example.com",
        "port": 22,
        "username": "deploy",
        "privateKeyPath": "~/.ssh/id_rsa"
      },
      "readonly": true,
      "blacklist": ["flushall", "flushdb"],
      "keepAliveSeconds": 180
    },
    "oracle-test": {
      "type": "oracle",
      "url": "oracle://USER:[email protected]: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"],
      "keepAliveSeconds": 180
    }
  }
}

权限配置

权限控制建议同时使用 readonly 和 blacklist，不要只依赖其中一个。

只读模式

默认值是 true
不配置 readonly 时，仍然会按只读模式处理
推荐所有日常查询连接都保持默认只读
需要修改数据时，建议先让 AI 生成对应 SQL 或命令，再由你确认后执行
只有明确需要写入的专用连接，才单独配置 readonly: false

命令黑名单

黑名单优先级高于只读模式
命中黑名单后会直接拒绝，不再继续判断是否只读
适合拦截高危命令，避免误执行删库、删表、结构变更、批量写入、清空缓存等操作
建议生产库、共享测试库、线上 Redis 都配置黑名单

执行顺序

先检查 blacklist
命中则直接拒绝
未命中再检查 readonly
readonly 生效时只允许读命令

常见高危命令

MySQL / PostgreSQL / Oracle 常见高危 SQL：

["drop", "truncate", "delete", "update", "insert", "merge", "alter", "create", "replace", "grant", "revoke"]

Redis 常见高危命令：

["flushall", "flushdb", "del", "unlink", "set", "mset", "expire", "rename", "hset", "lpush", "rpush", "sadd", "zadd"]

MongoDB 常见高危命令：

["insertOne", "insertMany", "updateOne", "updateMany", "replaceOne", "deleteOne", "deleteMany", "findAndModify", "findOneAndUpdate", "findOneAndDelete", "drop", "dropDatabase", "createIndex", "dropIndex"]

Oracle SQLcl

官方链接：https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/

Oracle 默认使用 SQLcl，避免默认依赖 Oracle Instant Client，也更适合 Oracle 11 等老库。可以不配置 oracleDriver，或显式配置为 SQLcl：

{
  "type": "oracle",
  "url": "oracle://USER:[email protected]: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 传入连接脚本，避免密码出现在命令行参数列表中。安全检查仍在执行前完成，黑名单和只读模式都会生效。

更新

npm install -g agent-database-cli@latest

卸载和清理

npm uninstall -g agent-database-cli
npm cache clean --force
rm -rf ~/.agent-database-cli

许可证

MIT

友情链接

LINUX DO - 新的理想型社区

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/workflows		.github/workflows
bin		bin
config		config
npm		npm
rust/src		rust/src
.gitignore		.gitignore
AI_INSTALL.md		AI_INSTALL.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
SKILL.md		SKILL.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agent-database-cli

简介

安装

环境要求

AI 一键安装

手动全局安装

配置

权限配置

只读模式

命令黑名单

执行顺序

常见高危命令

推荐配置示例

Oracle SQLcl

更新

卸载和清理

许可证

友情链接

About

Uh oh!

Releases 13

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

agent-database-cli

简介

安装

环境要求

AI 一键安装

手动全局安装

配置

权限配置

只读模式

命令黑名单

执行顺序

常见高危命令

推荐配置示例

Oracle SQLcl

更新

卸载和清理

许可证

友情链接

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages