DBCrust

A fast psql-style database workbench for your terminal. One CLI for PostgreSQL, MySQL, SQLite, ClickHouse, MongoDB, Elasticsearch, Docker databases, Vault-backed connections, and SQL over Parquet/CSV/JSON files — with optional AI, Django ORM analysis, Python bindings, and a desktop GUI.

curl -fsSL https://clement-tourriere.github.io/dbcrust/install.sh | sh
dbc postgres://user:pass@localhost/mydb

AI is optional and disabled by default. DBCrust works with zero AI setup. ?? sends schema metadata and your question, not row data; ??? and Django AI investigations can inspect bounded query results. Generated SQL is shown before execution.

Documentation · Quick start · AI/privacy · Django analyzer · Python API

Why DBCrust

• One workflow across databases — the same REPL, commands, and muscle memory across PostgreSQL, MySQL, SQLite, ClickHouse, MongoDB, and Elasticsearch.
• Files are databases too — inspect Parquet, CSV, and JSON with SQL via Apache DataFusion, no import step or notebook required.
• Optional AI you control — type ?? top 10 customers by revenue to generate SQL from schema context, or use ??? for bounded read-only investigations. Supports Anthropic, OpenAI, Gemini, Ollama, and 20+ other providers.
• DBCrust for Django — catch N+1 queries, missing select_related / prefetch_related, slow views, and index opportunities before production.
• Production-friendly plumbing — SSH tunnels (with auto-tunnel patterns), HashiCorp Vault dynamic credentials, Docker container auto-discovery, encrypted password storage.
• A REPL that helps — context-aware autocompletion, syntax highlighting, history search, external editor, EXPLAIN visualization (including an interactive TUI), named queries, saved sessions.
• Scriptable, embeddable, agent-ready — -c/-f/stdin one-shots with -o json|csv output, stable exit codes, a --read-only guard, and a Python API powered by the same Rust core.

Install

# Pre-built binary — macOS & Linux
curl -fsSL https://clement-tourriere.github.io/dbcrust/install.sh | sh

# Pre-built binary — Windows (PowerShell)
irm https://clement-tourriere.github.io/dbcrust/install.ps1 | iex

# Python 3.10+ (ships the same native binary)
uv tool install dbcrust          # or: pipx install dbcrust / pip install dbcrust
uvx dbcrust <url>                # run without installing

# From source (Rust 1.85+)
cargo install --path .

Two binaries are installed: dbcrust and the short alias dbc.

dbcrust --update                 # self-update (detects uv / pipx / pip / cargo / binary installs)
dbcrust --completions zsh        # shell completions (bash, zsh, fish, powershell, ...)

Quick start

dbcrust postgres://user:pass@localhost/mydb     # interactive session
dbcrust recent://                               # pick from recent connections
dbc ./users.csv                                 # infer CSV from the extension
dbcrust sqlite:///path/to/db.sqlite -c "SELECT count(*) FROM users"   # run and exit

Every connection type is a URL:

Full details: URL schemes reference.

Built for AI agents

Coding agents work best with CLIs they can shell out to — no MCP server to run, no per-tool token overhead, composable with pipes and exit codes. DBCrust's one-shot mode gives them one binary for every data service:

dbcrust session://prod -c '\ddl'                            # whole schema as compact DDL, one call
dbcrust session://prod --read-only --no-input -o json \
  -c "SELECT status, count(*) FROM orders GROUP BY status"  # single-line {"columns","rows",...} envelope
echo "SELECT count(*) FROM logs" | dbcrust ./logs.parquet   # stdin scripts; files are databases too

The contract is built for programmatic callers: results-only stdout (status goes to stderr, the pager never engages), JSON errors on stderr under -o json, stable exit codes (0 ok · 1 SQL error · 2 usage · 3 connection · 4 blocked by --read-only), --timeout/--max-rows limits, and --no-input so no prompt can ever hang an agent. The binary documents itself: run dbcrust agents for the full ~100-line contract, and paste the ready-made snippet into your project's CLAUDE.md/AGENTS.md from the agent quickstart.

--read-only is a best-effort statement guard backed by connect-level hardening (SQLite query_only, PostgreSQL default_transaction_read_only); for hard guarantees use a read-only database role — details in safety & guardrails.

SQL over local files

Inspect production exports, logs, and data drops without importing them into a database or opening a notebook.

dbc warehouse/events.parquet      # inferred from extension
dbc 'logs/*.csv?header=true'      # globs work too
dbc file://                       # interactive compatible-file picker
dbc json:///tmp/api-responses.ndjson

SELECT date_trunc('hour', ts) AS hour, count(*)
FROM events
WHERE level = 'ERROR'
GROUP BY hour
ORDER BY hour DESC;

