# Add a Migration Check to CI for a TypeORM Project

Yes. An agent adds a CI step that fails when your TypeORM entities and migrations disagree, with migration:generate --check in the e2e container, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-migration-check-to-ci/typeorm/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how migrations are generated, run and tested today, because a drift check only works where the real database and the real entities meet. In an API built from brocoders/nestjs-boilerplate, `package.json` pins `typeorm` 0.3.28 and `pg` 8.20.0 and defines a `typeorm` script, `env-cmd -- ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js`, that `migration:generate`, `migration:run` and `migration:revert` call with `--dataSource=src/database/data-source.ts`. That file builds an `AppDataSource` from `DATABASE_*` variables, with `synchronize` on only when `DATABASE_SYNCHRONIZE` is the string `true`, entities matched by the glob `**/*.entity{.ts,.js}` and migrations under `src/database/migrations/`. One migration lives there, `1715028537217-CreateUser.ts`, with 26 `queryRunner.query` statements creating `role`, `status`, `file`, `user`, `session` and their indexes. `src/database/typeorm-config.service.ts` repeats the same options for Nest's `TypeOrmModule`, and `docs/database.md` tells contributors to add an entity and then run `migration:generate`; nothing checks that they did.

CI already has the right place for the check. `.github/workflows/docker-e2e.yml` runs `docker compose -f docker-compose.relational.ci.yaml --env-file env-example-relational -p ci-relational up --build --exit-code-from api`, where `env-example-relational` sets `DATABASE_TYPE=postgres`, `DATABASE_HOST=postgres` and `DATABASE_SYNCHRONIZE=false`. The `api` service is built from `relational.e2e.Dockerfile` on `node:24.14.1-alpine`, which installs `ts-node` globally, writes an empty `.env` and runs `npm run build`, then starts `startup.relational.ci.sh`: wait for `postgres:5432`, `npm run migration:run`, `npm run seed:run:relational`, start the app, `npm run lint`, `npm run test:e2e -- --runInBand`. The hygen generators under `.hygen/generate/relational-resource` write new entities, so the drift risk is real every time someone scaffolds a resource and skips the generate step.

The agent adds one line to `startup.relational.ci.sh`, between `migration:run` and the seeds: `npm run migration:generate -- src/database/migrations/DriftCheck --check`. With `--check`, TypeORM compares the entities against the database the migrations just built and exits non-zero if a migration would be generated, writing no file. The `set -e` at the top of the script turns that into a failed container and, through `--exit-code-from api`, a failed job. Because `postmigration:generate` runs `npm run lint -- --fix` after every generate, the agent calls the CLI through the `typeorm` script directly for the check so lint does not run twice, and says so in the pull request.

In its sandbox the agent runs the same Compose command the workflow runs and reads the result. If the entities and the one migration agree, the step passes and the pull request is the one line plus a sentence in `docs/database.md`. If they do not, the first run of the check fails with the statements TypeORM would generate, and the agent commits the missing migration from `migration:generate` as a second commit, so the check is green on the branch and the pull request shows exactly what had drifted. Either way it quotes the `--check` output and the e2e summary from the container.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a migration drift check to CI for this TypeORM project. Read package.json, src/database/data-source.ts, src/database/typeorm-config.service.ts, src/database/migrations/, env-example-relational, docker-compose.relational.ci.yaml, relational.e2e.Dockerfile, startup.relational.ci.sh, .github/workflows/docker-e2e.yml and docs/database.md first. After migration:run in startup.relational.ci.sh, run TypeORM's migration:generate with --check against the data source so the container exits non-zero when the entities and migrations disagree; call the typeorm script directly so the postmigration:generate lint hook does not run. Run the relational Compose command the workflow runs and quote the check's output and the e2e summary. If the check finds drift, generate the missing migration in a second commit and show the check passing after it. Add one sentence to docs/database.md about the check. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `startup.relational.ci.sh` by one line and `docs/database.md` by one sentence, and, when the first run found drift, adds a migration file under `src/database/migrations/` in its own commit. The description quotes the `--check` output from the container, the e2e test summary, and the workflow's exit code.

