prisma/prisma

SQL Commenter

Active contributors: jacek-prisma, Oleksii Orlenko

Purpose

SQL Commenter plugins attach machine-readable comments to outgoing SQL so observability tools can correlate database queries with application context (model, action, trace ID, custom tags). Prisma 7 ships a small framework for these plugins across four packages, all under packages/sqlcommenter*.

The plugins are registered through the comments option on PrismaClient:

new PrismaClient({
  comments: [queryTagsPlugin(), traceContextPlugin(), queryInsightsPlugin()],
});

The packages

Package	Path	What it provides
`@prisma/sqlcommenter`	`packages/sqlcommenter`	Core types: `SqlCommenterPlugin`, `SqlCommenterContext`, `SqlCommenterQueryInfo`, `SqlCommenterTags`
`@prisma/sqlcommenter-query-tags`	`packages/sqlcommenter-query-tags`	`withQueryTags()` / `withMergedQueryTags()` — AsyncLocalStorage-based ad-hoc tags
`@prisma/sqlcommenter-trace-context`	`packages/sqlcommenter-trace-context`	Adds W3C Trace Context `traceparent` to comments
`@prisma/sqlcommenter-query-insights`	`packages/sqlcommenter-query-insights`	Adds parameterized query shape (`Model.action:base64Payload`)

The contract

From AGENTS.md:

SqlCommenterPlugin — the function shape every plugin matches
SqlCommenterContext — what plugins receive (transaction state, etc.)
SqlCommenterQueryInfo — distinguishes type: 'single' (one query) vs type: 'compacted' (batched queries merged into one SQL statement)
SqlCommenterTags — the dictionary of comment key/value pairs the plugin produces

Plugins return tags; the runtime in packages/client-engine-runtime/src/sql-commenter.ts serializes them and appends them to the SQL.

Where plugins run

graph LR
    User[User code with PrismaClient] -->|action| RH[RequestHandler]
    RH --> Engine[ClientEngine]
    Engine --> Plan[Query plan]
    Plan --> Interp[QueryInterpreter]
    Interp -->|emit SQL| Commenter[sql-commenter.ts]
    Commenter -->|invoke| Plugin1[query-tags]
    Commenter -->|invoke| Plugin2[trace-context]
    Commenter -->|invoke| Plugin3[query-insights]
    Plugin1 --> SQLOut[Final SQL with comments]
    Plugin2 --> SQLOut
    Plugin3 --> SQLOut
    SQLOut --> Adapter[Driver adapter]

Plugin examples

sqlcommenter-query-tags — uses Node's AsyncLocalStorage so users can add tags scoped to an async context:

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

sqlcommenter-trace-context — reads the current OpenTelemetry context and appends the traceparent header to the comment, so APM tools can stitch SQL execution into the trace.

sqlcommenter-query-insights — emits a base64-encoded payload of the parameterized query shape (Model.action:<payload>), useful for backends that aggregate query patterns.

Recent change: removing parameterization

The latest commit on main (d6d9fc9ed on 2026-04-28) is chore: remove parameterization from sqlcommenter-query-insights (#29518). The query-insights plugin no longer transmits parameter values in the comment, only the query shape — a privacy improvement.

E2E coverage

Per AGENTS.md:

E2E tests for sqlcommenter plugins live in packages/client/tests/e2e/sqlcommenter* directories.

These test the full pipeline (PrismaClient → engine → adapter → real database), confirming the comments survive into the actual SQL the database receives.

Integration points

@prisma/client-engine-runtime runs plugins through sql-commenter.ts
@prisma/client accepts plugins through the comments constructor option
OpenTelemetry, AsyncLocalStorage — used by individual plugins

Entry points for modification

New built-in plugin: create a new packages/sqlcommenter-<name>/ following the same structure
Change comment serialization: packages/client-engine-runtime/src/sql-commenter.ts
Add a new plugin context field: extend SqlCommenterContext in packages/sqlcommenter