Learn how to create and revert non-blocking schema changes with PlanetScale deploy requests.
Deploy requests are an integral part of the PlanetScale workflow. Database branching, coupled with deploy requests, allows you to deploy non-blocking schema changes to your production database with zero downtime. You can also undo deployments without losing any data that was written during that time.
Create a deploy request
Note: Your database must have a production branch before you can create a deploy request.
- Go to the overview page of the development branch you want to deploy to production.
- Under "Create a deploy request", select the branch you want to deploy to.
- Add a comment about the deploy request.
- Click "Create deploy request".
Review and deploy a deploy request
Once you create a deploy request, you or your team can review it and, optionally, approve it before deploying it to production.
PlanetScale will check if the request is deployable. This process includes checking for issues like foreign key constraints, missing unique keys, and more. We also check if there are any known conflicts with the production schema that could prevent a clean merge. While we attempt to find all possible conflicts, it is ultimately up to you to confirm merge details.
- Click the "Deploy requests" tab on the database overview page.
- Select the open deploy request you want to review.
- Under "Summary", you'll see if the request is deployable.
- To review the schema changes, click the "Schema changes" tab.
- You'll see the proposed changes here. New additions are highlighted in green, and deletions are highlighted in red.
- If you have required deploy requests to be approved before deployment, you'll also see the option to "Approve changes" or "Leave a comment" on the "Schema changes" tab.
- Once the request is approved, if required, it's ready to be added to the deploy queue. On the "Summary" tab, click "Add changes to deploy queue". The deployment will begin or be queued if there are other pending deployments.
- After you deploy, you have 30 minutes to "undo" it using our Rewind feature.
PlanetScale deploy request - approve changes
If you would like to require approval before a request can be deployed, go to the "Settings" page for your database and check the "Deploy requests require approval before deploy" box. You must be an Organization Administrator to enable this.
Close a deploy request
If you decide you don't want to proceed with a deploy request, you can easily close it.
- Click the "Deploy requests" tab on the database overview page.
- Select the request you want to close.
- Click on the "Close deploy request" button on the right-hand side.
Revert a schema change
If you ever merge a deploy request, only to realize you need to undo it, PlanetScale can handle that! The Rewind feature allows you to revert a recently deployed schema change while maintaining data that was written to the original schema during that time.
The Rewind feature is currently in limited beta. You must enroll your database and opt-in to the terms to access this feature.
How to revert a schema change with Rewind
You can revert a deployment for up to 30 minutes after the deploying. After the 30 minute period is up, the deployment becomes permanent, and you will no longer have the option to revert.
You must first agree to the beta terms before you can use Rewind. Go to the database Settings page, click "Beta features", and check "Enroll this database in the Rewind limited beta" to opt-in.
- Select the deploy request you want to revert.
- If you're not already enrolled, you'll see a Beta banner underneath the comment box on the deploy request page. Click "Enroll database" to opt-in to the Rewind limited beta terms.
- To revert the schema changes made with the deploy request, click "Revert changes" and confirm.
- We will immediately revert your production database back to its previous schema.
- Any data that was written to the original schema in the time between deploying and reverting will remain in your database after the revert.
- The Deploy Request will be closed, but the branch will remain for you to continue development on if you choose.
When is data not retained
There are some scenarios where some data is not retained when you revert your changes.
- You add a table or column to your schema and then revert it. If any data was written to those newly introduced fields between deployment and reverting, that data will not be retained upon revert, as the fields will no longer exist.
When are you unable to revert a schema change
There are also some edge cases where reverting a schema change is not possible. We will always attempt to revert, but if there are scenarios where your data integrity is at risk, we will not proceed with the revert. The following are some cases where a revert will fail:
- If you deploy a schema change that expands the length of some column, such as changing from
VARCHAR(50), and add new data larger than 10 characters to it, a revert attempt may fail. This is to protect your data. You may have written data to the
VARCHAR(50)field in that time that will not fit in the smaller 10 character space. If no data is added between deployment and revert, the revert process can proceed.
- Some examples of other similar scenarios where revert won't be possible (again, only if larger sized data is added between deployment and revert) are:
- Any other operation that expands the size of a field
- If you deploy a schema change that removes a unique key or relaxes a unique constraint, and in the time between deployment and attempting to revert, you insert rows that would otherwise conflict with that constraint, the revert may fail.
- Another uncommon but possible scenario: you deploy a schema change that has a
NOT NULLcolumn without a
DEFAULTvalue, combined with an
ALTER TABLE DROP COLUMNstatement for that column. If you insert some rows between the deployment and the revert attempt, the revert will fail. We will not be able to re-add that column for the newly inserted rows and will not know how to populate it.
For an in-depth look at how Rewind works, check out our Behind the scenes: how we built Rewind blog post.
The process of reverting a schema change will not count toward your
write, or storage limits. You will not be charged for the background processes we run, like creating a copy of the affected schema and data.
You may see some temporary
_vt tables in your database. These are used to facilitate the deployment and revert process and do not count toward your storage.