forge-sql-orm 2.1.16 → 2.1.17

package/README.md

@@ -23,7 +23,7 @@
 - ✅ **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**: Query execution metrics and analysis capabilities with automatic error analysis for timeout and OOM errors, plus scheduled slow query monitoring with execution plans
+- ✅ **Performance Monitoring**: Query execution metrics and analysis capabilities with automatic error analysis for timeout and OOM errors, scheduled slow query monitoring with execution plans, and async query degradation analysis for non-blocking performance monitoring
 - ✅ **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
@@ -2806,6 +2806,7 @@ All options are **optional**. If not specified, default values are used. You can
 | `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                        |
+| `asyncQueueName`         | `string`                         | `""`           | Queue name for async processing. If provided, query analysis will be queued for background processing instead of running synchronously. Requires consumer configuration in `manifest.yml`     |
 
 **Examples:**
 
@@ -2891,6 +2892,194 @@ resolver.define("fetch", async (req: Request) => {
 
 > **💡 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.
 
+### Async Query Degradation Analysis
+
+Forge-SQL-ORM supports asynchronous processing of query degradation analysis, allowing you to offload performance analysis to a background queue. This is particularly useful for production environments where you want to avoid blocking resolver responses while still capturing detailed performance metrics.
+
+#### Key Features
+
+- **Non-Blocking Analysis**: Query analysis runs asynchronously without blocking resolver responses
+- **Automatic Fallback**: Falls back to synchronous execution if async queue fails
+- **Log Correlation**: Job IDs help correlate resolver logs with consumer logs
+- **Queue-Based Processing**: Uses Forge's event queue system for reliable processing
+- **Configurable Timeout**: Customizable timeout for event queuing (default: 1200ms)
+
+#### Basic Setup
+
+**1. Configure consumer in `manifest.yml`:**
+
+```yaml
+modules:
+  consumer:
+    - key: print-degradation-queries
+      queue: degradationQueue
+      function: handlerAsyncDegradation
+
+  function:
+    - key: handlerAsyncDegradation
+      handler: index.handlerAsyncDegradation
+```
+
+**2. Create the handler function:**
+
+```typescript
+import { AsyncEvent } from "@forge/events";
+import { printDegradationQueriesConsumer } from "forge-sql-orm";
+import { FORGE_SQL_ORM } from "./utils/forgeSqlOrmUtils";
+
+export const handlerAsyncDegradation = (event: AsyncEvent) => {
+  return printDegradationQueriesConsumer(FORGE_SQL_ORM, event);
+};
+```
+
+**3. Enable async processing in resolver:**
+
+```typescript
+resolver.define("fetch", async (req: Request) => {
+  return await FORGE_SQL_ORM.executeWithMetadata(
+    async () => {
+      // ... your queries ...
+      return await SQL_QUERY;
+    },
+    async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+      if (totalDbExecutionTime > 800) {
+        await printQueries(); // Will queue for async processing
+      }
+    },
+    { asyncQueueName: "degradationQueue" }, // Enable async processing
+  );
+});
+```
+
+#### Configuration Options
+
+The `asyncQueueName` option enables async processing:
+
+| Option           | Type     | Default | Description                                                                                                                                                |
+| ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asyncQueueName` | `string` | `""`    | Queue name for async processing. If provided, query analysis will be queued instead of running synchronously. If empty or not provided, runs synchronously |
+
+#### How It Works
+
+1. **Resolver Execution**: When `printQueriesWithPlan()` is called with `asyncQueueName` configured:
+   - Creates an event payload with query statistics and metadata
+   - Sends event to the specified queue with a timeout (default: 1200ms)
+   - Logs a warning message with Job ID for correlation
+   - Returns immediately without waiting for analysis
+
+2. **Async Processing**: The consumer function (`handlerAsyncDegradation`):
+   - Receives the event from the queue
+   - Logs processing start with Job ID
+   - Executes query analysis (TopSlowest or SummaryTable mode)
+   - Prints execution plans and performance metrics
+
+3. **Fallback Behavior**: If queue push fails or times out:
+   - Falls back to synchronous execution automatically
+   - Logs a warning message
+   - Analysis still completes, just synchronously
+
+#### Log Correlation
+
+Both resolver and consumer logs include Job IDs to help you correlate related events:
+
+**Resolver log (when event is queued):**
+
+```
+WARN [Performance Analysis] Query degradation event queued for async processing | Job ID: abc-123 | Total DB time: 3531ms | Queries: 3 | Look for consumer log with jobId: abc-123
+```
+
+**Consumer log (when event is processed):**
+
+```
+WARN [Performance Analysis] Processing query degradation event | Job ID: abc-123 | Total DB time: 3531ms | Queries: 3 | Started: 2025-12-15T18:12:34.251Z
+WARN SQL: SELECT ... | Time: 3514 ms
+ Plan:
+ Projection_7 | task:root | ...
+```
+
+**To find all related logs:**
+
+- Search logs for: `"Job ID: abc-123"`
+- This will show both the queuing event and the processing event
+
+#### Example: Complete Setup
+
+**manifest.yml:**
+
+```yaml
+modules:
+  consumer:
+    - key: print-degradation-queries
+      queue: degradationQueue
+      function: handlerAsyncDegradation
+
+  function:
+    - key: handlerAsyncDegradation
+      handler: index.handlerAsyncDegradation
+```
+
+**index.ts:**
+
+```typescript
+import { AsyncEvent } from "@forge/events";
+import { printDegradationQueriesConsumer } from "forge-sql-orm";
+import { FORGE_SQL_ORM } from "./utils/forgeSqlOrmUtils";
+
+// Consumer handler
+export const handlerAsyncDegradation = (event: AsyncEvent) => {
+  return printDegradationQueriesConsumer(FORGE_SQL_ORM, event);
+};
+
+// Resolver with async analysis
+resolver.define("fetch", async (req: Request) => {
+  return await FORGE_SQL_ORM.executeWithMetadata(
+    async () => {
+      const users = await FORGE_SQL_ORM.selectFrom(demoUsers);
+      const orders = await FORGE_SQL_ORM.selectFrom(demoOrders);
+      return { users, orders };
+    },
+    async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+      const threshold = 800; // ms baseline
+
+      if (totalDbExecutionTime > threshold) {
+        console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
+        await printQueries(); // Queued for async processing
+      }
+    },
+    {
+      asyncQueueName: "degradationQueue", // Enable async processing
+      mode: "TopSlowest",
+      topQueries: 1,
+    },
+  );
+});
+```
+
+#### Benefits
+
+- **Non-Blocking**: Resolver responses are not delayed by query analysis
+- **Production Ready**: Suitable for production environments where performance is critical
+- **Reliable**: Automatic fallback ensures analysis always completes
+- **Traceable**: Job IDs enable easy log correlation
+- **Scalable**: Queue-based processing handles high load scenarios
+
+#### When to Use Async Processing
+
+**Use async processing when:**
+
+- You're in a production environment
+- Resolver response time is critical
+- You want to avoid blocking user requests
+- You need detailed analysis but can process it later
+
+**Use synchronous processing when:**
+
+- You're in development/debugging
+- You need immediate analysis results
+- You want simpler setup (no queue configuration)
+
+> **💡 Tip**: The async queue name must match the queue name configured in your `manifest.yml` consumer section. If the queue doesn't exist or the event fails to send, the system automatically falls back to synchronous execution.
+
 ### 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.

