PG PubSub

A Publish/Subscribe implementation on top of PostgreSQL NOTIFY/LISTEN

Installation

npm install pg-pubsub --save

Requirements

Node.js >= 6.x

Usage

Simple:

var pubsubInstance = new PGPubsub('postgres://username@localhost/database');
 
pubsubInstance.addChannel('channelName', function (channelPayload) {
  // Process the payload – if it was JSON that JSON has been parsed into an object for you
});
 
pubsubInstance.publish('channelName', { hello: "world" });

The above sends NOTIFY channelName, '{"hello":"world"}' to PostgreSQL, which will trigger the above listener with the parsed JSON in channelPayload.

More advanced variant:

var pubsubInstance = new PGPubsub('postgres://username@localhost/database');
 
pubsubInstance.addChannel('channelName');
 
// pubsubInstance is a full EventEmitter object that sends events on channel names
pubsubInstance.once('channelName', function (channelPayload) {
  // Process the payload
});

new PGPubsub([conString], [options])

• conString – a connection string for the Postgres database. If none is picked, then the default is the same default as for pg.Client()
• options.retryLimit – may be set to a numeric value to limit the the number of retries that are made

Methods

• addChannel(channelName[, eventListener]) – starts listening on a channel and optionally adds an event listener for that event. As PGPubsub inherits from EventEmitter one also add it oneself.
• removeChannel(channelName[, eventListener]) – either removes all event listeners and stops listeneing on the channel or removes the specified event listener and stops listening on the channel if that was the last listener attached.
• publish(channelName, data) – publishes the specified data JSON-encoded to the specified channel. It may be better to do this by sending the NOTIFY channelName, '{"hello":"world"}' query yourself using your ordinary Postgres pool, rather than relying on the single connection of this module. Returns a Promise that will become rejected or resolved depending on the success of the Postgres call.
• close – closes down the database connection and removes all listeners. Useful for graceful shutdowns.
• All EventEmitter methods are inherited from EventEmitter

Description

Creating a PGPubsub instance will not do much up front. It will prepare itself to start a Postgres connection once the first channel is added and then it will keep a connection open until its shut down, reconnecting it if it gets lost, so that it can constantly listen for new notifications.

Lint / Test

npm test or to watch, install grunt-cli then do grunt watch