Skip to main content

Getting Started

Prerequisites​

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

  • A .
  • 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.
note

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

1. Launch Optimize​

  1. Log in to your .
  2. 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 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.

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())

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())

2.5. Use Prisma Optimize to generate insights​

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

  1. In the Optimize dashboard, click the Start recording button, then 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 Stop 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.

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.