Benchmark: producer batch insert options and send_batch tradeoffs

[NikolayS]

Summary

Benchmarked PgQue producer paths to compare:

1. client-side loop over send();
2. legacy send_batch() implementation (PL/pgSQL loop over insert_event());
3. PR fix: make send_batch set-based #159 set-based send_batch() implementation;
4. PgQ-style direct set-based insert into current_event_table();
5. PgQ-style direct COPY into current_event_table().

This issue documents the numbers and the product/API conclusion: send_batch() is worth keeping as the safe high-level batch API, but COPY/direct table insert remains the expert maximum-throughput path.

Environment / method

• Branch: fix/send-batch-set-based / PR fix: make send_batch set-based #159 implementation.
• Fresh local Postgres DB with sql/pgque.sql installed.
• Python psycopg benchmark harness.
• Each case creates a fresh queue, inserts N events, commits, verifies count, drops queue.
• Repeats: 2 per case; table below uses median.
• Payloads:
  • JSON cases: {"x": i} style payloads.
  • Text cases: opaque-i payloads.
• These are local single-session microbenchmarks, not full server-class published benchmark numbers.

Results

N = 1,000

Path	Median seconds	Events/s
single send() in client loop	0.3277	3,051
legacy loop send_batch(jsonb[])	0.0514	19,470
new set-based send_batch(jsonb[])	0.0134	74,739
legacy loop send_batch(text[])	0.0364	27,494
new set-based send_batch(text[])	0.0090	111,447
direct set-based insert into current_event_table()	0.0058	171,286
direct COPY into current_event_table()	0.0087	114,293

N = 10,000

Path	Median seconds	Events/s
single send() in client loop	3.0403	3,289
legacy loop send_batch(jsonb[])	0.4029	24,822
new set-based send_batch(jsonb[])	0.1167	85,683
legacy loop send_batch(text[])	0.3642	27,457
new set-based send_batch(text[])	0.0748	133,717
direct set-based insert into current_event_table()	0.0674	148,331
direct COPY into current_event_table()	0.0649	154,147

N = 50,000

Path	Median seconds	Events/s
legacy loop send_batch(jsonb[])	2.2683	22,043
new set-based send_batch(jsonb[])	1.1400	43,858
legacy loop send_batch(text[])	1.8915	26,435
new set-based send_batch(text[])	0.6330	78,992
direct set-based insert into current_event_table()	0.2823	177,130
direct COPY into current_event_table()	0.3042	164,364

Interpretation

send_batch() is useful

Even the legacy loop send_batch() beats client-side send() loops because it removes client round-trips.

The set-based implementation in #159 is materially better:

• JSON batch, N=10k: ~3.5× faster than legacy loop.
• Text batch, N=10k: ~4.9× faster than legacy loop.
• Text batch gets close to direct insert/COPY for moderate batch sizes.

send_batch() is not the absolute max-throughput path

Direct PgQ-style insertion into current_event_table() and COPY remain faster, especially at 50k rows.

That is expected: those paths bypass the safe SQL API wrapper and operate directly on queue event tables. They are expert tools.

Product/API conclusion

Keep a two-tier story:

1. send_batch() — safe high-level API for app developers and drivers.

   • Stable grants (pgque_writer).
   • No dynamic table SQL in app code.
   • Returns event ids in input order.
   • Good throughput after fix: make send_batch set-based #159.

2. current_event_table() + direct INSERT/COPY — expert maximum-throughput path.

   • More fragile / lower-level.
   • Requires understanding active event tables, rotation semantics, defaults, and privileges.
   • Should be documented as advanced producer mode, not the default quickstart.

Recommendation

• Merge fix: make send_batch set-based #159 after CI/review if green.
• Document send_batch() as set-based but not COPY-level.
• Add a future docs/benchmark section for expert direct insert/COPY producer mode.
• Do not remove send_batch(); it fills the ergonomic middle between single send() and raw PgQ table access.

