Skip to main content

A convenient Python interface to Postgres's LISTEN and NOTIFY features.

Project description

# pgpubsub

pgpubsub provides convenient access to the [event notification
system]( built into
the [PostgreSQL]( database. This provides a
real-time Pub/Sub system similar to the one in

## Usage

First you need to make a connection.

import pgpubsub
pubsub = pgpubsub.connect(user='postgres', database='test')

The arguments accepted by the pgpubsub.connect() function are identical to those
supported by the

### Sending Events

To send an event, use the pubsub.notify() method:

pubsub.notify('test_channel', 'some message')

### Receiving Events

To receive events, you must first subscribe to a specific channel with the
pubsub.listen() method:


You can call pubsub.listen() multiple times to receive events from multiple


Note that channel names must be a valid SQL
To quote from the Postgres docs:

> SQL identifiers and key words must begin with a letter (a-z, but also letters
> with diacritical marks and non-Latin letters) or an underscore (_). Subsequent
> characters in an identifier or key word can be letters, underscores, digits
> (0-9), or dollar signs ($).

Once you have subscribed to one or more channels, you can choose to receive
events either by iterating over, or by repeatedly calling the
pubsub.get_event() method.


Because channels are SQL identifiers rather than strings, they can't be
quoted/escaped by Psycopg2 like strings can. It is not safe to build a channel
name from untrusted user input.


channel = 'events_' + username

If you do, then your whole database could be destroyed by someone with the
username "; DROP TABLE users;". [Mandatory XKCD](


This is a generator over the stream of events coming on the pubsub. It lets you
loop over the events just as you would a list.

for e in
print e.payload

Behind the scenes, the pubsub is blocking on the standard library's
function. You can provide two additional arguments to to
control how timeouts are handled when waiting on

- select_timeout: The number of seconds to wait on before giving
up and trying again. Defaults to 5.
- yield_timeouts: This defaults to False. If set to True, then
will yield a None each time you go for select_timeout seconds before receiving
an event. This is useful for things like WebSockets where you may want to
send a keepalive message even if no new data has been received.


for e in
if e is None:

#### pubsub.get_event()

This method always returns immediately. If an event has been received, it will
return that event. If no event has been received, it will return None.

If multiple events have been received and are waiting in the queue, then
repeated get_event() calls will keep returning the next event until there aren't
any left and it returns None. Example:

>>> pubsub.listen('test')
>>> pubsub.get_event() # Nothing delivered yet, so returns None
>>> pubsub.notify('test', 'message 1')
>>> pubsub.notify('test', 'message 2')
>>> pubsub.get_event()
Notify(9425, 'test', 'message 1')
>>> pubsub.get_event()
Notify(9425, 'test', 'message 2')
>>> pubsub.get_event() # No more messages, so returns None

The pubsub.get_event() method is intended for integration into event loops where
blocking on would cause problems.

### Unsubscribing

If you want to stop receiving events on one of the channels you're currently
subscribed to, you can call pubsub.unlisten():


### Event objects

The event objects returned by and pubsub.get_event() are
instances of psycopg2's
class. They have three possibly-interesting attributes:

- payload: A string containing the actual message.
- channel: The name of the channel to which the event was sent.
- pid: The pid of the process on the Postgres server that's handling the
sender's connection. This can be useful to prevent an endless loop in a
program that both sends and receives events.


my_pid = pubsub.conn.get_backend_pid()
for e in
sender_pid =
if sender_pid != my_pid:
pubsub.notify('echo', e.payload)

# Q & A

**Is it safe to pass pubsub objects between threads?**


**Why use the verbs 'notify' and 'listen' instead of 'publish' and

The methods in pgpubsub are designed to look as much as possible like the actual
SQL commands in Postgres, which are
[NOTIFY]( and
Postgres docs also refer to 'notification events' rather than 'messages', so
pgpubsub uses the same term.

**Why is there no callback-style interface?**

Someday there might be, if there's demand for it and a well-reasoned spec.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pgpubsub-0.0.2.tar.gz (3.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page