feat(driver-sql): dev guard that fails fast on the SQLite single-connection deadlock

Turns the latent 'bare this.knex query while a transaction holds SQLite's
only pooled connection' hang (surfacing as 'Knex: Timeout acquiring a
connection') into an immediate, actionable error at the call site.

- Track open transactions (beginTransaction++/commit+rollback--) with a
  WeakSet so the decrement is idempotent on double close.
- assertBareKnexSafe(op): throws only in the danger combination
  (non-production + SQLite + an open transaction). No-op in production and
  on non-SQLite dialects — zero hot-path cost.
- Wire it into ensureSequencesTable's bare-knex branch, catching the
  'opened a tx but forgot to thread it through as parentTrx' regression.

Adds sql-driver-sqlite-tx-guard.test.ts (11 cases: tx bookkeeping, guard
fires on the deadlock shape, guard stays quiet on legitimate paths, and
the production/non-sqlite/no-tx branch matrix).

Author: baozhoutao

.changeset/fix-autonumber-batch-deadlock.md

@@ -20,3 +20,10 @@ Fixes:
   transaction on SQLite instead of grabbing a second connection. It deliberately
   does not route DDL through the caller's transaction on MySQL, where DDL would
   implicitly commit the caller's in-flight transaction.
+- Added a dev/test guard (`assertBareKnexSafe`): on SQLite, issuing a bare
+  `this.knex` query while a transaction holds the single pooled connection now
+  fails fast with an actionable error instead of hanging until the opaque
+  `Knex: Timeout acquiring a connection`. No-op in production and on non-SQLite
+  dialects, so it adds no runtime cost on the hot path — it just turns this whole
+  class of "forgot to thread the transaction through" bug into an immediate,
+  self-explaining failure at the call site.

packages/plugins/driver-sql/src/sql-driver-sqlite-tx-guard.test.ts