Raw benchmark harness

The benchmark was run with a temporary Python/psycopg harness that creates equivalent legacy-loop functions for comparison and measures all paths in fresh queues.

[NikolayS]

Investigation notes from reproducing hardbyte's worker-scaling benchmark:

Benchmark referenced:
https://github.com/hardbyte/postgresql-job-queue-benchmarking/blob/main/results/2026-05-01-worker-scaling/SUMMARY.md

Finding

The published PgQue numbers (~200–300 ev/s) are from the single-row producer path, not from send_batch(..., 1000).

The summary says:

export PRODUCER_BATCH_MAX=1000

but in the benchmark harness this env var is not propagated into Docker adapters. bench_harness/orchestrator.py builds a fixed overrides map and _docker_launch() forwards only that map into the container. The forwarded variables include:

• SAMPLE_EVERY_S
• PRODUCER_RATE
• PRODUCER_MODE
• TARGET_DEPTH
• WORKER_COUNT
• producer rate control-file vars

PRODUCER_BATCH_MAX is absent, so pgque-bench/main.py falls back to:

producer_batch_max = max(1, env_int("PRODUCER_BATCH_MAX", 1))

That means the PgQue adapter uses batch_count == 1 and calls:

SELECT pgque.send(...)

not:

SELECT pgque.send_batch(..., ...::text[])

Trace confirmation

I temporarily instrumented the adapter and saw:

debug_producer_calls == debug_producer_rows_total

So the published run is effectively 1 producer SQL call per event.

Forced-batch run

After temporarily forcing PRODUCER_BATCH_MAX=1000 through Docker and using PR #159 (send_batch set-based implementation), the same benchmark shape shifted to true batches:

producer calls: ~9–12/s
rows/call:     1000
send time:     ~40–45 ms / 1000 rows

Short-run sampled throughput was roughly:

~10k–18k ev/s sampled
median ~10.3k ev/s in the short clean phase

So the 200–300 ev/s result is not representative of batched PgQue.

Why PR #159 doesn't improve their published result

Because their published PgQue path never calls send_batch().

PR #159 optimizes send_batch(). If the benchmark uses send() row-by-row, the optimized code is not on the hot path.

Bottleneck after batching is actually enabled

With real producer batching, producer insert is no longer the ceiling. The bottleneck moves to consumer-side batch processing in the benchmark adapter:

Observed per consumer batch:

consumer batches/s: ~7–8
rows/batch:         ~1200–1400
get_batch_events:   ~18 ms/batch
Python processing:  ~57–69 ms/batch  # includes harness job simulation / asyncio gather / 1ms work
finish_batch:       ~5–6 ms/batch

So the next performance work is not more producer-side send_batch() optimization; it is consumer/batch path profiling and possibly benchmark adapter tuning.

Conclusion

The hardbyte worker-scaling summary should be read as measuring PgQue's single-row producer path. Its note saying PRODUCER_BATCH_MAX=1000 is misleading for PgQue because that env var does not reach the PgQue Docker container.

A fair PgQue batched-producer comparison needs either:

1. forward PRODUCER_BATCH_MAX / PRODUCER_BATCH_MS into Docker adapters, or
2. add explicit CLI flags and include them in overrides, or
3. set adapter-specific batch defaults in pgque-bench/main.py for this scenario.

[NikolayS]

Autoresearch round: producer batching design + benchmarks

We did another deeper round of research on PR #159 / producer batching, including multiple independent review/benchmark agents and local scratch-DB probes. Short version: PR #159 is directionally correct and worth keeping, but #160 should track several follow-up performance paths separately.

Executive summary

1. PR fix: make send_batch set-based #159's set-based send_batch() is a real improvement over the original PL/pgSQL loop.

   • Original implementation: FOREACH over payloads, calling pgque.insert_event() once per item.
   • PR fix: make send_batch set-based #159: one queue/table lookup + one set-based INSERT ... SELECT via internal insert_event_bulk(text[]).
   • This removes per-row PL/pgSQL calls and repeated queue/table resolution.

