@mastra/duckdb 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @mastra/duckdb
 
+## 1.5.2
+
+### Patch Changes
+
+- Fixed severe CPU and memory spikes when listing traces from large DuckDB databases. ([#20175](https://github.com/mastra-ai/mastra/pull/20175))
+
+  Opening the traces page in Studio (or calling the list traces / list branches APIs) against a multi-GB trace database previously decompressed the entire span_events table for every page load, poll, and scroll — pinning all CPU cores and ballooning memory by several GB per query. On multi-GB databases, trace list queries now use roughly 5x less CPU and stay within a bounded memory budget:
+
+  - Page queries now scan only the time range containing the requested spans instead of the whole table
+  - Filtered and custom-ordered queries (status, hasChildError, order by endedAt) now paginate on a narrow column set before reconstructing full span payloads
+  - Delta polls now short-circuit when there is no new data
+
+  Also added `memoryLimit` and `threads` options to `DuckDBStore`. DuckDB previously used its default memory budget of 80% of system RAM, which could push application servers into swap; it now defaults to 2GB. File-backed databases spill larger-than-memory operations to disk. Note that `:memory:` databases cannot spill, so if you run very large queries against an in-memory database, raise `memoryLimit`.
+
+  ```typescript
+  const store = new DuckDBStore({
+    path: 'mastra.duckdb',
+    memoryLimit: '4GB', // default '2GB'
+    threads: 2, // default: one per CPU core
+  });
+  ```
+
+- Updated dependencies [[`ce93a3c`](https://github.com/mastra-ai/mastra/commit/ce93a3c114ea1cbfbd576f3db41d7c26c9844f5b), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`a211d09`](https://github.com/mastra-ai/mastra/commit/a211d09185dc65a746534914cf38b67f21ee9bac), [`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa), [`6218217`](https://github.com/mastra-ai/mastra/commit/62182171b6cfca0b099f1c6a77a2e65e7639ab86), [`5807d3a`](https://github.com/mastra-ai/mastra/commit/5807d3ae1d259b8b7d6df7e5bf2b485c694af9c8), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`05db566`](https://github.com/mastra-ai/mastra/commit/05db566fcbdcbf33d0bffca0c72ec30129e2e3ca), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`d1b7e3a`](https://github.com/mastra-ai/mastra/commit/d1b7e3a978a309a5653eeaa490d2d6c7c53bd093), [`29c584a`](https://github.com/mastra-ai/mastra/commit/29c584a13a88831e5ed1fdeb0ff8e82eae180433), [`c093146`](https://github.com/mastra-ai/mastra/commit/c0931466404d3c521308ea119cb165bb7e695155), [`8124754`](https://github.com/mastra-ai/mastra/commit/8124754ae89fbc69f8136d1df4a91904d0f84c4e), [`d12b2e4`](https://github.com/mastra-ai/mastra/commit/d12b2e4023fd9e3d3e93a9169f5088bcee2a849c)]:
+  - @mastra/core@1.54.0
+
+## 1.5.2-alpha.0
+
+### Patch Changes
+
+- Fixed severe CPU and memory spikes when listing traces from large DuckDB databases. ([#20175](https://github.com/mastra-ai/mastra/pull/20175))
+
+  Opening the traces page in Studio (or calling the list traces / list branches APIs) against a multi-GB trace database previously decompressed the entire span_events table for every page load, poll, and scroll — pinning all CPU cores and ballooning memory by several GB per query. On multi-GB databases, trace list queries now use roughly 5x less CPU and stay within a bounded memory budget:
+
+  - Page queries now scan only the time range containing the requested spans instead of the whole table
+  - Filtered and custom-ordered queries (status, hasChildError, order by endedAt) now paginate on a narrow column set before reconstructing full span payloads
+  - Delta polls now short-circuit when there is no new data
+
+  Also added `memoryLimit` and `threads` options to `DuckDBStore`. DuckDB previously used its default memory budget of 80% of system RAM, which could push application servers into swap; it now defaults to 2GB. File-backed databases spill larger-than-memory operations to disk. Note that `:memory:` databases cannot spill, so if you run very large queries against an in-memory database, raise `memoryLimit`.
+
+  ```typescript
+  const store = new DuckDBStore({
+    path: 'mastra.duckdb',
+    memoryLimit: '4GB', // default '2GB'
+    threads: 2, // default: one per CPU core
+  });
+  ```
+
+- Updated dependencies [[`ce93a3c`](https://github.com/mastra-ai/mastra/commit/ce93a3c114ea1cbfbd576f3db41d7c26c9844f5b), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`5807d3a`](https://github.com/mastra-ai/mastra/commit/5807d3ae1d259b8b7d6df7e5bf2b485c694af9c8), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`d1b7e3a`](https://github.com/mastra-ai/mastra/commit/d1b7e3a978a309a5653eeaa490d2d6c7c53bd093), [`c093146`](https://github.com/mastra-ai/mastra/commit/c0931466404d3c521308ea119cb165bb7e695155)]:
+  - @mastra/core@1.54.0-alpha.1
+
 ## 1.5.1
 
 ### Patch Changes
@@ -380,9 +430,7 @@
   });
 
   export const mastra = new Mastra({
-    agents: {
-      /* your agents here */
-    },
+    agents: {/* your agents here */},
     observability: new Observability({
       configs: {
         default: {
@@ -466,9 +514,7 @@
   });
 
   export const mastra = new Mastra({
-    agents: {
-      /* your agents here */
-    },
+    agents: {/* your agents here */},
     observability: new Observability({
       configs: {
         default: {
@@ -515,9 +561,7 @@
   });
 
   export const mastra = new Mastra({
-    agents: {
-      /* your agents here */
-    },
+    agents: {/* your agents here */},
     observability: new Observability({
       configs: {
         default: {

package/dist/db-Dl0fY488.js

@@ -0,0 +1,204 @@
+import { DuckDBInstance, DuckDBTimestampTZValue, DuckDBTimestampValue } from "@duckdb/node-api";
+import { MastraBase } from "@mastra/core/base";
+//#region src/storage/db/index.ts
+/**
+* Bind a single parameter to a prepared statement using explicit typed methods.
+* This avoids the "Cannot create values of type ANY" error that occurs when
+* DuckDB cannot infer parameter types from SQL context (e.g. json_extract_string).
+*/
+function bindParam(stmt, index, value) {
+	if (value === null || value === void 0) stmt.bindNull(index);
+	else if (typeof value === "string") stmt.bindVarchar(index, value);
+	else if (typeof value === "number") if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) stmt.bindInteger(index, value);
+	else stmt.bindDouble(index, value);
+	else if (typeof value === "boolean") stmt.bindBoolean(index, value);
+	else if (typeof value === "bigint") stmt.bindBigInt(index, value);
+	else if (value instanceof Date) stmt.bindTimestamp(index, new DuckDBTimestampValue(BigInt(value.getTime()) * 1000n));
+	else if (value instanceof DuckDBTimestampValue) stmt.bindTimestamp(index, value);
+	else if (value instanceof DuckDBTimestampTZValue) stmt.bindTimestampTZ(index, value);
+	else stmt.bindVarchar(index, JSON.stringify(value));
+}
+/** Convert DuckDB-specific return types to plain JS types */
+function toJsValue(val) {
+	if (val === null || val === void 0) return val;
+	if (val instanceof DuckDBTimestampValue) return new Date(Number(val.micros / 1000n));
+	if (typeof val === "bigint") return Number(val);
+	return val;
+}
+const DEFAULT_MEMORY_LIMIT = "2GB";
+/**
+* Shared DuckDB connection management for Mastra storage.
+* Defaults to a local file (`mastra.duckdb`) when no path is provided.
+* Pass `path: ':memory:'` for an ephemeral in-memory database.
+*/
+var DuckDBConnection = class extends MastraBase {
+	instance = null;
+	initialized = false;
+	initPromise = null;
+	path;
+	instanceOptions;
+	constructor(config = {}) {
+		super({
+			component: "STORAGE",
+			name: "DUCKDB"
+		});
+		this.path = config.path ?? "mastra.duckdb";
+		this.instanceOptions = {
+			max_memory: config.memoryLimit ?? DEFAULT_MEMORY_LIMIT,
+			...config.threads !== void 0 ? { threads: String(config.threads) } : {}
+		};
+	}
+	async initialize() {
+		if (this.initialized && this.instance) return;
+		if (this.initPromise) {
+			await this.initPromise;
+			if (this.instance) return;
+			this.initPromise = null;
+			this.initialized = false;
+		}
+		this.initPromise = (async () => {
+			try {
+				this.instance = await DuckDBInstance.create(this.path, this.instanceOptions);
+				this.initialized = true;
+			} catch (error) {
+				this.instance = null;
+				this.initialized = false;
+				this.initPromise = null;
+				throw error;
+			}
+		})();
+		return this.initPromise;
+	}
+	/** Create a new connection to the DuckDB instance, initializing if needed. */
+	async getConnection() {
+		await this.initialize();
+		if (!this.instance) throw new Error("DuckDB instance not initialized");
+		return this.instance.connect();
+	}
+	closeConnection(connection) {
+		const conn = connection;
+		try {
+			if (typeof conn?.closeSync === "function") {
+				conn.closeSync();
+				return;
+			}
+			if (typeof conn?.disconnectSync === "function") {
+				conn.disconnectSync();
+				return;
+			}
+			if (typeof conn?.close === "function") {
+				conn.close();
+				return;
+			}
+			if (typeof conn?.disconnect === "function") conn.disconnect();
+		} catch {}
+	}
+	/**
+	* Execute a SQL query and return results as objects.
+	*/
+	async query(sql, params = []) {
+		const connection = await this.getConnection();
+		try {
+			if (params.length === 0) {
+				const result = await connection.run(sql);
+				const rows = await result.getRows();
+				const columns = result.columnNames();
+				return rows.map((row) => {
+					const obj = {};
+					columns.forEach((col, i) => {
+						obj[col] = toJsValue(row[i]);
+					});
+					return obj;
+				});
+			}
+			let paramIndex = 0;
+			const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
+			const stmt = await connection.prepare(preparedSql);
+			for (let i = 0; i < params.length; i++) bindParam(stmt, i + 1, params[i]);
+			const result = await stmt.run();
+			const rows = await result.getRows();
+			const columns = result.columnNames();
+			return rows.map((row) => {
+				const obj = {};
+				columns.forEach((col, i) => {
+					obj[col] = toJsValue(row[i]);
+				});
+				return obj;
+			});
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Execute a SQL statement without returning results.
+	*/
+	async execute(sql, params = []) {
+		const connection = await this.getConnection();
+		try {
+			if (params.length === 0) {
+				await connection.run(sql);
+				return;
+			}
+			let paramIndex = 0;
+			const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
+			const stmt = await connection.prepare(preparedSql);
+			for (let i = 0; i < params.length; i++) bindParam(stmt, i + 1, params[i]);
+			await stmt.run();
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Execute multiple SQL statements in order using a single DuckDB connection.
+	*
+	* This is intended for schema setup/migrations where statements have no
+	* parameters and must remain ordered, but opening a connection per statement
+	* would dominate initialization cost. Blank statements are skipped. Like
+	* calling execute() repeatedly, this does not wrap statements in a transaction,
+	* so prior statements can remain applied if a later statement fails.
+	*/
+	async executeBatch(sqlStatements) {
+		const statements = sqlStatements.map((statement) => statement.trim()).filter(Boolean);
+		if (statements.length === 0) return;
+		const connection = await this.getConnection();
+		try {
+			const sql = statements.map((statement, i) => `-- executeBatch statement ${i + 1}\n${statement}`).join("\n;\n") + "\n;";
+			await connection.run(sql);
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Escape a value for safe inline SQL use.
+	* DuckDB prepared statements can't handle NULL for parameters typed as ANY,
+	* so for complex INSERT/UPDATE operations we inline values safely.
+	*/
+	static sqlValue(value) {
+		if (value === null || value === void 0) return "NULL";
+		if (typeof value === "number") {
+			if (!Number.isFinite(value)) return "NULL";
+			return String(value);
+		}
+		if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+		if (value instanceof Date) return `'${value.toISOString()}'::TIMESTAMP`;
+		if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+		return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+	}
+	/** Release the DuckDB instance, allowing garbage collection. */
+	async close() {
+		if (this.instance) {
+			try {
+				const instance = this.instance;
+				if (typeof instance.closeSync === "function") instance.closeSync();
+				else if (typeof instance.close === "function") instance.close();
+			} catch {}
+			this.instance = null;
+			this.initialized = false;
+			this.initPromise = null;
+		}
+	}
+};
+//#endregion
+export { bindParam as n, DuckDBConnection as t };
+
+//# sourceMappingURL=db-Dl0fY488.js.map

package/dist/db-Dl0fY488.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-Dl0fY488.js","names":[],"sources":["../src/storage/db/index.ts"],"sourcesContent":["import { DuckDBInstance, DuckDBTimestampValue, DuckDBTimestampTZValue } from '@duckdb/node-api';\nimport type { DuckDBPreparedStatement } from '@duckdb/node-api';\nimport { MastraBase } from '@mastra/core/base';\n\n/**\n * Bind a single parameter to a prepared statement using explicit typed methods.\n * This avoids the \"Cannot create values of type ANY\" error that occurs when\n * DuckDB cannot infer parameter types from SQL context (e.g. json_extract_string).\n */\nexport function bindParam(stmt: DuckDBPreparedStatement, index: number, value: unknown): void {\n  if (value === null || value === undefined) {\n    stmt.bindNull(index);\n  } else if (typeof value === 'string') {\n    stmt.bindVarchar(index, value);\n  } else if (typeof value === 'number') {\n    if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) {\n      stmt.bindInteger(index, value);\n    } else {\n      stmt.bindDouble(index, value);\n    }\n  } else if (typeof value === 'boolean') {\n    stmt.bindBoolean(index, value);\n  } else if (typeof value === 'bigint') {\n    stmt.bindBigInt(index, value);\n  } else if (value instanceof Date) {\n    stmt.bindTimestamp(index, new DuckDBTimestampValue(BigInt(value.getTime()) * 1000n));\n  } else if (value instanceof DuckDBTimestampValue) {\n    stmt.bindTimestamp(index, value);\n  } else if (value instanceof DuckDBTimestampTZValue) {\n    stmt.bindTimestampTZ(index, value);\n  } else {\n    // Fallback: serialize to JSON string\n    stmt.bindVarchar(index, JSON.stringify(value));\n  }\n}\n\n/** Convert DuckDB-specific return types to plain JS types */\nfunction toJsValue(val: unknown): unknown {\n  if (val === null || val === undefined) return val;\n  // DuckDBTimestampValue → Date (micros since epoch)\n  if (val instanceof DuckDBTimestampValue) {\n    return new Date(Number(val.micros / 1000n));\n  }\n  // BigInt → Number (safe for values we care about)\n  if (typeof val === 'bigint') {\n    return Number(val);\n  }\n  return val;\n}\n\n/** Configuration for the DuckDB database connection. */\nexport interface DuckDBStorageConfig {\n  /** Path to the DuckDB file. Defaults to 'mastra.duckdb'. Use ':memory:' for ephemeral. */\n  path?: string;\n  /**\n   * Maximum memory DuckDB may use (e.g. '2GB', '512MB').\n   * @default '2GB'\n   * DuckDB's own default is 80% of system RAM, which is far too aggressive for\n   * a store embedded in an application server — a single query against a large\n   * database can balloon the process by several GB and push the host into\n   * swap. Larger-than-memory operations spill to disk for file-backed\n   * databases. Raise this for dedicated analytical workloads.\n   */\n  memoryLimit?: string;\n  /**\n   * Number of threads DuckDB may use. Defaults to DuckDB's default (one per\n   * CPU core). Lower this to keep queries from monopolizing all cores of a\n   * shared application server.\n   */\n  threads?: number;\n}\n\nconst DEFAULT_MEMORY_LIMIT = '2GB';\n\n/**\n * Shared DuckDB connection management for Mastra storage.\n * Defaults to a local file (`mastra.duckdb`) when no path is provided.\n * Pass `path: ':memory:'` for an ephemeral in-memory database.\n */\nexport class DuckDBConnection extends MastraBase {\n  private instance: DuckDBInstance | null = null;\n  private initialized = false;\n  private initPromise: Promise<void> | null = null;\n  private path: string;\n  private instanceOptions: Record<string, string>;\n\n  constructor(config: DuckDBStorageConfig = {}) {\n    super({ component: 'STORAGE', name: 'DUCKDB' });\n    this.path = config.path ?? 'mastra.duckdb';\n    this.instanceOptions = {\n      max_memory: config.memoryLimit ?? DEFAULT_MEMORY_LIMIT,\n      ...(config.threads !== undefined ? { threads: String(config.threads) } : {}),\n    };\n  }\n\n  private async initialize(): Promise<void> {\n    if (this.initialized && this.instance) return;\n\n    if (this.initPromise) {\n      await this.initPromise;\n      if (this.instance) return;\n      this.initPromise = null;\n      this.initialized = false;\n    }\n\n    this.initPromise = (async () => {\n      try {\n        this.instance = await DuckDBInstance.create(this.path, this.instanceOptions);\n        this.initialized = true;\n      } catch (error) {\n        this.instance = null;\n        this.initialized = false;\n        this.initPromise = null;\n        throw error;\n      }\n    })();\n\n    return this.initPromise;\n  }\n\n  /** Create a new connection to the DuckDB instance, initializing if needed. */\n  async getConnection() {\n    await this.initialize();\n    if (!this.instance) {\n      throw new Error('DuckDB instance not initialized');\n    }\n    return this.instance.connect();\n  }\n\n  private closeConnection(connection: unknown): void {\n    const conn = connection as {\n      closeSync?: () => void;\n      disconnectSync?: () => void;\n      close?: () => void;\n      disconnect?: () => void;\n    };\n    try {\n      if (typeof conn?.closeSync === 'function') {\n        conn.closeSync();\n        return;\n      }\n      if (typeof conn?.disconnectSync === 'function') {\n        conn.disconnectSync();\n        return;\n      }\n      if (typeof conn?.close === 'function') {\n        conn.close();\n        return;\n      }\n      if (typeof conn?.disconnect === 'function') {\n        conn.disconnect();\n      }\n    } catch {\n      // Ignore close failures to avoid masking query/execute errors.\n    }\n  }\n\n  /**\n   * Execute a SQL query and return results as objects.\n   */\n  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {\n    const connection = await this.getConnection();\n    try {\n      if (params.length === 0) {\n        const result = await connection.run(sql);\n        const rows = await result.getRows();\n        const columns = result.columnNames();\n        return rows.map(row => {\n          const obj: Record<string, unknown> = {};\n          columns.forEach((col, i) => {\n            obj[col] = toJsValue(row[i]);\n          });\n          return obj as T;\n        });\n      }\n\n      let paramIndex = 0;\n      const preparedSql = sql.replace(/\\?/g, () => `$${++paramIndex}`);\n      const stmt = await connection.prepare(preparedSql);\n      for (let i = 0; i < params.length; i++) {\n        bindParam(stmt, i + 1, params[i]);\n      }\n      const result = await stmt.run();\n      const rows = await result.getRows();\n      const columns = result.columnNames();\n      return rows.map(row => {\n        const obj: Record<string, unknown> = {};\n        columns.forEach((col, i) => {\n          obj[col] = toJsValue(row[i]);\n        });\n        return obj as T;\n      });\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Execute a SQL statement without returning results.\n   */\n  async execute(sql: string, params: unknown[] = []): Promise<void> {\n    const connection = await this.getConnection();\n    try {\n      if (params.length === 0) {\n        await connection.run(sql);\n        return;\n      }\n      let paramIndex = 0;\n      const preparedSql = sql.replace(/\\?/g, () => `$${++paramIndex}`);\n      const stmt = await connection.prepare(preparedSql);\n      for (let i = 0; i < params.length; i++) {\n        bindParam(stmt, i + 1, params[i]);\n      }\n      await stmt.run();\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Execute multiple SQL statements in order using a single DuckDB connection.\n   *\n   * This is intended for schema setup/migrations where statements have no\n   * parameters and must remain ordered, but opening a connection per statement\n   * would dominate initialization cost. Blank statements are skipped. Like\n   * calling execute() repeatedly, this does not wrap statements in a transaction,\n   * so prior statements can remain applied if a later statement fails.\n   */\n  async executeBatch(sqlStatements: readonly string[]): Promise<void> {\n    const statements = sqlStatements.map(statement => statement.trim()).filter(Boolean);\n    if (statements.length === 0) return;\n\n    const connection = await this.getConnection();\n    try {\n      const sql =\n        statements.map((statement, i) => `-- executeBatch statement ${i + 1}\\n${statement}`).join('\\n;\\n') + '\\n;';\n      await connection.run(sql);\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Escape a value for safe inline SQL use.\n   * DuckDB prepared statements can't handle NULL for parameters typed as ANY,\n   * so for complex INSERT/UPDATE operations we inline values safely.\n   */\n  static sqlValue(value: unknown): string {\n    if (value === null || value === undefined) return 'NULL';\n    if (typeof value === 'number') {\n      if (!Number.isFinite(value)) return 'NULL';\n      return String(value);\n    }\n    if (typeof value === 'boolean') return value ? 'TRUE' : 'FALSE';\n    if (value instanceof Date) return `'${value.toISOString()}'::TIMESTAMP`;\n    if (typeof value === 'string') return `'${value.replace(/'/g, \"''\")}'`;\n    // Objects/arrays → JSON string\n    return `'${JSON.stringify(value).replace(/'/g, \"''\")}'`;\n  }\n\n  /** Release the DuckDB instance, allowing garbage collection. */\n  async close(): Promise<void> {\n    if (this.instance) {\n      try {\n        const instance = this.instance as unknown as { closeSync?: () => void; close?: () => void };\n        if (typeof instance.closeSync === 'function') {\n          instance.closeSync();\n        } else if (typeof instance.close === 'function') {\n          instance.close();\n        }\n      } catch {\n        // Ignore close failures to allow cleanup of references.\n      }\n      this.instance = null;\n      this.initialized = false;\n      this.initPromise = null;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/db-TBEcMD49.cjs

@@ -0,0 +1,215 @@
+let _duckdb_node_api = require("@duckdb/node-api");
+let _mastra_core_base = require("@mastra/core/base");
+//#region src/storage/db/index.ts
+/**
+* Bind a single parameter to a prepared statement using explicit typed methods.
+* This avoids the "Cannot create values of type ANY" error that occurs when
+* DuckDB cannot infer parameter types from SQL context (e.g. json_extract_string).
+*/
+function bindParam(stmt, index, value) {
+	if (value === null || value === void 0) stmt.bindNull(index);
+	else if (typeof value === "string") stmt.bindVarchar(index, value);
+	else if (typeof value === "number") if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) stmt.bindInteger(index, value);
+	else stmt.bindDouble(index, value);
+	else if (typeof value === "boolean") stmt.bindBoolean(index, value);
+	else if (typeof value === "bigint") stmt.bindBigInt(index, value);
+	else if (value instanceof Date) stmt.bindTimestamp(index, new _duckdb_node_api.DuckDBTimestampValue(BigInt(value.getTime()) * 1000n));
+	else if (value instanceof _duckdb_node_api.DuckDBTimestampValue) stmt.bindTimestamp(index, value);
+	else if (value instanceof _duckdb_node_api.DuckDBTimestampTZValue) stmt.bindTimestampTZ(index, value);
+	else stmt.bindVarchar(index, JSON.stringify(value));
+}
+/** Convert DuckDB-specific return types to plain JS types */
+function toJsValue(val) {
+	if (val === null || val === void 0) return val;
+	if (val instanceof _duckdb_node_api.DuckDBTimestampValue) return new Date(Number(val.micros / 1000n));
+	if (typeof val === "bigint") return Number(val);
+	return val;
+}
+const DEFAULT_MEMORY_LIMIT = "2GB";
+/**
+* Shared DuckDB connection management for Mastra storage.
+* Defaults to a local file (`mastra.duckdb`) when no path is provided.
+* Pass `path: ':memory:'` for an ephemeral in-memory database.
+*/
+var DuckDBConnection = class extends _mastra_core_base.MastraBase {
+	instance = null;
+	initialized = false;
+	initPromise = null;
+	path;
+	instanceOptions;
+	constructor(config = {}) {
+		super({
+			component: "STORAGE",
+			name: "DUCKDB"
+		});
+		this.path = config.path ?? "mastra.duckdb";
+		this.instanceOptions = {
+			max_memory: config.memoryLimit ?? DEFAULT_MEMORY_LIMIT,
+			...config.threads !== void 0 ? { threads: String(config.threads) } : {}
+		};
+	}
+	async initialize() {
+		if (this.initialized && this.instance) return;
+		if (this.initPromise) {
+			await this.initPromise;
+			if (this.instance) return;
+			this.initPromise = null;
+			this.initialized = false;
+		}
+		this.initPromise = (async () => {
+			try {
+				this.instance = await _duckdb_node_api.DuckDBInstance.create(this.path, this.instanceOptions);
+				this.initialized = true;
+			} catch (error) {
+				this.instance = null;
+				this.initialized = false;
+				this.initPromise = null;
+				throw error;
+			}
+		})();
+		return this.initPromise;
+	}
+	/** Create a new connection to the DuckDB instance, initializing if needed. */
+	async getConnection() {
+		await this.initialize();
+		if (!this.instance) throw new Error("DuckDB instance not initialized");
+		return this.instance.connect();
+	}
+	closeConnection(connection) {
+		const conn = connection;
+		try {
+			if (typeof conn?.closeSync === "function") {
+				conn.closeSync();
+				return;
+			}
+			if (typeof conn?.disconnectSync === "function") {
+				conn.disconnectSync();
+				return;
+			}
+			if (typeof conn?.close === "function") {
+				conn.close();
+				return;
+			}
+			if (typeof conn?.disconnect === "function") conn.disconnect();
+		} catch {}
+	}
+	/**
+	* Execute a SQL query and return results as objects.
+	*/
+	async query(sql, params = []) {
+		const connection = await this.getConnection();
+		try {
+			if (params.length === 0) {
+				const result = await connection.run(sql);
+				const rows = await result.getRows();
+				const columns = result.columnNames();
+				return rows.map((row) => {
+					const obj = {};
+					columns.forEach((col, i) => {
+						obj[col] = toJsValue(row[i]);
+					});
+					return obj;
+				});
+			}
+			let paramIndex = 0;
+			const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
+			const stmt = await connection.prepare(preparedSql);
+			for (let i = 0; i < params.length; i++) bindParam(stmt, i + 1, params[i]);
+			const result = await stmt.run();
+			const rows = await result.getRows();
+			const columns = result.columnNames();
+			return rows.map((row) => {
+				const obj = {};
+				columns.forEach((col, i) => {
+					obj[col] = toJsValue(row[i]);
+				});
+				return obj;
+			});
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Execute a SQL statement without returning results.
+	*/
+	async execute(sql, params = []) {
+		const connection = await this.getConnection();
+		try {
+			if (params.length === 0) {
+				await connection.run(sql);
+				return;
+			}
+			let paramIndex = 0;
+			const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
+			const stmt = await connection.prepare(preparedSql);
+			for (let i = 0; i < params.length; i++) bindParam(stmt, i + 1, params[i]);
+			await stmt.run();
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Execute multiple SQL statements in order using a single DuckDB connection.
+	*
+	* This is intended for schema setup/migrations where statements have no
+	* parameters and must remain ordered, but opening a connection per statement
+	* would dominate initialization cost. Blank statements are skipped. Like
+	* calling execute() repeatedly, this does not wrap statements in a transaction,
+	* so prior statements can remain applied if a later statement fails.
+	*/
+	async executeBatch(sqlStatements) {
+		const statements = sqlStatements.map((statement) => statement.trim()).filter(Boolean);
+		if (statements.length === 0) return;
+		const connection = await this.getConnection();
+		try {
+			const sql = statements.map((statement, i) => `-- executeBatch statement ${i + 1}\n${statement}`).join("\n;\n") + "\n;";
+			await connection.run(sql);
+		} finally {
+			this.closeConnection(connection);
+		}
+	}
+	/**
+	* Escape a value for safe inline SQL use.
+	* DuckDB prepared statements can't handle NULL for parameters typed as ANY,
+	* so for complex INSERT/UPDATE operations we inline values safely.
+	*/
+	static sqlValue(value) {
+		if (value === null || value === void 0) return "NULL";
+		if (typeof value === "number") {
+			if (!Number.isFinite(value)) return "NULL";
+			return String(value);
+		}
+		if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+		if (value instanceof Date) return `'${value.toISOString()}'::TIMESTAMP`;
+		if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+		return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+	}
+	/** Release the DuckDB instance, allowing garbage collection. */
+	async close() {
+		if (this.instance) {
+			try {
+				const instance = this.instance;
+				if (typeof instance.closeSync === "function") instance.closeSync();
+				else if (typeof instance.close === "function") instance.close();
+			} catch {}
+			this.instance = null;
+			this.initialized = false;
+			this.initPromise = null;
+		}
+	}
+};
+//#endregion
+Object.defineProperty(exports, "DuckDBConnection", {
+	enumerable: true,
+	get: function() {
+		return DuckDBConnection;
+	}
+});
+Object.defineProperty(exports, "bindParam", {
+	enumerable: true,
+	get: function() {
+		return bindParam;
+	}
+});
+
+//# sourceMappingURL=db-TBEcMD49.cjs.map

package/dist/db-TBEcMD49.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-TBEcMD49.cjs","names":["DuckDBTimestampValue","DuckDBTimestampTZValue","MastraBase","DuckDBInstance"],"sources":["../src/storage/db/index.ts"],"sourcesContent":["import { DuckDBInstance, DuckDBTimestampValue, DuckDBTimestampTZValue } from '@duckdb/node-api';\nimport type { DuckDBPreparedStatement } from '@duckdb/node-api';\nimport { MastraBase } from '@mastra/core/base';\n\n/**\n * Bind a single parameter to a prepared statement using explicit typed methods.\n * This avoids the \"Cannot create values of type ANY\" error that occurs when\n * DuckDB cannot infer parameter types from SQL context (e.g. json_extract_string).\n */\nexport function bindParam(stmt: DuckDBPreparedStatement, index: number, value: unknown): void {\n  if (value === null || value === undefined) {\n    stmt.bindNull(index);\n  } else if (typeof value === 'string') {\n    stmt.bindVarchar(index, value);\n  } else if (typeof value === 'number') {\n    if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) {\n      stmt.bindInteger(index, value);\n    } else {\n      stmt.bindDouble(index, value);\n    }\n  } else if (typeof value === 'boolean') {\n    stmt.bindBoolean(index, value);\n  } else if (typeof value === 'bigint') {\n    stmt.bindBigInt(index, value);\n  } else if (value instanceof Date) {\n    stmt.bindTimestamp(index, new DuckDBTimestampValue(BigInt(value.getTime()) * 1000n));\n  } else if (value instanceof DuckDBTimestampValue) {\n    stmt.bindTimestamp(index, value);\n  } else if (value instanceof DuckDBTimestampTZValue) {\n    stmt.bindTimestampTZ(index, value);\n  } else {\n    // Fallback: serialize to JSON string\n    stmt.bindVarchar(index, JSON.stringify(value));\n  }\n}\n\n/** Convert DuckDB-specific return types to plain JS types */\nfunction toJsValue(val: unknown): unknown {\n  if (val === null || val === undefined) return val;\n  // DuckDBTimestampValue → Date (micros since epoch)\n  if (val instanceof DuckDBTimestampValue) {\n    return new Date(Number(val.micros / 1000n));\n  }\n  // BigInt → Number (safe for values we care about)\n  if (typeof val === 'bigint') {\n    return Number(val);\n  }\n  return val;\n}\n\n/** Configuration for the DuckDB database connection. */\nexport interface DuckDBStorageConfig {\n  /** Path to the DuckDB file. Defaults to 'mastra.duckdb'. Use ':memory:' for ephemeral. */\n  path?: string;\n  /**\n   * Maximum memory DuckDB may use (e.g. '2GB', '512MB').\n   * @default '2GB'\n   * DuckDB's own default is 80% of system RAM, which is far too aggressive for\n   * a store embedded in an application server — a single query against a large\n   * database can balloon the process by several GB and push the host into\n   * swap. Larger-than-memory operations spill to disk for file-backed\n   * databases. Raise this for dedicated analytical workloads.\n   */\n  memoryLimit?: string;\n  /**\n   * Number of threads DuckDB may use. Defaults to DuckDB's default (one per\n   * CPU core). Lower this to keep queries from monopolizing all cores of a\n   * shared application server.\n   */\n  threads?: number;\n}\n\nconst DEFAULT_MEMORY_LIMIT = '2GB';\n\n/**\n * Shared DuckDB connection management for Mastra storage.\n * Defaults to a local file (`mastra.duckdb`) when no path is provided.\n * Pass `path: ':memory:'` for an ephemeral in-memory database.\n */\nexport class DuckDBConnection extends MastraBase {\n  private instance: DuckDBInstance | null = null;\n  private initialized = false;\n  private initPromise: Promise<void> | null = null;\n  private path: string;\n  private instanceOptions: Record<string, string>;\n\n  constructor(config: DuckDBStorageConfig = {}) {\n    super({ component: 'STORAGE', name: 'DUCKDB' });\n    this.path = config.path ?? 'mastra.duckdb';\n    this.instanceOptions = {\n      max_memory: config.memoryLimit ?? DEFAULT_MEMORY_LIMIT,\n      ...(config.threads !== undefined ? { threads: String(config.threads) } : {}),\n    };\n  }\n\n  private async initialize(): Promise<void> {\n    if (this.initialized && this.instance) return;\n\n    if (this.initPromise) {\n      await this.initPromise;\n      if (this.instance) return;\n      this.initPromise = null;\n      this.initialized = false;\n    }\n\n    this.initPromise = (async () => {\n      try {\n        this.instance = await DuckDBInstance.create(this.path, this.instanceOptions);\n        this.initialized = true;\n      } catch (error) {\n        this.instance = null;\n        this.initialized = false;\n        this.initPromise = null;\n        throw error;\n      }\n    })();\n\n    return this.initPromise;\n  }\n\n  /** Create a new connection to the DuckDB instance, initializing if needed. */\n  async getConnection() {\n    await this.initialize();\n    if (!this.instance) {\n      throw new Error('DuckDB instance not initialized');\n    }\n    return this.instance.connect();\n  }\n\n  private closeConnection(connection: unknown): void {\n    const conn = connection as {\n      closeSync?: () => void;\n      disconnectSync?: () => void;\n      close?: () => void;\n      disconnect?: () => void;\n    };\n    try {\n      if (typeof conn?.closeSync === 'function') {\n        conn.closeSync();\n        return;\n      }\n      if (typeof conn?.disconnectSync === 'function') {\n        conn.disconnectSync();\n        return;\n      }\n      if (typeof conn?.close === 'function') {\n        conn.close();\n        return;\n      }\n      if (typeof conn?.disconnect === 'function') {\n        conn.disconnect();\n      }\n    } catch {\n      // Ignore close failures to avoid masking query/execute errors.\n    }\n  }\n\n  /**\n   * Execute a SQL query and return results as objects.\n   */\n  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {\n    const connection = await this.getConnection();\n    try {\n      if (params.length === 0) {\n        const result = await connection.run(sql);\n        const rows = await result.getRows();\n        const columns = result.columnNames();\n        return rows.map(row => {\n          const obj: Record<string, unknown> = {};\n          columns.forEach((col, i) => {\n            obj[col] = toJsValue(row[i]);\n          });\n          return obj as T;\n        });\n      }\n\n      let paramIndex = 0;\n      const preparedSql = sql.replace(/\\?/g, () => `$${++paramIndex}`);\n      const stmt = await connection.prepare(preparedSql);\n      for (let i = 0; i < params.length; i++) {\n        bindParam(stmt, i + 1, params[i]);\n      }\n      const result = await stmt.run();\n      const rows = await result.getRows();\n      const columns = result.columnNames();\n      return rows.map(row => {\n        const obj: Record<string, unknown> = {};\n        columns.forEach((col, i) => {\n          obj[col] = toJsValue(row[i]);\n        });\n        return obj as T;\n      });\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Execute a SQL statement without returning results.\n   */\n  async execute(sql: string, params: unknown[] = []): Promise<void> {\n    const connection = await this.getConnection();\n    try {\n      if (params.length === 0) {\n        await connection.run(sql);\n        return;\n      }\n      let paramIndex = 0;\n      const preparedSql = sql.replace(/\\?/g, () => `$${++paramIndex}`);\n      const stmt = await connection.prepare(preparedSql);\n      for (let i = 0; i < params.length; i++) {\n        bindParam(stmt, i + 1, params[i]);\n      }\n      await stmt.run();\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Execute multiple SQL statements in order using a single DuckDB connection.\n   *\n   * This is intended for schema setup/migrations where statements have no\n   * parameters and must remain ordered, but opening a connection per statement\n   * would dominate initialization cost. Blank statements are skipped. Like\n   * calling execute() repeatedly, this does not wrap statements in a transaction,\n   * so prior statements can remain applied if a later statement fails.\n   */\n  async executeBatch(sqlStatements: readonly string[]): Promise<void> {\n    const statements = sqlStatements.map(statement => statement.trim()).filter(Boolean);\n    if (statements.length === 0) return;\n\n    const connection = await this.getConnection();\n    try {\n      const sql =\n        statements.map((statement, i) => `-- executeBatch statement ${i + 1}\\n${statement}`).join('\\n;\\n') + '\\n;';\n      await connection.run(sql);\n    } finally {\n      this.closeConnection(connection);\n    }\n  }\n\n  /**\n   * Escape a value for safe inline SQL use.\n   * DuckDB prepared statements can't handle NULL for parameters typed as ANY,\n   * so for complex INSERT/UPDATE operations we inline values safely.\n   */\n  static sqlValue(value: unknown): string {\n    if (value === null || value === undefined) return 'NULL';\n    if (typeof value === 'number') {\n      if (!Number.isFinite(value)) return 'NULL';\n      return String(value);\n    }\n    if (typeof value === 'boolean') return value ? 'TRUE' : 'FALSE';\n    if (value instanceof Date) return `'${value.toISOString()}'::TIMESTAMP`;\n    if (typeof value === 'string') return `'${value.replace(/'/g, \"''\")}'`;\n    // Objects/arrays → JSON string\n    return `'${JSON.stringify(value).replace(/'/g, \"''\")}'`;\n  }\n\n  /** Release the DuckDB instance, allowing garbage collection. */\n  async close(): Promise<void> {\n    if (this.instance) {\n      try {\n        const instance = this.instance as unknown as { closeSync?: () => void; close?: () => void };\n        if (typeof instance.closeSync === 'function') {\n          instance.closeSync();\n        } else if (typeof instance.close === 'function') {\n          instance.close();\n        }\n      } catch {\n        // Ignore close failures to allow cleanup of references.\n      }\n      this.instance = null;\n      this.initialized = false;\n      this.initPromise = null;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-duckdb
 description: Documentation for @mastra/duckdb. Use when working with @mastra/duckdb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/duckdb"
-  version: "1.5.1"
+  version: "1.5.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,12 +1,6 @@
 {
-  "version": "1.5.1",
+  "version": "1.5.2",
   "package": "@mastra/duckdb",
-  "exports": {
-    "DuckDBConnection": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-4LIZE4MC.js",
-      "line": 40
-    }
-  },
+  "exports": {},
   "modules": {}
 }

package/dist/docs/references/reference-storage-duckdb.md

@@ -110,6 +110,10 @@ const duckdb = new DuckDBStore({ path: ':memory:' })
 
 **path** (`string`): Path to the DuckDB database file. Use :memory: for an ephemeral in-memory database. (Default: `'mastra.duckdb'`)
 
+**memoryLimit** (`string`): Maximum memory DuckDB may use, such as '2GB' or '512MB'. Larger-than-memory operations spill to disk for file-backed databases. Raise this for dedicated analytical workloads. (Default: `'2GB'`)
+
+**threads** (`number`): Number of threads DuckDB may use. Lower this to keep queries from monopolizing all cores of a shared application server. (Default: `one per CPU core`)
+
 ### Lower-level types
 
 `@mastra/duckdb` also exports `DuckDBConnection` for sharing a single underlying database across multiple Mastra storage instances, and the corresponding `DuckDBStorageConfig` type. Most applications won't need these directly.