docs: upstream

planetscale/www-2024@59a6387
planetscale · Nov 7, 2024 · f3bf680 · f3bf680
1 parent 04c1cf6
commit f3bf680
Show file tree

Hide file tree

Showing 20 changed files with 977 additions and 459 deletions.
diff --git a/docs/concepts/access-control.md b/docs/concepts/access-control.md
@@ -58,6 +58,7 @@ The following table describes permissions assigned at the organization level for
 | Connect to production branches         | Create passwords or use pscale shell for production branches                   |        | ✔            |
 | Delete production branches             | Delete a production database branch                                            |        | ✔            |
 | Promote branches                       | Promote a branch to production                                                 |        | ✔            |
+| Modify VSchema                         | Edit the VSchema of a keyspace                                                 |        | ✔            |
 | Manage databases                       | Delete, update settings, or import a database                                  |        | ✔            |
 | Manage beta features                   | Opt-in or opt-out of a beta feature                                            |        | ✔            |
 | Create production service token grants | Create a service token grant to connect or delete a production database branch |        | ✔            |

diff --git a/docs/concepts/cluster-configuration.md b/docs/concepts/cluster-configuration.md
@@ -1,7 +1,7 @@
 ---
 title: 'Cluster configuration'
 subtitle: 'Create and manage sharded and unsharded keyspaces for your database.'
-date: '2024-09-20'
+date: '2024-11-07'
 ---
 
 {% callout type="warning" %}
@@ -23,15 +23,11 @@ These are advanced configuration settings that expose some of the underlying Vit
 
 This documentation will cover how to use everything in this cluster configuration page. For a full walkthrough with an example of setting up a sharded keyspace, refer to the [Sharding quickstart](/docs/sharding/sharding-quickstart).
 
-## Limitations
-
-Before you adjust any cluster configuration settings, it is important that you read through the following limitations:
-
-- This feature can currently only be used to shard **new** tables.
-- If you are an existing PlanetScale customer with already sharded tables, you can use the Cluster configuration settings to adjust the instance size, number of replicas, and VSchema for **already sharded tables**.
-- Sharded keyspaces are not currently supported on databases that have foreign key constraints enabled.
+{% callout type="note" %}
+harded keyspaces are not currently supported on databases that have foreign key constraints enabled.
+{% /callout %}
 
-If you have existing tables that need sharding, or if you would like additional support from our expert team, our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan) may be a good fit. [Get in touch](/contact) for a quick assessment.
+If you would like additional support from our expert team, our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan) may be a good fit. [Get in touch](/contact) for a quick assessment.
 
 ## Create a keyspace
 
@@ -41,8 +37,8 @@ To create a new [keyspace](/docs/sharding/keyspaces):
 2. Click "Cluster configuration" in the left nav.
 3. You should see the existing unsharded keyspace for your database here.
 4. Click "New keyspace".
-5. Enter the keyspace name. For example, if your existing unsharded keyspace is named `books`, you may create a sharded keyspace named `books-sharded`.
-6. Select whether you want to keep it unsharded, or, if not, select the number of shards you want to exist in this keyspace. In most cases, you will be adding a new sharded keyspace. Adding a new unsharded keyspace is not a common use case.
+5. Enter the keyspace name. For example, if your existing unsharded keyspace is named `metal`, you may create a sharded keyspace named `metal-sharded`.
+6. Select whether you want to keep it unsharded, or, if not, select the number of shards you want to exist in this keyspace. In most cases, you will be adding a new sharded keyspace. Adding a new unsharded keyspace is not a common use case, but is an option if you're looking to do [vertical sharding](/learn/courses/database-scaling/sharding/vertical-sharding).
 
 {% callout type="note" %}
 The cost of adding this additional keyspace largely depends on the number of shards you choose, the cluster size, and if you'd like to add additional replicas.

diff --git a/docs/concepts/cluster-sizing.md b/docs/concepts/cluster-sizing.md
@@ -42,5 +42,6 @@ When you choose to change cluster size, we upgrade each of your replicas one by
 
 ## Sharding
 
-If you are an Enterprise customer, another way you can scale your database is with **sharding**.
-Check out our [sharding documentation](/docs/sharding/overview) for more information.
+You can create sharded keyspaces on any plan by adding a new sharded keyspace using the [cluster configuration page](/docs/concepts/cluster-configuration) and running an [unsharded to sharded workflow](/docs/sharding/sharding-quickstart) in your dashboard.
+
+If you would like additional support from our expert team, our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan) may be a good fit. [Get in touch](/contact) for a quick assessment.
diff --git a/docs/concepts/planetscale-plans.md b/docs/concepts/planetscale-plans.md
@@ -43,29 +43,29 @@ Cluster size options are capped at `PS-400` until you have a successfully paid $
 
 On top of processing and memory, all **Scaler Pro** cluster sizes share the following:
 
