DB Extensions

Welcome to DbExtensions

Mon, 01 Jan 0001 00:00:00 +0000

Why ETLBox.DbExtensions?

Dapper is excellent at reading data. It is not a bulk writer. The usual workaround — a loop of INSERT/UPDATE/DELETE — is not only verbose. It costs one round-trip per row and gets slow as soon as the set grows.

Installation and Setup

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Before you get started, make sure your environment meets the following requirements:

ETLBox.DbExtensions supports all current .NET versions supported by Microsoft, including .NET 8/9 or later and .NET Framework 4.8.0 or later
Required: A supported ETLBox database provider package, e.g. ETLBox.SqlServer or ETLBox.Postgres
Recommended IDEs: Visual Studio 2022 , Visual Studio Code , or JetBrains Rider
Basic knowledge of C# and working with NuGet packages

Install via NuGet

Add the following packages to your project:

Bulk Insert

Mon, 01 Jan 0001 00:00:00 +0000

Use BulkInsert when you would otherwise loop INSERT statements — imports, staging loads, test data. On SQL Server this is SqlBulkCopy under the hood; you keep your POCOs instead of a DataTable.

DbExtensions Overview

Mon, 01 Jan 0001 00:00:00 +0000

ETLBox.DbExtensions addresses this gap by adding high-performance bulk operations directly to IDbConnection. It integrates cleanly with existing ADO.NET and Dapper workflows while keeping the API minimal and easy to adopt.

Bulk Update

Mon, 01 Jan 0001 00:00:00 +0000

Use BulkUpdate when many rows change at once (status flags, recalculated fields, sync from another system). Mark the key with [IdColumn] (or set IdColumns in options). A Dapper UPDATE in a loop is simpler for a few rows and much slower for thousands.

Performance

Mon, 01 Jan 0001 00:00:00 +0000

SQL Server, 5,000 rows

Measured with the DbExtensions.Benchmark project in etlbox.demo. Release build, local SQL Server, catalog demo. The Dapper baseline is one Execute per row — the pattern you write when Dapper has no bulk API.

Bulk Delete

Mon, 01 Jan 0001 00:00:00 +0000

Use BulkDelete to remove a known set of keys without building a giant IN (...) list or issuing one DELETE per row. Identify rows with [IdColumn] (or IdColumns in options).

Compared to

Mon, 01 Jan 0001 00:00:00 +0000

Dapper

Use Dapper for queries. Use DbExtensions when the next step is writing many rows.

using var connection = new SqlConnection(connectionString);

var customers = connection
 .Query<Customer>("SELECT * FROM Customer WHERE Active = 1")
 .ToList();

connection.BulkUpdate(customers);

A foreach + Execute is fine for a handful of rows. At thousands of rows it is the slow path we measured: one round-trip each. DbExtensions keeps your POCOs and the same connection.

Bulk Merge

Mon, 01 Jan 0001 00:00:00 +0000

Use BulkMerge when the source set should become the table (or a delta of it): insert missing rows, update existing ones, optionally delete rows that are no longer in the source. That is the operation where a Dapper select-then-insert-or-update loop hurts most.

Bulk Options

Mon, 01 Jan 0001 00:00:00 +0000

This article describes all available options for BulkInsert(), BulkUpdate(), and BulkDelete() via BulkOptions<T>, and explains which options apply specifically to BulkMerge() via MergeBulkOptions<T>.