Modo agente

Os backups via agente estão descontinuados. O Databasus agora executa backups físicos e PITR remotamente, com os backups nativos do PostgreSQL 17, sem nenhum agente instalado no servidor da base de dados. Leia o porquê e como os backups PITR funcionam agora.

O agente do Databasus permite backups físicos, backups incrementais, arquivamento de WAL e Point-in-Time Recovery (PITR) para bases de dados PostgreSQL.

Quando usar o agente

Para a maioria das bases de dados, os backups remotos são a opção mais simples. O Databasus se conecta diretamente à base de dados pela rede, executa backups lógicos com o pg_dump e não exige nenhum software adicional no servidor da base de dados. Os backups remotos funcionam tanto com bases gerenciadas na nuvem (RDS, Cloud SQL, Supabase) quanto com instâncias auto-hospedadas.

O agente foi pensado para cenários em que os backups remotos não bastam:

Recuperação de desastres com PITR: restaure para qualquer segundo entre backups, com perda de dados quase nula
Backups físicos: cópia no nível dos dados de todo o cluster, com backup e restauração mais rápidos para volumes grandes
Bases de dados não expostas publicamente: o agente se conecta ao Databasus por conexões de saída, então a base de dados nunca precisa de um endpoint público
Backups incrementais: arquivamento contínuo de segmentos WAL combinado com backups de base periódicos

Instalação guiada na interface

O Databasus mostra instruções interativas de instalação e restauração diretamente na interface. Ao abrir as configurações do agente de uma base de dados, todos os comandos já vêm preenchidos com os seus valores: arquitetura, ID da base de dados, token do agente, host do Databasus e tipo de implantação do PostgreSQL. Basta copiar cada comando e executá-lo no seu servidor.

A documentação abaixo cobre os mesmos passos, como referência e para quem prefere seguir um guia fora da interface.

Requisitos

PostgreSQL 15 ou mais recente
Linux (amd64 ou arm64)
Acesso de rede do agente à sua instância do Databasus (apenas de saída: a base de dados não precisa ser alcançável a partir do Databasus)

Instalação

Passo 1 — Baixar o agente

Baixe o binário do agente no servidor onde o PostgreSQL está rodando. Substitua <DATABASUS_HOST> pela URL da sua instância do Databasus e <ARCH> por amd64 ou arm64.

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

Passo 2 — Configurar o postgresql.conf

Adicione ou atualize estas configurações no seu postgresql.conf e depois reinicie o PostgreSQL.

Para instalações no host (substitua <WAL_QUEUE_DIR> pelo caminho real, por exemplo /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 instalações em Docker, o caminho do archive_command (/wal-queue) é o caminho dentro do container. Ele precisa corresponder ao destino do volume montado — veja o Passo 5.

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

Passo 3 — Configurar o pg_hba.conf

Adicione esta linha ao pg_hba.conf. Ela é necessária para o pg_basebackup fazer backups completos — não para replicação por streaming. Ajuste o endereço e o método de autenticação conforme necessário e depois recarregue o PostgreSQL.

host    replication   all   127.0.0.1/32   md5

Passo 4 — Conceder o privilégio de replicação

Este é um requisito do PostgreSQL para executar o pg_basebackup — não cria nenhuma réplica.

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

Passo 5 — Criar o diretório de fila de WAL

O PostgreSQL coloca aqui os segmentos WAL arquivados para o agente enviar.

mkdir -p /opt/databasus/wal-queue

Garanta que o PostgreSQL pode escrever no diretório e que o agente pode lê-lo:

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

Para instalações em Docker, o diretório da fila de WAL deve ser um volume compartilhado entre o container do PostgreSQL e o host. O agente lê os segmentos WAL pelo caminho do host, enquanto o PostgreSQL escreve no caminho do container via 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

Garanta que o diretório dentro do container é propriedade da conta postgres:

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

Passo 6 — Iniciar o agente

Substitua os marcadores em <ANGLE_BRACKETS> pelos seus valores reais.

PostgreSQL instalado no sistema (pg_basebackup disponível no 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 numa pasta específica (por exemplo /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 a porta do PostgreSQL dentro do container, normalmente 5432, e não a porta mapeada no 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

Depois da instalação

O agente fica rodando em segundo plano depois do start
Verificar o status: ./databasus-agent status
Ver os logs: databasus.log no diretório de trabalho
Parar o agente: ./databasus-agent stop

Restaurar a partir de um backup do agente

Restaure um backup físico ou incremental para um diretório de destino. Para Point-in-Time Recovery, adicione a opção --target-time para restaurar para um momento específico.

Passo 1 — Baixar o agente

Baixe o binário do agente no servidor onde você quer restaurar (mesmo comando do Passo 1 da instalação).

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

Passo 2 — Parar o PostgreSQL

O PostgreSQL deve estar parado antes da restauração. O diretório de destino deve estar vazio.

pg_ctl -D <PGDATA_DIR> stop

Para Docker:

docker stop <CONTAINER_NAME>

Passo 3 — Executar a restauração

Substitua <YOUR_AGENT_TOKEN> pelo token do seu agente e <PGDATA_DIR> pelo caminho de um diretório de dados PostgreSQL vazio.

Instalação no host:

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

Instalação em Docker (<HOST_PGDATA_PATH> é o caminho no host que será montado como o volume pgdata do container):

./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> no caminho PGDATA do container ao (re)criar o container do postgres. O caminho depende da versão principal: o PostgreSQL 18+ usa /var/lib/postgresql/<major>/docker; o PostgreSQL 17 e anteriores usam /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 Point-in-Time Recovery (PITR), adicione --target-time com uma data/hora em RFC 3339 (por exemplo 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>

Passo 4 — Ajustar o archive_command

O backup restaurado inclui a configuração original do archive_command. O PostgreSQL falhará ao arquivar segmentos WAL depois da recuperação, a menos que você faça uma de duas coisas:

Reconectar o agente: monte o diretório da fila de WAL e inicie o agente do Databasus na instância restaurada, igual à configuração original.
Desativar o arquivamento: se você ainda não precisa de backups contínuos, comente ou remova as configurações de arquivamento no postgresql.auto.conf:

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

Passo 5 — Iniciar o PostgreSQL

Inicie o PostgreSQL para começar a recuperação por WAL. Ele reproduzirá automaticamente os segmentos WAL.

pg_ctl -D <PGDATA_DIR> start

Para Docker:

docker start <CONTAINER_NAME>

Passo 6 — Limpeza

Quando a recuperação terminar, remova o diretório de restauração de WAL:

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

Como funciona

O agente do Databasus é um binário Go leve que executa dois processos em paralelo:

Streaming de WAL: coleta os segmentos WAL do diretório de fila a cada 10 segundos aproximadamente e os envia para o Databasus
Backups de base periódicos: executa o pg_basebackup no agendamento configurado para criar backups físicos completos do cluster

Durante a restauração, o agente baixa o backup de base e todos os segmentos WAL relevantes e depois configura o recovery.signal e o restore_command no postgresql.auto.conf. Quando o PostgreSQL inicia, ele reproduz os segmentos WAL até atingir o ponto de recuperação alvo.

O agente sempre inicia a conexão com o Databasus (de saída). O servidor da base de dados não precisa aceitar conexões de entrada vindas do Databasus, o que o torna adequado para redes privadas e ambientes com firewall.