Spring Data DynamoDB: Integrating Amazon DynamoDB with Spring Boot in Production

Amazon DynamoDB is a fully managed, serverless, key-value and document database that delivers single-digit millisecond performance at any scale. It's a go-to choice for high-traffic applications like gaming leaderboards, session stores, and real-time analytics pipelines. However, integrating it with Spring Boot has traditionally been a pain point. The official AWS SDK 1.x for Java was verbose, required manual marshalling, and lacked the repository abstraction that Spring developers love. Spring Data DynamoDB (version 5.1.0 as of this writing) changes that by providing a familiar DynamoDBRepository interface, annotation-driven table mappings, and support for global secondary indexes. But let's be clear: this isn't your typical JPA/Hibernate experience. DynamoDB is schema-less, but the library imposes a schema via annotations. You trade flexibility for convenience. In this tutorial, I'll walk you through setting up a production-grade Spring Boot 3.2 application with DynamoDB, covering repository patterns, querying with secondary indexes, and handling the inevitable provisioned throughput exceptions that will hit you in production. I'll also share war stories from a real-time analytics system that processed 50,000 writes per second on DynamoDB, including the mistakes that cost us a weekend. By the end, you'll have a solid foundation to build scalable, resilient data layers with Spring Data DynamoDB.

Setting Up Spring Data DynamoDB in Your Project

First, add the required dependencies to your pom.xml. I'll use Spring Boot 3.2.0 and Spring Data DynamoDB 5.1.0. Note that the library is not part of Spring Initializr, so you'll need to add the Spring Milestone repository. Here's the Maven configuration:

<dependency>
    <groupId>io.github.boostchicken</groupId>
    <artifactId>spring-data-dynamodb</artifactId>
    <version>5.1.0</version>
</dependency>
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-dynamodb</artifactId>
    <version>1.12.500</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

What the Official Docs Won't Tell You

The official Spring Data DynamoDB documentation is sparse and sometimes misleading. Here's what I learned the hard way: First, the library does NOT support @Transactional annotations out of the box. DynamoDB transactions are supported via the TransactWriteItems API, but Spring Data DynamoDB doesn't wrap that. You'll need to use the low-level AmazonDynamoDB client for transactions. Second, the @DynamoDBTable annotation requires a tableName attribute that must match exactly the DynamoDB table name—case-sensitive. Third, the library's query methods like findByPartitionKeyAndSortKey only work if you define a @DynamoDBHashKey and @DynamoDBRangeKey in your entity. If you use a Global Secondary Index (GSI), you must annotate the GSI fields with @DynamoDBIndexHashKey and @DynamoDBIndexRangeKey, and enable the index in the repository interface with @EnableScan or @EnableGSI. Fourth, the library does NOT support pagination out of the box for custom queries—you'll have to handle LastEvaluatedKey manually. Finally, the default AmazonDynamoDB client configuration uses com.amazonaws.ClientConfiguration with a default connection timeout of 50 seconds, which is way too high for production. Always override it.

@Configuration
@EnableDynamoDBRepositories(basePackages = "com.example.repository")
public class DynamoDBConfig {

    @Bean
    public AmazonDynamoDB amazonDynamoDB() {
        ClientConfiguration clientConfig = new ClientConfiguration();
        clientConfig.setConnectionTimeout(5000); // 5 seconds
        clientConfig.setRequestTimeout(10000);   // 10 seconds
        clientConfig.setMaxConnections(100);

        return AmazonDynamoDBClientBuilder.standard()
                .withClientConfiguration(clientConfig)
                .withRegion(Regions.US_EAST_1)
                .build();
    }

    @Bean
    public DynamoDBMapper dynamoDBMapper(AmazonDynamoDB amazonDynamoDB) {
        return new DynamoDBMapper(amazonDynamoDB);
    }
}

Defining Your DynamoDB Entity with Annotations

Map your Java class to a DynamoDB table using annotations. The @DynamoDBTable specifies the table name. @DynamoDBHashKey marks the partition key, and @DynamoDBRangeKey marks the sort key. For attributes, use @DynamoDBAttribute. If you want to store complex nested objects, use @DynamoDBDocument annotation on the nested class, and the library will automatically serialize it as a Map. Be careful with attribute names: DynamoDB is case-sensitive, and the library uses the field name by default unless you specify attributeName. Also, avoid using reserved words like "Status" or "Count"—they'll cause errors unless you use expression attribute names. Here's an example entity for a payment transaction:

@DynamoDBTable(tableName = "payment_transactions")
public class PaymentTransaction {

    @DynamoDBHashKey(attributeName = "transaction_id")
    private String transactionId;

    @DynamoDBRangeKey(attributeName = "created_at")
    private Long createdAt;

    @DynamoDBAttribute(attributeName = "user_id")
    private String userId;

    @DynamoDBAttribute(attributeName = "amount")
    private BigDecimal amount;

    @DynamoDBAttribute(attributeName = "status")
    private String status; // Avoid reserved word? Use expression attribute names in queries.

    @DynamoDBAttribute(attributeName = "metadata")
    @DynamoDBDocument
    private PaymentMetadata metadata;

    // getters and setters
}

Creating a Repository for CRUD Operations

Spring Data DynamoDB provides DynamoDBRepository<PagingAndSortingRepository<T, ID>> interface. You can extend it to get basic CRUD operations like save, findById, findAll, delete, and count. For custom queries, you can define methods using the query derivation mechanism. However, the query derivation is limited compared to JPA. For example, findByUserIdAndStatus will work only if userId is a GSI hash key and status is a GSI range key, and you annotate the repository with @EnableScan or @EnableGSI. Otherwise, it will throw an exception because DynamoDB requires a partition key for queries. Here's a repository example:

