CouchDB : sauvegarde et réplication

CouchDB offre deux approches : copier les fichiers de données (sauvegarde physique) ou répliquer les bases (copie logique, via l’API).

1. Sauvegarde physique des fichiers

Les bases sont des fichiers .couch sous /opt/couchdb/data. Pour une copie cohérente, arrêter le service (ou prendre un instantané du disque) :

sudo systemctl stop couchdb
sudo tar -czf /var/backups/couchdb-$(date +%F).tar.gz -C /opt/couchdb data /opt/couchdb/etc/local.d /opt/couchdb/etc/local.ini
sudo systemctl start couchdb
sha256sum /var/backups/couchdb-*.tar.gz

Sauvegarder aussi la configuration (local.ini, local.d/) : elle contient les empreintes des mots de passe administrateurs, donc protéger la sauvegarde (chmod 600, dossier restreint).

Restaurer

sudo systemctl stop couchdb
sudo tar -xzf /var/backups/couchdb-2026-01-01.tar.gz -C /opt/couchdb
sudo chown -R couchdb:couchdb /opt/couchdb/data
sudo systemctl start couchdb
curl -sn http://127.0.0.1:5984/_all_dbs

Les fichiers de data/ (dossiers shards/, fichiers _dbs.couch, _nodes.couch) doivent être restaurés ensemble.

2. Réplication vers une base de sauvegarde

La réplication copie les documents d’une base vers une autre (locale ou distante), de façon incrémentale :

curl -sn -X POST "$COUCH/_replicate" -H 'Content-Type: application/json' -d '{
  "source": "boutique",
  "target": "boutique-sauvegarde",
  "create_target": true
}' | jq .

Vers un autre serveur (HTTPS, compte dédié aux sauvegardes) :

curl -sn -X POST "$COUCH/_replicate" -H 'Content-Type: application/json' -d '{
  "source": "boutique",
  "target": { "url": "https://secours.exemple.com/boutique", "auth": { "basic": { "username": "replication", "password": "<mot-de-passe>" } } },
  "create_target": true
}'

La réplication transmet les documents et leurs révisions, pas les anciennes versions déjà compactées. Elle peut être répétée : seules les nouveautés sont copiées.

Réplication permanente : `_replicator`

Pour une réplication qui survit aux redémarrages :

curl -sn -X PUT "$COUCH/_replicator/boutique-vers-secours" -H 'Content-Type: application/json' -d '{
  "source": "boutique",
  "target": "https://replication:<mot-de-passe>@secours.exemple.com/boutique",
  "continuous": true,
  "create_target": true
}'
curl -sn "$COUCH/_scheduler/jobs" | jq '.jobs[] | {id, database, source, target}'
curl -sn "$COUCH/_scheduler/docs" | jq '.docs[] | {id, state}'

continuous: true maintient la copie à jour en continu. L’état se lit dans _scheduler/docs (running, crashing, failed).

Le mot de passe dans le document _replicator est stocké en clair dans la base _replicator (lisible par les administrateurs) : utiliser un compte dédié aux droits limités (membre en lecture/écriture de la base cible uniquement).

3. Export logique en JSON

Pour une petite base, un export lisible et portable :

curl -sn "$COUCH/boutique/_all_docs?include_docs=true&attachments=false" \
  | jq '{docs: [.rows[].doc | select(._id | startswith("_design/") | not)]}' \
  > boutique-$(date +%F).json
jq '.docs | length' boutique-*.json

Les documents de conception se sauvegardent à part :

curl -sn "$COUCH/boutique/_all_docs?startkey=\"_design/\"&endkey=\"_design0\"&include_docs=true" \
  | jq '{docs: [.rows[].doc]}' > boutique-conception.json

Restaurer un export

curl -sn -X PUT "$COUCH/boutique-restauree"
# retirer les _rev pour réécrire des documents neufs
jq '{docs: [.docs[] | del(._rev)]}' boutique-2026-01-01.json \
  | curl -sn -X POST "$COUCH/boutique-restauree/_bulk_docs" -H 'Content-Type: application/json' -d @- \
  | jq 'map(select(.error))'

La dernière commande affiche les documents en erreur. Les pièces jointes ne sont pas dans cet export : pour des bases avec pièces jointes, préférer la copie de fichiers ou la réplication.

Sauvegarde automatique avec systemd

Script /usr/local/bin/sauvegarde-couchdb :

#!/bin/bash
set -euo pipefail
dest=/var/backups/couchdb
mkdir -p "$dest"
stamp=$(date +%F)
for base in boutique clients; do
  curl -fsS --netrc-file /root/.netrc "http://127.0.0.1:5984/$base/_all_docs?include_docs=true" \
    | gzip > "$dest/$base-$stamp.json.gz"
done
find "$dest" -name '*.json.gz' -mtime +14 -delete

sudo chmod 700 /usr/local/bin/sauvegarde-couchdb

Service et minuteur systemd : voir systemd : minuteurs (ExecStart=/usr/local/bin/sauvegarde-couchdb, OnCalendar=*-*-* 03:00:00). Le fichier /root/.netrc contient un compte lecteur : chmod 600.

Mise à jour de CouchDB

Sauvegarder (fichiers et configuration).
Lire les notes de version et les changements cassants.
sudo apt update && sudo apt install --only-upgrade couchdb.
curl -sn http://127.0.0.1:5984/ : vérifier la version, puis les bases et les vues.

Après une montée de version majeure, les index de vues peuvent être reconstruits : surveiller _active_tasks.

Règles de sauvegarde

Appliquer la règle 3-2-1 : 3 copies, 2 supports, 1 hors du serveur.
Tester la restauration régulièrement sur une machine de test.
Surveiller la réplication (_scheduler/docs) et l’espace disque.
Protéger les sauvegardes (elles contiennent les données et la configuration).

Dépannage

Symptôme	Piste
`{"error":"unauthorized"}` à la réplication	Compte de la source ou de la cible incorrect ou sans droits
`{"error":"db_not_found"}` sur la cible	Ajouter `create_target: true` ou créer la base
Réplication en `crashing`	`_scheduler/docs` indique la cause : réseau, droits, certificat
La restauration de fichiers échoue au démarrage	Droits (`chown couchdb:couchdb`), fichiers `_dbs.couch` et `shards/` restaurés ensemble
`409 conflict` à la restauration JSON	Retirer les `_rev` (`del(._rev)`) ou restaurer dans une base vide
Disque plein pendant la copie	Compaction préalable, copie vers un autre volume

Ubuntu 24.04 et 26.04 : différences à connaître

Les méthodes sont identiques. Un fichier de données CouchDB est portable d’une machine à l’autre s’il est lu par la même version majeure de CouchDB.

Pour aller plus loin

Réplication
Retour : Installation