SU2.EntityFrameworkCore.Oracle.Bulks 0.0.0.2

SU2.EntityFrameworkCore.Oracle.Bulks

Cài đặt từ NuGet: dotnet add package SU2.EntityFrameworkCore.Oracle.Bulks

ID package và namespace .NET đều sử dụng tiền tố SU2 để đồng bộ tên package và mã nguồn.

Bản phát hành thử nghiệm Oracle, bổ sung cho các package SimpleBulks của SQL Server, MySQL và PostgreSQL. Phiên bản 1.0.0-rc-1 hỗ trợ .NET / EF Core 8, 9 và 10, sử dụng các provider Oracle.EntityFrameworkCore 8.23.26000, 9.23.26000, 10.23.26000 tương ứng cùng ODP.NET Core 23.26.0.

Các thao tác được hỗ trợ

• BulkInsert, BulkUpdate, BulkDelete và BulkMerge (upsert), hỗ trợ đồng bộ và bất đồng bộ.
• BulkMatch / BulkMatchAsync: đọc các dòng khớp trong cơ sở dữ liệu theo một hoặc nhiều cột, có thể chọn phép chiếu.
• Phương thức mở rộng DbContext, ConnectionContext và fluent builder.
• Profile TableMapper theo tên, mapping cột tường minh, khóa phức hợp, chọn cột và khóa đối chiếu tùy chỉnh.
• Array binding của ODP.NET với batch giới hạn, giá trị null có kiểu, timeout lệnh và hủy thao tác.
• Metadata thuộc tính vô hướng của EF, tên cột/schema và bộ chuyển đổi giá trị của provider.

Tính năng bổ sung

• DirectInsert/DirectUpdate/DirectDelete và Upsert, đồng bộ/bất đồng bộ, trả về số dòng bị ảnh hưởng (không suy đoán số dòng insert/update).
• Trả về khóa chính được sinh cho INSERT và MERGE. Mapping trực tiếp bật tính năng bằng OutputId(x => x.Id); EF sử dụng metadata khóa chính được sinh. Khóa Guid sinh phía client hỗ trợ OutputIdMode.ClientGenerated.
• KeepIdentity cho identity Oracle loại BY DEFAULT có thể insert. Identity loại GENERATED ALWAYS vẫn từ chối giá trị tường minh; thư viện không thay đổi schema để bỏ qua giới hạn này.
• Callback ConfigureSetClause và lựa chọn riêng WithInsertColumns/WithUpdateColumns cho merge.
• ConfigureWhenNotMatchedBySource cho DELETE hoặc UPDATE SET, sử dụng toàn bộ nguồn đã staging thay vì từng batch.
• API TempTable riêng theo transaction (Oracle 18c+), yêu cầu connection đang mở và local transaction tường minh.
• Collation cho khóa đối chiếu dạng chuỗi (ví dụ BINARY_CI), phụ thuộc phiên bản Oracle và cấu hình cơ sở dữ liệu.
• Mapping owned reference/complex reference cùng bảng, ràng buộc discriminator TPH, cột vô hướng shadow/field-backed, bộ chuyển đổi JSON tường minh và điều kiện concurrency dùng original value khi update/delete.
• Có thể bật UseTrackedExecution = true trên extension ghi DbContext cho graph nhiều bảng/JSON/owned collection được provider hỗ trợ.

Các sửa lỗi và chuyển đổi API kết quả

BulkUpdate/DirectUpdate trả về BulkUpdateResult; BulkDelete/DirectDelete trả về BulkDeleteResult; BulkMerge/Upsert trả về BulkMergeResult. Bản bất đồng bộ, kể cả builder, trả về Task<TResult>. Đọc result.AffectedRows thay vì coi kết quả DirectUpdate/DirectDelete/Upsert là int. Đây là thay đổi API mã nguồn/binary so với bản preview Oracle trước đó: cần biên dịch lại ứng dụng gọi và cập nhật các assertion. DirectInsert vẫn trả về int; BulkInsert vẫn trả về void/Task. Builder cũng cung cấp SingleInsert, SingleUpdate, SingleDelete, SingleMerge và các phiên bản bất đồng bộ.

