Skip to content

SQLCommenter for Drizzle

@query-doctor/sqlcommenter-drizzle patches Drizzle ORM so every SQL query it executes carries a structured comment with contextual metadata — the source file, HTTP route, request method, and OpenTelemetry trace context. Query Doctor reads these comments to connect slow or failing queries back to the code and request that produced them.

Prerequisites

Node.js >= 24.8.0
Drizzle ORM >= 0.35.0
ESM project ("type": "module" in your package.json) — the package does not ship a CommonJS build

Installation

npm
pnpm

npm install @query-doctor/sqlcommenter-drizzle

pnpm add @query-doctor/sqlcommenter-drizzle

Basic setup

Wrap your Drizzle instance with patchDrizzle:

import { drizzle } from "drizzle-orm/node-postgres";
import { patchDrizzle } from "@query-doctor/sqlcommenter-drizzle";

const db = patchDrizzle(drizzle(process.env.DATABASE_URL));

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

Field	Included by default	Description
`db_driver`	Yes	Identifies Drizzle as the driver
`file`	Yes	Source file that triggered the query
`route`	No	HTTP route (requires framework middleware)
`method`	No	HTTP request method (requires framework middleware)
Trace context	Automatic	OpenTelemetry trace/span IDs when a tracer is active
Custom fields	No	Any arbitrary key/value metadata you provide

Framework integration

To capture route and method, add the withRequestContext middleware from the /http export.

Express

import express from "express";
import { withRequestContext } from "@query-doctor/sqlcommenter-drizzle/http";

const app = express();
app.use(withRequestContext());

Hono

import { Hono } from "hono";
import { withRequestContext } from "@query-doctor/sqlcommenter-drizzle/http";

const app = new Hono();
app.use(withRequestContext());

Fastify

import Fastify from "fastify";
import { withRequestContext } from "@query-doctor/sqlcommenter-drizzle/http";

const fastify = Fastify();
fastify.addHook("onRequest", withRequestContext());

Database support

The package is primarily tested on PostgreSQL but should work with any database Drizzle supports, since the annotation is applied at the query string level.

Further reading