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.
Overview
TOML configuration enables:
- Multi-database support: Connect to multiple databases from a single DBHub instance
- Per-source settings: Configure timeouts, SSL, and SSH tunnels individually per database
- Per-tool settings: Apply different restrictions (readonly, max_rows) per tool
- Custom tools: Define reusable, parameterized SQL operations as MCP tools
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:
# 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
# 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.
Required. Unique identifier for this data source. Used for routing tool calls and in tool names.[[sources]]
id = "production"
dsn
Required. Database connection string. Same format as command-line --dsn. Using DSN
Individual Parameters
[[sources]]
id = "production"
dsn = "postgres://user:[email protected]: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 = "[email protected]"
authentication = "azure-active-directory-access-token"
connection_timeout
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
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.
sslmode
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.
Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite).[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
sslmode = "require"
Can also be set via DSN query parameter: ?sslmode=require
instanceName
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
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
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"
SSH Tunnel Options
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:[email protected]:5432/mydb"
# SSH tunnel configuration
ssh_host = "bastion.example.com"
ssh_port = 22
ssh_user = "ubuntu"
ssh_key = "~/.ssh/id_rsa"
ssh_passphrase = "my_key_passphrase" # Optional
ssh_proxy_jump = "jump1.example.com,[email protected]:2222"
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
Required. Tool name. Currently, the primary tool is execute_sql.[[tools]]
name = "execute_sql"
source = "production"
source
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
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]].
max_rows
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]].
statement
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"
description
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
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) |
| 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.
[[tools.parameters]]
name = "user_id"
type = "integer"
description = "The unique user ID"
[[tools.parameters]]
name = "limit"
type = "integer"
description = "Maximum number of results to return"
default = 10
[[tools.parameters]]
name = "status"
type = "string"
description = "Order status"
allowed_values = ["pending", "completed", "cancelled"]
[[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
# Multi-database configuration with different tool settings
[[sources]]
id = "production"
dsn = "postgres://user:[email protected]:5432/mydb"
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:[email protected]: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 |
dsn | string | ✅ | Database connection string |
connection_timeout | number | ❌ | Connection timeout (seconds) |
query_timeout | number | ❌ | Query timeout (seconds) |
sslmode | string | ❌ | SSL mode: disable, require |
instanceName | string | ❌ | SQL Server named instance |
authentication | string | ❌ | SQL Server auth method |
domain | string | ❌ | Windows domain (NTLM) |
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 |
ssh_passphrase | string | ❌ | SSH key passphrase |
ssh_proxy_jump | string | ❌ | ProxyJump hosts |
| 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) |
