Merge pull request #93529 from jonels-msft/hyperscale-connection-2

Improve acrolinx score for connection troubleshooting

Author: v-albemi

articles/postgresql/howto-hyperscale-troubleshoot-common-connection-issues.md

@@ -11,14 +11,14 @@ ms.date: 10/8/2019
 
 # Troubleshoot connection issues to Azure Database for PostgreSQL - Hyperscale (Citus)
 
-Connection problems may be caused by a variety of things, including:
+Connection problems may be caused by several things, such as:
 
 * Firewall settings
 * Connection time-out
-* Incorrect login information
+* Incorrect sign in information
 * Connection limit reached for server group
 * Issues with the infrastructure of the service
-* Maintenance being performed in the service
+* Service maintenance
 * The coordinator node failing over to new hardware
 
 Generally, connection issues to Hyperscale can be classified as follows:
@@ -28,56 +28,54 @@ Generally, connection issues to Hyperscale can be classified as follows:
 
 ## Troubleshoot transient errors
 
-Transient errors occur when maintenance is performed, the system encounters an
-error with the hardware or software, or briefly after you change the vCores of
-your coordinator node. The nodes in a Hyperscale server group have configurable
-high availability designed to mitigate these types of problems automatically.
-However, your application can lose its connection to the server for a short
-period of time even with high availability enabled. Some events can
-occasionally take longer to mitigate, such as when a large transaction causes a
-long-running recovery.
+Transient errors occur for a number of reasons. The most common include system
+Maintenance, error with hardware or software, and coordinator node vCore
+upgrades.
+
+Enabling high availability for Hyperscale server group nodes can mitigate these
+types of problems automatically. However, your application should still be
+prepared to lose its connection briefly. Also other events can take longer to
+mitigate, such as when a large transaction causes a long-running recovery.
 
 ### Steps to resolve transient connectivity issues
 
 1. Check the [Microsoft Azure Service
    Dashboard](https://azure.microsoft.com/status) for any known outages that
-   occurred during the time in which the errors were reported by the application.
-2. Applications that connect to a cloud service such as Azure Database for
-   PostgreSQL - Hyperscale (Citus) should expect transient errors and implement
-   retry logic to handle these errors instead of surfacing these as application
-   errors to users.
+   occurred during the time in which the application was reporting errors.
+2. Applications that connect to a cloud service such as Hyperscale (Citus)
+   should expect transient errors and react gracefully. For instance,
+   applications should implement retry logic to handle these errors instead of
+   surfacing them as application errors to users.
 3. As the server group approaches its resource limits, errors can seem like
    transient connectivity issues. Increasing node RAM, or adding worker nodes
    and rebalancing data may help.
-4. If connectivity problems continue, or if the duration for which your
-   application encounters the error exceeds 60 seconds or if you see multiple
-   occurrences of the error in a given day, file an Azure support request by
+4. If connectivity problems continue, or last longer than 60 seconds, or happen
+   more than once per day, file an Azure support request by
    selecting **Get Support** on the [Azure
    Support](https://azure.microsoft.com/support/options) site.
 
 ## Troubleshoot persistent errors
 
-If the application persistently fails to connect to Hyperscale (Citus), it
-usually indicates an issue with one of the following:
+If the application persistently fails to connect to Hyperscale (Citus), the
+most common causes are firewall misconfiguration or user error.
 
 * Coordinator node firewall configuration: Make sure that the Hyperscale server
   firewall is configured to allow connections from your client, including proxy
   servers and gateways.
 * Client firewall configuration: The firewall on your client must allow
-  connections to your database server. IP addresses and ports of the server
-  that you cannot to must be allowed as well as application names such as
-  PostgreSQL in some firewalls.
-* User error: You might have mistyped connection parameters, such as the server
-  name in the connection string or a missing *\@servername* suffix in the user
-  name.
+  connections to your database server. Some firewalls require allowing not only
+  application by name, but allowing the IP addresses and ports of the server.
+* User error: Double-check the connection string. You might have mistyped
+  parameters like the server name, or a forgot a *\@servername* suffix in the
+  user name.
 
 ### Steps to resolve persistent connectivity issues
 
 1. Set up [firewall rules](howto-hyperscale-manage-firewall-using-portal.md) to
    allow the client IP address. For temporary testing purposes only, set up a
    firewall rule using 0.0.0.0 as the starting IP address and using
-   255.255.255.255 as the ending IP address. This will open the server to all IP
-   addresses. If this resolves your connectivity issue, remove this rule and
+   255.255.255.255 as the ending IP address. That rule opens the server to all IP
+   addresses. If the rule resolves your connectivity issue, remove it and
    create a firewall rule for an appropriately limited IP address or address
    range.
 2. On all firewalls between the client and the internet, make sure that port