@@ -0,0 +1,196 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Dev/test guard against the SQLite single-connection dead-lock.
+//
+// SQLite's connection pool hands out exactly one connection. Issuing a bare
+// `this.knex` query while a transaction holds that connection blocks forever
+// acquiring a second one and finally fails with the opaque "Knex: Timeout
+// acquiring a connection" — the reported /api/v1/batch autonumber dead-lock.
+//
+// `assertBareKnexSafe` turns that latent, timeout-delayed hang into an
+// immediate, actionable error at the call site. This is the regression tripwire
+// for "a caller opened a transaction but forgot to thread it through": the
+// sequence-table ensure would otherwise silently fall back to `this.knex` and
+// dead-lock. The guard is a no-op in production and on non-SQLite dialects.
+
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import { SqlDriver } from '../src/index.js';
+
+const SEQUENCES_TABLE = '_objectstack_sequences';
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  return Promise.race([
+    p,
+    new Promise<T>((_, rej) => setTimeout(() => rej(new Error(`TIMEOUT: ${label}`)), ms)),
+  ]);
+}
+
+describe('SqlDriver SQLite single-connection tx guard', () => {
+  let driver: SqlDriver | undefined;
+  const savedEnv = process.env.NODE_ENV;
+
+  afterEach(async () => {
+    if (savedEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = savedEnv;
+    if (driver) await driver.disconnect();
+    driver = undefined;
+  });
+
+  async function setup() {
+    driver = new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    });
+    await driver.initObjects([
+      {
+        name: 'contract',
+        fields: {
+          contract_number: { type: 'autonumber', format: 'CTR-{0000}' },
+          name: { type: 'string' },
+        },
+      },
+    ]);
+    return (driver as any).knex;
+  }
+
+  /** Force the lazy fallback: drop the pre-created table and clear the cache. */
+  function coldStart() {
+    (driver as any).sequencesTableReady = false;
+    (driver as any).sequencesHasKeyHash = false;
+    (driver as any).sequencesTableEnsurePromise = null;
+  }
+
+  describe('beginTransaction bookkeeping', () => {
+    it('counts an open transaction and releases it on commit', async () => {
+      await setup();
+      expect((driver as any).activeTransactions).toBe(0);
+      const trx = await driver!.beginTransaction();
+      expect((driver as any).activeTransactions).toBe(1);
+      await driver!.commit(trx);
+      expect((driver as any).activeTransactions).toBe(0);
+    });
+
+    it('releases the count on rollback too', async () => {
+      await setup();
+      const trx = await driver!.beginTransaction();
+      expect((driver as any).activeTransactions).toBe(1);
+      await driver!.rollback(trx);
+      expect((driver as any).activeTransactions).toBe(0);
+    });
+
+    it('releases via the deprecated commitTransaction/rollbackTransaction aliases', async () => {
+      await setup();
+      const t1 = await driver!.beginTransaction();
+      await driver!.commitTransaction(t1);
+      expect((driver as any).activeTransactions).toBe(0);
+      const t2 = await driver!.beginTransaction();
+      await driver!.rollbackTransaction(t2);
+      expect((driver as any).activeTransactions).toBe(0);
+    });
+
+    it('does not double-decrement when a transaction is closed twice', async () => {
+      await setup();
+      const trx = await driver!.beginTransaction();
+      expect((driver as any).activeTransactions).toBe(1);
+      await driver!.commit(trx);
+      expect((driver as any).activeTransactions).toBe(0);
+      // A redundant second close must not drive the count negative.
+      await driver!.commit(trx).catch(() => {});
+      expect((driver as any).activeTransactions).toBe(0);
+    });
+  });
+
+  describe('guard fires on the dead-lock shape', () => {
+    it('fails fast (not a 6s timeout) when a cold ensure runs bare-knex mid-transaction', async () => {
+      const k = await setup();
+      await k.schema.dropTableIfExists(SEQUENCES_TABLE);
+      coldStart();
+
+      // A transaction now owns the single connection. A create WITHOUT threading
+      // that transaction through hits the lazy ensure on `this.knex` — the guard
+      // must reject immediately instead of blocking on connection acquisition.
+      const trx = await driver!.beginTransaction();
+      try {
+        await withTimeout(
+          (driver as any).ensureSequencesTable(undefined),
+          2000,
+          'ensureSequencesTable should have thrown, not hung',
+        );
+        throw new Error('expected the guard to throw');
+      } catch (err: any) {
+        expect(err.message).toMatch(/transaction is open|dead-lock|Timeout acquiring/i);
+        // Specifically the guard's message, not a real acquire-timeout.
+        expect(err.message).not.toMatch(/^TIMEOUT:/);
+      } finally {
+        await driver!.rollback(trx);
+      }
+    });
+
+    it('surfaces the guard through a real create() that forgot to pass the tx', async () => {
+      const k = await setup();
+      await k.schema.dropTableIfExists(SEQUENCES_TABLE);
+      coldStart();
+
+      const trx = await driver!.beginTransaction();
+      try {
+        await expect(
+          withTimeout(
+            driver!.create('contract', { name: 'A' }), // no { transaction: trx } — the bug shape
+            2000,
+            'create should have failed fast',
+          ),
+        ).rejects.toThrow(/transaction is open|dead-lock/i);
+      } finally {
+        await driver!.rollback(trx);
+      }
+    });
+  });
+
+  describe('guard does NOT fire on legitimate paths', () => {
+    it('allows a cold ensure that correctly rides the caller transaction', async () => {
+      const k = await setup();
+      await k.schema.dropTableIfExists(SEQUENCES_TABLE);
+      coldStart();
+
+      const trx = await driver!.beginTransaction();
+      // parentTrx passed → runs on the transaction, no bare-knex, no throw.
+      await expect((driver as any).ensureSequencesTable(trx)).resolves.toBeUndefined();
+      await driver!.commit(trx);
+      expect(await k.schema.hasTable(SEQUENCES_TABLE)).toBe(true);
+    });
+
+    it('allows bare-knex ensure when NO transaction is open (the initObjects path)', async () => {
+      const k = await setup();
+      await k.schema.dropTableIfExists(SEQUENCES_TABLE);
+      coldStart();
+      // activeTransactions === 0 → bare knex is safe.
+      await expect((driver as any).ensureSequencesTable(undefined)).resolves.toBeUndefined();
+      expect(await k.schema.hasTable(SEQUENCES_TABLE)).toBe(true);
+    });
+  });
+
+  describe('assertBareKnexSafe branch matrix', () => {
+    beforeEach(async () => {
+      await setup();
+    });
+
+    it('throws only in the danger combination: non-prod + sqlite + open tx', () => {
+      (driver as any).activeTransactions = 1;
+      delete process.env.NODE_ENV;
+      expect(() => (driver as any).assertBareKnexSafe('x')).toThrow(/transaction is open/i);
+    });
+
+    it('is a no-op in production (guard must never break real deployments)', () => {
+      (driver as any).activeTransactions = 1;
+      process.env.NODE_ENV = 'production';
+      expect(() => (driver as any).assertBareKnexSafe('x')).not.toThrow();
+    });
+
+    it('is a no-op when no transaction is open', () => {
+      (driver as any).activeTransactions = 0;
+      delete process.env.NODE_ENV;
+      expect(() => (driver as any).assertBareKnexSafe('x')).not.toThrow();
+    });
+  });
+});

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

