@trace-dev/plugin-pg

trace-dev instrumentation for pg (node-postgres). Installed automatically as part of @trace-dev/core — you only need this package directly if you want it without the rest of the bundle.

npm install @trace-dev/plugin-pg

import "@trace-dev/core/init";

With pg installed and initTracer() called, every pool.query(...) call is automatically wrapped in a db-type span, timed with the actual round trip (including connection acquisition), and its call site captured for the 📍 file:line shown in the terminal reporter.

Scope decision: Pool only

This plugin patches pg.Pool.prototype.query — not Client.prototype.query. That's deliberate: Pool is how the overwhelming majority of real backends use pg (raw new pg.Client() is mostly a one-off script/migration pattern, not request-handling code). It also avoids a real trap: pg-pool always dispatches the checked-out client's query() in callback form internally, even when the caller uses the Promise API — a naive "patch Client, skip callback-style calls" design silently instruments nothing for Pool usage. Patching Pool directly sidesteps that entirely and captures the correct call site (from the user's own code, synchronously) plus the full round trip — pool exhaustion under load is a real source of "why is this slow," not overhead worth hiding.

Known limitation (v1): standalone new pg.Client() without a Pool is not instrumented. Tracked as roadmap.

Security

Only the query text/shape is captured (e.g. pg.query(SELECT * FROM users WHERE id = $1)) — never bound parameter values.

Manual usage

import { pgPlugin } from "@trace-dev/plugin-pg";
import { registerPlugin } from "@trace-dev/core";

registerPlugin(pgPlugin);

Normally unnecessary — @trace-dev/core's auto-detection handles this for you.

License

MIT