# Custom JDBC Drivers Introduction

Source: https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/introduction/

*Deployment availability: Self-hosted.*

Qualytics ships built-in support for a set of JDBC databases. To connect to a JDBC database that is not on the [available datastore connectors](https://userguide.qualytics.io/source-datastore/datastore/connection/available-datastore-connectors/) list, a self-hosted deployment can register a custom driver. Once registered, the database appears as a connector in the add-datastore picker, renders its own connection form, and its datastores sync, profile, and scan like any built-in JDBC connector.

## What a Custom Driver Is

A custom driver is two artifacts placed on the Dataplane classpath:

1. **The vendor JDBC driver JAR**: the third-party `.jar` containing the JDBC driver class and its dependencies.
2. **The YAML driver definition**: a single file at `META-INF/jdbc-drivers/<prefix>.yaml` describing the driver's identity, how the JDBC URL is assembled, and the fields the connection form should collect.

The YAML can live inside the vendor JAR or in its own JAR. Both work, as long as every artifact is on the classpath when the Dataplane starts. The simplest packaging puts everything in one JAR:

```text
my-driver.jar
├── com/example/ExampleDriver.class           # vendor JDBC driver
├── com/example/...                           # vendor support classes
└── META-INF/
    └── jdbc-drivers/
        └── exampledb.yaml                    # driver definition
```

The definition file is the contract between your driver and the platform. Its full shape, from required keys to the connection field vocabulary, is documented on the [Requirements](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/deep-dive/requirements/) page.

## Trust Model

A custom driver is a trusted addition to your deployment. Qualytics runs the driver code as-is: there is no sandboxing, code signing, or validation of the JAR contents. Treat a custom driver JAR the same way you treat any other dependency you bake into your deployment image, and only install drivers you would trust anywhere else in your infrastructure.

This is also why custom drivers are a self-hosted capability: the deployment operator owns the image the driver ships in, and takes responsibility for what runs inside it.

## Division of Responsibility

| Concern | Owner |
| --- | --- |
| The driver code, its dependencies, and its behavior against the database | You (and the database vendor) |
| The YAML definition: URL template, connection form fields, SQL capabilities | You |
| Discovery, validation, URL assembly, form rendering, and running operations through the driver | Qualytics |

---

## Deep Dive

Understand how Qualytics discovers and validates a custom driver, and the definition contract it must follow.

- **How It Works**

  Discovery at startup, strict validation, how the connection URL is assembled, and how the connector surfaces in the app.

  [How It Works](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/deep-dive/how-it-works/)
- **Requirements**

  The YAML definition contract: required keys, the connection field vocabulary, validation rules, and a complete example.

  [Requirements](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/deep-dive/requirements/)

---

## How-tos

Step-by-step instructions for getting a custom driver into your deployment.

- **Install a Custom JDBC Driver**

  Package the driver, add it to the Dataplane image, restart, and verify the connector appears.

  [Install](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/how-tos/install/)

---

## Troubleshooting & FAQ

- **Troubleshooting**

  What to check when the Dataplane refuses to start or the connector never appears.

  [Troubleshooting](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/troubleshooting/)
- **FAQ**

  Common questions about availability, overrides, dialects, enrichment, and upgrades.

  [FAQ](https://userguide.qualytics.io/self-hosted/custom-jdbc-drivers/faq/)

*Last updated: September 3, 2026.*
