GoNavi 驱动扩展指南：三种方式接入新数据库，从可选代理到自定义 DSN-二趣网

GoNavi 驱动扩展指南：三种方式接入新数据库，从可选代理到自定义 DSN

【免费下载链接】GoNaviHigh-performance multi-data-source database client — ~30MB, AI & MCP ready, zero Electron bloat. | 高性能多数据源数据库客户端：约 30MB，AI 与 MCP 就绪，告别 Electron 膨胀。项目地址: https://gitcode.com/gh_mirrors/go/GoNavi

GoNavi 是基于 Go/Wails 的桌面数据库管理工具，GoNavi 驱动扩展把接入新数据库分成三档：内置驱动、可选驱动代理、自定义 DSN 数据源，成本从低到高依次选择。

内置档开箱即用，包括 MySQL、GoldenDB、PostgreSQL、Oracle、Redis、Chroma、Qdrant、RocketMQ、MQTT、Kafka、RabbitMQ。其余数据源走后两档：要么在驱动管理界面安装一个现成的可选驱动代理，要么自己写驱动、或者用 Driver + DSN 直接接入。本文按"先跑通、再拆内部、最后从零写"的顺序讲。

先跑通：三步装可选驱动代理

大多数场景不需要写代码。可选驱动代理已经把国产库、时序库、分析库都打好了包，你在界面上启用即可。

可选代理覆盖的数据源清单

关系与嵌入式：MariaDB、SQL Server、SQLite、DuckDB
国产数据库：达梦（Dameng）、人大金仓（Kingbase）、瀚高（HighGo）、Vastbase、OpenGauss、GaussDB
时序：TDengine、IoTDB
分析型：ClickHouse、StarRocks、Trino
其他：MongoDB、Elasticsearch、Sphinx

安装与生效

操作路径很短：主界面左下角设置图标，进入"驱动管理"，切到"可选驱动"选项卡，找到目标驱动点"安装"。GoNavi 会自动下载并配置对应的驱动代理二进制。装完留意提示：部分驱动需要重启应用才生效，重启后"新建连接"里就会出现该驱动类型。

如果列表里找不到你要的库，往下看后两节。

达梦驱动代理四件套：provider、impl、注册与 manifest 怎么分工

以达梦为例，一个可选驱动在代码里对应四个落点，理解了这个分工，后面自己写代理就只是填空。

1. provider 文件：声明"这个二进制是达梦代理"

cmd/optional-driver-agent/ 下每个驱动一个 provider 文件，靠 build tag 控制哪个文件参与编译。provider_dameng.go全文如下，作用是在包初始化时把驱动类型和实例工厂挂到主程序的全局变量上：

//go:build gonavi_dameng_driver package main import "GoNavi-Wails/internal/db" func init() { agentDriverType = "dameng" agentDatabaseFactory = func() db.Database { return &db.DamengDB{} } }

也就是说，编译时带上gonavi_dameng_driver标签，就会得到一个只含达梦支持的独立 agent 二进制；打gonavi_full_drivers标签则是全量编译。

2. impl 文件：实现 db.Database 接口

internal/db/dameng_impl.go 承载真正的逻辑：连接管理、DSN 拼装、查询执行、元数据获取（库、表、列、索引、外键、触发器）和 DDL 提取。所有驱动面向同一个接口，internal/db/database.go 里的核心方法如下，你的实现必须覆盖这些方法（注释为省略部分）：

