pg-pubsub

To use this library, install it as a dependency in your project using npm:

npm install pg-pubsub --save

When instantiating PGPubsub, you can provide an optional options object:

• log: A Function used for logging. By default, it is silent when NODE_ENV=production. Otherwise, it defaults to console.log(...).

{
  log: function(msg) { console.log(msg); }
}

Because PGPubsub is an EventEmitter, you can use standard event methods like .once() or .on() to handle channel notifications.

const PGPubsub = require('pg-pubsub');
const pubsubInstance = new PGPubsub('postgres://username@localhost/database');

await pubsubInstance.addChannel('channelName');

// pubsubInstance is a full EventEmitter object that sends events on channel names
pubsubInstance.once('channelName', channelPayload => {
  // Process the payload
});

This example demonstrates how to subscribe to a channel and publish a message to it.

const PGPubsub = require('pg-pubsub');
const pubsubInstance = new PGPubsub('postgres://username@localhost/database');

await pubsubInstance.addChannel('channelName', function (channelPayload) {
  // Process the payload – if it was JSON that JSON has been parsed into an object for you
});

await pubsubInstance.publish('channelName', { hello: "world" });

Create a new instance of PGPubsub by providing a PostgreSQL connection URI. The instance will prepare itself to connect once the first channel is added and will maintain an open connection to listen for notifications, reconnecting automatically if the connection is lost.

const PGPubsub = require('pg-pubsub');
const pubsubInstance = new PGPubsub('postgres://username@localhost/database', options);

Use publish(channelName, data) to send JSON-encoded data to a specific channel.

Note: For high-performance applications, it may be better to send the NOTIFY channelName, '...' query yourself using your application's standard Postgres connection pool rather than relying on the single connection maintained by this module.

Returns a Promise that resolves or rejects based on the success of the Postgres call.

await pubsubInstance.publish('channelName', { hello: 'world' });

Use removeChannel(channelName[, eventListener]) to stop listening on a channel:

• If an eventListener is provided, it removes that specific listener. If it was the last listener attached to that channel, the module stops listening to the channel in Postgres.
• If no eventListener is provided, it removes all event listeners and stops listening on the channel.

Use addChannel(channelName[, eventListener]) to start listening for notifications on a specific PostgreSQL channel.

• channelName: The name of the channel to listen to.
• eventListener (optional): A callback function that receives the payload. If the payload was JSON-encoded in Postgres, it is automatically parsed into a JavaScript object.

Returns a Promise that resolves when listening has started. Since PGPubsub inherits from EventEmitter, you can also listen to events using standard Node.js EventEmitter methods.

await pubsubInstance.addChannel('channelName', function (channelPayload) {
  // Process the payload
});

Use close() to close the database connection and remove all active listeners. This is recommended for graceful shutdowns of your application.

await pubsubInstance.close();

The PGPubsub class provides a high-level interface for managing PostgreSQL NOTIFY and LISTEN channels using an EventEmitter pattern. It handles automatic connection retries and manages the lifecycle of database connections and channel subscriptions.

Initialization

Initialize the class with either a connection string or a pg ClientConfig object. If no connection string is provided, it defaults to the DATABASE_URL environment variable.

const PGPubsub = require('pg-pubsub');

// Using a connection string
const pubsub = new PGPubsub('postgresql://user:pass@localhost:5432/db');

// Using a ClientConfig object
const pubsub = new PGPubsub({ host: 'localhost', user: 'postgres' }, { retryLimit: 5 });