DBCrust

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

CI PyPI Documentation License: MIT

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:

Scheme Example
PostgreSQL postgres://user:pass@localhost:5432/mydb?sslmode=require
MySQL mysql://root:pass@localhost:3306/mydb
SQLite sqlite:///path/to/db.sqlite or ./path/to/db.sqlite
ClickHouse clickhouse://user:pass@localhost:8123/default
MongoDB mongodb://user:pass@localhost:27017/mydb
Elasticsearch elasticsearch://localhost:9200
White Dragon white-dragon://localhost:7700
Parquet / CSV / JSON ./data.parquet · ./logs/app.csv · file:// picker · json:///events.json
Docker container docker:// (interactive picker) · docker://my-postgres/mydb
Saved session session://production_db
Recent connections recent://
Vault credentials vault://readonly@database/postgres-prod

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:

Commands
Explore \l databases · \c <db> switch · \dt tables · \d <table> describe · \ddl schema dump
Display \x expanded · \cs column selection · \e EXPLAIN mode · \ev interactive EXPLAIN TUI
Edit & run \ed open $EDITOR · \i <file> run SQL file · \w <file> write last query
Named queries \n list · \ns <name> <sql> save · \nd <name> delete
Connections \ss <name> save session · \s list sessions · \r recent · \docker containers
Credentials \savepass store password · \vc Vault cache status
Meta \ai AI assistant · \config settings editor · \h help · \q quit

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. An optional AWS-style vault_credential_process can obtain authentication lazily, so ordinary PostgreSQL/MySQL connections never start a Vault login flow. The helper is provider-neutral: any command that prints a token or JSON { "token": "…", "vault_addr": "…" } works.

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:

File Contents
config.toml App settings (display, limits, SSH patterns, AI, logging, ...)
sessions.toml Saved sessions
recent.toml Recent connections
named_queries.toml Named queries
vault_credentials.enc Encrypted Vault credential cache
~/.dbcrust Stored passwords (pgpass-style)

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 2026.8.16+ for toolchain and task management. mise install installs Bun, Commitizen, and Mr Boxington, which puts a shared, self-pruning cache behind Cargo commands run through mise.

mise install
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
mbx doctor                # verify the Rust build cache

With mise activated, plain cargo commands use the same cache. Set MBX_DISABLE=1 for a one-off uncached Cargo command.

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.

Project links

Data verified by PyPI on Sep 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ctourriere from gravatar.com ctourriere

Credits

Author: Clément Tourrière

GitHub Statistics

Data verified by PyPI on Sep 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

django

Tags

dbcrust database database-cli sql cli interactive repl postgres postgresql mysql sqlite clickhouse mongodb elasticsearch parquet csv json datafusion ssh-tunnel vault docker ai llm ai-agents coding-agents claude-code gui django orm python-library performance-analysis n-plus-one

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

