Merge pull request #5964 from EnterpriseDB/docs/pgd_reedit_13

Reedit of PGD doc - group 13

product_docs/docs/pgd/5/routing/readonly.mdx

@@ -7,10 +7,11 @@ navTitle: Read-only routing
 
 By default, PGD Proxy routes connections to the currently selected write leader in the cluster. This allows the write traffic conflicts to be rapidly and consistently resolved. Just routing everything to a single node, the write leader, is a natural fit for traditional high-availability deployments where system throughput is typically limited to the throughput of what a single node can handle.
 
-But for some use cases, this behavior also means that clients that are only querying the data are also placing a load on the current write leader. It's possible this read-only workload could be equally well served by one of the non-write leader nodes in the cluster. 
+But for some use cases, this behavior also means that clients that are only querying the data are also placing a load on the current write leader. It's possible this read-only workload could be equally well served by one of the non-write-leader nodes in the cluster. 
 
-If you could move traffic that has read-only queries to the non-write leader nodes, you could, at least in theory, handle a throughput that could be a multiple of a single node's capability. 
-An approach like this would, though, usually require changes to applications so that they were aware of details of cluster topology and the current node status to detect the write leader.
+
+If you could move traffic that has read-only queries to the non-write leader nodes, you could, at least in theory, handle a throughput which could be a multiple of a single nodes capability. 
+An approach like this, though, usually requires changes to applications so that they are aware of details of cluster topology and the current node status to detect the write leader.
 
 ## Read-only routing in PGD Proxy
 
