Skip to content

Commit d388a98

Browse files
crystall-bitquillcrystall-bitquill
authored
docs: spring tx failover example (#638)
1 parent 5865cf8 commit d388a98

File tree

20 files changed

+695
-40
lines changed

20 files changed

+695
-40
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ The main idea behind the AWS JDBC Driver is to add a software layer on top of an
2222
In an Amazon Aurora database cluster, **failover** is a mechanism by which Aurora automatically repairs the cluster status when a primary DB instance becomes unavailable. It achieves this goal by electing an Aurora Replica to become the new primary DB instance, so that the DB cluster can provide maximum availability to a primary read-write DB instance. The AWS JDBC Driver is designed to understand the situation and coordinate with the cluster in order to provide minimal downtime and allow connections to be very quickly restored in the event of a DB instance failure.
2323

2424
### Benefits of the AWS JDBC Driver
25-
This is partially due to the time required for the DNS of the new primary DB instance to be fully resolved in order to properly direct the connection. The AWS JDBC Driver allows customers to continue using their existing community drivers in addition to having the AWS JDBC Driver fully exploit failover behavior by maintaining a cache of the Aurora cluster topology and each DB instance's role (Aurora Replica or primary DB instance). This topology is provided via a direct query to the Aurora DB, essentially providing a shortcut to bypass the delays caused by DNS resolution. With this knowledge, the AWS JDBC Driver can more closely monitor the Aurora DB cluster status so that a connection to the new primary DB instance can be established as fast as possible.
25+
Although Aurora is able to provide maximum availability through the use of failover, existing client drivers do not currently support this functionality. This is partially due to the time required for the DNS of the new primary DB instance to be fully resolved in order to properly direct the connection. The AWS JDBC Driver allows customers to continue using their existing community drivers in addition to having the AWS JDBC Driver fully exploit failover behavior by maintaining a cache of the Aurora cluster topology and each DB instance's role (Aurora Replica or primary DB instance). This topology is provided via a direct query to the Aurora DB, essentially providing a shortcut to bypass the delays caused by DNS resolution. With this knowledge, the AWS JDBC Driver can more closely monitor the Aurora DB cluster status so that a connection to the new primary DB instance can be established as fast as possible.
2626

2727
### Enhanced Failure Monitoring
2828
Since a database failover is usually identified by reaching a network or a connection timeout, the AWS JDBC Driver introduces an enhanced and customizable manner to faster identify a database outage.
@@ -102,6 +102,8 @@ To find all the documentation and concrete examples on how to use the AWS JDBC D
102102

103103
| Description | Examples |
104104
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
105+
| Using the AWS JDBC Driver to get a simple connection | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgConnectionSample.java) |
106+
| Using the AWS JDBC Driver with failover handling | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgFailoverSample.java) |
105107
| Using the AWS IAM Authentication Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationPostgresqlExample.java) <br/> [MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMysqlExample.java) <br/> [MariaDB](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMariadbExample.java) |
106108
| Using the AWS Secrets Manager Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsSecretsManagerConnectionPluginPostgresqlExample.java) <br/> [MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsSecretsManagerConnectionPluginMySQLExample.java) |
107109
| Using the AWS Credentials Manager to configure an alternative AWS credentials provider. | [PostgreSQL and MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsCredentialsManagerExample.java) |
@@ -112,6 +114,7 @@ To find all the documentation and concrete examples on how to use the AWS JDBC D
112114
| Using HikariCP with the `AWSWrapperDatasource` | [PostgreSQL](examples/HikariExample/src/main/java/software/amazon/HikariExample.java) |
113115
| Using HikariCP with the `AWSWrapperDatasource` with failover handling | [PostgreSQL](examples/HikariExample/src/main/java/software/amazon/HikariFailoverExample.java) |
114116
| Using Spring and HikariCP with the AWS JDBC Driver | [PostgreSQL](examples/SpringBootHikariExample/README.md) |
117+
| Using Spring and HikariCP with the AWS JDBC Driver and failover handling | [PostgreSQL](examples/SpringTxFailoverExample/README.md) |
115118
| Using Spring and Hibernate with the AWS JDBC Driver | [PostgreSQL](examples/SpringHibernateExample/README.md) |
116119
| Using Spring and Wildfly with the AWS JDBC Driver | [PostgreSQL](examples/SpringWildflyExample/README.md) |
117120
| Using Vert.x and c3p0 with the AWS JDBC Driver | [PostgreSQL](examples/VertxExample/README.md) |

‎docs/development-guide/DevelopmentGuide.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ Windows:
155155
For more information on how to run the integration tests, please visit [Integration Tests](/docs/development-guide/IntegrationTests.md).
156156

157157
#### Sample Code
158-
[Connection Test Sample Code](/docs/driver-specific/postgresql/ConnectionSample.java)
158+
[Connection Test Sample Code](./../../examples/AWSDriverExample/src/main/java/software/amazon/PgConnectionSample.java)
159159

160160
## Architecture
161161
For more information on how the AWS Advanced JDBC Driver functions and how it is structured, please visit [Architecture](./Architecture.md).

‎docs/using-the-jdbc-driver/UsingTheJdbcDriver.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ The AWS JDBC Driver uses the protocol prefix `jdbc:aws-wrapper:`. Internally, th
1111
## Getting a Connection
1212
To get a connection from the AWS JDBC Driver, the user application can either connect with a DriverManager or with a DataSource.
1313

14-
The process of getting a connection with a DriverManager will remain the same as with other JDBC Drivers; [this example](../driver-specific/postgresql/ConnectionSample.java) demonstrates establishing a connection with the PostgreSQL JDBC driver. Note that when connection properties are configured in both the connection string and with a Properties object, the connection string values will take precedence.
14+
The process of getting a connection with a DriverManager will remain the same as with other JDBC Drivers; [this example](./../../examples/AWSDriverExample/src/main/java/software/amazon/PgConnectionSample.java) demonstrates establishing a connection with the PostgreSQL JDBC driver. Note that when connection properties are configured in both the connection string and with a Properties object, the connection string values will take precedence.
1515

1616
Establishing a connection with a DataSource may require some additional steps.
1717
For detailed information and examples, review the [Datasource](./DataSource.md) documentation.

0 commit comments

Comments
 (0)