-|                                                             | **Scaler Pro**                                                     |
-| ----------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Storage/month**                                           | 10 GB included; $0.50 per instance per additional 1 GB\*           |
-| **Row reads/month**                                         | _Unmetered_                                                        |
-| **Row writes/month**                                        | _Unmetered_                                                        |
-| **Available cluster sizes**                                 | 17                                                                 |
-| **Availability zones**                                      | 3                                                                  |
-| **Production branches**                                     | 1 included\*\*                                                     |
-| **Development branches**                                    | ~1,440 hours included (2× hours of current month)                  |
-| **Concurrent Connections**                                  | _Unmetered_                                                        |
-| **Query Insights retention**                                | 7 days                                                             |
-| **Horizontal sharding**                                     | [Supported for _new_ tables](/docs/concepts/cluster-configuration) |
-| [**Deployment options**](/docs/concepts/deployment-options) | Multi-tenant                                                       |
-| **Read-only regions**                                       | Available as an add-on                                             |
-| **Web console**                                             | Included                                                           |
-| **PlanetScale CLI**                                         | Included                                                           |
-| **SSO**                                                     | Available as an add-on\*\*\*                                       |
-| **Audit log retention**                                     | 6 months                                                           |
-| **Private connections**                                     | [Configurable](/docs/concepts/private-connections)                 |
-| **BAAs**                                                    | Available for an additional fee                                    |
-| **Automatic backups**                                       | Every 12 hours                                                     |
-| **Support**                                                 | Standard, upgrade available\*\*\*                                  |
-| [**Data Branching®**](/docs/concepts/data-branching)       | Included                                                           |
+|                                                             | **Scaler Pro**                                           |
+| ----------------------------------------------------------- | -------------------------------------------------------- |
+| **Storage/month**                                           | 10 GB included; $0.50 per instance per additional 1 GB\* |
+| **Row reads/month**                                         | _Unmetered_                                              |
+| **Row writes/month**                                        | _Unmetered_                                              |
+| **Available cluster sizes**                                 | 17                                                       |
+| **Availability zones**                                      | 3                                                        |
+| **Production branches**                                     | 1 included\*\*                                           |
+| **Development branches**                                    | ~1,440 hours included (2× hours of current month)        |
+| **Concurrent Connections**                                  | _Unmetered_                                              |
+| **Query Insights retention**                                | 7 days                                                   |
+| **Horizontal sharding**                                     | Included                                                 |
+| [**Deployment options**](/docs/concepts/deployment-options) | Multi-tenant                                             |
+| **Read-only regions**                                       | Available as an add-on                                   |
+| **Web console**                                             | Included                                                 |
+| **PlanetScale CLI**                                         | Included                                                 |
+| **SSO**                                                     | Available as an add-on\*\*\*                             |
+| **Audit log retention**                                     | 6 months                                                 |
+| **Private connections**                                     | [Configurable](/docs/concepts/private-connections)       |
+| **BAAs**                                                    | Available for an additional fee                          |
+| **Automatic backups**                                       | Every 12 hours                                           |
+| **Support**                                                 | Standard, upgrade available\*\*\*                        |
+| [**Data Branching®**](/docs/concepts/data-branching)       | Included                                                 |
 
 \* Production branch storage is billed at $1.50 (1 primary + 2 replicas) and development branch storage is billed at $0.50 (1 primary).
 

