tina4-nodejs 3.13.94 → 3.13.96

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(
@@ -112,6 +113,67 @@ export async function adapterCreateTable(
   else adapter.createTable(name, columns);
 }
 
+/**
+ * The true row count for `sql`, ignoring the pagination the caller applied.
+ *
+ * `count` on a DatabaseResult is the TRUE TOTAL for the filter, not the number
+ * of rows the 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 `toPaginate()` envelope built on it under-reported (ADR-0043).
+ * 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.
+ *
+ * This is the single source of truth for that probe. Both read paths that build a
+ * DatabaseResult — `Database.fetch()` and `QueryBuilder.get()` — call it, so the
+ * two can never drift (QueryBuilder.get used to leave `count` at rows-returned,
+ * diverging from db.fetch AND from Python/Ruby, whose get() routes through fetch).
+ *
+ * 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 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.
+ */
+export async function probeTotal(
+  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;
+  }
+}
+
 /**
  * Extract the engine-assigned auto-increment id from an `execute()` result.
  *
@@ -131,6 +193,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 +361,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);
 }
 
 /**
@@ -574,7 +500,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);
     }
 
@@ -584,7 +510,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);
   }
 
@@ -675,7 +601,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.
@@ -686,7 +636,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 probeTotal(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);
@@ -741,7 +692,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[];
   }
 
   /**
@@ -835,13 +789,52 @@ export class Database {
    * 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>, params?: unknown[]): Promise<DatabaseWriteResult> {
-    let effectiveFilter = filter ?? {};
+  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;
 
-    if (Object.keys(effectiveFilter).length === 0) {
+    // 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);
-      const missing = pkColumns.filter((c) => !(c in data));
+      // 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 ` +
@@ -856,8 +849,9 @@ export class Database {
       effectiveData = { ...data };
       const keyed: Record<string, unknown> = {};
       for (const col of pkColumns) {
-        keyed[col] = effectiveData[col];
-        delete effectiveData[col];
+        const callerKey = resolved[col];
+        keyed[col] = effectiveData[callerKey];
+        delete effectiveData[callerKey];
       }
       if (Object.keys(effectiveData).length === 0) {
         throw new Error(
@@ -879,10 +873,19 @@ export class Database {
   }
 
   /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
-  async delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult> {
+  async delete(table: string, filter?: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseWriteResult> {
     const effectiveFilter = filter ?? {};
-    if (!Array.isArray(effectiveFilter) && typeof effectiveFilter !== "string"
-        && Object.keys(effectiveFilter).length === 0) {
+    // 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}).`,
       );
@@ -1075,9 +1078,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) {
@@ -1416,21 +1445,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;
@@ -1438,11 +1477,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;
@@ -1450,11 +1489,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;
@@ -1462,11 +1501,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;
@@ -1577,7 +1616,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);
   }
 
@@ -1604,6 +1643,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);