diff --git a/docs/content/docs/databases.cn.mdx b/docs/content/docs/databases.cn.mdx
index 14a7c7777..405784df1 100644
--- a/docs/content/docs/databases.cn.mdx
+++ b/docs/content/docs/databases.cn.mdx
@@ -1,10 +1,10 @@
 ---
 title: 数据库支持
-description: 通过 Rust 原生驱动支持 25+ 种数据库，无 JDBC 依赖。
+description: 默认通过 Rust 原生驱动支持 25+ 种数据库，也可通过可选 JDBC 插件扩展更多数据库。
 ---
 
 <Callout type="info">
-Rust 原生驱动，不依赖 JDBC。MySQL / PostgreSQL 兼容数据库开箱即用。
+DBX 默认使用 Rust 原生驱动，不依赖 JDBC。需要连接更多数据库时，可以安装可选的 [JDBC 插件](/cn/docs/plugins)。
 </Callout>
 
 ## 完整支持
@@ -85,3 +85,7 @@ DM（达梦）通过 ODBC 连接，需要在系统上安装对应的 ODBC 驱动
     达梦暂未提供 macOS 原生 ODBC 驱动。开发/测试建议使用 Linux 环境连接。
   </Tab>
 </Tabs>
+
+## 可选 JDBC 插件
+
+如果目标数据库不在内置支持列表中，或你必须使用厂商提供的 JDBC 驱动，可以通过 [JDBC 插件](/cn/docs/plugins) 创建 JDBC 连接。JDBC 插件不会增加 DBX 主安装包体积，也不会自动下载数据库厂商驱动。
diff --git a/docs/content/docs/databases.mdx b/docs/content/docs/databases.mdx
index 8eb201ee0..712e291f1 100644
--- a/docs/content/docs/databases.mdx
+++ b/docs/content/docs/databases.mdx
@@ -1,10 +1,10 @@
 ---
 title: Database Support
-description: 25+ database engines through native Rust drivers, no JDBC dependency.
+description: 25+ database engines through native Rust drivers by default, with optional JDBC plugin support for more databases.
 ---
 
 <Callout type="info">
-Native Rust drivers, no JDBC dependency. MySQL and PostgreSQL compatible databases work out of the box.
+DBX uses native Rust drivers by default, with no JDBC required. For additional databases, install the optional [JDBC plugin](/docs/plugins).
 </Callout>
 
 ## Fully Supported
@@ -85,3 +85,7 @@ DM8 connects via the DM ODBC driver. Default port: **5236**, default user: **SYS
     DM does not provide a native macOS ODBC driver. For development/testing, DM is best accessed from Linux.
   </Tab>
 </Tabs>
+
+## Optional JDBC Plugin
+
+If your target database is not built in, or if you must use a vendor JDBC driver, create a JDBC connection with the [JDBC plugin](/docs/plugins). The JDBC plugin does not increase the main DBX installer size and does not automatically download vendor drivers.
diff --git a/docs/content/docs/plugins.cn.mdx b/docs/content/docs/plugins.cn.mdx
index 85815ed22..d1269a7bb 100644
--- a/docs/content/docs/plugins.cn.mdx
+++ b/docs/content/docs/plugins.cn.mdx
@@ -1,11 +1,277 @@
 ---
-title: 插件
-description: DBX 可选插件与驱动清单。
+title: JDBC 插件
+description: 安装 DBX JDBC 插件、导入数据库厂商驱动 JAR，并创建 JDBC 连接。
 ---
 
-DBX 可以从应用数据目录下的 `plugins` 目录发现可选插件。插件不会打包进主应用，因此可以在不增加默认安装包体积的前提下扩展特殊数据库支持。
+DBX 默认使用 Rust 原生数据库驱动。JDBC 是可选能力：当你需要连接 DBX 暂未内置支持的数据库，或希望使用数据库厂商提供的 JDBC 驱动时，可以安装 JDBC 插件。
 
