Command-Line Options

DBHub connects to your database in one of two ways:

A DSN — one connection string for a single database.
A TOML file — passed with --config, for one or more databases plus per-source and per-tool settings.

Choose one. A TOML file defines its sources itself, so --config and --dsn cannot be combined. Environment variables are a different matter: DSN and DB_* stay available to a TOML file through ${VAR} interpolation, which is the recommended way to keep credentials out of the file. When you use a DSN, DBHub takes it from the first of:

--dsn flag
DSN environment variable
DB_* environment variables
.env file (.env.local in development, .env in production)

Every other option — transport, port, host, and so on — is set by flag or environment variable, in the same order:

Command-line flag
Environment variable
.env file
Built-in default

This page covers command-line flags and environment variables. For TOML configuration, see TOML Configuration.

—transport

string

default:"stdio"

Transport protocol for MCP communication. Env: TRANSPORT.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, workbench, and API.

Both transports serve the stateless 2026-07-28 MCP protocol revision natively and fall back to the 2025-era protocol for older clients on the same endpoint — no configuration needed. On http, 2026-era clients send the standard Mcp-Method / Mcp-Name headers with every request, so a fronting gateway or WAF can route and rate-limit individual tools without parsing request bodies.

Feature	`stdio`	`http`
MCP communication	stdin/stdout	HTTP POST `/mcp`
Workbench	❌	✅ `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, workbench, and remote access
npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "..."

—port

number

default:"8080"

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

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

—host

string

default:"0.0.0.0"

HTTP bind address. Only used when --transport=http. Ignored for stdio transport. Env: DBHUB_HOST.

# Restrict to loopback (recommended for production)
npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --dsn "..."

# Bind to a specific interface
npx @bytebase/dbhub@latest --transport http --host 10.0.0.5 --port 8080 --dsn "..."

# IPv6 loopback
npx @bytebase/dbhub@latest --transport http --host ::1 --port 8080 --dsn "..."

The default 0.0.0.0 exposes DBHub on every network interface. For production, set --host 127.0.0.1 and place DBHub behind a reverse proxy (nginx/Caddy) or restrict with a firewall, or configure --auth-token (see below) to require a bearer token on every request.

—allowed-hosts

string

default:"(loopback + this machine)"

Comma-separated list of additional hostnames the HTTP transport accepts in the Host (and Origin) headers. This is DBHub’s DNS-rebinding protection: requests whose Host is not on the list are rejected with 403, so a malicious web page cannot rebind a hostname to your DBHub instance and drive its MCP tools from the victim’s browser. Only used when --transport=http. Env: DBHUB_ALLOWED_HOSTS.The list always includes loopback (localhost, 127.0.0.1, [::1]). When bound to a wildcard address (the default 0.0.0.0 / ::), this machine’s own hostname and external IP addresses are added automatically, so reaching DBHub by IP or machine name works without any extra configuration. You only need this flag for other names that resolve to DBHub — most commonly a reverse-proxy or public DNS name.

# Serve behind a public/reverse-proxy hostname
npx @bytebase/dbhub@latest --transport http --allowed-hosts "dbhub.example.com" --dsn "..."

# Multiple hostnames
npx @bytebase/dbhub@latest --transport http --allowed-hosts "dbhub.example.com,db.internal" --dsn "..."

# Disable the check entirely (only when fronted by your own auth/proxy)
npx @bytebase/dbhub@latest --transport http --allowed-hosts "*" --dsn "..."

A port in an entry is ignored — only the hostname is matched. IPv6 literals must be bracketed, e.g. [2001:db8::1]. The active allow-list is printed at startup. If a legitimate client gets a 403 “Host … is not allowed”, add its hostname here.

--allowed-hosts "*" turns off DNS-rebinding protection. Use it only when DBHub sits behind your own authentication and/or proxy.

—auth-token

string

Comma-separated list of bearer tokens required on every HTTP request. Only used when --transport=http. Unset by default — auth is off unless you configure this. Env: DBHUB_AUTH_TOKEN.Clients must send a matching token as Authorization: Bearer <token>; requests without one get 401 Unauthorized with a WWW-Authenticate: Bearer header. /healthz is exempt so uptime monitors don’t need a token.

# Single token
npx @bytebase/dbhub@latest --transport http --auth-token "s3cr3t-token" --dsn "..."

# Multiple tokens (rotate without downtime, or issue one per client)
npx @bytebase/dbhub@latest --transport http --auth-token "token-for-ci,token-for-agent" --dsn "..."

Client request (/api/sources is a plain GET; the MCP endpoint itself requires a JSON-RPC POST body, so it’s not a copy-pasteable example):

curl -H "Authorization: Bearer s3cr3t-token" http://localhost:8080/api/sources

Configuring a token is the opt-in — there’s no separate “require auth” flag to remember. A comma-separated list lets you rotate a leaked or expiring token by adding the new one, redeploying, and then removing the old one, and lets you hand different tokens to different clients so one can be revoked without affecting the others.

This is a flat shared-secret check, not OAuth — it answers “does this request have the secret,” not “who is this user” (no per-user scopes or audit trail). If you need real identity-based authorization, front DBHub with your own OAuth-aware proxy or IdP-integrated gateway instead.

—dsn

string

Database connection string (Data Source Name). Format: database_type://username:password@host:port/database_name?options. Env: DSN (see the resolution order at the top of this page).

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:secret@sqlserver.corp.local:1433/mydb?authentication=ntlm&domain=CORP

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

Integrated security (a trusted connection using the logged-in Windows user, with no username/password in the DSN) is not supported. DBHub uses the pure-JS tedious driver, which has no SSPI/Kerberos support. Note that authentication=ntlm still requires an explicit username and password in the DSN, so it is not a trusted connection. Use SQL authentication or, for Azure SQL, Azure AD instead.

# 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`, `verify-ca`, `verify-full`	`?sslmode=require`
`sslrootcert`	PostgreSQL	CA certificate path (requires `verify-ca` or `verify-full`)	`?sslrootcert=~/.ssl/ca.pem`
`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	`disable`	`require`	`verify-ca`	`verify-full`	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.
sslmode=verify-ca: SSL with CA certificate verification, but no hostname check. PostgreSQL only. Use sslrootcert to specify the CA certificate path.
sslmode=verify-full: SSL with CA certificate and hostname verification. PostgreSQL only. Use sslrootcert to specify the CA certificate path.

# Examples
postgres://user:password@localhost:5432/dbname?sslmode=disable
postgres://user:password@localhost:5432/dbname?sslmode=require
postgres://user:password@rds-host:5432/dbname?sslmode=verify-ca&sslrootcert=~/.ssl/rds-ca.pem
sqlserver://jsmith:secret@localhost:1433/mydb?authentication=ntlm&domain=CORP

Environment Variables (Alternative to —dsn)

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

string

Instance identifier to suffix tool names. Useful when running multiple DBHub instances (e.g., in Cursor). Env: ID.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

boolean

default:"false"

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

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

—config

string

Path to a TOML configuration file, for managing multiple database connections and advanced configurations.

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

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

A TOML file defines its own sources and source IDs, so --config is mutually exclusive with --dsn and --id. Use either a TOML file or command-line/environment configuration.

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, or a base64-encoded private key. 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"

# SSH config alias (resolves host, user, key, and ProxyJump from ~/.ssh/config)
npx @bytebase/dbhub@latest --dsn "..." --ssh-host mybastion

# Base64-encoded private key (useful in containerized/cloud environments)
export SSH_KEY=$(base64 < ~/.ssh/id_rsa)
npx @bytebase/dbhub@latest --dsn "..." \
  --ssh-host bastion.example.com --ssh-user ubuntu

--ssh-key / SSH_KEY accepts either a file path or a base64-encoded private key. DBHub automatically detects the format: it first tries to read the value as a file path, and if that fails, decodes it as base64.
When --ssh-host is a plain alias (no dots, not an IP address), DBHub automatically resolves it from ~/.ssh/config, reading the HostName, User, IdentityFile, and ProxyJump directives. Explicit flags always override values from the config file.
ProxyJump hops that are themselves ~/.ssh/config aliases are resolved recursively — each hop uses its own HostName/User/Port/IdentityFile (and its own nested ProxyJump), matching how ssh connects. Cyclic ProxyJump chains are rejected with an error.
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`)
`--host`	`DBHUB_HOST`	string	HTTP bind address (http transport only, default: `0.0.0.0`)
`--allowed-hosts`	`DBHUB_ALLOWED_HOSTS`	string	Extra hostnames accepted in Host/Origin headers (http transport only, default: loopback + this machine)
`--auth-token`	`DBHUB_AUTH_TOKEN`	string	Comma-separated bearer token(s) required on requests (http transport only, default: auth disabled)
`--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 or base64-encoded key
`--ssh-passphrase`	`SSH_PASSPHRASE`	string	SSH key passphrase
`--ssh-proxy-jump`	`SSH_PROXY_JUMP`	string	ProxyJump hosts

Getting Started

MCP Tools

Workbench

Configuration

—transport

—port

—host

—allowed-hosts

—auth-token

—dsn

—id

—demo

—config

SSH Tunnel Options

Quick Reference

​—transport

​—port

​—host

​—allowed-hosts

​—auth-token

​—dsn

​—id

​—demo

​—config

​SSH Tunnel Options

​Quick Reference

—transport

—port

—host

—allowed-hosts

—auth-token

—dsn

—id

—demo

—config

SSH Tunnel Options

Quick Reference