VSchema

VSchema overview

PlanetScale databases are powered by Vitess. Each Vitess cluster can have one or more keyspaces. For unsharded databases, there is a 1:1 relationship between a keyspace and a database within MySQL. For sharded databases, a single keyspace can map to multiple MySQL databases under the hood.

Each keyspace in your PlanetScale database has an associated VSchema. The VSchema contains information about how the keyspace is sharded, sequence tables, and other Vitess schema information.

Viewing VSChema

In order to view your VSchema, first go to the "Branches" tab in the PlanetScale app.

Click on the branch you would like to view the VSchema for. Then, select the keyspace and expand out the "Configuration Files" drop-down.

From here, you can inspect your VSchema configuration JSON file.

Modifying VSchema

You must have a sharded keyspace in order to make VSchema changes. At this time, sharded keyspaces can only be set up by reaching out to PlanetScale support.

If you have a database with at least one sharded keyspace, you can modify its VSchema using ALTER VSCHEMA ... commands. PlanetScale recommends making all such modifications in a development branch. When ready, you can make a deploy request to get the changes into production. Consider the following database with two keyspaces.

sharded is a sharded keyspace with two shards and tweeter is unsharded. Also note that safe migrations are enabled. In order to make a VSchema change for the production branch in this configuration, we first must create a new branch. We'll call it add-tweets

On this branch you can make your VSchema and schema changes. In this case, we'll create a new table called tweets in the sharded keyspace and also update the VSchema.

We will also create a sequence table in the unsharded keyspace, and update the VSchema accordingly:

We have now made updates both to our Vitess VSchema and MySQL schema. To get these changes into production, navigate to the "Branches" page and select the add-tweets branch. Here, you will be presented with a diff of both the VSchema and schema changes:

Click "Create deploy request." The deploy request should indicate that it is going to apply both VSchema and Schema changes:

Click "Deploy changes." Once complete, the Vschema and schema changes will be applied to your production branch.

Need help?

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