Skip to content

Connect to a database from your computer

This guide shows you how to connect to a database via localhost on a specific port.

Otters doing telecommunication

Reference implementation

See how RDS bastion is configured in pirates-iac.

Things to consider

The database will be accessible by anyone who can log in to the AWS account.

If you choose to omit the optional step involving the setup of VPC endpoints, it's important to understand the implications. When you run the ok forward command, as outlined in this guide, it initiates an ECS task running Nginx. This setup allows the container to access your database. However, it also grants Nginx access to the entire internet, denoted by the CIDR block 0.0.0.0/0. You should consider the security implications of this, but as a general guideline, you should not run this in production.

Before you begin

  • You have followed the setup guide and have a working environment
  • You have a database in a private subnet
  • You have an ECS cluster in a private subnet

Step 1: Configure

  1. Add RDS bastion package to your environment

    repo-iac/environments/dev
    ok pkg add rds-bastion
    
  2. Update configuration

    repo-iac/environments/dev/_config/rds-bastion.yml
    StackName: "rds-bastion"
    UseVPCEndpoints: false
    
  3. Install and apply the package

    repo-iac/environments/dev
    ok pkg install rds-bastion
    cd rds-bastion
    terraform init
    terraform apply
    

Step 2: Enhance container security with VPC endpoints (optional)

To enhance the security of your container and prevent it from accessing the internet directly, you can utilize VPC endpoints.

Before you begin

Once you have the VPC endpoints set up and your container image in place, the next step is to enable VPC endpoint support in your Terraform configuration.

  1. Open _config/rds-bastion.tf.
  2. Modify the file by setting the UseVPCEndpoints variable to true.
  3. Apply the configuration
repo-iac/environments/dev
ok pkg install rds-bastion
cd rds-bastion
terraform init
terraform apply

Step 3: Connect to database

  1. Run the ok forward command to start the port forwarding session.

    ok forward
    
  2. You will be presented a list of Task Definitions which is applicable for port forwarding. Select the one you want to use using the arrow keys and press enter.

    > ssm-pf-my-bastion-task-definition
    > ssm-pf-another-bastion-task-definition
    

    Now a new ECS task will be started. This usually takes 20 to 30 seconds.

  3. Next you will be presented a list of all the RDS instances in your environment. Select the one you want to port forward to using the arrow keys and press enter.

    > my-team-db.c7d1xxxi7fm.eu-west-1.rds.amazonaws.com
    > some-other-db.c7d1xxxi7fm.eu-west-1.rds.amazonaws.com
    
  4. Last step is to enter the ports you want to forward to and expose locally for the forwarded database.

  5. Now the database is port forwarded and you can connect to it using the forwarded ports.

    LOCAL_PORT=4812 # or replace this with the port you entered in step 4
    psql --host=localhost --port=$LOCAL_PORT --username=db_username --password --dbname=postgres
    
  6. When you are done, press Ctrl+C to stop the port forwarding session.

If you don't stop the port forwarding session manually, it will be stopped automatically by the Lambda function after some time of inactivity.

builds/ directory

What is the builds directory?

terraform apply will create a directory called builds. This should be committed to your IaC repository. If not, future runs of terraform apply will always detect a change. Sometimes terraform plan/apply will report a change even though the code has not changed. This is due to the hash changing and it is normal expected behavior.