Getting started with Prisma Optimize

Prerequisites

Before you begin with Prisma Optimize, ensure you have the following:

A Prisma Data Platform account.
A project using Prisma Client version 5.0.0 or higher (we recommend using the latest version).
A PostgreSQL, MySQL/MariaDB, CockroachDB, or MS SQL Server database.

Prisma Optimize is intended for use in local environments. Learn more in the FAQ.

1. Launch Optimize

Log in to your Prisma Data Platform account.
Follow the instructions
to access and launch Prisma Optimize.

2. Add Optimize to your application

2.1. Install the Optimize Prisma Client extension

Install Prisma Client and the Optimize extension:

npm install @prisma/client@latest @prisma/extension-optimize

Enabling tracing in older versions of Prisma ORM

For versions of Prisma ORM between 4.2.0 and 6.1.0, you need to enable the tracing preview feature in your Prisma schema file.

generator client {
  provider = "prisma-client-js"
  previewFeatures = ["tracing"]
}

2.2. Add the Optimize API Key to your `.env` file

Generate a Prisma Optimize API key

and add it to your .env file:

OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY"

2.3. Extend your Prisma Client instance

Extend your existing Prisma Client instance with the Optimize extension:

import { PrismaClient } from "@prisma/client";
import { withOptimize } from "@prisma/extension-optimize";

const prisma = new PrismaClient().$extends(withOptimize({ apiKey: process.env.OPTIMIZE_API_KEY }));

Using the Optimize extension with other extensions

Since extensions are applied one after another, make sure you apply them in the correct order. Extensions cannot share behavior and the last extension applied takes precedence.

If you are using Prisma Accelerate in your application, make sure you apply it after the Optimize extension. For example:

const prisma = new PrismaClient().$extends(withOptimize()).$extends(withAccelerate());

2.5. Use Prisma Optimize to generate insights

Follow these steps to start generating query insights with Prisma Optimize:

In the Optimize dashboard, click the Start recording button, then run your app and execute some Prisma queries while recording is active.
After your app runs and generates insights based on the executed Prisma queries, click the Stop recording button.
Explore individual query details by clicking on them, and check the Recommendations tab for any suggested improvements to enhance query performance.

Use Prisma AI to understand recommendations and apply them within your Prisma model context.

For a hands-on learning experience, try out the step-by-step example.

Need help?

If you need assistance, reach out in the #help-and-questions channel on our Discord, or connect with our community to see how others are using Optimize.

Getting Started