diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index e7526905f8c..e87e3dcd36d 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -204,6 +204,66 @@ target table can have additional columns not provided by the published table. Those will be filled with their default values. + + + Replication Slot Management + + + As mentioned earlier, each (active) subscription receives changes from a + replication slot on the remote (publishing) side. Normally, the remote + replication slot is created automatically when the subscription is created + using CREATE SUBSCRIPTION and it is dropped + automatically when the subscription is dropped using DROP + SUBSCRIPTION. In some situations, however, it can be useful or + necessary to manipulate the subscription and the underlying replication + slot separately. Here are some scenarios: + + + + + When creating a subscription, the replication slot already exists. In + that case, the subscription can be created using the NOCREATE + SLOT option to associate with the existing slot. + + + + + + When creating a subscription, the remote host is not reachable or in an + unclear state. In that case, the subscription can be created using + the NOCONNECT option. The remote host will then not + be contacted at all. This is what pg_dump + uses. The remote replication slot will then have to be created + manually before the subscription can be activated. + + + + + + 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 ALTER + SUBSCRIPTION before attempting to drop the subscription. + + + + + + When dropping a subscription, the remote host is not reachable. In + that case, disassociate the slot from the subscription + using ALTER SUBSCRIPTION 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 + instance is just unreachable, the replication slot should then be + dropped manually; otherwise it would continue to reserve WAL and might + eventually cause the disk to fill up. Such cases should be carefully + investigated. + + + + +