PostgreSQL en Docker: Guía paso a paso para principiantes

Configurar PostgreSQL en Docker

Lo único que necesitarás para ejecutar la base de datos Postgres en Docker es el propio motor Docker.

En esta sección, te guiaré a través del proceso para cubrir los requisitos previos y ejecutar una base de datos PostgreSQL totalmente funcional en un contenedor Docker.

Requisitos previos

Antes de empezar con PostgreSQL en Docker, necesitarás Docker instalado en tu sistema.

La instalación varía según el sistema operativo. Los usuarios de Windows y macOS pueden instalar simplemente DockerDesktop, que es una interfaz gráfica fácil de usar para gestionar contenedores. Descárgalo desde el sitio web oficial de Docker.

Los usuarios de Linux pueden instalar Docker Engine directamente utilizando el gestor de paquetes de su distribución. Por ejemplo, en Ubuntu:

sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker

Además de tener instalado Docker, es recomendable que estés familiarizado con los comandos básicos del terminal y con los conceptos básicos de Docker, como imágenes, contenedores y volúmenes. Estas guías prácticas de DataCamp te ayudan:

• Docker para principiantes: Guía práctica de contenedores
• Instala Docker en Ubuntu: De la instalación al primer contenedor

Extraer la imagen Docker de PostgreSQL

Antes de ejecutar PostgreSQL, tienes que descargar la imagen Docker oficial de PostgreSQL desde Docker Hub. Esta imagen sirve de plantilla para crear contenedores.

Para obtener la última imagen de PostgreSQL, abre tu terminal o símbolo del sistema y ejecuta

docker pull postgres

Este comando descarga la última versión estable de PostgreSQL. Si necesitas una versión concreta, puedes especificarla con una etiqueta:

docker pull postgres:17

Imagen 1 - Extrayendo la última versión estable de la imagen de la base de datos PostgreSQL

Algunas de las etiquetas de imagen PostgreSQL más utilizadas son:

• postgres:latest - La versión estable más reciente de PostgreSQL
• postgres:17 - PostgreSQL versión 14.x (el parche más reciente de la versión 17)
• postgres:17.4 - Una versión concreta (17.4 en este caso).
• postgres:bookworm - PostgreSQL construido sobre la distribución Linux Debian Bookworm.

Puedes ver todas las etiquetas disponibles en la página oficial de PostgreSQL Docker Hub.

Ejecutar PostgreSQL en un contenedor Docker

Una vez que tengas la imagen PostgreSQL, puedes crear e iniciar un contenedor con un solo comando:

docker run --name postgres-db -e POSTGRES_PASSWORD=mypassword postgres

Imagen 2 - Iniciar un contenedor PostgreSQL

Este comando crea un nuevo contenedor llamado postgres-db y establece una variable de entorno para la contraseña de PostgreSQL.

Sin embargo, este comando básico tiene limitaciones. Te recomiendo que utilices opciones adicionales:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -p 5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Imagen 3 - Iniciando un contenedor PostgreSQL con variables env en modo separado

Permíteme desglosar estas opciones adicionales:

• Variables de entorno:
  • POSTGRES_PASSWORD: Establece la contraseña del superusuario de PostgreSQL (obligatorio).
  • POSTGRES_USER: Crea un nuevo superusuario con este nombre (por defecto es "postgres" si no se especifica).
  • POSTGRES_DB: Crea una nueva base de datos con este nombre (por defecto, el nombre de usuario si no se especifica).
• La asignación de puertos (-p 5432:5432) asigna el puerto PostgreSQL del contenedor (5432) al mismo puerto de tu máquina anfitriona, lo que te permite conectarte a PostgreSQL utilizando localhost:5432.
• El montaje del volumen (-v postgres-data:/var/lib/postgresql/data) crea un volumen Docker llamado postgres-data que persiste los archivos de la base de datos fuera del contenedor. Esto garantiza que tus datos no se pierdan cuando el contenedor se detenga o se retire.
• La bandera -d asegura que el contenedor se ejecuta en modo separado. En lenguaje llano, esto significa que el contenedor se ejecuta en segundo plano.

