121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
# Инструкция по применению 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`
|
||
|
||
Приложение автоматически проверяет оба пути.
|