2. Do not replace PR fix: make send_batch set-based #159's current RETURNING/join shape yet.

   • A no-RETURNING-join prototype looked promising in one run, but round-2 validation showed mixed results.
   • It is also less conservative: it assumes pgque-owned event tables have no triggers/rules/partition routing that could rewrite/skip inserted rows.
   • Recommendation: keep current safer shape in fix: make send_batch set-based #159 unless a future patch proves a stable win across PG14–18 and realistic payloads.

3. The biggest newly discovered opportunity is a future single-JSON-array API.

   • Current safe client/API path uses jsonb[], which is expensive as a wire/API shape.
   • A single $3::jsonb parameter containing the whole array, expanded server-side with jsonb_array_elements(), was ~4–6x faster than current jsonb[] in scratch tests.
   • This should be a separate API/perf PR, not silently folded into fix: make send_batch set-based #159.

4. Clients should expose a raw/text batch fast path.

   • SQL already has send_batch(queue, type, text[]).
   • TS/Python/Go clients currently expose only JSON-safe APIs that call ::jsonb[].
   • Add explicit raw/text APIs later, clearly documented as opaque text, not bytes and not JSON-validated.

5. Direct INSERT/COPY remains the expert maximum-throughput tier.

   • It can beat safe APIs, especially COPY at large batches.
   • But it bypasses queue abstraction/disabled-insert checks/permissions/rotation safety unless documented carefully.

---

Original vs PR #159 implementation

Original send_batch(jsonb[]) on main:

foreach p in array i_payloads loop
    ids := array_append(ids,
        pgque.insert_event(i_queue, i_type, p::text));
end loop;
return ids;

PR #159 introduces an internal set-based primitive:

with input as materialized (
    select u.ord,
           u.payload as ev_data
      from unnest($2::text[]) with ordinality as u(payload, ord)
), numbered as materialized (
    select ord,
           nextval($1) as ev_id,
           ev_data
      from input
     order by ord
), ins as (
    insert into <current_event_table> (...)
    select ev_id, $3, null, null, $4, ev_data, null, null, null, null
      from numbered
     order by ord
    returning ev_id
)
select coalesce(array_agg(numbered.ev_id order by numbered.ord), '{}'::bigint[])
  from numbered
  join ins using (ev_id);

The public wrappers preserve API behavior:

• NULL array: raise payloads must not be null
• empty array: return {} before queue lookup
• non-empty missing queue: queue not found
• disabled queue: Insert into queue disallowed
• returned ids preserve input order

---

Local benchmark signals

These are local Docker/scratch-DB microbenchmarks, not publication-grade server numbers. They are still useful for relative ranking.

Methodology notes

• Fresh queue per run.
• Single producer/session unless noted.
• Mostly Postgres 18 local Docker; some agents used PG17.
• synchronous_commit=on unless noted.
• Small JSON/text payloads unless noted.
• Medians over small repeat counts.

Producer path ordering from repeated probes

Consistent ordering:

1. client row-by-row send() loop — worst, round-trip bound
2. legacy PL/pgSQL-loop send_batch() — better because one client round trip, still per-row server work
3. PR fix: make send_batch set-based #159 set-based send_batch() — much better
4. raw/text set-based path — often faster than JSON-safe path
5. direct table INSERT / COPY — expert ceiling, especially COPY at large N

Representative PG18 producer-only medians from one methodology agent:

Path	N=10k ev/s	N=50k ev/s
client send() loop jsonb	~1.0k	not run
legacy loop send_batch(jsonb[])	~16.4k	~17.8k
set-based send_batch(jsonb[])	~45.9k	~42.3k
legacy loop send_batch(text[])	~24.4k	~25.3k
set-based send_batch(text[])	~136.8k	~96.0k
direct insert into current event table	~116.8k	~128.0k
direct COPY into current event table	~152.0k	~205.1k

