# Support for AWS RDS

Connecting to an RDS database can be done with the standard Smile CDR database connection configuration, using the username and password, while pointing to the RDS instance. However, most installations want to use AWS-specific authentication methods. This can be accomplished via the AWS Advanced JDBC Driver.

## AWS Advanced JDBC Driver

As of 2025.05.R01, Smile CDR now supports usage of the [AWS Advanced JDBC Driver](https://github.com/aws/aws-advanced-jdbc-wrapper). This driver allows straightforward connections to AWS RDS databases. In previous versions, a patchwork of libraries were used to support this behavior. These have all been replaced with the AWS Advanced JDBC Driver. It is enabled by adding `aws-wrapper` into the JDBC prefix, so instead of using `jdbc:postgresql://`, you would use `jdbc:aws-wrapper:postgresql://`.

This driver is primarily configured via the JDBC URL. This means that plugins, configuration options, secret names, usernames, and passwords can all be injected via the JDBC URL.

Any configuration set in the JDBC URL will take precedence over the settings set in Smile CDR. For example, if you set `?user=myuser` in the JDBC URL, and then set `db.username=otheruser`, the resolved username will be `myuser`.

If you want to use these features, it is recommended to read the [official documentation](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/Documentation.md).

The remaining sections in this page cover common examples of how to connect to an RDS database using various authentication methods.

# Username and Password Authentication

Since you can configure the username and password directly in the JDBC URL, they can be set in the `db.url` property, and omitted from the `db.username` and `db.password` properties. The following is an example configuration which does this.

```properties
module.clustermgr.type                         =CLUSTER_MGR
module.clustermgr.config.db.driver             =POSTGRES_9_4
module.clustermgr.config.db.url                =jdbc:aws-wrapper:postgresql://my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr?user=myuser&password=somepassword
module.clustermgr.config.db.username           =
module.clustermgr.config.db.password           =
```

Copy

Let's analyze the JDBC URL: `jdbc:aws-wrapper:postgresql://my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr?user=myuser&password=somepassword`

- **jdbc:aws-wrapper:postgresql** – This indicates that the AWS Advanced JDBC Driver should be used, and that the underlying target driver should be for PostgreSQL.
- **my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr** – This is the connection URL of the RDS database, along with its port (5432), and the target database name (cdr)
- **user** – The user to use for the standard username + password authentication.
- **password** – The password to use for the standard username + password authentication.

# IAM Authentication

It is also possible to use this driver to connect to an AWS RDS database using AWS IAM authentication.

In versions before 2025.05.R01, the `Use IAM Authentication` setting had to be enabled. This setting is now deprecated, in favor of the preferred JDBC URL approach. The following is an example of such a configuration:

```properties
module.clustermgr.type                         =CLUSTER_MGR
module.clustermgr.config.db.driver             =POSTGRES_9_4
module.clustermgr.config.db.url                =jdbc:aws-wrapper:postgresql://my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr?wrapperPlugins=iam&user=rds-tester
module.clustermgr.config.db.username           =
module.clustermgr.config.db.password           =
```

Copy

Let's analyze the JDBC URL: `jdbc:aws-wrapper:postgresql://my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr?wrapperPlugins=iam&user=rds-tester`

- **jdbc:aws-wrapper:postgresql** – This indicates that the AWS Advanced JDBC Driver should be used, and that the underlying target driver should be for PostgreSQL.
- **my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr** – This is the connection URL of the RDS database, along with its port (5432), and the target database name (cdr)
- **wrapperPlugins=iam** – This enables the [IAM Authentication Plugin](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) for the driver.
- **user=rds-tester** – This is the username that should be used to connect to the RDS instance via IAM.

For IAM Authentication, the [DefaultCredentialProviderChain](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html) is used. Please visit that link to read about all the ways to provide credentials to the driver wrapper.

Since IAM Authentication to RDS also requires a region, the region is obtained using the [DefaultAwsRegionProviderChain](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/providers/DefaultAwsRegionProviderChain.html). This means that the region is obtained following the rules of the default region provider chain. Please visit that link to read about all the ways to provide a region to the SDK. The region can also be set by setting the JDBC URL property `iamRegion`.

Since IAM Authentication tokens have a lifetime of about 15 minutes, and Smile CDR uses a connection pool, you should set the [Connection Max Lifetime](/content/docs/configuration_categories/database.html#property-connection-max-lifetime-millis/index.html) setting to something less than 15 minutes. This can be set manually by using the JDBC URL property `iamExpiration`.

# AWS Secrets Manager Authentication

The AWS Advanced JDBC Driver can be configured to pull authentication credentials from AWS Secrets Manager.

In versions before 2025.05.R01, the Secrets Manager setting had to be enabled, and the secret name had to be set as the `db.username` field. This setting is now deprecated, in favor of the preferred JDBC URL approach. The following is an example of such a configuration:

```properties
module.clustermgr.type                         =CLUSTER_MGR
module.clustermgr.config.db.driver             =POSTGRES_9_4
module.clustermgr.config.db.url                =jdbc:aws-wrapper:postgresql://my-rds-url.cv6u6ikc8x5f.us-east-1.rds.amazonaws.com:5432/cdr?wrapperPlugins=awsSecretsManager&secretsManagerSecretId=rds!my-cluster-d7d541ea-3bf2-1103-b50d-7a634fcea6ad&secretsManagerRegion=us-east-1
module.clustermgr.config.db.username           =
module.clustermgr.config.db.password           =
```

Copy

Let's analyze the JDBC URL: `jdbc:aws-wrapper:postgresql://my-rds-url.cv6u6ikc8x5f.us-east-1.rds.amazonaws.com:5432/cdr?wrapperPlugins=awsSecretsManager&secretsManagerSecretId=rds!my-cluster-d7d541ea-3bf2-1103-b50d-7a634fcea6ad&secretsManagerRegion=us-east-1`

- **jdbc:aws-wrapper:postgresql** – This indicates that the AWS Advanced JDBC Driver should be used, and that the underlying target driver should be for PostgreSQL.
- **my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr** – This is the connection URL of the RDS database, along with its port (5432), and the target database name (cdr)
- **wrapperPlugins=awsSecretsManager** – This enables the [AWS Secrets Manager Plugin](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) for the driver.
- **secretsManagerSecretId=rds!my-cluster-d7d541ea-3bf2-1103-b50d-7a634fcea6ad** – This is the ID of the secret which contains the RDS credentials.
- **secretsManagerRegion=us-east-1** – The selected region for the AWS Secrets Manager connection.

# Troubleshooting Connection Issues

When encountering issues with AWS RDS connectivity, it's helpful to enable detailed logging from the AWS Advanced JDBC Driver. This can be done by setting the `wrapperLoggerLevel` parameter in your JDBC URL. Official documentation for it can be found [here](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters), but the options are provided below for reference.

## Enabling Debug Logging

Add the `wrapperLoggerLevel` parameter to your JDBC URL with one of the following values (from least to most verbose):

- `OFF` \- No logging (default)
- `SEVERE` \- Only severe error messages
- `WARNING` \- Warning messages and severe errors
- `INFO` \- Basic information, warnings, and errors
- `CONFIG` \- Configuration information
- `FINE` \- Detailed debug information
- `FINER` \- More detailed debug information
- `FINEST` \- Most detailed trace information
- `ALL` \- All logging information (highest verbosity)

Example:

```properties
module.clustermgr.config.db.url=jdbc:aws-wrapper:postgresql://my-rds-url.us-east-1.rds.amazonaws.com:5432/cdr?wrapperPlugins=iam&wrapperLoggerLevel=FINE&user=rds-tester
```

Copy

## Common Issues and Solutions

1. **IAM Authentication Failures**
   - Verify the IAM user has the `rds-db:connect` permission for the specific database resource
   - Verify that the IAM user has a role on the remote database itself.
   - Check if the AWS region is correctly determined or explicitly set via `iamRegion`
   - Ensure the RDS instance has IAM authentication enabled
   - Verify credentials are available via the DefaultCredentialProviderChain
2. **Secrets Manager Issues**
   - Verify the secret exists in the specified region
   - Ensure the secret has the correct format (must contain username and password fields)
   - Check that your IAM role has `secretsmanager:GetSecretValue` permission
   - Verify the secret's resource policy allows access from your service
3. **Connection Pool Timeout Issues**
   - For IAM authentication, ensure your `db.connectionpool.maxlifetime.millis` setting is less than 15 minutes (900,000ms)
   - If using IAM authentication with a specific expiration, adjust your connection pool settings accordingly
4. **SSL/TLS Issues**
   - Ensure your RDS instance requires SSL if you're enforcing SSL connections
   - Add `ssl=true` to your JDBC URL if necessary
   - Verify your certificate trust store configuration if using custom certificates

# Choosing Between IAM and Secrets Manager Authentication

Both AWS IAM and AWS Secrets Manager provide secure methods for connecting to RDS databases, but they serve different use cases.

## When to Use IAM Authentication

IAM Authentication is generally preferred when:

- You want to leverage existing IAM roles and don't want to manage separate database credentials
- You need temporary, short-lived credentials for security purposes
- You want to centrally manage database access through IAM policies
- Your environment already uses IAM roles extensively (e.g., EC2 instances, ECS tasks)
- You prefer not to store any credentials in your configuration

## When to Use Secrets Manager Authentication

AWS Secrets Manager is generally preferred when:

- You need to manage multiple sets of credentials (different username/password combinations)
- You need to store additional connection information beyond just username/password
- You want automated credential rotation policies
- Your database is using complex authentication schemes beyond what IAM supports
- You're in a hybrid environment where not all services can use IAM roles

# Limitations

The limitations are the same as those defined by the [AWS Advanced JDBC Driver](https://github.com/aws/aws-advanced-jdbc-wrapper?tab=readme-ov-file#known-limitations).

[Setting Up SQL Server (MSSQL)](/content/docs/database_administration/setting_up_sql_server_mssql.html)

AWS RDS Authentication

Database Administration

[Database Design](/content/docs/database_administration/database_design.html)
[Database Connection Pool](/content/docs/database_administration/database_connection_pool.html)
[Setting Up PostgreSQL](/content/docs/database_administration/setting_up_postgresql.html)
[Troubleshooting PostgreSQL](/content/docs/database_administration/troubleshooting_postgresql.html)
[Setting Up MySQL](/content/docs/database_administration/setting_up_mysql.html)
[Setting Up MariaDB](/content/docs/database_administration/setting_up_mariadb.html)
[Setting Up Oracle](/content/docs/database_administration/setting_up_oracle.html)
[Setting Up SQL Server (MSSQL)](/content/docs/database_administration/setting_up_sql_server_mssql.html)
[AWS RDS Authentication](/content/docs/database_administration/rds_auth.html)
[Azure Entra Authentication](/content/docs/database_administration/entra_auth.html)

[Azure Entra Authentication](/content/docs/database_administration/entra_auth.html)