docs: upstream

planetscale/www@223ce17

docs/concepts/cluster-sizing.md

@@ -1,7 +1,7 @@
 ---
 title: 'Cluster sizing'
 subtitle: 'Learn about how to select the right cluster size, how to upsize, and how to downsize.'
-date: '2024-05-08'
+date: '2024-08-29'
 ---
 
 You can easily upsize and downsize your database cluster from within the PlanetScale dashboard. This doc covers some information about selecting a cluster size upon database creation as well as how to upsize and downsize.
@@ -39,3 +39,8 @@ To change cluster sizes, go to your PlanetScale dashboard, click on your databas
 The time it takes to change sizes depends on the size and region of your database. Larger databases may take 20 minutes to upsize/downsize. However, this is all done online, so you will not experience any downtime. Keep in mind, once you update your cluster size, you cannot change sizes again until the first size change completes.
 
 When you choose to change cluster size, we upgrade each of your replicas one by one: delete the tablet container, create a new tablet container of the new size, attach the persistent volume, start it up, and connect it to the primary. Once that's complete, we fail the primary over to one of those new replicas, and do the same thing to the old primary.
+
+## 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.

docs/enterprise/managed/aws/back-up-and-restore.md

@@ -1,7 +1,7 @@
 ---
 title: 'Back up and restore'
 subtitle: 'Learn about how backups work in AWS and PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-06'
 ---
 

docs/enterprise/managed/aws/getting-started.md

@@ -1,7 +1,7 @@
 ---
 title: 'Set up PlanetScale Managed in AWS'
 subtitle: 'Learn how to set up PlanetScale Managed within a AWS sub-account.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-12-06'
 ---
 

docs/enterprise/managed/aws/privatelink.md

@@ -1,7 +1,7 @@
 ---
 title: 'Set up AWS PrivateLink with PlanetScale Managed'
 subtitle: 'Learn how to set up AWS PrivateLink to establish private database connectivity with PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2024-05-03'
 ---
 

docs/enterprise/managed/aws/reverse-privatelink.md

@@ -1,7 +1,7 @@
 ---
 title: 'Set up AWS Reverse PrivateLink with PlanetScale Managed'
 subtitle: 'Learn how to set up AWS PrivateLink to allow for data imports from an existing database environment into PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2024-05-03'
 ---
 

docs/enterprise/managed/cloud-accounts-and-contents.md

@@ -1,7 +1,7 @@
 ---
 title: 'Cloud accounts and contents'
 subtitle: 'Learn more about cloud account access and content restrictions for PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-06'
 ---
 

docs/enterprise/managed/data-requests.md

@@ -1,7 +1,7 @@
 ---
 title: 'Data requests'
 subtitle: 'Learn more about data requests for PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-06'
 ---
 

docs/enterprise/managed/gcp/back-up-and-restore.md

@@ -1,7 +1,7 @@
 ---
 title: 'Back up and restore'
 subtitle: 'Learn about how backups work in GCP and PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-06'
 ---
 

docs/enterprise/managed/gcp/getting-started.md

@@ -1,7 +1,7 @@
 ---
 title: 'Set up PlanetScale Managed in GCP'
 subtitle: 'Learn how to set up PlanetScale Managed within a GCP project.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-07'
 ---
 

docs/enterprise/managed/gcp/overview.md

@@ -1,7 +1,7 @@
 ---
 title: 'PlanetScale Managed on GCP overview'
 subtitle: 'Learn more about deploying PlanetScale in your Google Cloud Platform account with our PlanetScale Managed plan.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2024-08-29'
 ---
 

docs/enterprise/managed/gcp/private-service-connect.md

@@ -1,7 +1,7 @@
 ---
 title: 'Set up GCP Private Service Connect with PlanetScale Managed'
 subtitle: 'Learn how to set up GCP Private Service Connect to establish private database connectivity with PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2024-05-13'
 ---
 

docs/enterprise/managed/overview.md

@@ -1,7 +1,7 @@
 ---
 title: 'PlanetScale Managed overview'
 subtitle: 'Deploy PlanetScale in your Amazon Web Services or Google Cloud Platform account with our PlanetScale Managed plan.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-08'
 ---
 
@@ -30,7 +30,7 @@ Read more on how PlanetScale Managed works inside either cloud provider:
 
 Single-tenancy is one of many benefits when it comes to PlanetScale Managed. Still, with this PlanetScale Enterprise service, you also get:
 
-- [Database sharding](/docs/concepts/sharding) available
+- [Database sharding](/docs/sharding/overview) available
 - Option to sign BAAs for [HIPAA compliance](/blog/planetscale-and-hipaa)
 - Deployment to additional regions
 - [PCI compliance](/blog/planetscale-managed-is-now-pci-compliant) (AWS only)

