This repository shows how we use PlanetScale and Vercel to automatically create a new database branch for every pull request that contains database changes.
The following secrets need to be set in the Github repository:
PLANETSCALE_SERVICE_TOKEN_ID&PLANETSCALE_SERVICE_TOKEN: https://planetscale.com/docs/concepts/service-tokensPLANETSCALE_DB&PLANETSCALE_ORG: The name of the PlanetScale organization and databaseVERCEL_TEAM&VERCEL_PROJECT_ID: Your Vercel team and project IDVERCEL_TOKEN: An access token for the Vercel REST API
This has not been made to be cross-platform friendly. We all use MacOS. Changes will have to be made if you have devs working on Windows.
- Authenticated to the PlanetScale CLI: https://planetscale.com/features/cli
- Some fairly standard command-line tools:
jq,tr - Credentials for your staging branch in
.env(or whatever other branch you use for development when there are no schema changes)
At UploadThing, we currently use the staging database branch as the default development branch. This works until you need to make changes, and want to branch off onto a fresh, new branch. This setup allows for a streamlined process of creating a new database branch and automatically connecting the Vercel preview environment to it. Additionally, a PlanetScale deploy request is automatically created for you to merge before merging your pull request.
Locally, all you should ever have to do is run pnpm dev. This runs the dev script which checks if you have made any database schema changes. If you have, it will upsert a new database branch connected to the current Git branch. Then, we'll create some PlanetScale credentials and override the DATABASE_USERNAME and DATABASE_PASSWORD environment variables from your .env file with the new credentials. Finally, we'll sync the database schema to the new branch by running pnpm db:push, before starting the Next.js development server.
As noted in the dev script, you could tunnel into the database using
pscale connectto avoid creating new credentials everytime you start the development server. This however doesn't work withdatabase-jsout of the box.
Later when you push your local changes up to GitHub, the pscale-open workflow will run and check for schema changes as well. If it finds any, it will upsert a new database branch, create some PlanetScale credentials, and override the DATABASE_USERNAME and DATABASE_PASSWORD environment variables in the Vercel project for the current git branch (this is a super cool feature of Vercel btw). Then, it will trigger a redeploy so the new environment variables are used and the preview environment is connected to the new database branch. We'll update the PR description to let you know if there are deploy requests that has to be merged:
When pull requests are closed (merged or not), the database branch will be deleted (including all the credentials you've created for it), and the environment variable overrides will be removed from Vercel.