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`
|
|||
|
|
|
|||
|
|
Приложение автоматически проверяет оба пути.
|