Mode agent

Les sauvegardes par agent sont obsolètes. Databasus exécute désormais les sauvegardes physiques et PITR à distance grâce aux sauvegardes natives de PostgreSQL 17, sans aucun agent installé sur le serveur de base de données. Découvrez pourquoi, et comment les sauvegardes PITR fonctionnent désormais.

L'agent Databasus permet les sauvegardes physiques, les sauvegardes incrémentales, l'archivage des WAL et la restauration à un instant donné (PITR) pour les bases PostgreSQL.

Quand utiliser l'agent

Pour la plupart des bases, les sauvegardes distantes sont l'option la plus simple. Databasus se connecte directement à la base via le réseau, effectue des sauvegardes logiques avec pg_dump et ne demande aucun logiciel supplémentaire sur le serveur de base de données. Les sauvegardes distantes fonctionnent aussi bien avec les bases managées dans le cloud (RDS, Cloud SQL, Supabase) qu'avec les instances auto-hébergées.

L'agent est conçu pour les scénarios où les sauvegardes distantes ne suffisent pas :

  • Reprise après sinistre avec PITR : restaurez à n'importe quelle seconde entre deux sauvegardes, avec une perte de données quasi nulle
  • Sauvegardes physiques : copie au niveau fichier de l'ensemble du cluster, sauvegarde et restauration plus rapides pour les gros volumes
  • Bases non exposées publiquement : l'agent se connecte en sortie vers Databasus, la base n'a donc jamais besoin d'un point d'accès public
  • Sauvegardes incrémentales : archivage continu des segments WAL combiné à des sauvegardes de base périodiques

Configuration guidée dans l'application

Databasus fournit des instructions interactives d'installation et de restauration directement dans l'interface. Quand vous ouvrez les réglages de l'agent pour une base, toutes les commandes sont pré-remplies avec vos valeurs : architecture, identifiant de la base, jeton d'agent, hôte Databasus et type de déploiement PostgreSQL. Vous pouvez copier chaque commande et l'exécuter sur votre serveur.

La documentation ci-dessous couvre les mêmes étapes, en guise de référence et pour ceux qui préfèrent suivre un guide en dehors de l'interface.

Prérequis

  • PostgreSQL 15 ou plus récent
  • Linux (amd64 ou arm64)
  • Accès réseau de l'agent vers votre instance Databasus (en sortie uniquement : la base n'a pas besoin d'être joignable depuis Databasus)

Installation

Étape 1 — Télécharger l'agent

Téléchargez le binaire de l'agent sur le serveur où s'exécute PostgreSQL. Remplacez <DATABASUS_HOST> par l'URL de votre instance Databasus et <ARCH> par amd64 ou arm64.

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

Étape 2 — Configurer postgresql.conf

Ajoutez ou mettez à jour ces réglages dans votre postgresql.conf, puis redémarrez PostgreSQL.

Pour les installations sur l'hôte (remplacez <WAL_QUEUE_DIR> par le chemin réel, par ex. /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'

Pour les installations Docker, le chemin de archive_command (/wal-queue) est le chemin à l'intérieur du conteneur. Il doit correspondre à la cible du montage de volume (voir l'étape 5).

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

Étape 3 — Configurer pg_hba.conf

Ajoutez cette ligne dans pg_hba.conf. Elle est requise pour que pg_basebackup puisse faire des sauvegardes complètes, pas pour la réplication en streaming. Ajustez l'adresse et la méthode d'authentification si nécessaire, puis rechargez PostgreSQL.

host    replication   all   127.0.0.1/32   md5

Étape 4 — Accorder le privilège de réplication

C'est une exigence de PostgreSQL pour exécuter pg_basebackup : cela ne met pas en place un réplica.

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

Étape 5 — Créer le répertoire de file d'attente WAL

PostgreSQL y dépose les fichiers d'archive WAL que l'agent envoie ensuite.

mkdir -p /opt/databasus/wal-queue

Assurez-vous que PostgreSQL peut écrire dans ce répertoire et que l'agent peut le lire :

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

Pour les installations Docker, le répertoire de file d'attente WAL doit être un volume partagé entre le conteneur PostgreSQL et l'hôte. L'agent lit les fichiers WAL depuis le chemin de l'hôte, tandis que PostgreSQL écrit dans le chemin du conteneur 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

