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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Write the missing tests.
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.