Modo agente

Las copias mediante agente están obsoletas. Databasus ahora ejecuta las copias físicas y PITR de forma remota usando las copias nativas de PostgreSQL 17, sin ningún agente instalado en el servidor de la base de datos. Lea por qué y cómo funcionan ahora las copias PITR.

El agente de Databasus habilita copias de seguridad físicas, copias incrementales, archivado de WAL y recuperación a un punto en el tiempo (PITR) para bases de datos PostgreSQL.

Cuándo usar el agente

Para la mayoría de las bases de datos, las copias remotas son la opción más simple. Databasus se conecta directamente a la base de datos por la red, realiza copias lógicas con pg_dump y no requiere ningún software adicional en el servidor de la base de datos. Las copias remotas funcionan tanto con bases de datos gestionadas en la nube (RDS, Cloud SQL, Supabase) como con instancias autoalojadas.

El agente está pensado para escenarios donde las copias remotas no bastan:

Recuperación ante desastres con PITR: restaure a cualquier segundo entre copias con una pérdida de datos casi nula
Copias físicas: copia a nivel de archivos de todo el clúster, con copia y restauración más rápidas para conjuntos de datos grandes
Bases de datos no expuestas públicamente: el agente se conecta de forma saliente a Databasus, así que la base de datos nunca necesita un punto de acceso público
Copias incrementales: archivado continuo de segmentos WAL combinado con copias base periódicas

Configuración guiada en la aplicación

Databasus ofrece instrucciones interactivas de instalación y restauración directamente en la interfaz. Al abrir la configuración del agente para una base de datos, todos los comandos vienen rellenados con sus valores concretos: arquitectura, ID de la base de datos, token del agente, host de Databasus y tipo de despliegue de PostgreSQL. Puede copiar cada comando y ejecutarlo en su servidor.

La documentación siguiente cubre los mismos pasos como referencia y para quienes prefieren seguir una guía fuera de la interfaz.

Requisitos

PostgreSQL 15 o superior
Linux (amd64 o arm64)
Acceso de red desde el agente a su instancia de Databasus (solo saliente; la base de datos no necesita ser accesible desde Databasus)

Instalación

Paso 1 — Descargar el agente

Descargue el binario del agente en el servidor donde se ejecuta PostgreSQL. Reemplace <DATABASUS_HOST> por la URL de su instancia de Databasus y <ARCH> por amd64 o arm64.

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Paso 2 — Configurar postgresql.conf

Añada o actualice estos ajustes en su postgresql.conf y luego reinicie PostgreSQL.

Para instalaciones en el host (reemplace <WAL_QUEUE_DIR> por la ruta real, p. ej. /opt/databasus/wal-queue):

wal_level = replica
archive_mode = on
archive_command = 'cp %p <WAL_QUEUE_DIR>/%f.tmp && mv <WAL_QUEUE_DIR>/%f.tmp <WAL_QUEUE_DIR>/%f'

Para instalaciones en Docker, la ruta del archive_command (/wal-queue) es la ruta dentro del contenedor. Debe coincidir con el destino del montaje del volumen; consulte el paso 5.

wal_level = replica
archive_mode = on
archive_command = 'cp %p /wal-queue/%f.tmp && mv /wal-queue/%f.tmp /wal-queue/%f'

Paso 3 — Configurar pg_hba.conf

Añada esta línea a pg_hba.conf. Es necesaria para que pg_basebackup pueda tomar copias completas, no para replicación en streaming. Ajuste la dirección y el método de autenticación según convenga y luego recargue PostgreSQL.

host    replication   all   127.0.0.1/32   md5

Paso 4 — Conceder el privilegio de replicación

Es un requisito de PostgreSQL para ejecutar pg_basebackup; no configura ninguna réplica.

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

Paso 5 — Crear el directorio de la cola de WAL

PostgreSQL deja aquí los archivos de WAL archivados para que el agente los suba.

mkdir -p /opt/databasus/wal-queue

Asegúrese de que PostgreSQL pueda escribir en el directorio y el agente pueda leerlo:

chown postgres:postgres /opt/databasus/wal-queue
chmod 755 /opt/databasus/wal-queue

Para instalaciones en Docker, el directorio de la cola de WAL debe ser un volumen compartido entre el contenedor de PostgreSQL y el host. El agente lee los archivos WAL desde la ruta del host, mientras que PostgreSQL escribe en la ruta del contenedor mediante archive_command.

# In your docker run command:
docker run ... -v /opt/databasus/wal-queue:/wal-queue ...

# Or in docker-compose.yml:
volumes:
  - /opt/databasus/wal-queue:/wal-queue

Asegúrese de que el directorio dentro del contenedor pertenezca al usuario postgres:

# Inside the container (or via docker exec):
chown postgres:postgres /wal-queue

Paso 6 — Iniciar el agente

Reemplace los marcadores entre <ANGLE_BRACKETS> por sus valores reales.

PostgreSQL instalado en el sistema (pg_basebackup disponible en el PATH):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-wal-dir=/opt/databasus/wal-queue

PostgreSQL en una carpeta concreta (p. ej. /usr/lib/postgresql/17/bin):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \
  --pg-wal-dir=/opt/databasus/wal-queue

Docker (use el puerto de PostgreSQL dentro del contenedor, normalmente 5432, no el puerto mapeado al host):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=docker \
  --pg-docker-container-name=<CONTAINER_NAME> \
  --pg-wal-dir=/opt/databasus/wal-queue

Después de la instalación

El agente sigue ejecutándose en segundo plano tras start
Comprobar el estado: ./databasus-agent status
Ver los registros: databasus.log en el directorio de trabajo
Detener el agente: ./databasus-agent stop

Restaurar desde una copia del agente

Restaure una copia física o incremental en un directorio de destino. Para la recuperación a un punto en el tiempo, añada la opción --target-time para restaurar a un momento concreto.

Paso 1 — Descargar el agente

Descargue el binario del agente en el servidor donde quiere restaurar (el mismo comando que en el paso 1 de la instalación).

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Paso 2 — Detener PostgreSQL

PostgreSQL debe estar detenido antes de restaurar. El directorio de destino debe estar vacío.

pg_ctl -D <PGDATA_DIR> stop

Para Docker:

docker stop <CONTAINER_NAME>

Paso 3 — Ejecutar la restauración

Reemplace <YOUR_AGENT_TOKEN> por su token de agente y <PGDATA_DIR> por la ruta a un directorio de datos de PostgreSQL vacío.

Instalación en el host:

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR>

Instalación en Docker (<HOST_PGDATA_PATH> es la ruta en el host que se montará como el volumen pgdata del contenedor):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --pg-type=docker \
  --target-dir=<HOST_PGDATA_PATH>

Monte <HOST_PGDATA_PATH> en la ruta PGDATA del contenedor al (re)crear el contenedor de postgres. La ruta depende de la versión mayor: PostgreSQL 18+ usa /var/lib/postgresql/<major>/docker; PostgreSQL 17 y anteriores usan /var/lib/postgresql/data.

# PostgreSQL 17 and earlier
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/data postgres:17

# PostgreSQL 18+
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/18/docker postgres:18

Para la recuperación a un punto en el tiempo (PITR), añada --target-time con una marca de tiempo RFC 3339 (p. ej. 2025-01-15T14:30:00Z):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR> \
  --target-time=<RFC3339_TIMESTAMP>

Paso 4 — Gestionar archive_command

La copia restaurada incluye la configuración original de archive_command. PostgreSQL fallará al archivar los WAL tras la recuperación, a menos que haga una de estas dos cosas:

Volver a conectar el agente: monte el directorio de la cola de WAL e inicie el agente de Databasus en la instancia restaurada, igual que en la configuración original.
Desactivar el archivado: si todavía no necesita copias continuas, comente o restablezca los ajustes de archivado en postgresql.auto.conf:

# In <PGDATA_DIR>/postgresql.auto.conf, remove or comment out:
# archive_mode = on
# archive_command = '...'

Paso 5 — Iniciar PostgreSQL

Inicie PostgreSQL para comenzar la recuperación de WAL. Reproducirá los segmentos WAL automáticamente.

pg_ctl -D <PGDATA_DIR> start

Para Docker:

docker start <CONTAINER_NAME>

Paso 6 — Limpiar

Una vez completada la recuperación, elimine el directorio de restauración de WAL:

rm -rf <PGDATA_DIR>/databasus-wal-restore/

Cómo funciona

El agente de Databasus es un binario ligero escrito en Go que ejecuta dos procesos concurrentes:

Streaming de WAL: recoge los archivos de segmentos WAL del directorio de la cola aproximadamente cada 10 segundos y los sube a Databasus
Copias base periódicas: ejecuta pg_basebackup según el horario configurado para crear copias físicas completas del clúster de la base de datos

Durante la restauración, el agente descarga la copia base y todos los segmentos WAL pertinentes, y luego configura recovery.signal y restore_command en postgresql.auto.conf. Al arrancar, PostgreSQL reproduce los segmentos WAL hasta alcanzar el punto de recuperación objetivo.

El agente siempre inicia la conexión hacia Databasus (saliente). El servidor de la base de datos no necesita aceptar conexiones entrantes desde Databasus, lo que lo hace adecuado para redes privadas y entornos con cortafuegos.