Provided by: postgresql-client-8.4_8.4.11-1_amd64 bug

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  notification  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  automatically  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  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 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 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 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 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.

       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 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 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)]