Skip to content

Get Started with a Private AWS RDS Tunnel

Use StormTunnel to make a private RDS database available to a database client on your Mac. StormTunnel creates a local port and forwards its traffic through an EC2 instance managed by AWS Systems Manager (SSM). The database stays private; your client connects to 127.0.0.1 while the tunnel is running.

StormTunnel requires macOS 15 or later. For administrator setup, see Configure AWS for StormTunnel.

Before You Start

Ask your AWS administrator for:

  • The AWS profile to use and the AWS Region where the managed EC2 instance runs.
  • The instance ID of an EC2 instance that is online in Systems Manager.
  • The RDS endpoint and database port.
  • Confirmation that your AWS identity can start the required port-forwarding session and end its own sessions.
  • Confirmation that the EC2 instance can reach the RDS endpoint and port.

On your Mac, install AWS CLI v2 and the Session Manager plugin. In StormTunnel, open Settings > AWS and click Verify AWS Setup… to confirm the app can find them. See Prepare the Mac for installation links and details.

If your organization uses IAM Identity Center (SSO), configure an AWS profile first. Sign in with aws sso login --profile PROFILE in Terminal, or use in-app SSO with a Premium license. AWS profile sign-in is separate from the database username and password you use in your client.

Create and Start the Tunnel

  1. Open StormTunnel and click + in the toolbar (or press Cmd+N).
  2. 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 where the managed instance runs.
  4. Under Destination, enter the Instance ID of the SSM-managed EC2 instance, the Database or Service Host (the RDS endpoint), and the Remote Port (the database port). The instance is the SSM hop; the database host is the destination it reaches.
  5. Under Check Access, click Validate. This checks your credentials and verifies the instance status when AWS permissions allow. It does not open the port forward or test the database network path. Test Permissions checks read-only discovery permissions; ssm:StartSession and ssm:TerminateSession remain Unverified in that check. Starting the tunnel exercises session start; connecting your database client checks the route and database login. See AWS IAM permissions.
  6. Under Port Forwarding, choose a free Local Port on your Mac. It can match the database port if that port is available; otherwise choose another one, such as 5433.
  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.

For field-by-field examples and multiple database tunnels, see Connect to a private AWS RDS database.

Connect Your Database Client

With the tunnel running, set your database client’s host to 127.0.0.1 and its port to the Local Port you chose. Use your normal database username and password. Keep the tunnel running while you use the database.

For example, if you chose local port 5432 for PostgreSQL:

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

When you are finished, stop the tunnel from the tunnel list or the menu bar. The local endpoint is available only while the tunnel is running.

If It Does Not Connect

  • Profile or sign-in error: Confirm the selected profile. For SSO, sign in again. The profile must work with AWS CLI v2 on your Mac.
  • AWS tools missing: Install AWS CLI v2 and the Session Manager plugin, then use Verify AWS Setup… in Settings > AWS.
  • Access denied: Ask your AWS administrator to check ssm:StartSession, access to the required session document, and ssm:TerminateSession. The read-only checks can pass while starting the actual session is still denied.
  • Instance unavailable: Confirm the instance is online in Systems Manager and that the selected Region is correct.
  • Connection refused or timed out: Check that the EC2 instance can resolve and reach the RDS endpoint and port, and that the RDS security group allows traffic from the EC2 instance's security group.
  • Local port in use: Choose another local port.

See AWS troubleshooting or contact support.