forge-sql-orm 2.1.13 → 2.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.13",
+  "version": "2.1.15",
   "description": "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.",
   "main": "dist/index.js",
   "homepage": "https://github.com/vzakharchenko/forge-sql-orm#readme",
@@ -21,28 +21,29 @@
     "drizzle-driver",
     "drizzle-custom-driver",
     "orm",
+    "rovo",
     "database"
   ],
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/luxon": "^3.7.1",
     "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.47.0",
-    "@typescript-eslint/parser": "^8.47.0",
-    "@vitest/coverage-v8": "^4.0.12",
-    "@vitest/ui": "^4.0.12",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "@vitest/coverage-v8": "^4.0.14",
+    "@vitest/ui": "^4.0.14",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-vitest": "^0.5.4",
     "husky": "^9.1.7",
-    "knip": "^5.70.1",
+    "knip": "^5.70.2",
     "patch-package": "^8.0.1",
-    "prettier": "^3.6.2",
+    "prettier": "^3.7.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vitest": "^4.0.12"
+    "vitest": "^4.0.14"
   },
   "license": "MIT",
   "author": "Vasyl Zakharchenko",
@@ -70,14 +71,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@forge/sql": "^3.0.10",
+    "@forge/sql": "^3.0.12",
     "drizzle-orm": "^0.44.7"
   },
   "optionalDependencies": {
-    "@forge/kvs": "^1.0.8"
+    "@forge/kvs": "^1.2.0"
   },
   "dependencies": {
-    "luxon": "^3.7.2"
+    "luxon": "^3.7.2",
+    "node-sql-parser": "^5.3.13"
   },
   "lint-staged": {
     "*.{ts,tsx,css,scss,md}": [

package/src/core/ForgeSQLORM.ts

@@ -5,6 +5,7 @@ import {
   ForgeSqlOrmOptions,
   SchemaAnalyzeForgeSql,
   SchemaSqlForgeSql,
+  RovoIntegration,
 } from "./ForgeSQLQueryBuilder";
 import { ForgeSQLSelectOperations } from "./ForgeSQLSelectOperations";
 import {
@@ -38,9 +39,14 @@ import { cacheApplicationContext, localCacheApplicationContext } from "../utils/
 import { clearTablesCache } from "../utils/cacheUtils";
 import { SQLWrapper } from "drizzle-orm/sql/sql";
 import { WithSubquery } from "drizzle-orm/subquery";
-import { getLastestMetadata, metadataQueryContext } from "../utils/metadataContextUtils";
+import {
+  getLastestMetadata,
+  metadataQueryContext,
+  MetadataQueryOptions,
+} from "../utils/metadataContextUtils";
 import { operationTypeQueryContext } from "../utils/requestTypeContextUtils";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
+import { Rovo } from "./Rovo";
 
 /**
  * Implementation of ForgeSQLORM that uses Drizzle ORM for query building.
@@ -122,7 +128,15 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    * @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.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @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
@@ -134,12 +148,12 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (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 printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -162,12 +176,12 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    *           .where(eq(demoOrders.userId, demoUsers.id));
    *         return { users, orders };
    *       },
-   *       async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *       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 printQueries(); // Optionally log or capture diagnostics for further analysis
+   *           await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
    *         } else if (totalDbExecutionTime > threshold) {
    *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *         }
@@ -183,7 +197,47 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    * });
    * ```
    *
-   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+   * @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<T>(
     query: () => Promise<T>,
@@ -192,6 +246,7 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T> {
     return metadataQueryContext.run(
       {
@@ -202,6 +257,8 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
         printQueriesWithPlan: async () => {
           return;
         },
+        options: options,
+        statistics: [],
       },
       async () => {
         const result = await query();
@@ -827,6 +884,37 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
   with(...queries: WithSubquery[]) {
     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(): RovoIntegration {
+    return new Rovo(this, this.options);
+  }
 }
 
 /**
@@ -853,7 +941,15 @@ class ForgeSQLORM implements ForgeSqlOperation {
    * @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.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @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
@@ -865,12 +961,12 @@ class ForgeSQLORM implements ForgeSqlOperation {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (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 printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -893,12 +989,12 @@ class ForgeSQLORM implements ForgeSqlOperation {
    *           .where(eq(demoOrders.userId, demoUsers.id));
    *         return { users, orders };
    *       },
-   *       async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *       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 printQueries(); // Optionally log or capture diagnostics for further analysis
+   *           await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
    *         } else if (totalDbExecutionTime > threshold) {
    *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *         }
@@ -914,7 +1010,7 @@ class ForgeSQLORM implements ForgeSqlOperation {
    * });
    * ```
    *
-   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+   * @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<T>(
     query: () => Promise<T>,
@@ -923,8 +1019,9 @@ class ForgeSQLORM implements ForgeSqlOperation {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T> {
-    return this.ormInstance.executeWithMetadata(query, onMetadata);
+    return this.ormInstance.executeWithMetadata(query, onMetadata, options);
   }
 
   selectCacheable<TSelection extends SelectedFields>(
@@ -1390,6 +1487,37 @@ class ForgeSQLORM implements ForgeSqlOperation {
   with(...queries: WithSubquery[]) {
     return this.ormInstance.getDrizzleQueryBuilder().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(): RovoIntegration {
+    return this.ormInstance.rovo();
+  }
 }
 
 export default ForgeSQLORM;

package/src/core/ForgeSQLQueryBuilder.ts

@@ -1,4 +1,4 @@
-import { UpdateQueryResponse } from "@forge/sql";
+import { Result, UpdateQueryResponse } from "@forge/sql";
 import { SqlParameters } from "@forge/sql/out/sql-statement";
 import {
   AnyMySqlSelectQueryBuilder,
@@ -56,6 +56,8 @@ import { SQLWrapper } from "drizzle-orm/sql/sql";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
 import type { WithBuilder } from "drizzle-orm/mysql-core/subquery";
 import { WithSubquery } from "drizzle-orm/subquery";
+import { MySqlColumn } from "drizzle-orm/mysql-core";
+import { MetadataQueryOptions } from "../utils/metadataContextUtils";
 
 /**
  * Core interface for ForgeSQL operations.
@@ -120,6 +122,35 @@ export interface ForgeSqlOperation extends QueryBuilderForgeSql {
    * @returns {ForgeSQLCacheOperations} Interface for executing versioned SQL operations with cache management
    */
   modifyWithVersioningAndEvictCache(): ForgeSQLCacheOperations;
+
+  /**
+   * 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(): RovoIntegration;
 }
 
 /**
@@ -555,7 +586,15 @@ export interface QueryBuilderForgeSql {
    * @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.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @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
@@ -567,12 +606,12 @@ export interface QueryBuilderForgeSql {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (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 printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -625,6 +664,7 @@ export interface QueryBuilderForgeSql {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T>;
   /**
    * Executes a raw SQL query with local cache support.
@@ -998,6 +1038,175 @@ export interface SchemaSqlForgeSql {
   executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse>;
 }
 
+/**
+ * Interface for Rovo integration settings.
+ * Defines configuration for secure dynamic SQL query execution.
+ *
+ * @interface RovoIntegrationSetting
+ */
+export interface RovoIntegrationSetting {
+  /**
+   * Gets the account ID of the active user.
+   *
+   * @returns {string} The account ID of the active user
+   */
+  getActiveUser(): string;
+
+  /**
+   * Gets the context parameters for query substitution.
+   *
+   * @returns {Record<string, string>} Map of parameter names to their values
+   */
+  getParameters(): Record<string, string>;
+
+  /**
+   * Gets the name of the table to query.
+   *
+   * @returns {string} The table name
+   */
+  getTableName(): string;
+
+  /**
+   * Checks if Row-Level Security is enabled.
+   *
+   * @returns {boolean} True if RLS is enabled, false otherwise
+   */
+  isUseRLS(): boolean;
+
+  /**
+   * Generates the WHERE clause for Row-Level Security filtering.
+   *
+   * @param {string} alias - The table alias to use in the WHERE clause
+   * @returns {string} SQL WHERE clause condition for RLS filtering
+   */
+  userScopeWhere(alias: string): string;
+
+  /**
+   * Gets the list of field names required for RLS validation.
+   *
+   * @returns {string[]} Array of field names that must be present in SELECT clause for RLS
+   */
+  userScopeFields(): string[];
+}
+
+/**
+ * Interface for configuring Row-Level Security (RLS) settings.
+ * Provides a fluent API for setting up RLS conditions, required columns, and WHERE clauses.
+ *
+ * @interface RlsSettings
+ */
+export interface RlsSettings {
+  /**
+   * Sets a conditional function to determine if RLS should be applied.
+   *
+   * @param {() => Promise<boolean>} condition - Async function that returns true if RLS should be enabled
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsCondition(condition: () => Promise<boolean>): RlsSettings;
+
+  /**
+   * Adds a column name that must be present in the SELECT clause for RLS validation.
+   *
+   * @param {string} columnName - The name of the column to require
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsColumnName(columnName: string): RlsSettings;
+
+  /**
+   * Adds a Drizzle column that must be present in the SELECT clause for RLS validation.
+   *
+   * @param {MySqlColumn} column - The Drizzle column object
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsColumn(columnName: MySqlColumn): RlsSettings;
+
+  /**
+   * Sets the WHERE clause function for RLS filtering.
+   *
+   * @param {(alias: string) => string} wherePart - Function that generates WHERE clause
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsWherePart(wherePart: (alias: string) => string): RlsSettings;
+
+  /**
+   * Finishes RLS configuration and returns to the settings builder.
+   *
+   * @returns {RovoIntegrationSettingCreator} The parent settings builder
+   */
+  finish(): RovoIntegrationSettingCreator;
+}
+
+/**
+ * Interface for building Rovo integration settings.
+ * Provides a fluent API for configuring query settings including context parameters and RLS.
+ *
+ * @interface RovoIntegrationSettingCreator
+ */
+export interface RovoIntegrationSettingCreator {
+  /**
+   * Adds a context parameter for query substitution.
+   *
+   * @param {string} parameterName - The parameter name to replace in the query
+   * @param {string} value - The value to substitute for the parameter
+   * @returns {RovoIntegrationSettingCreator} This builder instance for method chaining
+   */
+  addContextParameter(parameterName: string, value: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Enables Row-Level Security (RLS) for the query.
+   *
+   * @returns {RlsSettings} RLS settings builder for configuring security options
+   */
+  useRLS(): RlsSettings;
+
+  /**
+   * Builds and returns the RovoIntegrationSetting instance.
+   *
+   * @returns {Promise<RovoIntegrationSetting>} The configured RovoIntegrationSetting instance
+   */
+  build(): Promise<RovoIntegrationSetting>;
+}
+
+/**
+ * Interface for Rovo integration - a secure pattern for natural-language analytics.
+ *
+ * Rovo provides secure execution of dynamic SQL queries with comprehensive security validations.
+ *
+ * @interface RovoIntegration
+ */
+export interface RovoIntegration {
+  /**
+   * Creates a settings builder for Rovo queries using a raw table name.
+   *
+   * @param {string} tableName - The name of the table to query
+   * @param {string} accountId - The account ID of the active user
+   * @returns {RovoIntegrationSettingCreator} Builder for configuring Rovo query settings
+   */
+  rovoRawSettingBuilder(tableName: string, accountId: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Creates a settings builder for Rovo queries using a Drizzle table object.
+   *
+   * @param {AnyMySqlTable} table - The Drizzle table object
+   * @param {string} accountId - The account ID of the active user
+   * @returns {RovoIntegrationSettingCreator} Builder for configuring Rovo query settings
+   */
+  rovoSettingBuilder(table: AnyMySqlTable, accountId: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Executes a dynamic SQL query with comprehensive security validations.
+   *
+   * @param {string} dynamicSql - The SQL query to execute (must be a SELECT statement)
+   * @param {RovoIntegrationSetting} settings - Configuration settings for the query
+   * @returns {Promise<Result<unknown>>} Query execution result with metadata
+   * @throws {Error} If the query violates security restrictions
+   */
+  dynamicIsolatedQuery(
+    dynamicSql: string,
+    settings: RovoIntegrationSetting,
+  ): Promise<Result<unknown>>;
+}
+
 /**
  * Interface for version field metadata.
  * Defines the configuration for optimistic locking version fields.