@lenne.tech/nest-server 12.1.0 → 12.2.0

package/src/core/common/persistence/sql/mysql/mysql-schema.migrator.ts

@@ -16,7 +16,12 @@ import {
   desiredMysqlTable,
   type MysqlDesiredColumn,
   type MysqlDesiredTable,
+  LIVE_KEY_PREFIX,
+  MYSQL_SYNC_COUNTERS,
+  MYSQL_SYNC_TRIGGER_VERSION,
   mysqlColumnDefinition,
+  mysqlSyncCountersStatement,
+  mysqlSyncTableStatements,
   NULL_SENTINEL_PREFIX,
   variantLabel,
 } from './mysql-schema.compiler.js';
@@ -72,12 +77,18 @@ interface CatalogTable {
   columns: Map<string, { collation: null | string; generated: boolean; type: string }>;
   /** framework-named index → unique */
   indexes: Map<string, boolean>;
+  /** Change-order triggers (`lt_sync_*`) on the table, as far as the connection may see them (the owner does) */
+  syncTriggers: Set<string>;
+  /** The trigger version the counter row records — readable by the application account too */
+  syncTriggerVersion: null | string;
 }
 
 interface Catalog {
   database: string;
   /** Whether the application account holds every DML right on the database */
   granted: boolean;
+  /** Whether the counter table of synchronized models exists */
+  syncCounters: boolean;
   tables: Map<string, CatalogTable>;
 }
 
@@ -109,6 +120,71 @@ export async function withMysqlSchemaLock<T>(owner: SqlExecutor, fn: (run: Run)
   });
 }
 
