1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2010-05-18 04:28:53 +02:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.35 2010/05/18 02:28:53 rhaas Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refentry id="SQL-NOTIFY">
|
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>NOTIFY</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2003-04-27 01:56:51 +02:00
|
|
|
<refname>NOTIFY</refname>
|
|
|
|
<refpurpose>generate a notification</refpurpose>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refnamediv>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-notify">
|
|
|
|
<primary>NOTIFY</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-27 01:56:51 +02:00
|
|
|
<synopsis>
|
2010-02-16 23:34:57 +01:00
|
|
|
NOTIFY <replaceable class="PARAMETER">channel</replaceable> [ , <replaceable class="PARAMETER">payload</replaceable> ]
|
2003-04-27 01:56:51 +02:00
|
|
|
</synopsis>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
The <command>NOTIFY</command> command sends a notification event together
|
|
|
|
with an optional <quote>payload</> string to each client application that
|
|
|
|
has previously executed
|
|
|
|
<command>LISTEN <replaceable class="parameter">channel</></command>
|
|
|
|
for the specified channel name in the current database.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
2005-01-04 01:39:53 +01:00
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
<command>NOTIFY</command> provides a simple
|
2005-01-04 01:39:53 +01:00
|
|
|
interprocess communication mechanism for a collection of processes
|
|
|
|
accessing the same <productname>PostgreSQL</productname> database.
|
2010-02-16 23:34:57 +01:00
|
|
|
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).
|
2005-01-04 01:39:53 +01:00
|
|
|
</para>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
The information passed to the client for a notification event includes the
|
|
|
|
notification channel
|
|
|
|
name, the notifying session's server process <acronym>PID</>, and the
|
|
|
|
payload string, which is an empty string if it has not been specified.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
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
|
2003-04-27 01:56:51 +02:00
|
|
|
the database, and the notify event essentially means, <quote>I changed this table,
|
2001-09-13 17:55:24 +02:00
|
|
|
take a look at it to see what's new</quote>. But no such association is enforced by
|
1999-07-06 19:16:42 +02:00
|
|
|
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
|
2010-02-16 23:34:57 +01:00
|
|
|
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.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<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,
|
Wording cleanup for error messages. Also change can't -> cannot.
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 20:10:30 +01:00
|
|
|
and the application programmer cannot accidentally forget to do it.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<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
|
2003-04-27 01:56:51 +02:00
|
|
|
is aborted, all the commands within it have had no
|
1999-07-06 19:16:42 +02:00
|
|
|
effect, including <command>NOTIFY</command>. But it can be disconcerting if one
|
2003-04-27 01:56:51 +02:00
|
|
|
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
|
1999-07-06 19:16:42 +02:00
|
|
|
after the transaction is completed (either committed or aborted). Again, the
|
2003-04-27 01:56:51 +02:00
|
|
|
reasoning is that if a notification were delivered within a transaction that was
|
2005-01-04 01:39:53 +01:00
|
|
|
later aborted, one would want the notification to be undone somehow —
|
|
|
|
but
|
2003-04-27 01:56:51 +02:00
|
|
|
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
|
1999-07-06 19:16:42 +02:00
|
|
|
is that applications using <command>NOTIFY</command> for real-time signaling
|
|
|
|
should try to keep their transactions short.
|
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
If the same channel name is signaled multiple times from the same
|
|
|
|
transaction with identical payload strings, the
|
|
|
|
database server can decide to deliver a single notification only.
|
|
|
|
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.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2003-04-27 01:56:51 +02:00
|
|
|
It is common for a client that executes <command>NOTIFY</command>
|
2010-02-16 23:34:57 +01:00
|
|
|
to be listening on the same notification channel itself. In that case
|
2003-04-27 01:56:51 +02:00
|
|
|
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
|
2010-02-16 23:34:57 +01:00
|
|
|
back, and can be ignored.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2010-02-16 23:34:57 +01:00
|
|
|
<term><replaceable class="PARAMETER">channel</replaceable></term>
|
2003-04-27 01:56:51 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-02-16 23:34:57 +01:00
|
|
|
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</> string to be communicated along with the
|
2010-02-17 01:57:06 +01:00
|
|
|
notification. This must be specified as a simple string literal.
|
|
|
|
In the default configuration it must be shorter than 8000 bytes.
|
2010-02-16 23:34:57 +01:00
|
|
|
(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.)
|
2003-04-27 01:56:51 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
2010-02-16 23:34:57 +01:00
|
|
|
<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>
|
|
|
|
A transaction that has executed <command>NOTIFY</command> cannot be
|
|
|
|
prepared for two-phase commit.
|
|
|
|
</para>
|
2010-05-18 04:28:53 +02:00
|
|
|
|
|
|
|
<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>
|
2010-02-16 23:34:57 +01:00
|
|
|
</refsect1>
|
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
|
|
|
Configure and execute a listen/notify sequence from
|
|
|
|
<application>psql</application>:
|
1998-12-29 03:24:47 +01:00
|
|
|
|
2000-03-26 20:32:30 +02:00
|
|
|
<programlisting>
|
2000-07-21 06:42:28 +02:00
|
|
|
LISTEN virtual;
|
|
|
|
NOTIFY virtual;
|
2003-09-13 01:04:46 +02:00
|
|
|
Asynchronous notification "virtual" received from server process with PID 8448.
|
2010-02-16 23:34:57 +01:00
|
|
|
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.
|
2000-03-26 20:32:30 +02:00
|
|
|
</programlisting>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
1998-12-29 03:24:47 +01:00
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is no <command>NOTIFY</command> statement in the SQL
|
|
|
|
standard.
|
|
|
|
</para>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsect1>
|
2003-09-15 05:21:51 +02:00
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2010-04-03 09:23:02 +02:00
|
|
|
<member><xref linkend="sql-listen"></member>
|
|
|
|
<member><xref linkend="sql-unlisten"></member>
|
2003-09-15 05:21:51 +02:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|