352 lines
10 KiB
Markdown
352 lines
10 KiB
Markdown
# Database Migrations для DAARION Production
|
||
|
||
**База даних:** PostgreSQL 15+
|
||
**Міграції:** 001 → 010
|
||
|
||
---
|
||
|
||
## 📋 Список міграцій
|
||
|
||
| # | Файл | Опис | Залежності |
|
||
|---|------|------|------------|
|
||
| 001 | `001_initial_schema.sql` | Базова схема (users, sessions) | - |
|
||
| 002 | `002_teams_channels.sql` | Teams та Channels | 001 |
|
||
| 003 | `003_messages.sql` | Messaging система | 002 |
|
||
| 004 | `004_agents_core.sql` | Agents та blueprints | 001 |
|
||
| 005 | `005_agent_events.sql` | Agent lifecycle events | 004 |
|
||
| 006 | `006_passkeys.sql` | Passkey authentication | 001 |
|
||
| 007 | `007_api_keys.sql` | API keys management | 001 |
|
||
| 008 | `008_microdao_core.sql` | MicroDAO система | 001 |
|
||
| 009 | `009_dao_governance.sql` | DAO governance та voting | 008 |
|
||
| 010 | `010_create_city_backend.sql` | City Rooms + Second Me | 001 |
|
||
|
||
---
|
||
|
||
## 🚀 Початкове застосування міграцій
|
||
|
||
### Метод 1: Через psql (Рекомендовано для першого deploy)
|
||
|
||
```bash
|
||
# 1. Підключитися до сервера
|
||
ssh user@daarion.space
|
||
|
||
# 2. Перейти в директорію проєкту
|
||
cd /opt/daarion
|
||
|
||
# 3. Запустити PostgreSQL (якщо ще не запущений)
|
||
docker compose -f docker-compose.all.yml up -d postgres
|
||
|
||
# 4. Почекати поки PostgreSQL готовий
|
||
docker compose -f docker-compose.all.yml exec postgres pg_isready -U daarion_user
|
||
|
||
# 5. Застосувати міграції по порядку
|
||
for i in {001..010}; do
|
||
echo "Applying migration ${i}..."
|
||
docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion -f /migrations/${i}_*.sql
|
||
|
||
if [ $? -eq 0 ]; then
|
||
echo "✅ Migration ${i} applied successfully"
|
||
else
|
||
echo "❌ Migration ${i} failed!"
|
||
exit 1
|
||
fi
|
||
done
|
||
|
||
echo "🎉 All migrations applied successfully!"
|
||
```
|
||
|
||
### Метод 2: Через migration service (автоматизовано)
|
||
|
||
```bash
|
||
# Якщо є окремий migrations service в docker-compose.all.yml:
|
||
docker compose -f docker-compose.all.yml run --rm migrations
|
||
```
|
||
|
||
---
|
||
|
||
## 📂 Структура міграцій
|
||
|
||
```text
|
||
/opt/daarion/
|
||
└── migrations/
|
||
├── 001_initial_schema.sql
|
||
├── 002_teams_channels.sql
|
||
├── 003_messages.sql
|
||
├── 004_agents_core.sql
|
||
├── 005_agent_events.sql
|
||
├── 006_passkeys.sql
|
||
├── 007_api_keys.sql
|
||
├── 008_microdao_core.sql
|
||
├── 009_dao_governance.sql
|
||
└── 010_create_city_backend.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 Перевірка стану міграцій
|
||
|
||
### Метод 1: Manual check
|
||
```bash
|
||
# Перевірити які таблиці створені
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "\dt"
|
||
|
||
# Перевірити конкретну таблицю
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "\d city_rooms"
|
||
|
||
# Перевірити seed дані
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "SELECT * FROM city_rooms;"
|
||
```
|
||
|
||
### Метод 2: Via migration tracking table
|
||
```bash
|
||
# Створити таблицю для tracking
|
||
docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion << 'EOF'
|
||
CREATE TABLE IF NOT EXISTS schema_migrations (
|
||
id SERIAL PRIMARY KEY,
|
||
version TEXT NOT NULL UNIQUE,
|
||
applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
EOF
|
||
|
||
# Перевірити застосовані міграції
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "SELECT * FROM schema_migrations ORDER BY applied_at;"
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Re-run міграцій (Idempotent)
|
||
|
||
Всі міграції мають бути **idempotent** (можна запускати декілька разів):
|
||
|
||
```sql
|
||
-- Приклад з 010_create_city_backend.sql:
|
||
CREATE TABLE IF NOT EXISTS city_rooms (...);
|
||
CREATE INDEX IF NOT EXISTS idx_city_rooms_slug ON city_rooms(slug);
|
||
|
||
INSERT INTO city_rooms (id, slug, name, ...) VALUES (...)
|
||
ON CONFLICT (id) DO NOTHING;
|
||
```
|
||
|
||
### Re-apply конкретної міграції
|
||
```bash
|
||
# Якщо потрібно перезастосувати (тільки якщо idempotent!)
|
||
docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion < migrations/010_create_city_backend.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ Migration Helper Script
|
||
|
||
Створити `scripts/migrate.sh`:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
# Кольори
|
||
GREEN='\033[0;32m'
|
||
RED='\033[0;31m'
|
||
YELLOW='\033[1;33m'
|
||
NC='\033[0m' # No Color
|
||
|
||
echo -e "${YELLOW}DAARION Database Migrations${NC}"
|
||
echo "======================================="
|
||
|
||
# Перевірка що PostgreSQL запущений
|
||
echo "Checking PostgreSQL status..."
|
||
if ! docker compose -f docker-compose.all.yml exec postgres pg_isready -U daarion_user > /dev/null 2>&1; then
|
||
echo -e "${RED}❌ PostgreSQL is not ready!${NC}"
|
||
exit 1
|
||
fi
|
||
|
||
echo -e "${GREEN}✅ PostgreSQL is ready${NC}"
|
||
|
||
# Застосування міграцій
|
||
MIGRATION_DIR="./migrations"
|
||
SUCCESS_COUNT=0
|
||
FAIL_COUNT=0
|
||
|
||
for migration in $(ls $MIGRATION_DIR/*.sql | sort); do
|
||
filename=$(basename "$migration")
|
||
echo -e "\n${YELLOW}Applying $filename...${NC}"
|
||
|
||
if docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion < "$migration"; then
|
||
echo -e "${GREEN}✅ $filename applied successfully${NC}"
|
||
((SUCCESS_COUNT++))
|
||
else
|
||
echo -e "${RED}❌ $filename failed!${NC}"
|
||
((FAIL_COUNT++))
|
||
exit 1
|
||
fi
|
||
done
|
||
|
||
echo -e "\n======================================="
|
||
echo -e "${GREEN}🎉 All migrations completed!${NC}"
|
||
echo -e "Success: ${GREEN}$SUCCESS_COUNT${NC}"
|
||
echo -e "Failed: ${RED}$FAIL_COUNT${NC}"
|
||
```
|
||
|
||
Використання:
|
||
```bash
|
||
chmod +x scripts/migrate.sh
|
||
./scripts/migrate.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔙 Rollback Strategy
|
||
|
||
### Створення rollback файлів (для майбутнього)
|
||
```text
|
||
migrations/
|
||
├── 010_create_city_backend.sql
|
||
└── 010_create_city_backend_rollback.sql
|
||
```
|
||
|
||
### Приклад rollback
|
||
```sql
|
||
-- 010_create_city_backend_rollback.sql
|
||
DROP TABLE IF EXISTS secondme_messages CASCADE;
|
||
DROP TABLE IF EXISTS secondme_sessions CASCADE;
|
||
DROP TABLE IF EXISTS city_feed_events CASCADE;
|
||
DROP TABLE IF EXISTS city_room_messages CASCADE;
|
||
DROP TABLE IF EXISTS city_rooms CASCADE;
|
||
```
|
||
|
||
**Застосування rollback:**
|
||
```bash
|
||
docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion < migrations/010_create_city_backend_rollback.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Testing міграцій
|
||
|
||
### Pre-deployment testing (на dev environment)
|
||
```bash
|
||
# 1. Backup поточної БД
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
pg_dump -U daarion_user daarion > backup_before_migration.sql
|
||
|
||
# 2. Застосувати міграції
|
||
./scripts/migrate.sh
|
||
|
||
# 3. Перевірити що все працює
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "SELECT COUNT(*) FROM city_rooms;"
|
||
|
||
# 4. Якщо щось не так - rollback:
|
||
docker compose -f docker-compose.all.yml exec -T postgres \
|
||
psql -U daarion_user -d daarion < backup_before_migration.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Моніторинг розміру БД
|
||
|
||
```bash
|
||
# Розмір БД
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "SELECT pg_size_pretty(pg_database_size('daarion'));"
|
||
|
||
# Розмір таблиць
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "
|
||
SELECT
|
||
tablename,
|
||
pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
|
||
FROM pg_tables
|
||
WHERE schemaname = 'public'
|
||
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC
|
||
LIMIT 10;
|
||
"
|
||
|
||
# Кількість записів
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U daarion_user -d daarion -c "
|
||
SELECT
|
||
schemaname,
|
||
relname,
|
||
n_live_tup
|
||
FROM pg_stat_user_tables
|
||
ORDER BY n_live_tup DESC;
|
||
"
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 Backup перед міграціями
|
||
|
||
```bash
|
||
# Автоматичний backup
|
||
BACKUP_FILE="backup_$(date +%Y%m%d_%H%M%S).sql"
|
||
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
pg_dump -U daarion_user daarion > /opt/daarion/backups/$BACKUP_FILE
|
||
|
||
echo "Backup created: $BACKUP_FILE"
|
||
|
||
# Compress backup
|
||
gzip /opt/daarion/backups/$BACKUP_FILE
|
||
```
|
||
|
||
---
|
||
|
||
## 🚨 Troubleshooting
|
||
|
||
### Проблема: Migration fails з permission error
|
||
**Рішення:**
|
||
```bash
|
||
# Перевірити права користувача
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U postgres -c "\du daarion_user"
|
||
|
||
# Надати потрібні права
|
||
docker compose -f docker-compose.all.yml exec postgres \
|
||
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE daarion TO daarion_user;"
|
||
```
|
||
|
||
### Проблема: Table already exists
|
||
**Рішення:**
|
||
Переконатися що міграція використовує `CREATE TABLE IF NOT EXISTS`
|
||
|
||
### Проблема: Foreign key constraint fails
|
||
**Рішення:**
|
||
Перевірити порядок міграцій — залежні таблиці мають створюватися після основних.
|
||
|
||
---
|
||
|
||
## ✅ Post-migration Checklist
|
||
|
||
- [ ] Всі 10 міграцій застосовані успішно
|
||
- [ ] Seed дані створені (5 default city rooms)
|
||
- [ ] Індекси створені
|
||
- [ ] Foreign keys працюють
|
||
- [ ] Таблиця tracking міграцій оновлена
|
||
- [ ] Backup БД створено
|
||
- [ ] Логи міграцій збережені
|
||
- [ ] Performance перевірено (query plans)
|
||
|
||
---
|
||
|
||
## 📚 Наступні кроки
|
||
|
||
1. ➡️ **Services Startup** (`docs/DEPLOY_SERVICES.md`)
|
||
2. ➡️ **Smoke Tests** (`docs/DEPLOY_SMOKETEST_CHECKLIST.md`)
|
||
3. ➡️ **Monitoring Setup** (`docs/DEPLOY_MONITORING.md`)
|
||
|
||
---
|
||
|
||
**Статус:** ✅ Migrations Guide Complete
|
||
**Версія:** 1.0.0
|
||
**Дата:** 24 листопада 2025
|