begriffs open source - ai-pg/blob - full-docs/html/sql-listen.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>LISTEN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-insert.html" title="INSERT" /><link rel="next" href="sql-load.html" title="LOAD" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">LISTEN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-insert.html" title="INSERT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-load.html" title="LOAD">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-LISTEN"><div class="titlepage"></div><a id="id-1.9.3.153.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">LISTEN</span></h2><p>LISTEN — listen for a notification</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 LISTEN <em class="replaceable"><code>channel</code></em>
   4 </pre></div><div class="refsect1" id="id-1.9.3.153.5"><h2>Description</h2><p>
   5    <code class="command">LISTEN</code> registers the current session as a
   6    listener on the notification channel named <em class="replaceable"><code>channel</code></em>.
   7    If the current session is already registered as a listener for
   8    this notification channel, nothing is done.
   9   </p><p>
  10    Whenever the command <code class="command">NOTIFY <em class="replaceable"><code>channel</code></em></code> is invoked, either
  11    by this session or another one connected to the same database, all
  12    the sessions currently listening on that notification channel are
  13    notified, and each will in turn notify its connected client
  14    application.
  15   </p><p>
  16    A session can be unregistered for a given notification channel with the
  17    <code class="command">UNLISTEN</code> command.  A session's listen
  18    registrations are automatically cleared when the session ends.
  19   </p><p>
  20    The method a client application must use to detect notification events depends on
  21    which <span class="productname">PostgreSQL</span> application programming interface it
  22    uses.  With the <span class="application">libpq</span> library, the application issues
  23    <code class="command">LISTEN</code> as an ordinary SQL command, and then must
  24    periodically call the function <code class="function">PQnotifies</code> to find out
  25    whether any notification events have been received.  Other interfaces such as
  26    <span class="application">libpgtcl</span> provide higher-level methods for handling notify events; indeed,
  27    with <span class="application">libpgtcl</span> the application programmer should not even issue
  28    <code class="command">LISTEN</code> or <code class="command">UNLISTEN</code> directly.  See the
  29    documentation for the interface you are using for more details.
  30   </p></div><div class="refsect1" id="id-1.9.3.153.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>channel</code></em></span></dt><dd><p>
  31       Name of a notification channel (any identifier).
  32      </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.153.7"><h2>Notes</h2><p>
  33    <code class="command">LISTEN</code> takes effect at transaction commit.
  34    If <code class="command">LISTEN</code> or <code class="command">UNLISTEN</code> is executed
  35    within a transaction that later rolls back, the set of notification
  36    channels being listened to is unchanged.
  37   </p><p>
  38    A transaction that has executed <code class="command">LISTEN</code> cannot be
  39    prepared for two-phase commit.
  40   </p><p>
  41    There is a race condition when first setting up a listening session:
  42    if concurrently-committing transactions are sending notify events,
  43    exactly which of those will the newly listening session receive?
  44    The answer is that the session will receive all events committed after
  45    an instant during the transaction's commit step.  But that is slightly
  46    later than any database state that the transaction could have observed
  47    in queries.  This leads to the following rule for
  48    using <code class="command">LISTEN</code>: first execute (and commit!) that
  49    command, then in a new transaction inspect the database state as needed
  50    by the application logic, then rely on notifications to find out about
  51    subsequent changes to the database state.  The first few received
  52    notifications might refer to updates already observed in the initial
  53    database inspection, but this is usually harmless.
  54   </p><p>
  55    <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>
  56    contains a more extensive
  57    discussion of the use of <code class="command">LISTEN</code> and
  58    <code class="command">NOTIFY</code>.
  59   </p></div><div class="refsect1" id="id-1.9.3.153.8"><h2>Examples</h2><p>
  60    Configure and execute a listen/notify sequence from
  61    <span class="application">psql</span>:
  62
  63 </p><pre class="programlisting">
  64 LISTEN virtual;
  65 NOTIFY virtual;
  66 Asynchronous notification "virtual" received from server process with PID 8448.
  67 </pre></div><div class="refsect1" id="id-1.9.3.153.9"><h2>Compatibility</h2><p>
  68    There is no <code class="command">LISTEN</code> statement in the SQL
  69    standard.
  70   </p></div><div class="refsect1" id="id-1.9.3.153.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>, <a class="xref" href="sql-unlisten.html" title="UNLISTEN"><span class="refentrytitle">UNLISTEN</span></a>, <a class="xref" href="runtime-config-resource.html#GUC-MAX-NOTIFY-QUEUE-PAGES">max_notify_queue_pages</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-insert.html" title="INSERT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-load.html" title="LOAD">Next</a></td></tr><tr><td width="40%" align="left" valign="top">INSERT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> LOAD</td></tr></table></div></body></html>