@prisma/query-plan-executor 7.1.0-dev.32 → 7.1.0-dev.34

package/dist/index.d.ts

@@ -34,8 +34,14 @@ declare class App {
     shutdown(): Promise<void>;
     /**
      * Executes a query plan and returns the result.
+     *
+     * @param queryPlan - The query plan to execute
+     * @param placeholderValues - Placeholder values for the query
+     * @param comments - Pre-computed SQL commenter tags from the client
+     * @param resourceLimits - Resource limits for the query
+     * @param transactionId - Transaction ID if running within a transaction
      */
-    query(queryPlan: QueryPlanNode, placeholderValues: Record<string, unknown>, resourceLimits: ResourceLimits, transactionId: string | null): Promise<unknown>;
+    query(queryPlan: QueryPlanNode, placeholderValues: Record<string, unknown>, comments: Record<string, string> | undefined, resourceLimits: ResourceLimits, transactionId: string | null): Promise<unknown>;
     /**
      * Starts a new transaction.
      */
@@ -648,6 +654,7 @@ operation: string;
 plan: Record<string, unknown>;
 params: Record<string, unknown>;
 model?: string | undefined;
+comments?: Record<string, string> | undefined;
 };
 };
 output: {
@@ -683,6 +690,7 @@ operation: string;
 plan: Record<string, unknown>;
 params: Record<string, unknown>;
 model?: string | undefined;
+comments?: Record<string, string> | undefined;
 };
 } & {
 param: {

package/dist/index.js

@@ -97752,7 +97752,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "7.1.0-dev.32";
+var version = "7.1.0-dev.34";
 
 // ../../node_modules/.pnpm/temporal-polyfill@0.3.0/node_modules/temporal-polyfill/chunks/internal.js
 function clampProp(e2, n2, t2, o2, r2) {
@@ -106556,6 +106556,41 @@ function normalizeDateTime(dt2) {
   }
   return dtWithTz;
 }
+function formatSqlComment(tags) {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    return "";
+  }
+  entries.sort(([a2], [b2]) => a2.localeCompare(b2));
+  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, context2) {
+  const merged = {};
+  for (const plugin of plugins) {
+    const tags = plugin(context2);
+    for (const [key, value] of Object.entries(tags)) {
+      if (value !== void 0) {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+function buildSqlComment(plugins, context2) {
+  const tags = applySqlCommenters(plugins, context2);
+  return formatSqlComment(tags);
+}
+function appendSqlComment(sql4, comment) {
+  if (!comment) {
+    return sql4;
+  }
+  return `${sql4} ${comment}`;
+}
 function providerToOtelSystem(provider) {
   switch (provider) {
     case "postgresql":
@@ -107280,6 +107315,7 @@ var QueryInterpreter = class _QueryInterpreter {
   #rawSerializer;
   #provider;
   #connectionInfo;
+  #sqlCommenter;
   constructor({
     transactionManager,
     placeholderValues,
@@ -107288,7 +107324,8 @@ var QueryInterpreter = class _QueryInterpreter {
     serializer,
     rawSerializer,
     provider,
-    connectionInfo
+    connectionInfo,
+    sqlCommenter
   }) {
     this.#transactionManager = transactionManager;
     this.#placeholderValues = placeholderValues;
@@ -107298,6 +107335,7 @@ var QueryInterpreter = class _QueryInterpreter {
     this.#rawSerializer = rawSerializer ?? serializer;
     this.#provider = provider;
     this.#connectionInfo = connectionInfo;
+    this.#sqlCommenter = sqlCommenter;
   }
   static forSql(options) {
     return new _QueryInterpreter({
@@ -107308,7 +107346,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) {
@@ -107372,10 +107411,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let sum2 = 0;
         for (const query2 of queries) {
+          const commentedQuery = this.#applyComments(query2);
           sum2 += await this.#withQuerySpanAndEvent(
-            query2,
+            commentedQuery,
             queryable,
-            () => queryable.executeRaw(query2).catch(
+            () => queryable.executeRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -107386,10 +107426,11 @@ var QueryInterpreter = class _QueryInterpreter {
         const queries = renderQuery(node.args, scope, generators, this.#maxChunkSize());
         let results;
         for (const query2 of queries) {
+          const commentedQuery = this.#applyComments(query2);
           const result = await this.#withQuerySpanAndEvent(
-            query2,
+            commentedQuery,
             queryable,
-            () => queryable.queryRaw(query2).catch(
+            () => queryable.queryRaw(commentedQuery).catch(
               (err) => node.args.type === "rawSql" ? rethrowAsUserFacingRawError(err) : rethrowAsUserFacing(err)
             )
           );
@@ -107547,6 +107588,22 @@ var QueryInterpreter = class _QueryInterpreter {
       onQuery: this.#onQuery
     });
   }
+  #applyComments(query2) {
+    if (!this.#sqlCommenter || this.#sqlCommenter.plugins.length === 0) {
+      return query2;
+    }
+    const comment = buildSqlComment(this.#sqlCommenter.plugins, {
+      query: this.#sqlCommenter.queryInfo,
+      sql: query2.sql
+    });
+    if (!comment) {
+      return query2;
+    }
+    return {
+      ...query2,
+      sql: appendSqlComment(query2.sql, comment)
+    };
+  }
 };
 function isEmpty(value) {
   if (Array.isArray(value)) {
@@ -111797,15 +111854,28 @@ var App = class _App {
   }
   /**
    * Executes a query plan and returns the result.
+   *
+   * @param queryPlan - The query plan to execute
+   * @param placeholderValues - Placeholder values for the query
+   * @param comments - Pre-computed SQL commenter tags from the client
+   * @param resourceLimits - Resource limits for the query
+   * @param transactionId - Transaction ID if running within a transaction
    */
-  async query(queryPlan, placeholderValues, resourceLimits, transactionId) {
+  async query(queryPlan, placeholderValues, comments, resourceLimits, transactionId) {
     return await this.#tracingHandler.runInChildSpan("query", async () => {
       const queryable = transactionId !== null ? await this.#transactionManager.getTransaction({ id: transactionId }, "query") : this.#db;
+      const sqlCommenter = comments && Object.keys(comments).length > 0 ? {
+        plugins: [() => comments],
+        // For pre-computed comments, we use a placeholder queryInfo since the actual
+        // query info was already used on the client side to compute the comments
+        queryInfo: { type: "single", action: "queryRaw", query: {} }
+      } : void 0;
       const queryInterpreter = QueryInterpreter.forSql({
         placeholderValues,
         tracingHelper: this.#tracingHandler,
         transactionManager: transactionId === null ? { enabled: true, manager: this.#transactionManager } : { enabled: false },
-        onQuery: logQuery
+        onQuery: logQuery,
+        sqlCommenter
       });
       const result = await Promise.race([
         queryInterpreter.run(queryPlan, queryable),
@@ -124038,7 +124108,8 @@ var QueryRequestBody = external_exports.object({
   model: external_exports.string().min(1).optional(),
   operation: external_exports.string().min(1),
   plan: external_exports.record(external_exports.string(), external_exports.unknown()),
-  params: external_exports.record(external_exports.string(), external_exports.unknown())
+  params: external_exports.record(external_exports.string(), external_exports.unknown()),
+  comments: external_exports.record(external_exports.string(), external_exports.string()).optional()
 });
 var TransactionStartRequestBody = external_exports.object({
   timeout: external_exports.number().optional(),
@@ -124082,7 +124153,13 @@ function createHonoServer(app, options) {
     return c2.json(app.getConnectionInfo());
   }).post("/query", zValidator("json", QueryRequestBody), async (c2) => {
     const request3 = c2.req.valid("json");
-    const data = await app.query(request3.plan, request3.params, c2.get("resourceLimits"), null);
+    const data = await app.query(
+      request3.plan,
+      request3.params,
+      request3.comments,
+      c2.get("resourceLimits"),
+      null
+    );
     return c2.json({ data });
   }).post("/transaction/start", zValidator("json", TransactionStartRequestBody), async (c2) => {
     const result = await app.startTransaction(c2.req.valid("json"), c2.get("resourceLimits"));
@@ -124093,6 +124170,7 @@ function createHonoServer(app, options) {
     const data = await app.query(
       request3.plan,
       request3.params,
+      request3.comments,
       c2.get("resourceLimits"),
       c2.req.param("txId")
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/query-plan-executor",
-  "version": "7.1.0-dev.32",
+  "version": "7.1.0-dev.34",
   "description": "This package is intended for Prisma's internal use",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,11 +20,11 @@
     "temporal-polyfill": "0.3.0",
     "vitest": "3.2.4",
     "zod": "4.1.3",
-    "@prisma/adapter-pg": "7.1.0-dev.32",
-    "@prisma/adapter-mariadb": "7.1.0-dev.32",
-    "@prisma/adapter-mssql": "7.1.0-dev.32",
-    "@prisma/client-engine-runtime": "7.1.0-dev.32",
-    "@prisma/driver-adapter-utils": "7.1.0-dev.32"
+    "@prisma/adapter-pg": "7.1.0-dev.34",
+    "@prisma/adapter-mssql": "7.1.0-dev.34",
+    "@prisma/adapter-mariadb": "7.1.0-dev.34",
+    "@prisma/client-engine-runtime": "7.1.0-dev.34",
+    "@prisma/driver-adapter-utils": "7.1.0-dev.34"
   },
   "files": [
     "dist"