add user documentation for DSQL plugin #1478

danielfrankcom · 2025-07-16T20:54:28Z

Summary

This PR adds user documentation and associated examples for using the AWS Aurora DSQL IAM authentication plugin.

This accompanies the change in #1477, which adds the dsql plugin implementation and tests.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

danielfrankcom · 2025-07-16T21:30:05Z

Update 96d089f adds references to the new docs/samples to the top-level documentation which I missed in the initial push.

The diff for the example table update is a little messy because the table cells are not aligned on main. Most of the lines are just whitespace changes, but I add 3 new rows:

A reference to the DSQL DriverManager example
A reference to the DSQL DataSource example
A reference to the existing DataSource example which was missing from the table

danielfrankcom · 2025-07-17T18:13:29Z

Update to 7f0d46e changes the dsql plugin name to iamDsql.

danielfrankcom · 2025-07-17T21:18:41Z

Change to 71a809e updates the wording around iamRegion, and gives a bit more detail about when it is required.

...erExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java

danielfrankcom · 2025-07-21T17:48:11Z

Update to c79cadd is a simple rebase, mostly to trigger CI jobs.

docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md

...es/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java

danielfrankcom · 2025-07-24T23:57:10Z

Update to ebcf5d8 improves some of the messaging in the main README.md file to point out the modularity of plugins, and indicate which database types are relevant for which plugins.

karenc-bq · 2025-07-30T06:10:24Z

README.md


 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.


Suggested change

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.

The AWS JDBC Driver provides modular functionality through feature plugins, with each plugin being relevant to specific database 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.

karenc-bq · 2025-07-30T06:14:31Z

README.md


-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


Does it make sense to specify authentication services? i.e. Seamless AWS Authentication Service Integration

karenc-bq · 2025-07-30T06:20:13Z

README.md

-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


Personally this heading sounds like we are going to talk about benefits of using Aurora databases instead of benefits of the wrapper. What do you think of changing this and the previous heading from

## Benefits of the AWS JDBC Driver ## Benefits for Aurora PostgreSQL, Aurora MySQL, and RDS

to

## Benefits of the AWS JDBC Driver for All Aurora and RDS Database Services ## Benefits of the AWS JDBC Driver for Aurora PostgreSQL, Aurora MySQL, and RDS

karenc-bq · 2025-07-30T06:24:02Z

docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md

+
+| 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` |


Based on the conversation above where IP and Custom Endpoints are not accepted during connection, does it make sense to mention iamHost in the docs right now?

karenc-bq · 2025-07-30T06:24:36Z

docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md

+|-------------------|:-------:|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
+| `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`                                      |


Is this accurate given DSQL allows you to set server sided token lifetime

karenc-bq · 2025-07-30T06:43:47Z

...erExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java

+
+// This file shows how to establish an Aurora DSQL connection using HikariCP datasource and the Aurora DSQL IAM
+// authentication plugin.
+public class AwsAuroraDsqlIamAuthenticationDatasourceExample {


What do you think of creating a new submodule for DSQL sample codes to reduce noise for DSQL customers

danielfrankcom force-pushed the dev/frankcom/dsql-docs branch from cf70258 to 96d089f Compare July 16, 2025 21:25

danielfrankcom mentioned this pull request Jul 17, 2025

add DSQL example for Spring Boot Hikari #1481

Open

danielfrankcom force-pushed the dev/frankcom/dsql-docs branch from 96d089f to 7f0d46e Compare July 17, 2025 18:12

danielfrankcom force-pushed the dev/frankcom/dsql-docs branch from 7f0d46e to 71a809e Compare July 17, 2025 21:18

imforster reviewed Jul 18, 2025

View reviewed changes

...erExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationDatasourceExample.java Show resolved Hide resolved

danielfrankcom force-pushed the dev/frankcom/dsql-docs branch from 71a809e to c79cadd Compare July 21, 2025 17:47

danielfrankcom mentioned this pull request Jul 22, 2025

Add support for DSQL iam authentication aws/aws-advanced-python-wrapper#919

Open

sergiyvamz reviewed Jul 22, 2025

View reviewed changes

docs/using-the-jdbc-driver/using-plugins/UsingTheDsqlAuthenticationPlugin.md Show resolved Hide resolved

sergiyvamz reviewed Jul 22, 2025

View reviewed changes

...es/AWSDriverExample/src/main/java/software/amazon/AwsAuroraDsqlIamAuthenticationExample.java Show resolved Hide resolved

sergiyvamz approved these changes Jul 23, 2025

View reviewed changes

add user documentation for DSQL plugin

ebcf5d8

danielfrankcom force-pushed the dev/frankcom/dsql-docs branch from c79cadd to ebcf5d8 Compare July 24, 2025 23:56

karenc-bq reviewed Jul 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add user documentation for DSQL plugin #1478

add user documentation for DSQL plugin #1478

Uh oh!

danielfrankcom commented Jul 16, 2025

Uh oh!

danielfrankcom commented Jul 16, 2025

Uh oh!

danielfrankcom commented Jul 17, 2025

Uh oh!

danielfrankcom commented Jul 17, 2025

Uh oh!

Uh oh!

danielfrankcom commented Jul 21, 2025

Uh oh!

Uh oh!

Uh oh!

danielfrankcom commented Jul 24, 2025 •

edited

Loading

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

karenc-bq Jul 30, 2025

Uh oh!

Uh oh!


		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

add user documentation for DSQL plugin #1478

Are you sure you want to change the base?

add user documentation for DSQL plugin #1478

Uh oh!

Conversation

danielfrankcom commented Jul 16, 2025

Summary

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Uh oh!

danielfrankcom commented Jul 16, 2025

Uh oh!

danielfrankcom commented Jul 17, 2025

Uh oh!

danielfrankcom commented Jul 17, 2025

Uh oh!

Uh oh!

danielfrankcom commented Jul 21, 2025

Uh oh!

Uh oh!

Uh oh!

danielfrankcom commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

karenc-bq Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

danielfrankcom commented Jul 24, 2025 •

edited

Loading