diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index dc32409feb..c2453b4530 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -203,4 +203,4 @@ jobs: else echo "Failing based on first run results" exit ${{ steps.lychee.outputs.exit_code }} - fi + fi \ No newline at end of file diff --git a/apps/docs/content/docs.v6/accelerate/getting-started.mdx b/apps/docs/content/docs.v6/accelerate/getting-started.mdx index ec3822f546..7284e7ba98 100644 --- a/apps/docs/content/docs.v6/accelerate/getting-started.mdx +++ b/apps/docs/content/docs.v6/accelerate/getting-started.mdx @@ -151,7 +151,7 @@ If VS Code does not recognize the `$extends` method, refer to [this section](/v6 Since [extensions are applied one after another](/v6/orm/prisma-client/client-extensions#conflicts-in-combined-extensions), 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 Optimize](/v6/optimize) in your application, make sure you apply it _before_ the Accelerate extension. For example: +If you are using [Query Insights](/query-insights) in your application, make sure you apply it _before_ the Accelerate extension. For example: ```ts const prisma = new PrismaClient({ diff --git a/apps/docs/content/docs.v6/meta.json b/apps/docs/content/docs.v6/meta.json index 63287b8295..0c19876210 100644 --- a/apps/docs/content/docs.v6/meta.json +++ b/apps/docs/content/docs.v6/meta.json @@ -4,7 +4,6 @@ "orm", "postgres", "accelerate", - "optimize", "guides", "platform", "ai" diff --git a/apps/docs/content/docs.v6/optimize/faq.mdx b/apps/docs/content/docs.v6/optimize/faq.mdx deleted file mode 100644 index f85072c557..0000000000 --- a/apps/docs/content/docs.v6/optimize/faq.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: FAQ -description: Frequently asked questions about Prisma Optimize. -url: /v6/optimize/faq -metaTitle: 'Prisma Optimize: FAQ' -metaDescription: Frequently asked questions about Prisma Optimize. ---- - -To learn more about frequently asked questions around Prisma Optimize and query recommendations, [visit this page](/v6/postgres/faq#query-optimization). diff --git a/apps/docs/content/docs.v6/optimize/getting-started.mdx b/apps/docs/content/docs.v6/optimize/getting-started.mdx deleted file mode 100644 index 88fe5bbcb6..0000000000 --- a/apps/docs/content/docs.v6/optimize/getting-started.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Getting Started -description: Learn how to quickly set up and start using Prisma Optimize. -url: /v6/optimize/getting-started -metaTitle: Getting started with Prisma Optimize -metaDescription: Learn how to quickly set up and start using Prisma Optimize. ---- - -## Prerequisites - -Before you begin with Prisma Optimize, ensure you have the following: - -- A [Prisma Data Platform account](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-page). -- A project using [Prisma Client](/v6/orm/prisma-client/setup-and-configuration/introduction) 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](/v6/postgres/faq#can-i-enable-query-optimizations-for-prisma-postgres-in-production). - -::: - -## 1. Launch Optimize - -1. Log in to your [Prisma Data Platform account](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-page). -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 -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. - -```prisma -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: - -```bash -OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY" -``` - -### 2.3. Extend your Prisma Client instance - -Extend your existing Prisma Client instance with the Optimize extension: - -```ts -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](/v6/orm/prisma-client/client-extensions#conflicts-in-combined-extensions), 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](/v6/accelerate) in your application, make sure you apply it _after_ the Optimize extension. For example: - -```ts -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: - -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](/v6/postgres/query-optimization/recordings#data-captured-in-a-recording-session) by clicking on them, and check the **Recommendations** tab for any suggested improvements to enhance query performance. - - :::info - Use [Prisma AI](/v6/postgres/query-optimization/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](https://github.com/prisma/prisma-examples/tree/latest/optimize/starter). - -## Need help? - -If you need assistance, reach out in the `#help-and-questions` channel on our [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=generated_text_cta), or connect with [our community](https://www.prisma.io/community) to see how others are using Optimize. diff --git a/apps/docs/content/docs.v6/optimize/index.mdx b/apps/docs/content/docs.v6/optimize/index.mdx deleted file mode 100644 index 62d310b209..0000000000 --- a/apps/docs/content/docs.v6/optimize/index.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Prisma Optimize -description: Prisma Optimize is a tool that helps you generate insights on your queries and recommends performance optimizations. -url: /v6/optimize -metaTitle: Prisma Optimize -metaDescription: Prisma Optimize is a tool that helps you generate insights on your queries and recommends performance optimizations. ---- - -[Prisma Optimize](https://www.prisma.io/optimize) helps you generate insights and provides recommendations that can help you make your database queries faster. - -This helps you to: - -- Generate insights about your database queries -- Identify errors to help debug your database queries -- Receive recommendations and discuss them with an AI assistant to enhance query performance. - -Optimize aims to help developers of all skill levels write efficient database queries, reducing database load and making applications more responsive. - -## Supported databases - -Optimize works with the database you already have. - -- PostgreSQL -- MySQL -- MariaDB -- CockroachDB -- MS SQL Server - -## Getting started - -- [Getting started](/v6/optimize/getting-started) - Start analyzing queries in 5 minutes -- [Recommendations](/v6/optimize/recommendations) - Performance optimization recommendations -- [Prisma AI](/v6/optimize/prisma-ai) - AI-powered query optimization assistance diff --git a/apps/docs/content/docs.v6/optimize/known-limitations.mdx b/apps/docs/content/docs.v6/optimize/known-limitations.mdx deleted file mode 100644 index 6bd66cae20..0000000000 --- a/apps/docs/content/docs.v6/optimize/known-limitations.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Known limitations about Prisma Optimize -description: Learn about known limitations of Optimize. -url: /v6/optimize/known-limitations -metaTitle: 'Optimize: Known limitations' -metaDescription: Learn about known limitations of Optimize. ---- - -Below are the known limitations when using Prisma Optimize. If you are aware of any limitations that are missing, please let us know on the `#help-and-questions` channel in our community [Discord](https://pris.ly/discord?utm_source=docs&utm_medium=intro_text). - -## Query limit on a recording session - -Each [recording session](/v6/postgres/query-optimization/recordings) can contain a maximum of 10,000 queries. Once this limit is reached, the recording session will end. - -## Recording limit per workspace - -Each [workspace](/v6/platform/about#workspace) can contain a maximum of 100 [recordings](/v6/postgres/query-optimization/recordings). - -## Scope and constraints for the Prisma AI - -While [Prisma AI](/v6/postgres/query-optimization/prisma-ai) can provide helpful guidance to implement a [recommendation](/v6/postgres/query-optimization/recommendations), there are some important limitations to keep in mind: - -- **Information and accuracy**: The AI provides advice based on a broad, general knowledge base and does not have direct access to Prisma ORM documentation. This may occasionally result in inaccuracies or outdated information. - -- **Limited context and adaptation**: The AI does not persist conversations or learn from previous interactions. Its responses are generalized and may not always address the specific needs of advanced users. - -- **Static knowledge and scope**: The AI's knowledge is static and may not include recent updates or best practices after a certain date. It provides advice only within the context of Prisma ORM and cannot modify or execute code, nor interact directly with user environments. - -## Using Prisma Accelerate client extension with the Optimize extension - -When using the [Optimize client extension](https://www.npmjs.com/package/@prisma/extension-optimize) with the [Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate), ensure the Accelerate client extension is added last to your extended `PrismaClient`. This allows cacheable operations to be received by Optimize. - -```ts -const prisma = new PrismaClient() - .$extends( - withOptimize({ - apiKey: process.env.OPTIMIZE_API_KEY, - }), - ) - .$extends(withAccelerate()); -``` - -### SQL references in MongoDB recommendations - -Prisma Optimize provides helpful recommendations for MongoDB users, though some explanations from [Prisma AI](/v6/postgres/query-optimization/prisma-ai) may reference SQL-specific concepts. However, the [recommendations](/v6/postgres/query-optimization/recommendations) remain useful and applicable to MongoDB environments. - -### Raw query visibility in MongoDB - -Raw queries are visible in MongoDB, though the parameters passed to them are not displayed. - -## Driver adapter compatibility - -Prisma Optimize is not yet compatible with [driver adapters](/v6/orm/overview/databases/database-drivers#driver-adapters). However, as a workaround, you can run your queries locally using the regular Prisma Client along with Prisma Optimize to inspect and improve query performance. diff --git a/apps/docs/content/docs.v6/optimize/meta.json b/apps/docs/content/docs.v6/optimize/meta.json deleted file mode 100644 index c924d6d803..0000000000 --- a/apps/docs/content/docs.v6/optimize/meta.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "title": "Optimize", - "root": true, - "pages": [ - "index", - "getting-started", - "recommendations", - "recordings", - "performance-metrics", - "prisma-ai", - "faq", - "known-limitations" - ] -} diff --git a/apps/docs/content/docs.v6/optimize/performance-metrics.mdx b/apps/docs/content/docs.v6/optimize/performance-metrics.mdx deleted file mode 100644 index c2642cf85f..0000000000 --- a/apps/docs/content/docs.v6/optimize/performance-metrics.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Performance metrics -description: Learn about the query performance metrics provided by Optimize. -url: /v6/optimize/performance-metrics -metaTitle: 'Optimize: Query performance metrics' -metaDescription: Learn about the query performance metrics provided by Optimize. ---- - -An Optimize recording session provides detailed insights into the latencies of executed queries, capturing key metrics such as average duration, 50th percentile, 99th percentile, and maximal query execution time. - -Learn more about [the performance metrics captured by Optimize here](/v6/postgres/query-optimization/performance-metrics). diff --git a/apps/docs/content/docs.v6/optimize/prisma-ai.mdx b/apps/docs/content/docs.v6/optimize/prisma-ai.mdx deleted file mode 100644 index 9940a85fac..0000000000 --- a/apps/docs/content/docs.v6/optimize/prisma-ai.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Prisma AI -description: Learn about using Optimize's Prisma AI feature. -url: /v6/optimize/prisma-ai -metaTitle: 'Optimize: Prisma AI' -metaDescription: Learn about using Optimize's Prisma AI feature. ---- - -Prisma AI enables you to ask follow-up questions on a provided [recommendation](/v6/postgres/query-optimization/recommendations) for additional clarity. Learn more about [Prisma AI here](/v6/postgres/query-optimization/prisma-ai). diff --git a/apps/docs/content/docs.v6/optimize/recommendations.mdx b/apps/docs/content/docs.v6/optimize/recommendations.mdx deleted file mode 100644 index 338d75a5f7..0000000000 --- a/apps/docs/content/docs.v6/optimize/recommendations.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Recommendations -description: Learn about using Optimize's recommendations. -url: /v6/optimize/recommendations -metaTitle: 'Optimize: Recommendations' -metaDescription: Learn about using Optimize's recommendations. ---- - -Optimize provides recommendations focused on performance improvements such as indexing issues, excessive data retrieval, and inefficient query patterns. Recommendations include: - -- [Excessive number of rows returned](/v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned) -- [Full table scans caused by LIKE operations](/v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations) -- [Queries on unindexed columns](/v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns) -- [Repeated query](/v6/postgres/query-optimization/recommendations/repeated-query) -- [Overfetching](/v6/postgres/query-optimization/recommendations/select-returning) -- [Using `@db.Money`](/v6/postgres/query-optimization/recommendations/avoid-db-money) -- [Using `@db.Char(n)`](/v6/postgres/query-optimization/recommendations/avoid-char) -- [Using `@db.VarChar(n)`](/v6/postgres/query-optimization/recommendations/avoid-varchar) -- [Using `timestamp(0)` or `timestamptz(0)`](/v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0) -- [Using `CURRENT_TIME`](/v6/postgres/query-optimization/recommendations/current-time) -- [Storing large objects or BLOBs in the database](/v6/postgres/query-optimization/recommendations/storing-blob-in-database) -- [Indexing on unique columns](/v6/postgres/query-optimization/recommendations/indexing-on-unique-columns) -- [Long-running transactions](/v6/postgres/query-optimization/recommendations/long-running-transactions) -- [Unnecessary indexes](/v6/postgres/query-optimization/recommendations/unnecessary-indexes) - -Learn more about the [recommendations generated by Optimize here](/v6/postgres/query-optimization/recommendations). diff --git a/apps/docs/content/docs.v6/optimize/recordings.mdx b/apps/docs/content/docs.v6/optimize/recordings.mdx deleted file mode 100644 index dc7e93e864..0000000000 --- a/apps/docs/content/docs.v6/optimize/recordings.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Recordings in Prisma Optimize -description: Learn about using Optimize's recording feature. -url: /v6/optimize/recordings -metaTitle: 'Optimize: Recordings' -metaDescription: Learn about using Optimize's recording feature. ---- - -The recordings feature helps developers debug and isolate sets of queries into distinct sessions, known as recordings. This targeted approach enables precise performance analysis and optimization by preventing the mixing of queries from different applications or test rounds, leading to clearer insights and more effective debugging. - -Learn more about the [Optimize recordings here](/v6/postgres/query-optimization/recommendations). diff --git a/apps/docs/content/docs.v6/orm/prisma-client/queries/query-optimization-performance.mdx b/apps/docs/content/docs.v6/orm/prisma-client/queries/query-optimization-performance.mdx index e96c66d336..b95bf726d0 100644 --- a/apps/docs/content/docs.v6/orm/prisma-client/queries/query-optimization-performance.mdx +++ b/apps/docs/content/docs.v6/orm/prisma-client/queries/query-optimization-performance.mdx @@ -1,12 +1,47 @@ --- -title: Query optimization using Prisma Optimize -description: How Prisma optimizes queries under the hood +title: Query optimization +description: How to identify and optimize query performance with Prisma url: /v6/orm/prisma-client/queries/query-optimization-performance -metaTitle: Query optimization using Prisma Optimize -metaDescription: How Prisma optimizes queries under the hood +metaTitle: Query optimization +metaDescription: How to identify and optimize query performance with Prisma --- -This guide shows how to identify and optimize query performance, debug performance issues, and address common challenges. +This guide covers identifying and optimizing query performance with Prisma. + +## Query Insights + +[Query Insights](/query-insights) is built into Prisma Postgres and shows you which queries are slow, how expensive they are, and what to fix. It works out of the box for raw SQL, but to see Prisma ORM operations (model name, action, query shape) you need one extra step. + +### Enabling Prisma ORM attribution + +Install `@prisma/sqlcommenter-query-insights`: + +```bash +npm install @prisma/sqlcommenter-query-insights +``` + +Then pass it to the `comments` option in your `PrismaClient` constructor: + +```ts +import { prismaQueryInsights } from "@prisma/sqlcommenter-query-insights"; +import { PrismaClient } from "@prisma/client"; + +const prisma = new PrismaClient({ + adapter: myAdapter, // driver adapter or Accelerate URL required + comments: [prismaQueryInsights()], +}); +``` + +This adds a SQL comment to every query containing the model, action, and parameterized query shape. Query Insights uses these annotations to trace SQL back to the exact Prisma call that generated it — even when a single Prisma call produces multiple SQL statements. + +#### Let your AI agent handle setup + +Copy this prompt into your AI coding assistant: + +``` +Install and configure @prisma/sqlcommenter-query-insights in my project so I can +see Prisma ORM queries in Query Insights. Docs: https://www.prisma.io/docs/query-insights +``` ## Debugging performance issues @@ -17,26 +52,7 @@ Several common practices can lead to slow queries and performance problems, such - Not caching repeated queries - Performing full table scans -:::info - -For more potential causes of performance issues, visit [this page](/v6/optimize/recommendations). - -::: - -[Prisma Optimize](/v6/optimize) offers [recommendations](/v6/optimize/recommendations) to identify and address the inefficiencies listed above and more, helping to improve query performance. - -To get started, follow the [integration guide](/v6/optimize/getting-started) and add Prisma Optimize to your project to begin diagnosing slow queries. - -
- -
+Use [Query Insights](/query-insights) to identify which queries are affected and what to change. :::tip diff --git a/apps/docs/content/docs.v6/orm/prisma-client/queries/select-fields.mdx b/apps/docs/content/docs.v6/orm/prisma-client/queries/select-fields.mdx index 5ebdd6440f..8faf60f35d 100644 --- a/apps/docs/content/docs.v6/orm/prisma-client/queries/select-fields.mdx +++ b/apps/docs/content/docs.v6/orm/prisma-client/queries/select-fields.mdx @@ -232,7 +232,7 @@ const postsWithAuthorsAndProfiles = await prisma.post.findFirst({ :::note -Be careful when deeply nesting relations because the underlying database query may become slow due it needing to access a lot of different tables. To ensure your queries always have optimal speed, consider adding a caching layer with [Prisma Accelerate](/v6/accelerate) or use [Prisma Optimize](/v6/optimize) to get query insights and recommendations for performance optimizations. +Be careful when deeply nesting relations because the underlying database query may become slow due to it needing to access a lot of different tables. To ensure your queries always have optimal speed, consider adding a caching layer with [Prisma Accelerate](/v6/accelerate) or use [Query Insights](/postgres/database/query-insights) to identify slow queries and optimize performance. ::: diff --git a/apps/docs/content/docs.v6/platform/about.mdx b/apps/docs/content/docs.v6/platform/about.mdx index aa8cb6bef0..35079f89cb 100644 --- a/apps/docs/content/docs.v6/platform/about.mdx +++ b/apps/docs/content/docs.v6/platform/about.mdx @@ -12,7 +12,7 @@ metaDescription: Learn about the Console to integrate the Prisma Data Platform p The [Console](https://console.prisma.io/login) enables you to manage and configure your projects that use Prisma Data Platform (PDP) products, and helps you integrate them into your application: - [Accelerate](/v6/accelerate): Speeds up your queries with a global database cache with scalable connection pooling. -- [Optimize](/v6/optimize): Provides you recommendations that can help you make your database queries faster. +- [Query Insights](/query-insights): Provides you recommendations that can help you make your database queries faster. - [Prisma Postgres](/v6/postgres): A managed PostgreSQL database that is optimized for Prisma ORM. ## Concepts @@ -44,7 +44,7 @@ In each workspace, you can: - manage billing, i.e. select a [subscription plan](https://www.prisma.io/pricing?utm_source=docs&utm_medium=platform-docs), configure payment methods, or view the invoice history. - view the usage of your enabled PDP products across all projects in that workspace. - invite other users to collaborate in the workspace. -- access the [Optimize dashboard](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-docs) to measure query performance and receive AI-powered recommendations. +- access [Query Insights](https://console.prisma.io) to monitor query performance. ### Database Metrics @@ -57,30 +57,9 @@ detailed reports on how your database is performing, with various metrics like: - Total operations - Cache utilization -#### Optimize +#### Query Insights -You can access Optimize within your [Prisma Data Platform account](https://console.prisma.io/optimize) workspace. - -##### Accessing the Optimize dashboard - -To access the Optimize dashboard in your desired workspace: - -1. Click the **Optimize** tab on the left navigation. -2. Click the **Generate API key** button. - -##### Generating an Optimize API key - -To obtain the Optimize API key: - -1. Navigate to the workspace where you want to use Optimize. -2. Ensure that Optimize is launched. If it isn't, click the **Generate API key** button. -3. In Optimize, click your profile name in the top right corner of the navbar. -4. Select **Settings**. -5. Click **Create API key**. -6. Enter a name for the API key in the **Name** field, then click **Create**. -7. Copy the API key and store it securely. This will be used in your project's [`.env` file](/v6/optimize/getting-started) via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button. - -You now have your Optimize API key. +[Query Insights](/postgres/database/query-insights) is available within your [Prisma Console](https://console.prisma.io) workspace and helps you identify slow queries and understand their performance characteristics. ### Project @@ -98,7 +77,7 @@ An environment is an isolated space used to provision PDP products for a specifi In each environment, you can: -- enable, disable and configure PDP products (Optimize, Accelerate, ...). +- enable, disable and configure PDP products (Accelerate, ...). - generate API keys. - for **Accelerate**: - set your database connection string. diff --git a/apps/docs/content/docs.v6/postgres/faq.mdx b/apps/docs/content/docs.v6/postgres/faq.mdx index 0e4ba33c08..2012b6208d 100644 --- a/apps/docs/content/docs.v6/postgres/faq.mdx +++ b/apps/docs/content/docs.v6/postgres/faq.mdx @@ -344,50 +344,45 @@ Check the [pricing page](https://www.prisma.io/pricing) for more details on the While you can increase these limits based on your subscription plan, it's _still_ recommended to optimize your database operations. [Learn more in our troubleshooting guide.](/v6/postgres/database/api-reference/error-reference) ::: -## Query optimization +## Query Insights -Prisma Postgres allows query optimization via [Prisma Optimize](/v6/optimize) and provides performance recommendations to help improve your database queries during development. You can enable it with Prisma Postgres or [also use it with your own database](/v6/optimize/getting-started), but setup and integration steps differ. +[Query Insights](/query-insights) is built into Prisma Postgres and helps you identify slow queries, understand their cost, and decide what to fix. -### Can you automatically implement optimizations? +### I only see raw SQL — how do I see my Prisma ORM queries? -Prisma Postgres's query optimization feature offers insights and recommendations on how to improve your database queries. It does not alter any existing queries or your Prisma schema. +By default, Query Insights shows raw SQL. To also see the Prisma ORM operation that generated each query (model name, action, and query shape), install the `@prisma/sqlcommenter-query-insights` package: -### How long is a recording session retained? - -There are no limits on the storage retention period. A query performance recording session will be stored until you explicitly delete it. - -### Do recommendation limits reset monthly? - -Yes, the recommendation usage resets at the beginning of each calendar month. For example, if you use `5` recommendations by the end of the month, your usage will reset to `0` at the start of the next month. - -### Can I get charged for exceeding the recommendation limit on the starter plan? +```bash +npm install @prisma/sqlcommenter-query-insights +``` -Yes, if you’re on the starter plan, exceeding `5` recommendations in a billing cycle will result in a `$5` charge at the end of that cycle. For more information, visit [our pricing page](https://www.prisma.io/pricing#optimize). +Then pass it to the `comments` option in your `PrismaClient` constructor: -### How are viewed Prisma AI recommendations tracked for billing? Are they counted based on generated or viewed recommendations? +```ts +import { prismaQueryInsights } from "@prisma/sqlcommenter-query-insights"; +import { PrismaClient } from "@prisma/client"; -They are counted based on viewed recommendations. Once you click on a recommendation from the recommendations table and view the recommendation's detail page, it counts as being seen. +const prisma = new PrismaClient({ + adapter: myAdapter, // driver adapter or Accelerate URL required + comments: [prismaQueryInsights()], +}); +``` -### Can I enable query optimizations for Prisma Postgres in production? +This annotates every query with a SQL comment containing the model, action, and parameterized query shape. Query Insights uses these annotations to map SQL back to the Prisma call that generated it. -No, query optimizations for Prisma Postgres is not meant to be enabled for production use. It is specifically designed for local development, providing valuable insights and optimizations during that phase. While it's technically possible to run it in a production environment, doing so could result in performance problems or unexpected behaviors, as this is not built to handle the complexity and scale of production workloads. For the best experience, we recommend testing query optimization solely in your development environment. +#### Let your AI agent handle setup -You can use the `enable` property in the client extension to run it [only in development environment](https://www.npmjs.com/package/@prisma/extension-optimize). By default, the `enable` property is set to `true`. +Copy this prompt into your AI coding assistant: -```ts title="script.ts" copy showLineNumbers -import { PrismaClient } from "@prisma/client"; -import { withOptimize } from "@prisma/extension-optimize"; - -const prisma = new PrismaClient().$extends( - withOptimize({ - apiKey: process.env.OPTIMIZE_API_KEY, - enable: process.env.ENVIRONMENT === "development", - }), -); ``` +Install and configure @prisma/sqlcommenter-query-insights in my project so I can +see Prisma ORM queries in Query Insights. Docs: https://www.prisma.io/docs/query-insights +``` + +### Does Query Insights alter my queries or schema? -### Why do I see "[optimize] HTTP 409 Conflict: There is no active recording to write queries to" warning? +No. Query Insights is read-only — it observes query behavior but does not rewrite queries or modify your Prisma schema. -This warning may occur when Prisma Optimize receives queries but no recording session is active. Typically, this can happen if Prisma Optimize is unintentionally enabled in your production environment. Prisma Optimize is specifically designed for use in local development environments and should not be enabled in production. To avoid this warning, ensure that Prisma Optimize is configured to run only during development. +### Can I use Query Insights in production? -If you are seeing this warning in your development environment, ensure that you have started a recording session in the Prisma Optimize Dashboard. +Query Insights is designed primarily for development and debugging. Running it in production is possible but not recommended, as the SQL comment annotations add a small overhead to every query. diff --git a/apps/docs/content/docs.v6/postgres/meta.json b/apps/docs/content/docs.v6/postgres/meta.json index 62d47047f4..aaea1f1a00 100644 --- a/apps/docs/content/docs.v6/postgres/meta.json +++ b/apps/docs/content/docs.v6/postgres/meta.json @@ -7,7 +7,6 @@ "introduction", "database", "integrations", - "query-optimization", "api-reference", "troubleshooting", "faq" diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/index.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/index.mdx deleted file mode 100644 index efedc30205..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Query optimization for Prisma Postgres -description: 'Learn how to record, analyze, and improve query performance using Prisma Optimize in Prisma Postgres.' -url: /v6/postgres/query-optimization -metaTitle: Query optimization with Prisma Postgres -metaDescription: 'Learn how to record, analyze, and improve query performance using Prisma Optimize in Prisma Postgres.' ---- - -Understand how Prisma Postgres helps you optimize query performance using the Prisma Optimize toolkit. This section covers setup, recommendations, recording queries, performance metrics, and using Prisma AI for guided improvements. - -## Getting started - -- [Setup](/v6/postgres/query-optimization/setup) - Learn how to quickly set up and start optimizing Prisma Postgres queries -- [Recommendations](/v6/postgres/query-optimization/recommendations) - Learn about the recommendations provided by Optimize -- [Prisma AI](/v6/postgres/query-optimization/prisma-ai) - Learn about using Optimize's Prisma AI feature diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/meta.json b/apps/docs/content/docs.v6/postgres/query-optimization/meta.json deleted file mode 100644 index d6358c16c1..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Query Optimization", - "pages": ["setup", "recommendations", "recordings", "performance-metrics", "prisma-ai"] -} diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/performance-metrics.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/performance-metrics.mdx deleted file mode 100644 index c6ea8b507f..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/performance-metrics.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Performance metrics -description: Learn about the query performance metrics provided by Optimize. -url: /v6/postgres/query-optimization/performance-metrics -metaTitle: 'Prisma Postgres: Query performance metrics' -metaDescription: Learn about the query performance metrics provided by Optimize. ---- - -An Optimize recording session provides detailed insights into the latencies of executed queries, capturing key metrics such as average duration, 50th percentile, 99th percentile, and maximal query execution time. - -## Total query durations - -Prisma Optimize measures total latency for query patterns, enabling you to analyze and debug slow queries effectively. - -### Average query duration (**`AVG`**) - -The average query duration reveals the mean execution time across all queries, helping you assess overall performance trends and identify inefficiencies that impact the user experience. - -### 50th percentile (**`P50`**) - -The 50th percentile, or median, query duration indicates the time within which half of your queries complete. This metric offers a clear view of typical user performance, unaffected by outliers. - -### 99th percentile (**`P99`**) - -The 99th percentile query duration highlights the execution time for the slowest 1% of queries. This metric is crucial for uncovering and addressing performance bottlenecks that, while infrequent, can significantly impact user satisfaction. - -### Maximal query duration (**`MAX`**) - -The maximal query duration measures the time taken by the single slowest query. This metric helps identify extreme cases, providing insights into the worst performance scenarios your system might face, so you can diagnose and resolve outliers. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/prisma-ai.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/prisma-ai.mdx deleted file mode 100644 index 8b53b0ce29..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/prisma-ai.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Query optimization with Prisma AI -description: Learn about using Optimize's Prisma AI feature. -url: /v6/postgres/query-optimization/prisma-ai -metaTitle: 'Prisma Postgres: Prisma AI' -metaDescription: Learn about using Optimize's Prisma AI feature. ---- - -Prisma AI enables you to ask follow-up questions on a provided [recommendation](/v6/postgres/query-optimization/recommendations) for additional clarity. - -## Using the Prisma AI - -To interact with the Prisma AI: - -1. Select a recommendation from an Optimize [recording](/v6/postgres/query-optimization/recordings). -2. Click the **Ask AI** button. - -Prisma AI helps you gain deeper insights into a recommendation and learn how to apply it effectively to your Prisma model. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-char.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-char.mdx deleted file mode 100644 index 5ec1485465..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-char.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Using @db.Char(n) -description: Learn about the recommendation provided by Optimize for using `@db.Char(n)` native type. -url: /v6/postgres/query-optimization/recommendations/avoid-char -metaTitle: Using @db.Char(n) -metaDescription: Learn about the recommendation provided by Optimize for using `@db.Char(n)` native type. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by the use of `@db.Char(n)` type in PostgreSQL. - -In the following example, the `@db.Char(n)` native type has been used within the `Item` model on the `name` field: - -```prisma -model Item { - // ... - name String @db.Char(1) - // ... -} -``` - -### Why this is a problem - -The `@db.Char(n)` type enforces a fixed length of `n`, which can cause unexpected issues in production if not properly managed by the application. In PostgreSQL, `char(n)` pads shorter values with spaces, leading to problems during comparisons and other operations. Unlike some databases that optimize `char(n)`, PostgreSQL does not offer such optimizations, making careful handling essential. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-db-money.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-db-money.mdx deleted file mode 100644 index e1e5c379bf..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-db-money.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Using @db.Money -description: Learn about the recommendation provided by Optimize for using `@db.Money` native type. -url: /v6/postgres/query-optimization/recommendations/avoid-db-money -metaTitle: Using @db.Money -metaDescription: Learn about the recommendation provided by Optimize for using `@db.Money` native type. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by the use of `@db.Money` type. - -The following model uses the `@db.Money` native type: - -```prisma -model Item { - // ... - price Decimal @db.Money - // ... -} -``` - -## What is the problem? - -The `@db.Money` data type in PostgreSQL is not ideal for storing monetary values. Internally, `@db.Money` is implemented as an integer, which offers speed but lacks flexibility. It handles fractional values and rounding in unexpected ways, which can lead to inaccuracies. - -Additionally, the `@db.Money` type does not store any information about the associated currency. Instead, it relies on the global `lc_monetary` locale setting, which may not be suitable for all use cases. - -For more information, refer to the [PostgreSQL documentation](https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_money). diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0.mdx deleted file mode 100644 index 19620fef00..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Using timestamp(0) or timestamptz(0) -description: Learn about the recommendation provided by Optimize for using `timestamp(0)` or `timestamptz(0)` native type. -url: /v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0 -metaTitle: Using timestamp(0) or timestamptz(0) -metaDescription: Learn about the recommendation provided by Optimize for using `timestamp(0)` or `timestamptz(0)` native type. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by the use of `@db.Timestamp(0)` and `@db.Timestamptz(0)` native types in PostgreSQL. - -The `@db.Timestamp(0)` and `@db.Timestamptz(0)` native types have been used within the following `User` model: - -```prisma -model User { - // ... - date DateTime @db.Timestamp(0) - deletedAt DateTime @db.Timestamptz(0) - // ... -} -``` - -### Why this is a problem - -When using a `@db.Timestamp(n)` or `@db.Timestamptz(n)` column with a precision of `0`, the database rounds the time to the nearest whole second, which can lead to unexpected results. - -For example, if you insert the current time, such as `15:30:45.678`, into a column with this precision, it will round up to `15:30:46`. This behavior can cause the recorded time to appear up to half a second in the future compared to the original time, which may be surprising when precise time accuracy is critical. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-varchar.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-varchar.mdx deleted file mode 100644 index e30c4f3f7a..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-varchar.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Using @db.VarChar(n) -description: Learn about the recommendation provided by Optimize for using `@db.VarChar(n)` native type. -url: /v6/postgres/query-optimization/recommendations/avoid-varchar -metaTitle: Using @db.VarChar(n) -metaDescription: Learn about the recommendation provided by Optimize for using `@db.VarChar(n)` native type. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by the use of `@db.VarChar(n)` type in PostgreSQL. - -The `@db.VarChar(n)` native type has been used within the `Item` model on the name field: - -```prisma -model Item { - // ... - name String @db.VarChar(1) - // ... -} -``` - -### Why this is a problem - -The `@db.VarChar(n)` type restricts content to a maximum length of `n`, which can cause unexpected issues in production if not properly managed by the application. In PostgreSQL, `varchar(n)` performs the same as `text`, and no additional optimizations are provided for `varchar(n)`, making the choice between them more about convention than performance. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/current-time.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/current-time.mdx deleted file mode 100644 index 8879e8a537..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/current-time.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Using CURRENT_TIME -description: Learn about the recommendation provided by Optimize for using the `CURRENT_TIME` function -url: /v6/postgres/query-optimization/recommendations/current-time -metaTitle: Using CURRENT_TIME -metaDescription: Learn about the recommendation provided by Optimize for using the `CURRENT_TIME` function ---- - -The following raw SQL query uses the `CURRENT_TIME` function: - -```ts -prisma.$queryRaw`SELECT CURRENT_TIME;`; -``` - -### Why this is a problem - -The `CURRENT_TIME` keyword returns only the time (e.g., 14:30:00) without a date, making it unsuitable for tasks like logging or generating timestamps that require precise event tracking. It returns a value of type `timetz`, which was added for SQL standard compatibility but is generally discouraged. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned.mdx deleted file mode 100644 index 0d9e8fcd86..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Excessive number of rows returned -description: Learn about the recommendation provided by Optimize for excessive number of rows returned. -url: /v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned -metaTitle: Excessive number of rows returned -metaDescription: Learn about the recommendation provided by Optimize for excessive number of rows returned. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by excessive number of rows returned from a query. - -The following query targeting a `User` model does not provide a [`take` option](/v6/orm/reference/prisma-client-reference#findmany): - -```ts -await prisma.user.findMany({ where: { email: "janedoe@gmail.com" } }); -``` - -## What is the problem? - -When a query is executed without specifying a limit, it will return all relevant rows, which can lead to several issues: - -### User experience - -- **Viewing data:** Users typically need only a portion of the data at any given time, not all of it at once. -- **Impact on the user's device:** Displaying all the data at once can strain the user's device resources. For example, loading thousands of rows in a web application can slow down or freeze the browser, consuming significant memory and CPU resources. -- **Waiting time:** Retrieving a large number of rows can significantly increase the time it takes to get the data from the database to the user's device. - -### Resource Utilization - -- **Unnecessary data load:** Processing more data than required wastes valuable resources. -- **Memory usage:** Excessive memory consumption can lead to inefficiency and, in severe cases, cause the system to run out of memory, disrupting the service. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations.mdx deleted file mode 100644 index 0b70a62543..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Full table scans caused by LIKE operations -description: Learn about the recommendation provided by Optimize for full table scans caused by Like operations. -url: /v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations -metaTitle: Full table scans caused by LIKE operations -metaDescription: Learn about the recommendation provided by Optimize for full table scans caused by Like operations. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by full table scans from `LIKE` operations. - -The following query targeting the `User` model provides `contains` and `endsWith` as options, which translate to `LIKE` and `ILIKE` SQL operators. - -```jsx -await prisma.user.findMany({ - where: { - email: { contains: "gmail.com" }, - name: { endsWith: "Burk" }, - }, -}); -``` - -## What is the problem? - -`LIKE` and `ILIKE` operators in SQL can lead to full table scans, potentially impacting performance, especially with larger datasets: - -### UX - -- **Slower load times:** Full table scans can significantly increase the time it takes to retrieve data, leading to longer wait times for users. - -### Resource utilization - -- **Increased resource usage:** Full table scans increase CPU, memory usage, and disk I/O, straining system resources for your database. -- **Increased costs:** In serverless database pricing plans, more intensive resource usage can translate into higher costs. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/index.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/index.mdx deleted file mode 100644 index 869fc6be09..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Recommendations -description: Learn about the recommendations provided by Optimize. -url: /v6/postgres/query-optimization/recommendations -metaTitle: Recommendations -metaDescription: Learn about the recommendations provided by Optimize. ---- - -Optimize provides recommendations focused on performance improvements such as indexing issues, excessive data retrieval, and inefficient query patterns. Recommendations include: - -:::info -Use [Prisma AI](/v6/postgres/query-optimization/prisma-ai) to ask follow-up questions about any recommendation. -::: diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/indexing-on-unique-columns.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/indexing-on-unique-columns.mdx deleted file mode 100644 index 2057ae5f76..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/indexing-on-unique-columns.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Indexing on unique columns -description: Learn about the recommendation provided by Optimize regarding indexing on uniquely constrained columns. -url: /v6/postgres/query-optimization/recommendations/indexing-on-unique-columns -metaTitle: Indexing on unique columns -metaDescription: Learn about the recommendation provided by Optimize regarding indexing on uniquely constrained columns. ---- - -Optimize identifies redundant indexing on unique columns and provides recommendations for better database performance. - -### Why this is an issue - -Unique constraints inherently enforce uniqueness by generating an underlying index. Adding an additional index to the same column is unnecessary and can lead to extra overhead. - -This redundancy increases write costs and slows down updates, as the database must synchronize multiple indexes. - -:::note - -This guideline also applies broadly to relational databases like PostgreSQL, MySQL, MariaDB, SQLite, and SQL Server, which automatically create indexes for unique constraints. - -::: diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/long-running-transactions.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/long-running-transactions.mdx deleted file mode 100644 index 5882c33695..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/long-running-transactions.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Long-running transactions -description: Learn about the recommendation provided by Optimize for long-running transaction. -url: /v6/postgres/query-optimization/recommendations/long-running-transactions -metaTitle: Long-running transactions -metaDescription: Learn about the recommendation provided by Optimize for long-running transaction. ---- - -Optimize provides actionable recommendations to help you identify and resolve performance issues caused by **long-running transactions**. - -**Long-running transactions** can negatively impact scalability and resilience by locking resources and holding database connections for extended periods. Below is a common example of a problematic long-running transaction: - -```ts -// Example: A single massive transaction performing multiple steps -await prisma.$transaction(async (prisma) => { - const order = await prisma.order.create({ - data: { - /* ... */ - }, - }); - await prisma.user.update({ - where: { id: userId }, - data: { balance: { decrement: order.total } }, - }); - await prisma.shipping.create({ data: { orderId: order.id /* ... */ } }); - // Additional dependent operations -}); -``` - -### What is the problem? - -Long-running transactions can cause several critical issues that harm the performance and reliability of your application: - -- **Database locks**: Long transactions hold locks on rows, tables, or other resources, preventing access by other queries. This leads to contention and blocking, which can significantly disrupt concurrent operations. - -- **Connection tie-ups**: Transactions occupy database connections for their entire duration. With a limited connection pool, this can quickly exhaust available connections, resulting in application-wide slowdowns or failures. - -- **Increased contention**: As locks accumulate and connections are tied up, other transactions queue up, creating bottlenecks, higher latency, and reduced throughput. - -- **Scalability challenges**: Inefficiencies caused by long transactions are magnified in high-traffic systems, limiting the system’s ability to scale effectively. - -- **Fragility**: When a long transaction fails or times out, all intermediate progress is lost. This is especially problematic in workflows with multiple dependent steps, as recovering from partial failures becomes complex and error-prone. - -- **Debugging difficulties**: Troubleshooting long-running transactions is challenging due to their multiple steps and potential failures caused by timeouts, deadlocks, or unexpected dependencies. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/meta.json b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/meta.json deleted file mode 100644 index 240d2e5af9..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/meta.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "title": "Recommendations", - "defaultOpen": false, - "pages": [ - "index", - "queries-on-unindexed-columns", - "full-table-scans-caused-by-like-operations", - "excessive-number-of-rows-returned", - "select-returning", - "repeated-query", - "long-running-transactions", - "storing-blob-in-database", - "indexing-on-unique-columns", - "unnecessary-indexes", - "avoid-char", - "avoid-varchar", - "avoid-db-money", - "avoid-timestamp-timestampz-0", - "current-time" - ] -} diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns.mdx deleted file mode 100644 index aa69738bc8..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Queries on unindexed columns -description: Learn about the recommendation provided by Optimize for queries on unindexed columns. -url: /v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns -metaTitle: Queries on unindexed columns -metaDescription: Learn about the recommendation provided by Optimize for queries on unindexed columns. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by missing database indexes. - -The following queries targeting the `User` model use a [`where` property](/v6/orm/prisma-client/queries/filtering-and-sorting) to filter on columns that do not have indexes: - -```ts -await prisma.user.findFirst({ - where: { - name: "Marc", - }, -}); - -await prisma.user.findFirst({ - where: { - name: "Jon", - }, -}); - -await prisma.user.count({ - where: { - name: "Nikolas", - }, -}); -``` - -## What is the problem? - -An index allows the database to retrieve data more quickly, similar to how an index in a book helps you locate information without reading every page. - -When using Prisma with a `where` property, if no indexes are defined for the relevant columns, the database may need to scan every row in the table (a _“full table scan”_) to find matches. This can be undesirable for several reasons: - -### User experience - -For large datasets, if the database must scan the entire table to find matching rows, users will experience longer waiting times. - -### Resource utilization - -- **High CPU usage:** Scanning large tables can significantly increase CPU usage, degrading overall system performance. -- **Memory consumption:** More memory is required to process and store data during a full table scan. -- **Disk I/O:** Full table scans increase disk input/output operations, potentially slowing down other database activities. - -:::warning - -While these issues might not appear in development due to smaller datasets, they can become _significant_ problems in production, where datasets are typically much larger. - -::: - -## More on database indexes - -### How indexes work - -Indexes create a data structure that stores the indexed column's values along with pointers to the corresponding rows in the table. When you query the database using an indexed column, the database can use this index to quickly locate the relevant rows instead of scanning the entire table. - -### The trade-offs of indexing - -- **Space vs. time:** Indexing requires additional storage space to save index data, but it significantly speeds up data retrieval. -- **Update overhead:** Every time data is added to, updated in, or removed from your table, there is an overhead to keep the indexes up to date, which can slow down write operations. - -### When to use indexes - -- **Large datasets:** Indexes are particularly beneficial for tables with a large number of rows. -- **Frequent queries with filtering or sorting:** Use indexes on columns that are frequently used for [filtering or sorting](/v6/orm/prisma-client/queries/filtering-and-sorting#filtering). -- **Looking up related data:** Use indexes on foreign key columns to speed up the retrieval of related records, such as when using [`include`](/v6/orm/prisma-client/queries/relation-queries#include-a-relation). - -### When not to use indexes - -- **Small tables:** For tables with very few rows, the overhead of maintaining indexes might not be worth the performance gain. -- **Write-heavy tables:** Indexes can slow down write operations (`create`, `update`, `delete`) because the index needs to be updated as well. Avoid excessive indexing on models with frequent write operations. -- **Infrequently accessed tables:** If a table is rarely accessed, the benefits of indexing may not justify the overhead. -- **Columns with large data:** Indexing columns with large data can lead to higher storage requirements and might not provide significant performance improvements. -- **Rarely filtered columns:** If a table is often accessed but rarely filtered by a specific column, creating an index on that column may not be beneficial. - -:::warning - -Even if you index a column, the database may not always use it. Many database management systems, such as PostgreSQL and MySQL, have a _query optimizer_ that evaluates multiple execution plans and selects the one it estimates to be most efficient. In some cases, this may involve ignoring an existing index in favor of a different execution plan that it determines will perform better for that specific query. - -::: diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/repeated-query.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/repeated-query.mdx deleted file mode 100644 index 67591ed97a..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/repeated-query.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Repeated query -description: Learn about the recommendation provided by Optimize for repeated queries. -url: /v6/postgres/query-optimization/recommendations/repeated-query -metaTitle: Repeated query -metaDescription: Learn about the recommendation provided by Optimize for repeated queries. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by repeated queries. - -The following query targeting the `Post` model is executed repeatedly with identical parameters: - -```ts -await prisma.post.findMany({ - where: { - published: true, - }, - take: 20, -}); -``` - -### What is the problem? - -When the same query is executed multiple times with the same parameters within a short time frame, it can lead to: - -- **Time waste:** A new connection may be established between the application and database, the query and its parameters are sent to the database, the database processes the query, and the results are sent back to the application. -- **Increased resource usage:** Query execution increases CPU and memory usage, as well as disk I/O, putting strain on your database's system resources. -- **Higher costs:** In serverless database pricing models, higher resource usage can result in increased costs. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/select-returning.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/select-returning.mdx deleted file mode 100644 index 101fa6fc58..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/select-returning.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Overfetching -description: Learn about the recommendation provided by Optimize for queries that are overfetching data. -url: /v6/postgres/query-optimization/recommendations/select-returning -metaTitle: Overfetching -metaDescription: Learn about the recommendation provided by Optimize for queries that are overfetching data. ---- - -Optimize provides recommendations to help you identify and resolve performance issues caused by over-fetched data. - -The following query might be overfetching data in queries on the `User` model: - -```ts -await prisma.user.findMany({ - where: { - email: { contains: "gmail" }, - }, - include: { - links: true, - }, -}); -``` - -## What is the problem? - -Retrieving data from all columns of a table, especially in large tables or those with complex relationships, can result in: - -- **Increased load times**: Fetching more data than necessary prolongs query processing and data transfer times. -- **Greater resource consumption**: Retrieving unnecessary fields places strain on memory and CPU resources, both in the database and on the machines running your application. -- **Higher costs**: Reading and transferring excess data can lead to increased processing costs. -- **Security risks**: You might unintentionally expose sensitive data that should remain within the database. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/storing-blob-in-database.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/storing-blob-in-database.mdx deleted file mode 100644 index 6a9ced3067..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/storing-blob-in-database.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Storing large objects or BLOBs in the database -description: Learn about the recommendations for avoiding the storage of large objects or BLOBs in the database. -url: /v6/postgres/query-optimization/recommendations/storing-blob-in-database -metaTitle: Storing large objects or BLOBs in the database -metaDescription: Learn about the recommendations for avoiding the storage of large objects or BLOBs in the database. ---- - -Optimize provides recommendations to help identify and resolve performance issues caused by storing large objects in the database. It also suggests alternative approaches to mitigate these challenges. - -The following model uses the `Bytes` type: - -```prisma -model User { - id Int @id @default(autoincrement()) - name String? - // Storing raw image data directly in the database - avatarBytes Bytes? -} -``` - -## What is the problem? - -Storing large binary objects (such as images) in the database can lead to several challenges: - -- **Excessive storage usage**: Large objects occupy significant space in the database, complicating management. -- **Increased I/O load**: Handling large objects adds strain to the database's input/output operations. -- **Slower query performance**: Most traditional databases are not optimized for efficiently serving large binary content, resulting in performance degradation during queries or updates. - -Moreover, storing large objects directly in the database can cause backups to become disproportionately large, increasing the time required for restoration processes. Serving these files through the database also creates a performance bottleneck, particularly under high traffic or frequent access scenarios. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/unnecessary-indexes.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/unnecessary-indexes.mdx deleted file mode 100644 index dae4e23130..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recommendations/unnecessary-indexes.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Unnecessary indexes -description: Learn about the recommendation provided by Optimize for using Unnecessary indexes -url: /v6/postgres/query-optimization/recommendations/unnecessary-indexes -metaTitle: Unnecessary indexes -metaDescription: Learn about the recommendation provided by Optimize for using Unnecessary indexes ---- - -Optimize detects unnecessary indexes and recommends removing them to improve database performance. - -### Why this is a problem - -Indexes enhance database query performance but can harm efficiency when overused. They consume storage and add overhead to `INSERT`, `UPDATE`, and `DELETE` operations. Unnecessary indexes can result in: - -- **Increased write costs:** Extra indexes slow down write operations. -- **Higher storage use:** Unused indexes waste storage space. -- **Query optimizer confusion:** Redundant indexes may cause inefficient query plans. - -Removing unnecessary indexes improves performance and simplifies maintenance. diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/recordings.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/recordings.mdx deleted file mode 100644 index 2f3ffae578..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/recordings.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Recordings -description: Learn about using Optimize's recording feature. -url: /v6/postgres/query-optimization/recordings -metaTitle: 'Prisma Postgres: Recordings' -metaDescription: Learn about using Optimize's recording feature. ---- - -The recordings feature helps developers debug and isolate sets of queries into distinct sessions, known as recordings. This targeted approach enables precise performance analysis and optimization by preventing the mixing of queries from different applications or test rounds, leading to clearer insights and more effective debugging. - -## Managing a recording session - -You can manually start and stop recording sessions via the [Optimize dashboard](https://console.prisma.io/optimize) by clicking the **Start Recording** and **Stop Recording** buttons. - -:::warning -A recording will automatically stop if the 10k query limit is reached or if the Prisma schema of the app is changed. -::: - -## Identifying a recording session - -You can rename and tag your recording sessions for easy identification and context. Click on the default name of the session and type the desired name. - -## Data captured in a recording session - -Each recording session captures detailed insights about the queries executed in your app, including: - -- All queries executed during the session. -- The raw query generated and sent to the database by Prisma ORM as **Raw Query**. -- The number of times a query pattern was executed, listed as **Count**. -- [Query performance metrics](/v6/postgres/query-optimization/performance-metrics). -- Errors encountered during query execution. - -Each recording can include up to 10k queries. There are no limits on storage retention. - -## Recommendations from a recording session - -When a recording session ends, Optimize generates recommendations such as: - -- [Excessive number of rows returned](/v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned) -- [Full table scans caused by LIKE operations](/v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations) -- [Queries on unindexed columns](/v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns) -- [Repeated query](/v6/postgres/query-optimization/recommendations/repeated-query) -- [Overfetching](/v6/postgres/query-optimization/recommendations/select-returning) -- [Using `@db.Money`](/v6/postgres/query-optimization/recommendations/avoid-db-money) -- [Using `@db.Char(n)`](/v6/postgres/query-optimization/recommendations/avoid-char) -- [Using `@db.VarChar(n)`](/v6/postgres/query-optimization/recommendations/avoid-varchar) -- [Using `timestamp(0)` or `timestamptz(0)`](/v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0) -- [Using `CURRENT_TIME`](/v6/postgres/query-optimization/recommendations/current-time) -- [Storing large objects or BLOBs in the database](/v6/postgres/query-optimization/recommendations/storing-blob-in-database) -- [Indexing on unique columns](/v6/postgres/query-optimization/recommendations/indexing-on-unique-columns) -- [Long-running transactions](/v6/postgres/query-optimization/recommendations/long-running-transactions) -- [Unnecessary indexes](/v6/postgres/query-optimization/recommendations/unnecessary-indexes) - -:::info -Use [Prisma AI](/v6/postgres/query-optimization/prisma-ai) to ask follow-up questions about a recommendation. -::: - -Learn more about the recommendations generated by Optimize [here](/v6/postgres/query-optimization/recommendations). diff --git a/apps/docs/content/docs.v6/postgres/query-optimization/setup.mdx b/apps/docs/content/docs.v6/postgres/query-optimization/setup.mdx deleted file mode 100644 index 052ec21202..0000000000 --- a/apps/docs/content/docs.v6/postgres/query-optimization/setup.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Setup -description: Learn how to quickly set up and start optimizing Prisma Postgres queries. -url: /v6/postgres/query-optimization/setup -metaTitle: Getting started with optimizing queries in Prisma Postgres -metaDescription: Learn how to quickly set up and start optimizing Prisma Postgres queries. ---- - -## Prerequisites - -Before you begin with Prisma Optimize for Prisma Postgres, ensure you have the following: - -- A [Prisma Data Platform account](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-page). -- A project using [Prisma Client](/v6/orm/prisma-client/setup-and-configuration/introduction) version `5.0.0` or higher (we recommend using the latest version). -- A [Prisma Postgres database](/v6/postgres/getting-started). - -:::note - -Prisma Optimize is intended for use in local environments. Learn more in the [FAQ](/v6/postgres/faq#can-i-enable-query-optimizations-for-prisma-postgres-in-production). - -::: - -## 1. Launch Optimize - -1. Log in to your [Prisma Data Platform account](https://console.prisma.io/optimize?utm_source=docs&utm_medium=ppg_optimize_page). -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 -npm install @prisma/extension-optimize -``` - -### 2.2. Add the Optimize API Key to your `.env` file - -Copy the Prisma Optimize API key and add it to your `.env` file: - -```bash -OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY" -``` - -### 2.3. Extend your Prisma Client instance - -Extend your existing Prisma Client instance with the Optimize extension: - -```ts -import { PrismaClient } from "../path/to/generated/prisma/client"; -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 - -Since [extensions are applied one after another](/v6/orm/prisma-client/client-extensions#conflicts-in-combined-extensions), make sure you apply them in the correct order. Extensions cannot share behavior and the last extension applied takes precedence. - -```ts -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: - -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](/v6/postgres/query-optimization/recordings#data-captured-in-a-recording-session) by clicking on them, and check the **Recommendations** tab for any suggested improvements to enhance query performance. - - :::info - Use [Prisma AI](/v6/postgres/query-optimization/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](https://pris.ly/discord?utm_source=docs&utm_medium=generated_text_cta), or connect with [our community](https://www.prisma.io/community) to see how others are using Optimize. diff --git a/apps/docs/content/docs/accelerate/getting-started.mdx b/apps/docs/content/docs/accelerate/getting-started.mdx index e56aa7535c..dc6c35708a 100644 --- a/apps/docs/content/docs/accelerate/getting-started.mdx +++ b/apps/docs/content/docs/accelerate/getting-started.mdx @@ -151,7 +151,7 @@ If VS Code does not recognize the `$extends` method, refer to [this section](/ac Since [extensions are applied one after another](/orm/prisma-client/client-extensions#conflicts-in-combined-extensions), 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 Optimize](/optimize) in your application, make sure you apply it _before_ the Accelerate extension. For example: +If you are using [Query Insights](/query-insights) in your application, make sure you apply it _before_ the Accelerate extension. For example: ```ts const prisma = new PrismaClient({ diff --git a/apps/docs/content/docs/console/features/meta.json b/apps/docs/content/docs/console/features/meta.json index 2957f85bbd..c7ec7b8321 100644 --- a/apps/docs/content/docs/console/features/meta.json +++ b/apps/docs/content/docs/console/features/meta.json @@ -1,7 +1,6 @@ { "title": "Features", "pages": [ - "metrics", - "optimize" + "metrics" ] } diff --git a/apps/docs/content/docs/console/features/optimize.mdx b/apps/docs/content/docs/console/features/optimize.mdx deleted file mode 100644 index 9d67181b4c..0000000000 --- a/apps/docs/content/docs/console/features/optimize.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Optimize -description: Access the Optimize dashboard and generate API keys for query performance monitoring -metaTitle: Optimize in Console | Query Performance Dashboard -metaDescription: 'Access the Prisma Optimize dashboard from Console. Generate API keys for query performance monitoring. Enable OPTIMIZE_API_KEY in your project.' -url: /console/features/optimize ---- - -You can access Optimize within your [Prisma Data Platform account](https://console.prisma.io/optimize) workspace. - -## Accessing the Optimize dashboard - -To access the Optimize dashboard in your desired workspace: - -1. Click the **Optimize** tab on the left navigation. -2. Click the **Generate API key** button. - -## Generating an Optimize API key - -To obtain the Optimize API key: - -1. Navigate to the workspace where you want to use Optimize. -2. Ensure that Optimize is launched. If it isn't, click the **Generate API key** button. -3. In Optimize, click your profile name in the top right corner of the navbar. -4. Select **Settings**. -5. Click **Create API key**. -6. Enter a name for the API key in the **Name** field, then click **Create**. -7. Copy the API key and store it securely. This will be used in your project's [`.env` file](/optimize/getting-started) via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button. - -You now have your Optimize API key. diff --git a/apps/docs/content/docs/console/index.mdx b/apps/docs/content/docs/console/index.mdx index cf2ef66113..7af9fa1dc9 100644 --- a/apps/docs/content/docs/console/index.mdx +++ b/apps/docs/content/docs/console/index.mdx @@ -11,7 +11,7 @@ metaDescription: Learn about the Console to integrate the Prisma Data Platform p The [Console](https://console.prisma.io/login) enables you to manage and configure your projects that use Prisma products, and helps you integrate them into your application: -- [Optimize](/optimize): Provides you with recommendations that can help you make your database queries faster. +- [Query Insights](/query-insights): Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes. - [Prisma Postgres](/postgres): A managed PostgreSQL database that is optimized for Prisma ORM. ## Getting started diff --git a/apps/docs/content/docs/orm/more/best-practices.mdx b/apps/docs/content/docs/orm/more/best-practices.mdx index 569930de34..f2ad4a0b9f 100644 --- a/apps/docs/content/docs/orm/more/best-practices.mdx +++ b/apps/docs/content/docs/orm/more/best-practices.mdx @@ -460,6 +460,6 @@ Creating a new client inside the handler on every invocation risks exhausting da ## Next steps -- [Query optimization](/optimize/recommendations) +- [Query optimization](/query-insights) - [Raw queries](/orm/prisma-client/using-raw-sql/raw-queries) - [Prisma Migrate workflows](/orm/prisma-migrate/workflows/development-and-production) diff --git a/apps/docs/content/docs/orm/prisma-client/queries/advanced/query-optimization-performance.mdx b/apps/docs/content/docs/orm/prisma-client/queries/advanced/query-optimization-performance.mdx index bb91ac61d6..7eed33f1eb 100644 --- a/apps/docs/content/docs/orm/prisma-client/queries/advanced/query-optimization-performance.mdx +++ b/apps/docs/content/docs/orm/prisma-client/queries/advanced/query-optimization-performance.mdx @@ -1,12 +1,47 @@ --- -title: Query optimization using Prisma Optimize -description: How Prisma optimizes queries under the hood +title: Query optimization +description: How to identify and optimize query performance with Prisma url: /orm/prisma-client/queries/advanced/query-optimization-performance -metaTitle: Query optimization using Prisma Optimize -metaDescription: How Prisma optimizes queries under the hood +metaTitle: Query optimization +metaDescription: How to identify and optimize query performance with Prisma --- -This guide covers identifying and optimizing query performance. +This page covers identifying and optimizing query performance with Prisma ORM. + +## Query Insights + +[Query Insights](/query-insights) is built into Prisma Postgres and shows you which queries are slow, how expensive they are, and what to fix. It works out of the box for raw SQL, but to see Prisma ORM operations (model name, action, query shape) you need one extra step. + +### Enabling Prisma ORM attribution + +Install `@prisma/sqlcommenter-query-insights`: + +```bash +npm install @prisma/sqlcommenter-query-insights +``` + +Then pass it to the `comments` option in your `PrismaClient` constructor: + +```ts +import { prismaQueryInsights } from "@prisma/sqlcommenter-query-insights"; +import { PrismaClient } from "@prisma/client"; + +const prisma = new PrismaClient({ + adapter: myAdapter, // driver adapter or Accelerate URL required + comments: [prismaQueryInsights()], +}); +``` + +This adds a SQL comment to every query containing the model, action, and parameterized query shape. Query Insights uses these annotations to trace SQL back to the exact Prisma call that generated it — even when a single Prisma call produces multiple SQL statements. + +#### Let your AI agent handle setup + +Copy this prompt into your AI coding assistant: + +``` +Install and configure @prisma/sqlcommenter-query-insights in my project so I can +see Prisma ORM queries in Query Insights. Docs: https://www.prisma.io/docs/query-insights +``` ## Debugging performance issues @@ -16,7 +51,7 @@ Common causes of slow queries: - Not caching repeated queries - Full table scans -[Prisma Optimize](/optimize) provides [recommendations](/optimize/recommendations) to address these issues. Follow the [integration guide](/optimize/getting-started) to get started. +Use [Query Insights](/query-insights) to identify which queries are affected and what to change. ## Using bulk queries diff --git a/apps/docs/content/docs/postgres/database/query-insights.mdx b/apps/docs/content/docs/postgres/database/query-insights.mdx index 1318910cdc..cf3eb61672 100644 --- a/apps/docs/content/docs/postgres/database/query-insights.mdx +++ b/apps/docs/content/docs/postgres/database/query-insights.mdx @@ -6,7 +6,7 @@ metaTitle: Query Insights with Prisma Postgres metaDescription: Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres. --- -Query Insights is built into Prisma Postgres and helps you understand which queries are slow, why they are expensive, and what to change next. It works out of the box with no agents or instrumentation required. +Query Insights is built into Prisma Postgres and helps you understand which queries are slow, why they are expensive, and what to change next. It is available in the [Prisma Console](https://console.prisma.io). For Prisma ORM queries, it connects your Prisma calls to the SQL they generate, including when a single call expands into multiple statements. For raw SQL or queries issued outside Prisma ORM, it still shows full SQL behavior. @@ -27,5 +27,5 @@ Query Insights is most useful for diagnosing N+1 patterns, missing indexes, over Query Insights is included with Prisma Postgres at no extra cost. :::info -Query Insights has its own dedicated section with full documentation, examples, and a step-by-step workflow. See [Query Insights](/docs/query-insights). +Query Insights has its own dedicated section with full documentation, examples, and setup instructions. See [Query Insights](/query-insights). ::: \ No newline at end of file diff --git a/apps/docs/content/docs/postgres/faq.mdx b/apps/docs/content/docs/postgres/faq.mdx index c9f7a67bc9..be1d68953e 100644 --- a/apps/docs/content/docs/postgres/faq.mdx +++ b/apps/docs/content/docs/postgres/faq.mdx @@ -344,50 +344,45 @@ Check the [pricing page](https://www.prisma.io/pricing) for more details on the While you can increase these limits based on your subscription plan, it's _still_ recommended to optimize your database operations. [Learn more in our troubleshooting guide.](/postgres/error-reference) ::: -## Query optimization +## Query Insights -Prisma Postgres allows query optimization via [Prisma Optimize](/optimize) and provides performance recommendations to help improve your database queries during development. You can enable it with Prisma Postgres or [also use it with your own database](/optimize/getting-started), but setup and integration steps differ. +[Query Insights](/query-insights) is built into Prisma Postgres and helps you identify slow queries, understand their cost, and decide what to fix. -### Can you automatically implement optimizations? +### I only see raw SQL — how do I see my Prisma ORM queries? -Prisma Postgres's query optimization feature offers insights and recommendations on how to improve your database queries. It does not alter any existing queries or your Prisma schema. +By default, Query Insights shows raw SQL. To also see the Prisma ORM operation that generated each query (model name, action, and query shape), install the `@prisma/sqlcommenter-query-insights` package: -### How long is a recording session retained? - -There are no limits on the storage retention period. A query performance recording session will be stored until you explicitly delete it. - -### Do recommendation limits reset monthly? - -Yes, the recommendation usage resets at the beginning of each calendar month. For example, if you use `5` recommendations by the end of the month, your usage will reset to `0` at the start of the next month. - -### Can I get charged for exceeding the recommendation limit on the starter plan? +```bash +npm install @prisma/sqlcommenter-query-insights +``` -Yes, if you’re on the starter plan, exceeding `5` recommendations in a billing cycle will result in a `$5` charge at the end of that cycle. For more information, visit [our pricing page](https://www.prisma.io/pricing#optimize). +Then pass it to the `comments` option in your `PrismaClient` constructor: -### How are viewed Prisma AI recommendations tracked for billing? Are they counted based on generated or viewed recommendations? +```ts +import { prismaQueryInsights } from "@prisma/sqlcommenter-query-insights"; +import { PrismaClient } from "@prisma/client"; -They are counted based on viewed recommendations. Once you click on a recommendation from the recommendations table and view the recommendation's detail page, it counts as being seen. +const prisma = new PrismaClient({ + adapter: myAdapter, + comments: [prismaQueryInsights()], +}); +``` -### Can I enable query optimizations for Prisma Postgres in production? +This annotates every query with a SQL comment containing the model, action, and parameterized query shape. Query Insights uses these annotations to map SQL back to the Prisma call that generated it. -No, query optimizations for Prisma Postgres is not meant to be enabled for production use. It is specifically designed for local development, providing valuable insights and optimizations during that phase. While it's technically possible to run it in a production environment, doing so could result in performance problems or unexpected behaviors, as this is not built to handle the complexity and scale of production workloads. For the best experience, we recommend testing query optimization solely in your development environment. +#### Let your AI agent handle setup -You can use the `enable` property in the client extension to run it [only in development environment](https://www.npmjs.com/package/@prisma/extension-optimize). By default, the `enable` property is set to `true`. +Copy this prompt into your AI coding assistant: -```ts title="script.ts" copy showLineNumbers -import { PrismaClient } from "@prisma/client"; -import { withOptimize } from "@prisma/extension-optimize"; - -const prisma = new PrismaClient().$extends( - withOptimize({ - apiKey: process.env.OPTIMIZE_API_KEY, - enable: process.env.ENVIRONMENT === "development", - }), -); ``` +Install and configure @prisma/sqlcommenter-query-insights in my project so I can +see Prisma ORM queries in Query Insights. Docs: https://www.prisma.io/docs/query-insights +``` + +### Does Query Insights alter my queries or schema? -### Why do I see "[optimize] HTTP 409 Conflict: There is no active recording to write queries to" warning? +No. Query Insights is read-only — it observes query behavior but does not rewrite queries or modify your Prisma schema. -This warning may occur when Prisma Optimize receives queries but no recording session is active. Typically, this can happen if Prisma Optimize is unintentionally enabled in your production environment. Prisma Optimize is specifically designed for use in local development environments and should not be enabled in production. To avoid this warning, ensure that Prisma Optimize is configured to run only during development. +### Can I use Query Insights in production? -If you are seeing this warning in your development environment, ensure that you have started a recording session in the Prisma Optimize Dashboard. +Query Insights is designed primarily for development and debugging. Running it in production is possible but not recommended, as the SQL comment annotations add a small overhead to every query. diff --git a/apps/docs/content/docs/query-insights/index.mdx b/apps/docs/content/docs/query-insights/index.mdx index 006f75d340..17e2268d77 100644 --- a/apps/docs/content/docs/query-insights/index.mdx +++ b/apps/docs/content/docs/query-insights/index.mdx @@ -6,12 +6,10 @@ metaTitle: Query Insights with Prisma Postgres metaDescription: Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres. --- -Query Insights is built into Prisma Postgres and helps you understand which queries are slow, why they are expensive, and what to change next. It works out of the box with no agents or instrumentation required, and it does not automatically rewrite your queries or schema. - -For Prisma ORM queries, it connects your Prisma calls to the SQL they generate, including when a single call expands into multiple statements. For raw SQL or queries issued outside Prisma ORM, it still shows full SQL behavior. +Query Insights is built into Prisma Postgres and helps you understand which queries are slow, why they are expensive, and what to change next. It does not automatically rewrite your queries or schema. :::info -Query Insights replaces Prisma Optimize and is now included with Prisma Postgres at no extra cost. +Query Insights replaces Prisma Optimize and is now included with Prisma Postgres at no extra cost. You can try it today in the [Prisma Console](https://console.prisma.io). ::: ## Dashboard @@ -57,25 +55,52 @@ The detail view shows: - A stat summary describing the query's table, execution count, average latency, and reads per call - The full SQL statement - An AI-generated analysis explaining whether the query needs optimization and why -- A copyable prompt you can paste into your editor to apply the fix +- A copyable prompt you can paste directly into your editor or an AI coding assistant to apply the suggested fix -This is where Query Insights becomes actionable. Instead of only seeing that a query is expensive, you can move from symptom to root cause to fix without leaving your workflow. +The AI analysis describes the likely cause of the performance issue, the specific change it recommends, and the expected impact. The copyable prompt includes your actual query along with context, so you can paste it into your editor or a tool like Cursor, Copilot, or Claude and get a concrete code change without switching context. :::info Treat the AI analysis as a starting point, not a final answer. Review any suggested change before shipping it. ::: -## Prisma context +## Prisma ORM attribution + +When using Prisma ORM, Query Insights can trace the full chain from your application code to the SQL it generates. This means you can see which `prisma.*` call produced a slow query, even when a single Prisma call expands into multiple SQL statements. + +For raw SQL or queries issued outside Prisma ORM, Query Insights still shows full SQL behavior, but ORM-level attribution requires the steps below. + +### Setup + +To enable ORM attribution, install the `@prisma/sqlcommenter-query-insights` package: + +```bash +npm install @prisma/sqlcommenter-query-insights +``` -The main difference between Query Insights and a SQL-only dashboard is attribution. +Then pass it to the `comments` option in your `PrismaClient` constructor: -With Prisma ORM queries, Query Insights traces the full chain: from the slow endpoint, to the Prisma query responsible, to the SQL it generated and its runtime impact. This is especially useful when a single Prisma call expands into multiple SQL statements, because you can inspect that relationship in one place instead of correlating it manually across logs and code. +```ts +import "dotenv/config"; +import { PrismaClient } from "../generated/prisma/client"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { prismaQueryInsights } from "@prisma/sqlcommenter-query-insights"; + +const adapter = new PrismaPg({ + connectionString: process.env.DATABASE_URL, +}); + +export const prisma = new PrismaClient({ + adapter: adapter, + comments: [prismaQueryInsights()], +}) + +``` -For queries issued outside Prisma ORM, Query Insights still shows full SQL behavior, but ORM-to-SQL attribution is exclusive to Prisma ORM. +This adds SQL comment annotations to queries so Query Insights can map SQL statements back to the Prisma calls that generated them. It is built on top of the [SQL comments](/orm/prisma-client/observability-and-logging/sql-comments) feature in Prisma Client. ## Availability -Query Insights is included with Prisma Postgres. +Query Insights is included with Prisma Postgres at no extra cost. You can try it today in the [Prisma Console](https://console.prisma.io). ## Typical issues @@ -155,4 +180,4 @@ The same pattern applies to other issues. Query Insights helps you identify the - Review [Connection pooling](/postgres/database/connection-pooling) for high-concurrency workloads - Use [Direct connections](/postgres/database/direct-connections) when connecting Prisma Postgres from other tools -- See [Prisma Client query optimization](/orm/prisma-client/queries/advanced/query-optimization-performance) for related Prisma ORM patterns \ No newline at end of file +- See [Prisma Client query optimization](/orm/prisma-client/queries/advanced/query-optimization-performance) for related Prisma ORM patterns diff --git a/apps/docs/cspell.json b/apps/docs/cspell.json index c6ac0098fa..89fe681676 100644 --- a/apps/docs/cspell.json +++ b/apps/docs/cspell.json @@ -258,6 +258,7 @@ "sslmode", "sslpassword", "Stammerjohann", + "Sunsetting", "Streamdal", "streamdal", "Subtacts", diff --git a/apps/docs/src/app/(docs)/(default)/layout.tsx b/apps/docs/src/app/(docs)/(default)/layout.tsx index 7ddbad0e2d..65f2e7dd55 100644 --- a/apps/docs/src/app/(docs)/(default)/layout.tsx +++ b/apps/docs/src/app/(docs)/(default)/layout.tsx @@ -9,6 +9,8 @@ import { StatusIndicator } from "@/components/status-indicator"; import { SidebarBannerCarousel } from "@/components/sidebar-banner"; import { fetchOgImage } from "@/lib/og-image"; import { cn } from "@prisma-docs/ui/lib/cn"; +import { getPageBadges } from "@/lib/page-badges"; +import { BadgeProvider, SidebarBadgeItem } from "@/components/sidebar-badge-provider"; // Sidebar announcement slides — set to [] to hide the banner const SIDEBAR_SLIDES = [ @@ -43,23 +45,28 @@ export default async function Layout({ children }: { children: React.ReactNode } }), ); + const badges = Object.fromEntries(getPageBadges()); + return ( - ) => ( -
- - -
- ), - }} - tree={source.pageTree} - > - {children} - + + ) => ( +
+ + +
+ ), + }} + tree={source.pageTree} + > + {children} + + ); } diff --git a/apps/docs/src/app/(docs)/v6/layout.tsx b/apps/docs/src/app/(docs)/v6/layout.tsx index fea68729f1..43df0407e7 100644 --- a/apps/docs/src/app/(docs)/v6/layout.tsx +++ b/apps/docs/src/app/(docs)/v6/layout.tsx @@ -33,11 +33,6 @@ export default async function Layout({ url: '/v6/accelerate', active: 'nested-url', }, - { - text: 'Optimize', - url: '/v6/optimize', - active: 'nested-url', - }, { text: 'Guides', url: '/v6/guides', diff --git a/apps/docs/src/components/sidebar-badge-provider.tsx b/apps/docs/src/components/sidebar-badge-provider.tsx new file mode 100644 index 0000000000..0ea9fa120f --- /dev/null +++ b/apps/docs/src/components/sidebar-badge-provider.tsx @@ -0,0 +1,52 @@ +'use client'; +import { createContext, use, type FC, type ReactNode } from "react"; +import type * as PageTree from "fumadocs-core/page-tree"; +import { SidebarItem } from "@/components/layout/notebook/sidebar"; +import { Badge } from "@prisma/eclipse"; + +export type BadgeType = "early-access" | "deprecated" | "preview"; + +const BadgeContext = createContext>({}); + +export function BadgeProvider({ + badges, + children, +}: { + badges: Record; + children: ReactNode; +}) { + return {children}; +} + +const BADGE_LABEL: Record = { + "early-access": "Early Access", + preview: "Preview", + deprecated: "Deprecated", +}; + +const BADGE_COLOR: Record = { + "early-access": "ppg", + preview: "neutral", + deprecated: "warning", +}; + +export const SidebarBadgeItem: FC<{ item: PageTree.Item }> = ({ item }) => { + const badges = use(BadgeContext); + const badge = badges[item.url] as BadgeType | undefined; + + return ( + + + {item.name} + {badge && ( + + )} + + + ); +}; diff --git a/apps/docs/src/components/version-switcher.tsx b/apps/docs/src/components/version-switcher.tsx index ca079a2d1a..d5d9bf5163 100644 --- a/apps/docs/src/components/version-switcher.tsx +++ b/apps/docs/src/components/version-switcher.tsx @@ -26,7 +26,7 @@ export function VersionSwitcher({ currentVersion }: VersionSwitcherProps) { const VERSION_SECTIONS: Record> = { v7: new Set(['accelerate', 'ai', 'cli', 'console', 'guides', 'management-api', 'optimize', 'orm', 'postgres', 'studio']), - v6: new Set(['accelerate', 'ai', 'guides', 'optimize', 'orm', 'platform', 'postgres']), + v6: new Set(['accelerate', 'ai', 'guides', 'orm', 'platform', 'postgres']), }; const rawPath = pathname.replace(/^\/v\d+(?=\/|$)/, '') || '/'; diff --git a/apps/docs/vercel.json b/apps/docs/vercel.json index 97f1a5172c..51abcc3337 100644 --- a/apps/docs/vercel.json +++ b/apps/docs/vercel.json @@ -263,6 +263,8 @@ {"source": "/docs/postgres/query-optimization/recommendations/unnecessary-indexes", "destination": "/docs/orm/prisma-client/queries/advanced/query-optimization-performance", "permanent": true}, {"source": "/docs/postgres/query-optimization/recordings", "destination": "/docs/orm/prisma-client/queries/advanced/query-optimization-performance", "permanent": true}, {"source": "/docs/postgres/query-optimization/setup", "destination": "/docs/orm/prisma-client/queries/advanced/query-optimization-performance", "permanent": true}, + {"source": "/v6/optimize/:path*", "destination": "/query-insights", "permanent": true}, + {"source": "/v6/postgres/query-optimization/:path*", "destination": "/query-insights", "permanent": true}, {"source": "/docs/postgres/integrations/viewing-data", "destination": "/docs/guides/postgres/viewing-data", "permanent": true}, {"source": "/docs/orm/prisma-client/queries/case-sensitivity", "destination": "/docs/orm/prisma-client/queries/crud", "permanent": true}, {"source": "/docs/orm/prisma-client/queries/computed-fields", "destination": "/docs/orm/prisma-client/queries/crud", "permanent": true},