add user documentation for DSQL plugin

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)

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.

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.
+<br>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)<br>
+[AwsAuroraDsqlIamAuthenticationDatasourceExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java)

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")

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));
+      }
+    }
+  }
+}

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));
+    }
+  }
+}