# How to Configure JDBC Drivers for Custom Databases in Chat2DB

> Learn how to configure JDBC drivers for custom databases in Chat2DB. Easily connect to any JDBC-compatible database by uploading JARs and saving driver configurations.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-28

---

**Chat2DB enables connectivity to any JDBC-compatible database by uploading driver JARs via the `/api/jdbc/driver/upload` endpoint and registering driver configurations through `/api/jdbc/driver/save`, which persists settings in `DriverConfig` and loads driver classes at runtime using isolated `URLClassLoader` instances.**

Chat2DB is an open-source database management tool that extends connectivity beyond built-in engines through a flexible JDBC driver configuration system. Understanding how to configure JDBC drivers for custom databases in Chat2DB allows you to integrate proprietary or third-party database engines by supplying the appropriate JAR files and connection metadata. The implementation spans multiple layers, from the web API controllers to the low-level driver management utilities.

## Understanding the Driver Architecture

The Chat2DB driver configuration system consists of several key components that handle persistence, conversion, and runtime loading:

- **`DriverConfig`** – A POJO located in [`chat2db-community-domain-api/src/main/java/ai/chat2db/community/domain/api/config/DriverConfig.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-domain-api/src/main/java/ai/chat2db/community/domain/api/config/DriverConfig.java) that stores all JDBC attributes, including the URL pattern, driver class name, download URLs, and custom flags.

- **`JdbcDriverRequest`** – A DTO in [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/driver/JdbcDriverRequest.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/model/request/driver/JdbcDriverRequest.java) that captures user input from the UI or API calls.

- **`JdbcDriverConverter`** – Found in [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/converter/driver/JdbcDriverConverter.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/converter/driver/JdbcDriverConverter.java), this utility converts between `JdbcDriverRequest` and `DriverConfig`, and constructs `DriverResponse` objects for API returns.

- **`IDbJdbcDriverService`** – The service interface defined in [`chat2db-community-domain-api/src/main/java/ai/chat2db/community/domain/api/service/db/IDbJdbcDriverService.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-domain-api/src/main/java/ai/chat2db/community/domain/api/service/db/IDbJdbcDriverService.java) that specifies CRUD operations and JAR file management.

- **`DbJdbcDriverServiceImpl`** – The core implementation in [`chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/db/DbJdbcDriverServiceImpl.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/db/DbJdbcDriverServiceImpl.java) that persists configurations to the database and manages physical JAR file storage.

- **`DbJdbcDriverController`** – The REST controller in [`chat2db-community-web/src/main/java/ai/chat2db/community/web/api/controller/DbJdbcDriverController.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/controller/DbJdbcDriverController.java) that exposes endpoints under `/api/jdbc/driver` for listing, downloading, uploading, saving, and deleting drivers.

