fix(driver-sql): report every member of a SQLite composite primary key, in key order (#11104)

`SqlDriver.introspectPrimaryKeys` filtered `PRAGMA table_info` rows on
`row.pk === 1`. SQLite does not report `pk` as a boolean — it is the column's
1-based position WITHIN the primary key (`0` = not part of the key, `1` = first
key column, `2` = second, ...). The filter kept only the first member of a
composite key and silently dropped the rest.

Both output signals were wrong together and for the same reason:
`introspectSchema` derives `col.isPrimary` FROM `primaryKeys`, so a consumer
could not cross-check its way back to the dropped member. Repairing the list
repairs the flag with it.

The rows are now also ordered by the `pk` ordinal instead of being taken in
`table_info` row order (which is COLUMN order). The two differ whenever a key
is declared out of column sequence, and `primaryKeys` is consumed as an
addressing / upsert-conflict-target key where order is load-bearing.

`SqliteWasmDriver` and `TursoDriver` extend `SqlDriver` and override neither
method, so they inherit the repair. The Postgres and MySQL arms did not carry
this defect and are unchanged.


Claude-Session: https://claude.ai/code/session_01RfyXxZ2WPjcjhuXpiQQc3y

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/sqlite-composite-primary-key-introspection.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+SQLite introspection now reports every member of a composite primary key, in
+declared key order. `SqlDriver.introspectPrimaryKeys` filtered
+`PRAGMA table_info` rows on `row.pk === 1`, but SQLite does not report `pk` as
+a boolean — it is the column's **1-based position within the primary key**
+(`0` = not part of the key, `1` = first key column, `2` = second, and so on).
+The filter therefore kept only the first member of a composite key and silently
+dropped the rest.
+
+Measured on in-memory SQLite, table declared `primary key (order_id, line_no)`:
+
+| signal | reported | reports instead |
+| --- | --- | --- |
+| `table.primaryKeys` | `['order_id']` | `['order_id', 'line_no']` |
+| `column.isPrimary` for `line_no` | `false` | `true` |
+
+Both signals were wrong together and for the same reason: `introspectSchema`
+derives `col.isPrimary` from `primaryKeys`, so a consumer could not recover the
+dropped member by cross-checking the two. Fixing the list repairs the flag with
+it.
+
+The rows are now also ordered by the `pk` ordinal rather than taken in
+`table_info` row order (which is *column* order). The two differ whenever a key
+is declared out of column sequence — a table with columns
+`(carrier_code, shipment_id, leg_seq)` and `primary key (shipment_id,
+carrier_code)` now reports `['shipment_id', 'carrier_code']` — and
+`primaryKeys` is consumed as an addressing / upsert-conflict-target key, where
+the order is load-bearing.
+
+Consumers affected: the federated-object codegen and the persisted
+`external_catalog` (ADR-0015) recorded a partial addressing/upsert key, and
+schema-drift comparison against a declared composite key read as drift on the
+dropped member. `SqliteWasmDriver` and `TursoDriver` extend `SqlDriver` and
+override neither method, so they inherit the repair. The Postgres and MySQL
+arms did not have this defect and are unchanged.

packages/drivers/driver-sql/src/sql-driver-composite-primary-key-introspection.test.ts

@@ -0,0 +1,170 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pin: SQLite introspection must report EVERY member of a composite primary
+ * key, in DECLARED KEY ORDER.
+ *
+ * `PRAGMA table_info` does not report `pk` as a boolean. It reports the
+ * column's **1-based position within the primary key** — `0` for "not part of
+ * the key", `1` for the first key column, `2` for the second, and so on.
+ * `introspectPrimaryKeys` previously filtered on `pk === 1`, which kept only
+ * the first member of a composite key and silently dropped the rest.
+ *
+ * Both output signals were wrong together and for the same reason:
+ * `introspectSchema` derives `col.isPrimary` FROM `primaryKeys`
+ * (`if (primaryKeys.includes(col.name)) col.isPrimary = true`), so a consumer
+ * could not recover the missing member by cross-checking the two. Both are
+ * asserted here.
+ *
+ * `SqliteWasmDriver` and `TursoDriver` extend `SqlDriver` and override neither
+ * `introspectPrimaryKeys` nor `introspectSchema`, so they inherit this arm.
+ * Only the better-sqlite3 binding is executed here.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SqlDriver } from '../src/index.js';
+
+/**
+ * The consumer-visible consequence, modelled locally: comparing a DECLARED
+ * composite key against what introspection recovered. This is what
+ * schema-drift comparison and the federated `external_catalog` addressing key
+ * do with `primaryKeys` — an under-reported member reads as drift.
+ *
+ * Order-sensitive on purpose: `pk` is an ordinal, so a key reported in column
+ * order rather than declared-key order is a different key for addressing and
+ * upsert-conflict-target purposes.
+ */
+function compareDeclaredKey(declared: string[], introspected: string[]): string[] {
+  const findings: string[] = [];
+  for (const col of declared) {
+    if (!introspected.includes(col)) findings.push(`missing_key_member:${col}`);
+  }
+  for (const col of introspected) {
+    if (!declared.includes(col)) findings.push(`unexpected_key_member:${col}`);
+  }
+  if (findings.length === 0 && declared.join(',') !== introspected.join(',')) {
+    findings.push(`key_order_mismatch:${declared.join(',')}!=${introspected.join(',')}`);
+  }
+  return findings;
+}
+
+describe('SqlDriver composite primary-key introspection (SQLite)', () => {
+  let driver: SqlDriver;
+  let knexInstance: any;
+
+  beforeEach(async () => {
+    driver = new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    });
+    knexInstance = (driver as any).knex;
+  });
+
+  afterEach(async () => {
+    await knexInstance.destroy();
+  });
+
+  it('pins the SQLite fact this repair rests on: `pk` is a 1-based ordinal, not a boolean', async () => {
+    await knexInstance.schema.createTable('order_lines', (t: any) => {
+      t.string('order_id').notNullable();
+      t.integer('line_no').notNullable();
+      t.string('sku');
+      t.primary(['order_id', 'line_no']);
+    });
+
+    const rows: any[] = await knexInstance.raw('PRAGMA table_info(order_lines)');
+    const pkByName = Object.fromEntries(rows.map((r) => [r.name, r.pk]));
+
+    // If SQLite ever reported `pk` as a boolean, the fix below would be wrong.
+    expect(pkByName).toEqual({ order_id: 1, line_no: 2, sku: 0 });
+  });
+
+  it('reports every member of a composite key, and derives isPrimary for all of them', async () => {
+    await knexInstance.schema.createTable('order_lines', (t: any) => {
+      t.string('order_id').notNullable();
+      t.integer('line_no').notNullable();
+      t.string('sku');
+      t.primary(['order_id', 'line_no']);
+    });
+
+    const schema = await driver.introspectSchema();
+    const table = schema.tables['order_lines'];
+
+    // Signal 1: the table-level list. `line_no` was dropped before the fix.
+    expect(table.primaryKeys).toEqual(['order_id', 'line_no']);
+
+    // Signal 2: the per-column flag, derived FROM signal 1 — repaired with it.
+    const isPrimaryByName = Object.fromEntries(table.columns.map((c) => [c.name, c.isPrimary === true]));
+    expect(isPrimaryByName).toEqual({ order_id: true, line_no: true, sku: false });
+  });
+
+  it('orders primaryKeys by pk ordinal, not by column position', async () => {
+    // Declared key order (shipment_id, carrier_code) deliberately differs from
+    // column order (carrier_code, shipment_id, leg_seq): iterating table_info
+    // rows in row order would yield the columns in the wrong key order.
+    await knexInstance.schema.createTable('shipment_legs', (t: any) => {
+      t.string('carrier_code').notNullable();
+      t.string('shipment_id').notNullable();
+      t.integer('leg_seq');
+      t.primary(['shipment_id', 'carrier_code']);
+    });
+
+    const rows: any[] = await knexInstance.raw('PRAGMA table_info(shipment_legs)');
+    // Row order is column order; the ordinals run against it.
+    expect(rows.map((r) => [r.name, r.pk])).toEqual([
+      ['carrier_code', 2],
+      ['shipment_id', 1],
+      ['leg_seq', 0],
+    ]);
+
+    const schema = await driver.introspectSchema();
+    expect(schema.tables['shipment_legs'].primaryKeys).toEqual(['shipment_id', 'carrier_code']);
+  });
+
+  it('reads as NO drift when a declared composite key is compared against introspection', async () => {
+    await knexInstance.schema.createTable('order_lines', (t: any) => {
+      t.string('order_id').notNullable();
+      t.integer('line_no').notNullable();
+      t.string('sku');
+      t.primary(['order_id', 'line_no']);
+    });
+
+    const schema = await driver.introspectSchema();
+    const introspected = schema.tables['order_lines'].primaryKeys;
+
+    expect(compareDeclaredKey(['order_id', 'line_no'], introspected)).toEqual([]);
+
+    // Negative control: the comparison above is a real detector, not a
+    // vacuously-empty one. A genuinely different declared key still drifts.
+    expect(compareDeclaredKey(['order_id', 'warehouse_id'], introspected)).toEqual([
+      'missing_key_member:warehouse_id',
+      'unexpected_key_member:line_no',
+    ]);
+    expect(compareDeclaredKey(['line_no', 'order_id'], introspected)).toEqual([
+      'key_order_mismatch:line_no,order_id!=order_id,line_no',
+    ]);
+  });
+
+  it('still reports a single-column key exactly, and an unkeyed table as empty', async () => {
+    await knexInstance.schema.createTable('widgets', (t: any) => {
+      t.string('id').primary();
+      t.string('name');
+    });
+
+    // No primary key at all: every `pk` is 0. Guards the repair against
+    // becoming `pk >= 0`, which would report every column as a key member.
+    await knexInstance.schema.createTable('audit_lines', (t: any) => {
+      t.string('actor');
+      t.string('action');
+    });
+
+    const schema = await driver.introspectSchema();
+
+    expect(schema.tables['widgets'].primaryKeys).toEqual(['id']);
+    expect(schema.tables['audit_lines'].primaryKeys).toEqual([]);
+
+    const auditPrimary = schema.tables['audit_lines'].columns.map((c) => c.isPrimary === true);
+    expect(auditPrimary).toEqual([false, false]);
+  });
+});

