TOML Configuration

TOML configuration is the recommended way to configure DBHub for multi-database setups and advanced configurations. It provides more flexibility than command-line options or environment variables.

Load a TOML file with --config:

npx @bytebase/dbhub@latest --config ./dbhub.toml

A TOML file defines its own database sources, so --config and --dsn cannot be combined. Environment variables such as DSN and DB_* remain available to the file through ${VAR} interpolation.

Overview

TOML configuration enables:

Multi-database support: Connect to multiple databases from a single DBHub instance
Per-source settings: Configure timeouts, SSL, SSH tunnels, and lazy connections individually per database
Per-tool settings: Apply different restrictions (readonly, max_rows) per tool
Custom tools: Define reusable, parameterized SQL operations as MCP tools
Environment variable interpolation: Use ${VAR} syntax to avoid hardcoding credentials
Hot reload: Automatically detect config changes and reload connections without restarting

Hot Reload

When using TOML configuration, DBHub automatically watches dbhub.toml for changes and reloads database connections without requiring a server restart. How it works:

DBHub detects file changes and waits 500ms (debounce) to handle editors that write in multiple steps
The new configuration is parsed and validated — if invalid, existing connections are preserved
All database connections are disconnected and reconnected with the new configuration
If reconnection fails, DBHub automatically rolls back to the previous working configuration

# Edit dbhub.toml while DBHub is running — changes apply automatically
# No server restart needed

STDIO transport limitation: In STDIO mode (the default for Claude Desktop, Cursor, etc.), hot reload updates the underlying database connections and tool settings, but clients won’t see newly added or removed tools until a full server restart. This is because STDIO clients discover tools once at startup.HTTP transport (--transport http) creates a fresh server per request, so all changes — including added/removed tools — take effect immediately.

Environment Variable Interpolation

Use ${VAR_NAME} syntax to reference environment variables in any string value. Variables are resolved from the process environment at config load time. This lets teams share a single dbhub.toml without hardcoding credentials:

dbhub.toml

[[sources]]
id = "production"
dsn = "postgres://readonly_user:${DB_PASSWORD}@db.example.com:5432/mydb"

[[sources]]
id = "staging"
type = "mysql"
host = "${STAGING_HOST}"
database = "myapp"
user = "root"
password = "${STAGING_PASSWORD}"
ssh_host = "bastion.example.com"
ssh_password = "${SSH_PASSWORD}"

# Set env vars, then start DBHub
export DB_PASSWORD="s3cret"
export STAGING_HOST="staging.example.com"
export STAGING_PASSWORD="staging_pass"
export SSH_PASSWORD="ssh_pass"
npx @bytebase/dbhub@latest --config dbhub.toml

Unresolved variables (where the environment variable is not set) are left as the literal ${VAR_NAME} string. No error is thrown for missing variables.

Configuration Structure

A TOML configuration file has two main sections:

[[sources]] - Database connection definitions
[[tools]] - Tool configuration (execution settings, custom tools)

Create dbhub.toml in your project directory, then load it with --config ./dbhub.toml:

dbhub.toml

