docs: upstream

planetscale/www@1f07150

docs/concepts/read-only-regions.md

@@ -1,7 +1,7 @@
 ---
 title: 'Read-only regions'
 subtitle: 'Add additional read-only regions to your production database.'
-date: '2023-05-03'
+date: '2023-10-25'
 ---
 
 ## Overview
@@ -15,20 +15,30 @@ This feature supports globally distributed applications by enabling your databas
 1. In the [PlanetScale dashboard](https://app.planetscale.com), select the database you want to add a read-only region to.
 2. Click on the production branch.
 3. Click the "**Add region**" button.
-   ![Add read-only region on production branch {priority}](/assets/docs/concepts/read-only-regions/branch-2.jpg)
 4. Select the desired AWS region from the dropdown of [available regions](/docs/concepts/regions).
-   ![Select read-only region on production branch](/assets/docs/concepts/read-only-regions/form.png)
 5. Click "**Add region**" and wait for your data to finish initially replicating across regions.
 6. Optionally, create credentials for your new read-only region by clicking the ellipsis and selecting "**Connect**". The credentials can only be used to connect to this read-only region. Any additional read-only regions will require their own credentials.
 
 ## How to remove a read-only region
 
 1. Go to your database's production branch.
-2. Click on the "..." at the top right of the region that you want to delete.
-3. Click "Delete region".
+2. Click on the "**...**" at the top right of the region that you want to delete.
+3. Click "**Delete region**".
 
 Once you delete a region, you will no longer be charged for the storage or row reads associated with that region.
 
+## How to query a read-only region
+
+Connecting to a read-only region requires using a separate connection string from your primary region.
+
+1. Go to your database's production branch.
+2. Click on the "**...**" at the top right of the region that you want to delete.
+3. Click "**Connect**".
+
+Alternatively, you can create a connection string by going to your database settings page > "**Passwords**" > "**New password**".
+
+All queries made over this connection will be routed to the read-only region.
+
 ## Concepts
 
 ### Replication across regions

docs/concepts/replicas.md

@@ -11,9 +11,44 @@ A replica is a continuously updated copy of your database. Replicas serve two ma
 - They provide an additional source for your data to be queried.
 - They increase database availability by enabling fast failovers for maintenance or unexpected failure.
 
+For information on replicas running in additional regions, see: [Read-only regions](/docs/concepts/read-only-regions).
+
+## How to query replicas
+
+PlanetScale replicas can be used to read data and reduce load on the primary. PlanetScale does not automatically route queries to replicas without your application
+telling it to.
+
+There are two ways to query replicas in your primary region.
+
+### 1. `USE @replica`
+
+By default, all queries are served by the primary, however you may route any `SELECT` queries to replicas by issuing the following command on a connection:
+
+```sql
+USE @replica
+```
+
+Once this command is run, all subsequent `SELECT` queries on that connection will be served by your read-only replicas instead of the primary node in your cluster.
+
+### 2. Append `@replica` to the database name
+
+To direct all queries to a replica, you can add `@replica` to the database name in your connection string.
+
+**MySQL CLI example:**
+
+```shell
+mysql -h aws.connect.psdb.cloud -D my-db-name@replica -u username -p password
+```
+
+This will direct all queries on the connection to one of your read-only replicas. Note: Using `my-db-name@replica` with database-js is currently not supported.
+
+{% callout type="tip" %}
+For querying replicas in separate regions, see: [Read-only regions](/docs/concepts/read-only-regions).
+{% /callout %}
+
 ## High availability
 
-Replicas within PlanetScale are used to enable high availability of your database. This is the primary reasons all production branches in PlanetScale are provided at least one replica. In situations where the underlying hardware or service hosting the primary MySQL node fails, our system will automatically elect a new primary node from the available replicas and reroute traffic to that new primary.
+Replicas within PlanetScale are used to enable high availability of your database. This is the primary reason all production branches in PlanetScale are provided at least one replica. In situations where the underlying hardware or service hosting the primary MySQL node fails, our system will automatically elect a new primary node from the available replicas and reroute traffic to that new primary.
 
 ## Multiple availability zones
 
@@ -33,34 +68,8 @@ We use replicas for every production database branch. The number of replicas for
 - **Scaler Pro** — Scaler Pro databases include 2 replicas per production branch distributed across multiple AZs in a given region.
 - **Enterprise** — The Enterprise plan is customizable to fit the needs of your organization, and as such can have as many replicas as needed.
 
-[Read only regions](/docs/concepts/read-only-regions) use the same replica configuration as their respective database, they are just hosted in a different geographical region. It is important to note that the MySQL nodes in read only regions are replicas intedned only for reading data and are not eligible for failover if the primary node experiences an outage.
+[Read-only regions](/docs/concepts/read-only-regions) use the same replica configuration as their respective database, they are just hosted in a different geographical region. It is important to note that the MySQL nodes in read-only regions are replicas intedned only for reading data and are not eligible for failover if the primary node experiences an outage.
 
 {% callout type="warning" %}
-⚠️ Development branches DO NOT use replicas as they are intended for building new features or experimenting with development and are not designed with the same resiliency as production branches.
+⚠️ Development branches DO NOT have replicas as they are intended for development only and are not designed with the same resiliency as production branches.
 {% /callout %}
-
-## How to use replicas in your PlanetScale database
-
-PlanetScale replicas can be used to read data and reduce load on the primary. There are two ways to do this.
-
-### 1. `USE @replica`
-
-By default, all queries are served by the primary, however you may route any `SELECT` queries to replicas by issuing the following command on a connection:
-
-```sql
-USE @replica
-```
-
-Once this command is run, all subsequent `SELECT` queries on that connection will be served by your read-only replicas instead of the primary node in your cluster.
-
-### 2. Append `@replica` to the database name
-
-To direct all queries to a replica, you can add `@replica` to the database name in your connection string.
-
-**MySQL CLI example:**
-
-```
-mysql -h aws.connect.psdb.cloud -D my-db-name@replica -u username -p password
-```
-
-This will direct all queries on the connection to one of your read-only replicas.