diff --git a/README.md b/README.md
index 81569bb73..7712e4484 100644
--- a/README.md
+++ b/README.md
@@ -7,44 +7,67 @@
The **Amazon Web Services (AWS) JDBC Driver** has been redesigned as an advanced JDBC wrapper.
-The wrapper is complementary to an existing JDBC driver and aims to extend the functionality of the driver to enable applications to take full advantage of the features of clustered databases such as Amazon Aurora. In other words, the AWS JDBC Driver does not connect directly to any database, but enables support of AWS and Aurora functionalities on top of an underlying JDBC driver of the user's choice.
+The wrapper is complementary to an existing JDBC driver and aims to extend the functionality of the driver to enable applications to take full advantage of the features of clustered databases such as Amazon Aurora. In other words, the AWS JDBC Driver does not connect directly to any database, but enables support of AWS and Aurora functionalities on top of an underlying JDBC driver of the user's choice. This approach enables service-specific enhancements, without requiring users to change their workflow and existing JDBC driver tooling.
The AWS JDBC Driver is targeted to work with **any** existing JDBC driver. Currently, the AWS JDBC Driver has been validated to support the [PostgreSQL JDBC Driver](https://github.com/pgjdbc/pgjdbc), [MySQL JDBC Driver](https://github.com/mysql/mysql-connector-j), and [MariaDB JDBC Driver](https://github.com/mariadb-corporation/mariadb-connector-j).
-In conjunction with the JDBC Drivers for PostgreSQL, MySQL, and MariaDB, the AWS JDBC Driver enables functionalities from Amazon Aurora such as fast failover for PostgreSQL and MySQL Aurora clusters. It also introduces integration with AWS authentication services such as [AWS Identity and Access Management (IAM)](https://aws.amazon.com/iam/) and [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/).
+The AWS JDBC Driver provides modular functionality through feature plugins, with each plugin being relevant to specific services based on their architecture and capabilities. For example, [AWS Identity and Access Management (IAM)](https://aws.amazon.com/iam/) authentication is supported across multiple services, while [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) applies to services that support password-based authentication. The fast failover plugin provides reduced recovery time during failover for Aurora PostgreSQL and Aurora MySQL clusters, though it is not applicable to Aurora DSQL due to its active-active architecture.
-## About the Wrapper
-Hosting a database cluster in the cloud via Aurora is able to provide users with sets of features and configurations to obtain maximum performance and availability, such as database failover. However, at the moment, most existing drivers do not currently support those functionalities or are not able to entirely take advantage of it.
+## Benefits of the AWS JDBC Driver
-The main idea behind the AWS JDBC Driver is to add a software layer on top of an existing JDBC driver that would enable all the enhancements brought by Aurora, without requiring users to change their workflow with their databases and existing JDBC drivers.
+### Seamless AWS Service Integration
-### What is Failover?
-In an Amazon Aurora database cluster, **failover** is a mechanism by which Aurora automatically repairs the cluster status when a primary DB instance becomes unavailable. It achieves this goal by electing an Aurora Replica to become the new primary DB instance, so that the DB cluster can provide maximum availability to a primary read-write DB instance. The AWS JDBC Driver is designed to understand the situation and coordinate with the cluster in order to provide minimal downtime and allow connections to be very quickly restored in the event of a DB instance failure.
+Built-in support for AWS Identity and Access Management (IAM) authentication eliminates the need to manage database passwords, while AWS Secrets Manager integration provides secure credential management for services that require password-based authentication.
-### Benefits of the AWS JDBC Driver
-Although Aurora is able to provide maximum availability through the use of failover, existing client drivers do not currently support this functionality. This is partially due to the time required for the DNS of the new primary DB instance to be fully resolved in order to properly direct the connection. The AWS JDBC Driver allows customers to continue using their existing community drivers in addition to having the AWS JDBC Driver fully exploit failover behavior by maintaining a cache of the Aurora cluster topology and each DB instance's role (Aurora Replica or primary DB instance). This topology is provided via a direct query to the Aurora DB, essentially providing a shortcut to bypass the delays caused by DNS resolution. With this knowledge, the AWS JDBC Driver can more closely monitor the Aurora DB cluster status so that a connection to the new primary DB instance can be established as fast as possible.
+### Preserve Existing Workflows
-### Enhanced Failure Monitoring
-Since a database failover is usually identified by reaching a network or a connection timeout, the AWS JDBC Driver introduces an enhanced and customizable manner to faster identify a database outage.
+The wrapper design allows developers to continue using their preferred JDBC drivers and existing database code while gaining service-specific enhancements. No application rewrites are required.
-Enhanced Failure Monitoring (EFM) is a feature available from the [Host Monitoring Connection Plugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md#enhanced-failure-monitoring) that periodically checks the connected database node's health and availability. If a database node is determined to be unhealthy, the connection is aborted (and potentially routed to another healthy node in the cluster).
+### Modular Plugin Architecture
-### Using the AWS JDBC Driver with RDS Multi-AZ DB Clusters
-The [AWS RDS Multi-AZ DB Clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) are capable of switching over the current writer node to another node in the cluster within approximately 1 second or less, in case of minor engine version upgrade or OS maintenance operations.
-The AWS JDBC Driver has been optimized for such fast failover when working with AWS RDS Multi-AZ DB Clusters.
+The plugin-based design ensures applications only load the functionality they need, reducing dependencies and overhead.
+
+## Benefits for Aurora PostgreSQL, Aurora MySQL, and RDS
+
+### Faster Failover and Reduced Downtime
+
+For Aurora PostgreSQL, Aurora MySQL, and RDS Multi-AZ DB clusters, the driver significantly reduces connection recovery time during [database failovers](./docs/using-the-jdbc-driver/WhatIsFailover.md). By maintaining a real-time cache of cluster topology and bypassing DNS resolution delays, applications can reconnect to healthy database instances in seconds rather than minutes.
+
+### Enhanced Failure Detection
+
+The driver includes Enhanced Failure Monitoring (EFM) that proactively monitors database node health, detecting failures faster than traditional timeout-based approaches. This allows applications to respond to issues before they impact end users.
+
+## Using the AWS JDBC Driver with...
+
+### Amazon Aurora PostgreSQL and Aurora MySQL
+
+The AWS JDBC Driver provides fast failover capabilities for Aurora PostgreSQL and Aurora MySQL clusters, significantly reducing connection recovery time during database failovers.
+
+Visit [this page](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md) for more details.
+
+### Amazon Aurora DSQL
+
+The AWS JDBC Driver is able to handle IAM authentication when working with AWS Aurora DSQL clusters.
+
+Visit [this page](./docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md) for more details.
+
+### Amazon RDS Multi-AZ DB Clusters
+
+The [AWS RDS Multi-AZ DB Clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) are capable of switching over the current writer node to another node in the cluster within approximately 1 second or less, in case of minor engine version upgrade or OS maintenance operations. The AWS JDBC Driver has been optimized for such fast failover when working with AWS RDS Multi-AZ DB Clusters.
With the `failover` plugin, the downtime during certain DB cluster operations, such as engine minor version upgrades, can be reduced to one second or even less with finely tuned parameters. It supports both MySQL and PostgreSQL clusters.
Visit [this page](./docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md) for more details.
-### Using the AWS JDBC Driver with plain RDS databases
+### Plain Amazon RDS databases
+
The AWS JDBC Driver also works with RDS provided databases that are not Aurora.
-Please visit [this page](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#using-the-aws-jdbc-driver-with-plain-rds-databases) for more information.
+Visit [this page](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#using-the-aws-jdbc-driver-with-plain-rds-databases) for more details.
## Getting Started
-For more information on how to download the AWS JDBC Driver, minimum requirements to use it,
-and how to integrate it within your project and with your JDBC driver of choice, please visit the
+For more information on how to download the AWS JDBC Driver, minimum requirements to use it,
+and how to integrate it within your project and with your JDBC driver of choice, please visit the
[Getting Started page](./docs/GettingStarted.md).
### Maven Central
@@ -128,7 +151,7 @@ The development team is aware of these limitations and is working to improve the
> [!WARNING]\
> **Blue/Green Support Behaviour and Version Compatibility**
->
+>
> The AWS Advanced JDBC Wrapper now includes enhanced full support for Blue/Green Deployments. This support requires a minimum database version that includes a specific metadata table. This constraint **does not** apply to RDS MySQL.
>
> If your database version does **not** support this table, the driver will automatically detect its absence and fallback to its previous behaviour. In this fallback mode, Blue/Green handling is subject to the same limitations listed above.
@@ -147,30 +170,33 @@ This driver currently does not support `planned failover` or `switchover` of Ama
## Examples
-| Description | Examples |
-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
-| Using the AWS JDBC Driver to get a simple connection | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgConnectionSample.java) |
-| Using the AWS JDBC Driver with failover handling | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgFailoverSample.java) |
-| Using the AWS IAM Authentication Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationPostgresqlExample.java)
[MySQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMysqlExample.java)
[MariaDB](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationMariadbExample.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) |
+| Description | Examples |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+| Using the AWS JDBC Driver to get a simple connection | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgConnectionSample.java) |
+| Using the AWS JDBC Driver with failover handling | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/PgFailoverSample.java) |
+| Using the AWS IAM Authentication Plugin with `DriverManager` | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsIamAuthenticationPostgresqlExample.java)
[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 Aurora DSQL IAM Authentication Plugin with `DriverManager` | [DSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java) |
+| Using the AWS Aurora DSQL IAM Authentication Plugin with `DataSource` | [DSQL](examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.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 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 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) |
## Getting Help and Opening Issues
If you encounter a bug with the AWS JDBC Driver, 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.
+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.
@@ -178,11 +204,11 @@ For all other questions, please use [GitHub discussions](https://github.com/aws/
## How to Contribute
1. Set up your environment by following the directions in the [Development Guide](docs/development-guide/DevelopmentGuide.md).
-2. To contribute, first make a fork of this project.
+2. To contribute, first make a fork of this project.
3. Make any changes on your fork. Make sure you are aware of the requirements for the project (e.g. do not require Java 7 if we are supporting Java 8 and higher).
-4. Create a pull request from your fork.
+4. Create a pull request from your fork.
5. Pull requests need to be approved and merged by maintainers into the main branch.
-**Note:** Before making a pull request, [run all tests](./docs/development-guide/DevelopmentGuide.md#running-the-tests) and verify everything is passing.
+ **Note:** Before making a pull request, [run all tests](./docs/development-guide/DevelopmentGuide.md#running-the-tests) and verify everything is passing.
### Code Style
The project source code is written using the [Google checkstyle](https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml), and the style is strictly enforced in our automation pipelines. Any contribution that does not respect/satisfy the style will automatically fail at build time.
diff --git a/docs/Documentation.md b/docs/Documentation.md
index a22ef8b3b..31a0c17e6 100644
--- a/docs/Documentation.md
+++ b/docs/Documentation.md
@@ -14,6 +14,7 @@
- [Failover Plugin v2](./using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md)
- [Host Monitoring Plugin](./using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md)
- [IAM Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md)
+ - [Aurora DSQL IAM Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md)
- [AWS Secrets Manager Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md)
- [Aurora Connection Tracker Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
- [Driver Metadata Connection Plugin](./using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md)
diff --git a/docs/using-the-jdbc-driver/WhatIsFailover.md b/docs/using-the-jdbc-driver/WhatIsFailover.md
new file mode 100644
index 000000000..a7a69e1a0
--- /dev/null
+++ b/docs/using-the-jdbc-driver/WhatIsFailover.md
@@ -0,0 +1,6 @@
+# What is Failover?
+In an Amazon Aurora database cluster, **failover** is a mechanism by which Aurora automatically repairs the cluster status when a primary DB instance becomes unavailable.
+
+It achieves this goal by electing an Aurora Replica to become the new primary DB instance, so that the DB cluster can provide maximum availability to a primary read-write DB instance.
+
+See [Failing over an Amazon Aurora DB cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-failover.html) for more information.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md
new file mode 100644
index 000000000..cdd94dc36
--- /dev/null
+++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md
@@ -0,0 +1,37 @@
+# AWS Aurora DSQL IAM Authentication Plugin
+
+## What is IAM?
+AWS Identity and Access Management (IAM) grants users access control across all Amazon Web Services. IAM supports granular permissions, giving you the ability to grant different permissions to different users. For more information on IAM and it's use cases, please refer to the [IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).
+
+## Prerequisites
+> [!WARNING]\
+> To use this plugin, you must include the runtime dependency [AWS Java SDK DSQL](https://central.sonatype.com/artifact/software.amazon.awssdk/dsql) in your project.
+>
+> Note: AWS Java SDK DSQL may have transitive dependencies that are also required (ex. [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.
+
+To enable the AWS Aurora DSQL IAM Authentication Plugin, add the plugin code `iamDsql` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value, or to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters).
+
+> [!WARNING]\
+> The `iam` plugin must NOT be specified when using the `iamDsql` plugin.
+
+This plugin requires valid AWS credentials. See more details at [AWS Credentials Configuration](../custom-configuration/AwsCredentialsConfiguration.md).
+
+## AWS Aurora DQSL 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.
+
ie. `cluster-identifier.dsql.us-east-1.on.aws`
+
+Connections established by the `iamDsql` plugin are beholden to the [Cluster quotas and database limits in Amazon Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_quotas.html). In particular, applications need to consider the maximum transaction duration, and maximum connection duration limits. Ensure connections are returned to the pool regularly, and not retained for long periods.
+
+## How do I use IAM with Aurora DQSL and the AWS JDBC Driver?
+1. Configure IAM roles for the cluster according to [Using database roles and IAM authentication](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html).
+2. Add the plugin code `iamDsql` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) parameter value.
+
+| Parameter | Value | Required | Description | Example Value |
+|-------------------|:-------:|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
+| `iamHost` | String | No | This property will override the default hostname that is used to generate the IAM token. The default hostname is derived from the connection string. | `cluster-identifier.dsql.us-east-1.on.aws` |
+| `iamRegion` | String | No | This property will override the default region that is used to generate the IAM token. The default region is parsed from the connection string where possible. Some connection string formats may not be supported, and the `iamRegion` must be provided in these cases. | `us-east-2` |
+| `iamExpiration` | Integer | No | This property determines how long an IAM token is kept in the driver cache before a new one is generated. The default expiration time is set to be 14 minutes and 30 seconds. Note that IAM database authentication tokens have a lifetime of 15 minutes. | `600` |
+
+## Sample code
+[AwsAuroraDsqlIamAuthenticationExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java)
+[AwsAuroraDsqlIamAuthenticationDatasourceExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java)
diff --git a/examples/AWSDriverExample/build.gradle.kts b/examples/AWSDriverExample/build.gradle.kts
index 3105edd7f..dca45db44 100644
--- a/examples/AWSDriverExample/build.gradle.kts
+++ b/examples/AWSDriverExample/build.gradle.kts
@@ -19,6 +19,7 @@ dependencies {
implementation("org.postgresql:postgresql:42.7.7")
implementation("com.mysql:mysql-connector-j:9.3.0")
implementation("software.amazon.awssdk:rds:2.31.78")
+ implementation("software.amazon.awssdk:dsql:2.31.78")
implementation("software.amazon.awssdk:secretsmanager:2.31.12")
implementation("software.amazon.awssdk:sts:2.31.78")
implementation("com.fasterxml.jackson.core:jackson-databind:2.19.0")
diff --git a/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java b/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java
new file mode 100644
index 000000000..e039d02e3
--- /dev/null
+++ b/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java
@@ -0,0 +1,66 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package software.amazon;
+
+import com.zaxxer.hikari.HikariDataSource;
+import software.amazon.jdbc.ds.AwsWrapperDataSource;
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.Properties;
+
+// This file shows how to establish an Aurora DSQL connection using HikariCP datasource and the Aurora DSQL IAM
+// authentication plugin.
+public class AwsAuroraDsqlIamAuthenticationDatasourceExample {
+
+ private static final String IAM_DATABASE_USER = "admin";
+
+ public static void main(String[] args) throws SQLException {
+ try (HikariDataSource ds = new HikariDataSource()) {
+
+ // Configure the connection pool:
+ ds.setUsername(IAM_DATABASE_USER);
+
+ // Specify the underlying datasource for HikariCP:
+ ds.setDataSourceClassName(AwsWrapperDataSource.class.getName());
+
+ // Configure AwsWrapperDataSource:
+ ds.addDataSourceProperty("jdbcProtocol", "jdbc:postgresql://");
+ ds.addDataSourceProperty("serverName", "cluster-identifier.dsql.us-east-1.on.aws");
+ ds.addDataSourceProperty("serverPort", "5432");
+ ds.addDataSourceProperty("database", "postgres");
+
+ // Specify the driver-specific data source for AwsWrapperDataSource:
+ ds.addDataSourceProperty("targetDataSourceClassName", "org.postgresql.ds.PGSimpleDataSource");
+
+ Properties targetDataSourceProps = new Properties();
+
+ // Enable the Aurora DSQL IAM authentication plugin.
+ targetDataSourceProps.setProperty("wrapperPlugins", "iamDsql");
+
+ ds.addDataSourceProperty("targetDataSourceProperties", targetDataSourceProps);
+
+ // Attempt a connection:
+ try (final Connection conn = ds.getConnection();
+ final Statement statement = conn.createStatement();
+ final ResultSet rs = statement.executeQuery("SELECT 1")) {
+ System.out.println(Util.getResult(rs));
+ }
+ }
+ }
+}
diff --git a/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java b/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java
new file mode 100644
index 000000000..de5208bf7
--- /dev/null
+++ b/examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java
@@ -0,0 +1,48 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package software.amazon;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.Properties;
+import software.amazon.jdbc.PropertyDefinition;
+
+public class AwsAuroraDsqlIamAuthenticationExample {
+ public static final String DSQL_CONNECTION_STRING =
+ "jdbc:aws-wrapper:postgresql://cluster-identifier.dsql.us-east-1.on.aws:5432/postgres";
+ private static final String USERNAME = "admin";
+
+ public static void main(String[] args) throws SQLException {
+
+ final Properties properties = new Properties();
+
+ // Enable AWS Aurora DSQL IAM database authentication and configure driver property values
+ properties.setProperty(PropertyDefinition.PLUGINS.name, "iamDsql");
+ properties.setProperty(PropertyDefinition.USER.name, USERNAME);
+
+ // Attempt a connection
+ try (Connection conn = DriverManager.getConnection(DSQL_CONNECTION_STRING, properties);
+ Statement statement = conn.createStatement();
+ ResultSet result = statement.executeQuery("SELECT 1")) {
+
+ System.out.println(Util.getResult(result));
+ }
+ }
+}