Restoring a PlanetScale database from branch history isn’t about time travel; it’s about surgical reconstruction of a specific database state.
Let’s imagine you’ve got a production database, my-prod-db, and a rogue DELETE statement or a bad migration script just wiped out a critical table, or worse, a significant chunk of your data. You’re in panic mode. PlanetScale’s branch history, however, offers a lifeline. It lets you roll back to a specific point in time within a branch’s lineage, effectively creating a new branch that represents that past state.
Here’s how you’d actually do it, step-by-step.
First, you need to identify the specific branch and the commit hash you want to restore from. You can find this in the PlanetScale UI under your database’s "History" tab. Each commit represents a schema change or data migration applied to that branch. You’ll see a list of commits, each with a unique hash.
Let’s say your production branch is called main and you’ve identified the commit hash a1b2c3d4e5f67890abcdef1234567890 that represents the state you want to revert to.
In the PlanetScale UI, navigate to your main branch. You’ll see an option to "Create Branch". Click that.
On the "Create Branch" page, you’ll be prompted to name your new branch. A descriptive name is crucial here. Something like restore-from-a1b2c3d-YYYYMMDD is a good convention.
Crucially, you’ll see an option that says "Branch from". By default, this is set to the latest commit on your current branch. This is where you make your change. Click on the "Branch from" selector and paste or type in the commit hash you identified earlier: a1b2c3d4e5f67890abcdef1234567890.
Once you’ve entered the commit hash, click "Create Branch".
PlanetScale will now create a brand new branch, restore-from-a1b2c3d-YYYYMMDD, that starts at the exact state of the main branch at commit a1b2c3d4e5f67890abcdef1234567890. This new branch contains the schema and data as it existed at that specific commit.
Now you have a branch that represents your desired historical state. What you do next depends on your goal.
If your goal is to replace the current main branch with this historical state, you’ll want to merge this new restore branch back into main.
- Open a Pull Request: Navigate to your
restore-from-a1b2c3d-YYYYMMDDbranch and click "New Pull Request". - Target Branch: Ensure the "Into" (target) branch is your
mainproduction branch. - Review: PlanetScale will show you the differences. Since you’re restoring, it will likely show deletions of rows or schema elements that were added after your chosen commit. Carefully review these changes to ensure they align with your recovery plan.
- Merge: Once satisfied, merge the pull request. This will update your
mainbranch to reflect the state of therestorebranch.
If your goal is to inspect the data at that historical point without immediately altering production, you can simply connect to the restore-from-a1b2c3d-YYYYMMDD branch using your database credentials and query it directly. This is invaluable for understanding what data was lost or changed.
This process is powerful because it leverages PlanetScale’s immutable branch history. When you create a branch from a specific commit, you’re not modifying the past; you’re creating a new lineage that diverges from the main history at that point. Merging it back effectively makes that historical state the new present for the target branch.
The most subtle, and often overlooked, aspect of this restore process is that the new branch created from a historical commit is itself a fully functional, independent branch. You can continue to develop on it, create further branches from it, or even abandon it if your investigation reveals a different recovery strategy. It doesn’t inherently "undo" anything on the original branch until you explicitly merge it back.
The next hurdle you’ll likely face after a successful restore is understanding why the data corruption occurred in the first place, leading you to investigate application logs or migration scripts.