Documentation Index
Fetch the complete documentation index at: https://dbhub.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 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, workbench, and API.
| 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
HTTP server port. Only used when --transport=http. Ignored for stdio transport.npx @bytebase/dbhub@latest --transport http --port 3000 --dsn "..."
—dsn
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: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
# 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:
| 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 |
| 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
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
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"
execute_sql_prod and execute_sql_staging toolsCannot 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
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
--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, 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) |
# 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.
- 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 or base64-encoded key |
--ssh-passphrase | SSH_PASSPHRASE | string | SSH key passphrase |
--ssh-proxy-jump | SSH_PROXY_JUMP | string | ProxyJump hosts |
