@fragno-dev/db 0.1.15 → 0.2.0

package/src/adapters/drizzle/test-utils.ts

@@ -2,7 +2,7 @@ import { mkdir, writeFile, rm, access } from "node:fs/promises";
 import { join } from "node:path";
 import { generateSchema, type SupportedProvider } from "./generate";
 import type { Schema } from "../../schema/create";
-import { settingsSchema } from "../../fragments/internal-fragment";
+import { internalSchema } from "../../fragments/internal-fragment";
 
 /**
  * Writes a Fragno schema to a temporary TypeScript file and dynamically imports it.
@@ -42,10 +42,10 @@ export async function writeAndLoadSchema(
   // Always include settings schema first (as done in generation-engine.ts), then the test schema
   // De-duplicate: if the test schema IS the settings schema, don't add it twice
   const fragments: Array<{ namespace: string; schema: Schema }> = [
-    { namespace: "", schema: settingsSchema },
+    { namespace: "", schema: internalSchema },
   ];
 
-  if (schema !== settingsSchema) {
+  if (schema !== internalSchema) {
     fragments.push({ namespace: namespace ?? "", schema });
   }
 

package/src/adapters/generic-sql/README.md

@@ -0,0 +1,14 @@
+# Generic SQL Adapter
+
+## Goals:
+
+- Follow roughly the Kysely interfaces so that we can use Kysely adapters.
+- Use this to replace ALL query execution logic.
+- "Own" the result transformation step.
+- Optionally able to create SQL migrations internally.
+- Be able to map names (tables, columns, constraints, etc)
+- Be able to run migrations directly from the Fragment
+
+## Non-goal:
+
+- Generate schemas in ORM-specific DSLs, this is left to the ORM adapters.

package/src/adapters/generic-sql/driver-config.ts

@@ -0,0 +1,144 @@
+export const supportedDatabases = ["sqlite", "postgresql", "mysql"] as const;
+export type SupportedDatabase = (typeof supportedDatabases)[number];
+
+export const supportedDriverTypes = [
+  "sqlocal",
+  "cloudflare_durable_objects",
+  "better-sqlite3",
+  "pg",
+  "pglite",
+  "mysql2",
+] as const;
+
+export type SupportedDriverType = (typeof supportedDriverTypes)[number];
+
+export abstract class DriverConfig<T extends SupportedDriverType = SupportedDriverType> {
+  abstract readonly driverType: T;
+  abstract readonly databaseType: SupportedDatabase;
+
+  abstract readonly supportsReturning: boolean;
+  abstract readonly supportsJson: boolean;
+
+  /**
+   * Column name for internal ID in RETURNING results.
+   * Only defined if supportsReturning is true.
+   */
+  abstract readonly internalIdColumn: string | undefined;
+
+  get supportsRowsAffected(): boolean {
+    return !!this.extractAffectedRows;
+  }
+
+  /**
+   * Extract the number of affected rows from a query result.
+   * Only implemented for drivers that support affected rows reporting.
+   *
+   * @param result - The query result from the SQL driver
+   * @returns The number of affected rows as bigint
+   * @throws Error if affected rows information is not found in the result
+   */
+  extractAffectedRows?(result: Record<string, unknown>): bigint;
+}
+
+export class SQLocalDriverConfig extends DriverConfig<"sqlocal"> {
+  override readonly driverType = "sqlocal";
+  override readonly databaseType = "sqlite";
+  override readonly supportsReturning = true;
+  override readonly supportsJson = false;
+  override readonly internalIdColumn = "_internalId";
+}
+
+export class CloudflareDurableObjectsDriverConfig extends DriverConfig<"cloudflare_durable_objects"> {
+  override readonly driverType = "cloudflare_durable_objects";
+  override readonly databaseType = "sqlite";
+  override readonly supportsReturning = true;
+  override readonly supportsJson = false;
+  override readonly internalIdColumn = "_internalId";
+}
+
+export class BetterSQLite3DriverConfig extends DriverConfig<"better-sqlite3"> {
+  override readonly driverType = "better-sqlite3";
+  override readonly databaseType = "sqlite";
+  override readonly supportsReturning = true;
+  override readonly supportsJson = false;
+  override readonly internalIdColumn = "_internalId";
+
+  override extractAffectedRows(result: Record<string, unknown>): bigint {
+    if ("numAffectedRows" in result) {
+      const value = result["numAffectedRows"];
+      if (typeof value === "bigint") {
+        return value;
+      }
+      if (typeof value === "number") {
+        return BigInt(value);
+      }
+    }
+
+    throw new Error(
+      `No affected rows found in result: ${JSON.stringify(result)}. Driver ${this.driverType} is expected to support affected rows.`,
+    );
+  }
+}
+
+export class NodePostgresDriverConfig extends DriverConfig<"pg"> {
+  override readonly driverType = "pg";
+  override readonly databaseType = "postgresql";
+  override readonly supportsReturning = true;
+  override readonly supportsJson = true;
+  override readonly internalIdColumn = "_internalId";
+
+  override extractAffectedRows(result: Record<string, unknown>): bigint {
+    if ("numAffectedRows" in result) {
+      const value = result["numAffectedRows"];
+      if (typeof value === "bigint") {
+        return value;
+      }
+      if (typeof value === "number") {
+        return BigInt(value);
+      }
+    }
+    if ("numChangedRows" in result) {
+      const value = result["numChangedRows"];
+      if (typeof value === "bigint") {
+        return value;
+      }
+      if (typeof value === "number") {
+        return BigInt(value);
+      }
+    }
+    throw new Error(
+      `No affected rows found in result: ${JSON.stringify(result)}. Driver ${this.driverType} is expected to support affected rows.`,
+    );
+  }
+}
+
+export class PGLiteDriverConfig extends DriverConfig<"pglite"> {
+  override readonly driverType = "pglite";
+  override readonly databaseType = "postgresql";
+  override readonly supportsReturning = true;
+  override readonly supportsJson = true;
+  override readonly internalIdColumn = "_internalId";
+
+  override extractAffectedRows(result: Record<string, unknown>): bigint {
+    if ("affectedRows" in result) {
+      const value = result["affectedRows"];
+      if (typeof value === "bigint") {
+        return value;
+      }
+      if (typeof value === "number") {
+        return BigInt(value);
+      }
+    }
+    throw new Error(
+      `No affected rows found in result: ${JSON.stringify(result)}. Driver ${this.driverType} is expected to support affected rows.`,
+    );
+  }
+}
+
+export class MySQL2DriverConfig extends DriverConfig<"mysql2"> {
+  override readonly driverType = "mysql2";
+  override readonly databaseType = "mysql";
+  override readonly supportsReturning = false;
+  override readonly supportsJson = true;
+  override readonly internalIdColumn = undefined;
+}

