forge-sql-orm 2.1.10 → 2.1.12

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, plus scheduled slow query monitoring with execution plans
 - ✅ **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
@@ -65,7 +64,8 @@
 ### 🔒 Advanced Features
 - [Optimistic Locking](#optimistic-locking)
 - [Query Analysis and Performance Optimization](#query-analysis-and-performance-optimization)
-- [Performance Monitoring](#performance-monitoring)
+- [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
 - [Date and Time Types](#date-and-time-types)
 
 ### 🛠️ Development Tools
@@ -82,7 +82,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 +99,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 +107,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 +275,39 @@ 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 fetch] High DB time: ${totalDbExecutionTime} ms`);
+        }
+      }
+    );
+  } 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
@@ -328,19 +359,31 @@ const rawUsers = await forgeSQL.execute(
 );
 
 // Raw SQL with caching
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names must be wrapped with backticks (`)
 const cachedRawUsers = await forgeSQL.executeCacheable(
-  "SELECT * FROM users WHERE active = ?", 
+  "SELECT * FROM `users` WHERE active = ?", 
   [true], 
   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`);
   }
 );
 
@@ -438,19 +481,31 @@ const rawUsers = await forgeSQL.execute(
 );
 
 // Raw SQL with caching
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names must be wrapped with backticks (`)
 const cachedRawUsers = await forgeSQL.executeCacheable(
-  "SELECT * FROM users WHERE active = ?", 
+  "SELECT * FROM `users` WHERE active = ?", 
   [true], 
   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`);
   }
 );
 ```
@@ -563,6 +618,9 @@ Please review the [official @forge/kvs quotas and limits](https://developer.atla
 - Monitor cache usage to stay within quotas
 - Use appropriate TTL values
 
+**⚠️ Important Cache Limitations:**
+- **Table names starting with `a_`**: Tables whose names start with `a_` (case-insensitive) are automatically ignored in cache operations. KVS Cache will not work with such tables, and they will be excluded from cache invalidation and cache key generation. This is by design to support special system tables or temporary tables.
+
 ### Step 1: Install Dependencies
 
 ```bash
@@ -1082,8 +1140,10 @@ const user = await forgeSQL
     .execute("SELECT * FROM users WHERE id = ?", [1]);
 
 // Using forgeSQL.executeCacheable() - Execute raw SQL with local and global caching
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names in SQL queries must be wrapped with backticks (`)
+// Example: SELECT * FROM `users` WHERE id = ? (NOT: SELECT * FROM users WHERE id = ?)
 const user = await forgeSQL
-    .executeCacheable("SELECT * FROM users WHERE id = ?", [1], 300);
+    .executeCacheable("SELECT * FROM `users` WHERE id = ?", [1], 300);
 
 // Using forgeSQL.getDrizzleQueryBuilder()
 const user = await forgeSQL
@@ -1212,19 +1272,31 @@ const users = await forgeSQL
   .execute("SELECT * FROM users WHERE active = ?", [true]);
 
 // Using executeCacheable() for raw SQL with local and global caching
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names in SQL queries must be wrapped with backticks (`)
+// Example: SELECT * FROM `users` WHERE active = ? (NOT: SELECT * FROM users WHERE active = ?)
 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);
-        }
-    );
+  .executeCacheable("SELECT * FROM `users` WHERE active = ?", [true], 300);
+
+// 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 +1647,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`);
     }
   );
   
@@ -1685,8 +1768,9 @@ await forgeSQL.executeWithLocalContext(async () => {
     .where(eq(users.active, true));
   
   // Raw SQL with multi-level caching
+  // ⚠️ IMPORTANT: When using executeCacheable(), all table names must be wrapped with backticks (`)
   const rawUsers = await forgeSQL.executeCacheable(
-    "SELECT id, name FROM users WHERE active = ?", 
+    "SELECT id, name FROM `users` WHERE active = ?", 
     [true], 
     300 // TTL in seconds
   );
@@ -1735,8 +1819,9 @@ const usersDistinct = await forgeSQL.selectDistinctCacheableFrom(Users)
   .where(eq(Users.active, true));
 
 // Raw SQL with local and global caching
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names must be wrapped with backticks (`)
 const rawUsers = await forgeSQL.executeCacheable(
-  "SELECT * FROM users WHERE active = ?",
+  "SELECT * FROM `users` WHERE active = ?",
   [true],
   300 // TTL in seconds
 );
@@ -1754,13 +1839,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`);
   }
 );
 ```
@@ -2036,6 +2132,34 @@ Configure in `manifest.yml`:
 - `hour` - Every hour
 - `day` - Every day
 
+### 5. Slow Query Scheduler Trigger
+
+This scheduler trigger automatically monitors and analyzes slow queries on a scheduled basis. For detailed information, see the [Slow Query Monitoring](#slow-query-monitoring) section.
+
+**Quick Setup:**
+
+```typescript
+import ForgeSQL, { slowQuerySchedulerTrigger } from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+export const slowQueryTrigger = () =>
+  slowQuerySchedulerTrigger(forgeSQL, { hours: 1, timeout: 3000 });
+```
+
+Configure in `manifest.yml`:
+```yaml
+  scheduledTrigger:
+    - key: slow-query-trigger
+      function: slowQueryTrigger
+      interval: hour
+  function:
+    - key: slowQueryTrigger
+      handler: index.slowQueryTrigger
+```
+
+> **💡 Note**: For complete documentation, examples, and configuration options, see the [Slow Query Monitoring](#slow-query-monitoring) section.
+
 ### Important Notes
 
 **Security Considerations**:
@@ -2065,6 +2189,170 @@ 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.
+
+### 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.
+
+#### Key Features
+
+- **Automatic Monitoring**: Runs on a scheduled interval (recommended: hourly)
+- **Detailed Performance Metrics**: Memory usage, execution time, and execution plans
+- **Console Logging**: Results are automatically logged to the Forge Developer Console
+- **Configurable Time Window**: Analyze queries from the last N hours (default: 1 hour)
+- **Automatic Plan Retrieval**: Execution plans are included for all slow queries
+
+#### Basic Setup
+
+**1. Create the trigger function:**
+
+```typescript
+import ForgeSQL, { slowQuerySchedulerTrigger } from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+// Monitor slow queries from the last hour (recommended for hourly schedule)
+export const slowQueryTrigger = () =>
+  slowQuerySchedulerTrigger(forgeSQL, { hours: 1, timeout: 3000 });
+```
+
+**2. Configure in `manifest.yml`:**
+
+```yaml
+modules:
+  scheduledTrigger:
+    - key: slow-query-trigger
+      function: slowQueryTrigger
+      interval: hour  # Run every hour
+  
+  function:
+    - key: slowQueryTrigger
+      handler: index.slowQueryTrigger
+```
+
+#### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hours` | `number` | `1` | Number of hours to look back for slow queries |
+| `timeout` | `number` | `3000` | Timeout in milliseconds for the diagnostic query execution |
+
+#### Example Console Output
+
+When slow queries are detected, you'll see output like this in the Forge Developer Console:
+
+```
+Found SlowQuery SQL: SELECT * FROM users u INNER JOIN orders o ON u.id = o.user_id WHERE u.active = ? | Memory: 8.50 MB | Time: 2500.00 ms
+ Plan:
+id task estRows operator info actRows execution info memory disk
+Projection_7 root 1000.00 forge_38dd1c6156b94bb59c2c9a45582bbfc7.users.id, ... 1000 time:2.5s, loops:1 8.50 MB N/A
+└─IndexHashJoin_14 root 1000.00 inner join, ... 1000 time:2.2s, loops:1 7.98 MB N/A
+
+Found SlowQuery SQL: SELECT * FROM products WHERE category = ? ORDER BY created_at DESC | Memory: 6.25 MB | Time: 1800.00 ms
+ Plan:
+...
+```
+
+#### Advanced Configuration
+
+```typescript
+import ForgeSQL, { slowQuerySchedulerTrigger } from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+// Monitor queries from the last 6 hours (for less frequent checks)
+export const sixHourSlowQueryTrigger = () =>
+  slowQuerySchedulerTrigger(forgeSQL, { hours: 6, timeout: 5000 });
+
+// Monitor queries from the last 24 hours (daily monitoring)
+export const dailySlowQueryTrigger = () =>
+  slowQuerySchedulerTrigger(forgeSQL, { hours: 24, timeout: 3000 });
+```
+
+#### How It Works
+
+1. **Scheduled Execution**: The trigger runs automatically on the configured interval (hourly recommended)
+2. **Query Analysis**: Queries TiDB's slow query log system table for queries executed within the specified time window
+3. **Performance Metrics**: Extracts and logs:
+   - SQL query text (sanitized for readability)
+   - Maximum memory usage (in MB)
+   - Query execution time (in ms)
+   - Detailed execution plan
+4. **Console Logging**: Results are logged to the Forge Developer Console via `console.warn()` for easy monitoring
+
+#### Best Practices
+
+- **Hourly Intervals**: Use `interval: hour` for timely detection of slow queries
+- **Default Time Window**: 1 hour is recommended for hourly schedules to avoid overlap
+- **Monitor Regularly**: Check console logs regularly to identify patterns in slow queries
+
+#### Benefits
+
+- **Proactive Monitoring**: Catch slow queries before they become critical issues
+- **Performance Trends**: Track query performance over time
+- **Optimization Insights**: Execution plans help identify optimization opportunities
+- **Zero Manual Intervention**: Fully automated monitoring with scheduled execution
+- **Production Safe**: Works silently in the background, only logs when slow queries are found
+
+> **💡 Tip**: The trigger queries up to 50 slow queries to prevent excessive logging. Transient timeouts are usually fine; repeated timeouts indicate the diagnostic query itself is slow and should be investigated.
 
 ### Available Analysis Tools
 
@@ -2138,213 +2426,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
 
@@ -2433,20 +2514,32 @@ const rawUsers = await forgeSQL.execute(
   [true]
 );
 
+// ⚠️ IMPORTANT: When using executeCacheable(), all table names must be wrapped with backticks (`)
 const cachedRawUsers = await forgeSQL.executeCacheable(
-  "SELECT * FROM users WHERE active = ?", 
+  "SELECT * FROM `users` WHERE active = ?", 
   [true], 
   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