dbhub.toml.example

# DBHub Multi-Database Configuration
#
# Documentation: https://dbhub.ai/config/toml
#
# Quick Start:
#   1. Copy this file to 'dbhub.toml' in your project directory
#   2. Uncomment and edit the sources you need
#   3. Delete or comment out sources you don't need
#
# Usage:
#   pnpm run dev                         # Uses ./dbhub.toml
#   pnpm run dev -- --config=/path/to/config.toml

# ============================================================================
# POSTGRESQL EXAMPLES (Local → Dev → Prod progression)
# ============================================================================

# Local PostgreSQL - DSN format (typical Docker/local dev setup)
[[sources]]
id = "local_pg"
description = "Local development database"
dsn = "postgres://postgres:postgres@localhost:5432/myapp"

# Local PostgreSQL - Individual parameters (use when password contains special characters like @, :, /)
# [[sources]]
# id = "local_pg"
# type = "postgres"
# host = "localhost"
# port = 5432
# database = "myapp"
# user = "postgres"
# password = "p@ss:word/123"
# sslmode = "disable"  # Optional: "disable" or "require"

# Local PostgreSQL with custom schema (non-public schema)
# [[sources]]
# id = "local_pg_custom_schema"
# dsn = "postgres://postgres:postgres@localhost:5432/myapp"
# search_path = "myschema,public"  # Comma-separated list of schemas; first is the default for discovery

# Development PostgreSQL (shared dev server)
# [[sources]]
# id = "dev_pg"
# dsn = "postgres://dev_user:dev_password@dev-db.internal.company.com:5432/myapp_dev?sslmode=require"
# connection_timeout = 30

# PostgreSQL on AWS RDS with IAM authentication (no password in config)
# [[sources]]
# id = "rds_pg_iam"
# type = "postgres"
# host = "mydb.abc123.eu-west-1.rds.amazonaws.com"
# port = 5432
# database = "myapp"
# user = "dbuser@example.com"
# aws_iam_auth = true
# aws_region = "eu-west-1"
# sslmode = "require"

# Production PostgreSQL (behind SSH bastion, lazy connection)
# [[sources]]
# id = "prod_pg"
# dsn = "postgres://app_user:secure_password@10.0.1.100:5432/myapp_prod?sslmode=require"
# lazy = true  # Defer connection until first query (avoids startup overhead for remote DBs)
# connection_timeout = 30
# # SSH tunnel configuration
# ssh_host = "bastion.company.com"
# ssh_port = 22
# ssh_user = "deploy"
# ssh_key = "~/.ssh/id_ed25519"
# # ssh_passphrase = "your_key_passphrase"  # If key is encrypted
# # ssh_keepalive_interval = 60  # Send keepalive every 60 seconds to prevent idle disconnects
# # ssh_keepalive_count_max = 3  # Disconnect after 3 missed responses

# Production PostgreSQL (multi-hop SSH through multiple jump hosts)
# [[sources]]
# id = "prod_pg_multihop"
# dsn = "postgres://app_user:secure_password@10.0.1.100:5432/myapp_prod?sslmode=require"
# # SSH tunnel with ProxyJump (connects through jump hosts in order)
# ssh_host = "internal-server.company.com"
# ssh_user = "deploy"
# ssh_key = "~/.ssh/id_ed25519"
# # ProxyJump: comma-separated list of jump hosts
# # Format: [user@]host[:port] - user/port optional, inherits from ssh_user if not specified
# # Note: While each jump host can have a different username, the same SSH key (or password)
# #       specified in ssh_key/ssh_password will be used for authentication to ALL hosts in the chain
# ssh_proxy_jump = "bastion.company.com,admin@jump2.internal:2222"

# ============================================================================
# MYSQL (Local development)
# ============================================================================

# [[sources]]
# id = "local_mysql"
# dsn = "mysql://root:mysql@localhost:3306/myapp"

# MySQL on AWS RDS with IAM authentication (no password in config)
# [[sources]]
# id = "rds_mysql_iam"
# type = "mysql"
# host = "mydb.abc123.eu-west-1.rds.amazonaws.com"
# port = 3306
# database = "myapp"
# user = "dbuser@example.com"
# aws_iam_auth = true
# aws_region = "eu-west-1"
# sslmode = "require"

