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

package/dist/index.mjs

@@ -16,83 +16,162 @@ import { PgPreparedQuery, PgSession } from "drizzle-orm/pg-core/session";
 import { fillPlaceholders, sql } from "drizzle-orm/sql/sql";
 
 // src/sql/query-rewriters.ts
-function adaptArrayOperators(query) {
-  const operators = [
-    { token: "@>", fn: "array_has_all" },
-    { token: "<@", fn: "array_has_all", swap: true },
-    { token: "&&", fn: "array_has_any" }
-  ];
-  const isWhitespace = (char) => char !== undefined && /\s/.test(char);
-  const walkLeft = (source, start) => {
-    let idx = start;
-    while (idx >= 0 && isWhitespace(source[idx])) {
-      idx--;
-    }
-    let depth = 0;
-    let inString = false;
-    for (;idx >= 0; idx--) {
-      const ch = source[idx];
-      if (ch === undefined)
-        break;
-      if (ch === "'" && source[idx - 1] !== "\\") {
-        inString = !inString;
+var OPERATORS = [
+  { token: "@>", fn: "array_has_all" },
+  { token: "<@", fn: "array_has_all", swap: true },
+  { token: "&&", fn: "array_has_any" }
+];
+var isWhitespace = (char) => char !== undefined && /\s/.test(char);
+function scrubForRewrite(query) {
+  let scrubbed = "";
+  let state = "code";
+  for (let i = 0;i < query.length; i += 1) {
+    const char = query[i];
+    const next = query[i + 1];
+    if (state === "code") {
+      if (char === "'") {
+        scrubbed += "'";
+        state = "single";
+        continue;
       }
-      if (inString)
+      if (char === '"') {
+        scrubbed += '"';
+        state = "double";
         continue;
-      if (ch === ")" || ch === "]") {
-        depth++;
-      } else if (ch === "(" || ch === "[") {
-        depth--;
-        if (depth < 0) {
-          return [idx + 1, source.slice(idx + 1, start + 1)];
-        }
-      } else if (depth === 0 && isWhitespace(ch)) {
-        return [idx + 1, source.slice(idx + 1, start + 1)];
       }
+      if (char === "-" && next === "-") {
+        scrubbed += "  ";
+        i += 1;
+        state = "lineComment";
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        scrubbed += "  ";
+        i += 1;
+        state = "blockComment";
+        continue;
+      }
+      scrubbed += char;
+      continue;
     }
-    return [0, source.slice(0, start + 1)];
-  };
-  const walkRight = (source, start) => {
-    let idx = start;
-    while (idx < source.length && isWhitespace(source[idx])) {
-      idx++;
-    }
-    let depth = 0;
-    let inString = false;
-    for (;idx < source.length; idx++) {
-      const ch = source[idx];
-      if (ch === undefined)
-        break;
-      if (ch === "'" && source[idx - 1] !== "\\") {
-        inString = !inString;
+    if (state === "single") {
+      if (char === "'" && next === "'") {
+        scrubbed += "''";
+        i += 1;
+        continue;
+      }
+      scrubbed += char === "'" ? "'" : ".";
+      if (char === "'") {
+        state = "code";
       }
-      if (inString)
+      continue;
+    }
+    if (state === "double") {
+      if (char === '"' && next === '"') {
+        scrubbed += '""';
+        i += 1;
         continue;
-      if (ch === "(" || ch === "[") {
-        depth++;
-      } else if (ch === ")" || ch === "]") {
-        depth--;
-        if (depth < 0) {
-          return [idx, source.slice(start, idx)];
-        }
-      } else if (depth === 0 && isWhitespace(ch)) {
+      }
+      scrubbed += char === '"' ? '"' : ".";
+      if (char === '"') {
+        state = "code";
+      }
+      continue;
+    }
+    if (state === "lineComment") {
+      scrubbed += char === `
+` ? `
+` : " ";
+      if (char === `
+`) {
+        state = "code";
+      }
+      continue;
+    }
+    if (state === "blockComment") {
+      if (char === "*" && next === "/") {
+        scrubbed += "  ";
+        i += 1;
+        state = "code";
+      } else {
+        scrubbed += " ";
+      }
+    }
+  }
+  return scrubbed;
+}
+function findNextOperator(scrubbed, start) {
+  for (let idx = start;idx < scrubbed.length; idx += 1) {
+    for (const operator of OPERATORS) {
+      if (scrubbed.startsWith(operator.token, idx)) {
+        return { index: idx, operator };
+      }
+    }
+  }
+  return null;
+}
+function walkLeft(source, scrubbed, start) {
+  let idx = start;
+  while (idx >= 0 && isWhitespace(scrubbed[idx])) {
+    idx -= 1;
+  }
+  let depth = 0;
+  for (;idx >= 0; idx -= 1) {
+    const ch = scrubbed[idx];
+    if (ch === ")" || ch === "]") {
+      depth += 1;
+    } else if (ch === "(" || ch === "[") {
+      if (depth === 0) {
+        return [idx + 1, source.slice(idx + 1, start + 1)];
+      }
+      depth = Math.max(0, depth - 1);
+    } else if (depth === 0 && isWhitespace(ch)) {
+      return [idx + 1, source.slice(idx + 1, start + 1)];
+    }
+  }
+  return [0, source.slice(0, start + 1)];
+}
+function walkRight(source, scrubbed, start) {
+  let idx = start;
+  while (idx < scrubbed.length && isWhitespace(scrubbed[idx])) {
+    idx += 1;
+  }
+  let depth = 0;
+  for (;idx < scrubbed.length; idx += 1) {
+    const ch = scrubbed[idx];
+    if (ch === "(" || ch === "[") {
+      depth += 1;
+    } else if (ch === ")" || ch === "]") {
+      if (depth === 0) {
         return [idx, source.slice(start, idx)];
       }
+      depth = Math.max(0, depth - 1);
+    } else if (depth === 0 && isWhitespace(ch)) {
+      return [idx, source.slice(start, idx)];
     }
-    return [source.length, source.slice(start)];
-  };
+  }
+  return [scrubbed.length, source.slice(start)];
+}
+function adaptArrayOperators(query) {
+  if (query.indexOf("@>") === -1 && query.indexOf("<@") === -1 && query.indexOf("&&") === -1) {
+    return query;
+  }
   let rewritten = query;
-  for (const { token, fn, swap } of operators) {
-    let idx = rewritten.indexOf(token);
-    while (idx !== -1) {
-      const [leftStart, leftExpr] = walkLeft(rewritten, idx - 1);
-      const [rightEnd, rightExpr] = walkRight(rewritten, idx + token.length);
-      const left = leftExpr.trim();
-      const right = rightExpr.trim();
-      const replacement = `${fn}(${swap ? right : left}, ${swap ? left : right})`;
-      rewritten = rewritten.slice(0, leftStart) + replacement + rewritten.slice(rightEnd);
-      idx = rewritten.indexOf(token, leftStart + replacement.length);
-    }
+  let scrubbed = scrubForRewrite(query);
+  let searchStart = 0;
+  while (true) {
+    const next = findNextOperator(scrubbed, searchStart);
+    if (!next)
+      break;
+    const { index, operator } = next;
+    const [leftStart, leftExpr] = walkLeft(rewritten, scrubbed, index - 1);
+    const [rightEnd, rightExpr] = walkRight(rewritten, scrubbed, index + operator.token.length);
+    const left = leftExpr.trim();
+    const right = rightExpr.trim();
+    const replacement = `${operator.fn}(${operator.swap ? right : left}, ${operator.swap ? left : right})`;
+    rewritten = rewritten.slice(0, leftStart) + replacement + rewritten.slice(rightEnd);
+    scrubbed = scrubForRewrite(rewritten);
+    searchStart = leftStart + replacement.length;
   }
   return rewritten;
 }
@@ -386,6 +465,12 @@ function dateToMicros(value) {
   if (value instanceof Date) {
     return BigInt(value.getTime()) * 1000n;
   }
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return BigInt(Math.trunc(value)) * 1000n;
+  }
   let normalized = value;
   if (!value.includes("T") && value.includes(" ")) {
     normalized = value.replace(" ", "T");
@@ -442,6 +527,7 @@ function wrapperToNodeApiValue(wrapper, toValue) {
 function isPool(client) {
   return typeof client.acquire === "function";
 }
+var PREPARED_CACHE = Symbol.for("drizzle-duckdb:prepared-cache");
 function isPgArrayLiteral(value) {
   return value.startsWith("{") && value.endsWith("}");
 }
@@ -455,14 +541,21 @@ function parsePgArrayLiteral(value) {
 }
 function prepareParams(params, options = {}) {
   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;
   });
@@ -486,13 +579,121 @@ function toNodeApiValue(value) {
   return value;
 }
 function deduplicateColumns(columns) {
-  const seen = {};
-  return columns.map((col) => {
-    const count = seen[col] ?? 0;
-    seen[col] = count + 1;
-    return count === 0 ? col : `${col}_${count}`;
+  const counts = new Map;
+  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) {
+  if (!entry)
+    return;
+  try {
+    entry.statement.destroySync();
+  } catch {}
+}
+function getPreparedCache(connection, size) {
+  const store = connection;
+  const existing = store[PREPARED_CACHE];
+  if (existing) {
+    existing.size = size;
+    return existing;
+  }
+  const cache = { size, entries: new Map };
+  store[PREPARED_CACHE] = cache;
+  return cache;
+}
+function evictOldest(cache) {
+  const oldest = cache.entries.keys().next();
+  if (!oldest.done) {
+    const key = oldest.value;
+    const entry = cache.entries.get(key);
+    cache.entries.delete(key);
+    destroyPreparedStatement(entry);
+  }
+}
+function evictCacheEntry(cache, key) {
+  const entry = cache.entries.get(key);
+  cache.entries.delete(key);
+  destroyPreparedStatement(entry);
+}
+async function getOrPrepareStatement(connection, query, cacheConfig) {
+  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) {
+  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, query, params, options = {}) {
+  if (isPool(client)) {
+    const connection2 = await client.acquire();
+    try {
+      return await materializeRows(connection2, query, params, options);
+    } finally {
+      await client.release(connection2);
+    }
+  }
+  const values = params.length > 0 ? params.map((param) => toNodeApiValue(param)) : undefined;
+  const connection = client;
+  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);
+      } else {
+        statement.clearBindings?.();
+      }
+      const result2 = await statement.run();
+      cache.entries.delete(query);
+      cache.entries.set(query, { statement });
+      return await materializeResultRows(result2);
+    } catch (error) {
+      evictCacheEntry(cache, query);
+      throw error;
+    }
+  }
+  const result = await connection.run(query, values);
+  return await materializeResultRows(result);
+}
+function clearPreparedCache(connection) {
+  const store = connection;
+  const cache = store[PREPARED_CACHE];
+  if (!cache)
+    return;
+  for (const entry of cache.entries.values()) {
+    destroyPreparedStatement(entry);
+  }
+  cache.entries.clear();
+}
 function mapRowsToObjects(columns, rows) {
   return rows.map((vals) => {
     const obj = {};
@@ -503,6 +704,7 @@ function mapRowsToObjects(columns, rows) {
   });
 }
 async function closeClientConnection(connection) {
+  clearPreparedCache(connection);
   if ("close" in connection && typeof connection.close === "function") {
     await connection.close();
     return;
@@ -515,27 +717,51 @@ async function closeClientConnection(connection) {
     connection.disconnectSync();
   }
 }
-async function executeOnClient(client, query, params) {
+async function executeOnClient(client, query, params, options = {}) {
+  const { columns, rows } = await materializeRows(client, query, params, options);
+  if (!rows || rows.length === 0) {
+    return [];
+  }
+  return mapRowsToObjects(columns, rows);
+}
+async function executeArraysOnClient(client, query, params, options = {}) {
+  return await materializeRows(client, query, params, options);
+}
+async function* executeInBatches(client, query, params, options = {}) {
   if (isPool(client)) {
     const connection = await client.acquire();
     try {
-      return await executeOnClient(connection, query, params);
+      yield* executeInBatches(connection, query, params, options);
+      return;
     } finally {
       await client.release(connection);
     }
   }
+  const rowsPerChunk = options.rowsPerChunk && options.rowsPerChunk > 0 ? options.rowsPerChunk : 1e5;
   const values = params.length > 0 ? params.map((param) => toNodeApiValue(param)) : undefined;
-  const result = await client.run(query, values);
-  const rows = await result.getRowsJS();
-  const columns = result.deduplicatedColumnNames?.() ?? result.columnNames();
-  const uniqueColumns = deduplicateColumns(columns);
-  return rows ? mapRowsToObjects(uniqueColumns, rows) : [];
+  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 = [];
+  for await (const chunk of result.yieldRowsJs()) {
+    const objects = mapRowsToObjects(columns, chunk);
+    for (const row of objects) {
+      buffer.push(row);
+      if (buffer.length >= rowsPerChunk) {
+        yield buffer;
+        buffer = [];
+      }
+    }
+  }
+  if (buffer.length > 0) {
+    yield buffer;
+  }
 }
-async function* executeInBatches(client, query, params, options = {}) {
+async function* executeInBatchesRaw(client, query, params, options = {}) {
   if (isPool(client)) {
     const connection = await client.acquire();
     try {
-      yield* executeInBatches(connection, query, params, options);
+      yield* executeInBatchesRaw(connection, query, params, options);
       return;
     } finally {
       await client.release(connection);
@@ -544,21 +770,20 @@ async function* executeInBatches(client, query, params, options = {}) {
   const rowsPerChunk = options.rowsPerChunk && options.rowsPerChunk > 0 ? options.rowsPerChunk : 1e5;
   const values = params.length > 0 ? params.map((param) => toNodeApiValue(param)) : undefined;
   const result = await client.stream(query, values);
-  const columns = result.deduplicatedColumnNames?.() ?? result.columnNames();
-  const uniqueColumns = deduplicateColumns(columns);
+  const rawColumns = typeof result.deduplicatedColumnNames === "function" ? result.deduplicatedColumnNames() : result.columnNames();
+  const columns = typeof result.deduplicatedColumnNames === "function" ? rawColumns : deduplicateColumns(rawColumns);
   let buffer = [];
   for await (const chunk of result.yieldRowsJs()) {
-    const objects = mapRowsToObjects(uniqueColumns, chunk);
-    for (const row of objects) {
+    for (const row of chunk) {
       buffer.push(row);
       if (buffer.length >= rowsPerChunk) {
-        yield buffer;
+        yield { columns, rows: buffer };
         buffer = [];
       }
     }
   }
   if (buffer.length > 0) {
-    yield buffer;
+    yield { columns, rows: buffer };
   }
 }
 async function executeArrowOnClient(client, query, params) {
@@ -580,6 +805,20 @@ async function executeArrowOnClient(client, query, params) {
 }
 
 // src/session.ts
+function isSavepointSyntaxError(error) {
+  if (!(error instanceof Error) || !error.message) {
+    return false;
+  }
+  return error.message.toLowerCase().includes("savepoint") && error.message.toLowerCase().includes("syntax error");
+}
+function rewriteQuery(mode, query) {
+  if (mode === "never") {
+    return { sql: query, rewritten: false };
+  }
+  const rewritten = adaptArrayOperators(query);
+  return { sql: rewritten, rewritten: rewritten !== query };
+}
+
 class DuckDBPreparedQuery extends PgPreparedQuery {
   client;
   dialect;
@@ -589,11 +828,12 @@ class DuckDBPreparedQuery extends PgPreparedQuery {
   fields;
   _isResponseInArrayMode;
   customResultMapper;
-  rewriteArrays;
+  rewriteArraysMode;
   rejectStringArrayLiterals;
+  prepareCache;
   warnOnStringArrayLiteral;
   static [entityKind] = "DuckDBPreparedQuery";
-  constructor(client, dialect, queryString, params, logger, fields, _isResponseInArrayMode, customResultMapper, rewriteArrays, rejectStringArrayLiterals, warnOnStringArrayLiteral) {
+  constructor(client, dialect, queryString, params, logger, fields, _isResponseInArrayMode, customResultMapper, rewriteArraysMode, rejectStringArrayLiterals, prepareCache, warnOnStringArrayLiteral) {
     super({ sql: queryString, params });
     this.client = client;
     this.dialect = dialect;
@@ -603,8 +843,9 @@ class DuckDBPreparedQuery extends PgPreparedQuery {
     this.fields = fields;
     this._isResponseInArrayMode = _isResponseInArrayMode;
     this.customResultMapper = customResultMapper;
-    this.rewriteArrays = rewriteArrays;
+    this.rewriteArraysMode = rewriteArraysMode;
     this.rejectStringArrayLiterals = rejectStringArrayLiterals;
+    this.prepareCache = prepareCache;
     this.warnOnStringArrayLiteral = warnOnStringArrayLiteral;
   }
   async execute(placeholderValues = {}) {
@@ -613,18 +854,23 @@ class DuckDBPreparedQuery extends PgPreparedQuery {
       rejectStringArrayLiterals: this.rejectStringArrayLiterals,
       warnOnStringArrayLiteral: this.warnOnStringArrayLiteral ? () => this.warnOnStringArrayLiteral?.(this.queryString) : undefined
     });
-    const rewrittenQuery = this.rewriteArrays ? adaptArrayOperators(this.queryString) : this.queryString;
-    if (this.rewriteArrays && rewrittenQuery !== this.queryString) {
+    const { sql: rewrittenQuery, rewritten: didRewrite } = rewriteQuery(this.rewriteArraysMode, this.queryString);
+    if (didRewrite) {
       this.logger.logQuery(`[duckdb] original query before array rewrite: ${this.queryString}`, params);
     }
     this.logger.logQuery(rewrittenQuery, params);
     const { fields, joinsNotNullableMap, customResultMapper } = this;
-    const rows = await executeOnClient(this.client, rewrittenQuery, params);
-    if (rows.length === 0 || !fields) {
-      return rows;
+    if (fields) {
+      const { rows: rows2 } = await executeArraysOnClient(this.client, rewrittenQuery, params, { prepareCache: this.prepareCache });
+      if (rows2.length === 0) {
+        return [];
+      }
+      return customResultMapper ? customResultMapper(rows2) : rows2.map((row) => mapResultRow(fields, row, joinsNotNullableMap));
     }
-    const rowValues = rows.map((row) => Object.values(row));
-    return customResultMapper ? customResultMapper(rowValues) : rowValues.map((row) => mapResultRow(fields, row, joinsNotNullableMap));
+    const rows = await executeOnClient(this.client, rewrittenQuery, params, {
+      prepareCache: this.prepareCache
+    });
+    return rows;
   }
   all(placeholderValues = {}) {
     return this.execute(placeholderValues);
@@ -641,9 +887,11 @@ class DuckDBSession extends PgSession {
   static [entityKind] = "DuckDBSession";
   dialect;
   logger;
-  rewriteArrays;
+  rewriteArraysMode;
   rejectStringArrayLiterals;
+  prepareCache;
   hasWarnedArrayLiteral = false;
+  rollbackOnly = false;
   constructor(client, dialect, schema, options = {}) {
     super(dialect);
     this.client = client;
@@ -651,13 +899,27 @@ class DuckDBSession extends PgSession {
     this.options = options;
     this.dialect = dialect;
     this.logger = options.logger ?? new NoopLogger;
-    this.rewriteArrays = options.rewriteArrays ?? true;
+    this.rewriteArraysMode = options.rewriteArrays ?? "auto";
     this.rejectStringArrayLiterals = options.rejectStringArrayLiterals ?? false;
+    this.prepareCache = options.prepareCache;
+    this.options = {
+      ...options,
+      rewriteArrays: this.rewriteArraysMode,
+      prepareCache: this.prepareCache
+    };
   }
   prepareQuery(query, fields, name, isResponseInArrayMode, customResultMapper) {
-    return new DuckDBPreparedQuery(this.client, this.dialect, query.sql, query.params, this.logger, fields, isResponseInArrayMode, customResultMapper, this.rewriteArrays, this.rejectStringArrayLiterals, this.rejectStringArrayLiterals ? undefined : this.warnOnStringArrayLiteral);
+    return new DuckDBPreparedQuery(this.client, this.dialect, query.sql, query.params, this.logger, fields, isResponseInArrayMode, customResultMapper, this.rewriteArraysMode, this.rejectStringArrayLiterals, this.prepareCache, this.rejectStringArrayLiterals ? undefined : this.warnOnStringArrayLiteral);
   }
-  async transaction(transaction) {
+  execute(query) {
+    this.dialect.resetPgJsonFlag();
+    return super.execute(query);
+  }
+  all(query) {
+    this.dialect.resetPgJsonFlag();
+    return super.all(query);
+  }
+  async transaction(transaction, config) {
     let pinnedConnection;
     let pool;
     let clientForTx = this.client;
@@ -670,8 +932,15 @@ class DuckDBSession extends PgSession {
     const tx = new DuckDBTransaction(this.dialect, session, this.schema);
     try {
       await tx.execute(sql`BEGIN TRANSACTION;`);
+      if (config) {
+        await tx.setTransaction(config);
+      }
       try {
         const result = await transaction(tx);
+        if (session.isRollbackOnly()) {
+          await tx.execute(sql`rollback`);
+          throw new TransactionRollbackError;
+        }
         await tx.execute(sql`commit`);
         return result;
       } catch (error) {
@@ -693,31 +962,56 @@ class DuckDBSession extends PgSession {
 query: ${query}`, []);
   };
   executeBatches(query, options = {}) {
+    this.dialect.resetPgJsonFlag();
     const builtQuery = this.dialect.sqlToQuery(query);
+    this.dialect.assertNoPgJsonColumns();
     const params = prepareParams(builtQuery.params, {
       rejectStringArrayLiterals: this.rejectStringArrayLiterals,
       warnOnStringArrayLiteral: this.rejectStringArrayLiterals ? undefined : () => this.warnOnStringArrayLiteral(builtQuery.sql)
     });
-    const rewrittenQuery = this.rewriteArrays ? adaptArrayOperators(builtQuery.sql) : builtQuery.sql;
-    if (this.rewriteArrays && rewrittenQuery !== builtQuery.sql) {
+    const { sql: rewrittenQuery, rewritten: didRewrite } = rewriteQuery(this.rewriteArraysMode, builtQuery.sql);
+    if (didRewrite) {
       this.logger.logQuery(`[duckdb] original query before array rewrite: ${builtQuery.sql}`, params);
     }
     this.logger.logQuery(rewrittenQuery, params);
     return executeInBatches(this.client, rewrittenQuery, params, options);
   }
+  executeBatchesRaw(query, options = {}) {
+    this.dialect.resetPgJsonFlag();
+    const builtQuery = this.dialect.sqlToQuery(query);
+    this.dialect.assertNoPgJsonColumns();
+    const params = prepareParams(builtQuery.params, {
+      rejectStringArrayLiterals: this.rejectStringArrayLiterals,
+      warnOnStringArrayLiteral: this.rejectStringArrayLiterals ? undefined : () => this.warnOnStringArrayLiteral(builtQuery.sql)
+    });
+    const { sql: rewrittenQuery, rewritten: didRewrite } = rewriteQuery(this.rewriteArraysMode, builtQuery.sql);
+    if (didRewrite) {
+      this.logger.logQuery(`[duckdb] original query before array rewrite: ${builtQuery.sql}`, params);
+    }
+    this.logger.logQuery(rewrittenQuery, params);
+    return executeInBatchesRaw(this.client, rewrittenQuery, params, options);
+  }
   async executeArrow(query) {
+    this.dialect.resetPgJsonFlag();
     const builtQuery = this.dialect.sqlToQuery(query);
+    this.dialect.assertNoPgJsonColumns();
     const params = prepareParams(builtQuery.params, {
       rejectStringArrayLiterals: this.rejectStringArrayLiterals,
       warnOnStringArrayLiteral: this.rejectStringArrayLiterals ? undefined : () => this.warnOnStringArrayLiteral(builtQuery.sql)
     });
-    const rewrittenQuery = this.rewriteArrays ? adaptArrayOperators(builtQuery.sql) : builtQuery.sql;
-    if (this.rewriteArrays && rewrittenQuery !== builtQuery.sql) {
+    const { sql: rewrittenQuery, rewritten: didRewrite } = rewriteQuery(this.rewriteArraysMode, builtQuery.sql);
+    if (didRewrite) {
       this.logger.logQuery(`[duckdb] original query before array rewrite: ${builtQuery.sql}`, params);
     }
     this.logger.logQuery(rewrittenQuery, params);
     return executeArrowOnClient(this.client, rewrittenQuery, params);
   }
+  markRollbackOnly() {
+    this.rollbackOnly = true;
+  }
+  isRollbackOnly() {
+    return this.rollbackOnly;
+  }
 }
 
 class DuckDBTransaction extends PgTransaction {
@@ -744,12 +1038,53 @@ class DuckDBTransaction extends PgTransaction {
   executeBatches(query, options = {}) {
     return this.session.executeBatches(query, options);
   }
+  executeBatchesRaw(query, options = {}) {
+    return this.session.executeBatchesRaw(query, options);
+  }
   executeArrow(query) {
     return this.session.executeArrow(query);
   }
   async transaction(transaction) {
-    const nestedTx = new DuckDBTransaction(this.dialect, this.session, this.schema, this.nestedIndex + 1);
-    return transaction(nestedTx);
+    const internals = this;
+    const savepoint = `drizzle_savepoint_${this.nestedIndex + 1}`;
+    const savepointSql = sql.raw(`savepoint ${savepoint}`);
+    const releaseSql = sql.raw(`release savepoint ${savepoint}`);
+    const rollbackSql = sql.raw(`rollback to savepoint ${savepoint}`);
+    const nestedTx = new DuckDBTransaction(internals.dialect, internals.session, this.schema, this.nestedIndex + 1);
+    if (internals.dialect.areSavepointsUnsupported()) {
+      return this.runNestedWithoutSavepoint(transaction, nestedTx, internals);
+    }
+    let createdSavepoint = false;
+    try {
+      await internals.session.execute(savepointSql);
+      internals.dialect.markSavepointsSupported();
+      createdSavepoint = true;
+    } catch (error) {
+      if (!isSavepointSyntaxError(error)) {
+        throw error;
+      }
+      internals.dialect.markSavepointsUnsupported();
+      return this.runNestedWithoutSavepoint(transaction, nestedTx, internals);
+    }
+    try {
+      const result = await transaction(nestedTx);
+      if (createdSavepoint) {
+        await internals.session.execute(releaseSql);
+      }
+      return result;
+    } catch (error) {
+      if (createdSavepoint) {
+        await internals.session.execute(rollbackSql);
+      }
+      internals.session.markRollbackOnly();
+      throw error;
+    }
+  }
+  runNestedWithoutSavepoint(transaction, nestedTx, internals) {
+    return transaction(nestedTx).catch((error) => {
+      internals.session.markRollbackOnly();
+      throw error;
+    });
   }
 }
 var arrayLiteralWarning = "Received a stringified Postgres-style array literal. Use duckDbList()/duckDbArray() or pass native arrays instead. You can also set rejectStringArrayLiterals=true to throw.";
@@ -771,15 +1106,30 @@ import {
 import {
   sql as sql2
 } from "drizzle-orm";
-
 class DuckDBDialect extends PgDialect {
   static [entityKind2] = "DuckDBPgDialect";
   hasPgJsonColumn = false;
+  savepointsSupported = 0 /* Unknown */;
+  resetPgJsonFlag() {
+    this.hasPgJsonColumn = false;
+  }
+  markPgJsonDetected() {
+    this.hasPgJsonColumn = true;
+  }
   assertNoPgJsonColumns() {
     if (this.hasPgJsonColumn) {
-      throw new Error("Pg JSON/JSONB columns are not supported in DuckDB. Replace them with duckDbJson() to use DuckDB’s native JSON type.");
+      throw new Error("Pg JSON/JSONB columns are not supported in DuckDB. Replace them with duckDbJson() to use DuckDB's native JSON type.");
     }
   }
+  areSavepointsUnsupported() {
+    return this.savepointsSupported === 2 /* No */;
+  }
+  markSavepointsSupported() {
+    this.savepointsSupported = 1 /* Yes */;
+  }
+  markSavepointsUnsupported() {
+    this.savepointsSupported = 2 /* No */;
+  }
   async migrate(migrations, session, config) {
     const migrationConfig = typeof config === "string" ? { migrationsFolder: config } : config;
     const migrationsSchema = migrationConfig.migrationsSchema ?? "drizzle";
@@ -816,8 +1166,8 @@ class DuckDBDialect extends PgDialect {
   }
   prepareTyping(encoder) {
     if (is2(encoder, PgJsonb) || is2(encoder, PgJson)) {
-      this.hasPgJsonColumn = true;
-      return "none";
+      this.markPgJsonDetected();
+      throw new Error("Pg JSON/JSONB columns are not supported in DuckDB. Replace them with duckDbJson() to use DuckDB's native JSON type.");
     } else if (is2(encoder, PgNumeric)) {
       return "decimal";
     } else if (is2(encoder, PgTime2)) {
@@ -951,41 +1301,148 @@ function resolvePoolSize(pool) {
 }
 function createDuckDBConnectionPool(instance, options = {}) {
   const size = options.size && options.size > 0 ? options.size : 4;
+  const acquireTimeout = options.acquireTimeout ?? 30000;
+  const maxWaitingRequests = options.maxWaitingRequests ?? 100;
+  const maxLifetimeMs = options.maxLifetimeMs;
+  const idleTimeoutMs = options.idleTimeoutMs;
+  const metadata = new WeakMap;
   const idle = [];
   const waiting = [];
   let total = 0;
   let closed = false;
+  let pendingAcquires = 0;
+  const shouldRecycle = (conn, now) => {
+    if (maxLifetimeMs !== undefined && now - conn.createdAt >= maxLifetimeMs) {
+      return true;
+    }
+    if (idleTimeoutMs !== undefined && now - conn.lastUsedAt >= idleTimeoutMs) {
+      return true;
+    }
+    return false;
+  };
   const acquire = async () => {
     if (closed) {
       throw new Error("DuckDB connection pool is closed");
     }
-    if (idle.length > 0) {
-      return idle.pop();
+    while (idle.length > 0) {
+      const pooled = idle.pop();
+      const now = Date.now();
+      if (shouldRecycle(pooled, now)) {
+        await closeClientConnection(pooled.connection);
+        total = Math.max(0, total - 1);
+        metadata.delete(pooled.connection);
+        continue;
+      }
+      pooled.lastUsedAt = now;
+      metadata.set(pooled.connection, {
+        createdAt: pooled.createdAt,
+        lastUsedAt: pooled.lastUsedAt
+      });
+      return pooled.connection;
     }
     if (total < size) {
+      pendingAcquires += 1;
       total += 1;
-      return await DuckDBConnection.create(instance);
+      try {
+        const connection = await DuckDBConnection.create(instance);
+        if (closed) {
+          await closeClientConnection(connection);
+          total -= 1;
+          throw new Error("DuckDB connection pool is closed");
+        }
+        const now = Date.now();
+        metadata.set(connection, { createdAt: now, lastUsedAt: now });
+        return connection;
+      } catch (error) {
+        total -= 1;
+        throw error;
+      } finally {
+        pendingAcquires -= 1;
+      }
+    }
+    if (waiting.length >= maxWaitingRequests) {
+      throw new Error(`DuckDB connection pool queue is full (max ${maxWaitingRequests} waiting requests)`);
     }
-    return await new Promise((resolve) => {
-      waiting.push(resolve);
+    return await new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        const idx = waiting.findIndex((w) => w.timeoutId === timeoutId);
+        if (idx !== -1) {
+          waiting.splice(idx, 1);
+        }
+        reject(new Error(`DuckDB connection pool acquire timeout after ${acquireTimeout}ms`));
+      }, acquireTimeout);
+      waiting.push({ resolve, reject, timeoutId });
     });
   };
   const release = async (connection) => {
+    const waiter = waiting.shift();
+    if (waiter) {
+      clearTimeout(waiter.timeoutId);
+      const now2 = Date.now();
+      const meta = metadata.get(connection) ?? { createdAt: now2, lastUsedAt: now2 };
+      const expired = maxLifetimeMs !== undefined && now2 - meta.createdAt >= maxLifetimeMs;
+      if (closed) {
+        await closeClientConnection(connection);
+        total = Math.max(0, total - 1);
+        metadata.delete(connection);
+        waiter.reject(new Error("DuckDB connection pool is closed"));
+        return;
+      }
+      if (expired) {
+        await closeClientConnection(connection);
+        total = Math.max(0, total - 1);
+        metadata.delete(connection);
+        try {
+          const replacement = await acquire();
+          waiter.resolve(replacement);
+        } catch (error) {
+          waiter.reject(error);
+        }
+        return;
+      }
+      meta.lastUsedAt = now2;
+      metadata.set(connection, meta);
+      waiter.resolve(connection);
+      return;
+    }
     if (closed) {
       await closeClientConnection(connection);
+      metadata.delete(connection);
+      total = Math.max(0, total - 1);
       return;
     }
-    const waiter = waiting.shift();
-    if (waiter) {
-      waiter(connection);
+    const now = Date.now();
+    const existingMeta = metadata.get(connection) ?? { createdAt: now, lastUsedAt: now };
+    existingMeta.lastUsedAt = now;
+    metadata.set(connection, existingMeta);
+    if (maxLifetimeMs !== undefined && now - existingMeta.createdAt >= maxLifetimeMs) {
+      await closeClientConnection(connection);
+      total -= 1;
+      metadata.delete(connection);
       return;
     }
-    idle.push(connection);
+    idle.push({
+      connection,
+      createdAt: existingMeta.createdAt,
+      lastUsedAt: existingMeta.lastUsedAt
+    });
   };
   const close = async () => {
     closed = true;
+    const waiters = waiting.splice(0, waiting.length);
+    for (const waiter of waiters) {
+      clearTimeout(waiter.timeoutId);
+      waiter.reject(new Error("DuckDB connection pool is closed"));
+    }
     const toClose = idle.splice(0, idle.length);
-    await Promise.all(toClose.map((conn) => closeClientConnection(conn)));
+    await Promise.allSettled(toClose.map((item) => closeClientConnection(item.connection)));
+    total = Math.max(0, total - toClose.length);
+    toClose.forEach((item) => metadata.delete(item.connection));
+    const maxWait = 5000;
+    const start = Date.now();
+    while (pendingAcquires > 0 && Date.now() - start < maxWait) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
   };
   return {
     acquire,
@@ -995,6 +1452,32 @@ function createDuckDBConnectionPool(instance, options = {}) {
   };
 }
 
+// src/options.ts
+var DEFAULT_REWRITE_ARRAYS_MODE = "auto";
+function resolveRewriteArraysOption(value) {
+  if (value === undefined)
+    return DEFAULT_REWRITE_ARRAYS_MODE;
+  if (value === true)
+    return "auto";
+  if (value === false)
+    return "never";
+  return value;
+}
+var DEFAULT_PREPARED_CACHE_SIZE = 32;
+function resolvePrepareCacheOption(option) {
+  if (!option)
+    return;
+  if (option === true) {
+    return { size: DEFAULT_PREPARED_CACHE_SIZE };
+  }
+  if (typeof option === "number") {
+    const size2 = Math.max(1, Math.floor(option));
+    return { size: size2 };
+  }
+  const size = option.size ?? DEFAULT_PREPARED_CACHE_SIZE;
+  return { size: Math.max(1, Math.floor(size)) };
+}
+
 // src/driver.ts
 class DuckDBDriver {
   client;
@@ -1009,8 +1492,9 @@ class DuckDBDriver {
   createSession(schema) {
     return new DuckDBSession(this.client, this.dialect, schema, {
       logger: this.options.logger,
-      rewriteArrays: this.options.rewriteArrays,
-      rejectStringArrayLiterals: this.options.rejectStringArrayLiterals
+      rewriteArrays: this.options.rewriteArrays ?? "auto",
+      rejectStringArrayLiterals: this.options.rejectStringArrayLiterals,
+      prepareCache: this.options.prepareCache
     });
   }
 }
@@ -1023,6 +1507,8 @@ function isConfigObject(data) {
 }
 function createFromClient(client, config = {}, instance) {
   const dialect = new DuckDBDialect;
+  const rewriteArraysMode = resolveRewriteArraysOption(config.rewriteArrays);
+  const prepareCache = resolvePrepareCacheOption(config.prepareCache);
   const logger = config.logger === true ? new DefaultLogger : config.logger || undefined;
   let schema;
   if (config.schema) {
@@ -1035,8 +1521,9 @@ function createFromClient(client, config = {}, instance) {
   }
   const driver = new DuckDBDriver(client, dialect, {
     logger,
-    rewriteArrays: config.rewriteArrays,
-    rejectStringArrayLiterals: config.rejectStringArrayLiterals
+    rewriteArrays: rewriteArraysMode,
+    rejectStringArrayLiterals: config.rejectStringArrayLiterals,
+    prepareCache
   });
   const session = driver.createSession(schema);
   const db = new DuckDBDatabase(dialect, session, schema, client, instance);
@@ -1093,6 +1580,17 @@ class DuckDBDatabase extends PgDatabase {
     if (isPool(this.$client) && this.$client.close) {
       await this.$client.close();
     }
+    if (!isPool(this.$client)) {
+      await closeClientConnection(this.$client);
+    }
+    if (this.$instance) {
+      const maybeClosable = this.$instance;
+      if (typeof maybeClosable.close === "function") {
+        await maybeClosable.close();
+      } else if (typeof maybeClosable.closeSync === "function") {
+        maybeClosable.closeSync();
+      }
+    }
   }
   select(fields) {
     const selectedFields = fields ? aliasFields(fields) : undefined;
@@ -1105,6 +1603,9 @@ class DuckDBDatabase extends PgDatabase {
   executeBatches(query, options = {}) {
     return this.session.executeBatches(query, options);
   }
+  executeBatchesRaw(query, options = {}) {
+    return this.session.executeBatchesRaw(query, options);
+  }
   executeArrow(query) {
     return this.session.executeArrow(query);
   }
@@ -1176,6 +1677,13 @@ function buildStructLiteral(value, schema) {
   });
   return sql4`struct_pack(${sql4.join(parts, sql4.raw(", "))})`;
 }
+function buildMapLiteral(value, valueType) {
+  const keys = Object.keys(value);
+  const vals = Object.values(value);
+  const keyList = buildListLiteral(keys, "TEXT");
+  const valList = buildListLiteral(vals, valueType?.endsWith("[]") ? valueType.slice(0, -2) : valueType);
+  return sql4`map(${keyList}, ${valList})`;
+}
 var duckDbList = (name, elementType) => customType({
   dataType() {
     return `${elementType}[]`;
@@ -1189,11 +1697,11 @@ var duckDbList = (name, elementType) => customType({
     }
     if (typeof value === "string") {
       const parsed = coerceArrayString(value);
-      if (parsed) {
+      if (parsed !== undefined) {
         return parsed;
       }
     }
-    return [];
+    return value;
   }
 })(name);
 var duckDbArray = (name, elementType, fixedLength) => customType({
@@ -1209,11 +1717,11 @@ var duckDbArray = (name, elementType, fixedLength) => customType({
     }
     if (typeof value === "string") {
       const parsed = coerceArrayString(value);
-      if (parsed) {
+      if (parsed !== undefined) {
         return parsed;
       }
     }
-    return [];
+    return value;
   }
 })(name);
 var duckDbMap = (name, valueType) => customType({
@@ -1298,6 +1806,21 @@ var duckDbInterval = (name) => customType({
     return value;
   }
 })(name);
+function shouldBindTimestamp(options) {
+  const bindMode = options.bindMode ?? "auto";
+  if (bindMode === "bind")
+    return true;
+  if (bindMode === "literal")
+    return false;
+  const isBun = typeof process !== "undefined" && typeof process.versions?.bun !== "undefined";
+  if (isBun)
+    return false;
+  const forceLiteral = typeof process !== "undefined" ? process.env.DRIZZLE_DUCKDB_FORCE_LITERAL_TIMESTAMPS : undefined;
+  if (forceLiteral && forceLiteral !== "0") {
+    return false;
+  }
+  return true;
+}
 var duckDbTimestamp = (name, options = {}) => customType({
   dataType() {
     if (options.withTimezone) {
@@ -1307,12 +1830,19 @@ var duckDbTimestamp = (name, options = {}) => customType({
     return `TIMESTAMP${precision}`;
   },
   toDriver(value) {
+    if (shouldBindTimestamp(options)) {
+      return wrapTimestamp(value, options.withTimezone ?? false, options.precision);
+    }
     const iso = value instanceof Date ? value.toISOString() : value;
     const normalized = iso.replace("T", " ").replace("Z", "+00");
     const typeKeyword = options.withTimezone ? "TIMESTAMPTZ" : "TIMESTAMP";
     return sql4.raw(`${typeKeyword} '${normalized}'`);
   },
   fromDriver(value) {
+    if (value && typeof value === "object" && "kind" in value && value.kind === "timestamp") {
+      const wrapped = value;
+      return wrapped.data instanceof Date ? wrapped.data : typeof wrapped.data === "number" || typeof wrapped.data === "bigint" ? new Date(Number(wrapped.data) / 1000) : wrapped.data;
+    }
     if (options.mode === "string") {
       if (value instanceof Date) {
         return value.toISOString().replace("T", " ").replace("Z", "+00");
@@ -1761,6 +2291,20 @@ function mapDuckDbType(column, imports, options) {
     imports.pgCore.add("text");
     return { builder: `text(${columnName(column.name)}) /* JSON */` };
   }
+  if (upper.startsWith("ENUM")) {
+    imports.pgCore.add("text");
+    const enumLiteral = raw.replace(/^ENUM\s*/i, "").trim();
+    return {
+      builder: `text(${columnName(column.name)}) /* ENUM ${enumLiteral} */`
+    };
+  }
+  if (upper.startsWith("UNION")) {
+    imports.pgCore.add("text");
+    const unionLiteral = raw.replace(/^UNION\s*/i, "").trim();
+    return {
+      builder: `text(${columnName(column.name)}) /* UNION ${unionLiteral} */`
+    };
+  }
   if (upper === "INET") {
     imports.local.add("duckDbInet");
     return { builder: `duckDbInet(${columnName(column.name)})` };
@@ -1826,7 +2370,7 @@ function mapDuckDbType(column, imports, options) {
   }
   imports.pgCore.add("text");
   return {
-    builder: `text(${columnName(column.name)}) /* TODO: verify type ${upper} */`
+    builder: `text(${columnName(column.name)}) /* unsupported DuckDB type: ${upper} */`
   };
 }
 function parseStructFields(inner) {
@@ -2049,13 +2593,19 @@ export {
   wrapJson,
   wrapBlob,
   wrapArray,
+  toIdentifier,
   sumN,
   sumDistinctN,
+  splitTopLevel,
   rowNumber,
+  resolveRewriteArraysOption,
+  resolvePrepareCacheOption,
   resolvePoolSize,
   rank,
   prepareParams,
   percentileCont,
+  parseStructFields,
+  parseMapValue,
   olap,
   migrate,
   median,
@@ -2064,9 +2614,12 @@ export {
   isPool,
   isDuckDBWrapper,
   introspect,
+  formatLiteral,
   executeOnClient,
+  executeInBatchesRaw,
   executeInBatches,
   executeArrowOnClient,
+  executeArraysOnClient,
   duckDbTimestamp,
   duckDbTime,
   duckDbStruct,
@@ -2085,7 +2638,12 @@ export {
   denseRank,
   createDuckDBConnectionPool,
   countN,
+  coerceArrayString,
   closeClientConnection,
+  buildStructLiteral,
+  buildMapLiteral,
+  buildListLiteral,
+  buildDefault,
   avgN,
   anyValue,
   POOL_PRESETS,