forge-sql-orm 2.1.9 → 2.1.11

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);
+    }
+}
+

package/dist/webtriggers/topSlowestStatementLastHourTrigger.d.ts

@@ -1,114 +0,0 @@
-import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
-import { OperationType } from "../utils/requestTypeContextUtils";
-interface TriggerOptions {
-    warnThresholdMs?: number;
-    memoryThresholdBytes?: number;
-    showPlan?: boolean;
-    operationType?: OperationType;
-    topN?: number;
-    hours?: number;
-    tables?: "SUMMARY_AND_HISTORY" | "CLUSTER_SUMMARY_AND_HISTORY";
-}
-interface TriggerResponse {
-    headers: {
-        "Content-Type": string[];
-    };
-    statusCode: number;
-    statusText?: string;
-    body: string;
-}
-/**
- * Performance monitoring scheduler trigger for Atlassian Forge SQL.
- *
- * This trigger analyzes query performance from the last hour and identifies slow or memory-intensive queries
- * that exceed configurable thresholds. It's designed specifically for Atlassian Forge's 16 MiB memory limit
- * and provides detailed insights for query optimization.
- *
- * ## Key Features
- * - **Memory-focused monitoring**: Primary focus on memory usage with configurable thresholds
- * - **Atlassian 16 MiB limit awareness**: Designed specifically for Forge SQL's memory constraints
- * - **Execution plan analysis**: Shows detailed query plans to help optimize memory consumption
- * - **Configurable thresholds**: Set custom memory usage and latency thresholds
- * - **Automatic filtering**: Excludes system queries (`Use`, `Set`, `Show`) and empty queries
- * - **Scheduled monitoring**: Run automatically on configurable intervals
- *
- * ## OR Logic Thresholds
- * Statements are included if they exceed **EITHER** threshold:
- * - `avgLatencyMs > warnThresholdMs` **OR**
- * - `avgMemBytes > memoryThresholdBytes`
- *
- * ## Configuration Tips
- * - **Memory-only monitoring**: Set `warnThresholdMs` to 10000ms (effectively disabled)
- * - **Latency-only monitoring**: Set `memoryThresholdBytes` to 16MB (16 * 1024 * 1024) (effectively disabled)
- * - **Combined monitoring**: Use both thresholds for comprehensive monitoring
- * - **Conservative monitoring**: 4MB warning (25% of 16MB limit)
- * - **Default monitoring**: 8MB warning (50% of 16MB limit)
- * - **Aggressive monitoring**: 12MB warning (75% of 16MB limit)
- *
- * ## Exclusions
- * - Statements with empty `digestText` or `digest`
- * - Service statements (`Use`, `Set`, `Show`)
- * - Queries that don't exceed either threshold
- *
- * @param orm - ForgeSQL ORM instance (required)
- * @param options - Configuration options
- * @param options.warnThresholdMs - Milliseconds threshold for latency monitoring (default: 300ms)
- * @param options.memoryThresholdBytes - Bytes threshold for memory usage monitoring (default: 8MB)
- * @param options.showPlan - Whether to include execution plan in logs (default: false)
- * @param options.operationType - Operation type context for query execution (default: "DML")
- * @param options.topN - Number of top slow queries to return (default: 1)
- * @param options.hours - Number of hours to look back (default: 1)
- * @param options.tables - Table configuration to use (default: "CLUSTER_SUMMARY_AND_HISTORY")
- * @returns Promise<TriggerResponse> - HTTP response with query results or error
- *
- * @example
- * ```typescript
- * import ForgeSQL, { topSlowestStatementLastHourTrigger } from "forge-sql-orm";
- *
- * const forgeSQL = new ForgeSQL();
- *
- * // Default thresholds: 300ms latency OR 8MB memory
- * export const performanceTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL);
- *
- * // Conservative memory monitoring: 4MB threshold
- * export const conservativeTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, {
- *     memoryThresholdBytes: 4 * 1024 * 1024
- *   });
- *
- * // Memory-only monitoring: 4MB threshold (latency effectively disabled)
- * export const memoryOnlyTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, {
- *     warnThresholdMs: 10000,
- *     memoryThresholdBytes: 4 * 1024 * 1024
- *   });
- *
- * // With execution plan in logs
- * export const withPlanTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, { showPlan: true });
- * ```
- *
- * @example
- * ```yaml
- * # manifest.yml configuration
- * scheduledTrigger:
- *   - key: performance-trigger
- *     function: performanceTrigger
- *     interval: hour
- *
- * function:
- *   - key: performanceTrigger
- *     handler: index.performanceTrigger
- * ```
- */
-/**
- * Main scheduler trigger function to log the single slowest SQL statement from the last hour.
- *
- * @param orm - ForgeSQL ORM instance (required)
- * @param options - Configuration options
- * @returns Promise<TriggerResponse> - HTTP response with query results or error
- */
-export declare const topSlowestStatementLastHourTrigger: (orm: ForgeSqlOperation, options?: TriggerOptions) => Promise<TriggerResponse>;
-export {};
-//# sourceMappingURL=topSlowestStatementLastHourTrigger.d.ts.map

package/dist/webtriggers/topSlowestStatementLastHourTrigger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"topSlowestStatementLastHourTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/topSlowestStatementLastHourTrigger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AASjE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAcjE,UAAU,cAAc;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,GAAG,6BAA6B,CAAC;CAChE;AA2BD,UAAU,eAAe;IACvB,OAAO,EAAE;QAAE,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAgWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,GAC7C,KAAK,iBAAiB,EACtB,UAAU,cAAc,KACvB,OAAO,CAAC,eAAe,CAoDzB,CAAC"}