DynamoDB backend
Latest stable Based on Leader release 0.4.0
Library module
Problem
Section titled “Problem”Preview: Validate API and operational behavior before production adoption.
Preview backend using DynamoDB conditional writes and logical lease expiry. It supports blocking, async, virtual-thread, coroutine, and group election.
When to use it
Section titled “When to use it”Use it for AWS workloads that already depend on DynamoDB and need region-local coordination without another service.
Coordinates
Section titled “Coordinates”Artifact: io.github.bluetape4k.leader:bluetape4k-leader-dynamodb
dependencies { implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>")) implementation("io.github.bluetape4k.leader:bluetape4k-leader-dynamodb")}Core concepts
Section titled “Core concepts”The table has string partition key lockName; rows store owner IDs, millisecond leaseExpiry, and second ttl. Correctness uses leaseExpiry; DynamoDB TTL is cleanup metadata only.
Quick start
Section titled “Quick start”val elector = DynamoDbLeaderElector( dynamoDbClient, DynamoDbLeaderElectionOptions(tableName = "bluetape4k_leader_locks"))elector.runIfLeader("export") { exportData() }API by task
Section titled “API by task”Choose sync, async-client suspend, virtual-thread, or group classes. The application provisions the table and owns both AWS clients.
Recommended patterns
Section titled “Recommended patterns”Use PAY_PER_REQUEST or capacity sized for contention, stable key prefixes, idempotent actions, and conditional owner checks for extend/release.
Integrations
Section titled “Integrations”Spring auto-configuration can use caller-owned AWS clients. The dynamodb-export example shows a complete job lifecycle.
Configuration
Section titled “Configuration”Configure table name, key prefix, wait/lease/minimum lease, retry behavior, and TTL attribute. Enable TTL on numeric ttl for cleanup.
Failure modes
Section titled “Failure modes”Conditional-check contention skips; SDK, IAM, throttling, and network failures propagate. TTL deletion delay must never decide whether acquisition is safe.
Operations
Section titled “Operations”Monitor consumed capacity, throttles, conditional failures, latency, stale-row count, and clock skew. Keep the table lifecycle in infrastructure code.
Testing
Section titled “Testing”Use DynamoDB Local/Testcontainers for two-client acquire, expiry, stale-owner release, group slots, suspend and virtual-thread paths.
Workshops and learning path
Section titled “Workshops and learning path”Run dynamodb-export and compare the AWS operational model with Redis or SQL backends.
Limitations
Section titled “Limitations”Preview status and eventually executed TTL cleanup require conservative operations. Cross-region coordination and global-table conflict behavior are outside this contract.
Release diagrams
Section titled “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-dynamodb architecture diagram
Section titled “leader-dynamodb architecture diagram”
Release README: leader-dynamodb/README.md
leader-dynamodb conditional lease sequence
Section titled “leader-dynamodb conditional lease sequence”
Release README: leader-dynamodb/README.md