Conceptos básicos de herramientas

10 ejemplos para crear un kit de herramientas de DBA con versiones fijadas en clústeres de PostgreSQL 18.4: herramientas de copia de seguridad, análisis de logs, control de hinchazón y asesoramiento que tu equipo puede reproducir en portátiles, entornos de staging y bastiones de producción.

Prerrequisitos

• Acceso SSH o kubectl exec a un host que pueda alcanzar Postgres (bastión o pod de depuración).
• Binarios cliente instalados en versiones documentadas en tu repositorio.
• Política de acceso de solo lectura a producción para los juniors; herramientas de escritura restringidas a los de guardia.

# tools/versions.env (confirma este archivo)
PG_VERSION=18.4
PGBACKREST_VERSION=2.55.0
PGBADGER_VERSION=12.4
PG_REPACK_VERSION=1.5.2
PSQL_CLIENT=18.4

Alcance: Esta sección cubre herramientas operativas, no drivers de aplicaciones. Consulta Conceptos básicos de psql para flujos de trabajo interactivos del cliente.

Ejemplos básicos

1. Kit de herramientas mínimo por rol

• Una herramienta por preocupación; evita agentes de copia de seguridad superpuestos en el mismo clúster
• RDS/Aurora gestionado: usa las APIs de copia de seguridad nativas; pgBackRest se aplica a clústeres autohospedados y algunas imágenes de VM

2. Verifica que las versiones del cliente coincidan con el servidor

psql "$DATABASE_URL" -c "SHOW server_version;"
psql --version
pgbackrest version
pgbadger --version

-- En psql
SELECT version();
SHOW server_version_num;  -- 180004 para 18.4

• La versión mayor del cliente debe coincidir con la versión mayor del servidor para la compatibilidad de pg_dump/pg_restore
• La deriva menor (cliente 18.3, servidor 18.4) generalmente está bien para consultas psql

3. Patrón de instalación en Linux Bastion

#!/usr/bin/env bash
set -euo pipefail
source tools/versions.env
 
# Ejemplo: pgBackRest desde paquete o versión fija de origen
sudo apt-get install -y "pgbackrest=${PGBACKREST_VERSION}*"
 
# pgbadger (Perl)
sudo apt-get install -y pgbadger
 
# Extensión pg_repack + CLI (el clúster debe ejecutar CREATE EXTENSION)
sudo apt-get install -y "postgresql-${PG_VERSION%%.*}-repack"

• Documenta los comandos de instalación en docs/runbooks/tooling.md
• Imágenes de contenedor: integra las versiones en Dockerfile; nunca uses apt install sin fijar en hosts de producción

4. Matriz de acceso a herramientas

| Herramienta     | Portátil de desarrollo | Bastión de staging | Bastión de producción | CI |
|-----------------|------------------------|--------------------|-----------------------|----|
| psql            | sí                     | sí                 | solo lectura          | trabajo de migración |
| pgBackRest      | no                     | sí (simulacro de restauración) | solo de guardia       | verificación de copia de seguridad |
| pgbadger        | sí (logs de muestra)   | sí                 | sí (leer logs)        | no |
| pg_repack       | solo local             | sí (ventana de cambio) | de guardia + ticket   | no |

• Las herramientas de escritura en producción requieren un ticket de cambio y emparejamiento para operadores primerizos
• CI ejecuta lint de migraciones y pgbackrest check contra un sandbox de restauración, no contra producción

5. Envío de logs para pgbadger

-- postgresql.conf (staging/producción)
ALTER SYSTEM SET log_destination = 'csvlog';
ALTER SYSTEM SET logging_collector = on;
ALTER SYSTEM SET log_min_duration_statement = '500ms';
ALTER SYSTEM SET log_line_prefix = '%m [%p] %u@%d ';
SELECT pg_reload_conf();

# Informe nocturno en el bastión
pgbadger /var/log/postgresql/postgresql-*.csv \
  -o /var/reports/pgbadger/$(date +%F) \
  --incremental

• pgbadger necesita formato de log CSV o estándar con líneas de duración
• Envía informes al almacenamiento de objetos; vincula consultas lentas a tickets

Relacionado: pgbadger

6. Límite de la herramienta de copia de seguridad

# Autohospedado: stanza de pgBackRest
pgbackrest --stanza=main info
pgbackrest --stanza=main check

# RDS: usa aws rds describe-db-snapshots (no pgBackRest)
aws rds describe-db-snapshots --db-instance-identifier myapp-prod

• Elige un sistema de copia de seguridad física por clúster
• El nombre de la stanza de pgBackRest coincide con el rol Patroni pg1 en topologías HA

Relacionado: pgBackRest, Conceptos básicos de PITR

7. Las herramientas de extensión necesitan aprobación de DBA

-- pg_repack requiere la extensión en cada base de datos
CREATE EXTENSION IF NOT EXISTS pg_repack;

• CREATE EXTENSION es un evento de gobernanza - rastréalo en la ADR de lista de permitidos de extensiones
• La versión de pg_repack debe coincidir con la versión mayor del servidor (extensión 18.x para PG 18)

Ejemplos intermedios

8. Diseño del directorio tools/ del monorepo

tools/
├── versions.env
├── bin/
│   ├── pg-health.sh
│   ├── run-pgbadger.sh
│   └── verify-backup.sh
└── README.md

#!/usr/bin/env bash
# tools/bin/pg-health.sh
set -euo pipefail
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -c "
SELECT datname, numbackends, xact_commit, blks_hit::float / NULLIF(blks_hit + blks_read, 0) AS cache_hit
FROM pg_stat_database
WHERE datname = current_database();"

• Los scripts usan set -euo pipefail y ON_ERROR_STOP=1
• El mismo script se ejecuta localmente contra Postgres de Docker y en pruebas de humo de staging

9. Lista de verificación de auditoría trimestral de herramientas

- [ ] versions.env coincide con server_version de producción
- [ ] pgbackrest check sale con 0 en todas las stanzas
- [ ] Informe de pgbadger generado en los últimos 7 días
- [ ] Extensión pg_repack presente solo donde se aprobó
- [ ] Sin cron de copia de seguridad duplicado (pg_basebackup Y pgBackRest)
- [ ] Paquetes del bastión coinciden con versions.env

• Adjunta los resultados de la auditoría al ticket de gobernanza
• Actualiza las herramientas después de la ventana de validación de la actualización menor de Postgres

10. Cuándo no añadir una herramienta

Preguntas frecuentes

Relacionado

• pgBackRest - copia de seguridad física y PITR
• pgbadger - informes de logs de consultas lentas
• pg_repack - recuperación de hinchazón en línea
• Mejores prácticas de herramientas esenciales - resumen del equipo de 25 elementos
• Conceptos básicos de extensiones - política de instalación de extensiones

Versiones de la pila: Esta página se escribió para PostgreSQL 18.4, pgBackRest 2.55+, pgBadger 12+, pg_repack 1.5+, y el cliente psql 18.4.