Prisma with PlanetScale quickstart
Learn how to integrate Prisma with PlanetScale
This guide will show you how to:
- Create a database with PlanetScale
- Integrate into a Next.js + Prisma application
Set up your PlanetScale database
Create a PlanetScale database
Once you're signed in, click on the "Create a database" button. Name your database
star-app, select the region closest to you, and click "Create database".
You can also use the PlanetScale CLI to create a database by running the following command:
REGION value, choose the region closest to you or your application's hosting location. You can find our regions and their slugs on the Regions page. If you do not specify a region, your database will automatically be deployed to US East - Northern Virginia.
Your database will deploy with an initial development branch,
Set up branches
Now that you have your PlanetScale database set up, you need to create a development branch to connect to your Prisma application.
Click on your
star-app database in the dashboard, and then click on the "Branches" tab in the top nav.
From here, click the "New branch" button. Name the branch
main as the base branch, select the region closest to you, and click "Create branch".
Or, to create the
initial-setup branch in the CLI, run the following command:
The new branch will default to the same region that was selected for
Set up Next.js app
Next, you need to set up your Next.js application. If you have an existing app, you can use that. Otherwise, instantiate a new Next app by running the following:
We are going to use npm in this quickstart, but you can also use yarn if you prefer.
Give your project a name (this tutorial is using
star-app). This will install the project with the
Once it's finished, enter into the project folder:
Now that you have your Next.js application ready, it's time to integrate Prisma.
First, you'll need to add the Prisma CLI as a development dependency to your project.
Next, you'll need to install the Prisma Client. In your
star-app directory, run the following command:
Then you need to set up your Prisma files. You can do this by running:
This creates the
prisma directory with a file named
schema.prisma. This file will hold your Prisma schema configuration, which includes your data sources (PlanetScale), generators (Prisma Client), and data models.
Open up the
prisma/schema.prisma file and paste in the following:
Next, you need to modify your environment variables to set the Prisma data source. Open up
.env at the root of your application and replace its contents with the following:
Connect to PlanetScale
Now you need to locally proxy into your PlanetScale database branches using the PlanetScale CLI. In a seperate terminal, run the following commands:
Keep this connection running. This establishes a secure connection to PlanetScale and listens on the specified local port. In the terminal, you'll see a local address returned. You can use this to connect to a MySQL client if you'd like.
Push Prisma schema to PlanetScale
Now it's time to push your Prisma schema. In a new terminal tab, run the following command:
The recommended workflow with using Prisma alongside PlanetScale is to use
prisma db push instead of
prisma migrate. You can read more about
prisma db push here.
Once this is successful, your PlanetScale database schema now matches the Prisma schema you configured in
View your schema in PlanetScale
You can confirm it worked in your PlanetScale dashboard or with the CLI.
- Select the
- Click on the "Branches" tab
- Click on "Schema"
- Click the "Refresh Schema" button
You should see one table:
And just like that, you have your development branch with your Prisma schema hosted on PlanetScale.
To view your database, you can use the PlanetScale CLI to open a MySQL shell where you can view your tables and schema. Run the following command:
Once you're in the MySQL shell, run the following:
You should see the
Star table. To view the
Star schema, run the following:
You can exit the shell by running:
Next, you need to add some data. You have several different options here. This tutorial will cover adding data using three different methods:
- Console in the PlanetScale dashboard
- PlanetScale CLI
- Prisma Studio
Option 1: Add data in PlanetScale dashboard console
In your PlanetScale dashboard, click on the
star-app database, select the
initial-setup branch, and click on the "Console" tab. This will let you run queries on your development database branch.
Star table is currently empty. To add some data, type in the following and press enter:
To confirm that it was added, run:
Option 2: Add data with PlanetScale CLI
To accomplish this same thing in the PlanetScale CLI, run the following in your terminal to enter into the MySQL shell:
Next, add a new star to the
Star table with:
To confirm it was added, run:
You can exit the shell by running:
Option 3: Add data with Prisma Studio
If you prefer a visual interface, you can also add data using Prisma Studio.
In your terminal, run the following to open up Prisma Studio:
This will open Prisma Studio locally in your browser. Click on the "Add record" button.
You can leave
updatedAt blank as they will auto-fill with default values. Fill in
constellation as follows:
To add the record, click the green "Save 1 change" button.
Prisma Studio showing the Star table with one record
Add an API route
Now that you have some data, you need to add a simple
GET endpoint in your Next.js app to retrieve it.
Back in your code editor, create a new file at
pages/api/stars.js and paste in the following:
Next, you need create a file at
lib/prisma.js. This will allow you to reuse the Prisma client. Paste in the following code:
Finally, start up your Next application by running the following:
You can now see all your
Star table data at
Deploy development branch to production
Currently, you're working on the development branch
initial-setup, which is branched off of the
main branch. The
initial-setup development branch is meant for applying schema changes and testing your migrations before you go to production.
Once you're happy with the
initial-setup branch, you can roll it up to the production branch. To do this, you first need to promote the
main branch to production. This
main branch is currently empty, but once it's set as the production branch, you'll be able to roll your changes from
initial-setup into it.
main to production:
- Go back to your
star-appdatabase in the PlanetScale dashboard
- Click on the
mainbranch under "Branches"
- Click on the "Promote branch" button
- Click "Promote branch" to confirm
main branch is now in production! A production branch protects you from direct schema changes, gives you high availability, and has automatic scheduled backups.
This production branch is currently empty. You can confirm this by going to the
main branch and clicking on the "Schema" tab. Let's fix that.
Create a deploy request
The final step in this process is to roll out your changes in your
initial-setup branch to production. To do this, you need to create a deploy request to your
main production branch.
In the dashboard, select the
initial-setup branch. On the "Overview" tab, you'll see the option to "Create a deploy request". Make sure
main is selected in the "Deploy to" dropdown, type in a comment to go with your deploy request, and click "Create deploy request".
PlanetScale will check to make sure there are no conflicts between the two branches. If not, you'll get the message "This deploy request is deployable". You can click on the "Schema changes" tab to see a diff of the schema changes to be deployed.
Example of the Star table schema in a deploy request on PlanetScale
Now, you're ready to deploy the
initial-setup branch to production! On the "Summary" tab of the deploy request, click the button "Add changes to deploy queue". The deployment has now been added to the deploy queue.
Once it's done deploying, you'll get a success message, "These changes have been deployed".
To verify that it worked correctly, go back to your
main branch and click on "Schema". You should now see the
Now that you have your Next.js application with a database in production on PlanetScale, you may want to deploy the entire application. You can deploy to Vercel in just a few easy steps by following our Deploy to Vercel guide.