Absolute numbers varied across agents/runs, but the ranking was stable.

---

Text-path implementation alternatives

We tested/prototyped several internal text variants:

• current PR input -> numbered -> INSERT RETURNING -> join
• no RETURNING join; aggregate ids from numbered
• generate_subscripts($2, 1) + $2[ord]
• RETURNING-only / nextval in insert select
• temp table staging
• direct insert / COPY baselines

Round-2 validation result:

Variant	Finding
current PR shape	conservative, correct, good performance
no-join text[]	correctness OK, but perf mixed; not a clear win
generate_subscripts	collapses at larger N; likely array subscript cost
RETURNING-only	can be fast but returned order is less formally tied to input order
temp table	decent for large batches, too much complexity/session state
direct/COPY	fastest expert paths, not normal API replacement

Round-2 concrete text measurements:

• 10k small text: current 0.0706s, no-join 0.0593s
• 50k small text: current 0.437s, no-join 0.501s
• 10k large text: current 0.804s, no-join 0.900s

Recommendation for #159: keep current text[] internal primitive shape.

---

JSON batching: important finding

Current PR send_batch(jsonb[]) does:

1. public wrapper receives jsonb[]
2. builds a text[] with array(select payload::text from unnest(i_payloads) ...)
3. calls insert_event_bulk(text[])
4. internal primitive unnests again

That double pass is expensive.

Round-2 JSON measurements:

Case	Current wrapper	Direct jsonb[] primitive	Single $3::jsonb array param
10k small JSON	0.308s	0.251s	0.051s
50k small JSON	1.676s	1.751s	0.395s
10k large JSON (~1.8KB each)	1.594s	1.207s	0.667s

The direct jsonb[] primitive can help some cases but is not universally huge. The single JSONB array parameter is the major win.

Semantic trap: do not use _elements_text() for safe JSON

jsonb_array_elements_text() can be faster, but it changes semantics:

• JSON null becomes SQL NULL
• current jsonb[] behavior stores JSON null as text 'null'

For compatibility, a future single-param JSON API should use:

jsonb_array_elements(i_payloads)

and cast each JSONB element to text, not _text().

Possible future API shape:

create function pgque.send_batch_json(
  i_queue text,
  i_type text,
  i_payloads jsonb
) returns bigint[];

where i_payloads must be a JSON array.

Clients would send one JSON value:

select pgque.send_batch_json($1, $2, $3::jsonb)

This avoids PostgreSQL array parameter encoding/parsing and per-element jsonb[] overhead.

Recommendation: track as a follow-up performance/API PR, not #159.

---

Client-library implications

Current clients all do per-item JSON serialization and call the safe jsonb[] API:

• TypeScript: JSON.stringify(payload) per item -> pgque.send_batch($1, $2, $3::jsonb[])
• Python: json.dumps() per dict/list -> pgque.send_batch(%s, %s, %s::jsonb[])
• Go: json.Marshal() per payload -> pgque.send_batch($1, $2, $3::jsonb[])

Local client benchmark examples:

Client	Current safe batch @1k	Notes
TypeScript	~50k–59k ev/s	varies by run; node-postgres array encoding visible
Python	~19k–23k ev/s	JSON serialization visible, sync psycopg wrapper
Go	not measured here	Go binary unavailable on this host; pgx likely efficient, but still pays server JSONB parse

Raw/same-payload probes showed text[] is usually faster than jsonb[]:

Client	jsonb[]	text[]
Python 1k	~20.8k ev/s	~28.5k ev/s
Python 10k	~31.3k ev/s	~37.7k ev/s
TypeScript 1k	~23.4k ev/s	~43.4k ev/s
TypeScript 10k	~62.4k ev/s	~67.8k ev/s

Round-2 single-JSON-array client probes were even stronger:

Client	current jsonb[] @10k	single JSONB/JSON array @10k
Python	~57k ev/s	~160k–193k ev/s
Node	~91k ev/s	~158k–159k ev/s

API recommendations:

1. Keep current safe JSON methods unchanged:

   • TS sendBatch(queue, type, payloads: unknown[])
   • Python send_batch(queue, type, payloads: list)
   • Go SendBatch(ctx, queue, typ string, payloads []any)

2. Add explicit raw/text APIs:

   • TS sendBatchRaw(...) or sendBatchText(...)
   • Python send_batch_raw(...) / send_batch_text(...)
   • Go SendBatchRaw(...) / SendBatchText(...)

   These should call:

   select pgque.send_batch($1, $2, $3::text[])

   Docs must be blunt:

   • opaque text, not bytes
   • no JSON validation/canonicalization
   • PostgreSQL text cannot store NUL bytes
   • SQL NULL elements become ev_data IS NULL

3. Consider future safe high-throughput JSON API using one JSONB array parameter:

   • SQL send_batch_json(queue, type, payloads jsonb)
   • clients can serialize the whole payload list once and pass $3::jsonb
   • preserve JSON null semantics with jsonb_array_elements(), not _text()

---

Hardbyte benchmark context

The old hardbyte worker-scaling result showing pgque around ~200–300 jobs/s appears to have measured the row-by-row producer path, despite the summary mentioning PRODUCER_BATCH_MAX=1000.

The issue: that env var was not propagated into Docker adapters in that run, so PgQue used:

select pgque.send(...)

not:

select pgque.send_batch(...)

Current hardbyte HEAD reportedly fixed producer batching propagation and includes a bulk-everywhere result where pgque uses send_batch(... text[]), with peak around ~21.8k jobs/s.

Defensible claim: the old ~300 jobs/s number is a row-by-row scenario, not PgQue's batched producer ceiling.

---

Direct INSERT / COPY expert tier

Direct insertion into pgque.current_event_table() and COPY can be fastest, especially for large batches. But this is not a replacement for send_batch().

Risks/caveats:

• caller must resolve current table and sequence correctly
• rotation race / transaction scope must be documented
• disabled-queue checks can be bypassed
• permissions become more complex
• caller must set/omit columns correctly so defaults fire (ev_txid, etc.)
• COPY does not naturally return ids unless caller preallocates them

Recommendation: document as advanced/admin producer mode with a transaction recipe and tests, not default client behavior.

---

Recommendation for PR #159

For #159 itself:

1. Keep set-based send_batch(); it is clearly better than the original loop.
2. Keep current public API unchanged: jsonb[] and text[] overloads.
3. Keep current conservative text[] internal implementation shape; do not switch to no-join based on current evidence.
4. Optional but not required for fix: make send_batch set-based #159: add direct internal jsonb[] primitive to avoid the current jsonb[] -> text[] -> unnest double pass. If scope/timing matters, leave this to a follow-up.
5. Do not add single-JSON-array API in fix: make send_batch set-based #159; make it a separate design/perf PR.

For follow-up work from #160:

• Add client raw/text batch APIs.
• Prototype send_batch_json(queue, type, payloads jsonb) using jsonb_array_elements() and benchmark PG14–18.
• Extend producer benchmarks:
  • batch sizes: 1, 10, 100, 1k, 10k, 50k
  • payload sizes: ~16B, 256B, 2KB
  • paths: client loop, legacy loop, set-based jsonb[], set-based text[], single-json-array, direct insert, COPY
  • report median/p95/variance, WAL bytes if practical, sync_commit on/off
  • include concurrent producers and consumer-side bottleneck profiling
• Document direct INSERT/COPY as expert mode only after rotation/permission/receive tests.

Bottom line

#159 is a good safe improvement and should not be judged only against COPY/direct-table ceilings. But #160 should become the roadmap for the next producer-throughput layer:

1. safe set-based send_batch() now;
2. explicit raw text client/API fast path;
3. future single-JSON-array safe fast path;
4. expert direct INSERT/COPY for maximum throughput.

