doc/src/sgml/ref/notify.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-NOTIFY">
   7  <refmeta>
   8   <refentrytitle id="sql-notify-title">NOTIFY</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>NOTIFY</refname>
  15   <refpurpose>generate a notification</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-notify">
  19   <primary>NOTIFY</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 NOTIFY <replaceable class="PARAMETER">name</replaceable>
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    The <command>NOTIFY</command> command sends a notification event to each
  33    client application that has previously executed
  34    <command>LISTEN <replaceable class="parameter">name</replaceable></command>
  35    for the specified notification name in the current database.
  36   </para>
  37
  38   <para>
  39    <command>NOTIFY</command> provides a simple form of signal or
  40    interprocess communication mechanism for a collection of processes
  41    accessing the same <productname>PostgreSQL</productname> database.
  42    Higher-level mechanisms can be built by using tables in the database to
  43    pass additional data (beyond a mere notification name) from notifier to
  44    listener(s).
  45   </para>
  46
  47   <para>
  48    The information passed to the client for a notification event includes the notification
  49    name and the notifying session's server process <acronym>PID</>.  It is up to the
  50    database designer to define the notification names that will be used in a given
  51    database and what each one means.
  52   </para>
  53
  54   <para>
  55    Commonly, the notification name is the same as the name of some table in
  56    the database, and the notify event essentially means, <quote>I changed this table,
  57    take a look at it to see what's new</quote>.  But no such association is enforced by
  58    the <command>NOTIFY</command> and <command>LISTEN</command> commands.  For
  59    example, a database designer could use several different notification names
  60    to signal different sorts of changes to a single table.
  61   </para>
  62
  63   <para>
  64    When <command>NOTIFY</command> is used to signal the occurrence of changes
  65    to a particular table, a useful programming technique is to put the
  66    <command>NOTIFY</command> in a rule that is triggered by table updates.
  67    In this way, notification happens automatically when the table is changed,
  68    and the application programmer cannot accidentally forget to do it.
  69   </para>
  70
  71   <para>
  72    <command>NOTIFY</command> interacts with SQL transactions in some important
  73    ways.  Firstly, if a <command>NOTIFY</command> is executed inside a
  74    transaction, the notify events are not delivered until and unless the
  75    transaction is committed.  This is appropriate, since if the transaction
  76    is aborted, all the commands within it have had no
  77    effect, including <command>NOTIFY</command>.  But it can be disconcerting if one
  78    is expecting the notification events to be delivered immediately.  Secondly, if
  79    a listening session receives a notification signal while it is within a transaction,
  80    the notification event will not be delivered to its connected client until just
  81    after the transaction is completed (either committed or aborted).  Again, the
  82    reasoning is that if a notification were delivered within a transaction that was
  83    later aborted, one would want the notification to be undone somehow &mdash;
  84    but
  85    the server cannot <quote>take back</quote> a notification once it has sent it to the client.
  86    So notification events are only delivered between transactions.  The upshot of this
  87    is that applications using <command>NOTIFY</command> for real-time signaling
  88    should try to keep their transactions short.
  89   </para>
  90
  91   <para>
  92    <command>NOTIFY</command> behaves like Unix signals in one important
  93    respect: if the same notification name is signaled multiple times in quick
  94    succession, recipients might get only one notification event for several executions
  95    of <command>NOTIFY</command>.  So it is a bad idea to depend on the number
  96    of notifications received.  Instead, use <command>NOTIFY</command> to wake up
  97    applications that need to pay attention to something, and use a database
  98    object (such as a sequence) to keep track of what happened or how many times
  99    it happened.
 100   </para>
 101
 102   <para>
 103    It is common for a client that executes <command>NOTIFY</command>
 104    to be listening on the same notification name itself.  In that case
 105    it will get back a notification event, just like all the other
 106    listening sessions.  Depending on the application logic, this could
 107    result in useless work, for example, reading a database table to
 108    find the same updates that that session just wrote out.  It is
 109    possible to avoid such extra work by noticing whether the notifying
 110    session's server process <acronym>PID</> (supplied in the
 111    notification event message) is the same as one's own session's
 112    <acronym>PID</> (available from <application>libpq</>).  When they
 113    are the same, the notification event is one's own work bouncing
 114    back, and can be ignored.  (Despite what was said in the preceding
 115    paragraph, this is a safe technique.
 116    <productname>PostgreSQL</productname> keeps self-notifications
 117    separate from notifications arriving from other sessions, so you
 118    cannot miss an outside notification by ignoring your own
 119    notifications.)
 120   </para>
 121  </refsect1>
 122
 123  <refsect1>
 124   <title>Parameters</title>
 125
 126   <variablelist>
 127    <varlistentry>
 128     <term><replaceable class="PARAMETER">name</replaceable></term>
 129     <listitem>
 130      <para>
 131       Name of the notification to be signaled (any identifier).
 132      </para>
 133     </listitem>
 134    </varlistentry>
 135   </variablelist>
 136  </refsect1>
 137
 138  <refsect1>
 139   <title>Examples</title>
 140
 141   <para>
 142    Configure and execute a listen/notify sequence from
 143    <application>psql</application>:
 144
 145 <programlisting>
 146 LISTEN virtual;
 147 NOTIFY virtual;
 148 Asynchronous notification "virtual" received from server process with PID 8448.
 149 </programlisting>
 150   </para>
 151  </refsect1>
 152
 153  <refsect1>
 154   <title>Compatibility</title>
 155
 156   <para>
 157    There is no <command>NOTIFY</command> statement in the SQL
 158    standard.
 159   </para>
 160  </refsect1>
 161
 162  <refsect1>
 163   <title>See Also</title>
 164
 165   <simplelist type="inline">
 166    <member><xref linkend="sql-listen" endterm="sql-listen-title"></member>
 167    <member><xref linkend="sql-unlisten" endterm="sql-unlisten-title"></member>
 168   </simplelist>
 169  </refsect1>
 170 </refentry>