tramai-spring-boot-starter-sovereign-persistence-jdbc

Version: 0.6.0
Status: Preview
Role: Opt-in Spring Boot starter for JDBC-backed sovereign persistence.

Purpose

This add-on starter replaces the sovereign runtime's in-memory stores with the JDBC stores from tramai-persistence-jdbc: approvals, continuations, audit, the ops audit outbox, approval-mutation records and multi-node worker leases. It activates only when you add the dependency, set tramai.sovereign.persistence.type: jdbc and a DataSource is available in the context.

Like the file starter, it runs before tramai-spring-sovereign so JDBC stores exist before the base starter's in-memory defaults could be created; those defaults are @ConditionalOnMissingBean and back off. Application-managed stores and codecs always win.

What it provides

Codec beans qualify their key injection explicitly (@Qualifier("sovereignJdbcEncryptionKey")), so an unrelated SecretKey bean elsewhere in the application cannot be picked up by accident.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-boot-starter")
    implementation("dev.tramai:tramai-spring-boot-starter-sovereign-persistence-jdbc")
    runtimeOnly("org.postgresql:postgresql")
}

tramai:
  profile: sovereign
  sovereign:
    persistence:
      type: jdbc
      jdbc:
        claim-lease-duration: 5m
        max-claim-limit: 500
      encryption:
        key-env: TRAMAI_SOVEREIGN_STORE_KEY

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/tramai

The schema migrations shipped with tramai-persistence-jdbc must be applied to the database before startup; the starter validates the key and claims the stores but does not run migrations.

tramai.sovereign.persistence.jdbc.* controls the outbox claim lease duration and the maximum records claimed per cycle. With JDBC persistence you can also enable lease-coordinated workers (tramai.sovereign.ops.outbox.worker.lease-enabled: true) so several nodes do not dispatch the same outbox batch.

When to use this starter

• Multi-node sovereign deployments that must share approval, audit and outbox state.
• You want transactional approval writes and lease-coordinated workers.
• You need durable resume-credential custody for the approved-continuation resume worker.

When NOT to use this starter

• Single-node deployments with no database — use tramai-spring-boot-starter-sovereign-persistence-file.
• You want to choose or hand-write the schema; the module expects its own PostgreSQL migrations.
• You need persistence without the ops surface — the ops starter is part of this starter's composition.