forge-sql-orm 2.1.10 → 2.1.12

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

@@ -47,6 +47,27 @@ function nowPlusSeconds(secondsToAdd: number): number {
   return Math.floor(dt.toSeconds());
 }
 
+/**
+ * Extracts all table/column names between backticks from SQL query and returns them as comma-separated string.
+ *
+ * @param sql - SQL query string
+ * @returns Comma-separated string of unique backticked values
+ */
+function extractBacktickedValues(sql: string): string {
+  const regex = /`([^`]+)`/g;
+  const matches = new Set<string>();
+  let match;
+
+  while ((match = regex.exec(sql.toLowerCase())) !== null) {
+    if (!match[1].startsWith("a_")) {
+      matches.add(`\`${match[1]}\``);
+    }
+  }
+
+  // Sort to ensure consistent order for the same input
+  return Array.from(matches).sort().join(",");
+}
+
 /**
  * Generates a hash key for a query based on its SQL and parameters.
  *
@@ -332,12 +353,14 @@ 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 &&
       (cacheResult[expirationName] as number) >= getCurrentTime() &&
-      sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]
+      extractBacktickedValues(sqlQuery.sql) === cacheResult[entityQueryName]
     ) {
       if (options.logCache) {
         // eslint-disable-next-line no-console
@@ -398,7 +421,7 @@ export async function setCacheResult(
       .set(
         key,
         {
-          [entityQueryName]: sqlQuery.sql.toLowerCase(),
+          [entityQueryName]: extractBacktickedValues(sqlQuery.sql),
           [expirationName]: nowPlusSeconds(cacheTtl),
           [dataName]: JSON.stringify(results),
         },

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,11 @@ 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 +190,13 @@ 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,31 @@
 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,14 @@ 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 +555,223 @@ 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;