Registry / messaging / graphql-pg-subscriptions

graphql-pg-subscriptions

library3.3.0jsnpmunverified

A GraphQL subscriptions implementation using PostgreSQL and Apollo's graphql-subscriptions PubSubEngine interface. v3.3.0 is the current stable release. This package allows multiple subscription manager instances to share a PostgreSQL-based PubSub mechanism, supporting large payloads via an optional table (usePayloadTable) to bypass PG NOTIFY's 8000-byte limit. It provides TypeScript types, a commonMessageHandler for transforming messages (e.g. injecting DataLoaders), and an 'error' event for handling failures like oversized payloads. Actively maintained by a solo developer with a focus on simplicity and small size, it works with Express.js and NestJS but is not designed for high-throughput or clustered deployments without additional configuration.

messaging

npm install graphql-pg-subscriptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-PG-SUBSCRI

graphql-pg-subscriptions

messagingjavascriptv3.3.0

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.

PostgresPubSub

✓ import { PostgresPubSub } from 'graphql-pg-subscriptions'

✗ import PostgresPubSub from 'graphql-pg-subscriptions'

Default export does not exist; must use named import. The package ships TypeScript types, so this import works in both ESM and CommonJS with bundler support.

commonMessageHandler

✓ import { commonMessageHandler } from 'graphql-pg-subscriptions'; // Not directly exported; it's a configuration option

✗ import { commonMessageHandler } from 'graphql-pg-subscriptions'

commonMessageHandler is not a symbol but a configuration option passed to the PostgresPubSub constructor. There is no separate named export for it.

withPostgresPubSub

✓ import { withPostgresPubSub } from 'graphql-pg-subscriptions'

Available since v2.0.0 as a convenience wrapper for integrating with Apollo Server's SubscriptionServer. Deprecated in v3.x in favor of direct PostgresPubSub usage.

Demonstrates connecting to PostgreSQL, initializing PostgresPubSub with large payload support, subscribing to errors, publishing messages, and subscribing to events.

import { PostgresPubSub } from 'graphql-pg-subscriptions'; import { Client } from 'pg'; const client = new Client({ user: process.env.PGUSER ?? 'postgres', host: process.env.PGHOST ?? 'localhost', database: process.env.PGDATABASE ?? 'postgres', password: process.env.PGPASSWORD ?? '', port: parseInt(process.env.PGPORT ?? '5432'), }); await client.connect(); const pubsub = new PostgresPubSub({ client, maxListeners: 20, usePayloadTable: true, // Enables storing large payloads in a pg table }); // Subscribe to errors pubsub.subscribe('error', console.error); // Publish a message pubsub.publish('USER_UPDATED', { id: 1, name: 'Alice' }).catch(console.error); // Subscribe to events pubsub.subscribe('USER_UPDATED', (payload) => { console.log('Received:', payload); }).catch(console.error);

Debug

Known issues

breakingIn v3.0.0, the constructor signature changed from `new PostgresPubSub(client: pg.Client, options?)` to `new PostgresPubSub({ client, ...options })`. Passing a bare client object will throw an error.

fix

Upgrade to v3 and wrap the client in an object: `new PostgresPubSub({ client })`.

affects: >=2.0.0 <3.0.0

breakingThe `usePayloadTable` option defaults to `false` in v3.0.0+. In v2.x it defaulted to `true`. If your application relies on large payloads, you must explicitly set `usePayloadTable: true`.

fix

Set `usePayloadTable: true` in the constructor options if you need to bypass PG NOTIFY's size limit.

affects: >=3.0.0

deprecated`withPostgresPubSub` is deprecated in v3.0.0. It was a helper for integrating with Apollo Server's SubscriptionServer, which itself is deprecated in favor of Apollo Server 4's plugin-based subscriptions.

fix

Use `PostgresPubSub` directly and configure your GraphQL server according to its supported subscription setup (e.g., `graphql-subscriptions` with `PubSub.asyncIterator`).

affects: >=3.0.0

gotchaPostgres NOTIFY has a payload size limit of 8000 bytes. If you publish a payload larger than this without setting `usePayloadTable: true`, the client will emit an 'error' event. The error message is 'payload string too long'.

fix

Set `usePayloadTable: true` in the constructor to store payloads in a PostgreSQL table, circumventing the NOTIFY size limit.

affects: all

gotchaThe package does not automatically handle reconnection if the PostgreSQL connection drops. The client passed to PostgresPubSub must be managed externally.

fix

Implement your own reconnection logic for the pg client (e.g., using `pg`'s `Client` with `reconnect` option or a connection pool) and create a new PostgresPubSub instance after reconnection.

affects: all

Errors

Common errors & fixes

TypeError: Class constructor PostgresPubSub cannot be invoked without 'new'

PostgresPubSub is a Class and must be instantiated with the `new` keyword.

fix

Use `const pubsub = new PostgresPubSub({ client })` instead of `PostgresPubSub(...)`.

PostgresPubSub is not a constructor

Importing default instead of named export (e.g., `import PostgresPubSub from 'graphql-pg-subscriptions'`).

fix

Use named import: `import { PostgresPubSub } from 'graphql-pg-subscriptions'`.

payload string too long

Published payload exceeds PostgreSQL NOTIFY limit (8000 bytes) and `usePayloadTable` is not enabled.

fix

Set `usePayloadTable: true` in the constructor options or ensure payloads are under 8000 bytes.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency: provides the PubSubEngine interface and Subscription types required for integration.

pgrequiredRuntime dependency: used to connect to PostgreSQL and manage LISTEN/NOTIFY and optional payload table operations.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/siamahnaf/graphql-pg-subscriptions ↗

packagegraphql-pg-subscriptions ↗

homepagehttps://github.com/siamahnaf/graphql-pg-subscriptions ↗