pg-notify

library1.0.6jsnpmunverified

pg-notify (v1.0.6) is a lightweight Postgres pub/sub client using PostgreSQL's built-in NOTIFY/LISTEN commands, built on top of the popular pg library. It provides automatic reconnection, payload size validation (default max 7999 bytes to match PostgreSQL's limit), and channel/payload sanitization. Active maintenance with frequent releases, focused on simplicity and minimal overhead compared to alternatives like pg-pubsub or message brokers.

database messaging

npm install pg-notify

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-NOTIFY

pg-notify

databasejavascriptv1.0.6

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.

PGPubSub

✓ import PGPubSub from 'pg-notify'

✗ import { PGPubSub } from 'pg-notify'

Default export, not named. This is the main class.

PGPubSub (CommonJS)

✓ const PGPubSub = require('pg-notify')

✗ const { PGPubSub } = require('pg-notify')

CJS default import via require; destructuring will not work.

TypeScript types

✓ import type { PGPubSubOptions, PGPubSubListenEvent } from 'pg-notify'

Types are exported alongside the class; cannot be default-imported.

Connects to PostgreSQL, subscribes to 'chat' channel, emits two messages, waits, then closes.

import PGPubSub from 'pg-notify'; const pubsub = new PGPubSub({ connectionString: process.env.DATABASE_URL ?? 'postgres://postgres:postgres@localhost:5432/mydb' }); async function main() { await pubsub.connect(); pubsub.on('chat', (payload) => { console.log('Received:', payload); }); await pubsub.emit('chat', { user: 'Alice', message: 'Hello!' }); await pubsub.emit('chat', 'plain string payload'); // Wait a bit for messages then close setTimeout(() => pubsub.close(), 2000); } main().catch(console.error);

Debug

Known issues

gotchaemit() with object payload auto-converts to JSON string via JSON.stringify; listener receives a JavaScript object if valid JSON, or a string otherwise.

fix

Ensure you parse manually if sending non-JSON strings. Objects are automatically serialized and deserialized.

affects: >=0.0.0

gotchaPayload size default is 7999 bytes (PostgreSQL's limit). You can set maxPayloadSize option but values > 7999 will cause server rejection unless PostgreSQL is configured with a larger limit.

fix

Set maxPayloadSize option if you have reconfigured PostgreSQL's max_notify_payload_length.

affects: >=0.0.0

deprecatedremoveListener(listener) is deprecated in favor of the off() method? Currently removeListener exists but off() is not documented. Check source if using off().

fix

Use removeListener(listener) as documented.

affects: >=0.0.0

gotchaMultiple instances can lead to duplicate connections if not managed properly. Each instance uses its own pg.Client.

fix

Use a singleton pubsub instance per connection string or share a pool if needed.

affects: >=0.0.0

gotchaIf you do not call pubsub.connect() before on() or emit(), the methods will fail silently or throw unhandled errors.

fix

Always await pubsub.connect() before using pubsub.

affects: >=0.0.0

Errors

Common errors & fixes

Error: listen failed - no connection

pubsub.on() called before pubsub.connect() resolves.

fix

Await pubsub.connect() before subscribing: await pubsub.connect(); await pubsub.on(...)

TypeError: PGPubSub is not a constructor

Using named import { PGPubSub } from 'pg-notify' but the package has a default export.

fix

Use default import: import PGPubSub from 'pg-notify'

Error: payload exceeds max size

emit() called with payload larger than maxPayloadSize (default 7999 bytes).

fix

Reduce payload size or increase maxPayloadSize option up to PostgreSQL's max_notify_payload_length.

Error: channel name too long

PostgreSQL limits channel names to 63 characters.

fix

Shorten channel name to 63 characters or less.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

pgrequiredpeer dependency required for PostgreSQL connection

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/aldis-ameriks/pg-notify ↗

packagepg-notify ↗

homepagehttps://github.com/aldis-ameriks/pg-notify#readme ↗