BulkFlowKit.Core 1.0.2

BulkFlowKit - High-Performance EF Core Bulk Operations

BulkFlowKit is a professional, high-performance open-source library for bulk insert, update, and delete operations in Entity Framework Core.

Features

• BulkInsert - Bulk data insertion
• BulkUpdate - Bulk data updates
• BulkDelete - Bulk data deletion
• 5 Database Support: SQL Server, PostgreSQL, MySQL, SQLite, Oracle
• EF Core 6, 8 support
• Batch Processing - Automatic batch processing for large datasets
• Progress Callback - Progress tracking
• Transaction Support - Compatible with existing transactions
• ContinueOnError - Skip failed batches and continue processing
• Primary Key Support - Single and composite primary keys

Installation

SQL Server

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.SqlServer

PostgreSQL

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.PostgreSql

MySQL

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.MySql

SQLite

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.Sqlite

Oracle

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.Oracle

Usage

BulkInsert

using BulkFlowKit.Core.Extensions;
using Microsoft.EntityFrameworkCore;

// Configure your database connection
var options = new DbContextOptionsBuilder<MyDbContext>()
    .UseSqlServer("your-connection-string")
    .Options;

await using var context = new MyDbContext(options);

// Bulk insert
var entities = Enumerable.Range(1, 10000)
    .Select(i => new Product
    {
        Name = $"Product {i}",
        Price = i * 10,
        CreatedAt = DateTime.UtcNow
    })
    .ToList();

await context.BulkInsertAsync(entities);

BulkUpdate

// First, fetch the data
var products = await context.Products
    .Where(p => p.Price < 100)
    .ToListAsync();

// Make updates
foreach (var product in products)
{
    product.Price *= 1.1m; // 10% increase
}

// Bulk update
await context.BulkUpdateAsync(products);

BulkDelete

// Fetch data to delete
var productsToDelete = await context.Products
    .Where(p => p.CreatedAt < DateTime.UtcNow.AddYears(-1))
    .ToListAsync();

// Bulk delete
await context.BulkDeleteAsync(productsToDelete);

Advanced Usage

// With batch size and progress callback
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 1000; // 1000 records per batch
    options.ProgressCallback = (processed) =>
    {
        Console.WriteLine($"Processed records: {processed}");
    };
});

// SQL Server specific options
await context.BulkInsertAsync(entities, options =>
{
    options.KeepIdentity = true; // Preserve identity values
    options.FireTriggers = true; // Fire triggers
    options.BatchSize = 5000;
});

// ContinueOnError: Skip failed batches and continue
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 10000; // Required for ContinueOnError
    options.ContinueOnError = true; // Skip failed batches
    options.OnError = (entity, ex, batchIndex) =>
    {
        Console.WriteLine($"Batch {batchIndex} error: {ex.Message}");
        // Log or handle the error
    };
});

ContinueOnError Feature

When ContinueOnError = true and BatchSize is specified, BulkFlowKit processes data in batches. If a batch fails, it's skipped and processing continues with the next batch.

Important Notes:

• BatchSize must be specified for ContinueOnError to work
• Each batch runs in its own transaction (external transactions are ignored in ContinueOnError mode)
• Failed batches are reported via the OnError callback
• This feature maintains bulk performance (each batch still uses COPY/BulkCopy)

Example:

// 1 million records, 10k per batch
// If batch 50 fails, batches 1-49 and 51-100 will still be inserted
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 10000;
    options.ContinueOnError = true;
    options.OnError = (entity, ex, batchIndex) =>
    {
        logger.LogError($"Batch {batchIndex} failed: {ex.Message}");
    };
});

Supported Databases

Requirements

• .NET 6.0 or 8.0
• Entity Framework Core 6.0 or 8.0
• Relevant database provider (e.g., Microsoft.EntityFrameworkCore.SqlServer)

Configuration

BulkFlowKit automatically registers itself (using Module Initializer). No additional configuration is required.

