JDBC 插件

DBX 默认使用 Rust 原生数据库驱动。JDBC 是可选能力：当你需要连接 DBX 暂未内置支持的数据库，或希望使用数据库厂商提供的 JDBC 驱动时，可以安装 JDBC 插件。

Desktop 导入的是本机 JAR；Docker/Web 中 JAR 和插件安装在服务器数据目录。浏览器电脑上的本地路径不能直接交给 Web 服务器使用，迁移配置时也不会自动携带驱动文件。

什么时候需要 JDBC

优先使用 DBX 内置数据库类型，例如 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle、DM、GaussDB 等。

以下情况再使用 JDBC：

• 目标数据库不在 DBX 内置类型中
• 内置驱动无法满足某个厂商特性
• 你的公司统一要求使用厂商 JDBC driver
• 你想用 JDBC 连接达梦、H2、DB2、Snowflake、SQLite JDBC 等数据库

需要准备什么

第一步：安装 Java

JDBC 插件是 Java 程序，需要本机有 Java runtime。安装后在终端确认：

java -version

如果系统提示找不到 java，需要先安装 Java。DBX 会优先使用 JAVA_HOME，其次尝试常见系统路径和 PATH 中的 java。

brew install openjdk

java -version

sudo apt install openjdk-17-jre

sudo dnf install java-17-openjdk

第二步：安装 DBX JDBC 插件

在 DBX 桌面版中打开：

1. 设置
2. JDBC 驱动
3. 点击 安装 JDBC 插件

安装成功后会显示类似：

已安装：v0.1.0

DBX JDBC 插件有自己的版本号，不会强制跟 DBX 主应用版本一致。主应用更新后不会自动安装 JDBC 插件；如果你手动卸载过，后续更新也不会自动装回来。

第三步：下载数据库厂商 JDBC 驱动

DBX 不会自动下载数据库厂商驱动。你需要从数据库官网或 Maven 仓库下载对应的 .jar 文件。

常见驱动示例：

第四步：导入 JDBC 驱动 JAR

在 DBX 中打开：

1. 设置
2. JDBC 驱动
3. 在 JDBC 驱动 JAR 区域点击导入按钮，选择下载好的 .jar

也可以直接粘贴本机 JAR 路径，然后点击导入。导入后，JAR 会复制到 DBX 的应用数据目录中，之后新建 JDBC 连接时可以从下拉框选择它。

导入驱动只复制文件，不会修改系统 Java、不安装数据库客户端，也不会把驱动上传到远端。

第五步：创建 JDBC 连接

创建连接时选择 JDBC 类型。

JDBC URL 通常已经包含主机、端口和数据库名，因此 JDBC 表单不会再单独显示主机和端口。

填写完成后点击 测试。测试成功后点击 保存，连接会出现在侧边栏中。

示例：连接达梦 DM

DBX 已经内置 DM ODBC 连接类型。如果你更想使用达梦官方 JDBC 驱动，可以走 JDBC 插件。

1. 安装 DBX JDBC 插件
2. 安装 Java
3. 从达梦安装目录或 Maven 仓库获取达梦 JDBC driver JAR，例如 DmJdbcDriver8.jar 或 DmJdbcDriver11.jar
4. 在 设置 → JDBC 驱动 中导入该 JAR
5. 新建连接，选择 JDBC
6. 填写：

达梦这里建议直接填写驱动类 dm.jdbc.driver.DmDriver，这样不依赖驱动 JAR 的自动发现配置。

示例：连接 H2 本地文件数据库

H2 很适合验证 JDBC 流程。

1. 安装 DBX JDBC 插件
2. 下载 H2 JDBC driver JAR
3. 在设置中导入 h2-*.jar
4. 新建连接，选择 JDBC
5. 填写：

保存后可以执行：

CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR(100)
);

INSERT INTO users VALUES (1, 'Alice');

SELECT * FROM users;

示例：连接 PostgreSQL

1. 下载 PostgreSQL JDBC driver JAR
2. 在设置中导入该 JAR
3. 新建 JDBC 连接
4. 填写：

如果数据库要求 SSL，可以在 JDBC URL 后添加参数：

jdbc:postgresql://localhost:5432/postgres?sslmode=require

常见问题

安装 JDBC 插件失败

检查网络是否能访问 DBX 的 GitHub Release。DBX 会尝试代理地址和 GitHub 原始地址，但代理站也可能不稳定。如果公司网络限制 GitHub，请换网络后重试。

提示找不到 Java

确认终端里可以运行：

java -version

如果终端可用但 DBX 不可用，重启 DBX。macOS 上如果 Java 只安装在 Homebrew 路径，也可以配置 JAVA_HOME。

提示 No JDBC driver was discovered

说明驱动 JAR 没有被自动识别。请在 驱动类（可选） 中填写对应驱动类，例如：

org.postgresql.Driver
com.mysql.cj.jdbc.Driver
dm.jdbc.driver.DmDriver
oracle.jdbc.OracleDriver

提示 No suitable driver

通常是 JDBC URL 和驱动不匹配。检查：

• 是否选择了正确数据库的 driver JAR
• JDBC URL 前缀是否正确，例如 jdbc:postgresql:、jdbc:mysql:、jdbc:dm:、jdbc:oracle:
• 是否需要填写驱动类

能连接但看不到表

JDBC 元数据依赖数据库驱动和账号权限。检查：

• 当前账号是否有读取 metadata 的权限
• JDBC URL 是否连接到了正确的数据库或 schema
• 表是否在不同 schema 下
• 数据库驱动是否完整支持 DatabaseMetaData

一个驱动需要多个 JAR 怎么办

在连接表单的 驱动 JAR 文本框中每行填写一个 JAR 路径，或在设置里分别导入多个 JAR 后选择/补充路径。

卸载插件

在 设置 → JDBC 驱动 中点击 卸载。卸载会移除 DBX JDBC 插件本体，但会保留你已经导入的数据库厂商 driver JAR，避免下次重新安装插件时还要重新导入。

给开发者：插件协议

DBX 会启动插件可执行文件，并通过 stdin/stdout 发送 JSON Lines 请求与响应。连接建立后，DBX 会复用同一个插件进程处理该连接上的查询和元数据请求。

插件目录需要包含 manifest.json：

{
  "id": "jdbc",
  "name": "DBX JDBC Plugin",
  "version": "0.1.0",
  "protocol_version": 1,
  "description": "Adds JDBC driver support.",
  "executable": "bin/dbx-jdbc-plugin",
  "drivers": [
    {
      "id": "jdbc",
      "label": "JDBC",
      "kind": "external",
      "database_type": "jdbc"
    }
  ]
}

当前 DBX 主应用支持插件协议版本 1。如果插件 manifest 声明了不同协议版本，DBX 会拒绝加载；每次插件请求也有 30 秒超时，避免驱动进程卡住后无限阻塞应用。

第一版协议支持 testConnection、connect、executeQuery、listDatabases、listSchemas、listTables 和 getColumns。