diff options
Diffstat (limited to 'doc/src/sgml/ref/notify.sgml')
| -rw-r--r-- | doc/src/sgml/ref/notify.sgml | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml new file mode 100644 index 0000000..d7dcbea --- /dev/null +++ b/doc/src/sgml/ref/notify.sgml @@ -0,0 +1,233 @@ +<!-- +doc/src/sgml/ref/notify.sgml +PostgreSQL documentation +--> + +<refentry id="sql-notify"> + <indexterm zone="sql-notify"> + <primary>NOTIFY</primary> + </indexterm> + + <refmeta> + <refentrytitle>NOTIFY</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>NOTIFY</refname> + <refpurpose>generate a notification</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable class="parameter">payload</replaceable> ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>NOTIFY</command> command sends a notification event together + with an optional <quote>payload</quote> string to each client application that + has previously executed + <command>LISTEN <replaceable class="parameter">channel</replaceable></command> + for the specified channel name in the current database. + Notifications are visible to all users. + </para> + + <para> + <command>NOTIFY</command> provides a simple + interprocess communication mechanism for a collection of processes + accessing the same <productname>PostgreSQL</productname> 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). + </para> + + <para> + The information passed to the client for a notification event includes the + notification channel + name, the notifying session's server process <acronym>PID</acronym>, and the + payload string, which is an empty string if it has not been specified. + </para> + + <para> + 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, <quote>I changed this table, + take a look at it to see what's new</quote>. But no such association is enforced by + the <command>NOTIFY</command> and <command>LISTEN</command> 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. + </para> + + <para> + When <command>NOTIFY</command> is used to signal the occurrence of changes + to a particular table, a useful programming technique is to put the + <command>NOTIFY</command> 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. + </para> + + <para> + <command>NOTIFY</command> interacts with SQL transactions in some important + ways. Firstly, if a <command>NOTIFY</command> 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 <command>NOTIFY</command>. 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 — + but + the server cannot <quote>take back</quote> 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 <command>NOTIFY</command> for real-time signaling + should try to keep their transactions short. + </para> + + <para> + 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, + <command>NOTIFY</command> 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. + </para> + + <para> + It is common for a client that executes <command>NOTIFY</command> + 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's server process <acronym>PID</acronym> (supplied in the + notification event message) is the same as one's own session's + <acronym>PID</acronym> (available from <application>libpq</application>). When they + are the same, the notification event is one's own work bouncing + back, and can be ignored. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">channel</replaceable></term> + <listitem> + <para> + Name of the notification channel to be signaled (any identifier). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable class="parameter">payload</replaceable></term> + <listitem> + <para> + The <quote>payload</quote> 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's best to put it in a database table and send the key of the record.) + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + 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 <command>NOTIFY</command> 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 <command>LISTEN</command> 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. + </para> + <para> + The function <function>pg_notification_queue_usage</function> returns the + fraction of the queue that is currently occupied by pending notifications. + See <xref linkend="functions-info"/> for more information. + </para> + <para> + A transaction that has executed <command>NOTIFY</command> cannot be + prepared for two-phase commit. + </para> + + <refsect2> + <title>pg_notify</title> + + <indexterm> + <primary>pg_notify</primary> + </indexterm> + + <para> + To send a notification you can also use the function + <literal><function>pg_notify</function>(<type>text</type>, + <type>text</type>)</literal>. 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 <command>NOTIFY</command> command if you need to work with + non-constant channel names and payloads. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Configure and execute a listen/notify sequence from + <application>psql</application>: + +<programlisting> +LISTEN virtual; +NOTIFY virtual; +Asynchronous notification "virtual" received from server process with PID 8448. +NOTIFY virtual, 'This is the payload'; +Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448. + +LISTEN foo; +SELECT pg_notify('fo' || 'o', 'pay' || 'load'); +Asynchronous notification "foo" with payload "payload" received from server process with PID 14728. +</programlisting></para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>NOTIFY</command> statement in the SQL + standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-listen"/></member> + <member><xref linkend="sql-unlisten"/></member> + </simplelist> + </refsect1> +</refentry> |