Guide to using Prisma with PlanetScale

content/300-guides/050-database/500-using-prisma-with-planetscale.mdx

@@ -0,0 +1,181 @@
+---
+title: 'Using Prisma with PlanetScale'
+metaTitle: 'Using Prisma with PlanetScale'
+metaDescription: 'Guide to using Prisma with PlanetScale'
+tocDepth: 2
+toc: true
+---
+
+<TopBlock>
+
+Prisma and [PlanetScale](https://planetscale.com/) together provide a development arena that optimizes rapid, type-safe development of data access applications, using Prisma's ORM and PlanetScale's highly scalable MySQL-based platform.
+
+This document discusses the concepts behind using Prisma and PlanetScale, explains the commonalities and differences between PlanetScale and other database providers, and leads you through the process for configuring your application to integrate with PlanetScale.
+
+</TopBlock>
+
+## What is PlanetScale?
+
+PlanetScale uses the [Vitess](https://vitess.io/) database clustering system to provide a MySQL-compatible database platform. Features include:
+
+- **Enterprise scalability.** PlanetScale provides a highly available production database cluster that supports scaling across multiple database servers.
+
+- **Database branches.** PlanetScale allows you to create [branches of your database schema](https://docs.planetscale.com/concepts/branching), so that you can test changes on a development branch before applying them to your production database.
+
+- **Support for non-blocking schema changes.** PlanetScale provides a workflow that allows users to update database schemas without locking the database or causing downtime.
+
+## Commonalities with other database providers
+
+Many aspects of using Prisma with PlanetScale are just like using Prisma with any other relational database. You can still:
+
+- model your database with the [Prisma Schema Language](/concepts/components/prisma-schema)
+- use Prisma's existing [`mysql` database connector](/concepts/database-connectors/mysql) in your schema, along with the [connection string PlanetScale provides you](https://docs.planetscale.com/concepts/connection-strings)
+- use [Introspection](/concepts/components/introspection) for existing projects if you already have a database schema in PlanetScale
+- use [`db push`](/concepts/components/prisma-migrate/db-push) to push changes in your schema to the database
+- use [Prisma Client](/concepts/components/prisma-client) in your application to talk to the database server at PlanetScale
+
+## Differences to consider
+
+PlanetScale's branching model and design for scalability means that there are also a number of differences to consider. You should be aware of the following points when deciding to use PlanetScale with Prisma:
+
+- **Referential integrity.** To support scaling across multiple database servers, PlanetScale [does not allow the use of foreign key constraints](https://docs.planetscale.com/tutorials/operating-without-foreign-keys), which are normally used in relational databases to enforce relationships between data in different tables. To maintain these relationships in your data while using PlanetScale with Prisma, you will need to use Prisma's ability to [emulate referential integrity in the Prisma client](https://www.prisma.io/docs/concepts/components/prisma-schema/relations/referential-integrity#handling-the-referential-integrity-in-prisma). For more information, see [How to enable emulation of referential integrity](#how-to-enable-emulation-of-referential-integrity).
+
+- **Branching and deploy requests.** PlanetScale provides two types of database branches: **development branches**, which allow you to test out schema changes, and **production branches**, which are protected from direct schema changes. Production branches are highly available and include automated daily backups. Once you are happy with the changes you make on a development branch, you can create a deploy request, which you can then review before deploying the changes to production. To learn more, see [How to use branches and deploy requests](#how-to-use-branches-and-deploy-requests).
+
+- **Creating indexes on foreign keys.** In a standard MySQL database, if a table has a column with a foreign key constraint, an index is automatically created on that column. As PlanetScale does not support foreign keys, these indexes are not created which can lead to issues with queries not being well optimised. To avoid this, you can create indexes in Prisma. For more information, see [How to create indexes on foreign keys](#how-to-create-indexes-on-foreign-keys).
+
+- **Making schema changes with `db push`.** When you merge a development branch into your production branch, PlanetScale will automatically compare the two schemas and generate its own migration path. This means that Prisma's [`prisma migrate`](/concepts/components/prisma-migrate) workflow, which generates its own history of migration files, is not a natural fit when working with PlanetScale. These migration files may not reflect the actual schema changes run by PlanetScale when the branch is merged.
+
+  <Admonition type="warning">
+    Instead, Prisma recommends you use the `prisma db push` command when making
+    schema changes with PlanetScale.
+  </Admonition>
+
+  For an example of how this works, see [How to make schema changes with `db push`](#how-to-make-schema-changes-with-db-push)
+
+## How to enable emulation of referential integrity
+
+Referential integrity is currently a Preview feature. To enable this, add it to the `previewFeatures` list in the `generator` block of `schema.prisma`, and set the `referentialIntegrity` type to `"prisma"` in the `datasource` block:
+
+```prisma file=schema.prisma
+datasource db {
+  provider             = "mysql"
+  url                  = env("DATABASE_URL")
+  referentialIntegrity = "prisma"
+}
+
+generator js {
+  provider        = "prisma-client-js"
+  previewFeatures = ["referentialIntegrity"]
+}
+```
+
+## How to use branches and deploy requests
+
+When connecting to PlanetScale with Prisma, you will need to use the correct connection string for your branch. The connection URL for a given database branch can be found from your PlanetScale account by going to the overview page for the branch and selecting the 'Connect' dropdown. In the 'Passwords' section, generate a new password and select 'Prisma' from the dropdown to get the Prisma format for the connection URL.
+
+See Prisma's [Getting Started guide](/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-typescript-planetscale) for more details of how to connect to a PlanetScale database.
+
+## How to create indexes on foreign keys
+
+As an example of a situation where you would want to an add an index, take this schema for a blog with posts and comments:
+
+```prisma file=schema.prisma
+model Post {
+  id       Int       @id @default(autoincrement())
+  title    String
+  content  String
+  likes    Int       @default(0)
+  comments Comment[]
+}
+
+model Comment {
+  id      Int    @id @default(autoincrement())
+  comment String
+  postId  Int
+  post    Post   @relation(fields: [postId], references: [id], onDelete: Cascade)
+}
+```
+
+The `postId` field in the `User` model refers to the corresponding `id` field in the `Post` model. However this is not implemented as a foreign key in PlanetScale, so it doesn't have an index. This means that some queries may not be well optimised. For example, if you query for all comments with a certain post `id`, PlanetScale may have to do a full table lookup, which could be slow and expensive.
+
+To avoid this, you can define an index on the `postId` field using [Prisma's `@@index` argument](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#index):
+
+```prisma file=schema.prisma highlight=15;add
+model Post {
+  id       Int       @id @default(autoincrement())
+  title    String
+  content  String
+  likes    Int       @default(0)
+  comments Comment[]
+}
+
+model Comment {
+  id      Int    @id @default(autoincrement())
+  comment String
+  postId  Int
+  post    Post   @relation(fields: [postId], references: [id], onDelete: Cascade)
+
+  @@index([postId])
+}
+```
+
+You can then add this change to your schema [using `db push`](#how-to-make-schema-changes-with-db-push).
+
+## How to make schema changes with `db push`
+
+As an example, let's say you decide to change the name of the `likes` field to `reactions`:
+
+```prisma file=schema.prisma highlight=5;edit
+model Post {
+  id        Int       @id @default(autoincrement())
+  title     String
+  content   String
+  reactions Int       @default(0)
+  comments  Comment[]
+}
+
+model Comment {
+  id      Int    @id @default(autoincrement())
+  comment String
+  postId  Int
+  post    Post   @relation(fields: [postId], references: [id], onDelete: Cascade)
+
+  @@index([postId])
+}
+```
+
+This will actually be implemented by PlanetScale in the database by dropping the `likes` column and adding a `reactions` column.
+
+To push these changes, run
+
+```terminal
+npx prisma db push
+```
+
+in the terminal from your project directory.
+
+## More on using PlanetScale with Prisma
+
+The fastest way to start using PlanetScale with Prisma is to refer to our Getting Started documentation:
+
+- [Start from scratch](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-planetscale)
+
+- [Add to existing project](https://www.prisma.io/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-planetscale)
+
+These tutorials will take you through the process of connecting to PlanetScale, pushing schema changes, and using the Prisma Client.
+
+For further tips on best practices when using Prisma and PlanetScale together, watch our video:
+
+<div class="videoWrapper">
+
+<iframe
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/iaHt5_hg44c"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+</div>