# Define database sources
[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
connection_timeout = 60

[[sources]]
id = "staging"
dsn = "mysql://root:pass@localhost:3306/myapp"

# Configure tools for each source
[[tools]]
name = "execute_sql"
source = "production"
readonly = true
max_rows = 1000

[[tools]]
name = "execute_sql"
source = "staging"
readonly = false

Start DBHub:

# Automatically loads ./dbhub.toml
npx @bytebase/dbhub@latest --transport http --port 8080

# Or specify custom location
npx @bytebase/dbhub@latest --config=/path/to/config.toml

Source Options

Sources define database connections. Each source represents a database that DBHub can connect to.

id

string

required

Required. Unique identifier for this data source. Used for routing tool calls and in tool names.

[[sources]]
id = "production"

description

string

Human-readable description of this data source. Helps AI models understand the purpose and contents of each database when multiple sources are configured.

[[sources]]
id = "production"
description = "Production PostgreSQL database containing customer and order data"
dsn = "postgres://user:pass@localhost:5432/mydb"

dsn

string

required

Required. Database connection string. Same format as command-line --dsn.

Using DSN
Individual Parameters

[[sources]]
id = "production"
dsn = "postgres://user:pass@prod.example.com:5432/myapp?sslmode=require"

[[sources]]
id = "staging"
dsn = "mysql://root:pass@localhost:3306/myapp_staging"

[[sources]]
id = "local"
dsn = "sqlite:///./dev.db"

Alternative to DSN: specify connection details individually. Useful for passwords with special characters (no URL encoding needed).

# PostgreSQL with SSL
[[sources]]
id = "production"
type = "postgres"
host = "prod.example.com"
port = 5432
database = "myapp"
user = "app_user"
password = "p@ss:word"  # No URL encoding needed
sslmode = "require"

# SQL Server with named instance
[[sources]]
id = "sqlserver_dev"
type = "sqlserver"
host = "localhost"
port = 1433
database = "mydb"
user = "sa"
password = "YourPassword123"
instanceName = "SQLEXPRESS"

# SQL Server with NTLM
[[sources]]
id = "corp_sqlserver"
type = "sqlserver"
host = "sqlserver.corp.local"
database = "app_db"
user = "jsmith"
password = "secret"
authentication = "ntlm"
domain = "CORP"

# SQL Server with Azure AD (no password)
[[sources]]
id = "azure_sqlserver"
type = "sqlserver"
host = "myserver.database.windows.net"
database = "mydb"
user = "admin@tenant.onmicrosoft.com"
authentication = "azure-active-directory-access-token"

Mixing dsn with individual fields. A dsn already encodes the connection identity (type, host, port, database, user, password). Fields that can also live in the DSN query string — sslmode, sslrootcert, instanceName, authentication, domain — may be set alongside a dsn and are applied when the DSN omits them.If such a field is set to a value that contradicts the DSN (e.g. dsn = "...?sslmode=disable" together with sslmode = "require", or a host/user/database that differs from the DSN), DBHub rejects the configuration at startup rather than silently ignoring the field. Set each value in only one place, or make the two values match.This includes a field the DSN omits entirely: a database alongside a DSN that names none is rejected too, since the field is never injected into the DSN.

connection_timeout

number

Connection timeout in seconds. The maximum time to wait when establishing a database connection.Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite).

[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
connection_timeout = 60  # 60 seconds

This option is only available via TOML. There is no CLI flag for connection timeout.

query_timeout

number

Query timeout in seconds. The maximum time to wait for a query to complete before timing out.Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite).

[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
query_timeout = 30  # 30 seconds

This option is only available via TOML. There is no CLI flag for query timeout.

lazy

boolean

default:"false"

Defer database connection until the first query. When enabled, the connection is not established at server startup but instead when a tool first accesses this source.This is useful for remote databases (e.g., RDS, Cloud SQL) where you want to avoid unnecessary connection overhead if the database may not be queried during a session.

[[sources]]
id = "production"
dsn = "postgres://user:pass@prod-db.example.com:5432/mydb"
lazy = true  # Connection deferred until first query

Startup behavior:

Without lazy: Connection established immediately, errors shown at startup
With lazy = true: Source registered but not connected, connection errors appear on first query

When a lazy source is accessed for the first time, there will be a brief delay as the connection is established. Connection errors will appear in tool responses rather than at startup.

sslmode

string

SSL/TLS mode for database connections.Options:

disable - No SSL/TLS encryption. Data is transmitted in plaintext.
require - SSL/TLS encryption enabled, but server certificate is not verified.
verify-ca - SSL with CA certificate verification (no hostname check). PostgreSQL only.
verify-full - SSL with CA certificate and hostname verification. PostgreSQL only.

Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite). The verify-ca and verify-full modes are only supported for PostgreSQL.