diff --git a/docs/concepts/what-is-planetscale.md b/docs/concepts/what-is-planetscale.md
@@ -62,7 +62,7 @@ PlanetScale allows you to break up a monolithic database and partition the data
 
 Another scenario that companies with massive databases often run into is connection limits due to MySQL. With PlanetScale, we can support [nearly infinite connections](/blog/one-million-connections). Vitess offers built-in [connection pooling](https://vitess.io/docs/reference/features/connection-pools/), and we've built our own [edge infrastructure](/blog/introducing-the-planetscale-serverless-driver-for-javascript) into PlanetScale to ensure connection limits are never an issue.
 
-We generally recommend exploring horizontal sharding when your database exceeds 250 GB of data and you are beginning to feel some of the [pains associated with large scale](/blog/how-to-scale-your-database-and-when-to-shard-mysql). [Sharding](/docs/concepts/cluster-configuration) is offered on our Scaler Pro plan (currently only supported for new tables). If you need assistance with with setting up horizontal sharding, migrating to PlanetScale, or want enterprise-level SLAs, we offer this through our [Enterprise plan](/enterprise) option. [Please reach out](/contact) for more information.
+We generally recommend exploring horizontal sharding when your database exceeds 250 GB of data and you are beginning to feel some of the [pains associated with large scale](/blog/how-to-scale-your-database-and-when-to-shard-mysql). [Sharding](/docs/concepts/cluster-configuration) is offered on our Scaler Pro plan. If you need assistance with with setting up horizontal sharding, migrating to PlanetScale, or want enterprise-level SLAs, we offer this through our [Enterprise plan](/enterprise) option. [Please reach out](/contact) for more information.
 
 ### Insights
 

diff --git a/docs/concepts/workflows.md b/docs/concepts/workflows.md
@@ -0,0 +1,18 @@
+---
+title: 'What are workflows?'
+subtitle: 'Learn how to use PlanetScale workflows to run different sequences to move data between keyspaces.'
+label: 'Beta feature'
+date: '2024-11-07'
+---
+
+PlanetScale workflows (currently in beta) provide pre-defined recipes that make it simple to run operations on your databases. There is currently only one workflow available &mdash; [moving tables from an unsharded to a sharded keyspace](/docs/sharding/sharding-quickstart), but we will continue to add more workflow options in the near future.
+
+If you are familiar with [Vitess Workflows](https://vitess.io/docsreference/vreplication/workflow/), you will see some similarities. For example, the PlanetScale workflow that allows you to move tables from an unsharded to a sharded keyspace is similar to the [Vitess `MoveTables` workflow](https://vitess.io/docs/user-guides/migration/move-tables/).
+
+## Create a workflow
+
+To create a new workflow, select your database, and click "Workflows" in the left nav. Next, click "New workflow". Because we currently only have one available workflow, this will drop you straight into the page to create a new workflow to move tables from an unsharded to sharded keyspace. In the future, you will have the option to choose other workflows.
+
+## View workflow history
+
+To view the history of all completed or pending workflows, click on "Workflows" in the left nav. From here, you can see all previous workflows along with information such as status, duration, and the time it took to complete.
diff --git a/docs/navigation/standard.md b/docs/navigation/standard.md
@@ -34,7 +34,7 @@
           slug: '/docs/imports/aws-rds-migration-guide'
         - label: 'Azure'
           slug: '/docs/imports/azure-database-for-mysql-migration-guide'
-        - label: 'Digital Ocean'
+        - label: 'DigitalOcean'
           slug: '/docs/imports/digitalocean-database-migration-guide'
         - label: 'GCP CloudSQL'
           slug: '/docs/imports/gcp-cloudsql-migration-guide'
@@ -214,18 +214,36 @@
 - label: 'Sharding your database'
   icon: 'sharding'
   items:
-    - label: 'Sharding with PlanetScale'
-      slug: '/docs/sharding/overview'
-    - label: 'Sharding quickstart'
-      slug: '/docs/sharding/sharding-quickstart'
-    - label: 'VSchema'
-      slug: '/docs/sharding/vschema'
-    - label: 'Vindexes'
-      slug: '/docs/sharding/vindexes'
-    - label: 'Keyspaces'
-      slug: '/docs/sharding/keyspaces'
-    - label: 'Creating sequence tables'
-      slug: '/docs/sharding/sequence-tables'
+    - label: 'Overview'
+      items:
+        - label: 'Sharding with PlanetScale'
+          slug: '/docs/sharding/overview'
+        - label: 'Workflows'
+          slug: '/docs/concepts/workflows'
+    - label: 'Guides'
+      items:
+        - label: 'Sharding quickstart'
+          slug: '/docs/sharding/sharding-quickstart'
+        - label: 'Sharding new tables'
+          slug: '/docs/sharding/sharding-new-tables'
+        - label: 'Avoiding cross-shard queries'
+          slug: '/docs/sharding/avoiding-cross-shard-queries'
+        - label: 'Keyspace targeting for ORMs and frameworks'
+          slug: '/docs/sharding/targeting-correct-keyspace'
+        - label: 'Creating sequence tables'
+          slug: '/docs/sharding/sequence-tables'
+        - label: 'Pre-sharding checklist'
+          slug: '/docs/sharding/pre-sharding-checklist'
+    - label: 'Concepts'
+      items:
+        - label: 'VSchema'
+          slug: '/docs/sharding/vschema'
+        - label: 'Vindexes'
+          slug: '/docs/sharding/vindexes'
+        - label: 'Keyspaces'
+          slug: '/docs/sharding/keyspaces'
+        - label: 'Sharding workflow state reference'
+          slug: '/docs/sharding/sharding-workflow-state-reference'
 
 - label: 'Vectors'
   icon: 'vectors'