Command-Line Options

DBHub supports three configuration methods with the following priority order:

Command-line arguments (highest priority)
TOML configuration file (if --config is provided or ./dbhub.toml exists)
Environment variables
.env files (.env.local in development, .env in production)

This page covers command-line flags and environment variables. For TOML configuration, see TOML Configuration. Command-line flags are passed when starting DBHub. These have the highest priority and override all other configuration methods.

—transport

--transport

string

default:"stdio"

Transport protocol for MCP communication.Options:

stdio - For desktop tools (Claude Desktop, Claude Code, Cursor). Pure MCP-over-stdio with no HTTP server.
http - For browser and network clients. Starts HTTP server with MCP endpoint, admin console, and API.

Feature	`stdio`	`http`
MCP communication	stdin/stdout	HTTP POST `/mcp`
Admin console	❌	✅ `http://host:port/`
Health check	❌	✅ `/healthz`
API	❌	✅ `/api/xxx`
Multiple instances	✅ No port conflicts	Requires different ports

# stdio (default) - for Claude Desktop, Claude Code, Cursor
# No HTTP server started
npx @bytebase/dbhub@latest --transport stdio --dsn "..."

# http - for web clients, admin console, and remote access
npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "..."

—port

--port

number

default:"8080"

HTTP server port. Only used when --transport=http. Ignored for stdio transport.

npx @bytebase/dbhub@latest --transport http --port 3000 --dsn "..."

—dsn

--dsn

string

Database connection string (Data Source Name). Format: database_type://username:password@host:port/database_name?options

PostgreSQL
MySQL
MariaDB
SQL Server
SQLite

# Format: postgres://[user]:[password]@[host]:[port]/[database]?[options]
postgres://myuser:mypassword@localhost:5432/mydb

# Format: mysql://[user]:[password]@[host]:[port]/[database]?[options]
mysql://root:password@localhost:3306/mydb

# Format: mariadb://[user]:[password]@[host]:[port]/[database]?[options]
mariadb://root:password@localhost:3306/mydb

# Format: sqlserver://[user]:[password]@[host]:[port]/[database]?[options]
sqlserver://sa:YourPassword123@localhost:1433/mydb

# Named instance (e.g., ENV1, ENV2, ENV3)
sqlserver://sa:YourPassword123@localhost:1433/mydb?instanceName=ENV1

# Windows/NTLM authentication
sqlserver://jsmith:[email protected]:1433/mydb?authentication=ntlm&domain=CORP

# Azure AD authentication (password optional/empty)
sqlserver://username@localhost:1433/mydb?authentication=azure-active-directory-access-token

# Format: sqlite:///[path/to/database.db] or sqlite:///:memory:

# Unix/Linux/macOS
sqlite:///var/lib/data/mydb.db

# Windows
sqlite:///C:/Users/YourName/data/database.db

# In-memory
sqlite:///:memory:

DSN Query Parameters:

Parameter	Databases	Description	Example
`sslmode`	PostgreSQL, MySQL, MariaDB, SQL Server	SSL mode: `disable`, `require`	`?sslmode=require`
`instanceName`	SQL Server	Named instance	`?instanceName=SQLEXPRESS`
`authentication`	SQL Server	Auth method: `ntlm`, `azure-active-directory-access-token`	`?authentication=ntlm`
`domain`	SQL Server	Windows domain (with `authentication=ntlm`)	`?domain=CORP`

SSL/TLS Options:

Database	`sslmode=disable`	`sslmode=require`	Default
PostgreSQL	✅	✅	Certificate verification
MySQL	✅	✅	Certificate verification
MariaDB	✅	✅	Certificate verification
SQL Server	✅	✅	Certificate verification
SQLite	❌	❌	N/A (file-based)

sslmode=disable: All SSL/TLS encryption is turned off. Data is transmitted in plaintext.
sslmode=require: Connection is encrypted, but the server’s certificate is not verified.

# Examples
postgres://user:password@localhost:5432/dbname?sslmode=disable
postgres://user:password@localhost:5432/dbname?sslmode=require
sqlserver://jsmith:secret@localhost:1433/mydb?authentication=ntlm&domain=CORP

Environment Variables (Alternative to —dsn)

DB_*

environment

Recommended for databases with complex passwords containing special characters:

Variable	Type	Description
`DB_TYPE`	string	Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite`
`DB_HOST`	string	Database server hostname (not needed for SQLite)
`DB_PORT`	number	Database server port. Default: PostgreSQL (`5432`), MySQL/MariaDB (`3306`), SQL Server (`1433`)
`DB_USER`	string	Database username (not needed for SQLite)
`DB_PASSWORD`	string	Database password (not needed for SQLite). Supports special characters without URL encoding.
`DB_NAME`	string	Database name or SQLite file path

export DB_TYPE=postgres
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=myuser
export DB_PASSWORD='p@ss:word#123'
export DB_NAME=mydb
npx @bytebase/dbhub@latest

—id

--id

string

Instance identifier to suffix tool names. Useful when running multiple DBHub instances (e.g., in Cursor).Tools will be named execute_sql_{id} for each instance.

npx @bytebase/dbhub@latest --id prod --dsn "postgres://user:pass@prod-host:5432/db"
npx @bytebase/dbhub@latest --id staging --dsn "postgres://user:pass@staging-host:5432/db"

Result: execute_sql_prod and execute_sql_staging tools

Cannot be used with --config (TOML configuration). TOML config defines source IDs directly in the configuration file. Use command-line DSN configuration instead if you need the --id flag.

—demo

--demo

boolean

default:"false"

Run DBHub with a bundled SQLite sample “employee” database for testing.

npx @bytebase/dbhub@latest --demo --transport http --port 8080

—config

--config

string

default:"./dbhub.toml"

Path to TOML configuration file for managing multiple database connections and advanced configurations.Automatically loads ./dbhub.toml if it exists in the current directory.

npx @bytebase/dbhub@latest --config ./dbhub.toml --transport http --port 8080

See TOML Configuration for complete configuration reference including source options, tool options, SSH tunnels, and custom tools.

--config (TOML) is mutually exclusive with:

--dsn - TOML configuration defines database connections directly
--id - TOML configuration defines source IDs directly in the file

If using TOML config, remove these flags. If you need --id or --dsn, use command-line/environment configuration instead.

SSH Tunnel Options

SSH tunnel configuration for connecting to databases through bastion/jump hosts.

Option	Env	Type	Description
`--ssh-host`	`SSH_HOST`	string	SSH server hostname or alias from `~/.ssh/config`
`--ssh-port`	`SSH_PORT`	number	SSH server port (default: `22`)
`--ssh-user`	`SSH_USER`	string	SSH username
`--ssh-password`	`SSH_PASSWORD`	string	SSH password (for password auth)
`--ssh-key`	`SSH_KEY`	string	Path to SSH private key file. Auto-detects `~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, etc. if not specified
`--ssh-passphrase`	`SSH_PASSPHRASE`	string	Passphrase for encrypted SSH key
`--ssh-proxy-jump`	`SSH_PROXY_JUMP`	string	ProxyJump hosts for multi-hop SSH. Format: `[user@]host[:port]` (comma-separated for chains)

Examples:

# Password auth
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu --ssh-password mypassword

# Key-based auth
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu --ssh-key ~/.ssh/id_rsa

# ProxyJump (single hop)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host target.internal --ssh-proxy-jump bastion.example.com

# ProxyJump (multi-hop: bastion1 → bastion2 → target)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host target.internal --ssh-proxy-jump "bastion1.com,admin@bastion2:2222"

ProxyJump is automatically read from ~/.ssh/config when using SSH host aliases
ProxyCommand is not supported (requires shell execution). Use ProxyJump instead
Path expansion for ~/ is supported in file paths

Quick Reference

CLI Option	Env	Type	Description
`--transport`	`TRANSPORT`	string	Transport mode: stdio or http (default: `stdio`)
`--port`	`PORT`	number	HTTP server port (http transport only, default: `8080`)
`--demo`	-	boolean	Use sample employee database
`--id`	`ID`	string	Instance identifier for tool names
`--config`	-	string	Path to TOML config file (default: `./dbhub.toml`)
`--dsn`	`DSN`	string	Database connection string (required unless using `--demo` or `--config`)
-	`DB_TYPE`	string	Database type
-	`DB_HOST`	string	Database hostname
-	`DB_PORT`	number	Database port (varies by type)
-	`DB_USER`	string	Database username
-	`DB_PASSWORD`	string	Database password
-	`DB_NAME`	string	Database name or SQLite file path
`--ssh-host`	`SSH_HOST`	string	SSH server hostname
`--ssh-port`	`SSH_PORT`	number	SSH server port (default: `22`)
`--ssh-user`	`SSH_USER`	string	SSH username
`--ssh-password`	`SSH_PASSWORD`	string	SSH password
`--ssh-key`	`SSH_KEY`	string	Path to SSH private key
`--ssh-passphrase`	`SSH_PASSPHRASE`	string	SSH key passphrase
`--ssh-proxy-jump`	`SSH_PROXY_JUMP`	string	ProxyJump hosts

Getting Started

MCP Tools

Configuration

—transport

—port

—dsn

—id

—demo

—config

SSH Tunnel Options

Quick Reference

Getting Started

MCP Tools

Configuration

​—transport

​—port

​—dsn

​—id

​—demo

​—config

​SSH Tunnel Options

​Quick Reference

—transport

—port

—dsn

—id

—demo

—config

SSH Tunnel Options

Quick Reference