packages/drivers/driver-sql/src/sql-driver.ts

@@ -12690,10 +12690,24 @@ export class SqlDriver implements IDataDriver {
 
         const result = await this.knex.raw(`PRAGMA table_info(${safeTableName})`);
 
-        for (const row of result) {
-          if (row.pk === 1) {
-            primaryKeys.push(row.name);
-          }
+        // `PRAGMA table_info` does not report `pk` as a boolean. It reports the
+        // column's 1-based position WITHIN the primary key — `0` for "not part
+        // of the key", `1` for the first key column, `2` for the second, and so
+        // on. Filtering on `pk === 1` therefore kept only the first member of a
+        // composite key and silently dropped the rest, and because
+        // `introspectSchema` derives `col.isPrimary` FROM this list, both output
+        // signals were wrong together.
+        //
+        // Ordering by the ordinal (rather than taking `table_info`'s row order,
+        // which is COLUMN order) makes `primaryKeys` the declared key order. The
+        // two differ whenever a key is declared out of column sequence, and this
+        // list is used as an addressing / upsert-conflict-target key, where the
+        // order is load-bearing.
+        const keyedRows = (result as { name: string; pk: number }[]).filter((row) => row.pk > 0);
+        keyedRows.sort((a, b) => a.pk - b.pk);
+
+        for (const row of keyedRows) {
+          primaryKeys.push(row.name);
         }
       }
     } catch {