docs: upstream

planetscale/www@472e674

docs/concepts/account-password-security.md

@@ -1,6 +1,6 @@
 ---
 title: 'Account password security'
-subtitle: 'Securing your Planetscale.com account password'
+subtitle: 'Securing your PlanetScale.com account password'
 date: '2022-08-01'
 ---
 

docs/concepts/billing.md

@@ -114,7 +114,7 @@ The `SELECT count(*)` query is a special case. The database engine optimizes thi
 
 With our in-dashboard [Insights tool](/docs/concepts/query-insights), you can explore active queries running against your database. The "**Queries during the last 24 hours**" list has a column that shows the total rows read for that particular query. The "rows read" surfaced here is the same number we use to calculate your total rows read for your billing calculation. In addition, you can click on a particular query to see more information about its performance.
 
-![PlanetScale Insights recent queries list](/assets/docs/concepts/query-insights/queries-2.png?v2)
+![PlanetScale Insights recent queries list](/assets/docs/concepts/query-insights/queries-2.jpg)
 
 If you'd prefer to test a query on your own, you can calculate the **approximate** rows read using the `EXPLAIN` statement. Running `EXPLAIN` with your query will return information about the query execution plan.
 

docs/concepts/connection-strings.md

@@ -1,14 +1,14 @@
 ---
 title: 'Connection strings'
 subtitle: 'Create reusable connection strings to connect to your PlanetScale database.'
-date: '2022-12-06'
+date: '2023-08-15'
 ---
 
 ## Creating a password
 
 1. To create a password, head to your database overview page at `https://app.planetscale.com/<ORGANIZATION>/<DATABASE_NAME>` and click on the "**Connect**" button.
 
-   ![Database overview page](/assets/docs/concepts/connection-strings/connect-2.png?v2)
+   ![Database overview page](/assets/docs/concepts/connection-strings/connect-2.png)
 
 2. On this dialog, click the `New password` button and you'll have the opportunity to select the branch to create a password for, pick a [password role](/docs/concepts/password-roles), and provide a recognizable name for the new credentials. Clicking `Create password` will then generate a **unique username and password pair** that can only be used to access the designated branch of your database. Take note of this password, as you won't be able to see it again.
 
@@ -21,7 +21,7 @@ suggestions. We support pre-generating connection strings for Go, Java, .Net, PH
 Rails, and Rust.
 {% /callout %}
 
-![Browse connection string in formats](/assets/docs/concepts/connection-strings/formats-2.png?v2)
+![Browse connection string in formats](/assets/docs/concepts/connection-strings/formats-2.png)
 
 {% callout type="tip" %}
 Make sure you copy the connection string for your application and the "General" format. We don't save the password in
@@ -36,7 +36,7 @@ Once you've created the password, you can head over to the "**Passwords**" setti
 You can also create passwords for branches other than `main` on this page.
 {% /callout %}
 
-![Manage passwords page](/assets/docs/concepts/connection-strings/manage-2.png?v2)
+![Manage passwords page](/assets/docs/concepts/connection-strings/manage-2.png)
 
 Clicking on the `...` icon on the row for your password allows you to pull up the connection string (except the password), rename it, or delete it.
 
