Українська
Перша міграція
Крок 1. Налаштування провайдера в одному місці
Навіщо. ChatexDbContext створюватимуть два місця: застосунок (зареєстрований для впровадження залежностей у темі 5) та інструмент dotnet ef, якому для читання моделі потрібен контекст. Обидва мають налаштовувати його однаково – той самий провайдер, та сама угода іменування, та сама політика повторних спроб – інакше інструмент згенерує схему, якої застосунок не чекає. Тому налаштування живе в одному методі, який викликають обидва.
Що зробити. Створіть DependencyInjection.cs у корені проєкту даних. Поки що в ньому лише цей метод; у темі 5 цей самий клас отримає реєстрацію всього рівня даних.
cs
using Microsoft.EntityFrameworkCore;
namespace Chatex.Data;
public static class DependencyInjection
{
internal static void Configure(DbContextOptionsBuilder options, string connectionString) =>
options.UseNpgsql(connectionString, npgsql => npgsql.EnableRetryOnFailure()).UseSnakeCaseNamingConvention();
}UseNpgsqlвибирає провайдер PostgreSQL із заданим рядком підключення.EnableRetryOnFailureзмушує EF Core повторити команду, що завершилась помилкою з тимчасової причини: обрив з’єднання, перезапуск бази даних, перемикання на резервний сервер. Без нього база даних, недоступна дві секунди, обертається помилками для кожного користувача, який у ці дві секунди надіслав повідомлення. Повторні спроби мають ціну для транзакцій, яку сплачує тема 5.UseSnakeCaseNamingConventionпоходить зEFCore.NamingConventions:LastActivityAtстаєlast_activity_at,ChatMembersстаєchat_members, первинний ключchatsстаєpk_chats.
Крок 2. Контекст для інструментів
Навіщо. Щоб створити міграцію, dotnet ef завантажує наш проєкт, створює контекст і читає його модель. Зазвичай інструмент отримує контекст із впровадження залежностей застосунку, запускаючи стартовий проєкт. Робочого застосунку в нас ще немає, та й пізніше краще, щоб створення міграції не залежало від запуску API з усіма його налаштуваннями. Клас, що реалізує IDesignTimeDbContextFactory<T>, повідомляє інструменту, як створити контекст безпосередньо.
Що зробити.
cs
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
namespace Chatex.Data;
/// <summary>Used by <c>dotnet ef</c> only. Reads the connection string from the CHATEX_DB environment variable.</summary>
internal sealed class ChatexDbContextFactory : IDesignTimeDbContextFactory<ChatexDbContext>
{
private const string DevConnectionString = "Host=localhost;Port=5432;Database=chatex;Username=postgres;Password=postgres";
public ChatexDbContext CreateDbContext(string[] args)
{
var connectionString = Environment.GetEnvironmentVariable("CHATEX_DB") ?? DevConnectionString;
var options = new DbContextOptionsBuilder<ChatexDbContext>();
DependencyInjection.Configure(options, connectionString);
return new ChatexDbContext(options.Options);
}
}Рядок підключення береться зі змінної середовища CHATEX_DB, а без неї – зі значення для бази даних розробки з compose.yaml. Оператор ?? повертає лівий операнд, якщо він не null. Задавайте її, коли інструмент має працювати з іншою базою даних; розробнику нічого задавати не потрібно. CI її теж не потребує: перевірка відсутніх міграцій порівнює модель зі знімком без бази даних (тема 22), а на сервері пакет міграцій отримує рядок підключення аргументом (тема 24).
Фабрика має модифікатор internal: нею користується лише інструмент, який знаходить її через рефлексію.
Крок 3. Створіть міграцію
Навіщо. Міграція – це клас C#, що описує одну зміну схеми: Up застосовує її, Down скасовує. EF Core порівнює поточну модель зі знімком (snapshot) моделі на момент останньої міграції й генерує код для різниці. Міграції входять до репозиторію, тож кожен розробник, CI і робочий сервер приводять свої бази даних до тієї самої схеми тими самими кроками (рис. 4.2).
Рис. 4.2. Шлях зміни схеми
Що зробити. Переконайтеся, що PostgreSQL працює (docker compose up --detach --wait), потім створіть першу міграцію з кореня репозиторію:
powershell
dotnet ef migrations add InitialCreate --project Source/Chatex.Data --output-dir MigrationsІнструмент збирає проєкт, створює контекст за допомогою фабрики й записує три файли до Source/Chatex.Data/Migrations:
| Файл | Вміст |
|---|---|
<timestamp>_InitialCreate.cs | міграція: Up створює 14 таблиць з ключами, індексами й обмеженнями, Down видаляє їх |
<timestamp>_InitialCreate.Designer.cs | модель такою, якою вона була на момент цієї міграції (метадані, їх ніколи не редагують) |
ChatexDbContextModelSnapshot.cs | поточна модель; наступне migrations add порівнює з нею |
Часова мітка – це поточний час, тож імена ваших файлів відрізнятимуться від еталонних (20261029094940_InitialCreate.cs); вміст має збігатися. Відкрийте міграцію й знайдіть таблицю chats – видно кожне рішення з конфігурацій:
cs
migrationBuilder.CreateTable(
name: "chats",
columns: table => new
{
id = table.Column<Guid>(type: "uuid", nullable: false),
type = table.Column<string>(type: "character varying(16)", maxLength: 16, nullable: false),
title = table.Column<string>(type: "character varying(128)", maxLength: 128, nullable: true),
// ...
direct_key = table.Column<string>(type: "character varying(65)", maxLength: 65, nullable: true),
created_by_id = table.Column<Guid>(type: "uuid", nullable: false),
// ...
deleted_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true)
},
constraints: table =>
{
table.PrimaryKey("pk_chats", x => x.id);
table.CheckConstraint("ck_chats_direct_key", "(type = 'Direct') = (direct_key IS NOT NULL)");
table.ForeignKey(
name: "fk_chats_users_created_by_id",
column: x => x.created_by_id,
principalTable: "users",
principalColumn: "id",
onDelete: ReferentialAction.Restrict);
});а нижче – індекс для сторінок історії:
cs
migrationBuilder.CreateIndex(
name: "ix_messages_chat_id_id",
table: "messages",
columns: new[] { "chat_id", "id" },
descending: new[] { false, true });Завжди читайте згенеровану міграцію
Інструмент записує те, що каже модель, а не те, що ви мали на увазі. Перейменована властивість, наприклад, з’являється як «видалити стовпець, додати новий» – і дані старого стовпця втрачаються. Читайте кожну міграцію, перш ніж комітити її; виправте модель і виконайте dotnet ef migrations remove, щоб спробувати ще раз.
Файл .editorconfig з теми 2 позначає папку Migrations як згенерований код, тож аналізатори не скаржаться на стиль згенерованих файлів.
Крок 4. Застосуйте її
Що зробити.
powershell
dotnet ef database update --project Source/Chatex.DataІнструмент підключається до бази даних, створює таблицю __EFMigrationsHistory, виконує Up кожної міграції, якої там ще немає, і записує її. Повторний запуск команди нічого не робить: міграцію вже застосовано.
Перевірка
Виведіть список таблиць:
powershell
docker compose exec postgres psql -U postgres -d chatex -c '\dt'У списку 14 таблиць: __EFMigrationsHistory, attachments, chat_members, chats, messages, refresh_tokens, role_claims, roles, user_claims, user_logins, user_profiles, user_roles, user_tokens, users. Потім опишіть одну з них:
powershell
docker compose exec postgres psql -U postgres -d chatex -c '\d chats'Вивід показує стовпці з типами (character varying(16), timestamp with time zone), індекси pk_chats, ix_chats_direct_key та ix_chats_public_handle (обидва UNIQUE), обмеження перевірки ck_chats_direct_key і зовнішній ключ на users із ON DELETE RESTRICT.
Крок 5. Подивіться, як працює обмеження
Навіщо. Обмеження перевірки й унікальні індекси захищають дані навіть від коду з помилками. Спробуймо вручну порушити правило «лише особисті чати мають прямий ключ».
Що зробити. Відкрийте інтерактивний сеанс psql:
powershell
docker compose exec postgres psql -U postgres -d chatexВставте користувача (лише стовпці, що не можуть бути NULL; uuidv7() – функція PostgreSQL 18) і спробуйте дати групі прямий ключ:
sql
insert into users (id, user_name, access_failed_count, email_confirmed, lockout_enabled,
phone_number_confirmed, two_factor_enabled, created_at)
values (uuidv7(), 'alice', 0, false, false, false, false, now());sql
insert into chats (id, type, title, direct_key, created_by_id, created_at, updated_at, last_activity_at)
select uuidv7(), 'Group', 'Wrong', 'a:b', id, now(), now(), now() from users where user_name = 'alice';Перевірка
Друга вставка завершується помилкою:
ERROR: new row for relation "chats" violates check constraint "ck_chats_direct_key"Така сама вставка без direct_key виконується. Приберіть за собою й вийдіть із psql:
sql
delete from chats; delete from users;sql
\qКрок 6. Тримайте модель і міграції синхронними
Навіщо. Розробник може змінити сутність і забути додати міграцію. Код збирається, тести навіть можуть пройти локально на старій базі даних – а сервер ламається після розгортання. EF Core може це виявити: він порівнює модель зі знімком.
Що зробити.
powershell
dotnet ef migrations has-pending-model-changes --project Source/Chatex.DataПеревірка
Команда виводить No changes have been made to the model since the last migration. Тепер додайте властивість public string? Note { get; set; } до Chat, зберіть проєкт і виконайте команду знову: вона повідомляє про зміни й завершується кодом помилки – саме це CI з теми 22 перевіряє під час кожного надсилання. Знову приберіть властивість.
Тепер працюють дві команди Run.ps1 з теми 2:
./Run.ps1 dbзапускає PostgreSQL і застосовує міграції – єдина команда, що потрібна новому розробнику після клонування;./Run.ps1 migration <Name>додає міграцію з правильними параметрами.