JDBC Plugin

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.

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

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:

java -version

If the command is missing, install Java first. DBX checks JAVA_HOME first, then common system locations and java from PATH.

brew install openjdk

java -version

sudo apt install openjdk-17-jre

sudo dnf install java-17-openjdk

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:

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:

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.

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:

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:

After saving, try:

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:

If SSL is required, add parameters to the JDBC URL:

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:

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:

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:

{
  "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"
    }
  ]
}

The current DBX app supports plugin protocol version 1. DBX rejects a plugin whose manifest declares a different protocol version, and each plugin request has a 30 second timeout so a hung driver process does not block the app indefinitely.

The initial protocol supports testConnection, connect, executeQuery, listDatabases, listSchemas, listTables, and getColumns.