Backslash Commands Reference¶

DBCrust provides a comprehensive set of backslash commands (meta-commands) that help you navigate and manage your database sessions efficiently. These commands are inspired by PostgreSQL's psql but enhanced with modern features.

📚 Command Categories¶

Navigation & InfoDisplay & OutputFile OperationsNamed QueriesSessions & HistoryVault ManagementHelp & Control

Command	Description	Example
`\l`	List databases	`\l`
`\dt`	List tables	`\dt`
`\d [table]`	Describe table or list all tables	`\d users`
`\c <database>`	Connect to database	`\c production`
`\config`	Show current configuration	`\config`

Command	Description	Example
`\x`	Toggle expanded display	`\x`
`\e`	Toggle EXPLAIN mode	`\e`
`\ecopy`	Copy last EXPLAIN to clipboard	`\ecopy`
`\cs`	Toggle column selection mode	`\cs`
`\csthreshold <n>`	Set column selection threshold	`\csthreshold 15`
`\clrcs`	Clear saved column selections	`\clrcs`
`\resetview`	Reset all view settings	`\resetview`

Command	Description	Example
`\w <file>`	Write last script to file	`\w query.sql`
`\i <file>`	Execute SQL file	`\i setup.sql`
`\ed`	Edit query in external editor	`\ed`

Command	Description	Example
`\n`	List named queries	`\n`
`\ns <name> <query>`	Save named query	`\ns users SELECT * FROM users`
`\nd <name>`	Delete named query	`\nd users`

Command	Description	Example
`\s [name]`	List saved sessions or connect	`\s` or `\s prod`
`\ss <name>`	Save current connection as session	`\ss production`
`\sd <name>`	Delete saved session	`\sd oldprod`
`\r`	List recent connections	`\r`
`\rc`	Clear recent connections	`\rc`

Command	Description	Example
`\vc`	Show vault credential cache status	`\vc`
`\vcc`	Clear all cached vault credentials	`\vcc`
`\vcr [role]`	Force refresh vault credentials	`\vcr` or `\vcr my-role`
`\vce`	Show expired vault credentials	`\vce`

Command	Description	Example
`\h`	Show help	`\h`
`\q`	Quit DBCrust	`\q`

🔍 Detailed Command Reference¶

`\l` - List Databases¶

Lists all databases on the current server.

\l

Output:

╭──────────────┬───────────┬──────────┬───────────────╮
│ Name         │ Owner     │ Encoding │ Description   │
├──────────────┼───────────┼──────────┼───────────────┤
│ myapp_dev    │ postgres  │ UTF8     │ Development   │
│ myapp_prod   │ postgres  │ UTF8     │ Production    │
│ analytics    │ analyst   │ UTF8     │ Data warehouse│
╰──────────────┴───────────┴──────────┴───────────────╯

`\dt` - List Tables¶

Lists all tables in the current database.

\dt

Output:

╭─────────────┬──────────┬──────────┬─────────────╮
│ Schema      │ Name     │ Type     │ Owner       │
├─────────────┼──────────┼──────────┼─────────────┤
│ public      │ users    │ table    │ postgres    │
│ public      │ orders   │ table    │ postgres    │
│ public      │ products │ table    │ postgres    │
╰─────────────┴──────────┴──────────┴─────────────╯

`\d [table]` - Describe Table¶

Without arguments, lists all tables. With a table name, shows detailed table structure.

-- List all tables
\d

-- Describe specific table
\d users

Output for \d users:

Table "public.users"
╭─────────────┬─────────────────────┬───────────┬─────────┬─────────────╮
│ Column      │ Type                │ Nullable  │ Default │ Description │
├─────────────┼─────────────────────┼───────────┼─────────┼─────────────┤
│ id          │ integer             │ not null  │ nextval │ Primary key │
│ name        │ character varying   │ not null  │         │ Full name   │
│ email       │ character varying   │ not null  │         │ Email addr  │
│ created_at  │ timestamp           │ not null  │ now()   │ Created     │
│ status      │ character varying   │           │ active  │ User status │
╰─────────────┴─────────────────────┴───────────┴─────────┴─────────────╯

Indexes:
    "users_pkey" PRIMARY KEY, btree (id)
    "users_email_key" UNIQUE CONSTRAINT, btree (email)
    "idx_users_status" btree (status)

`\c <database>` - Connect to Database¶

Switches to a different database on the same server.

