DOC: reviewed the latest changes in pg_shardman docs

Author: Liudmila Mantrova

doc/src/sgml/pg_shardman.sgml

@@ -11,18 +11,18 @@
     that enables sharding — splitting large tables into separate partitions, or shards,
     distributed between different servers. This extension aims for
     scalability and fault tolerance with ACID transactions support, targeting mainly
-    <acronym>OLTP</acronym> workloads. <filename>pg_shardman</filename>, supports:
+    <acronym>OLTP</acronym> workloads. <filename>pg_shardman</filename> offers the following features:
     <itemizedlist spacing="compact">
       <listitem>
         <para>
           Splitting tables into shards using hash partitioning provided
-          by <link linkend="pg-pathman">pg_pathman</link> and move the shards
+          by <link linkend="pg-pathman">pg_pathman</link> and moving the shards
           across cluster nodes to balance read/write load.
         </para>
       </listitem>
       <listitem>
         <para>
-          Running read-write queries on any node, regardless of the actual data
+          Running read/write queries on any node, regardless of the actual data
           location.  Queries will be automatically redirected to the node
           holding the required data via <xref linkend="postgres-fdw">.
         </para>
@@ -33,24 +33,24 @@
           number of replicas to create for each
           shard. <filename>pg_shardman</filename> leverages logical
           replication to keep replicas up-to-date. Synchronous and
-          asynchronous replication is supported.
+          asynchronous replication types are supported.
         </para>
       </listitem>
       <listitem>
         <para>
-         Atomic modification of data kept on multiple nodes in one
+         Atomic modification of data stored on multiple nodes in a single
          transaction using 2PC commit.
         </para>
       </listitem>
       <listitem>
         <para>
-         Cluster-wide REPEATABLE READ (as in Postgres) transaction isolation
-         level.
+         Support for cluster-wide <literal>Repeatable Read</literal>
+         transaction isolation level.
         </para>
       </listitem>
       <listitem>
         <para>
-         Manual failover with replica promotion
+         Manual failover with replica promotion.
         </para>
       </listitem>
     </itemizedlist>
@@ -76,8 +76,9 @@
     </listitem>
     <listitem>
       <para>
-       DDL support is very limited, see below. DCL support is basically
-       absent, only one user is supported.
+       <filename>pg_shardman</filename> provides only limited DDL support,
+       as explained in <xref linkend="working-with-cluster-data">. DCL support is virtually
+       absent, with only one user being supported.
       </para>
     </listitem>
     <listitem>
@@ -103,8 +104,8 @@
     </listitem>
     <listitem>
       <para>
-      Two-phase commit doesn't involve replicas; data inconsistencies are
-      possible if a node fails permanently.
+      Two-phase commit does not involve replicas, so a permanent node failure
+      may result in data inconsistencies.
       </para>
     </listitem>
     <listitem>
@@ -158,50 +159,58 @@
    <productname>&productname;</productname> as usual. However, to handle
    distributed transactions, <filename>pg_shardman</filename> relies on
    two-phase commit (<acronym>2PC</acronym>) protocol for atomicity and
-   Clock-SI algorithm for transaction isolation, which are enabled with the
-   following GUC variables:
+   Clock-SI algorithm for transaction isolation.
   </para>
 
-   <itemizedlist>
-    <listitem>
      <para>
-       <varname>postgres_fdw.use_twophase</varname> variable turns on
-       <acronym>2PC</acronym> support. With <acronym>2PC</acronym> enabled,
-       each transaction will be <firstterm>prepared</firstterm> on all
-       nodes before the commit. A successful <literal>PREPARE</literal>
-       on the node means that this node is ready to commit the transaction,
-       but it will only be committed if all other nodes can commit this
-       transaction as well. Otherwise, the transaction will be aborted.
-       This approach allows to ensure transaction atomicity across multiple nodes.
-       2PC is never used if transaction did writes only on single node.
+       To turn on <acronym>2PC</acronym> support, use the
+       <varname>postgres_fdw.use_twophase</varname> variable.
+       With <acronym>2PC</acronym> enabled, each transaction is
+       <firstterm>prepared</firstterm> on all nodes before the commit.
+       A successful <literal>PREPARE</literal> on the node means that
+       this node is ready to commit the transaction, but it will only be
+       committed if all the other nodes can commit this transaction as
+       well. Otherwise, the transaction will be aborted. This approach
+       allows to ensure transaction atomicity across multiple nodes.
      </para>
 
      <para>
-       This parameter can be changed at any time; the behavior for any one
-       transaction is determined by the setting in effect when it commits.
-       It is therefore possible to have some transactions commit with 2PC and
-       some without.
+       This parameter can be changed at any time. Since the transaction
+       behavior is determined by the <varname>postgres_fdw.use_twophase</varname>
+       setting at commit time, some distributed transactions may use
+       2PC while others may not. Regardless of this setting, 2PC is never used
+       for write transactions only affect a single node.
      </para>
 
      <para>
