https://github.com/aws/aws-secretsmanager-jdbc

The AWS Secrets Manager JDBC Library enables Java developers to easily connect to SQL databases using secrets stored in AWS Secrets Manager.
https://github.com/aws/aws-secretsmanager-jdbc

aws aws-secrets-manager jdbc-driver secret

Last synced: 4 days ago
JSON representation

The AWS Secrets Manager JDBC Library enables Java developers to easily connect to SQL databases using secrets stored in AWS Secrets Manager.

• Host: GitHub
• URL: https://github.com/aws/aws-secretsmanager-jdbc
• Owner: aws
• License: apache-2.0
• Created: 2018-10-22T23:23:36.000Z (over 6 years ago)
• Default Branch: v2
• Last Pushed: 2025-02-17T21:35:34.000Z (about 2 months ago)
• Last Synced: 2025-04-07T04:11:16.232Z (12 days ago)
• Topics: aws, aws-secrets-manager, jdbc-driver, secret
• Language: Java
• Homepage:
• Size: 130 KB
• Stars: 169
• Watchers: 24
• Forks: 80
• Open Issues: 25
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Codeowners: CODEOWNERS

Awesome Lists containing this project

• jimsghstars - aws/aws-secretsmanager-jdbc - The AWS Secrets Manager JDBC Library enables Java developers to easily connect to SQL databases using secrets stored in AWS Secrets Manager. (Java)

README

        
# AWS Secrets Manager JDBC Library

[![Java Build](https://github.com/aws/aws-secretsmanager-jdbc/actions/workflows/CI.yml/badge.svg?event=push)](https://github.com/aws/aws-secretsmanager-jdbc/actions/workflows/CI.yml)

[![Coverage](https://codecov.io/gh/aws/aws-secretsmanager-jdbc/branch/v2/graph/badge.svg?token=hCl7eBaSwn)](https://codecov.io/gh/aws/aws-secretsmanager-jdbc)

The **AWS Secrets Manager JDBC Library** enables Java developers to easily connect to SQL databases using secrets stored in AWS Secrets Manager.

## License

This library is licensed under the Apache 2.0 License.

## Features

* Provides wrappers to common JDBC drivers enabling simple database connectivity

* Provides database connection pooling support through c3p0

## Building from Source

After you've downloaded the code from GitHub, you can build it using Maven. To disable GPG signing in the build, use this command: `mvn clean install -Dgpg.skip=true`

## Usage

The recommended way to use the SQL Connection Library is to consume it from Maven.  The latest released version can be found at: https://mvnrepository.com/artifact/com.amazonaws.secretsmanager/aws-secretsmanager-jdbc

``` xml

    com.amazonaws.secretsmanager

    aws-secretsmanager-jdbc

    2.0.0

```

To use the latest build (pre-release), don't forget to enable the download of snapshot jars from Maven.

``` xml

  

    allow-snapshots

    true

    

      

        snapshots-repo

        https://aws.oss.sonatype.org/content/repositories/snapshots

        false

        true

      

    

  

```

### Usage Example

We provide database drivers that intercept calls to real database drivers and replace secret IDs with actual login credentials.

This prevents hard-coding database credentials into your application code.

The following is an example which uses the secret to resolve both the endpoint and the login credentials.

```

// Load the JDBC driver

Class.forName( "com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver" ).newInstance();

// Retrieve the connection info from the secret using the secret ARN

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);

```

To specify a custom endpoint and port instead of resolving from the secret, use the jdbc-secretsmanager prefix with your database information.

```

// Options to resolve the connection information

// Set url to secret arn to resolve endpoint and port from secret

String URL = "secretId";

// Use jdbc-secretsmanager prefix to specify endpoint and port instead of resolving from secret

String URL = "jdbc-secretsmanager:postgresql://example.com:5432/database";

```

The secret should be in the correct JSON format. For more information, see the [AWS Secrets Manager documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_secret_json_structure). For example:

```json

{

  "host": "",

  "username": "",

  "password": "",

  "dbname": "",

  "port": "",

}

```

We support a variety of drivers. For more information, see the [AWS Secrets Manager JDBC documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_jdbc).

## Credentials

This library uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html). The following options exist to override some of the defaults:

1) Set a PrivateLink DNS endpoint URL and a region in the secretsmanager.properties file:

```text

drivers.vpcEndpointUrl= #The endpoint URL

drivers.vpcEndpointRegion= #The endpoint region

```

2) Override the primary region by setting the 'AWS_SECRET_JDBC_REGION' environment variable to the preferred region, or via the secretsmanager.properties file:

```text

drivers.region= #The region to use.

```

If this driver is running on EKS, the library could pick up the credentials of the node it is running on instead of the service account role ([issue](https://github.com/aws/aws-secretsmanager-jdbc/issues/55)). To address this, add version `2` of `software.amazon.awssdk:sts` to your Gradle/Maven project file as a dependency.