forge-sql-orm 2.1.16 → 2.1.18

package/src/async/PrintQueryConsumer.ts

@@ -0,0 +1,114 @@
+import { AsyncEvent } from "@forge/events";
+import {
+  MetadataQueryOptions,
+  printDegradationQueries,
+  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 async function printDegradationQueriesConsumer(
+  forgeSQLORM: ForgeSqlOperation,
+  event: AsyncEvent,
+): Promise<void> {
+  const body: AsyncEventPrintQuery = event.body as AsyncEventPrintQuery;
+  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 printDegradationQueries(forgeSQLORM, body);
+}

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./utils/forgeDriver";
 export * from "./webtriggers";
 export * from "./lib/drizzle/extensions/additionalActions";
 export * from "./core/SystemTables";
+export * from "./async/PrintQueryConsumer";

package/src/utils/forgeDriverProxy.ts

@@ -1,7 +1,7 @@
 import { forgeDriver } from "./forgeDriver";
 import { injectSqlHints, SqlHints } from "./sqlHints";
 import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
-import { printQueriesWithPlan } from "./sqlUtils";
+import { handleErrorsWithPlan } from "./sqlUtils";
 
 /**
  * Error codes and constants for query analysis
@@ -57,22 +57,22 @@ export function createForgeDriverProxy(
         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: "OOM" | "TIMEOUT" = "TIMEOUT";
         if (isTimeoutError) {
           // eslint-disable-next-line no-console
           console.error(` TIMEOUT detected - Query exceeded time limit`);
         } 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 printQueriesWithPlan(forgeSqlOperation, queryDuration);
+        await handleErrorsWithPlan(forgeSqlOperation, queryDuration, errorType);
       }
 
       // Log SQL error details if requested

package/src/utils/metadataContextUtils.ts

@@ -2,12 +2,15 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { ForgeSQLMetadata } from "./forgeDriver";
 import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
 import { ExplainAnalyzeRow } from "../core/SystemTables";
-import { printQueriesWithPlan } from "./sqlUtils";
+import { printQueriesWithPlan, withTimeout } from "./sqlUtils";
 import { Parser } from "node-sql-parser";
+import { PushResult, Queue } from "@forge/events";
+import { AsyncEventPrintQuery } from "../async/PrintQueryConsumer";
 
+const TIMEOUT_ASYNC_EVENT_SENT = 1200;
 const DEFAULT_WINDOW_SIZE = 15 * 1000;
 
-type Statistic = { query: string; params: unknown[]; metadata: ForgeSQLMetadata };
+export type Statistic = { query: string; params: unknown[]; metadata: ForgeSQLMetadata };
 
 export type QueryPlanMode = "TopSlowest" | "SummaryTable";
 
@@ -17,6 +20,7 @@ export type MetadataQueryOptions = {
   topQueries?: number;
   showSlowestPlans?: boolean;
   normalizeQuery?: boolean;
+  asyncQueueName?: string;
 };
 
 export type MetadataQueryContext = {
@@ -42,6 +46,7 @@ function createDefaultOptions(): Required<MetadataQueryOptions> {
     summaryTableWindowTime: DEFAULT_WINDOW_SIZE,
     showSlowestPlans: true,
     normalizeQuery: true,
+    asyncQueueName: "",
   };
 }
 
@@ -58,6 +63,7 @@ function mergeOptionsWithDefaults(options?: MetadataQueryOptions): Required<Meta
     summaryTableWindowTime: options?.summaryTableWindowTime ?? defaults.summaryTableWindowTime,
     showSlowestPlans: options?.showSlowestPlans ?? defaults.showSlowestPlans,
     normalizeQuery: options?.normalizeQuery ?? defaults.normalizeQuery,
+    asyncQueueName: options?.asyncQueueName ?? defaults.asyncQueueName,
   };
 }
 
@@ -196,16 +202,21 @@ function formatExplainPlan(planRows: ExplainAnalyzeRow[]): string {
 
 /**
  * Prints query plans using summary tables if mode is SummaryTable and within time window.
- * @param context - The metadata query context
- * @param options - The merged options with defaults
- * @returns Promise that resolves when plans are printed
+ *
+ * Attempts to use CLUSTER_STATEMENTS_SUMMARY table for query analysis if:
+ * - Mode is set to "SummaryTable"
+ * - Time since query execution start is within the configured window
+ *
+ * @param context - The async event payload containing query statistics and options
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @returns Promise that resolves to true if summary tables were used, false otherwise
  */
 async function printPlansUsingSummaryTables(
-  context: MetadataQueryContext,
-  options: Required<MetadataQueryOptions>,
+  context: AsyncEventPrintQuery,
+  forgeSQLORM: ForgeSqlOperation,
 ): Promise<boolean> {
   const timeDiff = Date.now() - context.beginTime.getTime();
-
+  const options = context.options;
   if (options.mode !== "SummaryTable") {
     return false;
   }
@@ -213,7 +224,7 @@ async function printPlansUsingSummaryTables(
   if (timeDiff <= options.summaryTableWindowTime) {
     await new Promise((resolve) => setTimeout(resolve, 200));
     const summaryTableDiffMs = Date.now() - context.beginTime.getTime();
-    await printQueriesWithPlan(context.forgeSQLORM, summaryTableDiffMs);
+    await printQueriesWithPlan(forgeSQLORM, summaryTableDiffMs);
     return true;
   }
   // eslint-disable-next-line no-console
@@ -222,15 +233,20 @@ async function printPlansUsingSummaryTables(
 }
 
 /**
- * Prints query plans for the top slowest queries.
- * @param context - The metadata query context
- * @param options - The merged options with defaults
- * @returns Promise that resolves when plans are printed
+ * Prints query plans for the top slowest queries from the statistics.
+ *
+ * Sorts queries by execution time and prints the top N queries (based on topQueries option).
+ * For each query, it can optionally print the execution plan using EXPLAIN ANALYZE.
+ *
+ * @param context - The async event payload containing query statistics and options
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @returns Promise that resolves when all query plans are printed
  */
 async function printTopQueriesPlans(
-  context: MetadataQueryContext,
-  options: Required<MetadataQueryOptions>,
+  context: AsyncEventPrintQuery,
+  forgeSQLORM: ForgeSqlOperation,
 ): Promise<void> {
+  const options = context.options;
   const topQueries = context.statistics
     .toSorted((a, b) => b.metadata.dbExecutionTime - a.metadata.dbExecutionTime)
     .slice(0, options.topQueries);
@@ -240,7 +256,7 @@ async function printTopQueriesPlans(
       ? normalizeSqlForLogging(query.query)
       : query.query;
     if (options.showSlowestPlans) {
-      const explainAnalyzeRows = await context.forgeSQLORM
+      const explainAnalyzeRows = await forgeSQLORM
         .analyze()
         .explainAnalyzeRaw(query.query, query.params);
       const formattedPlan = formatExplainPlan(explainAnalyzeRows);
@@ -257,9 +273,33 @@ async function printTopQueriesPlans(
 
 /**
  * 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 async function saveMetaDataToContext(
   stringQuery: string,
@@ -285,15 +325,41 @@ export async function saveMetaDataToContext(
   // Set up printQueriesWithPlan function
   context.printQueriesWithPlan = async () => {
     const options = mergeOptionsWithDefaults(context.options);
-
-    // Try to use summary tables first if enabled
-    const usedSummaryTables = await printPlansUsingSummaryTables(context, options);
-    if (usedSummaryTables) {
-      return;
+    const param: AsyncEventPrintQuery = {
+      statistics: context.statistics,
+      totalDbExecutionTime: context.totalDbExecutionTime,
+      totalResponseSize: context.totalResponseSize,
+      beginTime: context.beginTime,
+      options,
+    };
+    if (options.asyncQueueName) {
+      const queue = new Queue({ key: options.asyncQueueName });
+      try {
+        const eventInfo = await withTimeout<PushResult>(
+          queue.push({
+            body: param,
+            concurrency: {
+              key: "orm_" + options.asyncQueueName,
+              limit: 2,
+            },
+          }),
+          `Event was not sent within ${TIMEOUT_ASYNC_EVENT_SENT}ms`,
+          TIMEOUT_ASYNC_EVENT_SENT,
+        );
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[Performance Analysis] Query degradation event queued for async processing | Job ID: ${eventInfo.jobId} | Total DB time: ${context.totalDbExecutionTime}ms | Queries: ${context.statistics.length} | Look for consumer log with jobId: ${eventInfo.jobId}`,
+        );
+        return;
+      } catch (e: any) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          "Async printing failed — falling back to synchronous execution: " + e.message,
+          e,
+        );
+      }
     }
-
-    // Fall back to printing top queries plans
-    await printTopQueriesPlans(context, options);
+    await printDegradationQueries(context.forgeSQLORM, param);
   };
 
   // Update aggregated metrics
@@ -303,6 +369,34 @@ export async function saveMetaDataToContext(
   }
 }
 
+/**
+ * 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 async function printDegradationQueries(
+  forgeSQLORM: ForgeSqlOperation,
+  params: AsyncEventPrintQuery,
+): Promise<void> {
+  // Try to use summary tables first if enabled
+  const usedSummaryTables = await printPlansUsingSummaryTables(params, forgeSQLORM);
+  if (usedSummaryTables) {
+    return;
+  }
+
+  // Fall back to printing top queries plans
+  await printTopQueriesPlans(params, forgeSQLORM);
+}
+
 /**
  * Gets the latest metadata from the current context.
  * @returns The current metadata context or undefined if not in a context

package/src/utils/sqlUtils.ts

@@ -2,6 +2,7 @@ import {
   and,
   AnyColumn,
   Column,
+  desc,
   gte,
   ilike,
   isNotNull,
@@ -711,6 +712,39 @@ export function nextVal(sequenceName: string): number {
   return sql.raw(`NEXTVAL(${sequenceName})`) as unknown as number;
 }
 
+/**
+ * Helper function to build base query for CLUSTER_STATEMENTS_SUMMARY table
+ */
+function buildClusterStatementsSummaryQuery(forgeSQLORM: ForgeSqlOperation, timeDiffMs: number) {
+  const statementsTable = clusterStatementsSummary;
+  return forgeSQLORM
+    .getDrizzleQueryBuilder()
+    .select({
+      digestText: withTidbHint(statementsTable.digestText),
+      avgLatency: statementsTable.avgLatency,
+      avgMem: statementsTable.avgMem,
+      execCount: statementsTable.execCount,
+      plan: statementsTable.plan,
+      stmtType: statementsTable.stmtType,
+    })
+    .from(statementsTable)
+    .where(
+      and(
+        isNotNull(statementsTable.digest),
+        not(ilike(statementsTable.digestText, "%information_schema%")),
+        notInArray(statementsTable.stmtType, ["Use", "Set", "Show", "Commit", "Rollback", "Begin"]),
+        gte(
+          statementsTable.lastSeen,
+          sql`DATE_SUB
+                        (NOW(), INTERVAL
+                        ${timeDiffMs * 1000}
+                        MICROSECOND
+                        )`,
+        ),
+      ),
+    );
+}
+
 /**
  * Analyzes and prints query performance data from CLUSTER_STATEMENTS_SUMMARY table.
  *
@@ -724,7 +758,7 @@ export function nextVal(sequenceName: string): number {
  *
  * @param forgeSQLORM - The ForgeSQL operation instance for database access
  * @param timeDiffMs - Time window in milliseconds to look back for queries (e.g., 1500 for last 1.5 seconds)
- * @param timeout - Optional timeout in milliseconds for the query execution (defaults to 1500ms)
+ * @param timeout - Optional timeout in milliseconds for the query execution (defaults to 3000ms)
  *
  * @example
  * ```typescript
@@ -743,42 +777,9 @@ export async function printQueriesWithPlan(
   timeout?: number,
 ) {
   try {
-    const statementsTable = clusterStatementsSummary;
     const timeoutMs = timeout ?? 3000;
     const results = await withTimeout(
-      forgeSQLORM
-        .getDrizzleQueryBuilder()
-        .select({
-          digestText: withTidbHint(statementsTable.digestText),
-          avgLatency: statementsTable.avgLatency,
-          avgMem: statementsTable.avgMem,
-          execCount: statementsTable.execCount,
-          plan: statementsTable.plan,
-          stmtType: statementsTable.stmtType,
-        })
-        .from(statementsTable)
-        .where(
-          and(
-            isNotNull(statementsTable.digest),
-            not(ilike(statementsTable.digestText, "%information_schema%")),
-            notInArray(statementsTable.stmtType, [
-              "Use",
-              "Set",
-              "Show",
-              "Commit",
-              "Rollback",
-              "Begin",
-            ]),
-            gte(
-              statementsTable.lastSeen,
-              sql`DATE_SUB
-                            (NOW(), INTERVAL
-                            ${timeDiffMs * 1000}
-                            MICROSECOND
-                            )`,
-            ),
-          ),
-        ),
+      buildClusterStatementsSummaryQuery(forgeSQLORM, timeDiffMs),
       `Timeout ${timeoutMs}ms in printQueriesWithPlan - transient timeouts are usually fine; repeated timeouts mean this diagnostic query is consistently slow and should be investigated`,
       timeoutMs + 200,
     );
@@ -803,6 +804,44 @@ export async function printQueriesWithPlan(
   }
 }
 
+export async function handleErrorsWithPlan(
+  forgeSQLORM: ForgeSqlOperation,
+  timeDiffMs: number,
+  type: "OOM" | "TIMEOUT",
+) {
+  try {
+    const statementsTable = clusterStatementsSummary;
+    const timeoutMs = 3000;
+    const baseQuery = buildClusterStatementsSummaryQuery(forgeSQLORM, timeDiffMs);
+    const orderColumn = type === "OOM" ? statementsTable.avgMem : statementsTable.avgLatency;
+    const query = baseQuery.orderBy(desc(orderColumn)).limit(formatLimitOffset(1));
+
+    const results = await withTimeout(
+      query,
+      `Timeout ${timeoutMs}ms in handleErrorsWithPlan - transient timeouts are usually fine; repeated timeouts mean this diagnostic query is consistently slow and should be investigated`,
+      timeoutMs + 200,
+    );
+
+    for (const result of results) {
+      // Average execution time (convert from nanoseconds to milliseconds)
+      const avgTimeMs = Number(result.avgLatency) / 1_000_000;
+      const avgMemMB = Number(result.avgMem) / 1_000_000;
+
+      // 1. Query info: SQL, memory, time, executions
+      // eslint-disable-next-line no-console
+      console.warn(
+        `SQL: ${result.digestText} | Memory: ${avgMemMB.toFixed(2)} MB | Time: ${avgTimeMs.toFixed(2)} ms | stmtType: ${result.stmtType} | Executions: ${result.execCount}\n Plan:${result.plan}`,
+      );
+    }
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.debug(
+      `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}. Try again after some time`,
+      error,
+    );
+  }
+}
+
 const SESSION_ALIAS_NAME_ORM = "orm";
 
 /**

package/src/webtriggers/fetchSchemaWebTrigger.ts

@@ -60,9 +60,9 @@ async function generateCreateTableStatements(tables: string[]): Promise<string[]
 
   for (const table of tables) {
     const createTableResult = await sql.executeDDL<CreateTableRow>(`SHOW CREATE TABLE "${table}"`);
-
     const createTableStatements = createTableResult.rows
       .filter((row) => !isSystemTable(row.Table))
+      .filter((row) => Boolean(row["Create Table"]))
       .map((row) => formatCreateTableStatement(row["Create Table"]));
 
     statements.push(...createTableStatements);