mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-31 16:47:48 +02:00
170 lines
6.4 KiB
Plaintext
170 lines
6.4 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.28 2006/09/16 00:30:19 momjian Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-NOTIFY">
|
|
<refmeta>
|
|
<refentrytitle id="sql-notify-title">NOTIFY</refentrytitle>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>NOTIFY</refname>
|
|
<refpurpose>generate a notification</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="sql-notify">
|
|
<primary>NOTIFY</primary>
|
|
</indexterm>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
NOTIFY <replaceable class="PARAMETER">name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The <command>NOTIFY</command> command sends a notification event to each
|
|
client application that has previously executed
|
|
<command>LISTEN <replaceable class="parameter">name</replaceable></command>
|
|
for the specified notification name in the current database.
|
|
</para>
|
|
|
|
<para>
|
|
<command>NOTIFY</command> provides a simple form of signal or
|
|
interprocess communication mechanism for a collection of processes
|
|
accessing the same <productname>PostgreSQL</productname> database.
|
|
Higher-level mechanisms can be built by using tables in the database to
|
|
pass additional data (beyond a mere notification name) from notifier to
|
|
listener(s).
|
|
</para>
|
|
|
|
<para>
|
|
The information passed to the client for a notification event includes the notification
|
|
name and the notifying session's server process <acronym>PID</>. It is up to the
|
|
database designer to define the notification names that will be used in a given
|
|
database and what each one means.
|
|
</para>
|
|
|
|
<para>
|
|
Commonly, the notification 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 notification names
|
|
to signal different sorts of changes to a single table.
|
|
</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 rule that is triggered by table updates.
|
|
In this way, notification happens automatically when the table is changed,
|
|
and the application programmer can't 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>
|
|
<command>NOTIFY</command> behaves like Unix signals in one important
|
|
respect: if the same notification name is signaled multiple times in quick
|
|
succession, recipients may get only one notification event for several executions
|
|
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
|
|
of notifications received. Instead, use <command>NOTIFY</command> to wake up
|
|
applications that need to pay attention to something, and use a database
|
|
object (such as a sequence) to keep track of what happened or how many times
|
|
it happened.
|
|
</para>
|
|
|
|
<para>
|
|
It is common for a client that executes <command>NOTIFY</command>
|
|
to be listening on the same notification name 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</> (supplied in the
|
|
notification event message) is the same as one's own session's
|
|
<acronym>PID</> (available from <application>libpq</>). When they
|
|
are the same, the notification event is one's own work bouncing
|
|
back, and can be ignored. (Despite what was said in the preceding
|
|
paragraph, this is a safe technique.
|
|
<productname>PostgreSQL</productname> keeps self-notifications
|
|
separate from notifications arriving from other sessions, so you
|
|
cannot miss an outside notification by ignoring your own
|
|
notifications.)
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the notification to be signaled (any identifier).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</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.
|
|
</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" endterm="sql-listen-title"></member>
|
|
<member><xref linkend="sql-unlisten" endterm="sql-unlisten-title"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|