package/dist/async/PrintQueryConsumer.d.ts

@@ -0,0 +1,98 @@
+import { AsyncEvent } from "@forge/events";
+import { MetadataQueryOptions, Statistic } from "../utils/metadataContextUtils";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+/**
+ * Event payload for async query degradation analysis.
+ * Contains query performance statistics and metadata for analysis.
+ */
+export type AsyncEventPrintQuery = {
+    /** Total database execution time across all queries in milliseconds */
+    totalDbExecutionTime: number;
+    /** Total response size across all queries in bytes */
+    totalResponseSize: number;
+    /** Timestamp when the query execution started */
+    beginTime: Date;
+    /** Query analysis options with all fields set to defaults if not provided */
+    options: Required<MetadataQueryOptions>;
+    /** Array of query statistics including SQL, parameters, and execution metadata */
+    statistics: Statistic[];
+};
+/**
+ * Consumer function for processing async query degradation events.
+ *
+ * This function is called by the Forge event system when a query degradation event
+ * is received from the queue. It processes the event and prints query performance
+ * analysis including execution plans for slow queries.
+ *
+ * The function logs a warning message with job ID, total DB time, query count, and
+ * start time to help correlate with the original resolver/service logs.
+ *
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param event - The async event containing query degradation data
+ * @returns Promise that resolves when query analysis is complete
+ *
+ * @example
+ * ```yaml
+ * # manifest.yml - Configure consumer for async query degradation analysis
+ * modules:
+ *   consumer:
+ *     - key: print-degradation-queries
+ *       queue: degradationQueue
+ *       function: handlerAsyncDegradation
+ *   function:
+ *     - key: handlerAsyncDegradation
+ *       handler: index.handlerAsyncDegradation
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // index.ts - Handler function that processes async events
+ * import { AsyncEvent } from "@forge/events";
+ * import { printDegradationQueriesConsumer } from "forge-sql-orm";
+ * import { FORGE_SQL_ORM } from "./utils/forgeSqlOrmUtils";
+ *
+ * export const handlerAsyncDegradation = (event: AsyncEvent) => {
+ *   return printDegradationQueriesConsumer(FORGE_SQL_ORM, event);
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using async queue in resolver - Enable async processing
+ * resolver.define("fetch", async (req: Request) => {
+ *   return await FORGE_SQL_ORM.executeWithMetadata(
+ *     async () => {
+ *       // ... your queries ...
+ *       return await SQL_QUERY;
+ *     },
+ *     async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+ *       if (totalDbExecutionTime > 800) {
+ *         await printQueries(); // Will queue for async processing
+ *       }
+ *     },
+ *     { asyncQueueName: "degradationQueue" } // Enable async processing
+ *   );
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Log correlation - How to find related logs
+ * //
+ * // 1. In resolver/service log, you'll see:
+ * //    [Performance Analysis] Query degradation event queued for async processing | Job ID: abc-123 | ...
+ * //
+ * // 2. In consumer log (handlerAsyncDegradation), search for the same Job ID:
+ * //    [Performance Analysis] Processing query degradation event | Job ID: abc-123 | ...
+ * //
+ * // 3. To find all related logs, search logs for: "Job ID: abc-123"
+ * //    This will show both the queuing event and the processing event
+ * //
+ * // Example log flow:
+ * // WARN resolver: [Performance Analysis] Query degradation event queued... | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: [Performance Analysis] Processing query degradation event | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: SQL: SELECT ... | Time: 3514 ms
+ * ```
+ */
+export declare function printDegradationQueriesConsumer(forgeSQLORM: ForgeSqlOperation, event: AsyncEvent): Promise<void>;
+//# sourceMappingURL=PrintQueryConsumer.d.ts.map

