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 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.

Project links

Data verified by PyPI on Jul 27, 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:
Newer release available (0.37.0)

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 Jul 27, 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.36.0-cp310-abi3-win_amd64.whl (14.3 MB view details)

Uploaded CPython 3.10+Windows x86-64

dbcrust-0.36.0-cp310-abi3-musllinux_1_2_x86_64.whl (18.4 MB view details)

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

dbcrust-0.36.0-cp310-abi3-musllinux_1_2_aarch64.whl (18.4 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

dbcrust-0.36.0-cp310-abi3-manylinux_2_28_aarch64.whl (18.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

dbcrust-0.36.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.6 MB view details)

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

dbcrust-0.36.0-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl (18.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ i686

dbcrust-0.36.0-cp310-abi3-macosx_11_0_arm64.whl (15.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

dbcrust-0.36.0-cp310-abi3-macosx_10_12_x86_64.whl (14.6 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c04471db5d7d645febca1d1f880b597bdee5774722e33fe33d3dc36b5d0d0570
MD5 9c0531696fb7da3cebed0f0c6c49373e
BLAKE2b-256 064a2984e2d0c9eaac6d3cb49b63e46a9fb873eed99665be916f0f5e5e1a9423

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4c87a9e4f899036e2364e32f62173d90a5343546bca31ef6c2bd0685fe59229e
MD5 5afd2623062ba3934d76d045cc06ea5e
BLAKE2b-256 2f67a8585f665cf71717e3b757f5b335476f41b13b6c4235122b38a6c826232d

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 6aa6071d388399a417a3404ac5aed6452fe0ce88bb763f248ed85141e78fe679
MD5 9de02074414c924c981dbcd60f99a4d1
BLAKE2b-256 3d6a12573f01a5917d4f914db235ff80fce42a5a016f4bd325ab1764cc8348f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 861fc52fc5e18820c29f659d920effcacf91cef65dd5ff217404b7c36de85c35
MD5 b962bf28fd0d8056c79778da021ce099
BLAKE2b-256 b1958bcad7a0460ff412a697ecd147307eb59a9b1a54aefd2d20225f1811e510

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6ff578aec8cc73456778d101a6b2fb0643173ab1519ddae3fce5716cfe2d1f18
MD5 ceb96c1790ef0b4ff7b85328bbf63c12
BLAKE2b-256 dd035b0fbd0c8343305431c066b4c2c354be37dc0207fdcbf0efd268569faa88

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 85051ff52e675a8d20ea637076bb66c80dd47139e117948d634d80474c5fc25f
MD5 0f0acae88b9be5afa459a147154db9b4
BLAKE2b-256 9cb7c83ef7a8d70580dd604eff0909f4bab5cb8084c68aa4896b51a62db2c16e

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e257fcc869964a9d0c652094cb663deb8580f65406901c7a43ab490dfbc1aef2
MD5 1f5b19e1f2607eef4522970051513bd3
BLAKE2b-256 ee7c9ae93b060dda45f34f5d3ffcf81f984d78ec27c160dfb1a619e852fe17ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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.36.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for dbcrust-0.36.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0884c53cb7ac88448a84f589ab90b075a310c4e35871b6e9270dc38d4dea5769
MD5 36cbaa2b3c8f581362fbdc7cc4eec809
BLAKE2b-256 5e686dadbc8217ad625cce7f8525ff2e505040f3145dd0c68cd1e1d4929e7dcb

See more details on using hashes here.

Provenance

The following attestation bundles were made for dbcrust-0.36.0-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

0.37.0

8 files

This release

0.36.0 This release

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