From Cloud to Container: Migrating a PostgreSQL Database from AWS RDS to Local Docker

Migrate everything from cloud to container in 10 minutes!

Introduction:

In today’s world, cloud databases like Amazon RDS make scaling and managing relational databases easier than ever. But there are times when running your own local copy of a database in a containerised environment, like Docker, can provide benefits like lower costs, more control, and faster local development. If you're looking to migrate your PostgreSQL database from AWS RDS to your own local Docker container, read on.

Why Migrate to Docker?

Before we dive into the technical details, let’s quickly cover some of the benefits of migrating a PostgreSQL database from AWS RDS to Docker:

1. Local Development & Testing: Having a local database gives you the flexibility to quickly spin up and tear down environments without worrying about cloud costs or internet connectivity.

2. Cost Savings: Running a local database in Docker is far less expensive than running an RDS instance, especially for small-scale development and testing.

3. Faster Iterations: No more waiting for data migration or network latency when running locally.

4. Control: You have full control over the PostgreSQL instance, allowing you to adjust settings and configurations more freely.

With those reasons in mind, let’s walk through the migration process!

TL;DR

This guide shows how to migrate a PostgreSQL database from AWS RDS to a local Docker container. It covers backing up your RDS database, setting up a Docker container with PostgreSQL, restoring the backup, and testing the migration locally. This migration offers benefits like cost savings, faster development, and more control over your database environment.

Step 1: Backup Your RDS Database

Before you do anything, you need to create a backup of your AWS RDS PostgreSQL database. We’ll use pg_dump to generate a snapshot of your current database.

# Backing up your PostgreSQL RDS database using pg_dump :

pg_dump -h your_rds_endpoint.amazonaws.com -p 5432 -U your_user -Fc your_db -f db_dump.dump

exit

Replace your_rds_endpoint, your_user, your-db, and with your actual database details.

This will create a dump file that contains all your data, including schema and table information. Make sure to store this backup file securely.

---

Step 2: Spin Up the Docker Container

Next, we need to set up PostgreSQL in a Docker container on your local machine.

docker run --name your_original_dbname_from_server -e POSTGRES_PASSWORD=your_original_passowrd -d postgres:12-alpine

You can replace `postgres:12-alpine` with the postgres version you used in your RDS database.

This will download the necessary Docker image and start your PostgreSQL container. You can check if the container is running by executing:

docker ps -a 

Step 3: Restore the Database from Backup

Now we create the appropriate user, an empty database with the same name so that we can do the db restoration easily. Follow below steps for the same:

# Enter into your container
docker exec -it postgres bash

# Login as postgres user
su postgres

# Create your original RDS user
createuser original_user_from_server

# Create your database
createdb your_db

# Start psql
psql

# Give your original user the same password
alter user your_original_user with encrypted password 'your_original_password';

# granting all access to the original database to this user
grant all privileges on database your_db to your_original_user;

exit

Step 4: The Magic lines

With the PostgreSQL container up and running, the next step is to restore your database from the backup file you created earlier.

To restore the dump file into your local PostgreSQL container, run:

# Copy the local dump file to the container
docker cp local_dump.dump your_container:/local_dump.dump

# Enter into the container
docker exec -it container_id bash

# Restore the dump
pg_restore -d your_db local_dump.dump

Step 5: Verify the Migration

Once the restore process completes, it’s time to verify that the migration was successful. You can connect to the local PostgreSQL instance using the psql command-line tool or any PostgreSQL GUI (e.g., DBeaver or pgAdmin).

# Enter into the container
docker exec -it container_id bash

# login as postgres user
su postgres

psql

#switch to your db
\c your_db

#checkout the tables and see if things are appropriately matching
\dt
SELECT * FROM any_table_listed_in_\dt;

Check that the tables, data, and schemas are all in place. If everything looks good, congratulations—you’ve successfully migrated your database from AWS RDS to a local Docker container!

Step 6: Test Your Application Locally

Now that your database is running locally in Docker, it's time to update your application's database connection settings to point to the new local PostgreSQL instance.

• Change the database host in your application's configuration to localhost.

Once the app is connected to the local database, perform some tests to ensure everything is functioning as expected.

---

Step 7: Clean Up

If you’re done with your migration and no longer need the RDS instance, be sure to delete it to avoid unnecessary costs. You can do this via the AWS Management Console or AWS CLI.

---

Conclusion

Migrating from AWS RDS to a local Docker PostgreSQL instance is a straightforward process that can provide significant benefits for development and testing environments. Docker containers make it easy to replicate cloud setups locally, ensuring that your development environment mirrors production. Whether you're looking to reduce costs, speed up local development, or simply have more control, this migration is a win-win.

---

Final Thoughts

While this guide focuses on PostgreSQL, the process for migrating other types of databases to Docker is similar. With Docker's power and flexibility, you can easily replicate most production database environments on your local machine, giving you an efficient and cost-effective solution for your development needs.

Happy coding, and welcome to your new local PostgreSQL environment!