Vérifiez que le répertoire à l'intérieur du conteneur appartient à l'utilisateur postgres :

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

Étape 6 — Démarrer l'agent

Remplacez les valeurs entre <ANGLE_BRACKETS> par vos valeurs réelles.

PostgreSQL installé au niveau du système (pg_basebackup disponible dans le 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 dans un dossier spécifique (par ex. /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 (utilisez le port PostgreSQL à l'intérieur du conteneur, en général 5432, et non le port mappé sur l'hôte) :

./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

Après l'installation

  • L'agent s'exécute en arrière-plan après start
  • Vérifier le statut : ./databasus-agent status
  • Consulter les journaux : databasus.log dans le répertoire de travail
  • Arrêter l'agent : ./databasus-agent stop

Restaurer depuis une sauvegarde de l'agent

Restaurez une sauvegarde physique ou incrémentale vers un répertoire cible. Pour la restauration à un instant donné, ajoutez l'option --target-time afin de restaurer à un moment précis.

Étape 1 — Télécharger l'agent

Téléchargez le binaire de l'agent sur le serveur où vous voulez restaurer (même commande que l'étape 1 de l'installation).

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

Étape 2 — Arrêter PostgreSQL

PostgreSQL doit être arrêté avant la restauration. Le répertoire cible doit être vide.

pg_ctl -D <PGDATA_DIR> stop

Pour Docker :

docker stop <CONTAINER_NAME>

Étape 3 — Lancer la restauration

Remplacez <YOUR_AGENT_TOKEN> par votre jeton d'agent et <PGDATA_DIR> par le chemin d'un répertoire de données PostgreSQL vide.

Installation sur l'hôte :

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

Installation Docker (<HOST_PGDATA_PATH> est le chemin sur l'hôte qui sera monté comme volume pgdata du conteneur) :

./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>

Montez <HOST_PGDATA_PATH> sur le chemin PGDATA du conteneur lors de la (re)création du conteneur postgres. Le chemin dépend de la version majeure : PostgreSQL 18+ utilise /var/lib/postgresql/<major>/docker ; PostgreSQL 17 et antérieurs utilisent /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

Pour la restauration à un instant donné (PITR), ajoutez --target-time avec un horodatage RFC 3339 (par ex. 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>

Étape 4 — Gérer archive_command

La sauvegarde restaurée contient la configuration archive_command d'origine. Après la récupération, PostgreSQL échouera à archiver les fichiers WAL, sauf si vous faites l'un des deux :

  • Rattacher l'agent : montez le répertoire de file d'attente WAL et démarrez l'agent Databasus sur l'instance restaurée, comme lors de l'installation d'origine.
  • Désactiver l'archivage : si vous n'avez pas encore besoin de sauvegardes continues, commentez ou réinitialisez les réglages d'archivage dans postgresql.auto.conf :
# In <PGDATA_DIR>/postgresql.auto.conf, remove or comment out:
# archive_mode = on
# archive_command = '...'

Étape 5 — Démarrer PostgreSQL

Démarrez PostgreSQL pour lancer la récupération des WAL. Il rejouera automatiquement les segments WAL.

pg_ctl -D <PGDATA_DIR> start

Pour Docker :

docker start <CONTAINER_NAME>

Étape 6 — Nettoyer

Une fois la récupération terminée, supprimez le répertoire de restauration des WAL :

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

Comment ça marche

L'agent Databasus est un binaire Go léger qui exécute deux processus concurrents :

  • Streaming des WAL : il récupère les segments WAL dans le répertoire de file d'attente environ toutes les 10 secondes et les envoie vers Databasus
  • Sauvegardes de base périodiques : il exécute pg_basebackup selon le planning configuré pour créer des sauvegardes physiques complètes du cluster

Pendant la restauration, l'agent télécharge la sauvegarde de base et tous les segments WAL nécessaires, puis configure recovery.signal et restore_command dans postgresql.auto.conf. Au démarrage, PostgreSQL rejoue les segments WAL jusqu'au point de récupération cible.

L'agent initie toujours la connexion vers Databasus (en sortie). Le serveur de base de données n'a pas besoin d'accepter de connexions entrantes depuis Databasus, ce qui le rend adapté aux réseaux privés et aux environnements derrière un pare-feu.