\c production_db

Output:

You are now connected to database "production_db" as user "postgres".

Display Commands¶

`\x` - Toggle Expanded Display¶

Switches between table and expanded (vertical) display formats.

\x

Before (table format):

╭────┬──────────┬──────────────────────╮
│ id │ name     │ email                │
├────┼──────────┼──────────────────────┤
│ 1  │ John Doe │ john@example.com     │
╰────┴──────────┴──────────────────────╯

After (expanded format):

-[ RECORD 1 ]----------
id    | 1
name  | John Doe  
email | john@example.com

`\e` - Toggle EXPLAIN Mode¶

Enables or disables automatic EXPLAIN for all queries.

\e  -- Enable EXPLAIN mode

SELECT * FROM users WHERE email = 'john@example.com';

Output with EXPLAIN enabled:

○ Execution Time: 0.89 ms
○ Planning Time: 0.12 ms

Index Scan using email_idx on users
│ Index Cond: (email = 'john@example.com'::text)
│ ○ Cost: 0.29..8.31 ○ Rows: 1 ○ Width: 156
└─ Returns: id, name, email, created_at, status

╭────┬──────────┬──────────────────────╮
│ id │ name     │ email                │
├────┼──────────┼──────────────────────┤
│ 1  │ John Doe │ john@example.com     │
╰────┴──────────┴──────────────────────╯

EXPLAIN modes:

\e on          -- Basic EXPLAIN
\e analyze     -- EXPLAIN ANALYZE
\e verbose     -- EXPLAIN VERBOSE
\e buffers     -- EXPLAIN (ANALYZE, BUFFERS)
\e off         -- Disable EXPLAIN

`\ecopy` - Copy EXPLAIN to Clipboard¶

Copies the last EXPLAIN plan in JSON format to your clipboard.

\ecopy

Output:

EXPLAIN plan copied to clipboard (JSON format)

`\cs` - Toggle Column Selection Mode¶

Enables or disables interactive column selection for all queries. When enabled, all queries will prompt for column selection regardless of the number of columns.

\cs  -- Toggle column selection mode on/off

Output:

Column selection is now enabled.

Auto-Trigger vs Manual Mode

Auto-Trigger: Column selection appears automatically when queries return more than the configured threshold (default: 10 columns)
Manual Mode (\cs enabled): Column selection appears for ALL queries, regardless of column count

`\csthreshold <number>` - Set Column Selection Threshold¶

Configures the number of columns that triggers automatic column selection. This setting is saved to your configuration file.

-- Set threshold to 15 columns
\csthreshold 15

-- Set threshold to 5 columns for detailed work
\csthreshold 5

Output:

Column selection threshold set to: 15

Default threshold: 10 columns

Interactive Column Selection Interface¶

When column selection is triggered (either automatically or via \cs mode), an interactive interface appears:

