Migrate New

Create a New Migration

Migrations in ncps are derived from the Ent schemas under ent/schema/. The schema is the only source of truth for DDL; SQL migration files are generated by cmd/generate-migrations (Atlas, used as a Go library) and applied at runtime by ncps migrate up (goose-driven).

Never hand-author a .sql file under migrations/<dialect>/ — Atlas seals the directory with atlas.sum and CI rejects any drift. The only exception is the --sql-only mode below, which is used for data backfills and the four-step NOT NULL recipe.

Workflow

1. Edit the Ent schema. Open ent/schema/<entity>.go and add or modify the field, edge, index, or annotation. New entities go in a new file under ent/schema/.

   The five codegen invariants apply — see .agent/skills/ent-schema/SKILL.md and cmd/ent-lint/ for enforcement details.

2. Regenerate the Ent client. This refreshes ent/migrate/schema.go, which cmd/generate-migrations then diffs against the on-disk migration history.

   go generate ./ent/...
   # or
   task ent:generate
   

   Commit the regenerated ent/ tree alongside the schema change — the ent-codegen-drift-check derivation in nix flake check rejects any commit where the tree is stale.

3. Generate per-dialect Atlas migrations. One descriptive snake_case name produces three new .sql files (sqlite + postgres + mysql) under migrations/<dialect>/ sharing one timestamp prefix, plus regenerates atlas.sum for each dialect.

   go run ./cmd/generate-migrations --name=add_users_table
   # or
   task migrations:gen NAME=add_users_table
   

   Placeholder names (auto, wip, tmp, todo, temp, test, empty, whitespace) are rejected — supply a descriptive identifier.

4. Review the generated SQL. Open each new file under migrations/<dialect>/ and verify:

   • The header carries -- +goose Up and -- +goose Down markers.
   • SQLite files that use PRAGMA foreign_keys = OFF to drive a temp-table-copy-rename rewrite ALSO carry -- +goose NO TRANSACTION at the top (goose otherwise wraps the migration in a transaction, which is incompatible with the PRAGMA).
   • The down migration is a clean inverse of the up — Ent's auto-generated down handles most cases, but verify nontrivial migrations by hand.

5. Data backfills + four-step NOT NULL recipe. Use --sql-only to emit empty Goose stubs (no Ent diff is run); fill them in manually.

   go run ./cmd/generate-migrations --sql-only --name=backfill_emails
   # or
   task migrations:sql NAME=backfill_emails
   

   The expand-contract policy applies — see CLAUDE.md and the data-model spec for the rationale. Never alter a column in place; split the change across multiple migrations.

Skips and overrides

• --skip=sqlite,mysql skips dialects you don't want regenerated. This is the escape hatch for hand-translated migrations (e.g. the Postgres bridge in §8 of the migrate-to-ent-and-atlas change).
• --postgres-url=<dsn> / --mysql-url=<dsn> (or NCPS_GEN_POSTGRES_URL / NCPS_GEN_MYSQL_URL) override the dev database URLs. Default URLs target the localhost test-user@test-db that nix run .#deps provides.

Verifying

• task ent:check (or go generate ./ent/... && git diff --exit-code ./ent/) confirms the Ent client is up to date.
• go run ./cmd/ent-lint --root . checks schemas against the implemented invariants (A1, A2, A4); A3 and A5 are enforced by code review until wired into the linter.
• go run ./cmd/atlas-sum-check --root . confirms every atlas.sum matches the directory contents.
• go test -race -run TestSchemaEquivalence ./migrations/... runs the load-bearing golden test against all three dialects (uses nix run .#deps for the Postgres + MySQL paths).

All four checks are wired into nix flake check as separate derivations under nix/checks/flake-module.nix.