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 Aug 24, 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 Aug 24, 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.0-cp310-abi3-win_amd64.whl (14.3 MB view details)

Uploaded CPython 3.10+Windows x86-64

dbcrust-0.37.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.37.0-cp310-abi3-musllinux_1_2_aarch64.whl (18.4 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

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

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

dbcrust-0.37.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.37.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.37.0-cp310-abi3-macosx_11_0_arm64.whl (15.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

dbcrust-0.37.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.37.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: dbcrust-0.37.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/7.0.0 CPython/3.13.14

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6ba137a0e66a800ffbe4f5d6d59f3dece829e71ffe1c492fd4edd4f5a226b0bb
MD5 78dda206c477499001787d54d1d0e512
BLAKE2b-256 0caf04abf88e8c1ce7be96ba44ac78f68dd8d195cf89ee254065d5e134851c7b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 38999311e859ffa01ed1d1f379902b514df4ba65a877ab731d32cc1c6a1a3b4b
MD5 2c3521b7cf876507e70eccbdb82ac790
BLAKE2b-256 efb8741a91cbd6873aed82a68748ab4e813080c5c7e5b42246a9f2d511495f54

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a24993cef375ebe5372f9c3bcb8fe7fc371f3f484044c2092a50340d2edfb9f3
MD5 e69aaeb52d1258f3725a007c1a449bb9
BLAKE2b-256 32bbefdf481ee368687a7788a1de766d50e181db31868e36ae7777441a6bfcc2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 082863401a8ddd2ea0250f4c57532192b4c2b0ce72b91ecfbb543bfbac415491
MD5 88eb289e808719ad18ce47265189f13b
BLAKE2b-256 cf22f0565c66020ca847344504d561bb7b27551a36d0537e647c43cb0dd475cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 12b91308aa874ce279287f458c50bb3e1c8571e264fd6becf37ededbeaaa8533
MD5 c7f2ecb52e6468cb971dd0fae781a9d1
BLAKE2b-256 5236bd77f32efe186d8a7423a6427d4266ce108a929d04a239e7c1de84b2134d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 6bd58349f8ccd4da25fcc271aa07e1c85dd5b2feef04139b33e1815bd2804a76
MD5 b1fb2c8cd1555a66897208c68d9b3b2f
BLAKE2b-256 048c2901bd9f9aca1f98656bffa0daeca2681e2a7a7fae35fc3edb51b9a87140

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d30816fffe6286c4a9ce06ac464f79ceaf5be1dac4fcab787bbfa8776c2f6305
MD5 3ecd1ee8555e53752d38bc1343a2a5f6
BLAKE2b-256 8ac53cbd8b0957dda423973ce398880f655dec2fed801b9f1de2f1c58ff8fece

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for dbcrust-0.37.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 5f6359be14ffdf70dfa4e33a308933586b1193b48469c3ebbb89d147e04dc1bf
MD5 861b9d5f55ed3b6a004a1ba8e82cadb0
BLAKE2b-256 e3c0674a8894e5d38010d183dd922eec869d0acf8c35ecc74f47348beeeefff0

See more details on using hashes here.

Provenance

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

This release

0.37.0 This release

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