This tutorial will guide you through how to run PostgreSQL with persistent storage inside a Docker container and connect to it.
PostgreSQL is an open-source, object-relational database management system. It has been around for over 30 years and advertises itself as “the most advanced open-source relational database in the world.”
Docker has become a standard in the IT industry for packaging, deploying, and running distributed applications with ease. Docker containers let you quickly spin up new applications without cluttering your system with dependencies.
You can use Docker to run a PostgreSQL database in a container as a remote server. Docker containers are based on open standards, enabling containers to run on all major Linux distributions, macOS and Microsoft Windows.
Run PostgreSQL in Docker
We will do here to download the PostgreSQL image, check that the image is ready, run the image with specific parameters, and finally connect to the running PostgreSQL instance.
1. Pull a PostgreSQL Server Docker Image
First, we need to get an existing PostgreSQL official image from the Docker Hub. Images are available for PostgreSQL versions 9, 10, 11, 12, and 13. Change the
latest tag to the required version if you need a specific release.
Now let’s pull the image:
sudo docker pull postgres:latest
Using the above command will pull the latest available version of PostgreSQL from the Docker Hub repository.
2. Run a Container from the PostgreSQL Server Docker Image
Before deploying, you’ll need to set up a Docker volume or bind mount to persist your database. Otherwise, your data will be lost when the container restarts. The mount should be made to
/var/lib/postgresql/data directory within the container.
We will create a docker volume for this guide and attach it to your PostgreSQL container.
The following command will create the volume in your local machine, which you can connect with PostgreSQL container later:
sudo docker volume create postgres-volume
Now that you have a PostgreSQL image on your machine and a volume to persist the data, you can deploy a container with:
sudo docker run -d --name=postgres13 -p 5432:5432 -v postgres-volume:/var/lib/postgresql/data -e POSTGRES_PASSWORD=[your_password] postgres
The docker run command will create a running PostgreSQL database within a Docker container.
Let’s break down this syntax. First, here is what each parameter in that command means:
-dwill run this container in a detached mode to run it in the background.
--nameassigns the name
postgres13to your container instance.
-pwill bind the PostgreSQL container port 5432 to the same port on your host machine. You’ll be able to connect to
localhost:5432using PostgreSQL clients (
psql) running on your host.
-voption bind that data folder inside the container volume (
/var/lib/postgresql) to the local Docker volume (
postgres-volume) you created in the previous step.
-esets an environment variable. In this case, the PostgreSQL root password.
postgresis the name of the image we use to create the container.
You can check whether the container is running by listing the running containers:
sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 6cb3293fe725 postgres "docker-entrypoint.s…" 19 minutes ago Up 19 minutes 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp postgres13
Congratulations! Your new PostgreSQL instance is now running on Docker.
Moreover, you can check the log file of the running PostgreSQL container with the following command:
sudo docker logs postgres13
3. Connect to the PostgreSQL Server
You can gain an interactive PostgreSQL shell by attaching it to the container and running the
psql command. This provides the full PostgreSQL command-line interface to use all the familiar commands and flags.
sudo docker exec -it postgres13 psql -U postgres
You can also connect with the PostgreSQL Docker instance using the
psql PostgreSQL client if you have it pre-installed on your host.
psql -h localhost -U postgres
One of the most significant use cases of using Docker is the ease of creating and accessing applications built within containers without worrying about dependencies and installations.
In this tutorial, we learned about setting up a PostgreSQL server using Docker instead of the actual host machine.
With microservices architecture where different microservices rely on their databases, deploying PostgreSQL servers as Docker containers have become common.
It is also widely used for local execution or end-to-end integration tests in an isolated environment.
Let me know if you have any questions or suggestions, and I’ll be happy to follow up with you.