prisma/prisma

SQL Commenter plugins

SQL Commenter plugins attach machine-readable comments to outgoing SQL so observability tools can correlate database activity with application context. The framework lives across four packages under packages/sqlcommenter* and runs inside @prisma/client-engine-runtime.

Lifecycle

graph LR
    Reg[new PrismaClient<br/>{ comments: [...] }] --> Client[PrismaClient]
    Client --> Engine[ClientEngine]
    Engine --> Plan[Query plan]
    Plan --> Interp[QueryInterpreter]
    Interp -->|emit SQL| Commenter[client-engine-runtime/src/sql-commenter.ts]
    Commenter --> P1[query-tags plugin]
    Commenter --> P2[trace-context plugin]
    Commenter --> P3[query-insights plugin]
    P1 -->|tag dict| Render[Tag serializer]
    P2 -->|tag dict| Render
    P3 -->|tag dict| Render
    Render --> SQL[Final SQL with /* tags */]
    SQL --> Adapter[Driver adapter]
    Adapter --> DB[(Database)]

The runtime in packages/client-engine-runtime/src/sql-commenter.ts invokes registered plugins in order, collects their tag dictionaries, and appends a serialized comment to the SQL before handing it to the adapter.

Plugin contract

From @prisma/sqlcommenter (packages/sqlcommenter/src/):

SqlCommenterPlugin — function signature every plugin satisfies
SqlCommenterContext — what plugins receive (transaction state, etc.)
SqlCommenterQueryInfo — per-query metadata; key field is type: 'single' | 'compacted'
SqlCommenterTags — Record<string, string> of comment key/value pairs the plugin returns

type: 'compacted' indicates the SQL is the result of DataLoader merging sibling queries into one statement; plugins receive metadata about all merged components.

Built-in plugins

Plugin	Package	Adds to comments
`withQueryTags`/`withMergedQueryTags`	`@prisma/sqlcommenter-query-tags`	Ad-hoc tags scoped via `AsyncLocalStorage`
`traceContextPlugin`	`@prisma/sqlcommenter-trace-context`	W3C Trace Context `traceparent` from OpenTelemetry
`queryInsightsPlugin`	`@prisma/sqlcommenter-query-insights`	Parameterized query shape (`Model.action:base64Payload`)

query-tags

Uses Node's AsyncLocalStorage to scope tags to async contexts:

import { withQueryTags } from '@prisma/sqlcommenter-query-tags';

withQueryTags({ requestId: ctx.requestId }, async () => {
  await prisma.user.findMany();
  // SQL receives /* requestId='...' */
});

withMergedQueryTags merges with an outer scope rather than replacing.

trace-context

Reads the active OTel context (via @opentelemetry/api) and emits traceparent. Useful for stitching SQL into distributed traces in APM tools that inspect SQL comments.

query-insights

Emits Model.action:<base64payload> where the payload describes the query shape — table, columns referenced, filter structure. The most recent commit on main (d6d9fc9ed, 2026-04-28) is chore: remove parameterization from sqlcommenter-query-insights (#29518) — parameter values are no longer transmitted, only the shape, for privacy.

Registration

import { withQueryTags } from '@prisma/sqlcommenter-query-tags';
import { traceContextPlugin } from '@prisma/sqlcommenter-trace-context';
import { PrismaClient } from './generated/client';

const prisma = new PrismaClient({
  comments: [queryTagsPlugin(), traceContextPlugin()],
});

comments is a constructor option validated in packages/client/src/runtime/utils/validatePrismaClientOptions.ts. Plugins run in registration order.

Custom plugins

A custom plugin is a function that returns a SqlCommenterPlugin. Implementing one only requires importing types from @prisma/sqlcommenter:

import type { SqlCommenterPlugin } from '@prisma/sqlcommenter';

export function customPlugin(): SqlCommenterPlugin {
  return {
    onQuery(info, context) {
      return { foo: 'bar' }; // adds /* foo='bar' */
    },
  };
}

E2E coverage

End-to-end tests for sqlcommenter plugins live in packages/client/tests/e2e/sqlcommenter* directories. They confirm comments survive into the actual SQL the database receives — important because SQL middleware in some adapters can rewrite statements.