bun-pg-listen

library0.1.1jsnpmunverified

Zero-dependency polyfill for PostgreSQL LISTEN/NOTIFY in Bun, currently at v0.1.1 with active development. Since Bun's built-in sql driver does not implement LISTEN/NOTIFY, this library provides a temporary, drop-in replacement that mirrors Bun.sql's connection configuration (env vars, URL, inline options) and adds SCRAM-SHA-256 authentication (RFC 7677), exponential backoff reconnection with automatic re-LISTEN, and TLS support (sslmode=require/verify-ca/verify-full). Designed to be removed once Bun native support lands (tracking issue oven-sh/bun#18214). Unlike alternatives like pg or postgres.js, it has zero runtime dependencies and focuses solely on the listen/notify pub/sub pattern for Bun >= 1.2 and Postgres >= 13.

database

npm install bun-pg-listen

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUN-PG-LISTEN

bun-pg-listen

databasejavascriptv0.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PgListener

✓ import { PgListener } from 'bun-pg-listen'

✗ const PgListener = require('bun-pg-listen')

ESM-only; CommonJS require is not supported.

PgListener

✓ const { PgListener } = await import('bun-pg-listen')

Dynamic import is valid for ESM.

default

✓ import PgListener from 'bun-pg-listen'

✗ const PgListener = require('bun-pg-listen')

Default export also available as named.

Shows basic connect, listen with callback, notify, and cleanup using the PgListener class.

import { PgListener } from 'bun-pg-listen'; const listener = new PgListener({ // connection config from env or inline }); await listener.connect(); const unlisten = await listener.listen('page_updates', (payload) => { console.log('Received:', payload); }); await listener.notify('page_updates', JSON.stringify({ pageId: 'abc', op: 'save' })); await unlisten(); await listener.close();

Debug

Known issues

gotchaBun's built-in sql driver does not support LISTEN/NOTIFY; this library is a polyfill. Once oven-sh/bun#18214 is resolved, migrate to native sql.listen.

fix

Monitor Bun releases and remove dependency when native support lands.

affects: >=0.0.1

breakingRequires Bun >= 1.2.0 and PostgreSQL >= 13 for SCRAM-SHA-256 authentication. MD5 authentication is not supported.

fix

Use Bun 1.2+ and Postgres 13+, or ensure server uses SCRAM-SHA-256.

affects: >=0.1.0

deprecatedThe constructor can accept a URL string as first argument, but passing options object is preferred for clarity.

fix

Use object notation: new PgListener({ hostname: '...', ... })

affects: >=0.0.1

gotchaThe library does not support MD5 password authentication. If your Postgres server uses MD5, connection will fail.

fix

Change postgresql.conf to use scram-sha-256 or update pg_hba.conf accordingly.

affects: >=0.0.1

gotchaTLS with sslmode=verify-full requires a valid CA that Bun's bundled CA store recognizes. For private CAs, pass tls.ca option.

fix

Provide CA cert via tls option: new PgListener(url, { tls: { ca: '...' } })

affects: >=0.0.1

Errors

Common errors & fixes

Error: SCRAM authentication requires password in SASLprep form

Password contains unsupported characters (UTF-8 is fine but some special chars need SASLprep).

fix

Ensure password is properly escaped or use alphanumeric characters. The library expects a UTF-8 string.

Error: connection closed unexpectedly

Server closed connection due to idle timeout, network issue, or incompatible auth.

fix

Enable reconnection callbacks (onReconnect) and ensure server supports SCRAM-SHA-256.

Error: No database URL found in environment variables

No connection config provided and no standard env var set (POSTGRES_URL, DATABASE_URL, etc.).

fix

Set one of: POSTGRES_URL, DATABASE_URL, PGURL, or pass config to PgListener constructor.

Error: tls: failed to verify certificate

Server certificate is not trusted by Bun's CA store (e.g., self-signed or private CA).

fix

Pass CA certificate via tls option: { tls: { ca: await Bun.file('ca.pem').text() } }

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

bunrequiredRequires Bun runtime >= 1.2.0

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kklimuk/bun-pg-listen ↗

packagebun-pg-listen ↗

homepagehttps://github.com/kklimuk/bun-pg-listen#readme ↗