# Руководство по миграциям базы данных

## Общая информация

Система миграций базы данных предназначена для поддержания структуры базы данных в актуальном состоянии и обеспечения возможности обновления между версиями приложения.

## Структура миграций

Миграции размещены в папке `backend/db/migrations/` и именуются по схеме `XXX_descriptive_name.sql`, где XXX - порядковый номер миграции.

### Категории миграций

1. **Основные структурные миграции** (001-013) - создание базовых таблиц и первоначальной структуры
2. **Функциональные миграции** - изменения, связанные с конкретными функциями
3. **Рефакторинг и оптимизация** (019+) - улучшение существующей структуры

## Важные миграции

### 019_identity_system_refactor.sql

Комплексная миграция, объединяющая несколько предыдущих миграций (014-018) для улучшения системы идентификации пользователей:

- Создание таблицы `guest_user_mapping` для связи гостевых идентификаторов с пользователями
- Добавление прямой связи между сообщениями и пользователями через поле `user_id`
- Очистка дублирующихся данных между таблицами `users` и `user_identities`
- Нормализация формата идентификаторов (приведение к нижнему регистру)
- Добавление ограничений и триггеров для поддержания целостности данных

## Применение миграций

При развертывании новой версии приложения миграции применяются автоматически через скрипт `backend/db/run-migrations.js`. Порядок применения определяется порядковым номером в имени файла.

## Создание новых миграций

1. **Именование**: Используйте следующий свободный порядковый номер и описательное имя
2. **Идемпотентность**: Миграции должны быть безопасны для повторного выполнения
3. **Проверки**: Добавляйте проверки существования объектов перед их созданием
4. **Тестирование**: Проверяйте миграцию на тестовой базе данных перед применением

Пример правильной идемпотентной миграции:

```sql
-- Создание таблицы, если она не существует
CREATE TABLE IF NOT EXISTS example_table (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL
);

-- Добавление колонки, если она отсутствует
DO $$
BEGIN
  IF NOT EXISTS (
    SELECT 1 FROM information_schema.columns
    WHERE table_name = 'example_table' AND column_name = 'new_column'
  ) THEN
    ALTER TABLE example_table ADD COLUMN new_column INTEGER;
  END IF;
END $$;
```

## Архивация устаревших миграций

Устаревшие миграции, объединенные в более новые версии, перемещаются в папку `backend/db/migrations/archive/`. Для архивации используйте скрипт `backend/scripts/cleanup_migrations.sh`.

## Диагностические функции

Для проверки состояния базы данных и корректности миграций созданы следующие диагностические функции SQL:

- `verify_identity_system()` - проверка состояния системы идентификации пользователей

Пример использования:

```sql
SELECT * FROM verify_identity_system();
```