DBHub 多数据库配置指南

DBHub 是一个通用数据库 MCP 服务器, 支持通过 TOML 配置文件或多实例方式管理多个数据库连接, 适合同时管理生产、测试、开发环境的数据库。

支持的数据库类型

• PostgreSQL
• MySQL
• MariaDB
• SQL Server
• SQLite

配置方式 1: TOML 配置文件 (推荐)

创建配置文件

在项目根目录创建 dbhub.toml 文件:

# 使用 DSN 格式
[[sources]]
id = "prod_pg"
dsn = "postgres://user:password@localhost:5432/production?sslmode=disable"
readonly = true
max_rows = 1000

[[sources]]
id = "staging_mysql"
dsn = "mysql://user:password@localhost:3306/staging"
readonly = false
max_rows = 500

[[sources]]
id = "dev_sqlite"
dsn = "sqlite:///path/to/dev.db"
max_rows = 100

# 使用独立参数格式 (密码包含特殊字符时推荐)
[[sources]]
id = "test_pg"
type = "postgres"
host = "localhost"
port = 5432
database = "testdb"
user = "testuser"
password = "my@complex:password#with&special"
readonly = false
max_rows = 500

# 使用 SSH 隧道连接远程数据库
[[sources]]
id = "remote_mysql"
type = "mysql"
host = "remote-db-host"
port = 3306
database = "mydb"
user = "dbuser"
password = "dbpass"
ssh_host = "bastion-host"
ssh_user = "sshuser"
ssh_key = "/path/to/private/key"

配置参数说明

• id: 唯一标识符, 用于指定要查询的数据库
• dsn: 数据库连接字符串 (与独立参数二选一)
• type: 数据库类型 (postgres, mysql, mariadb, sqlserver, sqlite)
• host, port, database, user, password: 独立连接参数
• readonly: 是否只读模式 (true/false)
• max_rows: 查询结果最大行数限制
• ssh_host, ssh_user, ssh_key: SSH 隧道配置

重要: 第一个 [[sources]] 配置项是默认数据库, 查询时不指定 source_id 则使用它。

DSN 格式参考

# PostgreSQL
postgres://user:password@host:5432/dbname?sslmode=disable

# MySQL
mysql://user:password@host:3306/dbname

# MariaDB
mariadb://user:password@host:3306/dbname

# SQL Server
sqlserver://user:password@host:1433/dbname

# SQLite (文件)
sqlite:///path/to/database.db

# SQLite (Windows)
sqlite:C:/Users/YourName/data/database.db

# SQLite (内存)
sqlite::memory:

启动 DBHub

# 自动加载当前目录的 dbhub.toml
npx @bytebase/dbhub --transport http --port 8080

# 指定配置文件路径
npx @bytebase/dbhub --transport http --port 8080 --config=/path/to/config.toml

# Docker 方式
docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  -v $(pwd)/dbhub.toml:/app/dbhub.toml \
  bytebase/dbhub \
  --transport http \
  --port 8080

配置方式 2: MCP 多实例 (适用于 Claude Desktop/Cursor)

在 MCP 配置文件中定义多个 dbhub 实例, 每个实例连接不同的数据库。

Claude Desktop 配置

编辑 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dbhub-prod": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "ID": "prod",
        "DSN": "postgres://user:password@prod-host:5432/dbname?sslmode=disable"
      }
    },
    "dbhub-staging": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "ID": "staging",
        "DSN": "mysql://user:password@staging-host:3306/dbname"
      }
    },
    "dbhub-dev": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "ID": "dev",
        "DSN": "sqlite:///path/to/dev.db"
      }
    }
  }
}

Cursor 配置

Cursor 支持 stdio 和 sse 传输模式:

{
  "mcpServers": {
    "dbhub-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport", "stdio"
      ],
      "env": {
        "ID": "prod",
        "DSN": "postgres://user:password@prod-host:5432/dbname"
      }
    },
    "dbhub-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport", "stdio"
      ],
      "env": {
        "ID": "staging",
        "DSN": "mysql://user:password@staging-host:3306/dbname"
      }
    }
  }
}

使用示例

TOML 配置方式

在 Claude Code 中使用 source_id 参数指定目标数据库:

// 查询生产库
mcp__dbhub__execute_sql({
  source_id: "prod_pg",
  sql: "SELECT * FROM users LIMIT 10"
})

// 查询测试库
mcp__dbhub__execute_sql({
  source_id: "staging_mysql",
  sql: "SELECT COUNT(*) FROM orders"
})

// 不指定 source_id 时使用默认数据库 (第一个配置项)
mcp__dbhub__execute_sql({
  sql: "SELECT * FROM products LIMIT 5"
})

MCP 多实例方式

使用工具名称后缀来指定数据库:

// 查询生产库 (通过 ID="prod" 路由)
mcp__dbhub__execute_sql({
  sql: "SELECT * FROM users LIMIT 10"
})

配置方式 3: 环境变量 (单数据库)

密码包含特殊字符时推荐使用环境变量:

export DB_TYPE=postgres
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=myuser
export DB_PASSWORD='my@complex:password/with#special&chars'
export DB_NAME=mydatabase
npx @bytebase/dbhub

或使用 .env 文件:

DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=my@complex:password/with#special&chars
DB_NAME=mydatabase
TRANSPORT=sse
PORT=8080

配置优先级

当多个配置源同时存在时, 优先级从高到低:

1. 命令行参数 (最高)
2. 环境变量
3. 环境文件 (.env.local 开发环境, .env 生产环境)
4. 默认值 (最低)

常用命令行选项

*使用 --demo 时可省略

Docker 部署示例

PostgreSQL 连接

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  bytebase/dbhub \
  --transport sse \
  --port 8080 \
  --dsn "postgres://user:password@host.docker.internal:5432/dbname?sslmode=disable"

演示模式

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  bytebase/dbhub \
  --transport sse \
  --port 8080 \
  --demo

使用 TOML 配置文件

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  -v $(pwd)/dbhub.toml:/app/dbhub.toml \
  bytebase/dbhub \
  --transport sse \
  --port 8080 \
  --config=/app/dbhub.toml

安全特性

• 只读模式: 通过 readonly=true 防止数据修改
• SSH 隧道: 支持通过跳板机安全访问远程数据库
• SSL/TLS: PostgreSQL 支持 SSL 加密连接
• 行数限制: 通过 max_rows 防止大查询
• 连接池: 自动管理数据库连接

注意事项

• Docker 主机访问: 在 Docker 中访问宿主机数据库时, 使用 host.docker.internal 替代 localhost
• SSL 模式: PostgreSQL 本地开发时可能需要 ?sslmode=disable
• 传输模式: Claude Desktop 需要 stdio, Web 客户端和 Cursor 使用 sse
• 密码特殊字符: 包含特殊字符的密码建议使用独立参数或环境变量方式配置

参考资料

• GitHub - bytebase/dbhub
• DBHub Installation Guide - DeepWiki
• DBHub Multi-Database Config
• DBHub on Awesome MCP Servers
• DBHub Documentation - Portia AI