Skip to content

Add a stack-only Appender writer for high-throughput inserts#345

Open
skuirrels wants to merge 2 commits into
Giorgi:Appender-Perffrom
skuirrels:feature/appender-scoped-writer-pr
Open

Add a stack-only Appender writer for high-throughput inserts#345
skuirrels wants to merge 2 commits into
Giorgi:Appender-Perffrom
skuirrels:feature/appender-scoped-writer-pr

Conversation

@skuirrels

@skuirrels skuirrels commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Problem

CreateRow() returns an independent IDuckDBAppenderRow, which means allocating a row object for every insert. The callback-based AppendRow() added in #336 can reuse its row, but the interface reference can still be retained outside the callback.

Timestamp conversion was also making a native call for every value in the mixed-row workload.

Solution

Add AppendRowScoped<TState>(), which passes a stack-only DuckDBAppenderRowWriter by reference. The writer cannot be boxed or stored on the managed heap, so the Appender can safely reuse its internal row state.

The new path keeps the existing validation, vector writers, chunk lifecycle, automatic EndRow(), and fault handling. CreateRow() is unchanged and still returns independent row objects.

The two APIs intentionally have different contracts: CreateRow() returns a retainable row, while AppendRowScoped() owns the complete row lifetime. I have left deprecation out of this PR so it stays focused on the faster API. If we want to steer callers away from CreateRow(), either you or I can follow up with a separate PR once the preferred migration path is agreed.

Benchmarks

10,000 precomputed mixed-type rows inside a transaction, rolled back after each invocation:

Path Latency Throughput Allocation
Previous fork result 247.7 ns/row 4.04M rows/s 816 B/row
CreateRow().EndRow() 86.47 ns/row 11.56M rows/s 64 B/row
AppendRowScoped() 79.48 ns/row 12.58M rows/s 0 B/row
Java JDBC 174.25 ns/row 5.74M rows/s -
Go 183.46 ns/row 5.45M rows/s -

Repeated scoped runs measured between 78.55 and 81.28 ns/row.

Tests

Added coverage for mixed and null values, chunk boundaries, callback and preparation failures, incomplete rows, existing CreateRow() behaviour, and timestamp precision/offset edge cases.

  • 82 focused tests passed with allocator scribbling enabled
  • 6,989 full tests passed
  • Release test and benchmark projects build successfully

@codecov

codecov Bot commented Jul 21, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 67.69231% with 21 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (Appender-Perf@258b750). Learn more about missing BASE report.

Files with missing lines Patch % Lines
DuckDB.NET.Data/DuckDBAppenderRowWriter.cs 30.00% 21 Missing ⚠️
Additional details and impacted files
@@               Coverage Diff                @@
##             Appender-Perf     #345   +/-   ##
================================================
  Coverage                 ?   87.46%           
================================================
  Files                    ?       78           
  Lines                    ?     3256           
  Branches                 ?      471           
================================================
  Hits                     ?     2848           
  Misses                   ?      296           
  Partials                 ?      112           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@skuirrels
skuirrels marked this pull request as ready for review July 21, 2026 18:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant