veza/veza-backend-api/docs/runbooks/db_down.md

Runbook: Database Down / DB Pool Exhausted

Signal

Alertes déclenchées:

• VezaDBPoolHighUsage - DB pool > 80% (20/25 connexions)
• VezaDBPoolExhausted - DB pool épuisé (wait count augmente)
• /readyz retourne 503 Service Unavailable avec status: "not_ready"

Symptômes observables:

• Erreurs 5xx sur endpoints nécessitant la DB
• Logs: database connection failed, connection pool exhausted
• Métriques: veza_db_pool_open_connections proche de 25, veza_db_pool_wait_count_total augmente

Hypothèses

1. DB down - PostgreSQL ne répond plus
2. DB pool saturé - Trop de connexions ouvertes, pool épuisé
3. Réseau - Problème de connectivité entre app et DB
4. DB lente - Requêtes bloquantes, connexions non libérées

Vérifications

1. Vérifier l'état de la DB

# Depuis le serveur DB
sudo systemctl status postgresql
# ou
docker ps | grep postgres

# Tester connexion directe
psql -h localhost -U veza -d veza_db -c "SELECT 1;"

2. Vérifier métriques Prometheus

# Pool connexions
curl -s http://localhost:9090/api/v1/query?query=veza_db_pool_open_connections

# Wait count (doit être stable, pas augmenter)
curl -s http://localhost:9090/api/v1/query?query=rate(veza_db_pool_wait_count_total[5m])

# Connexions en cours d'utilisation
curl -s http://localhost:9090/api/v1/query?query=veza_db_pool_in_use

3. Vérifier logs application

# Chercher erreurs DB
grep -i "database\|connection\|pool" /var/log/veza-backend-api/*.log | tail -50

# Chercher requêtes lentes (si logging activé)
grep "slow query" /var/log/veza-backend-api/*.log

4. Vérifier connexions actives DB

-- Depuis psql
SELECT count(*) FROM pg_stat_activity WHERE datname = 'veza_db';
SELECT pid, usename, application_name, state, query_start, query 
FROM pg_stat_activity 
WHERE datname = 'veza_db' 
ORDER BY query_start;

Actions Correctives

Si DB down

1. Redémarrer PostgreSQL:

   sudo systemctl restart postgresql
   # ou
   docker restart veza-postgres
   

2. Vérifier logs PostgreSQL:

   tail -100 /var/log/postgresql/postgresql-*.log
   # ou
   docker logs veza-postgres --tail 100
   

3. Vérifier espace disque:

   df -h /var/lib/postgresql
   

4. Vérifier mémoire:

   free -h
   

Si DB pool saturé

1. Identifier requêtes bloquantes:

   SELECT pid, usename, application_name, state, wait_event_type, wait_event, query_start, query
   FROM pg_stat_activity
   WHERE datname = 'veza_db' AND state != 'idle'
   ORDER BY query_start;
   

2. Tuer requêtes bloquantes (si nécessaire):

   SELECT pg_terminate_backend(pid) 
   FROM pg_stat_activity 
   WHERE datname = 'veza_db' 
   AND state = 'active' 
   AND query_start < NOW() - INTERVAL '5 minutes';
   

3. Augmenter pool temporairement (si configurable):

   • Modifier internal/config/config.go:446 (MaxOpenConns)
   • Redémarrer application
   • ⚠️ Attention: Augmenter le pool peut masquer le problème réel

4. Vérifier connexions non fermées:

   • Auditer code pour defer db.Close() manquants
   • Vérifier transactions non commitées/rollbackées

Si réseau

1. Tester connectivité:

   telnet <DB_HOST> 5432
   # ou
   nc -zv <DB_HOST> 5432
   

2. Vérifier firewall:

   sudo iptables -L -n | grep 5432
   

3. Vérifier DNS:

   nslookup <DB_HOST>
   

Post-Mortem Notes

À documenter après résolution

• Cause racine: DB down / Pool saturé / Réseau / Autre
• Durée de l'incident: De [heure début] à [heure fin]
• Impact: Endpoints affectés, utilisateurs impactés
• Actions prises: Liste des actions correctives
• Actions préventives:
  • Augmenter monitoring DB pool
  • Ajouter alertes sur requêtes lentes
  • Auditer code pour connexions non fermées
  • Configurer connection pooling côté DB (PgBouncer)

Métriques à surveiller post-incident

• veza_db_pool_open_connections - Doit rester < 20
• veza_db_pool_wait_count_total - Doit rester stable
• veza_db_pool_in_use - Doit être < open_connections
• /readyz - Doit retourner 200 ready

Références

• Configuration DB pool: internal/config/config.go:446 (MaxOpenConns: 25)
• Health check: internal/handlers/health.go:124-140
• Métriques DB: internal/metrics/db_pool.go