快速为 GoNavi 添加国产数据库支持：扩展驱动与自定义数据源完整指南（以人大金仓为例）
项目地址: https://gitcode.com/gh_mirrors/go/GoNavi GoNavi 是一个轻量级数据库管理客户端，可连接 MySQL、Oracle、Redis 等约 30 种数据源。它的扩展驱动系统把数据源支持分为内置、按需安装、自由扩展三层：国产数据库如人大金仓（KingbaseES）点击安装即可接入，有 Go 驱动的数据库还能通过自定义数据源方式直连。
场景：新建连接时找不到 KingbaseES，是缺功能吗？
不少团队的业务库跑在人大金仓上。第一次打开 GoNavi 新建连接时，类型下拉框里只有 MySQL、PostgreSQL 等常见选项，看不到 KingbaseES。这不是功能缺失，而是对应驱动还没启用。新建连接界面如下，类型列表就是需要补上选项的地方：
把选项补上只需要安装一次驱动，后面新建连接就能正常选择了。
能力分层：开箱即用、按需安装、自由扩展怎么选
GoNavi 的驱动体系按三层理解，每层对应不同用户：
- 开箱即用：MySQL、PostgreSQL、Oracle、Redis、Kafka、RocketMQ 等高频数据源全部内置，打开程序就能连，适合绝大多数人。
- 按需安装：KingbaseES、OpenGauss、瀚高、Vastbase、达梦等国产数据库，以及 ClickHouse、MongoDB、Elasticsearch 都在这里。驱动代码已随程序提供，但需在驱动管理里点一次"安装启用"才出现在连接列表中，适合确实要连这些库的用户。
- 自由扩展：程序没有内置驱动、但数据库有标准 Go 驱动时，可用自定义 Driver + DSN 方式接入，适合开发者和特殊需求用户。
在工作台首页可以总览各数据源的连接情况：
实操：三步接入国产数据库（KingbaseES 完整流程）
全程不需要写代码。金仓的默认端口常见为 54321，具体以你的部署环境为准。
第 1 步：安装 KingbaseES 驱动
打开设置 → 驱动管理，在可选驱动列表里找到 KingbaseES，点击安装。安装会在本地驱动目录生成 installed.json 标记文件，程序靠它判断驱动是否已启用。若界面提示该驱动不可用，先确认当前是包含此驱动的完整版本（精简版不含部分国产数据库驱动）。
第 2 步：新建连接
重启或刷新驱动列表后，新建连接选择 KingbaseES，填写主机、端口、用户名、密码。金仓与 PostgreSQL 协议兼容，用过 PG 的话各项配置会非常眼熟，填完点击测试连接。
第 3 步：测试通过即可日常使用
测试通过后保存连接，左侧对象树可以浏览库、表、列，SQL 编辑器可直接执行查询。
源码层面，金仓的接入实现位于 internal/db/ 的 kingbase_impl.go：它复用 PG 协议完成连接与类型转换，并单独适配了金仓的系统视图，所以库列表、表元数据等查询能正确工作。
进阶：什么时候才需要自定义驱动？
先给结论：目标数据库只要在内置或可选列表里，就不需要写自定义驱动。
两种情况才值得考虑自定义数据源：
- 数据库有标准 Go 驱动（已注册到 database/sql），但 GoNavi 未内置。此时新建连接选"自定义"，填驱动名（即 sql.Open 注册的名字）和 DSN（数据库连接字符串）即可，程序内部调用 sql.Open 完成连接，逻辑见 internal/db/custom_impl.go。
- 数据库协议私有、需要 SSH 隧道、特殊类型映射或事务托管，这时才需要实现完整的驱动代理（driver-agent，即一个独立进程，通过 JSON 行协议与主程序通信）。
驱动代理的最小流程（面向贡献者）：
- 在 internal/db/ 实现符合 Database 接口的结构体（Connect、Query、GetDatabases、GetTables 等方法）。
- 在 cmd/optional-driver-agent/ 新增 provider 文件，片段如下：
//go:build gonavi_kingbase_driver
func init() {
agentDriverType = "kingbase"
agentDatabaseFactory = func() db.Database {
return &db.KingbaseDB{}
}
}
文件顶部的编译标签是"开关"：每个代理二进制只编译自己对应的那个驱动。
- 在 internal/db/driver_support.go 的可选驱动表中登记类型名，并到驱动清单 docs/driver-manifest.json 补充版本与安装地址。金仓在清单中的条目形如：
"kingbase": {
"engine": "go",
"downloadUrl": "builtin://activate/kingbase",
},
避坑：驱动装好却看不到选项怎么办？
- 现象：驱动显示已安装，新建连接里没有选项 → 原因：未重启程序，或当前是精简构建未包含该驱动 → 处理：重启后检查驱动管理里的状态；提示"此构建未包含"时换完整版本。
- 现象：测试连接超时或被拒绝 → 原因：端口填错（金仓默认不是 5432）、服务端监听地址受限 → 处理：用金仓官方客户端验证同一组参数是否可连，再核对防火墙与 SSH 代理配置。
- 现象：能连上，但浏览表、列报错 → 原因：方言差异，金仓兼容 PG 但部分系统视图与类型名不同 → 处理：升级 GoNavi 到最新版（元数据查询会随版本持续适配），并确认账号对目标 schema 的权限。
- 现象：自定义驱动报 unknown driver → 原因：驱动名与 database/sql 注册名不一致，或该 Go 驱动未编入程序 → 处理：核对驱动名与 DSN；未内置的 Go 驱动建议走驱动代理路线。
收尾
GoNavi 的扩展驱动系统把"支持一个新数据库"从写代码问题变成了操作问题：常用库开箱即用，其余按需安装，真正长尾的场景留给自定义数据源。如果你需要列表之外的数据库，也欢迎直接参与：Fork 仓库 → 实现驱动与 provider → 补充测试用例 → 提交 PR，审核通过后即可被所有用户安装使用。
本文基于 GoNavi 当前公开版本编写，驱动清单与界面细节以最新版本为准。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