# Basic SSL (all network databases)
[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
sslmode = "require"

# Certificate verification (PostgreSQL only)
[[sources]]
id = "rds_postgres"
type = "postgres"
host = "mydb.abc123.eu-west-1.rds.amazonaws.com"
port = 5432
database = "myapp"
user = "app_user"
password = "secure_password"
sslmode = "verify-ca"
sslrootcert = "~/.ssl/rds-combined-ca-bundle.pem"

Can also be set via DSN query parameter: ?sslmode=require or ?sslmode=verify-ca&sslrootcert=/path/to/ca.pem

sslrootcert

string

Path to the CA certificate file for SSL certificate verification. Required when using sslmode=verify-ca or sslmode=verify-full.Supports ~/ path expansion.PostgreSQL only.

[[sources]]
id = "rds_postgres"
type = "postgres"
host = "mydb.abc123.eu-west-1.rds.amazonaws.com"
port = 5432
database = "myapp"
user = "app_user"
password = "secure_password"
sslmode = "verify-full"
sslrootcert = "~/.ssl/rds-combined-ca-bundle.pem"

Can also be set via DSN query parameter: ?sslmode=verify-full&sslrootcert=/path/to/ca.pem

instanceName

string

SQL Server named instance. Use when connecting to a specific SQL Server instance (e.g., SQLEXPRESS, ENV1).SQL Server only.

[[sources]]
id = "sqlserver_env1"
dsn = "sqlserver://sa:password@localhost:1433/mydb"
instanceName = "ENV1"

Can also be set via DSN query parameter: ?instanceName=ENV1

authentication

string

SQL Server authentication method. SQL Server only.Options:

ntlm - Windows/NTLM authentication. Requires domain parameter.
azure-active-directory-access-token - Azure AD authentication. Token is fetched automatically using Azure SDK.

[[sources]]
id = "sqlserver_corp"
dsn = "sqlserver://user:pass@localhost:1433/mydb"
authentication = "ntlm"
domain = "CORP"

Can also be set via DSN query parameter: ?authentication=ntlm&domain=CORP

domain

string

Windows domain for NTLM authentication. Required when authentication=ntlm. SQL Server only.

[[sources]]
id = "sqlserver_corp"
dsn = "sqlserver://user:pass@localhost:1433/mydb"
authentication = "ntlm"
domain = "CORP"

search_path

string

Comma-separated list of PostgreSQL schema names to set as the session search_path. The first schema in the list becomes the default schema for all discovery methods (getTables, getTableSchema, etc.).PostgreSQL only.

[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
search_path = "myschema,public"

Without search_path, DBHub defaults to the public schema for all schema discovery operations.

This option is only available via TOML. It is not supported as a DSN query parameter.

timezone

string

Controls how the driver interprets DATETIME values. Accepts "Z" (UTC), "local", or an offset such as "+09:00".MySQL / MariaDB only.

[[sources]]
id = "production"
dsn = "mysql://user:pass@localhost:3306/mydb"
timezone = "+09:00"

Passed through to the underlying driver’s timezone connection option. DATETIME is timezone-naive, so the driver needs to know which timezone the stored values represent in order to build the correct Date. When unset, the driver defaults to "local" (the host’s timezone), which yields an incorrect instant whenever the host timezone differs from the data’s. Set this to the timezone the DATETIME values are stored in (e.g. "+09:00") so they are converted to the correct UTC instant.

This option is only available via TOML. It is not supported as a DSN query parameter.

charset

string

Sets the connection character set (e.g. "utf8mb4"). On its own, the connection uses that character set’s default collation; combine with collation to pick a specific one.MySQL / MariaDB only.

[[sources]]
id = "production"
dsn = "mysql://user:pass@localhost:3306/mydb"
charset = "utf8mb4"

This option is only available via TOML. It is not supported as a DSN query parameter.

collation

string

Sets the connection collation (e.g. "utf8mb4_0900_ai_ci"), which determines how string literals and comparisons are ordered/compared on the connection (collation_connection). Can be set on its own or alongside charset; a collation already implies its character set, so when both are given the collation is authoritative.MySQL / MariaDB only.

[[sources]]
id = "production"
dsn = "mysql://user:pass@localhost:3306/mydb"
collation = "utf8mb4_0900_ai_ci"

When neither charset nor collation is set, the driver uses its built-in default (mysql2 defaults to utf8mb4_unicode_ci), which may not match your database’s collation. Set this to align the connection collation with your schema (e.g. MySQL 8’s utf8mb4_0900_ai_ci).

This option is only available via TOML. It is not supported as a DSN query parameter.

SSH Tunnel Options

group

SSH tunnel configuration for connecting to databases through bastion/jump hosts. Available fields: ssh_host, ssh_port, ssh_user, ssh_password, ssh_key, ssh_passphrase, ssh_proxy_jump.

[[sources]]
id = "production"
dsn = "postgres://user:pass@database.internal:5432/mydb"

# SSH tunnel configuration
ssh_host = "bastion.example.com"
ssh_port = 22
ssh_user = "ubuntu"
ssh_key = "~/.ssh/id_rsa"  # File path or base64-encoded key
ssh_passphrase = "my_key_passphrase"  # Optional
ssh_proxy_jump = "jump1.example.com,admin@jump2.internal:2222"

ssh_key accepts either a file path or a base64-encoded private key. DBHub automatically detects the format.See Command-Line Options - SSH Tunnel for complete documentation and examples.

Tool Options

Tools define MCP tools (like execute_sql) with specific execution settings. Tool options control how tools execute queries, not what databases they connect to.

Tool options cannot be set via command-line flags. They are only available in TOML configuration in the [[tools]] section.

name

string

required

Required. Tool name. Built-in tools are execute_sql, search_objects, and the opt-in explain_sql (see explain_sql) and health_check (see health_check); any other name defines a custom tool.

[[tools]]
name = "execute_sql"
source = "production"

source

string

required

Required. The source ID this tool should use. Must match an id from the [[sources]] section.

[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"

[[tools]]
name = "execute_sql"
source = "production"  # References the source above

readonly

boolean

default:"false"

Restrict SQL execution to read-only operations (SELECT, SHOW, DESCRIBE, EXPLAIN, PRAGMA). Write operations like INSERT, UPDATE, DELETE are blocked.

[[tools]]
name = "execute_sql"
source = "production"
readonly = true  # Read-only mode

This is a tool-level setting, not a source-level setting. Configure it in the [[tools]] section, not in [[sources]].

See Execute SQL documentation for more details.

max_rows

number

Maximum number of rows to return from SELECT queries. Queries returning more rows will be truncated.

[[tools]]
name = "execute_sql"
source = "production"
max_rows = 1000  # Limit to 1000 rows

This is a tool-level setting, not a source-level setting. Configure it in the [[tools]] section, not in [[sources]].

See Execute SQL documentation for more details.

statement

string

Optional predefined SQL statement for custom tools. Enables creating reusable, parameterized database operations that are automatically registered as MCP tools.

[[tools]]
name = "get_user_by_id"
description = "Retrieve user details by their unique ID"
source = "production"
statement = "SELECT id, name, email, created_at FROM users WHERE id = $1"

[[tools.parameters]]
name = "user_id"
type = "integer"
description = "The unique user ID"

See Custom Tools documentation for examples and patterns.

description

string

Required for custom tools. Human-readable description of the tool’s purpose. Helps AI models understand when and how to use the tool.

[[tools]]
name = "search_employees"
description = "Search employees by name with configurable result limit"
source = "production"
statement = "SELECT emp_no, first_name, last_name FROM employee WHERE first_name ILIKE '%' || $1 || '%' LIMIT $2"

parameters

array

Parameter definitions for custom tools. Each parameter defines a typed input that will be validated before execution.Parameter Fields:

Field	Type	Required	Description
`name`	string	✅	Parameter name (must match SQL placeholder order)
`type`	string	✅	Data type: `string`, `integer`, `float`, `boolean`, `array`
`description`	string	✅	Description of the parameter’s purpose
`required`	boolean	❌	Whether the parameter is required (default: `true`)
`default`	any	❌	Default value if parameter not provided
`allowed_values`	array	❌	List of allowed values (creates enum validation)

Parameter Placeholders by Database:

Database	Syntax	Example
PostgreSQL	`$1`, `$2`, `$3`	`WHERE id = $1 AND status = $2`
MySQL	`?`, `?`, `?`	`WHERE id = ? AND status = ?`
MariaDB	`?`, `?`, `?`	`WHERE id = ? AND status = ?`
SQLite	`?`, `?`, `?`	`WHERE id = ? AND status = ?`
SQL Server	`@p1`, `@p2`, `@p3`	`WHERE id = @p1 AND status = @p2`

The number of parameters must match the number of placeholders in your SQL statement. Validation occurs at server startup.

Basic Parameter:

[[tools.parameters]]
name = "user_id"
type = "integer"
description = "The unique user ID"

Optional Parameter with Default:

[[tools.parameters]]
name = "limit"
type = "integer"
description = "Maximum number of results to return"
default = 10

Constrained Parameter (Enum):

[[tools.parameters]]
name = "status"
type = "string"
description = "Order status"
allowed_values = ["pending", "completed", "cancelled"]

Optional Parameter (Nullable):

[[tools.parameters]]
name = "status"
type = "string"
description = "Optional status filter"
required = false
allowed_values = ["pending", "processing", "shipped", "delivered"]

Use optional parameters with SQL COALESCE to create flexible filters:

WHERE status = COALESCE($1, status)
-- Or for PostgreSQL with explicit NULL handling:
WHERE ($1::text IS NULL OR status = $1)

Complete Example

dbhub.toml

# Multi-database configuration with different tool settings

[[sources]]
id = "production"
dsn = "postgres://user:pass@db.prod.internal:5432/mydb"
lazy = true  # Defer connection until first query
connection_timeout = 60
query_timeout = 30
sslmode = "require"

# Production SSH tunnel through bastion
ssh_host = "bastion.prod.example.com"
ssh_user = "deploy"
ssh_key = "~/.ssh/prod_key"

[[sources]]
id = "staging"
dsn = "postgres://user:pass@db.staging.internal:5432/mydb"
connection_timeout = 30
query_timeout = 15

# Staging SSH tunnel
ssh_host = "bastion.staging.example.com"
ssh_user = "ubuntu"
ssh_key = "~/.ssh/staging_key"

[[sources]]
id = "local_sqlite"
dsn = "sqlite:///./data/local.db"

# Production tool - read-only with row limits
[[tools]]
name = "execute_sql"
source = "production"
readonly = true
max_rows = 1000

# Staging tool - full access with row limits
[[tools]]
name = "execute_sql"
source = "staging"
readonly = false
max_rows = 5000

# Local tool - full access, unlimited rows
[[tools]]
name = "execute_sql"
source = "local_sqlite"
readonly = false

# Custom tool - search employees with parameters
[[tools]]
name = "search_employees"
description = "Search employees by name with configurable result limit"
source = "production"
statement = "SELECT emp_no, first_name, last_name FROM employee WHERE first_name ILIKE '%' || $1 || '%' LIMIT $2"

[[tools.parameters]]
name = "search_term"
type = "string"
description = "Name to search for (case-insensitive partial match)"

[[tools.parameters]]
name = "limit"
type = "integer"
description = "Maximum number of results"
default = 10

Quick Reference

Source Options

Field	Type	Required	Description
`id`	string	✅	Unique source identifier
`description`	string	❌	Human-readable description of the data source
`dsn`	string	✅	Database connection string
`lazy`	boolean	❌	Defer connection until first query (default: `false`)
`connection_timeout`	number	❌	Connection timeout (seconds)
`query_timeout`	number	❌	Query timeout (seconds)
`sslmode`	string	❌	SSL mode: `disable`, `require`, `verify-ca`, `verify-full`
`sslrootcert`	string	❌	CA certificate path (PostgreSQL only, requires `verify-ca` or `verify-full`)
`instanceName`	string	❌	SQL Server named instance
`authentication`	string	❌	SQL Server auth method
`domain`	string	❌	Windows domain (NTLM)
`search_path`	string	❌	PostgreSQL schema search path (comma-separated)
`timezone`	string	❌	MySQL/MariaDB: `Z`, `local`, or offset like `+09:00`
`charset`	string	❌	MySQL/MariaDB: connection character set (`utf8mb4`)
`collation`	string	❌	MySQL/MariaDB: connection collation (`utf8mb4_0900_ai_ci`)
`ssh_host`	string	❌	SSH server hostname
`ssh_port`	number	❌	SSH server port (default: 22)
`ssh_user`	string	❌	SSH username
`ssh_password`	string	❌	SSH password
`ssh_key`	string	❌	SSH private key path or base64-encoded key
`ssh_passphrase`	string	❌	SSH key passphrase
`ssh_proxy_jump`	string	❌	ProxyJump hosts

Tool Options

Field	Type	Required	Description
`name`	string	✅	Tool name (e.g., `execute_sql`)
`source`	string	✅	Source ID to use
`description`	string	✅*	Tool description (*required for custom tools)
`statement`	string	❌	Predefined SQL for custom tools
`parameters`	array	❌	Parameter definitions for custom tools
`readonly`	boolean	❌	Read-only mode (default: `false`)
`max_rows`	number	❌	Max rows limit (default: unlimited)

Getting Started

MCP Tools

Workbench

Configuration

Overview

Hot Reload

Environment Variable Interpolation

Configuration Structure

Source Options

id

description

dsn

connection_timeout

query_timeout

lazy

sslmode

sslrootcert

instanceName

authentication

domain

search_path

timezone

charset

collation

SSH Tunnel Options

Tool Options

name

source

readonly

max_rows

statement

description

parameters

Complete Example

Quick Reference

Source Options

Tool Options

​Overview

​Hot Reload

​Environment Variable Interpolation

​Configuration Structure

​Source Options

​id

​description

​dsn

​connection_timeout

​query_timeout

​lazy

​sslmode

​sslrootcert

​instanceName

​authentication

​domain

​search_path

​timezone

​charset

​collation

​SSH Tunnel Options

​Tool Options

​name

​source

​readonly

​max_rows

​statement

​description

​parameters

​Complete Example

​Quick Reference

​Source Options

​Tool Options

Overview

Hot Reload

Environment Variable Interpolation

Configuration Structure

Source Options

id

description

dsn

connection_timeout

query_timeout

lazy

sslmode

sslrootcert

instanceName

authentication

domain

search_path

timezone

charset

collation

SSH Tunnel Options

Tool Options

name

source

readonly

max_rows

statement

description

parameters

Complete Example

Quick Reference

Source Options

Tool Options