Add diagnostics_channel TracingChannel support

[MiichelleZhou]

This PR introduces tracing channels support to pg-pool and pg querying methods as discussed in #3619

I haven't yet run a benchmark, but without active tracing or subscribers the overhead is non-existent so existing users shouldn't be affected. The overhead would come from the consumers of the diag channels published here which is done anyways via monkey patching.

I added the following channels:

Channel	Type	Package	Description
pg:query	TracingChannel	pg	Query lifecycle (start, end, error with async context)
pg:connection	TracingChannel	pg	Client connection lifecycle
pg:pool:connect	TracingChannel	pg-pool	Pool connection acquisition lifecycle
pg:pool:release	Channel	pg-pool	Client released back to pool
pg:pool:remove	Channel	pg-pool	Client removed from pool

I understand there may be hesitation given that AI tooling was used in the implementation. To be clear, this isn't a drive-by contribution. I designed the channel layout, wrote the proposal document, and iterated through multiple rounds to handle real edge cases (Node 18 compat, preserving custom Promise types, hasSubscribers guards). The AI assisted with the code, but the approach and decisions are mine.

Usage

Instrumentations will only need to subscribe to tracing channels to create traces, logs or metrics:

import { tracingChannel } from 'diagnostics_channel'

tracingChannel('pg:query').subscribe({
  start({ query, client }) {
    // start span
    // query: { text, name, rowMode }
    // client: { database, host, port, user, processID, ssl }
  },
  asyncEnd({ query, result }) {
    // end span
    // result: { rowCount, command }
  },
  error({ query, error }) {
    // record error on span
  },
})

This is part of a broader initiative to bring TracingChannel support to the most widely used Node.js database and cache libraries. The same pattern has already been merged and shipped in:

• mysql2
• node-redis
• ioredis

I have been directly involved in those prior implementations and I'm happy to own this through to release, address any feedback, and provide whatever support is needed. Would love to hear your thoughts.

Supersedes #3624.

---

Summary by cubic

Adds TracingChannel support to pg and pg-pool so instrumentation libraries can subscribe to query and connection lifecycle events without monkey-patching.

• Exposes pg:query, pg:connection, and pg:pool:connect TracingChannels plus pg:pool:release and pg:pool:remove channels.
• Emits structured context (query details, client info, result metadata) and guards publishing with a shouldTrace check so there's no overhead when no subscribers exist.
• Handles Node 18's missing aggregated hasSubscribers getter by treating undefined as possibly subscribed, and uses traceCallback instead of tracePromise to preserve custom Promise types.

^{Written for commit b922f0d. Summary will update on new commits.}

[Copilot]

Copilot review overview

🟡 Changes recommended

Packaging and lifecycle edge cases currently produce runtime failures or incomplete trace data.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Add diagnostics.js to the pg-pool package allowlist · New
• Preserve metadata for multi-statement query results · New
• Route query timeouts through the traced callback · New

What changed in this PR

Adds native diagnostics channels for tracing pg queries/connections and pg-pool lifecycle events.

Changes:

• Adds tracing and lifecycle channel helpers.
• Instruments query, connection, pool acquisition, release, and removal.
• Adds diagnostics-channel tests.

File	Description
packages/​pg/​lib/​diagnostics.js	Defines pg tracing channels.
packages/​pg/​lib/​client.js	Instruments queries and connections.
packages/​pg/​test/​unit/​client/​diagnostics-tests.js	Tests client diagnostics.
packages/​pg-pool/​diagnostics.js	Defines pool channels.
packages/​pg-pool/​index.js	Publishes pool lifecycle events.
packages/​pg-pool/​test/​diagnostics.js	Tests pool diagnostics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.