-      The well-known shortcoming of 2PC is that it is a blocking protocol: if
-      transaction coordinator has failed, some transactions might hang until
-      the resolution in PREPAREd state. <filename>pg_shardman</filename>
-      provides <function>shardman.recover_xacts()</> function to resolve them.
+      A well-known shortcoming of 2PC is that it is a blocking protocol: if
+      the transaction coordinator has failed, some transactions might hang
+      in the <literal>PREPARE</literal> state. <filename>pg_shardman</filename>
+      provides <xref linkend="shardman-recover-xacts"> function to resolve them.
      </para>
+
+     <para>To ensure cluster-wide transaction isolation, use the following variables:
+     </para>
+
+   <itemizedlist>
+    <listitem>
+      <para>
+       <varname>track_global_snapshots</varname> variable enables a
+       distributed transaction manager based on the Clock-SI
+       algorithm, which provides cluster-wide transaction isolation at
+       the <literal>Repeatable Read</literal> level. Changing this parameter
+       requires a server restart.
+      </para>
     </listitem>
     <listitem>
       <para>
-       <varname>track_global_snapshots</varname> and
-       <varname>postgres_fdw.use_global_snapshots</varname> variable control
-       the behaviour of distributed transaction manager based on the Clock-SI
-       algorithm, providing cluster-wide transaction isolation at
-       the <literal>REPEATABLE READ</literal> level. To use
-       it, <varname>track_global_snapshots</varname> must be set
-       to <literal>on</>; change of this parameter requires server restart.
-       <varname>postgres_fdw.use_global_snapshots</varname> defines whether to
-       use global snapshot for current transaction. It can by changed at any
-       time, its value is consulted during COMMIT.
+       <varname>postgres_fdw.use_global_snapshots</varname> variable
+       defines whether to use global snapshots for the current transaction.
+       If you set this variable to <literal>on</literal>, you must also
+       enable the distributed transaction manager using the
+       <varname>track_global_snapshots</varname> variable. You can change
+       the <varname>postgres_fdw.use_global_snapshots</varname> setting
+       at any time; its value is consulted during transaction commit.
       </para>
     </listitem>
   </itemizedlist>
@@ -212,8 +221,8 @@
     replication, which can cause data inconsistencies if a node fails
     permanently. A part of a distributed transaction might get lost and cause
     a non-atomic result if the coordinator has prepared the transaction
-    everywhere, started commiting it and then some node failed before
-    committing the transaction on replica.
+    everywhere, started commiting it, but one of the nodes failed before
+    committing the transaction on a replica.
   </para>
 
   <para>
@@ -430,10 +439,10 @@ max_prepared_transactions = 1000
 </listitem>
 <listitem>
  <para>
-  Adjust the <xref linkend="guc-synchronous-commit"> variable to match your
-  choice of replication mode: for synchronous replication, it must be set to
-  on. Note that you can set it on per-transaction basis, making some
-  transactions commit synchronously and some not.
+  Make sure the <xref linkend="guc-synchronous-commit"> variable specifies the
+  replication type of your choice. For synchronous replication, it must be set to
+  <literal>on</literal>. You can change this setting at any time, so
+  different transactions may use different replication modes.
 
   <programlisting>
 synchronous_commit = on
@@ -481,7 +490,7 @@ CREATE EXTENSION pg_shardman CASCADE;
         is mandatory, as superuser privileges are required to configure logical
         replication between the nodes. The optional <varname>conn_string</varname>
        parameter is used for configuring FDWs; this allows to access the data
-       without being superuser. If you omit this parameter, <filename>pg_shardman</filename>
+       without superuser rights. If you omit this parameter, <filename>pg_shardman</filename>
         uses <varname>super_conn_string</varname> for all purposes.
         The <replaceable>repl_group</replaceable> parameter defines the
         replication group to add the node to. If you omit this, the node is
@@ -755,7 +764,7 @@ SELECT create_hash_partitions('films', 'id', 30, redundancy = 1);
   Once a table is sharded and filled with data, you can execute
   <acronym>DML</acronym> statements on this table from any <filename>pg_shardman</filename> worker
   node. <acronym>DML</acronym> statements can access more than one shard, remote or local.
-  It is implemented using the standard <productname>&productname;</productname>
+  It is implemented using the standard <productname>&project;</productname>
   inheritance mechanism: all partitions are derived from the parent table.
   If the required partition is located on another node, it will be
   accessed using <filename>postgres_fdw</filename>.
@@ -776,17 +785,18 @@ SELECT create_hash_partitions('films', 'id', 30, redundancy = 1);
 </note>
 
 <para>
- DDL support is very limited. Function <xref linkend="shardman-alter-table">
-  alters root table at all nodes and updates its definition in metadata; it
-  can be used for column addition, removal and renaming. However, changing
+  DDL support is very limited. Function <xref linkend="shardman-alter-table">
+  alters root table on all nodes and updates its definition in cluster metadata; it
+  can be used to add, remove, or rename columns. However, changing
   column used as sharding key is not supported. NOT NULL constraint can also
   be created using this function. Foreign keys pointing to sharded tables are
   not supported. Though it is possible to create UNIQUE constraint, it will be
   enforced only on per-partition basis. Indexes which were created on table
   before sharding it will be included in table definiton and created on
   partitions and replicas too. <xref linkend="shardman-forall"> executes SQL
