Backup Automation Toolkit

Toolkit reproducible para automatizar respaldos y pruebas de recuperación de PostgreSQL mediante Python y Docker Compose.

Funciones

• Generación de respaldos PostgreSQL en formato personalizado comprimido.
• Archivos temporales y renombrado atómico para evitar copias incompletas.
• Checksums SHA-256.
• Verificación mediante pg_restore --list.
• Restauración automática en una base de datos de pruebas.
• Política de retención configurable.
• Logs persistentes.
• Reportes finales en JSON y Markdown.
• Scheduler opcional.
• Base PostgreSQL de demostración con datos iniciales.
• Pruebas unitarias y GitHub Actions.

Requisitos

• Docker Desktop o Docker Engine con Compose.
• make es opcional; todos los comandos tienen equivalente con Docker Compose.

Inicio rápido

Windows PowerShell

Copy-Item .env.example .env
docker compose up -d postgres
docker compose --profile tools run --rm backup run-all

Linux, macOS o WSL

cp .env.example .env
docker compose up -d postgres
docker compose --profile tools run --rm backup run-all

El último comando realiza el flujo completo:

1. genera el respaldo;
2. calcula SHA-256;
3. verifica el archivo;
4. restaura en app_db_restore_test;
5. elimina respaldos antiguos;
6. genera reportes.

Comandos

# Levantar PostgreSQL
make up

# Crear respaldo y aplicar retención
make backup

# Verificar el respaldo más reciente
make verify

# Restaurar el respaldo más reciente en la base de prueba
make restore

# Ejecutar el proceso completo
make run-all

# Listar respaldos
make status

# Activar respaldos programados
make scheduler

# Ejecutar pruebas unitarias
make test

Sin make:

docker compose --profile tools run --rm backup backup
docker compose --profile tools run --rm backup verify --latest
docker compose --profile tools run --rm backup restore --latest
docker compose --profile tools run --rm backup status

Configuración

Las variables principales se encuentran en .env:

Variable	Uso	Valor de ejemplo
PGDATABASE	Base que se respaldará	app_db
BACKUP_RETENTION	Número máximo de copias	5
RESTORE_TEST_DB	Destino de recuperación de prueba	app_db_restore_test
BACKUP_INTERVAL_SECONDS	Intervalo del scheduler	86400
DROP_TEST_DB_AFTER_RESTORE	Eliminar la base de prueba después de validar	false

No se debe subir el archivo .env al repositorio.

Archivos generados

backups/
├── app_db_AAAAMMDDTHHMMSSZ.dump
├── app_db_AAAAMMDDTHHMMSSZ.dump.sha256
└── app_db_AAAAMMDDTHHMMSSZ.dump.json

logs/
└── backup-tool.log

reports/
├── backup_report_AAAAMMDDTHHMMSSZ.json
└── backup_report_AAAAMMDDTHHMMSSZ.md

Estructura

backup-automation-toolkit/
├── backup_tool/
│   ├── cli.py
│   ├── config.py
│   ├── scheduler.py
│   ├── service.py
│   └── utils.py
├── docker/init/
├── docs/
├── tests/
├── compose.yaml
├── Dockerfile
├── Makefile
└── README.md

Seguridad

Este repositorio usa credenciales únicamente para demostración local. Para un entorno real se deben usar secretos externos, una cuenta PostgreSQL con privilegios mínimos, almacenamiento cifrado y copias fuera del servidor de origen.

Alcance

El proyecto demuestra respaldos lógicos con pg_dump. No sustituye estrategias empresariales como replicación, archivado continuo de WAL, recuperación a un punto en el tiempo ni copias externas verificadas.

Autor

Josué Isaí Sánchez Santos
Ingeniero en Sistemas Computacionales

Licencia

MIT.