Documentation for logical decoding.

Craig Ringer, Andres Freund, Christian Kruse, with edits by me.

Author: robertmhaas

doc/src/sgml/catalogs.sgml

@@ -5177,7 +5177,7 @@
 
   <para>
    For more on replication slots,
-   see <xref linkend="streaming-replication-slots">.
+   see <xref linkend="streaming-replication-slots"> and <xref linkend="logicaldecoding">.
   </para>
 
   <table>
@@ -5209,6 +5209,13 @@
       <entry>The slot type - <literal>physical</> or <literal>logical</></entry>
      </row>
 
+     <row>
+      <entry><structfield>plugin</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry></entry>
+      <entry>The basename of the shared object containing the output plugin this logical slot is using, or null for physical slots.</entry>
+     </row>
+
      <row>
       <entry><structfield>datoid</structfield></entry>
       <entry><type>oid</type></entry>
@@ -5242,6 +5249,24 @@
       </entry>
      </row>
 
+     <row>
+      <entry><structfield>xmin</structfield></entry>
+      <entry><type>xid</type></entry>
+      <entry></entry>
+      <entry>The oldest transaction that this slot needs the database to
+      retain.  <literal>VACUUM</literal> cannot remove catalog tuples deleted
+      by any later transaction.
+      </entry>
+     </row>
+
+     <row>
+      <entry><structfield>catalog_xmin</structfield></entry>
+      <entry><type>xid</type></entry>
+      <entry></entry>
+      <entry>The <literal>xmin</literal>, or oldest transaction ID, that this
+      slot forces to be retained in the system catalogs. </entry>
+     </row>
+
      <row>
       <entry><structfield>restart_lsn</structfield></entry>
       <entry><type>pg_lsn</type></entry>

doc/src/sgml/filelist.sgml

@@ -91,6 +91,7 @@
 <!ENTITY nls        SYSTEM "nls.sgml">
 <!ENTITY plhandler  SYSTEM "plhandler.sgml">
 <!ENTITY fdwhandler SYSTEM "fdwhandler.sgml">
+<!ENTITY logicaldecoding SYSTEM "logicaldecoding.sgml">
 <!ENTITY protocol   SYSTEM "protocol.sgml">
 <!ENTITY sources    SYSTEM "sources.sgml">
 <!ENTITY storage    SYSTEM "storage.sgml">

doc/src/sgml/func.sgml

@@ -16437,9 +16437,108 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
         command <literal>DROP_REPLICATION_SLOT</>.
        </entry>
       </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>pg_create_logical_replication_slot</primary>
+        </indexterm>
+        <literal><function>pg_create_logical_replication_slot(<parameter>slotname</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type>)</function></literal>
+       </entry>
+       <entry>
+        (<parameter>slotname</parameter> <type>name</type>, <parameter>xlog_position</parameter> <type>pg_lsn</type>)
+       </entry>
+       <entry>
+        Creates a new logical (decoding) replication slot named
+        <parameter>slotname</parameter> using the output plugin
+        <parameter>plugin</parameter>.  A call to this function has the same
+        effect as the replication protocol command
+        <literal>CREATE REPLICATION SLOT ... LOGICAL</literal>.
+       </entry>
+      </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>pg_logical_slot_get_changes</primary>
+        </indexterm>
+        <literal><function>pg_logical_slot_get_changes(<parameter>slotname</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
+       </entry>
+       <entry>
+        (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
+       </entry>
+       <entry>
+        Returns changes in the slot <parameter>slotname</parameter>, starting
+        from the point at which since changes have been consumed last.  If
+        <parameter>upto_lsn</> and <parameter>upto_nchanges</> are NULL,
+        logical decoding will continue until end of WAL.  If 
+        <parameter>upto_lsn</> is non-NULL, decoding will include only
+        those transactions which commit prior to the specified LSN.  If
+        <parameter>upto_nchanges</parameter> is non-NULL, decoding will
+        stop when the number of rows produced by decoding exceeds
+        the specified value.  Note, however, that the actual number of
+        rows returned may be larger, since this limit is only checked after
+        adding the rows produced when decoding each new transaction commit.
+       </entry>
+      </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>pg_logical_slot_peek_changes</primary>
+        </indexterm>
+        <literal><function>pg_logical_slot_peek_changes(<parameter>slotname</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
+       </entry>
+       <entry>
+        (<parameter>location</parameter> <type>text</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
+       </entry>
+       <entry>
+        Behaves just like
+        the <function>pg_logical_slot_get_changes()</function> function,
+        except that changes are not consumed; that is, they will be returned
+        again on future calls.
+       </entry>
+      </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>pg_logical_slot_get_binary_changes</primary>
+        </indexterm>
+        <literal><function>pg_logical_slot_get_binary_changes(<parameter>slotname</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
+       </entry>
+       <entry>
+        (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
+       </entry>
+       <entry>
+        Behaves just like
+        the <function>pg_logical_slot_get_changes()</function> function,
+        except that changes are returned as <type>bytea</type>.
+       </entry>
+      </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>pg_logical_slot_peek_binary_changes</primary>
+        </indexterm>
+        <literal><function>pg_logical_slot_peek_binary_changes(<parameter>slotname</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
+       </entry>
+       <entry>
+        (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
+       </entry>
+       <entry>
+        Behaves just like
+        the <function>pg_logical_slot_get_changes()</function> function,
+        except that changes are returned as <type>bytea</type> and that
+        changes are not consumed; that is, they will be returned again
+        on future calls.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
+
   </sect2>
 
   <sect2 id="functions-admin-dbobject">