@prisma/client-engine-runtime 7.1.0-dev.33 → 7.1.0-dev.35

package/dist/index.d.mts

@@ -6,11 +6,20 @@ import { Decimal } from '@prisma/client-runtime-utils';
 import type { IsolationLevel } from '@prisma/driver-adapter-utils';
 import { Span } from '@opentelemetry/api';
 import { SpanOptions } from '@opentelemetry/api';
+import type { SqlCommenterContext } from '@prisma/sqlcommenter';
+import type { SqlCommenterPlugin } from '@prisma/sqlcommenter';
+import type { SqlCommenterQueryInfo } from '@prisma/sqlcommenter';
 import { SqlDriverAdapter } from '@prisma/driver-adapter-utils';
 import { SqlQueryable } from '@prisma/driver-adapter-utils';
 import { SqlResultSet } from '@prisma/driver-adapter-utils';
 import { Transaction } from '@prisma/driver-adapter-utils';
 
+/**
+ * Applies SQL commenter plugins and returns the merged key-value pairs.
+ * Keys with undefined values are filtered out.
+ */
+export declare function applySqlCommenters(plugins: SqlCommenterPlugin[], context: SqlCommenterContext): Record<string, string>;
+
 export declare type BatchResponse = MultiBatchResponse | CompactedBatchResponse;
 
 export declare type BigIntTaggedValue = {
@@ -234,7 +243,7 @@ export declare type QueryEvent = {
 
 export declare class QueryInterpreter {
     #private;
-    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, }: QueryInterpreterOptions);
+    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, sqlCommenter, }: QueryInterpreterOptions);
     static forSql(options: {
         transactionManager: QueryInterpreterTransactionManager;
         placeholderValues: Record<string, unknown>;
@@ -242,6 +251,7 @@ export declare class QueryInterpreter {
         tracingHelper: TracingHelper;
         provider?: SchemaProvider;
         connectionInfo?: ConnectionInfo;
+        sqlCommenter?: QueryInterpreterSqlCommenter;
     }): QueryInterpreter;
     run(queryPlan: QueryPlanNode, queryable: SqlQueryable): Promise<unknown>;
     private interpretNode;
@@ -256,6 +266,12 @@ export declare type QueryInterpreterOptions = {
     rawSerializer?: (results: SqlResultSet) => Value;
     provider?: SchemaProvider;
     connectionInfo?: ConnectionInfo;
+    sqlCommenter?: QueryInterpreterSqlCommenter;
+};
+
+export declare type QueryInterpreterSqlCommenter = {
+    plugins: SqlCommenterPlugin[];
+    queryInfo: SqlCommenterQueryInfo;
 };
 
 export declare type QueryInterpreterTransactionManager = {

package/dist/index.d.ts

@@ -6,11 +6,20 @@ import { Decimal } from '@prisma/client-runtime-utils';
 import type { IsolationLevel } from '@prisma/driver-adapter-utils';
 import { Span } from '@opentelemetry/api';
 import { SpanOptions } from '@opentelemetry/api';
+import type { SqlCommenterContext } from '@prisma/sqlcommenter';
+import type { SqlCommenterPlugin } from '@prisma/sqlcommenter';
+import type { SqlCommenterQueryInfo } from '@prisma/sqlcommenter';
 import { SqlDriverAdapter } from '@prisma/driver-adapter-utils';
 import { SqlQueryable } from '@prisma/driver-adapter-utils';
 import { SqlResultSet } from '@prisma/driver-adapter-utils';
 import { Transaction } from '@prisma/driver-adapter-utils';
 
+/**
+ * Applies SQL commenter plugins and returns the merged key-value pairs.
+ * Keys with undefined values are filtered out.
+ */
+export declare function applySqlCommenters(plugins: SqlCommenterPlugin[], context: SqlCommenterContext): Record<string, string>;
+
 export declare type BatchResponse = MultiBatchResponse | CompactedBatchResponse;
 
 export declare type BigIntTaggedValue = {
@@ -234,7 +243,7 @@ export declare type QueryEvent = {
 
 export declare class QueryInterpreter {
     #private;
-    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, }: QueryInterpreterOptions);
+    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, sqlCommenter, }: QueryInterpreterOptions);
     static forSql(options: {
         transactionManager: QueryInterpreterTransactionManager;
         placeholderValues: Record<string, unknown>;
@@ -242,6 +251,7 @@ export declare class QueryInterpreter {
         tracingHelper: TracingHelper;
         provider?: SchemaProvider;
         connectionInfo?: ConnectionInfo;
+        sqlCommenter?: QueryInterpreterSqlCommenter;
     }): QueryInterpreter;
     run(queryPlan: QueryPlanNode, queryable: SqlQueryable): Promise<unknown>;
     private interpretNode;
@@ -256,6 +266,12 @@ export declare type QueryInterpreterOptions = {
     rawSerializer?: (results: SqlResultSet) => Value;
     provider?: SchemaProvider;
     connectionInfo?: ConnectionInfo;
+    sqlCommenter?: QueryInterpreterSqlCommenter;
+};
+
+export declare type QueryInterpreterSqlCommenter = {
+    plugins: SqlCommenterPlugin[];
+    queryInfo: SqlCommenterQueryInfo;
 };
 
 export declare type QueryInterpreterTransactionManager = {

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   TransactionManager: () => TransactionManager,
   TransactionManagerError: () => TransactionManagerError,
   UserFacingError: () => UserFacingError,
+  applySqlCommenters: () => applySqlCommenters,
   convertCompactedRows: () => convertCompactedRows,
   deserializeJsonResponse: () => deserializeJsonResponse,
   doKeysMatch: () => doKeysMatch,
@@ -691,6 +692,43 @@ function normalizeDateTime(dt) {
   return dtWithTz;
 }
 
+// src/sql-commenter.ts
+function formatSqlComment(tags) {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    return "";
+  }
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  const parts = entries.map(([key, value]) => {
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(value).replace(/'/g, "\\'");
+    return `${encodedKey}='${encodedValue}'`;
+  });
+  return `/*${parts.join(",")}*/`;
+}
+function applySqlCommenters(plugins, context) {
+  const merged = {};
+  for (const plugin of plugins) {
+    const tags = plugin(context);
+    for (const [key, value] of Object.entries(tags)) {
+      if (value !== void 0) {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+function buildSqlComment(plugins, context) {
+  const tags = applySqlCommenters(plugins, context);
+  return formatSqlComment(tags);
+}
+function appendSqlComment(sql, comment) {
+  if (!comment) {
+    return sql;
+  }
+  return `${sql} ${comment}`;
+}
+
 // src/tracing.ts
 var import_api = require("@opentelemetry/api");
 var noopTracingHelper = {
@@ -1442,6 +1480,7 @@ var QueryInterpreter = class _QueryInterpreter {
   #rawSerializer;
   #provider;
   #connectionInfo;
+  #sqlCommenter;
   constructor({
     transactionManager,
     placeholderValues,
@@ -1450,7 +1489,8 @@ var QueryInterpreter = class _QueryInterpreter {
     serializer,
     rawSerializer,
     provider,
-    connectionInfo
+    connectionInfo,
+    sqlCommenter
   }) {
     this.#transactionManager = transactionManager;
     this.#placeholderValues = placeholderValues;
@@ -1460,6 +1500,7 @@ var QueryInterpreter = class _QueryInterpreter {
     this.#rawSerializer = rawSerializer ?? serializer;
     this.#provider = provider;
     this.#connectionInfo = connectionInfo;
+    this.#sqlCommenter = sqlCommenter;
   }
   static forSql(options) {
     return new _QueryInterpreter({
@@ -1470,7 +1511,8 @@ var QueryInterpreter = class _QueryInterpreter {
       serializer: serializeSql,
       rawSerializer: serializeRawSql,
       provider: options.provider,
-      connectionInfo: options.connectionInfo
+      connectionInfo: options.connectionInfo,
+      sqlCommenter: options.sqlCommenter
     });
   }
   async run(queryPlan, queryable) {
@@ -1534,10 +1576,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let sum = 0;
         for (const query of queries) {
+          const commentedQuery = this.#applyComments(query);
           sum += await this.#withQuerySpanAndEvent(
-            query,
+            commentedQuery,
             queryable,
-            () => queryable.executeRaw(query).catch(
+            () => queryable.executeRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -1548,10 +1591,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let results;
         for (const query of queries) {
+          const commentedQuery = this.#applyComments(query);
           const result = await this.#withQuerySpanAndEvent(
-            query,
+            commentedQuery,
             queryable,
-            () => queryable.queryRaw(query).catch(
+            () => queryable.queryRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -1709,6 +1753,22 @@ var QueryInterpreter = class _QueryInterpreter {
       onQuery: this.#onQuery
     });
   }
+  #applyComments(query) {
+    if (!this.#sqlCommenter || this.#sqlCommenter.plugins.length === 0) {
+      return query;
+    }
+    const comment = buildSqlComment(this.#sqlCommenter.plugins, {
+      query: this.#sqlCommenter.queryInfo,
+      sql: query.sql
+    });
+    if (!comment) {
+      return query;
+    }
+    return {
+      ...query,
+      sql: appendSqlComment(query.sql, comment)
+    };
+  }
 };
 function isEmpty(value) {
   if (Array.isArray(value)) {
@@ -2155,6 +2215,7 @@ function createTimeoutIfDefined(cb, ms) {
   TransactionManager,
   TransactionManagerError,
   UserFacingError,
+  applySqlCommenters,
   convertCompactedRows,
   deserializeJsonResponse,
   doKeysMatch,

package/dist/index.mjs

@@ -641,6 +641,43 @@ function normalizeDateTime(dt) {
   return dtWithTz;
 }
 
+// src/sql-commenter.ts
+function formatSqlComment(tags) {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    return "";
+  }
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  const parts = entries.map(([key, value]) => {
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(value).replace(/'/g, "\\'");
+    return `${encodedKey}='${encodedValue}'`;
+  });
+  return `/*${parts.join(",")}*/`;
+}
+function applySqlCommenters(plugins, context) {
+  const merged = {};
+  for (const plugin of plugins) {
+    const tags = plugin(context);
+    for (const [key, value] of Object.entries(tags)) {
+      if (value !== void 0) {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+function buildSqlComment(plugins, context) {
+  const tags = applySqlCommenters(plugins, context);
+  return formatSqlComment(tags);
+}
+function appendSqlComment(sql, comment) {
+  if (!comment) {
+    return sql;
+  }
+  return `${sql} ${comment}`;
+}
+
 // src/tracing.ts
 import { SpanKind } from "@opentelemetry/api";
 var noopTracingHelper = {
@@ -1392,6 +1429,7 @@ var QueryInterpreter = class _QueryInterpreter {
   #rawSerializer;
   #provider;
   #connectionInfo;
+  #sqlCommenter;
   constructor({
     transactionManager,
     placeholderValues,
@@ -1400,7 +1438,8 @@ var QueryInterpreter = class _QueryInterpreter {
     serializer,
     rawSerializer,
     provider,
-    connectionInfo
+    connectionInfo,
+    sqlCommenter
   }) {
     this.#transactionManager = transactionManager;
     this.#placeholderValues = placeholderValues;
@@ -1410,6 +1449,7 @@ var QueryInterpreter = class _QueryInterpreter {
     this.#rawSerializer = rawSerializer ?? serializer;
     this.#provider = provider;
     this.#connectionInfo = connectionInfo;
+    this.#sqlCommenter = sqlCommenter;
   }
   static forSql(options) {
     return new _QueryInterpreter({
@@ -1420,7 +1460,8 @@ var QueryInterpreter = class _QueryInterpreter {
       serializer: serializeSql,
       rawSerializer: serializeRawSql,
       provider: options.provider,
-      connectionInfo: options.connectionInfo
+      connectionInfo: options.connectionInfo,
+      sqlCommenter: options.sqlCommenter
     });
   }
   async run(queryPlan, queryable) {
@@ -1484,10 +1525,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let sum = 0;
         for (const query of queries) {
+          const commentedQuery = this.#applyComments(query);
           sum += await this.#withQuerySpanAndEvent(
-            query,
+            commentedQuery,
             queryable,
-            () => queryable.executeRaw(query).catch(
+            () => queryable.executeRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -1498,10 +1540,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let results;
         for (const query of queries) {
+          const commentedQuery = this.#applyComments(query);
           const result = await this.#withQuerySpanAndEvent(
-            query,
+            commentedQuery,
             queryable,
-            () => queryable.queryRaw(query).catch(
+            () => queryable.queryRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -1659,6 +1702,22 @@ var QueryInterpreter = class _QueryInterpreter {
       onQuery: this.#onQuery
     });
   }
+  #applyComments(query) {
+    if (!this.#sqlCommenter || this.#sqlCommenter.plugins.length === 0) {
+      return query;
+    }
+    const comment = buildSqlComment(this.#sqlCommenter.plugins, {
+      query: this.#sqlCommenter.queryInfo,
+      sql: query.sql
+    });
+    if (!comment) {
+      return query;
+    }
+    return {
+      ...query,
+      sql: appendSqlComment(query.sql, comment)
+    };
+  }
 };
 function isEmpty(value) {
   if (Array.isArray(value)) {
@@ -2104,6 +2163,7 @@ export {
   TransactionManager,
   TransactionManagerError,
   UserFacingError,
+  applySqlCommenters,
   convertCompactedRows,
   deserializeJsonResponse,
   doKeysMatch,

package/dist/interpreter/query-interpreter.d.ts

@@ -1,4 +1,5 @@
 import { ConnectionInfo, SqlQueryable, SqlResultSet } from '@prisma/driver-adapter-utils';
+import type { SqlCommenterPlugin, SqlCommenterQueryInfo } from '@prisma/sqlcommenter';
 import { QueryEvent } from '../events';
 import { QueryPlanNode } from '../query-plan';
 import { type SchemaProvider } from '../schema';
@@ -20,10 +21,15 @@ export type QueryInterpreterOptions = {
     rawSerializer?: (results: SqlResultSet) => Value;
     provider?: SchemaProvider;
     connectionInfo?: ConnectionInfo;
+    sqlCommenter?: QueryInterpreterSqlCommenter;
+};
+export type QueryInterpreterSqlCommenter = {
+    plugins: SqlCommenterPlugin[];
+    queryInfo: SqlCommenterQueryInfo;
 };
 export declare class QueryInterpreter {
     #private;
-    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, }: QueryInterpreterOptions);
+    constructor({ transactionManager, placeholderValues, onQuery, tracingHelper, serializer, rawSerializer, provider, connectionInfo, sqlCommenter, }: QueryInterpreterOptions);
     static forSql(options: {
         transactionManager: QueryInterpreterTransactionManager;
         placeholderValues: Record<string, unknown>;
@@ -31,6 +37,7 @@ export declare class QueryInterpreter {
         tracingHelper: TracingHelper;
         provider?: SchemaProvider;
         connectionInfo?: ConnectionInfo;
+        sqlCommenter?: QueryInterpreterSqlCommenter;
     }): QueryInterpreter;
     run(queryPlan: QueryPlanNode, queryable: SqlQueryable): Promise<unknown>;
     private interpretNode;

package/dist/sql-commenter.d.ts

@@ -0,0 +1,28 @@
+import type { SqlCommenterContext, SqlCommenterPlugin } from '@prisma/sqlcommenter';
+/**
+ * Formats key-value pairs into a sqlcommenter-compatible comment string.
+ *
+ * Algorithm per https://google.github.io/sqlcommenter/spec/:
+ * 1. If the map is empty, return empty string
+ * 2. Sort keys lexicographically
+ * 3. URL-encode keys
+ * 4. URL-encode values
+ * 5. Replace ' with \' in values (after URL encoding)
+ * 6. Wrap values in single quotes
+ * 7. Join key='value' pairs with commas
+ * 8. Wrap in /* *\/
+ */
+export declare function formatSqlComment(tags: Record<string, string>): string;
+/**
+ * Applies SQL commenter plugins and returns the merged key-value pairs.
+ * Keys with undefined values are filtered out.
+ */
+export declare function applySqlCommenters(plugins: SqlCommenterPlugin[], context: SqlCommenterContext): Record<string, string>;
+/**
+ * Applies SQL commenter plugins and returns the formatted comment.
+ */
+export declare function buildSqlComment(plugins: SqlCommenterPlugin[], context: SqlCommenterContext): string;
+/**
+ * Appends a sqlcommenter comment to a SQL query.
+ */
+export declare function appendSqlComment(sql: string, comment: string): string;

package/dist/sql-commenter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/client-engine-runtime",
-  "version": "7.1.0-dev.33",
+  "version": "7.1.0-dev.35",
   "description": "This package is intended for Prisma's internal use",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -30,9 +30,10 @@
     "nanoid": "5.1.5",
     "ulid": "3.0.0",
     "uuid": "11.1.0",
-    "@prisma/client-runtime-utils": "7.1.0-dev.33",
-    "@prisma/debug": "7.1.0-dev.33",
-    "@prisma/driver-adapter-utils": "7.1.0-dev.33"
+    "@prisma/client-runtime-utils": "7.1.0-dev.35",
+    "@prisma/debug": "7.1.0-dev.35",
+    "@prisma/driver-adapter-utils": "7.1.0-dev.35",
+    "@prisma/sqlcommenter": "7.1.0-dev.35"
   },
   "devDependencies": {
     "@types/jest": "29.5.14",