CouchDB : utilisation en console

CouchDB n’a pas de client interactif dédié : l’API HTTP se pilote avec curl. Les exemples supposent un fichier ~/.netrc (voir Installation) ; sans lui, remplacer -n par -u admin.

Outils

sudo apt install curl jq

jq met en forme et filtre le JSON.

Alias et variable

export COUCH=http://127.0.0.1:5984
curl -n "$COUCH/"
curl -sn "$COUCH/_all_dbs" | jq .

Option `curl`	Rôle
`-n`	Lit les identifiants dans `~/.netrc`
`-s`	Silencieux (sans barre de progression)
`-X PUT`, `-X DELETE`	Méthode HTTP
`-H 'Content-Type: application/json'`	Type du corps (obligatoire pour envoyer du JSON)
`-d '{…}'` ou `-d @fichier.json`	Corps de la requête
`-i`	Affiche aussi les en-têtes (code de statut)
`-f`	Échoue sur un code d’erreur HTTP (utile en script)

Routes de base

Requête	Rôle
`GET /`	Informations et version
`GET /_up`	Le serveur est-il prêt ?
`GET /_all_dbs`	Liste des bases
`GET /_membership`	Nœuds de la grappe
`GET /_active_tasks`	Tâches en cours (compactions, indexations, réplications)
`GET /_node/_local/_stats`	Statistiques du nœud
`GET /_node/_local/_config`	Configuration en cours
`GET /_uuids?count=3`	Génère des identifiants uniques
`GET /_session`	Utilisateur courant

curl -sn "$COUCH/" | jq '{version, vendor}'
curl -sn "$COUCH/_session" | jq .
curl -sn "$COUCH/_uuids?count=2" | jq .
curl -sn "$COUCH/_active_tasks" | jq .

Créer, lire, supprimer : le cycle

curl -sn -X PUT "$COUCH/boutique"
curl -sn -X PUT "$COUCH/boutique/client-1" \
  -H 'Content-Type: application/json' \
  -d '{"nom":"Alice","email":"alice@exemple.com"}'
curl -sn "$COUCH/boutique/client-1" | jq .
curl -sn "$COUCH/boutique" | jq .

Réponse d’un enregistrement :

{ "ok": true, "id": "client-1", "rev": "1-967a00dff5e02add41819138abb3284d" }

La révision (rev) identifie la version du document : elle est nécessaire pour le modifier ou le supprimer (voir Bases et documents).

Codes de statut

Afficher uniquement le code :

curl -sn -o /dev/null -w '%{http_code}\n' "$COUCH/boutique/client-1"

Code	Sens
`200`	Succès
`201`	Créé (document ou base)
`202`	Accepté (traitement différé)
`304`	Non modifié (avec `If-None-Match`)
`400`	Requête invalide (JSON mal formé)
`401`	Non authentifié
`403`	Interdit
`404`	Introuvable
`409`	Conflit de révision
`412`	Base déjà existante (`PUT` d’une base)

Mettre en forme avec jq

curl -sn "$COUCH/boutique/_all_docs?include_docs=true" | jq '.rows[].doc'
curl -sn "$COUCH/boutique/_all_docs?include_docs=true" | jq -r '.rows[].doc | [.nom, .email] | @csv'
curl -sn "$COUCH/boutique/_all_docs" | jq '.total_rows'

Surveiller le serveur

curl -sn "$COUCH/_node/_local/_stats/couchdb/httpd" | jq .
curl -sn "$COUCH/_node/_local/_system" | jq '{uptime, memory}'
curl -sn "$COUCH/boutique" | jq '{doc_count, doc_del_count, sizes}'
sudo tail -n 50 /var/log/couchdb/couchdb.log

Script : vérifier le service

#!/bin/bash
set -euo pipefail
statut=$(curl -fsS http://127.0.0.1:5984/_up | jq -r .status)
[ "$statut" = "ok" ] || { echo "CouchDB indisponible" >&2; exit 1; }
echo "CouchDB prêt"

Interface Fauxton

Pour explorer visuellement, utiliser Fauxton (http://127.0.0.1:5984/_utils, via un tunnel SSH sur un serveur distant : voir Installation).

Dépannage

Symptôme	Piste
`{"error":"unauthorized"}`	Identifiants absents : `-n` ou `-u admin`
`{"error":"bad_request","reason":"invalid_json"}`	JSON mal formé : vérifier les guillemets (apostrophes autour du corps dans le shell)
`{"error":"bad_content_type"}`	En-tête `Content-Type: application/json` manquant
`{"error":"not_found","reason":"Database does not exist."}`	Nom de base incorrect
`curl: (7)`	Service arrêté
Caractères spéciaux dans l’URL	Encoder (`%2F` pour `/` dans un identifiant) ou utiliser `--data-urlencode`

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

Les commandes de cette page sont identiques sur les deux versions : elles dépendent de CouchDB, pas d’Ubuntu.

Pour aller plus loin

Référence de l’API
Suite : Bases et documents