perf(postgresql-transport): index dequeue path + robust idempotency

[jeremydmiller]

Summary

The Postgres counterpart to #3277. The PostgreSQL queue transport's dequeue (ORDER BY timestamp LIMIT n FOR UPDATE SKIP LOCKED) had no supporting index, so each poll scanned and sorted the queue table.

Changes

• Index the queue table timestamp column so the ordered LIMIT dequeue is an index scan. No SQL changes (ordering stays on timestamp); the index name goes through PostgresqlIdentifier.Shorten for NAMEDATALEN (PostgressqlQueue name size limit #2942).
• Robust idempotency: replaced locale-fragile e.Message.Contains("duplicate key value") with the SQLSTATE unique-violation code (PostgresException.SqlState == 23505).
• Docs: new "Dequeue Performance" note in the PostgreSQL guide.

Why no OptimizeQueueThroughput() here

SQL Server got an opt-in clustered-storage layout (#3277) that gave a ~350× drain improvement. That does not translate to Postgres: PG tables are heaps with no clustered index, so the physical-clustering win doesn't exist. Benchmarked A/B/C to confirm before deciding:

Variant	drain	deep-pop median (30k backlog)	p95
baseline (uuid PK, no index)	69,634/s	3.1 ms	3.9 ms
+ timestamp index (this PR)	98,401/s	0.8 ms	1.0 ms
+ bigint identity seq (rejected)	97,308/s	0.6 ms	0.8 ms

The seq redesign is marginal, so adding the knob would mean a table migration for ~no gain and misleading cross-DB parity. The doc instead points at autovacuum tuning as the real operational lever for high-churn PG queues.

Follow-up (not in this PR)

Batched outbox→queue send, matching the SQL Server transport plan.

Validation

• ✅ Full wolverine.slnx Release build clean.
• ✅ 24 PG transport tests pass locally against PostgreSQL 17 (the Postgres dev environment is reliable, so unlike perf(sqlserver-transport): index dequeue path + opt-in clustered queue layout #3277 the integration suite — including schema provisioning with the new index and idempotent double-send — was validated locally).
• A manual A/B/C benchmark is included (skipped in CI).

🤖 Generated with Claude Code