// Just install the relevant provider package and start using it!
// Automatic registration:
_ = typeof(BulkFlowKit.SqlServer.SqlServerBulkOperationExecutor); // For SQL Server

Performance

BulkFlowKit provides 10-100x faster performance compared to standard EF Core SaveChanges():

• 1 million record insert: ~5-10 seconds (EF Core: ~5-10 minutes)
• 100k record update: ~2-5 seconds (EF Core: ~2-5 minutes)
• 50k record delete: ~1-3 seconds (EF Core: ~1-3 minutes)

Note: Performance may vary based on database, network, and hardware.

Example Entity

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class MyDbContext : DbContext
{
    public MyDbContext(DbContextOptions<MyDbContext> options)
        : base(options)
    {
    }

    public DbSet<Product> Products { get; set; } = null!;

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Product>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Id).ValueGeneratedOnAdd();
        });
    }
}

Known Limitations

• MySQL/SQLite/Oracle: Bulk operations within active DbContext transactions are not supported
• SQLite/Oracle: KeepIdentity option is not supported
• Primary Key Required: Entities must have a primary key for BulkUpdate and BulkDelete operations
• ContinueOnError: Requires BatchSize to be specified, and external transactions are ignored

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please check existing issues before opening a new one.

Contact

Open an issue for questions.

BulkFlowKit - Yüksek Performanslı EF Core Bulk Operations

BulkFlowKit, Entity Framework Core için profesyonel, yüksek performanslı bulk insert, update ve delete işlemleri sunan açık kaynak bir kütüphanedir.

Özellikler

• BulkInsert - Toplu veri ekleme
• BulkUpdate - Toplu veri güncelleme
• BulkDelete - Toplu veri silme
• 5 Veritabanı Desteği: SQL Server, PostgreSQL, MySQL, SQLite, Oracle
• EF Core 6, 8 desteği
• Batch Processing - Büyük veri setleri için otomatik batch işleme
• Progress Callback - İlerleme takibi
• Transaction Desteği - Mevcut transaction'lar ile uyumlu
• ContinueOnError - Hata olan batch'leri atla ve devam et
• Primary Key Desteği - Tek ve çoklu kolonlu primary key'ler

Kurulum

SQL Server

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.SqlServer

PostgreSQL

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.PostgreSql

MySQL

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.MySql

SQLite

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.Sqlite

Oracle

dotnet add package BulkFlowKit.Core
dotnet add package BulkFlowKit.Oracle

Kullanım

BulkInsert

using BulkFlowKit.Core.Extensions;
using Microsoft.EntityFrameworkCore;

// Veritabanı bağlantınızı yapılandırın
var options = new DbContextOptionsBuilder<MyDbContext>()
    .UseSqlServer("your-connection-string")
    .Options;

await using var context = new MyDbContext(options);

// Toplu ekleme
var entities = Enumerable.Range(1, 10000)
    .Select(i => new Product
    {
        Name = $"Product {i}",
        Price = i * 10,
        CreatedAt = DateTime.UtcNow
    })
    .ToList();

await context.BulkInsertAsync(entities);

BulkUpdate

// Önce verileri çekin
var products = await context.Products
    .Where(p => p.Price < 100)
    .ToListAsync();

// Güncellemeleri yapın
foreach (var product in products)
{
    product.Price *= 1.1m; // %10 zam
}

// Toplu güncelleme
await context.BulkUpdateAsync(products);

BulkDelete

// Silinecek verileri çekin
var productsToDelete = await context.Products
    .Where(p => p.CreatedAt < DateTime.UtcNow.AddYears(-1))
    .ToListAsync();

// Toplu silme
await context.BulkDeleteAsync(productsToDelete);

Gelişmiş Kullanım

// Batch size ve progress callback ile
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 1000; // Her batch'te 1000 kayıt
    options.ProgressCallback = (processed) =>
    {
        Console.WriteLine($"İşlenen kayıt sayısı: {processed}");
    };
});

