Upgrade to v1

This guide covers migrating your project from Prisma 1 to Prisma ORM 7, the last release built on the schema.prisma workflow. Once you are on Prisma ORM 7, continue with the Prisma ORM 7 to 8 guide. The migration involves significant architectural changes, so plan it and test it in a separate environment before touching production.

Before you begin

Back up your database before starting the migration
Review the Prisma ORM documentation to understand the new architecture
Set up a separate development environment for testing the migration
Document your current Prisma 1 setup, including models, relations, and any custom configurations

Key changes

Architectural changes

Feature	Prisma 1	Prisma ORM
Database Connection	Uses Prisma Server as a proxy	Direct database connection
API	GraphQL API for database	Programmatic access via Prisma Client
Schema	GraphQL SDL + `prisma.yml`	Unified Prisma schema
Modeling	GraphQL SDL	Prisma Schema Language (PSL)
Workflow	`prisma deploy`	`prisma migrate` and `prisma db` commands

Feature changes

Removed: GraphQL API for database
New: Type-safe database client
Improved: Database introspection and migration tools
Improved: Support for more database features and types

Migration Strategy

1. Preparation

Install Prisma ORM

title="bun"

# Initialize a new project

bun init

bun add prisma@prev @prisma/client@7

# Initialize Prisma

bunx --bun prisma init

pnpm

# Initialize a new project
pnpm init
pnpm add prisma@prev @prisma/client@7

# Initialize Prisma
pnpm prisma init

yarn

# Initialize a new project
yarn init
yarn add prisma@prev @prisma/client@7

# Initialize Prisma
yarn prisma init

npm

# Initialize a new project
npm init
npm install prisma@prev @prisma/client@7

# Initialize Prisma
npx prisma init

Set up Database Connection

Update the DATABASE_URL in your .env file to point to your existing database:

DATABASE_URL="postgresql://user:password@localhost:5432/your_database?schema=public"

2. Schema Migration

Introspect Database

title="bun"

bunx prisma db pull

pnpm

pnpm prisma db pull

yarn

yarn prisma db pull

npm

npx prisma db pull

This will generate a schema.prisma file based on your existing database schema.

Update Schema

After introspection, you'll need to make several adjustments to the schema:

Default Values

// Before (Prisma 1)

model User {

  id        String   @default(cuid())

  email     String   @unique

  name      String?

  createdAt DateTime @default(now())

  updatedAt DateTime @updatedAt

}

Relations

// Before (Prisma 1)

type Post {

  id        ID!      @id

  title     String!

  author    User!    @relation(name: "UserPosts")

}

// After (Prisma ORM)

model Post {

  id        Int      @id @default(autoincrement())

  title     String

  author    User     @relation(fields: [authorId], references: [id])

  authorId  Int

}

3. Data Model Adjustments

3.1 Handling Special Types

Prisma 1 Type	Prisma ORM Equivalent	Notes
`ID`	`String @id @default(cuid())`	Add `@id` directive
`DateTime`	`DateTime`	No change needed
`Json`	`Json`	No change needed
`Enum`	`Enum`	Define enums in the schema

3.2 Relation Handling

Prisma ORM requires explicit relation fields and foreign keys:

model User {

  id    Int     @id @default(autoincrement())

  posts Post[]

}

model Post {

  id       Int    @id @default(autoincrement())

  title    String

  author   User   @relation(fields: [authorId], references: [id])

  authorId Int

}

4. Update Application Code

4.1 Replace Prisma 1 Client with Prisma Client

// Before (Prisma 1)

import { prisma } from './generated/prisma-client';

async function getUser(id: string) {

  return prisma.user({ id });

}

// After (Prisma ORM)

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function getUser(id: number) {

  return prisma.user.findUnique({

    where: { id }

  });

}

4.2 Update Queries and Mutations

Fetching Data

// Before (Prisma 1)

const user = await prisma.user({ id: 1 });

const posts = await prisma.user({ id: 1 }).posts();

// After (Prisma ORM)

const user = await prisma.user.findUnique({

  where: { id: 1 },

  include: { posts: true }

});

const posts = user?.posts;

Creating Records

// Before (Prisma 1)

const newUser = await prisma.createUser({

  name: 'Alice',

  email: 'alice@example.com'

});

