SQLCommenter for Prisma

Prisma 7.1+ has built-in SQLCommenter support via the comments option on PrismaClient. Combined with the @prisma/sqlcommenter-query-tags package for request-scoped tags, every SQL query Prisma executes can carry a structured comment with contextual metadata — the source file, HTTP route, request method, and custom fields. Query Doctor reads these comments to connect slow or failing queries back to the code and request that produced them.

Prerequisites

Prisma >= 7.1.0
@prisma/adapter-pg (or another Prisma driver adapter)
ESM project ("type": "module" in your package.json)

sh npm install @prisma/sqlcommenter @prisma/sqlcommenter-query-tags

sh pnpm add @prisma/sqlcommenter @prisma/sqlcommenter-query-tags

Basic setup

Pass an array of SqlCommenterPlugin functions to the comments option on PrismaClient:

import { PrismaClient } from "@prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
import { queryTags } from "@prisma/sqlcommenter-query-tags";
import type { SqlCommenterPlugin } from "@prisma/sqlcommenter";
import pg from "pg";

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const adapter = new PrismaPg(pool);

const appPlugin: SqlCommenterPlugin = (context) => ({
  db_driver: "prisma",
  ...(context.query.modelName && { model: context.query.modelName }),
  action: context.query.action,
});

const prisma = new PrismaClient({
  adapter,
  comments: [appPlugin, queryTags()],
});

Every query executed through prisma now includes a SQL comment with:

Field	Included by default	Description
`db_driver`	Yes	Identifies Prisma as the driver
`model`	Yes	Prisma model name (e.g. `User`, `Issue`)
`action`	Yes	Prisma operation (e.g. `findMany`, `create`)
`route`	No	HTTP route (requires framework middleware)
`method`	No	HTTP request method (requires framework middleware)
Custom fields	No	Any arbitrary key/value metadata you provide

Framework integration

To capture route and method, use withQueryTags from @prisma/sqlcommenter-query-tags as middleware. This uses AsyncLocalStorage to propagate tags through the request lifecycle.

Express

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

const app = express();

app.use((req, res, next) => {
  withQueryTags({ route: req.path, method: req.method }, async () => {
    return new Promise<void>((resolve) => {
      res.on("finish", resolve);
      next();
    });
  });
});

Hono

import { Hono } from "hono";
import { withQueryTags } from "@prisma/sqlcommenter-query-tags";

const app = new Hono();

app.use(async (c, next) => {
  await withQueryTags({ route: c.req.path, method: c.req.method }, () =>
    next(),
  );
});

Fastify

import Fastify from "fastify";
import { withQueryTags } from "@prisma/sqlcommenter-query-tags";

const fastify = Fastify();

fastify.addHook("onRequest", (request, reply, done) => {
  withQueryTags({ route: request.url, method: request.method }, async () => {
    return new Promise<void>((resolve) => {
      reply.raw.on("finish", resolve);
      done();
    });
  });
});

Database support

Prisma’s comments API works with any database that supports SQL comments, including PostgreSQL, MySQL, and SQLite.