forge-sql-orm
Version:
Drizzle ORM integration for Atlassian @forge/sql. Provides a custom driver, schema migration, two levels of caching (local and global via @forge/kvs), optimistic locking, and query analysis.
1,096 lines (1,095 loc) • 58.3 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const ForgeSQLCrudOperations_1 = require("./ForgeSQLCrudOperations");
const ForgeSQLSelectOperations_1 = require("./ForgeSQLSelectOperations");
const mysql_proxy_1 = require("drizzle-orm/mysql-proxy");
const forgeDriverProxy_1 = require("../utils/forgeDriverProxy");
const lib_1 = require("../lib");
const ForgeSQLAnalyseOperations_1 = require("./ForgeSQLAnalyseOperations");
const ForgeSQLCacheOperations_1 = require("./ForgeSQLCacheOperations");
const cacheContextUtils_1 = require("../utils/cacheContextUtils");
const cacheUtils_1 = require("../utils/cacheUtils");
const metadataContextUtils_1 = require("../utils/metadataContextUtils");
const requestTypeContextUtils_1 = require("../utils/requestTypeContextUtils");
const Rovo_1 = require("./Rovo");
/**
* Implementation of ForgeSQLORM that uses Drizzle ORM for query building.
* This class provides a bridge between Forge SQL and Drizzle ORM, allowing
* to use Drizzle's query builder while executing queries through Forge SQL.
*/
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.
*/
constructor(options) {
try {
const newOptions = options ?? {
logRawSqlQuery: false,
logCache: false,
disableOptimisticLocking: false,
cacheWrapTable: true,
cacheTTL: 120,
cacheEntityQueryName: "sql",
cacheEntityExpirationName: "expiration",
cacheEntityDataName: "data",
};
this.options = newOptions;
if (newOptions.logRawSqlQuery) {
// eslint-disable-next-line no-console
console.debug("Initializing ForgeSQLORM...");
}
// Initialize Drizzle instance with our custom driver
const proxiedDriver = (0, forgeDriverProxy_1.createForgeDriverProxy)(this, newOptions.hints, newOptions.logRawSqlQuery);
this.drizzle = (0, lib_1.patchDbWithSelectAliased)((0, mysql_proxy_1.drizzle)(proxiedDriver, { logger: newOptions.logRawSqlQuery }), newOptions);
this.crudOperations = new ForgeSQLCrudOperations_1.ForgeSQLCrudOperations(this, newOptions);
this.fetchOperations = new ForgeSQLSelectOperations_1.ForgeSQLSelectOperations(newOptions);
this.analyzeOperations = new ForgeSQLAnalyseOperations_1.ForgeSQLAnalyseOperation(this);
this.cacheOperations = new ForgeSQLCacheOperations_1.ForgeSQLCacheOperations(newOptions, this);
}
catch (error) {
// eslint-disable-next-line no-console
console.error("ForgeSQLORM initialization failed:", error);
throw error;
}
}
/**
* Executes a query and provides access to execution metadata with performance monitoring.
* This method allows you to capture detailed information about query execution
* including database execution time, response size, and query analysis capabilities.
*
* The method aggregates metrics across all database operations within the query function,
* making it ideal for monitoring resolver performance and detecting performance issues.
*
* @template T - The return type of the query
* @param query - A function that returns a Promise with the query result. Can contain multiple database operations.
* @param onMetadata - Callback function that receives aggregated execution metadata
* @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
* @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
* @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
* - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
* - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
* @param options - Optional configuration for query plan printing behavior
* @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
* @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
* @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
* @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
* @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
* @returns Promise with the query result
*
* @example
* ```typescript
* // Basic usage with performance monitoring
* const result = await forgeSQL.executeWithMetadata(
* async () => {
* const users = await forgeSQL.selectFrom(usersTable);
* const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
* return { users, orders };
* },
* (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* const threshold = 500; // ms baseline for this resolver
*
* if (totalDbExecutionTime > threshold * 1.5) {
* console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
* await printQueriesWithPlan(); // Analyze and print query execution plans
* } else if (totalDbExecutionTime > threshold) {
* console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
* }
*
* console.log(`DB response size: ${totalResponseSize} bytes`);
* }
* );
* ```
*
* @example
* ```typescript
* // Resolver with performance monitoring
* resolver.define("fetch", async (req: Request) => {
* try {
* return await forgeSQL.executeWithMetadata(
* async () => {
* // Resolver logic with multiple queries
* const users = await forgeSQL.selectFrom(demoUsers);
* const orders = await forgeSQL.selectFrom(demoOrders)
* .where(eq(demoOrders.userId, demoUsers.id));
* return { users, orders };
* },
* async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* const threshold = 500; // ms baseline for this resolver
*
* if (totalDbExecutionTime > threshold * 1.5) {
* console.warn(`[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
* await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
* } else if (totalDbExecutionTime > threshold) {
* console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
* }
*
* console.log(`DB response size: ${totalResponseSize} bytes`);
* }
* );
* } catch (e) {
* const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
* console.error(error, e);
* throw error;
* }
* });
* ```
*
* @example
* ```typescript
* // Using TopSlowest mode with custom topQueries
* const result = await forgeSQL.executeWithMetadata(
* async () => {
* const users = await forgeSQL.selectFrom(usersTable);
* return users;
* },
* async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* if (totalDbExecutionTime > 1000) {
* await printQueriesWithPlan(); // Will print top 3 slowest queries
* }
* },
* {
* mode: 'TopSlowest', // Print top slowest queries (default)
* topQueries: 3, // Print top 3 slowest queries
* }
* );
* ```
*
* @example
* ```typescript
* // Using SummaryTable mode for query analysis
* const result = await forgeSQL.executeWithMetadata(
* async () => {
* const users = await forgeSQL.selectFrom(usersTable);
* return users;
* },
* async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* if (totalDbExecutionTime > 1000) {
* await printQueriesWithPlan(); // Will use CLUSTER_STATEMENTS_SUMMARY if within time window
* }
* },
* {
* mode: 'SummaryTable', // Use summary tables mode
* summaryTableWindowTime: 10000, // 10 second window
* }
* );
* ```
*
* @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
*/
async executeWithMetadata(query, onMetadata, options) {
return metadataContextUtils_1.metadataQueryContext.run({
totalDbExecutionTime: 0,
totalResponseSize: 0,
beginTime: new Date(),
forgeSQLORM: this,
printQueriesWithPlan: async () => {
return;
},
options: options,
statistics: [],
}, async () => {
const result = await query();
const metadata = await (0, metadataContextUtils_1.getLastestMetadata)();
try {
if (metadata) {
await onMetadata(metadata.totalDbExecutionTime, metadata.totalResponseSize, metadata.printQueriesWithPlan);
}
}
catch (e) {
// eslint-disable-next-line no-console
console.error("[ForgeSQLORM][executeWithMetadata] Failed to run onMetadata callback", {
errorMessage: e?.message,
errorStack: e?.stack,
totalDbExecutionTime: metadata?.totalDbExecutionTime,
totalResponseSize: metadata?.totalResponseSize,
beginTime: metadata?.beginTime,
}, e);
}
return result;
});
}
/**
* 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 cacheContextUtils_1.cacheApplicationContext.run(cacheContextUtils_1.cacheApplicationContext.getStore() ?? { tables: new Set() }, async () => {
try {
return await cacheContext();
}
finally {
await (0, cacheUtils_1.clearTablesCache)(Array.from(cacheContextUtils_1.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 cacheContextUtils_1.localCacheApplicationContext.run(cacheContextUtils_1.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.
*/
modifyWithVersioning() {
return this.crudOperations;
}
/**
* Returns the singleton instance of ForgeSQLORMImpl.
* @param options - Options for configuring ForgeSQL ORM behavior.
* @returns The singleton instance of ForgeSQLORMImpl.
*/
static getInstance(options) {
ForgeSQLORMImpl.instance ??= new ForgeSQLORMImpl(options);
return ForgeSQLORMImpl.instance;
}
/**
* Retrieves the fetch operations instance.
* @returns Fetch operations.
*/
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.
*
* ⚠️ 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.drizzle;
}
/**
* 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.
*
* @template TSelection - The type of the selected fields
* @param {TSelection} fields - Object containing the fields to select, with table schemas as values
* @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
* @throws {Error} If fields parameter is empty
* @example
* ```typescript
* await forgeSQL
* .select({user: users, order: orders})
* .from(orders)
* .innerJoin(users, eq(orders.userId, users.id));
* ```
*/
select(fields) {
if (!fields) {
throw new Error("fields is empty");
}
return this.drizzle.selectAliased(fields);
}
/**
* Creates a 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
* @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
* @throws {Error} If fields parameter is empty
* @example
* ```typescript
* await forgeSQL
* .selectDistinct({user: users, order: orders})
* .from(orders)
* .innerJoin(users, eq(orders.userId, users.id));
* ```
*/
selectDistinct(fields) {
if (!fields) {
throw new Error("fields is empty");
}
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 Data Definition Language (DDL) SQL query.
* DDL operations include CREATE, ALTER, DROP, TRUNCATE, and other schema modification statements.
*
* This method is specifically designed for DDL operations and provides:
* - Proper operation type context for DDL queries
* - No caching (DDL operations should not be cached)
* - Direct execution without query optimization
*
* @template T - The expected return type of the query result
* @param query - The DDL SQL query to execute (SQLWrapper or string)
* @returns Promise with query results
* @throws {Error} If the DDL operation fails
*
* @example
* ```typescript
* // Create a new table
* await forgeSQL.executeDDL(`
* CREATE TABLE users (
* id INT PRIMARY KEY AUTO_INCREMENT,
* name VARCHAR(255) NOT NULL,
* email VARCHAR(255) UNIQUE
* )
* `);
*
* // Alter table structure
* await forgeSQL.executeDDL(sql`
* ALTER TABLE users
* ADD COLUMN created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
* `);
*
* // Drop a table
* await forgeSQL.executeDDL("DROP TABLE IF EXISTS old_users");
* ```
*/
async executeDDL(query) {
return this.executeDDLActions(async () => this.drizzle.executeQuery(query));
}
/**
* Executes a series of actions within a DDL operation context.
* This method provides a way to execute regular SQL queries that should be treated
* as DDL operations, ensuring proper operation type context for performance monitoring.
*
* This method is useful for:
* - Executing regular SQL queries in DDL context for monitoring purposes
* - Wrapping non-DDL operations that should be treated as DDL for analysis
* - Ensuring proper operation type context for complex workflows
* - Maintaining DDL operation context across multiple function calls
*
* @template T - The return type of the actions function
* @param actions - Function containing SQL operations to execute in DDL context
* @returns Promise that resolves to the return value of the actions function
*
* @example
* ```typescript
* // Execute regular SQL queries in DDL context for monitoring
* await forgeSQL.executeDDLActions(async () => {
* const slowQueries = await forgeSQL.execute(`
* SELECT * FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
* WHERE AVG_LATENCY > 1000000
* `);
* return slowQueries;
* });
*
* // Execute complex analysis queries in DDL context
* const result = await forgeSQL.executeDDLActions(async () => {
* const tableInfo = await forgeSQL.execute("SHOW TABLES");
* const performanceData = await forgeSQL.execute(`
* SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY_HISTORY
* WHERE SUMMARY_END_TIME > DATE_SUB(NOW(), INTERVAL 1 HOUR)
* `);
* return { tableInfo, performanceData };
* });
*
* // Execute monitoring queries with error handling
* try {
* await forgeSQL.executeDDLActions(async () => {
* const metrics = await forgeSQL.execute(`
* SELECT COUNT(*) as query_count
* FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
* `);
* console.log(`Total queries: ${metrics[0].query_count}`);
* });
* } catch (error) {
* console.error("Monitoring query failed:", error);
* }
* ```
*/
async executeDDLActions(actions) {
return requestTypeContextUtils_1.operationTypeQueryContext.run({ operationType: "DDL" }, async () => actions());
}
/**
* 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);
}
/**
* Provides access to Rovo integration - a secure pattern for natural-language analytics.
*
* Rovo enables secure execution of dynamic SQL queries with comprehensive security validations:
* - Only SELECT queries are allowed
* - Queries are restricted to a single table
* - JOINs, subqueries, and window functions are blocked
* - Row-Level Security (RLS) support for data isolation
*
* @returns {RovoIntegration} Rovo integration instance for secure dynamic queries
*
* @example
* ```typescript
* const rovo = forgeSQL.rovo();
* const settings = await rovo.rovoSettingBuilder(usersTable, accountId)
* .useRLS()
* .addRlsColumn(usersTable.id)
* .addRlsWherePart((alias) => `${alias}.id = '${accountId}'`)
* .finish()
* .build();
*
* const result = await rovo.dynamicIsolatedQuery(
* "SELECT id, name FROM users WHERE status = 'active'",
* settings
* );
* ```
*/
rovo() {
return new Rovo_1.Rovo(this, this.options);
}
}
/**
* Public class that acts as a wrapper around the private ForgeSQLORMImpl.
* Provides a clean interface for working with Forge SQL and Drizzle ORM.
*/
class ForgeSQLORM {
ormInstance;
constructor(options) {
this.ormInstance = ForgeSQLORMImpl.getInstance(options);
}
/**
* Executes a query and provides access to execution metadata with performance monitoring.
* This method allows you to capture detailed information about query execution
* including database execution time, response size, and query analysis capabilities.
*
* The method aggregates metrics across all database operations within the query function,
* making it ideal for monitoring resolver performance and detecting performance issues.
*
* @template T - The return type of the query
* @param query - A function that returns a Promise with the query result. Can contain multiple database operations.
* @param onMetadata - Callback function that receives aggregated execution metadata
* @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
* @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
* @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
* - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
* - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
* @param options - Optional configuration for query plan printing behavior
* @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
* @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
* @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
* @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
* @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
* @returns Promise with the query result
*
* @example
* ```typescript
* // Basic usage with performance monitoring
* const result = await forgeSQL.executeWithMetadata(
* async () => {
* const users = await forgeSQL.selectFrom(usersTable);
* const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
* return { users, orders };
* },
* (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* const threshold = 500; // ms baseline for this resolver
*
* if (totalDbExecutionTime > threshold * 1.5) {
* console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
* await printQueriesWithPlan(); // Analyze and print query execution plans
* } else if (totalDbExecutionTime > threshold) {
* console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
* }
*
* console.log(`DB response size: ${totalResponseSize} bytes`);
* }
* );
* ```
*
* @example
* ```typescript
* // Resolver with performance monitoring
* resolver.define("fetch", async (req: Request) => {
* try {
* return await forgeSQL.executeWithMetadata(
* async () => {
* // Resolver logic with multiple queries
* const users = await forgeSQL.selectFrom(demoUsers);
* const orders = await forgeSQL.selectFrom(demoOrders)
* .where(eq(demoOrders.userId, demoUsers.id));
* return { users, orders };
* },
* async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
* const threshold = 500; // ms baseline for this resolver
*
* if (totalDbExecutionTime > threshold * 1.5) {
* console.warn(`[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
* await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
* } else if (totalDbExecutionTime > threshold) {
* console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
* }
*
* console.log(`DB response size: ${totalResponseSize} bytes`);
* }
* );
* } catch (e) {
* const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
* console.error(error, e);
* throw error;
* }
* });
* ```
*
* @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
*/
async executeWithMetadata(query, onMetadata, options) {
return this.ormInstance.executeWithMetadata(query, onMetadata, 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.
*
* @template TSelection - The type of the selected fields
* @param {TSelection} fields - Object containing the fields to select, with table schemas as values
* @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
* @throws {Error} If fields parameter is empty
* @example
* ```typescript
* await forgeSQL
* .select({user: users, order: orders})
* .from(orders)
* .innerJoin(users, eq(orders.userId, users.id));
* ```
*/
select(fields) {
return this.ormInstance.select(fields);
}
/**
* Creates a 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
* @returns {MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>} A distinct select query builder with unique field aliases
* @throws {Error} If fields parameter is empty
* @example
* ```typescript
* await forgeSQL
* .selectDistinct({user: users, order: orders})
* .from(orders)
* .innerJoin(users, eq(orders.userId, users.id));
* ```
*/
selectDistinct(fields) {
return this.ormInstance.selectDistinct(fields);
}
/**
* Proxies the `modify` method from `ForgeSQLORMImpl`.
* @returns Modify operations.
*/
modifyWithVersioning() {
return this.ormInstance.modifyWithVersioning();
}
/**
* Proxies the `fetch` method from `ForgeSQLORMImpl`.
* @returns Fetch operations.
*/
fetch() {
return this.ormInstance.fetch();
}
/**
* Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
* @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
*/
analyze() {
return this.ormInstance.analyze();
}
/**
* Provides schema-level SQL cacheable operations with type safety.
* @returns {ForgeSQLCacheOperations} Interface for executing schema-bound SQL queries