Sign in|Get a demo
Navigation

Cluster configuration

The Cluster configuration tab in your PlanetScale dashboard allows you to configure your PlanetScale cluster.

From here, you can:

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.

If you would like additional support configuring your sharded keyspaces, our Enterprise plan may be a good fit. Get in touch for a quick assessment.

Adjust your cluster size

To adjust your cluster size, first select the keyspace you'd like to adjust. If you only have one keyspace, it will be selected by default.

Click on the "Cluster size" dropdown. Select the new cluster size, (Metal or network-attached storage). If you select Metal, make sure you select the correct storage size. Finally. click "Save".

A network-attached storage cluster (Amazon Elastic Block Storage or Google Persistent Disk) may take a few minutes to change sizes. And a Metal cluster can take hours, depending on the size.

You can check the status of the resize from the database homepage in the dashboard, CLI, or API. There will be no downtime or locking during this process.

For more information about selecting a cluster size, see the Cluster sizing documentation.

Create a keyspace

Warning

Misconfiguration to keyspaces can cause availability issues. We recommend thoroughly reading through the documentation in the Sharding section of the docs prior to adding additional keyspaces. If you have any questions, please reach out to our support team.

Warning

If you are using Vitess global routing, you must take extra care when adding a sharded keyspace to your database (for example, if you are using @primary). Before creating one, you must ensure that all tables from your first unsharded keyspace are added to the VSchema of that unsharded keyspace. Eg:

{
  "tables": {
    "users": { }
    ...
  }
}

Otherwise, queries will fail. Learn more about VSchema.

Note

Sharded keyspaces are not currently supported on databases that have foreign key constraints enabled.

To create a new keyspace:

  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 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.

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.

  1. 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-80s, each with 1 primary and 2 replicas.
  2. 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.
  3. 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.
  4. 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, or with the pscale CLI using pscale keyspace vschema update.

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 enabled (as recommended). Instead, to modify the VSchema, you should first create a new development branch. 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 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 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.

Modify keyspace settings

There are a number of keyspace-specific settings you can use to customize keyspace behavior.

Replication durability constraints

By default, replication to replica and read-only VTTablets is configured to maximize safety and data integrity. This behavior can be relaxed for performance improvements and reduced replication lag.

  • Maximum — Default setting; use maximum durability constraints.
  • Dynamic — Use maximum durability constraints when replication lag is under 5s, and automatically relax durability constraints when replication lag exceeds 5s. Durability constraints are automatically set back to maximum when replication lag reduces to under 5s.
  • Minimum — Reduce durability constraints. Optimizes for replica and read-only performance, but has highest risk of data loss on crashed instances.

VReplication settings

These settings improve performance during VReplication processes like deploy requests and workflows.

  • Optimize inserts — Enabled by default. When enabled, during binlog replication catch-up, skip sending insert events for rows that have yet to be copied. For more technical details, see the corresponding Vitess implementation.
  • Allow NOBLOB binlog row image — Enabled by default. When enabled, then we support enabling MySQL’s NOBLOB binlog mode, to omit unchanged BLOB and TEXT columns from replication events, reducing binlog size. For more technical details, see the corresponding Vitess Implementation.
  • Batch binlog statements — Disabled by default. If enabled, batches binlog statements and transactions to limit the number of round-trips to MySQL. For more technical details, see the corresponding Vitess implementation.

Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.