DuckDB (Bulk)

This page contains the latest information of the releases of RepoDb.DuckDb.BulkOperations library.

View the NuGet package here or download it directly here.

RepoDb.DuckDb.BulkOperations (v0.0.1-alpha1) - Preview

Released: September 25, 2026

New

First (alpha) release of the bulk operations extension for RepoDb.DuckDb, built on DuckDB.NET’s native DuckDBAppender (via the DuckDbBulkAppender wrapper). #1348

What’s included

• BulkInsert, BulkMerge, BulkUpdate, BulkDelete, and BulkDeleteByKey, each with an Async overload — callable against a DuckDBConnection, a BaseRepository<TEntity, DuckDBConnection>, or a DbRepository<DuckDBConnection>, with an entity list, a DataTable, or an IDataReader (BulkDeleteByKey takes a list of primary key values instead).
• DuckDbBulkImportIdentityBehavior (KeepIdentity default, ReturnIdentity) — controls whether identity values are sent as-is or read back. ReturnIdentity reads the generated values back via a RETURNING clause on the same statement that loads the staged rows into the real table.
• DuckDbBulkImportPseudoTableType (Auto, Memory, Physical) — selects the staging-table strategy backing BulkInsert (when ReturnIdentity is used), BulkMerge, BulkUpdate, BulkDelete, and BulkDeleteByKey.
• DuckDbBulkAppender / DuckDbBulkAppenderColumnMappingCollection — a public wrapper around DuckDBAppender that every bulk operation writes through internally; usable directly for custom bulk-write scenarios.
• DuckDbBulkInsertMapItem — explicit source-to-destination column mapping for BulkInsert/BulkMerge/BulkUpdate, with the destination type always resolved from the table’s own schema (no per-mapping type override).
• DuckDbTraceKeys — the traceKey constants for use with a custom ITrace.
• BulkMerge/BulkUpdate/BulkDelete/BulkDeleteByKey always stage through a pseudo (temporary, by default) table; BulkInsert writes straight into the target table unless identityBehavior is ReturnIdentity.
• Referenced the RepoDb package v1.17.0-alpha2.
• Referenced the RepoDb.DuckDb package v0.0.1-alpha1.
• References the DuckDB.NET.Data.Full package v1.5.5.

Known limitations (v1)

• DuckDbBulkImportPseudoTableType.Auto’s row-count-based resolution is not implemented yet — it currently maps straight to Memory on every call, regardless of row count.
• BulkMerge with ReturnIdentity does not use a single atomic MERGE: it snapshots matched/unmatched rows with a LEFT JOIN (ordered by the pseudo table’s rowid), issues a separate UPDATE ... FROM for the matches, then a separate insert-only INSERT ... WHERE NOT EXISTS ... RETURNING for the unmatched rows — three round trips instead of one, and the classification can go stale if another connection modifies the target table between the snapshot and the follow-up statements.
• Every bulk call creates its own pseudo table and drops it once the call completes, rather than reusing one across calls.
• No Unspecified identity-behavior state — DuckDbBulkImportIdentityBehavior defaults straight to KeepIdentity.
• DuckDbBulkInsertMapItem carries no per-mapping database-type override, unlike some other providers’ mapping classes — the destination column’s type is always taken from the table’s own schema.