Skip to content
DBCrust

Quick Start

Get connected in under 2 minutes.

Install

Section titled “Install”
Terminal window
curl -fsSL https://clement-tourriere.github.io/dbcrust/install.sh | sh

Both dbcrust and dbc (short alias) are available after installation.

See Installation for all options including shell completion setup.

First connection

Section titled “First connection”
Terminal window
dbcrust postgres://user:pass@localhost:5432/mydb

Tab-complete the URL scheme:

Terminal window
dbc pos[TAB]        → postgres://
dbc docker://[TAB]  → lists running containers
dbc session://[TAB] → lists saved sessions
Terminal window
dbcrust postgres://user:pass@localhost:5432/mydb

Essential commands

Section titled “Essential commands”

Once connected you get an interactive REPL:

Section titled “Navigate”
\l              -- list databases
\dt             -- list tables
\d users        -- describe table
\c other_db     -- switch database

Query

Section titled “Query”

SQL with tab-completion on table and column names:

SELECT id, na[TAB] FROM us[TAB] WHERE st[TAB] = 'active';
--           ↓          ↓            ↓
--          name       users        status

Display

Section titled “Display”
\x              -- toggle expanded (vertical) display
\e              -- toggle EXPLAIN mode (shows query plans)
\ev             -- interactive EXPLAIN TUI
\cs             -- toggle column selection for wide results

EXPLAIN visualization

Section titled “EXPLAIN visualization”
\e
SELECT u.name, COUNT(o.id) FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.name;
○ Execution Time: 2.34 ms • Planning Time: 0.45 ms


Hash Join
│ ○ Duration: 1.89 ms • Cost: 156 • Rows: 42
│   Hash Cond: (u.id = o.user_id)
├─ Seq Scan on users u
│  │ ○ Duration: 0.23 ms • Rows: 42
└─ Hash → Seq Scan on orders o
   │ ○ Duration: 0.34 ms • Rows: 234

Save and reuse

Section titled “Save and reuse”
-- Named queries with parameters
\ns daily SELECT * FROM orders WHERE created_at >= current_date - interval '$1 days'
daily 7


-- Sessions
\ss production_db
\s


-- Files
\w query.sql
\i setup.sql
\ed                -- open $EDITOR

Help

Section titled “Help”
\h              -- show all commands
\q              -- quit

Desktop GUI

Section titled “Desktop GUI”
Terminal window
mise install && mise run gui:dev

See Desktop GUI for the full guide.

Shell completion

Section titled “Shell completion”
Terminal window
dbcrust --completions bash > ~/.local/share/bash-completion/completions/dbcrust

What’s next

Section titled “What’s next”