Modernization

Upgrade EF Core with yesterday’s orders still intact

Use existing records to decide whether an ORM upgrade is ready, and keep database changes deliberate.

Published · AI disclosure

The upgrade builds, the application starts, and a new order saves. Before releasing it, the business still needs confidence that:

  • Orders created before the upgrade remain readable
  • Editing one field preserves the rest of the order
  • Searches and fulfillment receive the same business information
  • A return to the previous release remains workable after new writes

Start with one consequential feature: updating an existing order without changing its delivery instructions. That gives the team a concrete result to protect while upgrading the data-access layer.

Find out what the upgrade changes in storage

A package update can change more than the code that runs a query. Microsoft documents a specific example in EF Core 10: by default with UseAzureSql, or with an EF SQL Server compatibility setting of 170 or higher, JSON-mapped properties use the native json column type. Earlier versions used nvarchar(max). When the team scaffolds a migration, that difference can produce column alterations. Microsoft also identifies query restrictions that differ between the types. See the EF Core 10 breaking changes.

This documented change does not establish that data will be lost. It establishes a decision: does this release include a storage-format change, or should that work be evaluated separately?

An explicitly lower EF compatibility setting can retain text mapping with UseAzureSql. For an existing SQL Server JSON collection, EF Core 10 also allows the team to retain the text column explicitly. In the application’s OnModelCreating, where Order.DeliveryInstructions is a mapped string[]:

C#
modelBuilder.Entity<Order>()
    .PrimitiveCollection(o => o.DeliveryInstructions)
    .HasColumnType("nvarchar(max)");

Review the resulting migration against the existing schema. This setting addresses one column mapping; it does not settle the rest of the upgrade. The migration guidance also explains why a rename can be generated as a destructive drop-and-add operation and needs human review.

Bring yesterday’s records into the test

A database created entirely by the new version cannot show whether older records survived the transition.

Prepare an isolated database containing representative records produced by the previous release. Use controlled fixtures or an authorized, suitably sanitized restore. Keep the actual database engine, relevant configuration, and provider in the rehearsal: Microsoft describes material differences between SQL Server and SQLite test behavior.

Record expected values before upgrading. For the chosen order, retain its identifier, customer, total, currency, status, and delivery instructions. Include historical variations the business still supports, such as empty instructions and non-ASCII text. Apply the reviewed migration, if one is needed, then run the upgraded application against those records.

The first question is whether the same orders still mean the same thing. Counts can detect missing records; comparisons of agreed business fields can detect changes that counts miss.

Does an ordinary edit preserve the existing data?

Reading an order successfully leaves another question: what happens when someone saves it?

The following integration-test fragment changes an unrelated field, then reads the delivery instructions through a fresh context. It assumes the application’s OrdersDb, production-provider options, C# 12 or later, xUnit, and an isolated historical fixture containing order 1042 with the two expected instructions and a different starting InternalNote.

C#
using Microsoft.EntityFrameworkCore;
using Xunit;

string[] expected = ["Use side entrance", "Call on arrival"];

await using (var write = new OrdersDb(options))
{
    var order = await write.Orders.SingleAsync(o => o.Id == 1042);
    Assert.Equal<string>(expected, order.DeliveryInstructions);
    order.InternalNote = "Rechecked";
    await write.SaveChangesAsync();
}

await using var read = new OrdersDb(options);
var saved = await read.Orders.AsNoTracking()
    .SingleAsync(o => o.Id == 1042);
Assert.Equal<string>(expected, saved.DeliveryInstructions);
Assert.Equal("Rechecked", saved.InternalNote);

The expected instructions must survive. A fresh read matters because EF’s tracking queries can return an existing tracked instance. The final assertion also checks that the edit was stored. Extend the full test to the other protected values.

The APIs above were checked against the referenced product documentation; these fragments were not executed against SQL Server or Azure SQL. They demonstrate the check to implement, not evidence that a production upgrade has passed.

Decide what a return to the previous release means

If operations expects to restore the old application, rehearse that version reading and updating records written by the new one against the resulting schema. Moving traffic back does not reverse stored writes. A database restore needs its own decision about acceptable lost work and reconciliation.

Commission one bounded review of this existing-order edit. Ask for a short release recommendation containing:

  • The migration diff, with each schema change explained
  • Results from the historical-record rehearsal, including read, edit, and fresh-read checks on the actual database provider
  • A recovery recommendation with its rehearsed evidence, data limits, and decision owner

That report gives the release owner a practical basis for proceeding, separating a storage change, or holding the upgrade until a specific failure is resolved.

Discuss a verification engagement

Sources

Written with AI and not reviewed by a human. It may contain mistakes.