Quick Start¶
Get up and running with DBCrust in under 2 minutes! This guide will have you querying databases like a pro in no time.
🚀 Installation¶
The fastest way to install DBCrust as a standalone binary:
Unix (macOS, Linux):
Windows:
Then use immediately:
The fastest way to try DBCrust without any setup:
Or install globally for repeated use:
🔌 First Connection¶
DBCrust supports 8 different URL schemes with intelligent shell autocompletion. Type a partial scheme and press TAB for suggestions:
# Standard connection (both schemes work)
dbcrust postgres://username:password@localhost:5432/database_name
dbcrust postgres://username:password@localhost:5432/database_name
# With SSL (recommended)
dbcrust postgres://username:password@localhost:5432/database_name?sslmode=require
# Short alias with autocompletion
dbc pos[TAB] → postgres://
🎯 Essential Commands¶
Once connected, you'll see the DBCrust prompt. Here are the commands you'll use most:
Database Navigation¶
-- List all databases
\l
-- Switch to a different database
\c production_db
-- List tables in current database
\dt
-- Describe a specific table
\d users
Query Basics¶
-- Simple query
SELECT * FROM users LIMIT 5;
-- With autocompletion (press TAB)
SELECT id, na[TAB] FROM us[TAB] WHERE st[TAB] = 'active';
↓ ↓ ↓
name users status
Display Options¶
-- Toggle expanded display for wide tables
\x
-- Toggle EXPLAIN mode to see query plans
\e
-- Now all queries show execution plans automatically
SELECT * FROM users WHERE email = 'john@example.com';
💡 Power Features in 30 Seconds¶
1. Query Visualization¶
Enable EXPLAIN mode to see how your queries perform:
\e -- Enable EXPLAIN mode
SELECT u.name, COUNT(o.id) as orders
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.name;
Output:
○ Execution Time: 2.34 ms • Planning Time: 0.45 ms
Hash Join
│ Combines users and orders using hash table
│ ○ Duration: 1.89 ms • Cost: 156 • Rows: 42
│ Hash Cond: (u.id = o.user_id)
├─ Seq Scan on users u
│ │ ○ Duration: 0.23 ms • Cost: 12 • Rows: 42
└─ Hash on orders o
│ ○ Duration: 0.34 ms • Cost: 89 • Rows: 234
└─ Seq Scan on orders o
│ ○ Duration: 0.19 ms • Cost: 67 • Rows: 234
2. Named Queries¶
Save frequently used queries:
-- Save a query with parameters
\ns daily_active SELECT * FROM users WHERE last_login >= current_date - interval '$1 days';
-- Use it later
daily_active 7 -- Shows users active in last 7 days
daily_active 30 -- Shows users active in last 30 days
-- List all saved queries
\n
3. External Editor¶
For complex queries, use your favorite editor:
-- Opens query in $EDITOR (vim, nano, vscode, etc.)
\ed
-- Edit, save, and close - query runs automatically
4. File Operations¶
-- Save last query to file
\w my_query.sql
-- Load and execute a SQL file
\i scripts/monthly_report.sql
🚀 Shell Autocompletion Setup¶
Enable intelligent shell autocompletion for URL schemes and contextual suggestions:
# Create completions directory if it doesn't exist
mkdir -p ~/.zfunc
# Install completion scripts for both binaries
dbcrust --completions zsh > ~/.zfunc/_dbcrust
dbc --completions zsh > ~/.zfunc/_dbc
# Add these lines to your .zshrc (before oh-my-zsh if you use it):
fpath+=~/.zfunc
autoload -U compinit && compinit
# If you use oh-my-zsh, make sure these lines come BEFORE:
# source $ZSH/oh-my-zsh.sh
# Reload your shell
source ~/.zshrc
Smart Completions
Once set up, autocompletion provides: - URL schemes: dbc doc[TAB] → docker:// - Container names: dbc docker://post[TAB] → docker://postgres-dev - Session names: dbc session://prod[TAB] → session://production_db
🔧 Quick Configuration¶
DBCrust works great out of the box, but you can customize it:
Common settings:
[database]
default_limit = 1000
expanded_display_default = false
[ssh_tunnel_patterns]
"^db\\.internal\\..*\\.com$" = "jumphost.example.com"
[vault]
addr = "https://vault.company.com"
🐍 Python Integration¶
DBCrust isn't just a CLI - it's also a powerful Python library:
import dbcrust
# Execute a query and get results
result = dbcrust.run_command(
"postgres://user:pass@localhost/mydb",
"SELECT COUNT(*) FROM orders WHERE created_at >= current_date"
)
print(result)
# Launch interactive CLI from Python
dbcrust.run_cli("postgres://user:pass@localhost/mydb")
Django ORM Performance Analysis¶
For Django developers, DBCrust includes a powerful ORM analyzer:
from dbcrust.django import analyzer
# Detect N+1 queries and optimization opportunities
with analyzer.analyze() as analysis:
books = Book.objects.all()
for book in books:
print(book.author.name) # Will detect N+1 query
results = analysis.get_results()
print(results.summary) # Shows performance insights
Perfect for catching performance issues during development!
Learn more about Django ORM Analysis →
📚 What's Next?¶
Now that you're up and running:
- Django ORM Analyzer - Performance analysis for Django applications
- URL Schemes & Autocompletion - Master all connection methods
- Installation Guide - Detailed installation options
- User Guide - Complete feature walkthrough
- Python API - Integration with your Python projects
🆘 Common Issues¶
Connection refused?
Make sure your database is running and accessible:
Permission denied?
Check your credentials and database permissions:
SSL/TLS issues?
Try disabling SSL first to test basic connectivity: