PlanetScale

PlanetScale is a serverless database platform. This guide covers both PlanetScale MySQL and PlanetScale Postgres. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to PlanetScale using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database.

Prerequisites

You also need:

• A PlanetScale account
• A PlanetScale database (MySQL or Postgres)
• Database connection credentials from PlanetScale

1. Create a new project

mkdir hello-prisma
cd hello-prisma

Initialize a TypeScript project:

npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

2. Install required dependencies

Install the packages needed for this quickstart:

MySQL

npm install prisma @types/node --save-dev
npm install @prisma/client @prisma/adapter-planetscale undici dotenv

Postgres

npm install prisma @types/node @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

3. Configure ESM support

Update tsconfig.json for ESM compatibility:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0"
  }
}

Update package.json to enable ESM:

{
  "type": "module"
}

4. Initialize Prisma ORM

You can now invoke the Prisma CLI by prefixing it with npx:

npx prisma

Next, set up your Prisma ORM project by creating your Prisma Schema file with the following command:

MySQL

npx prisma init --datasource-provider mysql --output ../generated/prisma

Postgres

npx prisma init --datasource-provider postgresql --output ../generated/prisma

This command does a few things:

• Creates a prisma/ directory with a schema.prisma file containing your database connection and schema models
• Creates a .env file in the root directory for environment variables
• Creates a prisma.config.ts file for Prisma configuration

The generated prisma.config.ts file looks like this:

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

The generated schema uses the ESM-first prisma-client generator with a custom output path:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

5. Configure your connection

Update your .env file with your PlanetScale connection string:

DATABASE_URL="mysql://username:password@host.connect.psdb.cloud/mydb?sslaccept=strict"

Replace with your actual PlanetScale credentials from your database dashboard.

6. Define your data model

Open prisma/schema.prisma and add the following models:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

model User { 
  id    Int     @id @default(autoincrement()) 
  email String  @unique
  name  String?
  posts Post[]
} 

model Post { 
  id        Int     @id @default(autoincrement()) 
  title     String
  content   String? @db.Text
  published Boolean @default(false) 
  author    User    @relation(fields: [authorId], references: [id]) 
  authorId  Int

  @@index([authorId]) 
} 

7. Apply your schema to the database

MySQL

npx prisma db push

Postgres

npx prisma migrate dev --name init

This command creates the database tables based on your schema.

Now run the following command to generate the Prisma Client:

npx prisma generate

8. Instantiate Prisma Client

Now that you have all the dependencies installed, you can instantiate Prisma Client. You need to pass an instance of the Prisma ORM driver adapter adapter to the PrismaClient constructor:

import "dotenv/config";
import { PrismaPlanetScale } from "@prisma/adapter-planetscale";
import { PrismaClient } from "../generated/prisma/client";
import { fetch as undiciFetch } from "undici";

const adapter = new PrismaPlanetScale({ url: process.env.DATABASE_URL, fetch: undiciFetch });
const prisma = new PrismaClient({ adapter });

export { prisma };

9. Write your first query

Create a script.ts file to test your setup:

import { prisma } from "./lib/prisma";

async function main() {
  // Create a new user with a post
  const user = await prisma.user.create({
    data: {
      name: "Alice",
      email: "alice@prisma.io",
      posts: {
        create: {
          title: "Hello World",
          content: "This is my first post!",
          published: true,
        },
      },
    },
    include: {
      posts: true,
    },
  });
  console.log("Created user:", user);

  // Fetch all users with their posts
  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
    },
  });
  console.log("All users:", JSON.stringify(allUsers, null, 2));
}

main()
  .then(async () => {
    await prisma.$disconnect();
  })
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    process.exit(1);
  });

Run the script:

npx tsx script.ts

You should see the created user and all users printed to the console!

10. Explore your data with Prisma Studio

Prisma Studio is a visual editor for your database. Launch it with:

npx prisma studio

Next steps

You've successfully set up Prisma ORM. Here's what you can explore next:

• Learn more about Prisma Client: Explore the Prisma Client API for advanced querying, filtering, and relations
• Database migrations: Learn about Prisma Migrate for evolving your database schema
• Performance optimization: Discover query optimization techniques
• Build a full application: Check out our framework guides to integrate Prisma ORM with Next.js, Express, and more
• Join the community: Connect with other developers on Discord

More info

• Prisma Config reference
• Database connection management
• PlanetScale documentation