From 4aa1a484060820e77744974ee2bb5be9b935f1c4 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 07:50:34 -0400 Subject: [PATCH 01/11] docs(query-insights): add early access badge, expand AI prompt section, add sqlcommenter setup --- .../docs/postgres/database/query-insights.mdx | 5 ++- .../content/docs/query-insights/index.mdx | 45 ++++++++++++++----- 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/apps/docs/content/docs/postgres/database/query-insights.mdx b/apps/docs/content/docs/postgres/database/query-insights.mdx index 1318910cdc..6fc77c5b49 100644 --- a/apps/docs/content/docs/postgres/database/query-insights.mdx +++ b/apps/docs/content/docs/postgres/database/query-insights.mdx @@ -4,9 +4,10 @@ description: Inspect slow queries, connect Prisma calls to SQL, and apply focuse url: /postgres/database/query-insights metaTitle: Query Insights with Prisma Postgres metaDescription: Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres. +badge: "early-access" --- -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 currently in Early Access and available to try 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 +28,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](/docs/query-insights). ::: \ No newline at end of file diff --git a/apps/docs/content/docs/query-insights/index.mdx b/apps/docs/content/docs/query-insights/index.mdx index 006f75d340..7e14e2715d 100644 --- a/apps/docs/content/docs/query-insights/index.mdx +++ b/apps/docs/content/docs/query-insights/index.mdx @@ -4,14 +4,13 @@ description: Inspect slow queries, connect Prisma calls to SQL, and apply focuse url: /query-insights metaTitle: Query Insights with Prisma Postgres metaDescription: Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres. +badge: "early-access" --- -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 +56,47 @@ 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. -The main difference between Query Insights and a SQL-only dashboard is attribution. +### Setup + +To enable ORM attribution, install the `@prisma/sqlcommenter-query-insights` package: + +```bash +npm install @prisma/sqlcommenter-query-insights +``` -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. +Then add it as a Prisma Client extension: + +```ts +import "dotenv/config"; +import { PrismaPg } from "@prisma/adapter-pg"; +import { PrismaClient } from "../generated/prisma/client"; +import { withQueryInsights } from "@prisma/sqlcommenter-query-insights"; + +const connectionString = `${process.env.DATABASE_URL}`; + +const adapter = new PrismaPg({ connectionString }); +const prisma = new PrismaClient({ adapter }).$extends(withQueryInsights()); +``` -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 and is currently in Early Access. You can try it today in the [Prisma Console](https://console.prisma.io). ## Typical issues @@ -155,4 +176,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 From ae3ab9bb3b8031a12ea4a367a2b2bd4afe648235 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 07:59:57 -0400 Subject: [PATCH 02/11] feat(docs): more dropdown badge added --- apps/docs/src/lib/layout.shared.tsx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/apps/docs/src/lib/layout.shared.tsx b/apps/docs/src/lib/layout.shared.tsx index ecad3a97cc..f5d492e781 100644 --- a/apps/docs/src/lib/layout.shared.tsx +++ b/apps/docs/src/lib/layout.shared.tsx @@ -4,6 +4,7 @@ import logoDark from "../../public/img/logo-dark.svg"; import logoWhite from "../../public/img/logo-white.svg"; import { DiscordIcon } from "@/components/icons/discord"; import Link from "next/link"; +import { Badge } from "@prisma/eclipse"; export const logo = ( <> @@ -50,7 +51,16 @@ export const links: LinkItemTypeWithActivePaths[] = [ { text: "Management API", url: "/management-api", active: "nested-url" }, { text: "Studio", url: "/studio", active: "nested-url" }, { text: "AI", url: "/ai", active: "nested-url" }, - { text: "Query Insights", url: "/query-insights", active: "nested-url" }, + { + text: ( + + Query Insights + + + ), + url: "/query-insights", + active: "nested-url", + }, { text: "Accelerate", url: "/accelerate", active: "nested-url" }, { text: "Console", url: "/console", active: "nested-url" }, ], From 5150a40a92bb2c036153cff1c299d5b75dede4e3 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 08:06:41 -0400 Subject: [PATCH 03/11] feat(docs): sidebar badges added --- apps/docs/src/app/(docs)/(default)/layout.tsx | 41 +++++++++------ .../src/components/sidebar-badge-provider.tsx | 52 +++++++++++++++++++ 2 files changed, 76 insertions(+), 17 deletions(-) create mode 100644 apps/docs/src/components/sidebar-badge-provider.tsx 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/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 && ( + + )} + + + ); +}; From f5000579a1b52c1c2e2b7ca56faef1217123f9ff Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 08:29:47 -0400 Subject: [PATCH 04/11] fix(docs): broken links updated, and optimize page status changed to deprecated --- apps/docs/content/docs/accelerate/getting-started.mdx | 2 +- apps/docs/content/docs/console/features/optimize.mdx | 5 +++++ apps/docs/content/docs/console/index.mdx | 2 +- apps/docs/content/docs/orm/more/best-practices.mdx | 2 +- .../queries/advanced/query-optimization-performance.mdx | 2 +- apps/docs/content/docs/postgres/database/query-insights.mdx | 2 +- apps/docs/content/docs/postgres/faq.mdx | 2 +- 7 files changed, 11 insertions(+), 6 deletions(-) diff --git a/apps/docs/content/docs/accelerate/getting-started.mdx b/apps/docs/content/docs/accelerate/getting-started.mdx index 9f94a0968c..0444049313 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/optimize.mdx b/apps/docs/content/docs/console/features/optimize.mdx index 9d67181b4c..f06572c85a 100644 --- a/apps/docs/content/docs/console/features/optimize.mdx +++ b/apps/docs/content/docs/console/features/optimize.mdx @@ -4,8 +4,13 @@ description: Access the Optimize dashboard and generate API keys for query perfo 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 +badge: "deprecated" --- +:::warning +**Sunsetting Optimize** — Optimize is being retired on March 23. We're replacing it with [Query Insights](/query-insights), which is ready to use out of the box. +::: + You can access Optimize within your [Prisma Data Platform account](https://console.prisma.io/optimize) workspace. ## Accessing the Optimize dashboard 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..7ea6e79c0b 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 @@ -16,7 +16,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. +[Query Insights](/query-insights) helps you identify and address these issues. ## 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 6fc77c5b49..eaa424a81f 100644 --- a/apps/docs/content/docs/postgres/database/query-insights.mdx +++ b/apps/docs/content/docs/postgres/database/query-insights.mdx @@ -28,5 +28,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 setup instructions. 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..2715358c52 100644 --- a/apps/docs/content/docs/postgres/faq.mdx +++ b/apps/docs/content/docs/postgres/faq.mdx @@ -346,7 +346,7 @@ While you can increase these limits based on your subscription plan, it's _still ## Query optimization -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. +Prisma Postgres includes [Query Insights](/query-insights), which helps you identify slow queries and improve your database performance during development. ### Can you automatically implement optimizations? From bc576048307d017acb72c263c3f91b1160587f29 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 09:40:18 -0400 Subject: [PATCH 05/11] fix(): broken checks fixed --- .github/workflows/lychee.yml | 20 +++++++++---------- .../docs/console/features/optimize.mdx | 2 +- apps/docs/cspell.json | 1 + 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index dc32409feb..f408219083 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -159,16 +159,16 @@ jobs: echo "" >> lychee/formatted.md # Hard truncate as a final guardrail for sticky PR comments - python - <<'PY' - from pathlib import Path - p = Path("lychee/formatted.md") - if p.exists(): - max_chars = 60000 - text = p.read_text(encoding="utf-8") - if len(text) > max_chars: - note = "\n\n_Comment truncated to avoid GitHub body limit. Download the artifact for full details._\n" - p.write_text(text[: max_chars - len(note)] + note, encoding="utf-8") - PY + python - <<'PY' + from pathlib import Path + p = Path("lychee/formatted.md") + if p.exists(): + max_chars = 60000 + text = p.read_text(encoding="utf-8") + if len(text) > max_chars: + note = "\n\n_Comment truncated to avoid GitHub body limit. Download the artifact for full details._\n" + p.write_text(text[: max_chars - len(note)] + note, encoding="utf-8") + PY else # Ensure sticky PR comment always has content even if Lychee output is missing cat > lychee/formatted.md <<'EOF' diff --git a/apps/docs/content/docs/console/features/optimize.mdx b/apps/docs/content/docs/console/features/optimize.mdx index f06572c85a..35341d38b3 100644 --- a/apps/docs/content/docs/console/features/optimize.mdx +++ b/apps/docs/content/docs/console/features/optimize.mdx @@ -30,6 +30,6 @@ To obtain the Optimize API key: 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. +7. Copy the API key and store it securely. This will be used in your project's `.env` file via the `"OPTIMIZE_API_KEY"` environment variable. Finally, click the **"I've stored it securely"** button. You now have your Optimize API key. 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", From 13fa72a09a8e982a356b0a478663d0521fc9bcea Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 09:59:40 -0400 Subject: [PATCH 06/11] fix(): revert lychee back --- .github/workflows/lychee.yml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index f408219083..c2453b4530 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -159,16 +159,16 @@ jobs: echo "" >> lychee/formatted.md # Hard truncate as a final guardrail for sticky PR comments - python - <<'PY' - from pathlib import Path - p = Path("lychee/formatted.md") - if p.exists(): - max_chars = 60000 - text = p.read_text(encoding="utf-8") - if len(text) > max_chars: - note = "\n\n_Comment truncated to avoid GitHub body limit. Download the artifact for full details._\n" - p.write_text(text[: max_chars - len(note)] + note, encoding="utf-8") - PY + python - <<'PY' + from pathlib import Path + p = Path("lychee/formatted.md") + if p.exists(): + max_chars = 60000 + text = p.read_text(encoding="utf-8") + if len(text) > max_chars: + note = "\n\n_Comment truncated to avoid GitHub body limit. Download the artifact for full details._\n" + p.write_text(text[: max_chars - len(note)] + note, encoding="utf-8") + PY else # Ensure sticky PR comment always has content even if Lychee output is missing cat > lychee/formatted.md <<'EOF' @@ -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 From 19db1fb0f22f718759ebf72d42e7e4d95fa2247c Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 17 Mar 2026 12:27:28 -0400 Subject: [PATCH 07/11] fix(docs): remove optimize and fix links --- .../docs.v6/accelerate/getting-started.mdx | 2 +- apps/docs/content/docs.v6/meta.json | 1 - apps/docs/content/docs.v6/optimize/faq.mdx | 9 -- .../docs.v6/optimize/getting-started.mdx | 103 ------------------ apps/docs/content/docs.v6/optimize/index.mdx | 33 ------ .../docs.v6/optimize/known-limitations.mdx | 53 --------- apps/docs/content/docs.v6/optimize/meta.json | 14 --- .../docs.v6/optimize/performance-metrics.mdx | 11 -- .../content/docs.v6/optimize/prisma-ai.mdx | 9 -- .../docs.v6/optimize/recommendations.mdx | 26 ----- .../content/docs.v6/optimize/recordings.mdx | 11 -- .../query-optimization-performance.mdx | 6 +- .../prisma-client/queries/select-fields.mdx | 2 +- apps/docs/content/docs.v6/platform/about.mdx | 4 +- apps/docs/content/docs.v6/postgres/faq.mdx | 2 +- apps/docs/content/docs.v6/postgres/meta.json | 1 - .../postgres/query-optimization/index.mdx | 15 --- .../postgres/query-optimization/meta.json | 4 - .../performance-metrics.mdx | 29 ----- .../postgres/query-optimization/prisma-ai.mdx | 18 --- .../recommendations/avoid-char.mdx | 23 ---- .../recommendations/avoid-db-money.mdx | 27 ----- .../avoid-timestamp-timestampz-0.mdx | 26 ----- .../recommendations/avoid-varchar.mdx | 23 ---- .../recommendations/current-time.mdx | 17 --- .../excessive-number-of-rows-returned.mdx | 30 ----- ...-table-scans-caused-by-like-operations.mdx | 33 ------ .../recommendations/index.mdx | 13 --- .../indexing-on-unique-columns.mdx | 21 ---- .../long-running-transactions.mdx | 44 -------- .../recommendations/meta.json | 21 ---- .../queries-on-unindexed-columns.mdx | 84 -------------- .../recommendations/repeated-query.mdx | 28 ----- .../recommendations/select-returning.mdx | 31 ------ .../storing-blob-in-database.mdx | 30 ----- .../recommendations/unnecessary-indexes.mdx | 19 ---- .../query-optimization/recordings.mdx | 58 ---------- .../postgres/query-optimization/setup.mdx | 85 --------------- .../content/docs/console/features/meta.json | 3 +- .../docs/console/features/optimize.mdx | 35 ------ .../docs/postgres/database/query-insights.mdx | 3 +- .../content/docs/query-insights/index.mdx | 3 +- apps/docs/src/app/(docs)/v6/layout.tsx | 5 - apps/docs/src/components/version-switcher.tsx | 2 +- apps/docs/src/lib/layout.shared.tsx | 12 +- apps/docs/vercel.json | 2 + 46 files changed, 14 insertions(+), 1017 deletions(-) delete mode 100644 apps/docs/content/docs.v6/optimize/faq.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/getting-started.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/index.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/known-limitations.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/meta.json delete mode 100644 apps/docs/content/docs.v6/optimize/performance-metrics.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/prisma-ai.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/recommendations.mdx delete mode 100644 apps/docs/content/docs.v6/optimize/recordings.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/index.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/meta.json delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/performance-metrics.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/prisma-ai.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-char.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-db-money.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-timestamp-timestampz-0.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/avoid-varchar.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/current-time.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/excessive-number-of-rows-returned.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/full-table-scans-caused-by-like-operations.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/index.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/indexing-on-unique-columns.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/long-running-transactions.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/meta.json delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/queries-on-unindexed-columns.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/repeated-query.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/select-returning.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/storing-blob-in-database.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recommendations/unnecessary-indexes.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/recordings.mdx delete mode 100644 apps/docs/content/docs.v6/postgres/query-optimization/setup.mdx delete mode 100644 apps/docs/content/docs/console/features/optimize.mdx 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..89f08b2711 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 @@ -19,13 +19,11 @@ Several common practices can lead to slow queries and performance problems, such :::info -For more potential causes of performance issues, visit [this page](/v6/optimize/recommendations). +For more potential causes of performance issues, visit [Query Insights](/query-insights). ::: -[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. +[Query Insights](/query-insights) helps identify and address the inefficiencies listed above and more, helping to improve query performance.
-
+Use [Query Insights](/query-insights) to identify which queries are affected and what to change. :::tip diff --git a/apps/docs/content/docs.v6/postgres/faq.mdx b/apps/docs/content/docs.v6/postgres/faq.mdx index 551dc24c9e..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 includes [Query Insights](/query-insights), which provides performance recommendations to help improve your database queries. +[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/orm/prisma-client/queries/advanced/query-optimization-performance.mdx b/apps/docs/content/docs/orm/prisma-client/queries/advanced/query-optimization-performance.mdx index 7ea6e79c0b..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 -[Query Insights](/query-insights) helps you identify and address these issues. +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/faq.mdx b/apps/docs/content/docs/postgres/faq.mdx index 2715358c52..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 includes [Query Insights](/query-insights), which helps you identify slow queries and improve your database performance during development. +[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. From 5849908ee7b005c7bae8eb11152611d8a6e9e38f Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 18 Mar 2026 07:48:00 -0400 Subject: [PATCH 10/11] fix(docs): more removals of optimize --- .../prisma-client/queries/select-fields.mdx | 2 +- apps/docs/content/docs.v6/platform/about.mdx | 29 +++---------------- 2 files changed, 5 insertions(+), 26 deletions(-) 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 2dd1d31e27..867b59edea 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 [Query Insights](/query-insights) 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](/v6/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 dcba25184a..7101ebd1b2 100644 --- a/apps/docs/content/docs.v6/platform/about.mdx +++ b/apps/docs/content/docs.v6/platform/about.mdx @@ -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 via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button. - -You now have your Optimize API key. +[Query Insights](/v6/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. From bdb3453fbd1b8341a5c1024f07cdd470552b7910 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 18 Mar 2026 13:39:03 -0400 Subject: [PATCH 11/11] fix(docs): broken link updates --- .../content/docs.v6/orm/prisma-client/queries/select-fields.mdx | 2 +- apps/docs/content/docs.v6/platform/about.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 867b59edea..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 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](/v6/postgres/database/query-insights) to identify slow queries and optimize performance. +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 7101ebd1b2..35079f89cb 100644 --- a/apps/docs/content/docs.v6/platform/about.mdx +++ b/apps/docs/content/docs.v6/platform/about.mdx @@ -59,7 +59,7 @@ detailed reports on how your database is performing, with various metrics like: #### Query Insights -[Query Insights](/v6/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. +[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