Skip to main content
Command-line flags provide the highest priority configuration method in DBHub. Use these for quick testing, temporary overrides, or when you need to specify configuration at runtime.

​
Configuration Priority

DBHub resolves configuration in this order (highest to lowest priority):
  1. Command-line arguments (highest priority)
  2. TOML config file (--config or ./dbhub.toml)
  3. Environment variables
  4. .env files (.env.local in development, .env in production)
Command-line arguments override all other configuration sources, making them ideal for testing or temporary changes.

​
Database Connection

​
DSN Connection String

The --dsn flag accepts a full database connection string: 
pnpm run dev -- --dsn="postgres://user:password@localhost:5432/dbname"
​
--dsn
string
Database connection string in URL format. Supports all database types.Format: protocol://[user[:password]@]host[:port]/database[?options]

​
DSN Examples by Database Type

pnpm run dev -- --dsn="postgres://postgres:secret@localhost:5432/myapp"

# With SSL
pnpm run dev -- --dsn="postgres://user:[email protected]:5432/prod?sslmode=require"
If your password contains special characters like @, :, /, or #, they must be URL-encoded in the DSN, or use environment variables with individual connection parameters instead.

​
Demo Mode

​
--demo
boolean
default:"false"
Launch DBHub with an in-memory SQLite database pre-populated with sample employee data. Perfect for testing and exploration.
pnpm run dev -- --demo
Demo mode:
  • Creates an in-memory SQLite database
  • Pre-loads sample employee data (employees, departments, salaries)
  • Requires no additional configuration
  • Data is lost when the server stops

​
Transport Configuration

​
Transport Mode

​
--transport
string
default:"stdio"
MCP server transport protocol.Options:
  • stdio - Standard input/output (for Claude Desktop, Claude Code, Cursor)
  • http - HTTP transport with JSON responses (for network clients)
# Default stdio transport (for desktop clients)
pnpm run dev

# HTTP transport (for network clients or testing)
pnpm run dev -- --transport=http
stdio mode: Direct communication via standard input/output. Use with Claude Desktop, Claude Code, and Cursor.http mode: RESTful API at http://localhost:8080/mcp. Includes the workbench UI for testing tools.

​
HTTP Server Port

​
--port
number
default:"8080"
HTTP server port number. Only applicable when using --transport=http.
pnpm run dev -- --transport=http --port=3000
The port controls:
  • MCP endpoint: http://localhost:{port}/mcp
  • Workbench UI: http://localhost:{port}/
  • API endpoints: http://localhost:{port}/api/*

​
SSH Tunnel Options

Connect to databases through SSH bastion hosts:
​
--ssh-host
string
SSH server hostname or IP address. Can be an alias from ~/.ssh/config.
​
--ssh-port
number
default:"22"
SSH server port number.
​
--ssh-user
string
required
SSH username for authentication.
​
--ssh-password
string
SSH password authentication. Use either this or --ssh-key.
​
--ssh-key
string
Path to SSH private key file. Use either this or --ssh-password.Supports ~/ expansion (e.g., ~/.ssh/id_ed25519).
​
--ssh-passphrase
string
Passphrase for encrypted SSH private key.
​
--ssh-proxy-jump
string
Comma-separated list of jump hosts for multi-hop SSH connections.Format: [user@]host[:port],[user@]host[:port],...
​
--ssh-keepalive-interval
number
default:"0"
Seconds between SSH keepalive packets. Set to 0 to disable.
​
--ssh-keepalive-count-max
number
default:"3"
Maximum number of missed keepalive responses before disconnecting.

​
SSH Tunnel Examples

pnpm run dev -- \
  --dsn="postgres://user:[email protected]:5432/prod" \
  --ssh-host="bastion.company.com" \
  --ssh-user="deploy" \
  --ssh-password="secret"
DBHub automatically reads SSH configuration from ~/.ssh/config when using host aliases. This reduces the number of flags you need to specify.

​
Advanced Options

​
Custom Config File

​
--config
string
Path to TOML configuration file. If not specified, DBHub looks for ./dbhub.toml in the current directory.
pnpm run dev -- --config=/path/to/custom-config.toml
See TOML Configuration for details on multi-database setup and advanced configuration.

​
Source ID (Single Database Only)

​
--id
string
default:"default"
Custom identifier for the database source. Only applicable when using --dsn (not with TOML config).Affects tool naming: execute_sql_{id}, search_objects_{id}
# Tools will be named: execute_sql_prod, search_objects_prod
pnpm run dev -- --dsn="postgres://..." --id=prod
The --id flag cannot be used with TOML configuration. TOML files define source IDs directly in the [[sources]] sections.

​
Deprecated Options

The following flags have been removed and will cause an error if used:
Removed in current version:
  • --readonly - Use TOML [[tools]] configuration instead
  • --max-rows - Use TOML [[tools]] configuration instead
See execute_sql tool configuration for migration guidance.

​
SSL/TLS Options

SSL mode is specified in the DSN query string: 
# Disable SSL (local development)
pnpm run dev -- --dsn="postgres://user:pass@localhost:5432/db?sslmode=disable"

# Require SSL (production)
pnpm run dev -- --dsn="postgres://user:[email protected]:5432/db?sslmode=require"
Supported modes:
  • sslmode=disable - No SSL encryption
  • sslmode=require - SSL encryption without certificate verification
SSL options are only applicable to network databases (PostgreSQL, MySQL, MariaDB, SQL Server). SQLite does not support SSL.

​
Complete Example

Combining multiple options: 
pnpm run dev -- \
  --dsn="postgres://app:[email protected]:5432/myapp?sslmode=require" \
  --ssh-host="bastion.company.com" \
  --ssh-user="deploy" \
  --ssh-key="~/.ssh/id_ed25519" \
  --ssh-keepalive-interval=60 \
  --transport=http \
  --port=8080 \
  --id=prod
This configuration:
  • Connects to PostgreSQL with SSL required
  • Routes through SSH bastion with key authentication
  • Sends keepalive packets every 60 seconds
  • Serves HTTP transport on port 8080
  • Names tools execute_sql_prod and search_objects_prod

​
Next Steps

Environment Variables

Configure via .env files for persistent settings

TOML Configuration

Set up multiple databases with advanced options

Build docs developers (and LLMs) love

Get started for freeTalk to us