tina4-nodejs 3.13.92 → 3.13.95

package/packages/orm/src/adapters/sqlDialect.ts

@@ -0,0 +1,120 @@
+/**
+ * One CRUD SQL builder for every engine, instead of one per adapter.
+ *
+ * Feature 3's last open item, the 4.3x LOC finding: `insert`/`update`/`delete`
+ * built their SQL independently in all seven adapters. Building
+ * `INSERT INTO x (a, b) VALUES (?, ?)` is not engine-specific work - Ruby has
+ * always done it once - and the seven copies differed in exactly two ways:
+ *
+ *   IDENTIFIER QUOTING   "col"  |  `col`  |  [col]  |  Firebird's fbQuote
+ *   PARAMETER MARKER     ?      |  $1     |  @p1
+ *
+ * Both are captured in a `Dialect` below, so the builders are shared and each
+ * adapter declares only what genuinely differs about its engine.
+ *
+ * These functions build STRINGS and nothing else. Execution and result
+ * extraction stay in the adapters on purpose: those really are per-driver
+ * (`client.query` vs `lastInsertRowid` vs a Firebird transaction handle), and
+ * folding them in here would trade a real duplication for a fake abstraction.
+ *
+ * MongoDB has no entry: it does not build SQL at all.
+ */
+
+/** How one engine spells identifiers and parameter markers. */
+export interface Dialect {
+  /** Quote a table or column name for this engine. */
+  quote(name: string): string;
+  /**
+   * The parameter marker for the 1-based position `index`. Engines with
+   * positional markers ($1, @p1) use the index; the rest ignore it.
+   */
+  marker(index: number): string;
+}
+
+const doubleQuote = (name: string): string => `"${name}"`;
+const questionMark = (): string => "?";
+
+/** SQLite, and ODBC which follows the SQL standard spelling. */
+export const ANSI_DIALECT: Dialect = { quote: doubleQuote, marker: questionMark };
+
+/** PostgreSQL: standard quoting, positional $N markers. */
+export const POSTGRES_DIALECT: Dialect = {
+  quote: doubleQuote,
+  marker: (index) => `$${index}`,
+};
+
+/** MySQL: backtick quoting. */
+export const MYSQL_DIALECT: Dialect = {
+  quote: (name) => `\`${name}\``,
+  marker: questionMark,
+};
+
+/** MSSQL: bracket quoting, named @pN markers. */
+export const MSSQL_DIALECT: Dialect = {
+  quote: (name) => `[${name}]`,
+  marker: (index) => `@p${index}`,
+};
+
+/**
+ * Firebird quotes only when it has to: an unquoted identifier is folded to
+ * UPPER CASE, so quoting a lower-case name would make it unfindable. The
+ * adapter owns that rule and passes its own quoter in.
+ */
+export function firebirdDialect(fbQuote: (name: string) => string): Dialect {
+  return { quote: fbQuote, marker: questionMark };
+}
+
+/**
+ * `INSERT INTO <table> (<cols>) VALUES (<markers>)`.
+ *
+ * @param suffix Appended verbatim - PostgreSQL passes " RETURNING *" and MSSQL
+ *               its SCOPE_IDENTITY() probe, the genuinely engine-specific parts.
+ * @param startAt Position of the FIRST marker. PostgreSQL numbers its `$N` from
+ *                1; MSSQL names its `@pN` from 0 and BINDS by that same name, so
+ *                shifting it would produce SQL whose parameters do not exist.
+ *                Engines using `?` ignore this.
+ */
+export function buildInsert(
+  dialect: Dialect,
+  table: string,
+  keys: string[],
+  suffix = "",
+  startAt = 1,
+): string {
+  const columns = keys.map((k) => dialect.quote(k)).join(", ");
+  const placeholders = keys.map((_, i) => dialect.marker(startAt + i)).join(", ");
+  return `INSERT INTO ${dialect.quote(table)} (${columns}) VALUES (${placeholders})${suffix}`;
+}
+
+/**
+ * The `SET a = ?, b = ?` fragment of an UPDATE.
+ *
+ * @param startAt 1-based position of the FIRST marker. An UPDATE's WHERE
+ *                clause continues the numbering after the SET values, so a
+ *                positional engine ($N, @pN) must not restart at 1.
+ */
+export function buildSetClause(
+  dialect: Dialect,
+  keys: string[],
+  startAt = 1,
+): string {
+  return keys
+    .map((k, i) => `${dialect.quote(k)} = ${dialect.marker(startAt + i)}`)
+    .join(", ");
+}
+
+/**
+ * The `a = ? AND b = ?` fragment for an object filter.
+ *
+ * @param startAt 1-based position of the first marker, for the same reason as
+ *                buildSetClause.
+ */
+export function buildWhereClause(
+  dialect: Dialect,
+  keys: string[],
+  startAt = 1,
+): string {
+  return keys
+    .map((k, i) => `${dialect.quote(k)} = ${dialect.marker(startAt + i)}`)
+    .join(" AND ");
+}

