Skip to main content
Docker

How to run a PostgreSQL database using Docker Compose in just a few minutes?

Learn how to run PostgreSQL the powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance using Docker Compose.

β€” Christian Schou

I often use PostgreSQL as the database engine when making new applications. It's fast, easy to use, and integrates very well with almost any programming language and platform out there on the internet.

PostgreSQL
The world’s most advanced open source database.

If you are not running a Windows machine and you need to run a PostgreSQL database on either macOS or Linux, you could go with Docker. It is very easy to get started with PostgreSQL on Docker with just a few simple commands.

This article will be short, but very straightforward and easy to follow. By the end you will be able to use Docker and Docker Compose to run your very own PostgreSQL database.

Running your databases in containers is very ideal both in the development environment, but also in production. You can scale them easily and adapt to your user's needs without having to change the whole architecture of your hosting environment.

If you are working the smart way (work smart not hard) you incorporate the database into your CI/CD pipeline to make sure that there is always a database associated with your application and the other developers on your team will also have access to test new features on their development machine without having to download and install tons of software locally.

How to run PostgreSQL using Docker Compose?

It is very easy to get started with PostgreSQL when you specify your infrastructure as code using Docker Compose.

Below is a full docker-compose.yml file showing you how to get PostgreSQL up and running easily. It includes a volume section to automatically generate a local volume (path) for your database data. By doing this you won't lose your data if the container is restarted. Normally all data is in memory inside the container, but this way we can persist it.

Configure username and password

I always configure sensitive data inside the environment variables to make sure they are not exposed inside a compose file. This way I can share the compose files with other developers without them knowing my credentials.

The env. variables you need to configure are:

  • POSTGRES_USER
  • POSTGRES_PASSWORD

You can set the credentials as per your needs. Below are the credentials inside the compose file for demo purposes.

version: '3.5'


services:
  postgres:
    container_name: postgres_demo
    image: postgres:latest
    environment:
      POSTGRES_USER: super_admin
      POSTGRES_PASSWORD: SomeSecretPassword
      PGDATA: /data/postgres
    volumes:
       - postgres-db:/data/postgres
    ports:
      - "5432:5432"


volumes:
  postgres-db:
    driver: local

Let's fire it up

You can copy the code from above into your own docker compose file. I have named mine docker-compose.yml in this demo.

If you are on a Mac or Linux (GUI) computer you can bring up the terminal and execute the command below inside the folder where you have saved your compose file. If you are hardcore and only work in the CLI, then you can simply just execute the below command.

This will pull the latest version of PostgreSQL from Docker Hub.

docker-compose -f docker-compose.yml up -d

To verify the container is running we can execute the following command in the terminal. This will list all Docker processes.

docker ps

You should see something similar to this in your terminal:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
h1c2ad243a0n        postgres:latest     "docker-entrypoint.s…"   5 min ago           Up 5 minutes        0.0.0.0:5432->5432/tcp   postgres_demo

If you need to stop the container again, you can execute the following command inside your terminal:

docker stop postgres_demo

There you go, the container is stopped again and PostgreSQL is no longer running.

Summary

In this very short tutorial, you learned how to run PostgreSQL using Docker locally from a docker-compose.yml file. As you can see it is very straightforward to run a new database using docker and attach a volume (persistent storage) to the container.

If you got any questions, issues, or suggestions, please let me know in the comments below. Until next time - have it awesome!