ss14-migrations

🚀 Миграции Баз Данных SS14 (Database Migrations)

Этот навык описывает процесс создания и применения миграций базы данных в Space Station 14. Поскольку SS14 поддерживает и PostgreSQL, и SQLite, все изменения должны быть мигрированы для обоих движков.

🎯 Когда использовать этот навык

• При изменении моделей базы данных (Model.cs).
• При добавлении новых таблиц или столбцов.
• При переименовании или удалении существующих структур БД.
• Когда сервер падает при запуске с ошибкой "Applying Migrations".

⚔️ Система Двойной Миграции

SS14 поддерживает два отдельных набора миграций:

1. SQLite Config: Content.Server.Database/Migrations/Sqlite
2. PostgreSQL Config: Content.Server.Database/Migrations/Postgres

Это необходимо, потому что у движков разные типы данных, фичи и диалекты SQL. Одна миграция обычно не может быть применена к обоим сразу.

🛠️ Скрипты-помощники

В репозитории есть скрипты для упрощения добавления миграций сразу в оба контекста:

• Windows (PowerShell): Content.Server.Database/add-migration.ps1
• Linux/Mac (Bash): Content.Server.Database/add-migration.sh

📝 Создание Миграции

Предварительные требования

• Запустите базу данных (если используете локальный Postgres).
• Убедитесь, что ваши изменения в Model.cs компилируются.

Шаги

1. Перейдите в директорию проекта базы данных:

   cd Content.Server.Database
   

2. Запустите скрипт с понятным именем (CamelCase):

   ./add-migration.ps1 MyNewFeature
   

   Если скрипт упал или нужен ручной контроль, вот эквивалентные команды dotnet ef:

   # Создание миграции для SQLite
   dotnet ef migrations add --context SqliteServerDbContext -o Migrations/Sqlite MyNewFeature
   
   # Создание миграции для Postgres
   dotnet ef migrations add --context PostgresServerDbContext -o Migrations/Postgres MyNewFeature
   

3. Проверьте Созданные Файлы:

   • Migrations/Sqlite/YYYYMMDDHHMMSS_MyNewFeature.cs
   • Migrations/Postgres/YYYYMMDDHHMMSS_MyNewFeature.cs

✅ Чек-лист Проверки

• Предупреждения о потере данных: EF Core предупредил, что данные могут быть потеряны (например, при удалении столбца)?
• Совместимость Типов:
  • Убедитесь, что миграции SQLite не пытаются использовать типы Postgres, такие как inet или jsonb, без конвертации (это должно обрабатываться в DbContext).
• Raw SQL: Если вы использовали migrationBuilder.Sql("..."), убедитесь, что SQL совместим с конкретным движком этой миграции.

🚫 Антипаттерны (Чего НЕ делать)

❌ 1. Забыть про один из движков

Симптом: Сервер работает локально (SQLite), но падает на проде (Postgres) или наоборот. Почему: Рассинхрон схемы БД. EF Core не найдет нужную миграцию. Как надо: Всегда проверяйте, что в обеих папках есть файл миграции с одним таймстампом/именем.

❌ 2. Сложные изменения схемы в SQLite

Проблема: SQLite имеет ограниченную поддержку ALTER TABLE (например, нельзя переименовать столбец или изменить его тип без пересоздания таблицы). Последствия: EF Core попытается создать временную таблицу, скопировать все данные, удалить старую и переименовать новую. Это очень медленно на больших таблицах и опасно. Как надо: Избегайте сложных изменений (rename column, change column type) для SQLite, если возможно. Лучше добавить новый столбец и пометить старый как устаревший (Obsolete).

❌ 3. Циклические зависимости при билде

Проблема: Добавление миграции требует сборки проекта, но проект не собирается, так как вы используете новое поле в коде, которого еще нет в БД (или наоборот). Правильный поток:

1. Измените Model.cs (добавьте свойство).
2. Соберите проект (код компилируется, но БД рассинхронизирована).
3. Создайте миграцию.
4. Обновите БД (происходит автоматически при старте сервера).

❌ 4. Изменение уже влитых миграций

Плохо: Редактировать файл миграции, который уже был влит в master и задеплоен. Почему: Это сломает историю миграций у всех остальных разработчиков и на серверах. __EFMigrationsHistory будет содержать хэш старой версии, и EF Core упадет. Как надо: Если нашли баг в старой миграции — создайте новую миграцию, которая исправляет проблему.

🗑️ Удаление (откат) локальной миграции

Если вы создали миграцию, но передумали (и еще не закоммитили/не влили её):

# Удаляет последнюю миграцию из контекста
dotnet ef migrations remove --context SqliteServerDbContext
dotnet ef migrations remove --context PostgresServerDbContext