forge-sql-orm 2.1.14 → 2.1.16

package/README.md

@@ -10,6 +10,11 @@
 [![forge-sql-orm CI](https://github.com/vzakharchenko/forge-sql-orm/actions/workflows/node.js.yml/badge.svg)](https://github.com/vzakharchenko/forge-sql-orm/actions/workflows/node.js.yml)
 [![Coverage Status](https://coveralls.io/repos/github/vzakharchenko/forge-sql-orm/badge.svg?branch=master)](https://coveralls.io/github/vzakharchenko/forge-sql-orm?branch=master)
 [![DeepScan grade](https://deepscan.io/api/teams/26652/projects/29272/branches/940614/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=26652&pid=29272&bid=940614)
+[![Snyk Vulnerabilities](https://snyk.io/test/github/vzakharchenko/forge-sql-orm/badge.svg)](https://snyk.io/test/github/vzakharchenko/forge-sql-orm)
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=vzakharchenko_forge-sql-orm&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=vzakharchenko_forge-sql-orm)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=vzakharchenko_forge-sql-orm&metric=bugs)](https://sonarcloud.io/summary/new_code?id=vzakharchenko_forge-sql-orm)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=vzakharchenko_forge-sql-orm&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=vzakharchenko_forge-sql-orm)
 
 **Forge-SQL-ORM** is an ORM designed for working with [@forge/sql](https://developer.atlassian.com/platform/forge/storage-reference/sql-tutorial/) in **Atlassian Forge**. It is built on top of [Drizzle ORM](https://orm.drizzle.team) and provides advanced capabilities for working with relational databases inside Forge.
 
@@ -22,7 +27,7 @@
 - ✅ **Type-Safe Query Building**: Write SQL queries with full TypeScript support
 - ✅ **Supports complex SQL queries** with joins and filtering using Drizzle ORM
 - ✅ **Advanced Query Methods**: `selectFrom()`, `selectDistinctFrom()`, `selectCacheableFrom()`, `selectDistinctCacheableFrom()` for all-column queries with field aliasing
-- ✅ **Query Execution with Metadata**: `executeWithMetadata()` method for capturing detailed execution metrics including database execution time, response size, and query analysis capabilities with performance monitoring
+- ✅ **Query Execution with Metadata**: `executeWithMetadata()` method for capturing detailed execution metrics including database execution time, response size, and query analysis capabilities with performance monitoring. Supports two modes for query plan printing: TopSlowest mode (default) and SummaryTable mode
 - ✅ **Raw SQL Execution**: `execute()`, `executeCacheable()`, `executeDDL()`, and `executeDDLActions()` methods for direct SQL queries with local and global caching
 - ✅ **Common Table Expressions (CTEs)**: `with()` method for complex queries with subqueries
 - ✅ **Schema migration support**, allowing automatic schema evolution
@@ -347,6 +352,11 @@ resolver.define("fetch", async (req: Request) => {
           console.debug(`[Performance Debug fetch] High DB time: ${totalDbExecutionTime} ms`);
         }
       },
+      {
+        // Optional: Configure query plan printing behavior
+        mode: "TopSlowest", // Print top slowest queries (default)
+        topQueries: 3, // Print top 3 slowest queries
+      },
     );
   } catch (e) {
     const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
@@ -356,6 +366,19 @@ resolver.define("fetch", async (req: Request) => {
 });
 ```
 
+**Query Plan Printing Options:**
+
+The `printQueriesWithPlan` function supports two modes:
+
+1. **TopSlowest Mode (default)**: Prints execution plans for the slowest queries from the current resolver invocation
+   - `mode`: Set to `'TopSlowest'` (default)
+   - `topQueries`: Number of top slowest queries to analyze (default: 1)
+
+2. **SummaryTable Mode**: Uses `CLUSTER_STATEMENTS_SUMMARY` for query analysis
+   - `mode`: Set to `'SummaryTable'`
+   - `summaryTableWindowTime`: Time window in milliseconds (default: 15000ms)
+   - Only works if queries are executed within the specified time window
+
 ### 5. Rovo Integration (Secure Analytics)
 
 ```typescript
@@ -452,6 +475,11 @@ const usersWithMetadata = await forgeSQL.executeWithMetadata(
 
     console.log(`DB response size: ${totalResponseSize} bytes`);
   },
+  {
+    // Optional: Configure query plan printing
+    mode: "TopSlowest", // Print top slowest queries (default)
+    topQueries: 2, // Print top 2 slowest queries
+  },
 );
 
 // DDL operations for schema modifications
@@ -589,7 +617,12 @@ const usersWithMetadata = await forgeSQL.executeWithMetadata(
     }
 
     console.log(`DB response size: ${totalResponseSize} bytes`);
-  }
+  },
+  {
+    // Optional: Configure query plan printing
+    mode: 'TopSlowest', // Print top slowest queries (default)
+    topQueries: 1, // Print top slowest query
+  },
 );
 ```
 
@@ -993,23 +1026,23 @@ const optimizedData = await forgeSQL.executeWithLocalCacheContextAndReturnValue(
 
 ### When to Use Each Approach
 
-| Method                                                                 | Use Case                                                    | Versioning | Cache Management     |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------- | ---------- | -------------------- |
-| `insertWithCacheContext/insertWithCacheContext/updateWithCacheContext` | Basic Drizzle operations                                    | ❌ No      | Cache Context        |
-| `insertAndEvictCache()`                                                | Simple inserts without conflicts                            | ❌ No      | ✅ Yes               |
-| `updateAndEvictCache()`                                                | Simple updates without conflicts                            | ❌ No      | ✅ Yes               |
-| `deleteAndEvictCache()`                                                | Simple deletes without conflicts                            | ❌ No      | ✅ Yes               |
-| `insert/update/delete`                                                 | Basic Drizzle operations                                    | ❌ No      | ❌ No                |
-| `selectFrom()`                                                         | All-column queries with field aliasing                      | ❌ No      | Local Cache          |
-| `selectDistinctFrom()`                                                 | Distinct all-column queries with field aliasing             | ❌ No      | Local Cache          |
-| `selectCacheableFrom()`                                                | All-column queries with field aliasing and caching          | ❌ No      | Local + Global Cache |
-| `selectDistinctCacheableFrom()`                                        | Distinct all-column queries with field aliasing and caching | ❌ No      | Local + Global Cache |
-| `execute()`                                                            | Raw SQL queries with local caching                          | ❌ No      | Local Cache          |
-| `executeCacheable()`                                                   | Raw SQL queries with local and global caching               | ❌ No      | Local + Global Cache |
-| `executeWithMetadata()`                                                | Raw SQL queries with execution metrics capture              | ❌ No      | Local Cache          |
-| `executeDDL()`                                                         | DDL operations (CREATE, ALTER, DROP, etc.)                  | ❌ No      | No Caching           |
-| `executeDDLActions()`                                                  | Execute regular SQL queries in DDL operation context        | ❌ No      | No Caching           |
-| `with()`                                                               | Common Table Expressions (CTEs)                             | ❌ No      | Local Cache          |
+| Method                                                                 | Use Case                                                                                                               | Versioning | Cache Management     |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------- |
+| `insertWithCacheContext/insertWithCacheContext/updateWithCacheContext` | Basic Drizzle operations                                                                                               | ❌ No      | Cache Context        |
+| `insertAndEvictCache()`                                                | Simple inserts without conflicts                                                                                       | ❌ No      | ✅ Yes               |
+| `updateAndEvictCache()`                                                | Simple updates without conflicts                                                                                       | ❌ No      | ✅ Yes               |
+| `deleteAndEvictCache()`                                                | Simple deletes without conflicts                                                                                       | ❌ No      | ✅ Yes               |
+| `insert/update/delete`                                                 | Basic Drizzle operations                                                                                               | ❌ No      | ❌ No                |
+| `selectFrom()`                                                         | All-column queries with field aliasing                                                                                 | ❌ No      | Local Cache          |
+| `selectDistinctFrom()`                                                 | Distinct all-column queries with field aliasing                                                                        | ❌ No      | Local Cache          |
+| `selectCacheableFrom()`                                                | All-column queries with field aliasing and caching                                                                     | ❌ No      | Local + Global Cache |
+| `selectDistinctCacheableFrom()`                                        | Distinct all-column queries with field aliasing and caching                                                            | ❌ No      | Local + Global Cache |
+| `execute()`                                                            | Raw SQL queries with local caching                                                                                     | ❌ No      | Local Cache          |
+| `executeCacheable()`                                                   | Raw SQL queries with local and global caching                                                                          | ❌ No      | Local + Global Cache |
+| `executeWithMetadata()`                                                | Resolver-level profiling with execution metrics and configurable query plan printing (TopSlowest or SummaryTable mode) | ❌ No      | Local Cache          |
+| `executeDDL()`                                                         | DDL operations (CREATE, ALTER, DROP, etc.)                                                                             | ❌ No      | No Caching           |
+| `executeDDLActions()`                                                  | Execute regular SQL queries in DDL operation context                                                                   | ❌ No      | No Caching           |
+| `with()`                                                               | Common Table Expressions (CTEs)                                                                                        | ❌ No      | Local Cache          |
 
 where Cache context - allows you to batch cache invalidation events and bypass cache reads for affected tables.
 
@@ -1413,7 +1446,12 @@ const usersWithMetadata = await forgeSQL.executeWithMetadata(
     }
 
     console.log(`DB response size: ${totalResponseSize} bytes`);
-  }
+  },
+  {
+    // Optional: Configure query plan printing
+    mode: 'TopSlowest', // Print top slowest queries (default)
+    topQueries: 1, // Print top slowest query
+  },
 );
 
 // Using executeDDL() for DDL operations (CREATE, ALTER, DROP, etc.)
@@ -1781,6 +1819,11 @@ await forgeSQL.executeWithLocalContext(async () => {
 
       console.log(`DB response size: ${totalResponseSize} bytes`);
     },
+    {
+      // Optional: Configure query plan printing
+      topQueries: 1, // Print top slowest query (default)
+      mode: "TopSlowest", // Print top slowest queries (default)
+    },
   );
 
   // Insert operation - evicts local cache for users table
@@ -1982,6 +2025,11 @@ const usersWithMetadata = await forgeSQL.executeWithMetadata(
 
     console.log(`DB response size: ${totalResponseSize} bytes`);
   },
+  {
+    // Optional: Configure query plan printing
+    mode: "TopSlowest", // Print top slowest queries (default)
+    topQueries: 1, // Print top slowest query
+  },
 );
 ```
 
@@ -2622,6 +2670,227 @@ The error analysis mechanism:
 
 > **💡 Tip**: The automatic error analysis only triggers for timeout and OOM errors. Other errors are logged normally without plan analysis.
 
+### Resolver-Level Performance Monitoring
+
+The `executeWithMetadata()` method provides resolver-level profiling with configurable query plan printing. It aggregates metrics across all database operations within a resolver and supports two modes for query plan analysis.
+
+#### Basic Usage
+
+```typescript
+const result = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    const orders = await forgeSQL
+      .selectFrom(ordersTable)
+      .where(eq(ordersTable.userId, usersTable.id));
+    return { users, orders };
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    const threshold = 500; // ms baseline for this resolver
+
+    if (totalDbExecutionTime > threshold * 1.5) {
+      console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
+      await printQueriesWithPlan(); // Analyze and print query execution plans
+    } else if (totalDbExecutionTime > threshold) {
+      console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
+    }
+
+    console.log(`DB response size: ${totalResponseSize} bytes`);
+  },
+);
+```
+
+#### Query Plan Printing Options
+
+The `printQueriesWithPlan` function supports two modes, configurable via the optional `options` parameter:
+
+**1. TopSlowest Mode (default)**: Prints execution plans for the slowest queries from the current resolver invocation
+
+```typescript
+// Full configuration example
+const result = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    return users;
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    if (totalDbExecutionTime > 1000) {
+      await printQueriesWithPlan(); // Will print top 3 slowest queries with execution plans
+    }
+  },
+  {
+    mode: "TopSlowest", // Print top slowest queries (default)
+    topQueries: 3, // Number of top slowest queries to analyze (default: 1)
+    showSlowestPlans: true, // Show execution plans (default: true)
+  },
+);
+
+// Minimal configuration - only specify what you need
+const result2 = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    return users;
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    if (totalDbExecutionTime > 1000) {
+      await printQueriesWithPlan(); // Will print top 3 slowest queries (all other options use defaults)
+    }
+  },
+  {
+    topQueries: 3, // Only specify topQueries, mode and showSlowestPlans use defaults
+  },
+);
+
+// Disable execution plans - only show SQL and execution time
+const result3 = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    return users;
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    if (totalDbExecutionTime > 1000) {
+      await printQueriesWithPlan(); // Will print SQL and time only, no execution plans
+    }
+  },
+  {
+    showSlowestPlans: false, // Disable execution plan printing
+  },
+);
+
+// Use all defaults - pass empty object or omit options parameter
+const result4 = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    return users;
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    if (totalDbExecutionTime > 1000) {
+      await printQueriesWithPlan(); // Uses all defaults: TopSlowest mode, topQueries: 1, showSlowestPlans: true
+    }
+  },
+  {}, // Empty object - all options use defaults
+);
+```
+
+<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
+read_file
+
+**2. SummaryTable Mode**: Uses `CLUSTER_STATEMENTS_SUMMARY` for query analysis
+
+```typescript
+const result = await forgeSQL.executeWithMetadata(
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    return users;
+  },
+  async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+    if (totalDbExecutionTime > 1000) {
+      await printQueriesWithPlan(); // Will use CLUSTER_STATEMENTS_SUMMARY if within time window
+    }
+  },
+  {
+    mode: "SummaryTable", // Use SummaryTable mode
+    summaryTableWindowTime: 10000, // Time window in milliseconds (default: 15000ms)
+  },
+);
+```
+
+#### Configuration Options
+
+All options are **optional**. If not specified, default values are used. You can pass only the options you need to customize.
+
+| Option                   | Type                             | Default        | Description                                                                                                                                                                                   |
+| ------------------------ | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                   | `'TopSlowest' \| 'SummaryTable'` | `'TopSlowest'` | Query plan printing mode. `'TopSlowest'` prints execution plans for the slowest queries from the current resolver. `'SummaryTable'` uses `CLUSTER_STATEMENTS_SUMMARY` when within time window |
+| `summaryTableWindowTime` | `number`                         | `15000`        | Time window in milliseconds for summary table queries. Only used when `mode` is `'SummaryTable'`                                                                                              |
+| `topQueries`             | `number`                         | `1`            | Number of top slowest queries to analyze when `mode` is `'TopSlowest'`                                                                                                                        |
+| `showSlowestPlans`       | `boolean`                        | `true`         | Whether to show execution plans for slowest queries in TopSlowest mode. If `false`, only SQL and execution time are printed                                                                   |
+| `normalizeQuery`         | `boolean`                        | `true`         | Whether to normalize SQL queries by replacing parameter values with `?` placeholders. Set to `false` to disable normalization if it causes issues with complex queries                        |
+
+**Examples:**
+
+```typescript
+// Use all defaults - omit options or pass empty object
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn); // or { }
+
+// Customize only what you need
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn, { topQueries: 3 });
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn, { mode: "SummaryTable" });
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn, { showSlowestPlans: false });
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn, { normalizeQuery: false }); // Disable query normalization
+
+// Combine multiple options
+await forgeSQL.executeWithMetadata(queryFn, onMetadataFn, {
+  mode: "TopSlowest",
+  topQueries: 5,
+  showSlowestPlans: false,
+  normalizeQuery: true, // Enable query normalization (default)
+});
+```
+
+#### How It Works
+
+1. **TopSlowest Mode** (default):
+   - Collects all queries executed within the resolver
+   - Sorts them by execution time (slowest first)
+   - Prints execution plans for the top N queries (configurable via `topQueries`)
+   - If `showSlowestPlans` is `false`, only prints SQL and execution time without plans
+   - Works immediately after query execution
+
+2. **SummaryTable Mode**:
+   - Attempts to use `CLUSTER_STATEMENTS_SUMMARY` for query analysis
+   - Only works if queries are executed within the specified time window (`summaryTableWindowTime`)
+   - If the time window expires, falls back to TopSlowest mode
+   - Provides aggregated statistics from TiDB's system tables
+
+#### Example: Real-World Resolver
+
+```typescript
+resolver.define("fetch", async (req: Request) => {
+  try {
+    return await forgeSQL.executeWithMetadata(
+      async () => {
+        const users = await forgeSQL.selectFrom(demoUsers);
+        const orders = await forgeSQL
+          .selectFrom(demoOrders)
+          .where(eq(demoOrders.userId, demoUsers.id));
+        return { users, orders };
+      },
+      async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+        const threshold = 500; // ms baseline for this resolver
+
+        if (totalDbExecutionTime > threshold * 1.5) {
+          console.warn(
+            `[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`,
+          );
+          await printQueriesWithPlan(); // Analyze and print query execution plans
+        } else if (totalDbExecutionTime > threshold) {
+          console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
+        }
+      },
+      {
+        mode: "TopSlowest", // Print top slowest queries (default)
+        topQueries: 2, // Print top 2 slowest queries
+      },
+    );
+  } catch (e) {
+    const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
+    console.error(error, e);
+    throw error;
+  }
+});
+```
+
+#### Benefits
+
+- **Resolver-Level Profiling**: Aggregates metrics across all database operations in a resolver
+- **Configurable Analysis**: Choose between TopSlowest mode or SummaryTable mode
+- **Automatic Plan Formatting**: Execution plans are formatted in a readable format
+- **Performance Thresholds**: Set custom thresholds for performance warnings
+- **Zero Configuration**: Works out of the box with sensible defaults
+
+> **💡 Tip**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis when using SummaryTable mode, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+
 ### Slow Query Monitoring
 
 Forge-SQL-ORM provides a scheduler trigger (`slowQuerySchedulerTrigger`) that automatically monitors and analyzes slow queries on an hourly basis. This trigger queries TiDB's slow query log system table and provides detailed performance information including SQL query text, memory usage, execution time, and execution plans.
@@ -2912,6 +3181,11 @@ const usersWithMetadata = await forgeSQL.executeWithMetadata(
 
     console.log(`DB response size: ${totalResponseSize} bytes`);
   },
+  {
+    // Optional: Configure query plan printing
+    mode: "TopSlowest", // Print top slowest queries (default)
+    topQueries: 1, // Print top slowest query
+  },
 );
 
 // ✅ DDL operations for schema modifications

package/dist/core/ForgeSQLORM.d.ts

@@ -8,6 +8,7 @@ import { MySqlTable } from "drizzle-orm/mysql-core/table";
 import { MySqlDeleteBase, MySqlInsertBuilder, MySqlUpdateBuilder } from "drizzle-orm/mysql-core/query-builders";
 import { SQLWrapper } from "drizzle-orm/sql/sql";
 import { WithSubquery } from "drizzle-orm/subquery";
+import { MetadataQueryOptions } from "../utils/metadataContextUtils";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
 /**
  * Public class that acts as a wrapper around the private ForgeSQLORMImpl.
@@ -29,7 +30,15 @@ declare class ForgeSQLORM implements ForgeSqlOperation {
      * @param onMetadata - Callback function that receives aggregated execution metadata
      * @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
      * @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
-     * @param onMetadata.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+     * @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
+     *   - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
+     *   - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
+     * @param options - Optional configuration for query plan printing behavior
+     * @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
+     * @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
+     * @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
+     * @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
+     * @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
      * @returns Promise with the query result
      *
      * @example
@@ -41,12 +50,12 @@ declare class ForgeSQLORM implements ForgeSqlOperation {
      *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
      *     return { users, orders };
      *   },
-     *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+     *   (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
      *     const threshold = 500; // ms baseline for this resolver
      *
      *     if (totalDbExecutionTime > threshold * 1.5) {
      *       console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-     *       await printQueries(); // Analyze and print query execution plans
+     *       await printQueriesWithPlan(); // Analyze and print query execution plans
      *     } else if (totalDbExecutionTime > threshold) {
      *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
      *     }
@@ -69,12 +78,12 @@ declare class ForgeSQLORM implements ForgeSqlOperation {
      *           .where(eq(demoOrders.userId, demoUsers.id));
      *         return { users, orders };
      *       },
-     *       async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+     *       async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
      *         const threshold = 500; // ms baseline for this resolver
      *
      *         if (totalDbExecutionTime > threshold * 1.5) {
      *           console.warn(`[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-     *           await printQueries(); // Optionally log or capture diagnostics for further analysis
+     *           await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
      *         } else if (totalDbExecutionTime > threshold) {
      *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
      *         }
@@ -90,9 +99,9 @@ declare class ForgeSQLORM implements ForgeSqlOperation {
      * });
      * ```
      *
-     * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+     * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
      */
-    executeWithMetadata<T>(query: () => Promise<T>, onMetadata: (totalDbExecutionTime: number, totalResponseSize: number, printQueriesWithPlan: () => Promise<void>) => Promise<void> | void): Promise<T>;
+    executeWithMetadata<T>(query: () => Promise<T>, onMetadata: (totalDbExecutionTime: number, totalResponseSize: number, printQueriesWithPlan: () => Promise<void>) => Promise<void> | void, options?: MetadataQueryOptions): Promise<T>;
     selectCacheable<TSelection extends SelectedFields>(fields: TSelection, cacheTTL?: number): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
     selectDistinctCacheable<TSelection extends SelectedFields>(fields: TSelection, cacheTTL?: number): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
     /**

package/dist/core/ForgeSQLORM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgeSQLORM.d.ts","sourceRoot":"","sources":["../../src/core/ForgeSQLORM.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEL,mBAAmB,EACnB,2BAA2B,EAC3B,yBAAyB,EAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EAEvB,0BAA0B,EAC1B,kCAAkC,EAClC,yBAAyB,EACzB,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,uCAAuC,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAqzB3E;;;GAGG;AACH,cAAM,WAAY,YAAW,iBAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;gBAEpC,OAAO,CAAC,EAAE,kBAAkB;IAIxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2EG;IACG,mBAAmB,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACvB,UAAU,EAAE,CACV,oBAAoB,EAAE,MAAM,EAC5B,iBAAiB,EAAE,MAAM,EACzB,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KACtC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACxB,OAAO,CAAC,CAAC,CAAC;IAIb,eAAe,CAAC,UAAU,SAAS,cAAc,EAC/C,MAAM,EAAE,UAAU,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB,CAAC,UAAU,EAAE,2BAA2B,CAAC;IAI9D,uBAAuB,CAAC,UAAU,SAAS,cAAc,EACvD,MAAM,EAAE,UAAU,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB,CAAC,UAAU,EAAE,2BAA2B,CAAC;IAI9D;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC;IAIzC;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC;IAIjD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM;IAIrE;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI7E,uBAAuB,CAAC,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAGzE,qCAAqC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAGpF;;;;;;OAMG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE;;;;;;OAMG;IACH,0CAA0C,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzF;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,SAAS,UAAU,EAC9B,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIrF;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAM,SAAS,UAAU,EAC3C,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIrF;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,SAAS,UAAU,EAC9B,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIrF;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAM,SAAS,UAAU,EAC3C,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIrF;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,SAAS,UAAU,EAC9B,KAAK,EAAE,MAAM,GACZ,eAAe,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIlF;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAM,SAAS,UAAU,EAC3C,KAAK,EAAE,MAAM,GACZ,eAAe,CAAC,MAAM,EAAE,yBAAyB,EAAE,2BAA2B,CAAC;IAIlF;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,UAAU,SAAS,cAAc,EACtC,MAAM,EAAE,UAAU,GACjB,kBAAkB,CAAC,UAAU,EAAE,2BAA2B,CAAC;IAI9D;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,UAAU,SAAS,cAAc,EAC9C,MAAM,EAAE,UAAU,GACjB,kBAAkB,CAAC,UAAU,EAAE,2BAA2B,CAAC;IAI9D;;;OAGG;IACH,oBAAoB,IAAI,6BAA6B;IAIrD;;;OAGG;IACH,KAAK,IAAI,iBAAiB;IAI1B;;;OAGG;IACH,OAAO,IAAI,qBAAqB;IAIhC;;;OAGG;IACH,iCAAiC,IAAI,uBAAuB;IAI5D;;;;OAIG;IACH,sBAAsB;;;;;;;;;;;;;;;;;;IAItB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,CAAC,EACP,KAAK,EAAE,UAAU,GAAG,MAAM,GACzB,OAAO,CAAC,oBAAoB,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC;IAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI3D;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,CAAC,EAChB,KAAK,EAAE,UAAU,GAAG,MAAM,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC;IAI9D;;;;;;;;;;;;;OAaG;IACH,IAAI,KAAK,iDAER;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE;;;;;;;;;;;;IAI/B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,IAAI,IAAI,eAAe;CAGxB;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"ForgeSQLORM.d.ts","sourceRoot":"","sources":["../../src/core/ForgeSQLORM.ts"],"names":[],"mappings":"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"}