JDBC Drivers — Official Catalog and Governance

Downloading a database driver from a dubious website, finding out about the incompatibility only in production and never knowing whether that JAR carries a known vulnerability: that was the invisible cost of connecting each new source. DATTA removes that risk with an official catalog of 39 JDBC drivers and a security validation pipeline that every JAR goes through — downloaded automatically or uploaded by you — before it becomes available to any connection.

Management lives in Sistema›Drivers JDBC, restricted to administrators. This guide covers your responsibilities over the catalog: initial installation, manual upload, validation, lifecycle and monitoring.

Who does what

The platform no longer performs an automatic bootstrap in the backend — all initialization was moved to setup-datta.sh (commit 277661e, "refactor: move all initial setup from backend to setup-datta.sh"). Once installed, drivers are managed at runtime through the screen and the administration API.

What already ships in the catalog (39 drivers)

• Open-source relational: PostgreSQL, MySQL, MariaDB, SQLite, H2, HSQLDB, Apache Derby, CockroachDB (uses the PostgreSQL driver) and TimescaleDB (same).
• Analytical / columnar: DuckDB, ClickHouse, Apache Druid (via Avatica), Apache Pinot, Apache Doris and StarRocks (both MySQL-compatible).
• Data warehouse / cloud: Snowflake, Amazon Redshift, Azure Synapse (SQL Server-compatible), Databricks (manual download), IBM Db2.
• Enterprise: Oracle (manual), Microsoft SQL Server, SAP HANA, Teradata (manual), IBM Informix (manual), SAP ASE jConnect (manual), Firebird (Jaybird), Vertica, Exasol.
• Query engines: Trino, PrestoDB, Apache Spark Thrift (via Hive JDBC), Apache Hive, Apache Impala (Cloudera, manual), Apache Phoenix, Apache Drill.
• Time-series: QuestDB (PostgreSQL-compatible), Apache IoTDB, InfluxDB 3.x (via Flight SQL).

That is 39 entries in the official catalog, versioned by a version tag the developer increments on every structural change (new field, license change).

SQL dialects: you write it once, the platform translates

Every driver in the catalog has a matching dialect registered in the platform's dialect library — today 39 dialects, some of them shared (CockroachDB reuses the PostgreSQL one, Synapse the SQL Server one). The dialect absorbs each vendor's differences:

• catalog introspection (ALL_TABLES versus information_schema);
• case sensitivity (Oracle works in upper case);
• identifier quoting;
• pagination (LIMIT/OFFSET, FETCH or ROWNUM);
• date types (TIMESTAMP, DATETIME2, TIMESTAMPTZ);
• MERGE/UPSERT syntax.

Architecture rule: vendor-specific logic lives in the dialect and nowhere else.

Initial installation (Phase 7 of setup-datta.sh)

When the operator runs ./setup-datta.sh, Phase 7 — "Download and upload of the official JDBC drivers" — does the following, in order:

1. Authenticates as an administrator to obtain the session credentials.
2. For each catalog driver that is neither an alias nor requires a manual download: downloads the JAR from the vendor's official URL into the installation's log directory and uploads it to the platform along with the metadata (key, version, vendor). The driver upload endpoint is described in the API reference.
3. The validation pipeline runs on the spot; if it passes, the driver is registered as Pendente (pending) and waits for your approval. The exception is the Neo4j JDBC driver, which the installation then approves through the official catalog when the vulnerability scan completes without a blocking finding (section Installation from the official catalog). If it stays pending, the installation ends with the warning "driver Neo4j JDBC pendente de aprovação" and the example Database Agents over CNPJ are not registered: approve the driver (Revalidar and Aprovar) and run again the agent registration that the warning points to.
4. Click-through license drivers are skipped with a warning — it is up to you to download and upload them through the screen (next section).

The --skip-drivers flag skips Phase 7 entirely: use it when you need to run the setup again without redoing the downloads.

Manual download: drivers with click-through licenses

Some vendors require explicit license acceptance on their own site. For those, the automatic download is skipped and the driver shows up in the table with the Download manual badge and a direct link to the official page:

Step by step: uploading the Oracle driver

1. Open the official page from the link on the driver's row and download the JAR, accepting the OTN license.
2. In Sistema›Drivers JDBC, click Adicionar driver.
3. Select the .jar file and fill in the name, vendor, version and driver class.
4. Confirm the upload. The validation pipeline runs on the spot; if it passes, the driver enters as Pendente (pending). Check the outcome in the driver's details and click Aprovar (approve): from then on it can be used in new connections.

If the same JAR has been uploaded before, the platform recognizes it by the SHA-256 hash and reuses the existing record instead of creating a duplicate — the event is recorded as DRIVER.UPLOAD_DEDUP.

Security validation: no JAR gets in without the pipeline

Every JAR — from the setup or uploaded by you — goes through five stages in sequence:

1. Static bytecode analysis: classes with dangerous calls (Runtime.exec, ProcessBuilder, System.loadLibrary) are rejected, and so are JARs too small to be a real driver.
2. Vulnerability scan against the local CVE database (Trivy / Grype): an unmitigated HIGH or CRITICAL finding blocks the driver.
3. Digital signature verification, when the vendor publishes an .asc or a .sha256 hash.
4. Isolated load test: the driver class is loaded in an isolated class loader, to guarantee it comes up without an unhandled exception before any real connection.
5. Safe JAR extraction and metadata inference, which complete the driver's record.

Failed at any stage? The validation outcome is recorded with the reason and the driver goes to Quarentena (quarantined) — it is never exposed for use.

When the vulnerability scan does not complete

The scan may not complete: the scanning tool is unavailable, the CVE database could not be downloaded, the scan was interrupted or returned a report outside the expected format. This is not treated as a clean scan:

• the driver stays Pendente (pending), with a warning from the scan stage in the validation outcome, and is never approved automatically;
• the severity recorded on the driver is SCAN_FAILED ("no scan"), with no CVE count and no scan date;
• a Revalidar (re-validate) that does not complete either is recorded as an attempt in the driver's CVE report, but does not erase the last valid result: a driver with a critical CVE keeps showing the critical one.

To release the driver, click Revalidar in its details; with a valid scan and no blocking finding, click Aprovar (approve).

Installation without internet. In the installation from the offline package, the CVE database is not included and the scanner has nowhere to download it from: every scan ends without completing, and Revalidar does not help. In this mode, only manual approval (Aprovar) takes a driver out of Pendente — check the JAR first, because the platform could not scan it.

Scan deadline and a queue of one scan at a time

Each vulnerability scan has a 180-second deadline. This value was measured: the first scan after the drivers service restarts downloads the CVE database and takes about 50 seconds on the on-premises profile and about 100 seconds on the minimum profile (half a core and 1 GB of memory); with the database already downloaded, a scan takes a few seconds. A scan that goes past the deadline is stopped and counts as a scan that did not complete (previous section), with the warning "A varredura de vulnerabilidades excedeu o prazo de 180 s" (the scan exceeded the 180 s deadline).

The CVE database lives in a temporary volume of its own in the drivers service, capped at 4 GB, outside the JAR volume and therefore outside the drivers backup. It survives a restart of the service, but not its re-creation: after a version release, the first scan downloads it again.

Only one scan runs at a time. Uploads, Revalidar (re-validate) and installation from the catalog join a queue, in order of arrival; the download and the other pipeline stages keep running in parallel. A request that waits too long in the queue gets the message "O verificador de vulnerabilidades está ocupado. Tente novamente em alguns minutos." (the vulnerability scanner is busy, try again in a few minutes). In that case nothing is recorded: the upload does not create the driver, Revalidar changes neither the report nor the status, and installation from the catalog marks the entry as failed, to be retried on the next installation. A driver never stays Pendente (pending) because of the queue.

How to read the Security column

The Segurança (security) column of the driver list and the header of the driver details show the summary of the driver's last valid scan:

The Segurança tab of the details lists the CVEs of the last valid scan, with the identifier, the affected component, the summary and the fixing version, and its title shows the scanner and its version (for example, trivy 0.56.2). When the tab says "Lista de CVEs ainda não registrada — use Revalidar" (CVE list not recorded yet — use re-validate), the driver has the summary (the column shows severity and count), but the detailed list was not stored yet: that is the case of drivers scanned before this platform version. A Revalidar stores the list. This message never means "no CVE".

The findings of the static analysis and of the other pipeline stages are not stored: the tab shows them after a Revalidar, until you close the details. When it finishes, Revalidar reports the severity and count found, or that the scan could not run because the JAR could not be analyzed.

Lifecycle and governance

The four statuses

A driver you upload that passes validation enters as Pendente and is only used after Aprovar (approve); a validation failure goes straight to Quarentena. The list's status filter shows each group: pick "Pendentes" to see what is waiting for approval, or "Todos os status" to see every driver.

Installation from the official catalog

The Popular drivers oficiais button (and the Instalar button on each catalog card) downloads the vendor's JAR, runs it through the same pipeline and approves the driver automatically only when all of these hold:

• validation recorded no error;
• the JAR is signed, when the platform policy requires a signature;
• the vulnerability scan completed;
• the scan found no CVE of blocking severity.

If any of them is missing, the driver stays Pendente, the catalog card shows Aguardando aprovação (awaiting approval) instead of "Instalado", and the installation log explains the reason. If the downloaded JAR was already registered as Pendente (for example, uploaded earlier through the screen), the platform scans it again before deciding, with the same rule — it never approves based on an old result.

A catalog driver that stayed Pendente is not re-evaluated by another Popular drivers oficiais: for the installation it is already installed. To release it, open it through the "Pendentes" filter, click Revalidar and, with a valid scan, Aprovar.

A Descontinuado (deprecated) driver is your decision and is respected: Popular drivers oficiais does not reinstall it (the log records skipped_deprecated) and never brings it back to Aprovado. If the driver's file disappeared from storage, the installation restores it, and the driver stays deprecated.

