DBHub 使用教程

📖 项目简介

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

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

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

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

源码：github.com/bytebase/dbhub
安装文档：dbhub.ai/installation
命令行参数：dbhub.ai/config/command-line
多库配置：dbhub.ai/config/toml
Codex 试玩：codex mcp add dbhub -- npx @bytebase/dbhub@latest --transport stdio --demo
换成自己的库时，把 demo 换成 dsn，连接串格式见安装文档。
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

🔌

一条命令接进 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，问一句「这个库有哪些表」。通了再换成自己的库。

确认 Node 版本

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

bashnode -v

一条命令接进 Codex

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

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

确认已经接上

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

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

常用参数：

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

给生产库加上护栏

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

tomlreadonly = true
max_rows = 1000
query_timeout = 30

结合 Codex 使用

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

✅

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

🎯 典型应用场景

🔎

写接口时核对脏数据

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

📐

翻不熟的表结构

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

📤

把查询结果落成文件

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

🔒

只读排查线上库

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

🌉

经跳板机连内网库

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

🧩

一个进程接多个库

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

📈 和同类比

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

🧠

它不自己猜数据。Codex 通过这两个工具先看结构、再执行你允许的 SQL，所以回答能对上真实的表。

❓ 常见问题

Q: 和直接把连接串交给数据库客户端有什么不同？

客户端还是你自己写 SQL、自己拷结果。接上之后，提问、翻表、执行、把结果放进项目，都在 Codex 里完成。

Q: 支持哪些数据库？

PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、SQLite。Oracle 不需要再装 Instant Client。

Q: Node 版本不够，起不来怎么办？

npx 要求 Node.js 22.5 或更高。不想升级就改用 Docker 镜像 bytebase/dbhub，镜像里自带运行时。

Q: Windows 上第一次很慢？

npx 第一次会拉取各数据库驱动，等它下完即可。只要 SQLite 或 demo，可以只留 SQLite，它不需要额外驱动。

Q: --config 和 --dsn 能一起用吗？

不能。配置文件自己定义数据源，和 --dsn、--id 互斥。多库用配置文件，单库用 dsn 或 demo。

Q: 怎么和 Codex 结合？

用上面的 codex mcp add 那一行。装完执行 /mcp，看到 dbhub 状态是 enabled 再开始问。也可以把同样的命令写进 Codex 的配置文件，折叠链接里有文档。

Q: 它和 Bytebase 本体是什么关系？

DBHub 是 Bytebase 出品的轻量 MCP 网关，负责把库暴露成工具。Bytebase 本体是带审批、脱敏和审计的数据库治理平台，比 DBHub 重一档。这条片子演示的是网关这条接入路径。

Q: 可以商用吗？

仓库协议是 MIT。接入你自己的库之前，先把只读和行数限制配上，再让 AI 去查。