DEV Community: Ollie

Running EF Core migrations across tenant databases

Ollie — Sat, 03 Oct 2026 03:05:14 +0000

Checked against Tenantry 0.5, .NET 10 and EF Core 10.

With one database for everyone, a release applies its EF Core migrations once, with dotnet ef database update or a
migration bundle. With a database for each tenant, or a schema for each, the same release has to apply them to every
tenant's database, and dotnet ef database update updates one database at a time.

This post looks at what that takes, first by hand and then with Tenantry Pro's migration runner.

The loop most applications start with

Given Tenantry Core's tenant scopes, each of which connects the context to its tenant's database, the first version
is a loop at startup:

foreach (var tenant in await tenants.GetAllTenantsAsync(ct))
{
    await using var scope = scopes.CreateScope(tenant);
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync(ct);
}

It works for a handful of tenants, and then:

One failure stops the rest. A tenant whose database is unreachable, or whose data breaks a migration, throws, and the application fails to start, with the tenants before it on the new schema and those after it on the old one. Catching the exception keeps the loop going, but then something has to record which databases failed and why.
It runs on every instance. At startup, each replica migrates every tenant, so each one's startup grows with the number of tenants, and the load on your databases with tenants times replicas.
It takes as long as all the databases together. Migrating them one after another is slow once there are hundreds; migrating them all at once overwhelms the server.
It cannot tell you where things stand without migrating: which databases are behind, and by which migrations.
New tenants need it too, between creating their database and serving their first request.

The same with Tenantry Pro

Tenantry Pro's runner applies your existing migrations to every tenant's database or schema. It is registered next to
the database-per-tenant setup that Tenantry Core already has:

builder.Services.AddTenantry<string>(tenant => tenant
    .ResolveFromHeader("X-Tenant-Id")
    .UseStore<TenantStore>()
    .UseConnectionStrings(o => o.GetConnectionString = t =>
        $"Host=db;Database=app_{t.TenantId};Username=app;Password={builder.Configuration["DbPassword"]}")
    .UsePro(pro => pro.AddMigrations<AppDbContext>(o => o.MaxConcurrency = 4))
    .AddDbContextPerTenantDatabase<AppDbContext>((_, options) => options.UseNpgsql()));

It creates each tenant's context in that tenant's scope, as a request does, so the context's connection string,
schema and interceptors are the ones your application uses.

As a deployment step

The recommended way to run it is once per release, from one process, before the new version takes traffic: a CI/CD
stage or a Kubernetes Job. (An init container runs in every replica, which is the case to avoid.) The application
runs the migrations and exits when it is started with migrate-tenants:

await using var app = builder.Build();   // disposing it at exit writes out the last log messages

// dotnet MyApp.dll migrate-tenants
if (await app.RunTenantMigrationsIfRequestedAsync(args) is { } exitCode)
    return exitCode;   // 1 if any database failed, which fails the deployment step

await app.RunAsync();
return 0;

It is the same build you deploy, so the migrations, the tenant store and the connection strings are the release's
own. Each failure is logged once, as an error, and the run ends with a summary. A non-zero exit code stops the
pipeline before the new version starts.

What a run does with failures

Each database is on its own. A failure in one never stops the others. The run goes on, and the report says which databases failed and why.
A rerun picks up where it stopped. EF Core applies only what is pending, so after fixing the cause the same command finishes the job.
Tenants that share a database or schema are migrated once, together, and share one result: the shared database in mixed mode, say.
Cancelling stops it. Databases in progress are abandoned, the rest are not started, and those already migrated stay migrated.

From code, ITenantMigrationRunner<TKey> returns the report, and can report each database as it completes:

var report = await migrations.MigrateAllAsync(
    new Progress<MigrationResult<string>>(r => Console.WriteLine(
        $"{r.Database}: {(r.Succeeded ? $"{r.AppliedMigrations.Count} applied" : r.Error!.Message)}")),
    ct);

Console.WriteLine($"{report.Succeeded} of {report.Total} databases migrated");

Each result names its tenants, its database and schema, the migrations this run applied, its duration and, if it
failed, the exception. "Applied" means applied by this run: a migration another process applied first is not counted.

How many at once

By default the databases are migrated one at a time, so the database server is never flooded. MaxConcurrency (4
above) migrates several at once, which helps most when tenant databases are spread over several servers.

Where things stand

The runner also reads the status without changing anything, and without a licence check:

var status = await migrations.GetStatusAsync(ct);
var behind = status
    .Where(entry => !entry.IsUpToDate)
    .Select(entry => $"{entry.Database}: {entry.Error?.Message ?? $"{entry.PendingMigrations.Count} pending"}");

A database that cannot be read gets an entry with its error rather than failing the whole call. Tenantry Pro's
migration health check reports the same, for your monitoring.

New tenants

