Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
October 16, 2019 09:01
December 4, 2020 11:45
December 19, 2020 17:26
September 29, 2018 20:30
September 26, 2018 08:15
September 26, 2018 08:15
September 26, 2018 08:15


Postgres LISTEN & NOTIFY that works

Build Status NPM Version

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 Postgres NOTIFY statement and subscribes to notifications using LISTEN.


    📡  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


import createSubscriber from "pg-listen"
import { databaseURL } from "./config"

// Accepts the same connection config object that the "pg" package would take
const subscriber = 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)
})"error", (error) => {
  console.error("Fatal database connection error:", error)

process.on("exit", () => {

export async function connect () {
  await subscriber.connect()
  await subscriber.listenTo("my-channel")

export async function sendSampleMessage () {
  await subscriber.notify("my-channel", {
    greeting: "Hey, buddy.",


For details see dist/index.d.ts.

Error & event handling"connected", listener: () => void)

The connected event is emitted once after initially establishing the connection and later once after every successful reconnect. Reconnects happen automatically when pg-listen detects that the connection closed or became unresponsive."error", listener: (error: Error) => void)

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

This error event is usually emitted after multiple attempts to reconnect have failed."notification", listener: ({ channel, payload }) => void)

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

A more convenient way of subscribing to notifications is the instance.notifications event emitter."reconnect", listener: (attempt: number) => void)

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

instance.notifications.on(channelName: string, listener: (payload: any) => void)

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.

Why another package?

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

Using the NOTIFY and LISTEN features is not trivial using node-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, like pg-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 the DEBUG environment variable to pg-listen:* to enable debug logging.