forge-sql-orm 2.1.4 → 2.1.5

package/README.md

@@ -24,6 +24,7 @@
 - ✅ **Supports complex SQL queries** with joins and filtering using Drizzle ORM
 - ✅ **Advanced Query Methods**: `selectFrom()`, `selectDistinctFrom()`, `selectCacheableFrom()`, `selectDistinctCacheableFrom()` for all-column queries with field aliasing
 - ✅ **Raw SQL Execution**: `execute()` and `executeCacheable()` methods for direct SQL queries with local and global caching
+- ✅ **Query Execution with Metadata**: `executeWithMetadata()` method for capturing detailed execution metrics including database execution time, response size, and Forge SQL metadata
 - ✅ **Common Table Expressions (CTEs)**: `with()` method for complex queries with subqueries
 - ✅ **Schema migration support**, allowing automatic schema evolution
 - ✅ **Automatic entity generation** from MySQL/tidb databases
@@ -333,6 +334,16 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   300
 );
 
+// Raw SQL with execution metadata
+const usersWithMetadata = await forgeSQL.executeWithMetadata(
+  async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
+  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+    console.log(`Response size: ${totalResponseSize} bytes`);
+    console.log('Forge metadata:', forgeMetadata);
+  }
+);
+
 // Common Table Expressions (CTEs)
 const userStats = await forgeSQL
   .with(
@@ -406,6 +417,16 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   [true], 
   300
 );
+
+// Raw SQL with execution metadata
+const usersWithMetadata = await forgeSQL.executeWithMetadata(
+  async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
+  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+    console.log(`Response size: ${totalResponseSize} bytes`);
+    console.log('Forge metadata:', forgeMetadata);
+  }
+);
 ```
 
 ## Setting Up Caching with @forge/kvs (Optional)
@@ -777,6 +798,7 @@ const optimizedData = await forgeSQL.executeWithLocalCacheContextAndReturnValue(
 | `selectDistinctCacheableFrom()` | Distinct all-column queries with field aliasing and caching | ❌ No | Local + Global Cache |
 | `execute()` | Raw SQL queries with local caching | ❌ No | Local Cache |
 | `executeCacheable()` | Raw SQL queries with local and global caching | ❌ No | Local + Global Cache |
+| `executeWithMetadata()` | Raw SQL queries with execution metrics capture | ❌ No | Local Cache |
 | `with()` | Common Table Expressions (CTEs) | ❌ No | Local Cache |
 where Cache context - allows you to batch cache invalidation events and bypass cache reads for affected tables.
 
@@ -1163,6 +1185,17 @@ const users = await forgeSQL
 const users = await forgeSQL
   .executeCacheable("SELECT * FROM users WHERE active = ?", [true], 300);
 
+// Using executeWithMetadata() for capturing execution metrics
+const usersWithMetadata = await forgeSQL
+  .executeWithMetadata(
+    async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
+    (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+      console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+      console.log(`Response size: ${totalResponseSize} bytes`);
+      console.log('Forge metadata:', forgeMetadata);
+    }
+  );
+
 // Using execute() with complex queries
 const userStats = await forgeSQL
   .execute(`
@@ -1478,6 +1511,16 @@ await forgeSQL.executeWithLocalContext(async () => {
     [true]
   );
   
+  // Raw SQL with execution metadata and local caching
+  const usersWithMetadata = await forgeSQL.executeWithMetadata(
+    async () => await forgeSQL.execute("SELECT id, name FROM users WHERE active = ?", [true]),
+    (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+      console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+      console.log(`Response size: ${totalResponseSize} bytes`);
+      console.log('Forge metadata:', forgeMetadata);
+    }
+  );
+  
   // Insert operation - evicts local cache for users table
   await forgeSQL.insert(users).values({ name: 'New User', active: true });
   
@@ -1646,6 +1689,16 @@ const userStats = await forgeSQL
   })
   .from(sql`activeUsers au`)
   .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+
