Man Pages

notify(7) - phpMan notify(7) - phpMan

Command: man perldoc info search(apropos)  


NOTIFY(7)                        SQL Commands                        NOTIFY(7)



NAME
       NOTIFY - generate a notification


SYNOPSIS
       NOTIFY name


DESCRIPTION
       The  NOTIFY  command  sends a notification event to each client application that has previously executed LISTEN
       name for the specified notification name in the current database.

       NOTIFY provides a simple form of signal or interprocess communication mechanism for a collection  of  processes
       accessing  the  same PostgreSQL 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).

       The information passed to the client for a notification event includes the notification name and the  notifying
       session's  server  process 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.

       Commonly, the notification name is the same as the name of some table in the database,  and  the  notify  event
       essentially  means,  ''I  changed this table, take a look at it to see what's new''. But no such association is
       enforced by the NOTIFY and LISTEN commands. For example, a database designer could use several different  noti-
       fication names to signal different sorts of changes to a single table.

       When  NOTIFY  is used to signal the occurrence of changes to a particular table, a useful programming technique
       is to put the NOTIFY in a rule that is triggered by table updates.  In this way, notification happens automati-
       cally when the table is changed, and the application programmer cannot accidentally forget to do it.

       NOTIFY interacts with SQL transactions in some important ways. Firstly, if a NOTIFY is executed inside a trans-
       action, 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 NOTIFY. 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 ''take back'' a notifica-
       tion  once  it  has sent it to the client.  So notification events are only delivered between transactions. The
       upshot of this is that applications using NOTIFY for real-time signaling should try to keep their  transactions
       short.

       NOTIFY  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  NOTIFY.
       So  it is a bad idea to depend on the number of notifications received. Instead, use NOTIFY to wake up applica-
       tions 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.

       It  is  common  for a client that executes NOTIFY 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 appli-
       cation 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  PID (supplied in the notification event message) is the same as one's own session's
       PID (available from 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.  PostgreSQL keeps
       self-notifications separate from notifications arriving from other sessions, so  you  cannot  miss  an  outside
       notification by ignoring your own notifications.)

PARAMETERS
       name   Name of the notification to be signaled (any identifier).

EXAMPLES
       Configure and execute a listen/notify sequence from psql:

       LISTEN virtual;
       NOTIFY virtual;
       Asynchronous notification "virtual" received from server process with PID 8448.


COMPATIBILITY
       There is no NOTIFY statement in the SQL standard.

SEE ALSO
       LISTEN [listen(7)], UNLISTEN [unlisten(7)]



SQL - Language Statements         2014-02-17                         NOTIFY(7)