Configuration

Configuration

DBCrust stores its configuration in a TOML file located at ~/.config/dbcrust/config.toml. The configuration is automatically created with sensible defaults when you first run DBCrust.

📍 Configuration Location

# Default configuration directory
~/.config/dbcrust/
├── config.toml             # Main configuration file
├── recent.toml             # Recent connections storage
├── named_queries.toml      # Scoped named queries storage
├── vault_credentials.enc   # Encrypted vault credentials cache
└── history.txt             # Command history

🔧 Configuration Structure

Complete Example

~/.config/dbcrust/config.toml

[database]
default_limit = 1000
expanded_display_default = false
show_execution_time = true
auto_explain_threshold = 1000  # ms
null_display = "NULL"

# Named Query Settings
test_named_query_before_saving = true  # Validate queries before saving

[display]
border_style = 1  # 0=none, 1=light, 2=heavy
date_format = "%Y-%m-%d %H:%M:%S"
number_format = "human"  # "raw" or "human" (with commas)
max_column_width = 50
truncate_long_values = true

# Column Selection Settings
column_selection_threshold = 10        # Auto-trigger when result has more than N columns

# Server Information Display
show_server_info = true                # Show server version info on connection

# Editor settings are controlled via $EDITOR environment variable
# export EDITOR="code --wait"

[history]
max_entries = 10000
save_unnamed_queries = true
deduplicate = true
max_recent_connections = 10

[ssh_tunnel_patterns]
"^db\\.internal\\..*\\.com$" = "jumphost.example.com"
".*\\.private\\.net" = "user@jumphost.example.com:2222"
"prod-.*\\.company\\.com" = "bastion.company.com:22"

[vault]
addr = "https://vault.company.com"
mount_point = "database"
auth_method = "token"  # "token", "userpass", "ldap"
timeout = 30

# Vault Credential Caching
vault_credential_cache_enabled = true          # Enable/disable credential caching
vault_cache_renewal_threshold = 0.25           # Renew when 25% of TTL remaining
vault_cache_min_ttl_seconds = 300              # Minimum TTL required (5 minutes)

[security]
verify_ssl = true
ssl_cert_path = ""
ssl_key_path = ""
password_cache_timeout = 3600  # seconds

[performance]
connection_timeout = 30
query_timeout = 300
pool_max_connections = 10
enable_connection_pooling = true

[completion]
enabled = true
cache_duration = 300  # seconds
max_suggestions = 20
fuzzy_matching = true

[logging]
level = "info"  # "error", "warn", "info", "debug", "trace"
file_path = "~/.config/dbcrust/dbcrust.log"
max_file_size = "10MB"
max_files = 5

# Saved sessions (added by \ss command)
[saved_sessions.production]
host = "prod.example.com"
port = 5432
user = "app_user"
dbname = "myapp"
database_type = "PostgreSQL"
created_at = "2024-01-15T10:30:00Z"

[saved_sessions.staging]
host = "staging.example.com"
port = 3306
user = "root"
dbname = "myapp_staging"
database_type = "MySQL"
created_at = "2024-01-14T15:45:00Z"

# Note: Recent connections are stored separately in ~/.config/dbcrust/recent.toml

📄 Recent Connections File

DBCrust automatically tracks recent connections in a separate file to avoid mixing transient data with your configuration:

File: ~/.config/dbcrust/recent.toml

# Recent connections (automatically tracked)
[[connections]]
connection_url = "postgres://postgres@myapp-postgres.orb.local:5432/myapp # Docker: myapp-postgres"
display_name = "postgres@myapp-postgres.orb.local:5432/myapp (Docker: myapp-postgres)"
timestamp = "2024-01-15T14:22:33Z"
database_type = "PostgreSQL"
success = true

[[connections]]
connection_url = "postgres://user@localhost:5432/testdb"
display_name = "user@localhost:5432/testdb"
timestamp = "2024-01-15T14:20:15Z"
database_type = "PostgreSQL"
success = true

This file is managed automatically and stores up to the configured number of recent connections (default: 10). You can control this limit with the max_recent_connections setting in your main config file.

⚙️ Configuration Sections