package/dist/async/PrintQueryConsumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrintQueryConsumer.d.ts","sourceRoot":"","sources":["../../src/async/PrintQueryConsumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EACL,oBAAoB,EAEpB,SAAS,EACV,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,SAAS,EAAE,IAAI,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IACxC,kFAAkF;IAClF,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAsB,+BAA+B,CACnD,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/async/PrintQueryConsumer.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printDegradationQueriesConsumer = printDegradationQueriesConsumer;
+const metadataContextUtils_1 = require("../utils/metadataContextUtils");
+/**
+ * Consumer function for processing async query degradation events.
+ *
+ * This function is called by the Forge event system when a query degradation event
+ * is received from the queue. It processes the event and prints query performance
+ * analysis including execution plans for slow queries.
+ *
+ * The function logs a warning message with job ID, total DB time, query count, and
+ * start time to help correlate with the original resolver/service logs.
+ *
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param event - The async event containing query degradation data
+ * @returns Promise that resolves when query analysis is complete
+ *
+ * @example
+ * ```yaml
+ * # manifest.yml - Configure consumer for async query degradation analysis
+ * modules:
+ *   consumer:
+ *     - key: print-degradation-queries
+ *       queue: degradationQueue
+ *       function: handlerAsyncDegradation
+ *   function:
+ *     - key: handlerAsyncDegradation
+ *       handler: index.handlerAsyncDegradation
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // index.ts - Handler function that processes async events
+ * import { AsyncEvent } from "@forge/events";
+ * import { printDegradationQueriesConsumer } from "forge-sql-orm";
+ * import { FORGE_SQL_ORM } from "./utils/forgeSqlOrmUtils";
+ *
+ * export const handlerAsyncDegradation = (event: AsyncEvent) => {
+ *   return printDegradationQueriesConsumer(FORGE_SQL_ORM, event);
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using async queue in resolver - Enable async processing
+ * resolver.define("fetch", async (req: Request) => {
+ *   return await FORGE_SQL_ORM.executeWithMetadata(
+ *     async () => {
+ *       // ... your queries ...
+ *       return await SQL_QUERY;
+ *     },
+ *     async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+ *       if (totalDbExecutionTime > 800) {
+ *         await printQueries(); // Will queue for async processing
+ *       }
+ *     },
+ *     { asyncQueueName: "degradationQueue" } // Enable async processing
+ *   );
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Log correlation - How to find related logs
+ * //
+ * // 1. In resolver/service log, you'll see:
+ * //    [Performance Analysis] Query degradation event queued for async processing | Job ID: abc-123 | ...
+ * //
+ * // 2. In consumer log (handlerAsyncDegradation), search for the same Job ID:
+ * //    [Performance Analysis] Processing query degradation event | Job ID: abc-123 | ...
+ * //
+ * // 3. To find all related logs, search logs for: "Job ID: abc-123"
+ * //    This will show both the queuing event and the processing event
+ * //
+ * // Example log flow:
+ * // WARN resolver: [Performance Analysis] Query degradation event queued... | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: [Performance Analysis] Processing query degradation event | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: SQL: SELECT ... | Time: 3514 ms
+ * ```
+ */
+async function printDegradationQueriesConsumer(forgeSQLORM, event) {
+    const body = event.body;
+    body.beginTime = new Date(body.beginTime);
+    // eslint-disable-next-line no-console
+    console.warn(`[Performance Analysis] Processing query degradation event | Job ID: ${event.jobId} | Total DB time: ${body.totalDbExecutionTime}ms | Queries: ${body.statistics.length} | Started: ${body.beginTime.toISOString()}`);
+    await (0, metadataContextUtils_1.printDegradationQueries)(forgeSQLORM, body);
+}
+//# sourceMappingURL=PrintQueryConsumer.js.map

