perf(sqlserver-transport): index dequeue path + opt-in clustered queue layout

[jeremydmiller]

Summary

Performance work on the Sql Server queue transport. The dequeue path (SELECT TOP(n) ... ORDER BY timestamp) had no supporting index, so every poll scanned and sorted the whole queue table — the only index was the clustered primary key on a random Guid, which is also poor for write locality. This PR fixes the default and adds an opt-in high-throughput layout.

Changes

Default (safe, additive — no opt-in)

• Index the queue table timestamp column so the ordered TOP(n) dequeue is a seek instead of a full scan + sort.
• Robust idempotency: replaced locale-fragile e.Message.Contains("Violation of PRIMARY KEY constraint") with SQL error numbers (2627 / 2601).

Opt-in: OptimizeQueueThroughput()

A new fluent setting on the Sql Server transport config:

opts.UseSqlServerPersistenceAndTransport(connectionString)
    .OptimizeQueueThroughput();

The queue and scheduled tables are then clustered on a monotonic seq identity (FIFO dequeue as a clustered seek + physically contiguous deletes), with a unique non-clustered index on the message id (idempotent sends rely on the 2601 unique-index violation) and a filtered index on keep_until for the expiry sweep. This mirrors the layout Wolverine's own NServiceBus interop transport already uses (NServiceBusQueueTable).

Default is off; enabling it on an existing database triggers a one-time queue-table rebuild, so it's documented as a maintenance-window change. New apps can turn it on from the start. The NServiceBus interop transport already uses the equivalent clustered layout, so no opt-in is exposed there.

Docs

New "Optimizing Queue Throughput" section in the Sql Server guide.

Benchmarks

Raw-DDL A/B/C benchmark (batch 50, 30k-row backlog), included as a skipped manual test:

Layout	drain throughput	deep-pop median	deep-pop p95
baseline (clustered GUID, no index)	98/s	845 ms	1860 ms
default (+ timestamp index)	498/s	2.4 ms	853 ms
OptimizeQueueThroughput() (clustered seq)	34,612/s	2.4 ms	3.7 ms

Follow-up (not in this PR)

Batched outbox→queue send via a TVP, using a default-method ISender extension (the durable send path is per-envelope today). Tracked separately.

Validation / reviewer note

• ✅ Builds clean (full wolverine.slnx, Release).
• ✅ Physical schema designs proven by the raw-DDL benchmark; Weasel model uses the same APIs as the existing NServiceBusQueueTable (AutoNumber() + IsClustered + filtered Predicate).
• ⚠️ I could not run the xUnit transport suite / Weasel auto-migration locally — the dev SQL Server containers were unusable (one OOM-crashes, the other times out servicing Weasel's schema-introspection queries). The Weasel migration for the opt-in layout (fresh create and the existing-DB rebuild) needs to be validated by CI. A new integration test verify_optimized_schema_provisions_and_roundtrips exercises exactly that path, and the existing transport compliance suite covers the default layout.

🤖 Generated with Claude Code