@@ -370,6 +370,19 @@ export class SqlDriver implements IDataDriver {
   /** In-flight ensure promise; deduplicates concurrent first calls. */
   protected sequencesTableEnsurePromise: Promise<void> | null = null;
 
+  /**
+   * Count of transactions currently open through `beginTransaction`. On SQLite
+   * the pool holds a single connection, so while this is > 0 that connection is
+   * busy and any bare `this.knex` query would dead-lock acquiring a second one.
+   * Used only by the dev/test guard `assertBareKnexSafe`. Incremented in
+   * `beginTransaction`, decremented in `commit`/`rollback`; the `openTransactions`
+   * set makes the decrement idempotent so a double commit/rollback can't drive
+   * the count negative or double-count.
+   */
+  protected activeTransactions = 0;
+  /** Transactions counted in `activeTransactions` and not yet released. */
+  protected openTransactions = new WeakSet<object>();
+
   /**
    * Per-table tenant-isolation column. Populated during `initObjects` by
    * detecting an `organization_id` field. When set and the caller passes
@@ -758,6 +771,11 @@ export class SqlDriver implements IDataDriver {
     // on MySQL, where DDL implicitly commits the caller's transaction; there the
     // roomy pool (max=10) lets a fresh connection create the table safely.
     const runner: Knex | Knex.Transaction = parentTrx && this.isSqlite ? parentTrx : this.knex;
+    // If we are about to run DDL on a fresh pooled connection while a SQLite
+    // transaction holds the only one, fail fast with a clear message instead of
+    // dead-locking. This catches the "caller opened a transaction but did not
+    // thread it through as parentTrx" regression at the call site (dev/test only).
+    if (runner === this.knex) this.assertBareKnexSafe('ensureSequencesTable');
     this.sequencesTableEnsurePromise = (async () => {
       const exists = await runner.schema.hasTable(SEQUENCES_TABLE);
       if (!exists) {
@@ -1270,17 +1288,63 @@ export class SqlDriver implements IDataDriver {
   // ===================================
 
   async beginTransaction(): Promise<Knex.Transaction> {
-    return await this.knex.transaction();
+    const trx = await this.knex.transaction();
+    this.openTransactions.add(trx as unknown as object);
+    this.activeTransactions++;
+    return trx;
+  }
+
+  /** Idempotently drop a transaction from the open-count (safe on double close). */
+  protected releaseTransaction(transaction: unknown): void {
+    const key = transaction as object;
+    if (key && this.openTransactions.has(key)) {
+      this.openTransactions.delete(key);
+      this.activeTransactions = Math.max(0, this.activeTransactions - 1);
+    }
+  }
+
+  /**
+   * Dev/test guard against the SQLite single-connection dead-lock. SQLite's pool
+   * hands out exactly one connection, so issuing a bare `this.knex` query while a
+   * transaction holds that connection blocks forever acquiring a second one and
+   * finally fails with an opaque `Knex: Timeout acquiring a connection`. This
+   * turns that into an immediate, actionable error at the call site.
+   *
+   * No-op in production (zero overhead on the hot path) and on every non-SQLite
+   * dialect, whose roomy pools (max ≥ 10) cannot exhibit the single-connection
+   * dead-lock. Callers that legitimately need the connection during a
+   * transaction must bind the operation to that transaction instead of
+   * `this.knex`.
+   */
+  protected assertBareKnexSafe(op: string): void {
+    if (this.isProductionEnv()) return;
+    if (!this.isSqlite) return;
+    if (this.activeTransactions === 0) return;
+    throw new Error(
+      `[driver-sql] refusing to run '${op}' on a fresh pooled connection while a ` +
+        `transaction is open: SQLite's pool has a single connection, so acquiring a ` +
+        `second one would dead-lock (surfacing later as "Knex: Timeout acquiring a ` +
+        `connection"). Bind this operation to the active transaction instead of using ` +
+        `this.knex.`,
+    );
   }
 
   /** IDataDriver standard */
   async commit(transaction: unknown): Promise<void> {
-    await (transaction as Knex.Transaction).commit();
+    try {
+      await (transaction as Knex.Transaction).commit();
+    } finally {
+      this.releaseTransaction(transaction);
+    }
   }
 
   /** IDataDriver standard */
   async rollback(transaction: unknown): Promise<void> {
-    await (transaction as Knex.Transaction).rollback();
+    try {
+      await (transaction as Knex.Transaction).rollback();
+    } finally {
+      this.releaseTransaction(transaction);
+    }
   }
 
   /** @deprecated Use commit() instead */