194 lines
6.7 KiB
Plaintext
194 lines
6.7 KiB
Plaintext
---
|
|
title: DBX CLI
|
|
description: Use DBX connections from terminals, scripts, CI, and Codex.
|
|
---
|
|
|
|
<Callout type="info">DBX CLI is a dedicated command line package for terminal, script, and coding-agent workflows. It shares DBX connection storage and SQL safety rules with the MCP server.</Callout>
|
|
|
|
## Install
|
|
|
|
### npm
|
|
|
|
```bash
|
|
npm install -g @dbx-app/cli
|
|
```
|
|
|
|
### Homebrew
|
|
|
|
```bash
|
|
brew tap t8y2/dbx
|
|
brew install dbx-cli
|
|
```
|
|
|
|
Node.js 18.18.0 or newer is required for the npm launcher. The CLI itself does not depend on `better-sqlite3` or a Node.js native-module ABI. Homebrew users do not need to manage Node.js separately.
|
|
|
|
### Standalone native binary
|
|
|
|
The `packages-v*` GitHub Release provides native CLI archives for macOS, Linux, and Windows. Download the archive matching your platform, verify it with `CLI-SHA256SUMS`, extract it, and run `dbx` directly. Standalone binaries do not require Node.js.
|
|
|
|
```bash
|
|
tar -xzf dbx-cli-linux-x64-gnu.tar.gz
|
|
chmod +x dbx
|
|
./dbx --version
|
|
```
|
|
|
|
Set `DBX_DATA_DIR` when using a custom or portable DBX data directory.
|
|
|
|
Check the installed version:
|
|
|
|
```bash
|
|
dbx --version
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
```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
|
|
```
|
|
|
|
## Diagnostics
|
|
|
|
Use `dbx doctor` to inspect local DBX paths, connection-store health, and whether the desktop bridge is available:
|
|
|
|
```bash
|
|
dbx doctor
|
|
dbx doctor --json
|
|
```
|
|
|
|
If the optional platform package was not installed, reinstall without `--no-optional`:
|
|
|
|
```bash
|
|
npm uninstall -g @dbx-app/cli
|
|
npm install -g @dbx-app/cli
|
|
```
|
|
|
|
Use `dbx capabilities` to see which database types can be queried directly and which currently require DBX Desktop:
|
|
|
|
```bash
|
|
dbx capabilities
|
|
dbx capabilities --json
|
|
```
|
|
|
|
Direct execution currently supports PostgreSQL/Redshift, MySQL-compatible databases (MySQL, Doris, StarRocks), and SQLite. Other database types use the DBX Desktop bridge or DBX Agent/JDBC infrastructure.
|
|
|
|
## Default Connection
|
|
|
|
Set `DBX_CONNECTION` to omit the connection name for query and context commands:
|
|
|
|
```bash
|
|
DBX_CONNECTION=local dbx query "select 1" --json
|
|
DBX_CONNECTION=local dbx context --tables users,orders
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
Use `--json` or `--format json` for stable machine-readable output. Use `--format csv` for query, connection, and schema data that should be piped into other command line tools.
|
|
|
|
```bash
|
|
dbx query local "select id, name from users" --format csv
|
|
```
|
|
|
|
Errors are written to stderr and return a non-zero exit code.
|
|
|
|
## Query Controls
|
|
|
|
`dbx query` executes one SQL statement. It is read-only by default.
|
|
|
|
```bash
|
|
dbx query local "select * from users" --limit 50 --timeout 10s --json
|
|
```
|
|
|
|
Durations accept `ms`, `s`, or `m`, such as `500ms`, `10s`, or `1m`.
|
|
|
|
Use `--allow-writes` for non-dangerous write statements:
|
|
|
|
```bash
|
|
dbx query local "update users set name = 'Ada' where id = 1" --allow-writes
|
|
```
|
|
|
|
Dangerous SQL such as `DROP`, `TRUNCATE`, and `ALTER` requires both `--allow-writes` and `--allow-dangerous-sql`.
|
|
|
|
## SQL Starting With a Dash
|
|
|
|
Pass `--` before SQL that starts with a dash:
|
|
|
|
```bash
|
|
dbx query local --json -- "-- comment
|
|
select 1"
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
CLI JSON errors use stable codes:
|
|
|
|
| Code | Meaning |
|
|
| ------------------------ | --------------------------------------------------- |
|
|
| `UNKNOWN_OPTION` | An unsupported flag was provided |
|
|
| `INVALID_OPTION` | A flag is missing a value or has an invalid value |
|
|
| `INVALID_ARGUMENT` | Positional arguments are missing or conflicting |
|
|
| `CONNECTION_STORE_ERROR` | DBX connection storage exists but could not be read |
|
|
| `CONNECTION_NOT_FOUND` | No DBX connection matched the requested name |
|
|
| `SQL_BLOCKED` | SQL safety rules blocked execution |
|
|
| `DBX_NOT_RUNNING` | DBX Desktop bridge is unavailable |
|
|
| `ERROR` | Unexpected runtime failure |
|
|
|
|
## Desktop Deep Links
|
|
|
|
DBX Desktop supports `dbx://connection/new` links for opening the new connection dialog from browsers, bastion hosts, or scripts with connection fields prefilled.
|
|
|
|
DSN mode:
|
|
|
|
```bash
|
|
open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders'
|
|
```
|
|
|
|
Field mode:
|
|
|
|
```bash
|
|
open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test'
|
|
```
|
|
|
|
Supported fields:
|
|
|
|
| Field | Meaning |
|
|
| ------------ | ---------------------------------------------------------------------------------------- |
|
|
| `type` | Database type, such as `mysql`, `postgres`, `redis`, or `mongodb` |
|
|
| `url` | Database DSN; URL encoding is recommended |
|
|
| `name` | Display name in DBX; when omitted, DBX uses `database`, then `host` |
|
|
| `host` | Hostname or IP address |
|
|
| `port` | Port |
|
|
| `user` | Username |
|
|
| `password` | Password |
|
|
| `database` | Database name; for Redis this can be a DB index such as `0` |
|
|
| `url_params` | Extra connection parameters, such as `sslmode=require` |
|
|
| `ssl` | Enable SSL when set to `true` |
|
|
| `one_time` | Automatically connect when set to `true`, then delete the connection after disconnecting |
|
|
|
|
One-time connection example:
|
|
|
|
```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">Before testing system-level `dbx://` launches, install and open DBX Desktop once so the operating system can register the URL scheme. On macOS, use `open 'dbx://connection/new?...'` to test it.</Callout>
|
|
|
|
## Codex
|
|
|
|
Codex can call the CLI directly from shell tools:
|
|
|
|
```bash
|
|
dbx schema describe local users --json
|
|
dbx context local --tables users,orders | codex exec "Write a retention query"
|
|
```
|