PostgreSQL en Docker: conexión, volumen y respaldo

PostgreSQL en Docker resulta útil para desarrollar y probar una aplicación con una base aislada. Este ejemplo fija la familia PostgreSQL 16 y su ruta de datos correspondiente. No lo extrapoles automáticamente a otras versiones mayores de la imagen.

La publicación queda limitada al equipo local. Para comunicación entre servicios Docker puedes utilizar una red interna y evitar publicar la base en el host.

Prepara el proyecto

mkdir -p postgres-lab/secrets
cd postgres-lab
umask 077
openssl rand -base64 32 > secrets/postgres.txt
printf 'secrets/\n*.dump\n' > .gitignore
docker volume create postgres_lab_data

Conserva el secreto de forma privada y no lo compartas en la salida de un comando. Una variable _FILE evita incluirlo en el comando de creación, pero el archivo sigue necesitando protección.

Inicia PostgreSQL

docker run -d --name postgres-lab \
  -p 127.0.0.1:5433:5432 \
  --mount type=bind,src="$PWD/secrets",dst=/run/secrets,readonly \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres.txt \
  -e POSTGRES_DB=demo \
  -v postgres_lab_data:/var/lib/postgresql/data \
  postgres:16
docker logs --tail 50 postgres-lab
docker exec postgres-lab pg_isready -U postgres -d demo

El usuario postgres del ejemplo administra la base. Para una aplicación, crea otro rol con los permisos mínimos apropiados. No conviertas la cuenta administrativa en una contraseña compartida por todos los servicios.

Crea datos de prueba

docker exec -it postgres-lab psql -U postgres -d demo

Dentro de psql:

CREATE TABLE notas (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  texto text NOT NULL
);
INSERT INTO notas (texto) VALUES ('Prueba local');
SELECT * FROM notas;

La conexión local interna utiliza la configuración de autenticación del contenedor. Para acceso desde el host, emplea un cliente compatible, la dirección 127.0.0.1 y el puerto 5433, con el método de autenticación configurado.

Redes y disponibilidad

En otro contenedor, localhost no apunta a PostgreSQL. Utiliza el nombre del servicio dentro de una red compartida. Añade espera por salud y reintentos de aplicación; iniciar la base antes no garantiza disponibilidad instantánea.

Si aparece connection refused, revisa dirección, puerto y estado. Si aparece un fallo de autenticación, comprueba rol, base y contraseña. Evita cambiar simultáneamente todos esos elementos.

Respalda y restaura en otra base

Para el laboratorio:

docker exec postgres-lab pg_dump -U postgres -d demo -Fc > demo.dump

Revisa que el comando termine correctamente y protege el archivo. La restauración debe probarse en otra base con pg_restore y permisos adecuados, sin sobrescribir datos importantes.

pg_dump de una base no cubre automáticamente todos los objetos globales del servidor. Si necesitas recuperar roles u otros elementos, incorpora un procedimiento apropiado y documentado.

Cambios de versión y limpieza

Las variables de inicialización se aplican cuando el directorio de datos está vacío. Cambiar una contraseña en la configuración no modifica por sí mismo una base existente.

No cambies la etiqueta a otra versión mayor reutilizando datos a ciegas. Revisa pg_upgrade, exportación/importación y requisitos de la imagen. Elimina volúmenes únicamente cuando hayas comprobado su contenido y respaldo.

Preguntas frecuentes

¿El contenedor puede recrearse sin perder datos?

En este diseño el volumen conserva los datos si se reutiliza correctamente. Borrar el volumen o seleccionar otro puede producir pérdida o una instalación aparentemente vacía.

¿pg_isready confirma que mi aplicación tiene permisos?

No. Comprueba disponibilidad del servidor para conexiones en su alcance, no todas las credenciales ni operaciones de una aplicación.

¿Puedo usar siempre la ruta de volumen de este ejemplo?

No. Se eligió para la familia PostgreSQL 16. Consulta la documentación de la imagen al cambiar de versión mayor.

En pocas palabras

PostgreSQL en un contenedor necesita persistencia y un esquema de acceso apropiado. La versión de la imagen determina requisitos y rutas; una actualización mayor exige un procedimiento de migración.

Conclusión

Comprueba datos tras un reinicio y ensaya una restauración en una base separada. Documenta versión y volumen y revisa compatibilidad antes de actualizar la imagen.

Para continuar, revisa Docker: qué es y cómo usarlo para ejecutar contenedores y Cómo instalar Docker en Ubuntu 24.04: guía práctica paso a paso.

Fuentes y documentación

Documentación de hub.docker.com.

Documentación de www.postgresql.org.