@leonardovida-md/drizzle-neo-duckdb 1.2.0 → 1.2.2

package/dist/sql/ast-transformer.d.ts

@@ -4,12 +4,30 @@
  * Transforms:
  * - Array operators: @>, <@, && -> array_has_all(), array_has_any()
  * - JOIN column qualification: "col" = "col" -> "left"."col" = "right"."col"
+ *
+ * Performance optimizations:
+ * - LRU cache for transformed queries (avoids re-parsing identical queries)
+ * - Smart heuristics to skip JOIN qualification when not needed
+ * - Early exit when no transformation is required
  */
 export type TransformResult = {
     sql: string;
     transformed: boolean;
 };
 export declare function transformSQL(query: string): TransformResult;
+/**
+ * Clear the transformation cache. Useful for testing or memory management.
+ */
+export declare function clearTransformCache(): void;
+/**
+ * Get current cache statistics for monitoring.
+ */
+export declare function getTransformCacheStats(): {
+    size: number;
+    maxSize: number;
+};
 export declare function needsTransformation(query: string): boolean;
 export { transformArrayOperators } from './visitors/array-operators.ts';
 export { qualifyJoinColumns } from './visitors/column-qualifier.ts';
+export { rewriteGenerateSeriesAliases } from './visitors/generate-series-alias.ts';
+export { hoistUnionWith } from './visitors/union-with-hoister.ts';

package/dist/sql/visitors/column-qualifier.d.ts

@@ -1,5 +1,10 @@
 /**
  * AST visitor to qualify unqualified column references in JOIN ON clauses.
+ *
+ * Performance optimizations:
+ * - Early exit when no unqualified columns found in ON clause
+ * - Skip processing if all columns are already qualified
+ * - Minimal tree traversal when possible
  */
 import type { AST } from 'node-sql-parser';
 export declare function qualifyJoinColumns(ast: AST | AST[]): boolean;

package/dist/sql/visitors/generate-series-alias.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AST visitor to rewrite Postgres style generate_series aliases.
+ *
+ * Postgres lets you reference a generate_series alias as a column:
+ *   FROM generate_series(...) AS gs
+ *   SELECT gs::date
+ *
+ * DuckDB treats gs as a table alias, and the column is generate_series.
+ * This visitor rewrites unqualified column refs that match a
+ * generate_series alias to gs.generate_series.
+ */
+import type { AST } from 'node-sql-parser';
+export declare function rewriteGenerateSeriesAliases(ast: AST | AST[]): boolean;

package/dist/sql/visitors/union-with-hoister.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AST visitor to hoist WITH clauses out of UNION and other set operations.
+ *
+ * Drizzle can emit SQL like:
+ *   (with a as (...) select ...) union (with b as (...) select ...)
+ *
+ * DuckDB 1.4.x has an internal binder bug for this pattern.
+ * We merge per arm CTEs into a single top level WITH when names do not collide.
+ */
+import type { AST } from 'node-sql-parser';
+export declare function hoistUnionWith(ast: AST | AST[]): boolean;

package/package.json

@@ -3,7 +3,7 @@
   "module": "./dist/index.mjs",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A drizzle ORM client for use with DuckDB. Based on drizzle's Postgres client.",
   "type": "module",
   "scripts": {
@@ -11,7 +11,7 @@
     "build:declarations": "tsc --emitDeclarationOnly --project tsconfig.types.json",
     "test": "vitest",
     "t": "vitest --watch --ui",
-    "bench": "vitest bench --runInBand test/perf",
+    "bench": "vitest bench --run test/perf --pool=threads --poolOptions.threads.singleThread=true --no-file-parallelism",
     "perf:run": "bun run scripts/run-perf.ts",
     "perf:compare": "bun run scripts/compare-perf.ts"
   },

package/src/sql/ast-transformer.ts

@@ -4,6 +4,11 @@
  * Transforms:
  * - Array operators: @>, <@, && -> array_has_all(), array_has_any()
  * - JOIN column qualification: "col" = "col" -> "left"."col" = "right"."col"
+ *
+ * Performance optimizations:
+ * - LRU cache for transformed queries (avoids re-parsing identical queries)
+ * - Smart heuristics to skip JOIN qualification when not needed
+ * - Early exit when no transformation is required
  */
 
 import nodeSqlParser from 'node-sql-parser';
@@ -12,6 +17,8 @@ import type { AST } from 'node-sql-parser';
 
 import { transformArrayOperators } from './visitors/array-operators.ts';
 import { qualifyJoinColumns } from './visitors/column-qualifier.ts';
+import { rewriteGenerateSeriesAliases } from './visitors/generate-series-alias.ts';
+import { hoistUnionWith } from './visitors/union-with-hoister.ts';
 
 const parser = new Parser();
 
@@ -20,38 +27,125 @@ export type TransformResult = {
   transformed: boolean;
 };
 