-每个插件使用独立目录，并需要包含 `manifest.json`：
+<Callout type="info">
+JDBC 插件不会打包进 DBX 主应用，也不包含任何数据库厂商的 JDBC 驱动。你需要先安装 DBX JDBC 插件，再导入对应数据库的 JDBC driver JAR。
+</Callout>
+
+## 什么时候需要 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`。
+
+<Tabs groupId="java-install" items={['macOS', 'Windows', 'Linux']}>
+  <Tab value="macOS">
+    使用 Homebrew 安装：
+
+    ```bash
+    brew install openjdk
+    ```
+
+    如果 `java -version` 仍不可用，可以按 Homebrew 输出提示配置 `PATH` 或 `JAVA_HOME`。
+  </Tab>
+  <Tab value="Windows">
+    安装 Temurin、Oracle JDK 或 Microsoft Build of OpenJDK。安装后重新打开 DBX，并确认命令行中可以运行：
+
+    ```powershell
+    java -version
+    ```
+  </Tab>
+  <Tab value="Linux">
+    Debian / Ubuntu：
+
+    ```bash
+    sudo apt install openjdk-17-jre
+    ```
+
+    Fedora：
+
+    ```bash
+    sudo dnf install java-17-openjdk
+    ```
+  </Tab>
+</Tabs>
+
+## 第二步：安装 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` |
+
+<Callout type="warn">
+不同数据库和驱动版本的 URL 参数可能不同。以厂商官方文档为准。如果驱动依赖多个 JAR，请把需要的 JAR 路径都导入或填写进去。
+</Callout>
+
+## 第四步：导入 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
 {
@@ -26,31 +292,4 @@ DBX 可以从应用数据目录下的 `plugins` 目录发现可选插件。插
 }
 ```
 
-JDBC 连接类型是可选能力。DBX 主应用只保存 JDBC 连接元数据，真正执行 JDBC 查询需要安装提供驱动协议的插件进程。可选 JDBC 插件使用独立版本号，并通过 `protocol_version` 声明兼容的插件协议；它使用用户本机的 Java runtime，数据库对应的 JDBC driver JAR 由用户在设置中导入或在连接表单里填写路径。
-
-## 驱动协议
-
-DBX 会启动插件可执行文件，并通过 stdin/stdout 发送 JSON Lines 请求与响应。连接建立后，DBX 会复用同一个插件进程处理该连接上的查询和元数据请求。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "driver": "jdbc",
-  "method": "executeQuery",
-  "params": {
-    "connection": {},
-    "database": "default",
-    "schema": "",
-    "sql": "SELECT 1"
-  }
-}
-```
-
-响应格式如下：
-
-```json
-{ "id": 1, "result": { "columns": ["x"], "rows": [[1]], "affected_rows": 0, "execution_time_ms": 12, "truncated": false } }
-```
-
 第一版协议支持 `testConnection`、`connect`、`executeQuery`、`listDatabases`、`listSchemas`、`listTables` 和 `getColumns`。
diff --git a/docs/content/docs/plugins.mdx b/docs/content/docs/plugins.mdx
index 6adce785d..f56ad560c 100644
--- a/docs/content/docs/plugins.mdx
+++ b/docs/content/docs/plugins.mdx
@@ -1,11 +1,277 @@
 ---
-title: Plugins
-description: Optional DBX plugins and driver manifests.
+title: JDBC Plugin
+description: Install the DBX JDBC plugin, import vendor JDBC driver JARs, and create JDBC connections.
 ---
 
-DBX can discover optional plugins from the app data `plugins` directory. Plugins are not bundled with the main app, so they can add specialized database support without increasing the default installer size.
+DBX uses native Rust database drivers by default. JDBC is optional: install the JDBC plugin when you need to connect to a database that DBX does not support natively, or when you specifically need a vendor JDBC driver.
 
