> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/jdbcclient/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/jdbcclient/readme.md).

# JdbcClient

## Introduction

The JdbcClient module manages connections and access to JDBC compatible databases (RDBMS).

Each module (instance) manages a single pooled connection to a single RDBMS (a destination). To configure connections to multiple servers, use multiple modules. To increase throughput, increase the number of module instances.

The module provides a service on the internal event bus with a JSON based protocol and a java library for simplified use.

This module is used for all internal JDBC access, including the bundled JDBC valves.

## Prerequisites

RDBMS specific driver available on class path.

## Configuration

{% hint style="info" %}
**Module name:** `JdbcClient | JDBCClient`
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>name</code></td><td>Destination name. Unique identifier for a specific configuration/connection/service. This value must be unique for all jdbcclient configurations.</td><td><code>"default"</code></td><td>false</td></tr><tr><td><code>instances</code></td><td>Number of instances to deploy</td><td><code>1</code></td><td>false</td></tr><tr><td><code>jdbc</code></td><td>JDBC connection object</td><td></td><td>false</td></tr><tr><td><code>jdbc.url</code></td><td>RDBMS specific JDBC URL</td><td></td><td>true</td></tr><tr><td><code>jdbc.user</code></td><td>Connection user</td><td></td><td>true</td></tr><tr><td><code>jdbc.password</code></td><td>Connection password</td><td></td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "name": "JdbcClient",
    "config": {
        "name": "default",
        "jdbc": {
            "url": "jdbc:hsqldb:file:target/db/test",
            "user": "SA",
            "password": "secret"
        }
    }
}
```

{% endtab %}
{% endtabs %}

### Driver

JDBC requires a RDBMS specific driver. This driver must be manually downloaded and added to the server class path (restart required).

## Audit

The JdbcClient can record an audit trail for write operations (INSERT, UPDATE, DELETE) and optionally read operations (SELECT). Audit logging is disabled by default and must be explicitly enabled per operation type.

When audit is enabled, the caller is expected to supply an `AuditContext` containing the subject (the authenticated user performing the operation) and a correlation ID. The JDBC valves automatically construct this context from the session and the pipe trace ID.

{% hint style="info" %}
Audit events are published fire-and-forget on the internal event bus. If no audit module is running, events are silently dropped — no errors are returned to the caller.
{% endhint %}

### Configuration

The `audit` block is placed at the top level of the module config, alongside `jdbc`.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="180">Name</th><th width="320">Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>audit.create</code></td><td>Record an audit event for INSERT statements.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>audit.update</code></td><td>Record an audit event for UPDATE statements.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>audit.delete</code></td><td>Record an audit event for DELETE statements.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>audit.read</code></td><td>Record an audit event for SELECT statements.</td><td><code>false</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "name": "JdbcClient",
  "config": {
    "name": "default",
    "jdbc": {
      "url": "jdbc:postgresql://localhost/mydb",
      "user": "appuser",
      "password": "secret"
    },
    "audit": {
      "create": true,
      "update": true,
      "delete": true
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Audit event content

Each audit event contains the following information extracted from the SQL statement and its parameters:

| Field        | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `operation`  | `CREATE` (INSERT), `UPDATE`, `DELETE`, or `READ` (SELECT)                 |
| `entityType` | Name of the primary table                                                 |
| `entityId`   | WHERE clause with `?` placeholders substituted by actual parameter values |
| `changes`    | Column names and values from SET (UPDATE) or VALUES (INSERT) clauses      |
| `subject`    | Authenticated user from the pipe session, or `anonymous`                  |
| `traceId`    | Pipe trace ID used as correlation ID                                      |