Server Options

Database Connection

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

# Azure AD authentication
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:

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

Environment Variables

Recommended for databases with complex passwords containing special characters:

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

General

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 --transport stdio --dsn "..."

# http - for web clients, admin console, and remote access
npx @bytebase/dbhub --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 --transport http --port 3000 --dsn "..."

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 --id prod --dsn "postgres://user:pass@prod-host:5432/db"
npx @bytebase/dbhub --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.

config

--config

string

default:"./dbhub.toml"

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

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

See Multi-Database Setup for TOML configuration details.

demo

--demo

boolean

default:"false"

Run DBHub with a bundled SQLite sample “employee” database for testing.The demo database includes tables for employees, departments, salaries, titles, and more.

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

SSH Tunnel

ssh-host

--ssh-host

string

SSH server hostname for tunnel connection. Can also use SSH config host aliases from ~/.ssh/config.

npx @bytebase/dbhub \
  --dsn "postgres://user:[email protected]:5432/mydb" \
  --ssh-host bastion.example.com

See SSH Tunnel for detailed SSH configuration examples.

ssh-port

--ssh-port

number

default:"22"

SSH server port.

npx @bytebase/dbhub \
  --dsn "..." \
  --ssh-host bastion.example.com \
  --ssh-port 2222

ssh-user

--ssh-user

string

SSH username.

npx @bytebase/dbhub \
  --dsn "..." \
  --ssh-host bastion.example.com \
  --ssh-user ubuntu

ssh-password

--ssh-password

string

SSH password for password authentication.

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

ssh-key

--ssh-key

string

Path to SSH private key file for key-based authentication.DBHub automatically tries common default locations (~/.ssh/id_rsa, ~/.ssh/id_ed25519, etc.) if not specified.

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

ssh-passphrase

--ssh-passphrase

string

Passphrase for encrypted SSH private key.

npx @bytebase/dbhub \
  --dsn "..." \
  --ssh-host bastion.example.com \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa \
  --ssh-passphrase mykeypassphrase

Configuration Priority

DBHub follows this priority order for configuration:

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

Mutually Exclusive Options

--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.

Quick Reference

CLI Option	Env	Type	Default	Description
`--dsn`	`DSN`	string	Required*	Database connection string
-	`DB_TYPE`	string	-	Database type: postgres, mysql, mariadb, sqlserver, sqlite
-	`DB_HOST`	string	-	Database hostname
-	`DB_PORT`	number	Varies	Database port
-	`DB_USER`	string	-	Database username
-	`DB_PASSWORD`	string	-	Database password
-	`DB_NAME`	string	-	Database name or SQLite file path
`--transport`	`TRANSPORT`	string	`stdio`	Transport mode: stdio or http
`--port`	`PORT`	number	`8080`	HTTP server port
`--demo`	-	boolean	`false`	Use sample employee database
`--id`	`ID`	string	-	Instance identifier for tool names
`--config`	-	string	`./dbhub.toml`	Path to TOML config file
`--ssh-host`	`SSH_HOST`	string	-	SSH server hostname
`--ssh-port`	`SSH_PORT`	number	`22`	SSH server port
`--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

*Required unless using --demo or --config

Getting Started

Tools

Integrations

Configuration

Server Options

Database Connection

dsn

Environment Variables

General

transport

port

id

config

demo

SSH Tunnel

ssh-host

ssh-port

ssh-user

ssh-password

ssh-key

ssh-passphrase

Configuration Priority

Mutually Exclusive Options

Quick Reference

Getting Started

Tools

Integrations

Configuration

​Database Connection

​dsn

​Environment Variables

​General

​transport

​port

​id

​config

​demo

​SSH Tunnel

​ssh-host

​ssh-port

​ssh-user

​ssh-password

​ssh-key

​ssh-passphrase

​Configuration Priority

​Mutually Exclusive Options

​Quick Reference

Database Connection

dsn

Environment Variables

General

transport

port

id

config

demo

SSH Tunnel

ssh-host

ssh-port

ssh-user

ssh-password

ssh-key

ssh-passphrase

Configuration Priority

Mutually Exclusive Options

Quick Reference