package/src/adapters/generic-sql/generic-sql-adapter.test.ts

@@ -0,0 +1,50 @@
+import { SQLocalKysely } from "sqlocal/kysely";
+import { assert, describe, expect, it } from "vitest";
+import { SQLocalDriverConfig } from "./driver-config";
+import { GenericSQLAdapter } from "./generic-sql-adapter";
+import { column, idColumn, schema } from "../../schema/create";
+import { internalSchema } from "../../fragments/internal-fragment";
+
+describe("GenericSQLAdapter", () => {
+  const testSchema = schema((s) => {
+    return s.addTable("products", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("name", column("string"))
+        .addColumn("price", column("integer"))
+        .createIndex("name_idx", ["name"]);
+    });
+  });
+
+  it("Should be able to query using GenericSQLAdapter", async () => {
+    const { dialect } = new SQLocalKysely(":memory:");
+    const driverConfig = new SQLocalDriverConfig();
+
+    const adapter = new GenericSQLAdapter({ dialect, driverConfig });
+
+    // Create settings table first (needed for version tracking)
+    const settingsMigrations = adapter.prepareMigrations(internalSchema, "");
+    await settingsMigrations.executeWithDriver(adapter.driver, 0);
+
+    // Now run the actual test schema migrations (use a different namespace)
+    const migrations = adapter.prepareMigrations(testSchema, "test");
+    await migrations.executeWithDriver(adapter.driver, 0);
+
+    const queryEngine = adapter.createQueryEngine(testSchema, "test");
+
+    await queryEngine.create("products", {
+      name: "test",
+      price: 100,
+    });
+
+    const product = await queryEngine.findFirst("products", (b) =>
+      b.whereIndex("name_idx", (eb) => eb("name", "=", "test")),
+    );
+
+    assert(product);
+    expect(product.name).toBe("test");
+    expect(product.price).toBe(100);
+
+    await adapter.close();
+  });
+});

