LISTEN(7)

1LISTEN(7)                PostgreSQL 13.3 Documentation               LISTEN(7)
2
3
4

NAME

6       LISTEN - listen for a notification
7

SYNOPSIS

9       LISTEN channel
10

DESCRIPTION

12       LISTEN registers the current session as a listener on the notification
13       channel named channel. If the current session is already registered as
14       a listener for this notification channel, nothing is done.
15
16       Whenever the command NOTIFY channel is invoked, either by this session
17       or another one connected to the same database, all the sessions
18       currently listening on that notification channel are notified, and each
19       will in turn notify its connected client application.
20
21       A session can be unregistered for a given notification channel with the
22       UNLISTEN command. A session's listen registrations are automatically
23       cleared when the session ends.
24
25       The method a client application must use to detect notification events
26       depends on which PostgreSQL application programming interface it uses.
27       With the libpq library, the application issues LISTEN as an ordinary
28       SQL command, and then must periodically call the function PQnotifies to
29       find out whether any notification events have been received. Other
30       interfaces such as libpgtcl provide higher-level methods for handling
31       notify events; indeed, with libpgtcl the application programmer should
32       not even issue LISTEN or UNLISTEN directly. See the documentation for
33       the interface you are using for more details.
34

PARAMETERS

36       channel
37           Name of a notification channel (any identifier).
38

NOTES

40       LISTEN takes effect at transaction commit. If LISTEN or UNLISTEN is
41       executed within a transaction that later rolls back, the set of
42       notification channels being listened to is unchanged.
43
44       A transaction that has executed LISTEN cannot be prepared for two-phase
45       commit.
46
47       There is a race condition when first setting up a listening session: if
48       concurrently-committing transactions are sending notify events, exactly
49       which of those will the newly listening session receive? The answer is
50       that the session will receive all events committed after an instant
51       during the transaction's commit step. But that is slightly later than
52       any database state that the transaction could have observed in queries.
53       This leads to the following rule for using LISTEN: first execute (and
54       commit!) that command, then in a new transaction inspect the database
55       state as needed by the application logic, then rely on notifications to
56       find out about subsequent changes to the database state. The first few
57       received notifications might refer to updates already observed in the
58       initial database inspection, but this is usually harmless.
59
60       NOTIFY(7) contains a more extensive discussion of the use of LISTEN and
61       NOTIFY.
62

EXAMPLES

64       Configure and execute a listen/notify sequence from psql:
65
66           LISTEN virtual;
67           NOTIFY virtual;
68           Asynchronous notification "virtual" received from server process with PID 8448.
69

COMPATIBILITY

71       There is no LISTEN statement in the SQL standard.
72