@prisma/sqlcommenter

@prisma/sqlcommenter

Type definitions for SQL commenter plugins in Prisma Client.

Overview

This package provides TypeScript types for creating SQL commenter plugins that add metadata to SQL queries as comments. The comments follow the sqlcommenter format developed by Google.

SQL comments are useful for:

• Observability: Correlate database queries with application traces using traceparent
• Query Insights: Tag queries with metadata for analysis in database monitoring tools
• Debugging: Add custom context to queries for easier troubleshooting

Installation

npm install @prisma/sqlcommenter

Usage

Creating a Plugin

A SQL commenter plugin is a function that receives query context and returns key-value pairs to be added as comments:

import type { SqlCommenterPlugin, SqlCommenterContext } from '@prisma/sqlcommenter'

const myPlugin: SqlCommenterPlugin = (context: SqlCommenterContext) => {
  return {
    application: 'my-app',
    version: '1.0.0',
  }
}

Using Plugins with PrismaClient

Pass your plugins to the comments option when creating a PrismaClient instance:

import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: `${process.env.DATABASE_URL}` })

const prisma = new PrismaClient({
  adapter,
  comments: [myPlugin],
})

First-Party Plugins

• @prisma/sqlcommenter-query-tags: appends arbitrary tags to all queries within an async context.
• @prisma/sqlcommenter-trace-context: appends traceparent comments to SQL queries for distributed tracing.
• @prisma/sqlcommenter-query-insights: enables query insights for Prisma Postgres.

Query Context

Plugins receive a SqlCommenterContext object with information about the query being executed.

See API Reference for more details.

Conditional Keys

Plugins return a SqlCommenterTags object where keys can have undefined values. Keys with undefined values are automatically filtered out from the final comment:

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

const conditionalPlugin: SqlCommenterPlugin = (context) => ({
  model: context.query.modelName, // undefined for raw queries, automatically omitted
  action: context.query.action,
  // Include SQL length only when available (not available with Accelerate)
  sqlLength: context.sql ? String(context.sql.length) : undefined,
})

Example: Custom Application Tags

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

const applicationTags: SqlCommenterPlugin = (context) => ({
  application: 'my-service',
  environment: process.env.NODE_ENV ?? 'development',
  operation: context.query.action,
  model: context.query.modelName, // automatically omitted if undefined
})

Example: Async Context Propagation

import { AsyncLocalStorage } from 'node:async_hooks'
import type { SqlCommenterPlugin } from '@prisma/sqlcommenter'

const routeStorage = new AsyncLocalStorage<{ route: string }>()

const routeContext: SqlCommenterPlugin = () => ({
  route: routeStorage.getStore()?.route,
})

Output Format

The plugin outputs are merged, sorted by key, URL-encoded, and formatted according to the sqlcommenter specification:

SELECT "id", "name" FROM "User" /*application='my-app',environment='production',model='User'*/

API Reference

SqlCommenterTags

type SqlCommenterTags = { readonly [key: string]: string | undefined }

Key-value pairs to add as SQL comments. Keys with undefined values are automatically filtered out and will not appear in the final comment.

SqlCommenterPlugin

interface SqlCommenterPlugin {
  (context: SqlCommenterContext): SqlCommenterTags
}

A function that receives query context and returns key-value pairs. Return an empty object to add no comments for a particular query. Keys with undefined values are automatically omitted.

SqlCommenterContext

interface SqlCommenterContext {
  query: SqlCommenterQueryInfo
  sql?: string
}

Context provided to plugins containing information about the query.

• query: Information about the Prisma query being executed. See SqlCommenterQueryInfo.
• sql: The SQL query being executed. It is only available when using driver adapters but not when using Accelerate.

SqlCommenterQueryInfo

type SqlCommenterQueryInfo =
  | ({ type: 'single' } & SqlCommenterSingleQueryInfo)
  | ({ type: 'compacted' } & SqlCommenterCompactedQueryInfo)

Information about the query or queries being executed.

• type: 'single': A single Prisma query is being executed
• type: 'compacted': Multiple queries have been batched into a single SQL statement (e.g., automatic findUnique batching)

SqlCommenterSingleQueryInfo

interface SqlCommenterSingleQueryInfo {
  modelName?: string
  action: SqlCommenterQueryAction
  query: unknown
}

Information about a single Prisma query.

• modelName: The model being queried (e.g., "User", "Post"). Undefined for raw queries.
• action: The Prisma operation (e.g., "findMany", "createOne", "queryRaw")
• query: The full query object with selection and arguments. Specifics of the query representation are not part of the public API yet.

SqlCommenterCompactedQueryInfo

interface SqlCommenterCompactedQueryInfo {
  modelName?: string
  action: SqlCommenterQueryAction
  queries: unknown[]
}

Information about a compacted batch query.

• modelName: The model being queried (e.g., "User", "Post").
• action: The Prisma operation (e.g., "findUnique")
• queries: The full query objects with selections and arguments. Specifics of the query representation are not part of the public API yet.

Notes

• Plugins are called synchronously in array order
• Later plugins override earlier ones if they return the same key
• Keys with undefined values are filtered out (they do not remove keys set by earlier plugins)
• Keys and values are URL-encoded per the sqlcommenter spec
• Single quotes in values are escaped as \'
• Comments are appended to the end of SQL queries

License

Apache-2.0