+// LRU cache for transformed SQL queries
+// Key: original SQL, Value: transformed result
+const CACHE_SIZE = 500;
+const transformCache = new Map<string, TransformResult>();
+
+function getCachedOrTransform(
+  query: string,
+  transform: () => TransformResult
+): TransformResult {
+  const cached = transformCache.get(query);
+  if (cached) {
+    // Move to end for LRU behavior
+    transformCache.delete(query);
+    transformCache.set(query, cached);
+    return cached;
+  }
+
+  const result = transform();
+
+  // Add to cache with LRU eviction
+  if (transformCache.size >= CACHE_SIZE) {
+    // Delete oldest entry (first key in Map iteration order)
+    const oldestKey = transformCache.keys().next().value;
+    if (oldestKey) {
+      transformCache.delete(oldestKey);
+    }
+  }
+  transformCache.set(query, result);
+
+  return result;
+}
+
+const DEBUG_ENV = 'DRIZZLE_DUCKDB_DEBUG_AST';
+
+function hasJoin(query: string): boolean {
+  return /\bjoin\b/i.test(query);
+}
+
+function debugLog(message: string, payload?: unknown): void {
+  if (process?.env?.[DEBUG_ENV]) {
+    // eslint-disable-next-line no-console
+    console.debug('[duckdb-ast]', message, payload ?? '');
+  }
+}
+
 export function transformSQL(query: string): TransformResult {
   const needsArrayTransform =
     query.includes('@>') || query.includes('<@') || query.includes('&&');
-  const needsJoinTransform = query.toLowerCase().includes('join');
+  const needsJoinTransform =
+    hasJoin(query) || /\bupdate\b/i.test(query) || /\bdelete\b/i.test(query);
+  const needsUnionTransform =
+    /\bunion\b/i.test(query) ||
+    /\bintersect\b/i.test(query) ||
+    /\bexcept\b/i.test(query);
+  const needsGenerateSeriesTransform = /\bgenerate_series\b/i.test(query);
 
-  if (!needsArrayTransform && !needsJoinTransform) {
+  if (
+    !needsArrayTransform &&
+    !needsJoinTransform &&
+    !needsUnionTransform &&
+    !needsGenerateSeriesTransform
+  ) {
     return { sql: query, transformed: false };
   }
 
-  try {
-    const ast = parser.astify(query, { database: 'PostgreSQL' });
+  // Use cache for repeated queries
+  return getCachedOrTransform(query, () => {
+    try {
+      const ast = parser.astify(query, { database: 'PostgreSQL' });
 
-    let transformed = false;
+      let transformed = false;
 
-    if (needsArrayTransform) {
-      transformed = transformArrayOperators(ast) || transformed;
-    }
+      if (needsArrayTransform) {
+        transformed = transformArrayOperators(ast) || transformed;
+      }
 
-    if (needsJoinTransform) {
-      transformed = qualifyJoinColumns(ast) || transformed;
-    }
+      if (needsJoinTransform) {
+        transformed = qualifyJoinColumns(ast) || transformed;
+      }
+
+      if (needsGenerateSeriesTransform) {
+        transformed = rewriteGenerateSeriesAliases(ast) || transformed;
+      }
 
-    if (!transformed) {
+      if (needsUnionTransform) {
+        transformed = hoistUnionWith(ast) || transformed;
+      }
+
+      if (!transformed) {
+        debugLog('AST parsed but no transformation applied', {
+          join: needsJoinTransform,
+        });
+        return { sql: query, transformed: false };
+      }
+
+      const transformedSql = parser.sqlify(ast, { database: 'PostgreSQL' });
+
+      return { sql: transformedSql, transformed: true };
+    } catch (err) {
+      debugLog('AST transform failed; returning original SQL', {
+        error: (err as Error).message,
+      });
       return { sql: query, transformed: false };
     }
+  });
+}
 
-    const transformedSql = parser.sqlify(ast, { database: 'PostgreSQL' });
+/**
+ * Clear the transformation cache. Useful for testing or memory management.
+ */
+export function clearTransformCache(): void {
+  transformCache.clear();
+}
 
-    return { sql: transformedSql, transformed: true };
-  } catch {
-    return { sql: query, transformed: false };
-  }
+/**
+ * Get current cache statistics for monitoring.
+ */
+export function getTransformCacheStats(): { size: number; maxSize: number } {
+  return { size: transformCache.size, maxSize: CACHE_SIZE };
 }
 
 export function needsTransformation(query: string): boolean {
@@ -60,9 +154,17 @@ export function needsTransformation(query: string): boolean {
     query.includes('@>') ||
     query.includes('<@') ||
     query.includes('&&') ||
-    lower.includes('join')
+    lower.includes('join') ||
+    lower.includes('union') ||
+    lower.includes('intersect') ||
+    lower.includes('except') ||
+    lower.includes('generate_series') ||
+    lower.includes('update') ||
+    lower.includes('delete')
   );
 }
 
 export { transformArrayOperators } from './visitors/array-operators.ts';
 export { qualifyJoinColumns } from './visitors/column-qualifier.ts';
+export { rewriteGenerateSeriesAliases } from './visitors/generate-series-alias.ts';
+export { hoistUnionWith } from './visitors/union-with-hoister.ts';