+/** The collation of every table the framework creates — byte-wise, as identifiers and tokens compare on PostgreSQL */
+const FRAMEWORK_COLLATION = 'utf8mb4_bin';
+/**
+ * How long a collation switch waits for the metadata locks it needs, in seconds. `ALTER DATABASE` locks every table of
+ * the database exclusively, one after the other: behind an open transaction it waits, and every statement on the
+ * tables it already holds waits with it. The server's own default is a year
+ */
+const COLLATION_SWITCH_LOCK_WAIT_SECONDS = 5;
+
+/** Whether any of `tables` does not exist yet — only then does a library's migration create a table */
+export async function anyTableMissing(run: Run, tables: string[]): Promise<boolean> {
+  if (!tables.length) {
+    return false;
+  }
+  const { rows } = await run({
+    params: tables,
+    text: `SELECT COUNT(*) AS n FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${tables.map((_, index) => `$${index + 1}`).join(', ')})`,
+  });
+  return Number(rows[0]?.n) < new Set(tables).size;
+}
+
+/**
+ * `fn` with the database's default collation switched to the framework's and back afterwards — for a library that
+ * creates its tables without naming a collation (Better-Auth). Its tables then compare byte-wise like the framework's,
+ * and its foreign keys to them can be created at all: MariaDB refuses a key between `utf8mb4_bin` (`users.id`) and the
+ * server's default (`Foreign key constraint is incorrectly formed`), and on MySQL tokens and identifiers would compare
+ * case-insensitively. Restored afterwards, so the project's own DDL keeps the default it was given. Runs as the owner
+ * under the schema lock (`run` is the lock's connection); a process that dies in between leaves `utf8mb4_bin` behind,
+ * which changes no existing table.
+ *
+ * Only for a run that creates a table (`anyTableMissing()`): a column added to an existing table takes that table's
+ * collation, and the switch locks every table of the database. Its wait is bounded, so a first boot behind a long
+ * transaction fails with an error instead of freezing the database.
+ */
+export async function withFrameworkDefaultCollation<T>(run: Run, fn: () => Promise<T>): Promise<T> {
+  const { rows } = await run({
+    params: [],
+    text: `SELECT DEFAULT_CHARACTER_SET_NAME AS charset, DEFAULT_COLLATION_NAME AS collation
+      FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()`,
+  });
+  const { charset, collation } = (rows[0] ?? {}) as { charset?: string; collation?: string };
+  if (collation === FRAMEWORK_COLLATION) {
+    return fn();
+  }
+  if (!/^\w+$/.test(charset ?? '') || !/^\w+$/.test(collation ?? '')) {
+    throw new Error(`Cannot read the default collation of the database (found ${charset}/${collation})`);
+  }
+  const { rows: timeouts } = await run({ params: [], text: 'SELECT @@SESSION.lock_wait_timeout AS timeout' });
+  const previousTimeout = Number(timeouts[0]?.timeout);
+  await run({ params: [], text: `SET SESSION lock_wait_timeout = ${COLLATION_SWITCH_LOCK_WAIT_SECONDS}` });
+  try {
+    await run({ params: [], text: `ALTER DATABASE CHARACTER SET utf8mb4 COLLATE ${FRAMEWORK_COLLATION}` });
+    try {
+      return await fn();
+    } finally {
+      await run({ params: [], text: `ALTER DATABASE CHARACTER SET ${charset} COLLATE ${collation}` });
+    }
+  } finally {
+    if (Number.isInteger(previousTimeout) && previousTimeout > 0) {
+      await run({ params: [], text: `SET SESSION lock_wait_timeout = ${previousTimeout}` });
+    }
+  }
+}
+
 /** Apply every automatic change as the OWNER, under the schema lock; refuse when a migration is needed. */
 export async function applyMysqlSchema(
   owner: SqlExecutor,
@@ -166,6 +242,13 @@ export async function planMysqlSchema(
     options.appAccount,
   );
   const changes: SchemaChange[] = [];
+  if (tables.some((table) => table.sync) && !catalog.syncCounters) {
+    changes.push({
+      description: `create the change-order counters ${MYSQL_SYNC_COUNTERS}`,
+      kind: 'automatic',
+      statements: [mysqlSyncCountersStatement()],
+    });
+  }
   if (!catalog.granted) {
     changes.push({
       description: `grant ${options.appAccount} SELECT, INSERT, UPDATE, DELETE on database ${catalog.database}`,
@@ -190,12 +273,53 @@ function planNewTable(table: MysqlDesiredTable): SchemaChange[] {
     {
       description: `create table ${table.name} (${table.model.name})`,
       kind: 'automatic',
-      statements: [createMysqlTableStatement(table), ...table.indexes.map((index) => index.create)],
+      statements: [
+        createMysqlTableStatement(table),
+        ...table.indexes.map((index) => index.create),
+        ...(table.sync ? mysqlSyncTableStatements(table.name, table.sync) : []),
+      ],
       table: table.name,
     },
   ];
 }
 
+/**
+ * A synchronized table's change order: both triggers of the current version and its counter row. Triggers of an earlier
+ * version are replaced; a table that is no longer synchronized keeps its triggers until a migration drops them
+ */
+function planSync(table: MysqlDesiredTable, existing: CatalogTable): SchemaChange[] {
+  const name = table.name;
+  if (!table.sync) {
+    return existing.syncTriggers.size
+      ? [
+          {
+            description: `${name} is no longer synchronized; its change-order triggers are kept until a migration drops them`,
+            kind: 'notice',
+            statements: [],
+            table: name,
+          },
+        ]
+      : [];
+  }
+  if (existing.syncTriggerVersion === MYSQL_SYNC_TRIGGER_VERSION) {
+    return [];
+  }
+  const current = new Set([table.sync.insertTrigger, table.sync.updateTrigger]);
+  return [
+    {
+      description: `${existing.syncTriggerVersion ? 'replace' : 'add'} the change-order triggers of ${name}`,
+      kind: 'automatic',
+      statements: [
+        ...[...existing.syncTriggers]
+          .filter((trigger) => !current.has(trigger))
+          .map((trigger) => `DROP TRIGGER IF EXISTS ${quoteMysqlIdentifier(trigger)}`),
+        ...mysqlSyncTableStatements(name, table.sync),
+      ],
+      table: name,
+    },
+  ];
+}
+
 function planExistingTable(table: MysqlDesiredTable, existing: CatalogTable): SchemaChange[] {
   const changes: SchemaChange[] = [];
   const name = table.name;
@@ -255,7 +379,12 @@ function planExistingTable(table: MysqlDesiredTable, existing: CatalogTable): Sc
     }
   }
   for (const column of existing.columns.keys()) {
-    if (!declared.has(column) && !column.startsWith(NULL_SENTINEL_PREFIX) && !isForeignColumn(name, column)) {
+    if (
+      !declared.has(column) &&
+      !column.startsWith(NULL_SENTINEL_PREFIX) &&
+      !column.startsWith(LIVE_KEY_PREFIX) &&
+      !isForeignColumn(name, column)
+    ) {
       changes.push({
         description: `${name}.${column} is no longer declared; the column is kept until a migration drops it`,
         kind: 'notice',
@@ -284,16 +413,38 @@ function planExistingTable(table: MysqlDesiredTable, existing: CatalogTable): Sc
     }
     const sentinels = (index.sentinels ?? []).filter((sentinel) => deferred.has(sentinel) && !added.has(sentinel));
     sentinels.forEach((sentinel) => added.add(sentinel));
+    // A synchronized model's live-key columns read `deleted_at`: an existing model that became synchronized has none
+    // yet, and the boot that refuses this index never adds it
+    const deletedAt = table.columns.find((column) => column.name === 'deleted_at');
+    const needsDeletedAt =
+      !!table.sync &&
+      !!deletedAt &&
+      !existing.columns.has('deleted_at') &&
+      !added.has('deleted_at') &&
+      sentinels.some((sentinel) => sentinel.startsWith(LIVE_KEY_PREFIX));
+    if (needsDeletedAt) {
+      added.add('deleted_at');
+    }
+    // The framework unique index over the same fields that the model no longer declares is the one this live-only index
+    // replaces — a tombstone, which keeps no values, would collide on it
+    const stem = indexStem(index.name);
+    const superseded = table.sync
+      ? [...existing.indexes].filter(([old, unique]) => unique && !wanted.has(old) && indexStem(old) === stem)
+      : [];
     changes.push({
       description: `create ${index.unique ? 'unique ' : ''}index ${index.name} on ${name}`,
       // A unique index can fail on the rows already stored, and it changes what may be written: a reviewed decision
       kind: index.unique ? 'migration' : 'automatic',
       statements: [
+        ...(needsDeletedAt
+          ? [`ALTER TABLE ${quoted} ADD COLUMN ${mysqlColumnDefinition({ ...deletedAt!, primaryKey: false })}`]
+          : []),
         ...sentinels.map(
           (sentinel) =>
             `ALTER TABLE ${quoted} ADD COLUMN ${mysqlColumnDefinition(table.columns.find((column) => column.name === sentinel)!)}`,
         ),
         index.create,
+        ...superseded.map(([old]) => `DROP INDEX ${quoteMysqlIdentifier(old)} ON ${quoted}`),
       ],
       table: name,
     });
@@ -308,9 +459,15 @@ function planExistingTable(table: MysqlDesiredTable, existing: CatalogTable): Sc
       });
     }
   }
+  changes.push(...planSync(table, existing));
   return changes;
 }
 
+/** A framework index name without its definition hash (`ux_<table>__<fields>_<hash>`) */
+function indexStem(name: string): string {
+  return name.replace(/_[0-9a-f]{8}$/, '');
+}
+
 function sameType(column: MysqlDesiredColumn, current: { collation: null | string; type: string }): boolean {
   if (column.type !== current.type) {
     return false;
@@ -368,20 +525,48 @@ async function readCatalog(run: Run, tables: string[], appAccount: string): Prom
     text: `SELECT PRIVILEGE_TYPE AS privilege FROM information_schema.SCHEMA_PRIVILEGES
       WHERE GRANTEE = $1 AND TABLE_SCHEMA = DATABASE()`,
   });
+  const triggerResult = await run({
+    params: tables,
+    text: `SELECT EVENT_OBJECT_TABLE AS t, TRIGGER_NAME AS name FROM information_schema.TRIGGERS
+      WHERE TRIGGER_SCHEMA = DATABASE() AND EVENT_OBJECT_TABLE IN (${list}) AND TRIGGER_NAME LIKE 'lt\\_sync\\_%'`,
+  });
+  const countersResult = await run({
+    params: [MYSQL_SYNC_COUNTERS],
+    text: `SELECT COUNT(*) AS n FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = $1`,
+  });
+  const counterRows = Number(countersResult.rows[0]?.n)
+    ? (
+        await run({
+          params: tables,
+          text: `SELECT \`model\` AS t, \`triggers\` AS version FROM ${quoteMysqlIdentifier(MYSQL_SYNC_COUNTERS)} WHERE \`model\` IN (${list})`,
+        })
+      ).rows
+    : [];
 
   const catalog: Catalog = {
     database,
     granted: DML.every((privilege) => grantResult.rows.some((row) => row.privilege === privilege)),
+    syncCounters: Number(countersResult.rows[0]?.n) > 0,
     tables: new Map(),
   };
   const table = (name: string) => {
     let entry = catalog.tables.get(name);
     if (!entry) {
-      entry = { checks: new Set(), columns: new Map(), indexes: new Map() };
+      entry = {
+        checks: new Set(),
+        columns: new Map(),
+        indexes: new Map(),
+        syncTriggers: new Set(),
+        syncTriggerVersion: null,
+      };
       catalog.tables.set(name, entry);
     }
     return entry;
   };
+  for (const row of triggerResult.rows) {
+    table(row.t).syncTriggers.add(row.name);
+  }
+
   for (const row of columnResult.rows) {
     table(row.t).columns.set(row.c, {
       collation: row.collation ?? null,
@@ -395,6 +580,12 @@ async function readCatalog(run: Run, tables: string[], appAccount: string): Prom
   for (const row of checkResult.rows) {
     table(row.t).checks.add(row.name);
   }
+  // After the columns: only a table that exists has a counter row worth reading
+  for (const row of counterRows) {
+    if (catalog.tables.has(row.t)) {
+      table(row.t).syncTriggerVersion = row.version ?? null;
+    }
+  }
   return catalog;
 }
 

package/src/core/common/persistence/sql/postgres/postgres-schema.compiler.ts

@@ -2,6 +2,7 @@ import type { FieldDescriptor, IndexDescriptor, ModelDescriptor } from '../../mo
 import { UnsupportedQueryError } from '../sql-errors.js';
 import { columnName, quoteIdentifier, SqlLiterals, sqlLiteral } from '../sql-naming.js';
 import { schemaHash, shortName, tableName } from '../sql-schema.shared.js';
+import { isLiveFilter, SYNC_SEQUENCE_FIELD } from '../../sync-model.js';
 import { compilePostgresWhere } from './postgres-where.compiler.js';
 
 export { LOCK_MODEL, shortName, tableName } from '../sql-schema.shared.js';
@@ -23,6 +24,15 @@ export { LOCK_MODEL, shortName, tableName } from '../sql-schema.shared.js';
 /** Any string item that starts with `s_` after leading whitespace, case-insensitive (`looksLikeSystemRole`) */
 const SYSTEM_ROLE_PATH = '$[*] ? (@.type() == "string" && @ like_regex "^\\\\s*s_" flag "i")';
 
+/**
+ * Bumped whenever the change-order trigger (`lt_sync_stamp`) changes, so the migrator replaces the function and
+ * every table's trigger — the trigger's name carries the version, because a trigger has no comment the catalog query
+ * could read alongside the table
+ */
+export const SYNC_TRIGGER_VERSION = 'lt:sync:v1';
+export const SYNC_STAMP_FUNCTION = 'lt_sync_stamp';
+export const SYNC_TRIGGER = 'lt_sync_stamp_v1';
+
 /** Bumped whenever the generated guard function or policies change, so the migrator replaces them */
 export const RLS_VERSION = 'lt:tenant:v1';
 export const TENANT_FILTER_FUNCTION = 'lt_tenant_filter';
@@ -41,6 +51,12 @@ export interface DesiredColumn {
   renamedFrom?: string;
 }
 
+/** The objects that number a synchronized model's changes (offline-sync plan §3.4) */
+export interface DesiredSync {
+  /** The table's sequence: `nextval()` under the model's advisory lock gives commit order */
+  sequence: string;
+}
+
 export interface DesiredIndex {
   /** The CREATE statement */
   create: string;
@@ -61,6 +77,8 @@ export interface DesiredTable {
   name: string;
   /** What the model declares but the table cannot carry (text indexes, …), reported once */
   notices: string[];
+  /** Present for a synchronized model: its change-order sequence and trigger */
+  sync?: DesiredSync;
   /** Row-level security on `tenant_id` */
   tenantIsolated: boolean;
 }
@@ -119,7 +137,13 @@ export function desiredTable(model: ModelDescriptor, options: PostgresSchemaOpti
     indexes.push(desiredIndex(model, name, { fields: { tenantId: 1 }, options: {} }) as DesiredIndex);
   }
 
-  return { checks, columns, indexes, model, name, notices, tenantIsolated };
+  const sync = model.sync && model.fields[SYNC_SEQUENCE_FIELD] ? { sequence: syncSequenceName(name) } : undefined;
+  return { checks, columns, indexes, model, name, notices, ...(sync ? { sync } : {}), tenantIsolated };
+}
+
+/** The change-order sequence of a synchronized model's table */
+export function syncSequenceName(table: string): string {
+  return shortName('lt_sync', table, ['seq']);
 }
 
 function desiredColumn(field: FieldDescriptor): DesiredColumn {
@@ -223,7 +247,9 @@ function desiredIndex(model: ModelDescriptor, table: string, index: IndexDescrip
   const using = gin.length
     ? ` USING gin (${gin[0].expression} jsonb_path_ops)`
     : ` (${parts.map((part) => part.sql).join(', ')})`;
-  const nulls = unique && !conditions.length ? ' NULLS NOT DISTINCT' : '';
+  // A partial index admits NULL repeatedly unless told otherwise. That is harmless where the condition excludes NULL
+  // (sparse), but a synchronized model's live-record condition keeps MongoDB's rule: a second live NULL collides
+  const nulls = unique && (!conditions.length || (!sparse && isLiveFilter(partial))) ? ' NULLS NOT DISTINCT' : '';
   const where = conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '';
   return {
     create: `CREATE ${unique ? 'UNIQUE ' : ''}INDEX ${quoteIdentifier(name)} ON ${quoteIdentifier(table)}${using}${nulls}${where}`,
@@ -280,6 +306,52 @@ export function grantStatement(table: string, appRole: string): string {
   return `GRANT SELECT, INSERT, UPDATE, DELETE ON ${quoteIdentifier(table)} TO ${quoteIdentifier(appRole)}`;
 }
 
+/**
+ * The trigger function that numbers a synchronized model's writes (offline-sync plan §3.4, C1d; DEV-3900 measured
+ * the advisory lock against a counter row). A BEFORE ROW trigger runs after the row is locked, so a write takes its
+ * row first and the order last; the transaction-scoped advisory lock is released only after the commit is visible,
+ * so sequence order is commit order, and `nextval()` leaves no row version a long snapshot could pile up.
+ *
+ * A value the statement sets itself is kept: the store's multi-row writes lock their rows, take their numbers and set
+ * them explicitly in their final statement.
+ */
+export function syncFunctionStatements(): string[] {
+  const fn = quoteIdentifier(SYNC_STAMP_FUNCTION);
+  return [
+    `CREATE OR REPLACE FUNCTION ${fn}() RETURNS trigger
+LANGUAGE plpgsql SET search_path = pg_catalog AS $lt$
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    IF NEW.sync_seq IS NOT NULL THEN
+      RETURN NEW;
+    END IF;
+  ELSIF NEW.sync_seq IS DISTINCT FROM OLD.sync_seq THEN
+    RETURN NEW;
+  END IF;
+  PERFORM pg_advisory_xact_lock(hashtext('lenne.tech:sync:' || TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME));
+  NEW.sync_seq := nextval(format('%I.%I', TG_TABLE_SCHEMA, TG_ARGV[0])::regclass);
+  RETURN NEW;
+END
+$lt$`,
+    `COMMENT ON FUNCTION ${fn}() IS ${sqlLiteral(SYNC_TRIGGER_VERSION)}`,
+  ];
+}
+
+/**
+ * A synchronized table's sequence, the application role's use of it, the trigger, and the numbering of rows written
+ * before the table was synchronized (in the order of their ids, i.e. of their creation)
+ */
+export function syncTableStatements(table: string, sync: DesiredSync, appRole: string): string[] {
+  const quoted = quoteIdentifier(table);
+  const sequence = quoteIdentifier(sync.sequence);
+  return [
+    `CREATE SEQUENCE IF NOT EXISTS ${sequence}`,
+    `GRANT USAGE ON SEQUENCE ${sequence} TO ${quoteIdentifier(appRole)}`,
+    `CREATE TRIGGER ${quoteIdentifier(SYNC_TRIGGER)} BEFORE INSERT OR UPDATE ON ${quoted} FOR EACH ROW EXECUTE FUNCTION ${quoteIdentifier(SYNC_STAMP_FUNCTION)}(${sqlLiteral(sync.sequence)})`,
+    `UPDATE ${quoted} AS t SET "sync_seq" = n.seq FROM (SELECT "id", nextval(${sqlLiteral(sync.sequence)}::regclass) AS seq FROM (SELECT "id" FROM ${quoted} WHERE "sync_seq" IS NULL ORDER BY "id") AS o) AS n WHERE t."id" = n."id"`,
+  ];
+}
+
 /**
  * The guard every tenant policy calls. It reads the scope the store wrote into the transaction (`sql-session.ts`)
  * and RAISES `42501` without one, so a query on a tenant table outside the framework's context — a forgotten scope,

package/src/core/common/persistence/sql/postgres/postgres-schema.migrator.ts

@@ -18,6 +18,11 @@ import {
   grantStatement,
   type PostgresSchemaOptions,
   RLS_VERSION,
+  SYNC_STAMP_FUNCTION,
+  SYNC_TRIGGER,
+  SYNC_TRIGGER_VERSION,
+  syncFunctionStatements,
+  syncTableStatements,
   TENANT_FILTER_FUNCTION,
   TENANT_POLICY,
   tenantFilterFunctionStatements,
@@ -63,10 +68,15 @@ interface CatalogTable {
   granted: boolean;
   policyVersion: null | string;
   rls: boolean;
+  /** Change-order triggers (`lt_sync_*`) on the table */
+  syncTriggers: Set<string>;
 }
 
 interface Catalog {
   functionVersion: null | string;
+  /** Sequences of synchronized tables → whether the application role may use them */
+  sequences: Map<string, boolean>;
+  syncFunctionVersion: null | string;
   schema: string;
   /** Whether the application role may use the schema */
   schemaUsage: boolean;
@@ -124,9 +134,18 @@ export async function planPostgresSchema(
     run,
     tables.map((table) => table.name),
     options.appRole,
+    tables.flatMap((table) => (table.sync ? [table.sync.sequence] : [])),
   );
   const changes: SchemaChange[] = [];
 
+  if (tables.some((table) => table.sync) && catalog.syncFunctionVersion !== SYNC_TRIGGER_VERSION) {
+    changes.push({
+      description: `${catalog.syncFunctionVersion ? 'update' : 'create'} the change-order function ${SYNC_STAMP_FUNCTION}()`,
+      kind: 'automatic',
+      statements: syncFunctionStatements(),
+    });
+  }
+
   if (tables.some((table) => table.tenantIsolated) && catalog.functionVersion !== RLS_VERSION) {
     changes.push({
       description: `${catalog.functionVersion ? 'update' : 'create'} the tenant guard function ${TENANT_FILTER_FUNCTION}()`,
@@ -146,7 +165,9 @@ export async function planPostgresSchema(
       changes.push({ description: notice, kind: 'notice', statements: [], table: table.name });
     }
     const existing = catalog.tables.get(table.name);
-    changes.push(...(existing ? planExistingTable(table, existing, options) : planNewTable(table, options)));
+    changes.push(
+      ...(existing ? planExistingTable(table, existing, catalog.sequences, options) : planNewTable(table, options)),
+    );
   }
   return changes;
 }
@@ -161,6 +182,7 @@ function planNewTable(table: DesiredTable, options: PostgresSchemaOptions): Sche
         ...table.indexes.map((index) => index.create),
         ...(table.tenantIsolated ? tenantPolicyStatements(table.name) : []),
         grantStatement(table.name, options.appRole),
+        ...(table.sync ? syncTableStatements(table.name, table.sync, options.appRole) : []),
       ],
       table: table.name,
     },
@@ -170,6 +192,7 @@ function planNewTable(table: DesiredTable, options: PostgresSchemaOptions): Sche
 function planExistingTable(
   table: DesiredTable,
   existing: CatalogTable,
+  sequences: Map<string, boolean>,
   options: PostgresSchemaOptions,
 ): SchemaChange[] {
   const changes: SchemaChange[] = [];
@@ -249,7 +272,7 @@ function planExistingTable(
       description: `create ${index.unique ? 'unique ' : ''}index ${index.name} on ${name}`,
       // A unique index can fail on the rows already stored, and it changes what may be written: a reviewed decision
       kind: index.unique ? 'migration' : 'automatic',
-      statements: [index.create],
+      statements: index.unique ? liveUniqueMigration(table, existing, index, wanted) : [index.create],
       table: name,
     });
   }
@@ -294,9 +317,97 @@ function planExistingTable(
       table: name,
     });
   }
+  changes.push(...planSync(table, existing, sequences, options));
   return changes;
 }
 
+/**
+ * A synchronized table's change order: the trigger of the current version, its sequence and the application role's
+ * use of it. A trigger of an earlier version is replaced; a table that is no longer synchronized keeps its trigger
+ * (and its numbering) until a migration removes it
+ */
+function planSync(
+  table: DesiredTable,
+  existing: CatalogTable,
+  sequences: Map<string, boolean>,
+  options: PostgresSchemaOptions,
+): SchemaChange[] {
+  const name = table.name;
+  const quoted = quoteIdentifier(name);
+  if (!table.sync) {
+    return existing.syncTriggers.size
+      ? [
+          {
+            description: `${name} is no longer synchronized; its change-order trigger is kept until a migration drops it`,
+            kind: 'notice',
+            statements: [],
+            table: name,
+          },
+        ]
+      : [];
+  }
+  if (!existing.syncTriggers.has(SYNC_TRIGGER)) {
+    const outdated = [...existing.syncTriggers].map(
+      (trigger) => `DROP TRIGGER IF EXISTS ${quoteIdentifier(trigger)} ON ${quoted}`,
+    );
+    return [
+      {
+        description: `${outdated.length ? 'replace' : 'add'} the change-order trigger of ${name}`,
+        kind: 'automatic',
+        statements: [...outdated, ...syncTableStatements(name, table.sync, options.appRole)],
+        table: name,
+      },
+    ];
+  }
+  if (!sequences.get(table.sync.sequence)) {
+    return [
+      {
+        description: `let ${options.appRole} use the change-order sequence of ${name}`,
+        kind: 'automatic',
+        statements: syncTableStatements(name, table.sync, options.appRole).slice(0, 2),
+        table: name,
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * The statements of a new unique index's migration. A synchronized model's index reads `deleted_at`: when the table
+ * does not have it yet (an existing model that became synchronized), the column comes first — the boot that refuses the
+ * index never adds it. A framework unique index over the same fields that the model no longer declares is the one the
+ * live-only index replaces: it goes last, because a tombstone (which keeps no values) would collide on it
+ */
+function liveUniqueMigration(
+  table: DesiredTable,
+  existing: CatalogTable,
+  index: DesiredTable['indexes'][number],
+  wanted: Set<string>,
+): string[] {
+  const statements: string[] = [];
+  const deletedAt = table.columns.find((column) => column.name === 'deleted_at');
+  if (table.sync && deletedAt && !existing.columns.has('deleted_at') && index.create.includes('"deleted_at"')) {
+    statements.push(
+      `ALTER TABLE ${quoteIdentifier(table.name)} ADD COLUMN ${columnDefinition({ ...deletedAt, primaryKey: false })}`,
+    );
+  }
+  statements.push(index.create);
+  if (table.sync) {
+    const stem = indexStem(index.name);
+    for (const [old, unique] of existing.indexes) {
+      if (unique && !wanted.has(old) && indexStem(old) === stem) {
+        statements.push(`DROP INDEX IF EXISTS ${quoteIdentifier(old)}`);
+      }
+    }
+  }
+  return statements;
+}
+
+/** A framework index name without its definition hash (`ux_<table>__<fields>_<hash>`) */
+function indexStem(name: string): string {
+  return name.replace(/_[0-9a-f]{8}$/, '');
+}
+
 function sameType(
   column: DesiredTable['columns'][number],
   current: { collation: null | string; type: string },
@@ -321,7 +432,7 @@ function typeChange(
   };
 }
 
-async function readCatalog(run: Run, tables: string[], appRole: string): Promise<Catalog> {
+async function readCatalog(run: Run, tables: string[], appRole: string, sequences: string[]): Promise<Catalog> {
   // One query after the other: inside the migration transaction they share a single connection
   const schemaResult = await run({
     params: [appRole],
@@ -359,14 +470,31 @@ async function readCatalog(run: Run, tables: string[], appRole: string): Promise
       WHERE n.nspname = current_schema() AND c.relname = ANY($1) AND k.contype = 'c'`,
   });
   const functionResult = await run({
-    params: [TENANT_FILTER_FUNCTION],
-    text: `SELECT obj_description(p.oid, 'pg_proc') AS version
+    params: [[TENANT_FILTER_FUNCTION, SYNC_STAMP_FUNCTION]],
+    text: `SELECT p.proname AS name, obj_description(p.oid, 'pg_proc') AS version
       FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
-      WHERE n.nspname = current_schema() AND p.proname = $1 AND p.pronargs = 0`,
+      WHERE n.nspname = current_schema() AND p.proname = ANY($1) AND p.pronargs = 0`,
   });
+  const triggerResult = await run({
+    params: [tables],
+    text: `SELECT c.relname AS table, t.tgname AS name
+      FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = current_schema() AND c.relname = ANY($1) AND NOT t.tgisinternal AND t.tgname LIKE 'lt\\_sync\\_%'`,
+  });
+  const sequenceResult = sequences.length
+    ? await run({
+        params: [sequences, appRole],
+        text: `SELECT c.relname AS name, has_sequence_privilege($2, c.oid, 'USAGE') AS usage
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = current_schema() AND c.relkind = 'S' AND c.relname = ANY($1)`,
+      })
+    : { rowCount: 0, rows: [] };
+  const versionOf = (fn: string) => functionResult.rows.find((row) => row.name === fn)?.version ?? null;
 
   const catalog: Catalog = {
-    functionVersion: functionResult.rows[0]?.version ?? null,
+    functionVersion: versionOf(TENANT_FILTER_FUNCTION),
+    sequences: new Map(sequenceResult.rows.map((row: { name: string; usage: boolean }) => [row.name, row.usage])),
+    syncFunctionVersion: versionOf(SYNC_STAMP_FUNCTION),
     schema: schemaResult.rows[0].schema,
     schemaUsage: schemaResult.rows[0].usage,
     tables: new Map(),
@@ -380,8 +508,12 @@ async function readCatalog(run: Run, tables: string[], appRole: string): Promise
       indexes: new Map(),
       policyVersion: row.policy_version ?? null,
       rls: row.rls,
+      syncTriggers: new Set(),
     });
   }
+  for (const row of triggerResult.rows) {
+    catalog.tables.get(row.table)?.syncTriggers.add(row.name);
+  }
   for (const row of columnResult.rows) {
     catalog.tables.get(row.table)?.columns.set(row.name, { collation: row.collation ?? null, type: row.type });
   }