forge-sql-orm 2.1.9 → 2.1.11

package/README.md

@@ -9,7 +9,6 @@
 
 [![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)
-[![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)
 [![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)
 
 
@@ -19,11 +18,11 @@
 - ✅ **Custom Drizzle Driver** for direct integration with @forge/sql
 - ✅ **Local Cache System (Level 1)** for in-memory query optimization within single resolver invocation scope
 - ✅ **Global Cache System (Level 2)** with cross-invocation caching, automatic cache invalidation and context-aware operations (using [@forge/kvs](https://developer.atlassian.com/platform/forge/storage-reference/storage-api-custom-entities/) )
-- ✅ **Performance Monitoring**: Automated detection of memory-intensive queries with configurable thresholds (essential for Atlassian's 16 MiB per query limit)
+- ✅ **Performance Monitoring**: Query execution metrics and analysis capabilities with automatic error analysis for timeout and OOM errors
 - ✅ **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 Forge SQL metadata
+- ✅ **Query Execution with Metadata**: `executeWithMetadata()` method for capturing detailed execution metrics including database execution time, response size, and query analysis capabilities with performance monitoring
 - ✅ **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
@@ -82,7 +81,7 @@
 - [Query Analysis Example](examples/forge-sql-orm-example-query-analyses)
 - [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 `topSlowestStatementLastHourTrigger` performance monitoring
+- [Cache Example](examples/forge-sql-orm-example-cache) - Advanced caching capabilities with performance monitoring
 
 ### 📚 Reference
 - [ForgeSqlOrmOptions](#forgesqlormoptions)
@@ -99,7 +98,6 @@
 - [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
-- [Memory Usage Monitoring](#memory-usage-monitoring) - Memory-intensive query detection
 - [Migration Tools](#web-triggers-for-migrations) - Database migrations
 - [Query Analysis](#query-analysis-and-performance-optimization) - Performance optimization
 
@@ -108,7 +106,7 @@
 - [Optimistic Locking Example](examples/forge-sql-orm-example-optimistic-locking) - Real-world conflict handling
 - [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 with memory monitoring
+- [Cache Example](examples/forge-sql-orm-example-cache) - Advanced caching capabilities
 
 ## Usage Approaches
 
@@ -276,7 +274,41 @@ await forgeSQL.executeWithLocalContext(async () => {
 });
 ```
 
-### 4. Next Steps
+### 4. Resolver Performance Monitoring
+```typescript
+// Resolver with performance monitoring
+resolver.define("fetch", async (req: Request) => {
+  try {
+    return await forgeSQL.executeWithMetadata(
+      async () => {
+        // Resolver logic with multiple queries
+        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(); // Optionally log or capture diagnostics for further analysis
+        } else if (totalDbExecutionTime > threshold) {
+          console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
+        }
+        
+        console.log(`DB response size: ${totalResponseSize} bytes`);
+      }
+    );
+  } catch (e) {
+    const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
+    console.error(error, e);
+    throw error;
+  }
+});
+```
+
+### 5. 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
@@ -334,13 +366,24 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   300
 );
 
-// Raw SQL with execution metadata
+// Raw SQL with execution metadata and performance monitoring
 const usersWithMetadata = await forgeSQL.executeWithMetadata(
-  async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
-  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-    console.log(`Response size: ${totalResponseSize} bytes`);
-    console.log('Forge metadata:', forgeMetadata);
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+    return { users, orders };
+  },
+  (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`);
   }
 );
 
@@ -444,13 +487,24 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   300
 );
 
-// Raw SQL with execution metadata
+// Raw SQL with execution metadata and performance monitoring
 const usersWithMetadata = await forgeSQL.executeWithMetadata(
-  async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
-  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-    console.log(`Response size: ${totalResponseSize} bytes`);
-    console.log('Forge metadata:', forgeMetadata);
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+    return { users, orders };
+  },
+  (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`);
   }
 );
 ```
@@ -1215,16 +1269,26 @@ const users = await forgeSQL
 const users = await forgeSQL
   .executeCacheable("SELECT * FROM users WHERE active = ?", [true], 300);
 
-// Using executeWithMetadata() for capturing execution metrics
-const usersWithMetadata = await forgeSQL
-    .executeWithMetadata(
-        async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
-        (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-            console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-            console.log(`Response size: ${totalResponseSize} bytes`);
-            console.log('Forge metadata:', forgeMetadata);
-        }
-    );
+// Using executeWithMetadata() for capturing execution metrics and performance monitoring
+const usersWithMetadata = 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 };
+  },
+  (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`);
+  }
+);
 
 // Using executeDDL() for DDL operations (CREATE, ALTER, DROP, etc.)
 await forgeSQL.executeDDL(`
@@ -1575,13 +1639,24 @@ await forgeSQL.executeWithLocalContext(async () => {
     [true]
   );
   
-  // Raw SQL with execution metadata and local caching
+  // Raw SQL with execution metadata and performance monitoring
   const usersWithMetadata = await forgeSQL.executeWithMetadata(
-    async () => await forgeSQL.execute("SELECT id, name FROM users WHERE active = ?", [true]),
-    (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-      console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-      console.log(`Response size: ${totalResponseSize} bytes`);
-      console.log('Forge metadata:', forgeMetadata);
+    async () => {
+      const users = await forgeSQL.selectFrom(usersTable);
+      const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+      return { users, orders };
+    },
+    (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`);
     }
   );
   
@@ -1754,13 +1829,24 @@ const userStats = await forgeSQL
   .from(sql`activeUsers au`)
   .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
 
-// Using executeWithMetadata() for capturing execution metrics with caching
+// Using executeWithMetadata() for capturing execution metrics with performance monitoring
 const usersWithMetadata = await forgeSQL.executeWithMetadata(
-  async () => await forgeSQL.executeCacheable("SELECT * FROM users WHERE active = ?", [true], 300),
-  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-    console.log(`Response size: ${totalResponseSize} bytes`);
-    console.log('Forge metadata:', forgeMetadata);
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+    return { users, orders };
+  },
+  (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`);
   }
 );
 ```
@@ -2065,6 +2151,64 @@ Atlassian provides comprehensive query analysis tools in the development console
 
 Our analysis tools complement these built-in features by providing additional insights directly from TiDB's system schemas.
 
+### Automatic Error Analysis
+
+Forge-SQL-ORM automatically intercepts and analyzes critical query errors to help you diagnose performance issues. When a query fails due to **timeout** or **out-of-memory** errors, the library automatically:
+
+1. **Detects the error type** (SQL_QUERY_TIMEOUT or Out of Memory)
+2. **Logs detailed error information** to the Forge Developer Console
+3. **Waits for system tables to populate** (200ms delay)
+4. **Retrieves and logs the execution plan** for the failed query
+5. **Provides performance metrics** including memory usage, execution time, and query details
+
+This automatic analysis happens transparently - no additional code is required on your part.
+
+#### Supported Error Types
+
+- **SQL_QUERY_TIMEOUT**: Queries that exceed the execution time limit
+- **Out of Memory (OOM)**: Queries that exceed the 16 MiB memory limit (errno: 8175)
+
+#### Example Console Output
+
+When a query fails, you'll see output like this in the Forge Developer Console:
+
+```
+❌ TIMEOUT detected - Query exceeded time limit
+⏳ Waiting 200ms for CLUSTER_STATEMENTS_SUMMARY to populate...
+📊 Analyzing query performance and execution plan...
+⏱️  Query duration: 10500ms
+
+SQL: SELECT * FROM users u INNER JOIN orders o ON u.id = o.user_id WHERE u.active = ? | Memory: 12.45 MB | Time: 10500.00 ms | stmtType: Select | Executions: 1
+ Plan:
+id task estRows operator info actRows execution info memory disk
+Projection_7 root 1000.00 forge_38dd1c6156b94bb59c2c9a45582bbfc7.users.id, ... 1000 time:10.5s, loops:1 12.45 MB N/A
+└─IndexHashJoin_14 root 1000.00 inner join, ... 1000 time:10.2s, loops:1 11.98 MB N/A
+```
+
+#### How It Works
+
+The error analysis mechanism:
+
+1. **Error Detection**: When a query fails, the driver proxy checks the error code/errno
+2. **Error Logging**: Logs the specific error type to console.error
+3. **Data Population Wait**: Waits 200ms for TiDB's `CLUSTER_STATEMENTS_SUMMARY` table to be populated with the failed query's metadata
+4. **Query Analysis**: Automatically calls `printQueriesWithPlan()` to retrieve and display:
+   - SQL query text
+   - Memory consumption (average and max in MB)
+   - Execution time (average in ms)
+   - Statement type
+   - Number of executions
+   - Detailed execution plan
+
+#### Benefits
+
+- **Zero Configuration**: Works automatically - no setup required
+- **Immediate Insights**: Get execution plans for failed queries instantly
+- **Performance Debugging**: Identify bottlenecks without manual investigation
+- **Development Console Integration**: All logs appear in Atlassian Forge Developer Console
+- **No Code Changes**: Existing code automatically benefits from error analysis
+
+> **💡 Tip**: The automatic error analysis only triggers for timeout and OOM errors. Other errors are logged normally without plan analysis.
 
 ### Available Analysis Tools
 
@@ -2138,213 +2282,6 @@ This analysis provides insights into:
 - Resource usage at each step
 - Performance optimization opportunities
 
-## Performance Monitoring
-
-[↑ Back to Top](#table-of-contents)
-
-Forge-SQL-ORM provides automated performance monitoring capabilities to help you identify and track memory-intensive queries in your Forge SQL instance. This feature is **essential for Atlassian Forge applications** as it helps you stay within the **16 MiB per query memory limit** and provides detailed insights for optimization.
-
-### Why Performance Monitoring is Critical
-
-Atlassian Forge SQL has a strict **16 MiB memory limit per query**. Unlike slow query detection (which is available in the Forge Developer Console), there's **no built-in way to monitor memory usage** of your queries. This monitoring system fills that gap by:
-
-- **Detecting memory-intensive queries** before they hit the 16 MiB limit
-- **Providing detailed memory metrics** including average and maximum memory usage
-- **Showing execution plans** to help optimize memory consumption
-- **Configurable thresholds** to match your application's memory requirements
-- **Scheduled monitoring** via Forge scheduler triggers
-
-### Overview
-
-The performance monitoring system:
-- **Automatically detects memory-intensive queries** based on configurable memory thresholds
-- **Provides detailed memory metrics** including execution time, memory usage, and execution plans
-- **Logs memory issues** to the Forge Developer Console for easy debugging
-- **Supports scheduled monitoring** via Forge scheduler triggers
-- **Filters out system queries** to focus on your application's performance
-
-### Key Features
-
-- **Memory-Focused Performance Monitoring**: Primary focus on memory usage with configurable thresholds
-- **Atlassian 16 MiB Limit Awareness**: Designed specifically for Forge SQL's memory constraints
-- **Execution Plan Analysis**: Shows detailed query plans to help optimize memory consumption
-- **Configurable Thresholds**: Set custom memory usage thresholds (default: 4MB warning)
-- **Automatic Filtering**: Excludes system queries (`Use`, `Set`, `Show`) and empty queries
-- **Scheduled Monitoring**: Run automatically on configurable intervals
-
-### Basic Usage
-
-#### 1. Import the Trigger
-
-```typescript
-import ForgeSQL, { topSlowestStatementLastHourTrigger } from "forge-sql-orm";
-```
-
-#### 2. Create a Scheduler Function
-
-```typescript
-import ForgeSQL, { topSlowestStatementLastHourTrigger } from 'forge-sql-orm';
-
-// Initialize ForgeSQL ORM instance
-const forgeSQL = new ForgeSQL();
-
-// Basic usage with default thresholds (300ms latency, 8MB memory warning)
-export const performanceTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL);
-
-// Conservative performance monitoring: 4MB warning (well below 16MB limit)
-export const conservativeMemoryTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, { memoryThresholdBytes: 4 * 1024 * 1024 });
-
-// Aggressive performance monitoring: 12MB warning (75% of 16MB limit)
-export const aggressiveMemoryTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, { memoryThresholdBytes: 12 * 1024 * 1024 });
-
-// Memory-only performance monitoring: Only trigger on memory usage (latency effectively disabled)
-export const memoryOnlyTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, { warnThresholdMs: 10000, memoryThresholdBytes: 4 * 1024 * 1024 });
-
-// Latency-only monitoring: Only trigger on slow queries (memory effectively disabled)
-export const latencyOnlyTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, { warnThresholdMs: 500, memoryThresholdBytes: 16 * 1024 * 1024 });
-
-// With execution plan in logs
-export const performanceWithPlanTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, { showPlan: true });
-```
-
-#### 3. Configure in manifest.yml
-
-**As Scheduler Trigger (Recommended for Production):**
-```yaml
-scheduledTrigger:
-  - key: performance-trigger
-    function: perfTrigger
-    interval: hour  # Required: only hour interval is supported
-
-function:
-  - key: perfTrigger
-    handler: index.performanceTrigger
-```
-
-**As Web Trigger (Development Only):**
-```yaml
-webtrigger:
-  - key: print-slowest-queries
-    function: perfTrigger
-
-function:
-  - key: perfTrigger
-    handler: index.performanceTrigger
-```
-
-> **⚠️ Important**: Web triggers are not recommended for production as they violate the "run-on-atlassian" principle. Use scheduler triggers for production monitoring.
-
-### How It Works
-
-The performance monitoring trigger works differently depending on how it's configured:
-
-#### Scheduler Trigger Mode (Production)
-
-When used as a **scheduler trigger**, the system:
-- **Runs automatically** on the configured interval (hour only)
-- **Logs to Forge Developer Console** only when thresholds are exceeded
-- **No HTTP response** - operates silently in the background
-- **Perfect for production** monitoring without violating "run-on-atlassian"
-
-**Example Console Log Output:**
-```
-1. Select  avg=3006.03ms  max=3006.03ms  mem≈0.08MB(max 0.08MB)  exec=1 
-   digest=28344800f90f6c929484e83337404df7e55a660c5f4ce922c4b298ab5e90c425
-   sql=select `demo_users` . `id` as `a_userid_id` , `demo_users` . `name` as `a_username_name` , `demo_orders` . `product` as `a_product_product` , `demo_orders` . `id` as `a_productid_id` , `sleep` ( ? ) from `demo_users` inner join `demo_orders` on `demo_orders` . `user_id` = `demo_users` . `id`
-
-full plan:
-id task estRows operator info actRows execution info memory disk
-Projection_7 root 2.50 forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_users.id, forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_users.name, forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_orders.product, forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_orders.id, sleep(?)->Column#7 3 time:3s, loops:2, Concurrency:OFF 1.98 KB N/A
-└─IndexHashJoin_14 root 2.50 inner join, inner:IndexLookUp_11, outer key:forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_users.id, inner key:forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_orders.user_id, equal cond:eq(forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_users.id, forge_38dd1c6156b94bb59c2c9a45582bbfc7.demo_orders.user_id) 3 time:2.11ms, loops:2, inner:{total:1.31ms, concurrency:5, task:1, construct:6.62µs, fetch:1.3ms, build:4.68µs, join:6.14µs} 57.9 KB N/A
-```
-
-#### Web Trigger Mode (Development)
-
-When used as a **web trigger**, the system:
-- **Runs on-demand** when the web endpoint is called
-- **Returns JSON response** with detailed metrics
-- **Logs to console** AND provides structured data
-- **Useful for development** and debugging
-
-**Example JSON Response:**
-```json
-{
-  "success": true,
-  "window": "last_1h",
-  "top": 1,
-  "warnThresholdMs": 300,
-  "memoryThresholdBytes": 8388608,
-  "rows": [
-    {
-      "rank": 1,
-      "digest": "abc123...",
-      "stmtType": "Select",
-      "schemaName": "myapp",
-      "execCount": 150,
-      "avgLatencyMs": 450.25,
-      "maxLatencyMs": 1200.50,
-      "minLatencyMs": 200.10,
-      "avgProcessTimeMs": 400.20,
-      "avgWaitTimeMs": 50.05,
-      "avgBackoffTimeMs": 0.00,
-      "avgMemMB": 2.5,
-      "maxMemMB": 8.2,
-      "avgMemBytes": 2621440,
-      "maxMemBytes": 8598323,
-      "avgTotalKeys": 1000,
-      "firstSeen": "2024-01-15 10:30:00",
-      "lastSeen": "2024-01-15 11:30:00",
-      "planInCache": true,
-      "planCacheHits": 120,
-      "digestText": "SELECT * FROM users WHERE active = ?",
-      "plan": "IndexScan(users, idx_active)..."
-    }
-  ],
-  "generatedAt": "2024-01-15T11:30:00.000Z"
-}
-```
-
-### Configuration Options
-
-#### Threshold Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `warnThresholdMs` | `number` | `300` | Latency threshold in milliseconds (secondary) |
-| `memoryThresholdBytes` | `number` | `8 * 1024 * 1024` | **Memory usage threshold in bytes (primary focus)** |
-| `showPlan` | `boolean` | `false` | Whether to include execution plan in logs |
-| `logCache` | `boolean` | `false` | Whether to log cache operations |
-
-**⚠️ Important: OR Logic**
-The monitoring uses **OR logic** - if **either** threshold is exceeded, the query will be logged/returned:
-- Query exceeds `warnThresholdMs` **OR** `memoryThresholdBytes` → Included in results
-- This means you can set different thresholds for different monitoring priorities
-- No need to exceed both thresholds simultaneously
-
-**💡 Pro Tips:**
-- **Memory-only performance monitoring**: Set `warnThresholdMs` to a very high value (e.g., 10000ms) to trigger only on memory usage
-- **Latency-only monitoring**: Set `memoryThresholdBytes` to 16MB (16 * 1024 * 1024) to trigger only on latency
-- **Combined monitoring**: Use both thresholds for comprehensive monitoring
-- **Execution plan analysis**: Set `showPlan: true` to include detailed execution plans in logs (useful for debugging)
-- **Cache debugging**: Set `logCache: true` to log cache operations and debug caching issues
-
-**Memory Threshold Guidelines:**
-- **Conservative**: 4MB (25% of 16MB limit)
-- **Default**: 8MB (50% of 16MB limit) 
-- **Aggressive**: 12MB (75% of 16MB limit)
-- **Critical**: 14MB (87.5% of 16MB limit)
-
-#### Available Intervals
-
-- `hour` - **Every hour (Required)** - Statistics are available for approximately 12 hours
-
-> **⚠️ Important**: Due to Forge SQL's statistics retention policy (approximately 12 hours), **only `hour` interval is supported**. Using `day` or `week` intervals will result in incomplete or missing data.
 
 ## Migration Guide
 
@@ -2439,14 +2376,25 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   300
 );
 
-// ✅ Raw SQL execution with metadata capture
+// ✅ Raw SQL execution with metadata capture and performance monitoring
 const usersWithMetadata = await forgeSQL.executeWithMetadata(
-    async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
-    (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
-        console.log(`DB execution time: ${totalDbExecutionTime}ms`);
-        console.log(`Response size: ${totalResponseSize} bytes`);
-        console.log('Forge metadata:', forgeMetadata);
+  async () => {
+    const users = await forgeSQL.selectFrom(usersTable);
+    const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+    return { users, orders };
+  },
+  (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`);
+  }
 );
 
 // ✅ DDL operations for schema modifications