217 lines
7.8 KiB
Plaintext
217 lines
7.8 KiB
Plaintext
---
|
||
title: DBX CLI
|
||
description: 使用原生 DBX CLI 在终端、脚本、CI 和 Codex 中读取连接、Schema、查询结果和 AI 上下文。
|
||
---
|
||
|
||
<Callout type="info">DBX CLI 是独立命令行包，适合终端、脚本和 AI 编程助手工作流。它与 MCP Server 共享 DBX 连接存储和 SQL 安全规则。</Callout>
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install -g @dbx-app/cli
|
||
```
|
||
|
||
### Homebrew
|
||
|
||
```bash
|
||
brew tap t8y2/dbx
|
||
brew install dbx-cli
|
||
```
|
||
|
||
通过 npm 安装时需要 Node.js 18.18.0 或更高版本。CLI 本身不依赖 `better-sqlite3`，也不受 Node.js native module ABI 影响。Homebrew 用户不需要单独管理 Node.js。
|
||
|
||
### 独立原生版本
|
||
|
||
`packages-v*` GitHub Release 会提供适用于 macOS、Linux 和 Windows 的 CLI 原生压缩包。下载对应平台的压缩包后，使用 `CLI-SHA256SUMS` 校验，解压即可直接运行 `dbx`，不需要 Node.js。
|
||
|
||
```bash
|
||
tar -xzf dbx-cli-linux-x64-gnu.tar.gz
|
||
chmod +x dbx
|
||
./dbx --version
|
||
```
|
||
|
||
如果使用自定义或便携版 DBX 数据目录，可以设置 `DBX_DATA_DIR`。
|
||
|
||
查看版本：
|
||
|
||
```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
|
||
```
|
||
|
||
如果 npm 没有安装当前平台包，请不要使用 `--no-optional`，重新安装：
|
||
|
||
```bash
|
||
npm uninstall -g @dbx-app/cli
|
||
npm install -g @dbx-app/cli
|
||
```
|
||
|
||
使用 `dbx capabilities` 查看哪些数据库类型可以直接查询，哪些当前需要 DBX 桌面端：
|
||
|
||
```bash
|
||
dbx capabilities
|
||
dbx capabilities --json
|
||
```
|
||
|
||
当前原生直连清单由 CLI 二进制维护，包括 PostgreSQL、Redshift、MySQL、Doris、StarRocks、Manticore Search、SQLite、rqlite、KWDB 和 QuestDB。`dbx capabilities` 是当前版本的权威输出；其他类型需要运行中的 DBX Desktop bridge 或对应 Agent/外部驱动基础设施。
|
||
|
||
## 执行模式
|
||
|
||
### 本地存储
|
||
|
||
默认情况下 CLI 读取与 Desktop/MCP 相同的 `dbx.db` 连接存储。设置 `DBX_DATA_DIR` 时应指向包含 `dbx.db` 的目录。
|
||
|
||
- 原生直连类型可以在 Desktop 关闭时查询
|
||
- bridge 类型需要 Desktop 正在运行，并能从数据目录中的 bridge 端口文件发现本地服务
|
||
- Agent/JDBC、DuckDB 和其它外部驱动路径仍需要在 DBX 中安装匹配组件
|
||
- `dbx open` 始终是 Desktop UI 操作，Desktop 未运行时返回 `DBX_NOT_RUNNING`
|
||
|
||
### DBX Web / Docker
|
||
|
||
设置 `DBX_WEB_URL` 后，CLI 改为使用部署的 DBX Web 后端，而不是读取本机连接存储：
|
||
|
||
```bash
|
||
DBX_WEB_URL=https://dbx.example.com \
|
||
DBX_WEB_PASSWORD='your-login-password' \
|
||
dbx connections list --json
|
||
```
|
||
|
||
`DBX_WEB_PASSWORD` 是 Web 登录密码。Web 模式中的连接、权限、驱动和文件路径都属于服务器环境；`dbx open` 仍需要本机 Desktop bridge，不应作为远程 Web 自动化入口。
|
||
|
||
## 默认连接
|
||
|
||
设置 `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 连接执行一条 SQL，对 MongoDB 连接接受受支持的 Mongo shell 命令。Redis 不通过这个命令执行，需使用 MCP Redis 工具或 DBX 专用工作区。默认只读。
|
||
|
||
```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`。显式事务语句仍会被 CLI 阻止；需要多步固定 Session 时使用 [MCP 有状态会话](/cn/docs/mcp#有状态查询会话) 或 DBX 编辑器。
|
||
|
||
生产数据库上的写入和 DDL 即使传入两个允许参数也会被阻止。CLI 使用连接/数据库生产识别、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'
|
||
```
|
||
|
||
<Callout type="info">测试系统级 `dbx://` 唤起前，请先安装并启动一次 DBX 桌面端，让系统注册 URL 协议。macOS 可使用 `open 'dbx://connection/new?...'` 测试。</Callout>
|
||
|
||
## Codex
|
||
|
||
Codex 可以直接通过 shell 调用 CLI：
|
||
|
||
```bash
|
||
dbx schema describe local users --json
|
||
dbx context local --tables users,orders | codex exec "Write a retention query"
|
||
```
|