DBHub 使用教程-cmzhiku

项目简介

DBHub 是 Bytebase 开源的数据库 MCP 网关，MIT 协议。它站在 Codex 和数据库中间：你用中文提问，它自己翻表结构、写 SQL、跑完把结果交回来。

默认只挂两个工具，一个执行 SQL，一个搜表、列、索引和存储过程。PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、SQLite 六种库走同一个口子。可以开只读、限制返回行数、给查询加超时，也能走 SSH 隧道连服务器上的库。

官方文档里直接给了 Codex 的接入命令。先试玩不用自己装数据库，加 demo 参数就会带上一个 SQLite 样例库。

📎 相关链接与下载地址（点击展开）

核心亮点

🔌 一条命令接进 Codex

官方文档给出 Codex 的 mcp add 写法，装完在 Codex 里敲 /mcp 就能看到它亮起。

🗄️ 六种库一个口子

PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、SQLite，不用为每种库各装一个插件。

🛡️ 三道护栏

只读、限制行数、查询超时写在配置文件里。只读打开后，改表语句会被挡回来。

🧪 自带样例库

demo 参数启动一个 SQLite 员工库，本机不用先装数据库就能把整条链路跑通。

能力速览

项目	说明
输入	中文或英文问题；底层是 SQL。连接用 DSN，或多库配置文件
适用类型	本地开发库、只读排查、把查询结果导出成文件
输出	表结构、查询结果；也可以让 Codex 把结果写成项目里的文件
语言 / 兼容	Codex、Claude Code、Cursor、VS Code、Copilot CLI 等支持 MCP 的客户端
规格 / 容量	默认两个工具。可选执行计划、连接健康检查。多库写在同一个配置文件里，改完自动重新加载

环境要求

项目	要求
操作系统	Windows、macOS、Linux 都可以
运行环境	用 npx 时需要 Node.js 22.5 或更高（SQLite 走 Node 内置模块）
硬件	普通电脑即可，不需要独显
不想装 Node	用 Docker 镜像 bytebase/dbhub，镜像里已经带好运行时
关键依赖	npx 会按需拉数据库驱动。SQLite 和 demo 模式不需要额外驱动

如何使用

💡 最快的路径：先用 demo 样例库接进 Codex，问一句「这个库有哪些表」。通了再换成自己的库。

步骤 1

确认 Node 版本

npx 方式要求 Node.js 22.5 或更高。版本不够就改走 Docker 镜像，不用在本机升级 Node。

bash

node -v

步骤 2

一条命令接进 Codex

在项目目录执行下面这行。demo 会带上一个 SQLite 样例库，什么都不用另装。

bash

codex mcp add dbhub -- npx @bytebase/dbhub@latest --transport stdio --demo

步骤 3

确认已经接上

打开 Codex，输入 /mcp。看到 dbhub 一行状态是 enabled，就接上了。然后直接用中文问。

text

这个库里有哪些表
哪个部门平均工资最高
把这个结果导成 CSV 放到项目里

常用参数：

参数	作用
`--demo`	使用内置 SQLite 样例库，适合先跑通
`--dsn`	连接你自己的一个库。和配置文件二选一，不能同时用
`--config`	指向多库配置文件，适合同时接好几个库
`--transport`	stdio 给桌面客户端；http 才会打开网页工作台

步骤 4

给生产库加上护栏

只读、限制行数、查询超时这三项只写在配置文件里，命令行没有开关。demo 模式默认不是只读，要挡改表就得单独配。

toml

readonly = true
max_rows = 1000
query_timeout = 30

步骤 5

结合 Codex 使用

接上之后不用再开数据库客户端。问表结构、跑查询、把结果写成文件，都在 Codex 对话里完成。连服务器上的库时，同一条命令可以加 SSH 隧道参数，具体写法在折叠的文档链接里。

✅ 以前要自己粘 SQL、再把结果贴回去。接上之后，数据库成了 Codex 伸手就能翻的东西。

典型应用场景

🔎 写接口时核对脏数据

代码看完还要确认表里到底有没有那几行，直接问 Codex。

📐 翻不熟的表结构

先搜表和字段，再写 SQL，不用在客户端里一层层点开。

📤 把查询结果落成文件

说一句导出，结果写进项目目录，不用再手工拷贝。

🔒 只读排查线上库

打开只读之后，改表语句会被拒绝，适合让 AI 看生产数据。

🌉 经跳板机连内网库

支持 SSH 隧道和 ProxyJump，密钥可以用本机已有的配置。

🧩 一个进程接多个库

测试库、生产只读库写在同一个配置文件里，改完自动重新加载。

和同类比

对比	DBHub 的做法
默认工具数量	默认 2 个：执行 SQL、搜对象。可选再开执行计划和健康检查
数据库种类	六种关系库一个进程。多库不用各装一个 MCP
安全开关	只读、行数上限、查询超时在配置文件里按工具分别设置