---
title: DBX CLI
description: 在终端、脚本、CI 和 Codex 中使用 DBX 连接。
---
DBX CLI 是独立命令行包，适合终端、脚本和 AI 编程助手工作流。它与 MCP Server 共享 DBX 连接存储和 SQL 安全规则。
## 安装
```bash
npm install -g @dbx-app/cli
```
需要 Node.js 22.13.0 或更高版本。
查看版本：
```bash
dbx --version
```
## 常用命令
```bash
dbx doctor
dbx capabilities
dbx connections list --json
dbx connections list --format csv
dbx schema list local --json
dbx schema describe local users --json
dbx query local "select count(*) as total from users" --json
dbx query local "select id, name from users" --format csv
dbx query local "select * from users" --limit 50 --timeout 10s --json
dbx query local --file ./query.sql --json
dbx context local --tables users,orders
dbx open local users
```
## 诊断
使用 `dbx doctor` 查看本地 DBX 路径、连接存储健康状态，以及桌面端 bridge 是否可用：
```bash
dbx doctor
dbx doctor --json
```
如果切换 Node.js 版本后，`dbx doctor` 报 `NODE_MODULE_VERSION` 不匹配，请用运行 `dbx` 的同一个 Node.js 版本重建 native 依赖：
```bash
pnpm rebuild better-sqlite3 keytar --pending
```
如果是全局 npm 安装，使用同一个 Node.js 版本重新安装 CLI：
```bash
npm uninstall -g @dbx-app/cli
npm install -g @dbx-app/cli
```
使用 `dbx capabilities` 查看哪些数据库类型可以直接查询，哪些当前需要 DBX 桌面端：
```bash
dbx capabilities
dbx capabilities --json
```
当前直接执行支持 PostgreSQL/Redshift、MySQL 兼容数据库（MySQL、Doris、StarRocks）和 SQLite。其它数据库类型在对应驱动加入 `@dbx-app/node-core` 前，会使用 DBX 桌面端 bridge。
## 默认连接
设置 `DBX_CONNECTION` 后，`query` 和 `context` 命令可以省略连接名：
```bash
DBX_CONNECTION=local dbx query "select 1" --json
DBX_CONNECTION=local dbx context --tables users,orders
```
## 输出格式
使用 `--json` 或 `--format json` 可以获得稳定的机器可读输出。`--format csv` 适合把查询、连接、Schema 数据传给其它命令行工具。
```bash
dbx query local "select id, name from users" --format csv
```
错误会写入 stderr，并返回非零退出码。
## 查询控制
`dbx query` 执行单条 SQL，默认只读。
```bash
dbx query local "select * from users" --limit 50 --timeout 10s --json
```
时间支持 `ms`、`s`、`m`，例如 `500ms`、`10s`、`1m`。
非危险写操作需要显式使用 `--allow-writes`：
```bash
dbx query local "update users set name = 'Ada' where id = 1" --allow-writes
```
`DROP`、`TRUNCATE`、`ALTER` 等危险 SQL 需要同时显式使用 `--allow-writes` 和 `--allow-dangerous-sql`。
## 以短横线开头的 SQL
如果 SQL 以短横线开头，在 SQL 前加 `--`：
```bash
dbx query local --json -- "-- comment
select 1"
```
## 错误码
CLI JSON 错误使用稳定错误码：
| 错误码 | 含义 |
|---|---|
| `UNKNOWN_OPTION` | 使用了不支持的参数 |
| `INVALID_OPTION` | 参数缺少值或值不合法 |
| `INVALID_ARGUMENT` | 位置参数缺失或冲突 |
| `CONNECTION_STORE_ERROR` | DBX 连接存储存在，但无法读取 |
| `CONNECTION_NOT_FOUND` | 找不到指定的 DBX 连接 |
| `SQL_BLOCKED` | SQL 被安全规则拦截 |
| `DBX_NOT_RUNNING` | DBX 桌面端 bridge 不可用 |
| `ERROR` | 未预期的运行时错误 |
## 桌面端 Deep Link
DBX 桌面端支持通过 `dbx://connection/new` 从浏览器、堡垒机或脚本打开新建连接窗口并预填连接信息。
DSN 模式：
```bash
open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders'
```
字段模式：
```bash
open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test'
```
支持的字段：
| 字段 | 含义 |
|---|---|
| `type` | 数据库类型，例如 `mysql`、`postgres`、`redis`、`mongodb` |
| `url` | 数据库 DSN，建议 URL encode |
| `name` | DBX 中显示的连接名；未传时优先使用 `database`，其次使用 `host` |
| `host` | 主机地址 |
| `port` | 端口 |
| `user` | 用户名 |
| `password` | 密码 |
| `database` | 数据库名；Redis 可传 DB index，例如 `0` |
| `url_params` | 额外连接参数，例如 `sslmode=require` |
| `ssl` | 是否启用 SSL，`true` 表示启用 |
| `one_time` | `true` 时自动连接，断开后自动删除连接信息 |
一次性连接示例：
```bash
open 'dbx://connection/new?type=redis&host=127.0.0.1&port=6379&user=default&password=secret&database=0&one_time=true'
```
测试系统级 `dbx://` 唤起前，请先安装并启动一次 DBX 桌面端，让系统注册 URL 协议。macOS 可使用 `open 'dbx://connection/new?...'` 测试。
## Codex
Codex 可以直接通过 shell 调用 CLI：
```bash
dbx schema describe local users --json
dbx context local --tables users,orders | codex exec "Write a retention query"
```