@proteinjs/db-driver-spanner 1.19.0 → 1.20.1

package/test/BatchedDdl.test.ts

@@ -0,0 +1,293 @@
+import { Database, Spanner } from '@google-cloud/spanner';
+import { Logger } from '@proteinjs/logger';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getTables, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+
+const spannerDriver = new SpannerDriver(spannerConfig);
+
+interface BatchDdlParent extends Record {
+  name?: string;
+}
+
+interface BatchDdlChild extends Record {
+  label?: string;
+  parentId?: string;
+}
+
+/** Parent with a declared index — its create is CREATE TABLE + CREATE INDEX. */
+const parentTable = (): Table<BatchDdlParent> => {
+  return new (class extends Table<BatchDdlParent> {
+    name = 'db_test_batchddl_parent';
+    columns = withRecordColumns<BatchDdlParent>({
+      name: new StringColumn('name'),
+    });
+    indexes = [{ name: 'db_test_batchddl_parent_name_index', columns: ['name'] as (keyof BatchDdlParent)[] }];
+  })();
+};
+
+/** Child whose FK references the parent — creation order across the two tables is load-bearing. */
+const childTable = (): Table<BatchDdlChild> => {
+  return new (class extends Table<BatchDdlChild> {
+    name = 'db_test_batchddl_child';
+    columns = withRecordColumns<BatchDdlChild>({
+      label: new StringColumn('label'),
+      parentId: new StringColumn('parent_id', { references: { table: 'db_test_batchddl_parent' } }),
+    });
+    indexes = [{ name: 'db_test_batchddl_child_label_index', columns: ['label'] as (keyof BatchDdlChild)[] }];
+  })();
+};
+
+/** Parent redeclared with an extra column + extra index — the alter pass under test. */
+const grownParentTable = (): Table<BatchDdlParent & { nickname?: string }> => {
+  return new (class extends Table<BatchDdlParent & { nickname?: string }> {
+    name = 'db_test_batchddl_parent';
+    columns = withRecordColumns<BatchDdlParent & { nickname?: string }>({
+      name: new StringColumn('name'),
+      nickname: new StringColumn('nickname'),
+    });
+    indexes = [
+      { name: 'db_test_batchddl_parent_name_index', columns: ['name'] as (keyof BatchDdlParent)[] },
+      { name: 'db_test_batchddl_parent_nickname_index', columns: ['nickname'] as any },
+    ];
+  })();
+};
+
+describe('Batched DDL', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+    await dropTable(childTable());
+    await dropTable(parentTable());
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(childTable());
+    await dropTable(parentTable());
+    SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('a new table lands via one runUpdateSchema call (CREATE TABLE + its indexes in one batch)', async () => {
+    const parent = parentTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    await tableManager.loadTable(parent);
+
+    // Call-shape at the driver seam: the table's whole schema rides ONE schema-update operation.
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    // Outcome: the schema actually landed (INFORMATION_SCHEMA-backed metadata).
+    expect(await tableManager.tableExists(parent)).toBe(true);
+    const indexes = await tableManager.schemaMetadata.getIndexes(parent);
+    expect(indexes['db_test_batchddl_parent_name_index']).toEqual(['name']);
+
+    await dropTable(parent);
+  }, 60000);
+
+  test('an alter pass (add column + add index) lands via one runUpdateSchema call', async () => {
+    await tableManager.loadTable(parentTable());
+    const grown = grownParentTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    await tableManager.loadTable(grown);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    const columnMetadata = await tableManager.schemaMetadata.getColumnMetadata(grown);
+    expect(columnMetadata['nickname']).toBeDefined();
+    const indexes = await tableManager.schemaMetadata.getIndexes(grown);
+    expect(indexes['db_test_batchddl_parent_nickname_index']).toEqual(['nickname']);
+
+    await dropTable(grown);
+  }, 60000);
+
+  test('parent and FK child land in one ordered batch, and the FK is live', async () => {
+    const parent = parentTable();
+    const child = childTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    // The one-LRO claim is pinned at the CLIENT seam, not just the driver seam: a
+    // runUpdateSchema that quietly looped per-statement operations would still count 1 on the
+    // driver spy but N here.
+    const updateSchemaSpy = jest.spyOn(Database.prototype, 'updateSchema');
+
+    await tableManager.schemaOperations.createTables([parent, child]);
+
+    // One schema-update operation carrying the whole set: 2 CREATE TABLE + 2 CREATE INDEX,
+    // parent's CREATE before the child's (the child's inline FK resolves against it in-batch).
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(updateSchemaSpy).toHaveBeenCalledTimes(1);
+    expect(updateSchemaSpy.mock.calls[0][0]).toHaveLength(4);
+    const statements = spy.mock.calls[0][0] as string[];
+    expect(Array.isArray(statements)).toBe(true);
+    expect(statements).toHaveLength(4);
+    const parentCreateIndex = statements.findIndex((sql) => sql.includes('CREATE TABLE `db_test_batchddl_parent`'));
+    const childCreateIndex = statements.findIndex((sql) => sql.includes('CREATE TABLE `db_test_batchddl_child`'));
+    expect(parentCreateIndex).toBeGreaterThanOrEqual(0);
+    expect(childCreateIndex).toBeGreaterThan(parentCreateIndex);
+
+    // Outcome: both tables live, the child's foreign key and index actually exist.
+    expect(await tableManager.tableExists(parent)).toBe(true);
+    expect(await tableManager.tableExists(child)).toBe(true);
+    const foreignKeys = await tableManager.schemaMetadata.getForeignKeys(child);
+    expect(foreignKeys['parent_id']).toEqual({
+      referencedTableName: 'db_test_batchddl_parent',
+      referencedColumnName: 'id',
+    });
+    const childIndexes = await tableManager.schemaMetadata.getIndexes(child);
+    expect(childIndexes['db_test_batchddl_child_label_index']).toEqual(['label']);
+
+    await dropTable(child);
+    await dropTable(parent);
+  }, 60000);
+
+  test('a wrong-ordered batch (FK child before parent) is REJECTED by the backend — ordering is load-bearing', async () => {
+    const parent = parentTable();
+    const child = childTable();
+    // House-style access to the statement assembler: typed cast on the instance, not a public method.
+    const ops = tableManager.schemaOperations as unknown as { createTableStatements(table: Table<any>): string[] };
+    const childFirst = [...ops.createTableStatements(child), ...ops.createTableStatements(parent)];
+
+    // The child's CREATE TABLE carries an inline FK to a parent that is not yet in the
+    // projected schema at its position in the batch — validation rejects the batch and NOTHING
+    // applies. This is the failure our ordered assembly exists to prevent.
+    await expect(spannerDriver.runUpdateSchema(childFirst)).rejects.toThrow();
+    expect(await tableManager.tableExists(child)).toBe(false);
+    expect(await tableManager.tableExists(parent)).toBe(false);
+  }, 60000);
+
+  test('a schema-invalid statement mid-batch rejects the WHOLE batch upfront — nothing applied (validation phase)', async () => {
+    const parent = parentTable();
+    const ops = tableManager.schemaOperations as unknown as { createTableStatements(table: Table<any>): string[] };
+    const [createParentSql, createNameIndexSql] = ops.createTableStatements(parent);
+    // Statement 2 parses but is schema-invalid (index on a column the table does not have).
+    // Schema-shape errors are caught in the batch's upfront VALIDATION pass — run in order
+    // against the projected schema (the error names the missing column, so statement 1's table
+    // WAS in the validation context) — and reject the batch before anything applies. Strictly
+    // SAFER than the old serial path, which would have left statement 1's table behind.
+    const badIndexSql = 'CREATE INDEX db_test_batchddl_parent_bogus_index ON db_test_batchddl_parent(no_such_column)';
+
+    await expect(spannerDriver.runUpdateSchema([createParentSql, badIndexSql, createNameIndexSql])).rejects.toThrow(
+      /no_such_column/
+    );
+
+    expect(await tableManager.tableExists(parent)).toBe(false);
+  }, 60000);
+
+  test('a data-dependent failure mid-batch leaves EARLIER statements applied, LATER unapplied (apply phase)', async () => {
+    const parent = parentTable();
+    await tableManager.loadTable(parent);
+    // Two rows with the same `name`: schema validation cannot see this — only the APPLY phase
+    // (index backfill) can fail on it.
+    const client = new Spanner({ projectId: spannerConfig.projectId });
+    const database = client.instance(spannerConfig.instanceName).database(spannerConfig.databaseName);
+    database.on('error', () => undefined);
+    try {
+      await database.table(parent.name).insert([
+        { id: 'dup-1', name: 'dup', created: new Date(), updated: new Date() },
+        { id: 'dup-2', name: 'dup', created: new Date(), updated: new Date() },
+      ]);
+    } finally {
+      await database.close().catch(() => undefined);
+      client.close();
+    }
+
+    const statements = [
+      'CREATE INDEX db_test_batchddl_parent_pre_index ON db_test_batchddl_parent(name, id)',
+      'CREATE UNIQUE INDEX db_test_batchddl_parent_dup_unique ON db_test_batchddl_parent(name)',
+      'CREATE INDEX db_test_batchddl_parent_post_index ON db_test_batchddl_parent(id, name)',
+    ];
+    const logErrorSpy = jest.spyOn(Logger.prototype, 'error');
+    await expect(spannerDriver.runUpdateSchema(statements)).rejects.toThrow(/uniqueness violation/);
+
+    // The failure LOG must carry the backend's reason too. Apply-phase LRO errors put it in
+    // `error.message` and leave `error.details` UNDEFINED — logging details alone records an
+    // empty reason for exactly the failure class that leaves partial schema state behind.
+    const failureLog = logErrorSpy.mock.calls.find(
+      ([entry]) => entry.message === 'Failed when executing schema update'
+    );
+    expect(failureLog).toBeDefined();
+    expect(String((failureLog![0].obj as { errorDetails?: unknown }).errorDetails)).toMatch(/uniqueness violation/);
+
+    // Honest partial-failure semantics of the apply phase: NOT atomic. Statement 1 stays
+    // applied; statement 3, ordered after the failure, is cancelled.
+    const indexes = await tableManager.schemaMetadata.getIndexes(parent);
+    expect(indexes['db_test_batchddl_parent_pre_index']).toEqual(['name', 'id']);
+    expect(indexes['db_test_batchddl_parent_dup_unique']).toBeUndefined();
+    expect(indexes['db_test_batchddl_parent_post_index']).toBeUndefined();
+
+    await dropTable(parent);
+  }, 60000);
+
+  test('loadTables creates the whole absent set via one runUpdateSchema call; a second pass issues none', async () => {
+    const registeredTables = getTables();
+    // This package registers the migration table (@proteinjs/db) and the service-verbs doc table.
+    expect(registeredTables.length).toBeGreaterThanOrEqual(2);
+    for (const table of [...registeredTables].reverse()) {
+      await dropTable(table);
+    }
+
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+    await tableManager.loadTables();
+    expect(spy).toHaveBeenCalledTimes(1);
+    for (const table of registeredTables) {
+      expect(await tableManager.tableExists(table)).toBe(true);
+    }
+
+    // Reconcile pass on an up-to-date schema issues zero DDL.
+    spy.mockClear();
+    await tableManager.loadTables();
+    expect(spy).not.toHaveBeenCalled();
+  }, 60000);
+
+  test('createDb with ddl births a queryable database; dropDb removes it', async () => {
+    const databaseName = 'batchddl-born';
+    if (await spannerDriver.dbExists(databaseName)) {
+      await spannerDriver.dropDb(databaseName);
+    }
+
+    await spannerDriver.createDb(databaseName, {
+      ddl: [
+        'CREATE TABLE born_row (id STRING(36) NOT NULL, label STRING(MAX)) PRIMARY KEY (id)',
+        'CREATE INDEX born_row_label_index ON born_row(label)',
+      ],
+    });
+    expect(await spannerDriver.dbExists(databaseName)).toBe(true);
+
+    // Queryability check rides a dedicated client: SpannerDriver's process-wide Database handle
+    // is pinned to the suite's database, and this test is about the NEW database.
+    const client = new Spanner({ projectId: spannerConfig.projectId });
+    const database = client.instance(spannerConfig.instanceName).database(databaseName);
+    database.on('error', () => undefined);
+    try {
+      await database.table('born_row').insert({ id: 'r1', label: 'born' });
+      const [rows] = await database.run({ sql: 'SELECT id, label FROM born_row', json: true });
+      expect(rows).toEqual([{ id: 'r1', label: 'born' }]);
+      const [indexRows] = await database.run({
+        sql: `SELECT i.INDEX_NAME FROM INFORMATION_SCHEMA.INDEXES i WHERE i.TABLE_NAME = 'born_row' AND i.INDEX_NAME = 'born_row_label_index'`,
+        json: true,
+      });
+      expect(indexRows).toHaveLength(1);
+    } finally {
+      await database.close().catch(() => undefined);
+      client.close();
+    }
+
+    await spannerDriver.dropDb(databaseName);
+    expect(await spannerDriver.dbExists(databaseName)).toBe(false);
+  }, 60000);
+});

