Running PostgreSQL in Docker, A Quick and Practical Guide

2
PostgreSQL in Docker

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.

Related: Install Docker on Ubuntu: A Step-by Step Guide

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

The 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:

  • -d will run this container in detached mode so that it runs in the background.
  • --name assigns the name “postgres13” to your container instance.
  • -p will bind the PostgreSQL container port 5432 to the same port on your host machine. You’ll be able to connect to localhost:5432 using PostgreSQL clients (psql) running on your host.
  • -v option bind that data folder inside the container volume (/var/lib/postgresql) to the local Docker volume (postgres-volume) you created in the previous step.
  • -e sets an environment variable. In this case, the PostgreSQL root password.
  • postgres is 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

Conclusion

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.

Related: Install PostgreSQL on Ubuntu: An Easy-to-Follow Guide

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.

2 Comments

Leave a Reply

Your email address will not be published.

Latest from Tutorials