Only one catalog installation runs at a time. While one is in progress, a new Popular drivers oficiais, Instalar or Atualizar (in this or another tab) shows "Já existe um bootstrap de drivers em andamento. Aguarde a conclusão." (a bootstrap is already running; wait for it to finish) and does not start. Closing the tab interrupts the installation in progress; wait a few moments before retrying.

Catalog card badges

Each card under "Drivers oficiais disponíveis" shows one badge, evaluated in this order (the first one that applies wins):

Reinstalar (reinstall) downloads the JAR again and restores it on the existing driver without changing its status: a deprecated driver stays deprecated. The card of a deprecated driver has no button on purpose — bringing it back is your decision, with Reativar in the driver detail, and it is recorded in the audit trail. Atualizar (update) installs the new catalog version as a new driver, without touching the old one.

The "instalados" (installed) count at the top of the catalog counts only the cards with Instalado: deprecated drivers and drivers without a file are not included.

Administrator actions

Vendor documentation for the Copilot

The platform reindexes each driver's vendor documentation to feed the answers about that source. The ingestion runs in the background: the request answers immediately and progress is polled afterwards (RUNNING / COMPLETED / FAILED) — both endpoints are in the API reference. The crawl downloads same-level pages in parallel, controlled by datta.doc-ingest.crawl-concurrency (default 6), with a global time ceiling in datta.doc-ingest.crawl-timeout-seconds (default 120).

Audit trail

Every governance action emits an event:

Where the JAR is stored

The driver file lives on its own persistent volume (datta-drivers-pvc, 5 GB by default), separate from the driver record. They are two different things: the record holds name, version, hash and status; the file is what the services download in order to run queries.

If that volume is ephemeral, the symptom shows up far from the cause: after any restart — and every release is a restart — the catalog still lists the drivers as approved, and every database-agent query fails with Download falhou (HTTP 404) para driver <id>. Uploading the file again fixes it until the next release.

With more than one replica of the driver service, the volume must accept simultaneous read and write (ReadWriteMany): one replica writes the uploaded file and all the others must read it.

Monitoring

The drivers service publishes the datta.drivers.varredura.duracao metric: the duration of each vulnerability scan, including the wait in the queue, with the result in the outcome tag — ok (the scan completed), timeout (it went past the deadline), falha (it did not complete for another reason) and ocupado (it gave up on the queue). The latency of the other pipeline stages shows up in the service's HTTP request metrics.

Four signals deserve an alert:

Native sources stay out of the JDBC catalog

Sources with capabilities a generic JDBC driver cannot reach use the native connectors of the platform's execution engine — on purpose. Shipping a JDBC wrapper for them would trade the best of each engine for a lowest common denominator:

JDBC drivers for these sources do not enter the official catalog.

Named exception — Neo4j (Cypher, read-only). Neo4j's official JDBC driver is back in the catalog for a single use: the sample Database Agent that queries the CNPJ registry loaded into the platform itself, in Cypher and in a read session. The entry is deliberately narrow — SQL translation off, no GDS, writes refused — and it is not the data-integration path to Neo4j, which remains the native connector. See Database Agents in the user guide.

For developers: adding a driver to the catalog

Adding a new driver to the official catalog is a code change, made in the platform's official driver list:

1. Declare the entry with the driver's key.
2. Fill in name, vendor, version, driver class, source page, documentation URL, license type, sample JDBC URL, default port and tags.
3. If the JAR can be downloaded directly (Maven Central, for example), set the download URL; when the vendor publishes a .sha256, record the expected hash.
4. Click-through license: mark the driver as manual download and as requiring license acceptance.
5. Alias: point it at the base key (CockroachDB points at postgresql).
6. Register the matching dialect in the dialect library, if it does not exist yet.
7. Increment the catalog's version tag.
8. Adjust Phase 7 of setup-datta.sh only if the driver requires special handling — the generic loop covers the normal case.
9. Whenever possible, add a validation pipeline test.

Download host allowlist for the catalog

When a catalog driver is downloaded by the platform (catalog bootstrap through the administration API), the download is only accepted over HTTPS and from a host listed in datta.drivers.bootstrap.allowed-hosts, in the driver service's application.yml. The comparison ignores case, and the bootstrap does not follow redirects: a URL that answers 3xx fails. At boot, the service log reports how many hosts were loaded; an empty list logs a warning and turns the host check off.

To extend the list, add the vendor host to application.yml in the same change that adds the driver: the catalog test fails the build when a direct download uses a host outside it. You can also set the environment variable DATTA_DRIVERS_BOOTSTRAP_ALLOWEDHOSTS (comma-separated hosts), but it replaces the whole list instead of adding to it: repeat every host, including repo1.maven.org.

References

• Streaming runbook (Kafka/Debezium): Runbook — Streaming (F9).
• Connection operations, including credential backup and re-encryption: Runbook — Connection Management.
• Driver catalog, upload and documentation endpoints: API reference.