DBHub

--- title: "Command-Line Options" --- DBHub supports three configuration methods with the following priority order: 1. **Command-line arguments** (highest priority) 2. **TOML configuration file** (if `--config` is provided or `./dbhub.toml` exists) 3. **Environment variables** 4. **`.env` files** (`.env.local` in development, `.env` in production) This page covers command-line flags and environment variables. For TOML configuration, see [TOML Configuration](/config/toml). Command-line flags are passed when starting DBHub. These have the highest priority and override all other configuration methods. ### --transport <ParamField path="--transport" type="string" env="TRANSPORT" default="stdio"> Transport protocol for [MCP communication](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports). **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 | ```bash # 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 "..." ``` </ParamField> ### --port <ParamField path="--port" type="number" env="PORT" default="8080"> HTTP server port. Only used when `--transport=http`. Ignored for stdio transport. ```bash npx @bytebase/dbhub@latest --transport http --port 3000 --dsn "..." ``` </ParamField> ### --dsn <ParamField path="--dsn" type="string" env="DSN"> Database connection string (Data Source Name). Format: `database_type://username:password@host:port/database_name?options` <Tabs> <Tab title="PostgreSQL"> ```bash # Format: postgres://[user]:[password]@[host]:[port]/[database]?[options] postgres://myuser:mypassword@localhost:5432/mydb ``` </Tab> <Tab title="MySQL"> ```bash # Format: mysql://[user]:[password]@[host]:[port]/[database]?[options] mysql://root:password@localhost:3306/mydb ``` </Tab> <Tab title="MariaDB"> ```bash # Format: mariadb://[user]:[password]@[host]:[port]/[database]?[options] mariadb://root:password@localhost:3306/mydb ``` </Tab> <Tab title="SQL Server"> ```bash # 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 ``` </Tab> <Tab title="SQLite"> ```bash # 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: ``` </Tab> </Tabs> **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. ```bash # 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 ``` </ParamField> **Environment Variables (Alternative to --dsn)** <ParamField path="DB_*" type="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 | ```bash 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 ``` </ParamField> ### --id <ParamField path="--id" type="string" env="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. ```bash 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 <Warning> 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. </Warning> </ParamField> ### --demo <ParamField path="--demo" type="boolean" default="false"> Run DBHub with a bundled SQLite sample "employee" database for testing. ```bash npx @bytebase/dbhub@latest --demo --transport http --port 8080 ``` </ParamField> ### --config <ParamField path="--config" type="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. ```bash npx @bytebase/dbhub@latest --config ./dbhub.toml --transport http --port 8080 ``` See [TOML Configuration](/config/toml) for complete configuration reference including source options, tool options, SSH tunnels, and custom tools. <Warning> **`--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. </Warning> </ParamField> ### 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:** ```bash # 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" ``` <Note> - 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 </Note> ## 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 |