forge-sql-orm 2.0.30 → 2.1.1

package/dist/ForgeSQLORM.mjs

@@ -1,10 +1,13 @@
-import { isTable, sql, eq, and } from "drizzle-orm";
+import { isTable, sql, eq, and, getTableColumns } from "drizzle-orm";
 import { DateTime } from "luxon";
 import { isSQLWrapper } from "drizzle-orm/sql/sql";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getTableName } from "drizzle-orm/table";
+import * as crypto from "crypto";
+import { kvs, WhereConditions, Filter, FilterConditions } from "@forge/kvs";
 import { sql as sql$1, migrationRunner } from "@forge/sql";
 import { drizzle } from "drizzle-orm/mysql-proxy";
 import { customType, mysqlTable, timestamp, varchar, bigint } from "drizzle-orm/mysql-core";
-import { getTableName } from "drizzle-orm/table";
 const parseDateTime = (value, format) => {
   let result;
   if (value instanceof Date) {
@@ -27,6 +30,36 @@ const parseDateTime = (value, format) => {
   }
   return result;
 };
+function formatDateTime(value, format) {
+  let dt = null;
+  if (value instanceof Date) {
+    dt = DateTime.fromJSDate(value);
+  } else if (typeof value === "string") {
+    for (const parser of [
+      DateTime.fromISO,
+      DateTime.fromRFC2822,
+      DateTime.fromSQL,
+      DateTime.fromHTTP
+    ]) {
+      dt = parser(value);
+      if (dt.isValid) break;
+    }
+    if (!dt?.isValid) {
+      const parsed = Number(value);
+      if (!isNaN(parsed)) {
+        dt = DateTime.fromMillis(parsed);
+      }
+    }
+  } else if (typeof value === "number") {
+    dt = DateTime.fromMillis(value);
+  } else {
+    throw new Error("Unsupported type");
+  }
+  if (!dt?.isValid) {
+    throw new Error("Invalid Date");
+  }
+  return dt.toFormat(format);
+}
 function getPrimaryKeys(table) {
   const { columns, primaryKeys } = getTableMetadata(table);
   const columnPrimaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
@@ -289,6 +322,275 @@ function formatLimitOffset(limitOrOffset) {
 function nextVal(sequenceName) {
   return sql.raw(`NEXTVAL(${sequenceName})`);
 }
+const CACHE_CONSTANTS = {
+  BATCH_SIZE: 25,
+  MAX_RETRY_ATTEMPTS: 3,
+  INITIAL_RETRY_DELAY: 1e3,
+  RETRY_DELAY_MULTIPLIER: 2,
+  DEFAULT_ENTITY_QUERY_NAME: "sql",
+  DEFAULT_EXPIRATION_NAME: "expiration",
+  DEFAULT_DATA_NAME: "data",
+  HASH_LENGTH: 32
+};
+function getCurrentTime() {
+  const dt = DateTime.now();
+  return Math.floor(dt.toSeconds());
+}
+function nowPlusSeconds(secondsToAdd) {
+  const dt = DateTime.now().plus({ seconds: secondsToAdd });
+  return Math.floor(dt.toSeconds());
+}
+function hashKey(query) {
+  const h = crypto.createHash("sha256");
+  h.update(query.sql.toLowerCase());
+  h.update(JSON.stringify(query.params));
+  return "CachedQuery_" + h.digest("hex").slice(0, CACHE_CONSTANTS.HASH_LENGTH);
+}
+async function deleteCacheEntriesInBatches(results, cacheEntityName) {
+  for (let i = 0; i < results.length; i += CACHE_CONSTANTS.BATCH_SIZE) {
+    const batch = results.slice(i, i + CACHE_CONSTANTS.BATCH_SIZE);
+    let transactionBuilder = kvs.transact();
+    batch.forEach((result) => {
+      transactionBuilder = transactionBuilder.delete(result.key, { entityName: cacheEntityName });
+    });
+    await transactionBuilder.execute();
+  }
+}
+async function clearCursorCache(tables, cursor, options) {
+  const cacheEntityName = options.cacheEntityName;
+  if (!cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  const entityQueryName = options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+  let filters = new Filter();
+  for (const table of tables) {
+    const wrapIfNeeded = options.cacheWrapTable ? `\`${table}\`` : table;
+    filters.or(entityQueryName, FilterConditions.contains(wrapIfNeeded?.toLowerCase()));
+  }
+  let entityQueryBuilder = kvs.entity(cacheEntityName).query().index(entityQueryName).filters(filters);
+  if (cursor) {
+    entityQueryBuilder = entityQueryBuilder.cursor(cursor);
+  }
+  const listResult = await entityQueryBuilder.limit(100).getMany();
+  if (options.logRawSqlQuery) {
+    console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
+  }
+  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+  if (listResult.nextCursor) {
+    return listResult.results.length + await clearCursorCache(tables, listResult.nextCursor, options);
+  } else {
+    return listResult.results.length;
+  }
+}
+async function clearExpirationCursorCache(cursor, options) {
+  const cacheEntityName = options.cacheEntityName;
+  if (!cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  const entityExpirationName = options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+  let entityQueryBuilder = kvs.entity(cacheEntityName).query().index(entityExpirationName).where(WhereConditions.lessThan(Math.floor(DateTime.now().toSeconds())));
+  if (cursor) {
+    entityQueryBuilder = entityQueryBuilder.cursor(cursor);
+  }
+  const listResult = await entityQueryBuilder.limit(100).getMany();
+  if (options.logRawSqlQuery) {
+    console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
+  }
+  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+  if (listResult.nextCursor) {
+    return listResult.results.length + await clearExpirationCursorCache(listResult.nextCursor, options);
+  } else {
+    return listResult.results.length;
+  }
+}
+async function executeWithRetry(operation, operationName) {
+  let attempt = 0;
+  let delay = CACHE_CONSTANTS.INITIAL_RETRY_DELAY;
+  while (attempt < CACHE_CONSTANTS.MAX_RETRY_ATTEMPTS) {
+    try {
+      return await operation();
+    } catch (err) {
+      console.warn(`Error during ${operationName}: ${err.message}, retry ${attempt}`, err);
+      attempt++;
+      if (attempt >= CACHE_CONSTANTS.MAX_RETRY_ATTEMPTS) {
+        console.error(`Error during ${operationName}: ${err.message}`, err);
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay *= CACHE_CONSTANTS.RETRY_DELAY_MULTIPLIER;
+    }
+  }
+  throw new Error(`Maximum retry attempts exceeded for ${operationName}`);
+}
+async function clearCache(schema, options) {
+  const tableName = getTableName(schema);
+  if (cacheApplicationContext.getStore()) {
+    cacheApplicationContext.getStore()?.tables.add(tableName);
+  } else {
+    await clearTablesCache([tableName], options);
+  }
+}
+async function clearTablesCache(tables, options) {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  const startTime = DateTime.now();
+  let totalRecords = 0;
+  try {
+    totalRecords = await executeWithRetry(
+      () => clearCursorCache(tables, "", options),
+      "clearing cache"
+    );
+  } finally {
+    if (options.logRawSqlQuery) {
+      const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+      console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
+    }
+  }
+}
+async function clearExpiredCache(options) {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  const startTime = DateTime.now();
+  let totalRecords = 0;
+  try {
+    totalRecords = await executeWithRetry(
+      () => clearExpirationCursorCache("", options),
+      "clearing expired cache"
+    );
+  } finally {
+    const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+    console.info(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
+  }
+}
+async function getFromCache(query, options) {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  const entityQueryName = options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+  const expirationName = options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+  const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
+  const sqlQuery = query.toSQL();
+  const key = hashKey(sqlQuery);
+  if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
+    if (options.logRawSqlQuery) {
+      console.warn(`Context contains value to clear. Skip getting from cache`);
+    }
+    return void 0;
+  }
+  try {
+    const cacheResult = await kvs.entity(options.cacheEntityName).get(key);
+    if (cacheResult && cacheResult[expirationName] >= getCurrentTime() && sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]) {
+      if (options.logRawSqlQuery) {
+        console.warn(`Get value from cache, cacheKey: ${key}`);
+      }
+      const results = cacheResult[dataName];
+      return JSON.parse(results);
+    }
+  } catch (error) {
+    console.error(`Error getting from cache: ${error.message}`, error);
+  }
+  return void 0;
+}
+async function setCacheResult(query, options, results, cacheTtl) {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+  try {
+    const entityQueryName = options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+    const expirationName = options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+    const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
+    const sqlQuery = query.toSQL();
+    if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
+      if (options.logRawSqlQuery) {
+        console.warn(`Context contains value to clear. Skip setting from cache`);
+      }
+      return;
+    }
+    const key = hashKey(sqlQuery);
+    await kvs.transact().set(
+      key,
+      {
+        [entityQueryName]: sqlQuery.sql.toLowerCase(),
+        [expirationName]: nowPlusSeconds(cacheTtl),
+        [dataName]: JSON.stringify(results)
+      },
+      { entityName: options.cacheEntityName }
+    ).execute();
+    if (options.logRawSqlQuery) {
+      console.warn(`Store value to cache, cacheKey: ${key}`);
+    }
+  } catch (error) {
+    console.error(`Error setting cache: ${error.message}`, error);
+  }
+}
+const cacheApplicationContext = new AsyncLocalStorage();
+const localCacheApplicationContext = new AsyncLocalStorage();
+async function saveTableIfInsideCacheContext(table) {
+  const context = cacheApplicationContext.getStore();
+  if (context) {
+    const tableName = getTableName(table).toLowerCase();
+    context.tables.add(tableName);
+  }
+}
+async function saveQueryLocalCacheQuery(query, rows) {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const sql2 = query;
+    const key = hashKey(sql2.toSQL());
+    context.cache[key] = {
+      sql: sql2.toSQL().sql.toLowerCase(),
+      data: rows
+    };
+  }
+}
+async function getQueryLocalCacheQuery(query) {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const sql2 = query;
+    const key = hashKey(sql2.toSQL());
+    if (context.cache[key] && context.cache[key].sql === sql2.toSQL().sql.toLowerCase()) {
+      return context.cache[key].data;
+    }
+  }
+  return void 0;
+}
+async function evictLocalCacheQuery(table, options) {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const tableName = getTableName(table);
+    const searchString = options.cacheWrapTable ? `\`${tableName}\`` : tableName;
+    const keyToEvicts = [];
+    Object.keys(context.cache).forEach((key) => {
+      if (context.cache[key].sql.includes(searchString)) {
+        keyToEvicts.push(key);
+      }
+    });
+    keyToEvicts.forEach((key) => delete context.cache[key]);
+  }
+}
+async function isTableContainsTableInCacheContext(sql2, options) {
+  const context = cacheApplicationContext.getStore();
+  if (!context) {
+    return false;
+  }
+  const tables = Array.from(context.tables);
+  const lowerSql = sql2.toLowerCase();
+  return tables.some((table) => {
+    const tablePattern = options.cacheWrapTable ? `\`${table}\`` : table;
+    return lowerSql.includes(tablePattern);
+  });
+}
 class ForgeSQLCrudOperations {
   forgeOperations;
   options;
@@ -305,12 +607,17 @@ class ForgeSQLCrudOperations {
    * Inserts records into the database with optional versioning support.
    * If a version field exists in the schema, versioning is applied.
    *
+   * This method automatically handles:
+   * - Version field initialization for optimistic locking
+   * - Batch insertion for multiple records
+   * - Duplicate key handling with optional updates
+   *
    * @template T - The type of the table schema
-   * @param {T} schema - The entity schema
-   * @param {Partial<InferInsertModel<T>>[]} models - Array of entities to insert
-   * @param {boolean} [updateIfExists=false] - Whether to update existing records
-   * @returns {Promise<number>} The number of inserted rows
-   * @throws {Error} If the insert operation fails
+   * @param schema - The entity schema
+   * @param models - Array of entities to insert
+   * @param updateIfExists - Whether to update existing records (default: false)
+   * @returns Promise that resolves to the number of inserted rows
+   * @throws Error if the insert operation fails
    */
   async insert(schema, models, updateIfExists = false) {
     if (!models?.length) return 0;
@@ -319,25 +626,32 @@ class ForgeSQLCrudOperations {
     const preparedModels = models.map(
       (model) => this.prepareModelWithVersion(model, versionMetadata, columns)
     );
-    const queryBuilder = this.forgeOperations.getDrizzleQueryBuilder().insert(schema).values(preparedModels);
+    const queryBuilder = this.forgeOperations.insert(schema).values(preparedModels);
     const finalQuery = updateIfExists ? queryBuilder.onDuplicateKeyUpdate({
       set: Object.fromEntries(
         Object.keys(preparedModels[0]).map((key) => [key, schema[key]])
       )
     }) : queryBuilder;
     const result = await finalQuery;
+    await saveTableIfInsideCacheContext(schema);
     return result[0].insertId;
   }
   /**
    * Deletes a record by its primary key with optional version check.
    * If versioning is enabled, ensures the record hasn't been modified since last read.
    *
+   * This method automatically handles:
+   * - Single primary key validation
+   * - Optimistic locking checks if versioning is enabled
+   * - Version field validation before deletion
+   *
    * @template T - The type of the table schema
-   * @param {unknown} id - The ID of the record to delete
-   * @param {T} schema - The entity schema
-   * @returns {Promise<number>} Number of affected rows
-   * @throws {Error} If the delete operation fails
-   * @throws {Error} If multiple primary keys are found
+   * @param id - The ID of the record to delete
+   * @param schema - The entity schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if the delete operation fails
+   * @throws Error if multiple primary keys are found
+   * @throws Error if optimistic locking check fails
    */
   async deleteById(id, schema) {
     const { tableName, columns } = getTableMetadata(schema);
@@ -358,8 +672,12 @@ class ForgeSQLCrudOperations {
         conditions.push(eq(versionField, oldModel[versionMetadata.fieldName]));
       }
     }
-    const queryBuilder = this.forgeOperations.getDrizzleQueryBuilder().delete(schema).where(and(...conditions));
+    const queryBuilder = this.forgeOperations.delete(schema).where(and(...conditions));
     const result = await queryBuilder;
+    if (versionMetadata && result[0].affectedRows === 0) {
+      throw new Error(`Optimistic locking failed: record with primary key ${id} has been modified`);
+    }
+    await saveTableIfInsideCacheContext(schema);
     return result[0].affectedRows;
   }
   /**
@@ -369,13 +687,19 @@ class ForgeSQLCrudOperations {
    * - Checks for concurrent modifications
    * - Increments the version on successful update
    *
+   * This method automatically handles:
+   * - Primary key validation
+   * - Version field retrieval and validation
+   * - Optimistic locking conflict detection
+   * - Version field incrementation
+   *
    * @template T - The type of the table schema
-   * @param {Partial<InferInsertModel<T>>} entity - The entity with updated values
-   * @param {T} schema - The entity schema
-   * @returns {Promise<number>} Number of affected rows
-   * @throws {Error} If the primary key is not provided
-   * @throws {Error} If optimistic locking check fails
-   * @throws {Error} If multiple primary keys are found
+   * @param entity - The entity with updated values (must include primary key)
+   * @param schema - The entity schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if the primary key is not provided
+   * @throws Error if optimistic locking check fails
+   * @throws Error if multiple primary keys are found
    */
   async updateById(entity, schema) {
     const { tableName, columns } = getTableMetadata(schema);
@@ -405,13 +729,14 @@ class ForgeSQLCrudOperations {
         conditions.push(eq(versionField, currentVersion));
       }
     }
-    const queryBuilder = this.forgeOperations.getDrizzleQueryBuilder().update(schema).set(updateData).where(and(...conditions));
+    const queryBuilder = this.forgeOperations.update(schema).set(updateData).where(and(...conditions));
     const result = await queryBuilder;
     if (versionMetadata && result[0].affectedRows === 0) {
       throw new Error(
         `Optimistic locking failed: record with primary key ${entity[primaryKeyName]} has been modified`
       );
     }
+    await saveTableIfInsideCacheContext(schema);
     return result[0].affectedRows;
   }
   /**
@@ -430,8 +755,9 @@ class ForgeSQLCrudOperations {
     if (!where) {
       throw new Error("WHERE conditions must be provided");
     }
-    const queryBuilder = this.forgeOperations.getDrizzleQueryBuilder().update(schema).set(updateData).where(where);
+    const queryBuilder = this.forgeOperations.update(schema).set(updateData).where(where);
     const result = await queryBuilder;
+    await saveTableIfInsideCacheContext(schema);
     return result[0].affectedRows;
   }
   // Helper methods
@@ -575,7 +901,7 @@ class ForgeSQLCrudOperations {
     const [versionFieldName, versionFieldColumn] = versionField;
     const primaryKeys = this.getPrimaryKeys(schema);
     const [primaryKeyName, primaryKeyColumn] = primaryKeys[0];
-    const resultQuery = this.forgeOperations.getDrizzleQueryBuilder().select({
+    const resultQuery = this.forgeOperations.select({
       [primaryKeyName]: primaryKeyColumn,
       [versionFieldName]: versionFieldColumn
     }).from(schema).where(eq(primaryKeyColumn, primaryKeyValues[primaryKeyName]));
@@ -720,7 +1046,148 @@ function createForgeDriverProxy(options, logRawSqlQuery) {
     return forgeDriver(modifiedQuery, params, method);
   };
 }
-function createAliasedSelectBuilder(db, fields, selectFn) {
+const NON_CACHE_CLEARING_ERROR_CODES = [
+  "VALIDATION_ERROR",
+  "CONSTRAINT_ERROR"
+];
+const CACHE_CLEARING_ERROR_CODES = [
+  "DEADLOCK",
+  "LOCK_WAIT_TIMEOUT",
+  "CONNECTION_ERROR"
+];
+const NON_CACHE_CLEARING_PATTERNS = [
+  /validation/i,
+  /constraint/i
+];
+const CACHE_CLEARING_PATTERNS = [
+  /timeout/i,
+  /connection/i
+];
+function shouldClearCacheOnError(error) {
+  if (error?.code && NON_CACHE_CLEARING_ERROR_CODES.includes(error.code)) {
+    return false;
+  }
+  if (error?.message && NON_CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))) {
+    return false;
+  }
+  if (error?.code && CACHE_CLEARING_ERROR_CODES.includes(error.code)) {
+    return true;
+  }
+  if (error?.message && CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))) {
+    return true;
+  }
+  return true;
+}
+async function handleSuccessfulExecution(rows, onfulfilled, table, options, isCached) {
+  try {
+    await evictLocalCacheQuery(table, options);
+    await saveTableIfInsideCacheContext(table);
+    if (isCached && !cacheApplicationContext.getStore()) {
+      await clearCache(table, options);
+    }
+    const result = onfulfilled?.(rows);
+    return result;
+  } catch (error) {
+    if (shouldClearCacheOnError(error)) {
+      await evictLocalCacheQuery(table, options);
+      if (isCached) {
+        await clearCache(table, options).catch(() => {
+          console.warn("Ignore cache clear errors");
+        });
+      } else {
+        await saveTableIfInsideCacheContext(table);
+      }
+    }
+    throw error;
+  }
+}
+function handleFunctionCall(value, target, args, table, options, isCached) {
+  const result = value.apply(target, args);
+  if (typeof result === "object" && result !== null && "execute" in result) {
+    return wrapCacheEvictBuilder(result, table, options, isCached);
+  }
+  return result;
+}
+const wrapCacheEvictBuilder = (rawBuilder, table, options, isCached) => {
+  return new Proxy(rawBuilder, {
+    get(target, prop, receiver) {
+      if (prop === "then") {
+        return (onfulfilled, onrejected) => target.execute().then(
+          (rows) => handleSuccessfulExecution(rows, onfulfilled, table, options, isCached),
+          onrejected
+        );
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        return (...args) => handleFunctionCall(value, target, args, table, options, isCached);
+      }
+      return value;
+    }
+  });
+};
+function insertAndEvictCacheBuilder(db, table, options, isCached) {
+  const builder = db.insert(table);
+  return wrapCacheEvictBuilder(
+    builder,
+    table,
+    options,
+    isCached
+  );
+}
+function updateAndEvictCacheBuilder(db, table, options, isCached) {
+  const builder = db.update(table);
+  return wrapCacheEvictBuilder(
+    builder,
+    table,
+    options,
+    isCached
+  );
+}
+function deleteAndEvictCacheBuilder(db, table, options, isCached) {
+  const builder = db.delete(table);
+  return wrapCacheEvictBuilder(
+    builder,
+    table,
+    options,
+    isCached
+  );
+}
+async function handleCachedQuery(target, options, cacheTtl, selections, aliasMap, onfulfilled, onrejected) {
+  try {
+    const localCached = await getQueryLocalCacheQuery(target);
+    if (localCached) {
+      return onfulfilled?.(localCached);
+    }
+    const cacheResult = await getFromCache(target, options);
+    if (cacheResult) {
+      return onfulfilled?.(cacheResult);
+    }
+    const rows = await target.execute();
+    const transformed = applyFromDriverTransform(rows, selections, aliasMap);
+    await saveQueryLocalCacheQuery(target, transformed);
+    await setCacheResult(target, options, transformed, cacheTtl).catch((cacheError) => {
+      console.warn("Cache set error:", cacheError);
+    });
+    return onfulfilled?.(transformed);
+  } catch (error) {
+    return onrejected?.(error);
+  }
+}
+async function handleNonCachedQuery(target, selections, aliasMap, onfulfilled, onrejected) {
+  try {
+    const localCached = await getQueryLocalCacheQuery(target);
+    if (localCached) {
+      return onfulfilled?.(localCached);
+    }
+    const rows = await target.execute();
+    const transformed = applyFromDriverTransform(rows, selections, aliasMap);
+    await saveQueryLocalCacheQuery(target, transformed);
+    return onfulfilled?.(transformed);
+  } catch (error) {
+    return onrejected?.(error);
+  }
+}
+function createAliasedSelectBuilder(db, fields, selectFn, useCache, options, cacheTtl) {
   const { selections, aliasMap } = mapSelectFieldsWithAlias(fields);
   const builder = selectFn(selections);
   const wrapBuilder = (rawBuilder) => {
@@ -733,10 +1200,22 @@ function createAliasedSelectBuilder(db, fields, selectFn) {
           };
         }
         if (prop === "then") {
-          return (onfulfilled, onrejected) => target.execute().then((rows) => {
-            const transformed = applyFromDriverTransform(rows, selections, aliasMap);
-            return onfulfilled?.(transformed);
-          }, onrejected);
+          return (onfulfilled, onrejected) => {
+            if (useCache) {
+              const ttl = cacheTtl ?? options.cacheTTL ?? 120;
+              return handleCachedQuery(
+                target,
+                options,
+                ttl,
+                selections,
+                aliasMap,
+                onfulfilled,
+                onrejected
+              );
+            } else {
+              return handleNonCachedQuery(target, selections, aliasMap, onfulfilled, onrejected);
+            }
+          };
         }
         const value = Reflect.get(target, prop, receiver);
         if (typeof value === "function") {
@@ -754,13 +1233,122 @@ function createAliasedSelectBuilder(db, fields, selectFn) {
   };
   return wrapBuilder(builder);
 }
-function patchDbWithSelectAliased(db) {
+const DEFAULT_OPTIONS = {
+  logRawSqlQuery: false,
+  disableOptimisticLocking: false,
+  cacheTTL: 120,
+  cacheWrapTable: true,
+  cacheEntityQueryName: "sql",
+  cacheEntityExpirationName: "expiration",
+  cacheEntityDataName: "data"
+};
+function createRawQueryExecutor(db, options, useGlobalCache = false) {
+  return async function(query, cacheTtl) {
+    let sql2;
+    if (isSQLWrapper(query)) {
+      const sqlWrapper = query;
+      sql2 = sqlWrapper.getSQL().toQuery(db.dialect);
+    } else {
+      sql2 = {
+        sql: query,
+        params: []
+      };
+    }
+    const localCacheResult = await getQueryLocalCacheQuery(sql2);
+    if (localCacheResult) {
+      return localCacheResult;
+    }
+    if (useGlobalCache) {
+      const cacheResult = await getFromCache({ toSQL: () => sql2 }, options);
+      if (cacheResult) {
+        return cacheResult;
+      }
+    }
+    const results = await db.execute(query);
+    await saveQueryLocalCacheQuery(sql2, results);
+    if (useGlobalCache) {
+      await setCacheResult(
+        { toSQL: () => sql2 },
+        options,
+        results,
+        cacheTtl ?? options.cacheTTL ?? 120
+      );
+    }
+    return results;
+  };
+}
+function patchDbWithSelectAliased(db, options) {
+  const newOptions = { ...DEFAULT_OPTIONS, ...options };
   db.selectAliased = function(fields) {
-    return createAliasedSelectBuilder(db, fields, (selections) => db.select(selections));
+    return createAliasedSelectBuilder(
+      db,
+      fields,
+      (selections) => db.select(selections),
+      false,
+      newOptions
+    );
+  };
+  db.selectAliasedCacheable = function(fields, cacheTtl) {
+    return createAliasedSelectBuilder(
+      db,
+      fields,
+      (selections) => db.select(selections),
+      true,
+      newOptions,
+      cacheTtl
+    );
   };
   db.selectAliasedDistinct = function(fields) {
-    return createAliasedSelectBuilder(db, fields, (selections) => db.selectDistinct(selections));
+    return createAliasedSelectBuilder(
+      db,
+      fields,
+      (selections) => db.selectDistinct(selections),
+      false,
+      newOptions
+    );
+  };
+  db.selectAliasedDistinctCacheable = function(fields, cacheTtl) {
+    return createAliasedSelectBuilder(
+      db,
+      fields,
+      (selections) => db.selectDistinct(selections),
+      true,
+      newOptions,
+      cacheTtl
+    );
+  };
+  db.selectFrom = function(table) {
+    return db.selectAliased(getTableColumns(table)).from(table);
+  };
+  db.selectFromCacheable = function(table, cacheTtl) {
+    return db.selectAliasedCacheable(getTableColumns(table), cacheTtl).from(table);
+  };
+  db.selectDistinctFrom = function(table) {
+    return db.selectAliasedDistinct(getTableColumns(table)).from(table);
+  };
+  db.selectDistinctFromCacheable = function(table, cacheTtl) {
+    return db.selectAliasedDistinctCacheable(getTableColumns(table), cacheTtl).from(table);
+  };
+  db.insertWithCacheContext = function(table) {
+    return insertAndEvictCacheBuilder(db, table, newOptions, false);
+  };
+  db.insertAndEvictCache = function(table) {
+    return insertAndEvictCacheBuilder(db, table, newOptions, true);
+  };
+  db.updateWithCacheContext = function(table) {
+    return updateAndEvictCacheBuilder(db, table, newOptions, false);
+  };
+  db.updateAndEvictCache = function(table) {
+    return updateAndEvictCacheBuilder(db, table, newOptions, true);
   };
+  db.deleteWithCacheContext = function(table) {
+    return deleteAndEvictCacheBuilder(db, table, newOptions, false);
+  };
+  db.deleteAndEvictCache = function(table) {
+    return deleteAndEvictCacheBuilder(db, table, newOptions, true);
+  };
+  db.executeQuery = createRawQueryExecutor(db, newOptions, false);
+  db.executeQueryCacheable = createRawQueryExecutor(db, newOptions, true);
   return db;
 }
 class ForgeSQLAnalyseOperation {
@@ -911,14 +1499,14 @@ class ForgeSQLAnalyseOperation {
    * @returns {string} The SQL query for cluster statement history
    */
   buildClusterStatementQuery(tables, from, to) {
-    const formatDateTime = (date) => DateTime.fromJSDate(date).toFormat("yyyy-LL-dd'T'HH:mm:ss.SSS");
+    const formatDateTime2 = (date) => DateTime.fromJSDate(date).toFormat("yyyy-LL-dd'T'HH:mm:ss.SSS");
     const tableConditions = tables.map((table) => `TABLE_NAMES LIKE CONCAT(SCHEMA_NAME, '.', '%', '${table}', '%')`).join(" OR ");
     const timeConditions = [];
     if (from) {
-      timeConditions.push(`SUMMARY_BEGIN_TIME >= '${formatDateTime(from)}'`);
+      timeConditions.push(`SUMMARY_BEGIN_TIME >= '${formatDateTime2(from)}'`);
     }
     if (to) {
-      timeConditions.push(`SUMMARY_END_TIME <= '${formatDateTime(to)}'`);
+      timeConditions.push(`SUMMARY_END_TIME <= '${formatDateTime2(to)}'`);
     }
     let whereClauses;
     if (tableConditions?.length) {
@@ -991,12 +1579,167 @@ class ForgeSQLAnalyseOperation {
     return this.analyzeQueriesHistoryRaw(tableNames, fromDate, toDate);
   }
 }
+class ForgeSQLCacheOperations {
+  options;
+  forgeOperations;
+  /**
+   * Creates a new instance of ForgeSQLCacheOperations.
+   *
+   * @param options - Configuration options for the ORM
+   * @param forgeOperations - The ForgeSQL operations instance
+   */
+  constructor(options, forgeOperations) {
+    this.options = options;
+    this.forgeOperations = forgeOperations;
+  }
+  /**
+   * Evicts cache for multiple tables using Drizzle table objects.
+   *
+   * @param tables - Array of Drizzle table objects to clear cache for
+   * @returns Promise that resolves when cache eviction is complete
+   * @throws Error if cacheEntityName is not configured
+   */
+  async evictCacheEntities(tables) {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await this.evictCache(tables.map((t) => getTableName(t)));
+  }
+  /**
+   * Evicts cache for multiple tables by their names.
+   *
+   * @param tables - Array of table names to clear cache for
+   * @returns Promise that resolves when cache eviction is complete
+   * @throws Error if cacheEntityName is not configured
+   */
+  async evictCache(tables) {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await clearTablesCache(tables, this.options);
+  }
+  /**
+   * Inserts records with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().insert()` internally, providing:
+   * - Automatic version field initialization
+   * - Optimistic locking support
+   * - Cache eviction after successful operation
+   *
+   * @param schema - The table schema
+   * @param models - Array of entities to insert
+   * @param updateIfExists - Whether to update existing records
+   * @returns Promise that resolves to the number of inserted rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async insert(schema, models, updateIfExists) {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().insert(schema, models, updateIfExists);
+    await clearCache(schema, this.options);
+    return number;
+  }
+  /**
+   * Deletes a record by ID with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().deleteById()` internally, providing:
+   * - Optimistic locking checks before deletion
+   * - Version field validation
+   * - Cache eviction after successful operation
+   *
+   * @param id - The ID of the record to delete
+   * @param schema - The table schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async deleteById(id, schema) {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().deleteById(id, schema);
+    await clearCache(schema, this.options);
+    return number;
+  }
+  /**
+   * Updates a record by ID with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().updateById()` internally, providing:
+   * - Optimistic locking checks before update
+   * - Version field incrementation
+   * - Cache eviction after successful operation
+   *
+   * @param entity - The entity with updated values (must include primary key)
+   * @param schema - The table schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async updateById(entity, schema) {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().updateById(entity, schema);
+    await clearCache(schema, this.options);
+    return number;
+  }
+  /**
+   * Updates fields based on conditions with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().updateFields()` internally, providing:
+   * - Optimistic locking support (if version field is configured)
+   * - Version field validation and incrementation
+   * - Cache eviction after successful operation
+   *
+   * @param updateData - The data to update
+   * @param schema - The table schema
+   * @param where - Optional WHERE conditions
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async updateFields(updateData, schema, where) {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().updateFields(updateData, schema, where);
+    await clearCache(schema, this.options);
+    return number;
+  }
+  /**
+   * Executes a query with caching support.
+   * First checks cache, if not found executes query and stores result in cache.
+   *
+   * @param query - The Drizzle query to execute
+   * @param cacheTtl - Optional cache TTL override
+   * @returns Promise that resolves to the query results
+   * @throws Error if cacheEntityName is not configured
+   */
+  async executeQuery(query, cacheTtl) {
+    this.validateCacheConfiguration();
+    const sqlQuery = query;
+    const cacheResult = await getFromCache(sqlQuery, this.options);
+    if (cacheResult) {
+      return cacheResult;
+    }
+    const results = await query;
+    await setCacheResult(sqlQuery, this.options, results, cacheTtl ?? this.options.cacheTTL ?? 60);
+    return results;
+  }
+  /**
+   * Validates that cache configuration is properly set up.
+   *
+   * @throws Error if cacheEntityName is not configured
+   * @private
+   */
+  validateCacheConfiguration() {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+  }
+}
 class ForgeSQLORMImpl {
   static instance = null;
   drizzle;
   crudOperations;
   fetchOperations;
   analyzeOperations;
+  cacheOperations;
+  options;
   /**
    * Private constructor to enforce singleton behavior.
    * @param options - Options for configuring ForgeSQL ORM behavior.
@@ -1005,28 +1748,185 @@ class ForgeSQLORMImpl {
     try {
       const newOptions = options ?? {
         logRawSqlQuery: false,
-        disableOptimisticLocking: false
+        disableOptimisticLocking: false,
+        cacheWrapTable: true,
+        cacheTTL: 120,
+        cacheEntityQueryName: "sql",
+        cacheEntityExpirationName: "expiration",
+        cacheEntityDataName: "data"
       };
+      this.options = newOptions;
       if (newOptions.logRawSqlQuery) {
         console.debug("Initializing ForgeSQLORM...");
       }
       const proxiedDriver = createForgeDriverProxy(newOptions.hints, newOptions.logRawSqlQuery);
       this.drizzle = patchDbWithSelectAliased(
-        drizzle(proxiedDriver, { logger: newOptions.logRawSqlQuery })
+        drizzle(proxiedDriver, { logger: newOptions.logRawSqlQuery }),
+        newOptions
       );
       this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
       this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
       this.analyzeOperations = new ForgeSQLAnalyseOperation(this);
+      this.cacheOperations = new ForgeSQLCacheOperations(newOptions, this);
     } catch (error) {
       console.error("ForgeSQLORM initialization failed:", error);
       throw error;
     }
   }
+  /**
+   * 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.
+   * Queries executed within this context will bypass cache for tables that were marked for clearing.
+   *
+   * This is useful for:
+   * - Batch operations that affect multiple tables
+   * - Transaction-like operations where you want to clear cache only at the end
+   * - Performance optimization by reducing cache clear operations
+   *
+   * @param cacheContext - Function containing operations that may trigger cache evictions
+   * @returns Promise that resolves when all operations and cache clearing are complete
+   *
+   * @example
+   * ```typescript
+   * await forgeSQL.executeWithCacheContext(async () => {
+   *   await forgeSQL.modifyWithVersioning().insert(users, userData);
+   *   await forgeSQL.modifyWithVersioning().insert(orders, orderData);
+   *   // Cache for both users and orders tables will be cleared at the end
+   * });
+   * ```
+   */
+  executeWithCacheContext(cacheContext) {
+    return this.executeWithCacheContextAndReturnValue(cacheContext);
+  }
+  /**
+   * Executes operations within a cache context and returns a value.
+   * All clearCache calls within the context are collected and executed in batch at the end.
+   * Queries executed within this context will bypass cache for tables that were marked for clearing.
+   *
+   * @param cacheContext - Function containing operations that may trigger cache evictions
+   * @returns Promise that resolves to the return value of the cacheContext function
+   *
+   * @example
+   * ```typescript
+   * const result = await forgeSQL.executeWithCacheContextAndReturnValue(async () => {
+   *   await forgeSQL.modifyWithVersioning().insert(users, userData);
+   *   return await forgeSQL.fetch().executeQueryOnlyOne(selectUserQuery);
+   * });
+   * ```
+   */
+  async executeWithCacheContextAndReturnValue(cacheContext) {
+    return await this.executeWithLocalCacheContextAndReturnValue(
+      async () => await cacheApplicationContext.run(cacheApplicationContext.getStore() ?? { tables: /* @__PURE__ */ new Set() }, async () => {
+        try {
+          return await cacheContext();
+        } finally {
+          await clearTablesCache(
+            Array.from(cacheApplicationContext.getStore()?.tables ?? []),
+            this.options
+          );
+        }
+      })
+    );
+  }
+  /**
+   * Executes operations within a local cache context and returns a value.
+   * This provides in-memory caching for select queries within a single request scope.
+   * 
+   * @param cacheContext - Function containing operations that will benefit from local caching
+   * @returns Promise that resolves to the return value of the cacheContext function
+   */
+  async executeWithLocalCacheContextAndReturnValue(cacheContext) {
+    return await localCacheApplicationContext.run(localCacheApplicationContext.getStore() ?? { cache: {} }, async () => {
+      return await cacheContext();
+    });
+  }
+  /**
+   * Executes operations within a local cache context.
+   * This provides in-memory caching for select queries within a single request scope.
+   * 
+   * @param cacheContext - Function containing operations that will benefit from local caching
+   * @returns Promise that resolves when all operations are complete
+   */
+  executeWithLocalContext(cacheContext) {
+    return this.executeWithLocalCacheContextAndReturnValue(cacheContext);
+  }
+  /**
+   * Creates an insert query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+   *
+   * @param table - The table to insert into
+   * @returns Insert query builder (no versioning, no cache management)
+   */
+  insert(table) {
+    return this.drizzle.insertWithCacheContext(table);
+  }
+  /**
+   * Creates an insert query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+   *
+   * @param table - The table to insert into
+   * @returns Insert query builder with automatic cache eviction (no versioning)
+   */
+  insertAndEvictCache(table) {
+    return this.drizzle.insertAndEvictCache(table);
+  }
+  /**
+   * Creates an update query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+   *
+   * @param table - The table to update
+   * @returns Update query builder with automatic cache eviction (no versioning)
+   */
+  updateAndEvictCache(table) {
+    return this.drizzle.updateAndEvictCache(table);
+  }
+  /**
+   * Creates an update query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+   *
+   * @param table - The table to update
+   * @returns Update query builder (no versioning, no cache management)
+   */
+  update(table) {
+    return this.drizzle.updateWithCacheContext(table);
+  }
+  /**
+   * Creates a delete query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+   *
+   * @param table - The table to delete from
+   * @returns Delete query builder (no versioning, no cache management)
+   */
+  delete(table) {
+    return this.drizzle.deleteWithCacheContext(table);
+  }
+  /**
+   * Creates a delete query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+   *
+   * @param table - The table to delete from
+   * @returns Delete query builder with automatic cache eviction (no versioning)
+   */
+  deleteAndEvictCache(table) {
+    return this.drizzle.deleteAndEvictCache(table);
+  }
   /**
    * Create the modify operations instance.
    * @returns modify operations.
    */
-  modify() {
+  modifyWithVersioning() {
     return this.crudOperations;
   }
   /**
@@ -1038,13 +1938,6 @@ class ForgeSQLORMImpl {
     ForgeSQLORMImpl.instance ??= new ForgeSQLORMImpl(options);
     return ForgeSQLORMImpl.instance;
   }
-  /**
-   * Retrieves the CRUD operations instance.
-   * @returns CRUD operations.
-   */
-  crud() {
-    return this.modify();
-  }
   /**
    * Retrieves the fetch operations instance.
    * @returns Fetch operations.
@@ -1052,9 +1945,26 @@ class ForgeSQLORMImpl {
   fetch() {
     return this.fetchOperations;
   }
+  /**
+   * Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
+   * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
+   */
   analyze() {
     return this.analyzeOperations;
   }
+  /**
+   * Provides schema-level SQL operations with optimistic locking/versioning and automatic cache eviction.
+   *
+   * This method returns operations that use `modifyWithVersioning()` internally, providing:
+   * - Optimistic locking support
+   * - Automatic version field management
+   * - Cache eviction after successful operations
+   *
+   * @returns {ForgeSQLCacheOperations} Interface for executing versioned SQL operations with cache management
+   */
+  modifyWithVersioningAndEvictCache() {
+    return this.cacheOperations;
+  }
   /**
    * Returns a Drizzle query builder instance.
    *
@@ -1111,12 +2021,365 @@ class ForgeSQLORMImpl {
     }
     return this.drizzle.selectAliasedDistinct(fields);
   }
+  /**
+   * Creates a cacheable select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   *
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @param {number} cacheTTL - cache ttl optional default is 60 sec.
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .selectCacheable({user: users, order: orders},60)
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  selectCacheable(fields, cacheTTL) {
+    if (!fields) {
+      throw new Error("fields is empty");
+    }
+    return this.drizzle.selectAliasedCacheable(fields, cacheTTL);
+  }
+  /**
+   * Creates a cacheable distinct select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   *
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @param {number} cacheTTL - cache ttl optional default is 60 sec.
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .selectDistinctCacheable({user: users, order: orders}, 60)
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  selectDistinctCacheable(fields, cacheTTL) {
+    if (!fields) {
+      throw new Error("fields is empty");
+    }
+    return this.drizzle.selectAliasedDistinctCacheable(fields, cacheTTL);
+  }
+  /**
+   * Creates a select query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectFrom(table) {
+    return this.drizzle.selectFrom(table);
+  }
+  /**
+   * Creates a select distinct query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select distinct query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctFrom(table) {
+    return this.drizzle.selectDistinctFrom(table);
+  }
+  /**
+   * Creates a cacheable select query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectCacheableFrom(userTable, 300).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectCacheableFrom(table, cacheTTL) {
+    return this.drizzle.selectFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select distinct query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctCacheableFrom(table, cacheTTL) {
+    return this.drizzle.selectDistinctFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Executes a raw SQL query with local cache support.
+   * This method provides local caching for raw SQL queries within the current invocation context.
+   * Results are cached locally and will be returned from cache on subsequent identical queries.
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper
+   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+   * 
+   * // Using string
+   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  execute(query) {
+    return this.drizzle.executeQuery(query);
+  }
+  /**
+   * Executes a raw SQL query with both local and global cache support.
+   * This method provides comprehensive caching for raw SQL queries:
+   * - Local cache: Within the current invocation context
+   * - Global cache: Cross-invocation caching using @forge/kvs
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @param cacheTtl - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper with custom TTL
+   * const result = await forgeSQL.executeCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
+   * 
+   * // Using string with default TTL
+   * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  executeCacheable(query, cacheTtl) {
+    return this.drizzle.executeQueryCacheable(query, cacheTtl);
+  }
+  /**
+   * 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.
+   *
+   * @returns WithBuilder for creating CTEs
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * ```
+   */
+  get $with() {
+    return this.drizzle.$with;
+  }
+  /**
+   * Creates a query builder that uses Common Table Expressions (CTEs).
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @param queries - Array of CTE queries created with $with()
+   * @returns Query builder with CTE support
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * 
+   * const result = await forgeSQL.with(withQuery)
+   *   .select({ userId: withQuery.userId, count: withQuery.count })
+   *   .from(withQuery);
+   * ```
+   */
+  with(...queries) {
+    return this.drizzle.with(...queries);
+  }
 }
 class ForgeSQLORM {
   ormInstance;
   constructor(options) {
     this.ormInstance = ForgeSQLORMImpl.getInstance(options);
   }
+  selectCacheable(fields, cacheTTL) {
+    return this.ormInstance.selectCacheable(fields, cacheTTL);
+  }
+  selectDistinctCacheable(fields, cacheTTL) {
+    return this.ormInstance.selectDistinctCacheable(fields, cacheTTL);
+  }
+  /**
+   * Creates a select query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectFrom(table) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectFrom(table);
+  }
+  /**
+   * Creates a select distinct query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select distinct query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctFrom(table) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFrom(table);
+  }
+  /**
+   * Creates a cacheable select query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectCacheableFrom(userTable, 300).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectCacheableFrom(table, cacheTTL) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select distinct query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctCacheableFrom(table, cacheTTL) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFromCacheable(table, cacheTTL);
+  }
+  executeWithCacheContext(cacheContext) {
+    return this.ormInstance.executeWithCacheContext(cacheContext);
+  }
+  executeWithCacheContextAndReturnValue(cacheContext) {
+    return this.ormInstance.executeWithCacheContextAndReturnValue(cacheContext);
+  }
+  /**
+   * Executes operations within a local cache context.
+   * This provides in-memory caching for select queries within a single request scope.
+   * 
+   * @param cacheContext - Function containing operations that will benefit from local caching
+   * @returns Promise that resolves when all operations are complete
+   */
+  executeWithLocalContext(cacheContext) {
+    return this.ormInstance.executeWithLocalContext(cacheContext);
+  }
+  /**
+   * Executes operations within a local cache context and returns a value.
+   * This provides in-memory caching for select queries within a single request scope.
+   * 
+   * @param cacheContext - Function containing operations that will benefit from local caching
+   * @returns Promise that resolves to the return value of the cacheContext function
+   */
+  executeWithLocalCacheContextAndReturnValue(cacheContext) {
+    return this.ormInstance.executeWithLocalCacheContextAndReturnValue(cacheContext);
+  }
+  /**
+   * Creates an insert query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+   *
+   * @param table - The table to insert into
+   * @returns Insert query builder (no versioning, no cache management)
+   */
+  insert(table) {
+    return this.ormInstance.insert(table);
+  }
+  /**
+   * Creates an insert query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+   *
+   * @param table - The table to insert into
+   * @returns Insert query builder with automatic cache eviction (no versioning)
+   */
+  insertAndEvictCache(table) {
+    return this.ormInstance.insertAndEvictCache(table);
+  }
+  /**
+   * Creates an update query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+   *
+   * @param table - The table to update
+   * @returns Update query builder (no versioning, no cache management)
+   */
+  update(table) {
+    return this.ormInstance.update(table);
+  }
+  /**
+   * Creates an update query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+   *
+   * @param table - The table to update
+   * @returns Update query builder with automatic cache eviction (no versioning)
+   */
+  updateAndEvictCache(table) {
+    return this.ormInstance.updateAndEvictCache(table);
+  }
+  /**
+   * Creates a delete query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+   *
+   * @param table - The table to delete from
+   * @returns Delete query builder (no versioning, no cache management)
+   */
+  delete(table) {
+    return this.ormInstance.delete(table);
+  }
+  /**
+   * Creates a delete query builder that automatically evicts cache after execution.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+   *
+   * @param table - The table to delete from
+   * @returns Delete query builder with automatic cache eviction (no versioning)
+   */
+  deleteAndEvictCache(table) {
+    return this.ormInstance.deleteAndEvictCache(table);
+  }
   /**
    * Creates a select query with unique field aliases to prevent field name collisions in joins.
    * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
@@ -1155,19 +2418,12 @@ class ForgeSQLORM {
   selectDistinct(fields) {
     return this.ormInstance.selectDistinct(fields);
   }
-  /**
-   * Proxies the `crud` method from `ForgeSQLORMImpl`.
-   * @returns CRUD operations.
-   */
-  crud() {
-    return this.ormInstance.modify();
-  }
   /**
    * Proxies the `modify` method from `ForgeSQLORMImpl`.
    * @returns Modify operations.
    */
-  modify() {
-    return this.ormInstance.modify();
+  modifyWithVersioning() {
+    return this.ormInstance.modifyWithVersioning();
   }
   /**
    * Proxies the `fetch` method from `ForgeSQLORMImpl`.
@@ -1183,25 +2439,107 @@ class ForgeSQLORM {
   analyze() {
     return this.ormInstance.analyze();
   }
+  /**
+   * Provides schema-level SQL cacheable operations with type safety.
+   * @returns {ForgeSQLCacheOperations} Interface for executing schema-bound SQL queries
+   */
+  modifyWithVersioningAndEvictCache() {
+    return this.ormInstance.modifyWithVersioningAndEvictCache();
+  }
   /**
    * Returns a Drizzle query builder instance.
    *
-   * ⚠️ IMPORTANT: This method should be used ONLY for query building purposes.
-   * The returned instance should NOT be used for direct database connections or query execution.
-   * All database operations should be performed through Forge SQL's executeRawSQL or executeRawUpdateSQL methods.
-   *
    * @returns A Drizzle query builder instance for query construction only.
    */
   getDrizzleQueryBuilder() {
     return this.ormInstance.getDrizzleQueryBuilder();
   }
+  /**
+   * Executes a raw SQL query with local cache support.
+   * This method provides local caching for raw SQL queries within the current invocation context.
+   * Results are cached locally and will be returned from cache on subsequent identical queries.
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper
+   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+   * 
+   * // Using string
+   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  execute(query) {
+    return this.ormInstance.getDrizzleQueryBuilder().executeQuery(query);
+  }
+  /**
+   * Executes a raw SQL query with both local and global cache support.
+   * This method provides comprehensive caching for raw SQL queries:
+   * - Local cache: Within the current invocation context
+   * - Global cache: Cross-invocation caching using @forge/kvs
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @param cacheTtl - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper with custom TTL
+   * const result = await forgeSQL.executeCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
+   * 
+   * // Using string with default TTL
+   * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  executeCacheable(query, cacheTtl) {
+    return this.ormInstance.getDrizzleQueryBuilder().executeQueryCacheable(query, cacheTtl);
+  }
+  /**
+   * 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.
+   *
+   * @returns WithBuilder for creating CTEs
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * ```
+   */
+  get $with() {
+    return this.ormInstance.getDrizzleQueryBuilder().$with;
+  }
+  /**
+   * Creates a query builder that uses Common Table Expressions (CTEs).
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @param queries - Array of CTE queries created with $with()
+   * @returns Query builder with CTE support
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * 
+   * const result = await forgeSQL.with(withQuery)
+   *   .select({ userId: withQuery.userId, count: withQuery.count })
+   *   .from(withQuery);
+   * ```
+   */
+  with(...queries) {
+    return this.ormInstance.getDrizzleQueryBuilder().with(...queries);
+  }
 }
 const forgeDateTimeString = customType({
   dataType() {
     return "datetime";
   },
   toDriver(value) {
-    return DateTime.fromJSDate(new Date(value)).toFormat("yyyy-LL-dd'T'HH:mm:ss.SSS");
+    return formatDateTime(value, "yyyy-LL-dd' 'HH:mm:ss.SSS");
   },
   fromDriver(value) {
     const format = "yyyy-LL-dd'T'HH:mm:ss.SSS";
@@ -1213,7 +2551,7 @@ const forgeTimestampString = customType({
     return "timestamp";
   },
   toDriver(value) {
-    return DateTime.fromJSDate(value).toFormat("yyyy-LL-dd'T'HH:mm:ss.SSS");
+    return formatDateTime(value, "yyyy-LL-dd' 'HH:mm:ss.SSS");
   },
   fromDriver(value) {
     const format = "yyyy-LL-dd'T'HH:mm:ss.SSS";
@@ -1225,7 +2563,7 @@ const forgeDateString = customType({
     return "date";
   },
   toDriver(value) {
-    return DateTime.fromJSDate(value).toFormat("yyyy-LL-dd");
+    return formatDateTime(value, "yyyy-LL-dd");
   },
   fromDriver(value) {
     const format = "yyyy-LL-dd";
@@ -1237,7 +2575,7 @@ const forgeTimeString = customType({
     return "time";
   },
   toDriver(value) {
-    return DateTime.fromJSDate(value).toFormat("HH:mm:ss.SSS");
+    return formatDateTime(value, "HH:mm:ss.SSS");
   },
   fromDriver(value) {
     return parseDateTime(value, "HH:mm:ss.SSS");
@@ -1354,6 +2692,45 @@ async function dropTableSchemaMigrations() {
     return getHttpResponse(500, errorMessage);
   }
 }
+const clearCacheSchedulerTrigger = async (options) => {
+  try {
+    const newOptions = options ?? {
+      logRawSqlQuery: false,
+      disableOptimisticLocking: false,
+      cacheTTL: 120,
+      cacheEntityName: "cache",
+      cacheEntityQueryName: "sql",
+      cacheEntityExpirationName: "expiration",
+      cacheEntityDataName: "data"
+    };
+    if (!newOptions.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await clearExpiredCache(newOptions);
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 200,
+      statusText: "OK",
+      body: JSON.stringify({
+        success: true,
+        message: "Cache cleanup completed successfully",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    };
+  } catch (error) {
+    console.error("Error during cache cleanup: ", JSON.stringify(error));
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 500,
+      statusText: "Internal Server Error",
+      body: JSON.stringify({
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error during cache cleanup",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    };
+  }
+};
 const getHttpResponse = (statusCode, body) => {
   let statusText = "";
   if (statusCode === 200) {
@@ -1373,6 +2750,7 @@ export {
   ForgeSQLSelectOperations,
   applyFromDriverTransform,
   applySchemaMigrations,
+  clearCacheSchedulerTrigger,
   ForgeSQLORM as default,
   dropSchemaMigrations,
   dropTableSchemaMigrations,
@@ -1383,6 +2761,7 @@ export {
   forgeSystemTables,
   forgeTimeString,
   forgeTimestampString,
+  formatDateTime,
   formatLimitOffset,
   generateDropTableStatements,
   getHttpResponse,