DBHub

--- title: "Server Options" --- ## Database Connection ### 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 # Azure AD authentication 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> **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 ``` ### Environment Variables Recommended for databases with complex passwords containing special characters: <ParamField path="DB_TYPE" type="string" env="DB_TYPE"> Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite` </ParamField> <ParamField path="DB_HOST" type="string" env="DB_HOST"> Database server hostname (not needed for SQLite) </ParamField> <ParamField path="DB_PORT" type="number" env="DB_PORT"> Database server port. Default: PostgreSQL (`5432`), MySQL/MariaDB (`3306`), SQL Server (`1433`) </ParamField> <ParamField path="DB_USER" type="string" env="DB_USER"> Database username (not needed for SQLite) </ParamField> <ParamField path="DB_PASSWORD" type="string" env="DB_PASSWORD"> Database password (not needed for SQLite). Supports special characters without URL encoding. </ParamField> <ParamField path="DB_NAME" type="string" env="DB_NAME"> Database name or SQLite file path </ParamField> ```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 ``` </ParamField> ## Execution Controls ### readonly <ParamField path="--readonly" type="boolean" env="READONLY" default="false"> Restrict SQL execution to read-only operations. ```bash npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/mydb" ``` See [Read-Only Mode](/tools/execute-sql#read-only-mode) for details on allowed operations. </ParamField> ### max-rows <ParamField path="--max-rows" type="number" env="MAX_ROWS"> Limit the number of rows returned from SELECT queries. ```bash npx @bytebase/dbhub --max-rows 1000 --dsn "..." ``` See [Row Limiting](/tools/execute-sql#row-limiting) for details on how limits are applied. </ParamField> ## General ### 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, 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 | ```bash # 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 "..." ``` </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 --transport http --port 3000 --dsn "..." ``` </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 --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 <Note> 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. </Note> </ParamField> ### config <ParamField path="--config" type="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. ```bash npx @bytebase/dbhub --config ./dbhub.toml --transport http --port 8080 ``` See [Multi-Database Setup](/config/multi-database) for TOML configuration details. </ParamField> ### demo <ParamField path="--demo" type="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. ```bash npx @bytebase/dbhub --demo --transport http --port 8080 ``` </ParamField> ## SSH Tunnel ### ssh-host <ParamField path="--ssh-host" type="string" env="SSH_HOST"> SSH server hostname for tunnel connection. Can also use SSH config host aliases from `~/.ssh/config`. ```bash npx @bytebase/dbhub \ --dsn "postgres://user:pass@database.internal:5432/mydb" \ --ssh-host bastion.example.com ``` See [SSH Tunnel](/features/ssh-tunnel) for detailed SSH configuration examples. </ParamField> ### ssh-port <ParamField path="--ssh-port" type="number" env="SSH_PORT" default="22"> SSH server port. ```bash npx @bytebase/dbhub \ --dsn "..." \ --ssh-host bastion.example.com \ --ssh-port 2222 ``` </ParamField> ### ssh-user <ParamField path="--ssh-user" type="string" env="SSH_USER"> SSH username. ```bash npx @bytebase/dbhub \ --dsn "..." \ --ssh-host bastion.example.com \ --ssh-user ubuntu ``` </ParamField> ### ssh-password <ParamField path="--ssh-password" type="string" env="SSH_PASSWORD"> SSH password for password authentication. ```bash npx @bytebase/dbhub \ --dsn "..." \ --ssh-host bastion.example.com \ --ssh-user ubuntu \ --ssh-password mypassword ``` </ParamField> ### ssh-key <ParamField path="--ssh-key" type="string" env="SSH_KEY"> 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. ```bash npx @bytebase/dbhub \ --dsn "..." \ --ssh-host bastion.example.com \ --ssh-user ubuntu \ --ssh-key ~/.ssh/id_rsa ``` </ParamField> ### ssh-passphrase <ParamField path="--ssh-passphrase" type="string" env="SSH_PASSPHRASE"> Passphrase for encrypted SSH private key. ```bash npx @bytebase/dbhub \ --dsn "..." \ --ssh-host bastion.example.com \ --ssh-user ubuntu \ --ssh-key ~/.ssh/id_rsa \ --ssh-passphrase mykeypassphrase ``` </ParamField> ## Configuration Priority DBHub follows this priority order for configuration: 1. **Command-line arguments** (highest priority) 2. **TOML config file** (if `--config` is provided or `./dbhub.toml` exists) 3. **Environment variables** 4. **`.env` files** (`.env.local` in development, `.env` in production) ### Mutually Exclusive Options <Note> **`--config` (TOML) is mutually exclusive with:** - `--dsn` - TOML configuration defines database connections directly - `--id` - TOML configuration defines source IDs directly in the file - `--readonly` - TOML configuration defines readonly mode per-source using `readonly = true` If using TOML config, remove these flags. If you need `--id`, `--dsn`, or `--readonly`, use command-line/environment configuration instead. </Note> ## 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 | <Note> *Required unless using `--demo` or `--config` </Note>