Note
📊 We want to hear from you — community survey is open
Help us get to know who's using the AWS Advanced JDBC Wrapper. The survey is a single GitHub Discussion with one question per comment. You answer by reacting with emojis — pick all that apply, multi-select is supported.
- Takes about 3–5 minutes
- Covers usage, deployment topology, plugins, frameworks, and your experience
- Every reaction is visible to the community; total participants are counted from a single 👍 on the participation comment
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 Advanced JDBC Wrapper 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 Advanced JDBC Wrapper is targeted to work with any existing JDBC driver. Currently, the AWS Advanced JDBC Wrapper has been validated to support the PostgreSQL JDBC Driver, MySQL JDBC Driver, and MariaDB JDBC Driver (with some caveats, see below).
The AWS Advanced JDBC Wrapper 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) authentication is supported across multiple services, while AWS 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.
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.
The driver includes Remote Query Cache Plugin that stores cacheable read-only query results in a remote Valkey cache along with support for plain username/password authentication and IAM authentication with AWS ElastiCache. Applications can opt‑in per query using a SQL query hint that specifies a time‑to‑live (TTL).
Database multi-tenancy protection is disabled by default. Enable
cacheEnableDatabaseMultiTenancy when query visibility depends on supported database authorization
or session state. The protection covers only documented PostgreSQL and MySQL/MariaDB session state
and is not a complete tenant-isolation boundary. See the
Remote Query Cache Plugin
for supported operations, limitations, application security requirements, and performance
implications.
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.
The plugin-based design ensures applications only load the functionality they need, reducing dependencies and overhead.
For Aurora PostgreSQL, Aurora MySQL, and RDS Multi-AZ DB clusters, the driver significantly reduces connection recovery time during database failovers. 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.
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.
The AWS Advanced JDBC Wrapper provides fast failover capabilities for Aurora PostgreSQL and Aurora MySQL clusters, significantly reducing connection recovery time during database failovers.
Visit Using Failover 2 for more details.
The AWS RDS Multi-AZ DB Clusters 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 Advanced JDBC Wrapper 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 Support for RDS MultiAZ for more details.
As of version 3.0.0, the driver supports in-region failover and
cross-region planned failover and switchover of Amazon Aurora Global Databases.
A Global Writer Endpoint
is also recognized and can be handled to minimize potential stale DNS issues.
Please check failover plugin, failover2 plugin and
Aurora Initial Connection Strategy plugin for more information.
For detailed configuration instructions, see Aurora Global Databases.
The AWS Advanced JDBC Wrapper also provides limited functionality for RDS provided databases that are not Aurora, see the compatibility matrix for details.
As of version 3.0.0 the Simple R/W Splitting Plugin can be used with RDS Proxy. There are limitations with the AWS Advanced JDBC Wrapper and RDS Proxy. This is currently intended, by design, since 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). Due to this, functionality like Failover, Enhanced Host Monitoring, and Read/Write Splitting is not compatible since the driver relies on cluster topology and RDS Proxy handles this automatically.
The driver remains useful with RDS Proxy for authentication workflows, such as IAM authentication and AWS Secrets Manager integration. See Compatibility for compatibility information and refer to the using plugins documentation for details.
Visit Using Plain RDS for more details.
For more information on how to download the AWS Advanced JDBC Wrapper, 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.
You can find our driver by searching in The Central Repository with GroupId and ArtifactId software.amazon:aws-advanced-jdbc-wrapper.
<!-- Add the following dependency to your pom.xml, -->
<!-- replacing LATEST with the specific version as required -->
<dependency>
<groupId>software.amazon.jdbc</groupId>
<artifactId>aws-advanced-jdbc-wrapper</artifactId>
<version>LATEST</version>
</dependency>The driver ships with a self-contained configuration assistant skill, JDBC-WRAPPER-CONFIGURATION-ASSISTANT.md, that you can drop into your AI tool's knowledge base (Kiro, Cursor, Claude Projects, ChatGPT, Amazon Bedrock, GitHub Copilot, etc.) to help build, review, or troubleshoot wrapper configurations.
For drop-in locations, example prompts, and usage details, see Configuring the Driver with AI Tools in the Getting Started guide.
| Parameter | Available Since Version | Reference | Documentation Link |
|---|---|---|---|
activeHomeFailoverMode |
3.2.0 | GlobalDbFailoverConnectionPlugin.ACTIVE_HOME_FAILOVER_MODE |
Global Database (GDB) Failover Plugin |
allowAwsLoginSession |
4.4.0 | PropertyDefinition.ALLOW_AWS_LOGIN_SESSION |
AWS IAM Authentication Plugin |
allowStatementRecreationOnConnectionSwitch |
4.4.0 | UnifiedReadWriteSplittingPlugin.ALLOW_STATEMENT_RECREATION_ON_CONNECTION_SWITCH |
Read/Write Splitting Plugin |
appId |
2.3.6 | OktaAuthPlugin.APP_ID |
Okta Authentication Plugin |
assumeWriteTransaction |
4.4.0 | UnifiedReadWriteSplittingPlugin.ASSUME_WRITE_TRANSACTION |
Automatic Read/Write Splitting Plugin |
auditLoggingEnabled |
4.0.0 | EncryptionConfig.AUDIT_LOGGING_ENABLED |
KMS Encryption Plugin |
autoSortWrapperPluginOrder |
2.2.4 | PropertyDefinition.AUTO_SORT_PLUGIN_ORDER |
Plugins |
awsProfile |
2.3.3 | PropertyDefinition.AWS_PROFILE |
AWS Advanced JDBC Wrapper Parameters |
bgBaselineMs |
2.6.0 | BlueGreenStatusProvider.BG_INTERVAL_BASELINE_MS |
Blue/Green Deployment Plugin |
bgDeploymentRemovedGraceMs |
4.5.0 | BlueGreenStatusProvider.BG_DEPLOYMENT_REMOVED_GRACE_MS |
Blue/Green Deployment Plugin |
bgdId |
2.6.0 | BlueGreenConnectionPlugin.BGD_ID |
Blue/Green Deployment Plugin |
bgConnectTimeoutMs |
2.6.0 | BlueGreenConnectionPlugin.BG_CONNECT_TIMEOUT |
Blue/Green Deployment Plugin |
bgDropBlueConnections |
3.3.0 | BlueGreenStatusProvider.BG_DROP_BLUE_CONNECTIONS |
Blue/Green Deployment Plugin |
bgEndpointUnreachableMs |
4.5.0 | BlueGreenStatusProvider.BG_ENDPOINT_UNREACHABLE_MS |
Blue/Green Deployment Plugin |
bgHighMs |
2.6.0 | BlueGreenStatusProvider.BG_INTERVAL_HIGH_MS |
Blue/Green Deployment Plugin |
bgIncreasedMs |
2.6.0 | BlueGreenStatusProvider.BG_INTERVAL_INCREASED_MS |
Blue/Green Deployment Plugin |
bgReleaseOnBlueDnsUpdate |
4.4.0 | BlueGreenStatusProvider.BG_RELEASE_ON_BLUE_DNS_UPDATE |
Blue/Green Deployment Plugin |
bgSwitchoverTimeoutMs |
2.6.0 | BlueGreenStatusProvider.BG_SWITCHOVER_TIMEOUT_MS |
Blue/Green Deployment Plugin |
cachedReaderKeepAliveTimeoutMs |
3.0.0 | UnifiedReadWriteSplittingPlugin.CACHED_READER_KEEP_ALIVE_TIMEOUT |
Read/Write Splitting Plugin |
clusterId |
0.1.0 | RdsHostListProvider.CLUSTER_ID |
ClusterId |
clusterInstanceHostPattern |
0.1.0 | RdsHostListProvider.CLUSTER_INSTANCE_HOST_PATTERN |
Failover Plugin |
clusterTopologyHighRefreshRateMs |
2.4.0 | RdsHostListProvider.CLUSTER_TOPOLOGY_HIGH_REFRESH_RATE_MS |
Failover Plugin v2 |
clusterTopologyRefreshRateMs |
0.1.0 | RdsHostListProvider.CLUSTER_TOPOLOGY_REFRESH_RATE_MS |
Failover Plugin v2 |
connectTimeout |
2.3.1 | PropertyDefinition.CONNECT_TIMEOUT |
AWS Advanced JDBC Wrapper Parameters |
connectionPoolType |
3.1.0 | PropertyDefinition.CONNECTION_POOL_TYPE |
AWS Advanced JDBC Wrapper Parameters |
customEndpointInfoMaxRefreshRateMs |
3.1.0 | CustomEndpointPlugin.CUSTOM_ENDPOINT_INFO_MAX_REFRESH_RATE_MS |
Custom Endpoint Plugin |
customEndpointInfoRefreshRateBackoffFactor |
3.1.0 | CustomEndpointPlugin.CUSTOM_ENDPOINT_INFO_REFRESH_RATE_BACKOFF_FACTOR |
Custom Endpoint Plugin |
customEndpointInfoRefreshRateMs |
2.5.0 | CustomEndpointPlugin.CUSTOM_ENDPOINT_INFO_REFRESH_RATE_MS |
Custom Endpoint Plugin |
customEndpointMonitorExpirationMs |
2.5.0 | CustomEndpointPlugin.CUSTOM_ENDPOINT_MONITOR_IDLE_EXPIRATION_MS |
Custom Endpoint Plugin |
customEndpointRegion |
2.5.0 | CustomEndpointPlugin.REGION_PROPERTY |
Custom Endpoint Plugin |
dataCacheMaxSize |
4.4.0 | DataLocalCacheConnectionPlugin.DATA_CACHE_MAX_SIZE |
Data Local Cache Plugin |
dataCacheTriggerCondition |
0.1.0 | DataLocalCacheConnectionPlugin.DATA_CACHE_TRIGGER_CONDITION |
Data Local Cache Plugin |
dataCacheTtlMs |
4.4.0 | DataLocalCacheConnectionPlugin.DATA_CACHE_TTL_MS |
Data Local Cache Plugin |
dataKeyCacheEnabled |
4.0.0 | EncryptionConfig.DATA_KEY_CACHE_ENABLED |
KMS Encryption Plugin |
dataKeyCacheExpirationMs |
4.0.0 | EncryptionConfig.DATA_KEY_CACHE_EXPIRATION_MS |
KMS Encryption Plugin |
dataKeyCacheMaxSize |
4.0.0 | EncryptionConfig.DATA_KEY_CACHE_MAX_SIZE |
KMS Encryption Plugin |
cacheEndpointAddrRw |
3.3.0 | CacheConnection.CACHE_RW_ENDPOINT_ADDR |
Remote Query Cache Plugin |
cacheEndpointAddrRo |
3.3.0 | CacheConnection.CACHE_RO_ENDPOINT_ADDR |
Remote Query Cache Plugin |
cacheUseSSL |
3.3.0 | CacheConnection.CACHE_USE_SSL |
Remote Query Cache Plugin |
cacheTlsCaCertPath |
3.3.0 | CacheConnection.CACHE_TLS_CA_CERT_PATH |
Remote Query Cache Plugin |
cacheUsername |
3.3.0 | CacheConnection.CACHE_USERNAME |
Remote Query Cache Plugin |
cachePassword |
3.3.0 | CacheConnection.CACHE_PASSWORD |
Remote Query Cache Plugin |
cacheName |
3.3.0 | CacheConnection.CACHE_NAME |
Remote Query Cache Plugin |
cacheIamRegion |
3.3.0 | CacheConnection.CACHE_IAM_REGION |
Remote Query Cache Plugin |
cacheMaxQuerySize |
3.3.0 | RemoteQueryCachePlugin.CACHE_MAX_QUERY_SIZE |
Remote Query Cache Plugin |
cacheEnableDatabaseMultiTenancy |
4.5.0 | RemoteQueryCachePlugin.CACHE_ENABLE_DATABASE_MULTI_TENANCY |
Remote Query Cache Plugin |
cacheConnectionTimeoutMs |
3.3.0 | CacheConnection.CACHE_CONNECTION_TIMEOUT |
Remote Query Cache Plugin |
cacheConnectionPoolSize |
3.3.0 | CacheConnection.CACHE_CONNECTION_POOL_SIZE |
Remote Query Cache Plugin |
cacheKeyPrefix |
3.3.0 | CacheConnection.CACHE_KEY_PREFIX |
Remote Query Cache Plugin |
dbUser |
2.3.2 | FederatedAuthPlugin.DB_USER |
Federated Authentication Plugin |
dbUser |
2.3.2 | OktaAuthPlugin.DB_USER |
Okta Authentication Plugin |
enableConnectFailover |
2.4.0 | FailoverConnectionPlugin.ENABLE_CONNECT_FAILOVER |
Failover Plugin |
enableGreenNodeReplacement |
2.3.6 | PropertyDefinition.ENABLE_GREEN_NODE_REPLACEMENT |
AWS Advanced JDBC Wrapper Parameters |
failoverHomeRegion |
3.2.0 | GlobalDbFailoverConnectionPlugin.FAILOVER_HOME_REGION |
Global Database (GDB) Failover Plugin |
failWhenCacheDown |
3.3.0 | CacheConnection.FAIL_WHEN_CACHE_DOWN |
Remote Query Cache Plugin |
cacheInFlightWriteSizeLimitBytes |
3.3.0 | CacheMonitor.CACHE_IN_FLIGHT_WRITE_SIZE_LIMIT |
Remote Query Cache Plugin |
cacheHealthCheckInHealthyState |
3.3.0 | CacheMonitor.CACHE_HEALTH_CHECK_IN_HEALTHY_STATE |
Remote Query Cache Plugin |
cacheAllowStreamSource |
4.3.0 | RemoteQueryCachePlugin.CACHE_ALLOW_STREAM_SOURCE |
Remote Query Cache Plugin |
cacheAllowUrl |
4.3.0 | RemoteQueryCachePlugin.CACHE_ALLOW_URL |
Remote Query Cache Plugin |
database |
0.1.0 | PropertyDefinition.DATABASE |
AWS Advanced JDBC Wrapper Parameters |
defaultHostAvailabilityStrategy |
2.2.4 | HostAvailabilityStrategyFactory.DEFAULT_HOST_AVAILABILITY_STRATEGY |
Host Availability Strategy |
enableClusterAwareFailover |
0.1.0 | FailoverConnectionPlugin.ENABLE_CLUSTER_AWARE_FAILOVER |
Failover Plugin |
enableTelemetry |
2.3.0 | PropertyDefinition.ENABLE_TELEMETRY |
Monitoring |
endpointSubstitutionRole |
3.1.0 | AuroraInitialConnectionStrategyPlugin.ENDPOINT_SUBSTITUTION_ROLE |
Aurora Initial Connection Strategy Plugin |
enhancedLogQueryEnabled |
0.1.0 | LogQueryConnectionPlugin.ENHANCED_LOG_QUERY_ENABLED |
Using the AWS Advanced JDBC Wrapper |
encryptionMetadataSchema |
4.0.0 | EncryptionConfig.ENCRYPTION_METADATA_SCHEMA |
KMS Encryption Plugin |
failoverClusterTopologyRefreshRateMs |
0.1.0 | FailoverConnectionPlugin.FAILOVER_CLUSTER_TOPOLOGY_REFRESH_RATE_MS |
Failover Plugin |
failoverMode |
2.1.0 | FailoverConnectionPlugin.FAILOVER_MODE |
Failover Plugin |
failoverReaderConnectTimeoutMs |
0.1.0 | FailoverConnectionPlugin.FAILOVER_READER_CONNECT_TIMEOUT_MS |
Failover Plugin |
failoverReaderHostSelectorStrategy |
2.4.0 | FailoverConnectionPlugin.FAILOVER_READER_HOST_SELECTOR_STRATEGY |
Failover Plugin v2 |
failoverTimeoutMs |
0.1.0 | FailoverConnectionPlugin.FAILOVER_TIMEOUT_MS |
Failover Plugin Failover Plugin v2 |
failoverWriterReconnectIntervalMs |
0.1.0 | FailoverConnectionPlugin.FAILOVER_WRITER_RECONNECT_INTERVAL_MS |
Failover Plugin |
failureDetectionCount |
0.1.0 | HostMonitoringConnectionPlugin.FAILURE_DETECTION_COUNT |
Host Monitoring Plugin |
failureDetectionEnabled |
0.1.0 | HostMonitoringConnectionPlugin.FAILURE_DETECTION_ENABLED |
Host Monitoring Plugin |
failureDetectionInterval |
0.1.0 | HostMonitoringConnectionPlugin.FAILURE_DETECTION_INTERVAL |
Host Monitoring Plugin |
failureDetectionTime |
0.1.0 | HostMonitoringConnectionPlugin.FAILURE_DETECTION_TIME |
Host Monitoring Plugin |
gdbEnableGlobalWriteForwarding |
4.0.0 | GdbSettings.ENABLE_GWF |
Global Database (GDB) Read/Write Splitting Plugin |
gdbRwHomeRegion |
3.2.0 | GdbReadWriteSplittingPlugin.RW_HOME_REGION |
Global Database (GDB) Read/Write Splitting Plugin |
gdbRwRestrictReaderToHomeRegion |
3.2.0 | GdbReadWriteSplittingPlugin.RESTRICT_READER_TO_HOME_REGION |
Global Database (GDB) Read/Write Splitting Plugin |
gdbRwRestrictWriterToHomeRegion |
3.2.0 | GdbReadWriteSplittingPlugin.RESTRICT_WRITER_TO_HOME_REGION |
Global Database (GDB) Read/Write Splitting Plugin |
gdbAccessibleRegions |
4.1.0 | PropertyDefinition.GDB_ACCESSIBLE_REGIONS |
Global Database (GDB) Failover Plugin Global Database (GDB) Read/Write Splitting Plugin |
gdbMonitoringConnectionPriority |
4.1.0 | GdbMonitoringConnectionHandler.GDB_MONITORING_CONNECTION_PRIORITY |
Global Database (GDB) Failover Plugin |
globalClusterInstanceHostPatterns |
3.0.0 | GlobalAuroraHostListProvider.GLOBAL_CLUSTER_INSTANCE_HOST_PATTERNS |
Failover Plugin v2 Global Database (GDB) Failover Plugin |
hostAvailabilityStrategyInitialBackoffTime |
2.2.4 | HostAvailabilityStrategyFactory.HOST_AVAILABILITY_STRATEGY_INITIAL_BACKOFF_TIME |
Host Availability Strategy |
hostAvailabilityStrategyMaxRetries |
2.2.4 | HostAvailabilityStrategyFactory.HOST_AVAILABILITY_STRATEGY_MAX_RETRIES |
Host Availability Strategy |
httpClientConnectTimeout |
2.3.2 | FederatedAuthPlugin.HTTP_CLIENT_CONNECT_TIMEOUT |
Federated Authentication Plugin |
httpClientConnectTimeout |
2.3.2 | OktaAuthPlugin.HTTP_CLIENT_CONNECT_TIMEOUT |
Okta Authentication Plugin |
httpClientSocketTimeout |
2.3.2 | FederatedAuthPlugin.HTTP_CLIENT_SOCKET_TIMEOUT |
Federated Authentication Plugin |
httpClientSocketTimeout |
2.3.2 | OktaAuthPlugin.HTTP_CLIENT_SOCKET_TIMEOUT |
Okta Authentication Plugin |
iamAccessTokenPropertyName |
3.0.0 | IamAuthConnectionPlugin.IAM_TOKEN_PROPERTY_NAME |
AWS IAM Authentication Plugin |
iamDefaultPort |
0.1.0 | IamAuthConnectionPlugin.IAM_DEFAULT_PORT |
AWS IAM Authentication Plugin |
iamExpiration |
0.1.0 | IamAuthConnectionPlugin.IAM_EXPIRATION |
AWS IAM Authentication Plugin |
iamHost |
1.0.1 | IamAuthConnectionPlugin.IAM_HOST |
AWS IAM Authentication Plugin |
iamIdpArn |
2.3.2 | OktaAuthPlugin.IAM_IDP_ARN |
Okta Authentication Plugin |
iamRegion |
0.1.0 | IamAuthConnectionPlugin.IAM_REGION |
AWS IAM Authentication Plugin |
iamRoleArn |
2.3.2 | FederatedAuthPlugin.IAM_ROLE_ARN |
Federated Authentication Plugin |
iamRoleArn |
2.3.2 | OktaAuthPlugin.IAM_ROLE_ARN |
Okta Authentication Plugin |
iamTokenExpiration |
2.3.2 | FederatedAuthPlugin.IAM_TOKEN_EXPIRATION |
Federated Authentication Plugin |
iamTokenExpiration |
2.3.2 | OktaAuthPlugin.IAM_TOKEN_EXPIRATION |
Okta Authentication Plugin |
idpEndpoint |
2.3.2 | FederatedAuthPlugin.IDP_ENDPOINT |
Federated Authentication Plugin |
idpEndpoint |
2.3.2 | OktaAuthPlugin.IDP_ENDPOINT |
Okta Authentication Plugin |
idpName |
2.3.2 | FederatedAuthPlugin.IDP_NAME |
Federated Authentication Plugin |
idpPassword |
2.3.2 | FederatedAuthPlugin.IDP_PASSWORD |
Federated Authentication Plugin |
idpPassword |
2.3.2 | OktaAuthPlugin.IDP_PASSWORD |
Okta Authentication Plugin |
idpPort |
2.3.2 | FederatedAuthPlugin.IDP_PORT |
Federated Authentication Plugin |
idpUsername |
2.3.2 | FederatedAuthPlugin.IDP_USERNAME |
Federated Authentication Plugin |
idpUsername |
2.3.2 | OktaAuthPlugin.IDP_USERNAME |
Okta Authentication Plugin |
inactiveClusterWriterEndpointSubstitutionRole |
3.2.0 | AuroraInitialConnectionStrategyPlugin.INACTIVE_CLUSTER_WRITER_SUBSTITUTION_ROLE |
Aurora Initial Connection Strategy Plugin |
inactiveHomeFailoverMode |
3.2.0 | GlobalDbFailoverConnectionPlugin.INACTIVE_HOME_FAILOVER_MODE |
Global Database (GDB) Failover Plugin |
initialConnectionHostSelectorStrategy |
3.1.0 | AuroraInitialConnectionStrategyPlugin.HOST_SELECTOR_STRATEGY |
Aurora Initial Connection Strategy Plugin |
keyManagementMaxRetries |
4.0.0 | EncryptionConfig.KEY_MANAGEMENT_MAX_RETRIES |
KMS Encryption Plugin |
keyManagementRetryBackoffBaseMs |
4.0.0 | EncryptionConfig.KEY_MANAGEMENT_RETRY_BACKOFF_BASE_MS |
KMS Encryption Plugin |
kms.region |
4.0.0 | EncryptionConfig.KMS_REGION |
KMS Encryption Plugin |
limitlessConnectMaxRetries |
2.4.0 | LimitlessConnectionPlugin.MAX_RETRIES |
Using the Limitless Connection Plugin |
limitlessGetTransactionRouterInfoMaxRetries |
2.4.0 | LimitlessConnectionPlugin.GET_ROUTER_MAX_RETRIES |
Using the Limitless Connection Plugin |
limitlessGetTransactionRouterInfoRetryIntervalMs |
2.4.0 | LimitlessConnectionPlugin.GET_ROUTER_RETRY_INTERVAL_MILLIS |
Using the Limitless Connection Plugin |
limitlessTransactionRouterMonitorDisposalTimeMs |
2.4.0 | LimitlessRouterServiceImpl.MONITOR_DISPOSAL_TIME_MS |
Using the Limitless Connection Plugin |
limitlessTransactionRouterMonitorIntervalMs |
2.4.0 | LimitlessConnectionPlugin.INTERVAL_MILLIS |
Using the Limitless Connection Plugin |
limitlessWaitForTransactionRouterInfo |
2.4.0 | LimitlessConnectionPlugin.WAIT_FOR_ROUTER_INFO |
Using the Limitless Connection Plugin |
loadBalancingIncludeWriter |
4.2.0 | UnifiedReadWriteSplittingPlugin.LOAD_BALANCING_INCLUDE_WRITER |
Read/Write Splitting Plugin |
loginTimeout |
2.2.0 | PropertyDefinition.LOGIN_TIMEOUT |
AWS Advanced JDBC Wrapper Parameters |
metadataCacheEnabled |
4.0.0 | EncryptionConfig.METADATA_CACHE_ENABLED |
KMS Encryption Plugin |
metadataCacheExpirationMinutes |
4.0.0 | EncryptionConfig.METADATA_CACHE_EXPIRATION_MINUTES |
KMS Encryption Plugin |
metadataCacheRefreshIntervalMs |
4.0.0 | EncryptionConfig.METADATA_CACHE_REFRESH_INTERVAL_MS |
KMS Encryption Plugin |
monitorDisposalTime |
0.1.0 | HostMonitorServiceImpl.MONITOR_DISPOSAL_TIME_MS |
Host Monitoring Plugin |
monitoringConnectionPriority |
4.1.0 | AuroraMonitoringConnectionHandler.MONITORING_CONNECTION_PRIORITY |
Global Database (GDB) Failover Plugin |
openConnectionRetryIntervalMs |
2.3.1 | AuroraInitialConnectionStrategyPlugin.OPEN_CONNECTION_RETRY_INTERVAL_MS |
Aurora Initial Connection Strategy Plugin |
openConnectionRetryTimeoutMs |
2.3.1 | AuroraInitialConnectionStrategyPlugin.OPEN_CONNECTION_RETRY_TIMEOUT_MS |
Aurora Initial Connection Strategy Plugin |
password |
0.1.0 | PropertyDefinition.PASSWORD |
AWS Advanced JDBC Wrapper Parameters |
queryLevelLoadBalancing |
4.2.0 | UnifiedReadWriteSplittingPlugin.QUERY_LEVEL_LOAD_BALANCING |
Read/Write Splitting Plugin |
readerHostSelectorStrategy |
2.0.0 | ReadWriteSplittingPlugin.READER_HOST_SELECTOR_STRATEGY |
Read/Write Splitting Plugin |
readerInitialConnectionHostSelectorStrategy |
2.3.1 | AuroraInitialConnectionStrategyPlugin.READER_HOST_SELECTOR_STRATEGY |
Aurora Initial Connection Strategy Plugin |
resetSessionStateOnClose |
2.3.3 | PropertyDefinition.RESET_SESSION_STATE_ON_CLOSE |
AWS Advanced JDBC Wrapper Parameters |
responseMeasurementIntervalMs |
2.3.2 | FastestResponseStrategyPlugin.RESPONSE_MEASUREMENT_INTERVAL_MILLIS |
Using the AWS Advanced JDBC Wrapper |
rollbackOnSwitch |
2.3.3 | PropertyDefinition.ROLLBACK_ON_SWITCH |
AWS Advanced JDBC Wrapper Parameters |
roundRobinDefaultWeight |
2.2.5 | RoundRobinHostSelector.ROUND_ROBIN_DEFAULT_WEIGHT |
Host Selection Strategies |
roundRobinHostWeightPairs |
2.2.5 | RoundRobinHostSelector.ROUND_ROBIN_HOST_WEIGHT_PAIRS |
Host Selection Strategies |
rpIdentifier |
2.3.2 | FederatedAuthPlugin.RELAYING_PARTY_ID |
Federated Authentication Plugin |
secretsManagerConnectRetryIntervalMs |
4.4.0 | AwsSecretsManagerConnectionPlugin.SECRETS_MANAGER_CONNECT_RETRY_INTERVAL_MS_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerConnectRetryTimeoutMs |
4.4.0 | AwsSecretsManagerConnectionPlugin.SECRETS_MANAGER_CONNECT_RETRY_TIMEOUT_MS_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerEndpoint |
2.3.0 | AwsSecretsManagerConnectionPlugin.ENDPOINT_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerExpirationTimeSec |
3.1.0 | AwsSecretsManagerConnectionPlugin.SECRETS_MANAGER_EXPIRATION_SEC_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerRegion |
1.0.0 | AwsSecretsManagerConnectionPlugin.REGION_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerSecretId |
1.0.0 | AwsSecretsManagerConnectionPlugin.SECRET_ID_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerSecretPasswordProperty |
3.1.0 | AwsSecretsManagerConnectionPlugin.SECRETS_MANAGER_SECRET_PASSWORD_PROPERTY |
AWS Secrets Manager Plugin |
secretsManagerSecretUsernameProperty |
3.1.0 | AwsSecretsManagerConnectionPlugin.SECRETS_MANAGER_SECRET_USERNAME_PROPERTY |
AWS Secrets Manager Plugin |
singleWriterConnectionString |
1.0.1 | ConnectionStringHostListProvider.SINGLE_WRITER_CONNECTION_STRING |
Read/Write Splitting Plugin |
skipFailoverOnInterruptedThread |
2.5.5 | FailoverConnectionPlugin.SKIP_FAILOVER_ON_INTERRUPTED_THREAD |
Failover Plugin Failover Plugin v2 |
skipInactiveWriterClusterEndpointCheck |
3.2.0 | AuroraStaleDnsHelper.SKIP_INACTIVE_WRITER_CLUSTER_CHECK |
Global Database (GDB) Failover Plugin |
skipWrappingForPackages |
2.6.3 | PropertyDefinition.SKIP_WRAPPING_FOR_PACKAGES |
AWS Advanced JDBC Wrapper Parameters |
socketTimeout |
2.3.1 | PropertyDefinition.SOCKET_TIMEOUT |
AWS Advanced JDBC Wrapper Parameters |
srwConnectRetryIntervalMs |
3.0.0 | SimpleReadWriteSplittingPlugin.SRW_CONNECT_RETRY_INTERVAL_MS |
Simple Read/Write Splitting Plugin |
srwConnectRetryTimeoutMs |
3.0.0 | SimpleReadWriteSplittingPlugin.SRW_CONNECT_RETRY_TIMEOUT_MS |
Simple Read/Write Splitting Plugin |
srwReadEndpoint |
3.0.0 | SimpleReadWriteSplittingPlugin.SRW_READ_ENDPOINT |
Simple Read/Write Splitting Plugin |
srwWriteEndpoint |
3.0.0 | SimpleReadWriteSplittingPlugin.SRW_WRITE_ENDPOINT |
Simple Read/Write Splitting Plugin |
sslInsecure |
2.3.2 | FederatedAuthPlugin.SSL_INSECURE |
Federated Authentication Plugin |
sslInsecure |
2.3.2 | OktaAuthPlugin.SSL_INSECURE |
Okta Authentication Plugin |
targetDriverAutoRegister |
2.3.1 | TargetDriverDialectManager.TARGET_DRIVER_AUTO_REGISTER |
AWS Advanced JDBC Wrapper Parameters |
tcpKeepAlive |
2.3.1 | PropertyDefinition.TCP_KEEP_ALIVE |
AWS Advanced JDBC Wrapper Parameters |
telemetryFailoverAdditionalTopTrace |
2.3.0 | FailoverConnectionPlugin.TELEMETRY_FAILOVER_ADDITIONAL_TOP_TRACE |
Failover Plugin |
telemetryMetricsBackend |
2.3.0 | PropertyDefinition.TELEMETRY_METRICS_BACKEND |
Monitoring |
telemetrySubmitToplevel |
2.3.0 | PropertyDefinition.TELEMETRY_SUBMIT_TOPLEVEL |
Monitoring |
telemetryTracesBackend |
2.3.0 | PropertyDefinition.TELEMETRY_TRACES_BACKEND |
Monitoring |
transferSessionStateOnSwitch |
2.3.3 | PropertyDefinition.TRANSFER_SESSION_STATE_ON_SWITCH |
AWS Advanced JDBC Wrapper Parameters |
user |
0.1.0 | PropertyDefinition.USER |
AWS Advanced JDBC Wrapper Parameters |
verifyInactiveClusterWriterEndpointConnectionType |
3.2.0 | AuroraInitialConnectionStrategyPlugin.VERIFY_INACTIVE_CLUSTER_WRITER_CONNECTION_ROLE |
Aurora Initial Connection Strategy Plugin |
verifyInitialConnectionRole |
4.0.0 | ReadWriteSplittingPlugin.VERIFY_INITIAL_CONNECTION_ROLE |
Read/Write Splitting Plugin |
verifyInitialConnectionType |
3.0.0 | SimpleReadWriteSplittingPlugin.VERIFY_INITIAL_CONNECTION_TYPE |
Simple Read/Write Splitting Plugin |
verifyNewSrwConnections |
3.0.0 | SimpleReadWriteSplittingPlugin.VERIFY_NEW_SRW_CONNECTIONS |
Simple Read/Write Splitting Plugin |
verifyOpenedConnectionType |
2.5.5 | AuroraInitialConnectionStrategyPlugin.VERIFY_OPENED_CONNECTION_ROLE |
Aurora Initial Connection Strategy Plugin |
waitForCustomEndpointInfo |
2.5.0 | CustomEndpointPlugin.WAIT_FOR_CUSTOM_ENDPOINT_INFO |
Custom Endpoint Plugin |
waitForCustomEndpointInfoTimeoutMs |
2.5.0 | CustomEndpointPlugin.WAIT_FOR_CUSTOM_ENDPOINT_INFO_TIMEOUT_MS |
Custom Endpoint Plugin |
waitForInitialTopologyMs |
4.1.0 | AuroraInitialConnectionStrategyPlugin.WAIT_FOR_INITIAL_TOPOLOGY_MS |
Aurora Initial Connection Strategy Plugin |
weightedRandomHostWeightPairs |
2.6.5 | WeightedRandomHostSelector.WEIGHTED_RANDOM_HOST_WEIGHT_PAIRS |
Host Availability Strategy |
wrapperCaseSensitive |
2.6.0 | PropertyDefinition.CASE_SENSITIVE |
AWS Advanced JDBC Wrapper Parameters |
wrapperDialect |
2.0.0 | DialectManager.DIALECT |
Dialects |
wrapperDriverName |
1.0.2 | DriverMetaDataConnectionPlugin.WRAPPER_DRIVER_NAME |
DriverMetaDataConnectionPlugin |
wrapperLogUnclosedConnections |
1.0.0 | PropertyDefinition.LOG_UNCLOSED_CONNECTIONS |
AWS Advanced JDBC Wrapper Parameters |
wrapperLoggerLevel |
1.0.0 | PropertyDefinition.LOGGER_LEVEL |
Logging |
wrapperPlugins |
1.0.0 | PropertyDefinition.PLUGINS |
AWS Advanced JDBC Wrapper Parameters |
wrapperProfileName |
1.0.0 | PropertyDefinition.PROFILE_NAME |
Configuration Profiles |
wrapperTargetDriverDialect |
2.2.0 | TargetDriverDialectManager.TARGET_DRIVER_DIALECT |
AWS Advanced JDBC Wrapper Parameters |
A Secret ARN has the following format: arn:aws:secretsmanager:<Region>:<AccountId>:secret:SecretName-6RandomCharacters
Enabling logging is a very useful mechanism for troubleshooting any issue one might potentially experience while using the AWS Advanced JDBC Wrapper.
In order to learn how to enable and configure logging, check out the Logging section.
Technical documentation regarding the functionality of the AWS Advanced JDBC Wrapper will be maintained in this GitHub repository. Since the AWS Advanced JDBC Wrapper requires an underlying JDBC driver, please refer to the individual driver's documentation for driver-specific information.
To find all the documentation and concrete examples on how to use the AWS Advanced JDBC Wrapper, please refer to the AWS Advanced JDBC Wrapper Documentation page.
The MariaDB driver uses pipelining for some optimizations, and Aurora does not support pipelining. MariaDB removed its own aurora failover mode in MariaDB Connector/J 3.0 for that reason. The AWS Advanced JDBC Wrapper does not use that mode, because it provides failover itself.
The wrapper's integration tests cover MariaDB Connector/J 3.5.x against Aurora MySQL. MariaDB Connector/J 3.x enables its pipelining-dependent features only when the server advertises MariaDB bulk-operation support, which Aurora MySQL does not, so those features are not used in that configuration.
To disable pipelining explicitly, use the property that matches your driver version:
- MariaDB Connector/J 3.1 and above: set
disablePipelinetotrue. - MariaDB Connector/J 2.x: set
usePipelineAuthanduseBatchMultiSendtofalse.
// MariaDB Connector/J 3.1 and above
Properties props = new Properties();
props.setProperty("disablePipeline", "true");Note that usePipelineAuth and useBatchMultiSend do not exist in MariaDB Connector/J 3.x; they were removed in version 3.0. MariaDB Connector/J accepts unknown properties without raising an error, so setting them on a 3.x driver has no effect.
Support for Blue/Green deployments using the AWS Advanced JDBC Wrapper requires specific metadata tables. The following service versions provide support for Blue/Green Deployments:
- Supported RDS PostgreSQL Versions:
rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)and above. - Supported Aurora PostgreSQL Versions: Engine Release
17.5, 16.9, 15.13, 14.18, 13.21and above. - Supported Aurora MySQL Versions: Engine Release
3.07and above.
Please note that Aurora Global Database and RDS Multi-AZ clusters with Blue/Green deployments is currently not supported. For detailed information on supported database versions, refer to the Blue/Green Deployment Plugin Documentation.
| Description | Examples |
|---|---|
| Using the AWS Advanced JDBC Wrapper to get a simple connection | PostgreSQL |
| Using the AWS Advanced JDBC Wrapper with failover handling | PostgreSQL |
Using the AWS IAM Authentication Plugin with DriverManager |
PostgreSQL MySQL MariaDB |
Using the AWS IAM Authentication Plugin with DataSource |
PostgreSQL and MySQL |
Using the AWS Secrets Manager Plugin with DriverManager |
PostgreSQL MySQL |
| Using the AWS Credentials Manager to configure an alternative AWS credentials provider. | PostgreSQL and MySQL |
Using the AWS Advanced JDBC Wrapper with AWSWrapperDatasource |
PostgreSQL |
| Using the Driver Metadata Plugin to override driver name, this plugin enables specific database features that may only be available to target drivers | PostgreSQL |
Using the Read/Write Splitting Plugin with DriverManager |
PostgreSQL MySQL |
| Using the Read/Write Splitting Plugin with Spring | PostgreSQL MySQL |
Using HikariCP with the AWSWrapperDatasource |
PostgreSQL |
Using HikariCP with the AWSWrapperDatasource with failover handling |
PostgreSQL |
| Using Spring and HikariCP with the AWS Advanced JDBC Wrapper | PostgreSQL |
| Using Spring and HikariCP with the AWS Advanced JDBC Wrapper and failover handling | PostgreSQL |
| Using Spring and Hibernate with the AWS Advanced JDBC Wrapper | PostgreSQL |
| Using Spring and Wildfly with the AWS Advanced JDBC Wrapper | PostgreSQL |
| Using Vert.x and c3p0 with the AWS Advanced JDBC Wrapper | PostgreSQL |
| Using the AWS Advanced JDBC Wrapper with Telemetry and using the AWS Distro for OpenTelemetry Collector | PostgreSQL |
| Using the AWS Advanced JDBC Wrapper with Telemetry and using the AWS X-Ray Daemon | PostgreSQL |
| Configuring the AWS Advanced JDBC Wrapper with an AI tool (Cursor, Claude, ChatGPT, Bedrock, etc.) using the Configuration Assistant skill | JDBC Wrapper Configuration Assistant |
The AWS Advanced JDBC Wrapper is part of a broader family of AWS "wrapper" drivers that bring the same advanced functionality, such as failover support and IAM authentication, to other languages and database connectivity standards. If you are working outside of Java, you may find one of the following drivers useful:
| Driver | Repository |
|---|---|
| AWS Advanced Python Wrapper | https://github.com/aws/aws-advanced-python-wrapper |
| AWS Advanced NodeJS Wrapper | https://github.com/aws/aws-advanced-nodejs-wrapper |
| AWS Advanced Go Wrapper | https://github.com/aws/aws-advanced-go-wrapper |
| AWS Advanced .NET Wrapper | https://github.com/aws/aws-advanced-dotnet-data-provider-wrapper |
| AWS Advanced ODBC Wrapper | https://github.com/aws/aws-advanced-odbc-wrapper |
If you encounter a bug with the AWS Advanced JDBC Wrapper, we would like to hear about it. Please search the existing 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.
For all other questions, please use GitHub discussions.
- Set up your environment by following the directions in the Development Guide.
- To contribute, first make a fork of this project.
- 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).
- Create a pull request from your fork.
- Pull requests need to be approved and merged by maintainers into the main branch.
Note: Before making a pull request, run all tests and verify everything is passing.
The project source code is written using the Google checkstyle, 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.
The aws-advanced-jdbc-wrapper has a regular monthly release cadence. A new release will occur during the last week of each month. However, if there are no changes since the latest release, then a release will not occur.
This aws-advanced-jdbc-wrapper is being tested against the following Community and Aurora database versions in our test suite:
| Database | Versions |
|---|---|
| MySQL | 8.0.36 |
| PostgreSQL | 16.2 |
| Aurora MySQL | - Default version. To check the default version, open the RDS "Create database" page in the AWS console and check the pre-selected database version. - Latest release, as shown on this page. |
| Aurora PostgreSQL | - Default version. To check the default version, open the RDS "Create database" page in the AWS console and check the pre-selected database version. - Latest release, as shown on this page. |
The aws-advanced-jdbc-wrapper is compatible with MySQL 5.7 and MySQL 8.0 as per the Community MySQL Connector/J 8.0 Driver.
This software is released under the Apache 2.0 license.