- **`JdbcDriverManager`** – The runtime loader in [`chat2db-community-spi/src/main/java/ai/chat2db/spi/sql/JdbcDriverManager.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-spi/src/main/java/ai/chat2db/spi/sql/JdbcDriverManager.java) that creates dedicated classloaders for each driver to prevent classpath conflicts.

## Step-by-Step Configuration Process

### Uploading the Driver JAR

If your driver is not available via public Maven repositories, you must upload the JAR file directly to Chat2DB. The `DbJdbcDriverController` exposes a `POST /api/jdbc/driver/upload` endpoint that accepts multipart form data.

**`DbJdbcDriverServiceImpl`** handles the upload by writing the file to an internal driver storage directory and updating the corresponding `DriverConfig` with the local file path. This ensures the JAR persists across application restarts.

### Registering the Driver Configuration

After uploading the JAR (or specifying a download URL), you must register the driver configuration by calling `POST /api/jdbc/driver/save`. The request payload maps directly to the `DriverConfig` fields.

The **`JdbcDriverConverter.saveRequest2driverConfig()`** method transforms the incoming `JdbcDriverRequest` into a `DriverConfig` entity, automatically setting the `custom` flag to `true` to indicate a user-defined driver. The service validates that both `jdbcDriver` (the driver name) and `jdbcDriverClass` (the fully qualified class name) are non-empty before persisting.

## Runtime Driver Loading and Connection Management

When a connection request targets a custom database, **`JdbcDriverManager.getConnection()`** orchestrates the loading process:

1. **Driver Lookup** – The manager checks `DRIVER_ENTRY_MAP` for the driver name.
2. **Class Loading** – If not cached, `getJDBCDriver(driver)` invokes `getClassLoader()` to create a `URLClassLoader` pointing to the stored JAR file.
3. **Instantiation** – The system instantiates the driver class specified in `driver.getJdbcDriverClass()` and caches the instance in `DRIVER_ENTRY_MAP` for subsequent connections.

This isolated classloader approach ensures that custom driver dependencies do not conflict with other drivers or the core application classpath.

## Complete Configuration Examples

### Saving a Custom Driver Configuration

Use the REST API to register a new driver with metadata:

```json
POST /api/jdbc/driver/save
Content-Type: application/json

{
  "dbType": "CUSTOM_ANALYTICS",
  "jdbcDriver": "analyticsdb",
  "jdbcDriverClass": "com.analytics.jdbc.Driver",
  "url": "jdbc:analyticsdb://{host}:{port}/{database}",
  "downloadJdbcDriverUrls": [
    "https://internal.repo.com/drivers/analyticsdb-2.1.0.jar"
  ],
  "custom": true,
  "defaultDriver": false,
  "extendInfo": [
    { "key": "connectionTimeout", "value": "5000" },
    { "key": "enableCompression", "value": "true" }
  ]
}

```

The `extendInfo` array allows you to specify additional connection properties that Chat2DB will append to JDBC URLs or pass as connection parameters.

### Uploading a Driver JAR via cURL

If the driver JAR is not publicly accessible, upload it directly:

```bash
curl -X POST https://your-chat2db-host/api/jdbc/driver/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/analyticsdb-driver.jar"

```

**`DbJdbcDriverServiceImpl`** stores this file and associates it with the driver configuration created in the previous step.

### Connecting to a Data Source with Custom Driver

When creating a data source, reference the registered driver by its `jdbcDriver` name:

```json
{
  "name": "Production Analytics DB",
  "url": "jdbc:analyticsdb://db-server:5432/analytics",
  "driver": "analyticsdb",
  "driverConfig": {
    "extendInfo": [
      { "key": "sslMode", "value": "require" }
    ]
  }
}

```

Chat2DB will use `JdbcDriverManager` to load the `analyticsdb` driver class from the previously uploaded JAR and establish the connection.

## Summary

- **Driver metadata** is stored in the `DriverConfig` class, which captures URL patterns, class names, and custom properties.
- **File uploads** are handled by `DbJdbcDriverController` and persisted by `DbJdbcDriverServiceImpl` in a dedicated driver directory.
- **API conversion** between request DTOs and domain objects is managed by `JdbcDriverConverter.saveRequest2driverConfig()`.
- **Runtime isolation** is achieved through `JdbcDriverManager`, which uses dedicated `URLClassLoader` instances to load driver classes from JAR files without classpath contamination.

## Frequently Asked Questions

### What file format is required for custom JDBC drivers?

Chat2DB accepts standard **JAR files** containing the JDBC driver class and its dependencies. The `DbJdbcDriverServiceImpl` validates the uploaded file type and stores it in the application's driver directory, ready for classloader isolation by `JdbcDriverManager`.

### Can I configure a custom driver without uploading a JAR file?

Yes. If your driver is publicly available, specify the download URL in the `downloadJdbcDriverUrls` array within your `DriverConfig`. However, for air-gapped environments or proprietary drivers, you must use the `POST /api/jdbc/driver/upload` endpoint to make the JAR available to the Chat2DB server.

### How does Chat2DB prevent driver classpath conflicts?

The system uses **`JdbcDriverManager.getJDBCDriver()`**, which creates a separate `URLClassLoader` for each driver JAR. This isolation ensures that different versions of the same dependency (such as SLF4J or Guava) can coexist across multiple custom drivers without causing `ClassCastException` or linkage errors.

### Where are the uploaded driver configurations stored?

Driver configurations are persisted to the internal database via `DbJdbcDriverServiceImpl`, while the physical JAR files are stored in the file system under the application's configured driver directory. The `DriverConfig` entity maintains references to both the database records and the local file paths, enabling `JdbcDriverManager` to locate and load resources at runtime.