‫الگوهای بهینه در مدیریت EF Core Migrations

چکیده: مکانیزم Migrations در فریم‌ورک Entity Framework Core ابزاری قدرتمند برای تکامل تدریجی طرح‌واره پایگاه‌داده (Database Schema) همگام با مدل دامنه دات‌نت است. با این حال، تکیه بر تنظیمات پیش‌فرض در محیط‌های عملیاتی سازمانی (Production) چالش‌هایی نظیر از دست رفتن داده‌ها (Data Loss)، عدم همخوانی نسخه مدل، قفل شدن جداول و ناسازگاری در معماری‌های چندنسخه‌ای ایجاد می‌کند. این مقاله راهکارهای استاندارد، الگوهای نام‌گذاری، تغییرات ساختاری ایمن، استراتژی‌های استقرار در خطوط CI/CD، روش‌های صحیح مقداردهی اولیه داده‌ها (Data Seeding) و مانیتورینگ سلامت را بررسی می‌کند.

• AddUserTable
• AddMiddleNameToUserTable
• RemoveSalesDateFromClientOrderTable

[ستون اصلی] ──(EF Core Drop)──> [حذف کامل ستون و داده‌ها] ──(Add Column)──> [ایجاد ستون جدید با ساختار جدید]

• Expand: افزودن ستون جدید با نام یا نوع جدید در کنار ستون قبلی.
• Dual-Write / Sync: نگارش در هر دو فیلد یا همگام‌سازی با تریگر/بک‌گراند سرویس.
• Backfill: انتقال داده‌های قدیمی به فیلد جدید.
• Contract: منسوخ کردن فیلد قبلی و حذف نهایی آن در نسخه‌های بعدی.

نکته حیاتی: ویوها، پروسیجرها و ایندکس‌های سفارشی که به نام قبلی وابسته‌اند، به‌طور خودکار به‌روزرسانی نمی‌شوند و باید در اسکریپت مایگریشن مدنظر قرار گیرند.

dotnet ef migrations remove

• ابتدا وضعیت پایگاه‌داده را به نسخه قبل از تغییر برگردانید و سپس اقدام به حذف فایل کنید:

dotnet ef database update <PreviousMigrationName>
dotnet ef migrations remove

• اگر تغییرات در محیط‌های دیگر اِعمال شده‌اند، هرگز فایل‌های گذشته را حذف نکنید؛ بلکه با افزودن مایگریشن جدید (Forward-Fixing) ساختار را به حالت مطلوب ببرید.

# اجرا از پوشه پروژه Data
dotnet ef migrations add AddMiddleNameToUser --startup-project ../MyApp.ApiService
dotnet ef database update --startup-project ../MyApp.ApiService

• تضاد در محیط‌های چندنسخه‌ای (Multi-Instance/Horizontal Scaling): همزمانی در اجرای مایگریشن و ایجاد قفل‌های همپوشان.
• نقض اصل کمترین سطح دسترسی (Principle of Least Privilege): نیازمند بودن دسترسی سطح DDL (مانند ALTER TABLE) برای کاربری وب‌اپلیکیشن در دیتابیس.
• تأخیر در راه‌اندازی (Startup Timeout): توقف بالا آمدن کانتینر در صورت طولانی شدن فرآیند ساخت ایندکس‌های سنگین.

dotnet ef migrations bundle --self-contained -r linux-x64 -o efbundle
# اجرا در فرآیند استقرار
./efbundle --connection "Server=...;Database=...;"

dotnet ef migrations script --idempotent -o update.sql

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Country>().HasData(
        new Country { Id = 1, Name = "Iran", Code = "IR" },
        new Country { Id = 2, Name = "Germany", Code = "DE" }
    );
}

• الزام کلید اصلی: در HasData مقدار کلید اصلی (Primary Key) حتماً باید مشخص شود تا EF Core بتواند تغییرات رکوردها را در مایگریشن‌های بعدی شناسایی کند. تغییر شناسه موجود معادل حذف و ثبت مجدد خواهد بود.

public static class TestDataSeeder
{
    public static async Task SeedAsync(AppDbContext db)
    {
        if (!await db.Users.AnyAsync())
        {
            db.Users.AddRange(
                new User { Name = "Alice", Email = "alice@example.com" },
                new User { Name = "Bob", Email = "bob@example.com" }
            );
            await db.SaveChangesAsync();
        }
    }
}

// Program.cs
if (app.Environment.IsDevelopment())
{
    using var scope = app.Services.CreateScope();
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
    await TestDataSeeder.SeedAsync(db);
}

builder.Services.AddHealthChecks()
    .AddCheck<MigrationHealthCheck>("database_migrations");

public class MigrationHealthCheck(AppDbContext db) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken ct = default)
    {
        var pending = (await db.Database.GetPendingMigrationsAsync(ct)).ToList();

        return pending.Count == 0
            ? HealthCheckResult.Healthy("Database schema is fully synchronized.")
            : HealthCheckResult.Degraded($"{pending.Count} pending migration(s): {string.Join(", ", pending)}");
    }
}

[مایگریشن ۱] ──> [مایگریشن ۲] ──> ... ──> [مایگریشن ۱۰۰]
                         ↓
               [یکپارچه‌سازی (Squash)]
                         ↓
       [مایگریشن پایه نهایی با ثبت وضعیت در تاریخچه]

• ایجاد یک مایگریشن خالی پایانی و اِعمال آن بر تمامی محیط‌های موجود.
• ذخیره نام و برچسب زمانی (Timestamp) آن مایگریشن.
• حذف تمام فایل‌های مایگریشن قبلی از Solution و پاکسازی اسنپ‌شات.
• تولید یک مایگریشن نوظهور با اسامی یکسان با برچسب مرحله اول.
• به این ترتیب محیط‌های قدیمی تغییر جدیدی دریافت نکرده و محیط‌های جدید دیتابیس را به طور کامل از روی فایل تجمیع‌شده می‌سازند.