From v1

This guide helps you migrate from Prisma 1 to Prisma ORM version 2.x and later.

Main differences between Prisma 1 and Prisma ORM 2+

Prisma ORM 2.x and later versions:

• Don't require hosting a database proxy server (i.e., the Prisma server)
• Make the features of Prisma 1 more modular with dedicated tools:
  • Prisma Client: An improved version of Prisma Client 1.0
  • Prisma Migrate: Data modeling and migrations (formerly prisma deploy)
• Use the Prisma schema, a merge of Prisma 1 datamodel and prisma.yml
• Use its own modeling language instead of being based on GraphQL SDL
• Don't expose a GraphQL API for your database—only allow programmatic access via Prisma Client
• Allow connecting to any existing database via more powerful introspection

Upgrade strategies

There are two main upgrade strategies:

1. Upgrade all at once: Entirely remove Prisma 1 from your project and move everything over to Prisma ORM 2+ at once. Recommended for projects not yet in production or with little traffic.

2. Gradual upgrade side-by-side: Add Prisma ORM 2+ to the existing Prisma 1 project and gradually replace existing Prisma 1 features while running them side-by-side. Recommended for high-traffic production applications.

Upgrade path overview

1. Install the Prisma ORM 2+ CLI as a development dependency
2. Create your Prisma schema and configure the database connection URL
3. Use the Prisma CLI to introspect your Prisma 1 database and generate your Prisma schema
4. Run the Prisma 1 Upgrade CLI to fix schema incompatibilities
5. Install and generate Prisma Client
6. Adjust your application code, replacing Prisma Client 1.0 API calls with Prisma Client 2+ API calls

Schema incompatibilities

The database schema created by Prisma 1's prisma deploy is only partially compatible with Prisma ORM 2+. Here's an overview of common incompatibilities:

Using the Prisma 1 Upgrade CLI

The Prisma 1 Upgrade CLI helps you apply workarounds for schema incompatibilities. It generates SQL statements to fix the database schema and make it compatible with Prisma ORM 2+.

Initial setup

1. Set up Prisma ORM by installing the CLI and running npx prisma init
2. Connect to your database and introspect it with npx prisma db pull

Fixing schema incompatibilities

1. Invoke the Upgrade CLI with npx prisma-upgrade
2. Run the generated SQL commands against your database
3. Run prisma db pull again
4. Run npx prisma-upgrade again
5. The Upgrade CLI adjusts the Prisma schema by adding missing attributes

The Upgrade CLI is designed so you can stop and restart the process at any time. Once you run a SQL command, it won't show up the next time you invoke the Upgrade CLI.

Upgrading your application layer

After upgrading the Prisma layer, you need to update your application code. Choose the appropriate guide based on your current setup:

• GraphQL Nexus users: Replace the old nexus-prisma plugin with the new nexus-plugin-prisma
• prisma-binding users: Migrate to either Nexus or SDL-first GraphQL
• REST API users: Replace Prisma Client 1.0 calls with Prisma Client 2+ calls

Feature parity notes

Prisma ORM 2+ does not have full feature parity with Prisma 1. The main missing feature is:

• Real-time API (Subscriptions): Prisma ORM 2+ doesn't have built-in database subscriptions. For real-time functionality, consider using native database triggers or triggering GraphQL subscriptions manually inside mutation resolvers.

Getting help

If you encounter issues during migration:

1. Check the Prisma 1 Upgrade CLI repository for known issues
2. Visit the Prisma Discord for community support
3. Open an issue on GitHub for bugs