Provisioning a tenant runs the same migrations as one of its steps, after creating the database or schema and before
your seeders, so a new tenant starts on the current schema. See tenant lifecycle.

A schema per tenant

With a schema per tenant on SQL Server or PostgreSQL, migrations are generated as usual, without a schema, and each
tenant's tables, indexes, keys, sequences and migration history go into its own schema when they are applied.
SQL you add with migrationBuilder.Sql(...) is applied as written, so keep tenant migrations to EF Core's
operations.

Limits

There is no lock across instances. EF Core 9 and later lock a database while migrating it, on providers that support it, but two runs at once still both work through every tenant, and with EF Core 8, or PostgreSQL with EF Core 10, they can race on the same migration. Run it once, as a deployment step, rather than at startup on every replica.
It applies migrations; it does not write them. Generate them with dotnet ef migrations add as before.
MigrateAsync creates a database that does not exist, so a wrong connection string gets a new, empty database rather than an error. Create tenant databases with provisioning, and check the connection strings your store produces.
Migrations are not Native AOT compatible, here as in EF Core.

The tenant migrations guide has the rest, including running at startup for a
single instance and the exact behaviour of each EF Core version and database.

Read the tenant migrations guide

Add multi-tenancy to an existing ASP.NET Core application

Ollie — Sat, 03 Oct 2026 03:05:12 +0000

Checked against Tenantry 0.5, .NET 10, EF Core 10 and PostgreSQL 16.

Most applications do not start multi-tenant. They gain a second customer, then a third, and every query gains a
WHERE OrganisationId = …. One query without it shows a customer another customer's data.

This post adds tenant isolation to an application like that with Tenantry Core, the open-source part
of Tenantry. The organisations table stays the tenant registry, the tenant comes from the request, and EF Core applies
it to every query and save. The context stays the one you have.

The starting point

An ASP.NET Core API over EF Core and PostgreSQL. Organisations are the customers, and each order belongs to one:

public class Organisation
{
    public Guid Id { get; set; }
    public string Name { get; set; } = "";
    public string Slug { get; set; } = "";      // acme, as in acme.example.com
    public bool IsActive { get; set; } = true;
}

public class Order
{
    public int Id { get; set; }
    public string Reference { get; set; } = "";
    public decimal Total { get; set; }
    public Guid OrganisationId { get; set; }
    public Organisation? Organisation { get; set; }
}

public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Organisation> Organisations => Set<Organisation>();
    public DbSet<Order> Orders => Set<Order>();
}

Add the two packages:

dotnet add package Tenantry.AspNetCore
dotnet add package Tenantry.EfCore

1. The organisations table is the tenant registry

Tenantry has no tenants table of its own. It reads tenants from a store you write over what you already have, which
finds a tenant by id and lists them all. Override the third method when requests name a tenant by a slug or a domain.

public sealed record OrganisationTenant(Guid TenantId, string Name, bool IsActive) : ITenantDescriptor<Guid>;

public sealed class OrganisationTenantStore(AppDbContext db) : ITenantStore<Guid>
{
    public async ValueTask<ITenantDescriptor<Guid>?> GetTenantAsync(Guid tenantId, CancellationToken ct = default) =>
        await db.Organisations.AsNoTracking()
            .Where(o => o.Id == tenantId)
            .Select(o => new OrganisationTenant(o.Id, o.Name, o.IsActive))
            .SingleOrDefaultAsync(ct);

    public async ValueTask<IReadOnlyList<ITenantDescriptor<Guid>>> GetAllTenantsAsync(CancellationToken ct = default) =>
        await db.Organisations.AsNoTracking()
            .Select(o => new OrganisationTenant(o.Id, o.Name, o.IsActive))
            .ToListAsync<ITenantDescriptor<Guid>>(ct);

    // Requests name an organisation by its subdomain: acme.example.com.
    public async ValueTask<ITenantDescriptor<Guid>?> FindByIdentifierAsync(string identifier, CancellationToken ct = default) =>
        await db.Organisations.AsNoTracking()
            .Where(o => o.Slug == identifier)
            .Select(o => new OrganisationTenant(o.Id, o.Name, o.IsActive))
            .SingleOrDefaultAsync(ct);
}

The store only reads: creating and changing organisations stays in your code. It lists inactive organisations too,
because tools that work through every tenant, such as migrations, need them. The next step decides whether one may be
used. Organisation is not tenant-owned, so the store's queries are not filtered.

2. Resolve the tenant, and check that the caller may use it

builder.Services.AddTenantry<Guid>(tenant => tenant
    .ResolveFromSubdomain(o => o.BaseDomains.Add("example.com"))   // acme.example.com → acme
    .UseStore<OrganisationTenantStore>()
    .CacheTenants()                                                 // five minutes by default
    .RequireTenantByDefault()
    .ValidateTenantAccessByClaim("org_id")                          // the caller belongs to it
    .ValidateTenantAccess((_, t) => t.As<OrganisationTenant>().IsActive));