dbcrust-0.37.2-cp310-abi3-win_amd64.whl (14.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

dbcrust-0.37.2-cp310-abi3-musllinux_1_2_x86_64.whl (18.1 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

dbcrust-0.37.2-cp310-abi3-musllinux_1_2_aarch64.whl (18.0 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

dbcrust-0.37.2-cp310-abi3-manylinux_2_28_aarch64.whl (17.8 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

dbcrust-0.37.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

dbcrust-0.37.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl (18.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ i686

dbcrust-0.37.2-cp310-abi3-macosx_11_0_arm64.whl (14.4 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

dbcrust-0.37.2-cp310-abi3-macosx_10_12_x86_64.whl (14.2 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file dbcrust-0.37.2-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: dbcrust-0.37.2-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 14.0 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 38a5c66a2f2bfef692f20c2d23d35cff675b3e24b1469d81e0fcf4a820a2521e
MD5 69e7a710f8f6a0cbfce068e2374f07e2
BLAKE2b-256 e6999d33539c0f9bb593b0e438af0303fd0df87a8f7113ce93b4f8341b76e98f

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-win_amd64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 1c42927e3c4dae9a07fb332f74eeccd1e1f1470e382dc0dfc3949ec6b2fcfadd
MD5 2b73711ea0490068e481003b0a292f5a
BLAKE2b-256 c28ad9874c71401f95c617acd1280d62c96504b87b9fcd0eed3a1e0998180877

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 7450e8001d0d1bbb873793bbb1996671e6431c3cfeb6c9f049ded5782b90758f
MD5 5de32ba506769f831444c03c09729510
BLAKE2b-256 b044a379ccfbbf609564dd3c32364c6787ba8659bfe3c7ba729ebc3c9541d26a

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 34dd3432260493a88f59563ef9e69af7e95895629e7e486182cf7b3821020582
MD5 1238c6babe51c129d9afd47e6979fb6d
BLAKE2b-256 d3ba8eac7b02435463e6ee6e7d3c2250c637c45d695e6cdb109a076cc6ab82d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e6ca2c351a5f272dfeef2ceca7b42da1a8467e9d8385853437e5ce29d364f68e
MD5 2d2102cbb4aedef2ee0026cd38bd2853
BLAKE2b-256 6345fa01f16f029dbd44830273dbc59716fabfbbae465c98b714b15f58e808bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 7a4e4d638f95df368e13404be819c247bed451d9552c89b60fb4e35954b07993
MD5 14fa548d1ec55c42b364850ac5a13c8a
BLAKE2b-256 84c71ca8458757b01659c3756a73ec7fbdcb2e8c67daa211975a9f07e3e25a16

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a911c8d21497f05b82c26d1289b82905175e0b278897459a7faf3883e25ee461
MD5 c74cdf9ceccd7510190064d8424bd88a
BLAKE2b-256 a9a7b2b878f32f297b930aaf5dcc31b2a657be57eff58314e02953d79ccd6c02

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dbcrust-0.37.2-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.37.2-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f2dd7a2f27659a8a8e5a36011db1cbdb90152cfed5fa128d517a5d3e50260fd3
MD5 f02669efbabe7e414c0761a0c6eb3315
BLAKE2b-256 02af39a995a9c41ab5ca36ac05431e00c1c299fb2c7a72292ff7ff340d2ced4c

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.37.2-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on clement-tourriere/dbcrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.37.2 This release

8 files

0.37.0

8 files

0.36.0

8 files

0.35.0

8 files

0.34.1

8 files

0.34.0

8 files

0.33.0

8 files

0.32.0

8 files

0.31.2

8 files

0.31.1

8 files

0.31.0

8 files

0.30.1

8 files

0.30.0

8 files

0.29.0

8 files

0.28.1

8 files

0.27.1

8 files

0.27.0

8 files

0.26.1

8 files

0.26.0

8 files

0.25.0

8 files

0.24.0

8 files

0.23.3

10 files

0.23.2

10 files

0.23.1

10 files

0.23.0

10 files

0.22.5

10 files

0.22.2

10 files

0.22.0

8 files

0.21.4

8 files

0.21.3

8 files

0.21.2

8 files

0.21.1

8 files

0.21.0

8 files

0.20.1

8 files

0.20.0

8 files

0.19.0

8 files

0.18.0

8 files

0.17.0

8 files

0.16.1

8 files

0.16.0

8 files

0.15.1

8 files

0.14.1

8 files

0.14.0

8 files

0.13.2

8 files

0.13.1

8 files

0.13.0

8 files

0.12.3

8 files

0.12.2

7 files

0.12.1

7 files

0.12.0

7 files

0.11.5

7 files

0.11.4

7 files

0.11.3

7 files

0.11.2

7 files

0.11.1

7 files

0.11.0

7 files

0.10.5

7 files

0.10.4

7 files

0.10.3

7 files

0.10.2

7 files

0.10.1

7 files

0.10.0

7 files

0.9.0

7 files

0.8.1

7 files

0.8.0

7 files

0.7.4

7 files

0.7.3

7 files

0.7.2

7 files

0.7.1

7 files

0.7.0

7 files

0.6.2

7 files

0.6.1

7 files

0.6.0

7 files

0.5.0

7 files

0.4.1

7 files

0.4.0

7 files

0.3.1

7 files

0.3.0

7 files

0.2.0

7 files

0.1.0

7 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page