Automatic Prisma migrations
How to make changes to your PlanetScale database schema while using Prisma, a next-generation Node.js and TypeScript ORM
This document has been updated to include the recommended Prisma and PlanetScale workflow, specifically
the recommendation to use
prisma db push instead of
prisma migrate dev with shadow branches. Also, you previously needed to turn on the ability to automatically
copy the Prisma migration metadata. You no longer need to do this. Read more below.
In this tutorial, we're going to learn how to do Prisma migrations in PlanetScale as part of your deployment process using
prisma db push.
Quick introduction to Prisma's db push
From a high level, Prisma's
db push introspects your PlanetScale database to infer and execute the changes required to make your database schema reflect the state of your Prisma schema. When
prisma db push is run, it will ensure the schema in the PlanetScale branch you are currently connected to matches your current Prisma schema.
prisma db push over
prisma migrate dev for the following reasons:
PlanetScale provides Online Schema Changes that are deployed automatically when you merge a deploy request and prevents blocking schema changes that can lead to downtime. This is different from the typical Prisma workflow which uses
prisma migrate in order to generate SQL migrations for you based on changes in your Prisma schema. When using PlanetScale with Prisma, the responsibility of applying the changes is on the PlanetScale side. Therefore, there is little value to using
prisma migrate with PlanetScale.
Also, the migrations table created when
prisma migrate runs can also be misleading since PlanetScale does the actual migration when the deploy request is merged, not when
prisma migrate is run which only updates the schema in the development database branch. You can still see the history of your schema changes in PlanetScale.
- Add Prisma to your project using
npm install prisma --save-devor
yarn add prisma --dev(depending on what package manager you prefer).
npx prisma initinside of your project to create the initial files needed for Prisma.
- Install the PlanetScale CLI.
- Authenticate the CLI with the following command:
Execute your first Prisma db push
Prisma migrations follow the PlanetScale non-blocking schema change workflow. First, the schema is applied to a development branch and then the development branch is merged into the
main production database.
Let's begin with an example flow for running Prisma migrations in PlanetScale:
- Create a new prisma-playground database:
- Connect to the database branch:
This step assumes you created a new PlanetScale database and the
has not been promoted to production yet. You will need to create a new development branch if
main branch has been promoted to production.
- Update your
prisma/schema.prismafile with the following schema:
- Update your
- In another terminal, use the
db pushcommand to push the schema defined in
prisma migrate dev command, it will not create a migrations folder containing a SQL file with the SQL used to update the schema in your PlanetScale database. PlanetScale will be tracking your migrations in this workflow.
You can learn more about the
prisma db push command in the
db push is successful, you can see the table created in your terminal. For example, to see the
exit command to exit the MySQL shell.
Or you can see it in the PlanetScale UI under the Schema tab in your
- Now that the initial schema has been added, promote your
mainbranch to production status:
Execute succeeding Prisma migrations in PlanetScale
Our first example migration flow went well, but what happens when you need to run further changes to your schema?
Let's take a look:
- Create a new development branch from
- Close the proxy connection to your
mainbranch (if still open) and connect to the new
- In the
prisma/schema.prismafile, update the
Add a new
subtitle field to
db pushagain to update the schema in PlanetScale:
- Open a deploy request for your
add-subtitle-to-postsbranch, so that you can deploy these changes to
You can complete the deploy request either in the web app or with the
pscale deploy-request command.
- Once the deploy request is merged, you can see the results in your main branch's
Now that you've successfully conducted your first automatic Prisma migration in PlanetScale and know how to handle future migrations, it's time to deploy your application with a PlanetScale database! Let's learn how to deploy an application with a PlanetScale database to Vercel.