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