EFCore.BulkExtensions

When performing BulkInsert on tables with Identity columns (e.g., int autoincrement), set SetOutputIdentity = true to have the database-generated IDs updated back into your entity list. This is essential when inserting related parent-child entities where the child needs the parent's new ID as a Foreign Key.

// Recommended pattern for parent-child relationships
using (var transaction = context.Database.BeginTransaction())
{
    context.BulkInsert(entities, new BulkConfig { SetOutputIdentity = true });
    foreach (var entity in entities) {
        foreach (var subEntity in entity.ItemHistories) {
            subEntity.ItemId = entity.ItemId; // Sets FK to the generated PK
        }
        subEntities.AddRange(entity.ItemHistories);
    }
    context.BulkInsert(subEntities);
    transaction.Commit();
}

For TPH models where the Discriminator is a Shadow Property, you must first add the entities to the DbSet so the discriminator value is set before calling the bulk operation.

Example:

public class Student : Person { ... }
// Add to context so Shadow property 'Discriminator' is populated
context.Students.AddRange(entities);
context.BulkInsert(entities);

Certain databases require additional configuration to support bulk operations:

• MySQL: You may need to enable local_infile by executing the SQL command: SET GLOBAL local_infile = true;.
• SQLite: Requires the SQLitePCLRaw.bundle_e_sqlite3 package and a call to SQLitePCL.Batteries.Init().

You can install the main package which supports all databases, or install provider-specific packages to reduce your project's footprint.

To install the main package using the Package Manager Console, run: Install-Package EFCore.BulkExtensions

Provider-specific packages follow the naming convention EFCore.BulkExtensions.[Provider] (e.g., EFCore.BulkExtensions.SqlServer, EFCore.BulkExtensions.PostgreSql, EFCore.BulkExtensions.MySql, EFCore.BulkExtensions.Oracle, or EFCore.BulkExtensions.Sqlite).

To prevent lock escalation in SQL Server when performing large batch operations, use a chunk-based iteration pattern with Take(chunkSize).

// Batch iteration (useful in same cases to avoid lock escalation)
do {
    rowsAffected = query.Take(chunkSize).BatchDelete();
} while (rowsAffected >= chunkSize);

EFCore.BulkExtensions is organized into provider-specific packages to minimize dependencies. You can either install the main package which includes all providers, or install only the specific provider package required for your database.

• EFCore.BulkExtensions: The main package containing all provider implementations (SqlServer, PostgreSql, MySql, Oracle, Sqlite).
• EFCore.BulkExtensions.SqlServer: For SQL Server.
• EFCore.BulkExtensions.PostgreSql: For PostgreSQL.
• EFCore.BulkExtensions.MySql: For MySQL.
• EFCore.BulkExtensions.Oracle: For Oracle.
• EFCore.BulkExtensions.Sqlite: For SQLite.

All provider-specific packages depend on EFCore.BulkExtensions.Core.

To run a MySQL instance, use the mysql image. Note that the command includes --local-infile=1 which is often required for bulk data operations. The default configuration uses:

• Database: bulk
• Root Password: MySQL22
• Port: 3306

mysql:
  image: mysql
  environment:
    - MYSQL_DATABASE=bulk
    - MYSQL_ROOT_PASSWORD=MySQL22
  ports:
    - "3306:3306"
  volumes:
    - mysql_data:/var/lib/mysql_data
  command: --local-infile=1

To run an Oracle Express Edition instance, use the gvenzl/oracle-xe image. The default configuration uses:

• Password: Oracle
• Port: 1521

oracle:
  image: gvenzl/oracle-xe
  environment:
    - ORACLE_PASSWORD=Oracle
  ports:
    - "1521:1521"
  volumes:
    - oracle_data:/opt/oracle/oradata

To run Microsoft SQL Server, use the mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04 image. The default configuration uses:

• SA Password: SuperSecret42!
• Port: 1433
• EULA: Must be set to Y

sqlserver:
  image: mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04
  environment:
    - SA_PASSWORD=SuperSecret42!
    - ACCEPT_EULA=Y
  ports:
    - "1433:1433"

To run a PostgreSQL instance with PostGIS support for testing, use the postgis/postgis image. The default configuration uses the following credentials:

• User: postgres
• Password: Postgres22
• Database: bulk
• Port: 5432

postgres:
  image: "postgis/postgis"
  ports:
    - "5432:5432"
  environment:
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=Postgres22
    - POSTGRES_DB=bulk
  volumes:
    - postgis_data:/var/lib/postgresql/data

By default, each Bulk operation is a separate transaction and is automatically committed. To group multiple Bulk operations into a single atomic transaction, use context.Database.BeginTransaction().

using (var transaction = context.Database.BeginTransaction())
{
    context.BulkInsert(entities1List);
    context.BulkInsert(entities2List);
    transaction.Commit();
}

// or with C# 8.0+ syntax
using var transaction = context.Database.BeginTransaction();
context.BulkInsert(entities1List);
context.BulkInsert(entities2List);
transaction.Commit();