Features: - Visual Selection: Checkbox-style interface with arrow key navigation - Multi-Select: Use spacebar to select/deselect multiple columns - Keyboard Controls: - ↑/↓ Arrow keys: Navigate between columns
- Space: Toggle column selection - Enter: Confirm selection and show results - Ctrl+C: Abort query and return to prompt (doesn't exit DBCrust)

Example Usage:

-- This query has 11 columns, exceeds default threshold of 10
SELECT * FROM users_detailed;

Interactive Interface:

? Select columns to display: 
❯ ◯ id
  ◯ username  
  ◯ email
  ◯ first_name
  ◯ last_name
  ◯ created_at
  ◯ updated_at
  ◯ last_login
  ◯ is_active
  ◯ phone
  ◯ address
[↑↓ to move, space to select, enter to confirm, ctrl+c to abort]

After selection (e.g., selecting id, username, email):

Showing 3 of 11 columns
╭────┬──────────┬──────────────────────╮
│ id │ username │ email                │
├────┼──────────┼──────────────────────┤
│ 1  │ john_doe │ john@example.com     │
│ 2  │ jane_doe │ jane@example.com     │
╰────┴──────────┴──────────────────────╯

Session Persistence¶

Column selections are automatically remembered during your session:

Behavior: - Selections saved per table structure (based on column names) - Subsequent queries on same table use saved selection automatically - Persists until you clear selections or reset views

Example:

-- First time: interactive selection appears
SELECT * FROM users_detailed;  
-- [Select id, username, email]

-- Second time: uses saved selection automatically
SELECT * FROM users_detailed WHERE created_at > '2024-01-01';
-- Shows only id, username, email columns

`\clrcs` - Clear Column Selections¶

Removes all saved column selections, returning to fresh selection state for all tables.

\clrcs

Output:

Column views cleared.

After clearing, the next query on any table will prompt for column selection again.

`\resetview` - Reset All View Settings¶

Resets all display settings to defaults, including: - Column selections (clears all saved selections) - Expanded display mode (\x) - EXPLAIN mode (\e)

\resetview

Output:

View settings reset to defaults.

File Operations¶

`\w <filename>` - Write Script to File¶

Saves the last executed query or script to a file.

-- Execute a query
SELECT * FROM users WHERE created_at > '2024-01-01';

-- Save it to file
\w recent_users.sql

Output:

Script written to 'recent_users.sql' (156 bytes)

`\i <filename>` - Execute SQL File¶

Loads and executes SQL commands from a file.

\i setup_tables.sql

File contents (setup_tables.sql):

CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO users (name, email) VALUES
('Alice Johnson', 'alice@example.com'),
('Bob Smith', 'bob@example.com');

Output:

Executing setup_tables.sql...
CREATE TABLE
INSERT 0 2
Script execution completed successfully.

`\ed` - External Editor¶

Opens your default editor to write or edit a query.

\ed

Process: 1. Opens $EDITOR (vim, nano, code, etc.) 2. Edit your query 3. Save and close 4. Script is loaded and ready - press Enter to execute

Editor integration:

# Set preferred editor
export EDITOR="code --wait"  # VS Code
export EDITOR="vim"          # Vim
export EDITOR="nano"         # Nano

Workflow tip: After using \ed or \i, press Enter on an empty line to re-execute the last loaded script.

Named Queries¶

`\n` - List Named Queries¶

Shows all saved named queries.

\n

Output:

Named Queries:
╭─────────────────┬────────────────────────────────────────────╮
│ Name            │ Query                                      │
├─────────────────┼────────────────────────────────────────────┤
│ active_users    │ SELECT * FROM users WHERE status = 'act.. │
│ daily_orders    │ SELECT DATE(created_at), COUNT(*) FROM .. │
│ user_summary    │ SELECT COUNT(*), MAX(created_at) FROM ..  │
╰─────────────────┴────────────────────────────────────────────╯

`\ns <name> <query>` - Save Named Query¶

Saves a query with a name for later use. Supports parameter substitution.

-- Simple named query
\ns active_users SELECT * FROM users WHERE status = 'active'

-- With parameters
\ns user_by_id SELECT * FROM users WHERE id = $1

-- Multiple parameters
\ns user_orders SELECT * FROM orders WHERE user_id = $1 AND status = '$2'

-- All remaining parameters
\ns search_users SELECT * FROM users WHERE name ILIKE '%$*%'

Usage:

-- Execute named queries
active_users
user_by_id 123
user_orders 123 completed
search_users John Doe

`\nd <name>` - Delete Named Query¶

Removes a saved named query.

\nd active_users

Output:

Named query 'active_users' deleted.

Session Management¶

`\s [name]` - List or Connect to Sessions¶

Without arguments, lists all saved sessions. With a session name, connects to that session.

-- List all saved sessions
\s

Output:

Saved Sessions:
  production - PostgreSQL postgres@prod.db.com:5432/myapp
  staging - PostgreSQL postgres@staging.db.com:5432/myapp_staging  
  local_mysql - MySQL root@localhost:3306/testdb
  analytics - SQLite /data/analytics.db

Use 'session://<name>' to connect via command line

-- Connect to a saved session
\s production

Output:

Connecting to saved session 'production'...
✓ Successfully connected to database

`\ss <name>` - Save Session¶

Saves the current connection as a named session for quick reconnection.

\ss production

Output:

Session 'production' saved successfully

Password Security

Sessions never store passwords. DBCrust integrates with: - PostgreSQL: .pgpass file - MySQL: .my.cnf file
- SQLite: No authentication needed

`\sd <name>` - Delete Session¶

Removes a saved session.

\sd old_staging

Output:

Deleted session 'old_staging'

Connection History¶

`\r` - List Recent Connections¶

Shows your recent connection history with full URLs (excluding passwords).

\r

Output:

Recent Connections:
  [1] ✓ docker://postgres@myapp-postgres/myapp_dev - 2024-01-15 14:22 (PostgreSQL)
  [2] ✓ postgres://user@localhost:5432/testdb - 2024-01-15 14:15 (PostgreSQL)
  [3] ✗ mysql://root@badhost:3306/db - 2024-01-15 14:10 (MySQL)
  [4] ✓ sqlite:///home/user/data.db - 2024-01-15 13:55 (SQLite)

Use 'recent://' to interactively select and connect to a recent connection

Connection Status

✓ = Successful connection
✗ = Failed connection attempt

`\rc` - Clear Recent Connections¶

Clears all connection history.

\rc

Output:

Cleared all recent connections
Configuration saved

Vault Management¶

DBCrust provides intelligent caching for HashiCorp Vault dynamic credentials to improve performance and reduce Vault API calls.

`\vc` - Show Vault Credential Cache Status¶

Displays all cached Vault credentials with their expiration status and remaining TTL.

\vc

Output:

Vault credential cache status (showing 2 entries):
  database/myapp-prod/readonly (v-user-prod--ABC123-1234567890) - 0h58m remaining - VALID
  database/myapp-dev/admin (v-user-dev--XYZ789-9876543210) - 0h02m remaining - EXPIRES SOON

Status indicators: - VALID: Credentials have sufficient TTL remaining - EXPIRES SOON: Credentials below renewal threshold (default: 25% of original TTL) - EXPIRED: Credentials past expiration time (automatically cleaned up)

`\vcc` - Clear Vault Credential Cache¶

Removes all cached vault credentials, forcing fresh authentication on next vault:// connection.

\vcc

Output:

Cleared all cached vault credentials (2 entries removed)

Cache Clearing

This forces all subsequent Vault connections to fetch fresh credentials from Vault, which may impact performance and increase Vault API usage.

`\vcr [role]` - Force Refresh Vault Credentials¶

Forces refresh of Vault credentials, either for all cached entries or a specific role.

-- Refresh all cached credentials
\vcr

-- Refresh specific role
\vcr readonly

Output:

Refreshed vault credentials for role 'readonly'
New credentials valid for 1h0m

Use cases: - Force credential renewal before long-running operations - Refresh credentials that are near expiration - Update credentials after Vault policy changes

`\vce` - Show Expired Vault Credentials¶

Lists vault credentials that have expired but haven't been cleaned up yet.

\vce

Output:

Expired vault credentials (1 entry):
  database/myapp-staging/readonly - expired 0h15m ago

Automatic Cleanup

Expired credentials are automatically removed during normal cache operations. This command is mainly useful for troubleshooting.

Vault Credential Caching Behavior¶

Automatic Caching: - Credentials are automatically cached when using vault:// URLs - Cache persists between DBCrust sessions - Stored in encrypted file: ~/.config/dbcrust/vault_credentials.enc

Cache Validation: - Credentials are checked for expiration before use - TTL threshold prevents using credentials that expire soon (default: 5 minutes minimum) - Automatic cleanup removes expired credentials

Security Features: - All cached credentials are encrypted using AES-256-GCM - Encryption key derived from your Vault token - Cache automatically invalidated if Vault token changes

Configuration:

# ~/.config/dbcrust/config.toml
vault_credential_cache_enabled = true          # Enable/disable caching
vault_cache_renewal_threshold = 0.25           # Renew when 25% TTL remaining  
vault_cache_min_ttl_seconds = 300              # Minimum 5 minutes required

Example Workflow¶

-- First connection: fetches and caches credentials
dbcrust vault://readonly@database/myapp-prod

-- Check cache status
\vc
-- Output: database/myapp-prod/readonly (v-user--ABC123-1234567890) - 0h59m remaining - VALID

-- Reconnect quickly using cached credentials
dbcrust vault://readonly@database/myapp-prod
-- Uses cached credentials, no Vault API call

-- Force refresh if needed
\vcr readonly

-- Clear cache when done
\vcc

💡 Advanced Usage Patterns¶

Combining Commands¶

-- Switch database and list tables
\c analytics
\dt

-- Enable EXPLAIN and run query
\e on
SELECT COUNT(*) FROM large_table;

-- Save result and write to file
\w large_table_count.sql

Scripting Workflows¶

-- Create a setup script
\ed

-- In editor, write:
-- \c development
-- \i create_tables.sql  
-- \i seed_data.sql
-- \dt

-- Save and execute automatically

Query Development¶

-- Start with simple query
SELECT * FROM users LIMIT 5;

-- Refine in editor
\ed

-- Save final version
\w final_user_report.sql

-- Create named query for reuse
\ns user_report SELECT u.*, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id

🚀 Pro Tips¶

Command History

All backslash commands are saved in your command history and can be recalled with ↑/↓ arrows or Ctrl+R search.

Tab Completion

Most commands support tab completion:

\d us[TAB]  -- Completes to table names starting with 'us'
\ns my[TAB] -- Completes to existing named query names

Command Aliases

Some commands have shorter aliases:

\q = \quit
\? = \h = \help

File Paths

File commands support both absolute and relative paths:

\i /home/user/scripts/setup.sql     -- Absolute
\i ../migrations/001_create.sql     -- Relative
\w ~/backups/current_query.sql      -- Home directory

Column Selection Shortcuts

Efficient column selection workflows:

-- Temporarily adjust threshold for current session
\csthreshold 5          -- Lower threshold for detailed analysis

-- Enable manual mode for exploration
\cs                     -- Now all queries show column selection

-- Clear and reset when done
\clrcs                  -- Clear saved selections
\cs                     -- Disable manual mode
\csthreshold 10         -- Reset to default threshold

Error Recovery

If a file operation fails, the error message will suggest corrections:

\i nonexistent.sql
-- Error: File 'nonexistent.sql' not found
-- Did you mean: setup.sql, test.sql?

Master backslash commands?
URL Schemes Guide User Guide

Backslash Commands Reference¶

📚 Command Categories¶

🔍 Detailed Command Reference¶

Navigation Commands¶

\l - List Databases¶

\dt - List Tables¶

\d [table] - Describe Table¶

\c <database> - Connect to Database¶

Display Commands¶

\x - Toggle Expanded Display¶

\e - Toggle EXPLAIN Mode¶

\ecopy - Copy EXPLAIN to Clipboard¶

\cs - Toggle Column Selection Mode¶

\csthreshold <number> - Set Column Selection Threshold¶

Interactive Column Selection Interface¶

Session Persistence¶

\clrcs - Clear Column Selections¶

\resetview - Reset All View Settings¶

File Operations¶

\w <filename> - Write Script to File¶

\i <filename> - Execute SQL File¶

\ed - External Editor¶

Named Queries¶

\n - List Named Queries¶

\ns <name> <query> - Save Named Query¶

\nd <name> - Delete Named Query¶

Session Management¶

\s [name] - List or Connect to Sessions¶

\ss <name> - Save Session¶

\sd <name> - Delete Session¶

Connection History¶

\r - List Recent Connections¶

\rc - Clear Recent Connections¶

Vault Management¶

\vc - Show Vault Credential Cache Status¶

\vcc - Clear Vault Credential Cache¶

\vcr [role] - Force Refresh Vault Credentials¶

\vce - Show Expired Vault Credentials¶

Vault Credential Caching Behavior¶

Example Workflow¶

💡 Advanced Usage Patterns¶

Combining Commands¶

Scripting Workflows¶

Query Development¶

🚀 Pro Tips¶

`\l` - List Databases¶

`\dt` - List Tables¶

`\d [table]` - Describe Table¶

`\c <database>` - Connect to Database¶

`\x` - Toggle Expanded Display¶

`\e` - Toggle EXPLAIN Mode¶

`\ecopy` - Copy EXPLAIN to Clipboard¶

`\cs` - Toggle Column Selection Mode¶

`\csthreshold <number>` - Set Column Selection Threshold¶

`\clrcs` - Clear Column Selections¶

`\resetview` - Reset All View Settings¶

`\w <filename>` - Write Script to File¶

`\i <filename>` - Execute SQL File¶

`\ed` - External Editor¶

`\n` - List Named Queries¶

`\ns <name> <query>` - Save Named Query¶

`\nd <name>` - Delete Named Query¶

`\s [name]` - List or Connect to Sessions¶

`\ss <name>` - Save Session¶

`\sd <name>` - Delete Session¶

`\r` - List Recent Connections¶

`\rc` - Clear Recent Connections¶

`\vc` - Show Vault Credential Cache Status¶

`\vcc` - Clear Vault Credential Cache¶

`\vcr [role]` - Force Refresh Vault Credentials¶

`\vce` - Show Expired Vault Credentials¶