From 1bf067056684cdcc12cb623c2156ad55ad8dcb49 Mon Sep 17 00:00:00 2001 From: Maurice Date: Tue, 17 Nov 2026 11:48:16 +0100 Subject: [PATCH] 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. --- server/src/db/dialect/ddl.ts | 35 +++++++++++ server/src/db/migration-utils.ts | 26 +++++++- server/tests/unit/db/dialect/ddl.test.ts | 76 ++++++++++++++++++++++++ 3 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 server/src/db/dialect/ddl.ts create mode 100644 server/tests/unit/db/dialect/ddl.test.ts diff --git a/server/src/db/dialect/ddl.ts b/server/src/db/dialect/ddl.ts new file mode 100644 index 000000000..e4e42f52e --- /dev/null +++ b/server/src/db/dialect/ddl.ts @@ -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, `__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 { + readonly sqlite: T; + readonly postgres: T; +} + +/** The statements of one schema change, in the order they run, per engine. */ +export type EngineDdl = PerEngine; + +/** A column definition (`status TEXT DEFAULT 'pending'`) per engine, for `addColumnIfMissing`. */ +export type EngineColumn = PerEngine; + +/** The member of `choices` for the engine behind `platform`; any other engine is refused. */ +export function forEngine(platform: Platform, choices: PerEngine): T { + if (isSqlite(platform)) return choices.sqlite; + if (isPostgres(platform)) return choices.postgres; + return unsupported(platform); +} diff --git a/server/src/db/migration-utils.ts b/server/src/db/migration-utils.ts index a691277cb..2b06a9c94 100644 --- a/server/src/db/migration-utils.ts +++ b/server/src/db/migration-utils.ts @@ -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 { 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. */ diff --git a/server/tests/unit/db/dialect/ddl.test.ts b/server/tests/unit/db/dialect/ddl.test.ts new file mode 100644 index 000000000..bbc763a0b --- /dev/null +++ b/server/tests/unit/db/dialect/ddl.test.ts @@ -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([]); + }); +});