NOTIFY(7)

NAME

   NOTIFY - generate a notification

SYNOPSIS

   NOTIFY channel [ , payload ]

DESCRIPTION

   The NOTIFY command sends a notification event together with an optional
   "payload" string to each client application that has previously
   executed LISTEN channel for the specified channel name in the current
   database. Notifications are visible to all users.

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

   The information passed to the client for a notification event includes
   the notification channel name, the notifying session's server process
   PID, and the payload string, which is an empty string if it has not
   been specified.

   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 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 channel names to signal different sorts of changes to
   a single table. Alternatively, the payload string could be used to
   differentiate various cases.

   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.

   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, NOTIFY 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.

   It is common for a client that executes NOTIFY to be listening on the
   same notification channel 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.

PARAMETERS

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

   payload
       The "payload" string to be communicated along with the
       notification. This must be specified as a simple string literal. In
       the default configuration it must be shorter than 8000 bytes. (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.)

NOTES

   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 NOTIFY 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 LISTEN 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.

   A transaction that has executed NOTIFY cannot be prepared for two-phase
   commit.

   pg_notify
   To send a notification you can also use the function pg_notify(text,
   text). 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
   NOTIFY command if you need to work with non-constant channel names and
   payloads.

EXAMPLES

   Configure and execute a listen/notify sequence from psql:

       LISTEN virtual;
       NOTIFY virtual;
       Asynchronous notification "virtual" received from server process with PID 8448.
       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.

COMPATIBILITY

   There is no NOTIFY statement in the SQL standard.

SEE ALSO

   LISTEN(7), UNLISTEN(7)

Opportunity

Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.

Education

Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.