// SQL Server için özel seçenekler
await context.BulkInsertAsync(entities, options =>
{
    options.KeepIdentity = true; // Identity değerlerini koru
    options.FireTriggers = true; // Trigger'ları tetikle
    options.BatchSize = 5000;
});

// ContinueOnError: Hata olan batch'leri atla ve devam et
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 10000; // ContinueOnError için gerekli
    options.ContinueOnError = true; // Hata olan batch'leri atla
    options.OnError = (entity, ex, batchIndex) =>
    {
        Console.WriteLine($"Batch {batchIndex} hatası: {ex.Message}");
        // Hata logla veya işle
    };
});

ContinueOnError Özelliği

ContinueOnError = true ve BatchSize belirtildiğinde, BulkFlowKit verileri batch'ler halinde işler. Bir batch hata verirse atlanır ve bir sonraki batch ile devam edilir.

Önemli Notlar:

• ContinueOnError için BatchSize belirtilmesi zorunludur
• Her batch kendi transaction'ında çalışır (ContinueOnError modunda dış transaction'lar ignore edilir)
• Hata veren batch'ler OnError callback'i ile bildirilir
• Bu özellik bulk performansını korur (her batch hala COPY/BulkCopy kullanır)

Örnek:

// 1 milyon kayıt, 10k'lık batch'ler
// Eğer 50. batch hata verirse, 1-49 ve 51-100. batch'ler yine de insert edilir
await context.BulkInsertAsync(entities, options =>
{
    options.BatchSize = 10000;
    options.ContinueOnError = true;
    options.OnError = (entity, ex, batchIndex) =>
    {
        logger.LogError($"Batch {batchIndex} başarısız: {ex.Message}");
    };
});

Desteklenen Veritabanları

Gereksinimler

• .NET 6.0 veya 8.0
• Entity Framework Core 6.0 veya 8.0
• İlgili veritabanı provider'ı (örn: Microsoft.EntityFrameworkCore.SqlServer)

Yapılandırma

BulkFlowKit otomatik olarak kayıt yapılır (Module Initializer kullanarak). Herhangi bir ek yapılandırma gerekmez.

// Sadece ilgili provider paketini yükleyin ve kullanmaya başlayın!
// Otomatik kayıt için:
_ = typeof(BulkFlowKit.SqlServer.SqlServerBulkOperationExecutor); // SQL Server için

Performans

BulkFlowKit, standart EF Core SaveChanges() metoduna göre 10-100x daha hızlı performans sunar:

• 1 milyon kayıt insert: ~5-10 saniye (EF Core: ~5-10 dakika)
• 100 bin kayıt update: ~2-5 saniye (EF Core: ~2-5 dakika)
• 50 bin kayıt delete: ~1-3 saniye (EF Core: ~1-3 dakika)

Not: Performans veritabanı, network ve donanıma göre değişiklik gösterebilir.

Örnek Entity

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class MyDbContext : DbContext
{
    public MyDbContext(DbContextOptions<MyDbContext> options)
        : base(options)
    {
    }

    public DbSet<Product> Products { get; set; } = null!;

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Product>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Id).ValueGeneratedOnAdd();
        });
    }
}

Bilinen Sınırlamalar

• MySQL/SQLite/Oracle: Aktif DbContext transaction içinde bulk operasyonlar desteklenmiyor
• SQLite/Oracle: KeepIdentity seçeneği desteklenmiyor
• Primary Key Gereklidir: BulkUpdate ve BulkDelete için entity'lerin primary key'e sahip olması gerekir
• ContinueOnError: BatchSize belirtilmesi gerekir ve dış transaction'lar ignore edilir

Lisans

MIT License - Detaylar için LICENSE dosyasına bakın.

Katkıda Bulunma

Katkılarınızı bekliyoruz! Lütfen issue açmadan önce mevcut issue'ları kontrol edin.

İletişim

Sorularınız için issue açabilirsiniz.