diff --git a/docs/concepts/cluster-sizing.md b/docs/concepts/cluster-sizing.md index abc238b6..04e0f3aa 100644 --- a/docs/concepts/cluster-sizing.md +++ b/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. diff --git a/docs/enterprise/managed/aws/back-up-and-restore.md b/docs/enterprise/managed/aws/back-up-and-restore.md index 09e22c3f..f55d9a9e 100644 --- a/docs/enterprise/managed/aws/back-up-and-restore.md +++ b/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' --- diff --git a/docs/enterprise/managed/aws/getting-started.md b/docs/enterprise/managed/aws/getting-started.md index e49d1108..c4f8f66e 100644 --- a/docs/enterprise/managed/aws/getting-started.md +++ b/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' --- diff --git a/docs/enterprise/managed/aws/privatelink.md b/docs/enterprise/managed/aws/privatelink.md index 60d7e3ea..3065a954 100644 --- a/docs/enterprise/managed/aws/privatelink.md +++ b/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' --- diff --git a/docs/enterprise/managed/aws/reverse-privatelink.md b/docs/enterprise/managed/aws/reverse-privatelink.md index bfa86fe5..ec5b0fbf 100644 --- a/docs/enterprise/managed/aws/reverse-privatelink.md +++ b/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' --- diff --git a/docs/enterprise/managed/cloud-accounts-and-contents.md b/docs/enterprise/managed/cloud-accounts-and-contents.md index 242c229e..035f4d43 100644 --- a/docs/enterprise/managed/cloud-accounts-and-contents.md +++ b/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' --- diff --git a/docs/enterprise/managed/data-requests.md b/docs/enterprise/managed/data-requests.md index 4231aaf7..f6360d04 100644 --- a/docs/enterprise/managed/data-requests.md +++ b/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' --- diff --git a/docs/enterprise/managed/gcp/back-up-and-restore.md b/docs/enterprise/managed/gcp/back-up-and-restore.md index 71b1b6c4..34a2835a 100644 --- a/docs/enterprise/managed/gcp/back-up-and-restore.md +++ b/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' --- diff --git a/docs/enterprise/managed/gcp/getting-started.md b/docs/enterprise/managed/gcp/getting-started.md index c20d129a..928f4ed6 100644 --- a/docs/enterprise/managed/gcp/getting-started.md +++ b/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' --- diff --git a/docs/enterprise/managed/gcp/overview.md b/docs/enterprise/managed/gcp/overview.md index 8e459ca4..8751f006 100644 --- a/docs/enterprise/managed/gcp/overview.md +++ b/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' --- diff --git a/docs/enterprise/managed/gcp/private-service-connect.md b/docs/enterprise/managed/gcp/private-service-connect.md index 201f8d24..735f65a1 100644 --- a/docs/enterprise/managed/gcp/private-service-connect.md +++ b/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' --- diff --git a/docs/enterprise/managed/overview.md b/docs/enterprise/managed/overview.md index 71705102..d24305cc 100644 --- a/docs/enterprise/managed/overview.md +++ b/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) diff --git a/docs/enterprise/managed/schema-snapshots.md b/docs/enterprise/managed/schema-snapshots.md index 9e067863..d10d9ac0 100644 --- a/docs/enterprise/managed/schema-snapshots.md +++ b/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' --- diff --git a/docs/enterprise/managed/user-management.md b/docs/enterprise/managed/user-management.md index 01674a60..105c14eb 100644 --- a/docs/enterprise/managed/user-management.md +++ b/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' --- diff --git a/docs/enterprise/proof-of-concept.md b/docs/enterprise/proof-of-concept.md index e757f584..1a4e5dc7 100644 --- a/docs/enterprise/proof-of-concept.md +++ b/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. diff --git a/docs/navigation/standard.md b/docs/navigation/standard.md index a5ef753d..5ba1e089 100644 --- a/docs/navigation/standard.md +++ b/docs/navigation/standard.md @@ -202,8 +202,6 @@ 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' @@ -211,6 +209,16 @@ - 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' diff --git a/docs/concepts/sharding.md b/docs/sharding/overview.md similarity index 96% rename from docs/concepts/sharding.md rename to docs/sharding/overview.md index df9f893c..dc8e9de3 100644 --- a/docs/concepts/sharding.md +++ b/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 diff --git a/docs/sharding/sequence-tables.md b/docs/sharding/sequence-tables.md new file mode 100644 index 00000000..0431a197 --- /dev/null +++ b/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 %} diff --git a/docs/enterprise/vschema.md b/docs/sharding/vschema.md similarity index 92% rename from docs/enterprise/vschema.md rename to docs/sharding/vschema.md index d46c6e0d..450656b2 100644 --- a/docs/enterprise/vschema.md +++ b/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.