Connect to Amazon RDS for MySQL from your Mac

What you need

• The instance’s endpoint, port, and the master user name and password (or another MySQL user).
• A network path from your Mac. To connect from outside its VPC, AWS says the instance must be publicly accessible and its security group must allow you in. Otherwise, go through a host inside the VPC.
• The RDS certificate bundle, global-bundle.pem, to check the server’s certificate.

Find your connection details

1. Open the Amazon RDS console and choose Databases.
2. Choose the MySQL instance. On the Connectivity & security tab, copy the Endpoint and note the Port (3306 by default).
3. For the user name, open the Configuration tab and look at Master username (admin in AWS’s examples).

Or from the AWS CLI:

aws rds describe-db-instances \
  --filters "Name=engine,Values=mysql" \
  --query "*[].[DBInstanceIdentifier,Endpoint.Address,Endpoint.Port,MasterUsername]"

Network access. The instance’s VPC security group needs an inbound rule for its port from your address; the console’s My IP source fills in the address your browser has. For an instance that isn’t publicly accessible, AWS recommends a VPN or AWS Direct Connect, or else a bastion host: an EC2 instance in the same VPC that you tunnel through over SSH. An RDS Proxy can’t be made publicly accessible, so from a Mac you use the instance endpoint (or reach the proxy from inside the VPC).

Connection string

mysql://<user>:<password>@<instance>.<id>.<region>.rds.amazonaws.com:3306/<database>

The database part is optional. Percent-encode special characters in the password; see special characters in passwords and MySQL connection strings.

TLS

Every RDS for MySQL instance supports TLS, but it isn’t required unless you set the require_secure_transport parameter to ON in the instance’s DB parameter group (it’s OFF by default, and the change needs no reboot). With it on, an unencrypted client gets:

MySQL Error 3159 (HY000): Connections using insecure transport are prohibited while --require_secure_transport=ON.

The server certificate comes from an Amazon RDS certificate authority, which macOS doesn’t trust by default. Download the bundle that covers every commercial Region:

curl -O https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

Use it with full verification, which also checks the endpoint name against the certificate (--ssl-mode=VERIFY_IDENTITY in the MySQL client).

Connect with Inlet

1. Choose New Connection, pick MySQL, and enter the endpoint, port, user and password. Or paste a mysql:// URL and Inlet fills in the form.
2. Under TLS, choose verify-full and select global-bundle.pem as the CA file. That checks both the certificate and the endpoint name.
3. For a private instance, turn on the SSH tunnel and give the bastion host. Inlet uses the system ssh, so your ~/.ssh/config, the SSH agent and the 1Password SSH agent work. Keep the instance endpoint as the database host.
4. Keep the password in the Keychain, or have Inlet ask each time.
5. Tag the environment. A production connection opens read-only: the server refuses writes until you unlock it for ten minutes.

Connect from the command line

AWS’s example with full verification (MySQL 5.7 client or later):

mysql -h <instance>.<id>.<region>.rds.amazonaws.com --ssl-ca=global-bundle.pem --ssl-mode=VERIFY_IDENTITY -P 3306 -u <user> -p

The MariaDB client takes --ssl-ca=global-bundle.pem --ssl instead of --ssl-mode. Check which one you have with mysql --version. Homebrew’s mysql-client package has the MySQL client; it’s keg-only, so run /opt/homebrew/opt/mysql-client/bin/mysql.

IAM database authentication. The password is a token valid for 15 minutes, sent as clear text, so TLS is required:

RDSHOST="<instance>.<id>.<region>.rds.amazonaws.com"
TOKEN="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 3306 --region <region> --username <user>)"
mysql --host=$RDSHOST --port=3306 --ssl-ca=global-bundle.pem --enable-cleartext-plugin --user=<user> --password=$TOKEN

The MariaDB client doesn’t need --enable-cleartext-plugin. The token only matters while signing in; an open session continues after it expires.

Troubleshooting

• ERROR 2003: Can’t connect to MySQL server or a timeout: check the endpoint and port, that Publicly accessible is Yes, and that the security group allows your current IP. Some company firewalls block the database port.
• ERROR 1045: Access denied: wrong user or password, or a user that isn’t allowed from your address. With IAM, the token may be stale or made for a different host, port or user.
• Error 3159, insecure transport prohibited: require_secure_transport is on. Turn on TLS.
• Certificate verify failed: you connected by IP address or your own DNS name. Use the endpoint, and the bundle from AWS (only register the root CAs; AWS warns that adding intermediate certificates can break connections when RDS rotates server certificates).