forge-sql-orm 2.1.10 → 2.1.11

package/src/core/ForgeSQLQueryBuilder.ts

@@ -29,7 +29,6 @@ import {
   DeleteAndEvictCacheType,
   ExecuteQuery,
   ExecuteQueryCacheable,
-  ForgeSQLMetadata,
   InsertAndEvictCacheType,
   SelectAliasedCacheableType,
   SelectAliasedDistinctCacheableType,
@@ -544,32 +543,87 @@ export interface QueryBuilderForgeSql {
   executeWithLocalCacheContextAndReturnValue<T>(cacheContext: () => Promise<T>): Promise<T>;
 
   /**
-   * Executes a query and provides access to execution metadata.
+   * Executes a query and provides access to execution metadata with performance monitoring.
    * This method allows you to capture detailed information about query execution
-   * including database execution time, response size, and Forge SQL metadata.
+   * including database execution time, response size, and query analysis capabilities.
+   *
+   * The method aggregates metrics across all database operations within the query function,
+   * making it ideal for monitoring resolver performance and detecting performance issues.
    *
    * @template T - The return type of the query
-   * @param query - A function that returns a Promise with the query result
-   * @param onMetadata - Callback function that receives execution metadata
+   * @param query - A function that returns a Promise with the query result. Can contain multiple database operations.
+   * @param onMetadata - Callback function that receives aggregated execution metadata
+   * @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
+   * @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
+   * @param onMetadata.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
    * @returns Promise with the query result
+   *
    * @example
    * ```typescript
+   * // Basic usage with performance monitoring
    * const result = await forgeSQL.executeWithMetadata(
-   *   async () => await forgeSQL.select().from(users).where(eq(users.id, 1)),
-   *   (dbTime, responseSize, metadata) => {
-   *     console.log(`DB execution time: ${dbTime}ms`);
-   *     console.log(`Response size: ${responseSize} bytes`);
-   *     console.log('Forge metadata:', metadata);
+   *   async () => {
+   *     const users = await forgeSQL.selectFrom(usersTable);
+   *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
+   *     return { users, orders };
+   *   },
+   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *     const threshold = 500; // ms baseline for this resolver
+   *
+   *     if (totalDbExecutionTime > threshold * 1.5) {
+   *       console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
+   *       await printQueries(); // 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`);
    *   }
    * );
    * ```
+   *
+   * @example
+   * ```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, printQueries) => {
+   *         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 printQueries(); // Optionally log or capture diagnostics for further analysis
+   *         } else if (totalDbExecutionTime > threshold) {
+   *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
+   *         }
+   *
+   *         console.log(`DB response size: ${totalResponseSize} bytes`);
+   *       }
+   *     );
+   *   } catch (e) {
+   *     const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
+   *     console.error(error, e);
+   *     throw error;
+   *   }
+   * });
+   * ```
+   *
+   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
    */
   executeWithMetadata<T>(
     query: () => Promise<T>,
     onMetadata: (
       totalDbExecutionTime: number,
       totalResponseSize: number,
-      forgeMetadata: ForgeSQLMetadata,
+      printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
   ): Promise<T>;
   /**

package/src/core/SystemTables.ts

@@ -21,7 +21,7 @@ export const migrations = mysqlTable("__migrations", {
 
 const informationSchema = mysqlSchema("information_schema");
 
-export const slowQuery = informationSchema.table("SLOW_QUERY", {
+export const slowQuery = informationSchema.table("CLUSTER_SLOW_QUERY", {
   time: timestamp("Time", { fsp: 6, mode: "string" }).notNull(), // Timestamp when the slow query was recorded
 
   txnStartTs: bigint("Txn_start_ts", { mode: "bigint", unsigned: true }), // Transaction start timestamp (TSO)

package/src/utils/cacheUtils.ts

@@ -332,7 +332,9 @@ export async function getFromCache<T>(
   }
 
   try {
-    const cacheResult = await kvs.entity<CacheEntity>(options.cacheEntityName).get(key);
+    const cacheResult = (await kvs.entity<CacheEntity>(options.cacheEntityName).get(key)) as
+      | CacheEntity
+      | undefined;
 
     if (
       cacheResult &&

package/src/utils/forgeDriver.ts

@@ -1,6 +1,10 @@
 import { sql, UpdateQueryResponse } from "@forge/sql";
 import { saveMetaDataToContext } from "./metadataContextUtils";
 import { getOperationType } from "./requestTypeContextUtils";
+import {withTimeout} from "./sqlUtils";
+
+const timeoutMs =10000;
+const timeoutMessage = `Atlassian @forge/sql did not return a response within ${timeoutMs}ms (${timeoutMs / 1000} seconds), so the request is blocked. Possible causes: slow query, network issues, or exceeding Forge SQL limits.`;
 
 /**
  * Metadata structure for Forge SQL query results.
@@ -62,36 +66,6 @@ export function isUpdateQueryResponse(obj: unknown): obj is UpdateQueryResponse
   );
 }
 
-/**
- * Executes a promise with a timeout.
- *
- * @param promise - The promise to execute
- * @param timeoutMs - Timeout in milliseconds (default: 10000ms)
- * @returns Promise that resolves with the result or rejects on timeout
- * @throws {Error} When the operation times out
- */
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number = 10000): Promise<T> {
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    timeoutId = setTimeout(() => {
-      reject(
-        new Error(
-          `Atlassian @forge/sql did not return a response within ${timeoutMs}ms (${timeoutMs / 1000} seconds), so the request is blocked. Possible causes: slow query, network issues, or exceeding Forge SQL limits.`,
-        ),
-      );
-    }, timeoutMs);
-  });
-
-  try {
-    return await Promise.race([promise, timeoutPromise]);
-  } finally {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-  }
-}
-
 function inlineParams(sql: string, params: unknown[]): string {
   let i = 0;
   return sql.replace(/\?/g, () => {
@@ -148,7 +122,7 @@ async function processExecuteMethod(query: string, params: unknown[]): Promise<F
     sqlStatement.bindParams(...params);
   }
 
-  const result = await withTimeout(sqlStatement.execute());
+  const result = await withTimeout(sqlStatement.execute(), timeoutMessage, timeoutMs);
   await saveMetaDataToContext(result.metadata as ForgeSQLMetadata);
   if (!result.rows) {
     return { rows: [[]] };
@@ -171,7 +145,7 @@ async function processAllMethod(query: string, params: unknown[]): Promise<Forge
     await sqlStatement.bindParams(...params);
   }
 
-  const result = (await withTimeout(sqlStatement.execute())) as ForgeSQLResult;
+  const result = (await withTimeout(sqlStatement.execute(), timeoutMessage, timeoutMs)) as ForgeSQLResult;
   await saveMetaDataToContext(result.metadata);
 
   if (!result.rows) {
@@ -212,10 +186,9 @@ export const forgeDriver = async (
   method: QueryMethod,
 ): Promise<ForgeDriverResult> => {
   const operationType = await getOperationType();
-
   // Handle DDL operations
   if (operationType === "DDL") {
-    const result = await withTimeout(sql.executeDDL(inlineParams(query, params)));
+    const result = await withTimeout(sql.executeDDL(inlineParams(query, params)), timeoutMessage, timeoutMs);
     return await processDDLResult(method, result);
   }
 

package/src/utils/forgeDriverProxy.ts

@@ -1,11 +1,33 @@
 import { forgeDriver } from "./forgeDriver";
 import { injectSqlHints, SqlHints } from "./sqlHints";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+import { printQueriesWithPlan } from "./sqlUtils";
 
 /**
- * Creates a proxy for the forgeDriver that injects SQL hints
+ * Error codes and constants for query analysis
+ */
+const QUERY_ERROR_CODES = {
+  TIMEOUT: "SQL_QUERY_TIMEOUT",
+  OUT_OF_MEMORY_ERRNO: 8175,
+} as const;
+
+/**
+ * Delay to wait for CLUSTER_STATEMENTS_SUMMARY to be populated
+ */
+const STATEMENTS_SUMMARY_DELAY_MS = 200;
+
+/**
+ * Creates a proxy for the forgeDriver that injects SQL hints and handles query analysis
+ * @param forgeSqlOperation - The ForgeSQL operation instance
+ * @param options - SQL hints to inject
+ * @param logRawSqlQuery - Whether to log raw SQL queries
  * @returns A proxied version of the forgeDriver
  */
-export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: boolean) {
+export function createForgeDriverProxy(
+  forgeSqlOperation: ForgeSqlOperation,
+  options?: SqlHints,
+  logRawSqlQuery?: boolean,
+) {
   return async (
     query: string,
     params: any[],
@@ -20,16 +42,46 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
 
     if (options && logRawSqlQuery && modifiedQuery !== query) {
       // eslint-disable-next-line no-console
-      console.debug("injected Hints: " + modifiedQuery);
+      console.debug(`SQL Hints injected: ${modifiedQuery}`);
     }
+
+    const queryStartTime = Date.now();
+
     try {
-      // Call the original forgeDriver with the modified query
+      // Execute the query with injected hints
       return await forgeDriver(modifiedQuery, params, method);
-    } catch (error) {
+    } catch (error: any) {
+      // Check if this is a timeout or out-of-memory error that we want to analyze
+      const isTimeoutError = error.code === QUERY_ERROR_CODES.TIMEOUT;
+      const isOutOfMemoryError =
+        error?.context?.debug?.errno === QUERY_ERROR_CODES.OUT_OF_MEMORY_ERRNO;
+
+      if (isTimeoutError || isOutOfMemoryError) {
+        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`);
+        }
+
+        // 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);
+      }
+
+      // Log SQL error details if requested
       if (logRawSqlQuery) {
         // eslint-disable-next-line no-console
-        console.debug("SQL Error:", JSON.stringify(error));
+        console.debug(`SQL Error Details:`, JSON.stringify(error, null, 2));
       }
+
+      // Re-throw the original error
       throw error;
     }
   };

package/src/utils/metadataContextUtils.ts

@@ -1,19 +1,34 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { ForgeSQLMetadata } from "./forgeDriver";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+import { printQueriesWithPlan } from "./sqlUtils";
 
 export type MetadataQueryContext = {
   totalDbExecutionTime: number;
   totalResponseSize: number;
-  lastMetadata?: ForgeSQLMetadata;
+  beginTime: Date;
+  printQueriesWithPlan: () => Promise<void>;
+  forgeSQLORM: ForgeSqlOperation;
 };
 export const metadataQueryContext = new AsyncLocalStorage<MetadataQueryContext>();
 
-export async function saveMetaDataToContext(metadata: ForgeSQLMetadata): Promise<void> {
+export async function saveMetaDataToContext(metadata?: ForgeSQLMetadata): Promise<void> {
   const context = metadataQueryContext.getStore();
-  if (context && metadata) {
-    context.totalResponseSize += metadata.responseSize;
-    context.totalDbExecutionTime += metadata.dbExecutionTime;
-    context.lastMetadata = metadata;
+  if (context) {
+    context.printQueriesWithPlan = async () => {
+      if (process.env.NODE_ENV !== "test") {
+        await new Promise((r) => setTimeout(r, 200));
+      }
+       await printQueriesWithPlan(
+        context.forgeSQLORM,
+        Date.now() - context.beginTime.getTime(),
+      );
+    };
+    if (metadata) {
+      context.totalResponseSize += metadata.responseSize;
+      context.totalDbExecutionTime += metadata.dbExecutionTime;
+    }
+    // Log the results to console
   }
 }
 

package/src/utils/sqlUtils.ts

@@ -1,4 +1,18 @@
-import { AnyColumn, Column, isTable, SQL, sql, StringChunk } from "drizzle-orm";
+import {
+  and,
+  AnyColumn,
+  Column,
+  gte,
+    ilike,
+  isNotNull,
+  isTable,
+    ne,
+    not,
+  notInArray,
+  SQL,
+  sql,
+  StringChunk,
+} from "drizzle-orm";
 import { AnyMySqlTable, MySqlCustomColumn } from "drizzle-orm/mysql-core/index";
 import { DateTime } from "luxon";
 import { PrimaryKeyBuilder } from "drizzle-orm/mysql-core/primary-keys";
@@ -6,9 +20,16 @@ import { AnyIndexBuilder } from "drizzle-orm/mysql-core/indexes";
 import { CheckBuilder } from "drizzle-orm/mysql-core/checks";
 import { ForeignKeyBuilder } from "drizzle-orm/mysql-core/foreign-keys";
 import { UniqueConstraintBuilder } from "drizzle-orm/mysql-core/unique-constraint";
-import type { SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
+import {
+    SelectedFields
+} from "drizzle-orm/mysql-core/query-builders/select.types";
 import { MySqlTable } from "drizzle-orm/mysql-core";
 import { isSQLWrapper } from "drizzle-orm/sql/sql";
+import {clusterStatementsSummary, slowQuery} from "../core/SystemTables";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+import { ColumnDataType} from "drizzle-orm/column-builder";
+import {AnyMySqlColumn} from "drizzle-orm/mysql-core/columns/common";
+import type {ColumnBaseConfig} from "drizzle-orm/column";
 
 /**
  * Interface representing table metadata information
@@ -536,3 +557,209 @@ export function formatLimitOffset(limitOrOffset: number): number {
 export function nextVal(sequenceName: string): number {
   return sql.raw(`NEXTVAL(${sequenceName})`) as unknown as number;
 }
+
+/**
+ * Analyzes and prints query performance data from CLUSTER_STATEMENTS_SUMMARY table.
+ *
+ * This function queries the CLUSTER_STATEMENTS_SUMMARY table to find queries that were executed
+ * within the specified time window and prints detailed performance information including:
+ * - SQL query text
+ * - Memory usage (average and max in MB)
+ * - Execution time (average in ms)
+ * - Number of executions
+ * - Execution plan
+ *
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * // Analyze queries from the last 2 seconds
+ * await printQueriesWithPlan(forgeSQLORM, 2000);
+ *
+ * // Analyze queries with custom timeout
+ * await printQueriesWithPlan(forgeSQLORM, 1000, 3000);
+ * ```
+ *
+ * @throws Does not throw - errors are logged to console.debug instead
+ */
+export async function printQueriesWithPlan(
+  forgeSQLORM: ForgeSqlOperation,
+  timeDiffMs: number,
+  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
+                            )`,
+            ),
+          ),
+        ),
+          `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,
+    );
+
+    results.forEach((result) => {
+      // 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';
+
+/**
+ * Analyzes and logs slow queries from the last specified number of hours.
+ * 
+ * This function queries the slow query system table to find queries that were executed
+ * within the specified time window and logs detailed performance information including:
+ * - SQL query text
+ * - Maximum memory usage (in MB)
+ * - Query execution time (in ms)
+ * - Execution count
+ * - Execution plan
+ * 
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param hours - Number of hours to look back for slow queries (e.g., 1 for last hour, 24 for last day)
+ * @param timeout - Optional timeout in milliseconds for the query execution (defaults to 1500ms)
+ * 
+ * @example
+ * ```typescript
+ * // Analyze slow queries from the last hour
+ * await slowQueryPerHours(forgeSQLORM, 1);
+ * 
+ * // Analyze slow queries from the last 24 hours with custom timeout
+ * await slowQueryPerHours(forgeSQLORM, 24, 3000);
+ * 
+ * // Analyze slow queries from the last 6 hours
+ * await slowQueryPerHours(forgeSQLORM, 6);
+ * ```
+ * 
+ * @throws Does not throw - errors are logged to console.debug instead
+ */
+export async function slowQueryPerHours(forgeSQLORM: ForgeSqlOperation, hours:number, timeout?: number) {
+    try {
+        const timeoutMs = timeout ?? 1500;
+        const results = await withTimeout(
+            forgeSQLORM
+                .getDrizzleQueryBuilder()
+                .select({
+                    query: withTidbHint(slowQuery.query),
+                    queryTime: slowQuery.queryTime,
+                    memMax: slowQuery.memMax,
+                    plan: slowQuery.plan,
+                })
+                .from(slowQuery)
+                .where(
+                    and(
+                        isNotNull(slowQuery.digest),
+                        ne(slowQuery.sessionAlias, SESSION_ALIAS_NAME_ORM),
+                        gte(
+                            slowQuery.time,
+                            sql`DATE_SUB
+                            (NOW(), INTERVAL
+                            ${hours}
+                            HOUR
+                            )`,
+                        ),
+                    ),
+                ),
+            `Timeout ${timeoutMs}ms in slowQueryPerHours - transient timeouts are usually fine; repeated timeouts mean this diagnostic query is consistently slow and should be investigated`,
+            timeoutMs,
+        );
+       const response:string[] =[]
+        results.forEach((result) => {
+            // Convert memory from bytes to MB and handle null values
+            const memMaxMB = result.memMax ? Number(result.memMax) / 1_000_000 : 0;
+
+            const message = `Found SlowQuery SQL: ${result.query} | Memory: ${memMaxMB.toFixed(2)} MB | Time: ${result.queryTime} ms\n Plan:${result.plan}`;
+            response.push(message);
+            // 1. Query info: SQL, memory, time, executions
+            // eslint-disable-next-line no-console
+            console.warn(
+                message,
+            );
+        });
+        return response;
+    } 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,
+        );
+        return [`Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}`]
+    }
+}
+
+/**
+ * Executes a promise with a timeout.
+ *
+ * @param promise - The promise to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Promise that resolves with the result or rejects on timeout
+ * @throws {Error} When the operation times out
+ */
+export async function withTimeout<T>(promise: Promise<T>, message: string, timeoutMs: number): Promise<T> {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(
+                new Error(message),
+            );
+        }, timeoutMs);
+    });
+
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    } finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+
+export function withTidbHint<TDataType extends ColumnDataType, TPartial extends Partial<ColumnBaseConfig<TDataType, string>>>(column: AnyMySqlColumn<TPartial>): AnyMySqlColumn<TPartial> {
+    // We lie a bit to TypeScript here: at runtime this is a new SQL fragment,
+    // but returning TExpr keeps the column type info in downstream inference.
+    return sql`/*+ SET_VAR(tidb_session_alias=${sql.raw(`${SESSION_ALIAS_NAME_ORM}`)}) */ ${column}` as unknown as AnyMySqlColumn<TPartial>;
+}
+

package/src/webtriggers/index.ts

@@ -3,7 +3,7 @@ export * from "./applyMigrationsWebTrigger";
 export * from "./fetchSchemaWebTrigger";
 export * from "./dropTablesMigrationWebTrigger";
 export * from "./clearCacheSchedulerTrigger";
-export * from "./topSlowestStatementLastHourTrigger";
+export * from "./slowQuerySchedulerTrigger";
 
 export interface TriggerResponse<BODY> {
   body?: BODY;

package/src/webtriggers/slowQuerySchedulerTrigger.ts

@@ -0,0 +1,82 @@
+import {getHttpResponse, TriggerResponse} from "./index";
+import {slowQueryPerHours} from "../utils/sqlUtils";
+import {ForgeSqlOperation} from "../core/ForgeSQLQueryBuilder";
+
+/**
+ * Scheduler trigger for analyzing slow queries from the last specified number of hours.
+ * 
+ * This trigger analyzes slow queries from TiDB's slow query log system table and provides
+ * detailed performance information including SQL query text, memory usage, execution time,
+ * and execution plans. It's designed to be used as a scheduled trigger in Atlassian Forge
+ * to monitor query performance over time.
+ * 
+ * The function queries the slow query system table to find queries executed within the
+ * specified time window and logs detailed performance information to the console. Results
+ * are limited to the top 50 slow queries to prevent excessive output.
+ * 
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param options - Configuration options for the slow query analysis
+ * @param options.hours - Number of hours to look back for slow queries (default: 1)
+ * @param options.timeout - Timeout in milliseconds for the query execution (default: 2000ms)
+ * 
+ * @returns Promise<TriggerResponse<string>> - HTTP response with JSON stringified query results or error message
+ * 
+ * @example
+ * ```typescript
+ * import ForgeSQL, { slowQuerySchedulerTrigger } from "forge-sql-orm";
+ * 
+ * const forgeSQL = new ForgeSQL();
+ * 
+ * // Basic usage with default options (1 hour, 2000ms timeout)
+ * export const slowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 1, timeout: 2000 });
+ * 
+ * // Analyze slow queries from the last 6 hours with extended timeout
+ * export const sixHourSlowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 6, timeout: 5000 });
+ * 
+ * // Analyze slow queries from the last 24 hours
+ * export const dailySlowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 24, timeout: 3000 });
+ * ```
+ * 
+ * @example
+ * ```yaml
+ * # manifest.yml configuration
+ * scheduledTrigger:
+ *   - key: slow-query-trigger
+ *     function: slowQueryTrigger
+ *     interval: hour
+ * 
+ * function:
+ *   - key: slowQueryTrigger
+ *     handler: index.slowQueryTrigger
+ * ```
+ * 
+ * @remarks
+ * - Results are automatically logged to the Forge Developer Console via `console.warn()`
+ * - The function returns up to 50 slow queries to prevent excessive logging
+ * - Transient timeouts are usually fine; repeated timeouts indicate the diagnostic query itself is slow
+ * - This trigger is best used with hourly intervals to catch slow queries in a timely manner
+ * - Error responses return HTTP 500 with error details
+ * 
+ * @see {@link slowQueryPerHours} - The underlying function that performs the actual query analysis
+ */
+export async function slowQuerySchedulerTrigger(forgeSQLORM: ForgeSqlOperation, options: {
+    hours: number,
+    timeout: number
+}): Promise<TriggerResponse<string>> {
+    try {
+        return getHttpResponse<string>(200, JSON.stringify(await slowQueryPerHours(forgeSQLORM, options?.hours ?? 1, options?.timeout ?? 3000)));
+    } catch (error: any) {
+        const errorMessage =
+            error?.debug?.sqlMessage ??
+            error?.debug?.message ??
+            error.message ??
+            "Unknown error occurred";
+        // eslint-disable-next-line no-console
+        console.error(errorMessage);
+        return getHttpResponse<string>(500, errorMessage);
+    }
+}
+