From 97c42b50de86c945b35655b40c10e2c8f4279fb5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 3 Sep 2026 00:37:28 +0000
Subject: [PATCH] docs(driver-sql): pool docblocks name the factory's max 5,
 not knex's max 10

Two docblocks in `sql-driver.ts` justified themselves with knex's own
`poolDefaults()` (`{min: 2, max: 10}`) as if it were the size the platform
runs at. It is not: `buildSqlPool` in service-datasource's
`default-datasource-driver-factory.ts` hands every SQL datasource an explicit
`{min: 0, max: 5}` unless the datasource declares its own `pool`, so no
factory-composed datasource ever reaches knex's default.

Both docblocks now name `max: 5` and where that number lives, and keep the
knex fact as one clause -- it is true, and it is why the misreading is easy
to have. Comment-only; no executable line moves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68
---
 packages/drivers/driver-sql/src/sql-driver.ts | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/packages/drivers/driver-sql/src/sql-driver.ts b/packages/drivers/driver-sql/src/sql-driver.ts
index b285c8c380..86faea16e6 100644
--- a/packages/drivers/driver-sql/src/sql-driver.ts
+++ b/packages/drivers/driver-sql/src/sql-driver.ts
@@ -5898,7 +5898,11 @@ export class SqlDriver implements IDataDriver {
     // Run the DDL on the caller's own transaction instead; SQLite permits DDL
     // inside a transaction. We deliberately do NOT route DDL through `parentTrx`
     // on MySQL, where DDL implicitly commits the caller's transaction; there the
-    // roomy pool (max=10) lets a fresh connection create the table safely.
+    // pool has room (max=5) for a fresh connection to create the table safely.
+    // The 5 is `buildSqlPool`'s — service-datasource's
+    // `default-datasource-driver-factory.ts` gives every datasource it composes
+    // `{min:0,max:5}` unless one declares its own `pool` — not knex's roomier
+    // `poolDefaults()` of `{min:2,max:10}`, which the factory never reaches.
     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
@@ -8201,9 +8205,13 @@ export class SqlDriver implements IDataDriver {
    * 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
+   * dialect, whose pool holds more than one connection and so cannot exhibit the
+   * single-connection dead-lock. That headroom is `max: 5`, from `buildSqlPool`
+   * in service-datasource's `default-datasource-driver-factory.ts`, which gives
+   * every datasource it composes `{min:0,max:5}` unless one declares its own
+   * `pool` — not knex's roomier `poolDefaults()` of `{min:2,max:10}`, which the
+   * factory never reaches. 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 {