May 2, 2023

Running Postgres in Docker

Stephen Townshend

Developer Advocate (SRE)

So you want to spin up a Postgres database on your local machine, but you don't fancy having to install and manage everything manually? Running Postgres inside Docker is a great way to simplify the situation. It lets you:

Always run the latest version of Postgres without having to manage software updates
Keep your local machine clean by isolating Postgres within the Docker environment
Store data persistently using Docker persistent volumes

In this article I will explain how to do this step by step.

Before you begin

You will need Docker Desktop installed on your machine and have it running.

In order to test that your Postgres instance is working you will also need an IDE to connect to it and run queries. The de facto standard for Postgres IDEs is pgAdmin which is available for Windows or Mac (and many other platforms), but in the past I preferred HeidiSQL (only available on Windows).

Instructions

Firstly, from a terminal or PowerShell session, pull the latest Postgres container image to your local image repository:

docker pull postgres:latest

Next, let's create a persistent volume in Docker to store our databases, tables, and data. This will allow us to retain our data even when our container is shut down:

docker volume create postgres-volume

I've called my persistent volume "postgres-volume".

Lastly we can start our Postgres container using:

docker run --name my-postgres --env POSTGRES_PASSWORD=admin --volume postgres-volume:/var/lib/postgresql/data --publish 5432:5432 --detach postgres

Here's a breakdown of what the command is doing:

The --name command is used to give our container a name.
The --env command is passing in an environment variable called POSTGRES_PASSWORD which sets the password for the default Postgres user (the default user is called "postgres"). You could pass any other environment variables you like that the Postgres Docker image supports here.
The --volume command maps the Postgres data folder inside the container (where it stores everything) to the Docker persistent volume we just created.
The --publish command exposes the internal port 5432 (which is the Postgres default port) to port 5432 on your local machine. This is required in order for you to access Postgres.
The --deatch command tells Docker to run the container in detached mode, which lets you continue using your terminal or PowerShell session.

Testing it worked

I'm going to use pgAdmin below, but you can use any database IDE you like that supports Postgres.

When you start pgAdmin for the first time it will prompt you to create a master password and then register a server. If this is not your first time, right click on Servers and select Register > Server...

In the General tab give your connection a name:

In the Connection tab enter "localhost" as the Host name/address and then under Password enter the password you set when you created your Postgres container ("admin" in the example I provided):

Click Save and it will automatically connect to your Postgres instance. From here you can create and browse databases and tables (I created one called "Deleteme" in the screenshot below) or run queries to confirm that everything is working as expected:

Summary

Running apps using Docker is a great way to keep your local machine clean. It's easier to manage a container than all of the files potentially spread across your computer when you install it manually.

Remember that containers are ephemeral, they are frequently created and destroyed. Whenever an app requires persistent storage, make sure you configure it to use a persistent volume (in Docker) or the equivalent in Kubernetes would be a persistent volume claim (PVC).