package/packages/orm/src/adapters/sqlite.ts

@@ -1,4 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
+import { ANSI_DIALECT, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
 import { mkdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
@@ -99,6 +100,18 @@ export class SQLiteAdapter implements DatabaseAdapter {
   private db: DatabaseSync;
   private _lastInsertId: number | bigint | null = null;
 
+  /**
+   * TINA4_DATABASE_CONNECT_TIMEOUT DOES NOT APPLY HERE, deliberately.
+   *
+   * There is no connect() to bound: `node:sqlite` opens the file in this
+   * SYNCHRONOUS constructor, and a synchronous call cannot be interrupted by a
+   * timer on the same thread - the event loop only gets to run the timer after
+   * `new DatabaseSync()` has already returned. There is also no host and no port
+   * to name in a timeout error. The one case that could still block is a local
+   * file on a wedged network mount, which is a kernel-level stall no JS bound
+   * can reach. Stated here so the exclusion reads as a decision rather than an
+   * adapter somebody forgot.
+   */
   constructor(dbPath: string) {
     const resolved = resolveSqlitePath(dbPath);
     this.db = new DatabaseSync(resolved);
@@ -145,17 +158,13 @@ export class SQLiteAdapter implements DatabaseAdapter {
   }
 
   fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
-    let effectiveSql = sql;
-    if (limit !== undefined) {
-      // Skip appending LIMIT when the SQL already contains one (dedup)
-      const sqlBeforeComment = sql.toUpperCase().split("--")[0];
-      if (!sqlBeforeComment.includes("LIMIT")) {
-        effectiveSql += ` LIMIT ${limit}`;
-        if (skip !== undefined && skip > 0) {
-          effectiveSql += ` OFFSET ${skip}`;
-        }
-      }
-    }
+    // SQLTranslator.appendLimit owns BOTH halves of this decision: it scrubs
+    // literals and comments before asking "does the caller already have a
+    // LIMIT?", and it appends on a new line so the clause can never land inside
+    // a trailing `--` comment. The old inline version did neither, so
+    // `WHERE label != 'LIMIT'` and a trailing `-- LIMIT 5` each returned the
+    // WHOLE TABLE instead of the 100-row cap.
+    const effectiveSql = SQLTranslator.appendLimit(sql, limit, skip);
     return this.query<T>(effectiveSql, params);
   }
 
@@ -169,16 +178,14 @@ export class SQLiteAdapter implements DatabaseAdapter {
     if (Array.isArray(data)) {
       if (data.length === 0) return { success: true, affectedRows: 0 };
       const keys = Object.keys(data[0]);
-      const placeholders = keys.map(() => "?").join(", ");
-      const sql = `INSERT INTO "${table}" ("${keys.join('", "')}") VALUES (${placeholders})`;
+      const sql = buildInsert(ANSI_DIALECT, table, keys);
       const paramsList = data.map((row) => keys.map((k) => row[k]));
       const result = this.executeMany(sql, paramsList);
       return { success: true, affectedRows: result.totalAffected, lastId: result.lastId };
     }
 
     const keys = Object.keys(data);
-    const placeholders = keys.map(() => "?").join(", ");
-    const sql = `INSERT INTO "${table}" ("${keys.join('", "')}") VALUES (${placeholders})`;
+    const sql = buildInsert(ANSI_DIALECT, table, keys);
     const values = Object.values(data);
 
     try {
@@ -190,10 +197,30 @@ export class SQLiteAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
-    const setClauses = Object.keys(data).map((k) => `"${k}" = ?`).join(", ");
-    const whereClauses = Object.keys(filter).map((k) => `"${k}" = ?`).join(" AND ");
-    const sql = `UPDATE "${table}" SET ${setClauses} WHERE ${whereClauses}`;
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult {
+    const setClauses = buildSetClause(ANSI_DIALECT, Object.keys(data));
+
+    // A raw WHERE fragment + params is half the write_path contract's filter
+    // form ("a string filter with params works the same as a hash filter").
+    // Without this branch Object.keys("id = ?") yields the STRING INDICES
+    // ["0","1",...], producing `WHERE "0" = ? AND "1" = ?` and SQLite reports
+    // `no such column: "0"`. delete() below already carried this branch and
+    // update() did not — the same gap 3.13.94 closed in the postgres/mysql/
+    // mssql/firebird adapters, still open here on the DEFAULT engine.
+    if (typeof filter === "string") {
+      const where = filter ? ` WHERE ${filter}` : "";
+      const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses}${where}`;
+      const values = [...Object.values(data), ...(params ?? [])];
+      try {
+        const result = this.db.prepare(sql).run(...toSqlParams(values));
+        return { success: true, affectedRows: Number(result.changes) };
+      } catch (e) {
+        return { success: false, affectedRows: 0, error: (e as Error).message };
+      }
+    }
+
+    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
+    const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses} WHERE ${whereClauses}`;
     const values = [...Object.values(data), ...Object.values(filter)];
 
     try {
@@ -224,8 +251,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
       }
     }
 
-    const whereClauses = Object.keys(filter).map((k) => `"${k}" = ?`).join(" AND ");
-    const sql = `DELETE FROM "${table}" WHERE ${whereClauses}`;
+    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
+    const sql = `DELETE FROM ${ANSI_DIALECT.quote(table)} WHERE ${whereClauses}`;
     const values = Object.values(filter);
 
     try {
@@ -260,14 +287,14 @@ export class SQLiteAdapter implements DatabaseAdapter {
     this._inTransaction = false;
   }
 
-  tables(): string[] {
+  getTables(): string[] {
     const rows = this.query<{ name: string }>(
       "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
     );
     return rows.map((r) => r.name);
   }
 
-  columns(table: string): ColumnInfo[] {
+  getColumns(table: string): ColumnInfo[] {
     // v3.13.14 (#48): a SQLite "schema" is an ATTACH alias ("extra.widget").
     // PRAGMA accepts a schema prefix when both parts are plain identifiers.
     const [schema, tbl] = SQLTranslator.splitSchema(table);
@@ -279,7 +306,10 @@ export class SQLiteAdapter implements DatabaseAdapter {
       name: string; type: string; notnull: number; dflt_value: unknown; pk: number;
     }>;
     return rows.map((r) => ({
-      name: r.name, type: r.type, nullable: r.notnull === 0, default: r.dflt_value, primaryKey: r.pk === 1,
+      // PRAGMA table_info reports `pk` as the 1-BASED POSITION within the primary
+      // key, not a boolean: a composite key gives pk=1, pk=2, ... Testing `=== 1`
+      // reported only the first column of a composite key.
+      name: r.name, type: r.type, nullable: r.notnull === 0, default: r.dflt_value, primaryKey: Number(r.pk) > 0,
     }));
   }
 
@@ -360,10 +390,16 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   createTable(name: string, columns: Record<string, FieldDefinition>): void {
     const colDefs: string[] = [];
+    // A COMPOSITE key is declared ONCE, at table level (below). An inline
+    // PRIMARY KEY per column is invalid DDL - SQLite rejects it outright with
+    // "table X has more than one primary key", so a composite-key model could
+    // not create its own table at all.
+    const pkCols = Object.entries(columns).filter(([, d]) => d.primaryKey).map(([c]) => c);
+    const composite = pkCols.length > 1;
     for (const [colName, def] of Object.entries(columns)) {
       const sqlType = fieldTypeToSQLite(def.type);
       const parts = [`"${colName}" ${sqlType}`];
-      if (def.primaryKey) parts.push("PRIMARY KEY");
+      if (def.primaryKey && !composite) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("AUTOINCREMENT");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
       // A json column carries no DDL DEFAULT (parity with the Python master): an
@@ -372,6 +408,9 @@ export class SQLiteAdapter implements DatabaseAdapter {
       if (def.type !== "json" && def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
       colDefs.push(parts.join(" "));
     }
+    if (composite) {
+      colDefs.push(`PRIMARY KEY (${pkCols.map((c) => `"${c}"`).join(", ")})`);
+    }
     this.db.exec(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs.join(", ")})`);
   }
 

package/packages/orm/src/baseModel.ts

@@ -3,11 +3,12 @@ import {
   adapterQuery, adapterFetch, adapterExecute, adapterFetchOne,
   adapterStartTransaction, adapterCommit, adapterRollback,
   adapterTableExists, adapterCreateTable, extractLastInsertId,
+  DEFAULT_ROW_CAP,
 } from "./database.js";
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
-import { QueryCache } from "./sqlTranslator.js";
+import { QueryCache, SQLTranslator } from "./sqlTranslator.js";
 import { Log } from "../../core/src/index.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 
@@ -317,15 +318,17 @@ export class BaseModel {
       const url = process.env.TINA4_DATABASE_URL;
       if (url) {
         const parsed = parseDatabaseUrl(url);
-        if (parsed.type === "sqlite") {
+        if (parsed.engine === "sqlite") {
           // SQLite adapter is synchronous — create it inline and register as default
-          const dbPath = parsed.path ?? "./data/tina4.db";
-          const adapter = new SQLiteAdapter(dbPath);
+          const dbPath = parsed.database || "./data/tina4.db";
+          // Typed as the INTERFACE so the optional identity tag is assignable.
+          const adapter: DatabaseAdapter = new SQLiteAdapter(dbPath);
+          adapter.cacheIdentity = QueryCache.cacheIdentity(url);
           setAdapter(adapter);
           return adapter;
         }
         throw new Error(
-          `TINA4_DATABASE_URL is set to a non-SQLite engine ("${parsed.type}"). ` +
+          `TINA4_DATABASE_URL is set to a non-SQLite engine ("${parsed.engine}"). ` +
           `Call await initDatabase() at startup before using ORM models.`,
         );
       }
@@ -342,6 +345,34 @@ export class BaseModel {
     return Object.entries(this.fields).find(([, def]) => def.primaryKey)?.[0] ?? "id";
   }
 
+  /**
+   * EVERY primary-key field name, in declaration order.
+   *
+   * A key may span several columns. `getPkField()` returns only the FIRST and
+   * is kept for the auto-increment paths, which are single-column by
+   * definition. Anything that ADDRESSES a row must use this: keying on one
+   * column of a composite key matches every row sharing that value, which is
+   * the data-loss shape feature 4 removed from the raw write path below.
+   */
+  protected static getPkFields(): string[] {
+    const keys = Object.entries(this.fields)
+      .filter(([, def]) => def.primaryKey)
+      .map(([name]) => name);
+    return keys.length > 0 ? keys : ["id"];
+  }
+
+  /** A WHERE naming EVERY primary-key column, and its bound params. */
+  protected pkWhere(): { sql: string; params: unknown[] } {
+    const ModelClass = this.constructor as typeof BaseModel;
+    const clauses: string[] = [];
+    const params: unknown[] = [];
+    for (const name of ModelClass.getPkFields()) {
+      clauses.push(`${ModelClass.getDbColumn(name)} = ?`);
+      params.push((this as Record<string, unknown>)[name]);
+    }
+    return { sql: clauses.join(" AND "), params };
+  }
+
   /**
    * Get the primary key database column name (applies fieldMapping).
    */
@@ -538,16 +569,37 @@ export class BaseModel {
   }
 
   /**
-   * Find all records, optionally with a where clause.
-   * Alias: all()
-   * @param where Optional WHERE clause.
-   * @param params Optional query parameters.
-   * @param include Optional array of relationship names to eager-load.
+   * Find all records.
+   *
+   * BREAKING (3.13.95, parity): the signature is now
+   * `all(limit?, offset?, include?, orderBy?)`. It NO LONGER accepts leading
+   * `where`/`params`.
+   *
+   * Node was the sole outlier of the four. The master and the other two never
+   * had a filter on `all()`:
+   *   Python  all(limit=100, offset=0, include=None, order_by=None)
+   *   PHP     all(int $limit = 100, int $offset = 0, ?array $include, ?string $orderBy)
+   *   Ruby    all(limit: 100, offset: nil, order_by: nil, include: nil)
+   * Node's extra leading parameters shifted every argument, so the same
+   * positional call meant different things in different languages -- which is
+   * precisely what the parity mandate exists to prevent.
+   *
+   * MIGRATION: a filtered read moves to `where()`, which already exists and
+   * takes the conditions first:
+   *   before: User.all("age > ?", [28])
+   *   after:  User.where("age > ?", [28])
+   * TypeScript callers get a compile error (string is not assignable to number),
+   * so the break is loud rather than silent.
+   *
+   * @param limit   Max records (default 100, the shared cross-framework cap).
+   * @param offset  Records to skip (default 0).
+   * @param include Relationship names to eager-load.
+   * @param orderBy ORDER BY clause (e.g. "name ASC").
    */
   static async all<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
-    where?: string,
-    params?: unknown[],
+    limit: number = DEFAULT_ROW_CAP,
+    offset: number = 0,
     include?: string[],
     orderBy?: string,
   ): Promise<T[]> {
@@ -561,15 +613,16 @@ export class BaseModel {
     if (ModelClass.tableFilter) {
       conditions.push(ModelClass.tableFilter);
     }
-    if (where) {
-      conditions.push(where);
-    }
 
     const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
     const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
-    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
+    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`
+      + ` LIMIT ${limit} OFFSET ${offset}`;
 
-    const rows = await adapterQuery(db, sql, params);
+    // No bind parameters: the only conditions left are the framework's own
+    // softDelete / tableFilter literals. A caller-supplied filter belongs on
+    // where(), which binds its params properly.
+    const rows = await adapterQuery(db, sql, []);
     const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
     if (include) {
       await ModelClass._eagerLoad(instances, include);
@@ -583,7 +636,7 @@ export class BaseModel {
    *
    * @param conditions WHERE clause (e.g. "age > ? AND active = ?")
    * @param params     Bind parameters
-   * @param limit      Max records (default 20)
+   * @param limit      Max records (default 100)
    * @param offset     Skip records (default 0)
    * @param include    Relationship names to eager-load
    * @param orderBy    ORDER BY clause (e.g. "name ASC")
@@ -592,7 +645,7 @@ export class BaseModel {
     this: new (data?: Record<string, unknown>) => T,
     conditions: string,
     params?: unknown[],
-    limit: number = 20,
+    limit: number = DEFAULT_ROW_CAP,
     offset: number = 0,
     include?: string[],
     orderBy?: string,
@@ -676,7 +729,23 @@ export class BaseModel {
         isUpdate = true;
       } else {
         try {
-          isUpdate = await ModelClass.exists(pkValue);
+          // This asked exists(pkValue), which tests only the FIRST key column.
+          // On a composite key that is true for any row sharing that column, so
+          // inserting a genuinely NEW row was decided to be an UPDATE and
+          // silently OVERWROTE a different row: saving (acme, a2) rewrote
+          // (acme, a1). The check has to name the whole key, like the write
+          // that follows it.
+          const probe = this.pkWhere();
+          if (ModelClass.getPkFields().length > 1 && probe.sql) {
+            const found = await db.fetch(
+              `SELECT 1 AS present FROM ${ModelClass.tableName} WHERE ${probe.sql}`,
+              probe.params,
+              1,
+            );
+            isUpdate = (found as unknown as { length: number }).length > 0;
+          } else {
+            isUpdate = await ModelClass.exists(pkValue);
+          }
         } catch {
           // If we can't tell (e.g. table doesn't exist yet), fall back
           // to INSERT so the user sees the real driver error rather
@@ -689,16 +758,22 @@ export class BaseModel {
     await adapterStartTransaction(db);
     try {
       if (isUpdate) {
-        // Update
+        // Update — keyed on the WHOLE primary key (see pkWhere).
         const updateFields = Object.entries(ModelClass.fields).filter(
           ([name, def]) => !def.primaryKey && this[name] !== undefined,
         );
         if (updateFields.length === 0) { await adapterCommit(db); return this; }
 
         const setClause = updateFields.map(([k]) => `"${ModelClass.getDbColumn(k)}" = ?`).join(", ");
-        const values = [...updateFields.map(([k, def]) => toDbFieldValue(def, this[k])), pkValue];
-
-        await adapterExecute(db, `UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE "${pkCol}" = ?`, values);
+        // The key params come from pkWhere() below; appending pkValue here too
+        // would bind the first key column twice and shift every placeholder.
+        const values = [...updateFields.map(([k, def]) => toDbFieldValue(def, this[k]))];
+
+        // Keyed on the WHOLE primary key: one column of a composite key matches
+        // every row sharing that value.
+        const uw = this.pkWhere();
+        values.push(...uw.params);
+        await adapterExecute(db, `UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE ${uw.sql}`, values);
       } else {
         // Insert
         //
@@ -854,14 +929,14 @@ export class BaseModel {
     try {
       if (ModelClass.softDelete) {
         await adapterExecute(db,
-          `UPDATE "${ModelClass.tableName}" SET is_deleted = 1 WHERE "${pkCol}" = ?`,
-          [pkValue],
+          `UPDATE "${ModelClass.tableName}" SET is_deleted = 1 WHERE ${this.pkWhere().sql}`,
+          this.pkWhere().params,
         );
         this.is_deleted = 1;
       } else {
         await adapterExecute(db,
-          `DELETE FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`,
-          [pkValue],
+          `DELETE FROM "${ModelClass.tableName}" WHERE ${this.pkWhere().sql}`,
+          this.pkWhere().params,
         );
       }
       await adapterCommit(db);
@@ -1047,7 +1122,10 @@ export class BaseModel {
       const dbCol = this.getDbColumn(fieldName);
       const sqlType = typeMap[def.type] || "TEXT";
       const parts = [`"${dbCol}" ${sqlType}`];
-      if (def.primaryKey) parts.push("PRIMARY KEY");
+      // A COMPOSITE key is declared ONCE, at table level (below). An inline
+      // PRIMARY KEY per column is invalid DDL - SQLite, PostgreSQL and MySQL
+      // all reject two of them in one table.
+      if (def.primaryKey && this.getPkFields().length === 1) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("AUTOINCREMENT");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
       // A callable default (e.g. `default: () => new Date()`) is resolved per-row
@@ -1061,6 +1139,15 @@ export class BaseModel {
       colDefs.push(parts.join(" "));
     }
 
+    // A COMPOSITE key is declared ONCE, at table level; the per-column inline
+    // form above is suppressed for it, because two inline primary keys is
+    // invalid DDL on every engine.
+    const pkFields = this.getPkFields();
+    if (pkFields.length > 1) {
+      const pkCols = pkFields.map((f) => this.getDbColumn(f));
+      colDefs.push(`PRIMARY KEY (${pkCols.join(", ")})`);
+    }
+
     const sql = `CREATE TABLE IF NOT EXISTS "${this.tableName}" (${colDefs.join(", ")})`;
     await adapterStartTransaction(db);
     try {
@@ -1099,7 +1186,7 @@ export class BaseModel {
    * @param sql     SQL query string.
    * @param params  Bind parameters.
    * @param ttl     Cache TTL in seconds (default 60).
-   * @param limit   Max records to return (default 20).
+   * @param limit   Max records to return (default 100).
    * @param offset  Records to skip (default 0).
    * @param include Relationship names to eager-load on cache miss.
    */
@@ -1108,7 +1195,7 @@ export class BaseModel {
     sql: string,
     params?: unknown[],
     ttl = 60,
-    limit = 20,
+    limit = DEFAULT_ROW_CAP,
     offset = 0,
     include?: string[],
   ): Promise<T[]> {
@@ -1117,7 +1204,7 @@ export class BaseModel {
       ModelClass._queryCache = new QueryCache({ defaultTtl: ttl, maxSize: 500 });
     }
     const cacheKey = `${ModelClass.tableName}:${sql}:${limit}:${offset}`;
-    const key = QueryCache.queryKey(cacheKey, params ?? []);
+    const key = QueryCache.queryKey(cacheKey, params ?? [], ModelClass.getDb().cacheIdentity ?? "");
     const hit = ModelClass._queryCache.get(key) as T[] | undefined;
     if (hit !== undefined) return hit;
 
@@ -1149,10 +1236,18 @@ export class BaseModel {
     this: new (data?: Record<string, unknown>) => T,
     sql: string,
     params?: unknown[],
+    limit: number = DEFAULT_ROW_CAP,
+    offset: number = 0,
   ): Promise<T[]> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
-    const rows = await adapterQuery(db, sql, params);
+    // Skip appending when the caller's SQL already carries its own LIMIT --
+    // a second one is a syntax error on every engine. SQLTranslator.appendLimit
+    // scrubs literals/comments first (a substring search here used to drop the
+    // row cap on `WHERE label != 'LIMIT'`) and appends on a new line so the
+    // clause is never swallowed by a trailing `--` comment.
+    const paged = SQLTranslator.appendLimit(sql, limit, offset);
+    const rows = await adapterQuery(db, paged, params);
     return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
   }
 
@@ -1188,8 +1283,8 @@ export class BaseModel {
     await adapterStartTransaction(db);
     try {
       await adapterExecute(db,
-        `DELETE FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`,
-        [pkValue],
+        `DELETE FROM "${ModelClass.tableName}" WHERE ${this.pkWhere().sql}`,
+        this.pkWhere().params,
       );
       await adapterCommit(db);
     } catch (e) {
@@ -1220,8 +1315,8 @@ export class BaseModel {
     await adapterStartTransaction(db);
     try {
       await adapterExecute(db,
-        `UPDATE "${ModelClass.tableName}" SET is_deleted = 0 WHERE "${pkCol}" = ?`,
-        [pkValue],
+        `UPDATE "${ModelClass.tableName}" SET is_deleted = 0 WHERE ${this.pkWhere().sql}`,
+        this.pkWhere().params,
       );
       await adapterCommit(db);
     } catch (e) {
@@ -1239,8 +1334,8 @@ export class BaseModel {
     this: new (data?: Record<string, unknown>) => T,
     conditions?: string,
     params?: unknown[],
-    limit?: number,
-    offset?: number,
+    limit: number = DEFAULT_ROW_CAP,
+    offset: number = 0,
   ): Promise<T[]> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -1309,7 +1404,7 @@ export class BaseModel {
     params?: unknown[],
   ): void {
     const ModelClass = this as unknown as typeof BaseModel;
-    (ModelClass as any)[name] = (limit: number = 20, offset: number = 0) => {
+    (ModelClass as any)[name] = (limit: number = DEFAULT_ROW_CAP, offset: number = 0) => {
       return ModelClass.where.call(ModelClass as any, filterSql, params, limit, offset);
     };
   }