Puedes verificar que el contenedor está funcionando con

docker ps

Imagen 4 - Listado de todos los contenedores en ejecución

En la siguiente sección, te mostraré cómo configurar aún más tu contenedor PostgreSQL para casos de uso específicos.

Configurar PostgreSQL en Docker

La configuración básica que he cubierto en la sección anterior te servirá para empezar, pero para cualquier cosa más avanzada, probablemente querrás personalizar tu contenedor PostgreSQL.

De eso trata esta sección.

Configurar el almacenamiento persistente con volúmenes

Uno de los aspectos más importantes de ejecutar una base de datos en Docker es asegurarte de que tus datos persisten más allá del ciclo de vida del contenedor. Por defecto, todos los datos de un contenedor se pierden cuando se elimina el contenedor. Para una base de datos, esto no suele ser lo que quieres.

Los volúmenes Docker ofrecen una solución a este problema almacenando los datos fuera del sistema de archivos del contenedor.

Para configurarlo, empieza por crear un volumen con nombre:

docker volume create postgres-data

Opcionalmente, puedes inspeccionar los detalles del volumen ejecutando el siguiente comando:

docker volume inspect postgres-data

Imagen 5 - Listado de detalles de volumen

Ahora, al iniciar tu contenedor PostgreSQL, monta el volumen en el directorio de datos PostgreSQL:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

El parámetro -v postgres-data:/var/lib/postgresql/data conecta el volumen nombrado al directorio de datos del contenedor.

En resumen, utilizar volúmenes para PostgreSQL tiene estas ventajas:

• Tus datos persisten aunque elimines el contenedor.
• Puedes detener, iniciar o actualizar tu contenedor sin perder datos.
• Puedes crear copias de seguridad de tus datos haciendo una copia del volumen.
• Mejor rendimiento en comparación con los montajes bind (especialmente en macOS y Windows).

Exponer puertos para conectarse a PostgreSQL

Para conectarte a tu base de datos PostgreSQL desde aplicaciones que se ejecuten en tu máquina anfitriona, necesitas exponer el puerto PostgreSQL (5432) a tu sistema local.

Lo más sencillo es asignar el puerto 5432 del contenedor al mismo puerto de tu host:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d postgres

El parámetro -p 5432:5432 asigna el puerto 5432 del contenedor al puerto 5432 de tu máquina anfitriona.

Si ya tienes PostgreSQL u otro servicio utilizando el puerto 5432 en tu host, puedes mapearlo a un puerto diferente:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5433:5432 \
  -d postgres

Ahora, el puerto 5432 del contenedor está mapeado al puerto 5433 en tu host. Al conectarte, tendrás que especificar el puerto 5433 en lugar del 5432 predeterminado.

Por defecto, el puerto está expuesto en todas las interfaces de red (0.0.0.0). Opcionalmente, puedes restringirlo a localhost para mayor seguridad:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -d postgres

Esto sólo permite conexiones desde tu máquina local, no desde otras máquinas de la red.

Configurar los ajustes de PostgreSQL

Puedes cambiar muchas configuraciones predeterminadas de PostgreSQL al poner en marcha tu contenedor. Un enfoque habitual, pero no el único, es utilizar variables de entorno.

Aquí tienes un par de variables que puedes utilizar para configurar la base de datos:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -e POSTGRES_INITDB_ARGS="--data-checksums" \
  -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 \
  -d postgres

Y esto es lo que hace cada uno de ellos:

• POSTGRES_PASSWORD: Establece la contraseña de superusuario (obligatorio).
• POSTGRES_USER: Establece el nombre del superusuario (por defecto es "postgres").
• POSTGRES_DB: Establece el nombre por defecto de la base de datos (por defecto es el nombre de usuario).
• POSTGRES_INITDB_ARGS: Pasa argumentos al comando initdb de PostgreSQL.
• POSTGRES_HOST_AUTH_METHOD: Establece el método de autenticación.

