@fragno-dev/db 0.3.0 → 0.4.1

package/src/adapters/generic-sql/migration/prepared-migrations.test.ts

@@ -1,16 +1,17 @@
 import { describe, expect, test } from "vitest";
-import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
-import { createColdKysely } from "./cold-kysely";
-import { SQLiteSQLGenerator } from "./dialect/sqlite";
-import { PostgresSQLGenerator } from "./dialect/postgres";
-import { MySQLSQLGenerator } from "./dialect/mysql";
-import { createPreparedMigrations } from "./prepared-migrations";
+
 import {
   createNamingResolver,
   schemaNamingStrategy,
   suffixNamingStrategy,
   type SqlNamingStrategy,
 } from "../../../naming/sql-naming";
+import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
+import { createColdKysely } from "./cold-kysely";
+import { MySQLSQLGenerator } from "./dialect/mysql";
+import { PostgresSQLGenerator } from "./dialect/postgres";
+import { SQLiteSQLGenerator } from "./dialect/sqlite";
+import { createPreparedMigrations } from "./prepared-migrations";
 
 const testSchema = schema("test", (s) => {
   return s
@@ -36,7 +37,37 @@ const testSchema = schema("test", (s) => {
     });
 });
 
+const nullableSchema = schema("nullable", (s) => {
+  return s
+    .addTable("users", (t) => {
+      return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+    })
+    .alterTable("users", (t) => {
+      return t.alterColumn("name").nullable();
+    });
+});
+
 const resolver = createNamingResolver(testSchema, "test", suffixNamingStrategy);
