begriffs open source - ai-pg/blob - full-docs/man7/LISTEN.7

   1 '\" t
   2 .\"     Title: LISTEN
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "LISTEN" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 LISTEN \- listen for a notification
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 LISTEN \fIchannel\fR
  36 .fi
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBLISTEN\fR
  40 registers the current session as a listener on the notification channel named
  41 \fIchannel\fR\&. If the current session is already registered as a listener for this notification channel, nothing is done\&.
  42 .PP
  43 Whenever the command
  44 \fBNOTIFY \fR\fB\fIchannel\fR\fR
  45 is invoked, either by this session or another one connected to the same database, all the sessions currently listening on that notification channel are notified, and each will in turn notify its connected client application\&.
  46 .PP
  47 A session can be unregistered for a given notification channel with the
  48 \fBUNLISTEN\fR
  49 command\&. A session\*(Aqs listen registrations are automatically cleared when the session ends\&.
  50 .PP
  51 The method a client application must use to detect notification events depends on which
  52 PostgreSQL
  53 application programming interface it uses\&. With the
  54 libpq
  55 library, the application issues
  56 \fBLISTEN\fR
  57 as an ordinary SQL command, and then must periodically call the function
  58 \fBPQnotifies\fR
  59 to find out whether any notification events have been received\&. Other interfaces such as
  60 libpgtcl
  61 provide higher\-level methods for handling notify events; indeed, with
  62 libpgtcl
  63 the application programmer should not even issue
  64 \fBLISTEN\fR
  65 or
  66 \fBUNLISTEN\fR
  67 directly\&. See the documentation for the interface you are using for more details\&.
  68 .SH "PARAMETERS"
  69 .PP
  70 \fIchannel\fR
  71 .RS 4
  72 Name of a notification channel (any identifier)\&.
  73 .RE
  74 .SH "NOTES"
  75 .PP
  76 \fBLISTEN\fR
  77 takes effect at transaction commit\&. If
  78 \fBLISTEN\fR
  79 or
  80 \fBUNLISTEN\fR
  81 is executed within a transaction that later rolls back, the set of notification channels being listened to is unchanged\&.
  82 .PP
  83 A transaction that has executed
  84 \fBLISTEN\fR
  85 cannot be prepared for two\-phase commit\&.
  86 .PP
  87 There is a race condition when first setting up a listening session: if concurrently\-committing transactions are sending notify events, exactly which of those will the newly listening session receive? The answer is that the session will receive all events committed after an instant during the transaction\*(Aqs commit step\&. But that is slightly later than any database state that the transaction could have observed in queries\&. This leads to the following rule for using
  88 \fBLISTEN\fR: first execute (and commit!) that command, then in a new transaction inspect the database state as needed by the application logic, then rely on notifications to find out about subsequent changes to the database state\&. The first few received notifications might refer to updates already observed in the initial database inspection, but this is usually harmless\&.
  89 .PP
  90 \fBNOTIFY\fR(7)
  91 contains a more extensive discussion of the use of
  92 \fBLISTEN\fR
  93 and
  94 \fBNOTIFY\fR\&.
  95 .SH "EXAMPLES"
  96 .PP
  97 Configure and execute a listen/notify sequence from
  98 psql:
  99 .sp
 100 .if n \{\
 101 .RS 4
 102 .\}
 103 .nf
 104 LISTEN virtual;
 105 NOTIFY virtual;
 106 Asynchronous notification "virtual" received from server process with PID 8448\&.
 107 .fi
 108 .if n \{\
 109 .RE
 110 .\}
 111 .SH "COMPATIBILITY"
 112 .PP
 113 There is no
 114 \fBLISTEN\fR
 115 statement in the SQL standard\&.
 116 .SH "SEE ALSO"
 117 \fBNOTIFY\fR(7), \fBUNLISTEN\fR(7), max_notify_queue_pages