Además de las variables de entorno, también puedes personalizar la configuración de PostgreSQL para realizar cambios más avanzados en la configuración de la base de datos.

Algunos ajustes de PostgreSQL que se personalizan con frecuencia son:

• max_connections: Controla cuántas conexiones acepta PostgreSQL (por defecto es 100).
• shared_buffers: Establece la memoria utilizada para el almacenamiento en caché (el valor por defecto suele ser demasiado bajo para producción).
• work_mem: Memoria utilizada para las operaciones de consulta.
• maintenance_work_mem: Memoria utilizada para operaciones de mantenimiento.

Para una aplicación práctica, empieza por crear un archivo, llamémoslo my-postgres-conf:

max_connections = 200
shared_buffers = 1GB
work_mem = 16MB
maintenance_work_mem = 256MB

Ahora, monta este archivo cuando ejecutes el contenedor:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./my-postgres.conf:/etc/postgresql/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres \
  -c 'config_file=/etc/postgresql/postgresql.conf'

Resumiendo, configurando adecuadamente la persistencia, el acceso a la red y los ajustes de PostgreSQL, puedes crear un entorno PostgreSQL basado en Docker que funcione exactamente como quieres. La imagen base de postgres:latest es sólo eso, la base; hay muchas cosas que puedes ajustar.

En la siguiente sección, te mostraré cómo conectarte a la base de datos PostgreSQL que se ejecuta en Docker.

Conexión a PostgreSQL ejecutándose en Docker

Ahora que ya tienes tu contenedor PostgreSQL en marcha, el siguiente paso es conectarte a él. Al fin y al cabo, ¿por qué si no ibas a utilizar una base de datos?

En esta sección, te mostraré dos formas de conectarte a tu base de datos PostgreSQL en contenedor: utilizando la herramienta psql de la línea de comandos y utilizando una interfaz gráfica.

Como referencia, estoy ejecutando mi contenedor de base de datos con este comando:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres

Conexión mediante la herramienta de línea de comandos psql

La herramienta de línea de comandos psql es el cliente oficial de PostgreSQL que te permite interactuar con la base de datos mediante comandos SQL. 

Para conectarte a la base de datos PostgreSQL que se ejecuta en el contenedor desde tu máquina anfitriona, ejecuta el siguiente comando, pero recuerda actualizar los valores de usuario y base de datos:

docker exec -it postgres-db psql -U myuser -d mydatabase

Imagen 6 - Conexión a la base de datos Postgres mediante psql

Y ya está.

Si no estás seguro de lo que hace el comando, aquí tienes un sencillo desglose:

• docker exec -it postgres-db: Ejecuta un comando interactivo dentro del contenedor llamado "postgres-db".
• psql -U myuser -d mydatabase: Inicia psql, conectándote como "myuser" a la base de datos "mydatabase".

Si tienes problemas para conectarte, comprueba estos problemas comunes:

• Confirma que el contenedor se está ejecutando con docker ps.
• Verifica la asignación de puertos con docker port postgres-db.

Conexión mediante una herramienta GUI

Muchos desarrolladores prefieren utilizar una herramienta gráfica en lugar de una CLI, yo incluido. pgAdmin es una opción popular y gratuita para PostgreSQL, pero el proceso de conexión es similar para otras herramientas como DBeaver, DataGrip o TablePlus.

La instalación de pgAdmin es sencilla, así que no la trataré aquí.

Suponiendo que lo tengas instalado e iniciado, haz clic con el botón derecho del ratón en "Servidores" en el panel del navegador y selecciona "Registrar > Servidor". Ahora, en la pestaña General, dale un nombre a tu conexión:

Imagen 7 - Pestaña general de pgAdmin

A continuación, pasa a la pestaña "Conexión" e introduce estos datos:

• Nombre/dirección del host: localhost
• Puerto: 5432 (o el puerto que hayas mapeado)
• Base de datos de mantenimiento: mydatabase
• Nombre de usuario: myuser
• Contraseña: Tu contraseña PostgreSQL

Imagen 8 - Pestaña de conexión de pgAdmin