package/src/adapters/generic-sql/generic-sql-adapter.ts

@@ -0,0 +1,146 @@
+import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
+import {
+  fragnoDatabaseAdapterNameFakeSymbol,
+  fragnoDatabaseAdapterVersionFakeSymbol,
+  type DatabaseAdapter,
+  type DatabaseContextStorage,
+  type TableNameMapper,
+} from "../adapters";
+import type { CompiledQuery, Dialect, QueryResult } from "../../sql-driver/sql-driver";
+import { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
+import { sql } from "../../sql-driver/sql";
+import type { AnySchema } from "../../schema/create";
+import { createTableNameMapper } from "../shared/table-name-mapper";
+import type { SimpleQueryInterface } from "../../query/simple-query-interface";
+import { createExecutor } from "./generic-sql-uow-executor";
+import { UnitOfWorkDecoder } from "./uow-decoder";
+import { createPreparedMigrations, type PreparedMigrations } from "./migration/prepared-migrations";
+import type { DriverConfig } from "./driver-config";
+import { GenericSQLUOWOperationCompiler } from "./query/generic-sql-uow-operation-compiler";
+import { createUOWCompilerFromOperationCompiler } from "../shared/uow-operation-compiler";
+import {
+  fromUnitOfWorkCompiler,
+  type UnitOfWorkFactory,
+} from "../shared/from-unit-of-work-compiler";
+
+export interface UnitOfWorkConfig {
+  onQuery?: (query: CompiledQuery) => void;
+  dryRun?: boolean;
+}
+
+export interface GenericSQLOptions {
+  dialect: Dialect;
+  driverConfig: DriverConfig;
+  uowConfig?: UnitOfWorkConfig;
+}
+
+export class GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
+  readonly dialect: Dialect;
+  readonly driverConfig: DriverConfig;
+  readonly uowConfig?: UnitOfWorkConfig;
+
+  #schemaNamespaceMap = new WeakMap<AnySchema, string>();
+  #contextStorage: RequestContextStorage<DatabaseContextStorage>;
+
+  #driver: SqlDriverAdapter;
+
+  constructor({ dialect, driverConfig, uowConfig }: GenericSQLOptions) {
+    this.dialect = dialect;
+    this.driverConfig = driverConfig;
+    this.uowConfig = uowConfig;
+
+    this.#schemaNamespaceMap = new WeakMap<AnySchema, string>();
+    this.#contextStorage = new RequestContextStorage();
+
+    this.#driver = new SqlDriverAdapter(dialect);
+  }
+
+  get driver(): SqlDriverAdapter {
+    return this.#driver;
+  }
+
+  get [fragnoDatabaseAdapterNameFakeSymbol](): string {
+    return "generic-sql";
+  }
+
+  get [fragnoDatabaseAdapterVersionFakeSymbol](): number {
+    return 0;
+  }
+
+  get contextStorage(): RequestContextStorage<DatabaseContextStorage> {
+    return this.#contextStorage;
+  }
+
+  close(): Promise<void> {
+    return this.#driver.destroy();
+  }
+
+  async isConnectionHealthy(): Promise<boolean> {
+    const result = await this.#driver.executeQuery(sql`SELECT 1 as healthy`.compile(this.dialect));
+    return result.rows[0]["healthy"] === 1;
+  }
+
+  prepareMigrations<T extends AnySchema>(schema: T, namespace: string): PreparedMigrations {
+    return createPreparedMigrations({
+      schema,
+      namespace,
+      database: this.driverConfig.databaseType,
+      mapper: namespace ? this.createTableNameMapper(namespace) : undefined,
+      driver: this.#driver,
+    });
+  }
+
+  createTableNameMapper(namespace: string): TableNameMapper {
+    return createTableNameMapper(namespace, false);
+  }
+
+  async getSchemaVersion(namespace: string): Promise<string | undefined> {
+    const key = `${namespace}.schema_version`;
+    const query = sql`SELECT value FROM fragno_db_settings WHERE key = ${key};`.compile(
+      this.dialect,
+    );
+
+    let result: QueryResult<Record<string, unknown>>;
+    try {
+      result = await this.#driver.executeQuery(query);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("fragno_db_settings")) {
+        return undefined;
+      }
+      throw error;
+    }
+
+    const value = result.rows[0]["value"];
+
+    if (!value) {
+      return undefined;
+    }
+
+    if (typeof value !== "string") {
+      throw new Error(`Schema version for namespace ${namespace} is not a string`);
+    }
+
+    return value;
+  }
+
+  createQueryEngine<T extends AnySchema>(
+    schema: T,
+    namespace: string,
+  ): SimpleQueryInterface<T, UnitOfWorkConfig> {
+    this.#schemaNamespaceMap.set(schema, namespace);
+
+    const operationCompiler = new GenericSQLUOWOperationCompiler(this.driverConfig, (ns) =>
+      ns ? this.createTableNameMapper(ns) : undefined,
+    );
+
+    const factory: UnitOfWorkFactory = {
+      compiler: createUOWCompilerFromOperationCompiler(operationCompiler),
+      executor: createExecutor(this.#driver, this.driverConfig, false),
+      decoder: new UnitOfWorkDecoder(this.driverConfig),
+      uowConfig: this.uowConfig,
+      schemaNamespaceMap: this.#schemaNamespaceMap,
+    };
+
+    return fromUnitOfWorkCompiler(schema, factory);
+  }
+}