DBCrust registers matching files as SQL tables and lets DataFusion handle filtering, aggregations, joins, nested JSON fields, and glob patterns. See the file formats guide.

The interactive session

Connecting drops you into a REPL with context-aware SQL autocompletion, syntax highlighting, searchable history, and 60+ psql-style backslash commands. The most used:

Named queries support positional parameters ($1, $*, $@) and scopes — global, per-database-type, or session-local.

See the full command reference.

AI assistant

Turn natural language into SQL without leaving your session. The assistant uses your database's real schema as context, streams its answer, and always shows the SQL before running it (writes default to "No").

\ai setup                                        -- one-time wizard: provider, model, API key

?? top 10 customers by total order value this year
?? now only the active ones                      -- follow-ups keep conversation context

• Providers: Anthropic, OpenAI, Gemini, Ollama, Groq, DeepSeek, xAI, OpenRouter, and more — 25+ via genai, including any OpenAI-compatible endpoint for self-hosted models.
• Privacy controls: AI is opt-in. ?? sends schema metadata and your prompt/history; query results stay local. ??? and Django "Investigate with AI" can send bounded result rows, query plans, captured SQL, and source context. API keys live in your OS keychain, an encrypted file, or environment variables.

More in the AI assistant guide and privacy notes.

Tunnels, Vault & Docker

SSH tunneling — reach databases behind a jump host, explicitly or automatically via config patterns:

dbcrust postgres://user@db.internal/app --ssh-tunnel jumphost.example.com

# ~/.config/dbcrust/config.toml — auto-tunnel any host matching the pattern
[ssh_tunnel_patterns]
"^db\\.internal\\..*\\.com$" = "user@jumphost.example.com:2222"

HashiCorp Vault — dynamic database credentials with an encrypted local cache: dbcrust vault://readonly@database/postgres-prod.

Docker — dbcrust docker:// lists running database containers and connects without you hunting for ports or credentials.

Python API & DBCrust for Django

The Python package wraps the same Rust core via PyO3 — identical URLs, commands, and behavior.

import dbcrust

dbcrust.run_command("postgres://user:pass@localhost/mydb", "SELECT * FROM users LIMIT 5")
dbcrust.run_cli("postgres://user:pass@localhost/mydb")     # full interactive REPL

from dbcrust import PostgresClient
client = PostgresClient(host="localhost", user="postgres", dbname="myapp")
tables = client.list_tables()

DBCrust for Django catches ORM performance bugs before production: N+1 queries, duplicate queries, missing select_related / prefetch_related, slow views, and index opportunities, with recommendations tied back to code locations.

# settings.py
MIDDLEWARE = ["dbcrust.django.PerformanceAnalysisMiddleware", ...]

# or analyze a block of code explicitly
from dbcrust.django import analyzer
with analyzer.analyze() as analysis:
    for book in Book.objects.all():
        print(book.author.name)        # N+1 detected
results = analysis.get_results()

python manage.py dbcrust               # connect using your Django DB settings

Guides: Python API · Django analyzer.

Desktop GUI

A Tauri-based desktop app ships in the repo (built from source for now): CodeMirror SQL editor, schema explorer, visual EXPLAIN viewer, Docker discovery, multi-tab queries, and a system tray. See the GUI guide.

mise install && mise run gui:install
mise run gui:dev                       # development (hot-reload)
mise run gui:build                     # production .app / .dmg / .msi

Configuration

Settings live in ~/.config/dbcrust/ by default (override with DBCRUST_CONFIG_DIR=/path/to/dbcrust-config-dir), with user data kept in dedicated files:

Edit configuration interactively or from scripts — no connection required:

dbcrust config                         # interactive menu (also \config inside the REPL)
dbcrust config get logging.level
dbcrust config set logging.level debug
dbcrust config edit                    # open config.toml in $EDITOR

Full list of options: configuration reference.

Development

DBCrust uses mise for toolchain and task management — mise install sets up everything (Bun for the GUI, commitizen, etc.).

mise run build:dev        # debug build          mise run build      # release build
mise run test             # cargo test           mise run check      # fmt + lint + test
mise run py:dev           # maturin develop      mise run py:test    # Python tests
mise run gui:dev          # GUI with hot-reload  mise run docs       # docs dev server

src/                Rust core — CLI, REPL, database backends, AI assistant
├── commands.rs     backslash command system (enum + strum)
├── database_*.rs   per-database implementations
└── explain_tui/    interactive EXPLAIN visualizer (ratatui)
gui/                Tauri desktop app (React + TypeScript, Bun)
python/             Python bindings (PyO3 + maturin) and Django integration
docs/               documentation site (Astro Starlight)

More in the development guide.

License

MIT — see LICENSE.