Por último, haz clic en "Guardar" para conectarte:

Imagen 9 - Conexión correcta

Una vez conectado, puedes empezar a trabajar con tu base de datos como lo harías con una instancia PostgreSQL instalada localmente o aprovisionada en la nube. Lo bueno de Docker es que, desde la perspectiva de tu aplicación o cliente, no hay ninguna diferencia: es sólo una base de datos PostgreSQL accesible en la dirección especificada.

>¿Necesitas acceso programático a tu base de datos PostgreSQL? Aprende a acceder a ella desde Python.

En la siguiente sección, explicaré cómo gestionar tu contenedor PostgreSQL, incluyendo su parada, arranque y monitorización.

Gestión de PostgreSQL en Docker

Una cosa es ejecutar una base de datos PostgreSQL en un contenedor y conectarse a ella, pero la gestión es un animal completamente distinto. Por suerte para ti, tienes un puñado de comandos a tu disposición.

En esta sección, cubriré operaciones esenciales como detener e iniciar tu contenedor, examinar los registros y mantener actualizada tu versión de PostgreSQL.

Detener, reiniciar y eliminar el contenedor PostgreSQL

Las herramientas de línea de comandos de Docker te permiten gestionar el ciclo de vida de tu contenedor PostgreSQL.

Para detener un contenedor PostgreSQL en ejecución, ejecuta lo siguiente:

docker stop postgres-db

Del mismo modo, ejecuta el siguiente comando cuando necesites volver a ponerlo en marcha:

docker start postgres-db

Imagen 10 - Parar e iniciar el contenedor

Si quieres reiniciar un contenedor en ejecución, lo que puede ser útil después de cambiar ciertas configuraciones, ejecuta el siguiente comando:

docker restart postgres-db

En los casos en que hayas terminado por completo con un contenedor y quieras eliminarlono busques más allá de estos dos comandos:

docker stop postgres-db
docker rm postgres-db

Recuerda que eliminar un contenedor no elimina tus datos si has configurado un volumen correctamente. Tus datos seguirán estando en el volumen postgres-data creado anteriormente.

Puedes comprobar que se ha eliminado el contenedor ejecutando

docker ps -a

La bandera -a muestra todos los contenedores, incluidos los parados. Si tu contenedor se ha eliminado correctamente, no aparecerá en esta lista:

Imagen 11 - Listado de todos los contenedores

Inspeccionar los troncos

Cuando algo va mal o quieres controlar la actividad de tu base de datos, comprobar los registros es un buen primer paso.

Ejecuta este comando para ver los registros de tu contenedor PostgreSQL:

docker logs postgres-db

Muestra todos los registros desde que se inició el contenedor. Para una gran cantidad de registros, puede que quieras limitar la salida, digamos, para incluir sólo los últimos 50 registros:

docker logs --tail 50 postgres-db

Imagen 12 - Visualización de los registros de los contenedores

Por otra parte, si quieres seguir los registros en tiempo realéste es el comando que debes ejecutar:

docker logs -f postgres-db

Imagen 13 - Visualización de los registros de los contenedores en tiempo real

Esto es especialmente útil para depurar problemas de conexión u observar la actividad de la base de datos durante el desarrollo.

Pulsa Ctrl+C/CMD+C para dejar de seguir los registros.

Actualizar PostgreSQL en Docker

Con el tiempo, querrás actualizar tu versión de PostgreSQL para obtener las últimas funciones, mejoras de rendimiento y parches de seguridad.

En el momento de escribir esto, postgres:17.4 es la última versión, pero supongamos teóricamente que se ha publicado postgres:17.5. Esta sección te mostrará cómo actualizar la versión de la base de datos en tu contenedor.

Para empezar, extrae la última imagen de PostgreSQL (o una versión específica):

docker pull postgres:17.5

A continuación, detén y elimina el contenedor existente:

docker stop postgres-db
docker rm postgres-db

Por último, crea un nuevo contenedor con el mismo volumen:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres:17.5

Como estás utilizando el mismo volumen (postgres-data), se conservarán todos tus datos existentes.

