This repository has been archived by the owner on Nov 12, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 71
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
3070ea2
commit 30bb51f
Showing
9 changed files
with
873 additions
and
32 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| --- | ||
| title: 'Cluster configuration' | ||
| subtitle: 'Create and manage sharded and unsharded keyspaces for your database.' | ||
| date: '2024-09-20' | ||
| --- | ||
|
|
||
| {% callout type="warning" %} | ||
| Misconfiguration can cause availability issues. We recommend thoroughly reading through the documentation in the [Sharding section](/docs/sharding/overview) of the docs prior to making any changes. If you have any questions, please [reach out to our support team](https://support.planetscale.com). | ||
| {% /callout %} | ||
|
|
||
| ## Overview | ||
|
|
||
| The **Cluster configuration** tab in your PlanetScale dashboard allows you to create and manage sharded and unsharded keyspaces. | ||
|
|
||
| From here, you can: | ||
|
|
||
| - Create a sharded or unsharded keyspace | ||
| - Adjust the instance sizes for keyspaces | ||
| - Adjust the number of replicas for keyspaces | ||
| - Adjust the VSchema | ||
|
|
||
| These are advanced configuration settings that expose some of the underlying Vitess configuration of your cluster. | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## Create a keyspace | ||
|
|
||
| To create a new [keyspace](/docs/sharding/keyspaces): | ||
|
|
||
| 1. Select the database you want to configure. | ||
| 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 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. | ||
|
|
||
| **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. | ||
|
|
||
| 7. Choose the cluster sizes you would like to use for this keyspace. Keep in mind, if you are creating a sharded keyspace, this will spin up multiple clusters of the selected size. For example, if you are creating 4 shards and choose the `PS-80` cluster size, we will create 4 `PS-80`s, each with 1 primary and 2 replicas. | ||
| 8. Select the number of _additional_ replicas, if any, that you'd like to add to each cluster. Each cluster comes with 2 replicas by default, so any number you choose will be in addition to those 2. | ||
| 9. Review the new monthly cost for this keyspace below. This is in addition to your existing unsharded keyspace, as well as any other keyspaces you add. | ||
| 10. Once satisfied, click "Create keyspace". | ||
|
|
||
| ## Modify the VSchema of a keyspace via cluster configuration tab | ||
|
|
||
| **Note**: You can modify the VSchema on your development branch either in the cluster configuration tab, using the []`ALTER VSCHEMA` command](/docs/sharding/vschema#modifying-vschema), or with the pscale CLI using [`pscale keyspace vschema update`](/docs/reference/keyspace). | ||
|
|
||
| Once you have created your keyspace, you will see a new tab: **VSchema**. The VSchema contains information about how the keyspace is sharded, sequence tables, and other Vitess schema information. The VSchema tab allows you to configure the Vschema for your new keyspace or modify it for existing keyspaces. | ||
|
|
||
| We do not recommend modifying the VSchema directly on your production branch. In fact, it is not possible to do if you have [safe migrations](/docs/concepts/safe-migrations) enabled (as recommended). Instead, to modify the VSchema, you should first [create a new development branch](/docs/concepts/branching). Once you have your branch ready, follow these steps: | ||
|
|
||
| 1. To update the VSchema in the cluster configuration panel, select your new development branch from the dropdown at the top, and then select the keyspace below that has the VSchema you'd like to modify. | ||
| 2. Next, click the tab labeled "VSchema". | ||
| 3. Modify the VSchema configuration JSON file as needed. Refer to the [VSchema documentation](/docs/sharding/vschema) for more information about the available options. | ||
| 4. When finished, click "Save changes". We will validate your VSchema, and if it is valid, the changes will be saved. If there are errors, we will warn you here to change them before saving. | ||
| 5. Go back to your "Branches" tab and click on the development branch that you modified. You should see a note on the right that says "Updated VSchema configuration" which lets you know the VSchema(s) for this branch has been modified. | ||
| 6. From here, go through the normal [deploy request process](/docs/concepts/deploy-requests) to deploy this change to production. | ||
|
|
||
| Once your change is deployed to production, you can come back to the cluster configuration page, switch to your production branch, and view the updates to your VSchema. You can also click the "Changes" tab to see information, such as the resize event, status, and start/end time for any previous changes to the VSchema. | ||
|
|
||
| ## Modify routing rules | ||
|
|
||
| This configuration setting is currently only available for some Enterprise customers. To modify your routing rules, click "Manage routing rules" on the bottom left of the keyspace configuration panel. | ||
|
|
||
| Again, you will need to create a new branch to modify routing rules, as described in the "Modify the VSchema of a keyspace" section above. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| --- | ||
| title: 'PlanetScale CLI commands: keyspace' | ||
| subtitle: 'Use the PlanetScale CLI "keyspace" command to create and modify keyspaces and VSchemas from the pscale CLI.' | ||
| date: '2024-09-20' | ||
| meta: | ||
| title: 'CLI reference: keyspace' | ||
| --- | ||
|
|
||
| ## Getting started | ||
|
|
||
| Make sure to first [set up your PlanetScale developer environment](/docs/concepts/planetscale-environment-setup). Once you've installed the `pscale` CLI, you can interact with PlanetScale and manage your databases straight from the command line. | ||
|
|
||
| ## The `keyspace` command | ||
|
|
||
| This command allows you to view your keyspaces and view or update your VSchemas. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```bash | ||
| pscale keyspace <SUB-COMMAND> <FLAG> | ||
| ``` | ||
|
|
||
| ### Available sub-commands | ||
|
|
||
| | **Sub-command** | **Sub-command flags** | **Description** | | ||
| | -------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------ | | ||
| | `list <DATABASE_NAME> <BRANCH_NAME>` ` | | List all keyspaces within a database branch. | | ||
| | `show <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Show a specific keyspace within a database branch. | | ||
| | `vschema show <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Show the VSchema for a sharded keyspace. Empty on non-sharded keyspaces. | | ||
| | `vschema update <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--vschema <FILE>`\* | Update a VSchema of a keyspace. | | ||
|
|
||
| > \* _Flag is required_ | ||
| #### Sub-command flag descriptions | ||
|
|
||
| | **Sub-command flag** | **Description** | **Applicable sub-commands** | | ||
| | -------------------- | ------------------------------------------------- | --------------------------- | | ||
| | `--vschema <FILE>` | `<FILE>` is the path to the updated VSchema file. | `vschema update` | | ||
|
|
||
| ### Available flags | ||
|
|
||
| | **Flag** | **Description** | | ||
| | --------------------------- | ------------------------------------- | | ||
| | `-h`, `--help` | View help for auth command | | ||
| | `--org <ORGANIZATION_NAME>` | The organization for the current user | | ||
|
|
||
| ### Global flags | ||
|
|
||
| | **Command** | **Description** | | ||
| | ------------------------------- | ------------------------------------------------------------------------------------ | | ||
| | `--api-token <TOKEN>` | The API token to use for authenticating against the PlanetScale API. | | ||
| | `--api-url <URL>` | The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`. | | ||
| | `--config <CONFIG_FILE>` | Config file. Default is `$HOME/.config/planetscale/pscale.yml`. | | ||
| | `--debug` | Enable debug mode. | | ||
| | `-f`, `--format <FORMAT>` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. | | ||
| | `--no-color` | Disable color output. | | ||
| | `--service-token <TOKEN>` | The service token for authenticating. | | ||
| | `--service-token-id <TOKEN_ID>` | The service token ID for authenticating. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| title: 'What is a keyspace' | ||
| subtitle: 'Learn about what a keyspace is and how to modify them on your PlanetScale database.' | ||
| date: '2024-09-20' | ||
| --- | ||
|
|
||
| A keyspace is a logical database that maps directly to your database in PlanetScale. Once you begin sharding, you will create a new keyspace, or keyspaces, where your shards will exist. These sharded keyspaces map to new logical databases in your PlanetScale database. | ||
|
|
||
| To get a better sense of this, click on your [Cluster configuration](/docs/concepts/cluster-configuration) tab in your dashboard. If you have an existing unsharded database, you'll see that database listed there as an unsharded keyspace. If you click "New keyspace", you're able to configure a brand new keyspace here. | ||
|
|
||
| The most common use case for creating a new keyspace is to shard one or multiple tables. | ||
|
|
||
| All of your keyspaces are separate databases. And, again, sharded keyspaces hold multiple databases. However, with the power of Vitess, your application views these all as a single database. It uses the VTGate load balancer to route queries to the correct keyspace, and then the correct shard, and finally the correct primary or replica, as configured. | ||
|
|
||
| For more information about modifying a keyspace, please see the [Cluster configuration documentation](/docs/concepts/cluster-configuration). |
Oops, something went wrong.