Skip to main content
Set up the AWS side first, or Test Connection fails against a user the database never created for IAM.

​
On the AWS side

Enable IAM database authentication on the RDS instance or Aurora cluster. MySQL, MariaDB, and PostgreSQL all support it. Then create the database user:
A user is either password-authenticated or IAM-authenticated, never both. Connecting as a user that still has only a password fails.

​
Setting up

In the connection form, set Authentication to one of the AWS IAM options. The Password field gives way to the AWS fields, and Username takes the IAM database user.
Connection form with Authentication set to AWS IAM (Profile)

AWS IAM options in the connection form

Pick AWS IAM (Profile) if you already use the AWS CLI here: it reads the same files the same way. AWS Region is read from the endpoint when the hostname looks like mydb.abc123.us-east-1.rds.amazonaws.com. Fill it in for a CNAME or any other custom endpoint, or to override what was detected.

​
Token lifetime

Each connect signs a fresh token, valid for 15 minutes and never written to disk; automatic reconnects sign another. Nothing to paste, rotate, or refresh. IAM also requires encryption in transit, so an SSL mode of Disabled or Preferred is raised to Required for the connect.

​
Profiles

Profile Name lists the profiles found in ~/.aws/config and ~/.aws/credentials and accepts a typed name. Blank means default. Profiles resolve the way the AWS CLI resolves them:
  • Static aws_access_key_id / aws_secret_access_key pairs.
  • credential_process commands, so a profile can be backed by SSO, 1Password, or any other credential helper.
  • role_arn assume-role profiles, resolved through STS. Base credentials come from source_profile, chaining up to five deep, or from credential_source = Environment. mfa_serial is not supported.
For AWS IAM (SSO), run aws sso login --profile <name> first. A connect that fails on an expired session offers the browser sign-in.

​
Tunnels and port forwards

RDS checks the token against its own hostname and port, so the endpoint it was signed for is what matters, not the address dialed. A tunnel the app opens needs nothing extra: the token is signed for the Host and Port in the form, not the loopback address the driver gets. A forward you run yourself leaves 127.0.0.1 in the form, which names no database. Set RDS Endpoint to the real one:
The port is optional, falling back to 5432 for PostgreSQL and 3306 for MySQL and MariaDB. The field also covers a CNAME or any alias AWS did not issue, and is honored only when Host is loopback or already the same hostname.

​
Troubleshooting

​
Could not determine an AWS region for ”…”

The hostname is not a standard RDS endpoint. Fill in AWS Region.

​
TablePro cannot sign an RDS token for ”…”

The connection points at a port forward the app did not open. Fill in RDS Endpoint with the endpoint from the AWS console.

​
PAM authentication failed

PostgreSQL reports this and MySQL reports Access denied when the token was signed for the wrong endpoint. Check RDS Endpoint against the console, including the port.

​
Profile ”…” was not found

The profile has no static keys, no credential_process, and no role_arn. Check the name and the contents of ~/.aws/config and ~/.aws/credentials.

​
AWS SSO Sign-In Required

The cached SSO session expired. Accept the prompt, or run aws sso login --profile <name>.

​
Other AWS services

The same Authentication options reach Amazon ElastiCache (Redis) and Amazon Keyspaces (Cassandra), each with fields of its own on those pages.