Si estás actualizando a una versión nueva importante (como de la 17 a la 18), PostgreSQL ejecutará automáticamente las migraciones de datos necesarias cuando se inicie. Ten en cuenta estas cosas:

• Las actualizaciones de versiones importantes deben probarse primero en un entorno que no sea de producción.
• Haz siempre una copia de seguridad de tu volumen de datos antes de actualizar una versión importante.
• Comprueba las notas de la versión de PostgreSQL para ver si hay cambios de última hora.

Para crear una copia de seguridad antes de actualizarejecuta el siguiente comando:

docker run --rm -v postgres-data:/data -v $(pwd):/backup postgres:17.4 \
  bash -c "pg_dumpall -U myuser > /backup/postgres_backup.sql"

Esto crea un archivo de copia de seguridad SQL en tu directorio actual que puedes utilizar para restaurar tus datos si algo va mal.

>Puede que encuentres útil nuestra Hoja de trucos sobre los fundamentos de PostgreSQL yy como referencia rápida mientras trabajas en Docker.

En la siguiente sección, cubriré las mejores prácticas para utilizar PostgreSQL en Docker, incluyendo consideraciones de seguridad y consejos de optimización.

Buenas prácticas para utilizar PostgreSQL en Docker

La flexibilidad de Docker conlleva responsabilidad. En esta sección, compartiré algunas buenas prácticas para asegurarme de que tu configuración de PostgreSQL en contenedores es fiable, segura y sigue los estándares del sector.

Mantén tus datos seguros con copias de seguridad periódicas

Independientemente de cómo ejecutes PostgreSQL, las copias de seguridad periódicas son imprescindibles. He mencionado las copias de seguridad en la sección anterior, pero aquí es donde voy a dar un paso más. 

La forma más sencilla de hacer una copia de seguridad de una base de datos PostgreSQL que se ejecuta en Docker es utilizando pg_dump:

docker exec -t postgres-db pg_dump -U myuser mydatabase > backup.sql

Imagen 14 - Copia de seguridad de PostgreSQL

Para realizar una copia de seguridad completa de todas las bases de datos, incluidos los roles y los tablespaces, utiliza pg_dumpall:

docker exec -t postgres-db pg_dumpall -U myuser > full_backup.sql

Imagen 15 - Copia de seguridad completa de la base de datos PostgreSQL

Esta imagen muestra sólo un par de comandos de copia de seguridad, ya que no es posible ajustarlo todo a la pantalla.

En automatizar tus copias de seguridadpuedes crear un sencillo script de shell y ejecutarlo con cron:

#!/bin/bash
# backup.sh
TIMESTAMP=$(date +"%Y%m%d")
BACKUP_DIR="/Users/dradecic/Documents/pg-backups"

# Make sure the backup directory exists
mkdir -p $BACKUP_DIR

# Create the backup
docker exec postgres-db pg_dumpall -U myuser | gzip > $BACKUP_DIR/postgres_$TIMESTAMP.sql.gz

# Remove backups older than 30 days
find $BACKUP_DIR -name "postgres_*.sql.gz" -mtime +30 -delete

Haz que el script sea ejecutable y ejecútalo:

chmod +x backup.sh

bash backup.sh

Imagen 16 - Ejecutar un script de copia de seguridad de una base de datos PostgreSQL

Para automatizar completamente la copia de seguridad, puedes añadir el script a tu crontab para que se ejecute diariamente:

0 3 * * * /path/to/backup.sh

Este programa ejecuta la copia de seguridad todos los días a las 3 de la madrugada, pero, por supuesto, puedes ajustar el horario y la frecuencia según necesites. 

>Echa un vistazo a miía completa sobre cron jobs para para saber más sobre esta útil herramienta de automatización.

Para entornos de producción, considera la posibilidad de almacenar las copias de seguridad fuera de las instalaciones o en la nube para la recuperación ante desastres.

Utilizar volúmenes con nombre para la persistencia de datos

Aunque antes he tratado brevemente los volúmenes, merece la pena revisarlos más a fondo.

