Docker Compose for PostgreSQL step by step

This guide sets up a PostgreSQL database with Docker Compose for local development: the database your app uses while you code, without installing Postgres on your machine. It is aimed at people starting with Docker and at those who already use it but want a clean compose that does not lose data or leak passwords.

Minimal, working compose.yaml

Save this as compose.yaml. It has no version: key because that is obsolete in Compose v2.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

volumes:
  postgres_data:

And here is the matching .env.example. Copy it to .env, set a real password and add .env to your .gitignore.

POSTGRES_DB=app
POSTGRES_USER=app
POSTGRES_PASSWORD=CHANGE_ME

Why each part is there

• image: postgres:16-alpine. A pinned version, not :latest. That way a docker compose pull tomorrow does not change the major version on you without warning.
• environment with ${VARIABLE}. Credentials are interpolated from the .env, not written in plaintext in the compose. The real secret never enters git.
• volumes: postgres_data. Data lives in a named volume mounted at /var/lib/postgresql/data. Without it, a down would lose the whole database.
• ports: 127.0.0.1:5432:5432. Publishes Postgres on your loopback only, so you can connect with psql or a GUI client without opening it to the network.
• healthcheck with pg_isready. Checks that Postgres accepts connections. The command uses $$POSTGRES_USER: the $$ makes Compose pass a single $ to the container, where the variable does exist at runtime.

Day-to-day commands

docker compose up -d            # start in the background
docker compose ps               # service status and health
docker compose logs -f postgres # follow Postgres logs
docker compose exec postgres \
  psql -U app -d app            # open a psql session inside
docker compose down             # stop and remove containers (data safe)
docker compose down -v          # ALSO remove the volume (data deleted)

The difference between down and down -v is exactly the one that scares people: -v removes the volume and, with it, the entire database. Use it on purpose when you want to start fresh, never out of habit.

The classic mistake: I changed the password and it doesn't work

This is the number one question with Postgres in Docker. You change POSTGRES_PASSWORD in the .env, restart, and it still asks for the old password. Nothing is broken: the Postgres image only initializes the user and database the first time, when the volume is empty. On later starts the data already exists and the POSTGRES_* variables are ignored.

You have two paths, depending on whether you want to keep the data:

• Start fresh (development): docker compose down -v to remove the volume, then docker compose up -d. Postgres reinitializes with the new password.
• Keep the data: change the password via SQL: docker compose exec postgres psql -U app -d app -c "ALTER USER app PASSWORD 'new';", and update the .env to match.

Local and development, not production

This compose is honest about its scope: it is for coding against a real database on your machine. It is not production hardening. Before putting Postgres in front of users you will need, at a minimum, automated and tested backups, a strong password kept out of git, usually no port published to the host, and a deliberate decision about version upgrades. The healthchecks and secrets guide goes into more detail on those decisions.

Next steps

Generate this stack (with or without a local port, with or without a healthcheck) in the Docker Compose generator. If you are going to connect your own app to this database, continue with Node.js + PostgreSQL or add a web interface with PostgreSQL + pgAdmin.