# JDBC 插件

> 安装 DBX JDBC 插件、导入数据库厂商驱动 JAR，并创建 JDBC 连接。

Source: https://dbxio.com/cn/docs/plugins

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/plugins.



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

本页介绍的是 JDBC 插件和厂商 Driver JAR。若你要开发 SSH、SFTP、文件管理器或其他 DBX 扩展，并提交官方插件商店，请阅读

[开发和提交 DBX 插件](/cn/docs/plugin-development)

。

JDBC 插件不会打包进 DBX 主应用，也不包含任何数据库厂商的 JDBC 驱动。你需要先安装 DBX JDBC 插件，再导入对应数据库的 JDBC driver JAR。

“JDBC 能连接”不等于拥有原生 DBX profile 的全部能力。表树、对象源码、结构编辑、导入、传输和管理视图取决于 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 等数据库

## 需要准备什么

| 项目                    |   是否必需 | 说明                                              |
| --------------------- | -----: | ----------------------------------------------- |
| DBX JDBC 插件           |     必需 | 在 DBX 设置中一键安装，用来让 DBX 调用 JDBC                   |
| Java Runtime          |     必需 | 本机需要能运行 `java`；建议 Java 17 或更高版本                 |
| 数据库厂商 JDBC driver JAR |     必需 | 例如 PostgreSQL、MySQL、达梦、Oracle、H2、SQLite 等驱动 JAR |
| JDBC URL              |     必需 | JDBC URL 通常已经包含主机、端口、数据库名和参数                    |
| 用户名/密码                | 视数据库而定 | 文件型数据库或部分认证方式可能不需要                              |
| 驱动类                   |   通常可选 | 多数现代 JDBC 驱动可以自动注册；自动识别失败时再填写                   |

## 第一步：安装 Java

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

```bash
java -version
```

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

### macOS

使用 Homebrew 安装：

```bash
brew install openjdk
```

如果 `java -version` 仍不可用，可以按 Homebrew 输出提示配置 `PATH` 或 `JAVA_HOME`。

### Windows

安装 Temurin、Oracle JDK 或 Microsoft Build of OpenJDK。安装后重新打开 DBX，并确认命令行中可以运行：

```powershell
java -version
```

### Linux

Debian / Ubuntu：

```bash
sudo apt install openjdk-17-jre
```

Fedora：

```bash
sudo dnf install java-17-openjdk
```

## 第二步：安装 DBX JDBC 插件

在 DBX 桌面版中打开：

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

安装成功后会显示类似：

```text
已安装：v0.1.0
```

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

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

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

常见驱动示例：

| 数据库        | 常见 Maven Artifact                      | 驱动类                                            | JDBC URL 示例                                                       |
| ---------- | -------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
| PostgreSQL | `org.postgresql:postgresql`            | `org.postgresql.Driver`                        | `jdbc:postgresql://localhost:5432/postgres`                       |
| MySQL      | `com.mysql:mysql-connector-j`          | `com.mysql.cj.jdbc.Driver`                     | `jdbc:mysql://localhost:3306/test`                                |
| MariaDB    | `org.mariadb.jdbc:mariadb-java-client` | `org.mariadb.jdbc.Driver`                      | `jdbc:mariadb://localhost:3306/test`                              |
| 达梦 DM      | `com.dameng:DmJdbcDriver8`             | `dm.jdbc.driver.DmDriver`                      | `jdbc:dm://localhost:5236`                                        |
| SQL Server | `com.microsoft.sqlserver:mssql-jdbc`   | `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `jdbc:sqlserver://localhost:1433;databaseName=master`             |
| Oracle     | `com.oracle.database.jdbc:ojdbc11`     | `oracle.jdbc.OracleDriver`                     | `jdbc:oracle:thin:@//localhost:1521/ORCLPDB1`                     |
| H2         | `com.h2database:h2`                    | `org.h2.Driver`                                | `jdbc:h2:/tmp/dbx-h2-test`                                        |
| SQLite     | `org.xerial:sqlite-jdbc`               | `org.sqlite.JDBC`                              | `jdbc:sqlite:/Users/me/test.db`                                   |
| ClickHouse | `com.clickhouse:clickhouse-jdbc`       | `com.clickhouse.jdbc.ClickHouseDriver`         | `jdbc:clickhouse://localhost:8123/default`                        |
| DB2        | `com.ibm.db2:jcc`                      | `com.ibm.db2.jcc.DB2Driver`                    | `jdbc:db2://localhost:50000/SAMPLE`                               |
| Snowflake  | `net.snowflake:snowflake-jdbc`         | `net.snowflake.client.jdbc.SnowflakeDriver`    | `jdbc:snowflake://account.region.snowflakecomputing.com/?db=DEMO` |