@@ -28,13 +29,14 @@ Where available, the problem can be mitigated on the client side by passing [`de
 
 Only data nodes that aren't the write leader are valid as read-only nodes. For reference, the following node types aren't eligible to be a read-only node:
 
-* Witness nodes can't be eligible because they don't contain data. 
-* Logical standbys can't be eligible because they're standbys and prioritize replicating. 
-* Subscriber-only nodes also aren't currently eligible.
+* Witness nodes, because they don't contain data
+* Logical standbys, because they're standbys and prioritize replicating
+* Subscriber-only nodes
 
 ## Creating a proxy configuration
 
-SQL proxy-creation functions in PGD take an optional `proxy_mode` parameter. This parameter can be set to one of the following values:
+SQL proxy creation functions in PGD take an optional `proxy_mode` parameter. You can set this parameter to one of the following values:
+
 * `default` — This is the default value. It creates a proxy that can handle traffic that follows the write leader on port 6432.
 * `read-only` — This option creates a read-only proxy that routes traffic to nodes that aren't the write leader. It handles this read-only traffic only on port 6433.
 * `any` — This option creates create a proxy that can handle both read-only and write-leader-following traffic on separate ports: 6432 for write-leader-following traffic and 6433 for read-only traffic.
@@ -64,7 +66,7 @@ pgd create-proxy --proxy-name proxy-ro1 --node-group group-a --proxy-mode read-o
 ## Configuring running proxies
 
 !!! Note
-To change a proxy's configuration, after making changes, you must restart the proxy.
+After changing a proxy's configuration, restart the proxy to make the changes take effect.
 !!!
 
 You activate read-only routing on a proxy by setting the `read_listen_port` option to a port number. This port number is the port on which the proxy will listen for read-only traffic.
@@ -73,11 +75,11 @@ This is equivalent to creating a proxy with `proxy-mode` set to `any`.
 
 If you set a `read_listen_port` on a proxy and then set the `listen_port` to 0, the proxy listens only on the `read_listen_port` and routes only read-only traffic. 
 This is equivalent to creating a proxy with `proxy-mode` set to `read-only`. 
-The configuration elements related to the read/write port will be cleared (set to null).
+The configuration elements related to the read/write port are cleared (set to null).
 
 If you set a `listen_port` on a proxy and then set the `read_listen_port` to 0, the proxy listens only on the `listen_port` and routes only read/write traffic. 
 This is equivalent to creating a proxy with `proxy-mode` set to `default`. 
-The configuration elements related to the read-only port will be cleared (set to null).
+The configuration elements related to the read-only port are cleared (set to null).
 
 ### Configuring using SQL
 

product_docs/docs/pgd/5/security/roles-and-replication.mdx

@@ -8,13 +8,13 @@ DDL changes executed by a user are applied as that same user on each node.
 
 DML changes to tables are replicated as the table-owning user on the target node.
 
-By default, PGD will replicate new tables with the same owner across nodes.
+By default, PGD replicates new tables with the same owner across nodes.
 
 
-## Differing Table Ownership
+## Differing table ownership
 
-We recommend that that table be owned by the same user on each node, and it's
-the default behavior, but it can be overriden. In that case, there are some
+We recommend for the same user to own the table on each node. That's
+the default behavior, but you can override it. If you do, there are some
 things to take into account.
 
 Consider a situation where table A is owned by user X on node1 and owned by 
@@ -32,8 +32,8 @@ On tables with row-level security policies enabled, changes are replicated
 without reenforcing policies on apply. This behavior is equivalent to the
 changes being applied as `NO FORCE ROW LEVEL SECURITY`, even if `FORCE ROW LEVEL
 SECURITY` is specified. If this isn't what you want, specify a row_filter that
-avoids replicating all rows. We recommend but don't enforce that the row
-security policies on all nodes be identical or at least compatible.
+avoids replicating all rows. We recommend that the row
+security policies on all nodes be identical or at least compatible, but we don't enforce this.
 
 ## bdr_superuser role and replication
 
@@ -64,4 +64,3 @@ creating a foreign key with PGD. Relying solely on the REFERENCES privilege
 isn't typically useful since it makes the validation check execute using
 triggers rather than a table scan. It's typically too expensive to use
 successfully.
-

product_docs/docs/pgd/5/security/roles.mdx

@@ -2,7 +2,7 @@
 title: Roles
 ---
 
-Configuring and managing PGD doesn't require superuser access. We recommend that
+Configuring and managing PGD doesn't require superuser access and we recommend that
 you don't use superuser access. Instead, the privileges required to administer
 PGD are split across the following predefined roles.
 
@@ -16,16 +16,16 @@ PGD are split across the following predefined roles.
 
 
 These roles are named to be analogous to PostgreSQL's `pg_` [predefined
-roles](https://www.postgresql.org/docs/current/predefined-roles.html):
+roles](https://www.postgresql.org/docs/current/predefined-roles.html).
 
 The PGD `bdr_` roles are created when the BDR extension is installed. See [PGD
 predefined roles](pgd-predefined-roles) for more details of the privileges each
-one has.
+role has.
 
 Managing PGD doesn't require that administrators have access to user data.
 
 Arrangements for securing information about conflicts are discussed in
-[Logging conflicts to a table](../reference/conflict_functions/#logging-conflicts-to-a-table).
+[Logging conflicts to a table](/pgd/latest/reference/conflict_functions#logging-conflicts-to-a-table).
 
 You can monitor conflicts using the [`bdr.conflict_history_summary`](/pgd/latest/reference/catalogs-visible#bdrconflict_history_summary) view.
 

product_docs/docs/pgd/5/upgrades/app_upgrades.mdx

@@ -16,9 +16,9 @@ application schema upgrade on the cluster.
 
 ### Rolling application schema upgrades
 
-By default, DDL will automatically be sent to all nodes. You can control this behavior
+By default, DDL is automatically sent to all nodes. You can control this behavior
 manually, as described in
-[DDL Replication](../ddl/). You can use this approach
+[DDL replication](../ddl/). You can use this approach
 to create differences between database schemas across nodes.
 
 PGD is designed to allow replication to continue even with minor
@@ -30,7 +30,7 @@ standby nodes for reporting or testing.
     You must manage rolling application schema upgrades outside of PGD.
 
     Careful scripting is required to make this work correctly
-    on production clusters. Extensive testing is advised.
+    on production clusters. We recommend extensive testing.
 
 See [Replicating between nodes with differences](../appusage/) for details.
 

product_docs/docs/pgd/5/upgrades/bdr_pg_upgrade.mdx

@@ -5,14 +5,14 @@ title: In-place Postgres major version upgrades
 You can upgrade a PGD node to a newer major version of Postgres using the
 command-line utility bdr_pg_upgrade.
 
-bdr_pg_upgrade is a wrapper around the standard [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html)
-adding PGD-specific logic to the process to ensure a smooth upgrade.
+bdr_pg_upgrade is a wrapper around the standard [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) that
+adds PGD-specific logic to the process to ensure a smooth upgrade.
 
 ## Terminology
 
 This terminology is used when describing the upgrade process and components involved:
 
-*Postgres cluster*: — The database files, both executables and data, which make up a Postgres database instance on a system when run. 
+*Postgres cluster* — The database files, both executables and data, that make up a Postgres database instance on a system when run. 
 
 *Old Postgres cluster* — The existing Postgres cluster to upgrade, the one from which to migrate data.
 
@@ -34,10 +34,10 @@ You must meet several prerequisites for bdr_pg_upgrade:
 -   Configure peer authentication for both Postgres clusters. bdr_pg_upgrade
     requires peer authentication.
 -   The same PGD version must be installed on both clusters.
--   The PGD version must be 4.1.0 or above. Version 3.7.22 and later is also supported.
+-   The PGD version must be 4.1.0 or later. Version 3.7.22 and later is also supported.
 -   The new cluster must be in a shutdown state.
 -   You must install PGD packages in the new cluster.
--   The new cluster must be already initialized and configured as needed to
+-   The new cluster must already be initialized and configured as needed to
     match the old cluster configuration.
 -   Databases, tables, and other objects must not exist in the new cluster.
 
@@ -63,7 +63,7 @@ bdr_pg_upgrade [OPTION] ...
 #### Options
 
 In addition to the options for pg_upgrade, you can pass the following parameters
-to bdr_pg_upgrade:
+to bdr_pg_upgrade.
 
 **Required parameters**
 
@@ -77,7 +77,7 @@ Specify these parameters either in the command line or, for all but the `--datab
 
 **Optional parameters**
 
-These parameters are optional and are used by bdr_pg_upgrade.
+These parameters are optional and are used by bdr_pg_upgrade:
 
 -   `-p, --old-port` — Old cluster port number.
 -   `-s, --socketdir` — Directory to use for postmaster sockets during upgrade.
@@ -99,7 +99,7 @@ Any other parameter that's not one of the above is passed to pg_upgrade. pg_upgr
 
 #### Environment variables
 
-You can use these environment variables in place of command line parameters:
+You can use these environment variables in place of command-line parameters:
 
 -   `PGBINOLD` — Old Postgres cluster bin directory.
 -   `PGBINNEW` — New Postgres cluster bin directory.
@@ -151,7 +151,7 @@ These steps are performed when running bdr_pg_upgrade.
 | Connecting to old cluster                       | `skip`             |
 | Checking if bdr schema exists                   | `skip`             |
 | Turning DDL replication off                     | `skip`             |
-| Terminating connections to database.            | `skip`             |
+| Terminating connections to database             | `skip`             |
 | Waiting for all slots to be flushed             | `skip`             |
 | Disconnecting from old cluster                  | `skip`             |
 | Stopping old cluster                            | `skip`             |

product_docs/docs/pgd/5/upgrades/manual_overview.mdx

@@ -6,7 +6,7 @@ Because EDB Postgres Distributed consists of multiple software components,
 the upgrade strategy depends partially on the components that are being upgraded.
 
 In general, you can upgrade the cluster with almost zero downtime by
-using an approach called rolling upgrade. Using this approach, nodes are upgraded one by one, and
+using an approach called *rolling upgrade*. Using this approach, nodes are upgraded one by one, and
 the application connections are switched over to already upgraded nodes.
 
 You can also stop all nodes, perform the upgrade on all nodes, and
@@ -38,19 +38,19 @@ You can use both of these approaches in a rolling manner.
 
 While the cluster is going through a rolling upgrade, mixed versions of software
 are running in the cluster. For example, suppose nodeA has PGD 3.7.16, while
-nodeB and nodeC has 4.1.0. In this state, the replication and group
+nodeB and nodeC have 4.1.0. In this state, the replication and group
 management uses the protocol and features from the oldest version (3.7.16
 in this example), so any new features provided by the newer version
 that require changes in the protocol are disabled. Once all nodes are
 upgraded to the same version, the new features are enabled.
 
 Similarly, when a cluster with WAL-decoder-enabled nodes is going through a
-rolling upgrade, WAL decoder on a higher version of PGD node produces LCRs
-([logical change records](../node_management/decoding_worker/#enabling)) with a
+rolling upgrade, WAL decoder on a higher version of PGD node produces
+[logical change records (LCRs)](../node_management/decoding_worker/#enabling) with a
 higher pglogical version. WAL decoder on a lower version of PGD node produces
-LCRs with lower pglogical version. As a result, WAL senders on a higher version
-of PGD nodes are not expected to use LCRs due to a mismatch in protocol
-versions. On a lower version of PGD nodes, WAL senders may continue to use LCRs.
+LCRs with a lower pglogical version. As a result, WAL senders on a higher version
+of PGD nodes aren't expected to use LCRs due to a mismatch in protocol
+versions. On a lower version of PGD nodes, WAL senders can continue to use LCRs.
 Once all the PGD nodes are on the same PGD version, WAL senders use LCRs.
 
 A rolling upgrade starts with a cluster with all nodes at a prior release. It
@@ -69,16 +69,16 @@ EDB Postgres Advanced Server in one cluster. So you can't use this approach
 to change the Postgres variant.
 
 !!! Warning
-    Downgrades of the EDB Postgres Distributed aren't supported. They require
+    Downgrades of EDB Postgres Distributed aren't supported. They require
     that you manually rebuild the cluster.
 
 ### Rolling server software upgrades
 
 A rolling upgrade is where the [server software
 upgrade](#server-software-upgrade) is upgraded sequentially on each node in a
-cluster without stopping the the cluster. Each node is temporarily stopped from
-partiticpating in the cluster and its server software upgraded. Once updated, it
-is returned to the cluster and it then catches up with the cluster's activity
+cluster without stopping the cluster. Each node is temporarily stopped from
+participating in the cluster and its server software is upgraded. Once updated, it's
+returned to the cluster, and it then catches up with the cluster's activity
 during its absence.
 
 The actual procedure depends on whether the Postgres component is being
@@ -118,23 +118,23 @@ using the new [commit scope](../durability/commit-scopes)-based settings.
 We recommended the following approach for upgrading two BDR nodes that
 constitute a CAMO pair to PGD 5.0:
 
-- Ensure `bdr.enable_camo` remains `off` for transactions on any of
+1. Ensure `bdr.enable_camo` remains `off` for transactions on any of
   the two nodes, or redirect clients away from the two nodes. Removing
   the CAMO pairing while attempting to use CAMO leads to errors
   and prevents further transactions.
-- Uncouple the pair by deconfiguring CAMO either by resetting
+1. Uncouple the pair by deconfiguring CAMO either by resetting
   `bdr.camo_origin_for` and `bdr.camo_parter_of` (when upgrading from
   BDR 3.7.x) or by using `bdr.remove_camo_pair` (on BDR 4.x).
-- Upgrade the two nodes to PGD 5.0.
-- Create a dedicated node group for the two nodes and move them into
+1. Upgrade the two nodes to PGD 5.0.
+1. Create a dedicated node group for the two nodes and move them into
   that node group.
-- Create a [commit scope](../durability/commit-scopes) for this node
+1. Create a [commit scope](../durability/commit-scopes) for this node
   group and thus the pair of nodes to use CAMO.
-- Reactivate CAMO protection again by either setting a
+1. Reactivate CAMO protection again either by setting a
   `default_commit_scope` or by changing the clients to explicitly set
   `bdr.commit_scope` instead of `bdr.enable_camo` for their sessions
   or transactions.
-- If necessary, allow clients to connect to the CAMO protected nodes
+1. If necessary, allow clients to connect to the CAMO-protected nodes
   again.
 
 ## Upgrade preparation
@@ -175,7 +175,7 @@ detect the older version of the extension.
 ### Postgres upgrade
 
 The process of in-place upgrade of Postgres depends on whether you're
-upgrading to new minor version of Postgres or to a new major version of Postgres.
+upgrading to a new minor version of Postgres or to a new major version of Postgres.
 
 #### Minor version Postgres upgrade
 
@@ -191,13 +191,13 @@ version of Postgres you're upgrading to.
 
 Upgrading to a new major version of Postgres is more complicated than upgrading to a minor version.
 
-EDB Postgres Distributed provides a `bdr_pg_upgrade` command line utility,
+EDB Postgres Distributed provides a bdr_pg_upgrade command line utility,
 which you can use to do [in-place Postgres major version upgrades](bdr_pg_upgrade).
 
 !!! Note
     When upgrading to a new major version of any software, including Postgres, the
-    BDR extension, and others, it's always important to ensure the compatibility
-    of your application with the target version of the software you're upgrading.
+    BDR extension, and others, it's always important to ensure
+    your application is compatible with the target version of the software you're upgrading.
 
 ## Upgrade check and validation
 
@@ -218,7 +218,7 @@ HARP can temporarily coexist with the new
 
 -  Upgrade a whole pre-5 cluster to a PGD 5 cluster. 
 -  Set up the connection routing. 
--  Replace the HARP Proxy with PGD Proxy. 
+-  Replace HARP Proxy with PGD Proxy. 
 -  Move application connections to PGD Proxy instances.
 -  Remove the HARP Manager from all servers.