Làm Chủ EF Core Migrations: Phát Triển Cơ Sở Dữ Liệu Một Cách Tự Tín

Migration là code bạn review, không phải artifact bạn tin. Và migration đã chạy trên một database thì không được sửa — mọi chỉnh sửa sau đó chỉ làm database và snapshot lệch nhau trong im lặng. Bài này là quy trình làm việc đủ để bạn triển khai schema lên production mà không cần cửa sổ downtime, cùng những chỗ EF Core 10 vẫn để bạn tự chịu trách nhiệm.

Cập nhật 2026

  • EF Core 10 (10.0.14) là LTS đến 2028-11-10. .NET 8 và .NET 9 hết hỗ trợ ngày 2026-11-10; migration đầu tiên của dự án mới nên chạy trên .NET 10.
  • Từ EF Core 9, Migrate/MigrateAsync tự lấy lock toàn database, và ném lỗi nếu model có thay đổi chưa đóng gói vào migration (PendingModelChangesWarning). Đây là thay đổi hành vi quan trọng nhất với pipeline.
  • dotnet ef migrations has-pending-model-changes là lệnh dành cho CI; migration bundle chạy được mà không cần SDK, EF tool hay source code.
  • Idempotent script vẫn là lựa chọn khi cần DBA review; riêng SQLite không hỗ trợ sinh script idempotent.

Cơ chế: ba file và một bảng

Mỗi lần migrations add, EF Core so model hiện tại với snapshot cuối và sinh:

  • một file migration chứa Up(MigrationBuilder) và Down(MigrationBuilder) — phần Up là thứ sẽ chạy, phần Down là thứ bạn hy vọng chạy được khi rollback;
  • một file designer chứa metadata của migration;
  • một file *ModelSnapshot.cs — trạng thái model sau migration này, dùng làm mốc cho lần so sánh kế tiếp.

Khi áp dụng, EF đọc bảng __EFMigrationsHistory, so với danh sách migration trong assembly, rồi chạy tuần tự những migration còn thiếu. Bảng history là nguồn sự thật duy nhất; snapshot chỉ dùng lúc tạo migration mới. Hiểu điều này để biết vì sao sửa một migration đã áp dụng không có tác dụng: nó không bao giờ chạy lại.

Ba thứ migration không quản lý: stored procedure, trigger, view/function và grant quyền. Chúng không nằm trong snapshot, nên has-pending-model-changes không thấy drift. Nếu muốn version hóa, đưa chúng vào migration bằng migrationBuilder.Sql như bài trước đã bàn.

Các lệnh và khi nào dùng

Lệnh Việc nó làm Dùng khi
dotnet ef migrations add Ten So model với snapshot, sinh migration mới Sau khi đổi entity hoặc cấu hình
dotnet ef migrations list Liệt kê migration và trạng thái áp dụng Kiểm tra database đang ở đâu
dotnet ef database update Áp dụng migration còn thiếu Local, test, không dùng cho production
dotnet ef migrations script --idempotent -o out.sql Sinh SQL có kiểm tra history Cần review, archive, hoặc DBA chạy
dotnet ef migrations bundle --self-contained --target-runtime linux-x64 Đóng gói executable tự chạy migration CI/CD tự động, không cần SDK
dotnet ef migrations has-pending-model-changes Kiểm tra model có thay đổi chưa migrate Gate trong CI, chạy trước khi build artifact
dotnet ef migrations remove Xóa migration cuối Chỉ khi migration đó chưa áp dụng

Với solution nhiều project, thêm --project (nơi chứa DbContext) và --startup-project (nơi có cấu hình) để dotnet ef không đoán sai. --context cần khi một project có nhiều DbContext.

Quy trình làm việc

  1. Đổi model, chạy migrations add với tên mô tả hành động: AddDisplayNameToUsers, không phải Update1.
  2. Đọc Up và Down. Đây là bước bị bỏ qua nhiều nhất. EF có thể sinh DropColumn + AddColumn khi bạn chỉ định đổi tên cột; chạy nguyên bản là mất dữ liệu. Sửa thành RenameColumn trước khi áp dụng.
  3. Chạy dotnet ef database update ở local, kiểm tra schema thật, không chỉ tin build pass.
  4. Commit cả ba file cùng thay đổi model trong một commit. Không commit migration mà không có model, và không commit model mà không có migration.

