begriffs open source - ai-pg/blob - full-docs/txt/logical-replication-subscription.txt

   1
   2 29.2. Subscription #
   3
   4    29.2.1. Replication Slot Management
   5    29.2.2. Examples: Set Up Logical Replication
   6    29.2.3. Examples: Deferred Replication Slot Creation
   7
   8    A subscription is the downstream side of logical replication. The node
   9    where a subscription is defined is referred to as the subscriber. A
  10    subscription defines the connection to another database and set of
  11    publications (one or more) to which it wants to subscribe.
  12
  13    The subscriber database behaves in the same way as any other PostgreSQL
  14    instance and can be used as a publisher for other databases by defining
  15    its own publications.
  16
  17    A subscriber node may have multiple subscriptions if desired. It is
  18    possible to define multiple subscriptions between a single
  19    publisher-subscriber pair, in which case care must be taken to ensure
  20    that the subscribed publication objects don't overlap.
  21
  22    Each subscription will receive changes via one replication slot (see
  23    Section 26.2.6). Additional replication slots may be required for the
  24    initial data synchronization of pre-existing table data and those will
  25    be dropped at the end of data synchronization.
  26
  27    A logical replication subscription can be a standby for synchronous
  28    replication (see Section 26.2.8). The standby name is by default the
  29    subscription name. An alternative name can be specified as
  30    application_name in the connection information of the subscription.
  31
  32    Subscriptions are dumped by pg_dump if the current user is a superuser.
  33    Otherwise a warning is written and subscriptions are skipped, because
  34    non-superusers cannot read all subscription information from the
  35    pg_subscription catalog.
  36
  37    The subscription is added using CREATE SUBSCRIPTION and can be
  38    stopped/resumed at any time using the ALTER SUBSCRIPTION command and
  39    removed using DROP SUBSCRIPTION.
  40
  41    When a subscription is dropped and recreated, the synchronization
  42    information is lost. This means that the data has to be resynchronized
  43    afterwards.
  44
  45    The schema definitions are not replicated, and the published tables
  46    must exist on the subscriber. Only regular tables may be the target of
  47    replication. For example, you can't replicate to a view.
  48
  49    The tables are matched between the publisher and the subscriber using
  50    the fully qualified table name. Replication to differently-named tables
  51    on the subscriber is not supported.
  52
  53    Columns of a table are also matched by name. The order of columns in
  54    the subscriber table does not need to match that of the publisher. The
  55    data types of the columns do not need to match, as long as the text
  56    representation of the data can be converted to the target type. For
  57    example, you can replicate from a column of type integer to a column of
  58    type bigint. The target table can also have additional columns not
  59    provided by the published table. Any such columns will be filled with
  60    the default value as specified in the definition of the target table.
  61    However, logical replication in binary format is more restrictive. See
  62    the binary option of CREATE SUBSCRIPTION for details.
  63
  64 29.2.1. Replication Slot Management #
  65
  66    As mentioned earlier, each (active) subscription receives changes from
  67    a replication slot on the remote (publishing) side.
  68
  69    Additional table synchronization slots are normally transient, created
  70    internally to perform initial table synchronization and dropped
  71    automatically when they are no longer needed. These table
  72    synchronization slots have generated names: “pg_%u_sync_%u_%llu”
  73    (parameters: Subscription oid, Table relid, system identifier sysid)
  74
  75    Normally, the remote replication slot is created automatically when the
  76    subscription is created using CREATE SUBSCRIPTION and it is dropped
  77    automatically when the subscription is dropped using DROP SUBSCRIPTION.
  78    In some situations, however, it can be useful or necessary to
  79    manipulate the subscription and the underlying replication slot
  80    separately. Here are some scenarios:
  81      * When creating a subscription, the replication slot already exists.
  82        In that case, the subscription can be created using the create_slot
  83        = false option to associate with the existing slot.
  84      * When creating a subscription, the remote host is not reachable or
  85        in an unclear state. In that case, the subscription can be created
  86        using the connect = false option. The remote host will then not be
  87        contacted at all. This is what pg_dump uses. The remote replication
  88        slot will then have to be created manually before the subscription
  89        can be activated.
  90      * When dropping a subscription, the replication slot should be kept.
  91        This could be useful when the subscriber database is being moved to
  92        a different host and will be activated from there. In that case,
  93        disassociate the slot from the subscription using ALTER
  94        SUBSCRIPTION before attempting to drop the subscription.
  95      * When dropping a subscription, the remote host is not reachable. In
  96        that case, disassociate the slot from the subscription using ALTER
  97        SUBSCRIPTION before attempting to drop the subscription. If the
  98        remote database instance no longer exists, no further action is
  99        then necessary. If, however, the remote database instance is just
 100        unreachable, the replication slot (and any still remaining table
 101        synchronization slots) should then be dropped manually; otherwise
 102        it/they would continue to reserve WAL and might eventually cause
 103        the disk to fill up. Such cases should be carefully investigated.
 104
 105 29.2.2. Examples: Set Up Logical Replication #
 106
 107    Create some test tables on the publisher.
 108 /* pub # */ CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
 109 /* pub # */ CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
 110 /* pub # */ CREATE TABLE t3(e int, f text, PRIMARY KEY(e));
 111
 112    Create the same tables on the subscriber.
 113 /* sub # */ CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
 114 /* sub # */ CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
 115 /* sub # */ CREATE TABLE t3(e int, f text, PRIMARY KEY(e));
 116
 117    Insert data to the tables at the publisher side.
 118 /* pub # */ INSERT INTO t1 VALUES (1, 'one'), (2, 'two'), (3, 'three');
 119 /* pub # */ INSERT INTO t2 VALUES (1, 'A'), (2, 'B'), (3, 'C');
 120 /* pub # */ INSERT INTO t3 VALUES (1, 'i'), (2, 'ii'), (3, 'iii');
 121
 122    Create publications for the tables. The publications pub2 and pub3a
 123    disallow some publish operations. The publication pub3b has a row
 124    filter (see Section 29.4).
 125 /* pub # */ CREATE PUBLICATION pub1 FOR TABLE t1;
 126 /* pub # */ CREATE PUBLICATION pub2 FOR TABLE t2 WITH (publish = 'truncate');
 127 /* pub # */ CREATE PUBLICATION pub3a FOR TABLE t3 WITH (publish = 'truncate');
 128 /* pub # */ CREATE PUBLICATION pub3b FOR TABLE t3 WHERE (e > 5);
 129
 130    Create subscriptions for the publications. The subscription sub3
 131    subscribes to both pub3a and pub3b. All subscriptions will copy initial
 132    data by default.
 133 /* sub # */ CREATE SUBSCRIPTION sub1
 134 /* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub1'
 135 /* sub - */ PUBLICATION pub1;
 136 /* sub # */ CREATE SUBSCRIPTION sub2
 137 /* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub2'
 138 /* sub - */ PUBLICATION pub2;
 139 /* sub # */ CREATE SUBSCRIPTION sub3
 140 /* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub3'
 141 /* sub - */ PUBLICATION pub3a, pub3b;
 142
 143    Observe that initial table data is copied, regardless of the publish
 144    operation of the publication.
 145 /* sub # */ SELECT * FROM t1;
 146  a |   b
 147 ---+-------
 148  1 | one
 149  2 | two
 150  3 | three
 151 (3 rows)
 152
 153 /* sub # */ SELECT * FROM t2;
 154  c | d
 155 ---+---
 156  1 | A
 157  2 | B
 158  3 | C
 159 (3 rows)
 160
 161    Furthermore, because the initial data copy ignores the publish
 162    operation, and because publication pub3a has no row filter, it means
 163    the copied table t3 contains all rows even when they do not match the
 164    row filter of publication pub3b.
 165 /* sub # */ SELECT * FROM t3;
 166  e |  f
 167 ---+-----
 168  1 | i
 169  2 | ii
 170  3 | iii
 171 (3 rows)
 172
 173    Insert more data to the tables at the publisher side.
 174 /* pub # */ INSERT INTO t1 VALUES (4, 'four'), (5, 'five'), (6, 'six');
 175 /* pub # */ INSERT INTO t2 VALUES (4, 'D'), (5, 'E'), (6, 'F');
 176 /* pub # */ INSERT INTO t3 VALUES (4, 'iv'), (5, 'v'), (6, 'vi');
 177
 178    Now the publisher side data looks like:
 179 /* pub # */ SELECT * FROM t1;
 180  a |   b
 181 ---+-------
 182  1 | one
 183  2 | two
 184  3 | three
 185  4 | four
 186  5 | five
 187  6 | six
 188 (6 rows)
 189
 190 /* pub # */ SELECT * FROM t2;
 191  c | d
 192 ---+---
 193  1 | A
 194  2 | B
 195  3 | C
 196  4 | D
 197  5 | E
 198  6 | F
 199 (6 rows)
 200
 201 /* pub # */ SELECT * FROM t3;
 202  e |  f
 203 ---+-----
 204  1 | i
 205  2 | ii
 206  3 | iii
 207  4 | iv
 208  5 | v
 209  6 | vi
 210 (6 rows)
 211
 212    Observe that during normal replication the appropriate publish
 213    operations are used. This means publications pub2 and pub3a will not
 214    replicate the INSERT. Also, publication pub3b will only replicate data
 215    that matches the row filter of pub3b. Now the subscriber side data
 216    looks like:
 217 /* sub # */ SELECT * FROM t1;
 218  a |   b
 219 ---+-------
 220  1 | one
 221  2 | two
 222  3 | three
 223  4 | four
 224  5 | five
 225  6 | six
 226 (6 rows)
 227
 228 /* sub # */ SELECT * FROM t2;
 229  c | d
 230 ---+---
 231  1 | A
 232  2 | B
 233  3 | C
 234 (3 rows)
 235
 236 /* sub # */ SELECT * FROM t3;
 237  e |  f
 238 ---+-----
 239  1 | i
 240  2 | ii
 241  3 | iii
 242  6 | vi
 243 (4 rows)
 244
 245 29.2.3. Examples: Deferred Replication Slot Creation #
 246
 247    There are some cases (e.g. Section 29.2.1) where, if the remote
 248    replication slot was not created automatically, the user must create it
 249    manually before the subscription can be activated. The steps to create
 250    the slot and activate the subscription are shown in the following
 251    examples. These examples specify the standard logical decoding output
 252    plugin (pgoutput), which is what the built-in logical replication uses.
 253
 254    First, create a publication for the examples to use.
 255 /* pub # */ CREATE PUBLICATION pub1 FOR ALL TABLES;
 256
 257    Example 1: Where the subscription says connect = false
 258
 259      * Create the subscription.
 260 /* sub # */ CREATE SUBSCRIPTION sub1
 261 /* sub - */ CONNECTION 'host=localhost dbname=test_pub'
 262 /* sub - */ PUBLICATION pub1
 263 /* sub - */ WITH (connect=false);
 264 WARNING:  subscription was created, but is not connected
 265 HINT:  To initiate replication, you must manually create the replication slot, e
 266 nable the subscription, and refresh the subscription.
 267
 268      * On the publisher, manually create a slot. Because the name was not
 269        specified during CREATE SUBSCRIPTION, the name of the slot to
 270        create is same as the subscription name, e.g. "sub1".
 271 /* pub # */ SELECT * FROM pg_create_logical_replication_slot('sub1', 'pgoutput')
 272 ;
 273  slot_name |    lsn
 274 -----------+-----------
 275  sub1      | 0/19404D0
 276 (1 row)
 277
 278      * On the subscriber, complete the activation of the subscription.
 279        After this the tables of pub1 will start replicating.
 280 /* sub # */ ALTER SUBSCRIPTION sub1 ENABLE;
 281 /* sub # */ ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;
 282
 283    Example 2: Where the subscription says connect = false, but also
 284    specifies the slot_name option.
 285      * Create the subscription.
 286 /* sub # */ CREATE SUBSCRIPTION sub1
 287 /* sub - */ CONNECTION 'host=localhost dbname=test_pub'
 288 /* sub - */ PUBLICATION pub1
 289 /* sub - */ WITH (connect=false, slot_name='myslot');
 290 WARNING:  subscription was created, but is not connected
 291 HINT:  To initiate replication, you must manually create the replication slot, e
 292 nable the subscription, and refresh the subscription.
 293
 294      * On the publisher, manually create a slot using the same name that
 295        was specified during CREATE SUBSCRIPTION, e.g. "myslot".
 296 /* pub # */ SELECT * FROM pg_create_logical_replication_slot('myslot', 'pgoutput
 297 ');
 298  slot_name |    lsn
 299 -----------+-----------
 300  myslot    | 0/19059A0
 301 (1 row)
 302
 303      * On the subscriber, the remaining subscription activation steps are
 304        the same as before.
 305 /* sub # */ ALTER SUBSCRIPTION sub1 ENABLE;
 306 /* sub # */ ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;
 307
 308    Example 3: Where the subscription specifies slot_name = NONE
 309      * Create the subscription. When slot_name = NONE then enabled =
 310        false, and create_slot = false are also needed.
 311 /* sub # */ CREATE SUBSCRIPTION sub1
 312 /* sub - */ CONNECTION 'host=localhost dbname=test_pub'
 313 /* sub - */ PUBLICATION pub1
 314 /* sub - */ WITH (slot_name=NONE, enabled=false, create_slot=false);
 315
 316      * On the publisher, manually create a slot using any name, e.g.
 317        "myslot".
 318 /* pub # */ SELECT * FROM pg_create_logical_replication_slot('myslot', 'pgoutput
 319 ');
 320  slot_name |    lsn
 321 -----------+-----------
 322  myslot    | 0/1905930
 323 (1 row)
 324
 325      * On the subscriber, associate the subscription with the slot name
 326        just created.
 327 /* sub # */ ALTER SUBSCRIPTION sub1 SET (slot_name='myslot');
 328
 329      * The remaining subscription activation steps are same as before.
 330 /* sub # */ ALTER SUBSCRIPTION sub1 ENABLE;
 331 /* sub # */ ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;