| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.31 2008/11/14 10:22:47 petere Exp $ |
| PostgreSQL documentation |
| --> |
| |
| <refentry id="SQL-NOTIFY"> |
| <refmeta> |
| <refentrytitle id="sql-notify-title">NOTIFY</refentrytitle> |
| <manvolnum>7</manvolnum> |
| <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 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> 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 might 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> |