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:
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
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:
- the entity type carries
[ReadModel]—Cratis.Arc.Queries.ModelBound.ReadModelAttribute, the same attribute a Chronicle read model uses; there is no EF-specific one; - it is exposed as a public
DbSet<T>property; - that
DbSet<T>is on aReadOnlyDbContextsubtype.
⚠️ 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:
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:
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(orBaseDbContextwhen it truly writes) and passesDbContextOptionsthrough. - A read model intended for command injection carries
[ReadModel], is aDbSet<T>, and sits on aReadOnlyDbContext. - The read model has a single-property primary key.
WithEntityFrameworkCoreis given a non-empty connection string, or contexts are registered explicitly.- No provider is hard-coded;
UseDatabaseFromConnectionStringis used. - Every migration column goes through an Arc column helper, and required columns
say
nullable: false. - JSON columns are
[Json]on the model andJsonColumn/AddJsonColumnin the migration. - The migration was produced and applied with the standard EF Core tooling.
dotnet buildis 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.