Skip to content

P
Postgres FD Implementation
Commit 49c0864d authored by Robert Haas's avatar Robert Haas
Browse files
Options

Documentation for logical decoding. 

Craig Ringer, Andres Freund, Christian Kruse, with edits by me.
parent 8bdd12bb
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1085 additions and 5 deletions
doc/src/sgml/catalogs.sgml
View file @ 49c0864d
......@@ -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
View file @ 49c0864d
......@@ -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
View file @ 49c0864d
......@@ -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">
......
doc/src/sgml/logicaldecoding.sgml 0 → 100644
View file @ 49c0864d
This diff is collapsed.
doc/src/sgml/postgres.sgml
View file @ 49c0864d
......@@ -219,6 +219,7 @@
&spi;
&bgworker;
&logicaldecoding;
</part>
......
doc/src/sgml/protocol.sgml
View file @ 49c0864d
......@@ -1309,9 +1309,22 @@ the simple query protocol can be used in walsender mode.
Passing <literal>database</> as the value instructs walsender to connect to
the database specified in the <literal>dbname</> parameter, which will allow
the connection to be used for logical replication from that database.
</para>
<para>
For the purpose of testing replication commands, you can make a replication
connection via <application>psql</application> or any other <literal>libpq</literal>-using
tool with a connection string including the <literal>replication</literal> option,
e.g.:
<programlisting>
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</programlisting>
However it is often more useful to use
<application>pg_receivexlog</application> (for physical replication) or
<application>pg_recvlogical</application> (for logical replication).
</para>
<para>
The commands accepted in walsender mode are:
<variablelist>
<varlistentry>
<term>IDENTIFY_SYSTEM</term>
......@@ -1764,6 +1777,43 @@ The commands accepted in walsender mode are:
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slotname</> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</></term>
<listitem>
<para>
Instructs server to start streaming WAL for logical replication, starting
at WAL position <replaceable class="parameter">XXX/XXX</>. The server can
reply with an error, e.g. if the requested section of WAL has already
been recycled. On success, server responds with a CopyBothResponse
message, and then starts to stream WAL to the frontend.
</para>
<para>
The output plugin associated with the selected slot is used
to process the output for streaming.
</para>
<variablelist>
<varlistentry>
<term><literal>SLOT</literal> <replaceable class="parameter">slotname</></term>
<listitem>
<para>
The name of the slot to stream changes from. This parameter is required,
and must correspond to an existing logical replication slot created
with <literal>CREATE_REPLICATION_SLOT</literal> in
<literal>LOGICAL</literal> mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">XXX/XXX</></term>
<listitem>
<para>
The WAL position to begin streaming at.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slotname</></term>
......
doc/src/sgml/ref/allfiles.sgml
View file @ 49c0864d
......@@ -183,6 +183,7 @@ Complete list of usable sgml source files in this directory.
<!ENTITY pgDumpall SYSTEM "pg_dumpall.sgml">
<!ENTITY pgIsready SYSTEM "pg_isready.sgml">
<!ENTITY pgReceivexlog SYSTEM "pg_receivexlog.sgml">
<!ENTITY pgRecvlogical SYSTEM "pg_recvlogical.sgml">
<!ENTITY pgResetxlog SYSTEM "pg_resetxlog.sgml">
<!ENTITY pgRestore SYSTEM "pg_restore.sgml">
<!ENTITY postgres SYSTEM "postgres-ref.sgml">
......
doc/src/sgml/ref/alter_table.sgml
View file @ 49c0864d
......@@ -580,7 +580,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="SQL-CREATETABLE-REPLICA-IDENTITY">
<term><literal>REPLICA IDENTITY</literal></term>
<listitem>
<para>
......
doc/src/sgml/ref/create_table.sgml
View file @ 49c0864d
......@@ -137,7 +137,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<variablelist>
<varlistentry>
<varlistentry id="SQL-CREATETABLE-TEMPORARY">
<term><literal>TEMPORARY</> or <literal>TEMP</></term>
<listitem>
<para>
......@@ -171,7 +171,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
</listitem>
</varlistentry>
<varlistentry>
<varlistentry id="SQL-CREATETABLE-UNLOGGED">
<term><literal>UNLOGGED</></term>
<listitem>
<para>
......@@ -1051,6 +1051,17 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
</listitem>
</varlistentry>
<varlistentry>
<term><literal>user_catalog_table</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Declare a table as an additional catalog table, e.g. for the purpose of
logical replication. See
<xref linkend="logicaldecoding-capabilities"> for details.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
......
doc/src/sgml/ref/pg_recvlogical.sgml 0 → 100644
View file @ 49c0864d
This diff is collapsed.
doc/src/sgml/reference.sgml
View file @ 49c0864d
......@@ -231,6 +231,7 @@
&pgDumpall;
&pgIsready;
&pgReceivexlog;
&pgRecvlogical;
&pgRestore;
&psqlRef;
&reindexdb;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment