@sixb/ducklake 0.0.1 → 0.1.1

package/src/internal/dataset-row-merge.ts

@@ -0,0 +1,268 @@
+import type { DatasetDefinition } from "@sixb/core"
+import { getDatasetPrimaryKeyColumns, LakeStorageError } from "@sixb/core/lake-storage"
+import type { DuckLakeStorageOptions } from "../types"
+import { type ApplyDatasetRowsResult, inspectUniqueKeyedRelation } from "./dataset-row-commit"
+import { getBigIntLike } from "./duckdb-row"
+import type { DuckDbQueryRuntime } from "./duckdb-runtime"
+import { encodeDatasetTableName } from "./names"
+import { datasetSchemaColumnNamesSql } from "./schema"
+import { qualifiedTableName, quoteIdentifier, quoteSqlString } from "./sql"
+
+export interface ApplyDatasetMergeFromRelationInput {
+  readonly options: DuckLakeStorageOptions
+  readonly runtime: DuckDbQueryRuntime
+  readonly dataset: DatasetDefinition
+  readonly stagingTableName: string
+  readonly sequenceColumnName: string
+  readonly kindColumnName: string
+  readonly previousRowCount?: number
+  readonly validatedPrimaryKeyColumns?: readonly string[]
+}
+
+interface MergeEffectCounts {
+  readonly inserts: number
+  readonly updates: number
+  readonly deletes: number
+}
+
+export async function applyDatasetMergeFromRelation(
+  input: ApplyDatasetMergeFromRelationInput
+): Promise<ApplyDatasetRowsResult> {
+  const primaryKeyColumns = getDatasetPrimaryKeyColumns(input.dataset)
+  if (primaryKeyColumns === null) {
+    throw new LakeStorageError(
+      `[SixbDuckLake] Dataset '${input.dataset.id}' must define a primaryKey before it can be merged.`
+    )
+  }
+
+  const stagingTable = quoteIdentifier(input.stagingTableName)
+  const targetTable = qualifiedTableName(input.options, encodeDatasetTableName(input.dataset.id))
+  const sourceRowCount = await countRows(input.runtime, stagingTable)
+  const previousRowCount = await currentBaselineRowCount(input, targetTable, primaryKeyColumns)
+
+  return withMaterializedFinalChanges(input, primaryKeyColumns, async (finalChanges) => {
+    const effects = await countMergeEffects(input, targetTable, finalChanges, primaryKeyColumns)
+    const effectiveChangeCount = effects.inserts + effects.updates + effects.deletes
+
+    if (effectiveChangeCount === 0) {
+      return {
+        dataChangeExpected: false,
+        sourceRowCount,
+        resultingRowCount: { kind: "exact", value: previousRowCount },
+      }
+    }
+
+    const keyMatchSql = primaryKeyMatchSql(primaryKeyColumns, "target", "source")
+    const rowDifferenceSql = datasetRowDifferenceSql(input.dataset, "target", "source")
+    const kindColumn = `source.${quoteIdentifier(input.kindColumnName)}`
+
+    await input.runtime.run(`
+      DELETE FROM ${targetTable} AS target
+      USING ${finalChanges} AS source
+      WHERE ${keyMatchSql}
+        AND (
+          ${kindColumn} = ${quoteSqlString("delete")}
+          OR (
+            ${kindColumn} = ${quoteSqlString("upsert")}
+            AND (${rowDifferenceSql})
+          )
+        )
+    `)
+
+    const columnsSql = datasetSchemaColumnNamesSql(input.dataset.schema)
+    const selectedColumnsSql = input.dataset.schema.columns
+      .map((column) => `source.${quoteIdentifier(column.name)}`)
+      .join(", ")
+    const firstSequenceColumnName = firstSequenceName(input.sequenceColumnName)
+    await input.runtime.run(`
+      INSERT INTO ${targetTable} (${columnsSql})
+      SELECT ${selectedColumnsSql}
+      FROM ${finalChanges} AS source
+      WHERE ${kindColumn} = ${quoteSqlString("upsert")}
+        AND NOT EXISTS (
+          SELECT 1
+          FROM ${targetTable} AS target
+          WHERE ${keyMatchSql}
+        )
+      ORDER BY source.${quoteIdentifier(firstSequenceColumnName)}
+    `)
+
+    return {
+      dataChangeExpected: true,
+      sourceRowCount,
+      resultingRowCount: {
+        kind: "exact",
+        value: previousRowCount + effects.inserts - effects.deletes,
+      },
+    }
+  })
+}
+
+async function currentBaselineRowCount(
+  input: ApplyDatasetMergeFromRelationInput,
+  targetTable: string,
+  primaryKeyColumns: readonly string[]
+): Promise<number> {
+  // Sixb writes mark keyed versions only after the write path has enforced uniqueness. Older or
+  // external versions carry no marker and keep the full defensive audit.
+  if (sameColumns(input.validatedPrimaryKeyColumns, primaryKeyColumns)) {
+    return input.previousRowCount ?? countRows(input.runtime, targetTable)
+  }
+
+  return inspectUniqueKeyedRelation({
+    runtime: input.runtime,
+    dataset: input.dataset,
+    relationSql: targetTable,
+    context: "current baseline",
+  })
+}
+
+async function withMaterializedFinalChanges<T>(
+  input: ApplyDatasetMergeFromRelationInput,
+  primaryKeyColumns: readonly string[],
+  run: (finalChangesTable: string) => Promise<T>
+): Promise<T> {
+  const table = quoteIdentifier(`${input.stagingTableName}_final`)
+  await input.runtime.run(`
+    CREATE TEMP TABLE ${table} AS
+    ${finalChangesSelectSql(input, primaryKeyColumns)}
+  `)
+
+  let outcome:
+    | { readonly kind: "success"; readonly value: T }
+    | { readonly kind: "error"; readonly error: unknown }
+  try {
+    outcome = { kind: "success", value: await run(table) }
+  } catch (error) {
+    outcome = { kind: "error", error }
+  }
+
+  try {
+    await input.runtime.run(`DROP TABLE IF EXISTS ${table}`)
+  } catch (cleanupError) {
+    if (outcome.kind === "success") {
+      throw cleanupError
+    }
+  }
+
+  if (outcome.kind === "error") {
+    throw outcome.error
+  }
+
+  return outcome.value
+}
+
+function finalChangesSelectSql(
+  input: ApplyDatasetMergeFromRelationInput,
+  primaryKeyColumns: readonly string[]
+): string {
+  const sequenceColumn = quoteIdentifier(input.sequenceColumnName)
+  const keyColumnsSql = primaryKeyColumns.map((column) => quoteIdentifier(column)).join(", ")
+  const rankColumn = quoteIdentifier(rankName(input.sequenceColumnName))
+  const firstSequenceColumn = quoteIdentifier(firstSequenceName(input.sequenceColumnName))
+
+  return `
+    SELECT * EXCLUDE (${rankColumn})
+    FROM (
+      SELECT
+        *,
+        min(${sequenceColumn}) OVER (PARTITION BY ${keyColumnsSql}) AS ${firstSequenceColumn},
+        row_number() OVER (
+          PARTITION BY ${keyColumnsSql}
+          ORDER BY ${sequenceColumn} DESC
+        ) AS ${rankColumn}
+      FROM ${quoteIdentifier(input.stagingTableName)}
+    ) ranked_changes
+    WHERE ${rankColumn} = 1
+  `
+}
+
+async function countMergeEffects(
+  input: ApplyDatasetMergeFromRelationInput,
+  targetTable: string,
+  finalChanges: string,
+  primaryKeyColumns: readonly string[]
+): Promise<MergeEffectCounts> {
+  const matchColumn = primaryKeyColumns[0]
+  if (matchColumn === undefined) {
+    throw new LakeStorageError(
+      `[SixbDuckLake] Dataset '${input.dataset.id}' primaryKey must contain at least one column.`
+    )
+  }
+
+  const keyMatchSql = primaryKeyMatchSql(primaryKeyColumns, "target", "source")
+  const targetMatch = `target.${quoteIdentifier(matchColumn)} IS NOT NULL`
+  const kindColumn = `source.${quoteIdentifier(input.kindColumnName)}`
+  const rowDifferenceSql = datasetRowDifferenceSql(input.dataset, "target", "source")
+  const [row] = await input.runtime.query(`
+    SELECT
+      count(*) FILTER (
+        WHERE ${kindColumn} = ${quoteSqlString("upsert")} AND NOT (${targetMatch})
+      ) AS insert_count,
+      count(*) FILTER (
+        WHERE ${kindColumn} = ${quoteSqlString("upsert")}
+          AND ${targetMatch}
+          AND (${rowDifferenceSql})
+      ) AS update_count,
+      count(*) FILTER (
+        WHERE ${kindColumn} = ${quoteSqlString("delete")} AND ${targetMatch}
+      ) AS delete_count
+    FROM ${finalChanges} AS source
+    LEFT JOIN ${targetTable} AS target ON ${keyMatchSql}
+  `)
+
+  return {
+    inserts: row === undefined ? 0 : Number(getBigIntLike(row, "insert_count")),
+    updates: row === undefined ? 0 : Number(getBigIntLike(row, "update_count")),
+    deletes: row === undefined ? 0 : Number(getBigIntLike(row, "delete_count")),
+  }
+}
+
+function primaryKeyMatchSql(
+  primaryKeyColumns: readonly string[],
+  leftAlias: string,
+  rightAlias: string
+): string {
+  return primaryKeyColumns
+    .map(
+      (column) =>
+        `${leftAlias}.${quoteIdentifier(column)} = ${rightAlias}.${quoteIdentifier(column)}`
+    )
+    .join(" AND ")
+}
+
+function datasetRowDifferenceSql(
+  dataset: DatasetDefinition,
+  leftAlias: string,
+  rightAlias: string
+): string {
+  return dataset.schema.columns
+    .map(
+      (column) =>
+        `${leftAlias}.${quoteIdentifier(column.name)} IS DISTINCT FROM ${rightAlias}.${quoteIdentifier(
+          column.name
+        )}`
+    )
+    .join(" OR ")
+}
+
+async function countRows(runtime: DuckDbQueryRuntime, relationSql: string): Promise<number> {
+  const [row] = await runtime.query(`SELECT count(*) AS row_count FROM ${relationSql}`)
+  return row === undefined ? 0 : Number(getBigIntLike(row, "row_count"))
+}
+
+function rankName(sequenceColumnName: string): string {
+  return `${sequenceColumnName}_rank`
+}
+
+function firstSequenceName(sequenceColumnName: string): string {
+  return `${sequenceColumnName}_first`
+}
+
+function sameColumns(left: readonly string[] | undefined, right: readonly string[]): boolean {
+  return (
+    left !== undefined &&
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  )
+}

