Connect to a SQL database with credentials in an AWS Secrets Manager secret
In Java applications, you can use the Secrets Manager SQL Connection drivers to connect to MySQL, PostgreSQL, Oracle, and MSSQLServer databases using credentials stored in Secrets Manager. Each driver wraps the base JDBC driver, so you can use JDBC calls to access your database. However, instead of passing a username and password for the connection, you provide the ID of a secret. The driver calls Secrets Manager to retrieve the secret value, and then uses the credentials in the secret to connect to the database. The driver also caches the credentials using the Java client-side caching library , so future connections don't require a call to Secrets Manager. By default, the cache refreshes every hour and also when the secret is rotated. To configure the cache, see SecretCacheConfiguration .
You can download the source code from
GitHub
To use the Secrets Manager SQL Connection drivers:
Your application must be in Java 8 or higher.
Your secret must be one of the following:
-
A database secret in the expected JSON structure . To check the format, in the Secrets Manager console, view your secret and choose Retrieve secret value . Alternatively, in the AWS CLI, call get-secret-value .
-
An Amazon RDS managed secret . For this type of secret, you must specify an endpoint and port when you establish the connection.
If your database is replicated to other Regions, to connect to a replica database in another Region, you specify the regional endpoint and port when you create the connection. You can store regional connection information in the secret as extra key/value pairs, in SSM Parameter Store parameters, or in your code configuration.
To add the driver to your project, in your Maven build file
pom.xml
,
add the following dependency for the driver. For more information, see
Secrets Manager SQL Connection Library
<dependency> <groupId>com.amazonaws.secretsmanager</groupId> <artifactId>aws-secretsmanager-jdbc</artifactId> <version>1.0.8</version> </dependency>
The driver uses the
default credential provider chain
. If you run the driver on Amazon EKS, it might pick up the credentials of the node it is running on instead of the service account role. To address this, add version 1 of
com.amazonaws:aws-java-sdk-sts
to your Gradle or Maven project file as a dependency.
To set an AWS PrivateLink DNS endpoint URL and a region in the
secretsmanager.properties
file:
drivers.vpcEndpointUrl =
endpoint URL
drivers.vpcEndpointRegion =endpoint region
To override the primary region, set the
AWS_SECRET_JDBC_REGION
environment variable or make the following change to the
secretsmanager.properties
file:
drivers.region =
region
Examples:
Establish a connection to a database
The following example shows how to establish a connection to a database using the
credentials and connection information in a secret. Once you have the connection, you
can use JDBC calls to access the database. For more information, see
JDBC
Basics
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver" ).newInstance(); // Retrieve the connection info from the secret String URL = "
secretId
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver" ).newInstance(); // Retrieve the connection info from the secret String URL = "
secretId
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver" ).newInstance(); // Retrieve the connection info from the secret String URL = "
secretId
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver" ).newInstance(); // Retrieve the connection info from the secret String URL = "
secretId
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
Establish a connection by specifying the endpoint and port
The following example shows how to establish a connection to a database using the credentials in a secret with an endpoint and port that you specify.
Amazon RDS managed secrets don't include the endpoint and port of the database. To connect to a database using master credentials in a secret that's managed by Amazon RDS, you specify them in your code.
Secrets that are replicated to other Regions can improve latency for the connection to the regional database, but they do not contain different connection information from the source secret. Each replica is a copy of the source secret. To store regional connection information in the secret, add more key/value pairs for the endpoint and port information for the Regions.
Once you have the connection, you can use JDBC calls to access the database. For more
information, see
JDBC
Basics
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:
mysql://example.com:3306
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:
postgresql://example.com:5432/database
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:
oracle:thin:@example.com:1521/ORCL
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
// Load the JDBC driver Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver" ).newInstance(); // Set the endpoint and port. You can also retrieve it from a key/value pair in the secret. String URL = "jdbc-secretsmanager:
sqlserver://example.com:1433
"; // Populate the user property with the secret ARN to retrieve user and password from the secret Properties info = new Properties( ); info.put( "user", "secretId
" ); // Establish the connection conn = DriverManager.getConnection(URL, info);
Use c3p0 connection pooling to establish a connection
The following example shows how to establish a connection pool with a
c3p0.properties
file that uses the
driver to retrieve credentials and connection information from the secret. For
user
and
jdbcUrl
, enter the secret ID to configure the
connection pool. Then you can retrieve connections from the pool and use them as any
other database connections. For more information, see
JDBC
Basics
For more information about c3p0, see
c3p0
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver c3p0.jdbcUrl=secretId
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver c3p0.jdbcUrl=secretId
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver c3p0.jdbcUrl=secretId
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver c3p0.jdbcUrl=secretId
Use c3p0 connection pooling to establish a connection by specifying the endpoint and port
The following example shows how to establish a connection pool with a
c3p0.properties
file that uses the the driver to retrieve credentials in a secret with an endpoint and port that you specify. Then you can retrieve connections from the pool and use
them as any other database connections. For more information, see
JDBC
Basics
Amazon RDS managed secrets don't include the endpoint and port of the database. To connect to a database using master credentials in a secret that's managed by Amazon RDS, you specify them in your code.
Secrets that are replicated to other Regions can improve latency for the connection to the regional database, but they do not contain different connection information from the source secret. Each replica is a copy of the source secret. To store regional connection information in the secret, add more key/value pairs for the endpoint and port information for the Regions.
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver c3p0.jdbcUrl=jdbc-secretsmanager:mysql://example.com:3306
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver c3p0.jdbcUrl=jdbc-secretsmanager:postgresql://example.com:5432/database
c3p0.user=
secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver c3p0.jdbcUrl=jdbc-secretsmanager:oracle:thin:@example.com:1521/ORCL
c3p0.user=
secretId