package/dist/async/PrintQueryConsumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrintQueryConsumer.js","sourceRoot":"","sources":["../../src/async/PrintQueryConsumer.ts"],"names":[],"mappings":";;AAsGA,0EAWC;AAhHD,wEAIuC;AAoBvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACI,KAAK,UAAU,+BAA+B,CACnD,WAA8B,EAC9B,KAAiB;IAEjB,MAAM,IAAI,GAAyB,KAAK,CAAC,IAA4B,CAAC;IACtE,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,sCAAsC;IACtC,OAAO,CAAC,IAAI,CACV,uEAAuE,KAAK,CAAC,KAAK,qBAAqB,IAAI,CAAC,oBAAoB,iBAAiB,IAAI,CAAC,UAAU,CAAC,MAAM,eAAe,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CACrN,CAAC;IACF,MAAM,IAAA,8CAAuB,EAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC"}

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from "./utils/forgeDriver";
 export * from "./webtriggers";
 export * from "./lib/drizzle/extensions/additionalActions";
 export * from "./core/SystemTables";
+export * from "./async/PrintQueryConsumer";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -28,4 +28,5 @@ __exportStar(require("./utils/forgeDriver"), exports);
 __exportStar(require("./webtriggers"), exports);
 __exportStar(require("./lib/drizzle/extensions/additionalActions"), exports);
 __exportStar(require("./core/SystemTables"), exports);
