play-life/play-life-backend/MIGRATION_BASELINE.md

Инструкция по применению baseline миграции

Обзор

После перехода на golang-migrate текущая схема БД была зафиксирована как baseline миграция 000001_baseline.up.sql. Для существующих баз данных baseline миграция не должна применяться автоматически - вместо этого нужно использовать команду migrate force для установки текущей версии миграции.

Для существующих баз данных

Шаг 1: Создание backup

ОБЯЗАТЕЛЬНО создайте backup базы данных перед применением baseline:

# Используйте существующий скрипт 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), не применяя саму миграцию:

# Установите переменные окружения
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: Проверка

Проверьте, что версия миграции установлена правильно:

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 флаг:

migrate -path ./play-life-backend/migrations \
        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
        force 1

Для новых баз данных

Для новых баз данных baseline миграция применится автоматически при первом запуске приложения через функцию runMigrations().

Или вручную:

migrate -path ./play-life-backend/migrations \
        -database "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME?sslmode=disable" \
        up

Проверка схемы

После применения baseline (или установки версии для существующих БД) можно проверить схему:

# Экспорт схемы
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", исправьте это:

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

Приложение автоматически проверяет оба пути.