2017-01-19 18:00:00 +01:00
|
|
|
<!-- doc/src/sgml/logical-replication.sgml -->
|
|
|
|
|
|
|
|
<chapter id="logical-replication">
|
|
|
|
<title>Logical Replication</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication is a method of replicating data objects and their
|
|
|
|
changes, based upon their replication identity (usually a primary key). We
|
|
|
|
use the term logical in contrast to physical replication, which uses exact
|
|
|
|
block addresses and byte-by-byte replication. PostgreSQL supports both
|
2017-11-23 15:39:47 +01:00
|
|
|
mechanisms concurrently, see <xref linkend="high-availability"/>. Logical
|
2017-01-19 18:00:00 +01:00
|
|
|
replication allows fine-grained control over both data replication and
|
|
|
|
security.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication uses a <firstterm>publish</firstterm>
|
|
|
|
and <firstterm>subscribe</firstterm> model with one or
|
|
|
|
more <firstterm>subscribers</firstterm> subscribing to one or more
|
|
|
|
<firstterm>publications</firstterm> on a <firstterm>publisher</firstterm>
|
|
|
|
node. Subscribers pull data from the publications they subscribe to and may
|
|
|
|
subsequently re-publish data to allow cascading replication or more complex
|
|
|
|
configurations.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-04-21 21:33:25 +02:00
|
|
|
Logical replication of a table typically starts with taking a snapshot
|
2017-03-23 13:36:36 +01:00
|
|
|
of the data on the publisher database and copying that to the subscriber.
|
|
|
|
Once that is done, the changes on the publisher are sent to the subscriber
|
|
|
|
as they occur in real-time. The subscriber applies the data in the same
|
|
|
|
order as the publisher so that transactional consistency is guaranteed for
|
2017-01-19 18:00:00 +01:00
|
|
|
publications within a single subscription. This method of data replication
|
|
|
|
is sometimes referred to as transactional replication.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The typical use-cases for logical replication are:
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sending incremental changes in a single database or a subset of a
|
|
|
|
database to subscribers as they occur.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
Firing triggers for individual changes as they arrive on the
|
2017-01-19 18:00:00 +01:00
|
|
|
subscriber.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Consolidating multiple databases into a single one (for example for
|
|
|
|
analytical purposes).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Replicating between different major versions of PostgreSQL.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
2018-06-23 22:35:25 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2018-06-27 07:51:20 +02:00
|
|
|
Replicating between PostgreSQL instances on different platforms (for
|
|
|
|
example Linux to Windows)
|
2018-06-23 22:35:25 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2018-06-27 07:51:20 +02:00
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Giving access to replicated data to different groups of users.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sharing a subset of the database between multiple databases.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The subscriber database behaves in the same way as any other PostgreSQL
|
|
|
|
instance and can be used as a publisher for other databases by defining its
|
|
|
|
own publications. When the subscriber is treated as read-only by
|
|
|
|
application, there will be no conflicts from a single subscription. On the
|
2017-01-25 18:42:11 +01:00
|
|
|
other hand, if there are other writes done either by an application or by other
|
|
|
|
subscribers to the same set of tables, conflicts can arise.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-publication">
|
|
|
|
<title>Publication</title>
|
|
|
|
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
A <firstterm>publication</firstterm> can be defined on any physical
|
2020-06-15 19:12:58 +02:00
|
|
|
replication primary. The node where a publication is defined is referred to
|
2017-01-19 18:00:00 +01:00
|
|
|
as <firstterm>publisher</firstterm>. A publication is a set of changes
|
2017-01-25 18:42:11 +01:00
|
|
|
generated from a table or a group of tables, and might also be described as
|
|
|
|
a change set or replication set. Each publication exists in only one database.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Publications are different from schemas and do not affect how the table is
|
|
|
|
accessed. Each table can be added to multiple publications if needed.
|
Allow publishing the tables of schema.
A new option "FOR ALL TABLES IN SCHEMA" in Create/Alter Publication allows
one or more schemas to be specified, whose tables are selected by the
publisher for sending the data to the subscriber.
The new syntax allows specifying both the tables and schemas. For example:
CREATE PUBLICATION pub1 FOR TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
OR
ALTER PUBLICATION pub1 ADD TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
A new system table "pg_publication_namespace" has been added, to maintain
the schemas that the user wants to publish through the publication.
Modified the output plugin (pgoutput) to publish the changes if the
relation is part of schema publication.
Updates pg_dump to identify and dump schema publications. Updates the \d
family of commands to display schema publications and \dRp+ variant will
now display associated schemas if any.
Author: Vignesh C, Hou Zhijie, Amit Kapila
Syntax-Suggested-by: Tom Lane, Alvaro Herrera
Reviewed-by: Greg Nancarrow, Masahiko Sawada, Hou Zhijie, Amit Kapila, Haiying Tang, Ajin Cherian, Rahila Syed, Bharath Rupireddy, Mark Dilger
Tested-by: Haiying Tang
Discussion: https://www.postgresql.org/message-id/CALDaNm0OANxuJ6RXqwZsM1MSY4s19nuH3734j4a72etDwvBETQ@mail.gmail.com
2021-10-27 04:14:52 +02:00
|
|
|
Publications may currently only contain tables and all tables in schema.
|
|
|
|
Objects must be added explicitly, except when a publication is created for
|
|
|
|
<literal>ALL TABLES</literal>.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
Publications can choose to limit the changes they produce to
|
2018-04-07 17:24:53 +02:00
|
|
|
any combination of <command>INSERT</command>, <command>UPDATE</command>,
|
|
|
|
<command>DELETE</command>, and <command>TRUNCATE</command>, similar to how triggers are fired by
|
2017-06-23 21:12:36 +02:00
|
|
|
particular event types. By default, all operation types are replicated.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A published table must have a <quote>replica identity</quote> configured in
|
|
|
|
order to be able to replicate <command>UPDATE</command>
|
|
|
|
and <command>DELETE</command> operations, so that appropriate rows to
|
|
|
|
update or delete can be identified on the subscriber side. By default,
|
|
|
|
this is the primary key, if there is one. Another unique index (with
|
|
|
|
certain additional requirements) can also be set to be the replica
|
|
|
|
identity. If the table does not have any suitable key, then it can be set
|
|
|
|
to replica identity <quote>full</quote>, which means the entire row becomes
|
|
|
|
the key. This, however, is very inefficient and should only be used as a
|
|
|
|
fallback if no other solution is possible. If a replica identity other
|
|
|
|
than <quote>full</quote> is set on the publisher side, a replica identity
|
|
|
|
comprising the same or fewer columns must also be set on the subscriber
|
2020-09-03 12:38:32 +02:00
|
|
|
side. See <xref linkend="sql-altertable-replica-identity"/> for details on
|
2017-06-23 21:12:36 +02:00
|
|
|
how to set the replica identity. If a table without a replica identity is
|
|
|
|
added to a publication that replicates <command>UPDATE</command>
|
|
|
|
or <command>DELETE</command> operations then
|
|
|
|
subsequent <command>UPDATE</command> or <command>DELETE</command>
|
|
|
|
operations will cause an error on the publisher. <command>INSERT</command>
|
|
|
|
operations can proceed regardless of any replica identity.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Every publication can have multiple subscribers.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
A publication is created using the <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>
|
2017-01-25 18:42:11 +01:00
|
|
|
command and may later be altered or dropped using corresponding commands.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The individual tables can be added and removed dynamically using
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
<link linkend="sql-alterpublication"><command>ALTER PUBLICATION</command></link>. Both the <literal>ADD
|
2017-01-19 18:00:00 +01:00
|
|
|
TABLE</literal> and <literal>DROP TABLE</literal> operations are
|
|
|
|
transactional; so the table will start or stop replicating at the correct
|
|
|
|
snapshot once the transaction has committed.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-subscription">
|
|
|
|
<title>Subscription</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A <firstterm>subscription</firstterm> is the downstream side of logical
|
|
|
|
replication. The node where a subscription is defined is referred to as
|
2017-01-25 18:42:11 +01:00
|
|
|
the <firstterm>subscriber</firstterm>. A subscription defines the connection
|
2017-01-19 18:00:00 +01:00
|
|
|
to another database and set of publications (one or more) to which it wants
|
2017-01-25 18:42:11 +01:00
|
|
|
to subscribe.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The subscriber database behaves in the same way as any other PostgreSQL
|
|
|
|
instance and can be used as a publisher for other databases by defining its
|
|
|
|
own publications.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A subscriber node may have multiple subscriptions if desired. It is
|
|
|
|
possible to define multiple subscriptions between a single
|
2017-01-25 18:42:11 +01:00
|
|
|
publisher-subscriber pair, in which case care must be taken to ensure
|
2017-01-19 18:00:00 +01:00
|
|
|
that the subscribed publication objects don't overlap.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Each subscription will receive changes via one replication slot (see
|
Allow multiple xacts during table sync in logical replication.
For the initial table data synchronization in logical replication, we use
a single transaction to copy the entire table and then synchronize the
position in the stream with the main apply worker.
There are multiple downsides of this approach: (a) We have to perform the
entire copy operation again if there is any error (network breakdown,
error in the database operation, etc.) while we synchronize the WAL
position between tablesync worker and apply worker; this will be onerous
especially for large copies, (b) Using a single transaction in the
synchronization-phase (where we can receive WAL from multiple
transactions) will have the risk of exceeding the CID limit, (c) The slot
will hold the WAL till the entire sync is complete because we never commit
till the end.
This patch solves all the above downsides by allowing multiple
transactions during the tablesync phase. The initial copy is done in a
single transaction and after that, we commit each transaction as we
receive. To allow recovery after any error or crash, we use a permanent
slot and origin to track the progress. The slot and origin will be removed
once we finish the synchronization of the table. We also remove slot and
origin of tablesync workers if the user performs DROP SUBSCRIPTION .. or
ALTER SUBSCRIPTION .. REFERESH and some of the table syncs are still not
finished.
The commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
ALTER SUBSCRIPTION ... SET PUBLICATION ... with refresh option as true
cannot be executed inside a transaction block because they can now drop
the slots for which we have no provision to rollback.
This will also open up the path for logical replication of 2PC
transactions on the subscriber side. Previously, we can't do that because
of the requirement of maintaining a single transaction in tablesync
workers.
Bump catalog version due to change of state in the catalog
(pg_subscription_rel).
Author: Peter Smith, Amit Kapila, and Takamichi Osumi
Reviewed-by: Ajin Cherian, Petr Jelinek, Hou Zhijie and Amit Kapila
Discussion: https://postgr.es/m/CAA4eK1KHJxaZS-fod-0fey=0tq3=Gkn4ho=8N4-5HWiCfu0H1A@mail.gmail.com
2021-02-12 03:11:51 +01:00
|
|
|
<xref linkend="streaming-replication-slots"/>). Additional replication
|
|
|
|
slots may be required for the initial data synchronization of
|
|
|
|
pre-existing table data and those will be dropped at the end of data
|
|
|
|
synchronization.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
2017-07-02 06:10:57 +02:00
|
|
|
<para>
|
|
|
|
A logical replication subscription can be a standby for synchronous
|
2017-11-23 15:39:47 +01:00
|
|
|
replication (see <xref linkend="synchronous-replication"/>). The standby
|
2017-07-02 06:10:57 +02:00
|
|
|
name is by default the subscription name. An alternative name can be
|
|
|
|
specified as <literal>application_name</literal> in the connection
|
|
|
|
information of the subscription.
|
|
|
|
</para>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<para>
|
2017-04-12 04:02:59 +02:00
|
|
|
Subscriptions are dumped by <command>pg_dump</command> if the current user
|
|
|
|
is a superuser. Otherwise a warning is written and subscriptions are
|
|
|
|
skipped, because non-superusers cannot read all subscription information
|
|
|
|
from the <structname>pg_subscription</structname> catalog.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
The subscription is added using <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link> and
|
2017-01-19 18:00:00 +01:00
|
|
|
can be stopped/resumed at any time using the
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
<link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION</command></link> command and removed using
|
|
|
|
<link linkend="sql-dropsubscription"><command>DROP SUBSCRIPTION</command></link>.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When a subscription is dropped and recreated, the synchronization
|
|
|
|
information is lost. This means that the data has to be resynchronized
|
|
|
|
afterwards.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
The schema definitions are not replicated, and the published tables must
|
|
|
|
exist on the subscriber. Only regular tables may be
|
2017-01-19 18:00:00 +01:00
|
|
|
the target of replication. For example, you can't replicate to a view.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The tables are matched between the publisher and the subscriber using the
|
|
|
|
fully qualified table name. Replication to differently-named tables on the
|
|
|
|
subscriber is not supported.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2019-07-08 14:28:42 +02:00
|
|
|
Columns of a table are also matched by name. The order of columns in the
|
|
|
|
subscriber table does not need to match that of the publisher. The data
|
|
|
|
types of the columns do not need to match, as long as the text
|
|
|
|
representation of the data can be converted to the target type. For
|
|
|
|
example, you can replicate from a column of type <type>integer</type> to a
|
|
|
|
column of type <type>bigint</type>. The target table can also have
|
|
|
|
additional columns not provided by the published table. Any such columns
|
|
|
|
will be filled with the default value as specified in the definition of the
|
|
|
|
target table.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
2017-05-09 16:25:26 +02:00
|
|
|
|
|
|
|
<sect2 id="logical-replication-subscription-slot">
|
|
|
|
<title>Replication Slot Management</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As mentioned earlier, each (active) subscription receives changes from a
|
Allow multiple xacts during table sync in logical replication.
For the initial table data synchronization in logical replication, we use
a single transaction to copy the entire table and then synchronize the
position in the stream with the main apply worker.
There are multiple downsides of this approach: (a) We have to perform the
entire copy operation again if there is any error (network breakdown,
error in the database operation, etc.) while we synchronize the WAL
position between tablesync worker and apply worker; this will be onerous
especially for large copies, (b) Using a single transaction in the
synchronization-phase (where we can receive WAL from multiple
transactions) will have the risk of exceeding the CID limit, (c) The slot
will hold the WAL till the entire sync is complete because we never commit
till the end.
This patch solves all the above downsides by allowing multiple
transactions during the tablesync phase. The initial copy is done in a
single transaction and after that, we commit each transaction as we
receive. To allow recovery after any error or crash, we use a permanent
slot and origin to track the progress. The slot and origin will be removed
once we finish the synchronization of the table. We also remove slot and
origin of tablesync workers if the user performs DROP SUBSCRIPTION .. or
ALTER SUBSCRIPTION .. REFERESH and some of the table syncs are still not
finished.
The commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
ALTER SUBSCRIPTION ... SET PUBLICATION ... with refresh option as true
cannot be executed inside a transaction block because they can now drop
the slots for which we have no provision to rollback.
This will also open up the path for logical replication of 2PC
transactions on the subscriber side. Previously, we can't do that because
of the requirement of maintaining a single transaction in tablesync
workers.
Bump catalog version due to change of state in the catalog
(pg_subscription_rel).
Author: Peter Smith, Amit Kapila, and Takamichi Osumi
Reviewed-by: Ajin Cherian, Petr Jelinek, Hou Zhijie and Amit Kapila
Discussion: https://postgr.es/m/CAA4eK1KHJxaZS-fod-0fey=0tq3=Gkn4ho=8N4-5HWiCfu0H1A@mail.gmail.com
2021-02-12 03:11:51 +01:00
|
|
|
replication slot on the remote (publishing) side.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Additional table synchronization slots are normally transient, created
|
|
|
|
internally to perform initial table synchronization and dropped
|
|
|
|
automatically when they are no longer needed. These table synchronization
|
|
|
|
slots have generated names: <quote><literal>pg_%u_sync_%u_%llu</literal></quote>
|
|
|
|
(parameters: Subscription <parameter>oid</parameter>,
|
|
|
|
Table <parameter>relid</parameter>, system identifier <parameter>sysid</parameter>)
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Normally, the remote replication slot is created automatically when the
|
|
|
|
subscription is created using <command>CREATE SUBSCRIPTION</command> and it
|
|
|
|
is dropped automatically when the subscription is dropped using
|
|
|
|
<command>DROP SUBSCRIPTION</command>. In some situations, however, it can
|
|
|
|
be useful or necessary to manipulate the subscription and the underlying
|
|
|
|
replication slot separately. Here are some scenarios:
|
2017-05-09 16:25:26 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When creating a subscription, the replication slot already exists. In
|
2017-05-12 14:57:01 +02:00
|
|
|
that case, the subscription can be created using
|
|
|
|
the <literal>create_slot = false</literal> option to associate with the
|
|
|
|
existing slot.
|
2017-05-09 16:25:26 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When creating a subscription, the remote host is not reachable or in an
|
|
|
|
unclear state. In that case, the subscription can be created using
|
2017-05-12 14:57:01 +02:00
|
|
|
the <literal>connect = false</literal> option. The remote host will then not
|
2017-05-09 16:25:26 +02:00
|
|
|
be contacted at all. This is what <application>pg_dump</application>
|
|
|
|
uses. The remote replication slot will then have to be created
|
|
|
|
manually before the subscription can be activated.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When dropping a subscription, the replication slot should be kept.
|
|
|
|
This could be useful when the subscriber database is being moved to a
|
|
|
|
different host and will be activated from there. In that case,
|
|
|
|
disassociate the slot from the subscription using <command>ALTER
|
|
|
|
SUBSCRIPTION</command> before attempting to drop the subscription.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When dropping a subscription, the remote host is not reachable. In
|
|
|
|
that case, disassociate the slot from the subscription
|
|
|
|
using <command>ALTER SUBSCRIPTION</command> before attempting to drop
|
|
|
|
the subscription. If the remote database instance no longer exists, no
|
|
|
|
further action is then necessary. If, however, the remote database
|
2021-04-22 22:47:57 +02:00
|
|
|
instance is just unreachable, the replication slot (and any still
|
Allow multiple xacts during table sync in logical replication.
For the initial table data synchronization in logical replication, we use
a single transaction to copy the entire table and then synchronize the
position in the stream with the main apply worker.
There are multiple downsides of this approach: (a) We have to perform the
entire copy operation again if there is any error (network breakdown,
error in the database operation, etc.) while we synchronize the WAL
position between tablesync worker and apply worker; this will be onerous
especially for large copies, (b) Using a single transaction in the
synchronization-phase (where we can receive WAL from multiple
transactions) will have the risk of exceeding the CID limit, (c) The slot
will hold the WAL till the entire sync is complete because we never commit
till the end.
This patch solves all the above downsides by allowing multiple
transactions during the tablesync phase. The initial copy is done in a
single transaction and after that, we commit each transaction as we
receive. To allow recovery after any error or crash, we use a permanent
slot and origin to track the progress. The slot and origin will be removed
once we finish the synchronization of the table. We also remove slot and
origin of tablesync workers if the user performs DROP SUBSCRIPTION .. or
ALTER SUBSCRIPTION .. REFERESH and some of the table syncs are still not
finished.
The commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
ALTER SUBSCRIPTION ... SET PUBLICATION ... with refresh option as true
cannot be executed inside a transaction block because they can now drop
the slots for which we have no provision to rollback.
This will also open up the path for logical replication of 2PC
transactions on the subscriber side. Previously, we can't do that because
of the requirement of maintaining a single transaction in tablesync
workers.
Bump catalog version due to change of state in the catalog
(pg_subscription_rel).
Author: Peter Smith, Amit Kapila, and Takamichi Osumi
Reviewed-by: Ajin Cherian, Petr Jelinek, Hou Zhijie and Amit Kapila
Discussion: https://postgr.es/m/CAA4eK1KHJxaZS-fod-0fey=0tq3=Gkn4ho=8N4-5HWiCfu0H1A@mail.gmail.com
2021-02-12 03:11:51 +01:00
|
|
|
remaining table synchronization slots) should then be
|
|
|
|
dropped manually; otherwise it/they would continue to reserve WAL and might
|
2017-05-09 16:25:26 +02:00
|
|
|
eventually cause the disk to fill up. Such cases should be carefully
|
|
|
|
investigated.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
2017-01-19 18:00:00 +01:00
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-conflicts">
|
|
|
|
<title>Conflicts</title>
|
|
|
|
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
Logical replication behaves similarly to normal DML operations in that
|
2017-01-19 18:00:00 +01:00
|
|
|
the data will be updated even if it was changed locally on the subscriber
|
2017-01-25 18:42:11 +01:00
|
|
|
node. If incoming data violates any constraints the replication will
|
2017-01-19 18:00:00 +01:00
|
|
|
stop. This is referred to as a <firstterm>conflict</firstterm>. When
|
|
|
|
replicating <command>UPDATE</command> or <command>DELETE</command>
|
|
|
|
operations, missing data will not produce a conflict and such operations
|
|
|
|
will simply be skipped.
|
|
|
|
</para>
|
|
|
|
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
<para>
|
|
|
|
Logical replication operations are performed with the privileges of the role
|
|
|
|
which owns the subscription. Permissions failures on target tables will
|
|
|
|
cause replication conflicts, as will enabled
|
|
|
|
<link linkend="ddl-rowsecurity">row-level security</link> on target tables
|
|
|
|
that the subscription owner is subject to, without regard to whether any
|
2022-01-08 22:40:23 +01:00
|
|
|
policy would ordinarily reject the <command>INSERT</command>,
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
<command>UPDATE</command>, <command>DELETE</command> or
|
|
|
|
<command>TRUNCATE</command> which is being replicated. This restriction on
|
|
|
|
row-level security may be lifted in a future version of
|
|
|
|
<productname>PostgreSQL</productname>.
|
|
|
|
</para>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<para>
|
|
|
|
A conflict will produce an error and will stop the replication; it must be
|
|
|
|
resolved manually by the user. Details about the conflict can be found in
|
2022-03-01 01:47:52 +01:00
|
|
|
the subscriber's server log.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
The resolution can be done either by changing data or permissions on the subscriber so
|
2017-01-19 18:00:00 +01:00
|
|
|
that it does not conflict with the incoming change or by skipping the
|
|
|
|
transaction that conflicts with the existing data. The transaction can be
|
|
|
|
skipped by calling the <link linkend="pg-replication-origin-advance">
|
|
|
|
<function>pg_replication_origin_advance()</function></link> function with
|
2017-01-25 18:42:11 +01:00
|
|
|
a <parameter>node_name</parameter> corresponding to the subscription name,
|
|
|
|
and a position. The current position of origins can be seen in the
|
2017-01-19 18:00:00 +01:00
|
|
|
<link linkend="view-pg-replication-origin-status">
|
|
|
|
<structname>pg_replication_origin_status</structname></link> system view.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2017-06-16 15:55:55 +02:00
|
|
|
<sect1 id="logical-replication-restrictions">
|
|
|
|
<title>Restrictions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication currently has the following restrictions or missing
|
|
|
|
functionality. These might be addressed in future releases.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The database schema and DDL commands are not replicated. The initial
|
|
|
|
schema can be copied by hand using <literal>pg_dump
|
|
|
|
--schema-only</literal>. Subsequent schema changes would need to be kept
|
|
|
|
in sync manually. (Note, however, that there is no need for the schemas
|
|
|
|
to be absolutely the same on both sides.) Logical replication is robust
|
|
|
|
when schema definitions change in a live database: When the schema is
|
|
|
|
changed on the publisher and replicated data starts arriving at the
|
|
|
|
subscriber but does not fit into the table schema, replication will error
|
|
|
|
until the schema is updated. In many cases, intermittent errors can be
|
|
|
|
avoided by applying additive schema changes to the subscriber first.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sequence data is not replicated. The data in serial or identity columns
|
|
|
|
backed by sequences will of course be replicated as part of the table,
|
|
|
|
but the sequence itself would still show the start value on the
|
|
|
|
subscriber. If the subscriber is used as a read-only database, then this
|
|
|
|
should typically not be a problem. If, however, some kind of switchover
|
|
|
|
or failover to the subscriber database is intended, then the sequences
|
|
|
|
would need to be updated to the latest values, either by copying the
|
|
|
|
current data from the publisher (perhaps
|
|
|
|
using <command>pg_dump</command>) or by determining a sufficiently high
|
|
|
|
value from the tables themselves.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
2018-06-27 07:40:18 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Replication of <command>TRUNCATE</command> commands is supported, but
|
|
|
|
some care must be taken when truncating groups of tables connected by
|
|
|
|
foreign keys. When replicating a truncate action, the subscriber will
|
|
|
|
truncate the same group of tables that was truncated on the publisher,
|
2018-11-02 13:55:57 +01:00
|
|
|
either explicitly specified or implicitly collected via
|
2018-06-27 07:40:18 +02:00
|
|
|
<literal>CASCADE</literal>, minus tables that are not part of the
|
|
|
|
subscription. This will work correctly if all affected tables are part
|
|
|
|
of the same subscription. But if some tables to be truncated on the
|
|
|
|
subscriber have foreign-key links to tables that are not part of the same
|
|
|
|
(or any) subscription, then the application of the truncate action on the
|
|
|
|
subscriber will fail.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
2017-06-16 15:55:55 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-11-23 15:39:47 +01:00
|
|
|
Large objects (see <xref linkend="largeobjects"/>) are not replicated.
|
2017-06-16 15:55:55 +02:00
|
|
|
There is no workaround for that, other than storing data in normal
|
|
|
|
tables.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2020-04-06 15:15:52 +02:00
|
|
|
Replication is only supported by tables, including partitioned tables.
|
2020-09-21 18:43:42 +02:00
|
|
|
Attempts to replicate other types of relations, such as views, materialized
|
2020-04-06 15:15:52 +02:00
|
|
|
views, or foreign tables, will result in an error.
|
2020-03-10 08:42:59 +01:00
|
|
|
</para>
|
2020-04-06 15:15:52 +02:00
|
|
|
</listitem>
|
2020-03-10 08:42:59 +01:00
|
|
|
|
2020-04-06 15:15:52 +02:00
|
|
|
<listitem>
|
2020-03-10 08:42:59 +01:00
|
|
|
<para>
|
2020-04-06 15:15:52 +02:00
|
|
|
When replicating between partitioned tables, the actual replication
|
2020-04-08 09:59:27 +02:00
|
|
|
originates, by default, from the leaf partitions on the publisher, so
|
|
|
|
partitions on the publisher must also exist on the subscriber as valid
|
|
|
|
target tables. (They could either be leaf partitions themselves, or they
|
|
|
|
could be further subpartitioned, or they could even be independent
|
|
|
|
tables.) Publications can also specify that changes are to be replicated
|
|
|
|
using the identity and schema of the partitioned root table instead of
|
|
|
|
that of the individual leaf partitions in which the changes actually
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
originate (see <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>).
|
2017-06-16 15:55:55 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<sect1 id="logical-replication-architecture">
|
|
|
|
<title>Architecture</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication starts by copying a snapshot of the data on the
|
|
|
|
publisher database. Once that is done, changes on the publisher are sent
|
|
|
|
to the subscriber as they occur in real time. The subscriber applies data
|
|
|
|
in the order in which commits were made on the publisher so that
|
|
|
|
transactional consistency is guaranteed for the publications within any
|
|
|
|
single subscription.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication is built with an architecture similar to physical
|
2017-11-23 15:39:47 +01:00
|
|
|
streaming replication (see <xref linkend="streaming-replication"/>). It is
|
2017-01-25 18:42:11 +01:00
|
|
|
implemented by <quote>walsender</quote> and <quote>apply</quote>
|
|
|
|
processes. The walsender process starts logical decoding (described
|
2017-11-23 15:39:47 +01:00
|
|
|
in <xref linkend="logicaldecoding"/>) of the WAL and loads the standard
|
2017-01-19 18:00:00 +01:00
|
|
|
logical decoding plugin (pgoutput). The plugin transforms the changes read
|
|
|
|
from WAL to the logical replication protocol
|
2017-11-23 15:39:47 +01:00
|
|
|
(see <xref linkend="protocol-logical-replication"/>) and filters the data
|
2017-01-19 18:00:00 +01:00
|
|
|
according to the publication specification. The data is then continuously
|
|
|
|
transferred using the streaming replication protocol to the apply worker,
|
|
|
|
which maps the data to local tables and applies the individual changes as
|
2017-01-25 18:42:11 +01:00
|
|
|
they are received, in correct transactional order.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The apply process on the subscriber database always runs with
|
|
|
|
<varname>session_replication_role</varname> set
|
|
|
|
to <literal>replica</literal>, which produces the usual effects on triggers
|
|
|
|
and constraints.
|
|
|
|
</para>
|
2017-03-23 13:36:36 +01:00
|
|
|
|
2017-07-04 05:37:53 +02:00
|
|
|
<para>
|
|
|
|
The logical replication apply process currently only fires row triggers,
|
|
|
|
not statement triggers. The initial table synchronization, however, is
|
|
|
|
implemented like a <command>COPY</command> command and thus fires both row
|
|
|
|
and statement triggers for <command>INSERT</command>.
|
|
|
|
</para>
|
|
|
|
|
2017-03-23 13:36:36 +01:00
|
|
|
<sect2 id="logical-replication-snapshot">
|
|
|
|
<title>Initial Snapshot</title>
|
|
|
|
<para>
|
Allow multiple xacts during table sync in logical replication.
For the initial table data synchronization in logical replication, we use
a single transaction to copy the entire table and then synchronize the
position in the stream with the main apply worker.
There are multiple downsides of this approach: (a) We have to perform the
entire copy operation again if there is any error (network breakdown,
error in the database operation, etc.) while we synchronize the WAL
position between tablesync worker and apply worker; this will be onerous
especially for large copies, (b) Using a single transaction in the
synchronization-phase (where we can receive WAL from multiple
transactions) will have the risk of exceeding the CID limit, (c) The slot
will hold the WAL till the entire sync is complete because we never commit
till the end.
This patch solves all the above downsides by allowing multiple
transactions during the tablesync phase. The initial copy is done in a
single transaction and after that, we commit each transaction as we
receive. To allow recovery after any error or crash, we use a permanent
slot and origin to track the progress. The slot and origin will be removed
once we finish the synchronization of the table. We also remove slot and
origin of tablesync workers if the user performs DROP SUBSCRIPTION .. or
ALTER SUBSCRIPTION .. REFERESH and some of the table syncs are still not
finished.
The commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
ALTER SUBSCRIPTION ... SET PUBLICATION ... with refresh option as true
cannot be executed inside a transaction block because they can now drop
the slots for which we have no provision to rollback.
This will also open up the path for logical replication of 2PC
transactions on the subscriber side. Previously, we can't do that because
of the requirement of maintaining a single transaction in tablesync
workers.
Bump catalog version due to change of state in the catalog
(pg_subscription_rel).
Author: Peter Smith, Amit Kapila, and Takamichi Osumi
Reviewed-by: Ajin Cherian, Petr Jelinek, Hou Zhijie and Amit Kapila
Discussion: https://postgr.es/m/CAA4eK1KHJxaZS-fod-0fey=0tq3=Gkn4ho=8N4-5HWiCfu0H1A@mail.gmail.com
2021-02-12 03:11:51 +01:00
|
|
|
The initial data in existing subscribed tables are snapshotted and
|
|
|
|
copied in a parallel instance of a special kind of apply process.
|
|
|
|
This process will create its own replication slot and copy the existing
|
|
|
|
data. As soon as the copy is finished the table contents will become
|
|
|
|
visible to other backends. Once existing data is copied, the worker
|
|
|
|
enters synchronization mode, which ensures that the table is brought
|
|
|
|
up to a synchronized state with the main apply process by streaming
|
|
|
|
any changes that happened during the initial data copy using standard
|
|
|
|
logical replication. During this synchronization phase, the changes
|
|
|
|
are applied and committed in the same order as they happened on the
|
2021-04-09 06:53:07 +02:00
|
|
|
publisher. Once synchronization is done, control of the
|
Allow multiple xacts during table sync in logical replication.
For the initial table data synchronization in logical replication, we use
a single transaction to copy the entire table and then synchronize the
position in the stream with the main apply worker.
There are multiple downsides of this approach: (a) We have to perform the
entire copy operation again if there is any error (network breakdown,
error in the database operation, etc.) while we synchronize the WAL
position between tablesync worker and apply worker; this will be onerous
especially for large copies, (b) Using a single transaction in the
synchronization-phase (where we can receive WAL from multiple
transactions) will have the risk of exceeding the CID limit, (c) The slot
will hold the WAL till the entire sync is complete because we never commit
till the end.
This patch solves all the above downsides by allowing multiple
transactions during the tablesync phase. The initial copy is done in a
single transaction and after that, we commit each transaction as we
receive. To allow recovery after any error or crash, we use a permanent
slot and origin to track the progress. The slot and origin will be removed
once we finish the synchronization of the table. We also remove slot and
origin of tablesync workers if the user performs DROP SUBSCRIPTION .. or
ALTER SUBSCRIPTION .. REFERESH and some of the table syncs are still not
finished.
The commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
ALTER SUBSCRIPTION ... SET PUBLICATION ... with refresh option as true
cannot be executed inside a transaction block because they can now drop
the slots for which we have no provision to rollback.
This will also open up the path for logical replication of 2PC
transactions on the subscriber side. Previously, we can't do that because
of the requirement of maintaining a single transaction in tablesync
workers.
Bump catalog version due to change of state in the catalog
(pg_subscription_rel).
Author: Peter Smith, Amit Kapila, and Takamichi Osumi
Reviewed-by: Ajin Cherian, Petr Jelinek, Hou Zhijie and Amit Kapila
Discussion: https://postgr.es/m/CAA4eK1KHJxaZS-fod-0fey=0tq3=Gkn4ho=8N4-5HWiCfu0H1A@mail.gmail.com
2021-02-12 03:11:51 +01:00
|
|
|
replication of the table is given back to the main apply process where
|
2021-04-09 06:53:07 +02:00
|
|
|
replication continues as normal.
|
2017-03-23 13:36:36 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
2017-01-19 18:00:00 +01:00
|
|
|
</sect1>
|
|
|
|
|
2017-03-23 13:36:36 +01:00
|
|
|
<sect1 id="logical-replication-monitoring">
|
2017-01-19 18:00:00 +01:00
|
|
|
<title>Monitoring</title>
|
|
|
|
|
|
|
|
<para>
|
2017-01-25 18:42:11 +01:00
|
|
|
Because logical replication is based on a similar architecture as
|
|
|
|
<link linkend="streaming-replication">physical streaming replication</link>,
|
|
|
|
the monitoring on a publication node is similar to monitoring of a
|
2020-06-15 19:12:58 +02:00
|
|
|
physical replication primary
|
2017-11-23 15:39:47 +01:00
|
|
|
(see <xref linkend="streaming-replication-monitoring"/>).
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The monitoring information about subscription is visible in
|
2020-05-29 10:14:33 +02:00
|
|
|
<link linkend="monitoring-pg-stat-subscription">
|
|
|
|
<structname>pg_stat_subscription</structname></link>.
|
2017-01-19 18:00:00 +01:00
|
|
|
This view contains one row for every subscription worker. A subscription
|
|
|
|
can have zero or more active subscription workers depending on its state.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Normally, there is a single apply process running for an enabled
|
|
|
|
subscription. A disabled subscription or a crashed subscription will have
|
2017-03-23 13:36:36 +01:00
|
|
|
zero rows in this view. If the initial data synchronization of any
|
|
|
|
table is in progress, there will be additional workers for the tables
|
|
|
|
being synchronized.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-security">
|
|
|
|
<title>Security</title>
|
|
|
|
|
2020-08-10 18:22:54 +02:00
|
|
|
<para>
|
|
|
|
A user able to modify the schema of subscriber-side tables can execute
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
arbitrary code as the role which owns any subscription which modifies those tables. Limit ownership
|
|
|
|
and <literal>TRIGGER</literal> privilege on such tables to trusted roles.
|
|
|
|
Moreover, if untrusted users can create tables, use only
|
2020-08-10 18:22:54 +02:00
|
|
|
publications that list tables explicitly. That is to say, create a
|
Allow publishing the tables of schema.
A new option "FOR ALL TABLES IN SCHEMA" in Create/Alter Publication allows
one or more schemas to be specified, whose tables are selected by the
publisher for sending the data to the subscriber.
The new syntax allows specifying both the tables and schemas. For example:
CREATE PUBLICATION pub1 FOR TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
OR
ALTER PUBLICATION pub1 ADD TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
A new system table "pg_publication_namespace" has been added, to maintain
the schemas that the user wants to publish through the publication.
Modified the output plugin (pgoutput) to publish the changes if the
relation is part of schema publication.
Updates pg_dump to identify and dump schema publications. Updates the \d
family of commands to display schema publications and \dRp+ variant will
now display associated schemas if any.
Author: Vignesh C, Hou Zhijie, Amit Kapila
Syntax-Suggested-by: Tom Lane, Alvaro Herrera
Reviewed-by: Greg Nancarrow, Masahiko Sawada, Hou Zhijie, Amit Kapila, Haiying Tang, Ajin Cherian, Rahila Syed, Bharath Rupireddy, Mark Dilger
Tested-by: Haiying Tang
Discussion: https://www.postgresql.org/message-id/CALDaNm0OANxuJ6RXqwZsM1MSY4s19nuH3734j4a72etDwvBETQ@mail.gmail.com
2021-10-27 04:14:52 +02:00
|
|
|
subscription <literal>FOR ALL TABLES</literal> or
|
|
|
|
<literal>FOR ALL TABLES IN SCHEMA</literal> only when superusers trust
|
2020-08-10 18:22:54 +02:00
|
|
|
every user permitted to create a non-temp table on the publisher or the
|
|
|
|
subscriber.
|
|
|
|
</para>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<para>
|
2017-02-13 22:50:29 +01:00
|
|
|
The role used for the replication connection must have
|
2020-08-10 18:22:54 +02:00
|
|
|
the <literal>REPLICATION</literal> attribute (or be a superuser). If the
|
|
|
|
role lacks <literal>SUPERUSER</literal> and <literal>BYPASSRLS</literal>,
|
|
|
|
publisher row security policies can execute. If the role does not trust
|
|
|
|
all table owners, include <literal>options=-crow_security=off</literal> in
|
|
|
|
the connection string; if a table owner then adds a row security policy,
|
|
|
|
that setting will cause replication to halt rather than execute the policy.
|
|
|
|
Access for the role must be configured in <filename>pg_hba.conf</filename>
|
|
|
|
and it must have the <literal>LOGIN</literal> attribute.
|
2018-04-11 15:01:57 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In order to be able to copy the initial table data, the role used for the
|
|
|
|
replication connection must have the <literal>SELECT</literal> privilege on
|
|
|
|
a published table (or be a superuser).
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To create a publication, the user must have the <literal>CREATE</literal>
|
|
|
|
privilege in the database.
|
|
|
|
</para>
|
|
|
|
|
2017-03-15 18:52:07 +01:00
|
|
|
<para>
|
|
|
|
To add tables to a publication, the user must have ownership rights on the
|
Allow publishing the tables of schema.
A new option "FOR ALL TABLES IN SCHEMA" in Create/Alter Publication allows
one or more schemas to be specified, whose tables are selected by the
publisher for sending the data to the subscriber.
The new syntax allows specifying both the tables and schemas. For example:
CREATE PUBLICATION pub1 FOR TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
OR
ALTER PUBLICATION pub1 ADD TABLE t1,t2,t3, ALL TABLES IN SCHEMA s1,s2;
A new system table "pg_publication_namespace" has been added, to maintain
the schemas that the user wants to publish through the publication.
Modified the output plugin (pgoutput) to publish the changes if the
relation is part of schema publication.
Updates pg_dump to identify and dump schema publications. Updates the \d
family of commands to display schema publications and \dRp+ variant will
now display associated schemas if any.
Author: Vignesh C, Hou Zhijie, Amit Kapila
Syntax-Suggested-by: Tom Lane, Alvaro Herrera
Reviewed-by: Greg Nancarrow, Masahiko Sawada, Hou Zhijie, Amit Kapila, Haiying Tang, Ajin Cherian, Rahila Syed, Bharath Rupireddy, Mark Dilger
Tested-by: Haiying Tang
Discussion: https://www.postgresql.org/message-id/CALDaNm0OANxuJ6RXqwZsM1MSY4s19nuH3734j4a72etDwvBETQ@mail.gmail.com
2021-10-27 04:14:52 +02:00
|
|
|
table. To add all tables in schema to a publication, the user must be a
|
|
|
|
superuser. To create a publication that publishes all tables or all tables in
|
|
|
|
schema automatically, the user must be a superuser.
|
2017-03-15 18:52:07 +01:00
|
|
|
</para>
|
|
|
|
|
2017-01-19 18:00:00 +01:00
|
|
|
<para>
|
|
|
|
To create a subscription, the user must be a superuser.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The subscription apply process will run in the local database with the
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
privileges of the subscription owner.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
On the publisher, privileges are only checked once at the start of a
|
|
|
|
replication connection and are not re-checked as each change record is read.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Respect permissions within logical replication.
Prevent logical replication workers from performing insert, update,
delete, truncate, or copy commands on tables unless the subscription
owner has permission to do so.
Prevent subscription owners from circumventing row-level security by
forbidding replication into tables with row-level security policies
which the subscription owner is subject to, without regard to whether
the policy would ordinarily allow the INSERT, UPDATE, DELETE or
TRUNCATE which is being replicated. This seems sufficient for now, as
superusers, roles with bypassrls, and target table owners should still
be able to replicate despite RLS policies. We can revisit the
question of applying row-level security policies on a per-row basis if
this restriction proves too severe in practice.
Author: Mark Dilger
Reviewed-by: Jeff Davis, Andrew Dunstan, Ronan Dunklau
Discussion: https://postgr.es/m/9DFC88D3-1300-4DE8-ACBC-4CEF84399A53%40enterprisedb.com
2022-01-08 02:38:20 +01:00
|
|
|
On the subscriber, the subscription owner's privileges are re-checked for
|
|
|
|
each transaction when applied. If a worker is in the process of applying a
|
|
|
|
transaction when the ownership of the subscription is changed by a
|
|
|
|
concurrent transaction, the application of the current transaction will
|
|
|
|
continue under the old owner's privileges.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-config">
|
|
|
|
<title>Configuration Settings</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Logical replication requires several configuration options to be set.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
On the publisher side, <varname>wal_level</varname> must be set to
|
|
|
|
<literal>logical</literal>, and <varname>max_replication_slots</varname>
|
2017-03-23 13:36:36 +01:00
|
|
|
must be set to at least the number of subscriptions expected to connect,
|
|
|
|
plus some reserve for table synchronization. And
|
|
|
|
<varname>max_wal_senders</varname> should be set to at least the same as
|
|
|
|
<varname>max_replication_slots</varname> plus the number of physical
|
|
|
|
replicas that are connected at the same time.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2021-04-09 06:53:07 +02:00
|
|
|
<varname>max_replication_slots</varname> must also be set on the subscriber.
|
|
|
|
It should be set to at least the number of subscriptions that will be added
|
|
|
|
to the subscriber, plus some reserve for table synchronization.
|
2021-03-03 07:31:56 +01:00
|
|
|
<varname>max_logical_replication_workers</varname> must be set to at least
|
|
|
|
the number of subscriptions, again plus some reserve for the table
|
|
|
|
synchronization. Additionally the <varname>max_worker_processes</varname>
|
2017-03-23 13:36:36 +01:00
|
|
|
may need to be adjusted to accommodate for replication workers, at least
|
2017-01-19 18:00:00 +01:00
|
|
|
(<varname>max_logical_replication_workers</varname>
|
|
|
|
+ <literal>1</literal>). Note that some extensions and parallel queries
|
|
|
|
also take worker slots from <varname>max_worker_processes</varname>.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="logical-replication-quick-setup">
|
|
|
|
<title>Quick Setup</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
First set the configuration options in <filename>postgresql.conf</filename>:
|
|
|
|
<programlisting>
|
|
|
|
wal_level = logical
|
|
|
|
</programlisting>
|
|
|
|
The other required settings have default values that are sufficient for a
|
|
|
|
basic setup.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<filename>pg_hba.conf</filename> needs to be adjusted to allow replication
|
|
|
|
(the values here depend on your actual network configuration and user you
|
|
|
|
want to use for connecting):
|
|
|
|
<programlisting>
|
2017-03-22 20:26:04 +01:00
|
|
|
host all repuser 0.0.0.0/0 md5
|
2017-01-19 18:00:00 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Then on the publisher database:
|
|
|
|
<programlisting>
|
|
|
|
CREATE PUBLICATION mypub FOR TABLE users, departments;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
And on the subscriber database:
|
|
|
|
<programlisting>
|
|
|
|
CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar user=repuser' PUBLICATION mypub;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-03-23 13:36:36 +01:00
|
|
|
The above will start the replication process, which synchronizes the
|
|
|
|
initial table contents of the tables <literal>users</literal> and
|
|
|
|
<literal>departments</literal> and then starts replicating
|
|
|
|
incremental changes to those tables.
|
2017-01-19 18:00:00 +01:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|