Exposed JDBC backend

Library module

Problem

Implements single and group election with Exposed JDBC transactions for blocking and virtual-thread services.

When to use it

Choose it when an operated relational database should also coordinate jobs and an extra coordination service is unjustified.

Coordinates

Artifact: io.github.bluetape4k.leader:bluetape4k-leader-exposed-jdbc

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-exposed-jdbc")
}

Core concepts

Conditional row transitions acquire leases; expiry and owner tokens stop an old holder releasing a newer lease.

Quick start

val elector = ExposedJdbcLeaderElector(database)
elector.runIfLeader("invoice-close") { closeInvoices() }

API by task

Use blocking, group, factory, extension, history-sink, or ExposedJdbcVirtualThreadLeaderElector APIs by task.

Recommended patterns

Create schema before traffic, keep acquire transactions short, and separate the protected business transaction unless atomic coupling is deliberate.

Integrations

Works with the release’s Exposed JDBC databases. Spring can build factories from a Database bean.

Configuration

Tune wait, lease, minimum lease, retry, schema, isolation, statement timeout, and pool capacity.

Failure modes

Contention returns null; connection, permission, schema, rollback, and retry-exhaustion failures propagate.

Operations

Watch database latency, pool saturation, retries, cleanup, indexes, and clock consistency.

Testing

Use the production dialect in Testcontainers and test two connections, expiry, stale-owner release, group capacity, and rollback.

Workshops and learning path

Run migration-gate, compare R2DBC, then use batch-scheduler for a Spring job.

Limitations

The database is on every acquire path. Lease and business action are not one transaction unless explicitly designed that way.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

leader exposed jdbc Class Structure diagram

Release README: leader-exposed-jdbc/README.md

Sources

Elector · Initializer · Stable guide