docs/enterprise/managed/schema-snapshots.md

@@ -1,7 +1,7 @@
 ---
 title: 'Schema snapshots'
 subtitle: 'Learn more about transfers of schema snapshots for PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2024-02-13'
 ---
 

docs/enterprise/managed/user-management.md

@@ -1,7 +1,7 @@
 ---
 title: 'User management'
 subtitle: 'Learn how to set up users and access levels in PlanetScale Managed.'
-label: 'Managed'
+label: 'Enterprise'
 date: '2023-11-06'
 ---
 

docs/enterprise/proof-of-concept.md

@@ -40,7 +40,7 @@ Though the details change from customer to customer, the flow of work during the
 1. First, it's good to determine which database you want to start with.
    Long term, you may intend to move multiple databases and workloads into PlanetScale, but during the proof-of-concept phase it is often useful to focus on one specific database and workload to begin testing with.
 2. Based on this choice, your Solutions Architect will help you get the infrastructure set up for your database, and configured appropriately.
-3. If you are going to be using a sharded database, you will also work with us to determine your [sharding strategy](/docs/concepts/sharding), and we will help you decide the best [VSchema](https://vitess.io/docs/reference/features/vschema/) for your tables.
+3. If you are going to be using a sharded database, you will also work with us to determine your [sharding strategy](/docs/sharding/overview), and we will help you decide the best [VSchema](https://vitess.io/docs/reference/features/vschema/) for your tables.
 4. The next step is to get your data imported.
    We have a [self-serve tool for importing databases](/docs/imports/database-imports) into PlanetScale, but we often provide direct assistance with this, and for larger, more complex workloads our team can handle running the appropriate Vitess commands to migrate you over.
 5. After this, customers typically want to start testing the capabilities of their imported database.

docs/navigation/standard.md

@@ -202,15 +202,23 @@
   items:
     - label: 'Cluster sizing'
       slug: '/docs/concepts/cluster-sizing'
-    - label: 'Sharding with PlanetScale'
-      slug: '/docs/concepts/sharding'
     - label: 'Replicas'
       slug: '/docs/concepts/replicas'
     - label: 'Read-only regions'
       slug: '/docs/concepts/read-only-regions'
     - label: 'PlanetScale system limits'
       slug: '/docs/reference/planetscale-system-limits'
 
+- label: 'Sharding your database'
+  icon: 'sharding'
+  items:
+    - label: 'Sharding with PlanetScale'
+      slug: '/docs/sharding/overview'
+    - label: 'View and update VSchema'
+      slug: '/docs/sharding/vschema'
+    - label: 'Creating sequence tables'
+      slug: '/docs/sharding/sequence-tables'
+
 - label: 'Caching queries'
   icon: 'cache'
   items:
@@ -408,10 +416,6 @@
               slug: '/docs/enterprise/managed/data-requests'
             - label: 'Schema snapshots'
               slug: '/docs/enterprise/managed/schema-snapshots'
-    - label: 'Sharded Schemas'
-      items:
-        - label: 'View VSchema'
-          slug: '/docs/enterprise/vschema'
 
 - label: 'Plans and billing'
   icon: 'plans'

docs/concepts/sharding.md → docs/sharding/overview.md

@@ -1,13 +1,14 @@
 ---
 title: 'Sharding with PlanetScale'
 subtitle: 'Learn how PlanetScale can help you horizontally scale your MySQL database with our sharding solution.'
-date: '2023-06-12'
+label: 'Enterprise'
+date: '2023-08-29'
 ---
 
 With Vitess under the hood, we're able to offer an elegant horizontal scaling solution via sharding — with minimal application changes.
 
 {% callout %}
-Sharding is available on our [Enterprise plan](/docs/concepts/planetscale-plans). If you'd like more information about how we can help you shard your MySQL database, [get in touch](/contact).
+Sharding is available on our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan). If you'd like more information about how we can help you shard your MySQL database, [get in touch](/contact).
 {% /callout %}
 
 ## Sharding with PlanetScale

docs/sharding/sequence-tables.md

@@ -0,0 +1,95 @@
+---
+title: 'Sequence Tables'
+subtitle: 'Learn how to create sequence tables on a sharded PlanetScale database.'
+label: 'Enterprise'
+date: '2024-08-29'
+---
+
+{% callout %}
+This feature is only available on our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan). If you'd like more information about how we can help you shard your MySQL database, [get in touch](/contact).
+{% /callout %}
+
+In MySQL, it is common to have an integer primary key that uses the `AUTO_INCREMENT` feature for assigning IDs.
+However, if you have a horizontally-sharded table, you will not be able to use `AUTO_INCREMENT` for your ID.
+In such a setup, the rows of the table are distributed across many instances of MySQL.
+The separate instances of MySQL do not have a built-in way to coordinate which IDs are in use and which are not.
+Instead, you will need to use a **sequence table**.
+
+A [sequence table](https://vitess.io/docs/reference/features/vitess-sequences) is a special table that contains metadata for managing the incrementing ID values for the column of a horizontally sharded table.
+Each time you create a new horizontally sharded table, you should create the corresponding sequence table and update the VSchema.
+
+## Creating a horizontally-sharded table
+
+We recommend keeping [safe migrations](/docs/concepts/safe-migrations) enabled for all production databases.
+Thus, the first step to make schema modifications is to create a new [branch](/docs/concepts/branching),
+and connect to it via the [command line](/docs/reference/planetscale-cli).
+
+Next, to create a horizontally-sharded table, switch to your desired sharded keyspace.
+Create a new table in this keyspace, and do _not_ use `AUTO_INCREMENT` for your ID column.
+For example, to create a table in the `test_sharded` keyspace, run:
+
+```sql
+USE test_sharded;
+CREATE TABLE test(id BIGINT UNSIGNED PRIMARY KEY, data JSON);
+```
+
+Next, switch over to the unsharded keyspace that you want to use for sequence tables.
+Here, you'll create a sequence table.
+It is good practice to use the same name as the sharded table with `_seq` or `_sequence` appended.
+Being consistent with this naming will help maintain a clear association between your data tables and sequence tables.
+
+```sql
+USE test_unsharded;
+CREATE TABLE test_seq(id bigint, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence';
+```
+
+We also need to update the [VSchema](/docs/sharding/vschema) of our database.
+We need to tell Vitess about this new `SEQUENCE`, let it know to use the `id` column as the shard key, and tell it to use the `test_seq` table for fetching auto incrementing IDs.
+
+```sql
+ALTER VSCHEMA ADD SEQUENCE `test_unsharded`.`test_seq`;
+
+ALTER VSCHEMA ON `test_sharded`.`test` ADD VINDEX hash(id) USING hash;
+
+ALTER VSCHEMA ON `test_sharded`.`test` ADD auto_increment id USING `test_unsharded`.`test_seq`;
+```
+
+When you are comfortable with your schema changes, create a [deploy request](/docs/concepts/deploy-requests) and merge.
+
+## Sequence table values
+
+Unlike vanilla Vitess, PlanetScale will automatically populate the single required row into any sequence table created with the above steps.
+After merging your deploy request, you should be able to query the sequence table as follows:
+
+```sql
+SELECT * FROM test_unsharded.test_seq;
++----+---------+-------+
+| id | next_id | cache |
++----+---------+-------+
+|  0 |       1 |  1000 |
++----+---------+-------+
+1 row in set (0.04 sec)
+```
+
+- `id` Should always be 0.
+- `next_id` represents the next ID in the sequence to be fetched. You typically want this to start as 1.
+- `cache` represents the number of IDs that can be fetched and cached by a VTTablet. For good performance, this should be set to a large number like 1000 or more.
+
+We can check that the sequence table is working in assigning IDs by inserting a new row and then querying for the row with ID `1`.
+
+```sql
+INSERT INTO test (data) VALUES ('{"errors": [{"message": "Error message", "code": 10}]}');
+Query OK, 1 row affected (0.06 sec)
+
+SELECT data FROM test WHERE id=1;
++--------------------------------------------------------+
+| data                                                   |
++--------------------------------------------------------+
+| {"errors": [{"message": "Error message", "code": 10}]} |
++--------------------------------------------------------+
+1 row in set (0.05 sec)
+```
+
+{% callout %}
+Check out the [Vitess documentation on sequences](https://vitess.io/docs/reference/features/vitess-sequences/) for more information.
+{% /callout %}

docs/enterprise/vschema.md → docs/sharding/vschema.md

@@ -1,10 +1,14 @@
 ---
 title: 'VSchema'
 subtitle: 'Learn how to view and modify the VSchema of your keyspaces using the PlanetScale app.'
-label: 'VSchema'
-date: '2024-08-16'
+label: 'Enterprise'
+date: '2024-08-29'
 ---
 
+{% callout %}
+This feature is only available on our [Enterprise plan](/docs/concepts/planetscale-plans#planetscale-enterprise-plan). If you'd like more information about how we can help you shard your MySQL database, [get in touch](/contact).
+{% /callout %}
+
 ## VSchema overview
 
 PlanetScale databases are powered by Vitess.