BulkMergeResult.InsertedRows và UpdatedRows là nullable và hiện có giá trị null; HasBranchCounts là false. Oracle MERGE chỉ báo tổng số dòng bị ảnh hưởng, không cung cấp số dòng theo nhánh đáng tin cậy. Package không thực hiện pre-count có nguy cơ race condition để tạo số liệu giả. Đồng bộ nguồn cũng được cộng vào AffectedRows. Ở chế độ tracked, số đếm là số entry bị SaveChanges ảnh hưởng, bao gồm entry của owned graph, không chỉ entity gốc. Đây là chủ ý và không bảo đảm các trường kết quả giống hệt provider khác.

Khóa Guid phía client được khởi tạo trước khi staging khóa nguồn. Khóa hiện có được kiểm tra ở dạng model, vì vậy converter Guid-to-string không làm thay thế khóa; khi thao tác lỗi, các khóa được sinh sẽ được khôi phục. Concurrency token trong complex dùng entry tracking complex lồng nhau của entity gốc/owned. Đối tượng cha chỉ có getter vẫn có thể materialize nếu đã được khởi tạo; parent getter-only có giá trị null không thể được tạo và sẽ bị từ chối. Selector parent như x => x.Address được mở rộng thành các lá đã mapping khi ghi, đối chiếu, chọn cột trả về, khóa và bảng tạm. Selector không xác định hoặc chồng lấp sẽ bị từ chối; các lá chỉ đọc vẫn được bảo vệ khỏi thao tác ghi.

Context callback SQL cung cấp metadata TableInfor và helper quote cột đích. Helper nguồn trong set-clause chỉ tham chiếu các cột nguồn đã chọn. Parameters của đồng bộ chấp nhận object ẩn danh hoặc dictionary string/object và bind giá trị thành parameter. Alias nguồn chỉ tồn tại bên trong subquery NOT EXISTS: MergeContext.GetSourceTableColumn sẽ throw thay vì trả về alias không hợp lệ cho điều kiện/phép gán ở bảng đích. Hãy dùng helper cột đích trong callback đồng bộ.

Các giới hạn còn lại

Đây vẫn là bản preview, chưa cam kết API hoặc hiệu năng tương đương các provider khác. Phải chạy đạt live test Oracle trước khi dùng production. Mapping native chỉ hỗ trợ một bảng: TPT/entity splitting, owned nhiều bảng object, owned collection và aggregate JSON của EF yêu cầu tracked execution. Mapping JSON-to-CLOB trực tiếp có sẵn với ConfigureJsonProperty; materialize JSON native của EF chưa được triển khai. BulkMatch native không hỗ trợ các dạng nhiều bảng/JSON này. Materialize đa hình theo base type không được hỗ trợ; hãy truy vấn type cụ thể đã mapping. MERGE native có concurrency bị từ chối; dùng update hoặc tracked execution. Concurrency token do server sinh không được tự động làm mới sau update native.

Tracked execution dùng SaveChanges thay vì array binding và yêu cầu DbContext riêng có ChangeTracker rỗng. Nó ghi toàn bộ graph, không nhận cột projection, callback SQL, đồng bộ nguồn hoặc collation, sau đó xóa tracker. Đặt giá trị shadow/original token bằng ConfigureTrackedEntry. Tracked upsert kiểm tra entity gốc theo khóa chính rồi thêm/cập nhật graph được cung cấp; không bao giờ xóa child bị bỏ qua và không phải Oracle MERGE nguyên tử. Race khi insert đồng thời có thể lỗi do unique constraint. Mức hỗ trợ của provider quyết định dạng JSON/inheritance nào khả dụng trên từng phiên bản EF. Interceptor SaveChanges chạy ở chế độ tracked. API connection/fluent từ chối UseTrackedExecution thay vì bỏ qua.

Thao tác bulk native bỏ qua SaveChanges và global query filter. Hãy dùng tenant/scope key tường minh; không dựa vào global filter để phân quyền đọc/ghi. Callback SQL thô chỉ dành cho code ứng dụng đáng tin cậy.

DbContext

