LISTEN(7)

1LISTEN(7)                PostgreSQL 12.2 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
35       NOTIFY(7) contains a more extensive discussion of the use of LISTEN and
36       NOTIFY.
37

PARAMETERS

39       channel
40           Name of a notification channel (any identifier).
41

NOTES

43       LISTEN takes effect at transaction commit. If LISTEN or UNLISTEN is
44       executed within a transaction that later rolls back, the set of
45       notification channels being listened to is unchanged.
46
47       A transaction that has executed LISTEN cannot be prepared for two-phase
48       commit.
49

EXAMPLES

51       Configure and execute a listen/notify sequence from psql:
52
53           LISTEN virtual;
54           NOTIFY virtual;
55           Asynchronous notification "virtual" received from server process with PID 8448.
56

COMPATIBILITY

58       There is no LISTEN statement in the SQL standard.
59