app.UseAuthentication();
app.UseTenantry();
app.UseAuthorization();

Anyone can type a subdomain, so the access validators check the caller before the organisation becomes current:

the user's org_id claims must include the organisation's id, and it must be active;
otherwise the answer is 403, the same as for an organisation that does not exist, so users cannot find out which others do;
a request with no organisation gets 400, unless its endpoint calls AllowMissingTenant();
UseTenantry() goes after UseAuthentication(), because the validators read the user.

With CacheTenants, a deactivated organisation is served from the cache until its entry expires; call
ITenantInvalidator<Guid>.InvalidateAsync when you deactivate one.

3. Mark the tenant-owned entities

An entity is tenant-owned when it implements ITenantEntity<Guid>, whose one member is TenantId. Orders already
have that column, OrganisationId, so rename the property and keep the column and the relationship:

public class Order : ITenantEntity<Guid>
{
    public int Id { get; set; }
    public string Reference { get; set; } = "";
    public decimal Total { get; set; }
    public Guid TenantId { get; private set; }               // was OrganisationId
    public Organisation? Organisation { get; private set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Order>(order =>
    {
        order.Property(o => o.TenantId).HasColumnName("OrganisationId");
        order.HasOne(o => o.Organisation).WithMany().HasForeignKey(o => o.TenantId);
    });
}

No table changes and no data moves: your next migration changes only the model snapshot. The setter can be private,
because Tenantry sets TenantId on insert, and the compiler then finds the code that used to set OrganisationId by
hand.

4. One call on the context

builder.Services.AddDbContext<AppDbContext>(options => options
    .UseNpgsql(builder.Configuration.GetConnectionString("App"))
    .UseTenantry());

AppDbContext is still a plain DbContext: no base class, no interface and no SaveChanges override. With
AddDbContextPool the call is the same, and a pooled context reads the tenant each time it is used rather than when it
was created.

What it does now

I ran the following against PostgreSQL 16, with two organisations, Acme and Globex.

Queries are filtered. In Acme's requests, db.Orders.ToListAsync() returns Acme's orders, and FindAsync with
the id of a Globex order returns null, so an endpoint that loads before it changes answers 404. With no tenant, a
query matches nothing rather than everything.

Inserts are stamped with the current tenant. An insert that names another tenant throws
TenantIsolationViolationException, and one with no tenant at all throws TenantNotResolvedException; nothing is
written either way.

Updates and deletes are checked twice. An entity can be changed only while its own tenant is current, and it must
have been loaded or attached as that tenant. So an update built straight from a request body is refused, whichever
organisation the order belongs to:

// Refused: a new instance has no tenant, so SaveChanges throws TenantIsolationViolationException.
db.Orders.Update(new Order { Id = id, Reference = input.Reference, Total = input.Total });

// Load it as the current tenant, then change it: Globex's order is not found in Acme's request.
var order = await db.Orders.FindAsync(id);
if (order is null) return Results.NotFound();
order.Reference = input.Reference;

The second check is in the SQL. TenantId is a concurrency token, so the stored tenant is part of every UPDATE and
DELETE:

UPDATE "Orders" SET "Total" = @p0 WHERE "Id" = @p1 AND "OrganisationId" = @p2;

An entity that pairs Globex's order id with Acme's tenant id, the forged case, passes the first check and matches no
row: EF Core throws DbUpdateConcurrencyException, and Globex's order is unchanged.

Bulk updates and deletes (ExecuteUpdate, ExecuteDelete) are filtered in the same way, and an ExecuteUpdate
may not set TenantId.

What it does not do

The isolation is in EF Core, not in the database:

Raw SQL (FromSql, SqlQuery, ExecuteSql) is not seen. Add the tenant to it yourself.
IgnoreQueryFilters() turns the tenant filter off for that query, for administrators' reports. On EF Core 10, IgnoreQueryFilters([TenantryQueryFilters.Tenant]) keeps your other filters.
A context whose options do not call UseTenantry() is not isolated.
Anything that reaches the database directly is not checked. If that matters, add row-level security in the database, or give each tenant a database of its own.

The EF Core guide lists every case.

Background work

A job or a queue consumer has no subdomain. Open a scope for the organisation instead, with an injected
ITenantScopeFactory<Guid>:

await scopes.RunInScopeAsync(message.OrganisationId, async (scope, ct) =>
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    // Filtered and stamped for this organisation, as in a request.
}, cancellationToken);

Access validators run only for requests, so background work checks IsActive itself.

From here

The same store and resolution work with a database per tenant: UseConnectionStrings gives each organisation its
connection string, and AddDbContextPerTenantDatabase connects each context to it, pooled if you like. Tenant keys
can be int or string as well as Guid. The SecureApi sample
puts this together with JWT authentication and integration tests.

Get started with Tenantry Core