# ============================================================================
# MARIADB (Local development)
# ============================================================================

# [[sources]]
# id = "local_mariadb"
# dsn = "mariadb://root:mariadb@localhost:3306/myapp"

# MariaDB on AWS RDS with IAM authentication (no password in config)
# [[sources]]
# id = "rds_mariadb_iam"
# type = "mariadb"
# host = "mydb.abc123.eu-west-1.rds.amazonaws.com"
# port = 3306
# database = "myapp"
# user = "dbuser@example.com"
# aws_iam_auth = true
# aws_region = "eu-west-1"
# sslmode = "require"

# ============================================================================
# SQL SERVER (Local development)
# ============================================================================

# [[sources]]
# id = "local_sqlserver"
# dsn = "sqlserver://sa:YourStrong@Passw0rd@localhost:1433/myapp"
# # For named instances, use:
# # dsn = "sqlserver://sa:YourStrong@Passw0rd@localhost:1433/myapp?instanceName=SQLEXPRESS"
# query_timeout = 60  # Query timeout in seconds (works for all databases except SQLite)

# SQL Server - Individual parameters (use when password contains special characters)
# [[sources]]
# id = "local_sqlserver"
# type = "sqlserver"
# host = "localhost"
# port = 1433
# database = "myapp"
# user = "sa"
# password = "YourStrong@Passw0rd"
# instanceName = "SQLEXPRESS"  # Optional: for named instances
# sslmode = "disable"          # Optional: "disable" or "require"

# SQL Server with Windows/NTLM authentication (DSN format)
# [[sources]]
# id = "corp_sqlserver"
# dsn = "sqlserver://jsmith:secret@sqlserver.corp.local:1433/app_db?authentication=ntlm&domain=CORP"

# SQL Server with Windows/NTLM authentication (individual parameters)
# [[sources]]
# id = "corp_sqlserver"
# type = "sqlserver"
# host = "sqlserver.corp.local"
# port = 1433
# database = "app_db"
# user = "jsmith"
# password = "secret"
# authentication = "ntlm"      # Required for Windows auth
# domain = "CORP"              # Required when authentication = "ntlm"

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

# ============================================================================
# SQLITE (Local file or in-memory)
# ============================================================================

# File-based SQLite
# [[sources]]
# id = "local_sqlite"
# dsn = "sqlite:///path/to/database.db"

# In-memory SQLite (great for testing)
# [[sources]]
# id = "memory_sqlite"
# dsn = "sqlite:///:memory:"

# ============================================================================
# TOOL CONFIGURATION (Optional)
# ============================================================================
#
# By default, all sources get 'execute_sql' and 'search_objects' tools enabled.
# Use [[tools]] entries to customize behavior per source.

# [[tools]]
# name = "execute_sql"
# source = "local_pg"
# readonly = true
# max_rows = 1000

# [[tools]]
# name = "search_objects"
# source = "local_pg"

# ============================================================================
# CUSTOM TOOLS (Optional)
# ============================================================================
#
# Define reusable SQL queries as MCP tools. Great for common operations.

# Example: Current department managers (PostgreSQL - no parameters)
# [[tools]]
# name = "current_managers"
# description = "List all current department managers"
# source = "local_pg"
# readonly = true       # Optional: restrict to read-only operations
# max_rows = 100        # Optional: limit result set size
# statement = """
#   SELECT e.emp_no, e.first_name, e.last_name, d.dept_name, dm.from_date
#   FROM dept_manager dm
#   JOIN employee e ON dm.emp_no = e.emp_no
#   JOIN department d ON dm.dept_no = d.dept_no
#   ORDER BY d.dept_name
# """