// After (Prisma ORM)

const newUser = await prisma.user.create({

  data: {

    name: 'Alice',

    email: 'alice@example.com'

  }

});

Testing and Validation

1. Test Data Operations

Test all CRUD operations to ensure data consistency:

// Test create

const user = await prisma.user.create({

  data: { name: 'Test', email: 'test@example.com' }

});

// Test read

const foundUser = await prisma.user.findUnique({

  where: { id: user.id }

});

// Test update

const updatedUser = await prisma.user.update({

  where: { id: user.id },

  data: { name: 'Updated Name' }

});

// Test delete

await prisma.user.delete({

  where: { id: user.id }

});

2. Test Relations

Verify that all relations work as expected:

// Test relation queries

const userWithPosts = await prisma.user.findUnique({

  where: { id: 1 },

  include: {

    posts: true,

    profile: true

  }

});

// Test nested writes

const userWithNewPost = await prisma.user.create({

  data: {

    name: 'Bob',

    email: 'bob@example.com',

    posts: {

      create: {

        title: 'Hello World',

        content: 'This is my first post'

      }

    }

  },

  include: {

    posts: true

  }

});

Handling Special Cases

1. Real-time Subscriptions

Prisma ORM doesn't include built-in real-time subscriptions. Consider these alternatives:

Option 1: Database Triggers

-- PostgreSQL example

CREATE OR REPLACE FUNCTION notify_new_post()

RETURNS TRIGGER AS $$

BEGIN

  PERFORM pg_notify('new_post', row_to_json(NEW)::text);

  RETURN NEW;

END;

$$ LANGUAGE plpgsql;

CREATE TRIGGER new_post_trigger

AFTER INSERT ON "Post"

FOR EACH ROW EXECUTE FUNCTION notify_new_post();

Option 2: Application-Level Events

// Publish event when creating a post

const post = await prisma.post.create({

  data: {

    title: 'New Post',

    content: 'Content',

    author: { connect: { id: userId }}

  }

});

// Publish event to your pub/sub system

await pubsub.publish('POST_CREATED', { postCreated: post });

2. Authentication

If you were using Prisma 1's built-in authentication, you'll need to implement your own solution:

import { compare } from 'bcryptjs';

import { sign } from 'jsonwebtoken';

export async function login(email: string, password: string) {

  const user = await prisma.user.findUnique({ where: { email } });

  if (!user) throw new Error('User not found');

  

  const valid = await compare(password, user.password);

  if (!valid) throw new Error('Invalid password');

  

  const token = sign({ userId: user.id }, process.env.APP_SECRET!);

  return { token, user };

}

Migration Tools

Prisma 1 Upgrade CLI

The Prisma 1 Upgrade CLI can help automate parts of the migration:

title="bun"

# Install the upgrade CLI

bun add --global prisma1-upgrade

# Run the upgrade helper

prisma1-upgrade

pnpm

# Install the upgrade CLI
pnpm add -g prisma1-upgrade

# Run the upgrade helper
prisma1-upgrade

yarn

# Install the upgrade CLI
yarn global add prisma1-upgrade

# Run the upgrade helper
prisma1-upgrade

npm

# Install the upgrade CLI
npm install -g prisma1-upgrade

# Run the upgrade helper
prisma1-upgrade

This tool helps with:

Converting your Prisma 1 datamodel to Prisma schema
Identifying potential issues in your schema
Providing migration recommendations

Performance Considerations

Connection Pooling: Configure a connection limit so the client does not exhaust your database connections:

const prisma = new PrismaClient({

  log: ['query', 'info', 'warn', 'error'],

  datasources: {

    db: {

      url: process.env.DATABASE_URL + '&connection_limit=20'

    }

  }

});

Query Optimization: Use select to fetch only needed fields:

const user = await prisma.user.findUnique({

  where: { id: 1 },

  select: {

    id: true,

    name: true,

    email: true

  }

});

Next Steps

Your project now runs on Prisma ORM 7. To move to the current release, follow the Prisma ORM 7 to 8 guide (or the MongoDB version).

Getting Help

If you encounter issues during migration:

Search the GitHub Issues
Ask for help in the Prisma Slack
Open a GitHub Discussion