forge-sql-orm 2.1.4 → 2.1.6

package/src/utils/cacheContextUtils.ts

@@ -102,8 +102,9 @@ export async function saveQueryLocalCacheQuery<
       sql: sql.toSQL().sql.toLowerCase(),
       data: rows,
     };
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const q = sql.toSQL();
+      // eslint-disable-next-line no-console
       console.debug(
         `[forge-sql-orm][local-cache][SAVE] Stored result in cache. sql="${q.sql}", params=${JSON.stringify(q.params)}`,
       );
@@ -140,8 +141,9 @@ export async function getQueryLocalCacheQuery<
     const sql = query as { toSQL: () => Query };
     const key = hashKey(sql.toSQL());
     if (context.cache[key] && context.cache[key].sql === sql.toSQL().sql.toLowerCase()) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         const q = sql.toSQL();
+        // eslint-disable-next-line no-console
         console.debug(
           `[forge-sql-orm][local-cache][HIT] Returned cached result. sql="${q.sql}", params=${JSON.stringify(q.params)}`,
         );

package/src/utils/cacheUtils.ts

@@ -123,7 +123,8 @@ async function clearCursorCache(
 
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
+    // eslint-disable-next-line no-console
     console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
 
@@ -170,7 +171,8 @@ async function clearExpirationCursorCache(
 
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
+    // eslint-disable-next-line no-console
     console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
 
@@ -201,10 +203,12 @@ async function executeWithRetry<T>(operation: () => Promise<T>, operationName: s
     try {
       return await operation();
     } catch (err: any) {
+      // eslint-disable-next-line no-console
       console.warn(`Error during ${operationName}: ${err.message}, retry ${attempt}`, err);
       attempt++;
 
       if (attempt >= CACHE_CONSTANTS.MAX_RETRY_ATTEMPTS) {
+        // eslint-disable-next-line no-console
         console.error(`Error during ${operationName}: ${err.message}`, err);
         throw err;
       }
@@ -260,8 +264,9 @@ export async function clearTablesCache(
       "clearing cache",
     );
   } finally {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+      // eslint-disable-next-line no-console
       console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
     }
   }
@@ -287,7 +292,8 @@ export async function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<vo
     );
   } finally {
     const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-    if (options?.logRawSqlQuery) {
+    if (options?.logCache) {
+      // eslint-disable-next-line no-console
       console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
     }
   }
@@ -318,7 +324,8 @@ export async function getFromCache<T>(
 
   // Skip cache if table is in cache context (will be cleared)
   if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
+      // eslint-disable-next-line no-console
       console.warn(`Context contains value to clear. Skip getting from cache`);
     }
     return undefined;
@@ -332,13 +339,15 @@ export async function getFromCache<T>(
       (cacheResult[expirationName] as number) >= getCurrentTime() &&
       sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]
     ) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
+        // eslint-disable-next-line no-console
         console.warn(`Get value from cache, cacheKey: ${key}`);
       }
       const results = cacheResult[dataName];
       return JSON.parse(results as string);
     }
   } catch (error: any) {
+    // eslint-disable-next-line no-console
     console.error(`Error getting from cache: ${error.message}`, error);
   }
 
@@ -375,7 +384,8 @@ export async function setCacheResult(
 
     // Skip cache if table is in cache context (will be cleared)
     if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
+        // eslint-disable-next-line no-console
         console.warn(`Context contains value to clear. Skip setting from cache`);
       }
       return;
@@ -396,10 +406,12 @@ export async function setCacheResult(
       )
       .execute();
 
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
+      // eslint-disable-next-line no-console
       console.warn(`Store value to cache, cacheKey: ${key}`);
     }
   } catch (error: any) {
+    // eslint-disable-next-line no-console
     console.error(`Error setting cache: ${error.message}`, error);
   }
 }

package/src/utils/forgeDriver.ts

@@ -1,34 +1,234 @@
 import { sql, UpdateQueryResponse } from "@forge/sql";
+import { saveMetaDataToContext } from "./metadataContextUtils";
+import { getOperationType } from "./requestTypeContextUtils";
 
