Registry / database / aws-xray-sdk-postgres

aws-xray-sdk-postgres

JSON →
library3.12.0jsnpmunverified

aws-xray-sdk-postgres is the official AWS X-Ray patcher for Postgres (pg) Node.js driver, version 3.12.0. It automatically records SQL queries, request/response data, and errors as subsegments under the X-Ray trace. Compatible with Postgres 6.1.0+. Requires aws-xray-sdk-core as a peer dependency. Supports both automatic (via cls-hooked) and manual segment tracking. Ships TypeScript definitions. Maintenance is tied to the SDK core; release cadence is periodic alongside core updates. Key differentiator: seamless integration with AWS X-Ray for tracing database calls with minimal code changes.

databasedevops
npm install aws-xray-sdk-postgres
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · AWS-XRAY-SDK-POSTG
A
aws-xray-sdk-postgres
databasejavascriptv3.12.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

capturePostgres
✓ const capturePostgres = require('aws-xray-sdk-postgres')
✗ const capturePostgres = require('aws-xray-sdk-postgres').capturePostgres
The main export is a function, not an object. Use default require.
AWSXRay
✓ const AWSXRay = require('aws-xray-sdk-core')
✗ const AWSXRay = require('aws-xray-sdk-postgres')
AWSXRay is from aws-xray-sdk-core, not this package. This package only exports capturePostgres.
capturePostgres (TypeScript)
✓ import capturePostgres from 'aws-xray-sdk-postgres'
✗ import { capturePostgres } from 'aws-xray-sdk-postgres'
TypeScript default import works because the module has esModuleInterop or a synthetic default.

Patches the pg driver to automatically record query traces with X-Ray. Connects, runs a SELECT, and logs the result.

const AWSXRay = require('aws-xray-sdk-core'); const capturePostgres = require('aws-xray-sdk-postgres'); const pg = capturePostgres(require('pg')); const client = new pg.Client({ user: process.env.PG_USER ?? 'postgres', host: process.env.PG_HOST ?? 'localhost', database: process.env.PG_DB ?? 'mydb', password: process.env.PG_PASSWORD ?? '', port: parseInt(process.env.PG_PORT ?? '5432'), }); client.connect((err) => { if (err) throw err; client.query('SELECT $1::text as name', ['hello'], (err, result) => { if (err) throw err; console.log(result.rows[0].name); client.end(); }); });
Debug
Known issues
breakingv3 requires Node >= 14.x and aws-xray-sdk-core >= 3.x (peer dependency). Older versions incompatible.
fix
Use Node >=14 and ensure aws-xray-sdk-core ^3.12.0 is installed.
affects: >=3.0.0
deprecatedAutomatic mode uses cls-hooked which has known issues with async/await and may leak segments.
fix
Prefer manual mode by passing segment or use AWSXRay.getSegment() in async contexts.
affects: >=3.0.0
gotchacapturePostgres must receive the pg module itself, not an already patched instance.
fix
Call capturePostgres(require('pg')) before any pg.Client or pg.Pool is created.
affects: >=3.0.0
gotchaIn TypeScript, default import may not compile without esModuleInterop or synthetic default.
fix
Set 'esModuleInterop': true in tsconfig.json or use import * as capturePostgres from 'aws-xray-sdk-postgres'.
affects: >=3.0.0
gotchaSubsegments are not automatically closed if query callbacks throw synchronously.
fix
Ensure errors in callbacks are handled properly (e.g., use try-catch around the callback body).
affects: >=3.0.0
Errors
Common errors & fixes
Error: Cannot find module 'aws-xray-sdk-postgres'
Package not installed
fix
npm install aws-xray-sdk-postgres
TypeError: capturePostgres is not a function
Incorrect import: using destructured named import instead of default import
fix
Use const capturePostgres = require('aws-xray-sdk-postgres') (no braces)
Error: please install aws-xray-sdk-core to use this module
Missing peer dependency aws-xray-sdk-core
fix
npm install aws-xray-sdk-core
Error: pg.Client is not a constructor
capturePostgres was called on a pg instance that was already patched or the wrong object
fix
Call capturePostgres(require('pg')) directly on the default pg module
Upgrade
Version history
3.12.0latest on npm
Audit
Dependencies
aws-xray-sdk-corerequiredPeer dependency providing the X-Ray SDK core for segment/subsegment management
Agent activity
14 hits · last 30 days
node
10
OpenAI (training)
2
Resources
githubhttps://github.com/aws/aws-xray-sdk-node#master ↗
packageaws-xray-sdk-postgres ↗
homepagehttps://github.com/aws/aws-xray-sdk-node/tree/master#readme ↗
aws-xray-sdk-postgres — npm install aws-xray-sdk-postgres · libregistry