[database] - Database Behavior

Controls default database connection and query behavior.

Setting	Type	Default	Description
default_limit	integer	1000	Default LIMIT for queries without explicit LIMIT
expanded_display_default	boolean	false	Start in expanded display mode
show_execution_time	boolean	true	Show query execution time
auto_explain_threshold	integer	1000	Auto-enable EXPLAIN for slow queries (ms)
null_display	string	"NULL"	How to display NULL values
test_named_query_before_saving	boolean	true	Validate named queries with EXPLAIN before saving

Example:

[database]
default_limit = 500
expanded_display_default = true
show_execution_time = true
auto_explain_threshold = 2000
null_display = "∅"
test_named_query_before_saving = false  # Skip validation for faster saves

[display] - Output Formatting

Controls how query results and tables are displayed.

Setting	Type	Default	Description
border_style	integer	1	Table border style (0=none, 1=light, 2=heavy)
date_format	string	"%Y-%m-%d %H:%M:%S"	Date/timestamp display format
number_format	string	"human"	Number formatting ("raw" or "human")
max_column_width	integer	50	Maximum column width before truncation
truncate_long_values	boolean	true	Truncate long text values
column_selection_threshold	integer	10	Auto-trigger column selection when results exceed N columns
column_selection_default_all	boolean	false	Default all columns selected in column selection interface

Column Selection Configuration:

• column_selection_threshold: Automatically shows column selection interface when queries return more columns than this number
• column_selection_default_all: When true, all columns are pre-selected for opt-out behavior. When false (default), no columns are pre-selected for opt-in behavior.

Example:

[display]
border_style = 2
date_format = "%d/%m/%Y %H:%M"
number_format = "human"
max_column_width = 80
truncate_long_values = false

# Column selection settings
column_selection_threshold = 15        # Higher threshold for experienced users
column_selection_default_all = true    # Pre-select all columns (opt-out)

Column Selection Behavior:

• Auto-Trigger Mode: Column selection appears when query results have more columns than the threshold
• Force Mode: Use \cs to force column selection for all queries (toggle on/off)
• Runtime Control: Use \cs to toggle force mode and \csthreshold N to change threshold temporarily

[complex_display] - Complex Data Type Formatting

Controls how complex data types (JSON, arrays, vectors, GeoJSON) are displayed across all database types.

Setting	Type	Default	Description
display_mode	string	"truncated"	Default display mode: "full", "truncated", "summary", "viz"
truncation_length	integer	5	Number of elements to show at start/end when truncated
viz_width	integer	40	Width for visualization modes
show_metadata	boolean	false	Show metadata/statistics with formatted data
size_threshold	integer	20	Auto-switch to truncated mode for data above this size
show_dimensions	boolean	true	Show size/dimension information
full_elements_per_row	integer	8	Elements per row in full mode matrix layout
max_width	integer	80	Maximum display width before wrapping
full_show_numbers	boolean	true	Show element numbers in full mode

Complex Data Type Support:

• JSON/JSONB (PostgreSQL, MySQL): Enhanced formatting with syntax highlighting
• GeoJSON (PostGIS, MySQL spatial): Geographic data visualization
• Arrays (PostgreSQL {1,2,3}, ClickHouse [1,2,3]): Smart array formatting
• Vectors (pgvector [0.1,0.2,0.3]): Embedding/vector visualization
• BSON Documents (MongoDB): Nested document formatting
• Mixed Arrays (MongoDB): Heterogeneous array type analysis

Example:

[complex_display]
display_mode = "truncated"
truncation_length = 8
viz_width = 60
show_metadata = true
size_threshold = 30
show_dimensions = true
full_elements_per_row = 10
max_width = 100
full_show_numbers = false

Display Modes:

• full: Complete data with matrix-style layout for arrays
• truncated: Show first/last N elements with ”…” indicator
• summary: Statistical overview (type counts, size, nesting info)
• viz: ASCII visualization for vectors and large datasets

Server Information Display

Controls whether server version information is displayed when connecting to databases.

# Show server info on connection (default: true)
show_server_info = true

Configuration:

Setting	Default	Description
show_server_info	true	Display server version info when connecting