Como regla general, nuncadebes ejecutar PostgreSQL en Docker sin un volumen correctamente configurado. Si lo haces, tus datos se perderán cuando se elimine el contenedor o cuando Docker realice operaciones de limpieza.

Utilizar volúmenes con nombre (en lugar de volúmenes anónimos) facilita mucho la copia de seguridad y la gestión de los datos:

# Create a named volume
docker volume create postgres-data

# Use it when running the container
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Aquí no hay nada nuevo.

Los volúmenes con nombre también son más fáciles de respaldar. Para crear una copia de seguridad de todo el volumen, ejecuta el siguiente comando:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data-backup.tar.gz /data

Esto creará un archivo postgres-data-backup.tar.gz en la misma carpeta desde la que has ejecutado el comando.

Ahora, para restaurar este volumen, ejecuta lo siguiente:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/postgres-data-backup.tar.gz --strip 1"

Eso es.

Asegurar PostgreSQL en Docker

Cuando se trata de bases de datos, la seguridad nunca debe ser una idea tardía. Esta subsección te guiará a través de algunas prácticas esenciales para asegurar tu contenedor PostgreSQL.

Utiliza contraseñas fuertes y únicas

Evita las contraseñas predeterminadas o débiles. Genera una contraseña fuerte y aleatoria para tu superusuario PostgreSQL:

export POSTGRES_PASSWORD=$(openssl rand -base64 32)
echo "$POSTGRES_PASSWORD" > postgres-password.txt

docker run --name postgres-db \
  -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Imagen 17 - Utilizar una contraseña segura

Guarda esta contraseña de forma segura, por ejemplo en un gestor de contraseñas o en un archivo de variables de entorno que no esté registrado en el control de versiones.

Restringir el acceso a la red

Por defecto, Docker expone el puerto PostgreSQL en todas las interfaces. Para mejorar la seguridad, especialmente en producción, restringe el acceso a localhost:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Utilizar una configuración PostgreSQL personalizada

Crea una configuración PostgreSQL más segura modificando parámetros como los que se indican a continuación:

# Require SSL
ssl = on
ssl_cert_file = '/etc/ssl/certs/ssl-cert-snakeoil.pem'
ssl_key_file = '/etc/ssl/private/ssl-cert-snakeoil.key'

# Limit connection attempts
max_connections = 100
authentication_timeout = 1min

# Restrict access
listen_addresses = 'localhost'

Monta este archivo de configuración al iniciar tu contenedor:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf \
  -v ./postgresql.conf:/var/lib/postgresql/data/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Actualiza regularmente tu imagen PostgreSQL

Mantén actualizada tu versión de PostgreSQL para obtener los últimos parches de seguridad:

docker pull postgres:latest
docker stop postgres-db
docker rm postgres-db
# Then recreate with the latest image

Estas prácticas recomendadas te permitirán crear un entorno PostgreSQL más fiable y seguro en Docker, adecuado tanto para casos de desarrollo como de producción.

En la siguiente sección, explicaré cómo solucionar los problemas más comunes a los que te puedes enfrentar al ejecutar PostgreSQL en Docker.

Resolución de problemas de PostgreSQL en Docker

Tarde o temprano, te encontrarás con problemas al ejecutar PostgreSQL en Docker. En esta sección trataré los problemas más comunes y sus soluciones, lo que te ahorrará tiempo y frustraciones por el camino.

Problemas comunes con los contenedores PostgreSQL

Un problema común al que se enfrentan muchos usuarios es que su contenedor sale inmediatamente después de iniciar. Si ése es tu caso, comprueba los registros para identificar el problema:

docker logs postgres-db

Tu error podría estar relacionado con problemas de permisos en los volúmenes montados. Si es así, verás un mensaje de registro similar:

initdb: could not change permissions of directory "/var/lib/postgresql/data": Operation not permitted

Para solucionar este problema, comprueba la propiedad y los permisos de tu volumen y luego corrígelo si es necesario:

# Check the ownership
docker run --rm -v postgres-data:/data alpine ls -la /data

