From 5e45211a64149b3c659b90ff2de6fa982a5a93ed Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 14:17:33 +0200 Subject: Adding upstream version 15.5. Signed-off-by: Daniel Baumann --- doc/src/sgml/man7/NOTIFY.7 | 154 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 doc/src/sgml/man7/NOTIFY.7 (limited to 'doc/src/sgml/man7/NOTIFY.7') diff --git a/doc/src/sgml/man7/NOTIFY.7 b/doc/src/sgml/man7/NOTIFY.7 new file mode 100644 index 0000000..c99fe41 --- /dev/null +++ b/doc/src/sgml/man7/NOTIFY.7 @@ -0,0 +1,154 @@ +'\" t +.\" Title: NOTIFY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "NOTIFY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +NOTIFY \- generate a notification +.SH "SYNOPSIS" +.sp +.nf +NOTIFY \fIchannel\fR [ , \fIpayload\fR ] +.fi +.SH "DESCRIPTION" +.PP +The +\fBNOTIFY\fR +command sends a notification event together with an optional +\(lqpayload\(rq +string to each client application that has previously executed +\fBLISTEN \fR\fB\fIchannel\fR\fR +for the specified channel name in the current database\&. Notifications are visible to all users\&. +.PP +\fBNOTIFY\fR +provides a simple interprocess communication mechanism for a collection of processes accessing the same +PostgreSQL +database\&. A payload string can be sent along with the notification, and higher\-level mechanisms for passing structured data can be built by using tables in the database to pass additional data from notifier to listener(s)\&. +.PP +The information passed to the client for a notification event includes the notification channel name, the notifying session\*(Aqs server process +PID, and the payload string, which is an empty string if it has not been specified\&. +.PP +It is up to the database designer to define the channel names that will be used in a given database and what each one means\&. Commonly, the channel name is the same as the name of some table in the database, and the notify event essentially means, +\(lqI changed this table, take a look at it to see what\*(Aqs new\(rq\&. But no such association is enforced by the +\fBNOTIFY\fR +and +\fBLISTEN\fR +commands\&. For example, a database designer could use several different channel names to signal different sorts of changes to a single table\&. Alternatively, the payload string could be used to differentiate various cases\&. +.PP +When +\fBNOTIFY\fR +is used to signal the occurrence of changes to a particular table, a useful programming technique is to put the +\fBNOTIFY\fR +in a statement trigger that is triggered by table updates\&. In this way, notification happens automatically when the table is changed, and the application programmer cannot accidentally forget to do it\&. +.PP +\fBNOTIFY\fR +interacts with SQL transactions in some important ways\&. Firstly, if a +\fBNOTIFY\fR +is executed inside a transaction, the notify events are not delivered until and unless the transaction is committed\&. This is appropriate, since if the transaction is aborted, all the commands within it have had no effect, including +\fBNOTIFY\fR\&. But it can be disconcerting if one is expecting the notification events to be delivered immediately\&. Secondly, if a listening session receives a notification signal while it is within a transaction, the notification event will not be delivered to its connected client until just after the transaction is completed (either committed or aborted)\&. Again, the reasoning is that if a notification were delivered within a transaction that was later aborted, one would want the notification to be undone somehow \(em but the server cannot +\(lqtake back\(rq +a notification once it has sent it to the client\&. So notification events are only delivered between transactions\&. The upshot of this is that applications using +\fBNOTIFY\fR +for real\-time signaling should try to keep their transactions short\&. +.PP +If the same channel name is signaled multiple times with identical payload strings within the same transaction, only one instance of the notification event is delivered to listeners\&. On the other hand, notifications with distinct payload strings will always be delivered as distinct notifications\&. Similarly, notifications from different transactions will never get folded into one notification\&. Except for dropping later instances of duplicate notifications, +\fBNOTIFY\fR +guarantees that notifications from the same transaction get delivered in the order they were sent\&. It is also guaranteed that messages from different transactions are delivered in the order in which the transactions committed\&. +.PP +It is common for a client that executes +\fBNOTIFY\fR +to be listening on the same notification channel itself\&. In that case it will get back a notification event, just like all the other listening sessions\&. Depending on the application logic, this could result in useless work, for example, reading a database table to find the same updates that that session just wrote out\&. It is possible to avoid such extra work by noticing whether the notifying session\*(Aqs server process +PID +(supplied in the notification event message) is the same as one\*(Aqs own session\*(Aqs +PID +(available from +libpq)\&. When they are the same, the notification event is one\*(Aqs own work bouncing back, and can be ignored\&. +.SH "PARAMETERS" +.PP +\fIchannel\fR +.RS 4 +Name of the notification channel to be signaled (any identifier)\&. +.RE +.PP +\fIpayload\fR +.RS 4 +The +\(lqpayload\(rq +string to be communicated along with the notification\&. This must be specified as a simple string literal\&. In the default configuration it must be shorter than 8000 bytes\&. (If binary data or large amounts of information need to be communicated, it\*(Aqs best to put it in a database table and send the key of the record\&.) +.RE +.SH "NOTES" +.PP +There is a queue that holds notifications that have been sent but not yet processed by all listening sessions\&. If this queue becomes full, transactions calling +\fBNOTIFY\fR +will fail at commit\&. The queue is quite large (8GB in a standard installation) and should be sufficiently sized for almost every use case\&. However, no cleanup can take place if a session executes +\fBLISTEN\fR +and then enters a transaction for a very long time\&. Once the queue is half full you will see warnings in the log file pointing you to the session that is preventing cleanup\&. In this case you should make sure that this session ends its current transaction so that cleanup can proceed\&. +.PP +The function +\fBpg_notification_queue_usage\fR +returns the fraction of the queue that is currently occupied by pending notifications\&. See +Section\ \&9.26 +for more information\&. +.PP +A transaction that has executed +\fBNOTIFY\fR +cannot be prepared for two\-phase commit\&. +.SS "pg_notify" +.PP +To send a notification you can also use the function +\fBpg_notify\fR(text, text)\&. The function takes the channel name as the first argument and the payload as the second\&. The function is much easier to use than the +\fBNOTIFY\fR +command if you need to work with non\-constant channel names and payloads\&. +.SH "EXAMPLES" +.PP +Configure and execute a listen/notify sequence from +psql: +.sp +.if n \{\ +.RS 4 +.\} +.nf +LISTEN virtual; +NOTIFY virtual; +Asynchronous notification "virtual" received from server process with PID 8448\&. +NOTIFY virtual, \*(AqThis is the payload\*(Aq; +Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448\&. + +LISTEN foo; +SELECT pg_notify(\*(Aqfo\*(Aq || \*(Aqo\*(Aq, \*(Aqpay\*(Aq || \*(Aqload\*(Aq); +Asynchronous notification "foo" with payload "payload" received from server process with PID 14728\&. +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBNOTIFY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBLISTEN\fR(7), \fBUNLISTEN\fR(7) -- cgit v1.2.3