-Each plugin lives in its own folder and must include a `manifest.json` file:
+<Callout type="info">
+The JDBC plugin is not bundled with the main DBX app, and it does not include vendor JDBC drivers. Install the DBX JDBC plugin first, then import the database vendor's JDBC driver JAR.
+</Callout>
+
+## When to Use JDBC
+
+Prefer built-in DBX database types first, such as MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, DM, and GaussDB.
+
+Use JDBC when:
+
+- The target database is not built into DBX
+- The native driver does not cover a vendor-specific behavior
+- Your organization standardizes on a vendor JDBC driver
+- You want to connect to databases such as Dameng DM, H2, DB2, Snowflake, or SQLite through JDBC
+
+## Requirements
+
+| Item | Required | Notes |
+|---|---:|---|
+| DBX JDBC plugin | Yes | Installed from DBX settings; lets DBX call JDBC |
+| Java Runtime | Yes | The local machine must be able to run `java`; Java 17 or newer is recommended |
+| Vendor JDBC driver JAR | Yes | For example PostgreSQL, MySQL, Dameng DM, Oracle, H2, SQLite, or another vendor driver |
+| JDBC URL | Yes | The URL usually contains host, port, database name, and parameters |
+| Username/password | Depends | File databases or some auth modes may not need them |
+| Driver class | Usually optional | Most modern JDBC drivers auto-register; enter it only when auto-discovery fails |
+
+## Step 1: Install Java
+
+The JDBC plugin is a Java program, so your machine needs a Java runtime. After installation, verify it in a terminal:
+
+```bash
+java -version
+```
+
+If the command is missing, install Java first. DBX checks `JAVA_HOME` first, then common system locations and `java` from `PATH`.
+
+<Tabs groupId="java-install" items={['macOS', 'Windows', 'Linux']}>
+  <Tab value="macOS">
+    Install with Homebrew:
+
+    ```bash
+    brew install openjdk
+    ```
+
+    If `java -version` still does not work, follow the Homebrew output to configure `PATH` or `JAVA_HOME`.
+  </Tab>
+  <Tab value="Windows">
+    Install Temurin, Oracle JDK, or Microsoft Build of OpenJDK. Restart DBX after installation and verify:
+
+    ```powershell
+    java -version
+    ```
+  </Tab>
+  <Tab value="Linux">
+    Debian / Ubuntu:
+
+    ```bash
+    sudo apt install openjdk-17-jre
+    ```
+
+    Fedora:
+
+    ```bash
+    sudo dnf install java-17-openjdk
+    ```
+  </Tab>
+</Tabs>
+
+## Step 2: Install the DBX JDBC Plugin
+
+In DBX Desktop:
+
+1. Open **Settings**
+2. Go to **JDBC Drivers**
+3. Click **Install JDBC Plugin**
+
+After installation, DBX shows a status like:
+
+```text
+Installed: v0.1.0
+```
+
+The DBX JDBC plugin has its own version. It does not have to match the DBX app version. Updating DBX does not automatically install the JDBC plugin, and if you uninstall it manually, DBX will not reinstall it behind your back.
+
+## Step 3: Download the Vendor JDBC Driver
+
+DBX does not download vendor JDBC drivers automatically. Download the `.jar` file from the database vendor website or a Maven repository.
+
+Common examples:
+
+| Database | Common Maven Artifact | Driver Class | JDBC URL Example |
+|---|---|---|---|
+| 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` |
+| Dameng 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` |
+
+<Callout type="warn">
+JDBC URL parameters vary by database and driver version. Follow the vendor documentation. If a driver depends on multiple JARs, import or list all required JAR paths.
+</Callout>
+
+## Step 4: Import JDBC Driver JARs
+
+In DBX:
+
+1. Open **Settings**
+2. Go to **JDBC Drivers**
+3. In the **JDBC driver JARs** section, choose the downloaded `.jar`
+
+You can also paste a local JAR path and import it. DBX copies imported JARs into the app data directory, and new JDBC connections can select them from the driver dropdown.
+
+Importing a driver only copies local files. It does not change your system Java installation, install database clients, or upload the driver anywhere.
+
+## Step 5: Create a JDBC Connection
+
+Create a new connection and choose **JDBC**.
+
+| Field | What to enter |
+|---|---|
+| Name | Display name, such as `H2 Test`, `DM Dev`, or `Oracle Dev` |
+| JDBC URL | Full JDBC URL, such as `jdbc:postgresql://localhost:5432/postgres` |
+| Username | Database username; leave empty if not needed |
+| Password | Database password; leave empty if not needed |
+| Driver Class (optional) | Enter it only if auto-discovery fails, such as `org.postgresql.Driver` |
+| Driver JARs | Choose an imported driver from the dropdown, or enter local JAR paths |
+
+JDBC URLs usually already include host, port, and database name, so the JDBC form does not show separate host and port fields.
+
+Click **Test** after filling the form. If the test succeeds, click **Save** and the connection appears in the sidebar.
+
+## Example: Dameng DM
+
+DBX already has a built-in DM ODBC connection type. If you prefer the official Dameng JDBC driver, use the JDBC plugin.
+
+1. Install the DBX JDBC plugin
+2. Install Java
+3. Get the Dameng JDBC driver JAR from your DM installation directory or Maven repository, such as `DmJdbcDriver8.jar` or `DmJdbcDriver11.jar`
+4. Import the JAR in **Settings → JDBC Drivers**
+5. Create a new connection and choose **JDBC**
+6. Fill in:
+
+| Field | Value |
+|---|---|
+| JDBC URL | `jdbc:dm://127.0.0.1:5236` |
+| Username | `SYSDBA` |
+| Password | Your DM password |
+| Driver Class (optional) | `dm.jdbc.driver.DmDriver` |
+| Driver JARs | Choose the imported DM JDBC JAR |
+
+For DM, entering `dm.jdbc.driver.DmDriver` is recommended so the connection does not depend on automatic driver discovery metadata.
+
+## Example: H2 Local File Database
+
+H2 is a good way to verify the JDBC workflow.
+
+1. Install the DBX JDBC plugin
+2. Download the H2 JDBC driver JAR
+3. Import `h2-*.jar` in settings
+4. Create a new connection and choose **JDBC**
+5. Fill in:
+
+| Field | Value |
+|---|---|
+| JDBC URL | `jdbc:h2:/tmp/dbx-h2-demo` |
+| Username | `sa` |
+| Password | Leave empty |
+| Driver Class (optional) | `org.h2.Driver` |
+| Driver JARs | Choose the imported H2 JAR |
+
+After saving, try:
+
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY,
+  name VARCHAR(100)
+);
+
+INSERT INTO users VALUES (1, 'Alice');
+
+SELECT * FROM users;
+```
+
+## Example: PostgreSQL
+
+1. Download the PostgreSQL JDBC driver JAR
+2. Import it in settings
+3. Create a new JDBC connection
+4. Fill in:
+
+| Field | Value |
+|---|---|
+| JDBC URL | `jdbc:postgresql://localhost:5432/postgres` |
+| Username | `postgres` |
+| Password | Your PostgreSQL password |
+| Driver Class (optional) | `org.postgresql.Driver` |
+| Driver JARs | Choose the imported PostgreSQL JAR |
+
+If SSL is required, add parameters to the JDBC URL:
+
+```text
+jdbc:postgresql://localhost:5432/postgres?sslmode=require
+```
+
+## Troubleshooting
+
+### JDBC plugin installation fails
+
+Check whether your network can access DBX GitHub Releases. DBX tries proxy URLs and the original GitHub URL, but public proxies can still be unavailable. Try another network if GitHub is blocked.
+
+### Java cannot be found
+
+Verify in a terminal:
+
+```bash
+java -version
+```
+
+If the terminal works but DBX does not, restart DBX. On macOS, if Java is only installed under a Homebrew path, configure `JAVA_HOME`.
+
+### `No JDBC driver was discovered`
+
+The driver JAR was not auto-discovered. Enter the driver class manually, for example:
+
+```text
+org.postgresql.Driver
+com.mysql.cj.jdbc.Driver
+dm.jdbc.driver.DmDriver
+oracle.jdbc.OracleDriver
+```
+
+### `No suitable driver`
+
+The JDBC URL and driver probably do not match. Check:
+
+- The selected driver JAR belongs to the target database
+- The JDBC URL prefix is correct, such as `jdbc:postgresql:`, `jdbc:mysql:`, `jdbc:dm:`, or `jdbc:oracle:`
+- The driver class may need to be entered manually
+
+### The connection works but tables are missing
+
+JDBC metadata depends on the database driver and account permissions. Check:
+
+- The account can read metadata
+- The JDBC URL points to the expected database or schema
+- Tables may live under a different schema
+- The driver supports `DatabaseMetaData` for the objects you expect
+
+### A driver requires multiple JARs
+
+Enter one JAR path per line in the **Driver JARs** field, or import each required JAR in settings and add the remaining paths manually.
+
+## Uninstalling
+
+Click **Uninstall** in **Settings → JDBC Drivers**. DBX removes the JDBC plugin itself but keeps your imported vendor driver JARs, so you do not have to import them again if you reinstall the plugin later.
+
+## For Developers: Plugin Protocol
+
+DBX starts the plugin executable and exchanges JSON Lines requests and responses over stdin/stdout. After a connection is established, DBX reuses the same plugin process for queries and metadata requests on that connection.
+
+The plugin directory must include `manifest.json`:
 
 ```json
 {
@@ -26,31 +292,4 @@ Each plugin lives in its own folder and must include a `manifest.json` file:
 }
 ```
 
-The JDBC connection type is intentionally optional. The main DBX app stores JDBC connection metadata, but actual JDBC execution requires a plugin process that provides the driver protocol. The optional JDBC plugin has its own version and declares compatibility through `protocol_version`. It uses the local Java runtime, and users can import database-specific JDBC driver JARs in settings or provide paths in the connection form.
-
-## Driver protocol
-
-DBX starts the plugin executable and exchanges JSON Lines requests and responses over stdin/stdout. After a connection is established, DBX reuses the same plugin process for queries and metadata requests on that connection.
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "driver": "jdbc",
-  "method": "executeQuery",
-  "params": {
-    "connection": {},
-    "database": "default",
-    "schema": "",
-    "sql": "SELECT 1"
-  }
-}
-```
-
-Responses follow the same shape:
-
-```json
-{ "id": 1, "result": { "columns": ["x"], "rows": [[1]], "affected_rows": 0, "execution_time_ms": 12, "truncated": false } }
-```
-
-Supported initial methods are `testConnection`, `connect`, `executeQuery`, `listDatabases`, `listSchemas`, `listTables`, and `getColumns`.
+The initial protocol supports `testConnection`, `connect`, `executeQuery`, `listDatabases`, `listSchemas`, `listTables`, and `getColumns`.