> 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                                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fortifiedid.se/jdbcclient/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.