package/test/ConcurrentSchemaReconcile.test.ts

@@ -0,0 +1,237 @@
+import { IntegerColumn, Record, StringColumn, Table, TableChanges, withRecordColumns } from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+/**
+ * The concurrent-schema-reconcile race (closed by TableManager.reconcileConcurrentSchemaChange +
+ * SpannerSchemaOperations.isAlreadyExistsError).
+ *
+ * On a schema-changing release the migration Job, booting pods, and multiple replicas all run
+ * Db.init -> loadTables at once. loadTable/loadTables is check-then-act: two actors both observe a
+ * column/table as absent and both issue the CREATE/ALTER; Spanner serializes the DDL so the object
+ * lands EXACTLY once, and the loser's operation fails with a duplicate-name / duplicate-column
+ * error. Before the fix the loser rethrew — a booting pod exited (CrashLoopBackOff) and the
+ * migration Job exited 1 (a spurious migration-gate failure).
+ *
+ * The tolerance is not a blanket swallow: it fires only for the already-exists error CLASS and only
+ * after RE-READING the live schema and confirming it matches the INTENDED definition.
+ */
+
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+
+const spannerDriver = new SpannerDriver(spannerConfig);
+
+interface ReconcileRow extends Record {
+  name?: string;
+}
+
+interface GrownRow extends ReconcileRow {
+  nickname?: string;
+}
+
+/** Base table, `name` only — the pre-change schema. */
+const baseTable = (): Table<ReconcileRow> =>
+  new (class extends Table<ReconcileRow> {
+    name = 'db_test_reconcile';
+    columns = withRecordColumns<ReconcileRow>({
+      name: new StringColumn('name'),
+    });
+  })();
+
+/** Same table redeclared with an added `nickname` column — the alter under contention. */
+const grownTable = (): Table<GrownRow> =>
+  new (class extends Table<GrownRow> {
+    name = 'db_test_reconcile';
+    columns = withRecordColumns<GrownRow>({
+      name: new StringColumn('name'),
+      nickname: new StringColumn('nickname'),
+    });
+  })();
+
+interface ConflictRow extends Record {
+  qty?: any;
+}
+
+/** `qty` declared as a STRING — the definition the "winner" lands. */
+const conflictStringTable = (): Table<ConflictRow> =>
+  new (class extends Table<ConflictRow> {
+    name = 'db_test_reconcile_conflict';
+    columns = withRecordColumns<ConflictRow>({
+      qty: new StringColumn('qty'),
+    });
+  })();
+
+/** Same table+column redeclared as INT64 — a GENUINE conflict with what landed. */
+const conflictIntegerTable = (): Table<ConflictRow> =>
+  new (class extends Table<ConflictRow> {
+    name = 'db_test_reconcile_conflict';
+    columns = withRecordColumns<ConflictRow>({
+      qty: new IntegerColumn('qty'),
+    });
+  })();
+
+interface TableManagerInternals {
+  getTableChanges(table: Table<any>): Promise<TableChanges>;
+  reconcileConcurrentSchemaChange(tables: Table<any>[], error: unknown): Promise<void>;
+}
+
+type SpannerTableManager = ReturnType<SpannerDriver['getTableManager']>;
+
+/** House-style access to reconcile internals: a typed cast on the instance, not a public method. */
+const internals = (tableManager: SpannerTableManager) => tableManager as unknown as TableManagerInternals;
+
+/** House-style access to the driver-specific classifier. */
+const classifier = (tableManager: SpannerTableManager) =>
+  tableManager.schemaOperations as unknown as { isAlreadyExistsError(error: unknown): boolean };
+
+describe('Concurrent schema reconcile', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+  }, 60000);
+
+  beforeEach(async () => {
+    await dropTable(baseTable());
+    await dropTable(conflictStringTable());
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(baseTable());
+    await dropTable(conflictStringTable());
+    SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('two actors adding the SAME new column both succeed; the column lands once with the intended type', async () => {
+    // Winner: create the base table, then add `nickname` for real.
+    await tableManager.loadTable(baseTable());
+    await tableManager.loadTable(grownTable());
+
+    // Loser: a second reconciler whose PLANNING read is forced stale (nickname still absent), so it
+    // issues the real `ALTER TABLE ... ADD COLUMN nickname` that the backend rejects as a
+    // duplicate. mockImplementationOnce affects ONLY the planning read; the reconcile's own
+    // verification re-read sees the true (post-winner) schema.
+    const loserTm = spannerDriver.getTableManager();
+    const realGetColumnMetadata = loserTm.schemaMetadata.getColumnMetadata.bind(loserTm.schemaMetadata);
+    jest.spyOn(loserTm.schemaMetadata, 'getColumnMetadata').mockImplementationOnce(async (table) => {
+      const columnMetadata = await realGetColumnMetadata(table);
+      delete columnMetadata['nickname'];
+      return columnMetadata;
+    });
+
+    // OUTCOME: the loser's Db.init-equivalent does NOT reject — the duplicate DDL error is
+    // reconciled to success. (Pre-fix, this rejects with "Duplicate column name" — the red run.)
+    await expect(loserTm.loadTable(grownTable())).resolves.toBeUndefined();
+
+    // The column exists exactly once, with the intended type (StringColumn defaults to STRING(255)).
+    const columnMetadata = await tableManager.schemaMetadata.getColumnMetadata(grownTable());
+    expect(columnMetadata['nickname']).toBeDefined();
+    expect(columnMetadata['nickname'].type).toBe('STRING(255)');
+
+    // And the reconciled schema is truly up to date: a clean pass issues ZERO DDL.
+    const runUpdateSchemaSpy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+    await tableManager.loadTable(grownTable());
+    expect(runUpdateSchemaSpy).not.toHaveBeenCalled();
+  }, 60000);
+
+  test('two actors creating the SAME absent table both succeed; the table lands once', async () => {
+    // Winner: create the table for real.
+    await tableManager.loadTable(baseTable());
+
+    // Loser: a second reconciler forced to see the table as ABSENT at planning, so it issues the
+    // real `CREATE TABLE` that the backend rejects as a duplicate name.
+    const loserTm = spannerDriver.getTableManager();
+    jest.spyOn(loserTm.schemaMetadata, 'tableExists').mockImplementationOnce(async () => false);
+
+    // OUTCOME: the loser's create does NOT reject. (Pre-fix, this rejects with "Duplicate name in
+    // schema" — the red run.)
+    await expect(loserTm.loadTable(baseTable())).resolves.toBeUndefined();
+
+    expect(await tableManager.tableExists(baseTable())).toBe(true);
+  }, 60000);
+
+  test('GENUINE CONFLICT: an already-exists error whose live definition differs from intent STILL throws', async () => {
+    // Winner landed `qty` as STRING(MAX).
+    await tableManager.loadTable(conflictStringTable());
+
+    // Produce a REAL duplicate-column error by adding `qty` again as INT64 (a loser intending a
+    // different type). It IS the already-exists class...
+    let duplicateError: unknown;
+    try {
+      await spannerDriver.runUpdateSchema('ALTER TABLE `db_test_reconcile_conflict` ADD COLUMN `qty` INT64');
+    } catch (error) {
+      duplicateError = error;
+    }
+    expect(duplicateError).toBeDefined();
+    expect(classifier(tableManager).isAlreadyExistsError(duplicateError)).toBe(true);
+
+    // ...but the live schema (qty STRING(MAX)) does NOT match the intended definition (qty INT64),
+    // so reconcile must RETHROW the original error rather than mask a genuine conflict.
+    // (Bite: turn reconcile into a blanket swallow and this rejection disappears.)
+    await expect(
+      internals(tableManager).reconcileConcurrentSchemaChange([conflictIntegerTable()], duplicateError)
+    ).rejects.toBe(duplicateError);
+  }, 60000);
+
+  test('UNRELATED ERROR CLASS: a non-already-exists DDL error propagates unchanged', async () => {
+    // A table that already matches the live schema — verification alone would find nothing to do.
+    await tableManager.loadTable(baseTable());
+
+    // An error from a different class (INVALID_ARGUMENT: index on a missing column).
+    let unrelatedError: unknown;
+    try {
+      await spannerDriver.runUpdateSchema('CREATE INDEX db_test_reconcile_bad ON db_test_reconcile(no_such_col)');
+    } catch (error) {
+      unrelatedError = error;
+    }
+    expect(unrelatedError).toBeDefined();
+    expect(classifier(tableManager).isAlreadyExistsError(unrelatedError)).toBe(false);
+
+    // reconcile must NOT touch this — it is not the already-exists class, so it propagates
+    // unchanged. (Bite: broaden the classifier to match every error and this rejection disappears,
+    // because verification finds no pending changes on the up-to-date table and would swallow it.)
+    await expect(internals(tableManager).reconcileConcurrentSchemaChange([baseTable()], unrelatedError)).rejects.toBe(
+      unrelatedError
+    );
+  }, 60000);
+
+  test('classifier matches ONLY the already-exists class — by code family AND message class', () => {
+    const isAlreadyExists = (code: number | undefined, message: string) =>
+      classifier(tableManager).isAlreadyExistsError({ code, message });
+
+    // Matched: the duplicate/already-exists phrasings under the ALREADY_EXISTS code family {6, 9}.
+    expect(isAlreadyExists(9, '9 FAILED_PRECONDITION: Duplicate column name db_test.qty.')).toBe(true);
+    expect(isAlreadyExists(9, '9 FAILED_PRECONDITION: Duplicate name in schema: db_test.')).toBe(true);
+    expect(isAlreadyExists(6, '6 ALREADY_EXISTS: Table db_test already exists')).toBe(true);
+
+    // NOT matched — other code-9 (FAILED_PRECONDITION) errors that must never be swallowed.
+    expect(
+      isAlreadyExists(
+        9,
+        '9 FAILED_PRECONDITION: a concurrent schema change operation or read-write transaction is already in progress'
+      )
+    ).toBe(false);
+    expect(isAlreadyExists(9, '9 FAILED_PRECONDITION: Index backfill failed: uniqueness violation')).toBe(false);
+
+    // NOT matched — right message, wrong code family.
+    expect(isAlreadyExists(3, '3 INVALID_ARGUMENT: Duplicate column name db_test.qty.')).toBe(false);
+    expect(isAlreadyExists(5, '5 NOT_FOUND: Table not found: db_test')).toBe(false);
+
+    // NOT matched — reconcile-layer errors are plain Errors with no `code`.
+    expect(classifier(tableManager).isAlreadyExistsError(new Error('Unable to change column types in Spanner'))).toBe(
+      false
+    );
+    expect(classifier(tableManager).isAlreadyExistsError(undefined)).toBe(false);
+  });
+});