Example Output:

Server: PostgreSQL 17.5 (Debian 17.5-1.pgdg120+1)
Version: 0.16.1

Runtime Control:

-- Toggle server info display on/off
\serverinfo

Behavior:

• Enabled: Shows database server type, version, and DBCrust version on connection
• Disabled: Connects silently without version information
• Error Handling: If version query fails, connection continues normally (debug logging only)

Database Support:

• PostgreSQL: Shows full version string from SELECT version()
• MySQL: Shows version from SELECT VERSION() with role support detection
• SQLite: Shows version from SELECT sqlite_version() with database file info

[editor] - External Editor

Configuration for external editor integration (\ed command).

The editor integration uses your system’s $EDITOR environment variable to determine which editor to launch. Temporary files are automatically created in the system temp directory.

How it works:

• Uses $EDITOR environment variable (falls back to vim/nano/notepad)
• Creates temporary files in system temp directory
• Syntax highlighting is handled by your editor, not DBCrust

Popular editor configurations via environment variable:

# VS Code (waits for editor to close)
export EDITOR="code --wait"

# Vim/Neovim
export EDITOR="vim"

# Nano
export EDITOR="nano"

# Sublime Text (waits for editor to close)
export EDITOR="subl --wait"

# Emacs
export EDITOR="emacs"

Using the editor:

-- Edit current query in external editor
\ed

-- Load script from file
\i filename.sql

-- Empty Enter executes last edited/loaded script

[history] - History and Session Management

Controls command history and recent connection tracking.

Setting	Type	Default	Description
max_entries	integer	10000	Maximum number of command history entries
save_unnamed_queries	boolean	true	Save unnamed queries in history
deduplicate	boolean	true	Remove duplicate entries from history
max_recent_connections	integer	10	Maximum number of recent connections to track

Example:

[history]
max_entries = 5000
save_unnamed_queries = true
deduplicate = true
max_recent_connections = 15

[ssh_tunnel_patterns] - Automatic SSH Tunneling

Define patterns for automatic SSH tunnel creation based on hostname.

Format: "hostname_pattern" = "ssh_target"

Examples:

[ssh_tunnel_patterns]
# Internal company databases
"^db\\.internal\\..*\\.com$" = "jumphost.example.com"

# Private network
".*\\.private\\.net" = "user@jumphost.example.com:2222"

# Production environment
"prod-.*\\.company\\.com" = "bastion.company.com:22"

# AWS RDS through bastion
".*\\.rds\\.amazonaws\\.com$" = "ec2-bastion.company.com"

[vault] - HashiCorp Vault Integration

Configuration for dynamic database credentials via Vault, including intelligent credential caching.

Setting	Type	Default	Description
addr	string	$VAULT_ADDR	Vault server address
mount_point	string	"database"	Database secrets engine mount point
auth_method	string	"token"	Authentication method
timeout	integer	30	Request timeout in seconds
vault_credential_cache_enabled	boolean	true	Enable credential caching between sessions
vault_cache_renewal_threshold	float	0.25	Renew when remaining TTL < 25% of original
vault_cache_min_ttl_seconds	integer	300	Minimum TTL required (5 minutes)

Example:

[vault]
addr = "https://vault.company.com"
mount_point = "database"
auth_method = "userpass"
timeout = 60

# Credential Caching (improves performance)
vault_credential_cache_enabled = true
vault_cache_renewal_threshold = 0.25  # Renew when 25% TTL remaining
vault_cache_min_ttl_seconds = 300     # Require at least 5 minutes TTL

Credential Caching Behavior:

• Automatic: Credentials are cached on first vault:// connection
• Persistent: Cache survives between DBCrust sessions
• Secure: All credentials encrypted with AES-256-GCM using your Vault token
• Smart Renewal: Automatically refreshes credentials approaching expiration
• File Location: ~/.config/dbcrust/vault_credentials.enc

Cache Management Commands:

• \vc - Show cache status and remaining TTL
• \vcc - Clear all cached credentials
• \vcr [role] - Force refresh credentials
• \vce - Show expired credentials

[security] - Security Settings

SSL/TLS and security-related configuration.

