9.8.1Support 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.

9.8.1.1AWS Advanced JDBC Driver

As of 2025.05.R01, Smile CDR now supports usage of the AWS Advanced JDBC Driver. 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.

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

9.8.2Username 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.

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           =

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.

9.8.3IAM 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:

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           =

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 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 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. 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 setting to something less than 15 minutes. This can be set manually by using the JDBC URL property iamExpiration.

9.8.4AWS 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:

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           =

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 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.

9.8.5Troubleshooting 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, but the options are provided below for reference.

9.8.5.1Enabling 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:

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

9.8.5.2Common 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 connection-max-lifetime-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

9.8.6Choosing 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.

9.8.6.1When 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

9.8.6.2When 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

9.8.7Limitations

The limitations are the same as those defined by the AWS Advanced JDBC Driver.