dbx

DBX CLI

Prerequisite: DBX Desktop must be installed and configured with at least one connection. Run dbx doctor to verify setup. Install CLI: npm install -g @dbx-app/cli

Core Concepts

• Connection: A named database connection configured in DBX Desktop (e.g. "prod", "local"). Identified by name.
• Schema: Tables and views within a connection. Listed via dbx schema list.
• Query: Read-only SQL executed against a connection. Gated by --allow-writes and --allow-dangerous-sql.
• Context: Compact schema dump optimized for AI prompts — smaller and more focused than full schema output.

Resource Relationships

DBX Desktop
├── Connection (named)
│   ├── Schema (tables, views)
│   │   └── Table
│   │       └── Column (name, type, nullable, default)
│   └── Query (read-only by default)
└── Context (prompt-optimized schema dump)

Commands

⛔ NEVER bypass dbx CLI for database operations. If dbx returns SQL_BLOCKED or any error, do NOT use Python sqlite3, shell redirects, or any other tool to access the database directly. Always respect the CLI's safety gates. When in doubt, tell the user what the CLI returned and ask for their decision.

1. Check Setup

dbx doctor
dbx capabilities

Use doctor when the agent starts or when a command fails — it reveals whether the desktop bridge, connection DB, and native SQLite loader are available. Use capabilities to check which databases support direct execution vs require the desktop bridge.

2. List Connections

dbx connections list --json

Returns connections without exposing secrets. Parse JSON to present a clean list to the user. Always run this first before any schema or query operation — the user might not remember connection names.

3. Explore Schema

# List all tables in a connection
dbx schema list <connection> --json

# Describe a specific table
dbx schema describe <connection> <table> --json

Use schema list to survey what's available, then schema describe on specific tables the user asks about. Present column names, types, and nullability clearly.