Using Prisma with a PlanetScale database

[janpio]

UPDATE

As of 27.10.2022, the details in this issue are outdated.

Refer to https://www.prisma.io/docs/guides/database/using-prisma-with-planetscale for the latest instructions on using Prisma with PlanetScale.

Outdated Issue content

PlanetScale is a new and interesting cloud database based on MySQL. It's exciting!

PlanetScale is a bit different than other MySQL database providers though:

1. No support for foreign keys. This is challenging for Prisma users, as Prisma by default uses foreign keys to express relations.
2. No creation of additional databases using CREATE DATABASE but need to use their tooling (web UI or CLI). This can be challenging, as some development commands of Prisma like prisma migrate dev create temporary databases in the background.
3. No schema changes on your production database (but make them on branches, then merge the schema changes back). This is challenging for Prisma users, as usually they run Migrations against their database directly via prisma migrate deploy or prisma db push.

---

Here is how you can use Prisma and PlanetScale together anyway:

1. No foreign keys / No Prisma Migrate (migrate dev and db push)

   • Problem: PlanetScale does not allow foreign keys in the database schema (ERROR 70100 (1317): foreign key constraints are not allowed, see https://code.openark.org/blog/mysql/the-problem-with-mysql-foreign-key-constraints-in-online-schema-changes), which Prisma relies on for relations.
   • Starting with 2.27.0 Prisma catches the error and outputs a helpful error message (that currently redirects here)
   • Workaround starting with 3.1.1: Use the preview feature referentialIntegrity and the datasource propertly referentialIntegrity = "prisma" to enable a mode that automatically leaves out foreign keys in migrations:

     generator client {
       provider        = "prisma-client-js"
       previewFeatures = ["referentialIntegrity"]
     }
     
     datasource db {
       provider             = "mysql"
       url                  = env("DATABASE_URL")
       shadowDatabaseUrl    = env("SHADOW_DATABASE_URL")
       referentialIntegrity = "prisma"
     }
     
     ...
     

     You can now properly use prisma migrate dev and prisma db push ✅
     (Between 2.24.0 and 3.1.1 the setting was called planetScaleMode = true and hidden behind the preview feature flag planetScaleMode)

2. If you are using migrate dev to migrate: No CREATE DATABASE / No automatic shadow database creation

   • Problem: PlanetScale does not allow creating new databases with CREATE DATABASE, which Prisma Migrate prefers to use for the shadow database of Prisma Migrate.
   • Solution: Create a branch shadow or similar and open put its connection string as shadowDatabase of your datasource in schema.prisma ✅

     datasource db {
       provider             = "mysql"
       url                  = env("DATABASE_URL")
       shadowDatabaseUrl    = env("SHADOW_DATABASE_URL")
       referentialIntegrity = "prisma"
     }
     

   • Potential improvement: Catch error thrown if you try anyway and output better error message with link to documentation.

3. If you are using migrate dev to migrate: Prisma migration table is not copied to main by default

   • PlanetScale now has a setting "Automatic schema migrations" that enables this behavior:
     
     As you can see Prisma is one of the default options, and enabling this option and choosing Prisma makes sure that the content of the migration table _prisma_migrations is copied from the branch to main with the deploy request. 🥳

4. No schema changes on production branches

   • Problem: PlanetScale does not allow schema changes on the production branch of the database (ERROR HY000 (1105): direct DDL is disabled), which Prisma Migrate tries to do if you tell it to.
   • Starting with 2.27.0 Prisma catches the error and outputs a helpful error message (that currently redirects here)
   • Solution: Only execute Prisma Migrate on non production branches, then use a PlanetScale "deploy request" to merge the schema changes to your main ✅

We are very excited for you to try PlanetScale with Prisma. If you hit any bumps, let us know either here or in new issues or discussions in our repository. Thanks!

[heymartinadams]

Holy sh*t @janpio — that’s awesome of you to put this together! Thank you! 💚

We’ll stick with AWS for now until PlanetScale is a bit more out of beta and has enabled serverless deployment connections.

[janpio]

I updated the original post:

• More concrete instructions on how do work get the shadow database working (which works great!)
• Added a "Potential improvement" point to all problems, to show and communicate what we are thinking about right now

[janpio]

I updated the original post:

• Improved formatting and added error message for google-ability
• Added links to the two "Potential improvements" we have planned on our side
• Mentioned our brand new workaround planetScaleMode = true for the "No foreign keys" problem in Prisma Migrate (added in 2.24.0)

[bigint]

Planetscal serverless is available now 🎉

https://vercel.com/integrations/planetscale