forge-sql-orm 2.1.9 → 2.1.11

package/src/core/ForgeSQLORM.ts

@@ -28,7 +28,7 @@ import {
 } from "../lib/drizzle/extensions/additionalActions";
 import { ForgeSQLAnalyseOperation } from "./ForgeSQLAnalyseOperations";
 import { ForgeSQLCacheOperations } from "./ForgeSQLCacheOperations";
-import type { MySqlTable } from "drizzle-orm/mysql-core/table";
+import { MySqlTable } from "drizzle-orm/mysql-core/table";
 import {
   MySqlDeleteBase,
   MySqlInsertBuilder,
@@ -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 () => {
-        try {
-          return await query();
-        } finally {
+           const result = await query();
           const metadata = await getLastestMetadata();
-          if (metadata && metadata.lastMetadata) {
-            await onMetadata(
-              metadata.totalDbExecutionTime,
-              metadata.totalResponseSize,
-              metadata.lastMetadata,
-            );
-          }
-        }
+          try {
+               if (metadata) {
+                   await onMetadata(
+                       metadata.totalDbExecutionTime,
+                       metadata.totalResponseSize,
+                       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;
       },
     );
   }
@@ -762,32 +838,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);

package/src/core/ForgeSQLQueryBuilder.ts

@@ -29,7 +29,6 @@ import {
   DeleteAndEvictCacheType,
   ExecuteQuery,
   ExecuteQueryCacheable,
-  ForgeSQLMetadata,
   InsertAndEvictCacheType,
   SelectAliasedCacheableType,
   SelectAliasedDistinctCacheableType,
@@ -51,6 +50,7 @@ import {
 import {
   GetSelectTableName,
   GetSelectTableSelection,
+  SelectResultField,
 } from "drizzle-orm/query-builders/select.types";
 import { SQLWrapper } from "drizzle-orm/sql/sql";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
@@ -189,12 +189,23 @@ export interface QueryBuilderForgeSql {
     table: T,
   ): MySqlSelectBase<
     GetSelectTableName<T>,
-    T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
-    T["_"]["columns"] extends undefined ? "single" : "partial",
+    GetSelectTableSelection<T>,
+    "single",
     MySqlRemotePreparedQueryHKT,
     GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
     false,
     never,
+    {
+      [K in keyof {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }]: {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }[K];
+    }[],
     any
   >;
 
@@ -233,12 +244,23 @@ export interface QueryBuilderForgeSql {
     table: T,
   ): MySqlSelectBase<
     GetSelectTableName<T>,
-    T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
-    T["_"]["columns"] extends undefined ? "single" : "partial",
+    GetSelectTableSelection<T>,
+    "single",
     MySqlRemotePreparedQueryHKT,
     GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
     false,
     never,
+    {
+      [K in keyof {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }]: {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }[K];
+    }[],
     any
   >;
 
@@ -282,12 +304,23 @@ export interface QueryBuilderForgeSql {
     cacheTTL?: number,
   ): MySqlSelectBase<
     GetSelectTableName<T>,
-    T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
-    T["_"]["columns"] extends undefined ? "single" : "partial",
+    GetSelectTableSelection<T>,
+    "single",
     MySqlRemotePreparedQueryHKT,
     GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
     false,
     never,
+    {
+      [K in keyof {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }]: {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }[K];
+    }[],
     any
   >;
 
@@ -331,12 +364,23 @@ export interface QueryBuilderForgeSql {
     cacheTTL?: number,
   ): MySqlSelectBase<
     GetSelectTableName<T>,
-    T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
-    T["_"]["columns"] extends undefined ? "single" : "partial",
+    GetSelectTableSelection<T>,
+    "single",
     MySqlRemotePreparedQueryHKT,
     GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
     false,
     never,
+    {
+      [K in keyof {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }]: {
+        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
+          GetSelectTableSelection<T>[Key]
+        >;
+      }[K];
+    }[],
     any
   >;
 
@@ -499,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)