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

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

Execution Controls

readonly

--readonly

boolean

default:"false"

Restrict SQL execution to read-only operations.

npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/mydb"

See Read-Only Mode for details on allowed operations.

max-rows

--max-rows

number

Limit the number of rows returned from SELECT queries.

npx @bytebase/dbhub --max-rows 1000 --dsn "..."

See Row Limiting for details on how limits are applied.

General

transport

--transport

string

default:"stdio"

Transport protocol for MCP communication.Options:

stdio - For desktop tools (Claude Desktop, Claude Code, Cursor with stdio config)
http - For browser and network clients, streamable HTTP transport

# stdio (default) - for Claude Desktop, Claude Code
npx @bytebase/dbhub --transport stdio --dsn "..."

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

port

--port

number

default:"8080"

HTTP server port. Only applicable when using --transport=http.

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

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:pass@database.internal: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)

--config (TOML) and --dsn (CLI) are mutually exclusive. If --config is provided, TOML configuration takes precedence. You cannot combine --dsn with TOML configuration.

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
`--readonly`	`READONLY`	boolean	`false`	Restrict to read-only operations
`--max-rows`	`MAX_ROWS`	number	-	Limit SELECT query results
`--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

MCP Components

Integrations

Configuration

Server Options

Database Connection

dsn

Environment Variables

Execution Controls

readonly

max-rows

General

transport

port

id

config

demo

SSH Tunnel

ssh-host

ssh-port

ssh-user

ssh-password

ssh-key

ssh-passphrase

Configuration Priority

Quick Reference

Getting Started

MCP Components

Integrations

Configuration

​Database Connection

​dsn

​Environment Variables

​Execution Controls

​readonly

​max-rows

​General

​transport

​port

​id

​config

​demo

​SSH Tunnel

​ssh-host

​ssh-port

​ssh-user

​ssh-password

​ssh-key

​ssh-passphrase

​Configuration Priority

​Quick Reference

Database Connection

dsn

Environment Variables

Execution Controls

readonly

max-rows

General

transport

port

id

config

demo

SSH Tunnel

ssh-host

ssh-port

ssh-user

ssh-password

ssh-key

ssh-passphrase

Configuration Priority

Quick Reference