@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -1,13 +1,37 @@
+import superjson from "superjson";
+
+import { SETTINGS_NAMESPACE, internalSchema } from "../../fragments/internal-fragment.schema";
+import { createId } from "../../id";
+import { type SqlNamingStrategy } from "../../naming/sql-naming";
+import {
+  type OutboxConfig,
+  type OutboxRefLookup,
+  type OutboxRefMap,
+  encodeVersionstamp,
+  parseOutboxVersionValue,
+  versionstampToHex,
+} from "../../outbox/outbox";
+import { buildOutboxPlan, finalizeOutboxPayload } from "../../outbox/outbox-builder";
+import { createSQLSerializer } from "../../query/serialize/create-sql-serializer";
 import type {
   CompiledMutation,
   MutationResult,
   UOWExecutor,
 } from "../../query/unit-of-work/unit-of-work";
-import type { CompiledQuery } from "../../sql-driver/sql-driver";
+import { sql } from "../../sql-driver/sql";
+import type { CompiledQuery, Dialect } from "../../sql-driver/sql-driver";
 import type { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
 import type { DriverConfig } from "./driver-config";
+import { createColdKysely } from "./migration/cold-kysely";
 import { ResultInterpreter } from "./result-interpreter";
 
+export interface ExecutorOptions {
+  dryRun?: boolean;
+  dialect: Dialect;
+  outbox?: OutboxConfig;
+  namingStrategy?: SqlNamingStrategy;
+}
+
 export async function executeRetrieval(
   adapter: SqlDriverAdapter,
   retrievalBatch: CompiledQuery[],
@@ -32,6 +56,7 @@ export async function executeMutation(
   adapter: SqlDriverAdapter,
   driverConfig: DriverConfig,
   mutationBatch: CompiledMutation<CompiledQuery>[],
+  options: ExecutorOptions,
 ): Promise<MutationResult> {
   if (mutationBatch.length === 0) {
     return { success: true, createdInternalIds: [] };
@@ -39,9 +64,34 @@ export async function executeMutation(
 
   const createdInternalIds: (bigint | null)[] = [];
   const resultInterpreter = new ResultInterpreter(driverConfig);
+  const outboxEnabled = options.outbox?.enabled ?? false;
+  const shouldInclude = options.outbox?.shouldInclude;
+  const namingStrategy = options.namingStrategy ?? driverConfig.defaultNamingStrategy;
+
+  const outboxOperations = outboxEnabled
+    ? mutationBatch.flatMap((mutation) => {
+        const operation = mutation.operation;
+        if (!operation) {
+          return [];
+        }
+        if (shouldInclude && !shouldInclude(operation)) {
+          return [];
+        }
+        return [operation];
+      })
+    : [];
+
+  const outboxPlan = outboxOperations.length > 0 ? buildOutboxPlan(outboxOperations) : null;
+  const shouldWriteOutbox = outboxEnabled && outboxPlan !== null && outboxPlan.drafts.length > 0;
 
   try {
     await adapter.transaction(async (tx) => {
+      let outboxVersion: bigint | null = null;
+
+      if (shouldWriteOutbox) {
+        outboxVersion = await reserveOutboxVersion(tx, driverConfig, options.dialect);
+      }
+
       for (const compiledMutation of mutationBatch) {
         const result = await tx.executeQuery(compiledMutation.query);
 
@@ -86,6 +136,36 @@ export async function executeMutation(
           }
         }
       }
+
+      if (shouldWriteOutbox && outboxPlan && outboxVersion !== null) {
+        const uowId = mutationBatch[0]?.uowId;
+        if (!uowId) {
+          throw new Error("Outbox mutation batch is missing uowId.");
+        }
+
+        const refMap = await resolveOutboxRefMap(
+          tx,
+          driverConfig,
+          outboxPlan.lookups,
+          namingStrategy,
+        );
+        const payload = finalizeOutboxPayload(outboxPlan, outboxVersion);
+        const payloadSerialized = superjson.serialize(payload);
+        const versionstamp = versionstampToHex(encodeVersionstamp(outboxVersion, 0));
+
+        await insertOutboxMutationRows(tx, driverConfig, {
+          entryVersionstamp: versionstamp,
+          uowId,
+          mutations: payload.mutations,
+        });
+        await insertOutboxRow(tx, driverConfig, {
+          id: createId(),
+          versionstamp,
+          uowId,
+          payload: payloadSerialized,
+          refMap,
+        });
+      }
     });
 
     return { success: true, createdInternalIds };
@@ -96,6 +176,15 @@ export async function executeMutation(
       return { success: false };
     }
 
+    const errorCode =
+      typeof error === "object" && error !== null && "code" in error
+        ? (error as { code?: unknown }).code
+        : undefined;
+
+    if (errorCode === "40001" || errorCode === "40P01") {
+      return { success: false };
+    }
+
     // Other database errors should be thrown
     throw error;
   }
@@ -104,8 +193,10 @@ export async function executeMutation(
 export function createExecutor(
   adapter: SqlDriverAdapter,
   driverConfig: DriverConfig,
-  dryRun?: boolean,
+  options: ExecutorOptions,
 ): UOWExecutor<CompiledQuery, unknown> {
+  const dryRun = options.dryRun ?? false;
+
   return {
     async executeRetrievalPhase(retrievalBatch: CompiledQuery[]) {
       // In dryRun mode, skip execution and return empty results
@@ -124,7 +215,210 @@ export function createExecutor(
         };
       }
 
-      return executeMutation(adapter, driverConfig, mutationBatch);
+      return executeMutation(adapter, driverConfig, mutationBatch, options);
     },
   };
 }
+
+async function reserveOutboxVersion(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  dialect: Dialect,
+): Promise<bigint> {
+  const key = `${SETTINGS_NAMESPACE}.outbox_version`;
+  const id = createId();
+
+  switch (driverConfig.outboxVersionstampStrategy) {
+    case "insert-on-conflict-returning": {
+      const query =
+        driverConfig.databaseType === "postgresql"
+          ? sql`
+              insert into fragno_db_settings (id, key, value)
+              values (${id}, ${key}, '0')
+              on conflict (key) do update
+                set value = (fragno_db_settings.value::bigint + 1)::text
+              returning value;
+            `
+          : sql`
+              insert into fragno_db_settings (id, key, value)
+              values (${id}, ${key}, '0')
+              on conflict (key) do update
+                set value = cast(fragno_db_settings.value as integer) + 1
+              returning value;
+            `;
+
+      const result = await tx.executeQuery(query.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      return parseOutboxVersionValue(value);
+    }
+    case "update-returning": {
+      const query =
+        driverConfig.databaseType === "postgresql"
+          ? sql`
+              update fragno_db_settings
+              set value = (fragno_db_settings.value::bigint + 1)::text
+              where key = ${key}
+              returning value;
+            `
+          : sql`
+              update fragno_db_settings
+              set value = cast(fragno_db_settings.value as integer) + 1
+              where key = ${key}
+              returning value;
+            `;
+
+      const result = await tx.executeQuery(query.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      if (value === undefined) {
+        throw new Error("Outbox version row was not found for update-returning strategy.");
+      }
+      return parseOutboxVersionValue(value);
+    }
+    case "insert-on-duplicate-last-insert-id": {
+      const insertQuery = sql`
+        insert into fragno_db_settings (id, key, value)
+        values (${id}, ${key}, LAST_INSERT_ID(0))
+        on duplicate key update value = LAST_INSERT_ID(cast(value as unsigned) + 1);
+      `;
+
+      await tx.executeQuery(insertQuery.compile(dialect));
+
+      const selectQuery = sql`select LAST_INSERT_ID() as value;`;
+      const result = await tx.executeQuery(selectQuery.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      return parseOutboxVersionValue(value);
+    }
+  }
+}
+
+async function resolveOutboxRefMap(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  lookups: OutboxRefLookup[],
+  namingStrategy: SqlNamingStrategy,
+): Promise<OutboxRefMap | undefined> {
+  if (lookups.length === 0) {
+    return undefined;
+  }
+
+  const refMap: OutboxRefMap = {};
+  const db = createColdKysely(driverConfig.databaseType);
+
+  for (const lookup of lookups) {
+    const namespace = lookup.namespace ?? null;
+    const logicalTable = lookup.table.name;
+    const schemaName =
+      namingStrategy.namespaceScope === "schema" && namespace && namespace.length > 0
+        ? namingStrategy.namespaceToSchema(namespace)
+        : null;
+    const scopedDb = schemaName ? db.withSchema(schemaName) : db;
+    const tableName = namingStrategy.tableName(logicalTable, namespace);
+    const internalColumn = namingStrategy.columnName(
+      lookup.table.getInternalIdColumn().name,
+      logicalTable,
+    );
+    const externalColumn = namingStrategy.columnName(lookup.table.getIdColumn().name, logicalTable);
+
+    const query = scopedDb
+      .selectFrom(tableName)
+      .select(externalColumn)
+      .where(internalColumn, "=", lookup.internalId)
+      .compile();
+
+    const result = await tx.executeQuery(query);
+    const row = result.rows[0] as Record<string, unknown> | undefined;
+    const externalId = row?.[externalColumn];
+
+    if (typeof externalId !== "string") {
+      throw new Error(
+        `Failed to resolve outbox reference for ${tableName}.${internalColumn}=${String(lookup.internalId)}`,
+      );
+    }
+
+    refMap[lookup.key] = externalId;
+  }
+
+  return Object.keys(refMap).length > 0 ? refMap : undefined;
+}
+
+async function insertOutboxRow(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  options: {
+    id: string;
+    versionstamp: string;
+    uowId: string;
+    payload: { json: unknown; meta?: Record<string, unknown> };
+    refMap?: OutboxRefMap;
+  },
+): Promise<void> {
+  const { id, versionstamp, uowId, payload, refMap } = options;
+  const refMapValue = refMap ?? null;
+  const serializer = createSQLSerializer(driverConfig);
+  const outboxTable = internalSchema.tables.fragno_db_outbox;
+  const values = { id, versionstamp, uowId, payload, refMap: refMapValue };
+  const serializedValues: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values)) {
+    const col = outboxTable.getColumnByName(key);
+    if (!col) {
+      serializedValues[key] = value;
+      continue;
+    }
+    serializedValues[col.name] = serializer.serialize(value, col);
+  }
+  const db = createColdKysely(driverConfig.databaseType);
+
+  const query = db.insertInto("fragno_db_outbox").values(serializedValues).compile();
+
+  await tx.executeQuery(query);
+}
+
+async function insertOutboxMutationRows(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  options: {
+    entryVersionstamp: string;
+    uowId: string;
+    mutations: {
+      versionstamp: string;
+      schema: string;
+      table: string;
+      externalId: string;
+      op: string;
+    }[];
+  },
+): Promise<void> {
+  if (options.mutations.length === 0) {
+    return;
+  }
+
+  const serializer = createSQLSerializer(driverConfig);
+  const mutationsTable = internalSchema.tables.fragno_db_outbox_mutations;
+  const db = createColdKysely(driverConfig.databaseType);
+
+  for (const mutation of options.mutations) {
+    const values = {
+      id: createId(),
+      entryVersionstamp: options.entryVersionstamp,
+      mutationVersionstamp: mutation.versionstamp,
+      uowId: options.uowId,
+      schema: mutation.schema,
+      table: mutation.table,
+      externalId: mutation.externalId,
+      op: mutation.op,
+    };
+    const serializedValues: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(values)) {
+      const col = mutationsTable.getColumnByName(key);
+      if (!col) {
+        serializedValues[key] = value;
+        continue;
+      }
+      serializedValues[col.name] = serializer.serialize(value, col);
+    }
+
+    const query = db.insertInto("fragno_db_outbox_mutations").values(serializedValues).compile();
+    await tx.executeQuery(query);
+  }
+}

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

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DummyDriver,
+  MysqlAdapter,
+  MysqlQueryCompiler,
+  PostgresAdapter,
+  PostgresQueryCompiler,
+  SqliteAdapter,
+  SqliteQueryCompiler,
+} from "kysely";
+
+import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
+import type { Dialect } from "../../../sql-driver/sql-driver";
+import {
+  MySQL2DriverConfig,
+  NodePostgresDriverConfig,
+  SQLocalDriverConfig,
+} from "../driver-config";
+import { SqlAdapter } from "../generic-sql-adapter";
+
+const paritySchema = schema("parity", (s) => {
+  return s
+    .addTable("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .addColumn(
+          "createdAt",
+          column("timestamp").defaultTo((b) => b.now()),
+        )
+        .createIndex("users_email_idx", ["email"], { unique: true });
+    })
+    .alterTable("users", (t) => {
+      return t.addColumn("age", column("integer").nullable()).createIndex("users_age_idx", ["age"]);
+    })
+    .addTable("posts", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("authorId", referenceColumn())
+        .addColumn("title", column("string"))
+        .addColumn("isPublished", column("bool").defaultTo(false))
+        .createIndex("posts_author_idx", ["authorId"]);
+    })
+    .addReference("author", {
+      type: "one",
+      from: { table: "posts", column: "authorId" },
+      to: { table: "users", column: "id" },
+    });
+});
+
+function createDummyDialect(database: "postgresql" | "mysql" | "sqlite"): Dialect {
+  switch (database) {
+    case "postgresql":
+      return {
+        createAdapter: () => new PostgresAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => new PostgresQueryCompiler(),
+      };
+    case "mysql":
+      return {
+        createAdapter: () => new MysqlAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => new MysqlQueryCompiler(),
+      };
+    case "sqlite":
+      return {
+        createAdapter: () => new SqliteAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => new SqliteQueryCompiler(),
+      };
+  }
+}
+
+function getMigrationSql(adapter: SqlAdapter, namespace: string): string[] {
+  const prepared = adapter.prepareMigrations(paritySchema, namespace);
+  const migration = prepared.compile(0, paritySchema.version, {
+    updateVersionInMigration: false,
+  });
+  return migration.statements.map((statement) => statement.sql);
+}
+
+describe("migration SQL parity across SqlAdapter instances", () => {
+  const cases = [
+    {
+      name: "postgresql",
+      driverConfig: new NodePostgresDriverConfig(),
+    },
+    {
+      name: "sqlite",
+      driverConfig: new SQLocalDriverConfig(),
+    },
+    {
+      name: "mysql",
+      driverConfig: new MySQL2DriverConfig(),
+    },
+  ] as const;
+
+  for (const testCase of cases) {
+    it(`generates identical SQL for ${testCase.name}`, () => {
+      const dialect = createDummyDialect(testCase.name);
+      const namespace = "parity";
+
+      const firstAdapter = new SqlAdapter({
+        dialect,
+        driverConfig: testCase.driverConfig,
+      });
+
+      const secondAdapter = new SqlAdapter({
+        dialect,
+        driverConfig: testCase.driverConfig,
+      });
+
+      const firstSql = getMigrationSql(firstAdapter, namespace);
+      const secondSql = getMigrationSql(secondAdapter, namespace);
+
+      expect(firstSql).toEqual(secondSql);
+    });
+  }
+});

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

