# Cratis Arc Ef Core Migration

> Use when adding or changing an EF Core table, column, relationship or index behind an Arc application. Not for Chronicle read-model projections or query paging.

- Skill: `cratis/cratis-arc-ef-core-migration-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add cratis/cratis-arc-ef-core-migration-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cratis/cratis-arc-ef-core-migration-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Cratis (https://skillmd.com/u/cratis)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/cratis/cratis-arc-ef-core-migration-2

---


# Change an EF Core schema in an Arc application

Arc adds three things to Entity Framework Core: DbContext base types that apply
its conversions, cross-database column helpers for migrations, and a resolver
that makes an EF Core read model injectable into a command by the command's key.
Everything else is ordinary EF Core.

## Verified product sources

| Package | Purpose |
| --- | --- |
| `Cratis.Arc.EntityFrameworkCore` | `BaseDbContext`, `ReadOnlyDbContext`, `WithEntityFrameworkCore`, column helpers, `EntityFrameworkReadModelForCommandResolver` |
| `Cratis.Arc.Core` | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute`, `ICanResolveReadModelForCommand` |
| `Microsoft.EntityFrameworkCore` | EF Core itself, including all migration tooling |

Verify provider-specific migration behavior against the configured provider and the installed Arc version.

⚠️ **Arc ships no migration tooling of its own.** There is no design-time
DbContext factory, no migration runner, no table-name constant convention, and
nothing that reads or writes `__EFMigrationsHistory` anywhere in Arc. Migrations
are created and applied with the standard EF Core tooling. Guidance describing an
`ApplyAllMigrations` runner, a `WellKnownTables` class, or a mandatory
`Database`/`Core`/`Infrastructure` project split is describing **one
application's local convention**, not Arc.

## Pick the DbContext base type

| Base | Use for |
| --- | --- |
| `ReadOnlyDbContext` | Read models and projections — the vast majority |
| `BaseDbContext` | A context that genuinely owns writable state |

Both take `DbContextOptions` through a primary constructor; **neither has a
parameterless constructor**, so the derived context must pass options through:

```csharp
public class <Feature>DbContext(DbContextOptions<<Feature>DbContext> options)
    : ReadOnlyDbContext(options)
{
    public DbSet<<ReadModel>> <ReadModels> => Set<<ReadModel>>();
}
```

`BaseDbContext.OnModelCreating` applies Arc's JSON, `ConceptAs<T>` and `Guid`
conversions. Override `OnModelCreating` only after calling `base` — and do not
override `OnConfiguring`.

`ReadOnlyDbContext` throws `InvalidOperationException` from both `SaveChanges()`
and `SaveChangesAsync()`, and eagerly loads every navigation. Turn the eager
loading off by overriding `protected virtual bool IsEagerLoadingEnabled => false`.

Keep one focused context per feature rather than one context holding unrelated
entities.

## Wire it up

```csharp
builder.AddCratisArc(arc => arc.WithEntityFrameworkCore(
    options => options.ConnectionString = <connectionString>));
```

`WithEntityFrameworkCore(configureOptions?, configureEfCore?)` registers the
observation services and then, **only when `AutoDiscoverDbContexts` is true and
the connection string is non-empty**, discovers and registers every public
`BaseDbContext` subtype that is not marked `[IgnoreAutoRegistration]`.

Requires Arc 22.109.0 for options bound from `Cratis:EntityFrameworkCore` before
`configureOptions` runs; that callback wins over configuration. Read
../cratis-arc-hosting/references/connection-resolution.md when resolving tenant or schema-purpose
connections, including pooled contexts.

⚠️ Without a connection string from configuration or the callback,
`WithEntityFrameworkCore()` discovers **nothing**.
`EntityFrameworkCoreOptions.ConnectionString` defaults to the empty string, and
both discovery gates test it. A setup that looks wired and registers no context
is almost always this.

Discovery splits the contexts it finds: `ReadOnlyDbContext` subtypes are
registered read-only, everything else read-write. Registering by hand instead is
supported through `AddDbContextWithConnectionString<T>`,
`AddReadOnlyDbContextWithConnectionString<T>`,
`AddReadModelDbContextsFromAssemblies`, and
`AddReadModelDbContextsWithConnectionStringFromAssemblies` — note their
configuration callback is `Action<IServiceProvider, DbContextOptionsBuilder>`,
taking **two** parameters.

