photoplaces/database/migrations/000-migration-guide.md

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

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

Миграции хранятся в директории database/migrations/ и нумеруются в порядке выполнения:

• 001-initial-schema.sql - Основная схема базы данных
• 002-seed-data.sql - Тестовые данные для разработки
• 003-... - Последующие миграции

Правила создания миграций

1. Нумерация: Каждая миграция должна начинаться с трехзначного номера
2. Имена файлов: Используйте описательные имена в snake_case
3. Комментарии: Добавляйте комментарии к каждой миграции
4. Транзакции: Все изменения должны быть обернуты в BEGIN/COMMIT
5. Обратная совместимость: Миграции должны быть обратимыми

Порядок выполнения миграций

Миграции выполняются в порядке их нумерации. Система миграций должна:

1. Создать таблицу migrations для отслеживания выполненных миграций
2. Выполнять миграции по порядку
3. Записывать выполненные миграции в таблицу migrations
4. Предоставлять возможность отката миграций

Пример структуры таблицы миграций

CREATE TABLE migrations (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    executed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Инструменты для управления миграциями

Рекомендуемые инструменты:

• node-pg-migrate - для Node.js приложений
• Flyway - Java-based миграции
• Liquibase - кроссплатформенное решение
• Собственный скрипт - простой bash/Python скрипт

Рекомендации по разработке

1. Тестирование: Всегда тестируйте миграции на dev окружении
2. Резервное копирование: Делайте бэкап перед выполнением миграций
3. Версионирование: Храните миграции в системе контроля версий
4. Документация: Описывайте изменения в комментариях
5. Обратные миграции: Создавайте скрипты для отката изменений

Безопасность

• Никогда не храните чувствительные данные в миграциях
• Используйте переменные окружения для конфиденциальной информации
• Проверяйте миграции на наличие SQL инъекций

Пример использования с node-pg-migrate

1. Установите node-pg-migrate:

   npm install -g node-pg-migrate
   

2. Создайте новую миграцию:

   node-pg-migrate create add-new-feature
   

3. Выполните миграции:

   node-pg-migrate up
   

4. Откатите миграции:

   node-pg-migrate down
   

Важные замечания

• Миграции должны быть идемпотентными (можно выполнять multiple times)
• Избегайте DROP операций в миграциях
• Всегда добавляйте соответствующие индексы
• Тестируйте производительность миграций на больших объемах данных