# Инструкция по применению 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`

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