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

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

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

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

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

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

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

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

019_identity_system_refactor.sql

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

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

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

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

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

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

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

-- Создание таблицы, если она не существует
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() - проверка состояния системы идентификации пользователей

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

SELECT * FROM verify_identity_system();

4.4 KiB Raw Blame History Unescape Escape