4.0.0: Исправлена обработка старых дампов

play-life-backend/MIGRATION_BASELINE.md

@@ -0,0 +1,120 @@
+# Инструкция по применению baseline миграции
+
+## Обзор
+
+После перехода на `golang-migrate` текущая схема БД была зафиксирована как baseline миграция `000001_baseline.up.sql`. Для существующих баз данных baseline миграция **не должна применяться автоматически** - вместо этого нужно использовать команду `migrate force` для установки текущей версии миграции.
+
+## Для существующих баз данных
+
+### Шаг 1: Создание backup
+
+**ОБЯЗАТЕЛЬНО** создайте backup базы данных перед применением baseline:
+
+```bash
+# Используйте существующий скрипт dump-db.sh
+./dump-db.sh
+
+# Или вручную:
+pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME > backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+### Шаг 2: Установка версии миграции
+
+Для существующих баз данных нужно установить версию миграции в `1` (baseline), не применяя саму миграцию:
+
+```bash
+# Установите переменные окружения
+export DB_HOST=localhost
+export DB_PORT=5432
+export DB_USER=playeng
+export DB_PASSWORD=playeng
+export DB_NAME=playeng
+
+# Установите версию миграции в 1 (baseline)
+migrate -path ./play-life-backend/migrations \
+        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
+        force 1
+```
+
+**Важно:** Команда `force 1` устанавливает версию миграции в `1`, но **не выполняет** SQL из baseline миграции. Это правильно, так как схема уже существует.
+
+### Шаг 3: Проверка
+
+Проверьте, что версия миграции установлена правильно:
+
+```bash
+migrate -path ./play-life-backend/migrations \
+        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
+        version
+```
+
+Должно вывести: `1 (dirty)`
+
+Если выводит `1 (dirty)`, это нормально - это означает, что версия установлена, но миграция не была применена (что и требуется для baseline).
+
+### Шаг 4: Очистка dirty флага (опционально)
+
+Если нужно убрать dirty флаг:
+
+```bash
+migrate -path ./play-life-backend/migrations \
+        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
+        force 1
+```
+
+## Для новых баз данных
+
+Для новых баз данных baseline миграция применится автоматически при первом запуске приложения через функцию `runMigrations()`.
+
+Или вручную:
+
+```bash
+migrate -path ./play-life-backend/migrations \
+        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
+        up
+```
+
+## Проверка схемы
+
+После применения baseline (или установки версии для существующих БД) можно проверить схему:
+
+```bash
+# Экспорт схемы
+pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME --schema-only > current_schema.sql
+
+# Сравнение с baseline (если нужно)
+diff current_schema.sql play-life-backend/migrations/000001_baseline.up.sql
+```
+
+## Важные замечания
+
+1. **Никогда не применяйте baseline миграцию на существующих БД** - используйте только `migrate force 1`
+2. **Всегда создавайте backup** перед любыми операциями с миграциями
+3. **Проверяйте версию миграции** после установки baseline
+4. **Новые миграции** будут применяться автоматически при запуске приложения
+
+## Устранение проблем
+
+### Ошибка "dirty database version"
+
+Если база данных находится в состоянии "dirty", исправьте это:
+
+```bash
+migrate -path ./play-life-backend/migrations \
+        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
+        force <version>
+```
+
+Где `<version>` - текущая версия миграции (обычно 1 для baseline).
+
+### Ошибка "no change"
+
+Если при применении миграций вы видите "no change", это нормально - база данных уже на актуальной версии.
+
+### Проблемы с путями к миграциям
+
+Убедитесь, что путь к миграциям правильный:
+- Локально: `./play-life-backend/migrations`
+- В Docker: `/migrations`
+
+Приложение автоматически проверяет оба пути.