forge-sql-orm 2.1.5 → 2.1.7

package/src/core/ForgeSQLQueryBuilder.ts

@@ -26,19 +26,20 @@ import {
 } from "./SystemTables";
 import { ForgeSQLCacheOperations } from "./ForgeSQLCacheOperations";
 import {
-    DeleteAndEvictCacheType,
-    ExecuteQuery,
-    ExecuteQueryCacheable, ForgeSQLMetadata,
-    InsertAndEvictCacheType,
-    SelectAliasedCacheableType,
-    SelectAliasedDistinctCacheableType,
-    SelectAliasedDistinctType,
-    SelectAliasedType,
-    SelectAllDistinctFromAliasedType,
-    SelectAllDistinctFromCacheableAliasedType,
-    SelectAllFromAliasedType,
-    SelectAllFromCacheableAliasedType,
-    UpdateAndEvictCacheType,
+  DeleteAndEvictCacheType,
+  ExecuteQuery,
+  ExecuteQueryCacheable,
+  ForgeSQLMetadata,
+  InsertAndEvictCacheType,
+  SelectAliasedCacheableType,
+  SelectAliasedDistinctCacheableType,
+  SelectAliasedDistinctType,
+  SelectAliasedType,
+  SelectAllDistinctFromAliasedType,
+  SelectAllDistinctFromCacheableAliasedType,
+  SelectAllFromAliasedType,
+  SelectAllFromCacheableAliasedType,
+  UpdateAndEvictCacheType,
 } from "..";
 import {
   MySqlDeleteBase,
@@ -519,8 +520,12 @@ export interface QueryBuilderForgeSql {
    * ```
    */
   executeWithMetadata<T>(
-    query: () => Promise<T>, 
-    onMetadata: (totalDbExecutionTime: number, totalResponseSize: number, forgeMetadata: ForgeSQLMetadata) => Promise<void> | void
+    query: () => Promise<T>,
+    onMetadata: (
+      totalDbExecutionTime: number,
+      totalResponseSize: number,
+      forgeMetadata: ForgeSQLMetadata,
+    ) => Promise<void> | void,
   ): Promise<T>;
   /**
    * Executes a raw SQL query with local cache support.
@@ -538,9 +543,100 @@ export interface QueryBuilderForgeSql {
    * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
    * ```
    */
-  execute(
+  execute<T>(
     query: SQLWrapper | string,
-  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>>;
+
+  /**
+   * Executes a Data Definition Language (DDL) SQL query.
+   * DDL operations include CREATE, ALTER, DROP, TRUNCATE, and other schema modification statements.
+   *
+   * This method is specifically designed for DDL operations and provides:
+   * - Proper operation type context for DDL queries
+   * - No caching (DDL operations should not be cached)
+   * - Direct execution without query optimization
+   *
+   * @template T - The expected return type of the query result
+   * @param query - The DDL SQL query to execute (SQLWrapper or string)
+   * @returns Promise with query results
+   * @throws {Error} If the DDL operation fails
+   *
+   * @example
+   * ```typescript
+   * // Create a new table
+   * await forgeSQL.executeDDL(`
+   *   CREATE TABLE users (
+   *     id INT PRIMARY KEY AUTO_INCREMENT,
+   *     name VARCHAR(255) NOT NULL,
+   *     email VARCHAR(255) UNIQUE
+   *   )
+   * `);
+   *
+   * // Alter table structure
+   * await forgeSQL.executeDDL(sql`
+   *   ALTER TABLE users
+   *   ADD COLUMN created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+   * `);
+   *
+   * // Drop a table
+   * await forgeSQL.executeDDL("DROP TABLE IF EXISTS old_users");
+   * ```
+   */
+  executeDDL<T>(
+    query: SQLWrapper | string,
+  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>>;
+
+  /**
+   * Executes a series of actions within a DDL operation context.
+   * This method provides a way to execute regular SQL queries that should be treated
+   * as DDL operations, ensuring proper operation type context for performance monitoring.
+   *
+   * This method is useful for:
+   * - Executing regular SQL queries in DDL context for monitoring purposes
+   * - Wrapping non-DDL operations that should be treated as DDL for analysis
+   * - Ensuring proper operation type context for complex workflows
+   * - Maintaining DDL operation context across multiple function calls
+   *
+   * @template T - The return type of the actions function
+   * @param actions - Function containing SQL operations to execute in DDL context
+   * @returns Promise that resolves to the return value of the actions function
+   *
+   * @example
+   * ```typescript
+   * // Execute regular SQL queries in DDL context for monitoring
+   * await forgeSQL.executeDDLActions(async () => {
+   *   const slowQueries = await forgeSQL.execute(`
+   *     SELECT * FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
+   *     WHERE AVG_LATENCY > 1000000
+   *   `);
+   *   return slowQueries;
+   * });
+   *
+   * // Execute complex analysis queries in DDL context
+   * const result = await forgeSQL.executeDDLActions(async () => {
+   *   const tableInfo = await forgeSQL.execute("SHOW TABLES");
+   *   const performanceData = await forgeSQL.execute(`
+   *     SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY_HISTORY
+   *     WHERE SUMMARY_END_TIME > DATE_SUB(NOW(), INTERVAL 1 HOUR)
+   *   `);
+   *   return { tableInfo, performanceData };
+   * });
+   *
+   * // Execute monitoring queries with error handling
+   * try {
+   *   await forgeSQL.executeDDLActions(async () => {
+   *     const metrics = await forgeSQL.execute(`
+   *       SELECT COUNT(*) as query_count
+   *       FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
+   *     `);
+   *     console.log(`Total queries: ${metrics[0].query_count}`);
+   *   });
+   * } catch (error) {
+   *   console.error("Monitoring query failed:", error);
+   * }
+   * ```
+   */
+  executeDDLActions<T>(actions: () => Promise<T>): Promise<T>;
 
   /**
    * Executes a raw SQL query with both local and global cache support.
@@ -560,10 +656,10 @@ export interface QueryBuilderForgeSql {
    * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
    * ```
    */
-  executeCacheable(
+  executeCacheable<T>(
     query: SQLWrapper | string,
     cacheTtl?: number,
-  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>>;
   /**
    * Creates a Common Table Expression (CTE) builder for complex queries.
    * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
@@ -865,7 +961,7 @@ export interface ForgeSqlOrmOptions {
   /**
    * Additional metadata for table configuration.
    * Allows specifying table-specific settings and behaviors such as version fields for optimistic locking.
-   * 
+   *
    * @example
    * ```typescript
    * {

package/src/core/ForgeSQLSelectOperations.ts

@@ -58,7 +58,7 @@ export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
   async executeRawSQL<T extends object | unknown>(query: string, params?: unknown[]): Promise<T[]> {
     if (this.options.logRawSqlQuery) {
       const paramsStr = params ? `, with params: ${JSON.stringify(params)}` : "";
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug(`Executing with SQL ${query}${paramsStr}`);
     }
     const sqlStatement = sql.prepare<T>(query);
@@ -81,7 +81,7 @@ export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
       sqlStatement.bindParams(...params);
     }
     if (this.options.logRawSqlQuery) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug(
         `Executing Update with SQL ${query}` +
           (params ? `, with params: ${JSON.stringify(params)}` : ""),

package/src/core/SystemTables.ts

@@ -312,6 +312,22 @@ export const clusterStatementsSummaryHistory = informationSchema.table(
 // Types
 export type ClusterStatementsSummaryHistory = typeof clusterStatementsSummaryHistory.$inferSelect;
 
+export const statementsSummaryHistory = informationSchema.table(
+  "STATEMENTS_SUMMARY_HISTORY",
+  createClusterStatementsSummarySchema(),
+);
+
+// Types
+export type StatementsSummaryHistory = typeof statementsSummaryHistory.$inferSelect;
+
+export const statementsSummary = informationSchema.table(
+  "STATEMENTS_SUMMARY",
+  createClusterStatementsSummarySchema(),
+);
+
+// Types
+export type StatementsSummary = typeof statementsSummary.$inferSelect;
+
 export const clusterStatementsSummary = informationSchema.table(
   "CLUSTER_STATEMENTS_SUMMARY",
   createClusterStatementsSummarySchema(),

package/src/lib/drizzle/extensions/additionalActions.ts

@@ -22,9 +22,9 @@ import {
   saveQueryLocalCacheQuery,
   saveTableIfInsideCacheContext,
 } from "../../../utils/cacheContextUtils";
-import { BuildQueryConfig, isSQLWrapper, SQLWrapper } from "drizzle-orm/sql/sql";
+import { isSQLWrapper, SQLWrapper } from "drizzle-orm/sql/sql";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
-import { getTableColumns, Query } from "drizzle-orm";
+import { getTableColumns, Query, SQL } from "drizzle-orm";
 import { MySqlDialect } from "drizzle-orm/mysql-core/dialect";
 import type {
   GetSelectTableName,
@@ -204,17 +204,17 @@ export type SelectAllDistinctFromCacheableAliasedType = <T extends MySqlTable>(
 /**
  * Type for executing raw SQL queries with local cache
  */
-export type ExecuteQuery = (
+export type ExecuteQuery = <T>(
   query: SQLWrapper | string,
-) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>>;
 
 /**
  * Type for executing raw SQL queries with local and global cache
  */
-export type ExecuteQueryCacheable = (
+export type ExecuteQueryCacheable = <T>(
   query: SQLWrapper | string,
   cacheTtl?: number,
-) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>>;
 
 /**
  * Type for insert operations with cache eviction
@@ -260,7 +260,7 @@ async function handleSuccessfulExecution(
     if (isCached && !cacheApplicationContext.getStore()) {
       await clearCache(table, options);
     }
-    const result = onfulfilled?.(rows);
+    const result = onfulfilled ? onfulfilled(rows) : rows;
     return result;
   } catch (error) {
     // Only clear cache for certain types of errors
@@ -268,7 +268,7 @@ async function handleSuccessfulExecution(
       await evictLocalCacheQuery(table, options);
       if (isCached) {
         await clearCache(table, options).catch((e) => {
-            // eslint-disable-next-line no-console
+          // eslint-disable-next-line no-console
           console.warn("Ignore cache clear errors", e);
         });
       } else {
@@ -447,24 +447,27 @@ async function handleCachedQuery(
   try {
     const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
-      return onfulfilled?.(localCached);
+      return onfulfilled ? onfulfilled(localCached) : localCached;
     }
     const cacheResult = await getFromCache(target, options);
     if (cacheResult) {
-      return onfulfilled?.(cacheResult);
+      return onfulfilled ? onfulfilled(cacheResult) : cacheResult;
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
     await saveQueryLocalCacheQuery(target, transformed, options);
     await setCacheResult(target, options, transformed, cacheTtl).catch((cacheError) => {
       // Log cache error but don't fail the query
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.warn("Cache set error:", cacheError);
     });
 
-    return onfulfilled?.(transformed);
+    return onfulfilled ? onfulfilled(transformed) : transformed;
   } catch (error) {
-    return onrejected?.(error);
+    if (onrejected) {
+      return onrejected(error);
+    }
+    throw error;
   }
 }
 
@@ -490,14 +493,17 @@ async function handleNonCachedQuery(
   try {
     const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
-      return onfulfilled?.(localCached);
+      return onfulfilled ? onfulfilled(localCached) : localCached;
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
     await saveQueryLocalCacheQuery(target, transformed, options);
-    return onfulfilled?.(transformed);
+    return onfulfilled ? onfulfilled(transformed) : transformed;
   } catch (error) {
-    return onrejected?.(error);
+    if (onrejected) {
+      return onrejected(error);
+    }
+    throw error;
   }
 }
 
@@ -617,12 +623,8 @@ function createRawQueryExecutor(
     let sql: Query;
 
     if (isSQLWrapper(query)) {
-      const sqlWrapper = query as SQLWrapper;
-      sql = sqlWrapper
-        .getSQL()
-        .toQuery(
-          (db as unknown as { dialect: MySqlDialect }).dialect as unknown as BuildQueryConfig,
-        );
+      const dialect = (db as unknown as { dialect: MySqlDialect }).dialect;
+      sql = dialect.sqlToQuery(query as SQL);
     } else {
       sql = {
         sql: query,

package/src/utils/cacheContextUtils.ts

@@ -104,7 +104,7 @@ export async function saveQueryLocalCacheQuery<
     };
     if (options.logCache) {
       const q = sql.toSQL();
-        // eslint-disable-next-line no-console
+      // 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)}`,
       );
@@ -143,7 +143,7 @@ export async function getQueryLocalCacheQuery<
     if (context.cache[key] && context.cache[key].sql === sql.toSQL().sql.toLowerCase()) {
       if (options.logCache) {
         const q = sql.toSQL();
-          // eslint-disable-next-line no-console
+        // 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

@@ -124,7 +124,7 @@ async function clearCursorCache(
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
   if (options.logCache) {
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
 
@@ -172,7 +172,7 @@ async function clearExpirationCursorCache(
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
   if (options.logCache) {
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
 
@@ -203,12 +203,12 @@ async function executeWithRetry<T>(operation: () => Promise<T>, operationName: s
     try {
       return await operation();
     } catch (err: any) {
-        // eslint-disable-next-line no-console
+      // 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
+        // eslint-disable-next-line no-console
         console.error(`Error during ${operationName}: ${err.message}`, err);
         throw err;
       }
@@ -266,7 +266,7 @@ export async function clearTablesCache(
   } finally {
     if (options.logCache) {
       const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
     }
   }
@@ -293,7 +293,7 @@ export async function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<vo
   } finally {
     const duration = DateTime.now().toSeconds() - startTime.toSeconds();
     if (options?.logCache) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
     }
   }
@@ -325,7 +325,7 @@ export async function getFromCache<T>(
   // Skip cache if table is in cache context (will be cleared)
   if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
     if (options.logCache) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.warn(`Context contains value to clear. Skip getting from cache`);
     }
     return undefined;
@@ -340,14 +340,14 @@ export async function getFromCache<T>(
       sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]
     ) {
       if (options.logCache) {
-          // eslint-disable-next-line no-console
+        // 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
+    // eslint-disable-next-line no-console
     console.error(`Error getting from cache: ${error.message}`, error);
   }
 
@@ -385,7 +385,7 @@ export async function setCacheResult(
     // Skip cache if table is in cache context (will be cleared)
     if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
       if (options.logCache) {
-          // eslint-disable-next-line no-console
+        // eslint-disable-next-line no-console
         console.warn(`Context contains value to clear. Skip setting from cache`);
       }
       return;
@@ -407,11 +407,11 @@ export async function setCacheResult(
       .execute();
 
     if (options.logCache) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.warn(`Store value to cache, cacheKey: ${key}`);
     }
   } catch (error: any) {
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error(`Error setting cache: ${error.message}`, error);
   }
 }