The run's record keeps the full Compose log, so a reviewer can see the check run after `migration:run` and before the seeds, and can read the statements TypeORM wanted to generate if there were any.

Before merging, a reviewer reads any generated migration line by line, since TypeORM's diff can rename a column as a drop and an add, and decides whether the check should also run in the document-database job, where it does not apply because that path uses Mongoose.

## Run it on every pull request

Once the step is in the script, every pull request runs it, because `docker-e2e.yml` already triggers on `pull_request` to `main`. The question that remains is what to do when it fails. A `github` trigger on `pull_request.opened` and `pull_request.synchronize` starts a run for each pull request a person opens, with a prompt asking the agent to run the relational Compose command on that branch and, when the check fails, to generate the missing migration, push it to the branch and post a review that quotes the statements. The trigger adds the pull request after the prompt, so the prompt names no branch.

A pull request a bot opens never fires that trigger, so a handler on the reader's server starts those runs with the `…/pull/<n>` URL in `resources` and a `request_id` that is a UUID v5 of the head commit SHA, so a synchronize after a rebase starts a new run and a redelivered webhook does not. Each run builds the same containers CI does, in its own sandbox, and a pull request whose entities already match gets no review and no commit.

## Why run it on Rush?

Drift between entities and migrations is found in production, when `migration:run` succeeds and the first query hits a column that does not exist. The check is one flag on a command the project already has, but placing it needs the whole CI path read: where the database comes from, which script runs after it, what `set -e` and `--exit-code-from` do with the exit code, and which npm hook would fire. In a Rush sandbox the agent reads that path, adds the line, and runs the real Compose build to see it work.

The pull request shows the check running in the same containers CI uses, with its output, and any drift it found is already fixed on the branch. Across every TypeORM service a team maintains, the job runs in parallel, one sandbox and one pull request each, and each check runs against that service's own migrations.

## Frequently asked questions

### Why run the check in the Compose job instead of a new workflow?

Because the drift check needs a Postgres with the migrations applied and the built entities, and `docker-compose.relational.ci.yaml` already provides both. A separate job would set up a second database to answer the same question and add minutes to every pull request.

### Does --check write a migration file?

No. It compares and exits; the path argument is required by the command but nothing is written at it. When drift exists, the agent runs `migration:generate` without `--check` once, in a second commit, to produce the file the check was asking for.

### What if DATABASE_SYNCHRONIZE is true somewhere?

Then the schema is created from the entities and the check always passes, which is why it must run where `env-example-relational` sets it to `false`. The agent reads the value in the CI env file and says in the pull request that the check is only meaningful with it off.

### Will the generated migration be correct?

It is what TypeORM computes from the diff, which is right for added columns and tables and can be wrong for renames, which it expresses as a drop and an add. The reviewer reads it, and the check only asserts that the entities and the migrations agree, not that the migration preserves data.

## More TypeORM jobs

- [Add Optimistic Locking to TypeORM Entities](https://getrush.ai/run/add-optimistic-locking/typeorm/)
- [Add Query Timeouts to a TypeORM + NestJS App](https://getrush.ai/run/add-query-timeouts/typeorm/)
- [Add Read Replicas to a TypeORM App](https://getrush.ai/run/add-read-replicas/typeorm/)

## The same job on other stacks

- [Add an Alembic Migration Drift Check to CI](https://getrush.ai/run/add-migration-check-to-ci/alembic/)
- [Add a Drizzle Migration Drift Check to CI](https://getrush.ai/run/add-migration-check-to-ci/drizzle/)

## More jobs like this: Write the missing tests

- [Write Migration Rollback Tests for Alembic](https://getrush.ai/run/add-migration-rollback-tests/alembic/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
