@prisma/extension-optimize

Prisma Optimize Prisma Client extension

This is the package for the Prisma Client extension, which enables the use of Prisma Optimize.

Prisma Optimize enables developers to profile and get performance-related recommendations while developing applications with Prisma ORM.

It is part of the Prisma ecosystem, alongside other tools such as:

• Prisma Accelerate: Global database cache with scalable connection pooling.
• Prisma Pulse: Real-time database events with type-safe subscriptions.

Prisma is leading Data DX, a philosophy that promotes simplicity in data-driven application development. Learn more on the Data DX manifesto.

Getting started with Prisma Optimize

Resources

You can explore Optimize with the following resources:

• Get started
• Documentation
• Prisma Data Platform

Using Optimize

1. Launch Optimize

• Log in to your Prisma Data Platform account.
• Access and launch the Optimize dashboard by following the instructions here.

2. Add Optimize to your application

2.1. Update Your schema.prisma file

If you're using Prisma version 5 or earlier, run the following command in your terminal to install compatible packages, else use version 6:

Version 5:

npm install @prisma/client@^5 @prisma/instrumentation@^5
@prisma/extension-optimize
npm install --save-dev prisma@^5

Version 6:

npm install @prisma/client@^6
@prisma/extension-optimize @prisma/instrumentation@^6
npm install --save-dev prisma@^6

2.2. Update Your schema.prisma file for prisma client v.5

Skip this step if you're using prisma client v.6

Prisma Optimize uses Prisma ORM's OpenTelemetry tracing functionality. In the generator block of your Prisma schema, add the tracing preview feature:

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

Then, generate the Prisma Client:

npx prisma generate

2.2. Install the Optimize Prisma Client extension

Install the latest versions of Prisma Client and the Optimize extension:

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

2.3. Create an API Key via Optimize's UI and add it to your .env file

Generate an Optimize API key by following the instructions here and add it to your .env file:

OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY"

2.4. Extend your Prisma Client instance with the Optimize extension

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 }));

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.

• After your app runs and insights are generated for the desired 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.

NOTE: Use the AI Explainer feature 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.