@leonardovida-md/drizzle-neo-duckdb 1.1.0 → 1.1.2

package/dist/introspect.d.ts

@@ -63,4 +63,12 @@ export interface IntrospectResult {
 }
 export declare const DEFAULT_IMPORT_BASE = "@leonardovida-md/drizzle-neo-duckdb/helpers";
 export declare function introspect(db: DuckDBDatabase, opts?: IntrospectOptions): Promise<IntrospectResult>;
+export declare function buildDefault(defaultValue: string | null): string;
+export declare function parseStructFields(inner: string): Array<{
+    name: string;
+    type: string;
+}>;
+export declare function parseMapValue(raw: string): string;
+export declare function splitTopLevel(input: string, delimiter: string): string[];
+export declare function toIdentifier(name: string): string;
 export {};

package/dist/options.d.ts

@@ -0,0 +1,10 @@
+export type RewriteArraysMode = 'auto' | 'always' | 'never';
+export type RewriteArraysOption = boolean | RewriteArraysMode;
+export declare function resolveRewriteArraysOption(value?: RewriteArraysOption): RewriteArraysMode;
+export type PrepareCacheOption = boolean | number | {
+    size?: number;
+};
+export interface PreparedStatementCacheConfig {
+    size: number;
+}
+export declare function resolvePrepareCacheOption(option?: PrepareCacheOption): PreparedStatementCacheConfig | undefined;

package/dist/pool.d.ts