+__exportStar(require("./async/PrintQueryConsumer"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,kDAA6C;AAApC,uHAAA,OAAO,OAAA;AAEhB,8DAA4C;AAC5C,gEAA8C;AAC9C,kEAAgD;AAChD,mDAAiC;AACjC,sDAAoC;AACpC,gDAA8B;AAC9B,6EAA2D;AAC3D,sDAAoC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,kDAA6C;AAApC,uHAAA,OAAO,OAAA;AAEhB,8DAA4C;AAC5C,gEAA8C;AAC9C,kEAAgD;AAChD,mDAAiC;AACjC,sDAAoC;AACpC,gDAA8B;AAC9B,6EAA2D;AAC3D,sDAAoC;AACpC,6DAA2C"}

package/dist/utils/forgeDriverProxy.js

@@ -40,6 +40,11 @@ function createForgeDriverProxy(forgeSqlOperation, options, logRawSqlQuery) {
             const isTimeoutError = error.code === QUERY_ERROR_CODES.TIMEOUT;
             const isOutOfMemoryError = error?.context?.debug?.errno === QUERY_ERROR_CODES.OUT_OF_MEMORY_ERRNO;
             if (isTimeoutError || isOutOfMemoryError) {
+                // Wait for CLUSTER_STATEMENTS_SUMMARY to be populated with our failed query data
+                await new Promise((resolve) => setTimeout(resolve, STATEMENTS_SUMMARY_DELAY_MS));
+                const queryEndTime = Date.now();
+                const queryDuration = queryEndTime - queryStartTime;
+                let errorType = "TIMEOUT";
                 if (isTimeoutError) {
                     // eslint-disable-next-line no-console
                     console.error(` TIMEOUT detected - Query exceeded time limit`);
@@ -47,13 +52,10 @@ function createForgeDriverProxy(forgeSqlOperation, options, logRawSqlQuery) {
                 else {
                     // eslint-disable-next-line no-console
                     console.error(`OUT OF MEMORY detected - Query exceeded memory limit`);
+                    errorType = "OOM";
                 }
-                // Wait for CLUSTER_STATEMENTS_SUMMARY to be populated with our failed query data
-                await new Promise((resolve) => setTimeout(resolve, STATEMENTS_SUMMARY_DELAY_MS));
-                const queryEndTime = Date.now();
-                const queryDuration = queryEndTime - queryStartTime;
                 // Analyze the failed query using CLUSTER_STATEMENTS_SUMMARY
-                await (0, sqlUtils_1.printQueriesWithPlan)(forgeSqlOperation, queryDuration);
+                await (0, sqlUtils_1.handleErrorsWithPlan)(forgeSqlOperation, queryDuration, errorType);
             }
             // Log SQL error details if requested
             if (logRawSqlQuery) {

package/dist/utils/forgeDriverProxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"forgeDriverProxy.js","sourceRoot":"","sources":["../../src/utils/forgeDriverProxy.ts"],"names":[],"mappings":";;AAyBA,wDA8DC;AAvFD,+CAA4C;AAC5C,yCAAsD;AAEtD,yCAAkD;AAElD;;GAEG;AACH,MAAM,iBAAiB,GAAG;IACxB,OAAO,EAAE,mBAAmB;IAC5B,mBAAmB,EAAE,IAAI;CACjB,CAAC;AAEX;;GAEG;AACH,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,iBAAoC,EACpC,OAAkB,EAClB,cAAwB;IAExB,OAAO,KAAK,EACV,KAAa,EACb,MAAa,EACb,MAAyB,EAKxB,EAAE;QACH,kCAAkC;QAClC,MAAM,aAAa,GAAG,IAAA,yBAAc,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAErD,IAAI,OAAO,IAAI,cAAc,IAAI,aAAa,KAAK,KAAK,EAAE,CAAC;YACzD,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,uBAAuB,aAAa,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,IAAI,CAAC;YACH,wCAAwC;YACxC,OAAO,MAAM,IAAA,yBAAW,EAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,4EAA4E;YAC5E,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,KAAK,iBAAiB,CAAC,OAAO,CAAC;YAChE,MAAM,kBAAkB,GACtB,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,mBAAmB,CAAC;YAEzE,IAAI,cAAc,IAAI,kBAAkB,EAAE,CAAC;gBACzC,IAAI,cAAc,EAAE,CAAC;oBACnB,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACN,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;gBACxE,CAAC;gBAED,iFAAiF;gBACjF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC;gBAEjF,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAChC,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;gBAEpD,4DAA4D;gBAC5D,MAAM,IAAA,+BAAoB,EAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;YAC/D,CAAC;YAED,qCAAqC;YACrC,IAAI,cAAc,EAAE,CAAC;gBACnB,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACtE,CAAC;YAED,8BAA8B;YAC9B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"forgeDriverProxy.js","sourceRoot":"","sources":["../../src/utils/forgeDriverProxy.ts"],"names":[],"mappings":";;AAyBA,wDA8DC;AAvFD,+CAA4C;AAC5C,yCAAsD;AAEtD,yCAAkD;AAElD;;GAEG;AACH,MAAM,iBAAiB,GAAG;IACxB,OAAO,EAAE,mBAAmB;IAC5B,mBAAmB,EAAE,IAAI;CACjB,CAAC;AAEX;;GAEG;AACH,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,iBAAoC,EACpC,OAAkB,EAClB,cAAwB;IAExB,OAAO,KAAK,EACV,KAAa,EACb,MAAa,EACb,MAAyB,EAKxB,EAAE;QACH,kCAAkC;QAClC,MAAM,aAAa,GAAG,IAAA,yBAAc,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAErD,IAAI,OAAO,IAAI,cAAc,IAAI,aAAa,KAAK,KAAK,EAAE,CAAC;YACzD,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,uBAAuB,aAAa,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,IAAI,CAAC;YACH,wCAAwC;YACxC,OAAO,MAAM,IAAA,yBAAW,EAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,4EAA4E;YAC5E,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,KAAK,iBAAiB,CAAC,OAAO,CAAC;YAChE,MAAM,kBAAkB,GACtB,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,mBAAmB,CAAC;YAEzE,IAAI,cAAc,IAAI,kBAAkB,EAAE,CAAC;gBACzC,iFAAiF;gBACjF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC;gBAEjF,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAChC,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;gBACpD,IAAI,SAAS,GAAsB,SAAS,CAAC;gBAC7C,IAAI,cAAc,EAAE,CAAC;oBACnB,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACN,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;oBACtE,SAAS,GAAG,KAAK,CAAC;gBACpB,CAAC;gBACD,4DAA4D;gBAC5D,MAAM,IAAA,+BAAoB,EAAC,iBAAiB,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;YAC1E,CAAC;YAED,qCAAqC;YACrC,IAAI,cAAc,EAAE,CAAC;gBACnB,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACtE,CAAC;YAED,8BAA8B;YAC9B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/metadataContextUtils.d.ts

@@ -1,7 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { ForgeSQLMetadata } from "./forgeDriver";
 import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
-type Statistic = {
+import { AsyncEventPrintQuery } from "../async/PrintQueryConsumer";
+export type Statistic = {
     query: string;
     params: unknown[];
     metadata: ForgeSQLMetadata;
@@ -13,6 +14,7 @@ export type MetadataQueryOptions = {
     topQueries?: number;
     showSlowestPlans?: boolean;
     normalizeQuery?: boolean;
+    asyncQueueName?: string;
 };
 export type MetadataQueryContext = {
     totalDbExecutionTime: number;
@@ -26,15 +28,53 @@ export type MetadataQueryContext = {
 export declare const metadataQueryContext: AsyncLocalStorage<MetadataQueryContext>;
 /**
  * Saves query metadata to the current context and sets up the printQueriesWithPlan function.
+ *
+ * This function accumulates query statistics in the async context. When printQueriesWithPlan
+ * is called, it can either:
+ * - Queue the analysis for async processing (if asyncQueueName is provided)
+ * - Execute the analysis synchronously (fallback or if asyncQueueName is not set)
+ *
+ * For async processing, the function sends an event to the specified queue with a timeout.
+ * If the event cannot be sent within the timeout, it falls back to synchronous execution.
+ *
  * @param stringQuery - The SQL query string
- * @param params - Query parameters
- * @param metadata - Query execution metadata
+ * @param params - Query parameters used in the query
+ * @param metadata - Query execution metadata including execution time and response size
+ *
+ * @example
+ * ```typescript
+ * await FORGE_SQL_ORM.executeWithMetadata(
+ *   async () => {
+ *     // ... queries ...
+ *   },
+ *   async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+ *     if (totalDbExecutionTime > threshold) {
+ *       await printQueries(); // Will use async queue if configured
+ *     }
+ *   },
+ *   { asyncQueueName: "degradationQueue" }
+ * );
+ * ```
  */
 export declare function saveMetaDataToContext(stringQuery: string, params: unknown[], metadata: ForgeSQLMetadata): Promise<void>;
+/**
+ * Prints query degradation analysis for the provided event payload.
+ *
+ * This function processes query degradation events (either from async queue or synchronous call).
+ * It first attempts to use summary tables (CLUSTER_STATEMENTS_SUMMARY) if configured and within
+ * the time window. Otherwise, it falls back to printing execution plans for the top slowest queries.
+ *
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param params - The async event payload containing query statistics, options, and metadata
+ * @returns Promise that resolves when query analysis is complete
+ *
+ * @see printPlansUsingSummaryTables - For summary table analysis
+ * @see printTopQueriesPlans - For top slowest queries analysis
+ */
+export declare function printDegradationQueries(forgeSQLORM: ForgeSqlOperation, params: AsyncEventPrintQuery): Promise<void>;
 /**
  * Gets the latest metadata from the current context.
  * @returns The current metadata context or undefined if not in a context
  */
 export declare function getLastestMetadata(): Promise<MetadataQueryContext | undefined>;
-export {};
 //# sourceMappingURL=metadataContextUtils.d.ts.map

package/dist/utils/metadataContextUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadataContextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAOjE,KAAK,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAElF,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAkOlF;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EAAE,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAEpF"}
+{"version":3,"file":"metadataContextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAKnE,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEzF,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AA8OlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EAAE,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CA8Df;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAEpF"}