begriffs open source - ai-pg/blob - full-docs/txt/sql-listen.txt

   1
   2 LISTEN
   3
   4    LISTEN — listen for a notification
   5
   6 Synopsis
   7
   8 LISTEN channel
   9
  10 Description
  11
  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 Parameters
  36
  37    channel
  38           Name of a notification channel (any identifier).
  39
  40 Notes
  41
  42    LISTEN takes effect at transaction commit. If LISTEN or UNLISTEN is
  43    executed within a transaction that later rolls back, the set of
  44    notification channels being listened to is unchanged.
  45
  46    A transaction that has executed LISTEN cannot be prepared for two-phase
  47    commit.
  48
  49    There is a race condition when first setting up a listening session: if
  50    concurrently-committing transactions are sending notify events, exactly
  51    which of those will the newly listening session receive? The answer is
  52    that the session will receive all events committed after an instant
  53    during the transaction's commit step. But that is slightly later than
  54    any database state that the transaction could have observed in queries.
  55    This leads to the following rule for using LISTEN: first execute (and
  56    commit!) that command, then in a new transaction inspect the database
  57    state as needed by the application logic, then rely on notifications to
  58    find out about subsequent changes to the database state. The first few
  59    received notifications might refer to updates already observed in the
  60    initial database inspection, but this is usually harmless.
  61
  62    NOTIFY contains a more extensive discussion of the use of LISTEN and
  63    NOTIFY.
  64
  65 Examples
  66
  67    Configure and execute a listen/notify sequence from psql:
  68 LISTEN virtual;
  69 NOTIFY virtual;
  70 Asynchronous notification "virtual" received from server process with PID 8448.
  71
  72 Compatibility
  73
  74    There is no LISTEN statement in the SQL standard.
  75
  76 See Also
  77
  78    NOTIFY, UNLISTEN, max_notify_queue_pages