@@ -16,6 +16,14 @@ export declare function resolvePoolSize(pool: DuckDBPoolConfig | PoolPreset | fa
 export interface DuckDBConnectionPoolOptions {
     /** Maximum concurrent connections. Defaults to 4. */
     size?: number;
+    /** Timeout in milliseconds to wait for a connection. Defaults to 30000 (30s). */
+    acquireTimeout?: number;
+    /** Maximum number of requests waiting for a connection. Defaults to 100. */
+    maxWaitingRequests?: number;
+    /** Max time (ms) a connection may live before being recycled. */
+    maxLifetimeMs?: number;
+    /** Max idle time (ms) before an idle connection is discarded. */
+    idleTimeoutMs?: number;
 }
 export declare function createDuckDBConnectionPool(instance: DuckDBInstance, options?: DuckDBConnectionPoolOptions): DuckDBConnectionPool & {
     size: number;

package/dist/session.d.ts

@@ -9,7 +9,8 @@ import { type Query, SQL } from 'drizzle-orm/sql/sql';
 import type { Assume } from 'drizzle-orm/utils';
 import type { DuckDBDialect } from './dialect.ts';
 import type { DuckDBClientLike, RowData } from './client.ts';
-import { type ExecuteInBatchesOptions } from './client.ts';
+import { type ExecuteBatchesRawChunk, type ExecuteInBatchesOptions } from './client.ts';
+import type { PreparedStatementCacheConfig, RewriteArraysMode } from './options.ts';
 export type { DuckDBClientLike, RowData } from './client.ts';
 export declare class DuckDBPreparedQuery<T extends PreparedQueryConfig> extends PgPreparedQuery<T> {
     private client;
@@ -20,19 +21,21 @@ export declare class DuckDBPreparedQuery<T extends PreparedQueryConfig> extends
     private fields;
     private _isResponseInArrayMode;
     private customResultMapper;
-    private rewriteArrays;
+    private rewriteArraysMode;
     private rejectStringArrayLiterals;
+    private prepareCache;
     private warnOnStringArrayLiteral?;
     static readonly [entityKind]: string;
-    constructor(client: DuckDBClientLike, dialect: DuckDBDialect, queryString: string, params: unknown[], logger: Logger, fields: SelectedFieldsOrdered | undefined, _isResponseInArrayMode: boolean, customResultMapper: ((rows: unknown[][]) => T['execute']) | undefined, rewriteArrays: boolean, rejectStringArrayLiterals: boolean, warnOnStringArrayLiteral?: ((sql: string) => void) | undefined);
+    constructor(client: DuckDBClientLike, dialect: DuckDBDialect, queryString: string, params: unknown[], logger: Logger, fields: SelectedFieldsOrdered | undefined, _isResponseInArrayMode: boolean, customResultMapper: ((rows: unknown[][]) => T['execute']) | undefined, rewriteArraysMode: RewriteArraysMode, rejectStringArrayLiterals: boolean, prepareCache: PreparedStatementCacheConfig | undefined, warnOnStringArrayLiteral?: ((sql: string) => void) | undefined);
     execute(placeholderValues?: Record<string, unknown> | undefined): Promise<T['execute']>;
     all(placeholderValues?: Record<string, unknown> | undefined): Promise<T['all']>;
     isResponseInArrayMode(): boolean;
 }
 export interface DuckDBSessionOptions {
     logger?: Logger;
-    rewriteArrays?: boolean;
+    rewriteArrays?: RewriteArraysMode;
     rejectStringArrayLiterals?: boolean;
+    prepareCache?: PreparedStatementCacheConfig;
 }
 export declare class DuckDBSession<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = Record<string, never>> extends PgSession<DuckDBQueryResultHKT, TFullSchema, TSchema> {
     private client;
@@ -41,15 +44,22 @@ export declare class DuckDBSession<TFullSchema extends Record<string, unknown> =
     static readonly [entityKind]: string;
     protected dialect: DuckDBDialect;
     private logger;
-    private rewriteArrays;
+    private rewriteArraysMode;
     private rejectStringArrayLiterals;
+    private prepareCache;
     private hasWarnedArrayLiteral;
+    private rollbackOnly;
     constructor(client: DuckDBClientLike, dialect: DuckDBDialect, schema: RelationalSchemaConfig<TSchema> | undefined, options?: DuckDBSessionOptions);
     prepareQuery<T extends PreparedQueryConfig = PreparedQueryConfig>(query: Query, fields: SelectedFieldsOrdered | undefined, name: string | undefined, isResponseInArrayMode: boolean, customResultMapper?: (rows: unknown[][]) => T['execute']): PgPreparedQuery<T>;
-    transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
+    execute<T>(query: SQL): Promise<T>;
+    all<T = unknown>(query: SQL): Promise<T[]>;
+    transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
     private warnOnStringArrayLiteral;
     executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<GenericRowData<T>[], void, void>;
+    executeBatchesRaw(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
     executeArrow(query: SQL): Promise<unknown>;
+    markRollbackOnly(): void;
+    isRollbackOnly(): boolean;
 }
 export declare class DuckDBTransaction<TFullSchema extends Record<string, unknown>, TSchema extends TablesRelationalConfig> extends PgTransaction<DuckDBQueryResultHKT, TFullSchema, TSchema> {
     static readonly [entityKind]: string;
@@ -57,8 +67,10 @@ export declare class DuckDBTransaction<TFullSchema extends Record<string, unknow
     getTransactionConfigSQL(config: PgTransactionConfig): SQL;
     setTransaction(config: PgTransactionConfig): Promise<void>;
     executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<GenericRowData<T>[], void, void>;
+    executeBatchesRaw(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
     executeArrow(query: SQL): Promise<unknown>;
     transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
+    private runNestedWithoutSavepoint;
 }
 export type GenericRowData<T extends RowData = RowData> = T;
 export type GenericTableData<T = RowData> = T[];

package/dist/sql/query-rewriters.d.ts

@@ -1 +1,2 @@
+export declare function scrubForRewrite(query: string): string;
 export declare function adaptArrayOperators(query: string): string;

package/dist/sql/result-mapper.d.ts

@@ -1,2 +1,9 @@
 import { type AnyColumn, type SelectedFieldsOrdered } from 'drizzle-orm';
+export declare function normalizeInet(value: unknown): unknown;
+export declare function normalizeTimestampString(value: unknown, withTimezone: boolean): string | unknown;
+export declare function normalizeTimestamp(value: unknown, withTimezone: boolean): Date | unknown;
+export declare function normalizeDateString(value: unknown): string | unknown;
+export declare function normalizeDateValue(value: unknown): Date | unknown;
+export declare function normalizeTime(value: unknown): string | unknown;
+export declare function normalizeInterval(value: unknown): string | unknown;
 export declare function mapResultRow<TResult>(columns: SelectedFieldsOrdered<AnyColumn>, row: unknown[], joinsNotNullableMap: Record<string, boolean> | undefined): TResult;

package/dist/value-wrappers-core.d.ts

@@ -23,7 +23,7 @@ export interface StructValueWrapper extends DuckDBValueWrapper<'struct', Record<
 export interface MapValueWrapper extends DuckDBValueWrapper<'map', Record<string, unknown>> {
     readonly valueType?: string;
 }
-export interface TimestampValueWrapper extends DuckDBValueWrapper<'timestamp', Date | string> {
+export interface TimestampValueWrapper extends DuckDBValueWrapper<'timestamp', Date | string | number | bigint> {
     readonly withTimezone: boolean;
     readonly precision?: number;
 }
@@ -37,6 +37,6 @@ export declare function wrapList(data: unknown[], elementType?: string): ListVal
 export declare function wrapArray(data: unknown[], elementType?: string, fixedLength?: number): ArrayValueWrapper;
 export declare function wrapStruct(data: Record<string, unknown>, schema?: Record<string, string>): StructValueWrapper;
 export declare function wrapMap(data: Record<string, unknown>, valueType?: string): MapValueWrapper;
-export declare function wrapTimestamp(data: Date | string, withTimezone: boolean, precision?: number): TimestampValueWrapper;
+export declare function wrapTimestamp(data: Date | string | number | bigint, withTimezone: boolean, precision?: number): TimestampValueWrapper;
 export declare function wrapBlob(data: Buffer | Uint8Array): BlobValueWrapper;
 export declare function wrapJson(data: unknown): JsonValueWrapper;

package/package.json

@@ -3,7 +3,7 @@
   "module": "./dist/index.mjs",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A drizzle ORM client for use with DuckDB. Based on drizzle's Postgres client.",
   "type": "module",
   "scripts": {

package/src/bin/duckdb-introspect.ts

@@ -12,6 +12,7 @@ interface CliOptions {
   allDatabases: boolean;
   schemas?: string[];
   outFile: string;
+  outMeta?: string;
   includeViews: boolean;
   useCustomTimeTypes: boolean;
   importBasePath?: string;
@@ -20,6 +21,7 @@ interface CliOptions {
 function parseArgs(argv: string[]): CliOptions {
   const options: CliOptions = {
     outFile: path.resolve(process.cwd(), 'drizzle/schema.ts'),
+    outMeta: undefined,
     allDatabases: false,
     includeViews: false,
     useCustomTimeTypes: true,
@@ -52,6 +54,14 @@ function parseArgs(argv: string[]): CliOptions {
           argv[++i] ?? 'drizzle/schema.ts'
         );
         break;
+      case '--out-json':
+      case '--outJson':
+      case '--json':
+        options.outMeta = path.resolve(
+          process.cwd(),
+          argv[++i] ?? 'drizzle/schema.meta.json'
+        );
+        break;
       case '--include-views':
       case '--includeViews':
         options.includeViews = true;
@@ -88,6 +98,7 @@ Options:
   --all-databases  Introspect all attached databases (not just current)
   --schema         Comma separated schema list (defaults to all non-system schemas)
   --out            Output file (default: ./drizzle/schema.ts)
+  --json           Optional JSON metadata output (default: ./drizzle/schema.meta.json)
   --include-views  Include views in the generated schema
   --use-pg-time    Use pg-core timestamp/date/time instead of DuckDB custom helpers
   --import-base    Override import path for duckdb helpers (default: package name)
@@ -136,8 +147,19 @@ async function main() {
 
     await mkdir(path.dirname(options.outFile), { recursive: true });
     await writeFile(options.outFile, result.files.schemaTs, 'utf8');
+    if (options.outMeta) {
+      await mkdir(path.dirname(options.outMeta), { recursive: true });
+      await writeFile(
+        options.outMeta,
+        JSON.stringify(result.files.metaJson, null, 2),
+        'utf8'
+      );
+    }
 
     console.log(`Wrote schema to ${options.outFile}`);
+    if (options.outMeta) {
+      console.log(`Wrote metadata to ${options.outMeta}`);
+    }
   } finally {
     if (
       'closeSync' in connection &&
@@ -145,6 +167,11 @@ async function main() {
     ) {
       connection.closeSync();
     }
+    if ('closeSync' in instance && typeof instance.closeSync === 'function') {
+      instance.closeSync();
+    } else if ('close' in instance && typeof instance.close === 'function') {
+      await instance.close();
+    }
   }
 }
 

package/src/client.ts

@@ -2,6 +2,7 @@ import {
   listValue,
   timestampValue,
   type DuckDBConnection,
+  type DuckDBPreparedStatement,
   type DuckDBValue,
 } from '@duckdb/node-api';
 import {
@@ -9,6 +10,7 @@ import {
   wrapperToNodeApiValue,
   type AnyDuckDBValueWrapper,
 } from './value-wrappers.ts';
+import type { PreparedStatementCacheConfig } from './options.ts';
 
 export type DuckDBClientLike = DuckDBConnection | DuckDBConnectionPool;
 export type RowData = Record<string, unknown>;
@@ -25,6 +27,25 @@ export function isPool(
   return typeof (client as DuckDBConnectionPool).acquire === 'function';
 }
 
+export interface ExecuteClientOptions {
+  prepareCache?: PreparedStatementCacheConfig;
+}
+
+export type ExecuteArraysResult = { columns: string[]; rows: unknown[][] };
+
+type MaterializedRows = ExecuteArraysResult;
+
+type PreparedCacheEntry = {
+  statement: DuckDBPreparedStatement;
+};
+
+type PreparedStatementCache = {
+  size: number;
+  entries: Map<string, PreparedCacheEntry>;
+};
+
+const PREPARED_CACHE = Symbol.for('drizzle-duckdb:prepared-cache');
+
 export interface PrepareParamsOptions {
   rejectStringArrayLiterals?: boolean;
   warnOnStringArrayLiteral?: () => void;
@@ -49,17 +70,31 @@ export function prepareParams(
   options: PrepareParamsOptions = {}
 ): unknown[] {
   return params.map((param) => {
-    if (typeof param === 'string' && isPgArrayLiteral(param)) {
-      if (options.rejectStringArrayLiterals) {
-        throw new Error(
-          'Stringified array literals are not supported. Use duckDbList()/duckDbArray() or pass native arrays.'
-        );
-      }
-
-      if (options.warnOnStringArrayLiteral) {
-        options.warnOnStringArrayLiteral();
+    if (typeof param === 'string' && param.length > 0) {
+      const firstChar = param[0];
+      const maybeArrayLiteral =
+        firstChar === '{' ||
+        firstChar === '[' ||
+        firstChar === ' ' ||
+        firstChar === '\t';
+
+      if (maybeArrayLiteral) {
+        const trimmed =
+          firstChar === '{' || firstChar === '[' ? param : param.trim();
+
+        if (trimmed && isPgArrayLiteral(trimmed)) {
+          if (options.rejectStringArrayLiterals) {
+            throw new Error(
+              'Stringified array literals are not supported. Use duckDbList()/duckDbArray() or pass native arrays.'
+            );
+          }
+
+          if (options.warnOnStringArrayLiteral) {
+            options.warnOnStringArrayLiteral();
+          }
+          return parsePgArrayLiteral(trimmed);
+        }
       }
-      return parsePgArrayLiteral(param);
     }
     return param;
   });
@@ -103,14 +138,177 @@ function toNodeApiValue(value: unknown): DuckDBValue {
 }
 
 function deduplicateColumns(columns: string[]): string[] {
-  const seen: Record<string, number> = {};
-  return columns.map((col) => {
-    const count = seen[col] ?? 0;
-    seen[col] = count + 1;
-    return count === 0 ? col : `${col}_${count}`;
+  const counts = new Map<string, number>();
+  let hasDuplicates = false;
+
+  for (const column of columns) {
+    const next = (counts.get(column) ?? 0) + 1;
+    counts.set(column, next);
+    if (next > 1) {
+      hasDuplicates = true;
+      break;
+    }
+  }
+
+  if (!hasDuplicates) {
+    return columns;
+  }
+
+  counts.clear();
+  return columns.map((column) => {
+    const count = counts.get(column) ?? 0;
+    counts.set(column, count + 1);
+    return count === 0 ? column : `${column}_${count}`;
   });
 }
 
+function destroyPreparedStatement(entry: PreparedCacheEntry | undefined): void {
+  if (!entry) return;
+  try {
+    entry.statement.destroySync();
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+function getPreparedCache(
+  connection: DuckDBConnection,
+  size: number
+): PreparedStatementCache {
+  const store = connection as unknown as Record<
+    symbol,
+    PreparedStatementCache | undefined
+  >;
+  const existing = store[PREPARED_CACHE];
+  if (existing) {
+    existing.size = size;
+    return existing;
+  }
+
+  const cache: PreparedStatementCache = { size, entries: new Map() };
+  store[PREPARED_CACHE] = cache;
+  return cache;
+}
+
+function evictOldest(cache: PreparedStatementCache): void {
+  const oldest = cache.entries.keys().next();
+  if (!oldest.done) {
+    const key = oldest.value as string;
+    const entry = cache.entries.get(key);
+    cache.entries.delete(key);
+    destroyPreparedStatement(entry);
+  }
+}
+
+function evictCacheEntry(cache: PreparedStatementCache, key: string): void {
+  const entry = cache.entries.get(key);
+  cache.entries.delete(key);
+  destroyPreparedStatement(entry);
+}
+
+async function getOrPrepareStatement(
+  connection: DuckDBConnection,
+  query: string,
+  cacheConfig: PreparedStatementCacheConfig
+): Promise<DuckDBPreparedStatement> {
+  const cache = getPreparedCache(connection, cacheConfig.size);
+  const cached = cache.entries.get(query);
+  if (cached) {
+    cache.entries.delete(query);
+    cache.entries.set(query, cached);
+    return cached.statement;
+  }
+
+  const statement = await connection.prepare(query);
+  cache.entries.set(query, { statement });
+
+  while (cache.entries.size > cache.size) {
+    evictOldest(cache);
+  }
+
+  return statement;
+}
+
+async function materializeResultRows(result: {
+  getRowsJS: () => Promise<unknown[][] | undefined>;
+  columnNames: () => string[];
+  deduplicatedColumnNames?: () => string[];
+}): Promise<MaterializedRows> {
+  const rows = (await result.getRowsJS()) ?? [];
+  const baseColumns =
+    typeof result.deduplicatedColumnNames === 'function'
+      ? result.deduplicatedColumnNames()
+      : result.columnNames();
+  const columns =
+    typeof result.deduplicatedColumnNames === 'function'
+      ? baseColumns
+      : deduplicateColumns(baseColumns);
+
+  return { columns, rows };
+}
+
+async function materializeRows(
+  client: DuckDBClientLike,
+  query: string,
+  params: unknown[],
+  options: ExecuteClientOptions = {}
+): Promise<MaterializedRows> {
+  if (isPool(client)) {
+    const connection = await client.acquire();
+    try {
+      return await materializeRows(connection, query, params, options);
+    } finally {
+      await client.release(connection);
+    }
+  }
+
+  const values =
+    params.length > 0
+      ? (params.map((param) => toNodeApiValue(param)) as DuckDBValue[])
+      : undefined;
+
+  const connection = client as DuckDBConnection;
+
+  if (options.prepareCache && typeof connection.prepare === 'function') {
+    const cache = getPreparedCache(connection, options.prepareCache.size);
+    try {
+      const statement = await getOrPrepareStatement(
+        connection,
+        query,
+        options.prepareCache
+      );
+      if (values) {
+        statement.bind(values as DuckDBValue[]);
+      } else {
+        statement.clearBindings?.();
+      }
+      const result = await statement.run();
+      cache.entries.delete(query);
+      cache.entries.set(query, { statement });
+      return await materializeResultRows(result);
+    } catch (error) {
+      evictCacheEntry(cache, query);
+      throw error;
+    }
+  }
+
+  const result = await connection.run(query, values);
+  return await materializeResultRows(result);
+}
+
+function clearPreparedCache(connection: DuckDBConnection): void {
+  const store = connection as unknown as Record<
+    symbol,
+    PreparedStatementCache | undefined
+  >;
+  const cache = store[PREPARED_CACHE];
+  if (!cache) return;
+  for (const entry of cache.entries.values()) {
+    destroyPreparedStatement(entry);
+  }
+  cache.entries.clear();
+}
+
 function mapRowsToObjects(columns: string[], rows: unknown[][]): RowData[] {
   return rows.map((vals) => {
     const obj: Record<string, unknown> = {};
@@ -124,6 +322,8 @@ function mapRowsToObjects(columns: string[], rows: unknown[][]): RowData[] {
 export async function closeClientConnection(
   connection: DuckDBConnection
 ): Promise<void> {
+  clearPreparedCache(connection);
+
   if ('close' in connection && typeof connection.close === 'function') {
     await connection.close();
     return;
@@ -145,35 +345,41 @@ export async function closeClientConnection(
 export async function executeOnClient(
   client: DuckDBClientLike,
   query: string,
-  params: unknown[]
+  params: unknown[],
+  options: ExecuteClientOptions = {}
 ): Promise<RowData[]> {
-  if (isPool(client)) {
-    const connection = await client.acquire();
-    try {
-      return await executeOnClient(connection, query, params);
-    } finally {
-      await client.release(connection);
-    }
+  const { columns, rows } = await materializeRows(
+    client,
+    query,
+    params,
+    options
+  );
+
+  if (!rows || rows.length === 0) {
+    return [];
   }
 
-  const values =
-    params.length > 0
-      ? (params.map((param) => toNodeApiValue(param)) as DuckDBValue[])
-      : undefined;
-  const result = await client.run(query, values);
-  const rows = await result.getRowsJS();
-  const columns =
-    // prefer deduplicated names when available (Node API >=1.4.2)
-    result.deduplicatedColumnNames?.() ?? result.columnNames();
-  const uniqueColumns = deduplicateColumns(columns);
+  return mapRowsToObjects(columns, rows);
+}
 
-  return rows ? mapRowsToObjects(uniqueColumns, rows) : [];
+export async function executeArraysOnClient(
+  client: DuckDBClientLike,
+  query: string,
+  params: unknown[],
+  options: ExecuteClientOptions = {}
+): Promise<ExecuteArraysResult> {
+  return await materializeRows(client, query, params, options);
 }
 
 export interface ExecuteInBatchesOptions {
   rowsPerChunk?: number;
 }
 
+export interface ExecuteBatchesRawChunk {
+  columns: string[];
+  rows: unknown[][];
+}
+
 /**
  * Stream results from DuckDB in batches to avoid fully materializing rows in JS.
  */
@@ -203,15 +409,19 @@ export async function* executeInBatches(
       : undefined;
 
   const result = await client.stream(query, values);
+  const rawColumns =
+    typeof result.deduplicatedColumnNames === 'function'
+      ? result.deduplicatedColumnNames()
+      : result.columnNames();
   const columns =
-    // prefer deduplicated names when available (Node API >=1.4.2)
-    result.deduplicatedColumnNames?.() ?? result.columnNames();
-  const uniqueColumns = deduplicateColumns(columns);
+    typeof result.deduplicatedColumnNames === 'function'
+      ? rawColumns
+      : deduplicateColumns(rawColumns);
 
   let buffer: RowData[] = [];
 
   for await (const chunk of result.yieldRowsJs()) {
-    const objects = mapRowsToObjects(uniqueColumns, chunk);
+    const objects = mapRowsToObjects(columns, chunk);
     for (const row of objects) {
       buffer.push(row);
       if (buffer.length >= rowsPerChunk) {
@@ -226,6 +436,59 @@ export async function* executeInBatches(
   }
 }
 
+export async function* executeInBatchesRaw(
+  client: DuckDBClientLike,
+  query: string,
+  params: unknown[],
+  options: ExecuteInBatchesOptions = {}
+): AsyncGenerator<ExecuteBatchesRawChunk, void, void> {
+  if (isPool(client)) {
+    const connection = await client.acquire();
+    try {
+      yield* executeInBatchesRaw(connection, query, params, options);
+      return;
+    } finally {
+      await client.release(connection);
+    }
+  }
+
+  const rowsPerChunk =
+    options.rowsPerChunk && options.rowsPerChunk > 0
+      ? options.rowsPerChunk
+      : 100_000;
+
+  const values =
+    params.length > 0
+      ? (params.map((param) => toNodeApiValue(param)) as DuckDBValue[])
+      : undefined;
+
+  const result = await client.stream(query, values);
+  const rawColumns =
+    typeof result.deduplicatedColumnNames === 'function'
+      ? result.deduplicatedColumnNames()
+      : result.columnNames();
+  const columns =
+    typeof result.deduplicatedColumnNames === 'function'
+      ? rawColumns
+      : deduplicateColumns(rawColumns);
+
+  let buffer: unknown[][] = [];
+
+  for await (const chunk of result.yieldRowsJs()) {
+    for (const row of chunk) {
+      buffer.push(row as unknown[]);
+      if (buffer.length >= rowsPerChunk) {
+        yield { columns, rows: buffer };
+        buffer = [];
+      }
+    }
+  }
+
+  if (buffer.length > 0) {
+    yield { columns, rows: buffer };
+  }
+}
+
 /**
  * Return columnar results when the underlying node-api exposes an Arrow/columnar API.
  * Falls back to column-major JS arrays when Arrow is unavailable.