Xung đột Git trong thư mục Migrations gần như luôn có nghĩa là hai người cùng tạo migration trên cùng một nhánh. Cách xử lý đúng: giữ một migration, xóa cái còn lại cùng snapshot của nó, rồi tạo lại migration sau khi merge model. Không sửa timestamp để “đổi thứ tự” — thứ tự do tên file quyết định, nhưng nội dung đã lệch.

Một mẹo thực dụng: chạy dotnet ef migrations script 0 TenMigration để xem đúng SQL mà migration mới sẽ sinh, thay vì chỉ đọc code C#. Script từ 0 cho thấy toàn bộ schema như database mới; script từ migration trước cho thấy delta. Cách này bắt được cả kiểu cột và index do provider quyết định, những thứ không hiện rõ trong Up.

Triển khai: script hay bundle

Hai lựa chọn, chọn theo việc bạn có cần đọc SQL trước khi chạy hay không. Script idempotent cho phép DBA review, archive, và chạy trên nhiều database ở trạng thái khác nhau. Bundle là một executable đóng gói toàn bộ migration, chạy được trên máy không có .NET SDK, có lock và chạy seeding delegate. Bundle không cho xem SQL trước khi chạy — nếu quy trình bắt buộc review, dùng script.

# .github/workflows/migrate.yml (phần chính)
- run: dotnet tool restore
- run: dotnet ef migrations has-pending-model-changes --project src/Catalog.Api
- run: dotnet ef migrations bundle --self-contained --target-runtime linux-x64 --project src/Catalog.Api -o artifacts/efbundle
- uses: actions/upload-artifact@v4
  with:
    name: efbundle
    path: artifacts/efbundle

# job deploy, chạy một lần sau khi database healthy:
- run: ./efbundle --connection "$DEPLOY_CONNECTION"
  env:
    DEPLOY_CONNECTION: ${{ secrets.DEPLOY_CONNECTION }}

Ba nguyên tắc trong pipeline: connection string đến từ secret store, không nhúng vào bundle; identity chạy migration có quyền DDL, identity của ứng dụng chỉ có quyền đọc/ghi dữ liệu; migration chạy như một job một lần, không chạy trong entrypoint của mọi replica. Nếu ba điều này sai, bạn sẽ có một trong ba sự cố quen thuộc: lộ secret, ứng dụng có quyền xóa bảng, hoặc mười pod cùng migrate lúc deploy.

Zero-downtime: expand rồi contract

Một migration làm thay đổi schema mà code cũ vẫn đang chạy là migration phá production. Quy tắc: mỗi lần deploy, schema phải tương thích với cả phiên bản code trước và sau. Làm được bằng ba bước, mỗi bước một release:

  1. Expand — thêm cột nullable hoặc bảng mới, không đổi cột cũ. Code mới ghi cả hai nơi; code cũ vẫn chạy bình thường.
  2. Backfill — job chạy nền điền dữ liệu cũ, theo lô, có thể chạy lại. Không đặt backfill hàng triệu dòng trong migration.
  3. Contract — sau khi mọi instance đã dùng code mới và dữ liệu đã đủ, thêm NOT NULL, drop cột cũ trong một release sau.
-- Release 1 (expand): cột mới nullable, không khóa gì
ALTER TABLE dbo.Users ADD DisplayName nvarchar(200) NULL;

-- Backfill theo lô, chạy ngoài migration
UPDATE TOP (5000) dbo.Users
SET DisplayName = Name
WHERE DisplayName IS NULL;

-- Release 3 (contract): chỉ sau khi code cũ đã ngừng ghi Name
ALTER TABLE dbo.Users ALTER COLUMN DisplayName nvarchar(200) NOT NULL;
ALTER TABLE dbo.Users DROP COLUMN Name;

ALTER COLUMN ... NOT NULL quét toàn bảng và lấy lock; trên bảng lớn, đó là cửa sổ downtime thật. PostgreSQL có thể giảm lock bằng cách thêm CHECK (col IS NOT NULL) NOT VALID, chạy VALIDATE CONSTRAINT, rồi mới SET NOT NULL — constraint đã validate giúp bỏ qua lần quét thứ hai. Vẫn phải lên kế hoạch theo từng bảng, đừng giả định migration là thao tác tức thời.

Lock, drift và những điều không được làm