-   statement on all nodes; it can be used to create indexes later. For that it
-   is necessary to create an index on each partition separately, like described in <ulink url="https://github.com/postgrespro/pg_pathman/wiki/How-do-I-create-indexes"><filename>pg_pathman wiki</filename></ulink>.
+  statement on all nodes; it can be used to create indexes later. For that it
+  is necessary to create an index on each partition separately, as described
+  in <ulink url="https://github.com/postgrespro/pg_pathman/wiki/How-do-I-create-indexes"><filename>pg_pathman wiki</filename></ulink>.
 
 </para>
 
@@ -1149,9 +1159,9 @@ excludes this node from the cluster, as follows:
      <listitem>
       <para>
        When set to <literal>on</literal>, <filename>pg_shardman</filename>
-       adds replicas to list of <xref linkend="guc-synchronous-standby-names">,
-        enabling synchronous replication. This parameter should not be changed
-        if any replicas exist.
+       adds replicas to the list of <xref linkend="guc-synchronous-standby-names">,
+       enabling synchronous replication. This parameter should not be changed
+       if any replicas exist.
       </para>
       <para>
        Default: <literal>off</literal>
@@ -1174,9 +1184,10 @@ excludes this node from the cluster, as follows:
        Connection string for the shardlord. You can use all the options that
        libpq accepts in connection strings, as described in <xref linkend="libpq-paramkeywords">.
        You must ensure that the node is accessed on behalf of a superuser.
-        This GUC must be set on shardlord itself; you can also optionally set
-        it on worker nodes, in that case you can execute cluster management
-        functions on workers and they will be redirected to shardlord automatically.
+       This variable must be set on the shardlord itself. You can also optionally set
+       it on worker nodes if you would like to execute cluster management
+       functions on worker nodes. In this case, these commands will be automatically
+       redirected to the shardlord.
       </para>
       <para>
        This parameter can only be set in the <filename>postgresql.conf</>
@@ -1721,24 +1732,28 @@ excludes this node from the cluster, as follows:
      </term>
      <listitem>
       <para>
-        Execute SQL statement on all nodes.
+        Execute an SQL statement on all nodes.
       </para>
       <para>Arguments:
       </para>
       <itemizedlist spacing="compact">
         <listitem>
           <para>
-           <parameter>sql</parameter> &mdash; Statement to execute.
+           <parameter>sql</parameter> &mdash; the statement to execute.
           </para>
         </listitem>
         <listitem>
           <para>
-           <parameter>use_2pc</parameter> &mdash; use two-phase commit?
+           <parameter>use_2pc</parameter> &mdash; defines whether to use
+           two-phase commit. The default value is inherited from
+           the <xref linkend="guc-postgres-fdw-use-twophase"> setting.
           </para>
         </listitem>
         <listitem>
           <para>
-           <parameter>including_shardlord</parameter> &mdash; run statement on shardlord too?
+           <parameter>including_shardlord</parameter> &mdash; defines whether
+           to run the SQL statement on the shardlord. By default, the statement
+           is executed on worker nodes only.
           </para>
         </listitem>
         </itemizedlist>
@@ -1750,7 +1765,7 @@ excludes this node from the cluster, as follows:
   <function>shardman.alter_table(<parameter>relation</parameter> <type>regclass</type>, <parameter>alter_clause</parameter> <type>text</type>)
   </function>
   <indexterm>
-   <primary><function>shardman.forall()</></primary>
+   <primary><function>shardman.alter_table()</></primary>
 </indexterm>
 </term>
 <listitem>
@@ -1774,7 +1789,7 @@ excludes this node from the cluster, as follows:
  <para>
   Example:
   <programlisting>
-   SELECT shardman.alter_table('films', 'add column author text');
+   SELECT shardman.alter_table('films', 'ADD COLUMN author text');
 </programlisting>
 
  </para>

doc/src/sgml/postgres-fdw.sgml

@@ -635,12 +635,9 @@
     </term>
     <listitem>
      <para>
-      Enables/disables distributed transaction manager based on
-      Clock-SI algorithm. When enabled, provides cluster-wide transaction
-      isolation at the <literal>REPEATABLE READ</literal> level.
-      <varname>track_global_snapshots</varname> must be set to
-      <literal>true</literal> when enabling this. It can by changed at any
-       time, its value is consulted during COMMIT.
+      Enables/disables global snapshots for the current transaction
+      if <xref linkend="guc-track-global-snapshots"> is set to <literal>true</literal>.
+      This setting can be changed at any time, its value is consulted during transaction commit.
      </para>
      <para>
       Default: <literal>false</literal>