docs: upstream

planetscale/www@d7bf6b4

docs/concepts/connection-strings.md

@@ -13,7 +13,7 @@ date: '2023-08-15'
 3. Once created, you can browse the connection string in different framework formats by selecting framework in the "Select your language or framework" section. This will also show you all of the files you need to modify to get connected with PlanetScale in your framework or language of choice.
 
 {% callout %}
-You can connect to PlanetScale from any platform that supports MySQL. These connection strings are in place to let you hit the ground running. We support generating connection strings for Go, Java, .NET, PHP, Laravel, Symfony, Prisma, Python, Rails, Rust, and more. Please let us know if we're missing your favorite framework in this list or if you have any suggestions.
+There are two connection types for a password: `Primary` and `Replica`. The `Primary` connection type is used to connect to the primary region of your database, while the `Replica` connection type is used to route queries to your branch's replicas and read-only regions. You can create multiple passwords for a branch, each with a different connection type. [Read more about replicas](/docs/concepts/replicas).
 {% /callout %}
 
 {% callout type="tip" %}

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-10-25'
+date: '2024-04-17'
 ---
 
 ## Overview
@@ -17,27 +17,27 @@ This feature supports globally distributed applications by enabling your databas
 3. Click the "**Add region**" button.
 4. Select the desired AWS region from the dropdown of [available regions](/docs/concepts/regions).
 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**".
 
-Once you delete a region, you will no longer be charged for the storage or row reads associated with that region.
+Once you delete a region, you will no longer be charged for the storage or row reads associated with that region. If you were using global replica credentials, you do not need to take any additional action. Read queries will still be sent to the closest replica for any queries that are using global replica credentials.
 
 ## How to query a read-only region
 
-Connecting to a read-only region requires using a separate connection string from your primary region.
+Connecting to a read-only region requires using a [replica credential](/docs/concepts/replicas). You can create a global replica credential by following these steps:
 
 1. Go to your database's production branch.
-2. Click on the "**...**" at the top right of the region that you want to connect to.
-3. Click "**Connect**".
+2. Click on the "Connect" button in the top right
+3. On the "Connect" page, select "Replica" as the connection type.
+4. Click "Create password" to generate a new username and password pair.
 
 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.
+All queries made using this password will be routed to your branch's replicas or the nearest read-only region. If you want to route queries to a specific read-only region, you can go to the "**Passwords**" page within your database's settings page and select the created password. Under "**Database endpoint**", you can then select "**Direct**" and choose your desired host from the "**Host**" dropdown.
 
 ## Concepts
 

docs/concepts/replicas.md

@@ -1,7 +1,7 @@
 ---
 title: 'Database replicas'
 subtitle: 'Understand how replicas optimize and protect your PlanetScale database.'
-date: '2023-07-06'
+date: '2024-04-17'
 ---
 
 ## Overview
@@ -11,41 +11,51 @@ 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.
 
+{% callout type="warning" %}
+Before utilizing replicas for reducing load on the primary, it's important to understand the trade-offs. For more information, see the [Data consistency and replication lag](#data-consistency-and-replication-lag) section.
+{% /callout %}
+
 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.
+PlanetScale replicas can be used to read data and reduce load on the primary. PlanetScale does not automatically route queries to replicas unless you explicitly use a replica credential or tell your application to do so.
 
-There are two ways to query replicas in your primary region.
+### 1. Create a global replica credential (recommended)
 
-### 1. `USE @replica`
+With global replica credentials, you can have one credential that will automatically route queries to your branch's replicas and read-only regions. If you do not have any read-only regions, it will route to the included replicas on [your plan](/docs/concepts/planetscale-plans) (minimum of 2). If you do have any read-only regions, the queries will route to the closest replica out of your read-only region replicas and included failover replicas.
 
-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:
+To use this, create a new credential in the PlanetScale dashboard and select "**Replica**" as the connection type. You can then use the new credential's connection string to setup a replica-only database
+connection.
 
