forge-sql-orm 2.1.10 → 2.1.12

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

@@ -1 +1 @@
-{"version":3,"file":"cacheUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA2ClE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5C;AAmKD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoBf;AACD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBlF;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA2CxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA8Cf"}
+{"version":3,"file":"cacheUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAgElE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5C;AAmKD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoBf;AACD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBlF;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA6CxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA8Cf"}

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

@@ -1 +1 @@
-{"version":3,"file":"forgeDriver.d.ts","sourceRoot":"","sources":["../../src/utils/forgeDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;CACL,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1D,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,mBAAmB,CAO9E;AA2HD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,MAAM,EACb,QAAQ,OAAO,EAAE,EACjB,QAAQ,WAAW,KAClB,OAAO,CAAC,iBAAiB,CAgB3B,CAAC"}
+{"version":3,"file":"forgeDriver.d.ts","sourceRoot":"","sources":["../../src/utils/forgeDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAQtD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;CACL,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1D,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,mBAAmB,CAO9E;AAiGD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,MAAM,EACb,QAAQ,OAAO,EAAE,EACjB,QAAQ,WAAW,KAClB,OAAO,CAAC,iBAAiB,CAmB3B,CAAC"}

package/dist/utils/forgeDriverProxy.d.ts

@@ -1,9 +1,13 @@
 import { SqlHints } from "./sqlHints";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
 /**
- * Creates a proxy for the forgeDriver that injects SQL hints
+ * 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 declare function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: boolean): (query: string, params: any[], method: "all" | "execute") => Promise<{
+export declare function createForgeDriverProxy(forgeSqlOperation: ForgeSqlOperation, options?: SqlHints, logRawSqlQuery?: boolean): (query: string, params: any[], method: "all" | "execute") => Promise<{
     rows: any[];
     insertId?: number;
     affectedRows?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"forgeDriverProxy.d.ts","sourceRoot":"","sources":["../../src/utils/forgeDriverProxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,OAAO,IAE/E,OAAO,MAAM,EACb,QAAQ,GAAG,EAAE,EACb,QAAQ,KAAK,GAAG,SAAS,KACxB,OAAO,CAAC;IACT,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC,CAmBH"}
+{"version":3,"file":"forgeDriverProxy.d.ts","sourceRoot":"","sources":["../../src/utils/forgeDriverProxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAgBjE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,CAAC,EAAE,QAAQ,EAClB,cAAc,CAAC,EAAE,OAAO,IAGtB,OAAO,MAAM,EACb,QAAQ,GAAG,EAAE,EACb,QAAQ,KAAK,GAAG,SAAS,KACxB,OAAO,CAAC;IACT,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC,CAiDH"}

package/dist/utils/metadataContextUtils.d.ts

@@ -1,11 +1,14 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { ForgeSQLMetadata } from "./forgeDriver";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
 export type MetadataQueryContext = {
     totalDbExecutionTime: number;
     totalResponseSize: number;
-    lastMetadata?: ForgeSQLMetadata;
+    beginTime: Date;
+    printQueriesWithPlan: () => Promise<void>;
+    forgeSQLORM: ForgeSqlOperation;
 };
 export declare const metadataQueryContext: AsyncLocalStorage<MetadataQueryContext>;
-export declare function saveMetaDataToContext(metadata: ForgeSQLMetadata): Promise<void>;
+export declare function saveMetaDataToContext(metadata?: ForgeSQLMetadata): Promise<void>;
 export declare function getLastestMetadata(): Promise<MetadataQueryContext | undefined>;
 //# sourceMappingURL=metadataContextUtils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"metadataContextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC,CAAC;AACF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAElF,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAEpF"}
+{"version":3,"file":"metadataContextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;IAChB,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAAC;AACF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAElF,wBAAsB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAetF;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAEpF"}

package/dist/utils/sqlUtils.d.ts

@@ -5,7 +5,11 @@ 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 { 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
  */
@@ -77,5 +81,72 @@ export declare function mapSelectFieldsWithAlias<TSelection extends SelectedFiel
 export declare function applyFromDriverTransform<T, TSelection>(rows: T[], selections: TSelection, aliasMap: Record<string, AnyColumn>): T[];
 export declare function formatLimitOffset(limitOrOffset: number): number;
 export declare function nextVal(sequenceName: string): 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 declare function printQueriesWithPlan(forgeSQLORM: ForgeSqlOperation, timeDiffMs: number, timeout?: number): Promise<void>;
+/**
+ * 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 declare function slowQueryPerHours(forgeSQLORM: ForgeSqlOperation, hours: number, timeout?: number): Promise<string[]>;
+/**
+ * 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 declare function withTimeout<T>(promise: Promise<T>, message: string, timeoutMs: number): Promise<T>;
+export declare function withTidbHint<TDataType extends ColumnDataType, TPartial extends Partial<ColumnBaseConfig<TDataType, string>>>(column: AnyMySqlColumn<TPartial>): AnyMySqlColumn<TPartial>;
 export {};
 //# sourceMappingURL=sqlUtils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sqlUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sqlUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0C,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,aAAa,EAAqB,MAAM,8BAA8B,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,8BAA8B;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,yCAAyC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,0CAA0C;IAC1C,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IAC7C,kCAAkC;IAClC,MAAM,EAAE,GAAG,EAAE,CAAC;CACf;AAUD;;;;;GAKG;AAEH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,QAAQ,MAAM,KAAG,IA+BpE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,OAAO,GACnB,MAAM,CA+CR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAkCvF;AA0DD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAoEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,EAAE,CAkBV;AAED,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAuBhD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,GAAG,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,cAAc,GACvB,GAAG,CAmBL;AACD,wBAAgB,wBAAwB,CAAC,UAAU,SAAS,cAAc,EACxE,MAAM,EAAE,UAAU,GACjB;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAUtD;AAsED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,UAAU,EACpD,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAClC,CAAC,EAAE,CAUL;AAoCD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"sqlUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sqlUtils.ts"],"names":[],"mappings":"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"}

package/dist/webtriggers/index.d.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;
     headers?: Record<string, string[]>;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webtriggers/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AAErD,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,GAAI,IAAI,EAAE,YAAY,MAAM,EAAE,MAAM,IAAI,KAAG,eAAe,CAAC,IAAI,CAc1F,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webtriggers/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAE5C,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,GAAI,IAAI,EAAE,YAAY,MAAM,EAAE,MAAM,IAAI,KAAG,eAAe,CAAC,IAAI,CAc1F,CAAC"}

package/dist/webtriggers/slowQuerySchedulerTrigger.d.ts

@@ -0,0 +1,67 @@
+import { TriggerResponse } from "./index";
+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 declare function slowQuerySchedulerTrigger(forgeSQLORM: ForgeSqlOperation, options: {
+    hours: number;
+    timeout: number;
+}): Promise<TriggerResponse<string>>;
+//# sourceMappingURL=slowQuerySchedulerTrigger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slowQuerySchedulerTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/slowQuerySchedulerTrigger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,eAAe,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,iBAAiB,EAC9B,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAkBlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.10",
+  "version": "2.1.12",
   "description": "Drizzle ORM integration for Atlassian @forge/sql. Provides a custom driver, schema migration, two levels of caching (local and global via @forge/kvs), optimistic locking, and query analysis.",
   "main": "dist/ForgeSQLORM.js",
   "module": "dist/ForgeSQLORM.mjs",
@@ -32,24 +32,24 @@
     "database"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.38.0",
+    "@eslint/js": "^9.39.0",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^24.9.1",
+    "@types/node": "^24.9.2",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
     "@typescript-eslint/parser": "^8.46.2",
-    "@vitest/coverage-v8": "^4.0.1",
-    "@vitest/ui": "^4.0.1",
-    "eslint": "^9.38.0",
+    "@vitest/coverage-v8": "^4.0.6",
+    "@vitest/ui": "^4.0.6",
+    "eslint": "^9.39.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-vitest": "^0.5.4",
-    "knip": "^5.66.2",
+    "knip": "^5.66.4",
     "prettier": "^3.6.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vite": "^7.1.11",
-    "vitest": "^4.0.1"
+    "vite": "^7.1.12",
+    "vitest": "^4.0.6"
   },
   "license": "MIT",
   "author": "Vasyl Zakharchenko",
@@ -76,11 +76,11 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@forge/sql": "^3.0.8",
-    "drizzle-orm": "^0.44.6"
+    "@forge/sql": "^3.0.9",
+    "drizzle-orm": "^0.44.7"
   },
   "optionalDependencies": {
-    "@forge/kvs": "^1.0.5"
+    "@forge/kvs": "^1.0.8"
   },
   "dependencies": {
     "luxon": "^3.7.2"

package/src/core/ForgeSQLORM.ts

@@ -38,7 +38,6 @@ import { cacheApplicationContext, localCacheApplicationContext } from "../utils/
 import { clearTablesCache } from "../utils/cacheUtils";
 import { SQLWrapper } from "drizzle-orm/sql/sql";
 import { WithSubquery } from "drizzle-orm/subquery";
-import { ForgeSQLMetadata } from "../utils/forgeDriver";
 import { getLastestMetadata, metadataQueryContext } from "../utils/metadataContextUtils";
 import { operationTypeQueryContext } from "../utils/requestTypeContextUtils";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
@@ -90,7 +89,11 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
         console.debug("Initializing ForgeSQLORM...");
       }
       // Initialize Drizzle instance with our custom driver
-      const proxiedDriver = createForgeDriverProxy(newOptions.hints, newOptions.logRawSqlQuery);
+      const proxiedDriver = createForgeDriverProxy(
+        this,
+        newOptions.hints,
+        newOptions.logRawSqlQuery,
+      );
       this.drizzle = patchDbWithSelectAliased(
         drizzle(proxiedDriver, { logger: newOptions.logRawSqlQuery }),
         newOptions,
@@ -107,52 +110,125 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
   }
 
   /**
-   * 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.
    */
   async executeWithMetadata<T>(
     query: () => Promise<T>,
     onMetadata: (
       totalDbExecutionTime: number,
       totalResponseSize: number,
-      forgeMetadata: ForgeSQLMetadata,
+      printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
   ): Promise<T> {
     return metadataQueryContext.run(
       {
         totalDbExecutionTime: 0,
         totalResponseSize: 0,
+        beginTime: new Date(),
+        forgeSQLORM: this,
+        printQueriesWithPlan: async () => {
+          return;
+        },
       },
       async () => {
+        const result = await query();
+        const metadata = await getLastestMetadata();
         try {
-          return await query();
-        } finally {
-          const metadata = await getLastestMetadata();
-          if (metadata && metadata.lastMetadata) {
+          if (metadata) {
             await onMetadata(
               metadata.totalDbExecutionTime,
               metadata.totalResponseSize,
-              metadata.lastMetadata,
+              metadata.printQueriesWithPlan,
             );
           }
+        } catch (e: any) {
+          // eslint-disable-next-line no-console
+          console.error(
+            "[ForgeSQLORM][executeWithMetadata] Failed to run onMetadata callback",
+            {
+              errorMessage: e?.message,
+              errorStack: e?.stack,
+              totalDbExecutionTime: metadata?.totalDbExecutionTime,
+              totalResponseSize: metadata?.totalResponseSize,
+              beginTime: metadata?.beginTime,
+            },
+            e,
+          );
         }
+        return result;
       },
     );
   }
@@ -704,7 +780,10 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
    * ```
    */
-  executeCacheable<T>(query: SQLWrapper | string, cacheTtl?: number) {
+  executeCacheable<T>(
+    query: SQLWrapper | string,
+    cacheTtl?: number,
+  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>> {
     return this.drizzle.executeQueryCacheable<T>(query, cacheTtl);
   }
 
@@ -762,32 +841,87 @@ class ForgeSQLORM implements ForgeSqlOperation {
   }
 
   /**
-   * 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.
    */
   async executeWithMetadata<T>(
     query: () => Promise<T>,
     onMetadata: (
       totalDbExecutionTime: number,
       totalResponseSize: number,
-      forgeMetadata: ForgeSQLMetadata,
+      printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
   ): Promise<T> {
     return this.ormInstance.executeWithMetadata(query, onMetadata);
@@ -1209,7 +1343,10 @@ class ForgeSQLORM implements ForgeSqlOperation {
    * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
    * ```
    */
-  executeCacheable(query: SQLWrapper | string, cacheTtl?: number) {
+  executeCacheable<T>(
+    query: SQLWrapper | string,
+    cacheTtl?: number,
+  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>> {
     return this.ormInstance.executeCacheable(query, cacheTtl);
   }