[NikolayS]

Final bounded autoresearch pass: producer batching API

TL;DR:

• Keep PR fix: make send_batch set-based #159. The set-based text[] primitive is still the right conservative implementation for the current API.
• Do not replace fix: make send_batch set-based #159 with direct jsonb[] internals. In this pass direct jsonb[] was flat/slower than the current wrapper at 10k/50k.
• Best next API: add a single JSON/JSONB array parameter API, expanded with json[b]_array_elements(), not *_elements_text(). It was the only large safe win.
• Client story: keep current safe JSON API, add explicit raw text[] fast path, then add single-json-array safe fast path. Direct INSERT/COPY remains expert mode.

Evidence: PG18 local Docker, small JSON payloads, median of 5

Path	1k ev/s	10k ev/s	50k ev/s
legacy text loop	16k	21k	skipped
#159 current text[]	44k	56k	51k
direct INSERT text	60k	80k	68k
COPY text	96k	130k	172k
legacy jsonb[] loop	15k	18k	skipped
#159 current jsonb[] wrapper	28k	33k	31k
direct jsonb[] primitive	21k	33k	30k
single jsonb array, safe	118k	140k	131k
single json array, safe	112k	157k	144k

Evidence: ~1.8KB payloads, median of 3

Path	1k ev/s	10k ev/s
#159 current text[]	12k	11k
COPY text	40k	42k
#159 current jsonb[] wrapper	7.9k	9.2k
direct jsonb[] primitive	8.7k	7.8k
single jsonb array, safe	19k	18k
single json array, safe	22k	17k

Correctness / semantics checked

• Returned IDs and stored payload order: OK for text[] and single JSON/JSONB prototypes.
• JSON null semantics: using jsonb_array_elements() / json_array_elements() stores JSON null as text 'null'; this is why *_elements_text() must not be used for the safe JSON API.
• Public wrapper behavior: empty array returns {}; NULL array raises payloads must not be null; non-empty missing queue raises; disabled queue raises.
• Receive/ack smoke in this temporary harness was inconclusive: producer rows inserted correctly, but receive() returned no rows after force_tick(). I did not use that as ranking evidence.

Recommendation / next PRs

1. Merge/keep fix: make send_batch set-based #159 shape after the separate PR-lifecycle review items are resolved. No benchmark evidence here justifies changing fix: make send_batch set-based #159 before merge.
2. Add client raw/text methods: sendBatchText / send_batch_text / SendBatchText backed by send_batch(..., text[]).
3. Add a new safe high-throughput SQL API, e.g. send_batch_json(queue, type, payloads jsonb) (or JSON + JSONB overloads), requiring the parameter to be a JSON array and expanding with json[b]_array_elements().
4. Document direct INSERT/COPY as expert producer mode only: fastest, but lower-level, permission/rotation/disabled-queue caveats, COPY cannot naturally return IDs unless caller preallocates them.

Caveats

• These are local single-producer PG18 microbenchmarks with Python/psycopg parameter encoding included; not publication-grade server numbers.
• PG14/16/17 spot-check attempt was cut short because the host filled disk while pulling Docker images; no cross-version claim from this final pass.
• TS/Python prior probes already pointed the same way: single-json-array beats current jsonb[]; this pass focused on confirming the SQL/API decision.

Raw artifacts: /tmp/pgque160-final-20260502-065254/{final_bench.py,bench_small.csv,bench_large.csv,correctness.txt,run_small.log,run_large.log}.

[NikolayS]

TL;DR: reran the #160 producer-batching pass after disk cleanup, this time on PG18 + PG16, with 100/1k/10k/50k batches, small + ~1.8KB payloads, server + Python + TypeScript/node-pg clients, and receive/ack validation.

Recommendation stayed mostly stable:

• Keep PR fix: make send_batch set-based #159 as the conservative mergeable improvement. The set-based text[] primitive is a clear win over the legacy PL/pgSQL loop and preserves current API shape.
• Do not switch internals to direct jsonb[]. It was not consistently better than the current wrapper, and large payloads were often slower.
• Best next safe client API: add a single JSON/JSONB-array parameter path using json[b]_array_elements() (not *_elements_text()). It is the clearest end-to-end client win because it avoids per-element array adaptation/serialization overhead while preserving JSON null as JSON null.
• Raw text[] is still useful as an explicit fast path for already-serialized/opaque payloads.
• Direct INSERT/COPY remain the expert ceiling, especially for large payloads.

Artifacts: /tmp/pgque160_redo_20260502T072333Z (server_bench.csv, client_bench.csv, ts_client_bench.csv, correctness CSVs, scripts, logs). Values below are median k ev/s (min-max k ev/s).

Server-side microbench, 50k rows

Small payloads:

variant	PG18	PG16
#159 current text[]	81 (69-81)	77 (48-81)
#159 current jsonb[]	72 (68-80)	71 (66-78)
no-returning-join text[] prototype	110 (99-120)	112 (105-120)
direct jsonb[] internal prototype	77 (73-83)	69 (65-72)
single jsonb array param	99 (87-104)	87 (68-89)
single json array param	101 (95-109)	95 (89-102)
direct INSERT	118 (112-132)	116 (112-123)
COPY	118 (110-178)	130 (115-157)

Large payloads (~1.8KB):

variant	PG18	PG16
#159 current text[]	18 (17-18)	14 (13-14)
#159 current jsonb[]	15 (15-15)	11 (11-12)
no-returning-join text[] prototype	19 (18-19)	14 (13-15)
direct jsonb[] internal prototype	17 (17-17)	12 (11-12)
single jsonb array param	20 (19-20)	14 (14-15)
single json array param	21 (20-21)	15 (14-15)
direct INSERT	37 (35-39)	34 (33-35)
COPY	56 (54-60)	53 (52-57)

End-to-end client benchmark, 10k rows

Python/psycopg, includes client JSON serialization/adaptation:

path	small PG18	small PG16	large PG18	large PG16
current jsonb[] API	54 (36-56)	50 (45-55)	8 (8-9)	8 (7-9)
raw text[] SQL call	44 (41-62)	50 (49-62)	10 (9-11)	9 (9-11)
single jsonb array param	158 (132-183)	159 (141-175)	18 (16-19)	15 (14-17)

TypeScript/node-pg, includes client JSON serialization/adaptation (3 repeats):

path	small PG18	small PG16	large PG18	large PG16
current jsonb[] API	105 (100-122)	95 (81-95)	9 (9-10)	8 (8-8)
raw text[] SQL call	128 (108-163)	117 (87-126)	15 (12-16)	11 (10-13)
single jsonb array param	179 (160-223)	124 (109-150)	17 (15-17)	15 (14-16)

Correctness checks

Passed on PG18 and PG16:

• returned IDs in input order;
• payload order matches returned IDs;
• JSON null semantics for single jsonb array: JSON null stored as text 'null', not SQL NULL;
• empty array returns {} even for missing queue, matching PR fix: make send_batch set-based #159 compatibility choice;
• NULL array is rejected;
• missing non-empty queue is rejected;
• disabled queue is rejected;
• receive/ack smoke passes after subscribe + force_tick + ticker() in separate transaction.

Skeptic pass / what remains unproven

• The no-returning-join prototype looked consistently faster in this run, but it is a less conservative rewrite than fix: make send_batch set-based #159 and should be a follow-up only after targeted review of CTE execution/ordering assumptions.
• Server microbench paths generate payloads server-side; client tables are better evidence for API ergonomics and serialization cost.
• COPY/direct INSERT numbers are expert-mode baselines, not necessarily public API candidates.
• TS client repeats were 3, not 5, to keep the rerun bounded; Python and server main comparisons used 5 repeats.