package/src/internal/ducklake-catalog-schema.ts

@@ -1,4 +1,4 @@
-import type { DatasetColumnDefinition, DatasetSchema } from "@sixb/core"
+import type { DatasetColumnDefinition, DatasetPrimaryKey, DatasetSchema } from "@sixb/core"
 import { LakeStorageError } from "@sixb/core/lake-storage"
 import { duckDbTypeToDatasetColumnType } from "./schema"
 
@@ -10,8 +10,12 @@ export interface DuckLakeCatalogColumn {
   readonly columnType: string
   readonly nullsAllowed: boolean
   readonly parentColumnId?: bigint
+  readonly comment?: string
 }
 
+const SIXB_PRIMARY_KEY_COMMENT_NAMESPACE = "sixb:primary-key:"
+const SIXB_PRIMARY_KEY_COMMENT_PREFIX = `${SIXB_PRIMARY_KEY_COMMENT_NAMESPACE}v1:`
+
 const FILE_REF_STRUCT_CHILDREN = [
   { name: "blobId", type: "string" },
   { name: "digest", type: "string" },
@@ -46,6 +50,91 @@ export function duckLakeCatalogColumnsToDatasetSchema(
   }
 }
 
+export function duckLakePrimaryKeyColumnComment(ordinal: number): string {
+  return `${SIXB_PRIMARY_KEY_COMMENT_PREFIX}${ordinal}`
+}
+
+export function duckLakeCatalogColumnsToDatasetPrimaryKey(
+  tableName: string,
+  rows: readonly DuckLakeCatalogColumn[]
+): DatasetPrimaryKey | undefined {
+  const keyedColumns: { readonly column: DuckLakeCatalogColumn; readonly ordinal: number }[] = []
+  const seenOrdinals = new Set<number>()
+
+  for (const column of rows) {
+    const comment = column.comment
+    if (comment === undefined || !comment.startsWith(SIXB_PRIMARY_KEY_COMMENT_NAMESPACE)) {
+      continue
+    }
+
+    if (
+      column.parentColumnId !== undefined ||
+      !comment.startsWith(SIXB_PRIMARY_KEY_COMMENT_PREFIX)
+    ) {
+      throwInvalidPrimaryKeyMetadata(tableName, column, comment)
+    }
+
+    const ordinalText = comment.slice(SIXB_PRIMARY_KEY_COMMENT_PREFIX.length)
+    if (!/^(0|[1-9]\d*)$/.test(ordinalText)) {
+      throwInvalidPrimaryKeyMetadata(tableName, column, comment)
+    }
+
+    const ordinal = Number(ordinalText)
+    if (!Number.isSafeInteger(ordinal)) {
+      throwInvalidPrimaryKeyMetadata(tableName, column, comment)
+    }
+    if (seenOrdinals.has(ordinal)) {
+      throw new LakeStorageError(
+        `[SixbDuckLake] Dataset table '${tableName}' has duplicate primary-key ordinal '${ordinal}'.`
+      )
+    }
+    seenOrdinals.add(ordinal)
+
+    if (duckDbTypeToDatasetColumnType(column.columnType) !== "string") {
+      throw new LakeStorageError(
+        `[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must map to type 'string'.`
+      )
+    }
+    if (column.nullsAllowed) {
+      throw new LakeStorageError(
+        `[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must not be nullable.`
+      )
+    }
+
+    keyedColumns.push({ column, ordinal })
+  }
+
+  if (keyedColumns.length === 0) {
+    return undefined
+  }
+
+  keyedColumns.sort((left, right) => left.ordinal - right.ordinal)
+  for (const [expectedOrdinal, keyedColumn] of keyedColumns.entries()) {
+    if (keyedColumn.ordinal !== expectedOrdinal) {
+      throw new LakeStorageError(
+        `[SixbDuckLake] Dataset table '${tableName}' primary-key ordinals must be contiguous from 0.`
+      )
+    }
+  }
+
+  const columnNames = keyedColumns.map(({ column }) => column.columnName)
+  if (columnNames.length === 1) {
+    return columnNames[0]
+  }
+
+  return columnNames as [string, string, ...string[]]
+}
+
+function throwInvalidPrimaryKeyMetadata(
+  tableName: string,
+  column: DuckLakeCatalogColumn,
+  comment: string
+): never {
+  throw new LakeStorageError(
+    `[SixbDuckLake] Dataset table '${tableName}' has malformed primary-key metadata '${comment}' on column '${column.columnName}'.`
+  )
+}
+
 function duckLakeCatalogColumnToDefinition(
   tableName: string,
   column: DuckLakeCatalogColumn,

package/src/internal/ducklake-current-dataset-definitions.ts

@@ -11,6 +11,7 @@ import {
 import type { DuckDbQueryRuntime } from "./duckdb-runtime"
 import {
   type DuckLakeCatalogColumn,
+  duckLakeCatalogColumnsToDatasetPrimaryKey,
   duckLakeCatalogColumnsToDatasetSchema,
 } from "./ducklake-catalog-schema"
 import { decodeDatasetTableName, encodeDatasetTableName } from "./names"
@@ -56,14 +57,14 @@ export async function readCurrentDatasetDefinitions(
   const definitions = new Map<string, DatasetDefinition>()
 
   for (const table of tables) {
+    const columns = columnsByTableName.get(table.tableName) ?? []
+    const primaryKey = duckLakeCatalogColumnsToDatasetPrimaryKey(table.tableName, columns)
     const partitionBy = partitionByTableName.get(table.tableName) ?? []
     definitions.set(table.datasetId, {
       kind: "dataset",
       id: table.datasetId,
-      schema: duckLakeCatalogColumnsToDatasetSchema(
-        table.tableName,
-        columnsByTableName.get(table.tableName) ?? []
-      ),
+      schema: duckLakeCatalogColumnsToDatasetSchema(table.tableName, columns),
+      ...(primaryKey !== undefined ? { primaryKey } : {}),
       ...(partitionBy.length > 0 ? { partitionBy } : {}),
       ...(table.comment !== undefined ? { description: table.comment } : {}),
     })
@@ -121,6 +122,7 @@ async function readCurrentDatasetColumns(
 
   const ducklakeTable = duckLakeMetadataTableName(input.options, "ducklake_table")
   const ducklakeColumn = duckLakeMetadataTableName(input.options, "ducklake_column")
+  const ducklakeColumnTag = duckLakeMetadataTableName(input.options, "ducklake_column_tag")
   const rows = await input.runtime.query(`
     SELECT
       table_meta.table_name,
@@ -129,11 +131,17 @@ async function readCurrentDatasetColumns(
       column_meta.column_name,
       column_meta.column_type,
       CAST(column_meta.nulls_allowed AS BOOLEAN) AS nulls_allowed,
-      column_meta.parent_column
+      column_meta.parent_column,
+      column_tag."value" AS comment
     FROM ${ducklakeTable} table_meta
     JOIN ${ducklakeColumn} column_meta
       ON column_meta.table_id = table_meta.table_id
       AND column_meta.end_snapshot IS NULL
+    LEFT JOIN ${ducklakeColumnTag} column_tag
+      ON column_tag.table_id = column_meta.table_id
+      AND column_tag.column_id = column_meta.column_id
+      AND column_tag."key" = 'comment'
+      AND column_tag.end_snapshot IS NULL
     WHERE table_meta.end_snapshot IS NULL
       AND table_meta.table_name IN (${quoteSqlStringList(tableNames)})
     ORDER BY table_meta.table_name, column_meta.column_order
@@ -147,6 +155,7 @@ async function readCurrentDatasetColumns(
     columnType: getString(row, "column_type"),
     nullsAllowed: getBoolean(row, "nulls_allowed"),
     parentColumnId: getOptionalBigIntLike(row, "parent_column"),
+    comment: getOptionalString(row, "comment"),
   }))
 }
 

package/src/internal/ducklake-dataset-catalog.ts

@@ -8,6 +8,7 @@ import type { DuckDbQueryRuntime } from "./duckdb-runtime"
 import {
   type DuckLakeCatalogColumn,
   duckLakeCatalogColumnsToDatasetSchema,
+  duckLakePrimaryKeyColumnComment,
 } from "./ducklake-catalog-schema"
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager"
 import { readCurrentDatasetDefinitions } from "./ducklake-current-dataset-definitions"
@@ -59,19 +60,32 @@ export class DuckLakeDatasetCatalog {
     const qualifiedName = qualifiedTableName(this.options, tableName)
 
     // Creating a dataset can be several catalog DDL statements. Keep them in
-    // one runtime slot so writes cannot observe a half-created table.
+    // one transaction and runtime slot so nothing can observe a partial definition.
     await this.connections.withExclusiveAttached(async (runtime) => {
-      await runtime.run(
-        `CREATE TABLE ${qualifiedName} (${datasetSchemaToDuckDbColumnsSql(definition.schema)})`
-      )
-
-      if (definition.description !== undefined) {
+      await runtime.run("BEGIN TRANSACTION")
+      let committed = false
+      try {
         await runtime.run(
-          `COMMENT ON TABLE ${qualifiedName} IS ${quoteSqlString(definition.description)}`
+          `CREATE TABLE ${qualifiedName} (${datasetSchemaToDuckDbColumnsSql(definition.schema)})`
         )
-      }
 
-      await this.applyPartitionBy(runtime, qualifiedName, definition)
+        if (definition.description !== undefined) {
+          await runtime.run(
+            `COMMENT ON TABLE ${qualifiedName} IS ${quoteSqlString(definition.description)}`
+          )
+        }
+
+        await this.applyPrimaryKey(runtime, qualifiedName, definition)
+        await this.applyPartitionBy(runtime, qualifiedName, definition)
+
+        await runtime.run("COMMIT")
+        committed = true
+      } catch (error) {
+        if (!committed) {
+          await this.rollbackTransaction(runtime)
+        }
+        throw error
+      }
     })
     this.connections.markLocalCatalogChanged()
 
@@ -289,6 +303,26 @@ export class DuckLakeDatasetCatalog {
     }
   }
 
+  private async applyPrimaryKey(
+    runtime: DuckDbQueryRuntime,
+    qualifiedName: string,
+    definition: DatasetDefinition
+  ): Promise<void> {
+    if (definition.primaryKey === undefined) {
+      return
+    }
+
+    const columnNames =
+      typeof definition.primaryKey === "string" ? [definition.primaryKey] : definition.primaryKey
+    for (const [ordinal, columnName] of columnNames.entries()) {
+      await runtime.run(
+        `COMMENT ON COLUMN ${qualifiedName}.${quoteIdentifier(columnName)} IS ${quoteSqlString(
+          duckLakePrimaryKeyColumnComment(ordinal)
+        )}`
+      )
+    }
+  }
+
   private async setSchemaEvolutionCommitMetadata(
     runtime: DuckDbQueryRuntime,
     datasetId: string,

package/src/internal/ducklake-merge-session.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto"
+import type { DatasetRow, MergeChange } from "@sixb/core"
+import type {
+  BeginDatasetMergeInput,
+  CommitDatasetMergeInput,
+  DatasetMergeCommitResult,
+  LakeMergeSession,
+} from "@sixb/core/lake-storage"
+import {
+  cloneDatasetMergeChange,
+  getDatasetMergeChangeValidationError,
+  LakeStorageError,
+} from "@sixb/core/lake-storage"
+import type { DuckDbRuntime } from "./duckdb-runtime"
+import { appendDatasetRow } from "./row-appender"
+import { datasetSchemaToDuckDbNullableColumnsSql } from "./schema"
+import { quoteIdentifier } from "./sql"
+
+export interface DuckLakeCommitMergeInput {
+  readonly merge: BeginDatasetMergeInput
+  readonly baseVersionId: string | null
+  readonly commit?: CommitDatasetMergeInput
+  readonly stagingTableName: string
+  readonly sequenceColumnName: string
+  readonly kindColumnName: string
+  readonly changesWritten: number
+}
+
+type DuckLakeCommitMerge = (input: DuckLakeCommitMergeInput) => Promise<DatasetMergeCommitResult>
+
+const MERGE_CHANGE_BATCH_SIZE = 1000
+
+interface StagedMergeChange {
+  readonly sequence: bigint
+  readonly change: MergeChange<DatasetRow, DatasetRow>
+}
+
+interface CreateDuckLakeMergeSessionInput {
+  readonly commitMerge: DuckLakeCommitMerge
+  readonly runtime: DuckDbRuntime
+  readonly merge: BeginDatasetMergeInput
+  readonly baseVersionId: string | null
+}
+
+export async function createDuckLakeMergeSession(
+  input: CreateDuckLakeMergeSessionInput
+): Promise<LakeMergeSession> {
+  const suffix = randomUUID().replaceAll("-", "")
+  const stagingTableName = `sixb_merge_${suffix}`
+  const sequenceColumnName = `sixb_merge_sequence_${suffix}`
+  const kindColumnName = `sixb_merge_kind_${suffix}`
+
+  await input.runtime.run(`
+    CREATE TEMP TABLE ${quoteIdentifier(stagingTableName)} (
+      ${quoteIdentifier(sequenceColumnName)} UBIGINT NOT NULL,
+      ${quoteIdentifier(kindColumnName)} VARCHAR NOT NULL,
+      ${datasetSchemaToDuckDbNullableColumnsSql(input.merge.dataset.schema)}
+    )
+  `)
+
+  return new DuckLakeMergeSession(
+    input.commitMerge,
+    input.runtime,
+    input.merge,
+    input.baseVersionId,
+    stagingTableName,
+    sequenceColumnName,
+    kindColumnName
+  )
+}
+
+class DuckLakeMergeSession implements LakeMergeSession {
+  private closed = false
+  private cleanedUp = false
+  private nextSequence = 0n
+  private changesWritten = 0
+
+  constructor(
+    private readonly commitMerge: DuckLakeCommitMerge,
+    private readonly runtime: DuckDbRuntime,
+    private readonly input: BeginDatasetMergeInput,
+    private readonly baseVersionId: string | null,
+    private readonly stagingTableName: string,
+    private readonly sequenceColumnName: string,
+    private readonly kindColumnName: string
+  ) {}
+
+  async writeChanges(
+    changes:
+      | Iterable<MergeChange<DatasetRow, DatasetRow>>
+      | AsyncIterable<MergeChange<DatasetRow, DatasetRow>>
+  ): Promise<void> {
+    this.assertOpen()
+
+    let batch: StagedMergeChange[] = []
+    for await (const change of changes) {
+      const validationError = getDatasetMergeChangeValidationError(change, this.input.dataset)
+      if (validationError) {
+        throw new LakeStorageError(`[SixbDuckLake] ${validationError}`)
+      }
+
+      batch.push({
+        sequence: this.nextSequence,
+        change: cloneDatasetMergeChange(change),
+      })
+      this.nextSequence += 1n
+
+      if (batch.length >= MERGE_CHANGE_BATCH_SIZE) {
+        await this.appendBatchToStagingTable(batch)
+        batch = []
+      }
+    }
+
+    if (batch.length > 0) {
+      await this.appendBatchToStagingTable(batch)
+    }
+  }
+
+  private async appendBatchToStagingTable(batch: readonly StagedMergeChange[]): Promise<void> {
+    await this.runtime.withAppender(this.stagingTableName, (appender) => {
+      for (const staged of batch) {
+        appender.appendBigInt(staged.sequence)
+        appender.appendVarchar(staged.change.kind)
+        appendDatasetRow(
+          appender,
+          this.input.dataset.schema,
+          staged.change.kind === "upsert" ? staged.change.row : staged.change.key
+        )
+      }
+    })
+    this.changesWritten += batch.length
+  }
+
+  async commit(input?: CommitDatasetMergeInput): Promise<DatasetMergeCommitResult> {
+    this.assertOpen()
+    this.closed = true
+
+    let committed = false
+    try {
+      const result = await this.commitMerge({
+        merge: this.input,
+        baseVersionId: this.baseVersionId,
+        commit: input,
+        stagingTableName: this.stagingTableName,
+        sequenceColumnName: this.sequenceColumnName,
+        kindColumnName: this.kindColumnName,
+        changesWritten: this.changesWritten,
+      })
+      committed = true
+      await this.cleanup()
+      return result
+    } catch (error) {
+      if (!committed) {
+        await this.cleanup()
+      }
+      throw error
+    }
+  }
+
+  async abort(): Promise<void> {
+    if (this.closed) {
+      return
+    }
+
+    this.closed = true
+    await this.cleanup()
+  }
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new LakeStorageError("[SixbDuckLake] Merge session is already closed.")
+    }
+  }
+
+  private async cleanup(): Promise<void> {
+    if (this.cleanedUp) {
+      return
+    }
+
+    this.cleanedUp = true
+    try {
+      await this.runtime.run(`DROP TABLE IF EXISTS ${quoteIdentifier(this.stagingTableName)}`)
+    } catch {
+      // Preserve the commit/abort outcome. Temp tables disappear when the storage runtime closes.
+    }
+  }
+}