不同数据库和驱动版本的 URL 参数可能不同。以厂商官方文档为准。如果驱动依赖多个 JAR，请把需要的 JAR 路径都导入或填写进去。

Oracle 驱动请同时导入与 

`ojdbc`

 同版本的 

`com.oracle.database.nls:orai18n`

。基础 ojdbc jar 不支持 

`ZHS16GBK`

 等多字节字符集，缺少它时表/字段注释等元数据无法加载。通过 Maven 安装 

`com.oracle.database.jdbc:ojdbc*`

 时会自动附带同版本的 

`orai18n`

。使用 DBX 内置 Oracle 连接（默认驱动）则无需额外 JAR，已支持这些字符集。

## 第四步：导入 JDBC 驱动 JAR

在 DBX 中打开：

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

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

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

## 第五步：创建 JDBC 连接

创建连接时选择 **JDBC** 类型。

| 字段       | 怎么填                                                        |
| -------- | ---------------------------------------------------------- |
| 名称       | 连接显示名，例如 `H2 Test`、`DM Dev`、`Oracle Dev`                   |
| JDBC URL | 完整 JDBC URL，例如 `jdbc:postgresql://localhost:5432/postgres` |
| 用户名      | 数据库用户名；不需要认证时可以留空                                          |
| 密码       | 数据库密码；不需要认证时可以留空                                           |
| 驱动类（可选）  | 自动识别失败时填写，例如 `org.postgresql.Driver`                       |
| 驱动 JAR   | 从已导入驱动下拉框选择，或填写本机 JAR 路径                                   |

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. 填写：

| 字段       | 值                          |
| -------- | -------------------------- |
| JDBC URL | `jdbc:dm://127.0.0.1:5236` |
| 用户名      | `SYSDBA`                   |
| 密码       | 你的达梦密码                     |
| 驱动类（可选）  | `dm.jdbc.driver.DmDriver`  |
| 驱动 JAR   | 选择已导入的达梦 JDBC JAR          |

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

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

H2 很适合验证 JDBC 流程。

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

| 字段       | 值                          |
| -------- | -------------------------- |
| JDBC URL | `jdbc:h2:/tmp/dbx-h2-demo` |
| 用户名      | `sa`                       |
| 密码       | 留空                         |
| 驱动类（可选）  | `org.h2.Driver`            |
| 驱动 JAR   | 选择已导入的 H2 JAR              |

保存后可以执行：

```sql
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. 填写：

| 字段       | 值                                           |
| -------- | ------------------------------------------- |
| JDBC URL | `jdbc:postgresql://localhost:5432/postgres` |
| 用户名      | `postgres`                                  |
| 密码       | 你的 PostgreSQL 密码                            |
| 驱动类（可选）  | `org.postgresql.Driver`                     |
| 驱动 JAR   | 选择已导入的 PostgreSQL JAR                       |

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

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

## 常见问题

### 安装 JDBC 插件失败

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

### 提示找不到 Java

确认终端里可以运行：

```bash
java -version
```

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

### 提示 `No JDBC driver was discovered`

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

```text
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`：

```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`。

JDBC 连接配置会保存 

`jdbc_driver_class`

 和 

`jdbc_driver_paths`

。如果一个驱动需要多个 JAR，请把所有路径都绑定到连接上，这样元数据和查询调用会使用同一套 classpath。