Merge pull request #3226 from EnterpriseDB/release/2022-10-6a

Release: 2022-10-6a
EnterpriseDB · Oct 6, 2022 · 42bf705 · 42bf705
2 parents dbbc5d9 + dde6d15
commit 42bf705
Show file tree

Hide file tree

Showing 4 changed files with 61 additions and 14 deletions.
diff --git a/product_docs/docs/biganimal/release/getting_started/creating_a_cluster/index.mdx b/product_docs/docs/biganimal/release/getting_started/creating_a_cluster/index.mdx
@@ -35,14 +35,14 @@ Prior to creating your cluster, make sure you have enough resources. Without eno
 
      - [Single node](/biganimal/latest/overview/02_high_availability/#single-node) creates a cluster with one primary and no standby replicas. Suited for test environments where high availability might not be required. You can create single node clusters running EDB Postgres Advanced Server or PostgreSQL. 
 
-    -  [High availability](/biganimal/latest/overview/02_high_availability/#high-availability) creates a cluster with one primary and two standby replicas in different availability zones. You can create high availability clusters running EDB Postgres Advanced Server or PostgreSQL. 
+    -  [High availability](/biganimal/latest/overview/02_high_availability/#high-availability) creates a cluster with one primary and one or two standby replicas in different availability zones. You can create high-availability clusters running EDB Postgres Advanced Server or PostgreSQL. Only high-availability clusters allow you to enable read-only workloads for users. However, if you enable read-only workloads, then you might have to raise the IP address resource limits for the cluster. 
 
-    -  [Extreme high availability (beta)](/biganimal/latest/overview/02_high_availability/#extreme-high-availability-beta) creates a cluster configured with a leader node, three shadow nodes, and one witness node. This cluster uses EDB Postgres Distributed to deliver higher performance and faster recovery. You can create extreme high availability clusters with either PostgreSQL or Oracle compatibility. 
+    -  [Extreme high availability (beta)](/biganimal/latest/overview/02_high_availability/#extreme-high-availability-beta) creates a cluster configured with a leader node, three shadow nodes, and one witness node. This cluster uses EDB Postgres Distributed to deliver higher performance and faster recovery. You can create extreme high-availability clusters with either PostgreSQL or Oracle compatibility. 
 
     See [Supported cluster types](/biganimal/latest/overview/02_high_availability/) for more information about the different cluster types.
 
     !!! Note
-       You can't switch from a single node or high availability cluster to an extreme high availability cluster or vice versa. 
+       You can't switch from a single node or high-availability cluster to an extreme high-availability cluster or vice versa. 
 
 1. Select the number of standby replicas for your cluster. 
 
@@ -84,24 +84,40 @@ Prior to creating your cluster, make sure you have enough resources. Without eno
        To maximize your disk size for AWS, select Rb5 as your instance, and then io2 Block Express as your storage to get a maximum disk size of 64 TB and 256,000 IOPS.
 
 1.  In the **Storage** section, select your volume type from the **Volume Type** list. 
-    - For Azure, in **Volume Type** select either Premium SSD or Ultra Disk. Compared to Premium SSD volumes, Ultra Disks offer lower latency, high-performance options, and direct control over your disk's IOPS (input/output operations per second). BigAnimal recommends using Ultra Disks for workloads that require the most demanding performance. See [Using Azure ultra disks](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-enable-ultra-ssd?tabs=azure-portal) for more information. 
-      - For Premium SSD, in **Volume Properties**, select the type and amount of storage needed for your cluster. See [Azure Premium SSD storage types](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#premium-ssds) for more information. 
+       - For Azure, in **Volume Type** select either **Premium SSD** or **Ultra Disk**. Compared to Premium SSD volumes, ultra disks offer lower latency, high-performance options, and direct control over your disk's input/output operations per second (IOPS). For BigAnimal, we recommend using ultra disks for workloads that require the most demanding performance. See [Using Azure ultra disks](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-enable-ultra-ssd?tabs=azure-portal) for more information. 
+          - For Premium SSD, in **Volume Properties**, select the type and amount of storage needed for your cluster. See [Azure Premium SSD storage types](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#premium-ssds) for more information. 
 
-      - For Ultra Disk, in **Volume Properties**, select the disk size and IOPS for your cluster. BigAnimal calculates the throughput based on your IOPS settings. 
+          - For ultra disk, in **Volume Properties**, select the disk size and IOPS for your cluster. BigAnimal calculates the throughput based on your IOPS settings. 
 
-        !!!important
-        While setting the required IOPS for the disk you should consider the VM limits that are tied to the VM size that you have selected. See [Ultra disk IOPS](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#ultra-disk-iops) for more information.
+           !!!important
+           While setting the required IOPS for the disk that you selected, consider the VM limits that are tied to the VM size that you have selected. See [Ultra disk IOPS](https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#ultra-disk-iops) for more information.
 
-    - For AWS, in **Volume Type** select either General Purpose SSD (GP3), io2, or io2 Block Express. 
+       - For AWS, in **Volume Type** select either **General Purpose SSD (GP3)**, **io2**, or **io2 Block Express**.
 
-      !!!Note
-         io2 Block Express is available for selected instance types (such as R5b). However, you cannot switch between io2 and io2 Block Express after creating your cluster.
+       !!!Note
+       io2 Block Express is available for selected instance types (such as R5b). However, you can't switch between io2 and io2 Block Express after creating your cluster.
+       !!!  
 
-    In **Volume Properties**, select the disk size for your cluster and configure the IOPS.
+        In **Volume Properties**, select the disk size for your cluster, and configure the IOPS.
 
+1.  In the **Connections** section, you can enable **Read-only Workloads**. This feature directs read-only operations exclusively toward replicas. If this option is enabled, you might have to raise the IP address resource limits for the cluster:
+
+      - For Azure, the IP address quota is Standard Public IP Address.
+
+      - For AWS, the IP address quota is Elastic IP. You might also have to increase the **Network Load Balancers per Region** value. 
+
+    When enabling read-only workloads, keep in mind the following:
+
+      - Read-only workloads are routed to Postgres physical standbys. Commands run on read-only workloads aren't filtered by BigAnimal. The connection is read-only because it runs on a standy replica where Postgres doesn't permit changes to the contents of database tables. A privileged connection to a standby replica can still execute other sensitive commands permitted by Postgres on standby replicas, like modify replication slots or Postgres configuration settings, terminate backends, see activity from other users, and more. We recommend that you use a Postgres role with minimal privileges for your application, even for read-only workloads.
+
+      - Advisory locks aren't replicated between Postgres nodes, so advisory locks taken on a standby replica don't conflict with advisory locks taken on the primary or another standby replica.  We recommend that applications that rely on advisory locking avoid using read-only workloads for those transactions.
+
+    For information on replication lag while using read-only workloads, see [Synchronous replication](/biganimal/latest/overview/02_high_availability/#synchronous-replication). 
+
 1.  In the **Networking Connectivity** section, you specify whether to use private or public networking. Networking is set to **Public** by default. Public means that any client can connect to your cluster’s public IP address over the internet. Optionally, you can limit traffic to your public cluster by specifying an IP allowlist, which allows access only to certain blocks of IP addresses. To limit access, add one or more classless inter-domain routing (CIDR) blocks in the **IP Allowlists** section. CIDR is a method for allocating IP addresses and IP routing to a whole network or subnet. If you have any CIDR block entries, access is limited to those IP addresses. If none are specified, all network traffic is allowed. 
 
     Private networking allows only IP addresses within your private network to connect to your cluster. See [Cluster networking architecture](01_cluster_networking) for more information.
+
 1.  To optionally make updates to your database configuration parameters, select **Next: DB Configuration**.
 
 ### DB Configuration tab

diff --git a/product_docs/docs/biganimal/release/overview/02_high_availability.mdx b/product_docs/docs/biganimal/release/overview/02_high_availability.mdx
@@ -32,6 +32,8 @@ In case of unrecoverable failure of the primary, a restore from a backup is requ
 
 The high availability option is provided to minimize downtime in cases of failures. High-availability clusters—one *primary* and one or two *standby replicas*—are configured automatically, with standby replicas staying up to date through physical streaming replication. 
 
+If read-only workloads are enabled, then standby replicas serve the read-only workoads. In a two-node cluster, the single standby replica serves read-only workloads. In a three-node cluster, both standby replicas serve read-only workloads. The connections are made to the two standby replicas randomly and on a per-connection basis. 
+
 In cloud regions with availability zones, clusters are provisioned across zones to provide fault tolerance in the face of a datacenter failure.
 
 In case of temporary or permanent unavailability of the primary, a standby replica becomes the primary.
@@ -49,6 +51,9 @@ In a cluster with one primary and one replica (a two-node high availability clus
 
 In PostgreSQL terms, `synchronous_commit` is set to `on` and `synchronous_standby_names` is set to `ANY 1 (replica-1, replica-2)`. You can modify this behavior on a per-transaction, per-session, per-user, or per-database basis with appropriate `SET` or `ALTER` commands. 
 
+To ensure write availability, BigAnimal disables synchronous replication during maintenance operations of a two-node cluster.
+
+Since BigAnimal replicates to only one node synchronously, some standby replicas in three-node clusters might experience replication lag. Also, if you override the BigAnimal synchronous replication configuration, then the standby replicas are inconsistent. 
 
 ## Extreme high availability (beta)
 

diff --git a/..._docs/docs/biganimal/release/using_cluster/02_connecting_your_cluster/index.mdx b/..._docs/docs/biganimal/release/using_cluster/02_connecting_your_cluster/index.mdx
@@ -35,7 +35,6 @@ You are connected to database "edb_admin" as user "edb_admin" on host "xxxxxxxxx
 SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
 ```
 
-
 ## Connect to your cluster using `psql`
 
 1.  Sign in to the [BigAnimal](https://portal.biganimal.com) portal.
@@ -48,7 +47,6 @@ SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, co
 
 5.  Paste the command in your terminal.
 
-
 ## Connect to your cluster using common database drivers
 
 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal.
@@ -123,7 +121,34 @@ Enter the values in pgAdmin:
 
 1. Select **Save**. pgAdmin attempts to connect to the BigAnimal cluster. 
 
+## Connect a read-only workload
+
+Clusters that are read-only enabled display separate connection strings for **Read-only** and **Read/write** access. 
+
+To connect to your cluster with the read-only workload:
+
+1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal.
+
+1. Go to [Clusters](https://portal.biganimal.com/clusters).
+
+1. Select the cluster you want to connect to.
+
+1. Select the **Connect** tab.
+
+1. Copy the **Read-only Service URI**.
+
+1. Use the **Read-only Service URI** to connect to the cluster according to your database driver.
+
+We recommend that your applications run `SET default_transaction_read_only = true` for all read-only activity. For a libpq driver, add `options='-c default_transaction_read_only=true'` to the database connection string. Other drivers use similiar connection parameters. Also, applications can run `BEGIN TRANSACTION READ ONLY` to mark individual transactions as read-only.
+
+!!!Note
+   On read-only workloads, BigAnimal might cancel long-running queries and display an error message like the following:
+
+   ```text
+   ERROR: canceling statement due to conflict with recovery
+   ```
 
+For more information on querying standby replicas, see the [PostgreSQL Hot Standby documentation](https://www.postgresql.org/docs/current/hot-standby.html).
 
 ## Setting up cloud infrastructure to connect to a private network cluster
 

diff --git a/...t_docs/docs/biganimal/release/using_cluster/03_modifying_your_cluster/index.mdx b/...t_docs/docs/biganimal/release/using_cluster/03_modifying_your_cluster/index.mdx
@@ -36,6 +36,7 @@ You can also modify your cluster by installing Postgres extensions. See [Postgre
  | Instance type                                        | Cluster Settings | Changing the instance type can incur higher cloud infrastructure charges.                                                                                                                                                                                                        |
  | Volume type                                          | Cluster Settings | You cannot switch between the io2 and io2 Block Express volume types in an AWS cluster.                                                                                                                                                                                          |
  | Volume properties                                    | Cluster Settings | It can take up to six hours to tune IOPS or resize the disks of your cluster because AWS requires a cool down period after volume modifications as explained in the [Limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/modify-volume-requirements.html) section. The volume properties are disabled and cannot be modified while this is in progress. |
+ | Read-only workloads                                  | Cluster Settings | Enabling read-only workloads can incur higher cloud infrastructure charges. |
  | Networking type (public or private)                  | Cluster Settings | If you are using Azure and previously setup a private link and want to  change to a public network, you must remove the private link resources  before making the change.                                                                                                        |
  | Database configuration parameters                    | DB Configuration | \-                                                                                                                                                                                                                                                                                 |
  | Retention period for backups                         | Backups          | \-                                                                                                                                                                                                                                                                                 |