forge-sql-orm/dist/utils/metadataContextUtils.d.ts

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.

import { AsyncLocalStorage } from "node:async_hooks";
import { ForgeSQLMetadata } from "./forgeDriver";
import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
import { AsyncEventPrintQuery } from "../async/PrintQueryConsumer";
export type Statistic = {
    query: string;
    params: unknown[];
    metadata: ForgeSQLMetadata;
};
export type QueryPlanMode = "TopSlowest" | "SummaryTable";
export type MetadataQueryOptions = {
    mode?: QueryPlanMode;
    summaryTableWindowTime?: number;
    topQueries?: number;
    showSlowestPlans?: boolean;
    normalizeQuery?: boolean;
    asyncQueueName?: string;
};
export type MetadataQueryContext = {
    totalDbExecutionTime: number;
    totalResponseSize: number;
    beginTime: Date;
    options?: MetadataQueryOptions;
    statistics: Statistic[];
    printQueriesWithPlan: () => Promise<void>;
    forgeSQLORM: ForgeSqlOperation;
};
export declare const metadataQueryContext: AsyncLocalStorage<MetadataQueryContext>;
/**
 * Saves query metadata to the current context and sets up the printQueriesWithPlan function.
 *
 * This function accumulates query statistics in the async context. When printQueriesWithPlan
 * is called, it can either:
 * - Queue the analysis for async processing (if asyncQueueName is provided)
 * - Execute the analysis synchronously (fallback or if asyncQueueName is not set)
 *
 * For async processing, the function sends an event to the specified queue with a timeout.
 * If the event cannot be sent within the timeout, it falls back to synchronous execution.
 *
 * @param stringQuery - The SQL query string
 * @param params - Query parameters used in the query
 * @param metadata - Query execution metadata including execution time and response size
 *
 * @example
 * ```typescript
 * await FORGE_SQL_ORM.executeWithMetadata(
 *   async () => {
 *     // ... queries ...
 *   },
 *   async (totalDbExecutionTime, totalResponseSize, printQueries) => {
 *     if (totalDbExecutionTime > threshold) {
 *       await printQueries(); // Will use async queue if configured
 *     }
 *   },
 *   { asyncQueueName: "degradationQueue" }
 * );
 * ```
 */
export declare function saveMetaDataToContext(stringQuery: string, params: unknown[], metadata: ForgeSQLMetadata): Promise<void>;
/**
 * Prints query degradation analysis for the provided event payload.
 *
 * This function processes query degradation events (either from async queue or synchronous call).
 * It first attempts to use summary tables (CLUSTER_STATEMENTS_SUMMARY) if configured and within
 * the time window. Otherwise, it falls back to printing execution plans for the top slowest queries.
 *
 * @param forgeSQLORM - The ForgeSQL operation instance for database access
 * @param params - The async event payload containing query statistics, options, and metadata
 * @returns Promise that resolves when query analysis is complete
 *
 * @see printPlansUsingSummaryTables - For summary table analysis
 * @see printTopQueriesPlans - For top slowest queries analysis
 */
export declare function printDegradationQueries(forgeSQLORM: ForgeSqlOperation, params: AsyncEventPrintQuery): Promise<void>;
/**
 * Gets the latest metadata from the current context.
 * @returns The current metadata context or undefined if not in a context
 */
export declare function getLastestMetadata(): Promise<MetadataQueryContext | undefined>;
//# sourceMappingURL=metadataContextUtils.d.ts.map