This tutorial will guide you through the process of 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 when it comes to 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 if it were 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
What we will do here is 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. If you need a specific release, change
latest tag to the required version.
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 setup a Docker volume or bind mount to persist your database in. Otherwise, your data will be lost when the container restarts. The mount should be made to
/var/lib/postgresql/data directory within the container.
For the purposes of this guide, we will create a docker volume 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 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
docker run command will create a running PostgreSQL database within a Docker container.
Let’s break down this syntax. Here is what each parameter in that command means:
-dwill run this container in detached mode so that it runs in the background.
--nameassigns the name “postgres13” to 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 to the container and running the
psql command. This provides the full PostgreSQL command-line interface, so you can use all the familiar commands and flags.
sudo docker exec -it postgres13 psql -U postgres
You can also connect with the PostgreSQL Docker instance by 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 having to worry about dependencies and installations.
In this tutorial, we have learned about setting up a PostgreSQL server using Docker instead of the actual host machine.
These days, with microservices architecture where different microservices rely on their own databases, deploying PostgreSQL servers as Docker containers have become quite a common practice. It is also widely used for any local execution or for running end to end integration tests in an isolated environment.
Let me know if you have any questions or suggestions, I’ll be happy to follow-up with you.