How do I connect to an Amazon RDS database or Redis cluster using Systems Manager?

3 minute read

I want to connect to my Amazon Relational Database Service (Amazon RDS) database or Redis cluster from my local client.

Short description

You can connect to a private network with an AWS Systems Manager managed node using port forwarding to a remote host.



Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.

  1. Launch an EC2 instance in the same subnet as the RDS database or Redis cluster.

  2. Make sure that the EC2 instance is an SSM managed instance and its SSM agent ping status is Online. If you launched the instance in private subnet, create endpoints required for connectivity with Session Manager.

  3. Run the following AWS CLI command on your local machine to open a remote port forwarding session:

    macOS or Linux

    # aws ssm start-session \
     --target i-0822xxxxxxx4309b \
     --document-name AWS-StartPortForwardingSessionToRemoteHost \
     --parameters '{"host":[""],"portNumber":["3306"], "localPortNumber":["6379"]}'


    # aws ssm start-session ^
     --target i-0822xxxxxxx4309b ^
     --document-name AWS-StartPortForwardingSessionToRemoteHost ^
     --parameters host="",portNumber="3306",localPortNumber="6379"

    Note: Replace the following variables with your variables:

    • "i-0822xxxxxxx4309b" with your EC2 instance.
    • "" with your Amazon RDS or Redis cluster node endpoint.
    • "3306" with the remote host port number that you're connecting to.
    • "6379" with your client localhost port number.

    Example output macOS or Linux:

    Starting session with SessionId: XXXXX49c94e084f10c
    Port 6379 opened for sessionId XXXXX49c94e084f10c.
    Waiting for connections...
    Connection accepted for session [XXXXX49c94e084f10c]

    Example output Windows:

    alice@local-host ~ % redis-cli -c -h localhost -p 6379
    localhost:6379> set a "Hello"
    localhost:6379> get a
    localhost:6379> quit
    alice@local-host ~ %
  4. Press Ctrl-C to close the remote port forwarding session.

  5. Example macOS or Linux:

    ^CTerminate signal received, exiting.
    Exiting session with sessionId: XXXXX49c94e084f10c.
    alice@local-host ~ %

Related information

Use port forwarding in AWS Systems Manager Session Manager to connect to remote hosts

Starting a session (port forwarding to remote host)

Systems Manager announces support for port forwarding to remote hosts using Session Manager

How can I connect to a private Amazon RDS DB instance from a local machine using an Amazon EC2 instance as a bastion host?

AWS OFFICIALUpdated 9 months ago