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:- MySQL / MariaDB
- PostgreSQL
Import from AWS
Choose File > Import > Import from AWS… and the endpoints come from the AWS API instead of the console. The profile needsrds:DescribeDBInstances and rds:DescribeDBClusters, both in the AmazonRDSReadOnlyAccess policy.


Regions are searched in parallel, four at a time
1
Pick a profile
The list holds the profiles in
~/.aws/config and ~/.aws/credentials, and the line under it names how that one signs in. An expired IAM Identity Center session offers Sign In here.2
Pick regions
AWS has no default region, so Continue stays dimmed until at least one is selected. The profile’s own
region starts selected.3
Review and import
Every instance and cluster arrives as a row with its endpoint, port, and engine. A cluster brings its writer endpoint, and its reader endpoint as a second row that starts deselected.
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.

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 RDS endpoint, including one a CNAME leads to, since a token scoped to any other region is refused. The field applies only to an endpoint that names no region, such as a global database endpoint.
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. A profile resolves by what it declares, the way the AWS CLI resolves it, so AWS IAM (Profile) and AWS IAM (SSO) reach the same profiles:
role_arnassume-role profiles, resolved through STS. Base credentials come fromsource_profile, chaining up to five deep and resolving that profile by its own kind, or fromcredential_source = Environment.mfa_serialis not supported.- IAM Identity Center profiles, through
sso_sessionor the older inlinesso_start_url, using the token cache in~/.aws/sso/cache. - Static
aws_access_key_id/aws_secret_access_keypairs. credential_processcommands, so a profile can be backed by 1Password or any other credential helper.
web_identity_token_file is not supported and says so rather than reporting the profile incomplete.
A token from IAM Identity Center renews itself with its refresh token in its last 15 minutes, as the AWS CLI does, and the renewed token goes back into ~/.aws/sso/cache. A connect that fails because the session itself ended offers the browser sign-in; aws sso login --profile <name> does the same from the shell.
Custom hostnames
RDS accepts a token only for the endpoint AWS issued. When Host is a name of your own, such asreader.db.example.com, set up as a CNAME, each connect and reconnect follows the CNAME to the first RDS endpoint it reaches: an instance, a cluster or reader endpoint, or an RDS Proxy. The connection signs in as that endpoint and dials it directly, so the token never goes to a host it was not signed for, and SSL Verify Identity checks the endpoint’s own certificate.
Point the CNAME at another replica and the next connect or reconnect follows it. Host stays as you saved it.
This covers a direct connection. Behind a tunnel the SSH server or proxy resolves the name, so set RDS Endpoint as described below.
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 leaves127.0.0.1 in the form, which names no database. Set RDS Endpoint to the real one:
Redshift
Redshift hands out its own user and temporary password rather than a signed token. The same three options appear on a Redshift connection, and Redshift covers what each endpoint calls.On iPhone and iPad
Synced connections keep their AWS IAM option. AWS IAM (Profile) needs an access key saved on the device, and AWS IAM (SSO) signs in to IAM Identity Center from the device itself. IAM sign-in covers the setup.Troubleshooting
Could not determine an AWS region for ”…”
Host is neither an RDS endpoint nor, as far as this Mac’s DNS can tell, a CNAME for one. Set Host to the endpoint from the AWS console, or fill in AWS Region for a global database endpoint.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.TablePro could not look up ”…” in DNS
The CNAME lookup failed or ran out of time, so the connect stops rather than sign a token RDS would refuse. Check the network and connect again.The RDS Endpoint ”…” is not the database at ”…”
RDS Endpoint names another database than the one the connection reaches. Clear it on a direct connection: it is for a port forward or a tunnel.PAM authentication failed
PostgreSQL reports this and MySQL reportsAccess denied when the token was signed for the wrong endpoint. Check RDS Endpoint against the console, including the port, and that a custom Host is a CNAME for the endpoint rather than an address record.
Profile ”…” was not found
The profile declares no credentials at all: norole_arn, no sso_session or sso_start_url, no static keys, and no credential_process. 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 runaws sso login --profile <name>.