type Database interface { Connect(config connection.ConnectionConfig) error Close() error Ping() error Query(query string) ([]map[string]interface{}, []string, error) Exec(query string) (int64, error) GetDatabases() ([]string, error) GetTables(dbName string) ([]string, error) // GetColumns / GetIndexes / GetForeignKeys / GetTriggers / // GetCreateStatement 等元数据方法同理 }

达梦的 DSN 形态是dm://user:password@host:port?schema=...，impl 里还处理了 SSL 证书路径和 SSH 隧道转发，细节可以翻源码。

3. driver_support 注册：告诉主程序这是"可选档"

internal/db/driver_support.go 维护两个 map：coreBuiltinDrivers是内置档，optionalGoDrivers是需要安装启用的可选档。达梦注册成这样一行：

var optionalGoDrivers = map[string]struct{}{ "dameng": {}, "kingbase": {}, // 其余可选驱动按同样方式列出 }

注意这是运行时门控（按 installed.json 标记放行），并不削减主二进制体积。同一文件里的normalizeRuntimeDriverType还负责别名归一化，比如dm、dm8都会归到dameng。

4. driver-manifest 清单：驱动管理界面的数据来源

docs/driver-manifest.json 里每个驱动一个条目，字段含义：engine是引擎类型，version是底层 Go 驱动版本，downloadUrl用builtin://activate/xxx表示"无需下载、本地激活"。达梦条目：

"dameng": { "engine": "go", "version": "1.8.22", "checksumPolicy": "off", "downloadUrl": "builtin://activate/dameng" }

四件套齐了，界面上才会出现可安装的达梦选项。

自定义数据源：DSN 快速通道与完整代理最小骨架

有现成 Go 驱动时，直接走 DSN

目标库只要有一个标准的database/sql驱动（如github.com/go-sql-driver/mysql），四步就能连上，不用写一行代码：

新建连接，类型选"自定义"
驱动名填驱动注册名（例如mysql）
填 DSN 连接字符串
点测试连接，通了就保存

需要特殊处理时，写一个完整代理

需要自定义元数据逻辑、方言改写或非 SQL 协议的库，才值得做完整代理。最小骨架如下（先拉一份源码：git clone https://gitcode.com/gh_mirrors/go/GoNavi）：

新建 cmd/optional-driver-agent/provider_mydb.go，仿照达梦：build tag 用gonavi_mydb_driver，init()里设agentDriverType = "mydb"和工厂函数
在 internal/db/ 下新建mycustomdb_impl.go，实现db.Database接口；连接和查询逻辑照抄接口注释即可起步：

type MyCustomDB struct { conn *sql.DB } func (m *MyCustomDB) Connect(config connection.ConnectionConfig) error { // 按 config 拼装 DSN，sql.Open + Ping 建连 } func (m *MyCustomDB) Query(query string) ([]map[string]interface{}, []string, error) { // 执行查询，把行扫描成 map 返回 } // Close / GetDatabases / GetTables / GetColumns 等其余方法同理

在 internal/db/driver_support.go 的optionalGoDrivers加"mydb": {}
在 docs/driver-manifest.json 加一条builtin://activate/mydb条目

四处都改完，这个驱动就和达梦走同一条安装链路了。

落地避坑：方言适配、连接参数与常见报错对照清单

方言适配三要点

国产库大多派生自 PostgreSQL 或 MySQL，但有私有方言，适配时按三个层面逐项过：SQL 方言（分页、DDL、系统函数要按目标库重写）、元数据查询（系统表结构和标准库不同，GetTables/GetColumns的取数 SQL 要单独适配）、数据类型映射（库特有类型要映射回 Go 的通用表示）。

连接参数怎么给

配置统一走connection.ConnectionConfig，国产库的常见参数放在 Options 里。达梦的默认端口是 5236，初始账号通常是 SYSDBA，一个最小示例：

config := connection.ConnectionConfig{ Host: "192.168.0.20", Port: 5236, User: "SYSDBA", Password: "SYSDBA", Database: "TEST", }

如果连接走 SSH 隧道或需要 SSL，记得同时配置隧道参数或证书/私钥路径，达梦 impl 会在Connect里校验并给出明确报错。

三类高频报错的排查顺序

驱动加载失败：先确认驱动文件是否下载完整，再核对 build tag 是否与编译参数一致，最后看 GoNavi 日志里 agent 的启动输出
连接测试失败：按"网络连通性 → 防火墙与安全组 → 数据库服务状态"的顺序排除，必要时用数据库原生客户端直连对照
查询执行错误：先确认 SQL 在目标库方言下是否合法，再核对账号权限，最后查数据库侧错误日志

调试手段就三个：GoNavi 内置日志、原生客户端对照、网络抓包。够用，且顺序别乱。

性能上别忽略的几件事

驱动层做连接池复用、支持预处理语句、批量写入；应用层给查询设超时、分页取数、长任务异步化。这几条不做到，任何驱动都会在大数据量下先崩。

能力边界、路线图与贡献方式

当前体系覆盖关系、文档、时序、分析、消息、向量检索和搜索引擎类数据源，未内置的类型走自定义 DSN 或代理补齐。路线上计划覆盖图数据库（Neo4j、Nebula Graph）、更多时序库（InfluxDB、TimescaleDB）、分布式数据库（TiDB、CockroachDB）和云数据库（AWS RDS、Azure SQL）。

想贡献新驱动：Fork 仓库，按本文四件套补齐 provider、impl、注册与 manifest 清单，附测试用例后提 Pull Request，等审查合并即可。实现细节以当前版本源码为准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析