Improve documentation for START_REPLICATION ... LOGICAL.

The starting point may not be exactly what the client requested; it
may be at the slot's confirmed_flush_lsn.

Also, upgrade the message from DEBUG1 to LOG when this happens.

Reviewed-by: Amit Kapila
Discussion: https://postgr.es/m/c5c861d576f2511732f8002c76245da587110b1c.camel%40j-davis.com

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index e8cb78ff1f3776bd1e24232fa82d33186177bf6a..9843953b05ff45be53f5bdb394633991af9305ca 100644 (file)
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2410,10 +2410,22 @@ The commands accepted in replication mode are:
     START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ]
     
      
-      Instructs server to start streaming WAL for logical replication, starting
-      at WAL location XXX/XXX. The server can
-      reply with an error, for example if the requested section of WAL has already
-      been recycled. On success, server responds with a CopyBothResponse
+      Instructs server to start streaming WAL for logical replication,
+      starting at either WAL location 
+      class="parameter">XXX/XXX or the slot's
+      confirmed_flush_lsn (see 
+      linkend="view-pg-replication-slots"/>), whichever is greater. This
+      behavior makes it easier for clients to avoid updating their local LSN
+      status when there is no data to process. However, starting at a
+      different LSN than requested might not catch certain kinds of client
+      errors; so the client may wish to check that
+      confirmed_flush_lsn matches its expectations before
+      issuing START_REPLICATION.
+     
+
+     
+      The server can reply with an error, for example if the
+      slot does not exist. On success, server responds with a CopyBothResponse
       message, and then starts to stream WAL to the frontend.
      
 


diff --git a/src/backend/replication/logical/logical.c b/src/backend/replication/logical/logical.c

index 8dcb564af8f63375d03e3355de874c0a741fb533..64b8280c13562c28786026c267ec7715cfb8759f 100644 (file)

--- a/src/backend/replication/logical/logical.c
+++ b/src/backend/replication/logical/logical.c
@@ -520,8 +520,12 @@ CreateDecodingContext(XLogRecPtr start_lsn,
         * xlog records didn't result in anything relevant for logical
         * decoding. Clients have to be able to do that to support synchronous
         * replication.
+        *
+        * Starting at a different LSN than requested might not catch certain
+        * kinds of client errors; so the client may wish to check that
+        * confirmed_flush_lsn matches its expectations.
         */
-       elog(DEBUG1, "cannot stream from %X/%X, minimum is %X/%X, forwarding",
+       elog(LOG, "%X/%X has been already streamed, forwarding to %X/%X",
             LSN_FORMAT_ARGS(start_lsn),
             LSN_FORMAT_ARGS(slot->data.confirmed_flush));
 

diff --git a/src/backend/replication/logical/logical.c b/src/backend/replication/logical/logical.c
index 8dcb564af8f63375d03e3355de874c0a741fb533..64b8280c13562c28786026c267ec7715cfb8759f 100644 (file)
--- a/src/backend/replication/logical/logical.c
+++ b/src/backend/replication/logical/logical.c
@@ -520,8 +520,12 @@ CreateDecodingContext(XLogRecPtr start_lsn,
         * xlog records didn't result in anything relevant for logical
         * decoding. Clients have to be able to do that to support synchronous
         * replication.
+        *
+        * Starting at a different LSN than requested might not catch certain
+        * kinds of client errors; so the client may wish to check that
+        * confirmed_flush_lsn matches its expectations.
         */
-       elog(DEBUG1, "cannot stream from %X/%X, minimum is %X/%X, forwarding",
+       elog(LOG, "%X/%X has been already streamed, forwarding to %X/%X",
             LSN_FORMAT_ARGS(start_lsn),
             LSN_FORMAT_ARGS(slot->data.confirmed_flush));