Amazon Aurora and RDS

DataKlin connects to Amazon Aurora and Amazon RDS through its PostgreSQL and MySQL connectors, with AWS IAM authentication over verified TLS. Where its AWS credentials come from is covered in AWS credentials.

Create the connection

The New Connection dialog lists four entries for them, each under its database:

• Amazon Aurora PostgreSQL and Amazon RDS for PostgreSQL
• Amazon Aurora MySQL and Amazon RDS for MySQL

Each opens the PostgreSQL or MySQL connection form already set up for AWS:

• TLS mode Full verification, with the Amazon RDS CA bundle (built-in) as the CA certificate
• authentication AWS IAM, with credentials from an AWS profile
• a 45-second connect timeout, which gives an Aurora Serverless v2 cluster time to resume

Then:

1. On the General tab, enter the endpoint as the Host, the Port, the Database and the database User. There is no password field while AWS IAM is selected.
2. On the Security tab, choose the Credential source and the AWS profile. DataKlin fills in the AWS region from the endpoint’s host name. Click Test AWS credentials to check them: it shows the AWS account and the identity’s ARN.
3. Click Test connection. For Aurora it shows the Aurora version and whether the instance is the writer or a reader.
4. Click Save.

The saved connection is an ordinary PostgreSQL or MySQL connection. You can switch it to password authentication on the Security tab, and switch an existing PostgreSQL or MySQL connection to AWS IAM without creating it again.

AWS IAM authentication

DataKlin signs a fresh IAM database token for every new connection it opens to the server, including the extra connection MySQL needs to cancel a query. A token lasts 15 minutes, so this keeps long sessions and cancels working.

• AWS IAM needs verified TLS, Verify CA or Full verification, except to your own computer. DataKlin refuses it with TLS disabled.
• On MySQL, the token is sent with the cleartext password plugin, which DataKlin turns on only for AWS IAM and only over verified TLS.
• The database user must be set up for IAM authentication: on PostgreSQL, granted the rds_iam role; on MySQL, created with AWSAuthenticationPlugin. The IAM identity needs rds-db:connect permission for that user, and IAM database authentication must be turned on for the cluster or instance. When the server refuses a token, DataKlin lists these causes.

The Amazon RDS CA bundle

DataKlin includes the Amazon RDS CA bundle, so Full verification works without downloading a certificate. You can still choose a CA file instead on the Security tab, for example for AWS GovCloud. See TLS and certificates.

AWS Secrets Manager

Instead of AWS IAM, you can read the database user name and password from a secret, such as the master user secret that RDS manages for you:

1. On the Security tab, choose the authentication method AWS Secrets Manager.
2. Enter the Secret ARN, and the credential source and region as for AWS IAM.

The secret must be JSON with username and password. DataKlin reads it each time it connects, so a rotated password is picked up at the next connection. Like AWS IAM, it needs verified TLS except to your own computer.

Endpoints

DataKlin recognises Aurora and RDS cluster, reader, custom and instance endpoints from the host name.

• While a console is active, the status bar shows Aurora writer, Aurora reader or RDS.
• On a reader endpoint, DataKlin asks “Reader endpoint: open this connection read-only?”. Choose Open read-only to make it a read-only connection. It’s only a suggestion, because a reader endpoint of a cluster with no replicas points at the writer.
• If a connection to a writer endpoint fails because the database is read-only, DataKlin says the instance may have become a reader after a failover, and to reconnect.
• If a connection to an RDS host times out, DataKlin says an Aurora Serverless v2 cluster may be resuming, and to retry.

Through SSM port forwarding

When you reach the endpoint through a port forwarded to your computer, for example with AWS Systems Manager:

1. Enter localhost and the forwarded port as the Host and Port.
2. On the Security tab, enter the real endpoint as the Signing host, and its port as the Signing port. They are required for a host on your computer, because the IAM token must be signed for the real endpoint.
3. Also enter the real endpoint as the Server name in the Security tab’s encryption settings. In this release DataKlin doesn’t set it for you, and without it Full verification fails, because DataKlin checks the certificate against localhost.

Known issues

• The AWS features were tested against local stand-ins, not real AWS. Checks on real Aurora clusters are still to be done.
• With AWS Secrets Manager, a PostgreSQL connection keeps the first user name it read from the secret, so a rotation that switches between two users fails until you reconnect. MySQL isn’t affected.
• DataKlin can’t list your clusters and endpoints: enter the endpoint yourself.