RDS through AWS SSM

  • Desktop app
  • All plans
View as MarkdownFeature page

What it does

Reach an Amazon RDS database (or any service in a private subnet) that has no public endpoint, no inbound SSH and a locked security group, from your own machine, without a bastion or a VPN. AgentsRoom saves a connection whose transport is AWS SSM (a managed EC2 instance, an AWS profile, a region) and uses it as the Reach through hop of a database connection. When you open the database, the app starts an AWS Session Manager port-forwarding session through that instance to the RDS endpoint, binds it to a loopback port picked by the OS, and connects its database client through it. The same SSM connection also opens a plain terminal session on the instance.

Where to find it

  • Inside a project, terminal bar > Servers (or the dock's Servers, "Saved SSH and AWS SSM connections") > New connection > Transport: AWS SSM.
  • Then Databases > New connection > Reach through: pick that SSM connection.

How to use it

  1. Prerequisites on your machine: the aws CLI and the session-manager-plugin, plus a working AWS profile or SSO login. In AWS: a managed node running the SSM Agent, an IAM policy allowing ssm:StartSession, and a security group letting that node reach the database port.
  2. Servers > New connection: name, Transport = AWS SSM, Instance ID (i-0123456789abcdef0), AWS profile, Region, optional Remote shell (Server default, PowerShell, PowerShell 7) for the terminal session. No password and no key are stored: authorization comes from your local AWS profile. Test connection reports "Instance found and reporting to Session Manager", "its SSM agent is not reporting", "No instance with this id for this profile and region" or "The aws CLI was not found on this machine".
  3. Databases > New connection: the RDS endpoint as Host, the database port, user, password, and the SSM connection in Reach through. Keep Read-only connection on unless you need to write; tick This is production when it is.
  4. Open the database. The tunnel is declared ready only once the local port really accepts a connection; otherwise you get the error the CLI printed (expired SSO, wrong profile or region, missing plugin).
  5. Click Connect on the SSM connection itself to get a terminal on the instance, which is also how you run an agent CLI on a machine with no inbound SSH.

Settings

None specific. The client tool folders of Database Connections apply to exports through the tunnel.

Agent tools (MCP)

  • ssh_list, ssh_exec, ssh_transfer, ssh_connect, ssh_connection_new: an SSM connection is listed and used like any saved server; the agent never receives the AWS profile.
  • db_list, db_schema, db_query, db_connection_new: query the database through the tunnel, read-only; the agent gets a result set, never the password or the endpoint credentials.

Providers

All providers, no difference.

Mobile

Partly. The phone lists the SSM connection and can open its terminal session (the session is started on the desktop and streamed to the phone), and the Databases sheet queries through the tunnel read-only. No connection form on the phone, and AWS credentials are never sent to it.

Limits

  • Engines: MySQL / MariaDB, PostgreSQL and MongoDB, so RDS for MySQL, MariaDB and PostgreSQL, the compatible Aurora editions, and Amazon DocumentDB. SQL Server and Oracle on RDS are not supported.
  • The desktop must be running for the phone to use the tunnel.
  • The forwarded port is bound to 127.0.0.1 only and closed with the connection.
  • Describe-instance checks in Test connection are read-only and not billed; the session itself is billed by AWS as usual.

Common questions

  • Which SSM document is used? AWS-StartPortForwardingSessionToRemoteHost, with the database endpoint as host, its port, and the reserved local port. Forwarding to the instance itself is the same document with host=localhost.
  • Do I still need a bastion? No. The managed node needs no public IP and no inbound SSH; your machine joins the session from outside.
  • Does AgentsRoom store an AWS key? No: instance ID, profile name and region only, synced with your account so your other computers use the same profile. The database password lives in the vault, encrypted through the OS keychain, and is asked once on each computer.
  • Can an agent query through the tunnel? Yes, read-only, by naming the saved connection.
  • It hangs or fails immediately. Check that aws ssm start-session works in your own terminal; the app shows the CLI's error rather than an invisible prompt.

Related