Merge pull request #250742 from AlicjaKucharczyk/patch-2

Using Logical Replication Between Databases on the Same Server

Author: prmerger-automator[bot]

articles/postgresql/flexible-server/concepts-logical.md

@@ -66,9 +66,9 @@ Here's some sample code you can use to try out logical replication.
 
 1. Connect to the publisher database. Create a table and add some data.
    ```SQL
-   CREATE TABLE basic(id SERIAL, name TEXT);
-   INSERT INTO basic(name) VALUES ('apple');
-   INSERT INTO basic(name) VALUES ('banana');
+   CREATE TABLE basic (id INTEGER NOT NULL PRIMARY KEY, a TEXT);
+   INSERT INTO basic VALUES (1, 'apple');
+   INSERT INTO basic VALUES (2, 'banana');
    ```
 
 2. Create a publication for the table.
@@ -78,12 +78,12 @@ Here's some sample code you can use to try out logical replication.
 
 3. Connect to the subscriber database. Create a table with the same schema as on the publisher.
    ```SQL
-   CREATE TABLE basic(id SERIAL, name varchar(40));
+   CREATE TABLE basic (id INTEGER NOT NULL PRIMARY KEY, a TEXT);
    ```
 
-4. Create a subscription that will connect to the publication you created earlier.
+4. Create a subscription that connects to the publication you created earlier.
    ```SQL
-   CREATE SUBSCRIPTION sub CONNECTION 'host=<server>.postgres.database.azure.com user=<admin> dbname=<dbname> password=<password>' PUBLICATION pub;
+   CREATE SUBSCRIPTION sub CONNECTION 'host=<server>.postgres.database.azure.com user=<rep_user> dbname=<dbname> password=<password>' PUBLICATION pub;
    ```
 
 5. You can now query the table on the subscriber. You'll see that it has received data from the publisher.
@@ -100,9 +100,51 @@ Here's some sample code you can use to try out logical replication.
 
 Visit the PostgreSQL documentation to understand more about [logical replication](https://www.postgresql.org/docs/current/logical-replication.html).
 
+### Using logical replication between databases on the same server
+When you're aiming to set up logical replication between different databases residing on the same PostgreSQL server, it's essential to follow certain guidelines to avoid implementation restrictions that are currently present. As of now, creating a subscription that connects to the same database cluster will only succeed if the replication slot isn't created within the same command; otherwise, the `CREATE SUBSCRIPTION` call will hang, on a `LibPQWalReceiverReceive` wait event. This happens due to an existing restriction within Postgres engine, which might be removed in future releases.
+
+To effectively setup logical replication between your "source" and "target" databases on the same server while circumventing this restriction, follow the steps outlined below:
+
+First, create a table named "basic" with an identical schema in both the source and target databases:
+
+```SQL
+-- Run this on both source and target databases
+CREATE TABLE basic (id INTEGER NOT NULL PRIMARY KEY, a TEXT);
+```
+
+Next, in the source database, create a publication for the table and separately create a logical replication slot using the `pg_create_logical_replication_slot` function, which helps to avert the hanging issue that typically occurs when the slot is created in the same command as the subscription. Note that you'll need to use the `pgoutput` plugin:
+
+```SQL
+-- Run this on the source database
+CREATE PUBLICATION pub FOR TABLE basic;
+SELECT pg_create_logical_replication_slot('myslot', 'pgoutput');
+```
+
+Thereafter, in your target database, create a subscription to the previously created publication, ensuring that `create_slot` is set to `false` to prevent PostgreSQL from creating a new slot, and correctly specifying the slot name that was created in the previous step. Before running the command, replace the placeholders in the connection string with your actual database credentials:
+
+``` SQL
+-- Run this on the target database
+CREATE SUBSCRIPTION sub
+   CONNECTION 'dbname=<source dbname> host=<server>.postgres.database.azure.com port=5432 user=<rep_user> password=<password>'
+   PUBLICATION pub
+   WITH (create_slot = false, slot_name='myslot');
+```
+Having set up the logical replication, you can now test it by inserting a new record into the "basic" table in your source database and then verifying that it replicates to your target database:
+``` SQL
+-- Run this on the source database
+INSERT INTO basic SELECT 3, 'mango';
+
+-- Run this on the target database
+TABLE basic;
+```
+
+If everything is configured correctly, you should witness the new record from the source database in your target database, confirming the successful setup of logical replication.
+
+
+
 ### pglogical extension
 
-Here is an example of configuring pglogical at the provider database server and the subscriber. Refer to [pglogical extension documentation](https://github.com/2ndQuadrant/pglogical#usage) for more details. Also make sure you have performed prerequisite tasks listed above.
+Here's an example of configuring pglogical at the provider database server and the subscriber. Refer to [pglogical extension documentation](https://github.com/2ndQuadrant/pglogical#usage) for more details. Also make sure you have performed prerequisite tasks listed above.
 
 1. Install pglogical extension in the database in both the provider and the subscriber database servers.
     ```SQL
@@ -187,7 +229,7 @@ In the example below, we use the SQL interface with the wal2json plugin.
    SELECT data FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', '1');
    ```
 
-   The output will look like:
+   The output looks like:
    ```
    {
          "change": [
@@ -230,9 +272,9 @@ Visit the PostgreSQL documentation to understand more about [logical decoding](h
 
 
 ## Monitoring
-You must monitor logical decoding. Any unused replication slot must be dropped. Slots hold on to Postgres WAL logs and relevant system catalogs until changes have been read. If your subscriber or consumer fails or if it's improperly configured, the unconsumed logs will pile up and fill your storage. Also, unconsumed logs increase the risk of transaction ID wraparound. Both situations can cause the server to become unavailable. Therefore, it's critical that logical replication slots are consumed continuously. If a logical replication slot is no longer used, drop it immediately.
+You must monitor logical decoding. Any unused replication slot must be dropped. Slots hold on to Postgres WAL logs and relevant system catalogs until changes have been read. If your subscriber or consumer fails or if it's improperly configured, the unconsumed logs pile up and fill your storage. Also, unconsumed logs increase the risk of transaction ID wraparound. Both situations can cause the server to become unavailable. Therefore, it's critical that logical replication slots are consumed continuously. If a logical replication slot is no longer used, drop it immediately.
 
-The 'active' column in the pg_replication_slots view will indicate whether there's a consumer connected to a slot.
+The 'active' column in the pg_replication_slots view indicates whether there's a consumer connected to a slot.
 ```SQL
 SELECT * FROM pg_replication_slots;
 ```