@prisma/sqlcommenter 0.0.1

package/README.md

@@ -0,0 +1,174 @@
+# @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](https://google.github.io/sqlcommenter/) 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
+
+```bash
+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:
+
+```typescript
+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:
+
+```typescript
+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],
+})
+```
+
+### Query Context
+
+Plugins receive a `SqlCommenterContext` object with information about the query being executed:
+
+```typescript
+interface SqlCommenterContext {
+  query: SqlCommenterQueryInfo
+}
+
+type SqlCommenterQueryInfo =
+  | { type: 'single'; modelName?: string; action: string; query: unknown }
+  | { type: 'compacted'; queries: SqlCommenterSingleQueryInfo[] }
+```
+
+- **`type: 'single'`**: A single Prisma query is being executed
+  - `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
+
+- **`type: 'compacted'`**: Multiple queries have been batched into a single SQL statement (e.g., automatic `findUnique` batching or explicit `$transaction` batches)
+
+### Example: Custom Application Tags
+
+```typescript
+import type { SqlCommenterPlugin } from '@prisma/sqlcommenter'
+
+const applicationTags: SqlCommenterPlugin = (context) => {
+  const tags: Record<string, string> = {
+    application: 'my-service',
+    environment: process.env.NODE_ENV ?? 'development',
+  }
+
+  if (context.query.type === 'single' && context.query.modelName) {
+    tags.model = context.query.modelName
+    tags.operation = context.query.action
+  }
+
+  return tags
+}
+```
+
+### Example: Async Context Propagation
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { SqlCommenterPlugin } from '@prisma/sqlcommenter'
+
+const traceStorage = new AsyncLocalStorage<{ route: string }>()
+
+const traceContext: SqlCommenterPlugin = () => {
+  const store = traceStorage.getStore()
+  if (store?.route) {
+    return { route: store.route }
+  }
+  return {}
+}
+```
+
+## Output Format
+
+The plugin outputs are merged, sorted by key, URL-encoded, and formatted according to the [sqlcommenter specification](https://google.github.io/sqlcommenter/spec/):
+
+```sql
+SELECT "id", "name" FROM "User" /*application='my-app',environment='production',model='User'*/
+```
+
+## API Reference
+
+### `SqlCommenterPlugin`
+
+```typescript
+interface SqlCommenterPlugin {
+  (context: SqlCommenterContext): Record<string, string>
+}
+```
+
+A function that receives query context and returns key-value pairs. Return an empty object to add no comments for a particular query.
+
+### `SqlCommenterContext`
+
+```typescript
+interface SqlCommenterContext {
+  query: SqlCommenterQueryInfo
+}
+```
+
+Context provided to plugins containing information about the query.
+
+### `SqlCommenterQueryInfo`
+
+```typescript
+type SqlCommenterQueryInfo =
+  | ({ type: 'single' } & SqlCommenterSingleQueryInfo)
+  | { type: 'compacted'; queries: SqlCommenterSingleQueryInfo[] }
+```
+
+Information about the query or queries being executed.
+
+### `SqlCommenterSingleQueryInfo`
+
+```typescript
+interface SqlCommenterSingleQueryInfo {
+  modelName?: string
+  action: string
+  query: unknown
+}
+```
+
+Information about a single Prisma query.
+
+## Notes
+
+- Plugins are called synchronously in array order
+- Later plugins override earlier ones if they return the same key
+- 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

package/dist/index.d.mts

@@ -0,0 +1,86 @@
+/**
+ * Information about a compacted batch query (e.g. multiple independent
+ * `findUnique` queries automatically merged into a single `SELECT` SQL
+ * statement).
+ */
+export declare interface SqlCommenterCompactedQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post").
+     */
+    readonly modelName: string;
+    /**
+     * The Prisma operation (e.g., "findUnique").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query objects (selections, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly queries: ReadonlyArray<unknown>;
+}
+
+/**
+ * Context provided to SQL commenter plugins.
+ */
+export declare interface SqlCommenterContext {
+    /**
+     * Information about the Prisma query being executed.
+     */
+    readonly query: SqlCommenterQueryInfo;
+}
+
+/**
+ * A SQL commenter plugin that returns key-value pairs to be added as comments.
+ * Return an empty object to add no comments.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: SqlCommenterPlugin = (context) => {
+ *   return {
+ *     application: 'my-app',
+ *     model: context.query.modelName ?? 'raw',
+ *   }
+ * }
+ * ```
+ */
+export declare interface SqlCommenterPlugin {
+    (context: SqlCommenterContext): Record<string, string>;
+}
+
+/**
+ * Prisma query type corresponding to this SQL query.
+ */
+export declare type SqlCommenterQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw';
+
+/**
+ * Information about the query or queries being executed.
+ *
+ * - `single`: A single query is being executed
+ * - `compacted`: Multiple queries have been compacted into a single SQL statement
+ */
+export declare type SqlCommenterQueryInfo = ({
+    readonly type: 'single';
+} & SqlCommenterSingleQueryInfo) | ({
+    readonly type: 'compacted';
+} & SqlCommenterCompactedQueryInfo);
+
+/**
+ * Information about a single Prisma query.
+ */
+export declare interface SqlCommenterSingleQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post"). Undefined for raw queries.
+     */
+    readonly modelName?: string;
+    /**
+     * The Prisma operation (e.g., "findMany", "createOne", "queryRaw").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query object (selection, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly query: unknown;
+}
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Information about a compacted batch query (e.g. multiple independent
+ * `findUnique` queries automatically merged into a single `SELECT` SQL
+ * statement).
+ */
+export declare interface SqlCommenterCompactedQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post").
+     */
+    readonly modelName: string;
+    /**
+     * The Prisma operation (e.g., "findUnique").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query objects (selections, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly queries: ReadonlyArray<unknown>;
+}
+
+/**
+ * Context provided to SQL commenter plugins.
+ */
+export declare interface SqlCommenterContext {
+    /**
+     * Information about the Prisma query being executed.
+     */
+    readonly query: SqlCommenterQueryInfo;
+}
+
+/**
+ * A SQL commenter plugin that returns key-value pairs to be added as comments.
+ * Return an empty object to add no comments.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: SqlCommenterPlugin = (context) => {
+ *   return {
+ *     application: 'my-app',
+ *     model: context.query.modelName ?? 'raw',
+ *   }
+ * }
+ * ```
+ */
+export declare interface SqlCommenterPlugin {
+    (context: SqlCommenterContext): Record<string, string>;
+}
+
+/**
+ * Prisma query type corresponding to this SQL query.
+ */
+export declare type SqlCommenterQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw';
+
+/**
+ * Information about the query or queries being executed.
+ *
+ * - `single`: A single query is being executed
+ * - `compacted`: Multiple queries have been compacted into a single SQL statement
+ */
+export declare type SqlCommenterQueryInfo = ({
+    readonly type: 'single';
+} & SqlCommenterSingleQueryInfo) | ({
+    readonly type: 'compacted';
+} & SqlCommenterCompactedQueryInfo);
+
+/**
+ * Information about a single Prisma query.
+ */
+export declare interface SqlCommenterSingleQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post"). Undefined for raw queries.
+     */
+    readonly modelName?: string;
+    /**
+     * The Prisma operation (e.g., "findMany", "createOne", "queryRaw").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query object (selection, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly query: unknown;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@prisma/sqlcommenter",
+  "version": "0.0.1",
+  "description": "SQL commenter types for Prisma",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://www.prisma.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma.git",
+    "directory": "packages/sqlcommenter"
+  },
+  "bugs": "https://github.com/prisma/prisma/issues",
+  "scripts": {
+    "dev": "DEV=true tsx helpers/build.ts",
+    "build": "tsx helpers/build.ts",
+    "prepublishOnly": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false
+}