Skip to main content

Setup

Prerequisites​

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

note

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

1. Launch Optimize​

  1. Log in to your .
  2. Click the Optimize tab on the left navigation.
  3. Click the Generate API key button.
  4. Copy the API key that appears and paste it somewhere safe, like a password manager.
  5. Click the copy icons to continue through each setup screen until you see the Finish & optimize button. Click that to complete the setup.
  6. Once you're done, Optimize will automatically begin a new recording session in the background.

2. Add Optimize to your application​

2.1. Install the required Prisma Client extension​

Run the following command in your terminal to install the necessary dependencies:

npm install @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​

Copy the 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 { withAccelerate } from "@prisma/extension-optimize";
import { withOptimize } from "@prisma/extension-optimize";

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

Using the Optimize extension with other extensions or middleware​

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.

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

If you are using Prisma Middleware in your application, make sure they are added before any Prisma Client extensions (like Optimize). For example:

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

2.5. Use Prisma Optimize to generate insights​

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

  1. Run your app and execute some Prisma queries while recording is active.

  2. After your app runs and generates insights based on the executed Prisma queries, click the red Recording button.

  3. Explore individual query details by clicking on them, and check the Recommendations tab for any suggested improvements to enhance query performance.

    info

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

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.