Add PQTRACE env to enable protocol tracing in libpq
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t253264psql -h localhost -U postgresBuilt from patchset v1 (message #1), September 21, 2026 at 02:12 PM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t253264_1 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t253264_1 && git checkout t253264_1Patchset v1 (message #1) is on t253264_1
Hi,
Currently, libpq provides PQtrace to enable protocol tracing. However,
this can only be enabled by calling the PQtrace function, and there's
currently no way to use it with psql.
This patchset introduces a new PQTRACE option in libpq, allowing to
use protocol tracing in psql:
PQTRACE="-" psql
2026-07-30 14:33:06.654865 F 8 SSLRequest 1234 5679
2026-07-30 14:33:06.656358 B 1 SSLResponse N
...
2026-07-30 14:33:06.659056 B 5 ReadyForQuery I
postgres=#
PQTRACE can also be used in libpq_pipeline to replace the custom code,
simplifying it and adding test coverage on startup packets.
There are some limitations:
- multiple connections writing on the same file will overwrite each
other, so it is not supported.
- PQtrace won't be enabled on cancel connections if the target is a
file. If the target is stdout, PQtrace is enabled as 0004 modifies
fe-trace.c so lines are written in a single fwrite, preventing
possible interleaving.
Given that the goal is mostly to provide a quick and easy way to debug
protocol behavior, those limitations seem acceptable. With this
option, it will also be possible to create a test harness similar to
regress, where SQL scripts can be tested against expected traces and
outputs.
The patchset has the following files:
0001: Create the pqTraceOutputNbyte and use it for BackendKeyData and
CancelRequest to print the backend key as hex string.
Given that the BackendKeyData is a random key, there's not much
meaning to show the printable chars.
0002: Add additional regress masking for StartupMessage and
ParameterValue. Since those messages will appear in regression tests,
some of their values need to be masked.
0003: Add a mismatch length check on pqTraceOutputNoTypeByteMessage,
similar to what's already done in pqTraceOutputMessage.
0004: Make PQtrace write lines atomically. Instead of doing multiple
fprintf for a single line, a line is now buffered in a PQExpBuffer and
written as a single fwrite.
This will allow multiple connections tracing on stdout to print
without interleaving.
0005: Add the PQTRACE option to libpq.
0006: Switch libpq_pipeline to use PQTRACE. This simplifies
libpq_pipeline, and also adds startup messages to the expected traces.
This was originally posted on [0]/messages/by-id/CAO6_Xqo6gTv9=76H=k2qDRFU+KHuBiY2S=bQynEr6J8gS7L6xA@mail.gmail.com, but the original thread was about
fixing BackendKeyData tracing, so it seems better to create a
dedicated thread for this.
[0]: /messages/by-id/CAO6_Xqo6gTv9=76H=k2qDRFU+KHuBiY2S=bQynEr6J8gS7L6xA@mail.gmail.com
Regards,
Anthonin Bonnefoy
Attachments:
t253264_1v1-0003-Add-mismatch-length-check-on-pqTraceOutputNoTypeB.patchapplication/octet-stream; name=v1-0003-Add-mismatch-length-check-on-pqTraceOutputNoTypeB.patchDownload+15-1
v1-0001-Print-cancel-key-as-a-hex-string-in-trace.patchapplication/octet-stream; name=v1-0001-Print-cancel-key-as-a-hex-string-in-trace.patchDownload+29-3
v1-0002-Add-more-regress-masks-in-pqtrace.patchapplication/octet-stream; name=v1-0002-Add-more-regress-masks-in-pqtrace.patchDownload+25-13
v1-0004-Make-pqtrace-write-lines-atomically.patchapplication/octet-stream; name=v1-0004-Make-pqtrace-write-lines-atomically.patchDownload+265-249
v1-0005-Add-PQTRACE-env-to-enable-protocol-tracing-in-lib.patchapplication/octet-stream; name=v1-0005-Add-PQTRACE-env-to-enable-protocol-tracing-in-lib.patchDownload+116-2
v1-0006-Add-trace-of-startup-packets-in-libpq_pipeline-te.patchapplication/octet-stream; name=v1-0006-Add-trace-of-startup-packets-in-libpq_pipeline-te.patchDownload+225-33
On Fri, 31 Jul 2026 at 11:01, Anthonin Bonnefoy
<anthonin.bonnefoy@datadoghq.com> wrote:
This patchset introduces a new PQTRACE option in libpq, allowing to
use protocol tracing in psql:PQTRACE="-" psql
2026-07-30 14:33:06.654865 F 8 SSLRequest 1234 5679
2026-07-30 14:33:06.656358 B 1 SSLResponse N
...
2026-07-30 14:33:06.659056 B 5 ReadyForQuery I
postgres=#
I haven't had time to review this yet. But this is a feature I've
wanted for a long time! So huge +1 for the idea.