# Example: Search employees by salary range (PostgreSQL - required + optional parameter)
# [[tools]]
# name = "salary_search"
# description = "Find employees earning at least min_salary, optionally capped by max_salary"
# source = "local_pg"
# readonly = true       # Optional: restrict to read-only operations
# max_rows = 1000       # Optional: limit result set size
# statement = """
#   SELECT e.emp_no, e.first_name, e.last_name, s.amount as salary
#   FROM employee e
#   JOIN salary s ON e.emp_no = s.emp_no
#   WHERE s.amount >= $1
#     AND ($2::int IS NULL OR s.amount <= $2)
#   ORDER BY s.amount DESC
#   LIMIT 100
# """
#
# [[tools.parameters]]
# name = "min_salary"
# type = "integer"
# description = "Minimum salary (required)"
# required = true
#
# [[tools.parameters]]
# name = "max_salary"
# type = "integer"
# description = "Maximum salary (optional, defaults to no limit)"
# required = false

# Example: Delete employee salaries (PostgreSQL - with required parameter)
# [[tools]]
# name = "delete_employee_salaries"
# description = "Delete salary records for a specific employee"
# source = "local_pg"
# readonly = false  # Explicitly allow DELETE operations
# statement = "DELETE FROM salary WHERE emp_no = $1"
#
# [[tools.parameters]]
# name = "emp_no"
# type = "integer"
# description = "Employee number"
# required = true

# Example: Update employee department (PostgreSQL - with two required parameters)
# [[tools]]
# name = "update_employee_department"
# description = "Update an employee's department assignment"
# source = "local_pg"
# readonly = false  # Explicitly allow UPDATE operations
# statement = "UPDATE dept_emp SET dept_no = $2 WHERE emp_no = $1"
#
# [[tools.parameters]]
# name = "emp_no"
# type = "integer"
# description = "Employee number"
# required = true
#
# [[tools.parameters]]
# name = "dept_no"
# type = "string"
# description = "New department number (e.g., d001, d002)"
# required = true

# ============================================================================
# QUICK REFERENCE
# ============================================================================
#
# Source Fields:
#   id = "unique_id"           # Required: unique identifier
#   description = "..."        # Optional: human-readable description
#   dsn = "..."                # Connection string (or use individual params below)
#   lazy = true                # Defer connection until first query (default: false)
#   search_path = "schema1,public"  # PostgreSQL only: comma-separated schemas
#   aws_iam_auth = true         # Optional: enable AWS RDS IAM auth (postgres/mysql/mariadb)
#   aws_region = "eu-west-1"    # Required when aws_iam_auth = true
#
# DSN Formats:
#   PostgreSQL:  postgres://user:pass@host:5432/database?sslmode=require
#   MySQL:       mysql://user:pass@host:3306/database
#   MariaDB:     mariadb://user:pass@host:3306/database
#   SQL Server:  sqlserver://user:pass@host:1433/database
#   SQLite:      sqlite:///path/to/file.db  or  sqlite:///:memory:
#
# Default Ports:
#   PostgreSQL: 5432 | MySQL/MariaDB: 3306 | SQL Server: 1433
#
# SSH Tunnel Options:
#   ssh_host, ssh_port (default: 22), ssh_user
#   ssh_key (path to private key) OR ssh_password
#   ssh_passphrase (if key is encrypted)
#   ssh_proxy_jump (ProxyJump for multi-hop: "jump1.com,user@jump2.com:2222")
#   ssh_keepalive_interval (seconds between keepalive packets, default: 0 = disabled)
#   ssh_keepalive_count_max (max missed keepalive responses, default: 3)
#
# SSL Mode (for network databases, not SQLite):
#   sslmode = "disable"   # No SSL
#   sslmode = "require"   # SSL without certificate verification
#
# SQL Server Authentication:
#   authentication = "ntlm"                              # Windows/NTLM auth (requires domain)
#   authentication = "azure-active-directory-access-token"  # Azure AD auth
#   domain = "MYDOMAIN"                                  # Required for NTLM
#
# Tool Options:
#   readonly = true    # Restrict to SELECT, SHOW, DESCRIBE, EXPLAIN (works for execute_sql and custom tools)
#   max_rows = 1000    # Limit result set size (works for execute_sql and custom tools)
#
# Parameter Placeholders by Database:
#   PostgreSQL:     $1, $2, $3
#   MySQL/MariaDB:  ?, ?, ?
#   SQL Server:     @p1, @p2, @p3
#   SQLite:         ?, ?, ?