granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/listen.sgml

   1 <!--
   2 doc/src/sgml/ref/listen.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-LISTEN">
   7  <refmeta>
   8   <refentrytitle>LISTEN</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>LISTEN</refname>
  15   <refpurpose>listen for a notification</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-listen">
  19   <primary>LISTEN</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 LISTEN <replaceable class="PARAMETER">channel</replaceable>
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>LISTEN</command> registers the current session as a
  33    listener on the notification channel named <replaceable
  34    class="PARAMETER">channel</replaceable>.
  35    If the current session is already registered as a listener for
  36    this notification channel, nothing is done.
  37   </para>
  38
  39   <para>
  40    Whenever the command <command>NOTIFY <replaceable
  41    class="PARAMETER">channel</replaceable></command> is invoked, either
  42    by this session or another one connected to the same database, all
  43    the sessions currently listening on that notification channel are
  44    notified, and each will in turn notify its connected client
  45    application.
  46   </para>
  47
  48   <para>
  49    A session can be unregistered for a given notification channel with the
  50    <command>UNLISTEN</command> command.  A session's listen
  51    registrations are automatically cleared when the session ends.
  52   </para>
  53
  54   <para>
  55    The method a client application must use to detect notification events depends on
  56    which <productname>PostgreSQL</productname> application programming interface it
  57    uses.  With the <application>libpq</> library, the application issues
  58    <command>LISTEN</command> as an ordinary SQL command, and then must
  59    periodically call the function <function>PQnotifies</function> to find out
  60    whether any notification events have been received.  Other interfaces such as
  61    <application>libpgtcl</> provide higher-level methods for handling notify events; indeed,
  62    with <application>libpgtcl</> the application programmer should not even issue
  63    <command>LISTEN</command> or <command>UNLISTEN</command> directly.  See the
  64    documentation for the interface you are using for more details.
  65   </para>
  66
  67   <para>
  68    <xref linkend="sql-notify">
  69    contains a more extensive
  70    discussion of the use of <command>LISTEN</command> and
  71    <command>NOTIFY</command>.
  72   </para>
  73  </refsect1>
  74
  75  <refsect1>
  76   <title>Parameters</title>
  77
  78   <variablelist>
  79    <varlistentry>
  80     <term><replaceable class="PARAMETER">channel</replaceable></term>
  81     <listitem>
  82      <para>
  83       Name of a notification channel (any identifier).
  84      </para>
  85     </listitem>
  86    </varlistentry>
  87   </variablelist>
  88  </refsect1>
  89
  90  <refsect1>
  91   <title>Notes</title>
  92
  93   <para>
  94    <command>LISTEN</command> takes effect at transaction commit.
  95    If <command>LISTEN</command> or <command>UNLISTEN</command> is executed
  96    within a transaction that later rolls back, the set of notification
  97    channels being listened to is unchanged.
  98   </para>
  99   <para>
 100    A transaction that has executed <command>LISTEN</command> cannot be
 101    prepared for two-phase commit.
 102   </para>
 103  </refsect1>
 104
 105  <refsect1>
 106   <title>Examples</title>
 107
 108   <para>
 109    Configure and execute a listen/notify sequence from
 110    <application>psql</application>:
 111
 112 <programlisting>
 113 LISTEN virtual;
 114 NOTIFY virtual;
 115 Asynchronous notification "virtual" received from server process with PID 8448.
 116 </programlisting></para>
 117  </refsect1>
 118
 119  <refsect1>
 120   <title>Compatibility</title>
 121
 122   <para>
 123    There is no <command>LISTEN</command> statement in the SQL
 124    standard.
 125   </para>
 126  </refsect1>
 127
 128  <refsect1>
 129   <title>See Also</title>
 130
 131   <simplelist type="inline">
 132    <member><xref linkend="sql-notify"></member>
 133    <member><xref linkend="sql-unlisten"></member>
 134   </simplelist>
 135  </refsect1>
 136 </refentry>