+// Using executeWithMetadata() for capturing execution metrics with caching
+const usersWithMetadata = await forgeSQL.executeWithMetadata(
+  async () => await forgeSQL.executeCacheable("SELECT * FROM users WHERE active = ?", [true], 300),
+  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+    console.log(`Response size: ${totalResponseSize} bytes`);
+    console.log('Forge metadata:', forgeMetadata);
+  }
+);
 ```
 
 ### Manual Cache Management
@@ -1721,6 +1774,7 @@ The `ForgeSqlOrmOptions` object allows customization of ORM behavior:
 | Option                     | Type      | Description                                                                                                                                                                                                                     |
 | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `logRawSqlQuery`           | `boolean` | Enables logging of raw SQL queries in the Atlassian Forge Developer Console. Useful for debugging and monitoring. Defaults to `false`.                                                                                         |
+| `logCache`                 | `boolean` | Enables logging of cache operations (hits, misses, evictions) in the Atlassian Forge Developer Console. Useful for debugging caching issues. Defaults to `false`.                                                               |
 | `disableOptimisticLocking` | `boolean` | Disables optimistic locking. When set to `true`, no additional condition (e.g., a version check) is added during record updates, which can improve performance. However, this may lead to conflicts when multiple transactions attempt to update the same record concurrently. |
 | `additionalMetadata`       | `object`  | Allows adding custom metadata to all entities. This is useful for tracking common fields across all tables (e.g., `createdAt`, `updatedAt`, `createdBy`, etc.). The metadata will be automatically added to all generated entities. |
 | `cacheEntityName`          | `string`  | KVS Custom entity name for cache storage. Must match the `name` in your `manifest.yml` storage entities configuration. Required for caching functionality. Defaults to `"cache"`.                                                                                                                         |
@@ -2076,19 +2130,38 @@ export const memoryUsageTrigger = () =>
 
 // Conservative memory monitoring: 4MB warning (well below 16MB limit)
 export const conservativeMemoryTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, 300, 4 * 1024 * 1024);
+  topSlowestStatementLastHourTrigger(forgeSQL, { memoryThresholdBytes: 4 * 1024 * 1024 });
 
 // Aggressive memory monitoring: 12MB warning (75% of 16MB limit)
 export const aggressiveMemoryTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, 300, 12 * 1024 * 1024);
+  topSlowestStatementLastHourTrigger(forgeSQL, { memoryThresholdBytes: 12 * 1024 * 1024 });
 
 // Memory-only monitoring: Only trigger on memory usage (latency effectively disabled)
 export const memoryOnlyTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, 10000, 4 * 1024 * 1024);
+  topSlowestStatementLastHourTrigger(forgeSQL, { warnThresholdMs: 10000, memoryThresholdBytes: 4 * 1024 * 1024 });
 
 // Latency-only monitoring: Only trigger on slow queries (memory effectively disabled)
 export const latencyOnlyTrigger = () =>
-  topSlowestStatementLastHourTrigger(forgeSQL, 500, 16 * 1024 * 1024);
+  topSlowestStatementLastHourTrigger(forgeSQL, { warnThresholdMs: 500, memoryThresholdBytes: 16 * 1024 * 1024 });
+
+// With execution plan in logs
+export const withPlanTrigger = () =>
+  topSlowestStatementLastHourTrigger(forgeSQL, { showPlan: true });
+
+// With cache logging enabled
+export const withCacheLoggingTrigger = () =>
+  topSlowestStatementLastHourTrigger(forgeSQL, { logCache: true });
+
+// With both execution plan and cache logging
+export const withFullLoggingTrigger = () =>
+  topSlowestStatementLastHourTrigger(forgeSQL, { showPlan: true, logCache: true });
+
+// With custom ORM options for debugging
+const forgeSQL = new ForgeSQL({
+  logRawSqlQuery: true,
+  logCache: true,
+  cacheEntityName: "cache"
+});
 
 
 #### 3. Configure in manifest.yml
@@ -2196,7 +2269,8 @@ When used as a **web trigger**, the system:
 |-----------|------|---------|-------------|
 | `warnThresholdMs` | `number` | `300` | Latency threshold in milliseconds (secondary) |
 | `memoryThresholdBytes` | `number` | `8 * 1024 * 1024` | **Memory usage threshold in bytes (primary focus)** |
-| `options` | `ForgeSqlOrmOptions` | `undefined` | Optional ORM configuration |
+| `showPlan` | `boolean` | `false` | Whether to include execution plan in logs |
+| `logCache` | `boolean` | `false` | Whether to log cache operations |
 
 **⚠️ Important: OR Logic**
 The monitoring uses **OR logic** - if **either** threshold is exceeded, the query will be logged/returned:
@@ -2208,6 +2282,8 @@ The monitoring uses **OR logic** - if **either** threshold is exceeded, the quer
 - **Memory-only monitoring**: Set `warnThresholdMs` to a very high value (e.g., 10000ms) to trigger only on memory usage
 - **Latency-only monitoring**: Set `memoryThresholdBytes` to 16MB (16 * 1024 * 1024) to trigger only on latency
 - **Combined monitoring**: Use both thresholds for comprehensive monitoring
+- **Execution plan analysis**: Set `showPlan: true` to include detailed execution plans in logs (useful for debugging)
+- **Cache debugging**: Set `logCache: true` to log cache operations and debug caching issues
 
 **Memory Threshold Guidelines:**
 - **Conservative**: 4MB (25% of 16MB limit)
@@ -2312,6 +2388,16 @@ const cachedRawUsers = await forgeSQL.executeCacheable(
   300
 );
 
+// ✅ Raw SQL execution with metadata capture
+const usersWithMetadata = await forgeSQL.executeWithMetadata(
+  async () => await forgeSQL.execute("SELECT * FROM users WHERE active = ?", [true]),
+  (totalDbExecutionTime, totalResponseSize, forgeMetadata) => {
+    console.log(`DB execution time: ${totalDbExecutionTime}ms`);
+    console.log(`Response size: ${totalResponseSize} bytes`);
+    console.log('Forge metadata:', forgeMetadata);
+  }
+);
+
 // ✅ Common Table Expressions (CTEs)
 const userStats = await forgeSQL
   .with(

package/dist/ForgeSQLORM.js

@@ -410,7 +410,7 @@ async function clearCursorCache(tables, cursor, options) {
     entityQueryBuilder = entityQueryBuilder.cursor(cursor);
   }
   const listResult = await entityQueryBuilder.limit(100).getMany();
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
     console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
   await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
@@ -431,7 +431,7 @@ async function clearExpirationCursorCache(cursor, options) {
     entityQueryBuilder = entityQueryBuilder.cursor(cursor);
   }
   const listResult = await entityQueryBuilder.limit(100).getMany();
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
     console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
   await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
@@ -480,7 +480,7 @@ async function clearTablesCache(tables, options) {
       "clearing cache"
     );
   } finally {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const duration = luxon.DateTime.now().toSeconds() - startTime.toSeconds();
       console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
     }
@@ -499,7 +499,7 @@ async function clearExpiredCache(options) {
     );
   } finally {
     const duration = luxon.DateTime.now().toSeconds() - startTime.toSeconds();
-    if (options?.logRawSqlQuery) {
+    if (options?.logCache) {
       console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
     }
   }
@@ -514,7 +514,7 @@ async function getFromCache(query, options) {
   const sqlQuery = query.toSQL();
   const key = hashKey(sqlQuery);
   if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       console.warn(`Context contains value to clear. Skip getting from cache`);
     }
     return void 0;
@@ -522,7 +522,7 @@ async function getFromCache(query, options) {
   try {
     const cacheResult = await kvs.kvs.entity(options.cacheEntityName).get(key);
     if (cacheResult && cacheResult[expirationName] >= getCurrentTime() && sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         console.warn(`Get value from cache, cacheKey: ${key}`);
       }
       const results = cacheResult[dataName];
@@ -543,7 +543,7 @@ async function setCacheResult(query, options, results, cacheTtl) {
     const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
     const sqlQuery = query.toSQL();
     if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         console.warn(`Context contains value to clear. Skip setting from cache`);
       }
       return;
@@ -558,7 +558,7 @@ async function setCacheResult(query, options, results, cacheTtl) {
       },
       { entityName: options.cacheEntityName }
     ).execute();
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       console.warn(`Store value to cache, cacheKey: ${key}`);
     }
   } catch (error) {
@@ -586,7 +586,7 @@ async function saveQueryLocalCacheQuery(query, rows, options) {
       sql: sql2.toSQL().sql.toLowerCase(),
       data: rows
     };
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const q = sql2.toSQL();
       console.debug(
         `[forge-sql-orm][local-cache][SAVE] Stored result in cache. sql="${q.sql}", params=${JSON.stringify(q.params)}`
@@ -603,7 +603,7 @@ async function getQueryLocalCacheQuery(query, options) {
     const sql2 = query;
     const key = hashKey(sql2.toSQL());
     if (context.cache[key] && context.cache[key].sql === sql2.toSQL().sql.toLowerCase()) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         const q = sql2.toSQL();
         console.debug(
           `[forge-sql-orm][local-cache][HIT] Returned cached result. sql="${q.sql}", params=${JSON.stringify(q.params)}`
@@ -1034,6 +1034,18 @@ class ForgeSQLSelectOperations {
     return updateQueryResponseResults.rows;
   }
 }
+const metadataQueryContext = new node_async_hooks.AsyncLocalStorage();
+async function saveMetaDataInContextContext(metadata) {
+  const context = metadataQueryContext.getStore();
+  if (context && metadata) {
+    context.totalResponseSize += metadata.responseSize;
+    context.totalDbExecutionTime += metadata.dbExecutionTime;
+    context.lastMetadata = metadata;
+  }
+}
+async function getLastestMetadata() {
+  return metadataQueryContext.getStore();
+}
 const forgeDriver = async (query, params, method) => {
   if (method == "execute") {
     const sqlStatement = sql$1.sql.prepare(query);
@@ -1049,6 +1061,7 @@ const forgeDriver = async (query, params, method) => {
       await sqlStatement.bindParams(...params);
     }
     const result = await sqlStatement.execute();
+    await saveMetaDataInContextContext(result.metadata);
     let rows;
     rows = result.rows.map((r) => Object.values(r));
     return { rows };
@@ -1798,6 +1811,7 @@ class ForgeSQLORMImpl {
     try {
       const newOptions = options ?? {
         logRawSqlQuery: false,
+        logCache: false,
         disableOptimisticLocking: false,
         cacheWrapTable: true,
         cacheTTL: 120,
@@ -1823,6 +1837,42 @@ class ForgeSQLORMImpl {
       throw error;
     }
   }
+  /**
+   * Executes a query and provides access to execution metadata.
+   * This method allows you to capture detailed information about query execution
+   * including database execution time, response size, and Forge SQL metadata.
+   *
+   * @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
+   * @returns Promise with the query result
+   * @example
+   * ```typescript
+   * 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 executeWithMetadata(query, onMetadata) {
+    return metadataQueryContext.run({
+      totalDbExecutionTime: 0,
+      totalResponseSize: 0
+    }, async () => {
+      try {
+        return await query();
+      } finally {
+        const metadata = await getLastestMetadata();
+        if (metadata && metadata.lastMetadata) {
+          await onMetadata(metadata.totalDbExecutionTime, metadata.totalResponseSize, metadata.lastMetadata);
+        }
+      }
+    });
+  }
   /**
    * Executes operations within a cache context that collects cache eviction events.
    * All clearCache calls within the context are collected and executed in batch at the end.
@@ -2270,6 +2320,30 @@ class ForgeSQLORM {
   constructor(options) {
     this.ormInstance = ForgeSQLORMImpl.getInstance(options);
   }
+  /**
+   * Executes a query and provides access to execution metadata.
+   * This method allows you to capture detailed information about query execution
+   * including database execution time, response size, and Forge SQL metadata.
+   *
+   * @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
+   * @returns Promise with the query result
+   * @example
+   * ```typescript
+   * 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 executeWithMetadata(query, onMetadata) {
+    return this.ormInstance.executeWithMetadata(query, onMetadata);
+  }
   selectCacheable(fields, cacheTTL) {
     return this.ormInstance.selectCacheable(fields, cacheTTL);
   }
@@ -3218,7 +3292,25 @@ const clearCacheSchedulerTrigger = async (options) => {
     };
   }
 };
-const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, memoryThresholdBytes = 8 * 1024 * 1024) => {
+const DEFAULT_MEMORY_THRESHOLD = 8 * 1024 * 1024;
+const DEFAULT_TIMEOUT = 300;
+const topSlowestStatementLastHourTrigger = async (orm, options) => {
+  if (!orm) {
+    return {
+      statusCode: 500,
+      headers: { "Content-Type": ["application/json"] },
+      body: JSON.stringify({
+        success: false,
+        message: "ORM instance is required",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    };
+  }
+  let newOptions = options ?? {
+    warnThresholdMs: DEFAULT_TIMEOUT,
+    memoryThresholdBytes: DEFAULT_MEMORY_THRESHOLD,
+    showPlan: false
+  };
   const nsToMs = (v) => {
     const n = Number(v);
     return Number.isFinite(n) ? n / 1e6 : NaN;
@@ -3228,6 +3320,17 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
     return Number.isFinite(n) ? n / (1024 * 1024) : NaN;
   };
   const jsonSafeStringify = (value) => JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
+  function sanitizeSQL(sql2, maxLen = 1e3) {
+    let s = sql2;
+    s = s.replace(/--[^\n\r]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    s = s.replace(/'(?:\\'|[^'])*'/g, "?");
+    s = s.replace(/\b-?\d+(?:\.\d+)?\b/g, "?");
+    s = s.replace(/\s+/g, " ").trim();
+    if (s.length > maxLen) {
+      s = s.slice(0, maxLen) + " …[truncated]";
+    }
+    return s;
+  }
   const TOP_N = 1;
   try {
     const summaryHistory = clusterStatementsSummaryHistory;
@@ -3264,7 +3367,8 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
     const qHistory = orm.getDrizzleQueryBuilder().select(selectShape(summaryHistory)).from(summaryHistory).where(lastHourFilterHistory);
     const qSummary = orm.getDrizzleQueryBuilder().select(selectShape(summary)).from(summary).where(lastHourFilterSummary);
     const combined = mysqlCore.unionAll(qHistory, qSummary).as("combined");
-    const thresholdNs = Math.floor(warnThresholdMs * 1e6);
+    const thresholdNs = Math.floor((newOptions.warnThresholdMs ?? DEFAULT_TIMEOUT) * 1e6);
+    const memoryThresholdBytes = newOptions.memoryThresholdBytes ?? DEFAULT_MEMORY_THRESHOLD;
     const grouped = orm.getDrizzleQueryBuilder().select({
       digest: combined.digest,
       stmtType: combined.stmtType,
@@ -3335,8 +3439,8 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
       lastSeen: r.lastSeen,
       planInCache: r.planInCache,
       planCacheHits: r.planCacheHits,
-      digestText: r.digestText,
-      plan: r.plan
+      digestText: sanitizeSQL(r.digestText),
+      plan: newOptions.showPlan ? r.plan : void 0
     }));
     for (const f of formatted) {
       console.warn(
@@ -3344,7 +3448,7 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
    digest=${f.digest}
    sql=${(f.digestText || "").slice(0, 300)}${f.digestText && f.digestText.length > 300 ? "…" : ""}`
       );
-      if (f.plan) {
+      if (newOptions.showPlan && f.plan) {
         console.warn(`   full plan:
 ${f.plan}`);
       }
@@ -3357,8 +3461,9 @@ ${f.plan}`);
         success: true,
         window: "last_1h",
         top: TOP_N,
-        warnThresholdMs,
-        memoryThresholdBytes,
+        warnThresholdMs: newOptions.warnThresholdMs,
+        memoryThresholdBytes: newOptions.memoryThresholdBytes,
+        showPlan: newOptions.showPlan,
         rows: formatted,
         generatedAt: (/* @__PURE__ */ new Date()).toISOString()
       })