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 @goldskycom/pg-listen
# using yarn:
yarn add @goldskycom/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.
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.
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.
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.
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 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