using SU2.EntityFrameworkCore.Oracle.Bulks.BulkInsert;
using SU2.EntityFrameworkCore.Oracle.Bulks.BulkUpdate;
using SU2.EntityFrameworkCore.Oracle.Bulks.BulkDelete;
using SU2.EntityFrameworkCore.Oracle.Bulks.BulkMerge;

await dbContext.BulkInsertAsync(items, new BulkInsertOptions { BatchSize = 1000 });
await dbContext.BulkUpdateAsync(items, x => new { x.Name, x.Price });
await dbContext.BulkDeleteAsync(items);

// MERGE yêu cầu khóa đối chiếu có thể insert. Dùng khóa nghiệp vụ duy nhất nếu PK được sinh.
await dbContext.CreateBulkMergeBuilder<Product>()
    .WithKeys(x => x.Code)
    .ExecuteAsync(items, cancellationToken);

Cấu hình DbContext bằng provider UseOracle của Oracle. Cột generated-on-add được loại khỏi INSERT. Có thể truyền cột generated với KeepIdentity khi Oracle cho phép; các cột chỉ đọc khác không được chọn. Khóa chính sinh tự động được ghi ngược về object theo mặc định. Giá trị default/computed khác giữ trên server. INSERT chỉ có identity dùng DEFAULT. UPDATE loại trừ khóa đối chiếu. MERGE không bao giờ cập nhật cột trong mệnh đề ON. Khóa đối chiếu không được null (chuỗi cũng không được rỗng); bên gọi phải bảo đảm tính duy nhất trong cơ sở dữ liệu. Các khóa đối chiếu lặp trong input được xử lý theo thứ tự input, không khử trùng lặp. Các lệnh MERGE đồng thời có thể vẫn lỗi do unique constraint; package không tự động retry thao tác ghi.

Kết nối Oracle trực tiếp

using SU2.EntityFrameworkCore.Oracle.Bulks;
using SU2.EntityFrameworkCore.Oracle.Bulks.BulkInsert;
using Oracle.ManagedDataAccess.Client;

TableMapper.Configure<Product>(map => map
    .TableName("PRODUCTS")
    .PrimaryKeys(x => x.Id)
    .ConfigureProperty(x => x.Id, "ID", readOnly: true)
    .ConfigureProperty(x => x.Code, "CODE", OracleDbType.Varchar2)
    .ConfigureProperty(x => x.Name, "NAME", OracleDbType.NVarchar2)
    .ConfigureProperty(x => x.Price, "PRICE", OracleDbType.Decimal));

using var connection = new OracleConnection(connectionString);
await new ConnectionContext(connection).BulkInsertAsync(items);

Dùng đúng kiểu chữ của định danh Oracle: object cơ sở dữ liệu không quote thường dùng chữ hoa. Định danh được quote và escape; giá trị dòng được bind, không bao giờ nội suy vào SQL. Mapping trực tiếp mặc định dùng boolean tương thích NUMBER (0/1), GUID dạng byte RAW và chuỗi Unicode. Hãy cấu hình OracleDbType và conversion tường minh cho quy ước lưu trữ khác hoặc LOB. Mapping EF dùng relational type mapping và converter của provider thay cho các mặc định này. Oracle coi chuỗi rỗng là NULL. Giá trị phải phù hợp với kiểu cột Oracle đã cấu hình.

BulkMatch

using SU2.EntityFrameworkCore.Oracle.Bulks.BulkMatch;

// Trả về giá trị từ database, không phải object input.
var existing = await dbContext.BulkMatchAsync(importedProducts, x => x.Code);

// Tất cả cột đối chiếu đã chọn phải khớp. Thuộc tính trả về không chọn giữ giá trị mặc định của constructor.
var projected = await dbContext.BulkMatchAsync(importedProducts,
    x => new { x.Code, x.BranchCode },
    x => new { x.Id, x.Name },
    new BulkMatchOptions { BatchSize = 100 }, cancellationToken);

var directResults = await new ConnectionContext(connection)
    .CreateBulkMatchBuilder<Product>()
    .WithMatchedColumns(x => x.Code)
    .WithReturnedColumns(x => new { x.Id, x.Name })
    .WithBulkOptions(new BulkMatchOptions { MappingProfileName = "products" })
    .ExecuteAsync(importedProducts, cancellationToken);