package/src/adapters/generic-sql/generic-sql-uow-executor.ts

@@ -0,0 +1,130 @@
+import type {
+  CompiledMutation,
+  MutationResult,
+  UOWExecutor,
+} from "../../query/unit-of-work/unit-of-work";
+import type { CompiledQuery } from "../../sql-driver/sql-driver";
+import type { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
+import type { DriverConfig } from "./driver-config";
+import { ResultInterpreter } from "./result-interpreter";
+
+export async function executeRetrieval(
+  adapter: SqlDriverAdapter,
+  retrievalBatch: CompiledQuery[],
+): Promise<unknown[]> {
+  if (retrievalBatch.length === 0) {
+    return [];
+  }
+
+  const retrievalResults: unknown[] = [];
+
+  await adapter.transaction(async (tx) => {
+    for (const compiledQuery of retrievalBatch) {
+      const result = await tx.executeQuery(compiledQuery);
+      retrievalResults.push(result.rows);
+    }
+  });
+
+  return retrievalResults;
+}
+
+export async function executeMutation(
+  adapter: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  mutationBatch: CompiledMutation<CompiledQuery>[],
+): Promise<MutationResult> {
+  if (mutationBatch.length === 0) {
+    return { success: true, createdInternalIds: [] };
+  }
+
+  const createdInternalIds: (bigint | null)[] = [];
+  const resultInterpreter = new ResultInterpreter(driverConfig);
+
+  try {
+    await adapter.transaction(async (tx) => {
+      for (const compiledMutation of mutationBatch) {
+        const result = await tx.executeQuery(compiledMutation.query);
+
+        // Extract internal ID for INSERT operations
+        if (compiledMutation.op === "create") {
+          // Only try to extract internal ID if driver supports RETURNING
+          // If not supported, push null (expected case - system falls back to subqueries)
+          if (driverConfig.supportsReturning && driverConfig.internalIdColumn) {
+            const internalId = resultInterpreter.getCreatedInternalId(result);
+            createdInternalIds.push(internalId);
+          } else {
+            // Driver doesn't support RETURNING - this is expected, push null
+            createdInternalIds.push(null);
+          }
+        } else if (
+          (compiledMutation.op === "update" || compiledMutation.op === "delete") &&
+          compiledMutation.expectedAffectedRows !== null
+        ) {
+          // Check affected rows for updates/deletes
+          const affectedRows = resultInterpreter.getAffectedRows(result);
+
+          if (affectedRows !== compiledMutation.expectedAffectedRows) {
+            // Version conflict detected - the UPDATE/DELETE didn't affect the expected number of rows
+            // This means either the row doesn't exist or the version has changed
+            throw new Error(
+              `Version conflict: expected ${compiledMutation.expectedAffectedRows} rows affected, but got ${affectedRows}`,
+            );
+          }
+        }
+        // "check" operations are handled below via expectedReturnedRows
+
+        if (compiledMutation.expectedReturnedRows !== null) {
+          // For SELECT queries (check operations), verify row count
+          const returnedRowCount = resultInterpreter.getReturnedRowCount(result);
+
+          if (returnedRowCount !== BigInt(compiledMutation.expectedReturnedRows)) {
+            // Version conflict detected - the SELECT didn't return the expected number of rows
+            // This means either the row doesn't exist or the version has changed
+            throw new Error(
+              `Version conflict: expected ${compiledMutation.expectedReturnedRows} rows returned, but got ${returnedRowCount}`,
+            );
+          }
+        }
+      }
+    });
+
+    return { success: true, createdInternalIds };
+  } catch (error) {
+    // Transaction failed - could be version conflict or other constraint violation
+    // Return success=false to indicate the UOW should be retried
+    if (error instanceof Error && error.message.includes("Version conflict")) {
+      return { success: false };
+    }
+
+    // Other database errors should be thrown
+    throw error;
+  }
+}
+
+export function createExecutor(
+  adapter: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  dryRun?: boolean,
+): UOWExecutor<CompiledQuery, unknown> {
+  return {
+    async executeRetrievalPhase(retrievalBatch: CompiledQuery[]) {
+      // In dryRun mode, skip execution and return empty results
+      if (dryRun) {
+        return retrievalBatch.map(() => []);
+      }
+
+      return executeRetrieval(adapter, retrievalBatch);
+    },
+    async executeMutationPhase(mutationBatch: CompiledMutation<CompiledQuery>[]) {
+      // In dryRun mode, skip execution and return success with mock internal IDs
+      if (dryRun) {
+        return {
+          success: true,
+          createdInternalIds: mutationBatch.map(() => null),
+        };
+      }
+
+      return executeMutation(adapter, driverConfig, mutationBatch);
+    },
+  };
+}

package/src/adapters/generic-sql/migration/cold-kysely.ts

@@ -0,0 +1,55 @@
+import {
+  DummyDriver,
+  Kysely,
+  MysqlAdapter,
+  MysqlIntrospector,
+  MysqlQueryCompiler,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from "kysely";
+import type { SupportedDatabase } from "../driver-config";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type KyselyAny = Kysely<any>;
+
+/**
+ * Creates a Kysely instance that can only build queries, not execute them.
+ * This is used for SQL generation without requiring a database connection.
+ */
+export function createColdKysely(database: SupportedDatabase): KyselyAny {
+  switch (database) {
+    case "postgresql":
+      return new Kysely({
+        dialect: {
+          createAdapter: () => new PostgresAdapter(),
+          createDriver: () => new DummyDriver(),
+          createIntrospector: (db) => new PostgresIntrospector(db),
+          createQueryCompiler: () => new PostgresQueryCompiler(),
+        },
+      });
+
+    case "mysql":
+      return new Kysely({
+        dialect: {
+          createAdapter: () => new MysqlAdapter(),
+          createDriver: () => new DummyDriver(),
+          createIntrospector: (db) => new MysqlIntrospector(db),
+          createQueryCompiler: () => new MysqlQueryCompiler(),
+        },
+      });
+
+    case "sqlite":
+      return new Kysely({
+        dialect: {
+          createAdapter: () => new SqliteAdapter(),
+          createDriver: () => new DummyDriver(),
+          createIntrospector: (db) => new SqliteIntrospector(db),
+          createQueryCompiler: () => new SqliteQueryCompiler(),
+        },
+      });
+  }
+}