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.

Import from AWS

Choose File > Import > Import from AWS… and the endpoints come from the AWS API instead of the console. The profile needs rds:DescribeDBInstances and rds:DescribeDBClusters, both in the AmazonRDSReadOnlyAccess policy.
Import from AWS sheet, profile acme-prod, us-east-1 checked, Authentication set to AWS IAMImport from AWS sheet, profile acme-prod, us-east-1 checked, Authentication set to AWS IAM

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.
A row matching a saved connection on host and port is marked duplicate and starts deselected. Select it to add it as a copy. Username stays empty, because the IAM database user is rarely the master user. Imported connections carry the region and the profile, and take IAM authentication on every database that has it enabled. The rest ask for a password on the first connect. A region that answers with an error keeps its own line and leaves the others running. Engines with no TablePro driver, and databases with no endpoint yet, are named at the top of the list and skipped.

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)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 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_arn assume-role profiles, resolved through STS. Base credentials come from source_profile, chaining up to five deep and resolving that profile by its own kind, or from credential_source = Environment. mfa_serial is not supported.
  • IAM Identity Center profiles, through sso_session or the older inline sso_start_url, using the token cache in ~/.aws/sso/cache.
  • Static aws_access_key_id / aws_secret_access_key pairs.
  • credential_process commands, 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 as reader.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 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 tunnel to a CNAME. On a direct connection it is honored only when it names the endpoint the connection reaches.

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 reports Access 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: no role_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 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.