Đăng ký mapping có tên products trước khi dùng ví dụ cuối. Builder cũng nhận WithTable(table) / ToTable(table), và selector cột có thể là collection tên thuộc tính. Nếu không chỉ định cột đối chiếu trong builder, khóa chính đã mapping sẽ được dùng. Mặc định mọi cột đã mapping đều được trả về, bao gồm cột generated/chỉ đọc. Type trả về phải là reference type có constructor public không tham số và setter cho các thuộc tính được chọn.

BulkMatch dùng JOIN có parameter với rowset inline SELECT ... FROM DUAL UNION ALL ..., không dùng SELECT array-bound hoặc bảng tạm. Batch tối đa 100 dòng input và 1000 parameter; BatchSize = 0 nghĩa là 100. Giới hạn này kiểm soát kích thước SQL nhưng chưa được benchmark để thay thế staging-table khi xử lý hàng triệu input. Tất cả dòng kết quả được tích lũy trong bộ nhớ.

Đối chiếu dùng ngữ nghĩa = của Oracle: khóa NULL/chuỗi rỗng không khớp, kể cả với cột NULL. Khóa input trùng vẫn giữ bội số JOIN, kể cả giữa các batch; kết quả không được khử trùng lặp và thứ tự không được bảo đảm. Không hỗ trợ khóa đối chiếu LOB/LONG. Equality/collation tuân theo cấu hình database/session của Oracle, trừ khi truyền Collation và phiên bản Oracle hỗ trợ.

EF value converter được áp dụng hai chiều. Conversion tùy chỉnh trực tiếp phải cung cấp tham số tùy chọn convertFromProvider cho ConfigurePropertyConversion khi trả về cột đó; nếu không thao tác đọc sẽ lỗi rõ ràng. Cột conversion chỉ ghi vẫn có thể làm khóa đối chiếu. RAW-to-Guid dùng cùng thứ tự byte với conversion Guid-to-RAW của mapping trực tiếp.

Kết quả detached và không thay đổi entity input. Global query filter của EF (bao gồm tenant và soft-delete) không được áp dụng, vì API này đọc trực tiếp bảng đã mapping; hãy đưa các cột scope bắt buộc vào điều kiện đối chiếu hoặc không dùng API này ở nơi query filter thực hiện phân quyền. Các giới hạn mapping native một bảng vẫn được áp dụng.

BulkMatch chỉ đọc: không bắt đầu, commit hoặc rollback transaction. Nó dùng lại transaction của bên gọi nếu có và giữ nguyên quyền sở hữu connection. Các batch riêng biệt có thể quan sát trạng thái database đã commit khác nhau nếu bên gọi không cung cấp transaction đọc nhất quán phù hợp.

Transaction và connection

Transaction tường minh của ConnectionContext hoặc transaction hiện tại của DbContext được dùng lại, không bao giờ được package commit hoặc rollback. Nếu không có transaction tường minh/ambient, package sở hữu một transaction bao phủ mọi batch và rollback khi lỗi. Ambient enlistment dùng cấu hình connection của ODP.NET; bên gọi phải bảo đảm connection đang mở được enlist. Sau lỗi trong transaction do bên gọi sở hữu, bên gọi phải rollback để hoàn tác các dòng/batch đã thành công trước đó. Connection do package mở sẽ được đóng sau đó; connection đã mở sẵn sẽ được giữ nguyên. DML thông thường/BulkMatch không dùng DDL. TempTable và đồng bộ nguồn dùng CREATE PRIVATE TEMPORARY TABLE ... ON COMMIT DROP DEFINITION (việc tạo không implicit commit). Bảng tồn tại đến khi bên gọi commit/rollback; không tự động DROP sớm. BatchSize = 0 sử dụng 1000; kích thước hoặc thời gian chờ âm sẽ bị từ chối. Timeout = 0 nghĩa là không giới hạn thời gian. LogTo chỉ nhận text SQL, không nhận giá trị đã bind. Input rỗng không thực hiện I/O với database.

Biên dịch và kiểm thử

Từ thư mục src:

dotnet build EntityFrameworkCore.Oracle.SimpleBulks.slnx -c Release
dotnet test EntityFrameworkCore.Oracle.SimpleBulks.slnx -c Release
dotnet pack EntityFrameworkCore.Oracle.SimpleBulks/EntityFrameworkCore.Oracle.SimpleBulks.csproj -c Release -o ../artifacts

Unit test kiểm tra lệnh Oracle thực tế và metadata EF mà không cần database. Integration test được bật tùy chọn bằng SIMPLEBULKS_ORACLE_CONNECTION_STRING, trỏ đến schema Oracle dùng riêng cho test có quyền CREATE TABLE. Test tạo/xóa bảng tên ngẫu nhiên, kiểm tra DML và rollback thực tế, và tuyệt đối không chạy trên production. Repository này không lưu credential database.

Oracle documentation: https://github.com/oracle/dotnet-db-samples/tree/master/samples

Giá trị sinh, đồng bộ và bảng tạm

Việc trả về ID sinh hiện dùng thực thi từng dòng: INSERT RETURNING INTO, hoặc MERGE rồi tra cứu khóa trong cùng transaction. Đặt ReturnDbGeneratedId=false để dùng đường chạy nhanh array-bound. Khóa đối chiếu phải định danh duy nhất dòng cần tra cứu. ID trả về được khôi phục khi thao tác lỗi; nếu bên gọi rollback transaction của mình sau đó, bên gọi phải tự loại bỏ/tải lại các ID đã trả về.

Đồng bộ sử dụng private temporary table và yêu cầu Oracle 18c+ với prefix mặc định ORA$PTT_. Phải có AndCondition cho bảng đích, trừ khi bật tường minh AllowFullTableSynchronization=true. Nguồn rỗng có thể xóa/cập nhật mọi dòng trong phạm vi đó. Hãy kiểm tra phạm vi trước bằng schema dùng riêng. Thao tác không khóa toàn bộ bảng đích trước các bên ghi đồng thời. Ambient/distributed transaction và xóa ngầm toàn bộ TPH bị từ chối. ThenAction nhận DELETE hoặc UPDATE SET theo sau bởi phép gán Oracle đáng tin cậy; Parameters bind giá trị phạm vi. Không bao giờ đưa input người dùng trực tiếp vào callback SQL.

CreateTempTable trả về tên đã quote và giữ connection/transaction của bên gọi mở. NamePrefix phải khớp PRIVATE_TEMP_TABLE_PREFIX. Không thể dùng sau khi transaction kết thúc. Khi lỗi, hãy rollback transaction của bên gọi. Cần StoreType tường minh khi độ dài staging mặc định không đủ.

Live test Oracle

Dùng schema test riêng, tuyệt đối không dùng production. Bộ test tạo bảng SB_* tên ngẫu nhiên và xóa trong finally. Process bị ngắt có thể để lại bảng test; hãy kiểm tra trước khi dọn thủ công. Dùng Oracle 19c trở lên cho integration suite (private temporary table yêu cầu 18c+). Yêu cầu DBA cấp user riêng không phải SYS với CREATE SESSION, CREATE TABLE, tablespace mặc định có đủ quota, temporary tablespace và PRIVATE_TEMP_TABLE_PREFIX=ORA$PTT_. Không cấp quyền DBA. Máy chạy test phải truy cập được host/port và tên service PDB.

Từ thư mục src của package, nhập an toàn connection string mà không ghi vào shell history:

read -r -s -p 'Oracle test connection string: ' SIMPLEBULKS_ORACLE_CONNECTION_STRING
printf '\n'
export SIMPLEBULKS_ORACLE_CONNECTION_STRING

dotnet test EntityFrameworkCore.Oracle.SimpleBulks.Tests/EntityFrameworkCore.Oracle.SimpleBulks.Tests.csproj \
  -c Release -f net10.0 -m:1 \
  --filter 'FullyQualifiedName~OracleIntegrationTests' \
  --logger 'console;verbosity=normal'

unset SIMPLEBULKS_ORACLE_CONNECTION_STRING

Benchmark chèn hàng loạt

