Using Prisma with a PlanetScale database

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!

[bigint]

This is finally available 🎉

https://twitter.com/planetscaledata/status/1427371097352069120

[janpio]

I just updated the post:

• with the brand new Automatic schema migrations feature PlanetScale launched today, that includes support for Prisma’s _prisma_migrations table that holds the migration meta information. With that it is now much easier to use Prisma Migrate on branches, and then use PlanetScale’s deploy requests to merge the schema changes back to the main branch. Nice - thanks @planetscale 💚