LISTEN / NOTIFY

Postgres' built-in pubsub. The engine ships three helpers — listen, unlisten, notify — that produce CompiledQuery objects you hand to an adapter. Channel names are quoted as identifiers; payloads are bound as parameters.

#The three helpers

Export	SQL
`listen(channel)`	`LISTEN ""`
`unlisten(channel)`	`UNLISTEN ""`
`unlisten('*')`	`UNLISTEN *` — drop every subscription on this connection.
`notify(channel, payload?)`	`SELECT pg_notify($1, $2)` — payload is bound as a parameter.

notify uses pg_notify(channel, payload) rather than the bare NOTIFY channel, 'payload'syntax — the function form lets us bind the payload as a real parameter, which the bare form doesn't support.

#Subscribing

16 lines


1import { listen, unlisten } from 'zanith';
2 
3// Subscribe — runs on whichever connection the adapter hands out.
4await adapter.execute(listen('user_changes'));
5 
6// The adapter is responsible for surfacing notifications. With pg, the
7// underlying client emits a 'notification' event:
8const client = adapter.rawClient(); // pg-specific helper
9client.on('notification', (msg) => {
10  console.log(`channel=${msg.channel} payload=${msg.payload}`);
11});
12 
13// Stop listening:
14await adapter.execute(unlisten('user_changes'));
15// Or drop everything on this connection:
16await adapter.execute(unlisten('*'));

#Publishing

13 lines


1import { notify } from 'zanith';
2 
3// Wake every subscriber to 'user_changes'. Payload is optional.
4await adapter.execute(notify('user_changes'));
5 
6// Carry a payload — bound as a parameter, not interpolated.
7await adapter.execute(notify('user_changes', JSON.stringify({ userId: 42, action: 'updated' })));
8 
9// Inside a transaction — recipients see the notification only after COMMIT.
10await db.transaction(async (tx) => {
11  await tx.user.update({ where: { id: 42 }, data: { lastSeen: new Date() } });
12  await tx.executeRaw(...buildSqlForNotify('user_changes', '{"userId":42}'));
13});

Postgres queues notifications until the enclosing transaction commits. If you want the wake-up to fire alongside the data change, send the notify from inside the same transaction.

#Payload size

Postgres caps notification payloads at 8000 bytes. Use the payload to carry an id and a hint, then have the subscriber fetch the full record — never try to ship a row through it.

5 lines


1// Right.
2notify('user_changes', JSON.stringify({ id: userId, op: 'updated' }));
3 
4// Wrong — will throw above 8KB and is fragile even below.
5notify('user_changes', JSON.stringify(fullUserRecord));