@@ -66,6 +66,30 @@ For a list of tested MySQL GUI clients, review our article on [how to connect My
 PlanetScale Passwords are created for use with a single database branch.
 This strong security model allows you to generate passwords that are tied to a branch, and cannot access data/schema from another branch.
 
+## IP restrictions
+
+You can restrict database connections to specific IP ranges for a single password by updating its IP restrictions. This feature is currently in beta. For example, if you have a database for a web application and you create a password for use in the deployed application, you can restrict usage of that specific password to the IP ranges of the deployed application. If somebody attempts to connect to the database from outside of the deployed application, the connection will be refused. IP restrictions work on a per-password basis, so if you want to use the same restriction across passwords, they must be applied to each password separately.
+
+Some passwords are incompatible with IP restrictions, and you will need to create a new password to use IP restrictions.
+
+Examples of when you may want to use IP restrictions:
+
+- You want to segment database access so that the production database can only be connected to from production environments or development branches.
+- You use a bastion in production and want to ensure that all database connections originate or pass through the bastion.
+- You want to allow a single client to be able to access your database (e.g., for debugging) and want to provide the least amount of access for them to do so.
+- You have compliance requirements that require implementing a more stringent access control list in your database.
+
+### Updating the IP restrictions for a password
+
+1. Go to your database's "**Settings**" tab.
+2. Click "**Passwords**."
+3. You can update the IP restrictions for a password in two different ways: The first way is by opening the dropdown menu to the right of any password on the Passwords page and clicking "**Manage IP restrictions**." The second way is by clicking on the password and scrolling to the bottom of its page to update IP restrictions.
+4. Add the IP ranges that you want to allow to connect using the selected password.
+
+{% callout %}
+If your password has no IP restrictions, it is set to **allow all traffic**. Similarly, when you add a new IP range to the restrictions, all IP addresses out of this range cannot connect to your database using that password.
+{% /callout %}
+
 ## Disconnect clients by deleting passwords
 
 PlanetScale automatically disconnects clients that are using a deleted password.

docs/concepts/data-branching.md

@@ -33,7 +33,7 @@ Before you can use the feature, you have to enable it in your database settings
    - **None** — Creates a database branch with only the **schema** copied to the new branch.
    - **From most recent backup** — Creates a database branch with both the **schema and data** from the latest backup of the Base branch.
 
-   ![PlanetScale dashboard new branch dialog with seed option](/assets/docs/concepts/data-branching/branch.png)
+   ![PlanetScale dashboard new branch dialog with seed option](/assets/docs/concepts/data-branching/branch.jpg)
 
 3. Once you've selected an option, click "**Create branch**" to create a new branch.
 

docs/concepts/database-sleeping.md

@@ -46,7 +46,7 @@ Because database sleeping only applies to databases on the free Hobby plan, anot
 
 Once your database is sleeping, you can wake it in your PlanetScale dashboard.
 
-![PlanetScale dashboard database page - Sleeping database](/assets/docs/concepts/database-sleeping/database-2.png?v2)
+![PlanetScale dashboard database page - Sleeping database](/assets/docs/concepts/database-sleeping/database-2.png)
 
 ### Steps to wake a sleeping database:
 

docs/concepts/deploy-requests.md

@@ -1,7 +1,7 @@
 ---
 title: 'Deploy requests'
 subtitle: 'Learn how to create and revert non-blocking schema changes with PlanetScale deploy requests.'
-date: '2023-04-05'
+date: '2023-08-18'
 ---
 
 ## Overview
@@ -12,7 +12,9 @@ Deploy requests are an integral part of the [PlanetScale workflow](/docs/concept
 
 ## Create a deploy request
 
-**Note**: Your database must have a **production branch with [safe migrations](/docs/concepts/safe-migrations) enabled** before you can create a deploy request.
+{% callout %}
+Your database must have a **production branch with [safe migrations](/docs/concepts/safe-migrations) enabled** before you can create a deploy request.
+{% /callout %}
 
 1. Click on "**Branches**".
 2. Select the development branch you want to deploy to the production branch.
@@ -22,7 +24,7 @@ Deploy requests are an integral part of the [PlanetScale workflow](/docs/concept
 6. Optionally, add a comment about the deploy request.
 7. Click "**Create deploy request**".
 
-![Example of deploy request on branch page](/assets/docs/concepts/deploy-requests/deploy-request-page-2.png?v2)
+![Example of deploy request on branch page](/assets/docs/concepts/deploy-requests/deploy-request-page-2.png)
 
 ## Review and deploy a deploy request
 
@@ -37,7 +39,7 @@ PlanetScale will check if the request is deployable. This process includes check
 5. You'll see the proposed changes here. New additions are highlighted in green, and deletions are highlighted in red.
 6. If you have required deploy requests to be approved before deployment, other users in your Organization will see the option to "**Approve changes**" or "**Leave a comment**" on the "**Schema changes**" tab.
 
-   ![PlanetScale deploy request - approve changes](/assets/docs/concepts/deploy-requests/approve-2.png?v2)
+   ![PlanetScale deploy request - approve changes](/assets/docs/concepts/deploy-requests/approve-2.png)
 
 7. Once the request is approved, if required, it's ready to be added to the deploy queue. Click on the "Summary" tab, and you'll see the option to deploy.
 8. Here, you also have the option to enable [**Gated Deployments**](#gated-deployments), which gives you the power to control exactly when the migration cuts over. You'll see an "**Auto-apply changes**" checkbox, which is checked by default. If you uncheck this, you will get the option to apply the changes once the schema changes are complete. If you leave it checked, it will auto-deploy as soon as it's ready.
@@ -59,25 +61,17 @@ If you decide you don't want to proceed with a deploy request, you can easily cl
 
 If you ever merge a deploy request, only to realize you need to undo it, PlanetScale can handle that! You have the option to revert a recently deployed schema change while maintaining data that was written to the original schema during that time.
 
-{% callout %}
-The schema revert feature is currently in limited beta. You must enroll your database and opt-in to the terms to access this
-feature.
-{% /callout %}
-
 ### How to revert a schema change
 
 You can revert a deployment for **up to 30 minutes** after the deploying. After the 30 minute period is up, the deployment becomes permanent, and you will no longer have the option to revert.
 
-You must first agree to the beta terms before you can use the schema revert feature. Go to the database Settings page, click "**Beta features**", find the "**Revert schema changes**" section, and click "**Enroll**" to opt-in.
-
 {% vimeo src="https://player.vimeo.com/video/830571822" caption="Demonstration of how to revert a schema change" /%}
 
 1. Select the deploy request you want to revert.
-2. If you're not already enrolled, you'll see a Beta banner underneath the comment box on the deploy request page. Click "**Enroll database**" to opt-in to the limited beta terms.
-3. To revert the schema changes made with the deploy request, click "**Revert changes**" and confirm.
-4. We will immediately revert your production database back to its previous schema.
-5. Any data that was written to the original schema in the time between deploying and reverting will remain in your database after the revert.
-6. The Deploy Request will be closed, but the branch will remain for you to continue development on if you choose.
+2. To revert the schema changes made with the deploy request, click "**Revert changes**" and confirm.
+3. We will immediately revert your production database back to its previous schema.
+4. Any data that was written to the original schema in the time between deploying and reverting will remain in your database after the revert.
+5. The Deploy Request will be closed, but the branch will remain for you to continue development on if you choose.
 
 ### When is data not retained
 
@@ -121,12 +115,12 @@ This feature is helpful if you have long-running migrations. For very large or c
 
 1. When you open a deploy request, uncheck the "**Auto-apply changes**" box.
 
-   ![PlanetScale deploy request - Auto-apply changes checkbox unchecked](/assets/docs/concepts/deploy-requests/gated-deployments-2.png?v2)
+   ![PlanetScale deploy request - Auto-apply changes checkbox unchecked](/assets/docs/concepts/deploy-requests/gated-deployments-2.png)
 
 2. Once your deploy requests begins running, you'll also have the option to uncheck the box here.
 3. When your deploy request has completed and is ready for cutover, the "**Apply changes**" button will appear. You can now complete the deployment at any time by clicking this button.
 
-![PlanetScale deploy request - Apply changes from deployment button](/assets/docs/concepts/deploy-requests/apply-changes-2.png?v2)
+![PlanetScale deploy request - Apply changes from deployment button](/assets/docs/concepts/deploy-requests/apply-changes-2.png)
 
 {% callout %}
 If you have an open Gated Deployment, you cannot deploy another deploy request until the current one has been merged in.

docs/concepts/deployment-options.md

@@ -15,7 +15,7 @@ Your deployment options depend on the [PlanetScale plan](/docs/concepts/planetsc
 
 ## Multi-tenancy deployment on PlanetScale
 
-Multi-tenancy is the default deployment option. When you sign up for a PlanetScale account, whether on a Hobby, Scaler, or Team plan, your databases will be created in our multi-tenancy deployment offering. Our Enterprise plan also offers a multi-tenancy deployment option.
+Multi-tenancy is the default deployment option. When you sign up for a PlanetScale account, whether on a Hobby, Scaler, or Scaler Pro plan, your databases will be created in our multi-tenancy deployment offering. Our Enterprise plan also offers a multi-tenancy deployment option.
 
 ### Multi-tenancy highlights
 

docs/concepts/how-to-use-planetscale-boost.md

@@ -22,7 +22,7 @@ Before you can use PlanetScale Boost, you must select a cache size. Cache sizes
 | 8 GB       | 32 queries         |
 
 {% callout %}
-If you need a cache size greater than 8 GB, please [contact our support team](/support).
+If you need a cache size greater than 8 GB, please [contact our support team](https://support.planetscale.com).
 {% /callout %}
 
 To select a cache size, navigate to the "**Boost**" tab in the PlanetScale console and click "**Add a query cache**". A modal will appear asking you to select your desired cache size. Once you've selected the cache size needed for your application, click "**Add cache size**" to enable it.

docs/concepts/network-latency.md

@@ -0,0 +1,88 @@
+---
+title: 'Network latency'
+subtitle: 'Learn how network latency can impact query speed.'
+date: '2023-08-31'
+---
+
+## Overview
+
+When connecting to PlanetScale, it's important to understand how network latency can impact query speed.
+
+## What is network latency, and why is it important?
+
+Network latency is the time it takes for data to travel across a network between your application and your database. Minimizing network latency for databases is critical because it adds additional time to your application's queries.
+
+One of the primary causes of network latency is the distance between two endpoints. For example, if an application is hosted in Virginia and is communicating to a database in Paris, each query will spend around 80ms traveling between the two servers. For an application that does many queries, this network time adds up quickly and can greatly impact the application's performance.
+
+### Network latency and serverless applications
+
+In traditional applications, a single region hosts both the application and database. With these both collocated in the same region, network latency is minimized. For serverless or "edge" deployment models, this can become more complex. In these scenarios, the application is often deployed to several different regions while the primary database remains in a single region. This can result in high network latency between the application and database.
+
+When looking at network latency, there are two important dimensions to consider. First, the **distance between the application and PlanetScale's edge network**. And second, the **distance between the edge and the database**.
+
+While there is no solution to completely eliminating latency, the path the connection takes over the internet can be optimized for these serverless applications. PlanetScale does this by connecting to the nearest edge location and having the traffic backhauled via PlanetScale's network rather than traversing the public internet.
+
+For example, consider an application running in `us-east` that is connecting to a database in `eu-west`. This example is not optimized, and traffic is directed over public internet until it connects to PlanetScale's edge in `eu-west` before being directed to the database.
+
+```
+<client (us-east)> <-------> <edge (eu-west)> <-> <database (eu-west)>
+```
+
+The following example shows a more optimal traffic path. The application connects to PlanetScale's edge, and then the traffic is sent over PlanetScale's network to the database. This minimizes the time spent traversing the public internet.
+
+```
+<client (us-east)> <-> <edge (us-east)> <------> <database (eu-west)>
+```
+
+## How to tell if network latency is impacting my application
+
+When experiencing slow query times, it's important to rule out any potential networking issues. First, you need to be able to measure the time your application is spending waiting on the query. The best sources of this data are application performance monitoring (APM) services or query-level logging from your application. Since applications can be complex and many different factors can influence a performance problem, it's important to isolate and measure only the time spent on the query from the application's perspective.
+
+Once you have a measurement of the query in your application, you can then compare the query to the data in [Query Insights](/docs/concepts/query-insights). The difference between the numbers can give you an idea of how much time was spent transferring the data across the network. If you see a large difference, it is likely due to network latency between the application and database.
+
+If you can access your application's host machine, you can also use netcat` to understand the latency between the host and PlanetScale.
+
+```shell
+time nc -z aws.connect.psdb.cloud 3306
+
+Connection to aws.connect.psdb.cloud port 3306 [tcp/mysql] succeeded!
+nc -z aws.connect.psdb.cloud 3306  0.01s user 0.00s system 24% cpu 0.044 total
+```
+
+In this example, you can see establishing a connection took 44ms.
+
+## PlanetScale hostnames
+
+When connecting to PlanetScale, you have the option of two different hostnames: optimized or direct. For almost every case, we recommend using the optimized hostname. But there are some circumstances where using the direct hostname may work better for your application.
+
+{% callout type="note" %}
+This does not apply to PlanetScale Managed and single-tenant customers who have a single hostname for their account.
+{% /callout %}
+
+## Optimized hostname
+
+PlanetScale's optimized hostname uses Route 53's [latency-based](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy-latency.html) routing to connect to the closest edge in PlanetScale's network. Using this hostname optimizes latency and improves reliability as it can route around regional network outages.
+
+Examples of optimized hostnames:
+- `aws.connect.psdb.cloud`
+- `gcp.connect.psdb.cloud`
+
+We recommend everyone use this hostname by default as it provides the best connection in most cases.
+
+## Direct hostname
+
+In some rare cases, we have found that PlanetScale's optimized hostname may not direct traffic along the most optimal path. If you are experiencing this, one solution is using
+the direct hostname. We only recommend using this if your application and database are in the same region and you have confirmed the optimized hostname is directing traffic incorrectly.
+
+To test if the direct hostname is better for your application, you can compare it to the optimized hostname by running `netcat` from your application's host machine.
+
+```shell
+time nc -z us-east.connect.psdb.cloud 3306
+
+Connection to us-east.connect.psdb.cloud port 3306 [tcp/mysql] succeeded!
+nc -z us-east.connect.psdb.cloud 3306  0.01s user 0.00s system 26% cpu 0.037 total
+```
+
+{% callout type="note" %}
+If you have latency issues with the optimized hostname, we'd appreciate [hearing about your experience](https://support.planetscale.com/hc/en-us/requests/new) so that we can improve.
+{% /callout %}