-interface ForgeSQLResult {
+/**
+ * Metadata structure for Forge SQL query results.
+ * Contains execution timing, response size, and field information.
+ */
+export type ForgeSQLMetadata = {
+  dbExecutionTime: number;
+  responseSize: number;
+  fields: {
+    catalog: string;
+    name: string;
+    schema: string;
+    characterSet: number;
+    decimals: number;
+    table: string;
+    orgTable: string;
+    orgName: string;
+    flags: number;
+    columnType: number;
+    columnLength: number;
+  }[];
+};
+
+/**
+ * Result structure for Forge SQL queries.
+ * Contains rows data and execution metadata.
+ */
+export interface ForgeSQLResult {
   rows: Record<string, unknown>[] | Record<string, unknown>;
+  metadata: ForgeSQLMetadata;
 }
 
-export const forgeDriver = async (
-  query: string,
-  params: any[],
-  method: "all" | "execute",
-): Promise<{
-  rows: any[];
+/**
+ * Driver result structure for Drizzle ORM compatibility.
+ */
+export interface ForgeDriverResult {
+  rows: unknown[];
   insertId?: number;
   affectedRows?: number;
-}> => {
-  if (method == "execute") {
-    const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
-    if (params) {
-      sqlStatement.bindParams(...params);
+}
+
+/**
+ * Query execution method types.
+ */
+export type QueryMethod = "all" | "execute";
+
+/**
+ * Type guard to check if an object is an UpdateQueryResponse.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is an UpdateQueryResponse
+ */
+export function isUpdateQueryResponse(obj: unknown): obj is UpdateQueryResponse {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    typeof (obj as any).affectedRows === "number" &&
+    typeof (obj as any).insertId === "number"
+  );
+}
+
+/**
+ * Executes a promise with a timeout.
+ *
+ * @param promise - The promise to execute
+ * @param timeoutMs - Timeout in milliseconds (default: 10000ms)
+ * @returns Promise that resolves with the result or rejects on timeout
+ * @throws {Error} When the operation times out
+ */
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number = 10000): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(
+        new Error(
+          `Atlassian @forge/sql did not return a response within ${timeoutMs}ms (${timeoutMs / 1000} seconds), so the request is blocked. Possible causes: slow query, network issues, or exceeding Forge SQL limits.`,
+        ),
+      );
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
     }
-    const updateQueryResponseResults = await sqlStatement.execute();
-    let result = updateQueryResponseResults.rows as any;
-    return { ...result, rows: [result] };
-  } else {
-    const sqlStatement = await sql.prepare<unknown>(query);
-    if (params) {
-      await sqlStatement.bindParams(...params);
+  }
+}
+
+function inlineParams(sql: string, params: unknown[]): string {
+  let i = 0;
+  return sql.replace(/\?/g, () => {
+    const val = params[i++];
+    if (val === null) return "NULL";
+    if (typeof val === "number") return val.toString();
+    return `'${String(val).replace(/'/g, "''")}'`;
+  });
+}
+
+/**
+ * Processes DDL query results and saves metadata.
+ *
+ * @param result - The DDL query result
+ * @returns Processed result for Drizzle ORM
+ */
+async function processDDLResult(method: QueryMethod, result: any): Promise<ForgeDriverResult> {
+  if (result.metadata) {
+    await saveMetaDataToContext(result.metadata as ForgeSQLMetadata);
+  }
+
+  if (!result.rows) {
+    return { rows: [] };
+  }
+
+  if (isUpdateQueryResponse(result.rows)) {
+    const oneRow = result.rows as any;
+    return { ...oneRow, rows: [oneRow] };
+  }
+
+  if (Array.isArray(result.rows)) {
+    if (method === "execute") {
+      return { rows: result.rows };
+    } else {
+      const rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+      return { rows };
     }
-    const result = (await sqlStatement.execute()) as ForgeSQLResult;
-    let rows;
-    rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
-    return { rows: rows };
   }
+
+  return { rows: [] };
+}
+
+/**
+ * Processes execute method results (UPDATE, INSERT, DELETE).
+ *
+ * @param query - The SQL query
+ * @param params - Query parameters
+ * @returns Processed result for Drizzle ORM
+ */
+async function processExecuteMethod(query: string, params: unknown[]): Promise<ForgeDriverResult> {
+  const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+
+  if (params) {
+    sqlStatement.bindParams(...params);
+  }
+
+  const result = await withTimeout(sqlStatement.execute());
+  await saveMetaDataToContext(result.metadata as ForgeSQLMetadata);
+  if (!result.rows) {
+    return { rows: [] };
+  }
+
+  if (isUpdateQueryResponse(result.rows)) {
+    const oneRow = result.rows as any;
+    return { ...oneRow, rows: [oneRow] };
+  }
+
+  return { rows: result.rows };
+}
+
+/**
+ * Processes all method results (SELECT queries).
+ *
+ * @param query - The SQL query
+ * @param params - Query parameters
+ * @returns Processed result for Drizzle ORM
+ */
+async function processAllMethod(query: string, params: unknown[]): Promise<ForgeDriverResult> {
+  const sqlStatement = await sql.prepare<unknown>(query);
+
+  if (params) {
+    await sqlStatement.bindParams(...params);
+  }
+
+  const result = (await withTimeout(sqlStatement.execute())) as ForgeSQLResult;
+  await saveMetaDataToContext(result.metadata);
+
+  if (!result.rows) {
+    return { rows: [] };
+  }
+
+  const rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+
+  return { rows };
+}
+
+/**
+ * Main Forge SQL driver function for Drizzle ORM integration.
+ * Handles DDL operations, execute operations (UPDATE/INSERT/DELETE), and select operations.
+ *
+ * @param query - The SQL query to execute
+ * @param params - Query parameters
+ * @param method - Execution method ("all" for SELECT, "execute" for UPDATE/INSERT/DELETE)
+ * @returns Promise with query results compatible with Drizzle ORM
+ *
+ * @throws {Error} When DDL operations are called with parameters
+ *
+ * @example
+ * ```typescript
+ * // DDL operation
+ * await forgeDriver("CREATE TABLE users (id INT)", [], "all");
+ *
+ * // SELECT operation
+ * await forgeDriver("SELECT * FROM users WHERE id = ?", [1], "all");
+ *
+ * // UPDATE operation
+ * await forgeDriver("UPDATE users SET name = ? WHERE id = ?", ["John", 1], "execute");
+ * ```
+ */
+export const forgeDriver = async (
+  query: string,
+  params: unknown[],
+  method: QueryMethod,
+): Promise<ForgeDriverResult> => {
+  const operationType = await getOperationType();
+
+  // Handle DDL operations
+  if (operationType === "DDL") {
+    const result = await withTimeout(sql.executeDDL(inlineParams(query, params)));
+    return await processDDLResult(method, result);
+  }
+
+  // Handle execute method (UPDATE, INSERT, DELETE)
+  if (method === "execute") {
+    return await processExecuteMethod(query, params ?? []);
+  }
+
+  // Handle all method (SELECT)
+  return await processAllMethod(query, params ?? []);
 };