@EnableScan
@EnableGSI
public interface PaymentTransactionRepository
    extends DynamoDBRepository<PaymentTransaction, String> {

    // Query by partition key (transactionId) and sort key (createdAt) range
    List<PaymentTransaction> findByTransactionIdAndCreatedAtBetween(
        String transactionId, Long start, Long end);

    // Query by GSI: userId (hash) and status (range) - requires @EnableGSI
    List<PaymentTransaction> findByUserIdAndStatus(
        String userId, String status);

    // Scan with filter (not efficient for large tables)
    @ScanEnabled
    List<PaymentTransaction> findByAmountGreaterThan(BigDecimal amount);
}

Advanced Querying with DynamoDBQueryExpression

For complex queries beyond derived methods, use DynamoDBQueryExpression with the DynamoDBMapper. This gives you full control over key conditions, filter expressions, and pagination. You'll need to inject DynamoDBMapper into your service. Here's an example that queries by a GSI with pagination:

@Service
public class PaymentService {

    @Autowired
    private DynamoDBMapper dynamoDBMapper;

    public List<PaymentTransaction> findByUserIdPaginated(
            String userId, String lastEvaluatedKey, int limit) {

        PaymentTransaction hashKey = new PaymentTransaction();
        hashKey.setUserId(userId);

        DynamoDBQueryExpression<PaymentTransaction> query =
            new DynamoDBQueryExpression<PaymentTransaction>()
                .withHashKeyValues(hashKey)
                .withIndexName("user_id_index")
                .withConsistentRead(false)
                .withLimit(limit);

        if (lastEvaluatedKey != null) {
            Map<String, AttributeValue> exclusiveStartKey = new HashMap<>();
            exclusiveStartKey.put("user_id", new AttributeValue(userId));
            exclusiveStartKey.put("created_at", new AttributeValue().withN(lastEvaluatedKey));
            query.withExclusiveStartKey(exclusiveStartKey);
        }

        QueryResultPage<PaymentTransaction> result =
            dynamoDBMapper.queryPage(PaymentTransaction.class, query);

        return result.getResults();
    }
}

Handling Provisioned Throughput Exceptions and Retries

In production, DynamoDB will throw ProvisionedThroughputExceededException when you exceed your read/write capacity. The AWS SDK has a built-in retry mechanism, but it's not enough for high-throughput systems. You should implement a client-side retry with exponential backoff and jitter. Additionally, use a Circuit Breaker pattern to fail fast when DynamoDB is overwhelmed. Here's an example using Resilience4j:

@Service
public class ResilientPaymentService {

    @Autowired
    private PaymentTransactionRepository repository;

    @Retry(name = "dynamoDBRetry", fallbackMethod = "fallback")
    public PaymentTransaction savePayment(PaymentTransaction payment) {
        return repository.save(payment);
    }

    public PaymentTransaction fallback(PaymentTransaction payment, Throwable t) {
        // Log and send to dead letter queue
        log.error("Failed to save payment after retries: {}", payment.getTransactionId(), t);
        // Optionally, store in SQS for later reprocessing
        return null;
    }

    // Resilience4j configuration in application.yml
}

Testing with DynamoDB Local and Testcontainers

For integration tests, use DynamoDB Local via Testcontainers. This spins up a real DynamoDB instance in a Docker container, allowing you to test your repository methods without mocking. Here's an example using JUnit 5 and Testcontainers:

@SpringBootTest
@Testcontainers
public class PaymentRepositoryTest {

    @Container
    static GenericContainer<?> dynamoDB = new GenericContainer<>(
            "amazon/dynamodb-local:1.21.0")
            .withExposedPorts(8000);

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("amazon.dynamodb.endpoint", () ->
            "http://" + dynamoDB.getHost() + ":" + dynamoDB.getMappedPort(8000));
    }

    @Autowired
    private PaymentTransactionRepository repository;

    @Test
    void testSaveAndFind() {
        PaymentTransaction payment = new PaymentTransaction();
        payment.setTransactionId("txn_001");
        payment.setCreatedAt(System.currentTimeMillis());
        payment.setUserId("user_123");
        payment.setAmount(new BigDecimal("99.99"));
        payment.setStatus("COMPLETED");

        repository.save(payment);

        Optional<PaymentTransaction> found = repository.findById("txn_001");
        assertTrue(found.isPresent());
        assertEquals("COMPLETED", found.get().getStatus());
    }
}

Monitoring and Debugging DynamoDB in Production

Monitoring DynamoDB is critical. Use AWS CloudWatch metrics for ConsumedReadCapacityUnits, ConsumedWriteCapacityUnits, ThrottledRequests, and SystemErrors. Set up alarms for throttling. Also, enable DynamoDB Streams to capture changes for auditing or event-driven architectures. For debugging, enable AWS SDK request logging by adding logging.level.com.amazonaws.request=DEBUG in your application.yml. Be careful: this logs all request/response data, including potentially sensitive information. In production, use selective logging with a custom RequestHandler2. Here's an example of enabling CloudWatch metrics via the AWS SDK:

@Bean
public AmazonDynamoDB amazonDynamoDB() {
    ClientConfiguration clientConfig = new ClientConfiguration();
    clientConfig.setConnectionTimeout(5000);
    clientConfig.setRequestTimeout(10000);

    // Enable CloudWatch metrics collection
    clientConfig.setMetricsCollectorClass(CloudWatchMetricsCollector.class);

    return AmazonDynamoDBClientBuilder.standard()
            .withClientConfiguration(clientConfig)
            .withRegion(Regions.US_EAST_1)
            .build();
}