# PgPubSub class · @imqueue/pg-pubsub

Source: https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/pg-pubsub 3.0.5 — generated reference, not hand-written

Implements LISTEN/NOTIFY client for PostgreSQL connections.

It is a basic public interface of this library, so the end-user is going to work with this class directly to solve his/her tasks. Construct it with [PgPubSubOptions](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsuboptions/), subscribe channels once connected, then read messages from either the instance's own `'message'` event or the per-channel emitter on [PgPubSub.channels](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.channels/).

**Signature:**

```typescript
export declare class PgPubSub extends EventEmitter 
```
**Extends:** EventEmitter

## Remarks

Subscribe from inside the `'connect'` handler rather than after awaiting `connect()`. The connection reconnects automatically, and only the handler runs again on each reconnect — subscriptions made once, after the first connect, are not restored.

`close()` and `connect()` are a matched pair for temporarily stepping out of message handling: closing releases the channel locks, so another running copy takes over the channels while this one is busy, and connecting again competes for them. Use it when a process needs to do heavy work without holding up its channels. To shut down for good use [PgPubSub.destroy()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.destroy/) instead, which also removes the listeners and cannot be reconnected.

## Example 1

Connect, subscribe two channels and handle their messages:

```typescript
import { type AnyJson, PgPubSub } from '@imqueue/pg-pubsub';

const pubSub = new PgPubSub({ connectionString: process.env.DB_URL });

// subscribe inside 'connect' so the channels are restored on every reconnect
pubSub.on('connect', async () => {
    await Promise.all(
        ['ChannelOne', 'ChannelTwo'].map(channel => pubSub.listen(channel)),
    );
});

// one handler for every channel...
pubSub.on('message', (channel: string, payload: AnyJson) =>
    console.log(channel, payload),
);

// ...or one per channel
pubSub.channels.on('ChannelOne', (payload: AnyJson) => console.log(1, payload));
pubSub.channels.on('ChannelTwo', (payload: AnyJson) => console.log(2, payload));

await pubSub.connect();
```

## Example 2

Step out of handling and come back, letting another copy take the channels:

```typescript
await pubSub.close();
// ... heavy work here; another running copy handles the channels meanwhile
await pubSub.connect();
```

## Constructors


| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(options, logger)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub._constructor_/) |  | Constructs a new instance of the `PgPubSub` class |


## Properties


| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [channels](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.channels/) | `readonly` | PgChannelEmitter | Per-channel event emitter. Listening here scopes a handler to one channel, where the instance's own `'message'` event fires for every channel — which is usually what you want when a process listens to several. |
| [logger](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.logger/) | `readonly` | [AnyLogger](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.anylogger/) | Where connection, listen and lock lifecycle events are reported. Defaults to the console. |
| [options](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.options/) | `readonly` | [PgPubSubOptions](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsuboptions/) | Options this instance was constructed with, merged over the defaults in `DefaultOptions`. |
| [pgClient](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.pgclient/) | `readonly` | [PgClient](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgclient/) | Underlying postgres client. The instance may be replaced during automatic reconnect (pg clients are single-use), so do not cache this reference across reconnects. |


## Methods


| Method | Modifiers | Description |
| --- | --- | --- |
| [activeChannels()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.activechannels/) |  | Returns list of all active subscribed channels |
| [allChannels()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.allchannels/) |  | Returns list of all known channels, despite the fact they are listening (active) or not (inactive). |
| [close()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.close/) |  | Safely closes this database connection |
| [connect()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.connect/) |  | Establishes re-connectable database connection |
| [destroy()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.destroy/) |  | Destroys this object properly, destroying all locks, closing all connections and removing all event listeners to avoid memory leaking. So whenever you need to destroy an object programmatically - use this method. Note, that after destroy it is broken and should be removed from memory. |
| [inactiveChannels()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.inactivechannels/) |  | Returns list of all inactive channels (those which are known, but not actively listening at a time) |
| [isActive(channel)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.isactive/) |  | If channel argument passed will return true if channel is in active state (listening by this pub/sub), false - otherwise. If channel is not specified - will return true if there is at least one active channel listened by this pub/sub, false - otherwise. |
| [listen(channel)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.listen/) |  | Starts listening given channel. If singleListener option is set to true, it guarantees that only one process would be able to listen this channel at a time. |
| [notify(channel, payload)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.notify/) |  | Performs NOTIFY to a given channel with a given payload to all listening subscribers |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on/) |  | Sets `'end'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_9/) |  | Sets any unknown or user-defined event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_1/) |  | Sets `'connect'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_2/) |  | Sets `'close'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_3/) |  | Sets `'listen'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_4/) |  | Sets `'unlisten'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_5/) |  | Sets `'error'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_6/) |  | Sets `'reconnect'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_7/) |  | Sets `'message'` event handler |
| [on(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.on_8/) |  | Sets `'notify'` event handler |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once/) |  | Sets `'end'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_9/) |  | Sets any unknown or user-defined event handler, which would fire only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_1/) |  | Sets `'connect'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_2/) |  | Sets `'close'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_3/) |  | Sets `'listen'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_4/) |  | Sets `'unlisten'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_5/) |  | Sets `'error'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_6/) |  | Sets `'reconnect'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_7/) |  | Sets `'message'` event handler, which fired only one single time |
| [once(event, listener)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.once_8/) |  | Sets `'notify'` event handler, which fired only one single time |
| [unlisten(channel)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.unlisten/) |  | Stops listening of the given channel, and, if singleListener option is set to true - will release an acquired lock (if it was settled). |
| [unlistenAll()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgpubsub.unlistenall/) |  | Stops listening all connected channels, and, if singleListener option is set to true - will release all acquired locks (if any was settled). |