Spring Framework Balanced Reader (2 datasource) example

Author: sergiyvamz

examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md

@@ -0,0 +1,100 @@
+# Tutorial: Getting Started with the AWS Advanced JDBC Driver, Spring Boot and Hibernate for load-balanced 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 Driver, 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 AWS Advanced JDBC Driver internal connection pool configuration.
+
+> Note: this tutorial was written using the following technologies:
+>    - Spring Boot 2.7.1
+>    - Hibernate
+>    - AWS JDBC Driver 2.3.2
+>    - Postgresql 42.5.4
+>    - Gradle 7
+>    - Java 11
+
+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 Driver
+
+## Pre-requisites
+- This tutorial uses the 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 JDBC Driver 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 Driver as the default datasource.
+
+1. In the `application.yml`, add new datasources for Spring:
+    ```yaml
+    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. Datasource mentioned above does not use Hikari datasource that is default for Spring 2+ application. The AWS JDBC Driver manages its own internal connection pool (or several connection pools, if needed). That increases overall efficiency and help to facilitate failover support. All necessary configuration parameters are defined in `F0` configuration profile. Other configuration presets `D`, `E` and `F` could be used as well. Configuration profile/preset should use [Read/Write Splitting Plugin](../docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md). More details are available at [Configuration Profiles](../docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#configuration-profiles) and [Configuration Presets](../docs/using-the-jdbc-driver/ConfigurationPresets.md).
+   <br><br>
+   Optional configuration parameter `readerHostSelectorStrategy` in connection string helps to setup a strategy selecting a reader node. Possible values are `random`, `roundRobin` and `leastConnections`. More details are available at [Reader Selection Strategies](../docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md#reader-selection-strategies).
+
+
+3. Configure Hibernate dialect:
+   ```yaml
+   jpa:
+    properties:
+      hibernate:
+        dialect: org.hibernate.dialect.PostgreSQLDialect
+   ```
+
+4. [Optional] You can enable driver logging by adding the following to `application.yml`:
+   ```yaml
+   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 Driver to a simple Spring Boot and Hibernate application.

examples/SpringHibernateBalancedReaderOneDataSourceExample/build.gradle.kts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+    id("org.springframework.boot") version "2.7.0"
+    id("io.spring.dependency-management") version "1.1.4"
+}
+
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
+    implementation("org.springframework.retry:spring-retry")
+    implementation("org.postgresql:postgresql:42.7.1")
+    implementation("software.amazon.awssdk:rds:2.22.13")
+    implementation(project(":aws-advanced-jdbc-wrapper"))
+}

examples/SpringHibernateBalancedReaderOneDataSourceExample/gradle.properties

@@ -0,0 +1,16 @@
+#    Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License").
+#    You may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+# Do not publish the Jar file for this subproject
+nexus.publish=false