When managing a PostgreSQL container with Docker Compose, setting environment variables significantly impacts the container's initial operation and restart behavior. Understanding how the presence of a data volume affects the timing of each variable's application is crucial for safe operation.

1. Required Environment Variable: POSTGRES_PASSWORD

When running a PostgreSQL container from a Docker image, POSTGRES_PASSWORD is the only essential environment variable that must be always set, regardless of the state of the data volume.

Variable Name Role Timing of Application Behavior on Deletion
POSTGRES_PASSWORD Setting superuser password Always required (initial setup and container start process) Container fails to start (security error)

Key Point: This variable is a security requirement for starting the container, and it must be specified in the docker-compose.yml file even if data already exists.

2. Initial Setup Variables: Understanding Timing of Application

POSTGRES_USER and POSTGRES_DB are environment variables that apply only when the database cluster is first created (when the data volume is empty).

Variable Name Role Timing of Application Impact of Changes on Restart
POSTGRES_USER Designating the initial superuser name Only when volume is empty Ignored (keeps existing user)
POSTGRES_DB Creating the initial database name Only when volume is empty Ignored (keeps existing DB)

📌 Operation Principle on Restart

When restarting the container with docker-compose up -d while connecting to a volume that already contains data, the PostgreSQL image skips the initialization process (initdb) and loads the existing data.

Thus, when changing other settings like container name and logging method and restarting, changing the values of POSTGRES_USER or POSTGRES_DB will not change the user or name of the already existing database.

3. Docker Compose Example

Here is a concise docker-compose.yml example that includes required and recommended variables.

services:
  db:
    image: postgres:latest
    restart: always
    container_name: my_postgres_db  # Container name (can be changed)
    logging:
      driver: "json-file"          # Logging method (can be changed)
    environment:
      # ⚠️ Required variable: must be included.
      POSTGRES_PASSWORD: your_secure_password 

      # Initial setup variables: apply only when volume is empty.
      POSTGRES_USER: devuser
      POSTGRES_DB: main_app_db
    ports:
      - "5432:5432"
    volumes:
      # Volume for permanent data storage
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

✨ Operational Tip: Safe Configuration Changes

After changing the container name, logging settings, etc., use the following command to restart while keeping existing data intact.

docker-compose up -d

Note: Be extremely cautious not to use the command that deletes the volume containing data (docker-compose down -v).