Benchmark so sánh array DML của SimpleBulks với cơ chế chèn của PhenX.EntityFrameworkCore.BulkInsert.Oracle 0.5.0. Mặc định chạy 100.000/200.000/500.000 dòng, batch 10.000 dòng, ba lượt cho mỗi kích thước. Đặt LOCAL_ORACLE_CONNECTION_STRING hoặc SIMPLEBULKS_ORACLE_CONNECTION_STRING, sau đó chạy:

dotnet run --project src/EntityFrameworkCore.Oracle.SimpleBulks.Benchmarks/EntityFrameworkCore.Oracle.SimpleBulks.Benchmarks.csproj -c Release -- --sizes 100000,200000,500000 --iterations 3 --batch-size 10000

Mỗi lượt chạy dùng process mới, một bảng tên ngẫu nhiên và EF model ổn định. Cả hai đường chạy đều warm-up 1.000 dòng, kiểm tra và truncate, mở connection và khởi tạo metadata trước khi đo thời gian. Tạo input và GC cưỡng bức nằm ngoài khoảng đo; mỗi thư viện giữ chính sách transaction mặc định. Thứ tự thư viện được đảo giữa các lượt. Mọi số dòng warm-up/đo phải đúng số yêu cầu; nếu lỗi, sai số dòng hoặc lỗi dọn dẹp thì process trả mã thoát khác 0. Bảng được xóa trong finally. In thời gian trung vị và min/max cùng allocation managed trung bình của toàn process. Allocation được đo trên mọi thread trong lúc insert, không phải delta heap giữ lại. Working set được báo cáo dưới dạng snapshot tuyệt đối đầu/cuối, không phải mức peak. Allocation input, setup và verify bị loại khỏi phép đo; bộ nhớ cư trú của input có trong baseline working set. Bộ nhớ server DB không được đo. Tác vụ nền của runtime có thể ảnh hưởng allocation; tải máy/DB vẫn ảnh hưởng kết quả. Không chạy test hoặc benchmark khác đồng thời nếu cần số liệu đáng tin cậy.

Các kết quả nhiều kích thước trước đây dùng tên bảng động với model cache mặc định của EF là không hợp lệ: các lượt PhenX sau có thể trỏ vào bảng đã bị lượt trước xóa. Lỗi harness đó không chứng minh PhenX không thể insert 200k hoặc 500k dòng. Chỉ dùng kết quả từ harness đã sửa.

Dạng chuỗi kết nối: User Id=<test_user>;Password=<password>;Data Source=//<host>:1521/<pdb_service>. Với mật khẩu chứa ký tự phân cách của chuỗi kết nối, hãy tạo giá trị bằng OracleConnectionStringBuilder hoặc đặt trong dấu quote theo quy tắc của ODP.NET. Không dán thông tin xác thực vào cuộc trò chuyện, mã nguồn hoặc log dùng chung.

Kết quả mong đợi: 5 passed, 0 failed, 0 skipped khi chỉ chạy integration trên một framework. Skipped nghĩa là biến môi trường không đến được process test, không có nghĩa Oracle đã đạt. Bỏ -f net10.0 để chạy cả ba framework sau khi lượt đầu thành công. Suite bao phủ array DML, BulkMatch, rollback của bên gọi, ID sinh, Direct API, Upsert, KeepIdentity, bảng tạm và xóa nguồn theo phạm vi. Live regression test cũng bao phủ đồng bộ nguồn Guid-to-string, hoàn tác khóa sinh, original token complex lồng nhau, update/delete với token cũ và rollback toàn thao tác, ghi tracked owned nhiều bảng reference/collection thành công, ID child sinh tự động, ConfigureTrackedEntry và tracked upsert root đã có/chưa có. Đây chưa phải coverage đầy đủ cho mọi mapping nâng cao, collation hoặc phiên bản Oracle. Không đưa ra tuyên bố benchmark nào. Không tự động retry thao tác ghi lỗi trên production.

Xử lý sự cố: ORA-12514 thường cần kiểm tra tên service; ORA-01017 cần kiểm tra credential; ORA-01031/ORA-01950 cần DBA kiểm tra quyền/quota. Lỗi private table cần kiểm tra phiên bản Oracle và PRIVATE_TEMP_TABLE_PREFIX. Giữ nguyên lỗi và log đã che thông tin nhạy cảm để điều tra.