[MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMysqlExample.java)
[MariaDB](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMariadbExample.java) | | Using the AWS IAM Authentication Plugin with `DataSource` | [PostgreSQL and MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationDatasourceExample.java) | | Using the AWS Secrets Manager Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsSecretsManagerConnectionPluginPostgresqlExample.java)
[MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsSecretsManagerConnectionPluginMySQLExample.java) | | Using the AWS Credentials Manager to configure an alternative AWS credentials provider. | [PostgreSQL and MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsCredentialsManagerExample.java) | -| Using the AWS JDBC Driver with `AWSWrapperDatasource` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java) | +| Using the AWS Advanced JDBC Wrapper with `AWSWrapperDatasource` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java) | | Using the Driver Metadata Plugin to override driver name, this plugin [enables specific database features that may only be available to target drivers](https://github.com/aws/aws-advanced-jdbc-wrapper/issues/370) | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/DriverMetaDataConnectionPluginExample.java) | | Using the Read/Write Splitting Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingPostgresExample.java)
[MySQL](examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingMySQLExample.java) | | Using the Read/Write Splitting Plugin with Spring | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingSpringJdbcTemplatePostgresExample.java)
[MySQL](examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingSpringJdbcTemplateMySQLExample.java) | | Using HikariCP with the `AWSWrapperDatasource` | [PostgreSQL](examples/HikariExample/src/main/java/software/amazon/HikariExample.java) | | Using HikariCP with the `AWSWrapperDatasource` with failover handling | [PostgreSQL](examples/HikariExample/src/main/java/software/amazon/HikariFailoverExample.java) | -| Using Spring and HikariCP with the AWS JDBC Driver | [PostgreSQL](examples/SpringBootHikariExample/README.md) | -| Using Spring and HikariCP with the AWS JDBC Driver and failover handling | [PostgreSQL](examples/SpringTxFailoverExample/README.md) | -| Using Spring and Hibernate with the AWS JDBC Driver | [PostgreSQL](examples/SpringHibernateExample/README.md) | -| Using Spring and Wildfly with the AWS JDBC Driver | [PostgreSQL](examples/SpringWildflyExample/README.md) | -| Using Vert.x and c3p0 with the AWS JDBC Driver | [PostgreSQL](examples/VertxExample/README.md) | -| Using the AWS JDBC Driver with Telemetry and using the AWS Distro for OpenTelemetry Collector | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsOTLPExample.java) | -| Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](./examples/AWSDriverExample/src/main/java/software/amazon/TelemetryTracingXRayExample.java) | +| Using Spring and HikariCP with the AWS Advanced JDBC Wrapper | [PostgreSQL](examples/SpringBootHikariExample/README.md) | +| Using Spring and HikariCP with the AWS Advanced JDBC Wrapper and failover handling | [PostgreSQL](examples/SpringTxFailoverExample/README.md) | +| Using Spring and Hibernate with the AWS Advanced JDBC Wrapper | [PostgreSQL](examples/SpringHibernateExample/README.md) | +| Using Spring and Wildfly with the AWS Advanced JDBC Wrapper | [PostgreSQL](examples/SpringWildflyExample/README.md) | +| Using Vert.x and c3p0 with the AWS Advanced JDBC Wrapper | [PostgreSQL](examples/VertxExample/README.md) | +| Using the AWS Advanced JDBC Wrapper with Telemetry and using the AWS Distro for OpenTelemetry Collector | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsOTLPExample.java) | +| Using the AWS Advanced JDBC Wrapper with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](./examples/AWSDriverExample/src/main/java/software/amazon/TelemetryTracingXRayExample.java) | ## Getting Help and Opening Issues -If you encounter a bug with the AWS JDBC Driver, we would like to hear about it. +If you encounter a bug with the AWS Advanced JDBC Wrapper, we would like to hear about it. Please search the [existing issues](https://github.com/aws/aws-advanced-jdbc-wrapper/issues) to see if others are also experiencing the issue before reporting the problem in a new issue. GitHub issues are intended for bug reports and feature requests. When opening a new issue, please fill in all required fields in the issue template to help expedite the investigation process. diff --git a/docs/Documentation.md b/docs/Documentation.md index 07fe86a86..3e68db2a1 100644 --- a/docs/Documentation.md +++ b/docs/Documentation.md @@ -1,11 +1,11 @@ # Documentation - [Getting Started](./GettingStarted.md) -- [Using the AWS JDBC Driver](./using-the-jdbc-driver/UsingTheJdbcDriver.md) +- [Using the AWS Advanced JDBC Wrapper](./using-the-jdbc-driver/UsingTheJdbcDriver.md) - [Data Sources](./using-the-jdbc-driver/DataSource.md) - [Logging](./using-the-jdbc-driver/UsingTheJdbcDriver.md#logging) - [Telemetry](./using-the-jdbc-driver/Telemetry.md) - - [JDBC Wrapper Parameters](./using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) + - [JDBC Wrapper Parameters](./using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-wrapper-parameters) - [Database Dialects](./using-the-jdbc-driver/DatabaseDialects.md) - [Target Driver Dialects](./using-the-jdbc-driver/TargetDriverDialects.md) - [Plugins](./using-the-jdbc-driver/UsingTheJdbcDriver.md#plugins) @@ -24,7 +24,7 @@ - [Host Availability Strategy](./using-the-jdbc-driver/HostAvailabilityStrategy.md) - [Development Guide](./development-guide/DevelopmentGuide.md) - [Setup](./development-guide/DevelopmentGuide.md#setup) - - [Building the AWS JDBC Driver](./development-guide/DevelopmentGuide.md#building-the-aws-advanced-jdbc-driver) + - [Building the AWS Advanced JDBC Wrapper](./development-guide/DevelopmentGuide.md#building-the-aws-advanced-jdbc-wrapper) - [Testing Overview](./development-guide/DevelopmentGuide.md#testing-overview) - [Performance Tests](./development-guide/DevelopmentGuide.md#performance-tests) - [Running the Tests](./development-guide/DevelopmentGuide.md#running-the-tests) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 623360eb7..ea8d85c97 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -2,17 +2,17 @@ ## Minimum Requirements -Before using the AWS Advanced JDBC Driver, you must install: +Before using the AWS Advanced JDBC Wrapper, you must install: - Amazon Corretto 8+ or Java 8+. -- The AWS Advanced JDBC Driver. +- The AWS Advanced JDBC Wrapper. - Your choice of underlying JDBC driver. - To use the wrapper with Aurora with PostgreSQL compatibility, install the [PostgreSQL JDBC Driver](https://github.com/pgjdbc/pgjdbc). - To use the wrapper with Aurora with MySQL compatibility, install the [MySQL JDBC Driver](https://github.com/mysql/mysql-connector-j) or [MariaDB JDBC Driver](https://github.com/mariadb-corporation/mariadb-connector-j). -If you are using the AWS JDBC Driver as part of a Gradle project, include the wrapper and underlying driver as dependencies. For example, to include the AWS JDBC Driver and the PostgreSQL JDBC Driver as dependencies in a Gradle project, update the ```build.gradle``` file as follows: +If you are using the AWS Advanced JDBC Wrapper as part of a Gradle project, include the wrapper and underlying driver as dependencies. For example, to include the AWS Advanced JDBC Wrapper and the PostgreSQL JDBC Driver as dependencies in a Gradle project, update the ```build.gradle``` file as follows: -> **Note:** Depending on which features of the AWS JDBC Driver you use, you may have additional package requirements. Please refer to this [table](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#list-of-available-plugins) for more information. +> **Note:** Depending on which features of the AWS Advanced JDBC Wrapper you use, you may have additional package requirements. Please refer to this [table](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#list-of-available-plugins) for more information. ```gradle dependencies { @@ -21,11 +21,11 @@ dependencies { } ``` -## Obtaining the AWS JDBC Driver +## Obtaining the AWS Advanced JDBC Wrapper ### Direct Download and Installation -You can use pre-compiled packages that can be downloaded directly from [GitHub Releases](https://github.com/aws/aws-advanced-jdbc-wrapper/releases) or [Maven Central](https://central.sonatype.com/artifact/software.amazon.jdbc/aws-advanced-jdbc-wrapper) to install the AWS JDBC Driver. After downloading the AWS JDBC Driver, install it by including the .jar file in the application's CLASSPATH. +You can use pre-compiled packages that can be downloaded directly from [GitHub Releases](https://github.com/aws/aws-advanced-jdbc-wrapper/releases) or [Maven Central](https://central.sonatype.com/artifact/software.amazon.jdbc/aws-advanced-jdbc-wrapper) to install the AWS Advanced JDBC Wrapper. After downloading the AWS Advanced JDBC Wrapper, install it by including the .jar file in the application's CLASSPATH. For example, the following command uses wget to download the wrapper: @@ -33,17 +33,17 @@ For example, the following command uses wget to download the wrapper: wget https://github.com/aws/aws-advanced-jdbc-wrapper/releases/download/2.6.6/aws-advanced-jdbc-wrapper-2.6.6.jar ``` -Then, the following command adds the AWS JDBC Driver to the CLASSPATH: +Then, the following command adds the AWS Advanced JDBC Wrapper to the CLASSPATH: ```bash export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-advanced-jdbc-wrapper-2.6.6.jar ``` -> **Note**: There is also a JAR suffixed with `-bundle-federated-auth`. It is an Uber JAR that contains the AWS JDBC Driver as well as all the dependencies needed to run the Federated Authentication Plugin. **Our general recommendation is to use the `aws-advanced-jdbc-wrapper-2.6.6.jar` for use cases unrelated to complex Federated Authentication environments**. To learn more, please check out the [Federated Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md#bundled-uber-jar). +> **Note**: There is also a JAR suffixed with `-bundle-federated-auth`. It is an Uber JAR that contains the AWS Advanced JDBC Wrapper as well as all the dependencies needed to run the Federated Authentication Plugin. **Our general recommendation is to use the `aws-advanced-jdbc-wrapper-2.6.6.jar` for use cases unrelated to complex Federated Authentication environments**. To learn more, please check out the [Federated Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md#bundled-uber-jar). ### As a Maven Dependency -You can use [Maven's dependency management](https://central.sonatype.com/artifact/software.amazon.jdbc/aws-advanced-jdbc-wrapper) to obtain the AWS JDBC Driver by adding the following configuration to the application's Project Object Model (POM) file: +You can use [Maven's dependency management](https://central.sonatype.com/artifact/software.amazon.jdbc/aws-advanced-jdbc-wrapper) to obtain the AWS Advanced JDBC Wrapper by adding the following configuration to the application's Project Object Model (POM) file: ```xml
Otherwise: No
:warning:If `clusterId` is omitted when using a non-standard RDS URL, you may experience various issues. | A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. | None | -| `wrapperLoggerLevel` | `String` | No | Logger level of the AWS JDBC Driver.
If it is used, it must be one of the following values: `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. | `null` | +| `wrapperLoggerLevel` | `String` | No | Logger level of the AWS Advanced JDBC Wrapper.
If it is used, it must be one of the following values: `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. | `null` | | `database` | `String` | No | Database name. | `null` | | `user` | `String` | No | Database username. | `null` | | `password` | `String` | No | Database password. | `null` | | `wrapperDialect` | `String` | No | Please see [this page on database dialects](./DatabaseDialects.md), and whether you should include it. | `null` | -| `wrapperLogUnclosedConnections` | `Boolean` | No | Allows the AWS JDBC Driver to capture a stacktrace for each connection that is opened. If the `finalize()` method is reached without the connection being closed, the stacktrace is printed to the log. This helps developers to detect and correct the source of potential connection leaks. | `false` | +| `wrapperLogUnclosedConnections` | `Boolean` | No | Allows the AWS Advanced JDBC Wrapper to capture a stacktrace for each connection that is opened. If the `finalize()` method is reached without the connection being closed, the stacktrace is printed to the log. This helps developers to detect and correct the source of potential connection leaks. | `false` | | `loginTimeout` | `Integer` | No | Login timeout in milliseconds. | `null` | | `connectTimeout` | `Integer` | No | Socket connect timeout in milliseconds. | `null` | | `socketTimeout` | `Integer` | No | Socket timeout in milliseconds. | `null` | | `tcpKeepAlive` | `Boolean` | No | Enable or disable TCP keep-alive probe. | `false` | -| `targetDriverAutoRegister` | `Boolean` | No | Allows the AWS JDBC Driver to register a target driver based on `wrapperTargetDriverDialect` configuration parameter or, if it's missed, on a connection url protocol. | `true` | +| `targetDriverAutoRegister` | `Boolean` | No | Allows the AWS Advanced JDBC Wrapper to register a target driver based on `wrapperTargetDriverDialect` configuration parameter or, if it's missed, on a connection url protocol. | `true` | | `transferSessionStateOnSwitch` | `Boolean` | No | Enables transferring the session state to a new connection. | `true` | | `resetSessionStateOnClose` | `Boolean` | No | Enables resetting the session state before closing connection. | `true` | | `rollbackOnSwitch` | `Boolean` | No | Enables rolling back a current transaction, if any in effect, before switching to a new connection. | `true` | @@ -99,7 +99,7 @@ These parameters are applicable to any instance of the AWS JDBC Driver. | `skipWrappingForPackages` | `String` | No | Register Java package names (separated by comma) which will be left unwrapped. This setting modifies all future connections established by the driver, not just a particular connection. | `com.pgvector` | ## Plugins -The AWS JDBC Driver uses plugins to execute JDBC methods. You can think of a plugin as an extensible code module that adds extra logic around any JDBC method calls. The AWS JDBC Driver has a number of [built-in plugins](#list-of-available-plugins) available for use. +The AWS Advanced JDBC Wrapper uses plugins to execute JDBC methods. You can think of a plugin as an extensible code module that adds extra logic around any JDBC method calls. The AWS Advanced JDBC Wrapper has a number of [built-in plugins](#list-of-available-plugins) available for use. Plugins are loaded and managed through the Connection Plugin Manager and may be identified by a `String` name in the form of plugin code. @@ -108,7 +108,7 @@ Plugins are loaded and managed through the Connection Plugin Manager and may be | Parameter | Value | Required | Description | Default Value | |-----------------------------------|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------| | `wrapperPlugins` | `String` | No | Comma separated list of connection plugin codes.
Example: `failover,efm2` | `auroraConnectionTracker,failover2,efm2` | -| `autoSortWrapperPluginOrder` | `Boolean` | No | Allows the AWS JDBC Driver to sort connection plugins to prevent plugin misconfiguration. Allows a user to provide a custom plugin order if needed. | `true` | +| `autoSortWrapperPluginOrder` | `Boolean` | No | Allows the AWS Advanced JDBC Wrapper to sort connection plugins to prevent plugin misconfiguration. Allows a user to provide a custom plugin order if needed. | `true` | | `wrapperProfileName` | `String` | No | Driver configuration profile name. Instead of listing plugin codes with `wrapperPlugins`, the driver profile can be set with this parameter.
Example: See [below](#configuration-profiles). | `null` | To use a built-in plugin, specify its relevant plugin code for the `wrapperPlugins`. @@ -129,7 +129,7 @@ properties.setProperty("wrapperPlugins", ""); The Wrapper behaves like the target driver when no plugins are used. ### Configuration Profiles -An alternative way of loading plugins and providing configuration parameters is to use a configuration profile. You can create custom configuration profiles that specify which plugins the AWS JDBC Driver should load. After creating the profile, set the [`wrapperProfileName`](#connection-plugin-manager-parameters) parameter to the name of the created profile. +An alternative way of loading plugins and providing configuration parameters is to use a configuration profile. You can create custom configuration profiles that specify which plugins the AWS Advanced JDBC Wrapper should load. After creating the profile, set the [`wrapperProfileName`](#connection-plugin-manager-parameters) parameter to the name of the created profile. This method of loading plugins will most often be used by those who require custom plugins that cannot be loaded with the [`wrapperPlugins`](#connection-plugin-manager-parameters) parameter, or by those who are using preset configurations. Besides a list of plugins to load and configuration properties, configuration profiles may also include the following items: @@ -167,19 +167,19 @@ ConfigurationProfileBuilder.from("existingProfileName") DriverConfigurationProfiles.remove("testProfile"); ``` -The AWS JDBC Driver team has gathered and analyzed various user scenarios to create commonly used configuration profiles, or presets, for users. These preset configuration profiles are optimized, profiled, verified and can be used right away. Users can create their own configuration profiles based on the built-in presets as shown above. More details could be found at the [Configuration Presets](./ConfigurationPresets.md) page. +The AWS Advanced JDBC Wrapper team has gathered and analyzed various user scenarios to create commonly used configuration profiles, or presets, for users. These preset configuration profiles are optimized, profiled, verified and can be used right away. Users can create their own configuration profiles based on the built-in presets as shown above. More details could be found at the [Configuration Presets](./ConfigurationPresets.md) page. ### Executing Custom Code When Initializing a Connection In some use cases you may need to define a specific configuration for a new driver connection before your application can use it. For instance: - you might need to run some initial SQL queries when a connection is established, or; - you might need to check for some additional conditions to determine the initialization configuration required for a particular connection. -The AWS JDBC Driver allows specifying a special function that can initialize a connection. It can be done with `Driver.setConnectionInitFunc` method. The `resetConnectionInitFunc` method is also available to remove the function. +The AWS Advanced JDBC Wrapper allows specifying a special function that can initialize a connection. It can be done with `Driver.setConnectionInitFunc` method. The `resetConnectionInitFunc` method is also available to remove the function. The initialization function is called for all connections, including connections opened by the internal connection pools (see [Using Read Write Splitting Plugin and Internal Connection Pooling](./using-plugins/UsingTheReadWriteSplittingPlugin.md#internal-connection-pooling)). This helps user applications clean up connection sessions that have been altered by previous operations, as returning a connection to a pool will reset the state and retrieving it will call the initialization function again. > [!WARNING]\ -> Executing CPU and network intensive code in the initialization function may significantly impact the AWS JDBC Driver's overall performance. +> Executing CPU and network intensive code in the initialization function may significantly impact the AWS Advanced JDBC Wrapper's overall performance. ```java Driver.setConnectionInitFunc((connection, protocol, hostSpec, props) -> { @@ -192,7 +192,7 @@ Driver.setConnectionInitFunc((connection, protocol, hostSpec, props) -> { ### List of Available Plugins -The AWS JDBC Driver has several built-in plugins that are available to use. Please visit the individual plugin page for more details. +The AWS Advanced JDBC Wrapper has several built-in plugins that are available to use. Please visit the individual plugin page for more details. | Plugin name | Plugin Code | Database Compatibility | Description | Additional Required Dependencies | |-------------------------------------------------------------------------------------------------------------------|---------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -273,15 +273,15 @@ repositories { } ``` -## AWS JDBC Driver for MySQL Migration Guide +## AWS Advanced JDBC Wrapper for MySQL Migration Guide **[The Amazon Web Services (AWS) JDBC Driver for MySQL](https://github.com/awslabs/aws-mysql-jdbc)** allows an application to take advantage of the features of clustered MySQL databases. It is based on and can be used as a drop-in compatible for the [MySQL Connector/J driver](https://github.com/mysql/mysql-connector-j), and is compatible with all MySQL deployments. -The AWS JDBC Driver has the same functionalities as the AWS JDBC Driver for MySQL, as well as additional features such as support for Read/Write Splitting. This -section highlights the steps required to migrate from the AWS JDBC Driver for MySQL to the AWS JDBC Driver. +The AWS Advanced JDBC Wrapper has the same functionalities as the AWS Advanced JDBC Wrapper for MySQL, as well as additional features such as support for Read/Write Splitting. This +section highlights the steps required to migrate from the AWS Advanced JDBC Wrapper for MySQL to the AWS Advanced JDBC Wrapper. ### Replacement Steps @@ -293,13 +293,13 @@ section highlights the steps required to migrate from the AWS JDBC Driver for My ### Plugins Configuration -In the AWS JDBC Driver for MySQL, plugins are set by providing a list of connection plugin factories: +In the AWS Advanced JDBC Wrapper for MySQL, plugins are set by providing a list of connection plugin factories: ```java "jdbc:mysql:aws://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:3306/db?connectionPluginFactories=com.mysql.cj.jdbc.ha.plugins.AWSSecretsManagerPluginFactory,com.mysql.cj.jdbc.ha.plugins.failover.FailoverConnectionPluginFactory,com.mysql.cj.jdbc.ha.plugins.NodeMonitoringConnectionPluginFactory" ``` -In the AWS JDBC Driver, plugins are set by specifying the plugin codes: +In the AWS Advanced JDBC Wrapper, plugins are set by specifying the plugin codes: ```java "jdbc:aws-wrapper:mysql://db-identifier.XYZ.us-east-2.rds.amazonaws.com:3306/db?wrapperPlugins=iam,failover" @@ -308,14 +308,14 @@ In the AWS JDBC Driver, plugins are set by specifying the plugin codes: To see the list of available plugins and their associated plugin code, see the [documentation](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#list-of-available-plugins). -The AWS JDBC Driver also provides +The AWS Advanced JDBC Wrapper also provides the [Read-Write Splitting plugin](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md#read-write-splitting-plugin), this plugin allows the application to switch the connections between writer and reader instances by calling the `Connection#setReadOnly` method. ### Example Configurations -#### Using the IAM Authentication Plugin with AWS JDBC Driver for MySQL +#### Using the IAM Authentication Plugin with AWS Advanced JDBC Wrapper for MySQL ```java public static void main(String[] args) throws SQLException { @@ -332,7 +332,7 @@ public static void main(String[] args) throws SQLException { } ``` -#### Using the IAM Authentication Plugin with AWS JDBC Driver +#### Using the IAM Authentication Plugin with AWS Advanced JDBC Wrapper ```java public static void main(String[] args) throws SQLException { @@ -350,18 +350,18 @@ public static void main(String[] args) throws SQLException { } ``` -The IAM Authentication Plugin in the AWS JDBC Driver has extra parameters to support custom endpoints. For more +The IAM Authentication Plugin in the AWS Advanced JDBC Wrapper has extra parameters to support custom endpoints. For more information, -see [How do I use IAM with the AWS Advanced JDBC Driver?](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md#how-do-i-use-iam-with-the-aws-jdbc-driver) +see [How do I use IAM with the AWS Advanced JDBC Wrapper?](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md#how-do-i-use-iam-with-the-aws-advanced-jdbc-wrapper) ### Secrets Manager Plugin -The Secrets Manager Plugin in both the AWS JDBC Driver for MySQL and the AWS JDBC Driver uses the same configuration -parameters. To migrate to the AWS JDBC Driver, simply change +The Secrets Manager Plugin in both the AWS Advanced JDBC Wrapper for MySQL and the AWS Advanced JDBC Wrapper uses the same configuration +parameters. To migrate to the AWS Advanced JDBC Wrapper, simply change the `connectionPluginFactories=com.mysql.cj.jdbc.ha.plugins.AWSSecretsManagerPluginFactory` parameter to `wrapperPlugins=awsSecretsManager` -#### Using the AWS Secrets Manager Plugin with AWS JDBC Driver for MySQL +#### Using the AWS Secrets Manager Plugin with AWS Advanced JDBC Wrapper for MySQL ```java public static void main(String[] args) throws SQLException { @@ -378,7 +378,7 @@ public static void main(String[] args) throws SQLException { } } ``` -#### Using the AWS Secrets Manager Plugin with AWS JDBC Driver +#### Using the AWS Secrets Manager Plugin with AWS Advanced JDBC Wrapper ```java public static void main(String[] args) throws SQLException { @@ -398,10 +398,10 @@ public static void main(String[] args) throws SQLException { ``` ## Enable Logging -To enable logging in the AWS JDBC Driver, change the `logger=StandardLogger` parameter to `wrapperLoggerLevel=FINEST` +To enable logging in the AWS Advanced JDBC Wrapper, change the `logger=StandardLogger` parameter to `wrapperLoggerLevel=FINEST` ## Enable Third Party Classes and Packages -Depending on the requirements of a user's application, the AWS Advanced JDBC Driver performs special handling before and after operating on a database connection. This is achievable by wrapping over relevant data objects. +Depending on the requirements of a user's application, the AWS Advanced JDBC Wrapper performs special handling before and after operating on a database connection. This is achievable by wrapping over relevant data objects. Not all data objects require special handling and thus can be left unwrapped. One example being classes from the PGVector package. The driver allows you to specify such classes and packages that should be left intact with no wrapping. If needed, use the following code snippet as an example to register data objects that should be left unwrapped. @@ -412,6 +412,6 @@ Driver.skipWrappingForType(com.pgvector.PGbit.class); Driver.skipWrappingForPackage("com.pgvector"); ``` -This feature can be used to allow the AWS Advanced JDBC Driver to properly handle popular database extensions like [PGvector](https://github.com/pgvector/pgvector-java) and [PostGIS](https://github.com/postgis/postgis-java). +This feature can be used to allow the AWS Advanced JDBC Wrapper to properly handle popular database extensions like [PGvector](https://github.com/pgvector/pgvector-java) and [PostGIS](https://github.com/postgis/postgis-java). Using `Driver.skipWrappingForPackage()` method and using driver configuration parameter `skipWrappingForPackages` are functionally similar. The configuration parameter receives a comma separated list of package names while `Driver.skipWrappingForPackage()` accepts just one package at at time. diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md index 9ca6e0787..bd1059a61 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md @@ -1,9 +1,9 @@ # AWS Secrets Manager Plugin -The AWS Advanced JDBC Driver supports usage of database credentials stored as secrets in the [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) through the AWS Secrets Manager Connection Plugin. When you create a new connection with this plugin enabled, the plugin will retrieve the secret and the connection will be created with the credentials inside that secret. +The AWS Advanced JDBC Wrapper supports usage of database credentials stored as secrets in the [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) through the AWS Secrets Manager Connection Plugin. When you create a new connection with this plugin enabled, the plugin will retrieve the secret and the connection will be created with the credentials inside that secret. ## Enabling the AWS Secrets Manager Connection Plugin -> :warning: **Note:** To use this plugin, you must include the runtime dependencies [Jackson Databind](https://central.sonatype.com/artifact/com.fasterxml.jackson.core/jackson-databind) and [AWS Secrets Manager](https://central.sonatype.com/artifact/software.amazon.awssdk/secretsmanager) in your project. These parameters are required for the AWS JDBC Driver to pass database credentials to the underlying driver. +> :warning: **Note:** To use this plugin, you must include the runtime dependencies [Jackson Databind](https://central.sonatype.com/artifact/com.fasterxml.jackson.core/jackson-databind) and [AWS Secrets Manager](https://central.sonatype.com/artifact/software.amazon.awssdk/secretsmanager) in your project. These parameters are required for the AWS Advanced JDBC Wrapper to pass database credentials to the underlying driver. To enable the AWS Secrets Manager Connection Plugin, add the plugin code `awsSecretsManager` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value, or to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). @@ -29,4 +29,4 @@ The plugin assumes that the secret contains the following properties `username` ### Example [AwsSecretsManagerConnectionPluginPostgresqlExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/AwsSecretsManagerConnectionPluginPostgresqlExample.java) -demonstrates using the AWS Advanced JDBC Driver to make a connection to a PostgreSQL database using credentials fetched from the AWS Secrets Manager. +demonstrates using the AWS Advanced JDBC Wrapper to make a connection to a PostgreSQL database using credentials fetched from the AWS Secrets Manager. diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md index a85f9ea4f..6fdca42fe 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md @@ -4,7 +4,7 @@ The [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue-green-deployments/introduction.html) technique enables organizations to release applications by seamlessly shifting traffic between two identical environments running different versions of the application. This strategy effectively mitigates common risks associated with software deployment, such as downtime and limited rollback capability. -The AWS JDBC Driver leverages the Blue/Green Deployment approach by intelligently managing traffic distribution between blue and green nodes, minimizing the impact of stale DNS data and connectivity disruptions on user applications. +The AWS Advanced JDBC Wrapper leverages the Blue/Green Deployment approach by intelligently managing traffic distribution between blue and green nodes, minimizing the impact of stale DNS data and connectivity disruptions on user applications. ## Prerequisites > [!WARNING]\ @@ -50,7 +50,7 @@ During a [Blue/Green switchover](https://docs.aws.amazon.com/AmazonRDS/latest/Us - Internal security certificates are regenerated to accommodate the new node names -All factors mentioned above may cause application disruption. The AWS Advanced JDBC Driver aims to minimize the application disruption during Blue/Green switchover by performing the following actions: +All factors mentioned above may cause application disruption. The AWS Advanced JDBC Wrapper aims to minimize the application disruption during Blue/Green switchover by performing the following actions: - Actively monitors Blue/Green switchover status and implements appropriate measures to suspend, pass-through, or re-route database traffic - Prior to Blue/Green switchover initiation, compiles a comprehensive inventory of cluster and instance endpoints for both blue and green nodes along with their corresponding IP addresses - During the active switchover phase, temporarily suspends execution of JDBC calls to blue nodes, which helps unload database nodes and reduces transaction lag for green nodes, thereby enhancing overall switchover performance @@ -61,7 +61,7 @@ All factors mentioned above may cause application disruption. The AWS Advanced J Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). -## How do I use Blue/Green Deployment Plugin with the AWS JDBC Driver? +## How do I use Blue/Green Deployment Plugin with the AWS Advanced JDBC Wrapper? To enable the Blue/Green Deployment functionality, add the plugin code `bg` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) parameter value. The Blue/Green Deployment Plugin supports the following configuration parameters: @@ -105,7 +105,7 @@ properties.setProperty("blue-green-monitoring-socketTimeout", "10000"); ## Plan your Blue/Green switchover in advance -To optimize Blue/Green switchover support with the AWS JDBC Driver, advance planning is essential. Please follow these recommended steps: +To optimize Blue/Green switchover support with the AWS Advanced JDBC Wrapper, advance planning is essential. Please follow these recommended steps: 1. Create a Blue/Green Deployment for your database. 2. Configure your application by incorporating the `bg` plugin along with any additional parameters of your choice, then deploy your application to the corresponding environment. diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md index 612dbdf2c..3fd6ad54b 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md @@ -9,7 +9,7 @@ Verify plugin compatibility within your driver configuration using the [compatib - [AWS Java SDK RDS v2.7.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds) - Note: The above dependencies may have transitive dependencies that are also required (ex. AWS Java SDK RDS requires [AWS Java SDK Core](https://central.sonatype.com/artifact/software.amazon.awssdk/aws-core/)). If you are not using a package manager such as Maven or Gradle, please refer to Maven Central to determine these transitive dependencies. -## How to use the Custom Endpoint Plugin with the AWS JDBC Driver +## How to use the Custom Endpoint Plugin with the AWS Advanced JDBC Wrapper ### Enabling the Custom Endpoint Plugin diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md index 01c3db395..a00399b3f 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md @@ -1,5 +1,5 @@ # Failover Plugin v2 -The AWS Advanced JDBC Driver uses the Failover Plugin v2 to provide minimal downtime in the event of a DB instance failure. The plugin is the next version (v2) of the [Failover Plugin](./UsingTheFailoverPlugin.md) and unless explicitly stated otherwise, most of the information and suggestions for the Failover Plugin are applicable to the Failover Plugin v2. +The AWS Advanced JDBC Wrapper uses the Failover Plugin v2 to provide minimal downtime in the event of a DB instance failure. The plugin is the next version (v2) of the [Failover Plugin](./UsingTheFailoverPlugin.md) and unless explicitly stated otherwise, most of the information and suggestions for the Failover Plugin are applicable to the Failover Plugin v2. ## Differences between the Failover Plugin and the Failover Plugin v2 @@ -43,7 +43,7 @@ With the `failover2` plugin: - The `MonitoringRdsHostListProvider` continues topology monitoring at an increased rate to ensure all cluster nodes appear in the topology. ## Using the Failover Plugin v2 -The Failover Plugin v2 will be enabled by default if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. If you would like to override the default plugins, you can explicitly include the failover plugin v2 in your list of plugins by adding the plugin code `failover2` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). After you load the plugin, the failover feature will be enabled. +The Failover Plugin v2 will be enabled by default if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. If you would like to override the default plugins, you can explicitly include the failover plugin v2 in your list of plugins by adding the plugin code `failover2` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-wrapper-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). After you load the plugin, the failover feature will be enabled. Please refer to the [failover configuration guide](../FailoverConfigurationGuide.md) for tips to keep in mind when using the failover plugin. @@ -53,13 +53,13 @@ Please refer to the [failover configuration guide](../FailoverConfigurationGuide Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). ### Failover Plugin v2 Configuration Parameters -In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters for the AWS JDBC Driver through the connection URL to specify additional failover behavior. +In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters for the AWS Advanced JDBC Wrapper through the connection URL to specify additional failover behavior. | Parameter | Value | Required | Description | Default Value | |---------------------------------------|:--------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `failoverMode` | String | No | Defines a mode for failover process. Failover process may prioritize nodes with different roles and connect to them. Possible values:
- `strict-writer` - Failover process follows writer node and connects to a new writer when it changes.
- `reader-or-writer` - During failover, the driver tries to connect to any available/accessible reader node. If no reader is available, the driver will connect to a writer node. This logic mimics the logic of the Aurora read-only cluster endpoint.
- `strict-reader` - During failover, the driver tries to connect to any available reader node. If no reader is available, the driver raises an error. Reader failover to a writer node will only be allowed for single-node clusters. This logic mimics the logic of the Aurora read-only cluster endpoint.
If this parameter is omitted, default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | Default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | | `clusterInstanceHostPattern` | String | If connecting using an IP address or custom domain URL: Yes
Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](#host-pattern) for more information.
Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`
Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection string should look like this: `jdbc:aws-wrapper:mysql://customHost:1234/test?clusterInstanceHostPattern=?.customHost` | If the provided connection string is not an IP address or custom domain, the JDBC Driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. | -| `clusterTopologyRefreshRateMs` | Integer | No | Cluster topology refresh rate in milliseconds when a cluster is not in failover. It refers to the regular, slow monitoring rate explained above. | `30000` | +| `clusterTopologyRefreshRateMs` | Integer | No | Cluster topology refresh rate in milliseconds when a cluster is not in failover. It refers to the regular, slow monitoring rate ex``plained above. | `30000` | | `failoverTimeoutMs` | Integer | No | Maximum allowed time in milliseconds to attempt reconnecting to a new writer or reader instance after a cluster failover is initiated. | `300000` | | `clusterTopologyHighRefreshRateMs` | Integer | No | Interval of time in milliseconds to wait between attempts to update cluster topology after the writer has come back online following a failover event. It corresponds to the increased monitoring rate described earlier. Usually, the topology monitoring component uses this increased monitoring rate for 30s after a new writer was detected. | `100` | | `failoverReaderHostSelectorStrategy` | String | No | Strategy used to select a reader node during failover. For more information on the available reader selection strategies, see this [table](../ReaderSelectionStrategies.md). | `random` | diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md index 73b246fb6..0fd47cb2f 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md @@ -1,11 +1,11 @@ # Failover Plugin -In an Amazon Aurora database (DB) cluster, failover is a mechanism by which Aurora automatically repairs the DB 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 Advanced JDBC Driver uses the Failover Plugin to coordinate with this behavior in order to provide minimal downtime in the event of a DB instance failure. +In an Amazon Aurora database (DB) cluster, failover is a mechanism by which Aurora automatically repairs the DB 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 Advanced JDBC Wrapper uses the Failover Plugin to coordinate with this behavior in order to provide minimal downtime in the event of a DB instance failure. -## The AWS Advanced JDBC Driver Failover Process +## The AWS Advanced JDBC Wrapper Failover Process
Please refer to the [failover configuration guide](../FailoverConfigurationGuide.md) for tips to keep in mind when using the failover plugin. +The Failover Plugin v1 will **NOT** be enabled by default. Instead, the newer [Failover Plugin v2](./UsingTheFailover2Plugin.md) will be enabled by default if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. If you would like to use the Failover Plugin v1 instead of v2, it must be explicitly included by adding the plugin code `failover` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-wrapper-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). After you load the plugin, the failover feature will be enabled by default and the enableClusterAwareFailover parameter will be set to true.
Please refer to the [failover configuration guide](../FailoverConfigurationGuide.md) for tips to keep in mind when using the failover plugin. Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). ### Failover Parameters -In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters to the AWS JDBC Driver through the connection URL to specify additional failover behavior. +In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters to the AWS Advanced JDBC Wrapper through the connection URL to specify additional failover behavior. | Parameter | Value | Required | Description | Default Value | |----------------------------------------|:--------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `failoverMode` | String | No | Defines a mode for failover process. Failover process may prioritize nodes with different roles and connect to them. Possible values:
- `strict-writer` - Failover process follows writer node and connects to a new writer when it changes.
- `reader-or-writer` - During failover, the driver tries to connect to any available/accessible reader node. If no reader is available, the driver will connect to a writer node. This logic mimics the logic of the Aurora read-only cluster endpoint.
- `strict-reader` - During failover, the driver tries to connect to any available reader node. If no reader is available, the driver raises an error. Reader failover to a writer node will only be allowed for single-node clusters. This logic mimics the logic of the Aurora read-only cluster endpoint.
If this parameter is omitted, default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | Default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | | `clusterId` | `String` | If connecting using a non-standard RDS URL (e.g. an IP address, custom endpoint, rds proxy, or custom domain URL): Yes
Otherwise: No
:warning:If `clusterId` is omitted when using a non-standard RDS URL, you may experience various issues. | A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. | None | | `clusterInstanceHostPattern` | String | If connecting using an IP address or custom domain URL: Yes
Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](#host-pattern) for more information.
Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`
Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection string should look like this: `jdbc:aws-wrapper:mysql://customHost:1234/test?clusterInstanceHostPattern=?.customHost` | If the provided connection string is not an IP address or custom domain, the JDBC Driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. | -| `enableClusterAwareFailover` | Boolean | No | Set to `true` to enable the fast failover behavior offered by the AWS Advanced JDBC Driver. Set to `false` for simple JDBC connections that do not require fast failover functionality. | `true` | +| `enableClusterAwareFailover` | Boolean | No | Set to `true` to enable the fast failover behavior offered by the AWS Advanced JDBC Wrapper. Set to `false` for simple JDBC connections that do not require fast failover functionality. | `true` | | `failoverClusterTopologyRefreshRateMs` | Integer | No | Cluster topology refresh rate in milliseconds during a writer failover process. During the writer failover process, cluster topology may be refreshed at a faster pace than normal to speed up discovery of the newly promoted writer. | `2000` | | `failoverReaderConnectTimeoutMs` | Integer | No | Maximum allowed time in milliseconds to attempt to connect to a reader instance during a reader failover process. | `30000` | | `failoverTimeoutMs` | Integer | No | Maximum allowed time in milliseconds to attempt reconnecting to a new writer or reader instance after a cluster failover is initiated. | `300000` | @@ -39,7 +39,7 @@ In addition to the parameters that you can configure for the underlying driver, | ~~`enableFailoverStrictReader`~~ | Boolean | No | This parameter is no longer available and, if specified, it will be ignored by the driver. See `failoverMode` (`reader-or-writer` or `strict-reader`) for more details. | | ## Host Pattern -When connecting to Aurora clusters, the [`clusterInstanceHostPattern`](#failover-parameters) parameter is required if the connection string does not provide enough information about the database cluster domain name. If the Aurora cluster endpoint is used directly, the AWS JDBC Driver will recognize the standard Aurora domain name and can re-build a proper Aurora instance name when needed. In cases where the connection string uses an IP address, a custom domain name, or localhost, the driver won't know how to build a proper domain name for a database instance endpoint. For example, if a custom domain was being used and the cluster instance endpoints followed a pattern of `instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc., the driver would need to know how to construct the instance endpoints using the specified custom domain. Since there isn't enough information from the custom domain alone to create the instance endpoints, you should set the `clusterInstanceHostPattern` to `?.customHost`, making the connection string `jdbc:aws-wrapper:postgresql://customHost:1234/test?clusterInstanceHostPattern=?.customHost`. Refer to [this diagram](../../images/failover_behavior.png) about AWS JDBC Driver behavior during failover for different connection URLs and more details and examples. +When connecting to Aurora clusters, the [`clusterInstanceHostPattern`](#failover-parameters) parameter is required if the connection string does not provide enough information about the database cluster domain name. If the Aurora cluster endpoint is used directly, the AWS Advanced JDBC Wrapper will recognize the standard Aurora domain name and can re-build a proper Aurora instance name when needed. In cases where the connection string uses an IP address, a custom domain name, or localhost, the driver won't know how to build a proper domain name for a database instance endpoint. For example, if a custom domain was being used and the cluster instance endpoints followed a pattern of `instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc., the driver would need to know how to construct the instance endpoints using the specified custom domain. Since there isn't enough information from the custom domain alone to create the instance endpoints, you should set the `clusterInstanceHostPattern` to `?.customHost`, making the connection string `jdbc:aws-wrapper:postgresql://customHost:1234/test?clusterInstanceHostPattern=?.customHost`. Refer to [this diagram](../../images/failover_behavior.png) about AWS Advanced JDBC Wrapper behavior during failover for different connection URLs and more details and examples. ## Failover Exception Codes @@ -50,17 +50,17 @@ When connecting to Aurora clusters, the [`clusterInstanceHostPattern`](#failover | 08007 - Transaction Resolution Unknown | Yes | Yes | Yes | Yes | Yes | Yes | ### 08001 - Unable to Establish SQL Connection -When the AWS JDBC Driver throws a FailoverFailedSQLException, the original connection has failed, and the AWS JDBC Driver tried to failover to a new instance, but was unable to. There are various reasons this may happen: no nodes were available, a network failure occurred, and so on. In this scenario, please wait until the server is up or other problems are solved. (Exception will be thrown.) +When the AWS Advanced JDBC Wrapper throws a FailoverFailedSQLException, the original connection has failed, and the AWS Advanced JDBC Wrapper tried to failover to a new instance, but was unable to. There are various reasons this may happen: no nodes were available, a network failure occurred, and so on. In this scenario, please wait until the server is up or other problems are solved. (Exception will be thrown.) ### 08S02 - Communication Link -When the AWS JDBC Driver throws a FailoverSuccessSQLException, the original connection has failed while outside a transaction, and the AWS JDBC Driver successfully failed over to another available instance in the cluster. However, any session state configuration of the initial connection is now lost. In this scenario, you should: +When the AWS Advanced JDBC Wrapper throws a FailoverSuccessSQLException, the original connection has failed while outside a transaction, and the AWS Advanced JDBC Wrapper successfully failed over to another available instance in the cluster. However, any session state configuration of the initial connection is now lost. In this scenario, you should: - Reuse and reconfigure the original connection (e.g., reconfigure session state to be the same as the original connection). - Repeat that query that was executed when the connection failed, and continue work as desired. ### 08007 - Transaction Resolution Unknown -When the AWS JDBC Driver throws a TransactionStateUnknownSQLException, the original connection has failed within a transaction. In this scenario, the JDBC wrapper first attempts to rollback the transaction and then fails over to another available instance in the cluster. Note that the rollback might be unsuccessful as the initial connection may be broken at the time that the JDBC wrapper recognizes the problem. Note also that any session state configuration of the initial connection is now lost. In this scenario, you should: +When the AWS Advanced JDBC Wrapper throws a TransactionStateUnknownSQLException, the original connection has failed within a transaction. In this scenario, the JDBC wrapper first attempts to rollback the transaction and then fails over to another available instance in the cluster. Note that the rollback might be unsuccessful as the initial connection may be broken at the time that the JDBC wrapper recognizes the problem. Note also that any session state configuration of the initial connection is now lost. In this scenario, you should: - Reuse and reconfigure the original connection (e.g: reconfigure session state to be the same as the original connection). @@ -71,19 +71,19 @@ When the AWS JDBC Driver throws a TransactionStateUnknownSQLException, the origi #### Sample Code [PostgreSQL Failover Sample Code](./../../../examples/AWSDriverExample/src/main/java/software/amazon/PgFailoverSample.java) ->### :warning: Warnings About Proper Usage of the AWS Advanced JDBC Driver +>### :warning: Warnings About Proper Usage of the AWS Advanced JDBC Wrapper >1. A common practice when using JDBC drivers is to wrap invocations against a Connection object in a try-catch block, and dispose of the Connection object if an Exception is hit. If this practice is left unaltered, the application will lose the fast-failover functionality offered by the JDBC Driver. When failover occurs, the JDBC Driver internally establishes a ready-to-use connection inside the original Connection object before throwing an exception to the user. If this Connection object is disposed of, the newly established connection will be thrown away. The correct practice is to check the SQL error code of the exception and reuse the Connection object if the error code indicates successful failover. The [PostgreSQL Failover Sample Code](./../../../examples/AWSDriverExample/src/main/java/software/amazon/PgFailoverSample.java) demonstrates this practice. See the section about [Failover Exception Codes](#failover-exception-codes) for more details.
>2. We highly recommended that you use the cluster and read-only cluster endpoints instead of the direct instance endpoints of your Aurora cluster, unless you are confident in your application's use of instance endpoints. Although the JDBC Driver will correctly failover to the new writer instance when using instance endpoints, use of these endpoints is discouraged because individual instances can spontaneously change reader/writer status when failover occurs. The JDBC Driver will always connect directly to the instance specified if an instance endpoint is provided, so a write-safe connection cannot be assumed if the application uses instance endpoints. ## Connection Pooling -The AWS Advanced JDBC Driver is compatible with [connection pooling](../DataSource.md#Using-the-AwsWrapperDataSource-with-Connection-Pooling-Frameworks), but some connection pooling libraries may contain additional behaviour when dealing with SQL exceptions. This means the exceptions created by the AWS JDBC Driver may not be recognized, and depending on the connection pool, connections may be closed prematurely due to the unrecognized SQL exceptions. Users are recommended to investigate the connection pooling library of their choice, and to implement any required additional code to allow the connection pool to accept the exceptions raised by the AWS JDBC Driver. +The AWS Advanced JDBC Wrapper is compatible with [connection pooling](../DataSource.md#Using-the-AwsWrapperDataSource-with-Connection-Pooling-Frameworks), but some connection pooling libraries may contain additional behaviour when dealing with SQL exceptions. This means the exceptions created by the AWS Advanced JDBC Wrapper may not be recognized, and depending on the connection pool, connections may be closed prematurely due to the unrecognized SQL exceptions. Users are recommended to investigate the connection pooling library of their choice, and to implement any required additional code to allow the connection pool to accept the exceptions raised by the AWS Advanced JDBC Wrapper. ### HikariCP The failover plugin throws failover-related exceptions that need to be handled explicitly by HikariCP, otherwise connections will be closed immediately after failover. When using HikariCP with the failover plugin, you need to provide a custom exception override class. -The AWS JDBC Driver provides a custom exception override class for HikariCP; to use it, +The AWS Advanced JDBC Wrapper provides a custom exception override class for HikariCP; to use it, configure the HikariDataSource as follows: ```java diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md index ced3434c8..25bd73445 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md @@ -27,7 +27,7 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). ### Bundled Uber JAR -Included in AWS JDBC Driver release, is an Uber JAR that bundles the AWS JDBC Driver and all the package dependencies needed to use the Federated Authentication Plugin. +Included in AWS Advanced JDBC Wrapper release, is an Uber JAR that bundles the AWS Advanced JDBC Wrapper and all the package dependencies needed to use the Federated Authentication Plugin. It is suffixed with `-bundle-federated-auth`. This JAR is a drop-in ready solution and is **recommended for customers who do not have an automated package manager like Maven or Gradle**. @@ -41,7 +41,7 @@ If you would like to download and install the bundled Uber JAR, follow these [in > [!NOTE]\ > The bundled Uber JAR may trigger warnings of duplicate entries in the JAR Manifest File. This is because the bundle Uber JAR Manifest file also includes the JAR Manifest file of its dependencies, and as a result will trigger warnings. -## How to use the Federated Authentication Plugin with the AWS JDBC Driver +## How to use the Federated Authentication Plugin with the AWS Advanced JDBC Wrapper ### Enabling the Federated Authentication Plugin Note: AWS IAM database authentication is needed to use the Federated Authentication Plugin. This is because after the plugin acquires the authentication token (ex. SAML Assertion in the case of AD FS), the authentication token is then used to acquire an AWS IAM token. The AWS IAM token is then subsequently used to access the database. diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md index 5e0cc4802..89a117869 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md @@ -24,10 +24,10 @@ Although these alternatives are available, EFM is more configurable than simple This option is useful when a user application executes quick statements that run for predictable lengths of time. In this case, the network timeout should be set to a value such as the 95th to 99th percentile. One way to do this is with the `setNetworkTimeout` method. #### TCP Keepalive -This option is useful because it is built into the TCP protocol. How you enable it depends on the underlying driver provided to the AWS JDBC Driver. For example, to enable TCP Keepalive with an underlying PostgreSQL driver, you will need to set the property `tcpKeepAlive` to `true`. TCP Keepalive settings, which are similar to some Enhanced Failure Monitoring parameters, are all configurable. However, this is specific to operating systems, so you should verify what your system needs before configuring TCP Keepalive on your system. See [this page](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.BestPractices.FastFailover.html) for more information on how to set TCP Keepalive parameters. +This option is useful because it is built into the TCP protocol. How you enable it depends on the underlying driver provided to the AWS Advanced JDBC Wrapper. For example, to enable TCP Keepalive with an underlying PostgreSQL driver, you will need to set the property `tcpKeepAlive` to `true`. TCP Keepalive settings, which are similar to some Enhanced Failure Monitoring parameters, are all configurable. However, this is specific to operating systems, so you should verify what your system needs before configuring TCP Keepalive on your system. See [this page](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.BestPractices.FastFailover.html) for more information on how to set TCP Keepalive parameters. ### Enabling the Host Monitoring Connection Plugin -Enhanced Failure Monitoring will be enabled by default enabled if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. The Host Monitoring Connection Plugin can also be explicitly included by adding the plugin code `efm` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters). Enhanced Failure Monitoring is enabled by default when the Host Monitoring Connection Plugin is loaded, but it can be disabled with the parameter `failureDetectionEnabled` set to `false`. +Enhanced Failure Monitoring will be enabled by default enabled if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. The Host Monitoring Connection Plugin can also be explicitly included by adding the plugin code `efm` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-wrapper-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#aws-advanced-jdbc-wrapper-parameters). Enhanced Failure Monitoring is enabled by default when the Host Monitoring Connection Plugin is loaded, but it can be disabled with the parameter `failureDetectionEnabled` set to `false`. > :warning: **Note:** When loading the Host Monitoring Connection Plugin, the order plugins are loaded in matters. We recommend that you load the Host Monitoring Connection Plugin at the end (or as close to the end) as possible. When used in conjunction with the Failover Connection Plugin, the Host Monitoring Connection Plugin must be loaded after the Failover Connection Plugin. For example, when loading plugins with the `wrapperPlugins` parameter, the parameter value should be `failover,...,efm`. > @@ -69,10 +69,10 @@ properties.setProperty("monitoring-socketTimeout", "10"); > > The Host Monitoring Connection Plugin does not have default timeout values such as `connectTimeout` or `socketTimeout` since these values are driver specific. Most JDBC drivers use 0 as the default timeout value. If you **do not** override the default timeout value, the Host Monitoring Connection Plugin may wait forever to establish a monitoring connection in the event where the database node is unavailable. ->### :warning: Warnings About Usage of the AWS Advanced JDBC Driver with RDS Proxy +>### :warning: Warnings About Usage of the AWS Advanced JDBC Wrapper with RDS Proxy > We recommend you either disable the Host Monitoring Connection Plugin or avoid using RDS Proxy endpoints when the Host Monitoring Connection Plugin is active. > -> Although using RDS Proxy endpoints with the AWS Advanced JDBC Driver with Enhanced Failure Monitoring doesn't cause any critical issues, we don't recommend this approach. The main reason is that RDS Proxy transparently re-routes requests to a single database instance. RDS Proxy decides which database instance is used based on many criteria (on a per-request basis). Switching between different instances makes the Host Monitoring Connection Plugin useless in terms of instance health monitoring because the plugin will be unable to identify which instance it's connected to, and which one it's monitoring. This could result in false positive failure detections. At the same time, the plugin will still proactively monitor network connectivity to RDS Proxy endpoints and report outages back to a user application if they occur. +> Although using RDS Proxy endpoints with the AWS Advanced JDBC Wrapper with Enhanced Failure Monitoring doesn't cause any critical issues, we don't recommend this approach. The main reason is that RDS Proxy transparently re-routes requests to a single database instance. RDS Proxy decides which database instance is used based on many criteria (on a per-request basis). Switching between different instances makes the Host Monitoring Connection Plugin useless in terms of instance health monitoring because the plugin will be unable to identify which instance it's connected to, and which one it's monitoring. This could result in false positive failure detections. At the same time, the plugin will still proactively monitor network connectivity to RDS Proxy endpoints and report outages back to a user application if they occur. # Host Monitoring Plugin v2 diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md index d76d7f503..ee56dbc60 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md @@ -23,12 +23,12 @@ This plugin requires valid AWS credentials. See more details at [AWS Credentials Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). ## AWS IAM Database Authentication -The AWS JDBC Driver supports Amazon AWS Identity and Access Management (IAM) authentication. When using AWS IAM database authentication, the host URL must be a valid Amazon endpoint, and not a custom domain or an IP address. +The AWS Advanced JDBC Wrapper supports Amazon AWS Identity and Access Management (IAM) authentication. When using AWS IAM database authentication, the host URL must be a valid Amazon endpoint, and not a custom domain or an IP address.
ie. `db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com` IAM database authentication use is limited to certain database engines. For more information on limitations and recommendations, please [review the IAM documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html). -## How do I use IAM with the AWS JDBC Driver? +## How do I use IAM with the AWS Advanced JDBC Wrapper? 1. Enable AWS IAM database authentication on an existing database or create a new database with AWS IAM database authentication on the AWS RDS Console: 1. If needed, review the documentation about [creating a new database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html). 2. If needed, review the documentation about [modifying an existing database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.DBInstance.Modifying.html). diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md index 6c4213f36..da4b5da94 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md @@ -3,7 +3,7 @@ ## What is Amazon Aurora Limitless Database? Amazon Aurora Limitless Database is a new type of database that can horizontally scale to handle millions of write transactions per second and manage petabytes of data. -Users will be able to use the AWS JDBC Driver with Aurora Limitless Databases and optimize their experience using the Limitless Connection Plugin. +Users will be able to use the AWS Advanced JDBC Wrapper with Aurora Limitless Databases and optimize their experience using the Limitless Connection Plugin. To learn more about Aurora Limitless Database, see the [Amazon Aurora Limitless documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/limitless.html). ## Why use the Limitless Connection Plugin? @@ -17,7 +17,7 @@ The Limitless Connection Plugin achieves this with a monitoring thread that peri When a new connection is made, the plugin directs the connection to a transaction router selected from the cache using a weighted round-robin strategy. Routers with a higher load are assigned a lower weight, and routers with a lower load are assigned a higher weight. -## How to use the Limitless Connection Plugin with the AWS JDBC Driver +## How to use the Limitless Connection Plugin with the AWS Advanced JDBC Wrapper To enable the Limitless Connection Plugin, add the plugin code `limitless` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value, or to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). The URL used to connect to a limitless database is the DB shard group URL. diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md index a9638b637..40e28a162 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md @@ -27,7 +27,7 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md). -## How to use the Okta Authentication Plugin with the AWS JDBC Driver +## How to use the Okta Authentication Plugin with the AWS Advanced JDBC Wrapper ### Enabling the Okta Authentication Plugin > [!NOTE]\ diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md index bf78c3351..743d0e07a 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md @@ -118,9 +118,9 @@ Spring applications are encouraged to use configuration profiles and presets opt ## Example -[ReadWriteSplittingPostgresExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingPostgresExample.java) demonstrates how to enable and configure Read/Write Splitting with the AWS JDBC Driver. +[ReadWriteSplittingPostgresExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingPostgresExample.java) demonstrates how to enable and configure Read/Write Splitting with the AWS Advanced JDBC Wrapper. -[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure Read/Write Splitting plugin with the AWS JDBC Driver. This example application uses a configuration with internal connection pooling and provides a load-balanced reader connection according to a specified reader selection strategy. `@Transactional(readOnly = True)` annotations in the code help the `Read/Write Splitting Plugin` switch between datasources. +[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure Read/Write Splitting plugin with the AWS Advanced JDBC Wrapper. This example application uses a configuration with internal connection pooling and provides a load-balanced reader connection according to a specified reader selection strategy. `@Transactional(readOnly = True)` annotations in the code help the `Read/Write Splitting Plugin` switch between datasources. -[SpringHibernateBalancedReaderTwoDataSourceExample](../../../examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md) demonstrates how to enable and configure Read/Write Splitting plugin with the AWS JDBC Driver. This example application uses a configuration with two Spring datasources, where each datasource uses internal connection pooling. The example application provides a load-balanced reader connection according to a specified reader selection strategy. The example application does not use the `Read/Write Splitting Plugin`. Switching between the writer datasource and reader datasource occurs with the help of the `@WithLoadBalancedReaderDataSource` annotation. +[SpringHibernateBalancedReaderTwoDataSourceExample](../../../examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md) demonstrates how to enable and configure Read/Write Splitting plugin with the AWS Advanced JDBC Wrapper. This example application uses a configuration with two Spring datasources, where each datasource uses internal connection pooling. The example application provides a load-balanced reader connection according to a specified reader selection strategy. The example application does not use the `Read/Write Splitting Plugin`. Switching between the writer datasource and reader datasource occurs with the help of the `@WithLoadBalancedReaderDataSource` annotation. diff --git a/examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java b/examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java index a884edf4e..7f8e23261 100644 --- a/examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java +++ b/examples/AWSDriverExample/src/main/java/software/amazon/DatasourceExample.java @@ -40,7 +40,7 @@ public static void main(String[] args) throws SQLException { ds.setDatabase("employees"); ds.setServerPort("5432"); - // Configure the driver-specific and AWS JDBC Driver properties (optional): + // Configure the driver-specific and AWS Advanced JDBC Wrapper properties (optional): Properties targetDataSourceProps = new Properties(); // Alternatively, instead of using the methods above to configure the basic data source information, @@ -52,7 +52,7 @@ public static void main(String[] args) throws SQLException { // Configure any driver-specific properties: targetDataSourceProps.setProperty("ssl", "true"); - // Configure any AWS JDBC Driver properties: + // Configure any AWS Advanced JDBC Wrapper properties: targetDataSourceProps.setProperty("wrapperLoggerLevel", "ALL"); ds.setTargetDataSourceProperties(targetDataSourceProps); diff --git a/examples/AWSDriverExample/src/main/java/software/amazon/LimitlessPostgresqlExample.java b/examples/AWSDriverExample/src/main/java/software/amazon/LimitlessPostgresqlExample.java index 1fb66af98..67a76ea94 100644 --- a/examples/AWSDriverExample/src/main/java/software/amazon/LimitlessPostgresqlExample.java +++ b/examples/AWSDriverExample/src/main/java/software/amazon/LimitlessPostgresqlExample.java @@ -40,7 +40,7 @@ public static void main(String[] args) throws SQLException, InterruptedException ds.setDatabase("test"); ds.setServerPort("5432"); - // Configure the driver-specific and AWS JDBC Driver properties (optional): + // Configure the driver-specific and AWS Advanced JDBC Wrapper properties (optional): Properties targetDataSourceProps = new Properties(); // Alternatively, instead of using the methods above to configure the basic data source information, @@ -53,7 +53,7 @@ public static void main(String[] args) throws SQLException, InterruptedException // Configure any driver-specific properties: // targetDataSourceProps.setProperty("ssl", "true"); - // Configure any AWS JDBC Driver properties: + // Configure any AWS Advanced JDBC Wrapper properties: targetDataSourceProps.setProperty("wrapperLoggerLevel", "ALL"); ds.setTargetDataSourceProperties(targetDataSourceProps); diff --git a/examples/SpringBootHikariExample/README.md b/examples/SpringBootHikariExample/README.md index 0fd7aaa43..d56bea796 100644 --- a/examples/SpringBootHikariExample/README.md +++ b/examples/SpringBootHikariExample/README.md @@ -1,10 +1,10 @@ -# Tutorial: Getting started with Spring Boot, Hikari, and the AWS JDBC Driver +# Tutorial: Getting started with Spring Boot, Hikari, and the AWS Advanced JDBC Wrapper -In this tutorial, you will set up a Spring Boot application using Hikari and the AWS JDBC Driver. +In this tutorial, you will set up a Spring Boot application using Hikari and the AWS Advanced JDBC Wrapper. > Note: this tutorial was written using the following technologies: > - Spring Boot 2.7.0 -> - AWS JDBC Driver 2.6.6 +> - AWS Advanced JDBC Wrapper 2.6.6 > - Postgresql 42.5.4 > - Java 8 @@ -64,11 +64,11 @@ dependencies { } ``` -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. +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 the Datasource -In the `application.yml` file, configure Hikari and AWS JDBC Driver as its driver. +In the `application.yml` file, configure Hikari and AWS Advanced JDBC Wrapper as its driver. ```yaml spring: diff --git a/examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md b/examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md index 8d6d05c70..3751d586b 100644 --- a/examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md +++ b/examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md @@ -1,11 +1,11 @@ -# Tutorial: Getting Started with the AWS JDBC Driver, Spring Boot and Hibernate for load-balanced read-write and read-only connections (Single Datasource) +# 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 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 the AWS Advanced JDBC Driver internal connection pool configuration. +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 2.7.1 > - Hibernate -> - AWS JDBC Driver 2.3.2 +> - AWS Advanced JDBC Wrapper 2.3.2 > - Postgresql 42.5.4 > - Gradle 7 > - Java 11 @@ -13,7 +13,7 @@ In this tutorial, you will set up a Spring Boot and Hibernate application with t 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 +3. Configure the AWS Advanced JDBC Wrapper ## Pre-requisites - This tutorial uses the Amazon Aurora PostgreSQL database. @@ -52,10 +52,10 @@ dependencies { } ``` -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. +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 JDBC Driver as the default datasource. +Configure Spring to use the AWS Advanced JDBC Wrapper as the default datasource. 1. In the `application.yml`, add new datasources for Spring: ```yaml @@ -68,7 +68,7 @@ Configure Spring to use the AWS JDBC Driver as the default datasource. 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 2+ application. The AWS JDBC Driver 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](../../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). +2. The datasource mentioned above does not use Hikari datasource that is default for Spring 2+ 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](../../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).
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](../../docs/using-the-jdbc-driver/ReaderSelectionStrategies.md). @@ -97,4 +97,4 @@ 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. +This tutorial walks through the steps required to add and configure the AWS Advanced JDBC Wrapper to a simple Spring Boot and Hibernate application. diff --git a/examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md b/examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md index 1ae611a4f..c6b9eef47 100644 --- a/examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md +++ b/examples/SpringHibernateBalancedReaderTwoDataSourceExample/README.md @@ -1,11 +1,11 @@ -# Tutorial: Getting Started with the AWS Advanced JDBC Driver, Spring Boot and Hibernate for load-balanced write and read-only connections (Two Datasources) +# Tutorial: Getting Started with the AWS Advanced JDBC Wrapper, Spring Boot and Hibernate for load-balanced write and read-only connections (Two Datasources) -In this tutorial, you will set up a Spring Boot and Hibernate application with the AWS Advanced JDBC Driver, and use two datasources to fetch and update data from an Aurora PostgreSQL database. One datasource is configured to provide a writer connection. The other datasource is configured to provide a reader connection to off load a writer node from read-only queries. Both datasources provide pooled connections through AWS Advanced JDBC Driver internal connection pool configuration. +In this tutorial, you will set up a Spring Boot and Hibernate application with the AWS Advanced JDBC Wrapper, and use two datasources to fetch and update data from an Aurora PostgreSQL database. One datasource is configured to provide a writer connection. The other datasource is configured to provide a reader connection to off load a writer node from read-only queries. Both datasources provide pooled connections through AWS Advanced JDBC Wrapper 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 +> - AWS Advanced JDBC Wrapper 2.3.2 > - Postgresql 42.5.4 > - Gradle 7 > - Java 11 @@ -13,7 +13,7 @@ In this tutorial, you will set up a Spring Boot and Hibernate application with t 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 +3. Configure the AWS Advanced JDBC Wrapper ## Pre-requisites - This tutorial uses the Aurora PostgreSQL database. @@ -56,10 +56,10 @@ dependencies { } ``` -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. +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 JDBC Driver as the default datasource. +Configure Spring to use the AWS Advanced JDBC Wrapper as the default datasource. 1. In the `application.yml`, add new datasources for Spring: ```yaml @@ -78,7 +78,7 @@ Configure Spring to use the AWS JDBC Driver as the default datasource. driver-class-name: software.amazon.jdbc.Driver type: org.springframework.jdbc.datasource.SimpleDriverDataSource ``` -2. The datasources mentioned above do not use Hikari datasources which are the default for Spring 2+ applications. The AWS JDBC Driver 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 `SF_F0` configuration profile. Other configuration presets from `SF_` family can be used as well. 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). +2. The datasources mentioned above do not use Hikari datasources which are the default for Spring 2+ applications. 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 `SF_F0` configuration profile. Other configuration presets from `SF_` family can be used as well. 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).
Optional configuration parameter `readerInitialConnectionHostSelectorStrategy` 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/ReaderSelectionStrategies.md). @@ -107,4 +107,4 @@ For detailed logs use `TRACE` for `software.amazon.jdbc` package. Start the application by running `./gradlew :springhibernatetwodatasource:bootRun` in the terminal. You should see the application making a connection to the database and fetching data from the `Book` table. # Summary -This tutorial walks through the steps required to add and configure the AWS JDBC Driver to a simple Spring Boot and Hibernate application that load balances connections. +This tutorial walks through the steps required to add and configure the AWS Advanced JDBC Wrapper to a simple Spring Boot and Hibernate application that load balances connections. diff --git a/examples/SpringHibernateExample/README.md b/examples/SpringHibernateExample/README.md index 97bb20661..ca2e60bcc 100644 --- a/examples/SpringHibernateExample/README.md +++ b/examples/SpringHibernateExample/README.md @@ -1,11 +1,11 @@ -# Tutorial: Getting Started with the AWS Advanced JDBC Driver, Spring Boot and Hibernate +# Tutorial: Getting Started with the AWS Advanced JDBC Wrapper, Spring Boot and Hibernate -In this tutorial, you will set up a Spring Boot and Hibernate application with the AWS Advanced JDBC Driver, and use the IAM Authentication plugin to fetch some data from an Aurora PostgreSQL database. +In this tutorial, you will set up a Spring Boot and Hibernate application with the AWS Advanced JDBC Wrapper, and use the IAM Authentication plugin to fetch some data from an Aurora PostgreSQL database. > Note: this tutorial was written using the following technologies: > - Spring Boot 2.7.1 > - Hibernate -> - AWS JDBC Driver 2.6.6 +> - AWS Advanced JDBC Wrapper 2.6.6 > - Postgresql 42.5.4 > - Gradle 7 > - Java 11 @@ -13,7 +13,7 @@ In this tutorial, you will set up a Spring Boot and Hibernate application with t 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 +3. Configure the AWS Advanced JDBC Wrapper ## Pre-requisites - A database with IAM authentication enabled. This tutorial uses the Aurora PostgreSQL database. For information on how to enable IAM database authentication for Aurora databases, please see the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html). @@ -136,10 +136,10 @@ dependencies { } ``` -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. +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 Driver as the default datasource. +Configure Spring to use the AWS Advanced JDBC Wrapper as the default datasource. 1. In the `application.yml`, add a new datasource for Spring: @@ -181,4 +181,4 @@ logging: Start the application by running `./gradlew :springhibernate: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. +This tutorial walks through the steps required to add and configure the AWS Advanced JDBC Wrapper to a simple Spring Boot and Hibernate application. diff --git a/examples/SpringTxFailoverExample/README.md b/examples/SpringTxFailoverExample/README.md index 3c21c4a35..8288ffd70 100644 --- a/examples/SpringTxFailoverExample/README.md +++ b/examples/SpringTxFailoverExample/README.md @@ -1,10 +1,10 @@ # Tutorial: Getting started with Spring Boot and Failover -In this tutorial, you will set up a Spring Boot application using the AWS JDBC Driver. This sample application will contain an example of how to retry transactions interrupted by failover. This tutorial is an extension of the [Spring Boot HikariCP example](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/examples/SpringBootHikariExample/README.md) and will contain similar elements. +In this tutorial, you will set up a Spring Boot application using the AWS Advanced JDBC Wrapper. This sample application will contain an example of how to retry transactions interrupted by failover. This tutorial is an extension of the [Spring Boot HikariCP example](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/examples/SpringBootHikariExample/README.md) and will contain similar elements. > Note: this tutorial was written using the following technologies: > - Spring Boot 2.7.0 -> - AWS JDBC Driver 2.6.6 +> - AWS Advanced JDBC Wrapper 2.6.6 > - Postgresql 42.5.4 > - Java 8 @@ -107,11 +107,11 @@ dependencies { } ``` -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. +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 the Datasource -In the `application.yml` file, configure Hikari and AWS JDBC Driver as its driver. +In the `application.yml` file, configure Hikari and AWS Advanced JDBC Wrapper as its driver. Note that in Spring Boot 2 and 3, Hikari is the default DataSource implementation. So, a bean explicitly specifying Hikari as a Datasource is not needed. diff --git a/examples/SpringWildflyExample/README.md b/examples/SpringWildflyExample/README.md index 6aa809e08..49b14a5a5 100644 --- a/examples/SpringWildflyExample/README.md +++ b/examples/SpringWildflyExample/README.md @@ -1,11 +1,11 @@ -# Tutorial: Getting Started with the AWS JDBC Driver, Spring Boot and Wildfly +# Tutorial: Getting Started with the AWS Advanced JDBC Wrapper, Spring Boot and Wildfly -In this tutorial, you will set up a Wildfly and Spring Boot application with the AWS Advanced JDBC Driver, and use the wrapper to execute some simple database operations. +In this tutorial, you will set up a Wildfly and Spring Boot application with the AWS Advanced JDBC Wrapper, and use the wrapper to execute some simple database operations. > Note: this tutorial was written using the following technologies: > - Spring Boot 2.7.1 > - Wildfly 26.1.1 Final -> - AWS JDBC Driver 2.6.6 +> - AWS Advanced JDBC Wrapper 2.6.6 > - Postgresql 42.5.4 > - Gradle 7 > - Java 11 @@ -99,13 +99,13 @@ dependencies { } ``` -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. +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 Wildfly > Note: for simplicity, this repository does not contain the entire wildfly application, and instead only contains the modified files. Download the Wildfly 26.1.1 Servlet-Only Distribution from the [Wildfly website](https://www.wildfly.org/downloads/). -In the Wildfly `standalone/configuration/standalone.xml` file, configure the AWS Advanced JDBC Driver as your datasource by adding the following to the `