Adding upstream version 15.4.upstream/15.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 &mdash;
+   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>