package/src/utils/forgeDriverProxy.ts

@@ -19,6 +19,7 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
     const modifiedQuery = injectSqlHints(query, options);
 
     if (options && logRawSqlQuery && modifiedQuery !== query) {
+      // eslint-disable-next-line no-console
       console.debug("injected Hints: " + modifiedQuery);
     }
     try {
@@ -26,6 +27,7 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
       return await forgeDriver(modifiedQuery, params, method);
     } catch (error) {
       if (logRawSqlQuery) {
+        // eslint-disable-next-line no-console
         console.debug("SQL Error:", JSON.stringify(error));
       }
       throw error;

package/src/utils/metadataContextUtils.ts

@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ForgeSQLMetadata } from "./forgeDriver";
+
+export type MetadataQueryContext = {
+  totalDbExecutionTime: number;
+  totalResponseSize: number;
+  lastMetadata?: ForgeSQLMetadata;
+};
+export const metadataQueryContext = new AsyncLocalStorage<MetadataQueryContext>();
+
+export async function saveMetaDataToContext(metadata: ForgeSQLMetadata): Promise<void> {
+  const context = metadataQueryContext.getStore();
+  if (context && metadata) {
+    context.totalResponseSize += metadata.responseSize;
+    context.totalDbExecutionTime += metadata.dbExecutionTime;
+    context.lastMetadata = metadata;
+  }
+}
+
+export async function getLastestMetadata(): Promise<MetadataQueryContext | undefined> {
+  return metadataQueryContext.getStore();
+}