Từ EF Core 9, database update, bundle và MigrateAsync tự lấy lock toàn database trước khi chạy. Script SQL không được bảo vệ — nó chạy ngoài EF. Cơ chế lock phụ thuộc provider; trên SQLite, lock là một bảng và có thể bị bỏ quên nếu process chết giữa chừng, chặn các lần migrate sau. Với SQLite, đừng chạy migration từ nhiều instance.

  • Không sửa migration đã áp dụng. EF không kiểm tra checksum; database đã có tên migration trong history, nên bản sửa không bao giờ chạy. Database và snapshot lệch nhau, và migration tiếp theo sẽ sinh SQL dựa trên giả định sai.
  • Không bọc MigrateAsync trong transaction tường minh. EF Core 9 không hỗ trợ; migration tự quản lý transaction của nó.
  • Không tin Down là rollback miễn phí. Down chỉ đảo schema, không khôi phục dữ liệu đã xóa. Với thao tác mất dữ liệu, rollback thật là restore backup.
  • Squash không có lệnh built-in. Cách làm là tạo một migration baseline mới từ model hiện tại, xóa migration cũ, rồi chèn dòng history tương ứng trên các database đã tồn tại. Việc này thủ công và dễ sai; chỉ làm khi lịch sử migration đã quá lớn và bạn có môi trường để diễn tập.

Seeding: ba loại dữ liệu, ba cách

HasData chỉ dành cho dữ liệu tham chiếu cố định: mã quốc gia, danh mục hệ thống. Nó cần khóa tường minh, không được dùng DateTime.Now hay giá trị ngẫu nhiên, và mỗi lần sửa sẽ sinh migration update/delete — đúng nhưng ồn ào. Với dữ liệu cần kiểm tra tồn tại hoặc phụ thuộc môi trường, dùng seeding delegate của EF Core 9+:

optionsBuilder.UseSeeding((context, _) =>
{
    if (!context.Set<Category>().Any(c => c.Slug == "books"))
    {
        context.Set<Category>().Add(new Category { Slug = "books", Name = "Sách" });
        context.SaveChanges();
    }
});

Seeding delegate chạy với Migrate, bundle và EnsureCreated, nhưng không chạy khi bạn áp dụng script SQL. Nếu quy trình của bạn là script cho DBA, đừng giả định seed đã có. Dữ liệu cần biến đổi phức tạp thì viết SQL trong migration hoặc một job riêng, đừng nhồi vào HasData.

MigrateAsync lúc startup: được, nhưng có giá

Gọi await db.Database.MigrateAsync(ct) trong startup là cách đơn giản nhất để deploy một app nhỏ. Cái giá: ứng dụng cần quyền DDL, thời gian khởi động phụ thuộc migration, không ai review SQL, rollback khó, và mọi replica đều thử migrate — lock của EF Core 9+ giúp không hỏng schema, nhưng replica đến sau vẫn chờ. Với hệ thống nhiều instance hoặc cần HA, tách migration thành job một lần. Với app một instance, startup migration chấp nhận được nếu bạn có backup và biết cách rollback.

Đừng gọi EnsureCreated trước Migrate. EnsureCreated tạo schema không có bảng history, khiến Migrate thất bại.

Checklist production

  • has-pending-model-changes là gate CI, không phải lệnh chạy tay khi nhớ.
  • Migration được review bởi người thứ hai, đặc biệt khi có DropColumn, DropTable, ALTER COLUMN hoặc Sql(...).
  • Backfill chạy theo lô, có thể dừng và chạy lại; không nằm trong migration.
  • Script hoặc bundle đã diễn tập trên bản copy production có cùng kích thước dữ liệu.
  • Identity deploy có quyền DDL; identity runtime không có.
  • Rollback = restore backup đã kiểm tra, không chỉ là chạy Down.

2027

.NET 11 GA tháng 11/2026 (STS), EF Core 11 đi cùng; .NET 12 LTS dự kiến 2027. Xu hướng rõ ràng là migration được đóng gói và chạy như artifact deploy, không phải như một đoạn code trong startup. Kỹ năng giữ nguyên giá trị là expand-contract và đọc migration trước khi chạy.

Đọc tiếp: EF Core Code-First, Change Tracking trong EF Core, Stored Procedures, Constraints & Triggers, và GitHub Actions cho ASP.NET Core.