137 lines
3.8 KiB
Plaintext
137 lines
3.8 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/listen.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-LISTEN">
|
|
<indexterm zone="sql-listen">
|
|
<primary>LISTEN</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle>LISTEN</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>LISTEN</refname>
|
|
<refpurpose>listen for a notification</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
LISTEN <replaceable class="PARAMETER">channel</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>LISTEN</command> registers the current session as a
|
|
listener on the notification channel named <replaceable
|
|
class="PARAMETER">channel</replaceable>.
|
|
If the current session is already registered as a listener for
|
|
this notification channel, nothing is done.
|
|
</para>
|
|
|
|
<para>
|
|
Whenever the command <command>NOTIFY <replaceable
|
|
class="PARAMETER">channel</replaceable></command> is invoked, either
|
|
by this session or another one connected to the same database, all
|
|
the sessions currently listening on that notification channel are
|
|
notified, and each will in turn notify its connected client
|
|
application.
|
|
</para>
|
|
|
|
<para>
|
|
A session can be unregistered for a given notification channel with the
|
|
<command>UNLISTEN</command> command. A session's listen
|
|
registrations are automatically cleared when the session ends.
|
|
</para>
|
|
|
|
<para>
|
|
The method a client application must use to detect notification events depends on
|
|
which <productname>PostgreSQL</productname> application programming interface it
|
|
uses. With the <application>libpq</> library, the application issues
|
|
<command>LISTEN</command> as an ordinary SQL command, and then must
|
|
periodically call the function <function>PQnotifies</function> to find out
|
|
whether any notification events have been received. Other interfaces such as
|
|
<application>libpgtcl</> provide higher-level methods for handling notify events; indeed,
|
|
with <application>libpgtcl</> the application programmer should not even issue
|
|
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
|
|
documentation for the interface you are using for more details.
|
|
</para>
|
|
|
|
<para>
|
|
<xref linkend="sql-notify">
|
|
contains a more extensive
|
|
discussion of the use of <command>LISTEN</command> and
|
|
<command>NOTIFY</command>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">channel</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Name of a notification channel (any identifier).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
<command>LISTEN</command> takes effect at transaction commit.
|
|
If <command>LISTEN</command> or <command>UNLISTEN</command> is executed
|
|
within a transaction that later rolls back, the set of notification
|
|
channels being listened to is unchanged.
|
|
</para>
|
|
<para>
|
|
A transaction that has executed <command>LISTEN</command> cannot be
|
|
prepared for two-phase commit.
|
|
</para>
|
|
</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>LISTEN</command> statement in the SQL
|
|
standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-notify"></member>
|
|
<member><xref linkend="sql-unlisten"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|