package/src/utils/requestTypeContextUtils.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export type OperationType = "DML" | "DDL";
+
+export type OperationTypeQueryContext = {
+  operationType: OperationType;
+};
+export const operationTypeQueryContext = new AsyncLocalStorage<OperationTypeQueryContext>();
+
+export async function getOperationType(): Promise<OperationType> {
+  return operationTypeQueryContext.getStore()?.operationType ?? "DML";
+}

package/src/utils/sqlUtils.ts

@@ -329,6 +329,7 @@ export function generateDropTableStatements(
   const dropStatements: string[] = [];
   const validOptions = options ?? { sequence: true, table: true };
   if (!validOptions.sequence && !validOptions.table) {
+    // eslint-disable-next-line no-console
     console.warn('No drop operations requested: both "table" and "sequence" options are false');
     return [];
   }

package/src/webtriggers/applyMigrationsWebTrigger.ts

@@ -31,13 +31,15 @@ export const applySchemaMigrations = async (
     if (typeof migration !== "function") {
       throw new Error("migration is not a function");
     }
-
-    console.log("Provisioning the database");
+    // eslint-disable-next-line no-console
+    console.debug("Provisioning the database");
     await sql._provision();
-    console.info("Running schema migrations");
+    // eslint-disable-next-line no-console
+    console.debug("Running schema migrations");
     const migrations = await migration(migrationRunner);
     const successfulMigrations = await migrations.run();
-    console.info("Migrations applied:", successfulMigrations);
+    // eslint-disable-next-line no-console
+    console.debug("Migrations applied:", successfulMigrations);
 
     const migrationList = await migrationRunner.list();
     let migrationHistory = "No migrations found";
@@ -51,8 +53,8 @@ export const applySchemaMigrations = async (
         .map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`)
         .join("\n");
     }
-
-    console.info("Migrations history:\nid, name, migrated_at\n", migrationHistory);
+    // eslint-disable-next-line no-console
+    console.debug("Migrations history:\nid, name, migrated_at\n", migrationHistory);
 
     return {
       headers: { "Content-Type": ["application/json"] },
@@ -68,6 +70,7 @@ export const applySchemaMigrations = async (
       error?.debug?.context?.message ??
       error.message ??
       "Unknown error occurred";
+    // eslint-disable-next-line no-console
     console.error("Error during migration:", errorMessage);
     return {
       headers: { "Content-Type": ["application/json"] },

package/src/webtriggers/clearCacheSchedulerTrigger.ts

@@ -64,6 +64,7 @@ export const clearCacheSchedulerTrigger = async (options?: ForgeSqlOrmOptions) =
       }),
     };
   } catch (error) {
+    // eslint-disable-next-line no-console
     console.error("Error during cache cleanup: ", JSON.stringify(error));
     return {
       headers: { "Content-Type": ["application/json"] },

package/src/webtriggers/dropMigrationWebTrigger.ts

@@ -34,6 +34,7 @@ export async function dropSchemaMigrations(): Promise<TriggerResponse<string>> {
 
     // Execute each statement
     for (const statement of dropStatements) {
+      // eslint-disable-next-line no-console
       console.debug(`execute DDL: ${statement}`);
       await sql.executeDDL(statement);
     }
@@ -48,6 +49,7 @@ export async function dropSchemaMigrations(): Promise<TriggerResponse<string>> {
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }

package/src/webtriggers/dropTablesMigrationWebTrigger.ts

@@ -34,6 +34,7 @@ export async function dropTableSchemaMigrations(): Promise<TriggerResponse<strin
 
     // Execute each statement
     for (const statement of dropStatements) {
+      // eslint-disable-next-line no-console
       console.debug(`execute DDL: ${statement}`);
       await sql.executeDDL(statement);
     }
@@ -48,6 +49,7 @@ export async function dropTableSchemaMigrations(): Promise<TriggerResponse<strin
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }

package/src/webtriggers/fetchSchemaWebTrigger.ts

@@ -46,6 +46,7 @@ export async function fetchSchemaWebTrigger(): Promise<TriggerResponse<string>>
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }