forge-sql-orm 2.1.13 → 2.1.15

package/README.md

@@ -10,6 +10,7 @@
 [![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)
 
 **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 +23,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
@@ -33,6 +34,7 @@
 - ✅ **Ready-to-use Migration Triggers** Built-in web triggers for applying migrations, dropping tables (development-only), and fetching schema (development-only) with proper error handling and security controls
 - ✅ **Optimistic Locking** Ensures data consistency by preventing conflicts when multiple users update the same record
 - ✅ **Query Plan Analysis**: Detailed execution plan analysis and optimization insights
+- ✅ **Rovo Integration** Secure pattern for natural-language analytics with comprehensive security validations, Row-Level Security (RLS) support, and dynamic SQL query execution
 
 ## Table of Contents
 
@@ -68,6 +70,7 @@
 ### 🔒 Advanced Features
 
 - [Optimistic Locking](#optimistic-locking)
+- [Rovo Integration](#rovo-integration) - Secure pattern for natural-language analytics with dynamic SQL queries
 - [Query Analysis and Performance Optimization](#query-analysis-and-performance-optimization)
 - [Automatic Error Analysis](#automatic-error-analysis) - Automatic timeout and OOM error detection with execution plans
 - [Slow Query Monitoring](#slow-query-monitoring) - Scheduled monitoring of slow queries with execution plans
@@ -90,6 +93,7 @@
 - [Organization Tracker Example](examples/forge-sql-orm-example-org-tracker)
 - [Checklist Example](examples/forge-sql-orm-example-checklist)
 - [Cache Example](examples/forge-sql-orm-example-cache) - Advanced caching capabilities with performance monitoring
+- [Rovo Integration Example](https://github.com/vzakharchenko/Forge-Secure-Notes-for-Jira) - Real-world Rovo AI agent implementation with secure natural-language analytics
 
 ### 📚 Reference
 
@@ -109,6 +113,7 @@
 - [Global Cache System (Level 2)](#global-cache-system-level-2) - Cross-invocation persistent caching
 - [Local Cache System (Level 1)](#local-cache-operations-level-1) - In-memory invocation caching
 - [Optimistic Locking](#optimistic-locking) - Data consistency
+- [Rovo Integration](#rovo-integration) - Secure natural-language analytics
 - [Migration Tools](#web-triggers-for-migrations) - Database migrations
 - [Query Analysis](#query-analysis-and-performance-optimization) - Performance optimization
 
@@ -119,6 +124,7 @@
 - [Organization Tracker Example](examples/forge-sql-orm-example-org-tracker) - Complex relationships
 - [Checklist Example](examples/forge-sql-orm-example-checklist) - Jira integration
 - [Cache Example](examples/forge-sql-orm-example-cache) - Advanced caching capabilities
+- [Rovo Integration Example](https://github.com/vzakharchenko/Forge-Secure-Notes-for-Jira) - Real-world Rovo AI agent with secure analytics
 
 ## Usage Approaches
 
@@ -342,6 +348,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;
@@ -351,12 +362,46 @@ resolver.define("fetch", async (req: Request) => {
 });
 ```
 
-### 5. Next Steps
+**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
+// Secure dynamic SQL queries for natural-language analytics
+const rovo = forgeSQL.rovo();
+const settings = await rovo
+  .rovoSettingBuilder(usersTable, accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .useRLS()
+  .addRlsColumn(usersTable.id)
+  .addRlsWherePart((alias) => `${alias}.${usersTable.id.name} = '${accountId}'`)
+  .finish()
+  .build();
+
+const result = await rovo.dynamicIsolatedQuery(
+  "SELECT id, name FROM users WHERE status = 'active' AND userId = :currentUserId",
+  settings,
+);
+```
+
+### 6. Next Steps
 
 - [Full Installation Guide](#installation) - Complete setup instructions
 - [Core Features](#core-features) - Learn about key capabilities
 - [Global Cache System (Level 2)](#global-cache-system-level-2) - Cross-invocation caching features
 - [Local Cache System (Level 1)](#local-cache-operations-level-1) - In-memory caching features
+- [Rovo Integration](#rovo-integration) - Secure natural-language analytics
 - [API Reference](#reference) - Complete API documentation
 
 ## Drizzle Usage with forge-sql-orm
@@ -426,6 +471,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
@@ -466,6 +516,22 @@ const userStats = await forgeSQL
   })
   .from(sql`activeUsers au`)
   .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+
+// Rovo Integration for secure dynamic SQL queries
+const rovo = forgeSQL.rovo();
+const settings = await rovo
+  .rovoSettingBuilder(usersTable, accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .useRLS()
+  .addRlsColumn(usersTable.id)
+  .addRlsWherePart((alias) => `${alias}.${usersTable.id.name} = '${accountId}'`)
+  .finish()
+  .build();
+
+const rovoResult = await rovo.dynamicIsolatedQuery(
+  "SELECT id, name FROM users WHERE status = 'active' AND userId = :currentUserId",
+  settings,
+);
 ```
 
 This approach gives you direct access to all Drizzle ORM features while still using the @forge/sql backend with enhanced caching and versioning capabilities.
@@ -547,7 +613,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
+  },
 );
 ```
 
@@ -951,23 +1022,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.
 
@@ -1371,7 +1442,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.)
@@ -1739,6 +1815,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
@@ -1940,6 +2021,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
+  },
 );
 ```
 
@@ -2011,6 +2097,223 @@ await forgeSQL.modifyWithVersioningAndEvictCache().updateById(
 );
 ```
 
+## Rovo Integration
+
+[↑ Back to Top](#table-of-contents)
+
+Rovo is a secure pattern for natural-language analytics in Forge apps. It enables safe execution of dynamic SQL queries with comprehensive security validations, making it ideal for AI-powered analytics features where users can query data using natural language.
+
+**📖 Real-World Example**: See [Forge-Secure-Notes-for-Jira](https://github.com/vzakharchenko/Forge-Secure-Notes-for-Jira) for a complete implementation of Rovo AI agent with secure natural-language analytics.
+
+### Key Features
+
+- **Security-First Design**: Multiple layers of security validations to prevent SQL injection and unauthorized data access
+- **Single Table Isolation**: Queries are restricted to a single table to prevent cross-table data access
+- **Row-Level Security (RLS)**: Built-in support for data isolation based on user context
+- **Comprehensive Validation**: Blocks JOINs, subqueries, window functions, and other potentially unsafe operations
+- **Post-Execution Validation**: Verifies query results to ensure security fields are present and come from the correct table
+- **Type-Safe Configuration**: Uses Drizzle ORM table objects for type-safe column references
+
+### Security Validations
+
+Rovo performs multiple security checks before and after query execution:
+
+1. **Query Type Validation**: Only SELECT queries are allowed
+2. **Table Restriction**: Queries must target only the specified table
+3. **JOIN Detection**: JOINs are blocked using EXPLAIN analysis
+4. **Subquery Detection**: Scalar subqueries in SELECT columns are blocked
+5. **Window Function Detection**: Window functions are blocked for security
+6. **Execution Plan Validation**: Verifies that only the expected table is accessed
+7. **RLS Field Validation**: Ensures required security fields are present in results
+8. **Post-Execution Validation**: Verifies all fields come from the correct table
+
+### Basic Usage
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+// Get Rovo instance
+const rovo = forgeSQL.rovo();
+
+// Create settings builder using Drizzle table object
+const settings = await rovo
+  .rovoSettingBuilder(usersTable, accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .useRLS()
+  .addRlsColumn(usersTable.id)
+  .addRlsWherePart((alias) => `${alias}.${usersTable.id.name} = '${accountId}'`)
+  .finish()
+  .build();
+
+// Execute dynamic SQL query
+const result = await rovo.dynamicIsolatedQuery(
+  "SELECT id, name FROM users WHERE status = 'active' AND userId = :currentUserId",
+  settings,
+);
+
+console.log(result.rows); // Query results
+console.log(result.metadata); // Query metadata
+```
+
+### Row-Level Security (RLS) Configuration
+
+RLS allows you to filter data based on user context, ensuring users can only access their own data:
+
+```typescript
+const rovo = forgeSQL.rovo();
+
+// Configure RLS with conditional activation and multiple security fields
+const settings = await rovo
+  .rovoSettingBuilder(securityNotesTable, accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .addContextParameter(":currentProjectKey", projectKey)
+  .addContextParameter(":currentIssueKey", issueKey)
+  .useRLS()
+  .addRlsCondition(async () => {
+    // Conditionally enable RLS based on user role
+    const userService = getUserService();
+    return !(await userService.isAdmin()); // Only apply RLS for non-admin users
+  })
+  .addRlsColumn(securityNotesTable.createdBy) // Required field for RLS validation
+  .addRlsColumn(securityNotesTable.targetUserId) // Additional security field
+  .addRlsWherePart(
+    (alias) =>
+      `${alias}.${securityNotesTable.createdBy.name} = '${accountId}' OR ${alias}.${securityNotesTable.targetUserId.name} = '${accountId}'`,
+  ) // RLS filter with OR condition
+  .finish()
+  .build();
+
+// The query will automatically be wrapped with RLS filtering:
+// SELECT * FROM (original_query) AS t WHERE (t.createdBy = 'accountId' OR t.targetUserId = 'accountId')
+```
+
+### Context Parameters
+
+You can use context parameters for query substitution. Parameters use the `:parameterName` format (colon prefix, not double braces):
+
+```typescript
+const rovo = forgeSQL.rovo();
+
+const settings = await rovo
+  .rovoSettingBuilder(usersTable, accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .addContextParameter(":projectKey", "PROJ-123")
+  .addContextParameter(":status", "active")
+  .useRLS()
+  .addRlsColumn(usersTable.id)
+  .addRlsWherePart((alias) => `${alias}.${usersTable.userId.name} = '${accountId}'`)
+  .finish()
+  .build();
+
+// In the SQL query, parameters are replaced:
+const result = await rovo.dynamicIsolatedQuery(
+  "SELECT * FROM users WHERE projectKey = :projectKey AND status = :status AND userId = :currentUserId",
+  settings,
+);
+// Becomes: SELECT * FROM users WHERE projectKey = 'PROJ-123' AND status = 'active' AND userId = 'accountId'
+```
+
+### Using Raw Table Names
+
+You can use `rovoRawSettingBuilder` with raw table name string:
+
+```typescript
+const rovo = forgeSQL.rovo();
+
+// Using rovoRawSettingBuilder with raw table name
+const settings = await rovo
+  .rovoRawSettingBuilder("users", accountId)
+  .addContextParameter(":currentUserId", accountId)
+  .useRLS()
+  .addRlsColumnName("id")
+  .addRlsWherePart((alias) => `${alias}.id = '${accountId}'`)
+  .finish()
+  .build();
+
+const result = await rovo.dynamicIsolatedQuery(
+  "SELECT id, name FROM users WHERE status = 'active' AND userId = :currentUserId",
+  settings,
+);
+```
+
+### Security Restrictions
+
+Rovo blocks the following operations for security:
+
+- **Data Modification**: Only SELECT queries are allowed
+- **JOINs**: JOIN operations are detected and blocked
+- **Subqueries**: Scalar subqueries in SELECT columns are blocked
+- **Window Functions**: Window functions (e.g., `COUNT(*) OVER(...)`) are blocked
+- **Multiple Tables**: Queries referencing multiple tables are blocked
+- **Table Aliases**: Post-execution validation ensures fields come from the correct table
+
+### Error Handling
+
+Rovo provides detailed error messages when security violations are detected:
+
+```typescript
+try {
+  const result = await rovo.dynamicIsolatedQuery(
+    "SELECT * FROM users u JOIN orders o ON u.id = o.userId",
+    settings,
+  );
+} catch (error) {
+  // Error: "Security violation: JOIN operations are not allowed..."
+  console.error(error.message);
+}
+```
+
+### Example: Real-World Function Implementation
+
+> **💡 Full Example**: See the complete implementation in [Forge-Secure-Notes-for-Jira](https://github.com/vzakharchenko/Forge-Secure-Notes-for-Jira) repository.
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+import { Result } from "@forge/sql";
+
+const FORGE_SQL_ORM = new ForgeSQL();
+
+export async function runSecurityNotesQuery(
+  event: {
+    sql: string;
+    context: {
+      jira: {
+        issueKey: string;
+        projectKey: string;
+      };
+    };
+  },
+  context: { principal: { accountId: string } },
+): Promise<Result<unknown>> {
+  const rovoIntegration = FORGE_SQL_ORM.rovo();
+  const accountId = context.principal.accountId;
+
+  const settings = await rovoIntegration
+    .rovoSettingBuilder(securityNotesTable, accountId)
+    .addContextParameter(":currentUserId", accountId)
+    .addContextParameter(":currentProjectKey", event.context?.jira?.projectKey ?? "")
+    .addContextParameter(":currentIssueKey", event.context?.jira?.issueKey ?? "")
+    .useRLS()
+    .addRlsCondition(async () => {
+      // Conditionally disable RLS for admin users
+      const userService = getUserService();
+      return !(await userService.isAdmin());
+    })
+    .addRlsColumn(securityNotesTable.createdBy)
+    .addRlsColumn(securityNotesTable.targetUserId)
+    .addRlsWherePart(
+      (alias: string) =>
+        `${alias}.${securityNotesTable.createdBy.name} = '${accountId}' OR ${alias}.${securityNotesTable.targetUserId.name} = '${accountId}'`,
+    )
+    .finish()
+    .build();
+
+  return await rovoIntegration.dynamicIsolatedQuery(event.sql, settings);
+}
+```
+
 ## ForgeSqlOrmOptions
 
 The `ForgeSqlOrmOptions` object allows customization of ORM behavior:
@@ -2363,6 +2666,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.
@@ -2653,6 +3177,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