Skip to content

Connect to a Private AWS RDS Database

Forward a private Amazon RDS or Aurora endpoint to a local port through an EC2 instance managed by AWS Systems Manager (SSM). Your database client connects to your Mac; the managed instance reaches the private database inside AWS.

Connection Path

Database client on your Mac → localhost:LOCAL_PORT
                            → AWS Session Manager
                            → SSM-managed EC2 instance
                            → private RDS endpoint

The RDS database stays private. The EC2 instance must be able to resolve and reach the RDS endpoint on its database port. Your AWS profile controls the Session Manager session; database credentials are still entered in your database client.

Requirements

  • AWS CLI v2 and the Session Manager plugin on your Mac.
  • An AWS profile with the required Session Manager permissions.
  • An SSM-managed EC2 instance in a network that can reach the RDS database.
  • An RDS security group rule that allows the database port from the EC2 instance's security group.
  • The RDS endpoint, database port, and database credentials.

See AWS configuration for the administrator checklist.

Create the Tunnel

  1. Copy the RDS endpoint and port from the AWS console.
  2. In StormTunnel, click +, enter a Tunnel Name, and set Connection Type to AWS Session Manager.
  3. Under AWS Session Manager, choose your AWS Profile and the AWS Region containing the EC2 instance.
  4. Under Destination, enter the Instance ID of the SSM-managed instance. Set Database or Service Host to the RDS endpoint and Remote Port to the RDS port.
  5. Under Check Access, click Validate. See Check access.
  6. Under Port Forwarding, choose an unused Local Port. Using the RDS port is convenient when it is free.
  7. Click Save, select the tunnel, then choose Tunnel → Toggle Selected Tunnel or press Cmd+Enter to start it. You can also start it from the menu bar. See Managing tunnels.

The instance ID is the managed machine Session Manager connects to. The database host is where that machine forwards traffic. These are different values. The Local Port is on your Mac and can differ from the RDS port if the default port is already in use.

PostgreSQL Example

Field Value
AWS Profile production
AWS Region us-east-1
Instance ID i-0123456789abcdef0
Database or Service Host mydb.example.us-east-1.rds.amazonaws.com
Remote Port 5432
Local Port 5432

Start the tunnel, then connect your client to 127.0.0.1:5432 using your database credentials. For example:

psql -h 127.0.0.1 -p 5432 -U your_user -d your_database

For MySQL or MariaDB, the default port is usually 3306. Aurora endpoints use the port configured for the cluster.

Check Access

The Check Access section helps diagnose AWS access before you connect:

  • Validate checks your credentials and verifies the managed instance's status when AWS permissions allow. It does not start a port-forwarding session or test the connection from the instance to RDS.
  • Test Permissions checks read-only discovery permissions and lists each as Granted, Missing, or Unverified. ssm:StartSession and ssm:TerminateSession are Unverified because checking them would require starting or ending a real session. Starting the tunnel exercises ssm:StartSession; connecting your database client to the local port checks whether the destination is reachable and your database credentials work. Copy IAM Policy copies a starting policy to the clipboard.

Both checks resolve credentials through AWS CLI v2, as starting a tunnel does, so IAM Identity Center profiles work. If credentials are expired, MFA is required, or the CLI is missing, StormTunnel reports that before a connection attempt. See IAM permissions for the user policy, instance role, and network requirements.

Multiple Databases

Create a separate tunnel for each database. Assign a different local port to each active tunnel; the remote port can stay the same as the database port.

Database Local port Remote port
Production MySQL 3306 3306
Staging MySQL 3307 3306
Analytics PostgreSQL 5432 5432

Security

  • Keep RDS in private subnets and restrict its security group to the required sources.
  • Limit the EC2 instance's network access to the destinations and ports it needs.
  • Scope Session Manager permissions to the required instances and port-forwarding documents.
  • Disconnect the tunnel when you finish.

Troubleshooting

  • Credential or sign-in error: Sign in again for SSO profiles, or refresh temporary credentials. Confirm aws sts get-caller-identity --profile PROFILE works in Terminal.
  • Access denied: Use Test Permissions, then ask your AWS administrator to verify that your user or role can start a session with the required port-forwarding document and end its own sessions. The start permission is not verified by the read-only check.
  • Instance unavailable: Confirm that the EC2 instance is online in Systems Manager.
  • Connection refused or timeout: Check DNS, routes, network ACLs, and both security groups between the EC2 instance and RDS.
  • Local connection fails: Confirm the tunnel is connected and the database client uses the local port you selected.

See Troubleshooting.