Build a Spring Boot REST API with Amazon Aurora DSQL

---

This article is a cross-post of the AWS Database Blog post by John Thach and Mirron Panicker. Read the full walkthrough here: https://aws.amazon.com/blogs/database/build-a-spring-boot-rest-api-with-amazon-aurora-dsql/

---

Overview

In this post, we show how to build a Spring Boot REST API that integrates with Amazon Aurora DSQL. You'll configure the Aurora DSQL JDBC Connector for IAM authentication, implement optimistic concurrency control with retry logic, and run the application across two regional nodes to observe active-active behavior.

Architecture

The application uses:

• Spring Boot 3.3 (REST API framework)
• HikariCP (connection pooling)
• Aurora DSQL JDBC Connector (IAM auth, token refresh, TLS)
• Application Load Balancer (traffic distribution)

Two Spring Boot nodes (us-east-1 and us-west-2) each connect to their regional Aurora DSQL endpoint with synchronous cross-region replication between them.

Key Patterns

Aurora DSQL JDBC Connector Setup

The connector handles IAM authentication, token refresh, and TLS automatically:

spring.datasource.url=jdbc:aws-dsql:postgresql://<your-endpoint>.dsql.<region>.on.aws
spring.datasource.driver-class-name=software.amazon.dsql.jdbc.DSQLConnector
spring.datasource.username=<username>
spring.cloud.aws.region.static=<region>

Optimistic Concurrency Control

Aurora DSQL uses optimistic concurrency control instead of traditional locking. Two layers of handling are required:

Layer 1: Tell HikariCP not to evict the connection on a 40001 error

public static class DsqlExceptionOverride implements SQLExceptionOverride {
    public SQLExceptionOverride.Override adjudicate(SQLException ex) {
        if ("40001".equals(ex.getSQLState())) {
            return SQLExceptionOverride.Override.DO_NOT_EVICT;
        }
        return SQLExceptionOverride.Override.CONTINUE_EVICT;
    }
}

Layer 2: Retry the transaction with exponential backoff

@Retryable(
    retryFor = OptimisticLockingFailureException.class,
    maxAttemptsExpression = "${dsql.retry.max-attempts:4}",
    backoff = @Backoff(
        delayExpression      = "${dsql.retry.initial-delay-ms:100}",
        multiplierExpression = "${dsql.retry.multiplier:2.0}",
        maxDelayExpression   = "${dsql.retry.max-delay-ms:2000}",
        random = true
    ))

Multi-Region Concurrent Writes

The load test demonstrates active-active behavior: 500 concurrent +1 updates from us-east-1 and 500 concurrent -1 updates from us-west-2. All 1,000 operations succeed with the final stock returning to 1000, proving full consistency across regions.

Prerequisites

• AWS account with an Aurora DSQL cluster
• AWS CLI configured with credentials
• Java 17+, Maven 3.6+
• IAM user or role with dsql:DbConnectAdmin permission scoped to your cluster

Sample Code

The full sample application is available on GitHub: https://github.com/aws-samples/aurora-dsql-samples/tree/main/java/spring_boot

Key Takeaways

1. Aurora DSQL JDBC Connector handles IAM auth, token refresh, and TLS, reducing manual password management and SSL configuration.
2. Optimistic concurrency requires retry logic but enables better scalability than pessimistic locking. Two handling layers are needed: HikariCP exception override + Spring Retry.
3. Connection pooling with proper HikariCP configuration supports efficient connection reuse.

Security Considerations

• Scope IAM policies to specific cluster ARNs using dsql:DbConnect for non-admin users
• Use IAM roles (EC2 instance roles, ECS task roles) rather than long-lived access keys
• Place an ALB in front of application nodes with Route 53 health checks for regional failover

Production Considerations

• Add CloudWatch metrics for connection pool utilization, token refresh rates, and retry counts
• Use structured logging with correlation IDs
• Implement Spring Boot Actuator health indicators for load balancer integration
• Review Aurora DSQL DPU-based pricing for your workload

---

For the complete step-by-step walkthrough including cluster creation, deployment, and cleanup instructions, read the full blog post: https://aws.amazon.com/blogs/database/build-a-spring-boot-rest-api-with-amazon-aurora-dsql/