Skip to main content
Agent skill

Add Migration

Use when an EF Core model change needs a migration, or when a migration has to be reviewed as SQL before it is committed.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Add Migration when an AI agent needs a reusable SKILL.md workflow for this job: Use when an EF Core model change needs a migration, or when a migration has to be reviewed as SQL before it is committed.

When not to use it

Skip Add Migration when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/add-migration
# Save SKILL.md to ~/.claude/skills/add-migration/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/add-migration/SKILL.md. For a shared project, commit the folder at .claude/skills/add-migration/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Add Migration skill for this task: Use Add Migration when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

67/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
72/100
Practical detail
68/100
Source evidence
54/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Add Migration

Appends one EF Core migration for the current model and reviews it as SQL. Applying it is the pipeline's: nothing here starts Docker, the orchestration, or a database.

**Every migration in this repository is permanent.** Nothing regenerates, renames, reorders, or deletes one, and no command here does either. A migration identifier is written into `__EFMigrationsHistory` on every database that applies it, so a regenerated baseline leaves that database recording an identifier no later migration can reach — it can then only be recreated, which means destroying whatever mail it held. The workflow is additive for every database that exists, which includes the persistent local one, not only the ones a release will create.

Clearing local data is a different operation with a different command, and it touches no file:

```bash aspire resource mailfathom-migrations ef-database-reset --apphost backend/src/AppHost/AppHost.csproj --non-interactive ```

## Preconditions

- The model change is saved. Docker is not required at any step. - A deployment that configures a non-default `Persistence:TextSearchConfiguration` exports it first, because the value is compiled into the search vector's stored generated column and a migration is generated for exactly one configuration:

```bash export Persistence__TextSearchConfiguration=english ```

The host compares the configured value against the live schema at startup and refuses to run on a mismatch, so skipping this produces a startup failure rather than a silently wrong index.

## Workflow

### 1. Generate

```bash scripts/add-migration.sh <MigrationName> ```

The name describes what the migration does to the schema, in PascalCase — `AddEmailRetentionPolicy`, not `Update2`. It becomes part of a permanent identity, so it is chosen once. The script refuses `Initial`, refuses a name already in use, builds the startup project so the tool reads the current model, generates the migration, and writes the copyright and license header into it.

Nothing here starts the orchestration or touches a database. Generating a migration compares the model against the committed model snapshot and writes files, which has the same answer whether or not PostgreSQL is running, so the script points the design-time factory at a port nothing listens on — if generation ever starts requiring a database, it fails rather than silently reaching one.

Three files change under `backend/src/Infrastructure/Persistence/Migrations/`: the new migration, its designer file, and the model snapshot. The snapshot is the only existing file the workflow rewrites, and EF owns it — never hand-edit it. The `.editorconfig` beside them is hand-written and relaxes the two diagnostics EF's generator trips.

**An empty migration means the model did not change.** EF generates one with empty `Up` and `Down` methods rather than failing, so delete it and find out why the change did not reach the model — a configuration not applied, a property on a type the context does not map, a build that did not run. An intentionally SQL-only migration is the one exception: it is written deliberately, says in a comment why it carries no model change, and is reviewed as SQL like any other.

### 2. Review it as SQL, not only as C#

This is the step the whole workflow exists for, and it is the one no script performs: the generated C# hides what PostgreSQL was actually asked to do.

```bash scripts/script-migration.sh ```

With no arguments this scripts the newest migration from the one before it, which is the range a review has to cover. `scripts/script-migration.sh 0` produces the whole schema from an empty database instead.

Read it for: destructive operations, and in particular a rename EF inferred as a drop followed by an add, which loses every value in the column; the PostgreSQL types, nullability, and defaults each column ends up with; the indexes and constraints the documented query shapes need; `ON DELETE` behavior on each foreign key; the generated `tsvector` column and its text search configuration; and the lock and duration a statement implies on a table that already holds mail.

Fix the model and regenerate rather than hand-editing the generated migration — but once a migration has merged, it is fixed forward by another migration instead.

### 3. Commit it with the model change

Update `docs/architecture/stored-email-schema.md` when the change is visible to a reader of the schema, and commit the migration together with the model change that caused it. A migration committed on its own cannot be reviewed, because the reason for it is in the other commit.

### 4. Let the pipeline apply it

Nothing here applies the migration to a database: the pull request does. Two `Backend` jobs answer for it.

- `Pending model changes` runs `dotnet ef migrations has-pending-model-changes` on any pull request touching `backend/src/`, so a model change that reaches `main` without its migration fails before merge rather than at a host's startup. - `Apply migrations` runs on any pull request touching a migration, the app model, or the tooling that generates the schema artifact. It builds the artifact an operator applies, applies it to an empty PostgreSQL twice and over the newest release's schema and the rows that release seeded, and fails when the upgraded schema differs from the fresh one. The schema PostgreSQL ended up holding is the run's `applied-schema` artifact — read it beside the SQL from step 2.

A local orchestration still applies pending migrations when it starts, which is how a developer's own database keeps up; that is a convenience of `aspire start`, not a step this workflow asks for.

## When something is stuck

- **`Changes have been made to the model since the last migration` in CI, but nothing looks changed.** The model snapshot is stale rather than the model. Configuration that produces no SQL — a constraint name, an index filter — still moves the snapshot, so the fix is a migration whose `Up` is empty by design or a regenerated snapshot as part of the next real migration.

- **`Apply migrations` fails on the upgrade but not on the empty database.** The migration assumes a table holds nothing, or holds only what a fresh installation seeds: a `NOT NULL` column with no default, a constraint the release's seeded rows violate. Fix the model and regenerate, as step 2 says.

- **`Apply migrations` reports that the upgraded schema differs.** The diff in its log is what an existing installation would carry and a fresh one would not. A migration whose effect depends on what the database already holds is the usual cause; make it produce the same schema either way.

- **`error IDE0073` on a generated migration.** The formatter did not reach it. `--include` has to name the files rather than their directory, and the scope has to be the solution: these files belong to `Infrastructure`, and an `--include` filter evaluated against another project's workspace silently matches nothing and still exits `0`.

Intended uses

  • Use Add Migration when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.