feat(db): write a migration's schema change once per engine

A migration after the Postgres baseline's cut runs on both engines, but its DDL
is not one language. engineDdl(this, { sqlite, postgres }) queues the statements
of the engine the migration runs on, like addSql, and addColumnIfMissing takes a
column definition per engine, both picked in the dialect layer so a migration
never branches on the engine itself.
This commit is contained in:
Maurice
2026-11-17 11:48:16 +01:00
parent f3ea50b17b
commit a99cd40f4d
3 changed files with 135 additions and 2 deletions
+35
View File
@@ -0,0 +1,35 @@
import { isPostgres, isSqlite, unsupported } from './platform';
import type { Platform } from '@mikro-orm/core';
/**
* Schema statements a migration writes once per engine.
*
* A migration after the Postgres baseline's cut (`through` in
* `assets/postgres/baseline.json`) runs on both engines, and their DDL is not
* one language: SQLite rebuilds a table where Postgres alters it, and the
* Postgres side has to read exactly as MikroORM generates it from the entities
* (`bigint`, `bigserial` ids, `<table>_<column>_foreign` keys), or PARITY-PG
* fails. So a migration hands both spellings to `engineDdl` in
* `db/migration-utils.ts`, which picks the one for the engine it runs on here;
* `npm run gen:pg-migration` writes the Postgres side and `lint:dialect`
* refuses DDL a newer migration spells outside it.
*/
/** One value per engine, picked by the platform the migration runs on. */
interface PerEngine<T> {
readonly sqlite: T;
readonly postgres: T;
}
/** The statements of one schema change, in the order they run, per engine. */
export type EngineDdl = PerEngine<readonly string[]>;
/** A column definition (`status TEXT DEFAULT 'pending'`) per engine, for `addColumnIfMissing`. */
export type EngineColumn = PerEngine<string>;
/** The member of `choices` for the engine behind `platform`; any other engine is refused. */
export function forEngine<T>(platform: Platform, choices: PerEngine<T>): T {
if (isSqlite(platform)) return choices.sqlite;
if (isPostgres(platform)) return choices.postgres;
return unsupported(platform);
}
+24 -2
View File
@@ -1,4 +1,5 @@
import { columnNamesSql, tableExistsSql } from './dialect/catalog';
import { forEngine, type EngineColumn, type EngineDdl } from './dialect/ddl';
import { TableNotFoundException } from '@mikro-orm/core';
import type { Migration } from '@mikro-orm/migrations';
@@ -25,16 +26,37 @@ interface ColumnRow {
* name"; this checks first instead, so a genuine failure still propagates.
*
* `definition` is the full column spec, e.g. `status TEXT DEFAULT 'pending'`.
* A migration after the Postgres baseline's cut runs on both engines and
* passes one per engine instead (`{ sqlite: 'status TEXT', postgres: 'status text' }`),
* so Postgres never gets a SQLite spelling; `lint:dialect` refuses a plain
* string there.
*/
export async function addColumnIfMissing(
migration: Migration,
table: string,
column: string,
definition: string,
definition: string | EngineColumn,
): Promise<void> {
if ((await columnNames(migration, table)).has(column)) return;
const platform = migration.getEntityManager().getPlatform();
await migration.execute(`alter table ${platform.quoteIdentifier(table)} add column ${definition}`);
const spec = typeof definition === 'string' ? definition : forEngine(platform, definition);
await migration.execute(`alter table ${platform.quoteIdentifier(table)} add column ${spec}`);
}
/**
* Queues a schema change written once per engine, the way `addSql` queues a
* statement: the statements for the engine the migration runs on, in order,
* after whatever the migration queued before. Every migration after the
* Postgres baseline's cut writes its DDL through this (`lint:dialect` refuses
* it anywhere else in such a migration): the SQLite statements by hand, the
* Postgres ones as `npm run gen:pg-migration` prints them.
*
* Like `addSql`, nothing runs before `up()` returns, so a statement the
* migration sends with `this.execute` runs first; send data statements that
* need the new schema with `addSql` after this call.
*/
export function engineDdl(migration: Migration, ddl: EngineDdl): void {
for (const statement of forEngine(migration.getEntityManager().getPlatform(), ddl)) migration.addSql(statement);
}
/** True when `table` exists in the current database. */
+76
View File
@@ -0,0 +1,76 @@
/**
* Schema statements written once per engine (src/db/dialect/ddl.ts) and the
* migration side of it in src/db/migration-utils.ts: `engineDdl` queues the
* statements of the engine the migration runs on, in order, and
* `addColumnIfMissing` takes a column definition per engine, so a migration
* after the Postgres baseline's cut never hands Postgres a SQLite spelling.
*/
import { forEngine } from '../../../../src/db/dialect/ddl';
import { addColumnIfMissing, engineDdl } from '../../../../src/db/migration-utils';
import { Platform } from '@mikro-orm/core';
import type { Migration } from '@mikro-orm/migrations';
import { BasePostgreSqlPlatform, SqlitePlatform } from '@mikro-orm/sql';
import { describe, expect, it, vi } from 'vitest';
const sqlite = new SqlitePlatform();
const postgres = new BasePostgreSqlPlatform();
class OtherPlatform extends Platform {}
/** A migration on `platform` that records what it queues and executes; `columns` is what the catalog answers. */
function migrationOn(platform: Platform, columns: string[] = []) {
const queued: string[] = [];
const executed: string[] = [];
const migration = {
addSql: vi.fn((sql: string) => queued.push(sql)),
execute: vi.fn(async (sql: string) => {
if (sql.startsWith('alter table')) {
executed.push(sql);
return [];
}
return columns.map((name) => ({ name }));
}),
getEntityManager: () => ({ getPlatform: () => platform }),
} as unknown as Migration;
return { migration, queued, executed };
}
const DDL = {
sqlite: ['CREATE TABLE t (id INTEGER PRIMARY KEY)', 'CREATE INDEX t_a ON t (a)'],
postgres: ['create table "t" ("id" bigserial primary key)', 'create index "t_a" on "t" ("a")'],
};
describe('engine DDL', () => {
it('DDL-001: forEngine picks the member of the platform and refuses any other engine', () => {
expect(forEngine(sqlite, { sqlite: 1, postgres: 2 })).toBe(1);
expect(forEngine(postgres, { sqlite: 1, postgres: 2 })).toBe(2);
expect(() => forEngine(new OtherPlatform(), { sqlite: 1, postgres: 2 })).toThrow();
});
it('DDL-002: engineDdl queues the statements of the engine it runs on, in order', () => {
const onSqlite = migrationOn(sqlite);
engineDdl(onSqlite.migration, DDL);
expect(onSqlite.queued).toEqual(DDL.sqlite);
const onPostgres = migrationOn(postgres);
engineDdl(onPostgres.migration, DDL);
expect(onPostgres.queued).toEqual(DDL.postgres);
expect(() => engineDdl(migrationOn(new OtherPlatform()).migration, DDL)).toThrow();
});
it('DDL-003: addColumnIfMissing adds the definition of the engine it runs on, once', async () => {
const definition = { sqlite: 'note TEXT', postgres: 'note text null' };
const onPostgres = migrationOn(postgres);
await addColumnIfMissing(onPostgres.migration, 'trips', 'note', definition);
expect(onPostgres.executed).toEqual(['alter table "trips" add column note text null']);
const onSqlite = migrationOn(sqlite);
await addColumnIfMissing(onSqlite.migration, 'trips', 'note', definition);
expect(onSqlite.executed).toEqual(['alter table `trips` add column note TEXT']);
const present = migrationOn(postgres, ['note']);
await addColumnIfMissing(present.migration, 'trips', 'note', definition);
expect(present.executed).toEqual([]);
});
});