Run PostgreSQL Using Docker with Docker Compose

Running PostgreSQL in a Docker container makes it incredibly easy to spin up a database without installing anything on our local machine. In this article, we’ll walk through how to set up PostgreSQL using Docker Compose in a simple and friendly way.

Tables of contents:

• 1. Create a docker-compose.yml file
• 2. Start PostgreSQL Container
• 3. Connect to PostgreSQL
  • Option 1: Using Docker CLI with psql command
  • Option 2: Use a GUI Client
• 4. Stop and Remove Containers
• 5. Restarting Without Losing Data
• 6. Use System Environment Variables
• 7. References

Technologies used:

• Docker 28
• Official Docker postgres image (latest tag)

1. Create a docker-compose.yml file

Create a file named docker-compose.yml and add the following content:

services:
  postgres:
    image: postgres:latest
    container_name: my_postgres
    restart: always
    environment:
      POSTGRES_USER: mkyong
      POSTGRES_PASSWORD: password
      POSTGRES_DB: testdb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
    driver: local

2. Start PostgreSQL Container

Run this command in the same directory as our docker-compose.yml file:

docker-compose up -d

This will:

• Pull the latest PostgreSQL image (if not already present),
• Create a container named my_postgres
• Map port 5432 from the container to our local machine.

3. Connect to PostgreSQL

We can connect to the running database in two ways:

Option 1: Using Docker CLI with psql command

Run the following command to access the PostgreSQL CLI:

docker exec -it my_postgres psql -U mkyong -d testdb

This will bring up the PostgreSQL prompt:

docker exec -it my_postgres psql -U mkyong -d testdb
psql (17.4 (Debian 17.4-1.pgdg120+2))
Type "help" for help.

testdb=# \l

Access the PostgreSQL CLI and show all tables:

docker exec -it my_postgres psql -U mkyong -d testdb
psql (17.4 (Debian 17.4-1.pgdg120+2))
Type "help" for help.

testdb-# \dt

             List of relations
 Schema |       Name       | Type  | Owner  
--------+------------------+-------+--------
 public | question         | table | mkyong
 public | question_options | table | mkyong
 public | quiz             | table | mkyong
(3 rows)

Option 2: Use a GUI Client

Tools like pgAdmin, DBeaver, or DataGrip make it easy to manage our databases visually.

Use the following connection details:

• Host: localhost
• Port: 5432
• Database: testdb
• User: mkyong
• Password: password

4. Stop and Remove Containers

To stop the PostgreSQL container:

docker-compose down

If we want to remove the volumes (i.e., delete all data), add the -v flag:

docker-compose down -v

P.S This will permanently delete the database and all its contents. Use with caution.

5. Restarting Without Losing Data

Docker volumes allow us to persist PostgreSQL data even after restarting or recreating containers. The volumes section in our docker-compose.yml ensures this.

services:
  postgres:
    image: postgres:latest
    container_name: my_postgres
    restart: always
    environment:
      POSTGRES_USER: mkyong
      POSTGRES_PASSWORD: password
      POSTGRES_DB: testdb
    ports:
      - "5432:5432"
    # Take the volume named `postgres_data`, and map it to the internal PostgreSQL data directory."
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
    driver: local

To test this, stop the container:

docker-compose down

Then start it again:

docker-compose up -d

The data will still be available because it’s stored in the postgres_data volume.

6. Use System Environment Variables

For better security and flexibility, we can store sensitive data in system environment variables instead of hardcoding them.

environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}

Then, in our terminal or .env file, define:

POSTGRES_USER=mkyong
POSTGRES_PASSWORD=password
POSTGRES_DB=testdb

This approach is very helpful in CI/CD pipelines or when working on teams.

7. References

• How to Use the Postgres Docker Official Image
• PostgreSQL image in Docker Hub
• Docker – Running MariaDB as a container
• How to access the Docker container’s shell
• How to run an init script for Docker Postgres
• How to list containers in Docker
• How to access the Docker container’s shell
• How to stop and remove all docker containers