Prisma ORM has released version 7. This version brings new ways to handle packages and database adapters. If you use Next.js, you need to know these changes to keep your app running well. This guide shows you how to install Prisma 7, set up a local PostgreSQL database, and connect to Supabase.
One of the main change is that Prisma moved away from the rust-engine and rebuilt in Typescript. Moving to a Rust-free client really set the stage for a faster client runtime, a smaller footprint, and simpler deployment story. You no longer needed to worry about runtime-specific quirks or infrastructure providers, like Cloudflare Workers, limiting the size of the deployed application. The continued on the path and kept iterating on what would become the Rust-free Prisma Client. The results?

• 90% smaller bundle output
• 3x faster query execution
• Significantly lower CPU and memory utilization
• Simpler deployments for Vercel Edge and Cloudflare Workers

Getting Started with Prisma 7

First, you need a Next.js project. Open your terminal in your project folder. You will start by installing the Prisma CLI. Use this command to install Prisma as a dev dependency:

npm install -D prisma

You can add @7 to the end if you want to be specific. Once the install finishes, check your package.json file. You should see Prisma version 7 listed under dev dependencies.

Now, initialize Prisma in your project:

npx prisma init

This command creates a new prisma folder. Inside, you will find a schema.prisma file. It also creates a .env file for your database secrets.

Connecting a Local Database

Open the .env file. You need to provide a database URL. For a local PostgreSQL setup, the URL looks like this:

postgresql://USER:PASSWORD@localhost:5432/DATABASE_NAME

Replace the placeholders with your actual database details. Make sure your local PostgreSQL service is running before moving forward.

Schema changes

The older prisma-client-js provider will be removed in future releases of Prisma ORM. Upgrade to the new prisma-client provider which uses the new Rust-free client. This will give you faster queries, smaller bundle size, and require less system resources when deployed to your server.

Additionally, the output field is now required in the generator block. Prisma Client will no longer be generated in node_modules by default. You must specify a custom output path.

//Schema.Prisma Before
generator client {
    provider = "prisma-client-js"
    engineType = "binary"
}

//After
generator client {
    provider = "prisma-client"
    output = "./generated/prisma"
}
//Additionally other fields such as url, directUrl, and shadowDatabaseUrl in the datasource block are deprecated.

Creating Your First Schema

Open schema.prisma. You need a model to store data. Here is a simple "User" model you can use:

//schema.prisma
generator client {
    provider = "prisma-client"
    output = "../src/generated/prisma"
    previewFeatures = ["relationJoins"]
}

datasource db {
    provider = "postgresql"
}

model User {
    id              Int              @id @default (autoincrement())
    username        String           @unique
    email           String           @unique
    password_digest String
    role            Role             @default (user)
    createdAt       DateTime         @default (now())
    updatedAt       DateTime         @updatedAt
    picture         String ?
    bio             String ?          @default ("This user has no bio")
}

After saving your schema, run the generate command:

npx prisma generate

This creates the Prisma Client. In version 7, this client is often stored in an src/generated folder. Next, push your schema to the database:

npx prisma db push

This command syncs your code with your database. You can view your data by running npx prisma studio. This opens a web tool at localhost:5555 to see your tables.

Prisma Config

One of the major breaking change in V7 is that now prisma requires a prisma.config.ts where you put your configuration insteading of adding the database url in the schema.

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_UNPOOLED"),
    },
});

Setting Up the Prisma Client with Adapters

Prisma 7 uses adapters to talk to the database. You should create a central file to hold your database connection. Create a folder named lib and a file inside called db.ts. You need to install the PostgreSQL adapter:

npm install @prisma/adapter-pg

In your db.ts file, you will set up a global Prisma instance. This prevents your app from opening too many connections during development. Here is how the setup looks:

1. Import PrismaClient from your generated folder.
2. Import PrismaPg from the adapter package.
3. Set up the adapter using your database connection.
4. Export the Prisma instance.

// lib/db.ts
import { PrismaClient } from '@prisma/client';
import { PrismaPg } from '@prisma/adapter-pg';
import { Client } from 'pg';
const connectionString = `${process.env.DATABASE_URL}`;
const client = new Client({ connectionString });
const adapter = new PrismaPg(client);
const prisma = new PrismaClient({ adapter });
export default prisma;

Fetching Data in Next.js

To show data on your website, go to your page.tsx file. You must make the component an async function. This allows you to wait for the database to respond. Import your database instance from the lib folder. Inside the component, fetch your posts like this:

  // app/page.tsx
  import prisma from '@/lib/db';
  async function PostsPage() {
  const posts = await prisma.post.findMany();
  return ( Posts {posts.map((post) => ({post.title} {post.content}{post.createdAt.toISOString()}))}
  );
}
export default PostsPage;

If you see errors, make sure you installed the Prisma Client package:

npm install @prisma/client

Both the CLI and the Client must be on version 7. If they match, your app will load the data from your database and show it on the screen.

Connecting to Supabase

Supabase is a great choice for hosting your database online. Create a new project on the Supabase website. Once your project is ready, follow these steps:

• Go to the Connect settings.
• Select ORMs and choose Prisma.
• Copy the connection string provided.
• Update your .env file with the new URL.

Handling Direct URLs

Supabase often provides a "Direct URL" for migrations. In your schema.prisma file, you might need to add a directUrl field in the datasource block. This helps Prisma manage the database schema without using a connection pooler.

datasource db {
    provider = "postgresql"
    url = env("DATABASE_URL")
    shadowDatabaseUrl = env("DIRECT_URL")
}

Run npx prisma db push again to set up your tables on Supabase. You can then add a row of data in the Supabase dashboard. Refresh your Next.js app, and the new data will appear.

Conclusion

Setting up Prisma 7 requires a few more steps than older versions. You must install the right adapters and the latest client package. By following these steps, you create a strong foundation for your Next.js app. Using Prisma Studio and Supabase makes it easy to manage your data. Always remember to run the generate command after you change your schema. This ensures your code knows exactly what your database looks like. Try adding a new model to your schema today to practice your skills!

Resources

Read about the changes in Prisma 7 in their official page: Upgrade to Prisma ORM 7 | Prisma Documentation