sql.postgres.notify

import sql.postgres.notify

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.postgres.notify.* needs import sql.postgres.notify.

LISTEN and NOTIFY, PostgreSQL’s own publish and subscribe.

A connection that has run LISTEN channel receives a message whenever anything runs NOTIFY channel, including from another connection or another process entirely. It is the one part of this adapter with no equivalent in SQLite, so it lives here rather than in the shared contract and is reached through db.native().

var listener = db.native().listener()

listener.listen('jobs')

while true {
  for message in listener.poll() {
    handle(message.payload)
  }
}

Notifications arrive between other messages, so a connection that is busy running statements collects them as it goes and poll() hands over whatever has accumulated. A connection doing nothing else has to ask, which is what wait() does.

Classes

Listener

class sql.postgres.Listener

Subscribes a connection to channels and collects what arrives.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.postgres.Listener(connection)

Parameters

• connection (PostgresConnection)

Listener.channels()

sql.postgres.Listener.channels() -> list[string]

The channels this listener is subscribed to.

Returns list[string]

Listener.listen()

sql.postgres.Listener.listen(channel: string)

Subscribes to channel.

Parameters

• channel (string)

Listener.unlisten()

sql.postgres.Listener.unlisten(channel: string)

Unsubscribes from channel.

Parameters

• channel (string)

Listener.notify()

sql.postgres.Listener.notify(channel: string, payload)

Sends a notification.

The payload is bound rather than pasted in, so it can hold anything including quotes.

Parameters

• channel (string)
• payload (string|nil)

Listener.poll()

sql.postgres.Listener.poll() -> list[dict]

Whatever has arrived since the last call, without waiting.

Returns list[dict] — Each { channel, payload, pid }.

Listener.wait()

sql.postgres.Listener.wait(rounds) -> list[dict]

Waits for at least one notification, checking the connection each time round.

There is no way to block on a socket and a database at once here, so this asks the server a trivial question on each pass, which is what carries any pending notification back with it.

Parameters

• rounds (number|nil) — How many times to check before giving up. Unlimited when nil.

Returns list[dict] — The notifications received, which is empty only if rounds ran out.

Listener.close()

sql.postgres.Listener.close()

Unsubscribes from everything. Safe to call more than once.

Listener.to_string()

sql.postgres.Listener.to_string()

2026, Richard Ore and Zuri contributors