Skip to content

README.md

Latest commit

 

History

History
100 lines (82 loc) · 5.2 KB

README.md

File metadata and controls

100 lines (82 loc) · 5.2 KB

Tutorial: Getting Started with the AWS Advanced JDBC Wrapper, Spring Boot and Hibernate for load-balanced read-write and read-only connections (Single Datasource)

In this tutorial, you will set up a Spring Boot and Hibernate application with the AWS Advanced JDBC Wrapper, and use a single datasource to fetch and update data from an Aurora PostgreSQL database. The datasource is configured to provide a writer connection or a reader connection to off-load a writer node from read-only queries. It provides pooled connections through the AWS Advanced JDBC Wrapper internal connection pool configuration.

Note: this tutorial was written using the following technologies:

  • Spring Boot 3.4.4
  • Hibernate 6.x (via Spring Boot)
  • AWS Advanced JDBC Wrapper 3.3.0
  • Postgresql 42.7.10
  • Gradle 8
  • Java 17

You will progress through the following sections:

  1. Create a Gradle Spring Boot project
  2. Add the required Gradle dependencies
  3. Configure the AWS Advanced JDBC Wrapper

Pre-requisites

  • This tutorial uses the Amazon Aurora PostgreSQL database.

Step 1: Create a Gradle Project

Create a Gradle project with the following project hierarchy:

└───src
    └───main
        ├───java
        │   └───example
        │       ├───data
        │       │   ├───Book.java
        │       │   ├───BookRepository.java
        │       │   └───BookService.java
        │       └───spring
        │           ├───Config.java
        │           ├───ShouldRetryTransactionException.java
        │           └───SpringHibernateBalancedReaderOneDataSourceExampleApplication.java
        └───resources
                └───application.yml

Note: this sample code assumes the target database contains a table named Book that can be generated using the SQL queries provided in src/main/resources/books.sql.

Step 2: Add the required Gradle Dependencies

In your build.gradle.kts, add the following dependencies.

dependencies {
   implementation("org.springframework.boot:spring-boot-starter-jdbc")
   implementation("org.springframework.retry:spring-retry")
   implementation("org.postgresql:postgresql")
   implementation("software.amazon.jdbc:aws-advanced-jdbc-wrapper:latest")
}

Please note that the sample code inside the AWS Advanced JDBC Wrapper project will use the dependency implementation(project(":aws-advanced-jdbc-wrapper")) instead of implementation("software.amazon.jdbc:aws-advanced-jdbc-wrapper:latest") as seen above.

Step 3: Configure Spring and Hibernate

Configure Spring to use the AWS Advanced JDBC Wrapper as the default datasource.

  1. In the application.yml, add new datasources for Spring:

    spring:
  datasource:
    load-balanced-writer-and-reader-datasource:
      url: jdbc:aws-wrapper:postgresql://test-cluster.cluster-XYZ.us-east-2.rds.amazonaws.com:5432/postgres?wrapperProfileName=F0&readerHostSelectorStrategy=roundRobin
      username: dev_user
      password: dev_password
      driver-class-name: software.amazon.jdbc.Driver
      type: org.springframework.jdbc.datasource.SimpleDriverDataSource

  2. The datasource mentioned above does not use Hikari datasource that is default for Spring Boot 3+ application. The AWS Advanced JDBC Wrapper manages its own internal connection pool (or several connection pools, if needed), which increases overall efficiency and helps facilitate failover support. All necessary configuration parameters are defined in the F0 configuration profile. Other configuration presets D, E and F can be used as well. Any configuration profile or preset specified should use the Read/Write Splitting Plugin. More details are available at Configuration Profiles and Configuration Presets.

    Including the optional configuration parameter readerHostSelectorStrategy in the connection string helps to set up a strategy to select a reader node. Possible values are random, roundRobin and leastConnections. More details are available at Reader Selection Strategies.

  3. Configure Hibernate dialect:

    jpa:
 properties:
   hibernate:
     dialect: org.hibernate.dialect.PostgreSQLDialect

  4. [Optional] You can enable driver logging by adding the following to application.yml:

    logging:
   level:
     software:
       amazon:
         jdbc: INFO
         jdbc.states: INFO
     example: TRACE

For detailed logs use TRACE for software.amazon.jdbc package.

Start the application by running ./gradlew :springhibernateonedatasource:bootRun in the terminal. You should see the application making a connection to the database and fetching data from the Example table.

Summary

This tutorial walks through the steps required to add and configure the AWS Advanced JDBC Wrapper to a simple Spring Boot and Hibernate application.