Use `UseDatabaseFromConnectionString(connectionString)` rather than hard-coding
`UseSqlite`/`UseNpgsql`/`UseSqlServer`. It picks the provider from the connection
string, creates a SQLite file's directory when needed, and installs the Arc
migrations SQL generator for that provider — which is what adds the JSON
validation constraint for `[Json]` columns. Supported values of `DatabaseType`
are `Sqlite`, `SqlServer` and `PostgreSql`.

## Making a read model injectable into a command

An EF Core entity becomes a command-injectable read model when **all** of these
hold:

1. the entity type carries `[ReadModel]` — `Cratis.Arc.Queries.ModelBound.ReadModelAttribute`,
   the same attribute a Chronicle read model uses; there is no EF-specific one;
2. it is exposed as a public `DbSet<T>` property;
3. that `DbSet<T>` is on a **`ReadOnlyDbContext`** subtype.

⚠️ Point 3 is the one that bites. A `[ReadModel]` entity on a plain
`BaseDbContext` is still registered and still queryable — it is simply **never**
contributed to command-side resolution, because only read-only contexts are
handed to it. Nothing warns.

The resolver declares `ReadModelForCommandOwnership.Declared`, so a `DbSet<T>`
carrying a read model claims that type even when another provider already
resolves it. Resolution loads the entity by its **single-property primary key**
from the command's resolved key; a composite key throws
`EntityDoesNotHavePrimaryKey`, and a command with no usable key raises
`UnableToResolveReadModelFromCommandContext`, which is a client-input failure
(HTTP 400) rather than a server fault.

`ARC0006` warns when such a parameter is non-nullable, because a command-scoped
read model can be missing; reject a missing one rather than returning a nullable
event from `Handle()`. It is the only Arc diagnostic that touches EF Core
read models, and only because they share `[ReadModel]`.

## Write the migration

Use the standard EF Core tooling — `dotnet ef migrations add <Name>` and
`dotnet ef database update` — with the `Microsoft.EntityFrameworkCore.Design`
package referenced by the project that owns the context. Arc contributes nothing
to how a migration is created, discovered, or applied.

A migration that is committed or applied to any database is append-only: never edit or delete it. Correct a mistake with a new migration. Only a migration that is both unapplied and uncommitted may be removed (`dotnet ef migrations remove`) and regenerated.

What Arc **does** contribute is a set of column helpers that pick the right
provider-specific SQL type, so one migration works across SQLite, SQL Server and
PostgreSQL. Use them instead of a raw `table.Column<T>()` with a hard-coded type.

On `ColumnsBuilder`, inside `CreateTable`:

```csharp
migrationBuilder.CreateTable(
    name: "<Table>",
    columns: table => new
    {
        Id = table.StringColumn(migrationBuilder, nullable: false),
        <Name> = table.StringColumn(migrationBuilder, maxLength: 200, nullable: false),
        <Count> = table.NumberColumn<int>(migrationBuilder, nullable: true),
        <At> = table.DateTimeOffsetColumn(migrationBuilder),
        <Key> = table.GuidColumn(migrationBuilder),
    },
    constraints: table => table.PrimaryKey("PK_<Table>", x => x.Id));
```

`StringColumn`, `NumberColumn<T>`, `BoolColumn`, `AutoIncrementColumn`,
`GuidColumn` and `DateTimeOffsetColumn` all take the `MigrationBuilder` as their
first argument — that is how they learn which database they are generating for.
All of them except `AutoIncrementColumn` default `nullable` to **`true`**, so a
required column has to say `nullable: false` explicitly; `AutoIncrementColumn`
has no `nullable` parameter and is always `NOT NULL`.

On `MigrationBuilder`, for an existing table:

```csharp
migrationBuilder.AddStringColumn(
    name: "<Column>",
    table: "<Table>",
    maxLength: 1000,
    nullable: true);
```

`AddStringColumn`, `AddNumberColumn<T>`, `AddBoolColumn`,
`AddAutoIncrementColumn`, `AddGuidColumn`, `AddDateTimeOffsetColumn`,
`AddPointColumn`, `AddLineStringColumn` and `AddPolygonColumn` follow the same
`(name, table, …, schema)` shape. `NumberColumn<T>`/`AddNumberColumn<T>` are
constrained to `INumber<T>`.

