You can use the DriverManager
class or a datasource to establish a new connection when using the AWS JDBC Driver. The AWS JDBC Driver has a built-in datasource class named AwsWrapperDataSource that allows the AWS JDBC Driver to work with various driver-specific datasources.
To establish a connection with the AwsWrapperDataSource, you must:
- Select a driver-specific datasource depending on what underlying driver is being used (for example:
org.postgresql.ds.PGSimpleDataSource
orcom.mysql.cj.jdbc.MysqlDataSource
). - Set up basic connection information in the AwsWrapperDataSource. See this table for the available options.
- Configure any needed driver-specific datasource in the AwsWrapperDataSource using the target dataSource properties.
- Configure any needed AWS JDBC Driver properties in the AwsWrapperDataSource using the target dataSource properties.
See the table below for a list of configurable properties.
⚠️ Note: If the same connection property is provided both explicitly in the connection URL and in the datasource properties, the value set in the datasource properties will take precedence.
Property | Configuration Method | Description | Type | Required | Example |
---|---|---|---|---|---|
Server name | setServerName |
The name of the server. | String |
Yes, if no URL is provided. | db-server.mydomain.com |
Server port | setServerPort |
The server port. | String |
No | 5432 |
Database name | setDatabase |
The name of the database. | String |
No | testDatabase |
JDBC URL | setJdbcUrl |
The URL to connect with. | String |
No. Either URL or server name should be set. If both URL and server name have been set, URL will take precedence. Please note that some drivers, such as MariaDb, require some parameters to be included particularly in the URL. | jdbc:postgresql://localhost/postgres |
JDBC protocol | setJdbcProtocol |
The JDBC protocol that will be used. | String |
Yes, if the JDBC URL has not been set. | jdbc:postgresql: |
Underlying DataSource class | setTargetDataSourceClassName |
The fully qualified class name of the underlying DataSource class the AWS JDBC Driver should use. | String |
Yes, if the JDBC URL has not been set. | org.postgresql.ds.PGSimpleDataSource |
Target DataSource Properties | setTargetDataSourceProperties |
Any additional properties that are required. This includes properties specific to the current underlying driver as well as any AWS JDBC Driver properties. | Properties |
No | See this example. |
The JDBC Wrapper also supports establishing a connection with a connection pooling framework.
To use the AWS JDBC Driver with a connection pool, you must:
- Configure the connection pool.
- Set the datasource class name to
software.amazon.jdbc.ds.AwsWrapperDataSource
for the connection pool. - Configure the
AwsWrapperDataSource
. - Configure the driver-specific datasource.
HikariCP is a popular connection pool; the steps that follow configure a simple connection pool with HikariCP and PostgreSQL:
-
Configure the HikariCP datasource:
HikariDataSource ds = new HikariDataSource(); // Configure the connection pool: ds.setMaximumPoolSize(5); ds.setIdleTimeout(60000); ds.setUsername(USER); ds.setPassword(PASSWORD);
-
Set the datasource class name to
software.amazon.jdbc.ds.AwsWrapperDataSource
:ds.setDataSourceClassName(AwsWrapperDataSource.class.getName());
-
Configure the
AwsWrapperDataSource
:// Note: jdbcProtocol is required when connecting via server name ds.addDataSourceProperty("jdbcProtocol", "jdbc:postgresql:"); ds.addDataSourceProperty("serverName", "db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com"); ds.addDataSourceProperty("serverPort", "5432"); ds.addDataSourceProperty("database", "postgres"); // Alternatively, the AwsWrapperDataSource can be configured with a JDBC URL instead of individual properties as seen above. ds.addDataSourceProperty("jdbcUrl", "jdbc:aws-wrapper:postgresql://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:5432/postgres");
-
Set the driver-specific datasource:
ds.addDataSourceProperty("targetDataSourceClassName", "org.postgresql.ds.PGSimpleDataSource");
-
Configure the driver-specific datasource and any AWS JDBC Driver properties, if needed. This step is optional:
Properties targetDataSourceProps = new Properties(); targetDataSourceProps.setProperty("socketTimeout", "10"); targetDataSourceProps.setProperty("wrapperLoggerLevel", "ALL"); ds.addDataSourceProperty("targetDataSourceProperties", targetDataSourceProps);
⚠️ Note: HikariCP supports either DataSource-based configuration or DriverManager-based configuration by specifying thedataSourceClassName
or thejdbcUrl
. When using theAwsWrapperDataSource
you must specify thedataSourceClassName
, and theHikariDataSource.setJdbcUrl
method should not be used. For more information see HikariCP's documentation.
See here for a simple AWS Driver Datasource example.
See here for a complete Hikari example.