forge-sql-orm 2.0.30 → 2.1.1

package/README.md

@@ -17,8 +17,13 @@
 
 ## Key Features
 - ✅ **Custom Drizzle Driver** for direct integration with @forge/sql
+- ✅ **Local Cache System (Level 1)** for in-memory query optimization within single resolver invocation scope
+- ✅ **Global Cache System (Level 2)** with cross-invocation caching, automatic cache invalidation and context-aware operations (using [@forge/kvs](https://developer.atlassian.com/platform/forge/storage-reference/storage-api-custom-entities/) )
 - ✅ **Type-Safe Query Building**: Write SQL queries with full TypeScript support
 - ✅ **Supports complex SQL queries** with joins and filtering using Drizzle ORM
+- ✅ **Advanced Query Methods**: `selectFrom()`, `selectDistinctFrom()`, `selectCacheableFrom()`, `selectDistinctCacheableFrom()` for all-column queries with field aliasing
+- ✅ **Raw SQL Execution**: `execute()` and `executeCacheable()` methods for direct SQL queries with local and global caching
+- ✅ **Common Table Expressions (CTEs)**: `with()` method for complex queries with subqueries
 - ✅ **Schema migration support**, allowing automatic schema evolution
 - ✅ **Automatic entity generation** from MySQL/tidb databases
 - ✅ **Automatic migration generation** from MySQL/tidb databases
@@ -26,24 +31,129 @@
 - ✅ **Schema Fetching** Development-only web trigger to retrieve current database schema and generate SQL statements for schema recreation
 - ✅ **Ready-to-use Migration Triggers** Built-in web triggers for applying migrations, dropping tables (development-only), and fetching schema (development-only) with proper error handling and security controls
 - ✅ **Optimistic Locking** Ensures data consistency by preventing conflicts when multiple users update the same record
-- ✅ **Query Plan Analysis**: Detailed execution plan analysis and optimization insights (Performance analysis and Troubleshooting only)
+- ✅ **Query Plan Analysis**: Detailed execution plan analysis and optimization insights
+
+## Table of Contents
+
+### 🚀 Getting Started
+- [Key Features](#key-features)
+- [Usage Approaches](#usage-approaches)
+- [Installation](#installation)
+- [CLI Commands](#cli-commands) | [CLI Documentation](forge-sql-orm-cli/README.md)
+- [Quick Start](#quick-start)
+
+### 📖 Core Features
+- [Field Name Collision Prevention](#field-name-collision-prevention-in-complex-queries)
+- [Drizzle Usage with forge-sql-orm](#drizzle-usage-with-forge-sql-orm)
+- [Direct Drizzle Usage with Custom Driver](#direct-drizzle-usage-with-custom-driver)
+
+### 🗄️ Database Operations
+- [Fetch Data](#fetch-data)
+- [Modify Operations](#modify-operations)
+- [SQL Utilities](#sql-utilities)
+
+### ⚡ Caching System
+- [Setting Up Caching with @forge/kvs](#setting-up-caching-with-forgekvs-optional)
+- [Global Cache System (Level 2)](#global-cache-system-level-2)
+- [Cache Context Operations](#cache-context-operations)
+- [Local Cache Operations (Level 1)](#local-cache-operations-level-1)
+- [Cache-Aware Query Operations](#cache-aware-query-operations)
+- [Manual Cache Management](#manual-cache-management)
+
+### 🔒 Advanced Features
+- [Optimistic Locking](#optimistic-locking)
+- [Query Analysis and Performance Optimization](#query-analysis-and-performance-optimization)
+- [Date and Time Types](#date-and-time-types)
+
+### 🛠️ Development Tools
+- [CLI Commands](#cli-commands) | [CLI Documentation](forge-sql-orm-cli/README.md)
+- [Web Triggers for Migrations](#web-triggers-for-migrations)
+- [Step-by-Step Migration Workflow](#step-by-step-migration-workflow)
+- [Drop Migrations](#drop-migrations)
+
+### 📚 Examples
+- [Simple Example](examples/forge-sql-orm-example-simple)
+- [Drizzle Driver Example](examples/forge-sql-orm-example-drizzle-driver-simple)
+- [Optimistic Locking Example](examples/forge-sql-orm-example-optimistic-locking)
+- [Dynamic Queries Example](examples/forge-sql-orm-example-dynamic)
+- [Query Analysis Example](examples/forge-sql-orm-example-query-analyses)
+- [Organization Tracker Example](examples/forge-sql-orm-example-org-tracker)
+- [Checklist Example](examples/forge-sql-orm-example-checklist)
+
+### 📚 Reference
+- [ForgeSqlOrmOptions](#forgesqlormoptions)
+- [Migration Guide](#migration-guide)
+
+## 🚀 Quick Navigation
+
+**New to Forge-SQL-ORM?** Start here:
+- [Quick Start](#quick-start) - Get up and running in 5 minutes
+- [Installation](#installation) - Complete setup guide
+- [Basic Usage Examples](#fetch-data) - Simple query examples
+
+**Looking for specific features?**
+- [Global Cache System (Level 2)](#global-cache-system-level-2) - Cross-invocation persistent caching
+- [Local Cache System (Level 1)](#local-cache-operations-level-1) - In-memory invocation caching
+- [Optimistic Locking](#optimistic-locking) - Data consistency
+- [Migration Tools](#web-triggers-for-migrations) - Database migrations
+- [Query Analysis](#query-analysis-and-performance-optimization) - Performance optimization
+
+**Looking for practical examples?**
+- [Simple Example](examples/forge-sql-orm-example-simple) - Basic ORM usage
+- [Optimistic Locking Example](examples/forge-sql-orm-example-optimistic-locking) - Real-world conflict handling
+- [Organization Tracker Example](examples/forge-sql-orm-example-org-tracker) - Complex relationships
+- [Checklist Example](examples/forge-sql-orm-example-checklist) - Jira integration
 
 ## Usage Approaches
 
-### 1. Direct Drizzle Usage
+
+### 1. Full Forge-SQL-ORM Usage
+```typescript
+import ForgeSQL from "forge-sql-orm";
+const forgeSQL = new ForgeSQL();
+```
+Best for: Advanced features like optimistic locking, automatic versioning, and automatic field name collision prevention in complex queries.
+
+### 2. Direct Drizzle Usage
 ```typescript
 import { drizzle } from "drizzle-orm/mysql-proxy";
 import { forgeDriver } from "forge-sql-orm";
 const db = drizzle(forgeDriver);
 ```
-Best for: Simple CRUD operations without optimistic locking. Note that you need to manually patch drizzle `patchDbWithSelectAliased` for select fields to prevent field name collisions in Atlassian Forge SQL.
+Best for: Simple Modify operations without optimistic locking. Note that you need to manually patch drizzle `patchDbWithSelectAliased` for select fields to prevent field name collisions in Atlassian Forge SQL.
 
-### 2. Full Forge-SQL-ORM Usage
+
+### 3. Local Cache Optimization
 ```typescript
 import ForgeSQL from "forge-sql-orm";
 const forgeSQL = new ForgeSQL();
+
+// Optimize repeated queries within a single invocation
+await forgeSQL.executeWithLocalContext(async () => {
+  // Multiple queries here will benefit from local caching
+  const users = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // This query will use local cache (no database call)
+  const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Using new methods for better performance
+  const usersFrom = await forgeSQL.selectFrom(users)
+    .where(eq(users.active, true));
+  
+  // This will use local cache (no database call)
+  const cachedUsersFrom = await forgeSQL.selectFrom(users)
+    .where(eq(users.active, true));
+  
+  // Raw SQL with local caching
+  const rawUsers = await forgeSQL.execute(
+    "SELECT id, name FROM users WHERE active = ?", 
+    [true]
+  );
+});
 ```
-Best for: Advanced features like optimistic locking, automatic versioning, and automatic field name collision prevention in complex queries.
+Best for: Performance optimization of repeated queries within resolvers or single invocation contexts.
 
 ## Field Name Collision Prevention in Complex Queries
 
@@ -91,18 +201,149 @@ Forge-SQL-ORM is designed to work with @forge/sql and requires some additional s
 
 ✅ Step 1: Install Dependencies
 
+**Basic installation (without caching):**
 ```sh
-npm install forge-sql-orm @forge/sql drizzle-orm momment -S
-npm install forge-sql-orm-cli  -D
+npm install forge-sql-orm @forge/sql drizzle-orm -S
+```
+
+**With caching support:**
+```sh
+npm install forge-sql-orm @forge/sql @forge/kvs drizzle-orm -S
 ```
 
 This will:
 - Install Forge-SQL-ORM (the ORM for @forge/sql)
 - Install @forge/sql, the Forge database layer
+- Install @forge/kvs, the Forge Key-Value Store for caching (optional, only needed for caching features)
 - Install Drizzle ORM and its MySQL driver
 - Install TypeScript types for MySQL
 - Install forge-sql-orm-cli A command-line interface tool for managing Atlassian Forge SQL migrations and model generation with Drizzle ORM integration.
 
+## Quick Start
+
+### 1. Basic Setup
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+// Initialize ForgeSQL
+const forgeSQL = new ForgeSQL();
+
+// Simple query
+const users = await forgeSQL.select().from(users);
+```
+
+### 2. With Caching (Optional)
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+// Initialize with caching
+const forgeSQL = new ForgeSQL({
+  cacheEntityName: "cache",
+  cacheTTL: 300
+});
+
+// Cached query
+const users = await forgeSQL.selectCacheable({ id: users.id, name: users.name })
+  .from(users).where(eq(users.active, true));
+```
+
+### 3. Local Cache Optimization
+```typescript
+// Optimize repeated queries within a single invocation
+await forgeSQL.executeWithLocalContext(async () => {
+  const users = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // This query will use local cache (no database call)
+  const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Using new methods for better performance
+  const usersFrom = await forgeSQL.selectFrom(users)
+    .where(eq(users.active, true));
+  
+  // Raw SQL with local caching
+  const rawUsers = await forgeSQL.execute(
+    "SELECT id, name FROM users WHERE active = ?", 
+    [true]
+  );
+});
+```
+
+### 4. Next Steps
+- [Full Installation Guide](#installation) - Complete setup instructions
+- [Core Features](#core-features) - Learn about key capabilities
+- [Global Cache System (Level 2)](#global-cache-system-level-2) - Cross-invocation caching features
+- [Local Cache System (Level 1)](#local-cache-operations-level-1) - In-memory caching features
+- [API Reference](#reference) - Complete API documentation
+
+## Drizzle Usage with forge-sql-orm
+
+If you prefer to use Drizzle ORM with the additional features of Forge-SQL-ORM (like optimistic locking and caching), you can use the enhanced API:
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+const forgeSQL = new ForgeSQL();
+
+// Versioned operations with cache management (recommended)
+await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [userData]);
+await forgeSQL.modifyWithVersioningAndEvictCache().updateById(updateData, Users);
+
+// Versioned operations without cache management
+await forgeSQL.modifyWithVersioning().insert(Users, [userData]);
+await forgeSQL.modifyWithVersioning().updateById(updateData, Users);
+
+// Non-versioned operations with cache management
+await forgeSQL.insertAndEvictCache(Users).values(userData);
+await forgeSQL.updateAndEvictCache(Users).set(updateData).where(eq(Users.id, 1));
+
+// Basic Drizzle operations (cache context aware)
+await forgeSQL.insert(Users).values(userData);
+await forgeSQL.update(Users).set(updateData).where(eq(Users.id, 1));
+
+// Direct Drizzle access
+const db = forgeSQL.getDrizzleQueryBuilder();
+const users = await db.select().from(users);
+
+// Using new methods for enhanced functionality
+const usersFrom = await forgeSQL.selectFrom(users)
+  .where(eq(users.active, true));
+
+const usersDistinct = await forgeSQL.selectDistinctFrom(users)
+  .where(eq(users.active, true));
+
+const usersCacheable = await forgeSQL.selectCacheableFrom(users)
+  .where(eq(users.active, true));
+
+// Raw SQL execution
+const rawUsers = await forgeSQL.execute(
+  "SELECT * FROM users WHERE active = ?", 
+  [true]
+);
+
+// Raw SQL with caching
+const cachedRawUsers = await forgeSQL.executeCacheable(
+  "SELECT * FROM users WHERE active = ?", 
+  [true], 
+  300
+);
+
+// Common Table Expressions (CTEs)
+const userStats = await forgeSQL
+  .with(
+    forgeSQL.selectFrom(users).where(eq(users.active, true)).as('activeUsers'),
+    forgeSQL.selectFrom(orders).where(eq(orders.status, 'completed')).as('completedOrders')
+  )
+  .select({
+    totalActiveUsers: sql`COUNT(au.id)`,
+    totalCompletedOrders: sql`COUNT(co.id)`
+  })
+  .from(sql`activeUsers au`)
+  .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+```
+
+This approach gives you direct access to all Drizzle ORM features while still using the @forge/sql backend with enhanced caching and versioning capabilities.
+
 ## Direct Drizzle Usage with Custom Driver
 
 If you prefer to use Drizzle ORM directly without the additional features of Forge-SQL-ORM (like optimistic locking), you can use the custom driver:
@@ -116,24 +357,424 @@ const db = patchDbWithSelectAliased(drizzle(forgeDriver));
 
 // Use drizzle directly
 const users = await db.select().from(users);
+const users = await db.selectAliased(getTableColumns(users)).from(users);
+const users = await db.selectAliasedDistinct(getTableColumns(users)).from(users);
+await db.insert(users)...;
+await db.update(users)...;
+await db.delete(users)...;
+// Use drizzle with kvs cache
+const users = await db.selectAliasedCacheable(getTableColumns(users)).from(users);
+const users = await db.selectAliasedDistinctCacheable(getTableColumns(users)).from(users);
+await db.insertAndEvictCache(users)...;
+await db.updateAndEvictCache(users)...;
+await db.deleteAndEvictCache(users)...;
+
+// Use drizzle with kvs cache context
+await forgeSQL.executeWithCacheContext(async () => {
+  await db.insertWithCacheContext(users)...;
+  await db.updateWithCacheContext(users)...;
+  await db.deleteWithCacheContext(users)...;
+  // invoke without cache
+   const users = await db.selectAliasedCacheable(getTableColumns(users)).from(users);  
+  // Cache is cleared only once at the end for all affected tables
+});
+
+// Using new methods with direct drizzle
+const usersFrom = await forgeSQL.selectFrom(users)
+  .where(eq(users.active, true));
+
+const usersDistinct = await forgeSQL.selectDistinctFrom(users)
+  .where(eq(users.active, true));
+
+const usersCacheable = await forgeSQL.selectCacheableFrom(users)
+  .where(eq(users.active, true));
+
+// Raw SQL execution
+const rawUsers = await forgeSQL.execute(
+  "SELECT * FROM users WHERE active = ?", 
+  [true]
+);
+
+// Raw SQL with caching
+const cachedRawUsers = await forgeSQL.executeCacheable(
+  "SELECT * FROM users WHERE active = ?", 
+  [true], 
+  300
+);
+```
+
+## Setting Up Caching with @forge/kvs (Optional)
+
+The caching system is optional and only needed if you want to use cache-related features. To enable the caching system, you need to install the required dependency and configure your manifest.
+
+### How Caching Works
+
+To use caching, you need to use Forge-SQL-ORM methods that support cache management:
+
+**Methods that perform cache eviction after execution and in cache context (batch eviction):**
+- `forgeSQL.insertAndEvictCache()`
+- `forgeSQL.updateAndEvictCache()`
+- `forgeSQL.deleteAndEvictCache()`
+- `forgeSQL.modifyWithVersioningAndEvictCache()`
+- `forgeSQL.getDrizzleQueryBuilder().insertAndEvictCache()`
+- `forgeSQL.getDrizzleQueryBuilder().updateAndEvictCache()`
+- `forgeSQL.getDrizzleQueryBuilder().deleteAndEvictCache()`
+
+**Methods that participate in cache context only (batch eviction):**
+- All methods except the default Drizzle methods:
+  - `forgeSQL.insert()`
+  - `forgeSQL.update()`
+  - `forgeSQL.delete()`
+  - `forgeSQL.modifyWithVersioning()`
+  - `forgeSQL.getDrizzleQueryBuilder().insertWithCacheContext()`
+  - `forgeSQL.getDrizzleQueryBuilder().updateWithCacheContext()`
+  - `forgeSQL.getDrizzleQueryBuilder().deleteWithCacheContext()`
+
+**Methods do not do evict cache, better do not use with cache feature:**
+  - `forgeSQL.getDrizzleQueryBuilder().insert()`
+  - `forgeSQL.getDrizzleQueryBuilder().update()`
+  - `forgeSQL.getDrizzleQueryBuilder().delete()`
+
+**Cacheable methods:**
+  - `forgeSQL.selectCacheable()`
+  - `forgeSQL.selectDistinctCacheable()`
+  - `forgeSQL.getDrizzleQueryBuilder().selectAliasedCacheable()`
+  - `forgeSQL.getDrizzleQueryBuilder().selectAliasedDistinctCacheable()`
+
+**Cache context example:**
+```typescript
+await forgeSQL.executeWithCacheContext(async () => {
+  // These methods participate in batch cache clearing
+  await forgeSQL.insert(Users).values(userData);
+  await forgeSQL.update(Users).set(updateData).where(eq(Users.id, 1));
+  await forgeSQL.delete(Users).where(eq(Users.id, 1));
+  // Cache is cleared only once at the end for all affected tables
+});
 ```
 
-##  Drizzle Usage with forge-sql-orm
 
-If you prefer to use Drizzle ORM  with the additional features of Forge-SQL-ORM (like optimistic locking), you can use the custom driver:
+The diagram below shows the lifecycle of a cacheable query in Forge-SQL-ORM:
+
+1. Resolver calls forge-sql-orm with a SQL query and parameters.
+2. forge-sql-orm generates a cache key = hash(sql, parameters).
+3. It asks @forge/kvs for an existing cached result.
+   - Cache hit → result is returned immediately.
+   - Cache miss / expired → query is executed against @forge/sql.
+4. Fresh result is stored in @forge/kvs with TTL and returned to the caller.
+
+![img.png](img/umlCache1.png)
+
+
+The diagram below shows how Evict Cache works in Forge-SQL-ORM:
+
+1. **Data modification** is executed through `@forge/sql` (e.g., `UPDATE users ...`).
+2. After a successful update, **forge-sql-orm** queries the `cache` entity by using the **`sql` field** with `filter.contains("users")` to find affected cached queries.
+3. The returned cache entries are deleted in **batches** (up to 25 per transaction).
+4. Once eviction is complete, the update result is returned to the resolver.
+5. **Note:** Expired entries are not processed here — they are cleaned up separately by the scheduled cache cleanup trigger using the `expiration` index.
+
+![img.png](img/umlCacheEvict1.png)
 
+The diagram below shows how Scheduled Expiration Cleanup works:
+
+1. A periodic scheduler (Forge trigger) runs cache cleanup independently of data modifications.
+2. forge-sql-orm queries the cache entity by the expiration index to find entries with expiration < now.
+3. Entries are deleted in batches (up to 25 per transaction) until the page is empty; pagination is done with a cursor (e.g., 100 per page).
+4. This keeps the cache footprint small and prevents stale data accumulation.
+
+![img.png](img/umlCacheEvictScheduler1.png)
+
+The diagram below shows how Cache Context works:
+
+`executeWithCacheContext(fn)` lets you group multiple data modifications and perform **one consolidated cache eviction** at the end:
+
+1. The context starts with an empty `affectedTables` set.
+2. Each successful `INSERT/UPDATE/DELETE` inside the context registers its table name in `affectedTables`.
+3. **Reads inside the same context** that target tables present in `affectedTables` will **bypass the cache** (read-through to SQL) to avoid serving stale data. These reads also **do not write** back to cache until eviction completes.
+4. On context completion, `affectedTables` is de-duplicated and used to build **one combined KVS query** over the `sql` field with
+   `filter.or(filter.contains("<t1>"), filter.contains("<t2>"), ...)`, returning all impacted cache entries in a single scan (paged by cursor, e.g., 100/page).
+5. Matching cache entries are deleted in **batches** (≤25 per transaction) until the page is exhausted; then the next page is fetched via the cursor.
+6. Expiration is handled separately by the scheduled cleanup and is **not part of** the context flow.
+
+![img.png](img/umlCacheEvictCacheContext1.png)
+
+
+### Important Considerations
+
+**@forge/kvs Limits:**
+Please review the [official @forge/kvs quotas and limits](https://developer.atlassian.com/platform/forge/platform-quotas-and-limits/#kvs-and-custom-entity-store-quotas) before implementing caching.
+
+**Caching Guidelines:**
+- Don't cache everything - be selective about what to cache
+- Don't cache simple and fast queries - sometimes direct query is faster than cache
+- Consider data size and frequency of changes
+- Monitor cache usage to stay within quotas
+- Use appropriate TTL values
+
+### Step 1: Install Dependencies
+
+```bash
+npm install @forge/kvs -S
+```
+
+### Step 2: Configure Manifest
+
+Add the storage entity configuration and scheduler trigger to your `manifest.yml`:
+
+```yaml
+modules:
+  scheduledTrigger:
+    - key: clear-cache-trigger
+      function: clearCache
+      interval: fiveMinute
+  storage:
+    entities:
+      - name: cache
+        attributes:
+          sql:
+            type: string
+          expiration:
+            type: integer
+          data:
+            type: string
+        indexes:
+          - sql
+          - expiration
+  sql:
+    - key: main
+      engine: mysql
+  function:
+    - key: clearCache
+      handler: index.clearCache
+```
+```typescript
+// Example usage in your Forge app
+import { clearCacheSchedulerTrigger } from "forge-sql-orm";
+
+export const clearCache = () => {
+  return clearCacheSchedulerTrigger({ 
+    cacheEntityName: "cache",
+  });
+};
+```
+
+
+### Step 3: Configure ORM Options
+
+Set the cache entity name in your ForgeSQL configuration:
+
+```typescript
+const options = {
+  cacheEntityName: "cache", // Must match the entity name in manifest.yml
+  cacheTTL: 300, // Default cache TTL in seconds (5 minutes)
+  cacheWrapTable: true, // Wrap table names with backticks in cache keys
+  // ... other options
+};
+
+const forgeSQL = new ForgeSQL(options);
+```
+
+**Important Notes:**
+- The `cacheEntityName` must exactly match the `name` in your manifest storage entities
+- The entity attributes (`sql`, `expiration`, `data`) are required for proper cache functionality
+- Indexes on `sql` and `expiration` improve cache lookup performance
+- Cache data is automatically cleaned up based on TTL settings
+- No additional permissions are required beyond standard Forge app permissions
+
+### Complete Setup Examples
+
+**Basic setup (without caching):**
+
+**package.json:**
+```shell
+npm install forge-sql-orm @forge/sql drizzle-orm -S
+```
+
+**manifest.yml:**
+```yaml
+modules:
+  sql:
+    - key: main
+      engine: mysql
+```
+
+**index.ts:**
 ```typescript
 import ForgeSQL from "forge-sql-orm";
+
 const forgeSQL = new ForgeSQL();
-forgeSQL.crud().insert(...);
-forgeSQL.crud().updateById(...);
-const db = forgeSQL.getDrizzleQueryBuilder();
 
-// Use drizzle
-const users = await db.select().from(users);
+// simple insert
+await forgeSQL.insert(Users, [userData]);
+// Use versioned operations without caching
+await forgeSQL.modifyWithVersioning().insert(Users, [userData]);
+const users = await forgeSQL.select({id: Users.id});
+
+
 ```
 
-This approach gives you direct access to all Drizzle ORM features while still using the @forge/sql backend.
+**With caching support:**
+```shell
+npm install forge-sql-orm @forge/sql @forge/kvs drizzle-orm -S
+```
+
+**manifest.yml:**
+```yaml
+modules:
+  scheduledTrigger:
+    - key: clear-cache-trigger
+      function: clearCache
+      interval: fiveMinute
+  storage:
+    entities:
+      - name: cache
+        attributes:
+          sql:
+            type: string
+          expiration:
+            type: integer
+          data:
+            type: string
+        indexes:
+          - sql
+          - expiration
+  sql:
+    - key: main
+      engine: mysql
+  function:
+    - key: clearCache
+      handler: index.clearCache
+```
+
+**index.ts:**
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL({
+    cacheEntityName: "cache"
+});
+
+import {clearCacheSchedulerTrigger} from "forge-sql-orm";
+import {getTableColumns} from "drizzle-orm";
+
+export const clearCache = () => {
+    return clearCacheSchedulerTrigger({
+        cacheEntityName: "cache",
+    });
+};
+
+
+// Now you can use caching features
+const usersData = await forgeSQL.selectCacheable(getTableColumns(users)).from(users).where(eq(users.active, true))
+
+// simple insert
+await forgeSQL.insertAndEvictCache(users, [userData]);
+// Use versioned operations with caching
+await forgeSQL.modifyWithVersioningAndEvictCache().insert(users, [userData]);
+
+// use Cache Context
+const data = await forgeSQL.executeWithCacheContextAndReturnValue(async () => {
+    // after insert mark users to evict
+    await forgeSQL.insert(users, [userData]);
+       // after insertAndEvictCache mark orders to evict
+    await forgeSQL.insertAndEvictCache(orders, [order1, order2]);
+    // execute query and put result to local cache
+    await forgeSQL.selectCacheable({userId: users.id, userName: users.name, orderId: orders.id, orderName: orders.name})
+        .from(users)
+        .innerJoin(orders, eq(orders.userId, users.id)).where(eq(users.active, true))
+    // use local cache without @forge/kvs and @forge/sql
+    return await forgeSQL.selectCacheable({userId: users.id, userName: users.name, orderId: orders.id, orderName: orders.name})
+        .from(users)
+        .innerJoin(orders, eq(orders.userId, users.id)).where(eq(users.active, true))
+})
+// execute query and put result to kvs cache
+await forgeSQL.selectCacheable({userId: users.id, userName: users.name, orderId: orders.id, orderName: orders.name})
+        .from(users)
+        .innerJoin(orders, eq(orders.userId, users.id)).where(eq(users.active, true))
+
+// get result from @foge/kvs cache without real @forge/sql call
+await forgeSQL.selectCacheable({userId: users.id, userName: users.name, orderId: orders.id, orderName: orders.name})
+        .from(users)
+        .innerJoin(orders, eq(orders.userId, users.id)).where(eq(users.active, true))
+
+// use Local Cache for performance optimization
+const optimizedData = await forgeSQL.executeWithLocalCacheContextAndReturnValue(async () => {
+    // First query - hits database and caches result
+    const users = await forgeSQL.select({id: users.id, name: users.name})
+        .from(users).where(eq(users.active, true));
+    
+    // Second query - uses local cache (no database call)
+    const cachedUsers = await forgeSQL.select({id: users.id, name: users.name})
+        .from(users).where(eq(users.active, true));
+    
+    // Using new methods for better performance
+    const usersFrom = await forgeSQL.selectFrom(users)
+        .where(eq(users.active, true));
+    
+    // This will use local cache (no database call)
+    const cachedUsersFrom = await forgeSQL.selectFrom(users)
+        .where(eq(users.active, true));
+    
+    // Raw SQL with local caching
+    const rawUsers = await forgeSQL.execute(
+        "SELECT id, name FROM users WHERE active = ?", 
+        [true]
+    );
+    
+    // Insert operation - evicts local cache
+    await forgeSQL.insert(users).values({name: 'New User', active: true});
+    
+    // Third query - hits database again and caches new result
+    const updatedUsers = await forgeSQL.select({id: users.id, name: users.name})
+        .from(users).where(eq(users.active, true));
+    
+    return { users, cachedUsers, updatedUsers, usersFrom, cachedUsersFrom, rawUsers };
+});
+
+```
+
+## Choosing the Right Method - ForgeSQL ORM
+
+### When to Use Each Approach
+
+| Method | Use Case | Versioning | Cache Management |
+|--------|----------|------------|------------------|
+| `modifyWithVersioningAndEvictCache()` | High-concurrency scenarios with Cache support| ✅ Yes | ✅ Yes |
+| `modifyWithVersioning()` | High-concurrency scenarios | ✅ Yes | Cache Context |
+| `insertAndEvictCache()` | Simple inserts | ❌ No | ✅ Yes |
+| `updateAndEvictCache()` | Simple updates | ❌ No | ✅ Yes |
+| `deleteAndEvictCache()` | Simple deletes | ❌ No | ✅ Yes |
+| `insert/update/delete` | Basic Drizzle operations | ❌ No | Cache Context |
+| `selectFrom()` | All-column queries with field aliasing | ❌ No | Local Cache |
+| `selectDistinctFrom()` | Distinct all-column queries with field aliasing | ❌ No | Local Cache |
+| `selectCacheableFrom()` | All-column queries with field aliasing and caching | ❌ No | Local + Global Cache |
+| `selectDistinctCacheableFrom()` | Distinct all-column queries with field aliasing and caching | ❌ No | Local + Global Cache |
+| `execute()` | Raw SQL queries with local caching | ❌ No | Local Cache |
+| `executeCacheable()` | Raw SQL queries with local and global caching | ❌ No | Local + Global Cache |
+| `with()` | Common Table Expressions (CTEs) | ❌ No | Local Cache |
+
+
+## Choosing the Right Method - Direct Drizzle
+
+### When to Use Each Approach
+
+| Method | Use Case | Versioning | Cache Management |
+|--------|----------|------------|------------------|
+| `insertWithCacheContext/insertWithCacheContext/updateWithCacheContext` | Basic Drizzle operations | ❌ No | Cache Context |
+| `insertAndEvictCache()` | Simple inserts without conflicts | ❌ No | ✅ Yes |
+| `updateAndEvictCache()` | Simple updates without conflicts | ❌ No | ✅ Yes |
+| `deleteAndEvictCache()` | Simple deletes without conflicts | ❌ No | ✅ Yes |
+| `insert/update/delete` | Basic Drizzle operations | ❌ No | ❌ No |
+| `selectFrom()` | All-column queries with field aliasing | ❌ No | Local Cache |
+| `selectDistinctFrom()` | Distinct all-column queries with field aliasing | ❌ No | Local Cache |
+| `selectCacheableFrom()` | All-column queries with field aliasing and caching | ❌ No | Local + Global Cache |
+| `selectDistinctCacheableFrom()` | Distinct all-column queries with field aliasing and caching | ❌ No | Local + Global Cache |
+| `execute()` | Raw SQL queries with local caching | ❌ No | Local Cache |
+| `executeCacheable()` | Raw SQL queries with local and global caching | ❌ No | Local + Global Cache |
+| `with()` | Common Table Expressions (CTEs) | ❌ No | Local Cache |
+where Cache context - allows you to batch cache invalidation events and bypass cache reads for affected tables.
+
 
 ## Step-by-Step Migration Workflow
 
@@ -344,6 +985,49 @@ const users = await db.select().from(users);
 ### Basic Fetch Operations
 
 ```js
+// Using forgeSQL.select()
+const user = await forgeSQL
+    .select({user: users})
+    .from(users);
+
+// Using forgeSQL.selectDistinct()
+const user = await forgeSQL
+    .selectDistinct({user: users})
+    .from(users);
+
+// Using forgeSQL.selectCacheable()
+const user = await forgeSQL
+    .selectCacheable({user: users})
+    .from(users);
+
+// Using forgeSQL.selectFrom() - Select all columns with field aliasing
+const user = await forgeSQL
+    .selectFrom(users)
+    .where(eq(users.id, 1));
+
+// Using forgeSQL.selectDistinctFrom() - Select distinct all columns with field aliasing
+const user = await forgeSQL
+    .selectDistinctFrom(users)
+    .where(eq(users.id, 1));
+
+// Using forgeSQL.selectCacheableFrom() - Select all columns with field aliasing and caching
+const user = await forgeSQL
+    .selectCacheableFrom(users)
+    .where(eq(users.id, 1));
+
+// Using forgeSQL.selectDistinctCacheableFrom() - Select distinct all columns with field aliasing and caching
+const user = await forgeSQL
+    .selectDistinctCacheableFrom(users)
+    .where(eq(users.id, 1));
+
+// Using forgeSQL.execute() - Execute raw SQL with local caching
+const user = await forgeSQL
+    .execute("SELECT * FROM users WHERE id = ?", [1]);
+
+// Using forgeSQL.executeCacheable() - Execute raw SQL with local and global caching
+const user = await forgeSQL
+    .executeCacheable("SELECT * FROM users WHERE id = ?", [1], 300);
+
 // Using forgeSQL.getDrizzleQueryBuilder()
 const user = await forgeSQL
   .getDrizzleQueryBuilder()
@@ -399,6 +1083,31 @@ const orderWithUser = await forgeSQL
   .from(orders)
   .innerJoin(users, eq(orders.userId, users.id));
 
+// Using new selectFrom methods with joins
+const orderWithUser = await forgeSQL
+  .selectFrom(orders)
+  .innerJoin(users, eq(orders.userId, users.id))
+  .where(eq(orders.id, 1));
+
+// Using selectCacheableFrom with joins and caching
+const orderWithUser = await forgeSQL
+  .selectCacheableFrom(orders)
+  .innerJoin(users, eq(orders.userId, users.id))
+  .where(eq(orders.id, 1));
+
+// Using with() for Common Table Expressions (CTEs)
+const userStats = await forgeSQL
+  .with(
+    forgeSQL.selectFrom(users).where(eq(users.active, true)).as('activeUsers'),
+    forgeSQL.selectFrom(orders).where(eq(orders.status, 'completed')).as('completedOrders')
+  )
+  .select({
+    totalActiveUsers: sql`COUNT(au.id)`,
+    totalCompletedOrders: sql`COUNT(co.id)`
+  })
+  .from(sql`activeUsers au`)
+  .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+
 // OR with direct drizzle
 const db = patchDbWithSelectAliased(drizzle(forgeDriver));
 const orderWithUser = await db
@@ -440,32 +1149,125 @@ const userStats = await forgeSQL
 const users = await forgeSQL
   .fetch()
   .executeRawSQL<Users>("SELECT * FROM users");
+
+// Using execute() for raw SQL with local caching
+const users = await forgeSQL
+  .execute("SELECT * FROM users WHERE active = ?", [true]);
+
+// Using executeCacheable() for raw SQL with local and global caching
+const users = await forgeSQL
+  .executeCacheable("SELECT * FROM users WHERE active = ?", [true], 300);
+
+// Using execute() with complex queries
+const userStats = await forgeSQL
+  .execute(`
+    SELECT 
+      u.id,
+      u.name,
+      COUNT(o.id) as order_count,
+      SUM(o.amount) as total_amount
+    FROM users u
+    LEFT JOIN orders o ON u.id = o.user_id
+    WHERE u.active = ?
+    GROUP BY u.id, u.name
+  `, [true]);
 ```
 
-## CRUD Operations
+## Modify Operations
 
-### Insert Operations
+Forge-SQL-ORM provides multiple approaches for Modify operations, each with different characteristics:
 
-  ```js
-// Single insert
-const userId = await forgeSQL.crud().insert(Users, [{ id: 1, name: "Smith" }]);
+### 1. Basic Drizzle Operations (Cache Context Aware)
 
-// Bulk insert
-await forgeSQL.crud().insert(Users, [
+These operations work like standard Drizzle methods but participate in cache context when used within `executeWithCacheContext()`:
+
+```js
+// Basic insert (participates in cache context when used within executeWithCacheContext)
+await forgeSQL.insert(Users).values({ id: 1, name: "Smith" });
+
+// Basic update (participates in cache context when used within executeWithCacheContext)
+await forgeSQL.update(Users)
+  .set({ name: "Smith Updated" })
+  .where(eq(Users.id, 1));
+
+// Basic delete (participates in cache context when used within executeWithCacheContext)
+await forgeSQL.delete(Users)
+  .where(eq(Users.id, 1));
+```
+
+### 2. Non-Versioned Operations with Cache Management
+
+These operations don't use optimistic locking but provide cache invalidation:
+
+```js
+// Insert without versioning but with cache invalidation
+await forgeSQL.insertAndEvictCache(Users).values({ id: 1, name: "Smith" });
+
+// Update without versioning but with cache invalidation
+await forgeSQL.updateAndEvictCache(Users)
+  .set({ name: "Smith Updated" })
+  .where(eq(Users.id, 1));
+
+// Delete without versioning but with cache invalidation
+await forgeSQL.deleteAndEvictCache(Users)
+  .where(eq(Users.id, 1));
+```
+
+### 3. Versioned Operations with Cache Management (Recommended)
+
+These operations use optimistic locking and automatic cache invalidation:
+
+```js
+// Insert with versioning and cache management
+const userId = await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [{ id: 1, name: "Smith" }]);
+
+// Bulk insert with versioning
+await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [
     { id: 2, name: "Smith" },
     { id: 3, name: "Vasyl" },
   ]);
 
-// Insert with duplicate handling
-  await forgeSQL.crud().insert(
-  Users,
-    [
-      { id: 4, name: "Smith" },
-      { id: 4, name: "Vasyl" },
-    ],
-  true
-  );
+// Update by ID with optimistic locking and cache invalidation
+await forgeSQL.modifyWithVersioningAndEvictCache().updateById({ id: 1, name: "Smith Updated" }, Users);
 
+// Delete by ID with versioning and cache invalidation
+await forgeSQL.modifyWithVersioningAndEvictCache().deleteById(1, Users);
+```
+
+### 4. Versioned Operations without Cache Management
+
+These operations use optimistic locking but don't manage cache:
+
+```js
+// Insert with versioning only (no cache management)
+const userId = await forgeSQL.modifyWithVersioning().insert(Users, [{ id: 1, name: "Smith" }]);
+
+// Update with versioning only
+await forgeSQL.modifyWithVersioning().updateById({ id: 1, name: "Smith Updated" }, Users);
+
+// Delete with versioning only
+await forgeSQL.modifyWithVersioning().deleteById(1, Users);
+```
+
+### 5. Legacy Modify Operations (Removed in 2.1.x)
+
+⚠️ **BREAKING CHANGE**: The `crud()` and `modify()` methods have been completely removed in version 2.1.x.
+
+```js
+// ❌ These methods no longer exist in 2.1.x
+// const userId = await forgeSQL.crud().insert(Users, [{ id: 1, name: "Smith" }]);
+// await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, Users);
+// await forgeSQL.crud().deleteById(1, Users);
+
+// ✅ Use the new methods instead
+const userId = await forgeSQL.modifyWithVersioning().insert(Users, [{ id: 1, name: "Smith" }]);
+await forgeSQL.modifyWithVersioning().updateById({ id: 1, name: "Smith Updated" }, Users);
+await forgeSQL.modifyWithVersioning().deleteById(1, Users);
+```
+
+### Advanced Operations
+
+```js
 // Insert with sequence (nextVal)
 import { nextVal } from "forge-sql-orm";
 
@@ -474,38 +1276,24 @@ const user = {
   name: "user test",
   organization_id: 1
 };
-const id = await forgeSQL.modify().insert(appUser, [user]);
-
-// The generated SQL will be:
-// INSERT INTO app_user (id, name, organization_id) 
-// VALUES (NEXTVAL(user_id_seq), ?, ?) -- params: ["user test", 1]
-  ```
-
-### Update Operations
-
-  ```js
-// Update by ID with optimistic locking
-await forgeSQL.crud().updateById({ id: 1, name: "Smith Updated" }, Users);
-
-// Update specific fields
-await forgeSQL.crud().updateById(
-  { id: 1,  age: 35 },
-  Users
-);
+const id = await forgeSQL.modifyWithVersioning().insert(appUser, [user]);
 
 // Update with custom WHERE condition
-await forgeSQL.crud().updateFields(
+await forgeSQL.modifyWithVersioning().updateFields(
     { name: "New Name", age: 35 },
   Users,
   eq(Users.email, "smith@example.com")
 );
-```
-
-### Delete Operations
 
-```js
-// Delete by ID
-await forgeSQL.crud().deleteById(1, Users);
+// Insert with duplicate handling
+await forgeSQL.modifyWithVersioning().insert(
+  Users,
+  [
+    { id: 4, name: "Smith" },
+    { id: 4, name: "Vasyl" },
+  ],
+  true
+);
 ```
 
 ## SQL Utilities
@@ -543,8 +1331,332 @@ const result = await forgeSQL
 - This prevents SQL injection by ensuring only numeric values are inserted
 - Always use this function instead of string concatenation for LIMIT and OFFSET values
 
+## Global Cache System (Level 2)
+
+[↑ Back to Top](#table-of-contents)
+
+Forge-SQL-ORM includes a sophisticated global caching system that provides **cross-invocation caching** - the ability to share cached data between different resolver invocations. The global cache system is built on top of [@forge/kvs Custom entity store](https://developer.atlassian.com/platform/forge/storage-reference/storage-api-custom-entities/) and provides persistent cross-invocation caching with automatic serialization/deserialization of complex data structures.
+
+### Cache Levels Overview
+
+Forge-SQL-ORM implements a two-level caching architecture:
+
+- **Level 1 (Local Cache)**: In-memory caching within a single resolver invocation scope
+- **Level 2 (Global Cache)**: Cross-invocation persistent caching using KVS storage
+
+This multi-level approach provides optimal performance by checking the fastest cache first, then falling back to cross-invocation persistent storage.
+
+### Cache Configuration
+
+The caching system uses Atlassian Forge's Custom entity store to persist cache data. Each cache entry is stored as a custom entity with automatic TTL management and efficient key-based retrieval.
+
+```typescript
+const options = {
+  cacheEntityName: "cache", // KVS Custom entity name for cache storage
+  cacheTTL: 300, // Default cache TTL in seconds (5 minutes)
+  cacheWrapTable: true, // Wrap table names with backticks in cache keys
+  additionalMetadata: {
+    users: {
+      tableName: "users",
+      versionField: {
+        fieldName: "updatedAt",
+      }
+    }
+  }
+};
+
+const forgeSQL = new ForgeSQL(options);
+```
+
+### How Caching Works with @forge/kvs
+
+The caching system leverages Forge's Custom entity store to provide:
+
+- **Persistent Storage**: Cache data survives app restarts and deployments
+- **Automatic TTL**: Built-in expiration handling through Forge's entity lifecycle
+- **Efficient Retrieval**: Fast key-based lookups using Forge's optimized storage
+- **Data Serialization**: Automatic handling of complex objects and query results
+- **Batch Operations**: Efficient bulk cache operations for better performance
+
+```typescript
+// Cache entries are stored as custom entities in Forge's KVS
+// Example cache key structure:
+// Key: "CachedQuery_8d74bdd9d85064b72fb2ee072ca948e5"
+// Value: { data: [...], expiration: 1234567890, sql: "select * from 1" }
+```
+
+
+### Cache Context Operations
+
+The cache context allows you to batch cache invalidation events and bypass cache reads for affected tables:
+
+```typescript
+// Execute operations within a cache context
+await forgeSQL.executeWithCacheContext(async () => {
+  // All cache invalidation events are collected and executed in batch
+  await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [userData]);
+  await forgeSQL.modifyWithVersioningAndEvictCache().updateById(updateData, Users);
+  // Cache is cleared only once at the end for all affected tables
+});
+
+// Execute with return value
+const result = await forgeSQL.executeWithCacheContextAndReturnValue(async () => {
+  const user = await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [userData]);
+  return user;
+});
+
+// Basic operations also participate in cache context
+await forgeSQL.executeWithCacheContext(async () => {
+  // These operations will participate in batch cache clearing
+  await forgeSQL.insert(Users).values(userData);
+  await forgeSQL.update(Users).set(updateData).where(eq(Users.id, 1));
+  await forgeSQL.delete(Users).where(eq(Users.id, 1));
+  // Cache is cleared only once at the end for all affected tables
+});
+```
+
+### Local Cache Operations (Level 1)
+
+Forge-SQL-ORM provides a local cache system (Level 1 cache) that stores query results in memory for the duration of a single resolver invocation. This is particularly useful for optimizing repeated queries within the same execution context(resolver invocation).
+
+#### What is Local Cache?
+
+Local cache is an in-memory caching layer that operates within a single resolver invocation scope. Unlike the global KVS cache, local cache:
+
+- **Stores data in memory** using Node.js `AsyncLocalStorage`
+- **Automatically clears** when the invocation completes (Resolver call)
+- **Provides instant access** to previously executed queries in resolver invocation
+- **Reduces database load** for repeated operations within the same invocation
+- **Works alongside** the global KVS cache system
+
+#### Key Features of Local Cache
+
+- **In-Memory Storage**: Query results are cached in memory using Node.js `AsyncLocalStorage`
+- **Invocation-Scoped**: Cache is automatically cleared when the invocation completes
+- **Automatic Eviction**: Cache is cleared when insert/update/delete operations are performed
+- **No Persistence**: Data is not stored between Invocations (unlike global KVS cache)
+- **Performance Optimization**: Reduces database queries for repeated operations
+- **Simple Configuration**: Works out of the box with simple setup
+
+#### Usage Examples
+
+##### Basic Local Cache Usage
+
+```typescript
+// Execute operations within a local cache context
+await forgeSQL.executeWithLocalContext(async () => {
+  // First call - executes query and caches result
+  const users = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Second call - gets result from local cache (no database query)
+  const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Using new selectFrom methods with local caching
+  const usersFrom = await forgeSQL.selectFrom(users)
+    .where(eq(users.active, true));
+  
+  // This will use local cache (no database call)
+  const cachedUsersFrom = await forgeSQL.selectFrom(users)
+    .where(eq(users.active, true));
+  
+  // Using execute() with local caching
+  const rawUsers = await forgeSQL.execute(
+    "SELECT id, name FROM users WHERE active = ?", 
+    [true]
+  );
+  
+  // This will use local cache (no database call)
+  const cachedRawUsers = await forgeSQL.execute(
+    "SELECT id, name FROM users WHERE active = ?", 
+    [true]
+  );
+  
+  // Insert operation - evicts local cache for users table
+  await forgeSQL.insert(users).values({ name: 'New User', active: true });
+  
+  // Third call - executes query again and caches new result
+  const updatedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+});
+
+// Execute with return value
+const result = await forgeSQL.executeWithLocalCacheContextAndReturnValue(async () => {
+  // First call - executes query and caches result
+  const users = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Second call - gets result from local cache (no database query)
+  const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  return { users, cachedUsers };
+});
+```
+
+##### Real-World Resolver Example
+
+```typescript
+// Atlassian forge resolver with local cache optimization
+const userResolver = async (req) => {
+  return await forgeSQL.executeWithLocalCacheContextAndReturnValue(async () => {
+    // Get user details using selectFrom (all columns with field aliasing)
+    const user = await forgeSQL.selectFrom(users)
+      .where(eq(users.id, args.userId));
+    
+    // Get user's orders using selectCacheableFrom (with caching)
+    const orders = await forgeSQL.selectCacheableFrom(orders)
+      .where(eq(orders.userId, args.userId));
+    
+    // Get user's profile using raw SQL with execute()
+    const profile = await forgeSQL.execute(
+      "SELECT id, bio, avatar FROM profiles WHERE user_id = ?", 
+      [args.userId]
+    );
+    
+    // Get user statistics using complex raw SQL
+    const stats = await forgeSQL.execute(`
+      SELECT 
+        COUNT(o.id) as total_orders,
+        SUM(o.amount) as total_spent,
+        AVG(o.amount) as avg_order_value
+      FROM orders o 
+      WHERE o.user_id = ? AND o.status = 'completed'
+    `, [args.userId]);
+    
+    // If any of these queries are repeated within the same resolver,
+    // they will use the local cache instead of hitting the database
+    
+    return {
+      ...user[0],
+      orders,
+      profile: profile[0],
+      stats: stats[0]
+    };
+  });
+};
+```
+
+
+#### Local Cache (Level 1) vs Global Cache (Level 2)
+
+| Feature | Local Cache (Level 1) | Global Cache (Level 2) |
+|---------|----------------------|------------------------|
+| **Storage** | In-memory (Node.js process) | Persistent (KVS Custom Entities) |
+| **Scope** | Single forge invocation | Cross-invocation (between calls) |
+| **Persistence** | No (cleared on invocation end) | Yes (survives app redeploy) |
+| **Performance** | Very fast (memory access) | Fast (KVS optimized storage) |
+| **Memory Usage** | Low (invocation-scoped) | Higher (persistent storage) |
+| **Use Case** | Invocation optimization | Cross-invocation data sharing |
+| **Configuration** | None required | Requires KVS setup |
+| **TTL Support** | No (invocation-scoped) | Yes (automatic expiration) |
+| **Cache Eviction** | Automatic on DML operations | Manual or scheduled cleanup |
+| **Best For** | Repeated queries in single invocation | Frequently accessed data across invocations |
+
+#### Integration with Global Cache (Level 2)
+
+Local cache (Level 1) works alongside the global cache (Level 2) system:
+
+```typescript
+// Multi-level cache checking: Level 1 → Level 2 → Database
+await forgeSQL.executeWithLocalContext(async () => {
+  // This will check:
+  // 1. Local cache (Level 1 - in-memory)
+  // 2. Global cache (Level 2 - KVS)
+  // 3. Database query
+  const users = await forgeSQL.selectCacheable({ id: users.id, name: users.name })
+    .from(users).where(eq(users.active, true));
+  
+  // Using new methods with multi-level caching
+  const usersFrom = await forgeSQL.selectCacheableFrom(users)
+    .where(eq(users.active, true));
+  
+  // Raw SQL with multi-level caching
+  const rawUsers = await forgeSQL.executeCacheable(
+    "SELECT id, name FROM users WHERE active = ?", 
+    [true], 
+    300 // TTL in seconds
+  );
+});
+```
+
+#### Local Cache Flow Diagram
+
+The diagram below shows how local cache works in Forge-SQL-ORM:
+
+1. **Request Start**: Local cache context is initialized with empty cache
+2. **First Query**: Cache miss → Global cache miss → Database query → Save to local cache
+3. **Repeated Query**: Cache hit → Return cached result (no database call)
+4. **Data Modification**: Insert/Update/Delete → Evict local cache for affected table
+5. **Query After Modification**: Cache miss (was evicted) → Database query → Save to local cache
+6. **Request End**: Local cache context is destroyed, all data cleared
+
+![Local Cache Flow](img/localCacheFlow.txt)
+
+### Cache-Aware Query Operations
+
+```typescript
+// Execute queries with caching
+const users = await forgeSQL.modifyWithVersioningAndEvictCache().executeQuery(
+  forgeSQL.select().from(Users).where(eq(Users.active, true)),
+  600 // Custom TTL in seconds
+);
+
+// Execute single result queries with caching
+const user = await forgeSQL.modifyWithVersioningAndEvictCache().executeQueryOnlyOne(
+  forgeSQL.select().from(Users).where(eq(Users.id, 1))
+);
+
+// Execute raw SQL with caching
+const results = await forgeSQL.modifyWithVersioningAndEvictCache().executeRawSQL(
+  "SELECT * FROM users WHERE active = ?",
+  [true],
+  300 // TTL in seconds
+);
+
+// Using new methods for cache-aware operations
+const usersFrom = await forgeSQL.selectCacheableFrom(Users)
+  .where(eq(Users.active, true));
+
+const usersDistinct = await forgeSQL.selectDistinctCacheableFrom(Users)
+  .where(eq(Users.active, true));
+
+// Raw SQL with local and global caching
+const rawUsers = await forgeSQL.executeCacheable(
+  "SELECT * FROM users WHERE active = ?",
+  [true],
+  300 // TTL in seconds
+);
+
+// Using with() for Common Table Expressions with caching
+const userStats = await forgeSQL
+  .with(
+    forgeSQL.selectFrom(users).where(eq(users.active, true)).as('activeUsers'),
+    forgeSQL.selectFrom(orders).where(eq(orders.status, 'completed')).as('completedOrders')
+  )
+  .select({
+    totalActiveUsers: sql`COUNT(au.id)`,
+    totalCompletedOrders: sql`COUNT(co.id)`
+  })
+  .from(sql`activeUsers au`)
+  .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+```
+
+### Manual Cache Management
+
+```typescript
+// Clear cache for specific tables
+await forgeSQL.modifyWithVersioningAndEvictCache().evictCache(["users", "orders"]);
+
+// Clear cache for specific entities
+await forgeSQL.modifyWithVersioningAndEvictCache().evictCacheEntities([Users, Orders]);
+```
+
 ## Optimistic Locking
 
+[↑ Back to Top](#table-of-contents)
+
 Optimistic locking is a concurrency control mechanism that prevents data conflicts when multiple transactions attempt to update the same record concurrently. Instead of using locks, this technique relies on a version field in your entity models.
 
 ### Supported Version Field Types
@@ -575,7 +1687,19 @@ const forgeSQL = new ForgeSQL(options);
 
 ```typescript
 // The version field will be automatically handled
-await forgeSQL.crud().updateById(
+await forgeSQL.modifyWithVersioning().updateById(
+  { 
+    id: 1, 
+    name: "Updated Name",
+    updatedAt: new Date() // Will be automatically set if not provided
+  }, 
+  Users
+);
+```
+or with cache support
+```typescript
+// The version field will be automatically handled
+await forgeSQL.modifyWithVersioningAndEvictCache().updateById(
   { 
     id: 1, 
     name: "Updated Name",
@@ -594,10 +1718,46 @@ The `ForgeSqlOrmOptions` object allows customization of ORM behavior:
 | `logRawSqlQuery`           | `boolean` | Enables logging of raw SQL queries in the Atlassian Forge Developer Console. Useful for debugging and monitoring. Defaults to `false`.                                                                                         |
 | `disableOptimisticLocking` | `boolean` | Disables optimistic locking. When set to `true`, no additional condition (e.g., a version check) is added during record updates, which can improve performance. However, this may lead to conflicts when multiple transactions attempt to update the same record concurrently. |
 | `additionalMetadata`       | `object`  | Allows adding custom metadata to all entities. This is useful for tracking common fields across all tables (e.g., `createdAt`, `updatedAt`, `createdBy`, etc.). The metadata will be automatically added to all generated entities. |
+| `cacheEntityName`          | `string`  | KVS Custom entity name for cache storage. Must match the `name` in your `manifest.yml` storage entities configuration. Required for caching functionality. Defaults to `"cache"`.                                                                                                                         |
+| `cacheTTL`                 | `number`  | Default cache TTL in seconds. Defaults to `120` (2 minutes).                                                                                                                                                                   |
+| `cacheWrapTable`           | `boolean` | Whether to wrap table names with backticks in cache keys. Defaults to `true`.                                                                                                                                                  |
+| `hints`                    | `object`  | SQL hints for query optimization. Optional configuration for advanced query tuning.                                                                                                                                             |
 
 ## CLI Commands
 
-Documentation [here](forge-sql-orm-cli/README.md)
+Forge-SQL-ORM provides a command-line interface for managing database migrations and model generation.
+
+**📖 [Full CLI Documentation](forge-sql-orm-cli/README.md)** - Complete CLI reference with all commands and options.
+
+### Quick CLI Reference
+
+The CLI tool provides the following main commands:
+
+- `generate:model` - Generate Drizzle ORM models from your database schema
+- `migrations:create` - Create new migration files
+- `migrations:update` - Update existing migrations with schema changes
+- `migrations:drop` - Create migration to drop tables
+
+### Installation
+
+```bash
+npm install -g forge-sql-orm-cli
+```
+
+### Basic Usage
+
+```bash
+# Generate models from database
+forge-sql-orm-cli generate:model --dbName myapp --output ./database/entities
+
+# Create migration
+forge-sql-orm-cli migrations:create --dbName myapp --entitiesPath ./database/entities
+
+# Update migration
+forge-sql-orm-cli migrations:update --dbName myapp --entitiesPath ./database/entities
+```
+
+For detailed information about all available options and advanced usage, see the [Full CLI Documentation](forge-sql-orm-cli/README.md).
 
 ## Web Triggers for Migrations
 
@@ -718,6 +1878,41 @@ CREATE TABLE IF NOT EXISTS orders (...);
 SET foreign_key_checks = 1;
 ```
 
+### 4. Clear Cache Scheduler Trigger
+
+This trigger automatically cleans up expired cache entries based on their TTL (Time To Live). It's useful for:
+- Automatic cache maintenance
+- Preventing cache storage from growing indefinitely
+- Ensuring optimal cache performance
+- Reducing storage costs
+
+```typescript
+// Example usage in your Forge app
+import { clearCacheSchedulerTrigger } from "forge-sql-orm";
+
+export const clearCache = () => {
+  return clearCacheSchedulerTrigger({ 
+    cacheEntityName: "cache",
+  });
+};
+```
+
+Configure in `manifest.yml`:
+```yaml
+  scheduledTrigger:
+    - key: clear-cache-trigger
+      function: clearCache
+      interval: fiveMinute
+  function:
+    - key: clearCache
+      handler: index.clearCache
+```
+
+**Available Intervals**:
+- `fiveMinute` - Every 5 minutes
+- `hour` - Every hour
+- `day` - Every day
+
 ### Important Notes
 
 **Security Considerations**:
@@ -733,34 +1928,20 @@ SET foreign_key_checks = 1;
 
 ## Query Analysis and Performance Optimization
 
-⚠️ **IMPORTANT NOTE**: The query analysis features described below are experimental and should be used only for troubleshooting purposes. These features rely on TiDB's `information_schema` and `performance_schema` which may change in future updates. As of April 2025, these features are available but their future availability is not guaranteed.
+[↑ Back to Top](#table-of-contents)
+
+Forge-SQL-ORM provides comprehensive query analysis tools to help you optimize your database queries and identify performance bottlenecks.
 
 ### About Atlassian's Built-in Analysis Tools
 
-Atlassian already provides comprehensive query analysis tools in the development console, including:
+Atlassian provides comprehensive query analysis tools in the development console, including:
 - Basic query performance metrics
 - Slow query tracking (queries over 500ms)
 - Basic execution statistics
 - Query history and patterns
 
-Our analysis tools are designed to complement these built-in features by providing additional insights directly from TiDB's system schemas. However, they should be used with caution and only for troubleshooting purposes.
-
-### Usage Guidelines
+Our analysis tools complement these built-in features by providing additional insights directly from TiDB's system schemas.
 
-1. **Development and Troubleshooting Only**
-   - These tools should not be used in production code
-   - Intended only for development and debugging
-   - Use for identifying and fixing performance issues
-
-2. **Schema Stability**
-   - Features rely on TiDB's `information_schema` and `performance_schema`
-   - Schema structure may change in future TiDB updates
-   - No guarantee of long-term availability
-
-3. **Current Availability (April 2025)**
-   - `information_schema` based analysis is currently functional
-   - Query plan analysis is available
-   - Performance metrics collection is working
 
 ### Available Analysis Tools
 
@@ -773,10 +1954,10 @@ const analyzeForgeSql = forgeSQL.analyze();
 
 #### Query Plan Analysis
 
-⚠️ **For Troubleshooting Only**: This feature should only be used during development and debugging sessions.
+Query plan analysis helps you understand how your queries are executed and identify optimization opportunities.
 
 ```typescript
-// Example usage for troubleshooting a specific query
+// Example usage for analyzing a specific query
 const forgeSQL = new ForgeSQL();
 const analyzeForgeSql = forgeSQL.analyze();
 
@@ -801,15 +1982,163 @@ const rawPlan = await analyzeForgeSql.explainRaw(
   "SELECT * FROM users WHERE id = ?",
   [1]
 );
+
+// Analyze new methods
+const usersFromPlan = await analyzeForgeSql.explain(
+  forgeSQL.selectFrom(users).where(eq(users.active, true))
+);
+
+const usersCacheablePlan = await analyzeForgeSql.explain(
+  forgeSQL.selectCacheableFrom(users).where(eq(users.active, true))
+);
+
+// Analyze Common Table Expressions (CTEs)
+const ctePlan = await analyzeForgeSql.explain(
+  forgeSQL
+    .with(
+      forgeSQL.selectFrom(users).where(eq(users.active, true)).as('activeUsers'),
+      forgeSQL.selectFrom(orders).where(eq(orders.status, 'completed')).as('completedOrders')
+    )
+    .select({
+      totalActiveUsers: sql`COUNT(au.id)`,
+      totalCompletedOrders: sql`COUNT(co.id)`
+    })
+    .from(sql`activeUsers au`)
+    .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`))
+);
 ```
 
-This analysis helps you understand:
+This analysis provides insights into:
 - How the database executes your query
 - Which indexes are being used
 - Estimated vs actual row counts
 - Resource usage at each step
-- Potential performance bottlenecks
+- Performance optimization opportunities
+
+
+## Migration Guide
+
+### Migrating from 2.0.x to 2.1.x
+
+This section covers the breaking changes introduced in version 2.1.x and how to migrate your existing code.
+
+#### 1. Method Renaming (BREAKING CHANGES)
+
+**Removed Methods:**
+- `forgeSQL.modify()` → **REMOVED** (use `forgeSQL.modifyWithVersioning()`)
+- `forgeSQL.crud()` → **REMOVED** (use `forgeSQL.modifyWithVersioning()`)
+
+**Migration Steps:**
+
+1. **Replace `modify()` calls:**
+   ```typescript
+   // ❌ Old (2.0.x) - NO LONGER WORKS
+   await forgeSQL.modify().insert(Users, [userData]);
+   await forgeSQL.modify().updateById(updateData, Users);
+   await forgeSQL.modify().deleteById(1, Users);
+   
+   // ✅ New (2.1.x) - REQUIRED
+   await forgeSQL.modifyWithVersioning().insert(Users, [userData]);
+   await forgeSQL.modifyWithVersioning().updateById(updateData, Users);
+   await forgeSQL.modifyWithVersioning().deleteById(1, Users);
+   ```
+
+2. **Replace `crud()` calls:**
+   ```typescript
+   // ❌ Old (2.0.x) - NO LONGER WORKS
+   await forgeSQL.crud().insert(Users, [userData]);
+   await forgeSQL.crud().updateById(updateData, Users);
+   await forgeSQL.crud().deleteById(1, Users);
+   
+   // ✅ New (2.1.x) - REQUIRED
+   await forgeSQL.modifyWithVersioning().insert(Users, [userData]);
+   await forgeSQL.modifyWithVersioning().updateById(updateData, Users);
+   await forgeSQL.modifyWithVersioning().deleteById(1, Users);
+   ```
+
+#### 2. New API Methods
+
+**New Methods Available:**
+- `forgeSQL.insert()` - Basic Drizzle operations
+- `forgeSQL.update()` - Basic Drizzle operations  
+- `forgeSQL.delete()` - Basic Drizzle operations
+- `forgeSQL.insertAndEvictCache()` - Basic Drizzle operations with evict cache after execution
+- `forgeSQL.updateAndEvictCache()` - Basic Drizzle operations with evict cache after execution
+- `forgeSQL.deleteAndEvictCache()` - Basic Drizzle operations with evict cache after execution
+- `forgeSQL.selectFrom()` - All-column queries with field aliasing
+- `forgeSQL.selectDistinctFrom()` - Distinct all-column queries with field aliasing
+- `forgeSQL.selectCacheableFrom()` - All-column queries with field aliasing and caching
+- `forgeSQL.selectDistinctCacheableFrom()` - Distinct all-column queries with field aliasing and caching
+- `forgeSQL.execute()` - Raw SQL queries with local caching
+- `forgeSQL.executeCacheable()` - Raw SQL queries with local and global caching
+- `forgeSQL.with()` - Common Table Expressions (CTEs)
+
+**Optional Migration:**
+You can optionally migrate to the new API methods for better performance and cache management:
+
+```typescript
+// ❌ Old approach (still works)
+await forgeSQL.modifyWithVersioning().insert(Users, [userData]);
+
+// ✅ New approach (recommended for new code)
+await forgeSQL.insert(Users).values(userData);
+// or for versioned operations with cache management
+await forgeSQL.modifyWithVersioningAndEvictCache().insert(Users, [userData]);
+
+// ✅ New query methods for better performance
+const users = await forgeSQL.selectFrom(Users)
+  .where(eq(Users.active, true));
+
+const usersDistinct = await forgeSQL.selectDistinctFrom(Users)
+  .where(eq(Users.active, true));
+
+const usersCacheable = await forgeSQL.selectCacheableFrom(Users)
+  .where(eq(Users.active, true));
+
+// ✅ Raw SQL execution with caching
+const rawUsers = await forgeSQL.execute(
+  "SELECT * FROM users WHERE active = ?", 
+  [true]
+);
+
+const cachedRawUsers = await forgeSQL.executeCacheable(
+  "SELECT * FROM users WHERE active = ?", 
+  [true], 
+  300
+);
+
+// ✅ Common Table Expressions (CTEs)
+const userStats = await forgeSQL
+  .with(
+    forgeSQL.selectFrom(users).where(eq(users.active, true)).as('activeUsers'),
+    forgeSQL.selectFrom(orders).where(eq(orders.status, 'completed')).as('completedOrders')
+  )
+  .select({
+    totalActiveUsers: sql`COUNT(au.id)`,
+    totalCompletedOrders: sql`COUNT(co.id)`
+  })
+  .from(sql`activeUsers au`)
+  .leftJoin(sql`completedOrders co`, eq(sql`au.id`, sql`co.userId`));
+```
+
+#### 3. Automatic Migration Script
+
+You can use a simple find-and-replace to migrate your code:
+
+```bash
+# Replace modify() calls
+find . -name "*.ts" -o -name "*.js" | xargs sed -i 's/forgeSQL\.modify()/forgeSQL.modifyWithVersioning()/g'
+
+# Replace crud() calls  
+find . -name "*.ts" -o -name "*.js" | xargs sed -i 's/forgeSQL\.crud()/forgeSQL.modifyWithVersioning()/g'
+```
+
+#### 4. Breaking Changes
+
+**Important:** The old methods (`modify()` and `crud()`) have been completely removed in version 2.1.x.
 
+- ❌ **2.1.x**: Old methods are no longer available
+- ✅ **Migration Required**: You must update your code to use the new methods
 
 ## License
 This project is licensed under the **MIT License**.