Setting	Type	Default	Description
verify_ssl	boolean	true	Verify SSL certificates
ssl_cert_path	string	""	Path to client SSL certificate
ssl_key_path	string	""	Path to client SSL key
password_cache_timeout	integer	3600	Password cache timeout (seconds)

Example:

[security]
verify_ssl = true
ssl_cert_path = "~/.ssl/client.crt"
ssl_key_path = "~/.ssl/client.key"
password_cache_timeout = 1800

🚀 Environment Variable Overrides

Many configuration options can be overridden with environment variables:

# Database connection
export DBCRUST_DATABASE_URL="postgres://user@host/db"

# SSH tunnel
export DBCRUST_SSH_TUNNEL="user@jumphost.com:2222"

# Vault configuration
export VAULT_ADDR="https://vault.company.com"
export VAULT_TOKEN="your-token"

# Editor
export EDITOR="code --wait"

# Logging
export DBCRUST_LOG_LEVEL="debug"

📝 Common Configuration Examples

Development Environment

[database]
default_limit = 100
show_execution_time = true
expanded_display_default = false

[display]
border_style = 1
max_column_width = 100

[editor]
command = "code --wait"

[logging]
level = "debug"

Production Environment

[database]
default_limit = 1000
auto_explain_threshold = 2000

[ssh_tunnel_patterns]
"prod-db\\.company\\.com" = "prod-bastion.company.com"
"staging-db\\.company\\.com" = "staging-bastion.company.com"

[vault]
addr = "https://vault.company.com"
mount_point = "database"
auth_method = "ldap"

[security]
verify_ssl = true
password_cache_timeout = 1800

[logging]
level = "info"

Data Analysis Workflow

[database]
default_limit = 10000
expanded_display_default = true
show_execution_time = true

[display]
number_format = "human"
max_column_width = 80
truncate_long_values = false

[editor]
command = "jupyter lab"
temp_dir = "~/analysis/queries"

[performance]
query_timeout = 600  # 10 minutes for long analytics queries

🔧 Configuration Management

View Current Configuration

-- Show all current settings
\config

-- Or check specific file
cat ~/.config/dbcrust/config.toml

Reset to Defaults

# Backup current config
cp ~/.config/dbcrust/config.toml ~/.config/dbcrust/config.toml.backup

# Remove config file (will be recreated with defaults)
rm ~/.config/dbcrust/config.toml

# Start DBCrust to generate new default config
dbcrust --help

Configuration Validation

DBCrust validates configuration on startup and will show warnings for invalid settings:

⚠️  Warning: Invalid border_style '3' in config. Using default value '1'.
⚠️  Warning: SSH tunnel pattern '^invalid[regex' is not valid regex.
✅ Configuration loaded successfully.

Hot Reloading

Some configuration changes can be applied without restarting:

-- Reload configuration
\config reload

-- Or restart connection with new settings
\reconnect

🎯 Best Practices

Security

Sensitive Information

Never store passwords or tokens directly in the config file:

# ❌ Don't do this
[database]
password = "secret123"

# ✅ Use environment variables or Vault
[vault]
addr = "https://vault.company.com"

Performance

Connection Pooling

Enable connection pooling for frequently accessed databases:

[performance]
enable_connection_pooling = true
pool_max_connections = 10
connection_timeout = 30

Team Configurations

Shared Settings

For team environments, consider:

# Share common SSH tunnel patterns
[ssh_tunnel_patterns]
"^.*\\.company\\.internal$" = "shared-bastion.company.com"

# Standardize display settings
[display]
border_style = 1
date_format = "%Y-%m-%d %H:%M:%S UTC"

🆘 Troubleshooting

Common Issues

Config file not found

# Create config directory
mkdir -p ~/.config/dbcrust

# Generate default config
dbcrust --init-config

Permission denied

# Fix permissions
chmod 755 ~/.config/dbcrust
chmod 644 ~/.config/dbcrust/config.toml

Invalid TOML syntax

# Validate TOML syntax
python -c "import toml; toml.load('~/.config/dbcrust/config.toml')"

# Or use online validator
echo "Check at: https://www.toml-lint.com/"