PostgreSQL + pgAdmin con Docker Compose

Entorno local reproducible: PostgreSQL y pgAdmin con Docker Compose. Pensado para desarrollo, practica y pruebas en Windows, macOS y Linux.

Tabla de contenidos

• Objetivo
• Estructura del proyecto
• Configuracion (.env)
• Servicios
• Como levantar el proyecto
• Acceso (PostgreSQL y pgAdmin)
• Comandos utiles
• Solucion de problemas
• Licencia y autor

Objetivo

• Levantar PostgreSQL sin instalarlo directamente en el sistema operativo.
• Administrar la base desde el navegador con pgAdmin.
• Persistir datos entre reinicios mediante volumenes nombrados de Docker.
• Usar un solo usuario de base de datos (root) para ver y administrar todas las DB.

Estructura del proyecto

PostgreSQL/
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md

Tras el primer docker compose up -d, Docker crea volumenes (suelen llevar prefijo del nombre del proyecto), por ejemplo:

• <proyecto>_postgres_data - datos de PostgreSQL
• <proyecto>_pgadmin_data - configuracion y sesiones de pgAdmin

Configuracion (.env)

Puedes crear un .env en la raiz para ajustar puertos, versiones y credenciales sin editar docker-compose.yml. Si no existe .env, Compose usa los valores por defecto definidos en el compose.

Crear .env desde la plantilla

cp .env.example .env

En Windows (PowerShell):

Copy-Item .env.example .env

Ejemplo de variables

POSTGRES_VERSION=15.3
PGADMIN_VERSION=latest
POSTGRES_PORT=5432
PGADMIN_PORT=8080
POSTGRES_USER=root
POSTGRES_PASSWORD=tu_password_root
POSTGRES_DB=postgres
PGADMIN_DEFAULT_EMAIL=admin@local.dev
PGADMIN_DEFAULT_PASSWORD=tu_password_pgadmin

Se usa un solo usuario de base de datos: POSTGRES_USER (por defecto root).

Servicios

Servicio	Rol	Detalle breve
myDB	PostgreSQL	Imagen postgres:${POSTGRES_VERSION} (por defecto 15.3), puerto ${POSTGRES_PORT} -> 5432, volumen postgres_data, healthcheck con pg_isready.
pdAdmin	UI web	Imagen dpage/pgadmin4:${PGADMIN_VERSION}, puerto ${PGADMIN_PORT} -> 80, espera a PostgreSQL sano (depends_on + service_healthy).

Red interna: course_net (bridge). Dentro de Docker, el host de PostgreSQL es el nombre del servicio: myDB. Desde tu PC usa localhost y el puerto configurado.

Como levantar el proyecto

1) Requisitos

• Docker en ejecucion (Docker Desktop en Windows/macOS; Docker Engine + plugin Compose en Linux).
• Docker Compose v2: docker compose version.

2) Entrar en la carpeta del proyecto

Linux / macOS (Bash, zsh):

cd /ruta/a/tu/proyecto/PostgreSQL

Windows (PowerShell):

cd "C:\ruta\a\tu\proyecto\PostgreSQL"

Windows (CMD):

cd /d C:\ruta\a\tu\proyecto\PostgreSQL

3) Arrancar en segundo plano

docker compose up -d

4) Comprobar estado

docker compose ps

Deberias ver myDB en estado healthy y pdAdmin en Up.

Acceso (PostgreSQL y pgAdmin)

Los valores salen de tu .env o, si no hay .env, de los defaults del docker-compose.yml.

PostgreSQL desde el host (DBeaver, TablePlus, psql local, apps)

Campo	Valor
Host	127.0.0.1 o localhost
Puerto	POSTGRES_PORT (por defecto 5432)
Usuario	POSTGRES_USER (por defecto root)
Contrasena	POSTGRES_PASSWORD
Base inicial	POSTGRES_DB (por defecto postgres)

pgAdmin

• URL: http://localhost:<PGADMIN_PORT> (por defecto 8080).
• Login web: PGADMIN_DEFAULT_EMAIL + PGADMIN_DEFAULT_PASSWORD.
• Al registrar servidor PostgreSQL dentro de pgAdmin:
  • Host: myDB
  • Port: 5432
  • Username: POSTGRES_USER
  • Password: POSTGRES_PASSWORD

Comandos utiles

docker compose down
docker compose restart
docker volume ls

docker compose logs -f myDB
docker compose logs -f pdAdmin

docker compose exec myDB psql -U root -d postgres
docker compose exec myDB psql -U root -d postgres -c '\l'

# Borra contenedores y volumenes de este proyecto (pierdes los datos)
docker compose down -v

Solucion de problemas

• No conecta desde cliente del host: usa localhost o 127.0.0.1, no myDB.
• pgAdmin no abre: revisa docker compose ps y docker compose logs pdAdmin.
• PostgreSQL aun no listo: espera a estado healthy y recarga pgAdmin.
• Puerto 5432 u 8080 ocupado: cambia POSTGRES_PORT o PGADMIN_PORT en .env.

Licencia y autor

Uso educativo y desarrollo local.

Autor: Yamil G. Zaracho R.