For a JSON column use `table.JsonColumn<T>(migrationBuilder)` or
`migrationBuilder.AddJsonColumn<T>(...)`. Those annotate the operation with
`cratis:ColumnType = "json"`, which is what makes the provider's Arc migrations
generator emit the validation constraint — `json_valid` on SQLite,
`ISJSON(...) = 1` on SQL Server, a `jsonb` check plus a GIN index on PostgreSQL.
Mark the corresponding property `[Json]`.

`migrationBuilder.GetDatabaseType()` is available when a migration genuinely has
to branch per provider.

## Tracked and native upserts

Requires Arc 22.135.0 for `DbSet<TEntity>.UpsertAsync(item, cancellationToken)`.
On supported SQL Server, PostgreSQL and SQLite mappings it executes an immediate,
parameterized native upsert matching the complete primary key, including composite
keys and value converters. Native key matching and writing are atomic. It uses
the context's connection/current transaction, bypasses tracking and does not
refresh generated values or already tracked instances. It adds no retry policy.

Use application-assigned keys and single-table scalar mappings. Unsupported
providers or mappings (including unset generated keys, SQL Server identity
columns, navigations, owned entities, shadow properties, inheritance and multiple
tables) fall back to tracked persistence and require `SaveChangesAsync`. The
existing `Upsert(item)` always uses tracked read-then-write persistence and also
requires saving; that path is not an atomic database upsert. Choose it explicitly
when deferred persistence is required. Do not rely on fallback for concurrency
protection or assume the native path flushes pending tracked changes.

## Observing an EF Core read model

`DbSet<T>` gains `Observe(filter?, configure?)`, `ObserveSingle(filter?, configure?)`
and `ObserveById<TEntity, TId>(id, configure?)`, returning
`ISubject<IEnumerable<T>>` / `ISubject<T>`. Register the services with
`AddEntityFrameworkCoreObservation()` and `options.AddObservation(serviceProvider)`
on the context — `WithEntityFrameworkCore` already does the first for you.

Paging and sorting are applied at the source; the query pipeline validates
`page >= 0` and `pageSize > 0`. Unknown observation sort fields are ignored.
Auxiliary observations can pass `ignoreQueryContext: true` so only the primary
uses client paging/sorting and writes totals. `ObserveSingle`/`ObserveById` emit
`default` when the row is absent/deleted/outside the filter, remaining subscribed.
Indexer-property keys (shared-type entities) are supported; composite and
shadow-only keys are refused at setup. Source:
`Source/DotNET/EntityFrameworkCore/Observe/DbSetObserveExtensions.cs`.

⚠️ Database-level change notification differs by provider: PostgreSQL uses
LISTEN/NOTIFY, SQL Server uses Service Broker, and **SQLite has none at all** —
its notifier is a no-op and only in-process changes are seen. Notification setup
failures are logged and degrade to in-process only rather than failing the app.

## Specify it

Arc ships no EF Core test harness. The framework's own EF Core specifications
use SQLite in-memory with `EnsureCreated()` for the fast path, and real
PostgreSQL and SQL Server containers for provider-specific behavior. The EF Core
in-memory provider is not used anywhere.

`EnsureCreated()` builds the schema from the model, **not** from the migrations,
so a specification suite that uses it will not notice a migration that does not
match the model. Cover the migration itself against a real provider when the
schema shape matters.

## Verify

- The context derives from `ReadOnlyDbContext` (or `BaseDbContext` when it truly
  writes) and passes `DbContextOptions` through.
- A read model intended for command injection carries `[ReadModel]`, is a
  `DbSet<T>`, and sits on a `ReadOnlyDbContext`.
- The read model has a single-property primary key.
- `WithEntityFrameworkCore` is given a non-empty connection string, or contexts
  are registered explicitly.
- No provider is hard-coded; `UseDatabaseFromConnectionString` is used.
- Every migration column goes through an Arc column helper, and required columns
  say `nullable: false`.
- JSON columns are `[Json]` on the model and `JsonColumn`/`AddJsonColumn` in the
  migration.
- The migration was produced and applied with the standard EF Core tooling.
- `dotnet build` is clean in Debug and Release and the specifications pass.

## Route near misses

- A Chronicle-backed read model or projection: the Chronicle read-model guidance.
- Server-side paging or sorting on a query: `cratis-arc-query-paging`.
- What an injected read model resolves to when it does not exist:
  `cratis-arc-command`.

