forge-sql-orm 2.0.17 → 2.0.19

package/src/core/ForgeSQLQueryBuilder.ts

@@ -10,39 +10,61 @@ import {
   MySqlSelectDynamic,
   type SelectedFields,
 } from "drizzle-orm/mysql-core/query-builders/select.types";
-import { InferInsertModel, SQL } from "drizzle-orm";
+import { InferInsertModel, Query, SQL } from "drizzle-orm";
 import moment from "moment/moment";
 import { parseDateTime } from "../utils/sqlUtils";
 import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT } from "drizzle-orm/mysql-proxy/index";
-
-// ============= Core Types =============
+import { SqlHints } from "../utils/sqlHints";
+import {
+  ClusterStatementRowCamelCase,
+  ExplainAnalyzeRow,
+  SlowQueryNormalized,
+} from "./SystemTables";
 
 /**
- * Interface representing the main ForgeSQL operations.
- * Provides access to CRUD operations and schema-level SQL operations.
+ * Core interface for ForgeSQL operations.
+ * Provides access to CRUD operations, schema-level SQL operations, and query analysis capabilities.
+ *
+ * @interface ForgeSqlOperation
+ * @extends {QueryBuilderForgeSql}
  */
 export interface ForgeSqlOperation extends QueryBuilderForgeSql {
   /**
-   * Provides CRUD (Create, Read, Update, Delete) operations.
+   * Provides CRUD (Create, Update, Delete) operations.
+   * @deprecated Use modify() instead for better type safety and consistency
    * @returns {CRUDForgeSQL} Interface for performing CRUD operations
    */
   crud(): CRUDForgeSQL;
 
   /**
-   * Provides schema-level SQL fetch operations.
+   * Provides modify (Create, Update, Delete) operations with optimistic locking support.
+   * @returns {CRUDForgeSQL} Interface for performing CRUD operations
+   */
+  modify(): CRUDForgeSQL;
+
+  /**
+   * Provides schema-level SQL fetch operations with type safety.
    * @returns {SchemaSqlForgeSql} Interface for executing schema-bound SQL queries
    */
   fetch(): SchemaSqlForgeSql;
+
+  /**
+   * Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
+   * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
+   */
+  analyze(): SchemaAnalyzeForgeSql;
 }
 
 /**
  * Interface for Query Builder operations.
- * Provides access to the underlying Drizzle ORM query builder.
+ * Provides access to the underlying Drizzle ORM query builder with enhanced functionality.
+ *
+ * @interface QueryBuilderForgeSql
  */
 export interface QueryBuilderForgeSql {
   /**
    * Creates a new query builder for the given entity.
-   * @returns {MySql2Database<Record<string, unknown>>} The Drizzle database instance for building queries
+   * @returns {MySqlRemoteDatabase<Record<string, unknown>>} The Drizzle database instance for building queries
    */
   getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>>;
 
@@ -87,25 +109,25 @@ export interface QueryBuilderForgeSql {
   ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
 }
 
-// ============= CRUD Operations =============
-
 /**
- * Interface for CRUD (Create, Read, Update, Delete) operations.
+ * Interface for Modify (Create, Update, Delete) operations.
  * Provides methods for basic database operations with support for optimistic locking.
+ *
+ * @interface CRUDForgeSQL
  */
 export interface CRUDForgeSQL {
   /**
    * Inserts multiple records into the database.
    * @template T - The type of the table schema
    * @param {T} schema - The entity schema
-   * @param {Partial<InferInsertModel<T>>[]} models - The list of entities to insert
+   * @param {InferInsertModel<T>[]} models - The list of entities to insert
    * @param {boolean} [updateIfExists] - Whether to update the row if it already exists (default: false)
    * @returns {Promise<number>} The number of inserted rows
    * @throws {Error} If the insert operation fails
    */
   insert<T extends AnyMySqlTable>(
     schema: T,
-    models: Partial<InferInsertModel<T>>[],
+    models: InferInsertModel<T>[],
     updateIfExists?: boolean,
   ): Promise<number>;
 
@@ -158,11 +180,81 @@ export interface CRUDForgeSQL {
   ): Promise<number>;
 }
 
-// ============= Schema SQL Operations =============
+/**
+ * Interface for schema analysis operations.
+ * Provides methods for analyzing query performance and execution plans.
+ *
+ * @interface SchemaAnalyzeForgeSql
+ */
+export interface SchemaAnalyzeForgeSql {
+  /**
+   * Executes EXPLAIN on a Drizzle query.
+   * @param {{ toSQL: () => Query }} query - The Drizzle query to analyze
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  explain(query: { toSQL: () => Query }): Promise<ExplainAnalyzeRow[]>;
+
+  /**
+   * Executes EXPLAIN on a raw SQL query.
+   * @param {string} query - The SQL query to analyze
+   * @param {unknown[]} bindParams - The query parameters
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  explainRaw(query: string, bindParams: unknown[]): Promise<ExplainAnalyzeRow[]>;
+
+  /**
+   * Executes EXPLAIN ANALYZE on a Drizzle query.
+   * @param {{ toSQL: () => Query }} query - The Drizzle query to analyze
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  explainAnalyze(query: { toSQL: () => Query }): Promise<ExplainAnalyzeRow[]>;
+
+  /**
+   * Executes EXPLAIN ANALYZE on a raw SQL query.
+   * @param {string} query - The SQL query to analyze
+   * @param {unknown[]} bindParams - The query parameters
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  explainAnalyzeRaw(query: string, bindParams: unknown[]): Promise<ExplainAnalyzeRow[]>;
+
+  /**
+   * Analyzes slow queries from the database.
+   * @returns {Promise<SlowQueryNormalized[]>} The normalized slow query data
+   */
+  analyzeSlowQueries(): Promise<SlowQueryNormalized[]>;
+
+  /**
+   * Analyzes query history for specific tables using Drizzle table objects.
+   * @param {AnyMySqlTable[]} tables - The Drizzle table objects to analyze
+   * @param {Date} [fromDate] - The start date for the analysis
+   * @param {Date} [toDate] - The end date for the analysis
+   * @returns {Promise<ClusterStatementRowCamelCase[]>} The analyzed query history
+   */
+  analyzeQueriesHistory(
+    tables: AnyMySqlTable[],
+    fromDate?: Date,
+    toDate?: Date,
+  ): Promise<ClusterStatementRowCamelCase[]>;
+
+  /**
+   * Analyzes query history for specific tables using raw table names.
+   * @param {string[]} tables - The table names to analyze
+   * @param {Date} [fromDate] - The start date for the analysis
+   * @param {Date} [toDate] - The end date for the analysis
+   * @returns {Promise<ClusterStatementRowCamelCase[]>} The analyzed query history
+   */
+  analyzeQueriesHistoryRaw(
+    tables: string[],
+    fromDate?: Date,
+    toDate?: Date,
+  ): Promise<ClusterStatementRowCamelCase[]>;
+}
 
 /**
  * Interface for schema-level SQL operations.
  * Provides methods for executing SQL queries with schema binding and type safety.
+ *
+ * @interface SchemaSqlForgeSql
  */
 export interface SchemaSqlForgeSql {
   /**
@@ -199,11 +291,11 @@ export interface SchemaSqlForgeSql {
   executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse>;
 }
 
-// ============= Configuration Types =============
-
 /**
  * Interface for version field metadata.
  * Defines the configuration for optimistic locking version fields.
+ *
+ * @interface VersionFieldMetadata
  */
 export interface VersionFieldMetadata {
   /** Name of the version field */
@@ -213,6 +305,8 @@ export interface VersionFieldMetadata {
 /**
  * Interface for table metadata.
  * Defines the configuration for a specific table.
+ *
+ * @interface TableMetadata
  */
 export interface TableMetadata {
   /** Name of the table */
@@ -224,26 +318,23 @@ export interface TableMetadata {
 /**
  * Type for additional metadata configuration.
  * Maps table names to their metadata configuration.
+ *
+ * @type {AdditionalMetadata}
  */
 export type AdditionalMetadata = Record<string, TableMetadata>;
 
 /**
- * Options for configuring ForgeSQL ORM behavior.
+ * Interface for ForgeSQL ORM options
+ *
+ * @interface ForgeSqlOrmOptions
  */
 export interface ForgeSqlOrmOptions {
-  /**
-   * Enables logging of raw SQL queries in the Atlassian Forge Developer Console.
-   * Useful for debugging and monitoring SQL operations.
-   * @default false
-   */
+  /** Whether to log raw SQL queries */
   logRawSqlQuery?: boolean;
-
-  /**
-   * Disables optimistic locking for all operations.
-   * When enabled, version checks are skipped during updates.
-   * @default false
-   */
+  /** Whether to disable optimistic locking */
   disableOptimisticLocking?: boolean;
+  /** SQL hints to be applied to queries */
+  hints?: SqlHints;
 
   /**
    * Additional metadata for table configuration.
@@ -265,11 +356,11 @@ export interface ForgeSqlOrmOptions {
   additionalMetadata?: AdditionalMetadata;
 }
 
-// ============= Custom Types =============
-
 /**
  * Custom type for MySQL datetime fields.
  * Handles conversion between JavaScript Date objects and MySQL datetime strings.
+ *
+ * @type {CustomType}
  */
 export const forgeDateTimeString = customType<{
   data: Date;
@@ -291,6 +382,8 @@ export const forgeDateTimeString = customType<{
 /**
  * Custom type for MySQL timestamp fields.
  * Handles conversion between JavaScript Date objects and MySQL timestamp strings.
+ *
+ * @type {CustomType}
  */
 export const forgeTimestampString = customType<{
   data: Date;
@@ -301,7 +394,7 @@ export const forgeTimestampString = customType<{
     return "timestamp";
   },
   toDriver(value: Date) {
-    return moment(value as Date).format("YYYY-MM-DDTHH:mm:ss.SSS");
+    return moment(new Date(value)).format("YYYY-MM-DDTHH:mm:ss.SSS");
   },
   fromDriver(value: unknown) {
     const format = "YYYY-MM-DDTHH:mm:ss.SSS";
@@ -312,6 +405,8 @@ export const forgeTimestampString = customType<{
 /**
  * Custom type for MySQL date fields.
  * Handles conversion between JavaScript Date objects and MySQL date strings.
+ *
+ * @type {CustomType}
  */
 export const forgeDateString = customType<{
   data: Date;
@@ -333,6 +428,8 @@ export const forgeDateString = customType<{
 /**
  * Custom type for MySQL time fields.
  * Handles conversion between JavaScript Date objects and MySQL time strings.
+ *
+ * @type {CustomType}
  */
 export const forgeTimeString = customType<{
   data: Date;

package/src/core/ForgeSQLSelectOperations.ts

@@ -57,9 +57,8 @@ export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
    */
   async executeRawSQL<T extends object | unknown>(query: string, params?: unknown[]): Promise<T[]> {
     if (this.options.logRawSqlQuery) {
-      console.debug(
-        `Executing with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : "",
-      );
+      const paramsStr = params ? `, with params: ${JSON.stringify(params)}` : "";
+      console.debug(`Executing with SQL ${query}${paramsStr}`);
     }
     const sqlStatement = sql.prepare<T>(query);
     if (params) {
@@ -82,9 +81,8 @@ export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
     }
     if (this.options.logRawSqlQuery) {
       console.debug(
-        `Executing Update with SQL ${query}` + params
-          ? `, with params: ${JSON.stringify(params)}`
-          : "",
+        `Executing Update with SQL ${query}` +
+          (params ? `, with params: ${JSON.stringify(params)}` : ""),
       );
     }
     const updateQueryResponseResults = await sqlStatement.execute();

package/src/core/SystemTables.ts

@@ -1,5 +1,6 @@
 import { bigint, mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
 import { Table } from "drizzle-orm";
+import { sql } from "@forge/sql";
 
 export const migrations = mysqlTable("__migrations", {
   id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
@@ -7,4 +8,178 @@ export const migrations = mysqlTable("__migrations", {
   migratedAt: timestamp("migratedAt").defaultNow().notNull(),
 });
 
+export interface ExplainAnalyzeRow {
+  id: string;
+  estRows?: string;
+  estCost?: string;
+  actRows?: string;
+  task?: string;
+  accessObject?: string;
+  executionInfo?: string;
+  operatorInfo?: string;
+  memory?: string;
+  disk?: string;
+}
+
+export interface SlowQueryNormalized {
+  time: string;
+  txnStartTs: number;
+  user: string;
+  host: string;
+  connId: number;
+  db: string;
+  query: string;
+  digest: string;
+  queryTime: number;
+  compileTime: number;
+  optimizeTime: number;
+  processTime: number;
+  waitTime: number;
+  parseTime: number;
+  rewriteTime: number;
+  copTime: number;
+  copProcAvg: number;
+  copProcMax: number;
+  copProcP90: number;
+  copProcAddr: string;
+  copWaitAvg: number;
+  copWaitMax: number;
+  copWaitP90: number;
+  copWaitAddr: string;
+  memMax: number;
+  diskMax: number;
+  totalKeys: number;
+  processKeys: number;
+  requestCount: number;
+  kvTotal: number;
+  pdTotal: number;
+  resultRows: number;
+  rocksdbBlockCacheHitCount: number;
+  rocksdbBlockReadCount: number;
+  rocksdbBlockReadByte: number;
+  plan: string;
+  parsedPlan?: ExplainAnalyzeRow[];
+  binaryPlan: string;
+  planDigest: string;
+}
+
+export interface ClusterStatementRowCamelCase {
+  instance: string;
+  summaryBeginTime: string;
+  summaryEndTime: string;
+  stmtType: string;
+  schemaName: string;
+  digest: string;
+  digestText: string;
+  tableNames: string;
+  indexNames: string | null;
+  sampleUser: string;
+  execCount: number;
+  sumErrors: number;
+  sumWarnings: number;
+  sumLatency: number;
+  maxLatency: number;
+  minLatency: number;
+  avgLatency: number;
+  avgParseLatency: number;
+  maxParseLatency: number;
+  avgCompileLatency: number;
+  maxCompileLatency: number;
+  sumCopTaskNum: number;
+  maxCopProcessTime: number;
+  maxCopProcessAddress: string;
+  maxCopWaitTime: number;
+  maxCopWaitAddress: string;
+  avgProcessTime: number;
+  maxProcessTime: number;
+  avgWaitTime: number;
+  maxWaitTime: number;
+  avgBackoffTime: number;
+  maxBackoffTime: number;
+  avgTotalKeys: number;
+  maxTotalKeys: number;
+  avgProcessedKeys: number;
+  maxProcessedKeys: number;
+  avgRocksdbDeleteSkippedCount: number;
+  maxRocksdbDeleteSkippedCount: number;
+  avgRocksdbKeySkippedCount: number;
+  maxRocksdbKeySkippedCount: number;
+  avgRocksdbBlockCacheHitCount: number;
+  maxRocksdbBlockCacheHitCount: number;
+  avgRocksdbBlockReadCount: number;
+  maxRocksdbBlockReadCount: number;
+  avgRocksdbBlockReadByte: number;
+  maxRocksdbBlockReadByte: number;
+  avgPrewriteTime: number;
+  maxPrewriteTime: number;
+  avgCommitTime: number;
+  maxCommitTime: number;
+  avgGetCommitTsTime: number;
+  maxGetCommitTsTime: number;
+  avgCommitBackoffTime: number;
+  maxCommitBackoffTime: number;
+  avgResolveLockTime: number;
+  maxResolveLockTime: number;
+  avgLocalLatchWaitTime: number;
+  maxLocalLatchWaitTime: number;
+  avgWriteKeys: number;
+  maxWriteKeys: number;
+  avgWriteSize: number;
+  maxWriteSize: number;
+  avgPrewriteRegions: number;
+  maxPrewriteRegions: number;
+  avgTxnRetry: number;
+  maxTxnRetry: number;
+  sumExecRetry: number;
+  sumExecRetryTime: number;
+  sumBackoffTimes: number;
+  backoffTypes: string | null;
+  avgMem: number;
+  maxMem: number;
+  avgDisk: number;
+  maxDisk: number;
+  avgKvTime: number;
+  avgPdTime: number;
+  avgBackoffTotalTime: number;
+  avgWriteSqlRespTime: number;
+  avgTidbCpuTime: number;
+  avgTikvCpuTime: number;
+  maxResultRows: number;
+  minResultRows: number;
+  avgResultRows: number;
+  prepared: number;
+  avgAffectedRows: number;
+  firstSeen: string;
+  lastSeen: string;
+  planInCache: number;
+  planCacheHits: number;
+  planInBinding: number;
+  querySampleText: string;
+  prevSampleText: string;
+  planDigest: string;
+  plan: string;
+  binaryPlan: string;
+  charset: string;
+  collation: string;
+  planHint: string;
+  maxRequestUnitRead: number;
+  avgRequestUnitRead: number;
+  maxRequestUnitWrite: number;
+  avgRequestUnitWrite: number;
+  maxQueuedRcTime: number;
+  avgQueuedRcTime: number;
+  resourceGroup: string;
+  planCacheUnqualified: number;
+  planCacheUnqualifiedLastReason: string;
+  parsedPlan?: ExplainAnalyzeRow[];
+}
+
+/**
+ * Retrieves all tables from the database
+ */
+export async function getTables(): Promise<string[]> {
+  const tables = await sql.executeDDL<string>("SHOW TABLES");
+  return tables.rows.flatMap((tableInfo) => Object.values(tableInfo));
+}
+
 export const forgeSystemTables: Table[] = [migrations];

package/src/index.ts

@@ -7,5 +7,6 @@ export * from "./utils/sqlUtils";
 export * from "./utils/forgeDriver";
 export * from "./webtriggers";
 export * from "./lib/drizzle/extensions/selectAliased";
+export * from "./core/SystemTables";
 
 export default ForgeSQLORM;

package/src/utils/forgeDriverProxy.ts

@@ -0,0 +1,27 @@
+import { forgeDriver } from "./forgeDriver";
+import { injectSqlHints, SqlHints } from "./sqlHints";
+
+/**
+ * Creates a proxy for the forgeDriver that injects SQL hints
+ * @returns A proxied version of the forgeDriver
+ */
+export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: boolean) {
+  return async (
+    query: string,
+    params: any[],
+    method: "all" | "execute",
+  ): Promise<{
+    rows: any[];
+    insertId?: number;
+    affectedRows?: number;
+  }> => {
+    // Inject SQL hints into the query
+    const modifiedQuery = injectSqlHints(query, options);
+
+    if (options && logRawSqlQuery && modifiedQuery !== query) {
+      console.warn("modified query: " + modifiedQuery);
+    }
+    // Call the original forgeDriver with the modified query
+    return forgeDriver(modifiedQuery, params, method);
+  };
+}

package/src/utils/sqlHints.ts

@@ -0,0 +1,63 @@
+/**
+ * Interface for SQL hints configuration
+ */
+export interface SqlHints {
+  /** SQL hints for SELECT queries */
+  select?: string[];
+  /** SQL hints for INSERT queries */
+  insert?: string[];
+  /** SQL hints for UPDATE queries */
+  update?: string[];
+  /** SQL hints for DELETE queries */
+  delete?: string[];
+}
+
+/**
+ * Detects the type of SQL query and injects appropriate hints
+ * @param query - The SQL query to analyze
+ * @param hints - The hints configuration
+ * @returns The modified query with injected hints
+ */
+export function injectSqlHints(query: string, hints?: SqlHints): string {
+  if (!hints) {
+    return query;
+  }
+
+  // Normalize the query for easier matching
+  const normalizedQuery = query.trim().toUpperCase();
+
+  // Get the appropriate hints based on query type
+  let queryHints: string[] | undefined;
+
+  if (normalizedQuery.startsWith("SELECT")) {
+    queryHints = hints.select;
+  } else if (normalizedQuery.startsWith("INSERT")) {
+    queryHints = hints.insert;
+  } else if (normalizedQuery.startsWith("UPDATE")) {
+    queryHints = hints.update;
+  } else if (normalizedQuery.startsWith("DELETE")) {
+    queryHints = hints.delete;
+  }
+
+  // If no hints for this query type, return original query
+  if (!queryHints || queryHints.length === 0) {
+    return query;
+  }
+
+  // Join all hints with spaces
+  const hintsString = queryHints.join(" ");
+
+  // Inject hints into the query
+  if (normalizedQuery.startsWith("SELECT")) {
+    return `SELECT /*+ ${hintsString} */ ${query.substring(6)}`;
+  } else if (normalizedQuery.startsWith("INSERT")) {
+    return `INSERT /*+ ${hintsString} */ ${query.substring(6)}`;
+  } else if (normalizedQuery.startsWith("UPDATE")) {
+    return `UPDATE /*+ ${hintsString} */ ${query.substring(6)}`;
+  } else if (normalizedQuery.startsWith("DELETE")) {
+    return `DELETE /*+ ${hintsString} */ ${query.substring(6)}`;
+  }
+
+  // If no match found, return original query
+  return query;
+}