<!--
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>