CoreEx: DB Migration

Guides you through any persistence-shape change for a CoreEx domain — relational schema migrations or Cosmos container/provisioning changes — through to regenerated access-layer artefacts.

When to Use

• Adding a new relational table for a new entity (transactional or reference-data)
• Altering an existing relational table — adding/modifying/removing columns, indexes, or constraints
• Adding or changing a Cosmos container declaration, partition-key shape, or seed-data import for a CoreEx entity
• Any other persistence-shape change that needs to flow through to regenerated *.g.cs Infrastructure files or typed accessors
• Non-entity relational schema changes (adding an index, a unique constraint, a function)

When Not to Use

• Provisioning the transactional outbox — run dotnet run -- script outbox <schema> <name> directly; see coreex-tooling.instructions.md
• Changing reference-data seed rows only — edit Data/ref-data.seed.yaml and run dotnet run -- Data
• Generating CoreEx contracts/services/repositories — that is *.CodeGen, not *.Database
• Runtime or deployment issues

Resolve project-wide choices from state before asking. Read the solution-root AGENTS.md
Feature Configuration for data-provider (SqlServer / Postgres / Cosmos — gates this whole skill; None
means no persistence project) and outbox-enabled. Only prompt for what is unrecorded; re-state resolved values
for confirmation.

Quick Reference

All commands run from the *.Database project directory.

Relational providers (SqlServer / Postgres)

Task	Command
Bring DB up to date	dotnet run -- database
Inspect current table state	dotnet run -- inspect <schema> <table>
New transactional table	dotnet run -- script create <schema> <table>
New reference-data table	dotnet run -- script refdata <schema> <table>
Alter existing table	dotnet run -- script alter <schema> <table>
Non-entity schema change	dotnet run -- script
Apply everything + regenerate	dotnet run -- All
Drop + full rebuild (destructive, confirm first)	dotnet run -- dropandall --accept-prompts

Cosmos provider

Task	Command / file
Declare or change containers	Edit Program.ConfigureProvisionArgs(CosmosDbProvisionArgs)
Add or amend seed data	Edit Data/*.seed.yaml / Data/*.json (top-level key = container id)
Create/import baseline	dotnet run -- All
Recreate containers + data	dotnet run -- ResetAndData
Drop + recreate database (destructive, confirm first)	dotnet run -- DropAndAll

Naming

• Script commands produce a file named yyyyMMdd-HHmmss-<descriptor>.{sql|pgsql} using the current UTC date and time.
• For create, refdata, and alter the descriptor is auto-derived from the table name.
• For bare script (non-entity changes), DbEx names the file with a placeholder suffix — rename it immediately to a 3–5 word kebab summary of intent (e.g. add-unique-code-index, drop-legacy-status-column).
• The complete filename (timestamp + descriptor + extension) must not exceed 255 characters. The project name and Migrations folder (e.g. Contoso.Products.Database.Migrations) are used as an embedded-resource name prefix internally, so keep descriptors concise.

Polyglot Note

Provider	Script extension	Casing
PostgreSQL	.pgsql	snake_case
SQL Server	.sql	PascalCase

Check the project's *.Database/Program.cs or host wiring to confirm the provider in use. Cosmos domains declare containers in ConfigureProvisionArgs(...) instead of dbex.yaml/migration scripts.

For the full step-by-step decision tree, SQL column templates, and guardrails see `references/workflow.md`.

JSON Columns

A column whose name ends with Json (SQL Server) or _json (PostgreSQL) stores a serialised .NET type as JSON text. DbEx surfaces this in Inspect output as Json: Yes.

Three things are required:

1. A columns: entry in dbex.yaml — without it, DbEx generates string? with no converter.
   name: (DB column name including the suffix), property: (C# name without suffix), type: (CLR type, e.g. Persistence.Address? or List<string>?).
2. A hand-authored persistence POCO in Infrastructure/Persistence/ when the stored type is a complex object. For natively-serialisable types (List<string>?, Dictionary<K,V>?, etc.) use the .NET type directly — no extra class needed.
3. No manual .HasConversion(...) call — TypeToJsonStringEfConverter<T> is auto-wired in the generated *DbContext.g.cs when type: is non-string.

Default column types (unless the user explicitly opts into unbounded/native JSON storage): bounded text matching the DB's normal string-column convention — NVARCHAR(n) (SQL Server) / VARCHAR(n) (PostgreSQL), e.g. NVARCHAR(2000)/VARCHAR(2000) as a reasonable starting size. NVARCHAR(MAX) / native JSONB/JSON are an override for when unbounded storage or in-database JSON querying/indexing is deliberately wanted — see samples/src/Contoso.Products.Database (tags_json → native JSONB, an intentional override) vs. samples/src/Contoso.Shopping.Database (ShippingAddressJson → bounded NVARCHAR(2000), the default) for both side-by-side.

For the full workflow, example YAML, DDD aggregate vs CRUD service guidance, and POCO class conventions see `references/workflow.md` — JSON columns.

Key References

• `/.github/instructions/coreex-tooling.instructions.md` — relational DbEx command reference and Cosmos provisioning-console conventions
• `/.github/instructions/coreex-repositories.instructions.md` — what the generated *.g.cs feeds into
• Related skills: `coreex-refdata` (reference-data tables + CodeGen), `coreex-repository` (maps the generated persistence models)
• Illustrative examples (CoreEx sample — not present in your project):
  • PostgreSQL domain database project — canonical .pgsql / snake_case migrations, dbex.yaml, seed files
  • SQL Server domain database project — canonical .sql / PascalCase migrations, dbex.yaml, seed files
  • Cosmos domain database project — CosmosDbConsole, ConfigureProvisionArgs, and container-keyed seed files