Connecting with a DataSource

You can use the DriverManager class or a datasource to establish a new connection when using the AWS Advanced JDBC Wrapper. The AWS Advanced JDBC Wrapper has a built-in datasource class named AwsWrapperDataSource that allows the AWS Advanced JDBC Wrapper to work with various driver-specific datasources.

Distributed (XA) transactions: to participate in XA / two-phase commit transactions coordinated by a JTA transaction manager, use the javax.sql.XADataSource entry point instead. See Using the AWS Advanced JDBC Wrapper as an XADataSource.

Using the AwsWrapperDataSource

To establish a connection with the AwsWrapperDataSource, you must:

1. Select a driver-specific datasource depending on what underlying driver is being used (for example: org.postgresql.ds.PGSimpleDataSource or com.mysql.cj.jdbc.MysqlDataSource).
2. Set up basic connection information in the AwsWrapperDataSource. See this table for the available options.
3. Configure any needed driver-specific datasource in the AwsWrapperDataSource using the target dataSource properties.
4. Configure any needed AWS Advanced JDBC Wrapper properties in the AwsWrapperDataSource using the target dataSource properties.

Configurable DataSource Properties

See the table below for a list of configurable properties.

:warning: 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 Advanced JDBC Wrapper 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 Advanced JDBC Wrapper properties.	Properties	No	See this example.

Using the AwsWrapperDataSource with Connection Pooling Frameworks

The JDBC Wrapper also supports establishing a connection with a connection pooling framework.

To use the AWS Advanced JDBC Wrapper with a connection pool, you must:

1. Configure the connection pool.
2. Set the datasource class name to software.amazon.jdbc.ds.AwsWrapperDataSource for the connection pool.
3. Configure the AwsWrapperDataSource.
4. Configure the driver-specific datasource.

HikariCP Pooling Example

HikariCP is a popular connection pool; the steps that follow configure a simple connection pool with HikariCP and PostgreSQL:

1. Configure the HikariCP datasource:

   HikariDataSource ds = new HikariDataSource();
   
   // Configure the connection pool:
   ds.setMaximumPoolSize(5);
   ds.setIdleTimeout(60000);
   ds.setUsername(USER);
   ds.setPassword(PASSWORD);
   

2. Set the datasource class name to software.amazon.jdbc.ds.AwsWrapperDataSource:

   ds.setDataSourceClassName(AwsWrapperDataSource.class.getName());
   

3. 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");
   

   See the DatasourceUrlExample for a complete example of configuring the data source with a JDBC URL.

4. Set the driver-specific datasource:

   ds.addDataSourceProperty("targetDataSourceClassName", "org.postgresql.ds.PGSimpleDataSource");
   

5. Configure the driver-specific datasource and any AWS Advanced JDBC Wrapper properties, if needed. This step is optional:

   Properties targetDataSourceProps = new Properties();
   targetDataSourceProps.setProperty("socketTimeout", "10");
   targetDataSourceProps.setProperty("wrapperLoggerLevel", "ALL");
   ds.addDataSourceProperty("targetDataSourceProperties", targetDataSourceProps);
   

   Alternatively, the driver-specific datasource and any AWS Advanced JDBC Wrapper properties can be supplied as query parameters of the JDBC URL instead of being set in code:

   ds.addDataSourceProperty("jdbcUrl", "jdbc:aws-wrapper:postgresql://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:5432/postgres?socketTimeout=10&wrapperLoggerLevel=ALL");
   

   Note

   
   wrapperLoggerLevel is applied on a best-effort basis when a connection is opened, and it doesn't override a level that is explicitly configured for a particular logger, for example in a logging.properties file. See Logging for the details.

Examples

See here for a simple AWS Driver Datasource example.

See here for a complete Hikari example.