postgrespro.git / summary / log / commit / refs

commit    bfc80683ce51590545350b2c8ccfaa9e7a2a1870
Author:   Michael Paquier <michael@paquier.xyz>
Date:     Fri Apr 05 01:37:59 2019 +0000

    Fix some documentation in pg_rewind
    
    Since 11, it is possible to use a non-superuser role when using an
    online source cluster with pg_rewind as long as the role has proper
    permissions to execute on the source all the functions used by
    pg_rewind, and the documentation stated that a superuser is necessary.
    Let's add at the same time all the details needed to create such a
    role.
    
    A second confusion which comes a lot from users is that it is necessary
    to issue a checkpoint on a freshly-promoted standby so as its control
    file has up-to-date timeline information which is used by pg_rewind to
    validate the operation.  Let's document that properly.  This is
    back-patched down to 9.5 where pg_rewind has been introduced.
    
    Author: Michael Paquier
    Reviewed-by: Magnus Hagander
    Discussion: https://postgr.es/m/CABUevEz5bpvbwVsYCaSMV80CBZ5-82nkMzbb+Bu=h1m=rLdn=g@mail.gmail.com
    Backpatch-through: 9.5


 doc/src/sgml/ref/pg_rewind.sgml | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index d98406c420..e9715d5cf7 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -155,10 +155,12 @@ PostgreSQL documentation
       <listitem>
        <para>
         Specifies a libpq connection string to connect to the source
-        <productname>PostgreSQL</productname> server to synchronize the target with.
-        The connection must be a normal (non-replication) connection
-        with superuser access. This option requires the source
-        server to be running and not in recovery mode.
+        <productname>PostgreSQL</productname> server to synchronize the target
+        with. The connection must be a normal (non-replication) connection
+        with a role having sufficient permissions to execute the functions
+        used by <application>pg_rewind</application> on the source server
+        (see Notes section for details) or a superuser role.  This option
+        requires the source server to be running and not in recovery mode.
        </para>
       </listitem>
      </varlistentry>
@@ -246,6 +248,30 @@ PostgreSQL documentation
  <refsect1>
   <title>Notes</title>
 
+  <para>
+   When executing <application>pg_rewind</application> using an online
+   cluster as source, a role having sufficient permissions to execute the
+   functions used by <application>pg_rewind</application> on the source
+   cluster can be used instead of a superuser.  Here is how to create such
+   a role, named <literal>rewind_user</literal> here:
+<programlisting>
+CREATE USER rewind_user LOGIN;
+GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;
+</programlisting>  
+  </para>
+
+  <para>
+   When executing <application>pg_rewind</application> using an online
+   cluster as source which has been recently promoted, it is necessary
+   to execute a <command>CHECKPOINT</command> after promotion so as its
+   control file reflects up-to-date timeline information, which is used by
+   <application>pg_rewind</application> to check if the target cluster
+   can be rewound using the designated source cluster.
+  </para>
+
   <refsect2>
    <title>How it works</title>
 


[parent: 57a7a3adfe4e]