📡 PostgreSQL LISTEN & NOTIFY for node.js that finally works.
MIT License
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)
})
subscriber.events.on("error", (error) => {
console.error("Fatal database connection error:", error)
process.exit(1)
})
process.on("exit", () => {
subscriber.close()
})
export async function connect () {
await subscriber.connect()
await subscriber.listenTo("my-channel")
}
export async function sendSampleMessage () {
await subscriber.notify("my-channel", {
greeting: "Hey, buddy.",
timestamp: Date.now()
})
}
For details see dist/index.d.ts.
instance.events.on("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.
instance.events.on("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.
instance.events.on("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.
instance.events.on("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.
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.
MIT