Repository files navigation

PostgreSQL can act as a message broker: Send notifications with arbitrary payloads from one database client to others.

Works with node.js 8+ and plain JavaScript or TypeScript 3. Uses the PostgresNOTIFY statement and subscribes to notifications usingLISTEN.

    📡  Send and subscribe to messages

    ⏳  Continuous connection health checks

    ♻️  Reconnects automatically

    ❗️  Proper error handling

    👌  Type-safe API

# using npm:npm install pg-listen# using yarn:yarn add pg-listen

importcreateSubscriberfrom"pg-listen"import{databaseURL}from"./config"// Accepts the same connection config object that the "pg" package would takeconstsubscriber=createSubscriber({connectionString:databaseURL})subscriber.notifications.on("my-channel",(payload)=>{// Payload as passed to subscriber.notify() (see below)console.log("Received notification in 'my-channel':",payload)})subscriber.events.on("error",(error)=>{console.error("Fatal database connection error:",error)process.exit(1)})process.on("exit",()=>{subscriber.close()})exportasyncfunctionconnect(){awaitsubscriber.connect()awaitsubscriber.listenTo("my-channel")}exportasyncfunctionsendSampleMessage(){awaitsubscriber.notify("my-channel",{greeting:"Hey, buddy.",timestamp:Date.now()})}

For details seedist/index.d.ts.

Theconnected event is emitted once after initially establishing the connection and later once after every successful reconnect. Reconnects happen automatically whenpg-listen detects that the connection closed or became unresponsive.

Anerror event is emitted for fatal errors that affect the notification subscription. A standard way of handling those kinds of errors would be toconsole.error()-log the error and terminate the process with a non-zero exit code.

Thiserror event is usually emitted after multiple attempts to reconnect have failed.

Emitted whenever a notification is received. You must have subscribed to that channel before usinginstance.listenTo() in order to receive notifications.

A more convenient way of subscribing to notifications is theinstance.notifications event emitter.

Emitted when a connection issue has been detected and an attempt to re-connect to the database is started.

The convenient way of subscribing to notifications. Don't forget to call.listenTo(channelName) to subscribe the Postgres client to this channel in order to receive notifications.

In one sentence: Because none of the existing packages was working reliably in production.

Using theNOTIFY andLISTEN features is not trivial usingnode-postgres (pg) directly, since you cannot use connection pools and even distinct client connections also tend to time out.

There are already a few packages out there, likepg-pubsub, but neither of them seems to work reliably. Errors are being swallowed, the code is hard to reason about, there is no type-safety, ...

This package aims to fix those shortcomings. Postgres LISTEN & NOTIFY in node that finally works.

Set theDEBUG environment variable topg-listen:* to enable debug logging.

MIT