-```sql
-USE @replica
+If you have `pscale` installed locally, you can create a replica credential with the following command:
+
+```shell
+pscale password create <database> <branch> --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.
+All queries made using this credential will be routed to the nearest replica, even as you add and remove read-only regions.
 
-### 2. Append `@replica` to the database name
+### 2. `USE @replica` (not recommended)
 
-To direct all queries to a replica, you can add `@replica` to the database name in your connection string.
+{% callout type="warning" %}
+We do not recommend using this method to query replicas. We will soon be deprecating this method, but we will maintain the documentation until a deprecation date has been set. If you are currently using this method, we recommend switching to method 1.
+{% /callout %}
 
-**MySQL CLI example:**
+If you are not using a global replica credential, then, 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:
 
-```shell
-mysql -h aws.connect.psdb.cloud -D my-db-name@replica -u username -p password
+```sql
+USE @replica
 ```
 
-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.
+Once this command is run, all subsequent `SELECT` queries on that connection will be served by your branch's replicas instead of the primary node in your cluster. Please note that this does not send queries to any read-only regions, if you want to route queries all replicas, including read-only regions, you should use a global replica credential (method 1 above).
 
 {% callout type="tip" %}
 For querying replicas in separate regions, see: [Read-only regions](/docs/concepts/read-only-regions).
 {% /callout %}
 
+We highly recommend using a global replica credential to ensure that your queries are always routed to the nearest replica.
+
 ## High availability
 
 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.
@@ -60,15 +70,19 @@ Whenever data is updated (`INSERT`, `UPDATE`, `DELETE`) on the primary node, tho
 
 It is important to be aware of replication lag whenever querying data from your replicas. For example, if you make an update and then immediately try to query for that updated data via a replica, it may not be available yet due to replication lag.
 
+## When should you use replicas in your application?
+
+Replicas are useful for offloading read-heavy workloads from the primary node. By using replicas, you can distribute the read load across multiple nodes, which can help improve the performance of your application. Some examples of where you might want to query a replica are scheduled jobs, analytics jobs, search features, or aggregate queries. Replicas can also be used to provide a read-only view of your data to users or applications that do not need to write data, such as when a user is logged out or writing one-off queries for debugging purposes.
+
 ## When are replicas used in PlanetScale?
 
 We use replicas for every production database branch. The number of replicas for a given database depends on the selected plan for that database:
 
-- **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.
+- **Scaler Pro** &mdash; Scaler Pro databases include 2 replicas per production branch distributed across multiple AZs in a given region.
+- **Enterprise** &mdash; 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 intended only for reading data and are not eligible for failover if the primary node experiences an outage.
 
 {% callout type="warning" %}
-⚠️ Development branches DO NOT have replicas as they are intended for development only 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 %}

docs/concepts/what-is-planetscale.md

@@ -115,11 +115,15 @@ The API is useful for building PlanetScale into other developer tooling for fast
 
 See the [PlanetScale API reference](https://api-docs.planetscale.com) for more information.
 
+### Replicas
+
+Every production PlanetScale branch comes with two [replicas](/docs/concepts/replicas). Replicas are read-only copies of your database that can be used to offload read traffic from your primary. With global replica credentials, you can have one credential that will automatically route queries to your branch's replicas and read-only regions.
+
 ### Read-only regions
 
-Spin up [read-only regions](/docs/concepts/read-only-regions) with the click of a button. For globally distributed applications, it's important to serve your users as close as possible to their location to prevent high read latency.
+Spin up [read-only regions](/docs/concepts/read-only-regions) with the click of a button. For globally distributed applications, read-only regions allow you to place a copy of your data close to your users.
 
-You don't have to worry about complicated replication strategies or manually setting this up on your own. Just go to the dashboard, add a new read-only region, copy the connection string, and add it to your application.
+To query your read-only region, create [a replica credential](/docs/concepts/replicas) for your database. Replica queries will be automatically routed to the nearest read-only region or one of the branch's replicas, whichever has the lowest latency available.
 
 ## Get in touch