Schema drift check in CI
Your migrations and your entities describe the same schema, and you want CI to fail as soon as they disagree.
yaml
name: schema
on: [push, pull_request]
jobs:
drift:
runs-on: ubuntu-latest
services:
database:
image: postgres:18-alpine
env:
POSTGRES_USER: test
POSTGRES_PASSWORD: test
POSTGRES_DB: test
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U test"
--health-interval 5s
--health-timeout 5s
--health-retries 10
env:
TYPEORM_CONNECTION: postgres
TYPEORM_HOST: 127.0.0.1
TYPEORM_PORT: 5432
TYPEORM_USERNAME: test
TYPEORM_PASSWORD: test
TYPEORM_DATABASE: test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- run: npm ci
- run: npm run build
# creates the database if needed and runs the migrations
- run: npx typeorm-extension db create -d src/data-source.ts
# exit code 1 and the reconciling statements if the schema deviates
- run: npx typeorm-extension db drift -d src/data-source.tsThe CLI reads the TYPEORM_* variables and merges them into the options of the data-source file (see Data Source). If your data-source.ts reads variables of its own, set those in the env block instead.
Why it works
db createruns the migrations when the data source configures any (andsynchronize(false)only when it configures none), so the drift check sees the schema the migrations produce.db driftcompares that schema with the entity metadata and never writes. It exits with1and prints the statements when they differ, and with2on any other error, such as a failed connection.- The CLI runs on the build here, so
-d src/data-source.tsloadsdist/data-source.js(see Running from a build). Without a build step, run it withtsxinstead. - The check only proves that the migrations match the entities when the data source configures migrations. Without any,
db createbuilds the schema from the entities and the check always passes. Make sure the CI data source lists its migrations. --skipWithoutMigrationsreports no drift for a data source without migrations. Use it only where that is intended (asynchronize()driven sqlite setup sharing the file), never for the job that validates migrations.
In a test instead
To keep the check in your test suite, call getSchemaDrift after the migrations have run:
typescript
import { DataSource } from 'typeorm';
import { describe, expect, it } from 'vitest';
import { getSchemaDrift } from 'typeorm-extension';
import { options } from '../src/data-source';
describe('schema', () => {
it('matches the entities after the migrations', async () => {
const dataSource = new DataSource({ ...options, migrationsRun: false, synchronize: false });
await dataSource.initialize();
try {
await dataSource.runMigrations();
const drift = await getSchemaDrift(dataSource);
expect(drift.up.map((statement) => statement.query)).toEqual([]);
} finally {
await dataSource.destroy();
}
});
});Run it against an empty database: on one that already has the tables (for example from an earlier synchronize()), the comparison no longer shows what the migrations alone produce.
Comparing the statements rather than drift.exists puts them in the test output when the check fails.