Al gestionar un contenedor de PostgreSQL con Docker Compose, la configuración de las variables de entorno tiene un impacto significativo en el comportamiento inicial del contenedor y en su forma de reiniciarse. En particular, la existencia de volúmenes de datos afecta el momento de aplicación de cada variable, por lo que es fundamental comprender esto para una operación segura.

1. Variables de entorno obligatorias: POSTGRES_PASSWORD

Cuando se ejecuta un contenedor de PostgreSQL a partir de una imagen de Docker, POSTGRES_PASSWORD es la única variable de entorno obligatoria que debe ser configurada, independientemente del estado del volumen de datos.

Nombre de la variable Rol Momento de aplicación Comportamiento al eliminar
POSTGRES_PASSWORD Configuración de la contraseña del superusuario Siempre necesario (configuración inicial y proceso de inicio del contenedor) Fallo en el inicio del contenedor (error de seguridad)

Clave: Esta variable es un requisito de seguridad para iniciar el contenedor y debe estar especificada en el archivo docker-compose.yml, incluso si ya existe datos.

2. Variables de configuración inicial: comprensión del momento de aplicación

POSTGRES_USER y POSTGRES_DB son variables de entorno que solo se aplican cuando el clúster de bases de datos se crea por primera vez (cuando el volumen de datos está vacío).

Nombre de la variable Rol Momento de aplicación Impacto de los cambios en reinicios
POSTGRES_USER Especificar el nombre del superusuario inicial Solo cuando el volumen está vacío Ignorado (mantiene al usuario existente)
POSTGRES_DB Crear el nombre de la base de datos inicial Solo cuando el volumen está vacío Ignorado (mantiene la base de datos existente)

📌 Principio de funcionamiento en reinicios

Al reiniciar un contenedor con un volumen que ya tiene datos, utilizando docker-compose up -d, la imagen de PostgreSQL salta el proceso de inicialización (initdb) y carga los datos existentes.

Por lo tanto, si cambias otros ajustes como el nombre del contenedor o el método de registro y reinicias, los valores de POSTGRES_USER o POSTGRES_DB no cambiarán los usuarios o nombres de la base de datos ya existentes.

3. Ejemplo de Docker Compose

A continuación se presenta un breve ejemplo de docker-compose.yml que incluye variables obligatorias y recomendadas.

services:
  db:
    image: postgres:latest
    restart: always
    container_name: my_postgres_db  # Nombre del contenedor (puede cambiarse)
    logging:
      driver: "json-file"          # Método de registro (puede cambiarse)
    environment:
      # ⚠️ Variables obligatorias: deben incluirse.
      POSTGRES_PASSWORD: your_secure_password 

      # Variables de configuración inicial: solo se aplican cuando el volumen está vacío.
      POSTGRES_USER: devuser
      POSTGRES_DB: main_app_db
    ports:
      - "5432:5432"
    volumes:
      # Volumen para almacenamiento permanente de datos
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

✨ Consejos de operación: cambios seguros en la configuración

Después de cambiar el nombre del contenedor, la configuración del registro, etc., puedes reiniciar mientras mantienes los datos existentes utilizando el siguiente comando.

docker-compose up -d

Nota: Debes tener especial cuidado con el comando que elimina el volumen con datos (docker-compose down -v), que nunca debe usarse.