tina4-nodejs 3.13.92 → 3.13.95

package/packages/orm/src/database.ts

@@ -1,8 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, FieldDefinition } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
+import { DatabaseUrl } from "./databaseUrl.js";
 import { CachedDatabaseAdapter, type CachedAdapterOptions } from "./cachedDatabase.js";
-import { QueryCache } from "./sqlTranslator.js";
+import { QueryCache, SQLTranslator } from "./sqlTranslator.js";
 
 /**
  * v3.13.12 — strip trailing `;` and whitespace from user-supplied SQL
@@ -96,13 +97,13 @@ export async function adapterTableExists(adapter: DatabaseAdapter, name: string)
 export async function adapterTables(adapter: DatabaseAdapter): Promise<string[]> {
   return (adapter as any).tablesAsync
     ? await (adapter as any).tablesAsync()
-    : adapter.tables();
+    : adapter.getTables();
 }
 
 export async function adapterColumns(adapter: DatabaseAdapter, table: string): Promise<ColumnInfo[]> {
   return (adapter as any).columnsAsync
     ? await (adapter as any).columnsAsync(table)
-    : adapter.columns(table);
+    : adapter.getColumns(table);
 }
 
 export async function adapterCreateTable(
@@ -131,6 +132,16 @@ export function extractLastInsertId(result: unknown): number | bigint | null {
 }
 
 let activeAdapter: DatabaseAdapter | null = null;
+/**
+ * The default row cap on every read path that advertises a `limit`.
+ *
+ * One number for the whole family (Python, PHP, Ruby and Node all default to
+ * this). Pagination is a default principle: an un-paginated read of a table
+ * that grew to a million rows is a production incident waiting to happen. A
+ * caller who wants more passes a bigger limit.
+ */
+export const DEFAULT_ROW_CAP = 100;
+
 const namedAdapters: Map<string, DatabaseAdapter> = new Map();
 
 /**
@@ -289,166 +300,20 @@ export interface DatabaseConfig {
 /**
  * Parsed result from a TINA4_DATABASE_URL connection string.
  */
-export interface ParsedDatabaseUrl {
-  type: "sqlite" | "postgres" | "mysql" | "mssql" | "firebird" | "mongodb" | "odbc";
-  path?: string;
-  host?: string;
-  port?: number;
-  user?: string;
-  password?: string;
-  database?: string;
-  /** ODBC-specific: raw connection string passed to odbc.connect() */
-  connectionString?: string;
-}
-
 /**
- * Parse a TINA4_DATABASE_URL connection string into its components.
+ * Parse a connection URL into a `DatabaseUrl` value.
  *
- * Supported formats:
- *   sqlite:///path/to/db.sqlite
- *   sqlite://./relative/path.db
- *   postgresql://user:pass@host:port/dbname
- *   postgres://user:pass@host:port/dbname
- *   mysql://user:pass@host:port/dbname
+ * Breaking (feature 5): this returned a `ParsedDatabaseUrl` struct whose fields
+ * were `type`, `user` and `path`. It now returns a `DatabaseUrl`, whose fields
+ * are `engine`, `username` and `database` - the same names PHP, Python and Ruby
+ * use, and the same names as the TINA4_DATABASE_USERNAME env var they come from.
+ * `ParsedDatabaseUrl` is gone rather than kept as an alias.
  *
- * @param url - The connection URL string.
- * @param username - Optional username to merge when the URL has no credentials.
- * @param password - Optional password to merge when the URL has no credentials.
- * @returns Parsed database configuration.
- * @throws Error if the URL scheme is not supported.
+ * The 43-CC body that used to live here - the worst function measured anywhere
+ * in the audit - is now one small parser per engine inside the value type.
  */
