The other day, I needed to set up a PostgreSQL database, and after considering various solutions, I decided to use Docker. In this tutorial, I’ll share the solution that worked for my problem.

Creating a PostgreSQL Database Using Docker Compose#

Docker Compose is a powerful tool that allows us to manage multiple containers from a single central point. You might think it’s a bit much for setting up a database, but I found it surprisingly easy to set up and use.

Let’s start!

Creating the docker-compose.yml File#

Docker Compose requires a configuration file named docker-compose.yml where we define and configure our containers. Writing this file is straightforward; here’s the one I used for my database:

version: '3'
services:
  postgres-db:
    image: postgres:latest
    container_name: postgres_container
    volumes:
      - "/path_to_local_storage:/var/lib/postgresql/data"
    environment:
      - POSTGRES_DB=my_db
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    ports:
      - '5433:5432'

In the above file:

  • We define a service named postgres-db containing the PostgreSQL database image.
  • You can customize the container_name to your preference.
  • To ensure data persistence and choose a custom storage location, define your preferred local path in the ‘volumes’ section.
  • Set your database credentials (user, password) and the default database name in the environment section.
  • The port mapping is configured to use the default PostgreSQL ports. You can adjust this mapping if necessary; the format is local_machine_port:docker port.

Starting the database#

To start your database, open a terminal in the directory where your docker-compose.yml is located (or specify a relative path to the file) and run this command (assuming you’re using Docker Compose 2):

docker compose -p example up -d

This command creates the containers defined in the compose file. You can customize the project name with the -p property.

Stopping the database#

To stop your database, use this command:

docker compose down

Connecting locally to the database#

Connecting to the database locally on your computer is simple. Access http://localhost:5433 using your chosen username and password. While I use DataGrip to connect, any database software can connect to it.

Troubleshooting#

During the container creation process, I encountered some common issues, along with their solutions.

Issue: The image exited with code 1.#

If your container exits immediately when launched, check the container logs by running:

docker logs my_container_name

I discovered that my data directory contained hidden files that caused this issue. Deleting these hidden files allowed the database to start and function as expected.

Issue: The mounting point is not valid.#

If you encounter issues starting the image, it may be related to the local path name. If your path contains spaces, a simple workaround is to enclose the path in double quotes.

Conclusion#

By utilizing docker-compose, we can easily start and manage data persistence for our databases. This method provides a straightforward and quick way to create databases with data persistence. I hope this tutorial proves as helpful to you as it was to me.

Happy coding!