drizzle-cube 0.5.6 → 0.5.8

package/dist/server/server/cube-utils.d.ts

@@ -0,0 +1,133 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { Cube, CubeJoin, QueryContext, MultiCubeQueryContext, SqlExpression, SecurityContext } from './types';
+/**
+ * Resolve cube reference (handles direct, lazy, and string name references)
+ *
+ * String references are resolved from the optional `cubes` registry map.
+ * Returns `null` when a string ref cannot be resolved (logs a warning).
+ */
+export declare function resolveCubeReference(ref: Cube | (() => Cube) | string, cubes?: Map<string, Cube>): Cube | null;
+/**
+ * Reverse a semantic relationship type for bidirectional join path resolution.
+ * When traversing a join edge in reverse (target→source instead of source→target),
+ * the relationship semantics flip: belongsTo↔hasMany, hasOne stays hasOne,
+ * belongsToMany stays belongsToMany (symmetric).
+ */
+export declare function reverseRelationship(relationship: string): string;
+/**
+ * Derive SQL join type from semantic relationship
+ */
+export declare function getJoinType(relationship: string, override?: string): string;
+/**
+ * DRIZZLE ORM LIMITATION: SQL Object Mutation Protection
+ *
+ * Create an isolated copy of a SQL expression to prevent mutation issues
+ * when the expression will be reused across multiple query contexts.
+ *
+ * ## Background
+ *
+ * Drizzle SQL objects are mutable - their internal `queryChunks` array can be
+ * modified during query construction. When column objects (like employees.id)
+ * are reused across multiple parts of a query (SELECT, WHERE, GROUP BY), this
+ * mutation can cause:
+ * - Duplicate SQL fragments in generated queries
+ * - Incorrect parameter binding order
+ * - Query execution failures
+ *
+ * ## Evidence from Drizzle Source Code
+ *
+ * Investigation of Drizzle ORM source code (/tmp/drizzle-orm/drizzle-orm/src/sql/sql.ts)
+ * revealed:
+ *
+ * 1. SQL objects have a mutable `queryChunks` array (line 133)
+ * 2. The `append()` method directly mutates this array
+ * 3. No public `clone()` method exists (only internal SQL.Aliased.clone())
+ * 4. The `sql` template function creates NEW arrays but chunks are pushed by reference
+ *
+ * ## The Double Wrapping Pattern
+ *
+ * `sql`${sql`${expr}`}`` creates two layers of SQL isolation:
+ *
+ * **Single wrap** (`sql`${expr}``):
+ * - Creates a new SQL object
+ * - But queryChunks contains REFERENCES to original objects
+ * - Original objects can still be mutated
+ *
+ * **Double wrap** (`sql`${sql`${expr}`}``):
+ * - Inner wrap: Creates fresh SQL from original expression
+ * - Outer wrap: Creates complete isolation from shared state
+ * - When Drizzle processes nested SQL, it recursively builds from inner chunks
+ * - This prevents corruption when SQL expressions are reused
+ *
+ * ## When to Use
+ *
+ * - **resolveSqlExpression()**: ALWAYS (expressions may be reused)
+ * - **buildMeasureExpression()**: ALWAYS (after resolveSqlExpression)
+ * - **New aggregations**: Single wrap OK (creating fresh SQL for first time)
+ *
+ * ## Alternatives Investigated
+ *
+ * - ❌ Use Drizzle's clone() - Doesn't exist publicly
+ * - ❌ Store SQL factory functions - Still returns same column objects
+ * - ❌ Create fresh column references - Impossible, columns are singletons
+ * - ❌ Avoid SQL reuse - Unavoidable (same dimension in SELECT, WHERE, GROUP BY)
+ *
+ * ## Performance Impact
+ *
+ * - Memory: ~200 bytes per wrap (negligible)
+ * - CPU: Two function calls during query building (microseconds)
+ * - No runtime query performance impact
+ *
+ * @param expr - SQL expression that may be reused across query contexts
+ * @returns Isolated SQL expression safe for reuse
+ */
+export declare function isolateSqlExpression(expr: AnyColumn | SQL): SQL;
+/**
+ * Sanitize a property key to prevent prototype pollution.
+ * Keys in this codebase come from validated cube field names (e.g., "Cube.measure")
+ * but CodeQL cannot trace that validation across module boundaries.
+ */
+export declare function safeKey(key: string): string;
+/**
+ * Helper to resolve SQL expressions with mutation protection
+ *
+ * Evaluates function-based SQL expressions and applies isolation to prevent
+ * Drizzle's internal mutation from corrupting reused SQL objects.
+ *
+ * @param expr - Column, SQL object, or function that returns one
+ * @param ctx - Query context for function evaluation
+ * @returns Isolated SQL expression safe for reuse
+ */
+export declare function resolveSqlExpression(expr: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL), ctx: QueryContext): AnyColumn | SQL;
+/**
+ * Helper to create multi-cube query context
+ */
+export declare function createMultiCubeContext(baseContext: QueryContext, cubes: Map<string, Cube>, currentCube: Cube): MultiCubeQueryContext;
+/**
+ * Type guard to check if value is a function-based SQL expression
+ */
+export declare function isFunctionSqlExpression(expr: SqlExpression): expr is (ctx: QueryContext) => AnyColumn | SQL;
+/**
+ * Helper function to create cubes
+ */
+export declare function defineCube(name: string, definition: Omit<Cube, 'name'>): Cube;
+/**
+ * Expanded join information for belongsToMany relationships
+ */
+export interface ExpandedBelongsToManyJoin {
+    /** Junction table joins */
+    junctionJoins: Array<{
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        table: any;
+        condition: SQL;
+    }>;
+    /** Security conditions for junction table (if any) */
+    junctionSecurityConditions?: SQL[];
+}
+/**
+ * Expand a belongsToMany join into junction table joins
+ * This converts a many-to-many relationship into two separate joins:
+ * 1. Source cube -> Junction table
+ * 2. Junction table -> Target cube
+ */
+export declare function expandBelongsToManyJoin(joinDef: CubeJoin, securityContext: SecurityContext): ExpandedBelongsToManyJoin;

