If want to create a PostgreSQL database on your computer without losing time, this tutorial for you! Thanks to Docker, we will be able to create a functional database in just a few minutes.

Pre-requirements

If you're not familiar yet with Docker and Docker-Compose, I recommend you to read my two previous articles.

1. A beginner's guide to Docker — how to create your first Docker application You are a developer, and you want to start with Docker? This article is for you.

2. A Beginner's Guide to Docker — How to Create a Client/Server Side with Docker-Compose You are a developer, and you want to discover docker-compose? This article is for you. After a short introduction on Docker-Compose, you will be able to create your first client/server-side application with Docker.

After reading these two articles, you will understand Docker better. Then, you will start using it in your development environments!

Why using Docker-Compose to create your database

PostgreSQL is one of the most used database engines nowadays. If you're here today, it's because you're going to use it in your project!

When I'm working on a new project, I like to have a clean environment. One of the things I dislike the most is installing "big" tools on my computers (for example a database engine).

I like to use containers for some of my tools. I'm not going to lie to you, I'm not always moving all my environment to Docker, but I like to have a part of it in a dedicated one.

One of the good things of doing that is that one command is enough to set up a database from scratch with new parameters. Also, in one command, you can shut down all the environment and free your computer from work.

Now let's create your Docker-Compose for PostgreSQL

The goal of this tutorial is to create a docker-compose containing a PostgreSQL database.
So, you can start your database in only one command whenever you need it.

1. Create files in your project

Consider that you have an existing project. If not, I invite you to create an empty folder on your computer.

In the root of your project, you can create a docker-compose.yml (this file will contain the instructions to create your database).

You should have that kind of folder architecture:

    .
    ├── back/
    ├── docker-compose.yml
    └── front/
    2 directories, 1 file

2. Edit the Docker-Compose file

A bit of theory: in our Docker-Compose file, the goal is to run a PostgreSQL database. To do that, our Docker must contain all the dependencies that we need.

Fortunately, the DockerHub website contains a pre-designed image for PostgreSQL.

All we have to do is to import that image in our docker-compose and configure it.

Note: I provide a docker-compose with comments for understanding purposes.

# A docker-compose must always start by the version tag.
# We use '3' because it's the last version.
version: "3"

# You should know that docker-compose works with services.
# 1 service = 1 container.
# For example, a service maybe, a server, a client, a database...
# We use the keyword 'services' to start to create services.
services:
  # The name of our service is "database"
  # but you can use the name of your choice.
  # Note: This may change the commands you are going to use a little bit.
  database:
    # Official PostgreSQL image from DockerHub (we use the last version)
    image: "postgres:latest"

    # By default, a PostgreSQL database is running on the 5432 port.
    # If we want to access the database from our computer (outside the container),
    # we must share the port with our computer's port.
    # The syntax is [port we want on our machine]:[port we want to retrieve in the container]
    # Note: You are free to change your computer's port,
    # but take into consideration that it will change the way
    # you are connecting to your database.
    ports:
      - 5432:5432

    environment:
      - POSTGRES_USER=username # The PostgreSQL user (useful to connect to the database)
      - POSTGRES_PASSWORD=password # The PostgreSQL password (useful to connect to the database)
      - POSTGRES_DB=default_database # The PostgreSQL default database (automatically created at firt launch)

With this first version of your docker-compose file, you will be able to run your database and connect to it!

2a. Optional configurations

Before running your docker-compose, I share with you some optional configurations.

Replace the environment tag by a .env file

If you don't want to put your environment variable in your docker-compose file, you can create a .env file at your project root.

Now, you should have that kind of folder architecture:

    .
    ├── .env
    ├── back/
    ├── docker-compose.yml
    └── front/
    2 directories, 2 files

In the .env file, you can type enter the following content.

POSTGRES_USER=username
POSTGRES_PASSWORD=password
POSTGRES_DB=default_database

Note: The variables inside the .env file are the same as in your docker-compose.

Then, you can remove the environment part of your docker-compose.

# REMOVE THESE LINES
environment:
  - POSTGRES_USER=username # The PostgreSQL user (useful to connect to the database)
  - POSTGRES_PASSWORD=password # The PostgreSQL password (useful to connect to the database)
  - POSTGRES_DB=default_database # The PostgreSQL default database (automatically created at first launch)

And replace then with the following lines.

# The `env_file` tag allows us to declare an environment file
env_file:
  - .env # The name of your environment file (the one at the repository root)

Now your docker-compose will use the environment variables defined inside the .env.

Use a volume to persist data on your computer

By default, the database data will be only in the container. If you decide to delete the container, all the data are going to disappear definitively.

To save the database data on your computer, you can add the following section inside of the database service of your docker-compose.

# The `volumes` tag allows us to share a folder with our container.
# Its syntax is as follows: [folder path on our machine]:[folder path to retrieve in the container]
volumes:
  # In this example, we are sharing the folder `db-data` in our root repository, with the default PostgreSQL data path.
  # It means that every time the repository is modifying the data inside
  # of `/var/lib/postgresql/data/`, automatically the change will appear in `db-data`.
  # You don't need to create the `db-data` folder. Docker-Compose will do it for you.
  - ./db-data/:/var/lib/postgresql/data/

Note: This part is not mandatory, it's an optional configuration. It can be useful if you want to delete your container and keeping the data locally. We are not going to use the volumes tag at the end of the tutorial.

3. Build Docker-Compose

Because we're not using a Dockerfile in the docker-compose, we don't need to build the image.

Note: The docker-compose will download the PostgreSQL latest image with the run command.

4. Run Docker-Compose

Your docker-compose is ready! The docker-compose will download the PostgreSQL latest image; then your database will start!
In the root of your project repository, you can type the command below.

$ docker-compose up

There you go, that's it. Now you can use the software/programming language of your choice and connect to your database.

Note: As a reminder, the database is accessible on localhost with the 5432 port. In your environment variables, you can find the username, the password and the default database.

5. Stop Docker-Compose

To avoid background processes on your computer, I recommend stopping the container when you finish working on your project.

In the root of your project, you can do it with the command below.

$ docker-compose down

Once you want to work again on your project, you can use docker-compose up to run your database.

Code is available

If you want to retrieve the complete docker-compose code, I've hosted it on my Github.
Feel free to use it for your projects!

GitHub: Docker Compose with PostgreSQL ready to use

If you want more content like this, you can follow me on Twitter, where I tweet about web development, self-improvement, and my journey as a fullstack developer!