backend-orm-migrations

name

backend-orm-migrations

description

Define and implement backend ORM and migration contracts for backend service repos. Use when Codex must choose or apply ORM/migration architecture, add or change database models, create migration files, define migration commands, connect backend code to PostgreSQL or another relational database, or generate implementable task.md instructions for schema/persistence work. Trigger for backend repo work involving SQLAlchemy, SQLModel, Alembic, Django migrations, Prisma, Drizzle, TypeORM, Knex, ORM models, migrations, schema changes, table design, repository/session patterns, or frontend/backend split systems where only the backend repo owns persistence.

Backend ORM Migrations

OpenCode Greenfield Bootstrap Metadata

This is a backend persistence add-on. It is docs-only until a framework-specific bootstrap script is added; use it to load ORM, migration, schema, and task handoff contracts when persistence work is selected or requested.

{
  "role": "backend",
  "category": "database",
  "database": "orm-migrations",
  "frameworks": ["backend", "fastapi", "django", "node", "typescript"],
  "order": 50,
  "packageManager": "none",
  "scaffoldCommand": [],
  "verificationCommands": []
}

Responsibility Boundary

Use this skill only for backend service repos. Frontend/admin UI repos consume API contracts and must not own ORM, migration, table, or database session work.

This skill owns backend persistence architecture:

• ORM/migration framework selection when the repo does not already have one.
• Exact package, path, model, migration, command, and verification contracts.
• Safe schema evolution and migration review.
• Task handoff details that let implementers work without guessing persistence paths.

Use alongside related skills:

• pgdb-docker-orm: PostgreSQL Docker/Compose service, volume, port, DATABASE_URL, DB health and data-safety operations.
• backend-feature-fastapi: FastAPI HTTP feature/router/schema/service structure.
• docker-compose-ops / docker-build: compose and image verification.

Repo Declaration Rule

Backend repos that own persistence should declare this skill in README.md / AGENTS.md together with their backend framework skill and database/devops skill. Example for a FastAPI PostgreSQL service:

backend-feature-fastapi
backend-orm-migrations
pgdb-docker-orm
docker-build
docker-compose-ops

Frontend, admin UI, and other client repos must not declare this skill unless they contain the backend service that owns migrations. They consume API payloads from backend tasks instead.

Decision Workflow

1. Read backend repo evidence first: README.md, AGENTS.md, manifests, existing DB modules, ORM configs, migration dirs, and package scripts.
2. If an ORM/migration framework already exists, keep it. Do not introduce a second migration framework.
3. If the backend stack is FastAPI + uv + PostgreSQL and no ORM/migration framework exists, use references/fastapi-sqlalchemy-alembic.md.
4. If the backend stack is Django, use references/django-migrations.md.
5. If the backend stack is Node/TypeScript, use references/node-orm-migrations.md.
6. If the framework cannot be determined, return a blocker instead of creating generic models/migrations tasks.

Required Contract Output

For implementation or generated task.md, define all of these fields exactly:

• ORM framework and migration framework.
• Dependency changes and package-manager commands.
• Runtime database config key and connection URL format.
• DB/session module path.
• Model package/entity path.
• Migration config path and migration versions path.
• Commands to create, apply, inspect, and verify migrations.
• How migration metadata imports models.
• Table naming, ID strategy, timestamp/audit fields, enum strategy, indexes, and constraints.
• Verification commands and expected evidence.

Do not write vague file areas such as models/migrations, migration command selected later, use ORM, or add schema. Use exact paths from repo evidence or this skill's selected reference. If exact paths cannot be decided, block with TASK_CONCRETE_CONTRACT_MISSING.

Task Handoff Requirements

Generated backend tasks must include a persistence section with this shape:

## Backend ORM / Migration Contract
- Skill: `backend-orm-migrations`
- Selected ORM:
- Selected migration framework:
- Packages:
- Runtime DB config:
- DB/session path:
- Model paths:
- Migration config:
- Migration versions:
- Create migration command:
- Apply migration command:
- Status/table inspection command:
- Required model metadata import:
- Data safety notes:

Downstream domain API tasks must depend on the foundation task when the foundation task creates ORM/migration tooling. They must say: Use T001 Backend ORM / Migration Contract; if absent, block with UPSTREAM_CONTRACT_MISSING.

Safety Rules

• Never reset, drop, or delete a database volume without explicit user approval.
• Never use raw SQL DDL as the source of truth when an ORM migration framework is available or selected.
• Always review generated migrations before applying them.
• Do not hide destructive operations inside autogenerated migrations.
• Do not commit secrets, real credentials, .env values, DB dumps, local volumes, or generated cache/build artifacts.
• Keep app runtime connection strings separate from host inspection commands.

Verification

Minimum verification after schema work:

• Dependency install/sync command succeeds.
• Backend compile/build command succeeds.
• Migration create/apply/status command succeeds.
• Table inspection proves expected tables exist.
• At least one minimal backend request or service check proves the app can use the selected DB/session path.

Use repo README/AGENTS commands first. Add commands from the selected reference only when the repo has no existing ORM/migration command.

References

• FastAPI + uv + PostgreSQL with no existing ORM: read references/fastapi-sqlalchemy-alembic.md.
• Django backend: read references/django-migrations.md.
• Node/TypeScript backend: read references/node-orm-migrations.md.