package/dist/server/server/database-utils.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseAdapter } from './adapters/base-adapter';
+/**
+ * Create a database adapter for the specified engine type
+ * @param engineType - The database engine type
+ * @returns Database adapter instance
+ */
+export declare function createDatabaseAdapter(engineType: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): DatabaseAdapter;
+/**
+ * Get available database adapters
+ * @returns Array of supported engine types
+ */
+export declare function getSupportedEngines(): ('postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake')[];
+/**
+ * Check if an engine type is supported
+ * @param engineType - Engine type to check
+ * @returns True if supported, false otherwise
+ */
+export declare function isEngineSupported(engineType: string): engineType is 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';

package/dist/server/server/executor.d.ts

@@ -0,0 +1,183 @@
+import { SecurityContext, SemanticQuery, QueryResult, DatabaseExecutor, Cube, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, QueryAnalysis, RLSSetupFn } from './types';
+export declare class QueryExecutor {
+    private dbExecutor;
+    private queryBuilder;
+    private drizzlePlanBuilder;
+    private databaseAdapter;
+    private comparisonQueryBuilder;
+    private funnelQueryBuilder;
+    private flowQueryBuilder;
+    private retentionQueryBuilder;
+    private cacheConfig?;
+    private logicalPlanBuilder;
+    private planOptimiser;
+    private rlsSetup?;
+    constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig, rlsSetup?: RLSSetupFn);
+    /**
+     * Execute a function within a RLS-configured transaction context.
+     * If no rlsSetup function is configured, the function is called directly.
+     * Otherwise, opens a transaction, calls rlsSetup to configure RLS, then
+     * runs fn with this.dbExecutor replaced by a transaction-scoped executor.
+     *
+     * Concurrency-safe: the dbExecutor is per-request (created fresh by
+     * SemanticLayerCompiler.createQueryExecutor), so reassigning this.dbExecutor
+     * only affects this request.
+     */
+    private withRLSContext;
+    /**
+     * Unified query execution method that handles both single and multi-cube queries
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    execute(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Build a logical plan for a query without executing it.
+     * Useful for testing, debugging, and plan inspection.
+     */
+    buildLogicalPlan(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): import('./logical-plan').QueryNode;
+    /**
+     * Analyze planning decisions for a regular query using the same logical
+     * planning path as execution and dry-run SQL generation.
+     */
+    analyzeQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
+    /**
+     * Legacy interface for single cube queries
+     */
+    executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Execute a comparison query with caching support
+     * Wraps executeComparisonQuery with cache set logic
+     */
+    private executeComparisonQueryWithCache;
+    /**
+     * Execute a comparison query with multiple date periods
+     * Expands compareDateRange into multiple sub-queries and merges results
+     */
+    private executeComparisonQuery;
+    private buildComparisonExecutionPlan;
+    /**
+     * Execute a funnel query with caching support
+     */
+    private executeFunnelQueryWithCache;
+    /**
+     * Execute a funnel analysis query
+     */
+    private executeFunnelQuery;
+    /**
+     * Execute a flow query with caching support
+     */
+    private executeFlowQueryWithCache;
+    /**
+     * Execute a flow analysis query
+     * Produces Sankey diagram data (nodes and links)
+     */
+    private executeFlowQuery;
+    /**
+     * Execute a retention query with caching support
+     */
+    private executeRetentionQueryWithCache;
+    /**
+     * Execute a retention analysis query
+     * Calculates cohort-based retention rates
+     */
+    private executeRetentionQuery;
+    /**
+     * Standard query execution (non-comparison)
+     * This is the core execution logic extracted for use by comparison queries
+     */
+    private executeStandardQuery;
+    /**
+     * Create a query context with optional filter cache.
+     */
+    private createQueryContext;
+    /**
+     * Normalize engine type for optimiser passes.
+     * SingleStore follows MySQL SQL semantics for planner choices.
+     */
+    private getOptimiserEngineType;
+    /**
+     * Shared regular-query planning pipeline used by execute, dry-run SQL,
+     * and analysis. This is the single source of planning truth.
+     */
+    private buildRegularQueryArtifacts;
+    /**
+     * Validate that all cubes in the query plan have proper security filtering.
+     * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
+     *
+     * Security is critical in multi-tenant applications - this validation helps
+     * detect cubes that may leak data across tenants.
+     */
+    private validateSecurityContext;
+    /**
+     * Generate raw SQL for debugging (without execution) - unified approach
+     */
+    generateSQL(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate raw SQL for multi-cube queries without execution - unified approach
+     */
+    generateMultiCubeSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a funnel query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunFunnel(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a flow query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunFlow(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunRetention(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Execute EXPLAIN on a query to get the execution plan
+     * Generates the SQL using the same secure path as execute/generateSQL,
+     * then runs EXPLAIN on the database.
+     */
+    explainQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Generate SQL for any query mode without execution.
+     * This is the canonical dry-run SQL entrypoint used by explain/adapters.
+     */
+    dryRunSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL using unified approach (works for both single and multi-cube)
+     */
+    private generateUnifiedSQL;
+    private resolveQueryMode;
+    private validateQueryForMode;
+    private executeQueryByModeWithCache;
+    private executeRegularQueryWithCache;
+    private cacheResult;
+    private generateSqlForMode;
+    private generateComparisonSQL;
+    /**
+     * Generate annotations for UI metadata - unified approach
+     */
+    private generateAnnotations;
+    /**
+     * Pre-build filter SQL and store in cache for reuse across CTEs and main query
+     * This enables parameter deduplication - the same filter values are shared
+     * rather than appearing as separate parameters in different parts of the query
+     */
+    private preloadFilterCache;
+}

package/dist/server/server/executors/base-executor.d.ts

@@ -0,0 +1,16 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, DatabaseExecutor, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+/**
+ * Abstract base class for database executors
+ */
+export declare abstract class BaseDatabaseExecutor implements DatabaseExecutor {
+    db: DrizzleDatabase;
+    schema?: any | undefined;
+    databaseAdapter: DatabaseAdapter;
+    constructor(db: DrizzleDatabase, schema?: any | undefined, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake');
+    abstract execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    abstract getEngineType(): 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    abstract explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    abstract getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}

package/dist/server/server/executors/databend-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class DatabendExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'databend';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * Databend supports EXPLAIN and EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * Databend uses system tables for index information
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating Databend executors
+ */
+export declare function createDatabendExecutor(db: DrizzleDatabase, schema?: any): DatabendExecutor;

package/dist/server/server/executors/duckdb-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class DuckDBExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'duckdb';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * DuckDB supports EXPLAIN and EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * DuckDB uses duckdb_indexes() table function
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating DuckDB executors
+ */
+export declare function createDuckDBExecutor(db: DrizzleDatabase, schema?: any): DuckDBExecutor;

package/dist/server/server/executors/index.d.ts

@@ -0,0 +1,21 @@
+import { DrizzleDatabase, DatabaseExecutor } from '../types';
+/**
+ * Database executors for different database engines
+ * Handles SQL execution with proper type coercion
+ */
+export { BaseDatabaseExecutor } from './base-executor';
+export { PostgresExecutor, createPostgresExecutor } from './postgres-executor';
+export { MySQLExecutor, createMySQLExecutor } from './mysql-executor';
+export { SQLiteExecutor, createSQLiteExecutor } from './sqlite-executor';
+export { SingleStoreExecutor, createSingleStoreExecutor } from './singlestore-executor';
+export { DuckDBExecutor, createDuckDBExecutor } from './duckdb-executor';
+export { DatabendExecutor, createDatabendExecutor } from './databend-executor';
+export { SnowflakeExecutor, createSnowflakeExecutor } from './snowflake-executor';
+/**
+ * Auto-detect database type and create appropriate executor
+ * @param db - Drizzle database instance
+ * @param schema - Optional schema for type inference
+ * @param engineType - Optional explicit engine type override
+ * @returns Appropriate database executor
+ */
+export declare function createDatabaseExecutor(db: DrizzleDatabase, schema?: any, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): DatabaseExecutor;

package/dist/server/server/executors/mysql-executor.d.ts

@@ -0,0 +1,27 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class MySQLExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (measure fields + numeric dimensions)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'mysql' | 'singlestore';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating MySQL executors
+ */
+export declare function createMySQLExecutor(db: DrizzleDatabase, schema?: any): MySQLExecutor;

package/dist/server/server/executors/postgres-executor.d.ts

@@ -0,0 +1,27 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class PostgresExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'postgres';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating PostgreSQL executors
+ */
+export declare function createPostgresExecutor(db: DrizzleDatabase, schema?: any): PostgresExecutor;

package/dist/server/server/executors/singlestore-executor.d.ts

@@ -0,0 +1,9 @@
+import { DrizzleDatabase } from '../types';
+import { MySQLExecutor } from './mysql-executor';
+export declare class SingleStoreExecutor extends MySQLExecutor {
+    getEngineType(): 'singlestore';
+}
+/**
+ * Factory function for creating SingleStore executors
+ */
+export declare function createSingleStoreExecutor(db: DrizzleDatabase, schema?: any): SingleStoreExecutor;

package/dist/server/server/executors/snowflake-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class SnowflakeExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'snowflake';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * Snowflake supports EXPLAIN and EXPLAIN USING TEXT/JSON/TABULAR
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * Snowflake doesn't use traditional indexes (it uses micro-partitioning)
+     */
+    getTableIndexes(_tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating Snowflake executors
+ */
+export declare function createSnowflakeExecutor(db: DrizzleDatabase, schema?: any): SnowflakeExecutor;

package/dist/server/server/executors/sqlite-executor.d.ts

@@ -0,0 +1,28 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class SQLiteExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'sqlite';
+    /**
+     * Execute EXPLAIN QUERY PLAN on a SQL query to get the execution plan
+     * Note: SQLite doesn't support EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], _options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating SQLite executors
+ */
+export declare function createSQLiteExecutor(db: DrizzleDatabase, schema?: any): SQLiteExecutor;

package/dist/server/server/explain/databend-parser.d.ts

@@ -0,0 +1,16 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse Databend EXPLAIN output
+ *
+ * Databend EXPLAIN output is typically indented text showing the query plan tree.
+ * Example:
+ * "Filter"
+ * "├── filters: [employees.organisation_id = 1]"
+ * "├── TableScan"
+ * "│   ├── table: employees"
+ * "│   ├── estimated rows: 1000"
+ */
+export declare function parseDatabendExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/duckdb-parser.d.ts

@@ -0,0 +1,28 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse DuckDB EXPLAIN output
+ *
+ * Example DuckDB EXPLAIN output:
+ * "┌───────────────────────────┐"
+ * "│      EXPLANATION OF       │"
+ * "│     QUERY PLAN            │"
+ * "└───────────────────────────┘"
+ * "┌─────────────────────────────────────────────────────────────────────┐"
+ * "│                     QUERY PLAN                                      │"
+ * "├─────────────────────────────────────────────────────────────────────┤"
+ * "│  HASH_JOIN                                                          │"
+ * "│  ├──SEQ_SCAN employees                                              │"
+ * "│  │  (cost=100.0 rows=1000)                                          │"
+ * "│  └──SEQ_SCAN departments                                            │"
+ * "│     (cost=50.0 rows=500)                                            │"
+ * "└─────────────────────────────────────────────────────────────────────┘"
+ *
+ * Or simpler format:
+ * "HASH_JOIN"
+ * "├──SEQ_SCAN employees"
+ * "└──SEQ_SCAN departments"
+ */
+export declare function parseDuckDBExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * EXPLAIN plan parsers
+ * Normalize raw EXPLAIN output from different databases to a common format
+ */
+export { parsePostgresExplain } from './postgres-parser';
+export { parseMySQLExplain } from './mysql-parser';
+export { parseSQLiteExplain } from './sqlite-parser';
+export { parseDuckDBExplain } from './duckdb-parser';
+export type { ExplainOperation, ExplainResult, ExplainSummary, ExplainOptions } from '../types/executor';

package/dist/server/server/explain/mysql-parser.d.ts

@@ -0,0 +1,38 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * MySQL EXPLAIN row structure
+ * Standard columns returned by EXPLAIN
+ */
+interface MySQLExplainRow {
+    id: number;
+    select_type: string;
+    table: string | null;
+    partitions: string | null;
+    type: string;
+    possible_keys: string | null;
+    key: string | null;
+    key_len: string | null;
+    ref: string | null;
+    rows: number;
+    filtered: number;
+    Extra: string | null;
+}
+/**
+ * Parse MySQL EXPLAIN output
+ *
+ * MySQL EXPLAIN returns rows with columns:
+ * id, select_type, table, partitions, type, possible_keys, key, key_len, ref, rows, filtered, Extra
+ *
+ * The 'type' column indicates access method:
+ * - ALL: Full table scan (like Seq Scan)
+ * - index: Full index scan
+ * - range: Index range scan
+ * - ref: Index lookup using non-unique index
+ * - eq_ref: Index lookup using unique index
+ * - const: Single row lookup
+ */
+export declare function parseMySQLExplain(rows: MySQLExplainRow[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;
+export {};