+const nullableResolver = createNamingResolver(nullableSchema, "nullable", suffixNamingStrategy);
+const fkLaterSchema = schema("fk_later", (s) => {
+  return s
+    .addTable("users", (t) => {
+      return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+    })
+    .addTable("posts", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("title", column("string"))
+        .addColumn("authorId", referenceColumn());
+    })
+    .addReference("author", {
+      type: "one",
+      from: { table: "posts", column: "authorId" },
+      to: { table: "users", column: "id" },
+    });
+});
+
+const fkLaterResolver = createNamingResolver(fkLaterSchema, "fk_later", suffixNamingStrategy);
 
 describe("PreparedMigrations - PostgreSQL", () => {
   const coldKysely = createColdKysely("postgresql");
@@ -434,7 +465,7 @@ describe("PreparedMigrations - Integration", () => {
     expect(transactionStarted).toBe(true);
     expect(executedStatements.length).toBe(2);
     expect(executedStatements[0]).toMatchInlineSnapshot(
-      `"create table "users_test" ("id" varchar(30) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null)"`,
+      `"create table "users_test" ("id" varchar(128) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null)"`,
     );
     expect(executedStatements[1]).toMatchInlineSnapshot(
       `"insert into "fragno_db_settings" ("id", "key", "value") values ('BflimUWc1NbCMMDD9SM3gQ', 'test.schema_version', '1')"`,
@@ -588,7 +619,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
 
     const sql = prepared.getSQL(0, 2, { updateVersionInMigration: true });
     expect(sql).toMatchInlineSnapshot(`
-      "create table "users_test" ("id" varchar(30) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
+      "create table "users_test" ("id" varchar(128) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
 
       alter table "users_test" add column "age" integer;
 
@@ -610,7 +641,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
 
     const sql = prepared.getSQL(0, 4, { updateVersionInMigration: true });
     expect(sql).toMatchInlineSnapshot(`
-      "create table "users_test" ("id" varchar(30) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
+      "create table "users_test" ("id" varchar(128) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
 
       alter table "users_test" add column "age" integer;
 
@@ -618,7 +649,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
 
       create index "idx_users_age_idx_test_1c69311d" on "users_test" ("age");
 
-      create table "posts_test" ("id" varchar(30) not null unique, "title" text not null, "authorId" bigint not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
+      create table "posts_test" ("id" varchar(128) not null unique, "title" text not null, "authorId" bigint not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
 
       alter table "posts_test" add constraint "fk_posts_users_author_test_8d48035c" foreign key ("authorId") references "users_test" ("_internalId") on delete restrict on update restrict;
 
@@ -656,7 +687,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
 
     const sql = prepared.getSQL(2, 3, { updateVersionInMigration: true });
     expect(sql).toMatchInlineSnapshot(`
-      "create table "posts_test" ("id" varchar(30) not null unique, "title" text not null, "authorId" bigint not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
+      "create table "posts_test" ("id" varchar(128) not null unique, "title" text not null, "authorId" bigint not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
 
       update "fragno_db_settings" set "value" = '3' where "key" = 'test.schema_version';"
     `);
@@ -688,6 +719,20 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
     `);
   });
 
+  test("SQLite: adding FK after table creation throws", () => {
+    const prepared = createPreparedMigrations({
+      schema: fkLaterSchema,
+      namespace: "fk_later",
+      database: "sqlite",
+      resolver: fkLaterResolver,
+    });
+
+    const previousVersion = fkLaterSchema.version - 1;
+    expect(() =>
+      prepared.getSQL(previousVersion, fkLaterSchema.version, { updateVersionInMigration: false }),
+    ).toThrow("SQLite doesn't support modifying foreign keys");
+  });
+
   test("MySQL: migration 0 -> 4 with FK checks disabled", () => {
     const prepared = createPreparedMigrations({
       schema: testSchema,
@@ -700,7 +745,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
     expect(sql).toMatchInlineSnapshot(`
       "SET FOREIGN_KEY_CHECKS = 0;
 
-      create table \`users_test\` (\`id\` varchar(30) not null unique, \`name\` text not null, \`_internalId\` bigint not null  auto_increment, \`_version\` integer default 0 not null, constraint \`users_test__internalId\` primary key (\`_internalId\`));
+      create table \`users_test\` (\`id\` varchar(128) not null unique, \`name\` text not null, \`_internalId\` bigint not null  auto_increment, \`_version\` integer default 0 not null, constraint \`users_test__internalId\` primary key (\`_internalId\`));
 
       alter table \`users_test\` add column \`age\` integer;
 
@@ -708,7 +753,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
 
       create index \`idx_users_age_idx_test_1c69311d\` on \`users_test\` (\`age\`);
 
-      create table \`posts_test\` (\`id\` varchar(30) not null unique, \`title\` text not null, \`authorId\` bigint not null, \`_internalId\` bigint not null  auto_increment, \`_version\` integer default 0 not null, constraint \`posts_test__internalId\` primary key (\`_internalId\`));
+      create table \`posts_test\` (\`id\` varchar(128) not null unique, \`title\` text not null, \`authorId\` bigint not null, \`_internalId\` bigint not null  auto_increment, \`_version\` integer default 0 not null, constraint \`posts_test__internalId\` primary key (\`_internalId\`));
 
       alter table \`posts_test\` add constraint \`fk_posts_users_author_test_8d48035c\` foreign key (\`authorId\`) references \`users_test\` (\`_internalId\`) on delete restrict on update restrict;
 
@@ -718,6 +763,64 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
     `);
   });
 
+  test("PostgreSQL: migration 1 -> 2 (make column nullable)", () => {
+    const prepared = createPreparedMigrations({
+      schema: nullableSchema,
+      namespace: "nullable",
+      database: "postgresql",
+      resolver: nullableResolver,
+    });
+
+    const sql = prepared.getSQL(1, 2, { updateVersionInMigration: false });
+    expect(sql).toMatchInlineSnapshot(
+      `"alter table "users_nullable" alter column "name" drop not null;"`,
+    );
+  });
+
+  test("MySQL: migration 1 -> 2 (make column nullable)", () => {
+    const prepared = createPreparedMigrations({
+      schema: nullableSchema,
+      namespace: "nullable",
+      database: "mysql",
+      resolver: nullableResolver,
+    });
+
+    const sql = prepared.getSQL(1, 2, { updateVersionInMigration: false });
+    expect(sql).toMatchInlineSnapshot(`
+      "SET FOREIGN_KEY_CHECKS = 0;
+
+      alter table \`users_nullable\` modify column \`name\` text;
+
+      SET FOREIGN_KEY_CHECKS = 1;"
+    `);
+  });
+
+  test("SQLite: migration 1 -> 2 (make column nullable)", () => {
+    const prepared = createPreparedMigrations({
+      schema: nullableSchema,
+      namespace: "nullable",
+      database: "sqlite",
+      resolver: nullableResolver,
+    });
+
+    const sql = prepared.getSQL(1, 2, { updateVersionInMigration: false });
+    expect(sql).toMatchInlineSnapshot(`
+      "PRAGMA defer_foreign_keys = ON;
+
+      PRAGMA foreign_keys = OFF;
+
+      create table "users_nullable__fragno_tmp_414fdd" ("id" text not null unique, "name" text, "_internalId" integer not null primary key autoincrement, "_version" integer default 0 not null);
+
+      insert into "users_nullable__fragno_tmp_414fdd" ("id", "name", "_internalId", "_version") select "id", "name", "_internalId", "_version" from "users_nullable";
+
+      drop table "users_nullable";
+
+      alter table "users_nullable__fragno_tmp_414fdd" rename to "users_nullable";
+
+      PRAGMA foreign_keys = ON;"
+    `);
+  });
+
   test("compile returns CompiledMigration with statements array", () => {
     const prepared = createPreparedMigrations({
       schema: testSchema,
@@ -744,7 +847,7 @@ describe("PreparedMigrations - Multi-step Migration Scenarios", () => {
     const sql = prepared.getSQL(0, 1, { updateVersionInMigration: false });
     expect(sql).not.toContain("fragno_db_settings");
     expect(sql).toMatchInlineSnapshot(
-      `"create table "users_test" ("id" varchar(30) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);"`,
+      `"create table "users_test" ("id" varchar(128) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);"`,
     );
   });
 });

package/src/adapters/generic-sql/migration/prepared-migrations.ts

@@ -1,16 +1,17 @@
+import type { Kysely } from "kysely";
+
+import { generateMigrationFromSchema } from "../../../migration-engine/auto-from-schema";
+import type { NamingResolver } from "../../../naming/sql-naming";
 import type { AnySchema } from "../../../schema/create";
 import type { SqlDriverAdapter } from "../../../sql-driver/sql-driver-adapter";
-import type { NamingResolver } from "../../../naming/sql-naming";
-import { generateMigrationFromSchema } from "../../../migration-engine/auto-from-schema";
+import type { DriverConfig, SupportedDatabase } from "../driver-config";
+import type { SQLiteStorageMode } from "../sqlite-storage";
 import { createColdKysely } from "./cold-kysely";
-import { type SQLGenerator } from "./sql-generator";
-import { SQLiteSQLGenerator } from "./dialect/sqlite";
-import { PostgresSQLGenerator } from "./dialect/postgres";
 import { MySQLSQLGenerator } from "./dialect/mysql";
+import { PostgresSQLGenerator } from "./dialect/postgres";
+import { SQLiteSQLGenerator } from "./dialect/sqlite";
 import { executeMigration, type CompiledMigration } from "./executor";
-import type { DriverConfig, SupportedDatabase } from "../driver-config";
-import type { Kysely } from "kysely";
-import type { SQLiteStorageMode } from "../sqlite-storage";
+import { type SQLGenerator } from "./sql-generator";
 /**
  * Options for executing a migration.
  */

package/src/adapters/generic-sql/migration/sql-generator.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import {
   type ColumnDefinitionBuilder,
   type CompiledQuery,
@@ -6,17 +8,17 @@ import {
   type RawBuilder,
   sql,
 } from "kysely";
-import { createHash } from "node:crypto";
+
+import { SETTINGS_TABLE_NAME } from "../../../fragments/internal-fragment.schema";
 import type {
   ColumnInfo,
   ColumnOperation,
   MigrationOperation,
 } from "../../../migration-engine/shared";
-import { SETTINGS_TABLE_NAME } from "../../../fragments/internal-fragment.schema";
 import type { NamingResolver } from "../../../naming/sql-naming";
+import { createSQLTypeMapper } from "../../../schema/type-conversion/create-sql-type-mapper";
 import type { DriverConfig, SupportedDatabase } from "../driver-config";
 import type { SQLiteStorageMode } from "../sqlite-storage";
-import { createSQLTypeMapper } from "../../../schema/type-conversion/create-sql-type-mapper";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type KyselyAny = Kysely<any>;

package/src/adapters/generic-sql/query/create-sql-query-compiler.ts

@@ -1,10 +1,10 @@
-import type { DriverConfig } from "../driver-config";
 import type { NamingResolver } from "../../../naming/sql-naming";
+import type { DriverConfig } from "../driver-config";
 import type { SQLiteStorageMode } from "../sqlite-storage";
-import { SQLQueryCompiler, type AnyKysely } from "./sql-query-compiler";
-import { PostgreSQLQueryCompiler } from "./dialect/postgres";
 import { MySQLQueryCompiler } from "./dialect/mysql";
+import { PostgreSQLQueryCompiler } from "./dialect/postgres";
 import { SQLiteQueryCompiler } from "./dialect/sqlite";
+import { SQLQueryCompiler, type AnyKysely } from "./sql-query-compiler";
 
 /**
  * Factory function to create a dialect-specific SQL query compiler.

package/src/adapters/generic-sql/query/cursor-utils.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { column, idColumn, schema } from "../../../schema/create";
-import { Cursor } from "../../../query/cursor";
+
 import type { Condition } from "../../../query/condition-builder";
+import { Cursor } from "../../../query/cursor";
+import { column, idColumn, schema } from "../../../schema/create";
 import { NodePostgresDriverConfig } from "../driver-config";
 import { buildCursorCondition } from "./cursor-utils";
 

package/src/adapters/generic-sql/query/cursor-utils.ts

@@ -1,6 +1,6 @@
-import type { AnyColumn } from "../../../schema/create";
 import type { Condition } from "../../../query/condition-builder";
 import { decodeCursor, serializeCursorValues, type Cursor } from "../../../query/cursor";
+import type { AnyColumn } from "../../../schema/create";
 import type { DriverConfig } from "../driver-config";
 import type { SQLiteStorageMode } from "../sqlite-storage";
 

package/src/adapters/generic-sql/query/db-now-sql.ts

@@ -0,0 +1,49 @@
+import { sql } from "kysely";
+
+import type { AnyColumn } from "../../../schema/create";
+import type { DriverConfig } from "../driver-config";
+import { sqliteStorageDefault, type SQLiteStorageMode } from "../sqlite-storage";
+
+type ColumnType = AnyColumn["type"];
+
+type BuildDbNowSqlOptions = {
+  driverConfig: DriverConfig;
+  columnType: ColumnType;
+  offsetMs: number;
+  sqliteStorageMode?: SQLiteStorageMode;
+};
+
+export const buildDbNowSql = ({
+  driverConfig,
+  columnType,
+  offsetMs,
+  sqliteStorageMode,
+}: BuildDbNowSqlOptions) => {
+  if (driverConfig.databaseType === "sqlite") {
+    const storageMode = sqliteStorageMode ?? sqliteStorageDefault;
+    const storage = columnType === "date" ? storageMode.dateStorage : storageMode.timestampStorage;
+    if ((columnType === "timestamp" || columnType === "date") && storage === "epoch-ms") {
+      const base = sql`(cast((julianday('now') - 2440587.5)*86400000 as integer))`;
+      return offsetMs === 0 ? base : sql`${base} + ${offsetMs}`;
+    }
+    if (offsetMs === 0) {
+      return sql`CURRENT_TIMESTAMP`;
+    }
+    const roundedSeconds = Math.round((offsetMs / 1000) * 1000) / 1000;
+    const modifier = `${roundedSeconds >= 0 ? "+" : ""}${roundedSeconds} seconds`;
+    return sql`datetime('now', ${modifier})`;
+  }
+
+  if (driverConfig.databaseType === "mysql") {
+    if (offsetMs === 0) {
+      return sql`CURRENT_TIMESTAMP`;
+    }
+    const micros = Math.trunc(offsetMs * 1000);
+    return sql`TIMESTAMPADD(MICROSECOND, ${micros}, CURRENT_TIMESTAMP)`;
+  }
+
+  if (offsetMs === 0) {
+    return sql`CURRENT_TIMESTAMP`;
+  }
+  return sql`(CURRENT_TIMESTAMP + (${offsetMs} * interval '1 millisecond'))`;
+};

package/src/adapters/generic-sql/query/generic-sql-uow-operation-compiler.test.ts

@@ -1,8 +1,9 @@
 import { describe, test, expect } from "vitest";
-import { GenericSQLUOWOperationCompiler } from "./generic-sql-uow-operation-compiler";
-import { BetterSQLite3DriverConfig, NodePostgresDriverConfig } from "../driver-config";
-import { schema, column, idColumn, referenceColumn, FragnoId } from "../../../schema/create";
+
 import { Cursor } from "../../../query/cursor";
+import { schema, column, idColumn, referenceColumn, FragnoId } from "../../../schema/create";
+import { BetterSQLite3DriverConfig, NodePostgresDriverConfig } from "../driver-config";
+import { GenericSQLUOWOperationCompiler } from "./generic-sql-uow-operation-compiler";
 
 // Test schema with indexes
 const testSchema = schema("test", (s) => {
@@ -18,7 +19,8 @@ const testSchema = schema("test", (s) => {
         .addColumn("invitedBy", referenceColumn().nullable())
         .createIndex("idx_email", ["email"], { unique: true })
         .createIndex("idx_users_name", ["name"])
-        .createIndex("idx_age", ["age"]);
+        .createIndex("idx_age", ["age"])
+        .createIndex("idx_users_name_created_id", ["name", "createdAt", "id"]);
     })
     .addTable("posts", (t) => {
       return t
@@ -133,6 +135,45 @@ const customIdSchema = schema("customid", (s) => {
     });
 });
 
+const joinOnlySchema = schema("joinonly", (s) => {
+  return s
+    .addTable("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .createIndex("idx_users_email", ["email"]);
+    })
+    .addTable("invitations", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .createIndex("idx_inv_email", ["email"]);
+    })
+    .addTable("memberships", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("userId", referenceColumn())
+        .createIndex("idx_memberships_user", ["userId"]);
+    })
+    .addReference("invitedUser", {
+      type: "one",
+      from: { table: "invitations", column: "email" },
+      to: { table: "users", column: "email" },
+      foreignKey: false,
+    })
+    .addReference("membershipUser", {
+      type: "one",
+      from: { table: "memberships", column: "userId" },
+      to: { table: "users", column: "id" },
+    })
+    .addReference("memberships", {
+      type: "many",
+      from: { table: "users", column: "id" },
+      to: { table: "memberships", column: "userId" },
+      foreignKey: false,
+    });
+});
+
 describe("GenericSQLUOWOperationCompiler", () => {
   const driverConfig = new BetterSQLite3DriverConfig();
 
@@ -886,6 +927,45 @@ describe("GenericSQLUOWOperationCompiler", () => {
       );
       expect(result!.parameters).toEqual([1, "Alice", 5]);
     });
+
+    test("should compile find with composite cursor pagination", () => {
+      const compiler = new GenericSQLUOWOperationCompiler(driverConfig);
+      const createdAt = new Date("2024-01-01T00:00:00.000Z");
+      const cursor = new Cursor({
+        indexName: "idx_users_name_created_id",
+        orderDirection: "desc",
+        pageSize: 7,
+        indexValues: { name: "Alice", createdAt, id: "user-123" },
+      });
+
+      const result = compiler.compileFind({
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "idx_users_name_created_id",
+        options: {
+          useIndex: "idx_users_name_created_id",
+          select: true,
+          orderByIndex: { indexName: "idx_users_name_created_id", direction: "desc" },
+          after: cursor,
+          pageSize: 7,
+        },
+      });
+
+      expect(result).not.toBeNull();
+      expect(result!.sql).toMatchInlineSnapshot(
+        `"select "users"."id" as "id", "users"."name" as "name", "users"."email" as "email", "users"."age" as "age", "users"."isActive" as "isActive", "users"."createdAt" as "createdAt", "users"."invitedBy" as "invitedBy", "users"."_internalId" as "_internalId", "users"."_version" as "_version" from "users" where ("users"."name" < ? or ("users"."name" = ? and "users"."createdAt" < ?) or ("users"."name" = ? and "users"."createdAt" = ? and "users"."id" < ?)) order by "users"."name" desc, "users"."createdAt" desc, "users"."id" desc limit ?"`,
+      );
+      expect(result!.parameters).toEqual([
+        "Alice",
+        "Alice",
+        createdAt.getTime(),
+        "Alice",
+        createdAt.getTime(),
+        "user-123",
+        7,
+      ]);
+    });
   });
 
   describe("complex where conditions", () => {
@@ -1099,6 +1179,62 @@ describe("GenericSQLUOWOperationCompiler", () => {
       );
     });
 
+    test("should compile join-only relation without internal id coercion", () => {
+      const compiler = new GenericSQLUOWOperationCompiler(driverConfig);
+
+      const result = compiler.compileFind({
+        type: "find",
+        schema: joinOnlySchema,
+        table: joinOnlySchema.tables.invitations,
+        indexName: "primary",
+        options: {
+          useIndex: "primary",
+          select: ["id"],
+          joins: [
+            {
+              relation: joinOnlySchema.tables.invitations.relations.invitedUser,
+              options: {
+                select: ["email"],
+              },
+            },
+          ],
+        },
+      });
+
+      expect(result).not.toBeNull();
+      expect(result!.sql).toMatchInlineSnapshot(
+        `"select "invitedUser"."email" as "invitedUser:email", "invitedUser"."_internalId" as "invitedUser:_internalId", "invitedUser"."_version" as "invitedUser:_version", "invitations"."id" as "id", "invitations"."_internalId" as "_internalId", "invitations"."_version" as "_version" from "invitations" left join "users" as "invitedUser" on "invitations"."email" = "invitedUser"."email""`,
+      );
+    });
+
+    test("should coerce left-side id for join-only relations", () => {
+      const compiler = new GenericSQLUOWOperationCompiler(driverConfig);
+
+      const result = compiler.compileFind({
+        type: "find",
+        schema: joinOnlySchema,
+        table: joinOnlySchema.tables.users,
+        indexName: "primary",
+        options: {
+          useIndex: "primary",
+          select: ["id"],
+          joins: [
+            {
+              relation: joinOnlySchema.tables.users.relations.memberships,
+              options: {
+                select: ["id"],
+              },
+            },
+          ],
+        },
+      });
+
+      expect(result).not.toBeNull();
+      expect(result!.sql).toMatchInlineSnapshot(
+        `"select "memberships"."id" as "memberships:id", "memberships"."_internalId" as "memberships:_internalId", "memberships"."_version" as "memberships:_version", "users"."id" as "id", "users"."_internalId" as "_internalId", "users"."_version" as "_version" from "users" left join "memberships" as "memberships" on "users"."_internalId" = "memberships"."userId""`,
+      );
+    });
+
     test("should compile join with specific column selection", () => {
       const compiler = new GenericSQLUOWOperationCompiler(driverConfig);
 
@@ -1220,7 +1356,7 @@ describe("GenericSQLUOWOperationCompiler", () => {
 
       expect(result).not.toBeNull();
       expect(result!.sql).toMatchInlineSnapshot(
-        `"select "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and "users"."name" like ?)"`,
+        `"select "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and "author"."name" like ?)"`,
       );
       expect(result!.parameters).toEqual(["%john%"]);
     });
@@ -1267,7 +1403,7 @@ describe("GenericSQLUOWOperationCompiler", () => {
 
       expect(result).not.toBeNull();
       expect(result!.sql).toMatchInlineSnapshot(
-        `"select "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and ("users"."name" like ? and "users"."isActive" = ?))"`,
+        `"select "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and ("author"."name" like ? and "author"."isActive" = ?))"`,
       );
     });
 
@@ -1358,7 +1494,7 @@ describe("GenericSQLUOWOperationCompiler", () => {
 
       expect(result).not.toBeNull();
       expect(result!.sql).toMatchInlineSnapshot(
-        `"select "author"."id" as "author:id", "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and "users"."id" = ?)"`,
+        `"select "author"."id" as "author:id", "author"."name" as "author:name", "author"."_internalId" as "author:_internalId", "author"."_version" as "author:_version", "posts"."id" as "id", "posts"."title" as "title", "posts"."_internalId" as "_internalId", "posts"."_version" as "_version" from "posts" left join "users" as "author" on ("posts"."userId" = "author"."_internalId" and "author"."id" = ?)"`,
       );
       expect(result!.parameters).toEqual(["user-123"]);
     });
@@ -1498,7 +1634,7 @@ describe("GenericSQLUOWOperationCompiler", () => {
 
       expect(result).not.toBeNull();
       expect(result!.sql).toMatchInlineSnapshot(
-        `"select "product"."productId" as "product:productId", "product"."name" as "product:name", "product"."_internalId" as "product:_internalId", "product"."_version" as "product:_version", "product_categories"."id" as "id", "product_categories"."_internalId" as "_internalId", "product_categories"."_version" as "_version" from "product_categories" left join "products" as "product" on ("product_categories"."prodRef" = "product"."_internalId" and "products"."productId" = ?)"`,
+        `"select "product"."productId" as "product:productId", "product"."name" as "product:name", "product"."_internalId" as "product:_internalId", "product"."_version" as "product:_version", "product_categories"."id" as "id", "product_categories"."_internalId" as "_internalId", "product_categories"."_version" as "_version" from "product_categories" left join "products" as "product" on ("product_categories"."prodRef" = "product"."_internalId" and "product"."productId" = ?)"`,
       );
       expect(result!.parameters).toEqual(["prod-456"]);
     });

package/src/adapters/generic-sql/query/generic-sql-uow-operation-compiler.ts

@@ -1,22 +1,23 @@
-import { UOWOperationCompiler } from "../../shared/uow-operation-compiler";
 import type { CompiledQuery } from "kysely";
-import type { DriverConfig } from "../driver-config";
+
 import type { NamingResolver } from "../../../naming/sql-naming";
-import type { SQLiteStorageMode } from "../sqlite-storage";
+import { buildCondition } from "../../../query/condition-builder";
+import type { Condition } from "../../../query/condition-builder";
+import { buildFindOptions } from "../../../query/orm/orm";
+import type { AnySelectClause } from "../../../query/simple-query-interface";
 import type {
   RetrievalOperation,
   MutationOperation,
   CompiledMutation,
 } from "../../../query/unit-of-work/unit-of-work";
 import type { AnyColumn, AnySchema } from "../../../schema/create";
-import { buildCondition } from "../../../query/condition-builder";
+import { UOWOperationCompiler } from "../../shared/uow-operation-compiler";
+import type { DriverConfig } from "../driver-config";
+import { createColdKysely } from "../migration/cold-kysely";
+import type { SQLiteStorageMode } from "../sqlite-storage";
 import { createSQLQueryCompiler } from "./create-sql-query-compiler";
-import { SQLQueryCompiler } from "./sql-query-compiler";
 import { buildCursorCondition } from "./cursor-utils";
-import type { Condition } from "../../../query/condition-builder";
-import { buildFindOptions } from "../../../query/orm/orm";
-import type { AnySelectClause } from "../../../query/simple-query-interface";
-import { createColdKysely } from "../migration/cold-kysely";
+import { SQLQueryCompiler } from "./sql-query-compiler";
 
 /**
  * Generic SQL UOW Operation Compiler.
@@ -118,13 +119,7 @@ export class GenericSQLUOWOperationCompiler extends UOWOperationCompiler<Compile
       orderBy = indexColumns.map((col) => [col, orderDirection]);
     }
 
-    // Handle cursor pagination - build a cursor condition
-    // TODO: Multi-column cursor pagination not yet supported
-    if ((after || before) && indexColumns.length > 1) {
-      throw new Error(
-        "Multi-column cursor pagination is not yet supported in Generic SQL implementation",
-      );
-    }
+    // Handle cursor pagination - build a cursor condition (supports multi-column lexicographic compare)
     const cursorCondition = buildCursorCondition(
       after || before,
       indexColumns,
@@ -169,6 +164,7 @@ export class GenericSQLUOWOperationCompiler extends UOWOperationCompiler<Compile
         orderBy,
         limit: effectiveLimit,
         join,
+        readTracking: op.readTracking,
       });
     }
 
@@ -184,7 +180,10 @@ export class GenericSQLUOWOperationCompiler extends UOWOperationCompiler<Compile
       return null;
     }
 
-    return sqlCompiler.compileFindMany(op.table, compiledOptions);
+    return sqlCompiler.compileFindMany(op.table, {
+      ...compiledOptions,
+      readTracking: op.readTracking,
+    });
   }
 
   override compileCreate(

package/src/adapters/generic-sql/query/select-builder.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+
 import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
 import { mapSelect, extendSelect } from "./select-builder";