TramAI - governed AI workflows for Java and Kotlin

tramai-persistence-jdbc

Version: 0.6.0
Status: Preview
Role: PostgreSQL/JDBC-backed implementations of the sovereign store contracts.

Purpose

tramai-persistence-jdbc implements the store contracts owned by tramai-core, tramai-engine and tramai-security against a JDBC DataSource. It is the durable, multi-node option for sovereign deployments: approvals, continuations, audit streams, suspended invocations and the ops worker leases that coordinate several application nodes.

The module ships its own PostgreSQL schema (tramai/persistence/jdbc/postgres/V1…V7, covering sovereign persistence, approval continuations, audit events, outbox, worker leases and resume-credential custody). Applying those migrations to your database is a deployment step, not something the module does for you.

What it provides

TypeImplements
JdbcApprovalStoreApprovalStore
JdbcApprovalContinuationStoreApprovalContinuationStore (exactly-once claim, lazy expiry)
JdbcAuditStoreAuditStore (hash-chained, sequenced streams)
JdbcSuspendedInvocationStoreSuspendedInvocationStore
JdbcAuditPayloadCodec, JdbcContinuationArgumentsCodec, JdbcReplayEnvelopeCodecEncrypted payload encoding for the encrypted column types
JdbcEncryptedAuditPayload, JdbcEncryptedContinuationArguments, JdbcEncryptedReplayEnvelopeStored payload shapes

Failure semantics

Driver and connectivity failures do not leak SQL, table names, connection strings or vendor diagnostics. Every store statement is executed through the module's internal safe-operation wrapper (JdbcSafeOperation.kt), which converts an unexpected SQLException into IllegalStateException with a redacted diagnostic message. Coroutine cancellation and domain errors stay intact and unwrapped:

  • CancellationException and cancellation detected via rethrowIfCancellation() — propagated unchanged
  • TramaiException, ApprovalStoreException, ApprovalContinuationStoreException, IllegalArgumentException, IllegalStateException — rethrown unchanged
  • any other failure, including SQLException — IllegalStateException with the sanitized message

That is why surrounding catch (e: SQLException) blocks are wrong against these stores: no raw driver exception escapes them.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-persistence-jdbc")
}

Spring Boot applications wire these stores through tramai-spring-boot-starter-sovereign-persistence-jdbc:

tramai:
  sovereign:
    persistence:
      type: jdbc
      encryption:
        key-env: TRAMAI_SOVEREIGN_STORE_KEY

Store construction itself is composition-root work: the module takes a DataSource (and the encryption key material) from the caller and never owns connection lifecycle.

When to use this module

  • More than one application node must share sovereign approval, continuation and audit state.
  • You already run PostgreSQL and want the same transactional store for approvals and their audit outbox.
  • You need worker-lease coordination between nodes.

When NOT to use this module

  • A single node with no database — tramai-persistence-file is the encrypted local option.
  • You need a non-PostgreSQL dialect: the shipped schema and migrations are PostgreSQL-specific.
  • You want to add Spring wiring here — that belongs to the sovereign persistence starters.
Previous
Next