Copias de seguridad y restauración de PostgreSQL en Docker

pg_dump permite crear una copia lógica de una base de datos PostgreSQL sin detener el servidor. En un despliegue Docker, el comando puede ejecutarse dentro del contenedor y enviar su salida al host para almacenarla fuera del ciclo de vida del contenedor [1][2].

Los ejemplos usan volcados SQL en texto comprimidos con gzip o xz, como en un flujo sencillo de consola. La restauración escribe en la base de datos de destino: comprueba el nombre del servicio, las credenciales y el estado de la base antes de ejecutarla.

Preparar variables del entorno

Ejecuta los comandos desde el directorio del proyecto de Docker Compose o sustituye el servicio por el nombre real del contenedor. Define los valores según tu despliegue:

DB_SERVICE="database"
DB_NAME="<BASE_DE_DATOS>"
DB_USER="<USUARIO_POSTGRES>"
BACKUP_DIR="./backups"
mkdir -p "$BACKUP_DIR"

En los ejemplos siguientes se asume que el usuario puede leer la base indicada y que el directorio local tiene espacio suficiente. Protege el directorio de copias: un volcado puede contener información personal y datos de la aplicación.

Crear una copia con gzip

pg_dump escribe por defecto un script SQL en texto. Se puede comprimir directamente en el host canalizando la salida del servicio de PostgreSQL [1]:

set -o pipefail
BACKUP="$BACKUP_DIR/${DB_NAME}_$(date +%Y%m%d-%H%M%S).sql.gz"

docker compose exec -T "$DB_SERVICE" \
  pg_dump --username "$DB_USER" --dbname "$DB_NAME" \
  | gzip > "$BACKUP"

-T desactiva la asignación de una terminal pseudo-TTY. Es importante para que la salida binaria o comprimida no se altere al atravesar la tubería [2]. set -o pipefail permite que el shell detecte también un fallo de pg_dump, aunque gzip haya creado un archivo.

Alternativa con xz

Si xz está instalado en el host, puede usarse para comprimir el mismo volcado SQL:

set -o pipefail
BACKUP="$BACKUP_DIR/${DB_NAME}_$(date +%Y%m%d-%H%M%S).sql.xz"

docker compose exec -T "$DB_SERVICE" \
  pg_dump --username "$DB_USER" --dbname "$DB_NAME" \
  | xz -T4 -c > "$BACKUP"

El parámetro -T4 permite a xz usar hasta cuatro hilos. Ajusta el número a los recursos disponibles. La compresión no sustituye una copia separada ni demuestra que la restauración funcionará.

Validar el archivo

Comprueba que el archivo existe y que el compresor puede leerlo:

ls -lh "$BACKUP"
gzip -t "$BACKUP"  # para .gz
xz -t "$BACKUP"    # para .xz

Conserva además una política de retención y una copia fuera del host Docker. La prueba más fiable es restaurar periódicamente en una base aislada y verificar que la aplicación puede usar los datos.

Restaurar un volcado SQL comprimido

La restauración debe dirigirse a una base vacía o preparada para recibir el contenido del volcado. No canalices una copia sobre una base con datos que quieras conservar: el script puede recrear objetos y fallar ante objetos ya existentes. psql acepta SQL por entrada estándar; -v ON_ERROR_STOP=1 hace que detenga la ejecución ante un error SQL [3].

Desde gzip:

set -o pipefail
gzip -dc "$BACKUP" \
  | docker compose exec -T "$DB_SERVICE" \
      psql --username "$DB_USER" --dbname "$DB_NAME" -v ON_ERROR_STOP=1

Desde xz:

set -o pipefail
xz -dc "$BACKUP" \
  | docker compose exec -T "$DB_SERVICE" \
      psql --username "$DB_USER" --dbname "$DB_NAME" -v ON_ERROR_STOP=1

Haz una copia del destino antes de reemplazarlo. Una restauración en la base equivocada puede sobrescribir información o dejar una instalación incompleta.

Formato personalizado de pg_dump

Para bases grandes o cuando se necesite restaurar objetos seleccionados, pg_dump también ofrece un formato personalizado. Este formato puede comprimirse y se restaura con pg_restore, no con psql [1][4]:

set -o pipefail
BACKUP="$BACKUP_DIR/${DB_NAME}_$(date +%Y%m%d-%H%M%S).dump"

docker compose exec -T "$DB_SERVICE" \
  pg_dump --format=custom --username "$DB_USER" --dbname "$DB_NAME" \
  > "$BACKUP"

Restaura el archivo en una base de destino que hayas creado previamente:

docker compose exec -T "$DB_SERVICE" \
  pg_restore --username "$DB_USER" --dbname "$DB_NAME" \
  --exit-on-error < "$BACKUP"

Confirma que la versión de pg_dump es compatible con el servidor de origen y el servidor de destino. La documentación explica los límites de compatibilidad entre versiones mayores [1].

En resumen

• Ejecuta pg_dump en el servicio PostgreSQL y redirige su salida a un archivo del host.
• Desactiva el pseudo-TTY para que las tuberías no alteren la salida.
• Comprueba el archivo comprimido y ensaya su restauración fuera de producción.
• Restaura el SQL comprimido con psql; usa pg_restore para el formato personalizado.
• Verifica dos veces la base de destino y conserva otra copia antes de sobrescribir datos.

📚 Fuentes consultadas

1. pg_dump — PostgreSQL: documentación oficial
2. docker compose exec — Docker Docs
3. psql — PostgreSQL: documentación oficial
4. pg_restore — PostgreSQL: documentación oficial

Imagen