Skip to content

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.ts

The 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 create runs the migrations when the data source configures any (and synchronize(false) only when it configures none), so the drift check sees the schema the migrations produce.
  • db drift compares that schema with the entity metadata and never writes. It exits with 1 and prints the statements when they differ, and with 2 on any other error, such as a failed connection.
  • The CLI runs on the build here, so -d src/data-source.ts loads dist/data-source.js (see Running from a build). Without a build step, run it with tsx instead.
  • The check only proves that the migrations match the entities when the data source configures migrations. Without any, db create builds the schema from the entities and the check always passes. Make sure the CI data source lists its migrations.
  • --skipWithoutMigrations reports no drift for a data source without migrations. Use it only where that is intended (a synchronize() 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.