This README is the stable, user-facing performance summary for CSharpDB. It answers three questions:

• How fast is CSharpDB on the core workloads we care about?
• Which benchmark produced each published number?
• Is the latest release benchmark run clean enough to promote?

Historical release logs, failed-run notes, and investigation detail live in HISTORY.md. The full harness catalog lives in BENCHMARK_CATALOG.md.

Published numbers in this file are a release contract, not a scratchpad. They are promoted only from the balanced release-core suite after the release guardrail comparison passes on the canonical or same-machine runner.

Core rules:

• The main README is user-first. It should stay short enough to scan.
• --all is diagnostic only. It is never a direct source for published tables.
• Failed release runs go to HISTORY.md, not into the current scorecard.
• Targeted reruns can diagnose a problem, but they do not replace current published numbers unless the full release-core promotion rule passes.
• The generated region below is owned by scripts/Update-BenchmarkReadme.ps1 and release-core-manifest.json.

Current release health:

The generated block below contains the scorecard first, then the current core result tables. Do not edit inside the markers; update release-core-manifest.json and rerun the updater.

These are the headline rows readers should use first. Detailed tables below map each number back to a source CSV row.

These detailed tables are generated from the approved source artifacts listed above.

Each row is total successful commits/sec across one shared engine. The intended insert shape uses ConcurrentWriteTransactions and disjoint explicit key ranges.

These rows are from the May 5, 2026 targeted validation run for the opt-in ImplicitInsertExecutionMode.ConcurrentWriteTransactions insert path. They are not promoted release-core scorecard rows yet; they document the current proof point for hot one-row concurrent inserts and are guarded by current-only release checks until the release-core suite includes these shapes directly.

Command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --insert-fan-in-diagnostics --repro

Source CSV:

tests/CSharpDB.Benchmarks/bin/Release/net10.0/results/insert-fan-in-diagnostics-20260505-233424.csv

Operational guidance: keep Serialized as the default. Use ConcurrentWriteTransactions only for workloads that can benefit from shared-engine one-row commit fan-in; InsertBatch remains the preferred bulk-ingest path.

These May 5, 2026 rows are diagnostic close-out proof for the current advanced optimizer and async I/O batching phases. They are not promoted release-core scorecard rows; they document workload-shaped gains and audited coverage while future adaptive re-optimization and specialized maintenance tuning remain separate roadmap items. Public planner-stat inspection is now covered by the sys.planner_* catalog and EXPLAIN ESTIMATE diagnostic benchmarks.

Optimizer command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --optimizer-closeout --repro

Optimizer source CSV:

tests/CSharpDB.Benchmarks/bin/Release/net10.0/results/optimizer-closeout-20260505-204536.csv

Public planner diagnostics smoke command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --micro --filter *SystemCatalogBenchmarks*Planner* --job Dry
dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --micro --filter *ExplainEstimate* --job Dry

These May 6, 2026 rows are diagnostic proof for opt-in adaptive query re-optimization. The SQL rows measure default-disabled behavior, enabled wrapper overhead, and eligible join shapes on the benchmark seed data. The synthetic rows force the adaptive operator switch paths directly so the run records divergence and switch counters even when the normal planner already avoids a bad plan.

Command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --adaptive-reoptimization

Source CSV:

tests/CSharpDB.Benchmarks/bin/Release/net10.0/results/adaptive-reoptimization-20260506-073419.csv

Interpretation: this feature is not a universal speedup. It should be enabled only for workloads where stale statistics or parameter-sensitive joins produce materially wrong join choices; stable, well-analyzed plans should expect no gain and some opt-in wrapper cost.

Async I/O command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --async-io-closeout --repro

Async I/O source CSV:

tests/CSharpDB.Benchmarks/bin/Release/net10.0/results/async-io-closeout-20260505-204638.csv

These April 26, 2026 rows are diagnostic proof for the opt-in source-generated collection fast path. They compare source-generated JSON payloads with generated binary direct payloads for supported document graphs. They are not promoted release-core scorecard rows; durable single-row collection writes can still be flush-bound, so these numbers mainly describe CPU and allocation wins in encode/decode and field/index-reader paths.

Command:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --micro --filter *GeneratedCollection*

Source CSVs:

BenchmarkDotNet.Artifacts/results/CSharpDB.Benchmarks.Micro.GeneratedCollection*Benchmarks-report.csv

Interpretation: generated collections are worth using when collection payload CPU, direct field extraction, or index-reader cost is visible in the profile. They should not be sold as a durable commit-throughput feature, because WAL flush policy still dominates one-row durable writes.

Run the balanced release-core benchmark suite:

dotnet run -c Release --project .\tests\CSharpDB.Benchmarks\CSharpDB.Benchmarks.csproj -- --release-core --repeat 3 --repro

Run the release guardrail comparison:

pwsh -NoProfile .\tests\CSharpDB.Benchmarks\scripts\Run-Perf-Guardrails.ps1 -Mode release

Preview a README refresh from an approved manifest:

pwsh -NoProfile .\tests\CSharpDB.Benchmarks\scripts\Update-BenchmarkReadme.ps1 `
  -RunManifest .\tests\CSharpDB.Benchmarks\release-core-manifest.json `
  -DryRun

Promote approved results:

pwsh -NoProfile .\tests\CSharpDB.Benchmarks\scripts\Update-BenchmarkReadme.ps1 `
  -RunManifest .\tests\CSharpDB.Benchmarks\release-core-manifest.json

Promotion checklist:

• The release-core suite was run with --repeat 3 --repro.
• The release guardrail result is clean.
• The manifest points only to the approved median artifacts.
• The generated README diff only changes benchmark numbers, source artifacts, or snapshot metadata.
• Failed or noisy runs are recorded in HISTORY.md.

Related files:

• HISTORY.md: previous release logs, failed runs, and investigation notes.
• BENCHMARK_CATALOG.md: complete harness list and classification.
• SQLITE_COMPARISON.md: focused same-runner CSharpDB vs SQLite comparison.
• release-core-manifest.json: source-of-truth manifest for published README tables.
• scripts/Update-BenchmarkReadme.ps1: generated-results updater.