How to run PostgreSQL on Docker

Docker, a pivotal tool in modern web development, offers an isolated and flexible environment for running various applications. Among these, PostgreSQL stands out as a popular choice for relational database management.

This guide aims to explain, step-by-step, how to install, run, and access PostgreSQL on Docker. It also covers some frequently asked questions about running PostgreSQL on Docker.

Installing & running Docker on macOS

When it comes to installing Docker on macOS, there are two options: Docker Desktop and Homebrew. Docker Desktop is the official Docker application for macOS, while Homebrew is a package manager that simplifies the installation process.

Docker App for Mac:

1. Visit the Docker Documentation and download Docker for Mac.
2. Open the installer and follow the on-screen instructions.
3. Once installed, launch Docker from the Applications folder.
4. Adjust preferences as needed to allocate resources like memory and CPU.

Homebrew Installation:
Your can find the Homebrew formula for Docker here.
Open Terminal and run

brew install --cask docker

To start Docker, run open /Applications/Docker.app in Terminal. Docker will need some permissions to run, so follow the on-screen instructions to grant them.

Running PostgreSQL Using Docker

When it comes to running PostgreSQL within a Docker environment on macOS, you have two primary options:

1. Single Docker Command Method: This is a straightforward approach where you use a single command to start a PostgreSQL container.
   It's quick and easy, suitable for simple setups or individual developers. More details can be found on Docker's official PostgreSQL image page.

1. Docker Compose Method: This method involves using a docker-compose.yml file to define and run your PostgreSQL container.
   It's more scalable and maintainable, ideal for complex applications or team environments. Docker Compose documentation provides a comprehensive guide on this approach.

Both methods have their advantages, and the choice largely depends on your specific project needs and preferences, but for a local first setup I recommend the Single Docker Command Method.

Install PostgreSQL with a Single Docker Command Method

Open Terminal and enter:

docker run -d --name my_postgres -v my_dbdata:/var/lib/postgresql/data -p 54320:5432 -e POSTGRES_PASSWORD=my_password postgres:15-alpine

This command does the following:

• -d: Runs the container in detached mode.
• --name: Assigns a name to your container.
• -v: Creates a volume for data persistence.
• -p: Maps a port from the container to your host machine.
• -e: Sets environment variables, like the PostgreSQL password.

The PostgreSQL 15 image will be pulled and run in the container named 'my_postgres'.

Install PostgreSQL with Docker Compose file

Create a directory for your project and navigate into it.

Make a docker-compose.yml file with:

version: "3"
services:
  db:
    image: "postgres:13"
    container_name: "my_postgres"
    environment:
      POSTGRES_PASSWORD: "my_password"
    ports:
      - "54320:5432"
    volumes:
      - my_dbdata:/var/lib/postgresql/data

Run docker-compose up -d to start PostgreSQL in a Docker container.

Your docker PostgreSQL container will be mounted. You can check it with docker ps.

Accessing the PostgreSQL Docker Container

You know have docker running with PostgreSQL, but how do you access it?

First thing first, open the Docker App, and you'll see the container running. If for any reason it isn't running just click the start button.

To interract with the container you'll use the docker exec command and then to access PostgreSQL you'll use the psql command. Open a new Terminal window and run:

docker exec -it my_postgres psql -U postgres

If you need to troubleshoot something, you can access docker logs for that container using the docker logs command:

docker logs -f my_postgres

You can access your PostgreSQL database right from your preferred DB client, like TablePlus I use as an example here:
Use the port, db_name, user and password defined when you created the Docker Container.

FAQ

How to install different PostgreSQL versions

• Create distinct Docker volumes and containers for each PostgreSQL version.
• For instance, PostgreSQL 13 can be run on port 5013 and PostgreSQL 12 on 5012.
• Use different container names like postgres-13 and postgres-12 for clarity.

How to connect to different PostgreSQL versions containers

• Have each Docker container running for each version on a specific port. You can use the psql command, or configure your app or client with port corresponding to the Postgres version you need to access to.

How to run PostgreSQL Docker Containers on Boot:

• Utilize Docker’s --restart flag to control container behavior on boot.
• Options like always, unless-stopped, and on-failure offer flexibility in managing container lifecycles.
• For instance, docker run -d --restart unless-stopped postgres:13 ensures the container restarts automatically unless explicitly stopped.

How to run PostgreSQL Docker Containers in the Background:

• Use the -d flag to run containers in the background.
• For instance, docker run -d postgres:13 runs the container in the background.

How to stop PostgreSQL Docker Containers:

• Use the docker stop command to stop a container.
• For instance, docker stop my_postgres stops the container named my_postgres.