tina4-nodejs 3.13.42 → 3.13.44

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

@@ -68,7 +68,10 @@ export interface PostgresConfig {
 
 export class PostgresAdapter implements DatabaseAdapter {
   private client: InstanceType<typeof import("pg").Client> | null = null;
-  private _lastInsertId: number | bigint | null = null;
+  // string is included for non-integer primary keys: a UUID PK (the common
+  // `id uuid PRIMARY KEY DEFAULT gen_random_uuid()` shape) returns its id as a
+  // 36-char string via RETURNING, not a SERIAL integer (#256).
+  private _lastInsertId: number | bigint | string | null = null;
 
   constructor(private config: PostgresConfig | string) {}
 
@@ -115,16 +118,20 @@ export class PostgresAdapter implements DatabaseAdapter {
 
   /**
    * Normalise an `id` column value (typed `unknown` because pg row values are
-   * `unknown`) into the `number | bigint | null` shape `_lastInsertId` /
-   * `DatabaseResult.lastInsertId` expect. At runtime PG returns numeric PKs as
-   * number/bigint (the int8/numeric type parsers above coerce them to Number);
-   * a numeric string is coerced, anything else (null/undefined/non-numeric)
-   * becomes null.
+   * `unknown`) into the shape `_lastInsertId` / `DatabaseResult.lastInsertId`
+   * expect. At runtime PG returns numeric PKs as number/bigint (the int8/numeric
+   * type parsers above coerce them to Number); a numeric string is coerced to a
+   * number so the SERIAL path always returns the integer id.
+   *
+   * A non-numeric string id — the UUID PK case (`id uuid PRIMARY KEY DEFAULT
+   * gen_random_uuid()`) returned via RETURNING — is preserved as-is so the
+   * insert surfaces the actual id instead of null (#256). null/undefined/empty
+   * still become null.
    */
-  private normalizeId(value: unknown): number | bigint | null {
+  private normalizeId(value: unknown): number | bigint | string | null {
     if (typeof value === "number" || typeof value === "bigint") return value;
-    if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
-      return Number(value);
+    if (typeof value === "string" && value.trim() !== "") {
+      return Number.isNaN(Number(value)) ? value : Number(value);
     }
     return null;
   }
@@ -202,12 +209,33 @@ export class PostgresAdapter implements DatabaseAdapter {
     return rows[0] ?? null;
   }
 
-  insert(table: string, data: Record<string, unknown>): DatabaseResult {
+  insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult {
     throw new Error("Use insertAsync() for PostgreSQL.");
   }
 
-  async insertAsync(table: string, data: Record<string, unknown>): Promise<DatabaseResult> {
+  async insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult> {
     this.ensureConnected();
+    // A list of dicts is a batch insert — build one parameterised INSERT and run
+    // it once per row via executeManyAsync (ONE connection, wrapped in a single
+    // transaction). Database.insert / the docs advertise `data: object | object[]`;
+    // without this branch a list called Object.keys() on the array — `["0","1",…]`
+    // — producing garbage SQL (mirrors the Python `'list' has no attribute keys`
+    // crash this fix addresses).
+    if (Array.isArray(data)) {
+      if (data.length === 0) return { success: true, rowsAffected: 0 };
+      const keys = Object.keys(data[0]);
+      const placeholders = keys.map(() => "?").join(", ");
+      const sql = `INSERT INTO "${table}" ("${keys.join('", "')}") VALUES (${placeholders})`;
+      const paramsList = data.map((row) => keys.map((k) => row[k]));
+      try {
+        const result = await this.executeManyAsync(sql, paramsList);
+        if (result.lastInsertId !== undefined) this._lastInsertId = result.lastInsertId;
+        return { success: true, rowsAffected: result.totalAffected, lastInsertId: result.lastInsertId };
+      } catch (e) {
+        return { success: false, rowsAffected: 0, error: (e as Error).message };
+      }
+    }
+
     const keys = Object.keys(data);
     const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
     const sql = `INSERT INTO "${table}" ("${keys.join('", "')}") VALUES (${placeholders}) RETURNING *`;
@@ -337,7 +365,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     }));
   }
 
-  lastInsertId(): number | bigint | null {
+  lastInsertId(): number | bigint | string | null {
     return this._lastInsertId;
   }
 

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

@@ -18,9 +18,23 @@ function isIdentifier(str: string): boolean {
  */
 type SqlParam = null | number | bigint | string | NodeJS.ArrayBufferView;
 
-/** Narrow adapter-level `unknown[]` params to node:sqlite's bindable type. */
+/**
+ * Coerce adapter-level `unknown[]` params to node:sqlite's bindable shape.
+ *
+ * node:sqlite only binds null/number/bigint/string/ArrayBufferView and REJECTS a
+ * raw JS boolean ("Provided value cannot be bound to SQLite parameter N"). SQLite
+ * stores booleans as INTEGER 0/1 (fieldTypeToSQLite maps "boolean" -> INTEGER, and
+ * boolean defaults already emit 1/0), so coerce here at the single bind boundary —
+ * every write path (execute/query/fetchOne/insert/update/delete and ORM save())
+ * funnels through this. booleans -> 0/1, Date -> ISO-8601 string, undefined -> null.
+ */
 function toSqlParams(params: readonly unknown[]): SqlParam[] {
-  return params as SqlParam[];
+  return params.map((p) => {
+    if (typeof p === "boolean") return p ? 1 : 0;
+    if (p === undefined) return null;
+    if (p instanceof Date) return p.toISOString();
+    return p as SqlParam;
+  });
 }
 
 /**

package/packages/orm/src/autoCrud.ts

@@ -64,6 +64,19 @@ export class AutoCrud {
   }
 }
 
+/**
+ * Filter discovered models down to those that explicitly opted into auto-CRUD via
+ * `static autoCrud = true` (the documented opt-in gate; default false). The server
+ * passes only these to generateCrudRoutes, so a model without the flag gets no CRUD
+ * endpoints. Exported so the opt-in gate is locked in by a test rather than
+ * re-implemented at each call site.
+ */
+export function crudEligibleModels(models: DiscoveredModel[]): DiscoveredModel[] {
+  return models.filter(
+    (m) => (m.modelClass as { autoCrud?: boolean } | undefined)?.autoCrud === true,
+  );
+}
+
 /**
  * Generate CRUD route definitions for the given models.
  * (Standalone function for backward compatibility.)

package/packages/orm/src/baseModel.ts

@@ -679,7 +679,9 @@ export class BaseModel {
         // the caller; don't overwrite it with the driver's last_id.
         if (pkField?.autoIncrement) {
           // RETURNING result: pg puts it in rows[0][pkCol]; normalise here.
-          let newId = extractLastInsertId(result);
+          // string is allowed for a non-integer PK surfaced by lastInsertId()
+          // (e.g. a PostgreSQL UUID PK) — #256.
+          let newId: number | bigint | string | null = extractLastInsertId(result);
           if (newId === null && result && typeof result === "object") {
             const rows = (result as any).rows;
             if (Array.isArray(rows) && rows[0]) {

package/packages/orm/src/cachedDatabase.ts

@@ -397,7 +397,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.columns(table);
   }
 
-  lastInsertId(): number | bigint | null {
+  lastInsertId(): number | bigint | string | null {
     return this.adapter.lastInsertId();
   }
 

package/packages/orm/src/database.ts

@@ -519,6 +519,19 @@ export class Database {
     this.adapter = adapter;
   }
 
+  /**
+   * Set the engine type ("sqlite" | "postgres" | "mysql" | "mssql" |
+   * "firebird" | "mongodb"). The static `Database.create` factory assigns the
+   * private `dbType` directly; `initDatabase()` (a free function, no private
+   * access) routes through this setter so a URL connection is correctly typed.
+   * Without it a `postgres://` connection kept the `"sqlite"` default and
+   * `getNextId()` took the SQLite branch — hitting the non-existent
+   * `tina4_sequences` table on PostgreSQL instead of native sequences (#255).
+   */
+  setDbType(type: string): void {
+    this.dbType = type;
+  }
+
   /**
    * Async factory: creates a Database from a connection URL.
    * Works with all adapter types (sqlite, postgres, mysql, mssql, firebird).
@@ -755,8 +768,8 @@ export class Database {
     }
   }
 
-  /** Insert a row into a table. */
-  async insert(table: string, data: Record<string, unknown>): Promise<DatabaseWriteResult> {
+  /** Insert one row (object) or a batch of rows (array of objects) into a table. */
+  async insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseWriteResult> {
     const adapter = this.getNextAdapter();
     const result = (adapter as any).insertAsync
       ? await (adapter as any).insertAsync(table, data)
@@ -1434,11 +1447,19 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     if (pool > 0) {
       // Pool-aware path — delegate to Database.create which manages
       // round-robin adapter rotation and async-local-storage transaction pinning.
-      // Database.create already exposes the global; exposeDb here is idempotent.
+      // Database.create already sets dbType + exposes the global; exposeDb here
+      // is idempotent.
       return exposeDb(await Database.create(url, resolvedUser, resolvedPassword, pool));
     }
+    // Single-connection URL path. Parse the URL so the engine type is known and
+    // set it on the Database — otherwise dbType keeps its "sqlite" default and a
+    // postgres://… connection takes the SQLite getNextId branch, crashing on the
+    // missing tina4_sequences table instead of using native sequences (#255).
+    const parsed = parseDatabaseUrl(url, resolvedUser, resolvedPassword);
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
-    return exposeDb(new Database(setAdapter(adapter)));
+    const db = new Database(setAdapter(adapter));
+    db.setDbType(parsed.type);
+    return exposeDb(db);
   }
 
   // Legacy config path — normalize "sqlserver" to "mssql"
@@ -1459,11 +1480,21 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     );
   }
 
+  // Legacy config-object path. As with the URL path above, the constructed
+  // Database must be told its engine type — otherwise dbType keeps its "sqlite"
+  // 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 => {
+    const db = new Database(setAdapter(adapter));
+    db.setDbType(type);
+    return exposeDb(db);
+  };
+
   switch (type) {
     case "sqlite": {
       const { SQLiteAdapter } = await import("./adapters/sqlite.js");
       const adapter = new SQLiteAdapter(config?.path ?? "./data/tina4.db");
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "postgres": {
       const { PostgresAdapter } = await import("./adapters/postgres.js");
@@ -1475,7 +1506,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "mysql": {
       const { MysqlAdapter } = await import("./adapters/mysql.js");
@@ -1487,7 +1518,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "mssql": {
       const { MssqlAdapter } = await import("./adapters/mssql.js");
@@ -1499,7 +1530,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "firebird": {
       const { FirebirdAdapter } = await import("./adapters/firebird.js");
@@ -1511,7 +1542,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "mongodb": {
       const { MongodbAdapter } = await import("./adapters/mongodb.js");
@@ -1524,14 +1555,14 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
       const connectionString = `mongodb://${creds}${host}:${port}/${database}`;
       const adapter = new MongodbAdapter(connectionString);
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     case "odbc": {
       const { OdbcAdapter } = await import("./adapters/odbc.js");
       const connStr = config?.connectionString ?? config?.url?.replace(/^odbc:\/\/\//, "") ?? "";
       const adapter = new OdbcAdapter({ connectionString: connStr });
       await adapter.connect();
-      return exposeDb(new Database(setAdapter(adapter)));
+      return finished(adapter);
     }
     default:
       throw new Error(`Unknown database type: ${type}`);

package/packages/orm/src/index.ts

@@ -45,7 +45,7 @@ export {
   shouldSkipCreateTable,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
-export { AutoCrud, generateCrudRoutes } from "./autoCrud.js";
+export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
 export { buildQuery, parseQueryString } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";

package/packages/orm/src/migration.ts

@@ -28,15 +28,41 @@ const ALTER_ADD_RE =
   /^\s*ALTER\s+TABLE\s+(?:"([^"]+)"|(\S+))\s+ADD\s+(?:"([^"]+)"|(\S+))/i;
 
 /**
- * Check if the adapter is a Firebird adapter (duck-type check).
- * We look for the `queryAsync` method and `translateSql` which are
- * unique to the Firebird adapter.
+ * Check if the adapter is a Firebird adapter.
+ *
+ * Detection is by the adapter's class name (`constructor.name`) — the engine
+ * discriminator used throughout this package (see `engineOf`). A previous
+ * duck-type check (`queryAsync` + `translateSql`) was WRONG: every async
+ * adapter (Postgres/MySQL/MSSQL) exposes BOTH of those, so the Postgres
+ * adapter was mis-identified as Firebird. That routed the migration-tracking
+ * CREATE into the Firebird `CREATE GENERATOR` + no-default-id DDL and the
+ * record INSERT into the Firebird `GEN_ID()` path — both invalid on Postgres,
+ * so `migrate()` died on the FIRST migration with "syntax error" / aborted
+ * transaction. Class-name detection fixes the mis-route without altering the
+ * runner loop, transaction handling, or raise/return semantics.
+ */
+/**
+ * Unwrap a CachedDatabaseAdapter (what initDatabase() returns) to the concrete
+ * underlying adapter. Engine detection keys on constructor.name, which on the
+ * wrapper reads "CachedDatabaseAdapter" — so without unwrapping, every real app
+ * (all of which go through initDatabase) is mis-detected as SQLite and migrate()
+ * emits AUTOINCREMENT on Postgres/MySQL/MSSQL. Drills through any nesting; a raw
+ * adapter passes through unchanged.
  */
+function unwrapAdapter(db: DatabaseAdapter): DatabaseAdapter {
+  let cur: unknown = db;
+  while (
+    cur &&
+    (cur as { constructor?: { name?: string } }).constructor?.name === "CachedDatabaseAdapter" &&
+    (cur as { adapter?: unknown }).adapter
+  ) {
+    cur = (cur as { adapter: unknown }).adapter;
+  }
+  return cur as DatabaseAdapter;
+}
+
 function isFirebirdAdapter(db: DatabaseAdapter): boolean {
-  return (
-    typeof (db as any).queryAsync === "function" &&
-    typeof (db as any).translateSql === "function"
-  );
+  return unwrapAdapter(db).constructor.name === "FirebirdAdapter";
 }
 
 /**
@@ -87,12 +113,41 @@ const CREATE_TABLE_RE =
 /**
  * Identify the database engine via the adapter's class name.
  * (constructor.name is the engine discriminator used throughout this package.)
+ *
+ * SQLite is the default for any unrecognized adapter (matches the rest of the
+ * package and Python's `db.get_database_type() or "sqlite"`).
  */
-function engineOf(db: DatabaseAdapter): "firebird" | "mssql" | "other" {
-  const name = db.constructor.name;
-  if (name === "FirebirdAdapter") return "firebird";
-  if (name === "MssqlAdapter") return "mssql";
-  return "other";
+function engineOf(
+  db: DatabaseAdapter,
+): "firebird" | "mssql" | "postgres" | "mysql" | "sqlite" {
+  switch (unwrapAdapter(db).constructor.name) {
+    case "FirebirdAdapter": return "firebird";
+    case "MssqlAdapter": return "mssql";
+    case "PostgresAdapter": return "postgres";
+    case "MysqlAdapter": return "mysql";
+    default: return "sqlite";
+  }
+}
+
+/**
+ * Engine-aware auto-increment integer primary-key column for the
+ * `tina4_migration` tracking table.
+ *
+ * Each engine spells an auto-increment integer PK differently — SQLite uses
+ * AUTOINCREMENT, PostgreSQL SERIAL, MySQL AUTO_INCREMENT, MSSQL IDENTITY(1,1).
+ * Emitting raw `AUTOINCREMENT` on any non-SQLite engine fails with
+ * "syntax error at or near AUTOINCREMENT" — which is exactly why `migrate()`
+ * was unusable on PostgreSQL/MySQL/MSSQL. Mirrors the engine-aware id DDL in
+ * the adapters' createTableAsync and Python's `_create_v3_table`. (Firebird is
+ * handled by its own generator branch and never reaches here.)
+ */
+function migrationIdColumn(db: DatabaseAdapter): string {
+  switch (engineOf(db)) {
+    case "postgres": return "id SERIAL PRIMARY KEY";
+    case "mysql": return "id INTEGER PRIMARY KEY AUTO_INCREMENT";
+    case "mssql": return "id INTEGER IDENTITY(1,1) PRIMARY KEY";
+    default: return "id INTEGER PRIMARY KEY AUTOINCREMENT";
+  }
 }
 
 /**
@@ -192,7 +247,7 @@ function buildAddColumnSql(
   colName: string,
   def: FieldDefinition,
 ): string {
-  const engine = adapter.constructor.name;
+  const engine = unwrapAdapter(adapter).constructor.name;
   const isPg = engine === "PostgresAdapter";
   const typeMap: Record<string, string> = isPg
     ? { integer: "INTEGER", string: def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)", text: "TEXT", number: "DOUBLE PRECISION", numeric: "DOUBLE PRECISION", boolean: "BOOLEAN", datetime: "TIMESTAMP" }
@@ -237,12 +292,24 @@ export async function ensureMigrationTable(): Promise<void> {
         applied_at VARCHAR(50) NOT NULL
       )`);
     } else {
-      await adapterCreateTable(adapter, MIGRATION_TABLE, {
-        id: { type: "integer", primaryKey: true, autoIncrement: true },
-        name: { type: "string", required: true },
-        batch: { type: "integer", required: true },
-        applied_at: { type: "datetime", default: "now" },
-      });
+      // Engine-aware bookkeeping DDL (non-Firebird) — same per-engine id column
+      // and column types as the inline `migrate()` bootstrap. Raw AUTOINCREMENT
+      // is SQLite-only and a syntax error elsewhere; SERIAL/AUTO_INCREMENT/
+      // IDENTITY(1,1) are produced via migrationIdColumn(). VARCHAR name (UNIQUE-
+      // safe on MySQL) and DATETIME applied_at on MSSQL (TIMESTAMP is rowversion
+      // there). SQLite gives VARCHAR TEXT affinity, so SQLite stays unchanged.
+      // applied_at keeps a CURRENT_TIMESTAMP default so recordMigration() (which
+      // inserts only name+batch) still works — same as the prior createTable.
+      const idCol = migrationIdColumn(adapter);
+      const engine = engineOf(adapter);
+      const ifNotExists = engine === "mssql" ? "" : "IF NOT EXISTS ";
+      const appliedType = engine === "mssql" ? "DATETIME" : "TEXT";
+      await adapterExecute(adapter, `CREATE TABLE ${ifNotExists}"${MIGRATION_TABLE}" (
+        ${idCol},
+        name VARCHAR(500) NOT NULL,
+        batch INTEGER NOT NULL DEFAULT 1,
+        applied_at ${appliedType} NOT NULL DEFAULT CURRENT_TIMESTAMP
+      )`);
     }
   } else {
     // Ensure batch column exists on older tables that only had passed/description
@@ -360,7 +427,17 @@ export async function removeMigrationRecord(name: string): Promise<void> {
  *
  * @param migrationsDir - Directory containing migration files (default: "migrations")
  * @param delimiter - SQL statement delimiter (default: ";")
- * @returns Array of rolled-back migration names
+ * @returns Array of the down-migration files that were run, e.g.
+ *   "000001_create_users.down.sql". (The legacy down-FUNCTION Map API returns the
+ *   bare migration name instead, since no .down.sql file is involved there.)
+ *
+ * NOTE on return form (intentional, cross-framework): migration return values reflect
+ * WHAT each method acted on, so the forms differ by method and that is by design (not
+ * unified). migrate()/getApplied()/getPending() return the up-migration filename
+ * ("name.sql"); rollback() returns the DOWN-migration filename it executed
+ * ("name.down.sql") — matching the Python master. So a caller diffing rollback()
+ * against getApplied() compares ".down.sql" vs ".sql": strip the suffixes (or compare
+ * the bare "name" stem) to relate them.
  */
 export async function rollback(
   migrationsDir?: string | Map<string, () => void | Promise<void>>,
@@ -377,6 +454,8 @@ export async function rollback(
         await down();
       }
       await removeMigrationRecord(migration.name);
+      // Legacy down-FUNCTION API: no .down.sql file is involved here, so return the
+      // bare migration name (the file-based path below returns "name.down.sql").
       rolledBack.push(migration.name);
     }
     return rolledBack;
@@ -419,7 +498,9 @@ export async function rollback(
     }
 
     await removeMigrationRecord(migration.name);
-    rolledBack.push(migration.name);
+    // Return the down-migration file that was run (e.g. "name.down.sql"), matching
+    // the Python master's rollback return form.
+    rolledBack.push(`${migration.name}.down.sql`);
   }
 
   return rolledBack;
@@ -629,32 +710,30 @@ export async function migrate(
         batch INTEGER NOT NULL DEFAULT 1,
         applied_at VARCHAR(50) NOT NULL
       )`);
-    } else if (db.constructor.name === "PostgresAdapter") {
-      // PostgreSQL: SERIAL + TIMESTAMP (not AUTOINCREMENT/TEXT).
-      await adapterExecute(db, `CREATE TABLE IF NOT EXISTS "${MIGRATION_TABLE}" (
-        id SERIAL PRIMARY KEY,
-        name TEXT NOT NULL,
-        batch INTEGER NOT NULL DEFAULT 1,
-        applied_at TEXT NOT NULL
-      )`);
-    } else if (engineOf(db) === "mssql") {
-      // MSSQL has no AUTOINCREMENT / IF NOT EXISTS — route the bootstrap
-      // through the adapter's engine-aware createTable (IDENTITY(1,1) etc.),
-      // exactly like ensureMigrationTable does. Emitting raw
-      // AUTOINCREMENT/IF NOT EXISTS here is invalid on SQL Server.
-      await adapterCreateTable(db, MIGRATION_TABLE, {
-        id: { type: "integer", primaryKey: true, autoIncrement: true },
-        name: { type: "string", required: true },
-        batch: { type: "integer", required: true },
-        applied_at: { type: "datetime", default: "now" },
-      });
     } else {
-      // SQLite / MySQL — both support IF NOT EXISTS + AUTOINCREMENT/AUTO_INCREMENT.
-      await adapterExecute(db, `CREATE TABLE IF NOT EXISTS "${MIGRATION_TABLE}" (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT NOT NULL,
+      // Engine-aware bookkeeping DDL (non-Firebird). Each engine spells an
+      // auto-increment integer PK differently — SQLite AUTOINCREMENT, Postgres
+      // SERIAL, MySQL AUTO_INCREMENT, MSSQL IDENTITY(1,1) — so the id column is
+      // built per engine (raw `AUTOINCREMENT` is a syntax error on every other
+      // engine; that is the bug that made `migrate()` unusable on
+      // Postgres/MySQL/MSSQL). The `name` column is VARCHAR (not TEXT) so it can
+      // carry a UNIQUE index on MySQL; `applied_at` is DATETIME on MSSQL
+      // (TIMESTAMP there is rowversion, not a real timestamp). SQLite gives
+      // VARCHAR TEXT affinity, so SQLite behaviour is byte-for-byte unchanged.
+      // MSSQL has no IF NOT EXISTS (already guarded by the tableExists check
+      // above), so it is omitted; the other engines tolerate it being absent.
+      // applied_at keeps a CURRENT_TIMESTAMP default so the recordMigration()
+      // path (which inserts only name+batch) still works — preserving the prior
+      // engine-aware createTable behaviour that supplied that default.
+      const idCol = migrationIdColumn(db);
+      const engine = engineOf(db);
+      const ifNotExists = engine === "mssql" ? "" : "IF NOT EXISTS ";
+      const appliedType = engine === "mssql" ? "DATETIME" : "TEXT";
+      await adapterExecute(db, `CREATE TABLE ${ifNotExists}"${MIGRATION_TABLE}" (
+        ${idCol},
+        name VARCHAR(500) NOT NULL,
         batch INTEGER NOT NULL DEFAULT 1,
-        applied_at TEXT NOT NULL
+        applied_at ${appliedType} NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`);
     }
   } else {

package/packages/orm/src/types.ts

@@ -52,7 +52,9 @@ export interface ColumnInfo {
 export interface DatabaseResult {
   success: boolean;
   rowsAffected: number;
-  lastInsertId?: number | bigint;
+  // string covers a non-integer primary key (e.g. a PostgreSQL UUID PK returns
+  // its id as a string via RETURNING, not a SERIAL integer) — #256.
+  lastInsertId?: number | bigint | string;
   error?: string;
 }
 
@@ -96,8 +98,8 @@ export interface DatabaseAdapter {
   /** List columns with types for a table. */
   columns(table: string): ColumnInfo[];
 
-  /** Get the last auto-increment id. */
-  lastInsertId(): number | bigint | null;
+  /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
+  lastInsertId(): number | bigint | string | null;
 
   /** Close the connection. */
   close(): void;