{"id":43567,"library":"pg-notify","title":"pg-notify","description":"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.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/aldis-ameriks/pg-notify","tags":["javascript","postgres","pubsub","pg","notify","listen","subscribe","typescript"],"install":[{"cmd":"npm install pg-notify","lang":"bash","label":"npm"},{"cmd":"yarn add pg-notify","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-notify","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for PostgreSQL connection","package":"pg","optional":false}],"imports":[{"note":"Default export, not named. This is the main class.","wrong":"import { PGPubSub } from 'pg-notify'","symbol":"PGPubSub","correct":"import PGPubSub from 'pg-notify'"},{"note":"CJS default import via require; destructuring will not work.","wrong":"const { PGPubSub } = require('pg-notify')","symbol":"PGPubSub (CommonJS)","correct":"const PGPubSub = require('pg-notify')"},{"note":"Types are exported alongside the class; cannot be default-imported.","wrong":"","symbol":"TypeScript types","correct":"import type { PGPubSubOptions, PGPubSubListenEvent } from 'pg-notify'"}],"quickstart":{"code":"import PGPubSub from 'pg-notify';\n\nconst pubsub = new PGPubSub({\n  connectionString: process.env.DATABASE_URL ?? 'postgres://postgres:postgres@localhost:5432/mydb'\n});\n\nasync function main() {\n  await pubsub.connect();\n\n  pubsub.on('chat', (payload) => {\n    console.log('Received:', payload);\n  });\n\n  await pubsub.emit('chat', { user: 'Alice', message: 'Hello!' });\n  await pubsub.emit('chat', 'plain string payload');\n\n  // Wait a bit for messages then close\n  setTimeout(() => pubsub.close(), 2000);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Connects to PostgreSQL, subscribes to 'chat' channel, emits two messages, waits, then closes."},"warnings":[{"fix":"Ensure you parse manually if sending non-JSON strings. Objects are automatically serialized and deserialized.","message":"emit() with object payload auto-converts to JSON string via JSON.stringify; listener receives a JavaScript object if valid JSON, or a string otherwise.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Set maxPayloadSize option if you have reconfigured PostgreSQL's max_notify_payload_length.","message":"Payload 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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use removeListener(listener) as documented.","message":"removeListener(listener) is deprecated in favor of the off() method? Currently removeListener exists but off() is not documented. Check source if using off().","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Use a singleton pubsub instance per connection string or share a pool if needed.","message":"Multiple instances can lead to duplicate connections if not managed properly. Each instance uses its own pg.Client.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Always await pubsub.connect() before using pubsub.","message":"If you do not call pubsub.connect() before on() or emit(), the methods will fail silently or throw unhandled errors.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'7999':39 'activ':49 'altern':62 'automat':32 'broker':69 'built':18,22 'built-in':17 'byte':40 'channel/payload':47 'client':13 'command':21 'compar':60 'default':37 'focus':54 'frequent':52 'javascript':70 'librari':29 'lightweight':10 'like':63 'limit':45 'listen':75 'mainten':50 'match':42 'max':38 'messag':68 'minim':58 'notifi':3,6,74 'notify/listen':20 'overhead':59 'payload':34 'pg':2,5,28,65,73 'pg-notifi':1,4 'pg-pubsub':64 'popular':27 'postgr':11,71 'postgresql':15,43 'provid':31 'pub/sub':12 'pubsub':66,72 'reconnect':33 'releas':53 'sanit':48 'simplic':56 'size':35 'subscrib':76 'top':24 'typescript':77 'use':14 'v1.0.6':7 'valid':36","created_at":"2026-06-05T17:00:24.963663+00:00","updated_at":"2026-06-05T17:00:24.963663+00:00","problems":[{"fix":"Await pubsub.connect() before subscribing: await pubsub.connect(); await pubsub.on(...)","cause":"pubsub.on() called before pubsub.connect() resolves.","error":"Error: listen failed - no connection"},{"fix":"Use default import: import PGPubSub from 'pg-notify'","cause":"Using named import { PGPubSub } from 'pg-notify' but the package has a default export.","error":"TypeError: PGPubSub is not a constructor"},{"fix":"Reduce payload size or increase maxPayloadSize option up to PostgreSQL's max_notify_payload_length.","cause":"emit() called with payload larger than maxPayloadSize (default 7999 bytes).","error":"Error: payload exceeds max size"},{"fix":"Shorten channel name to 63 characters or less.","cause":"PostgreSQL limits channel names to 63 characters.","error":"Error: channel name too long"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/aldis-ameriks/pg-notify#readme","github":"https://github.com/aldis-ameriks/pg-notify","docs":null,"changelog":null,"pypi":null,"npm":"pg-notify","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}