# Fix the permissions
docker run --rm -v postgres-data:/data alpine chmod 700 /data

Otro problema común es la falta de variables de entorno necesarias. Un mensaje de registro típico cuando ocurre tiene este aspecto:

Database is uninitialized and superuser password is not specified

Para solucionarlo, asegúrate de que estás configurando la variable de entorno POSTGRES_PASSWORD necesaria -o cualquier otra variable de entorno, en realidad-:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

También es frecuente el error "El directorio de datos no está vacío pero faltan archivos PostgreSQL". Este es el mensaje de registro que probablemente verás:

PostgreSQL Database directory appears to contain a database; Skipping initialization

Seguido de errores sobre archivos que faltan.

Esto suele ocurrir cuando has montado un volumen que contiene archivos pero no una base de datos PostgreSQL válida. Puede que tengas que reinicializar utilizando un nuevo volumen:

docker volume create postgres-data-new
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data-new:/var/lib/postgresql/data \
  -d postgres

Resolver problemas de conectividad

Si no puedes conectarte a tu base de datos PostgreSQL que se ejecuta en un contenedor, empieza por confirmando que el contenedor se está ejecutando:

docker ps | grep postgres-db

Si no aparece, es posible que se haya bloqueado. Comprueba los registros como se ha descrito anteriormente.

Si aparece en la lista pero sigues sin poder conectarte, verifica la asignación de puertos:

docker port postgres-db

Deberías ver algo así:

Imagen 18 - Cartografía del puerto de contenedores

Si no es así, puede que tu asignación de puertos sea incorrecta. Vuelve a crear el contenedor con la opción -p adecuada.

Si sigues sin poder conectarte a la base de datos, es hora de comprobar la configuración de la conexión. Comprueba estos parámetros:

• Nombre de host: localhost o 127.0.0.1 (no el nombre del contenedor).
• Puerto: El puerto host de tu mapeo (normalmente 5432).
• Nombre de usuario: El valor de POSTGRES_USER (por defecto es "postgres").
• Contraseña: El valor de POSTGRES_PASSWORD.
• Base de datos: El valor de POSTGRES_DB (por defecto es el mismo que POSTGRES_USER).

Inténtalo de nuevo después de solucionar estos problemas. Si el problema persiste, debes probar la conectividad desde dentro del contenedor:

docker exec -it postgres-db psql -U postgres

Si esto funciona, el problema está en la asignación de puertos o en la red externa.

Por último, puedes comprobar si hay problemas con el cortafuegos. Puede que el cortafuegos de tu sistema esté bloqueando las conexiones al puerto PostgreSQL, así que compruébalo:

# Linux
sudo iptables -L | grep 5432

# macOS
sudo pfctl -sr | grep 5432

Comprobando estos problemas comunes, deberías ser capaz de identificar y resolver la mayoría de los problemas con PostgreSQL en Docker. Si sigues atascado, la documentación de PostgreSQL y Docker y los foros de la comunidad son recursos excelentes para solucionar problemas más específicos.

Resumiendo Base de datos PostgreSQL en Docker

Y ahí lo tienes: ¡la guía definitiva para configurar y ejecutar bases de datos PostgreSQL en Docker! He cubierto todo lo que necesitas saber para empezar, desde configurar tu primer contenedor hasta configurar, conectar y gestionar tu base de datos. 

Las opciones tradicionales de PostgreSQL, como instalar la base de datos localmente o aprovisionarla en la nube, son subóptimas o caras para fines de desarrollo. Docker salva esta distancia. No importa si lo utilizas para desarrollo local, pruebas o incluso entornos de producción, PostgreSQL en contenedor ofrece una flexibilidad y consistencia difíciles de superar.

Ahora estás más que preparado para integrar la base de datos Postgres en Docker en tus aplicaciones.

Si quieres profundizar más, te recomiendo estos cursos de DataCamp:

• Crear bases de datos PostgreSQL
• Introducción a Docker
• SQL para Administradores de Bases de Datos
• Funciones para Manipular Datos en PostgreSQL