Skip to content

command-line.mdx

Latest commit

 

History

History
315 lines (244 loc) · 13.2 KB

command-line.mdx

File metadata and controls

315 lines (244 loc) · 13.2 KB
Raw
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.

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](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 
# 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 "..."

--host

HTTP bind address. Only used when `--transport=http`. Ignored for stdio transport. 
# 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 — DBHub does not authenticate HTTP clients.

--dsn

Database connection string (Data Source Name). Format: `database_type://username:password@host:port/database_name?options` ```bash # Format: postgres://[user]:[password]@[host]:[port]/[database]?[options] postgres://myuser:mypassword@localhost:5432/mydb ``` 
<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>

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)

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"

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

Run DBHub with a bundled SQLite sample "employee" database for testing. 
npx @bytebase/dbhub@latest --demo --transport http --port 8080

--config

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

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

**`--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)

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. - 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)
--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