How to Use DBX CLI for Schema Inspection and Query Execution: A Complete Guide

The DBX CLI provides terminal-based commands for exploring database schemas and executing read-only SQL queries, offering output in Markdown tables, JSON, or CSV formats through a Node.js wrapper architecture.

The DBX CLI (available in the t8y2/dbx repository) is a thin Node.js wrapper around the @dbx-app/node-core backend that enables developers to inspect database structures and run queries directly from the command line. Whether you need to quickly list tables in a connection, examine column metadata, or validate SQL scripts, the CLI provides a streamlined interface that automatically handles driver detection, safety validation, and formatted output rendering.

Understanding the DBX CLI Architecture

The CLI implementation in packages/cli/src/cli.ts follows a three-stage pipeline that transforms raw command-line arguments into executed database operations:

• Argument parsing – The parseFlags function (lines 37-74) processes process.argv into a structured ParsedFlags object, extracting connection names, SQL statements, and formatting options.
• Backend initialization – The createBackend function imported from @dbx-app/node-core (lines 61-63) instantiates a driver-aware backend capable of direct database communication or proxying through the DBX Desktop bridge.
• Command dispatch – Lines 64-126 route parsed commands to specific handlers for schema, query, context, and other sub-commands, each resolving connections via backend.findConnection before invoking database methods.

Schema Inspection Commands

Schema exploration relies on two primary commands that interface directly with the backend's metadata methods.

Listing Tables and Views

The dbx schema list <connection> command retrieves all tables and views available in the specified connection:

dbx schema list production --json

Internally, this resolves the connection configuration through backend.findConnection (lines 39-43 in cli.ts), then invokes backend.listTables (lines 27-33). Results render as a Markdown table by default, or as JSON or CSV when using the --json or --format csv flags.

Describing Table Structure

To inspect column-level metadata—including data types, nullability constraints, defaults, and comments—use the describe command:

dbx schema describe production users --format csv

This executes backend.describeTable and formats output through the mdTable helper in packages/cli/src/cli-format.ts, with the same format overrides available as the list command.

Query Execution Workflow

The dbx query command enables read-only SQL execution with built-in safety mechanisms and flexible input methods.

SQL Safety Evaluation

Before executing any statement, the CLI invokes evaluateSqlSafety (lines 68-76 in cli.ts) to validate the query against configured safety flags:

• allowWrites – Blocks or permits data modification statements
• allowDangerous – Controls execution of potentially destructive operations

These checks respect environment defaults or explicit runtime flags.

Running Queries from Files

For complex multi-line statements, the --file parameter reads SQL from disk rather than inline strings:

dbx query analytics --file ./scripts/monthly_report.sql --limit 1000 --timeout 30s

The backend.executeQuery method (lines 78-84) processes the statement with optional --limit (row restriction) and --timeout (duration limits) controls. Results output as formatted tables, CSV, or raw JSON depending on the --format specification.

Output Formatting Options

Both schema and query commands support three output modes controlled via flags:

• Markdown tables – Default human-readable format using the mdTable utility in packages/cli/src/cli-format.ts
• JSON – Machine-parseable structures via --json
• CSV – Spreadsheet-compatible text via --format csv

This flexibility allows the CLI to serve both interactive exploration and automated data pipeline integration.

Integration with DBX Desktop

For database drivers requiring the DBX Desktop bridge (such as JDBC connections), the CLI automatically forwards requests via HTTP using postBridge (lines 212-218 in cli.ts). The doctor command verifies bridge availability and connection health:

dbx doctor

To open a specific table directly in the DBX Desktop UI:

dbx open local users

This requires an active bridge connection and launches the graphical interface pre-filtered to the specified table.

Practical Examples

List all tables in a local connection with JSON output:

dbx schema list local --json

Describe table structure in CSV format for documentation:

dbx schema describe local users --format csv

Execute a parameterized query with safety limits:

dbx query local "SELECT id, name FROM users WHERE active = true" --limit 100 --timeout 5s --json

Generate schema context for AI prompting:

dbx context local --tables users,orders --json

Summary

• The DBX CLI in t8y2/dbx provides schema inspection via schema list and schema describe commands, utilizing backend.listTables and backend.describeTable from the core Node.js backend.
• Query execution requires dbx query and enforces safety through evaluateSqlSafety checks against allowWrites and allowDangerous flags.
• Output formatting supports Markdown tables (default), JSON (--json), and CSV (--format csv) through helpers in packages/cli/src/cli-format.ts.
• File-based execution uses --file <path> for complex SQL scripts, while connection resolution occurs through backend.findConnection.
• DBX Desktop integration handles non-direct drivers via postBridge, with the doctor command verifying bridge status.

Frequently Asked Questions

How does the DBX CLI resolve database connections?

The CLI resolves connections through backend.findConnection (lines 39-43 in packages/cli/src/cli.ts), which matches the provided connection name against configured profiles in the DBX backend. This method supports both direct database drivers and connections requiring the DBX Desktop bridge.

Can I execute INSERT or UPDATE statements with the DBX CLI?

No, the DBX CLI is designed for read-only operations. The evaluateSqlSafety function (lines 68-76) explicitly checks statements against allowWrites flags, blocking data modification commands unless explicitly overridden by environment configurations—providing a safeguard against accidental data changes.

What file formats does the DBX CLI support for SQL input?

The CLI accepts SQL via inline strings or external files using the --file <path> flag (lines 66-68). It reads standard .sql text files and passes their contents to backend.executeQuery, making it compatible with any UTF-8 encoded SQL script regardless of complexity or line length.

How do I troubleshoot connection issues with the DBX CLI?

Use the dbx doctor command to verify backend initialization and bridge availability. For drivers requiring the DBX Desktop application, ensure the HTTP bridge is accessible—the CLI uses postBridge (lines 212-218) to forward requests when direct driver connections are unavailable, and the doctor command reports specific connectivity failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}