Docker Compose: PostgreSQL + pgAdmin

pgAdmin te da una interfaz web para mirar y editar tu base de datos PostgreSQL con clics, en vez de a golpe de psql. Es muy cómodo en desarrollo. Esta guía monta los dos servicios juntos y se centra en lo que más confunde la primera vez: cómo conectar pgAdmin a Postgres y por qué el panel no debe quedar expuesto.

compose.yaml de Postgres + pgAdmin

Fíjate en un detalle: la base de datos no publica puerto. Solo pgAdmin publica el suyo, y atado a loopback.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    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
  pgadmin:
    image: dpage/pgadmin4:8.12
    restart: unless-stopped
    environment:
      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}
    ports:
      - "127.0.0.1:5050:80"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - pgadmin_data:/var/lib/pgadmin

volumes:
  postgres_data:
  pgadmin_data:

El .env.example:

POSTGRES_DB=app
POSTGRES_USER=app
POSTGRES_PASSWORD=CHANGE_ME
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=CHANGE_ME

Levántalo y abre http://localhost:5050. Entra con el email y la contraseña de PGADMIN_DEFAULT_*.

Conectar pgAdmin a Postgres: usa el nombre del servicio

Este es el error número uno. Dentro de pgAdmin, al registrar un servidor nuevo, en Host name/address mucha gente escribe localhost y obtiene un could not connect to server. La razón: dentro del contenedor de pgAdmin, localhost es el propio pgAdmin, no Postgres.

Los datos correctos de conexión son:

• Host name/address: postgres (el nombre del servicio)
• Port: 5432
• Username / Password: los de POSTGRES_USER y POSTGRES_PASSWORD

Dos contraseñas distintas

Es fácil mezclarlas. El login de pgAdmin (PGADMIN_DEFAULT_EMAIL / PGADMIN_DEFAULT_PASSWORD) sirve para entrar en la interfaz web. Las credenciales de la base de datos (POSTGRES_USER / POSTGRES_PASSWORD) son las que pones al registrar el servidor dentro de pgAdmin. No son la misma cosa.

Por qué no exponer el panel

pgAdmin es una herramienta de administración: quien entra puede leer, modificar o borrar todos tus datos. Por eso aquí el puerto va atado a 127.0.0.1: solo lo alcanzas desde tu equipo. Publicarlo a Internet con 5050:80 y una contraseña floja es una puerta abierta a tu base de datos.

En producción, lo razonable es no desplegar pgAdmin de cara al público: déjalo tras una VPN o un reverse proxy con TLS y autenticación, o no lo despliegues y conéctate con psql cuando lo necesites.

Que pgAdmin recuerde tus servidores

El volumen pgadmin_data:/var/lib/pgadmin guarda la configuración del panel (servidores registrados, preferencias). Sin él, cada down te obliga a registrar el servidor de nuevo. Con él, pgAdmin recuerda tu conexión entre reinicios.

Siguientes pasos

Genera este stack en el generador de Docker Compose. Si solo quieres la base de datos sin panel, vuelve a la guía de PostgreSQL.