efcore-postgres-dotnet · git:20261108.c2f94bf · 2026-11-08 · sha256 762f2233157c9154
efcore-postgres-dotnet git:20261108.c2f94bfA
Immutable. This exact content never changes and is served at /api/v1/blob/762f2233157c9154.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_m6uf4lpv6fmcekdw/762f2233157c9154b8af20ea28ecad53b108bab0602884c00d5b2c5f5de7c191.json
Then /plugin install efcore-postgres-dotnet@markdownregistry-m6uf4lpv6fmcekdw in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: efcore-postgres-dotnet
description: >-
EF Core on PostgreSQL with Npgsql — the provider specifics on top of
`efcore-dotnet`. Use when mapping or querying a Postgres store from EF Core:
optimistic concurrency, date and time columns, the legacy timestamp
switch, precision, collation, schemas, indexes, or the Npgsql
registration. It encodes: xmin as a shadow row version, the legacy
timestamp switch with `timestamp without time zone` kept on purpose,
microsecond precision, the database collation, one schema per layer, and
indexes only on foreign keys.
---
# EF Core on PostgreSQL (Npgsql)
The Postgres specifics of `efcore-dotnet`, through `Npgsql.EntityFrameworkCore.PostgreSQL`: `options.UseNpgsql(connectionString)`, the connection string read where the context is registered and required at startup.
## Optimistic concurrency — xmin
When writes to a row can race (concurrent consumers, see `messaging`), guard them with Postgres's own row version:
```csharp
entity
.Property<uint>("Version")
.IsRowVersion();
```
- **A shadow property over `xmin`**: every Postgres row has it, so there is no column to add, nothing in the aggregate and no migration.
- A save over a row written since it was read throws `DbUpdateConcurrencyException`. Let it propagate — the message is retried and the use case re-decides against the row as it now is. No retry loop in the service.
- It works because the operation reads and writes through one scoped context, so the tracker holds the original `xmin`.
- Only where writes can actually race. A table written by one sequential process doesn't need it.
## Dates and times
- **The legacy timestamp switch stays**: `AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true)` in `Program.cs`, before the host is built, and every date column mapped as **`HasColumnType("timestamp without time zone")`**. Moving to `timestamptz` means migrating live columns — the end state, deliberately deferred. Don't mix models: new date columns follow the same convention.
- Without the switch Npgsql refuses to write a `DateTime` of `Kind.Utc` into a `timestamp without time zone` column; with it, a read comes back `Unspecified` — which is why the columns this layer writes in UTC get the kind converter on the mapping (see `efcore-dotnet`).
- **Postgres keeps microseconds**; .NET carries 100 ns. A date written and read back, or sent as a parameter, is truncated — so dates that are compared (a version guard, a sweep) are truncated to microseconds before they are stored, or a redelivered `…4567` looks newer than the stored `…4560`. The truncation lives in the value object's conversion (see `ddd-dotnet`).
- Test fixtures set the same switch before the first connection, or the suite runs under different rules than production.
## Collation, schemas, names
- The model declares the database's collation — `modelBuilder.UseCollation("<the store's collation>")`, e.g. `"es_ES.UTF8"` — so ordering and comparisons agree with the store's.
- **One schema per store**, never `public`: `ToTable("pedidos", "<schema>")`. Tables and columns in snake_case, constraints named (`pk_pedidos`).
- The schema scripts are idempotent (`CREATE … IF NOT EXISTS`) and run in order: schema, tables, indexes — then `migrations/`, by version and not by name — `6.9.0` before `6.10.0` — each an `ALTER TABLE … ADD COLUMN IF NOT EXISTS …` (see `efcore-dotnet`).
- **String columns are `text`.** Postgres stores `text` and `varchar(n)` the same way; a bound in the type is a rule enforced by the store, with a `22001` instead of the typed `ValidationException`, and changing it is an `ALTER`. The rule lives in the value object's validator, and there is no `HasMaxLength` on a Postgres mapping — with an explicit `text` it does nothing.
## Indexes
**Only the foreign keys are indexed**, as plain ascending `(col)` indexes. Flag columns (`meta_active`) were measured and are useless — a value shared by most rows makes the planner scan anyway — so don't add them. Any other index needs a measured query plan that uses it.