@@ -11,6 +11,7 @@ import {
   SqliteIntrospector,
   SqliteQueryCompiler,
 } from "kysely";
+
 import type { SupportedDatabase } from "../driver-config";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/adapters/generic-sql/migration/dialect/mysql.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
+
 import type { MigrationOperation } from "../../../../migration-engine/shared";
+import { createNamingResolver, type SqlNamingStrategy } from "../../../../naming/sql-naming";
+import { column, idColumn, schema } from "../../../../schema/create";
 import { createColdKysely } from "../cold-kysely";
 import { MySQLSQLGenerator } from "./mysql";
 
@@ -194,7 +197,7 @@ describe("MySQLSQLGenerator", () => {
 
       const sql = compileOne(operation);
       expect(sql).toMatchInlineSnapshot(
-        `"create table \`users\` (\`_internalId\` bigint not null primary key auto_increment, \`name\` text not null)"`,
+        `"create table \`users\` (\`_internalId\` bigint not null  auto_increment, \`name\` text not null, constraint \`users__internalId\` primary key (\`_internalId\`))"`,
       );
     });
   });
@@ -628,6 +631,7 @@ describe("MySQLSQLGenerator", () => {
         type: "drop-foreign-key",
         table: "posts",
         name: "posts_user_id_fk",
+        referencedTable: "users",
       };
 
       const sql = compileOne(operation);
@@ -893,10 +897,25 @@ describe("MySQLSQLGenerator", () => {
   });
 
   describe("table name mapping", () => {
-    const mapper = {
-      toPhysical: (name: string) => `prefix_${name}`,
-      toLogical: (name: string) => name.replace("prefix_", ""),
+    const mappingSchema = schema("mapping", (s) =>
+      s
+        .addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("email", column("string")),
+        )
+        .addTable("posts", (t) =>
+          t.addColumn("id", idColumn()).addColumn("user_id", column("string")),
+        ),
+    );
+    const namingStrategy: SqlNamingStrategy = {
+      namespaceScope: "suffix",
+      namespaceToSchema: (namespace) => namespace,
+      tableName: (logicalTable) => `prefix_${logicalTable}`,
+      columnName: (logicalColumn) => logicalColumn,
+      indexName: (logicalIndex) => `idx_${logicalIndex}`,
+      uniqueIndexName: (logicalIndex) => `uidx_${logicalIndex}`,
+      foreignKeyName: ({ referenceName }) => referenceName,
     };
+    const resolver = createNamingResolver(mappingSchema, null, namingStrategy);
 
     it("should apply table name mapping to create-table", () => {
       const operation: MigrationOperation = {
@@ -905,7 +924,7 @@ describe("MySQLSQLGenerator", () => {
         columns: [{ name: "id", type: "integer", isNullable: false, role: "external-id" }],
       };
 
-      const statements = generator.compile([operation], mapper);
+      const statements = generator.compile([operation], resolver);
       expect(statements[1].sql).toMatchInlineSnapshot(
         `"create table \`prefix_users\` (\`id\` integer not null unique)"`,
       );
@@ -923,7 +942,7 @@ describe("MySQLSQLGenerator", () => {
         },
       };
 
-      const statements = generator.compile([operation], mapper);
+      const statements = generator.compile([operation], resolver);
       expect(statements[1].sql).toMatchInlineSnapshot(
         `"alter table \`prefix_posts\` add constraint \`posts_user_id_fk\` foreign key (\`user_id\`) references \`prefix_users\` (\`id\`) on delete restrict on update restrict"`,
       );
@@ -938,9 +957,9 @@ describe("MySQLSQLGenerator", () => {
         unique: true,
       };
 
-      const statements = generator.compile([operation], mapper);
+      const statements = generator.compile([operation], resolver);
       expect(statements[1].sql).toMatchInlineSnapshot(
-        `"create unique index \`idx_email_prefix_users\` on \`prefix_users\` (\`email\`)"`,
+        `"create unique index \`uidx_idx_email\` on \`prefix_users\` (\`email\`)"`,
       );
     });
   });

package/src/adapters/generic-sql/migration/dialect/mysql.ts

@@ -1,11 +1,12 @@
 import { type ColumnDefinitionBuilder, type CompiledQuery, type RawBuilder, sql } from "kysely";
+
 import type {
   ColumnInfo,
   ColumnOperation,
   MigrationOperation,
 } from "../../../../migration-engine/shared";
 import { isUpdated } from "../../../../migration-engine/shared";
-import type { TableNameMapper } from "../../../shared/table-name-mapper";
+import type { NamingResolver } from "../../../../naming/sql-naming";
 import { SQLGenerator } from "../sql-generator";
 
 const errors = {
@@ -69,7 +70,9 @@ export class MySQLSQLGenerator extends SQLGenerator {
    */
   protected override compileUpdateColumn(
     tableName: string,
+    logicalTableName: string,
     operation: Extract<ColumnOperation, { type: "update-column" }>,
+    resolver?: NamingResolver,
   ): CompiledQuery | CompiledQuery[] {
     const col = operation.value;
 
@@ -82,9 +85,13 @@ export class MySQLSQLGenerator extends SQLGenerator {
     }
 
     // MySQL: Use modifyColumn which requires the full column definition
-    return this.db.schema
+    return this.getSchemaBuilder(resolver)
       .alterTable(tableName)
-      .modifyColumn(operation.name, sql.raw(this.getDBType(col)), (b) => this.buildColumn(col, b))
+      .modifyColumn(
+        this.getColumnName(operation.name, logicalTableName, resolver),
+        sql.raw(this.getDBType(col)),
+        (b) => this.buildColumn(col, b),
+      )
       .compile();
   }
 
@@ -93,12 +100,44 @@ export class MySQLSQLGenerator extends SQLGenerator {
    */
   protected override compileDropForeignKey(
     operation: Extract<MigrationOperation, { type: "drop-foreign-key" }>,
-    mapper?: TableNameMapper,
+    resolver?: NamingResolver,
   ): CompiledQuery {
-    const { table, name } = operation;
-    return this.db.schema
-      .alterTable(this.getTableName(table, mapper))
-      .dropConstraint(name)
+    const { table, name, referencedTable } = operation;
+    return this.getSchemaBuilder(resolver)
+      .alterTable(this.getTableName(table, resolver))
+      .dropConstraint(this.getForeignKeyName(name, table, referencedTable, resolver))
       .compile();
   }
+
+  /**
+   * MySQL: add a named primary key constraint for the internal ID column to align naming.
+   */
+  protected override compileCreateTable(
+    operation: Extract<MigrationOperation, { type: "create-table" }>,
+    resolver?: NamingResolver,
+  ): CompiledQuery {
+    const compiled = super.compileCreateTable(operation, resolver);
+    const tableName = this.getTableName(operation.name, resolver);
+    const internalIdColumn = operation.columns.find((col) => col.role === "internal-id");
+
+    if (!internalIdColumn) {
+      return compiled;
+    }
+
+    const pkColumn = this.getColumnName(internalIdColumn.name, operation.name, resolver);
+    const pkName = `${tableName}__${pkColumn.replace(/^_+/, "")}`;
+    const escapedPkColumn = pkColumn.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const columnRegex = new RegExp("`" + escapedPkColumn + "`([^,]*?)\\bprimary key\\b", "i");
+
+    let sqlText = compiled.sql.replace(columnRegex, "`" + pkColumn + "`$1");
+    sqlText = sqlText.replace(
+      /\)\s*$/,
+      ", constraint `" + pkName + "` primary key (`" + pkColumn + "`))",
+    );
+
+    return {
+      ...compiled,
+      sql: sqlText,
+    };
+  }
 }