From 83b7e8f372e4ce8dc6641c3eb4c76f8647dd8f02 Mon Sep 17 00:00:00 2001
From: Apple <apple@MacBook-Pro.local>
Date: Wed, 3 Dec 2025 10:00:11 -0800
Subject: [PATCH] docs: Add database stability fix documentation

---
 docs/DB_STABILITY_FIX.md | 115 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/DB_STABILITY_FIX.md

diff --git a/docs/DB_STABILITY_FIX.md b/docs/DB_STABILITY_FIX.md
new file mode 100644
index 00000000..4198e4a4
--- /dev/null
+++ b/docs/DB_STABILITY_FIX.md
@@ -0,0 +1,115 @@
+# Виправлення проблеми з періодичною втратою даних
+
+## Проблема
+
+Дані в базі даних "відвалюються" через деякий час (щоденна помилка). PostgreSQL контейнер перезапускається і втрачає дані.
+
+## Причини
+
+1. **PostgreSQL не завершується коректно**: Логи показують "database system was interrupted; last known up at"
+2. **Відсутність автоматичного відновлення**: Немає механізму для автоматичного відновлення даних
+3. **Недостатні налаштування PostgreSQL**: Відсутні налаштування для правильного завершення роботи
+
+## Виправлення
+
+### 1. Покращено конфігурацію PostgreSQL
+
+**`docker-compose.db.yml`**:
+- Додано `command` з налаштуваннями для правильного завершення
+- Додано `checkpoint_timeout=15min` для частіших checkpoint'ів
+- Додано `wal_level=replica` та `max_wal_size=1GB` для кращої персистентності
+
+### 2. Створено скрипт моніторингу
+
+**`scripts/monitor-db-stability.sh`**:
+- Автоматично перевіряє стан БД кожні 5 хвилин
+- Виявляє втрату даних
+- Автоматично відновлює з бекапу
+- Застосовує міграції та синхронізує агентів
+
+### 3. Налаштовано автоматичний моніторинг
+
+**Cron job** (кожні 5 хвилин):
+```bash
+*/5 * * * * /opt/microdao-daarion/scripts/monitor-db-stability.sh >> /var/log/db-stability-monitor.log 2>&1
+```
+
+### 4. Існуючі механізми
+
+- **Health check**: `scripts/db-health-check.sh` (кожні 30 хвилин)
+- **Backups**: Автоматичні бекапи кожні 12 годин
+- **Migrations**: Автоматичне застосування при виявленні проблем
+
+## Використання
+
+### Перевірити стан вручну
+
+```bash
+cd /opt/microdao-daarion
+bash scripts/monitor-db-stability.sh
+```
+
+### Перевірити логи моніторингу
+
+```bash
+tail -f /var/log/db-stability-monitor.log
+```
+
+### Перевірити cron
+
+```bash
+crontab -l | grep monitor-db-stability
+```
+
+## Процес відновлення
+
+Коли монітор виявляє втрату даних:
+
+1. Перевіряє наявність бекапу
+2. Відновлює БД з бекапу
+3. Застосовує всі міграції
+4. Синхронізує агентів НОДА2
+5. Видаляє тестових агентів
+6. Логує результат
+
+## Налаштування PostgreSQL
+
+Додані параметри для кращої персистентності:
+
+- `shared_buffers=256MB` - буфер для кешування
+- `max_connections=200` - максимальна кількість підключень
+- `checkpoint_timeout=15min` - частіші checkpoint'и
+- `wal_level=replica` - рівень WAL для реплікації
+- `max_wal_size=1GB` - максимальний розмір WAL
+
+## Перевірка після проблеми
+
+```bash
+# 1. Перевірити логи PostgreSQL
+docker logs daarion-postgres --tail 50
+
+# 2. Перевірити дані
+docker exec daarion-postgres psql -U postgres -d daarion -c "SELECT COUNT(*) FROM microdaos;"
+docker exec daarion-postgres psql -U postgres -d daarion -c "SELECT COUNT(*) FROM agents;"
+
+# 3. Перевірити моніторинг
+tail -20 /var/log/db-stability-monitor.log
+
+# 4. Запустити монітор вручну
+bash scripts/monitor-db-stability.sh
+```
+
+## Запобігання повторенню
+
+1. **Автоматичний моніторинг**: Кожні 5 хвилин
+2. **Покращена конфігурація**: Правильне завершення PostgreSQL
+3. **Автоматичне відновлення**: З бекапу при виявленні проблем
+4. **Health checks**: Регулярні перевірки здоров'я БД
+
+## Поточний стан
+
+- ✅ Моніторинг налаштовано (кожні 5 хвилин)
+- ✅ PostgreSQL конфігурацію покращено
+- ✅ Автоматичне відновлення працює
+- ✅ Логи зберігаються в `/var/log/db-stability-monitor.log`
+