-export function parseDatabaseUrl(url: string, username?: string, password?: string): ParsedDatabaseUrl {
-  let result: ParsedDatabaseUrl;
-
-  // Handle sqlite:// separately because URL class mangles the path.
-  //
-  // Convention (matches tina4-python, tina4-php, and the docs):
-  //   sqlite::memory:              → in-memory
-  //   sqlite:///:memory:           → in-memory (URL form)
-  //   sqlite:///app.db             → ./app.db (relative to cwd)
-  //   sqlite:///data/app.db        → ./data/app.db (relative)
-  //   sqlite:////absolute/app.db   → /absolute/app.db (absolute)
-  //   sqlite:///C:/Users/app.db    → C:/Users/app.db (Windows absolute)
-  if (url === "sqlite::memory:" || url === "sqlite:///:memory:") {
-    result = { type: "sqlite", path: ":memory:" };
-  } else if (url.startsWith("sqlite:///")) {
-    // Strip the "sqlite://" prefix (leaving one "/" + path)
-    let rest = url.slice("sqlite://".length); // e.g. "/data/app.db" or "//abs/app.db" or "/C:/Users/..."
-    // Drop exactly one leading "/"
-    if (rest.startsWith("/")) rest = rest.slice(1);
-    // Windows absolute: C:/Users/app.db or C:\...
-    const isWindowsAbs = /^[A-Za-z]:[\/\\]/.test(rest);
-    // Unix absolute: still starts with "/" after the strip (four-slash URL form)
-    const isUnixAbs = rest.startsWith("/");
-    result = { type: "sqlite", path: isWindowsAbs || isUnixAbs ? rest : rest };
-    // Relative paths are resolved against cwd by the SQLite adapter at connect time;
-    // keep the string as-is here so tests can inspect the raw form.
-  } else if (url.startsWith("sqlite://")) {
-    // sqlite://./relative or sqlite://relative — legacy two-slash form
-    const path = url.slice("sqlite://".length);
-    result = { type: "sqlite", path };
-  } else if (url.startsWith("sqlite:")) {
-    // sqlite:/abs/app.db (one slash = a real absolute path) or sqlite:app.db (relative).
-    // Keep the leading slash so resolveSqlitePath's isAbsolute() sees the absolute path —
-    // this form used to fall through and throw "unsupported scheme" (the naive-abs footgun).
-    const path = url.slice("sqlite:".length);
-    result = { type: "sqlite", path };
-  } else if (url.startsWith("mssql://") || url.startsWith("sqlserver://")) {
-    // Handle mssql:// and sqlserver:// with custom parsing (URL class doesn't know these schemes)
-    const match = url.match(/(?:mssql|sqlserver):\/\/(?:([^:]+):([^@]+)@)?([^:/]+)(?::(\d+))?\/(.*)/);
-    if (!match) throw new Error(`Invalid MSSQL URL: ${url}`);
-    result = {
-      type: "mssql",
-      user: match[1] ? decodeURIComponent(match[1]) : undefined,
-      password: match[2] ? decodeURIComponent(match[2]) : undefined,
-      host: match[3],
-      port: match[4] ? parseInt(match[4], 10) : undefined,
-      database: match[5],
-    };
-  } else if (url.startsWith("firebird://")) {
-    const match = url.match(/firebird:\/\/(?:([^:]+):([^@]+)@)?([^:/]+)(?::(\d+))?\/(.*)/);
-    if (!match) throw new Error(`Invalid Firebird URL: ${url}`);
-    result = {
-      type: "firebird",
-      user: match[1] ? decodeURIComponent(match[1]) : undefined,
-      password: match[2] ? decodeURIComponent(match[2]) : undefined,
-      host: match[3],
-      port: match[4] ? parseInt(match[4], 10) : undefined,
-      database: "/" + match[5],
-    };
-  } else if (url.startsWith("odbc:///")) {
-    // odbc:///DSN=MyDSN  or  odbc:///DRIVER={driver};SERVER=host;DATABASE=db
-    // Strip the "odbc:///" prefix and pass the rest directly as the connection string
-    const connectionString = url.slice("odbc:///".length);
-    result = { type: "odbc", connectionString };
-  } else if (url.startsWith("mongodb://") || url.startsWith("mongodb+srv://")) {
-    // Pass through as-is; MongodbAdapter handles the full connection string
-    let parsed: URL;
-    try {
-      parsed = new URL(url);
-    } catch {
-      throw new Error(`Invalid MongoDB URL: ${url}`);
-    }
-    const database = parsed.pathname.replace(/^\//, "") || "tina4";
-    result = {
-      type: "mongodb",
-      host: parsed.hostname || undefined,
-      port: parsed.port ? parseInt(parsed.port, 10) : undefined,
-      user: parsed.username ? decodeURIComponent(parsed.username) : undefined,
-      password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
-      database,
-    };
-  } else {
-    // Normalize postgres:// and pgsql:// (the PDO/Laravel/Doctrine scheme
-    // name, issue #58) to postgresql:// for URL parsing.
-    const normalizedUrl = /^(postgres|pgsql):\/\//.test(url)
-      ? url.replace(/^(postgres|pgsql):\/\//, "postgresql://")
-      : url;
-
-    let parsed: URL;
-    try {
-      parsed = new URL(normalizedUrl);
-    } catch {
-      throw new Error(`Invalid database URL: ${url}`);
-    }
-
-    const scheme = parsed.protocol.replace(/:$/, "");
-    let type: "sqlite" | "postgres" | "mysql" | "mssql" | "firebird";
-
-    switch (scheme) {
-      case "postgresql":
-        type = "postgres";
-        break;
-      case "mysql":
-        type = "mysql";
-        break;
-      default:
-        throw new Error(`Unsupported database URL scheme: "${scheme}". Supported: sqlite, postgres/postgresql, mysql, mssql/sqlserver, firebird.`);
-    }
-
-    const database = parsed.pathname.startsWith("/")
-      ? parsed.pathname.slice(1)
-      : parsed.pathname;
-
-    result = {
-      type,
-      host: parsed.hostname || undefined,
-      port: parsed.port ? parseInt(parsed.port, 10) : undefined,
-      user: parsed.username ? decodeURIComponent(parsed.username) : undefined,
-      password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
-      database: database || undefined,
-    };
-  }
-
-  // Merge separate username/password when the URL contained no credentials
-  if (!result.user && username) {
-    result.user = username;
-  }
-  if (!result.password && password) {
-    result.password = password;
-  }
-
-  return result;
+export function parseDatabaseUrl(url: string, username?: string, password?: string): DatabaseUrl {
+  return new DatabaseUrl(url, username, password);
 }
 
 /**
@@ -484,6 +349,9 @@ export class Database {
   /** Factory for creating new adapters (used by pool) */
   private adapterFactory: (() => Promise<DatabaseAdapter>) | null = null;
 
+  /** table -> primary-key column name (or null), introspected once */
+  private _pkCache: Map<string, string[]> = new Map();
+
   /**
    * Whether a standalone write auto-commits. ON by default — a write made
    * outside an explicit transaction commits on its own connection before
@@ -571,7 +439,7 @@ export class Database {
       db.poolIndex = 0;
       db.adapter = null;  // Don't use single-adapter path
       db.adapterFactory = async () => wrapWithCache(await createAdapterFromUrl(url, username, password), { sharedCache });
-      db.dbType = parsed.type;
+      db.dbType = parsed.engine;
       return exposeDb(db);
     }
 
@@ -581,7 +449,7 @@ export class Database {
     const adapter = await createAdapterFromUrl(url, username, password);
     const wrapped = setAdapter(adapter);
     const db = new Database(wrapped);
-    db.dbType = parsed.type;
+    db.dbType = parsed.engine;
     return exposeDb(db);
   }
 
@@ -672,7 +540,31 @@ export class Database {
    * the fallback resolves instantly). This is the breaking change that makes
    * the wrapper work uniformly across every engine.
    */
+  /**
+   * Fetch rows with pagination, capped at DEFAULT_ROW_CAP (100) when the
+   * caller does not pass a limit.
+   *
+   * The cap is the one row-cap number the whole family shares (Python, PHP and
+   * Ruby all default `fetch` to 100). Node was the outlier: `limit` was
+   * optional with NO default, so a bare `db.fetch("select * from big_table")`
+   * returned every row.
+   *
+   * `fetchAll` deliberately does NOT inherit the cap — see below.
+   */
   async fetch(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<DatabaseResult> {
+    return this._fetchWithLimit(sql, params, limit ?? DEFAULT_ROW_CAP, offset, opts);
+  }
+
+  /**
+   * The shared read body. `limit` is passed through VERBATIM: `undefined`
+   * means "no LIMIT clause at all", which is how `fetchAll` stays uncapped.
+   *
+   * This exists because Node's adapters treat `limit: 0` as `LIMIT 0` (zero
+   * rows), not as the "no truncation" sentinel Python and PHP use — so the cap
+   * cannot live on the parameter default, or `fetchAll()` would silently
+   * inherit it and stop returning every row.
+   */
+  private async _fetchWithLimit(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<DatabaseResult> {
     // v3.13.12: strip trailing `;` before the adapter wraps with COUNT(*)
     // or appends LIMIT/OFFSET. Without this, `"SELECT * FROM t;"` becomes
     // `"SELECT * FROM t; LIMIT 100 OFFSET 0"` — a syntax error.
@@ -683,7 +575,8 @@ export class Database {
       // no store, run directly (mirrors the Python master's `no_cache`).
       const rows = await adapterFetch(adapter, sql, params, limit, offset, opts?.noCache);
       this.lastError = null;
-      return new DatabaseResult(rows, undefined, undefined, limit, offset, adapter, sql);
+      const total = await this.countProbe(adapter, sql, params, limit);
+      return new DatabaseResult(rows, undefined, total, limit, offset, adapter, sql);
     } catch (e: any) {
       // v3.13.11 #49.2: fetch() records last_error like execute() does.
       this.lastError = e?.message ?? String(e);
@@ -691,6 +584,63 @@ export class Database {
     }
   }
 
+  /**
+   * The true row count for `sql`, ignoring the pagination we appended.
+   *
+   * `count` is the TRUE TOTAL for the filter, not the number of rows this page
+   * returned. Node and Ruby used to populate it with `records.length` while
+   * Python and PHP populated it from a probe, so `db.fetch(sql).count` answered
+   * 20 here and 250 there for one query against one table, and every paginated
+   * response built on it under-reported. MEASURED 2026-08-05 on a 250-row table
+   * read with limit=20: Node reported total 20 over 2 pages against Python's
+   * 250 over 13.
+   *
+   * Only probed when a limit was actually applied. With no limit the rows
+   * returned ARE the whole answer for this SQL, so `records.length` is already
+   * the true total and a second round-trip would buy nothing — which is also
+   * what keeps `fetchAll()` at one query.
+   *
+   * BEST EFFORT, and it can never mask a real failure: it runs AFTER the main
+   * query (which has already thrown on bad SQL) and returns undefined on any
+   * error. `undefined` — not 0 — is the miss value, so DatabaseResult falls
+   * back to records.length, a true lower bound. Reporting 0 next to 100 real
+   * records would be the same "states a wrong number authoritatively" defect
+   * this change exists to remove.
+   *
+   * The closing paren goes on its OWN LINE: appended inline, a trailing
+   * `-- comment` in the caller's SQL comments it out and the probe dies with
+   * "incomplete input". Postgres, MySQL and MSSQL additionally require a name
+   * for the derived table; SQLite and Firebird do not, and Firebird rejects
+   * `AS` there — so the alias comes from the adapter, not an assumption.
+   */
+  private async countProbe(
+    adapter: DatabaseAdapter,
+    sql: string,
+    params: unknown[] | undefined,
+    limit: number | undefined,
+  ): Promise<number | undefined> {
+    if (limit === undefined || limit <= 0) return undefined;
+    try {
+      const alias = (adapter as any).countSubqueryAlias as string | undefined;
+      const suffix = alias ? ` AS ${alias}` : "";
+      const rows = await adapterFetch(
+        adapter,
+        `SELECT COUNT(*) AS tina4_total FROM (${sql}\n)${suffix}`,
+        params,
+        undefined,
+        undefined,
+        true,
+      );
+      const row = Array.isArray(rows) ? (rows[0] as Record<string, unknown> | undefined) : undefined;
+      if (!row) return undefined;
+      const value = row["tina4_total"] ?? row["TINA4_TOTAL"] ?? Object.values(row)[0];
+      const n = Number(value);
+      return Number.isFinite(n) ? n : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   /**
    * Fetch a single row or null.
    *
@@ -738,7 +688,10 @@ export class Database {
    * SEPARATE trailing argument, never the params array.
    */
   async fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<T[]> {
-    return (await this.fetch(sql, params, limit, offset, opts)).records as T[];
+    // Routes through _fetchWithLimit, NOT fetch(), so `limit` stays verbatim.
+    // Going through fetch() would apply the 100-row cap and make a method
+    // called "fetchAll" quietly stop returning them all.
+    return (await this._fetchWithLimit(sql, params, limit, offset, opts)).records as T[];
   }
 
   /**
@@ -787,28 +740,174 @@ export class Database {
     return result;
   }
 
-  /** Update rows in a table matching filter. */
-  async update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult> {
+  /**
+   * The table's primary-key column, introspected once and cached.
+   *
+   * Uses the cross-engine getColumns() contract (v3.13.14, #48), which reports
+   * primaryKey per column on every adapter. Resolves to null when the table has
+   * no primary key or cannot be introspected.
+   */
+  async primaryKey(table: string): Promise<string[]> {
+    if (!this._pkCache.has(table)) {
+      let pk: string[] = [];
+      try {
+        const columns = await this.getColumns(table);
+        pk = columns.filter((c) => c.primaryKey).map((c) => c.name);
+      } catch {
+        pk = [];
+      }
+      this._pkCache.set(table, pk);
+    }
+    return this._pkCache.get(table) ?? [];
+  }
+
+  /**
+   * A failed write must be loud.
+   *
+   * The adapters catch a SQL error and return { success: false, affectedRows: 0 },
+   * so a filterless update produced invalid SQL ("... WHERE ") and reported
+   * nothing rather than raising. A caller who does not inspect the result
+   * believes the write landed (audit feature 4, P1).
+   */
+  private static assertWrote(result: DatabaseWriteResult, verb: string, table: string): DatabaseWriteResult {
+    if (result && (result as any).success === false) {
+      throw new Error(
+        `${verb} failed on ${table}: ${(result as any).error ?? "unknown error"}`,
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Update rows. A write with no filter is an error, not a full-table write.
+   *
+   * With no explicit filter the primary key is taken out of `data` and used as
+   * the WHERE clause. With neither a filter nor a primary key in `data` this
+   * throws rather than silently changing nothing (audit feature 4, P1).
+   */
+  async update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseWriteResult> {
+    let effectiveFilter: Record<string, unknown> | string = filter ?? {};
+    let effectiveData = data;
+
+    // A string filter is the OTHER documented form ("id = ?" + params), so it
+    // must be tested as a string: Object.keys("id = ?") is ["0",..,"5"], which
+    // is non-empty by accident rather than by meaning — and an EMPTY string
+    // filter would then be treated as a real filter instead of falling through
+    // to the primary key.
+    const filterIsEmpty = typeof effectiveFilter === "string"
+      ? effectiveFilter.trim() === ""
+      : Object.keys(effectiveFilter).length === 0;
+
+    if (filterIsEmpty) {
+      const pkColumns = await this.primaryKey(table);
+      // Resolve each key column to the caller's OWN key for it, matched
+      // case-insensitively.
+      //
+      // The engines disagree about identifier case BY DESIGN and always will:
+      // Firebird folds an unquoted identifier to UPPER, PostgreSQL folds it to
+      // LOWER, MySQL and SQLite preserve what was typed. Introspection returns
+      // the ENGINE's spelling while `data` carries the caller's, so `c in data`
+      // failed on whichever engine folds the other way. A case-sensitivity bug,
+      // not a Firebird quirk - Firebird just made it visible first.
+      //
+      // Deliberately does NOT lower-case introspection output: that would
+      // special-case one engine and break a genuinely quoted mixed-case table.
+      // The WHERE is built from the ENGINE's column name and the CALLER's value.
+      const resolved: Record<string, string> = {};
+      const missing: string[] = [];
+      for (const col of pkColumns) {
+        const folded = String(col).toLowerCase();
+        const matches = Object.keys(data).filter((k) => k.toLowerCase() === folded);
+        if (matches.length > 1) {
+          // Ambiguity is refused, never guessed - choosing wrong here writes the
+          // WHERE clause of an UPDATE.
+          throw new Error(
+            `update was given more than one key for the primary-key column ${col}: ` +
+              `[${matches.slice().sort().join(", ")}] (table=${table}). These differ ` +
+              `only by case, so which one identifies the row is ambiguous - pass ` +
+              `exactly one, or pass an explicit filter.`,
+          );
+        }
+        if (matches.length === 1) resolved[col] = matches[0];
+        else missing.push(col);
+      }
+      if (pkColumns.length === 0 || missing.length > 0) {
+        throw new Error(
+          `update requires a filter or the complete primary key in the data; pass ` +
+            `filter explicitly to update multiple rows (table=${table}, ` +
+            `primary key=[${pkColumns.join(", ")}], missing from data=[${missing.join(", ")}]). ` +
+            `To empty a table use truncate(${table}).`,
+        );
+      }
+      // EVERY key column goes into the WHERE. A composite key built from only its
+      // first column would match every row sharing that value - the data-loss bug
+      // this method exists to prevent, reintroduced.
+      effectiveData = { ...data };
+      const keyed: Record<string, unknown> = {};
+      for (const col of pkColumns) {
+        const callerKey = resolved[col];
+        keyed[col] = effectiveData[callerKey];
+        delete effectiveData[callerKey];
+      }
+      if (Object.keys(effectiveData).length === 0) {
+        throw new Error(
+          `update was given only the primary key [${pkColumns.join(", ")}] and no ` +
+            `columns to set (table=${table})`,
+        );
+      }
+      effectiveFilter = keyed;
+    }
+
     const adapter = this.getNextAdapter();
     const result = (adapter as any).updateAsync
-      ? await (adapter as any).updateAsync(table, data, filter ?? {}, params)
-      : adapter.update(table, data, filter ?? {}, params);
+      ? await (adapter as any).updateAsync(table, effectiveData, effectiveFilter, params)
+      : adapter.update(table, effectiveData, effectiveFilter, params);
     if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
-    return result;
+    return Database.assertWrote(result, "update", table);
   }
 
-  /** Delete rows from a table matching filter. */
-  async delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult> {
+  /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
+  async delete(table: string, filter?: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseWriteResult> {
+    const effectiveFilter = filter ?? {};
+    // A BLANK string counts as no filter. The old guard skipped the emptiness
+    // test for anything typed string, so `delete(t, "")` fell through to the
+    // adapter, which renders an empty WHERE as `DELETE FROM "t"` — a silent
+    // whole-table delete through the very method that exists to make that
+    // impossible. truncate() is the explicit spelling.
+    const filterIsEmpty = Array.isArray(effectiveFilter)
+      ? effectiveFilter.length === 0
+      : typeof effectiveFilter === "string"
+        ? effectiveFilter.trim() === ""
+        : Object.keys(effectiveFilter).length === 0;
+    if (filterIsEmpty) {
+      throw new Error(
+        `delete requires a filter (table=${table}). To remove every row use truncate(${table}).`,
+      );
+    }
+
     const adapter = this.getNextAdapter();
     const result = (adapter as any).deleteAsync
-      ? await (adapter as any).deleteAsync(table, filter ?? {}, params)
-      : adapter.delete(table, filter ?? {}, params);
+      ? await (adapter as any).deleteAsync(table, effectiveFilter, params)
+      : adapter.delete(table, effectiveFilter, params);
     if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
-    return result;
+    return Database.assertWrote(result, "delete", table);
+  }
+
+  /** Remove every row. The explicit spelling of a whole-table delete. */
+  async truncate(table: string): Promise<DatabaseWriteResult> {
+    const adapter = this.getNextAdapter();
+    // The adapters' delete() already accepts a raw string WHERE clause.
+    const result = (adapter as any).deleteAsync
+      ? await (adapter as any).deleteAsync(table, "1 = 1", [])
+      : adapter.delete(table, "1 = 1" as any, []);
+    if (this.autoCommit && !this.inExplicitTransaction()) {
+      try { await adapterCommit(adapter); } catch { /* no active transaction */ }
+    }
+    return Database.assertWrote(result, "truncate", table);
   }
 
   /** Close all database connections (pool or single). */
@@ -975,9 +1074,35 @@ export class Database {
     // (Database.execute_many delegating to adapter.execute_many's owns_txn guard).
     const owns = !this.inExplicitTransaction();
     if (owns) await adapterStartTransaction(adapter);
+
+    // ONE round-trip per CHUNK instead of one per ROW. Looping execute() here
+    // pays a full network round-trip for every row: 500 rows took 9848ms on
+    // PostgreSQL against 15.8ms as a single multi-row VALUES (625x), MySQL 216x,
+    // MSSQL 121x. buildBatchInserts returns an empty array for anything it
+    // cannot collapse safely — RETURNING, upserts, non-INSERT statements, ragged
+    // rows, Firebird — and the row-at-a-time loop then runs unchanged.
+    const batched = SQLTranslator.buildBatchInserts(sql, paramSets, this.dbType ?? "");
+
     try {
-      for (const params of paramSets) {
-        results.push(await adapterExecute(adapter, sql, params));
+      if (batched.length > 0) {
+        let row = 0;
+        for (const [chunkSql, chunkParams] of batched) {
+          const result = await adapterExecute(adapter, chunkSql, chunkParams);
+          // executeMany's contract is ONE RESULT PER ROW, and callers index into
+          // it. Collapsing rows into chunks must not shorten the array, so each
+          // row reports the result of the statement that actually wrote it.
+          // Node is the only one of the four returning per-row results — Python,
+          // PHP and Ruby return a count or a single DatabaseResult — so this is
+          // the one place the collapse could have been observable.
+          const rowsInChunk = chunkParams.length / (paramSets[0]?.length || 1);
+          for (let i = 0; i < rowsInChunk && row < paramSets.length; i++, row++) {
+            results.push(result);
+          }
+        }
+      } else {
+        for (const params of paramSets) {
+          results.push(await adapterExecute(adapter, sql, params));
+        }
       }
       if (owns) await adapterCommit(adapter);
     } catch (e) {
@@ -1316,21 +1441,31 @@ export class Database {
  * connected; SQLite connects lazily.
  */
 export async function createAdapterFromUrl(url: string, username?: string, password?: string): Promise<DatabaseAdapter> {
+  const adapter = await buildAdapterFromUrl(url, username, password);
+  // Tag the adapter with WHICH DATABASE it is connected to. The query cache
+  // folds this into every key, so two databases sharing one cache backend
+  // cannot serve each other's rows. Set here because this is the single funnel
+  // where a URL becomes an adapter.
+  adapter.cacheIdentity = QueryCache.cacheIdentity(url);
+  return adapter;
+}
+
+async function buildAdapterFromUrl(url: string, username?: string, password?: string): Promise<DatabaseAdapter> {
   const parsed = parseDatabaseUrl(url, username, password);
 
-  switch (parsed.type) {
+  switch (parsed.engine) {
     case "sqlite": {
       const { SQLiteAdapter } = await import("./adapters/sqlite.js");
-      return new SQLiteAdapter(parsed.path ?? "./data/tina4.db");
+      return new SQLiteAdapter(parsed.database || "./data/tina4.db");
     }
     case "postgres": {
       const { PostgresAdapter } = await import("./adapters/postgres.js");
       const adapter = new PostgresAdapter({
-        host: parsed.host,
-        port: parsed.port,
-        user: parsed.user,
-        password: parsed.password,
-        database: parsed.database,
+        host: parsed.host ?? undefined,
+        port: parsed.port ?? undefined,
+        user: parsed.username ?? undefined,
+        password: parsed.password ?? undefined,
+        database: parsed.database || undefined,
       });
       await adapter.connect();
       return adapter;
@@ -1338,11 +1473,11 @@ export async function createAdapterFromUrl(url: string, username?: string, passw
     case "mysql": {
       const { MysqlAdapter } = await import("./adapters/mysql.js");
       const adapter = new MysqlAdapter({
-        host: parsed.host,
-        port: parsed.port,
-        user: parsed.user,
-        password: parsed.password,
-        database: parsed.database,
+        host: parsed.host ?? undefined,
+        port: parsed.port ?? undefined,
+        user: parsed.username ?? undefined,
+        password: parsed.password ?? undefined,
+        database: parsed.database || undefined,
       });
       await adapter.connect();
       return adapter;
@@ -1350,11 +1485,11 @@ export async function createAdapterFromUrl(url: string, username?: string, passw
     case "mssql": {
       const { MssqlAdapter } = await import("./adapters/mssql.js");
       const adapter = new MssqlAdapter({
-        host: parsed.host,
-        port: parsed.port,
-        user: parsed.user,
-        password: parsed.password,
-        database: parsed.database,
+        host: parsed.host ?? undefined,
+        port: parsed.port ?? undefined,
+        user: parsed.username ?? undefined,
+        password: parsed.password ?? undefined,
+        database: parsed.database || undefined,
       });
       await adapter.connect();
       return adapter;
@@ -1362,11 +1497,11 @@ export async function createAdapterFromUrl(url: string, username?: string, passw
     case "firebird": {
       const { FirebirdAdapter } = await import("./adapters/firebird.js");
       const adapter = new FirebirdAdapter({
-        host: parsed.host,
-        port: parsed.port,
-        user: parsed.user,
-        password: parsed.password,
-        database: parsed.database,
+        host: parsed.host ?? undefined,
+        port: parsed.port ?? undefined,
+        user: parsed.username ?? undefined,
+        password: parsed.password ?? undefined,
+        database: parsed.database || undefined,
       });
       await adapter.connect();
       return adapter;
@@ -1477,7 +1612,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     const parsed = parseDatabaseUrl(url, resolvedUser, resolvedPassword);
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
     const db = new Database(setAdapter(adapter));
-    db.setDbType(parsed.type);
+    db.setDbType(parsed.engine);
     return exposeDb(db);
   }
 
@@ -1504,6 +1639,11 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   // default and a `{ type: "postgres" }` connection takes the SQLite getNextId
   // branch and crashes on the missing tina4_sequences table (#255).
   const finished = (adapter: DatabaseAdapter): Database => {
+    // Same identity tag as the URL path above - a config-object connection is
+    // just as capable of sharing a cache backend with another database.
+    adapter.cacheIdentity = QueryCache.cacheIdentity(
+      `${type}://${config?.host ?? ""}:${config?.port ?? ""}/${config?.database ?? config?.path ?? ""}`,
+    );
     const db = new Database(setAdapter(adapter));
     db.setDbType(type);
     return exposeDb(db);