@mastra/duckdb 1.3.0-alpha.1 → 1.3.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @mastra/duckdb
 
+## 1.3.1-alpha.0
+
+### Patch Changes
+
+- Improved DuckDB observability initialization by batching schema setup statements on one connection while preserving migration order. ([#16239](https://github.com/mastra-ai/mastra/pull/16239))
+
+## 1.3.0
+
+### Minor Changes
+
+- - **Added** `listBranches` and `getSpans` implementations. ([#16154](https://github.com/mastra-ai/mastra/pull/16154))
+  - Historical span data is queryable immediately; no migration required.
+
+- Added `count_distinct` aggregation and server-side TopK to the metrics storage API so dashboards built on high-cardinality fields (like `threadId` or `resourceId`) stay fast and bounded. ([#16137](https://github.com/mastra-ai/mastra/pull/16137))
+
+  **New aggregation**
+
+  `getMetricAggregate`, `getMetricBreakdown`, and `getMetricTimeSeries` accept `aggregation: 'count_distinct'` with a `distinctColumn`. Backends pick the most efficient native implementation — `uniq` on ClickHouse, `approx_count_distinct` on DuckDB.
+
+  `distinctColumn` is restricted to a low/medium-cardinality categorical allowlist (`entityType`, `entityName`, `parentEntityType`, `parentEntityName`, `rootEntityType`, `rootEntityName`, `name`, `provider`, `model`, `environment`, `executionSource`, `serviceName`). ID columns are not allowed — distinct counts over near-unique values converge to the row count and are rarely useful.
+
+  ```ts
+  await store.getMetricAggregate({
+    name: ['mastra_llm_tokens_total'],
+    aggregation: 'count_distinct',
+    distinctColumn: 'model',
+    filters: { timestamp: { start, end } },
+  });
+  ```
+
+  **Server-side TopK**
+
+  `getMetricBreakdown` accepts `limit` and `orderDirection`, so breakdowns never return the full cardinality of a column from the database. Ordering is always by the aggregated `value`; `orderDirection` flips between top-N (`DESC`, default) and bottom-N (`ASC`).
+
+  ```ts
+  await store.getMetricBreakdown({
+    name: ['mastra_agent_duration_ms'],
+    aggregation: 'sum',
+    groupBy: ['threadId'],
+    limit: 20,
+    orderDirection: 'DESC',
+  });
+  ```
+
+### Patch Changes
+
+- Improved performance of `listTraces` and `listBranches` on DuckDB. The Traces and Branches lists in the observability UI now load noticeably faster, especially on large span tables, because filtering and pagination happen up front and the store only assembles full span data for the rows on the page being viewed. ([#16165](https://github.com/mastra-ai/mastra/pull/16165))
+
+  No API or behavior changes — return shapes and filter semantics are unchanged, and no migration is required.
+
+- Added direct score lookup support to observability storage so score records can be fetched by `scoreId` without scanning paginated score lists, including DuckDB and ClickHouse vNext observability stores. ([#16162](https://github.com/mastra-ai/mastra/pull/16162))
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`1d64a76`](https://github.com/mastra-ai/mastra/commit/1d64a765861a0772ea187bab76e5ed37bf82d042), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`a0d9b6d`](https://github.com/mastra-ai/mastra/commit/a0d9b6d6b810aeaa9e177a0dcc99a4402e609634), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`b0c7022`](https://github.com/mastra-ai/mastra/commit/b0c70224f80dad7c0cdbfb22cbff22e0f75c064f), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
+  - @mastra/core@1.32.0
+
 ## 1.3.0-alpha.1
 
 ### Patch Changes

package/dist/{chunk-37GBWD4M.js → chunk-4LIZE4MC.js}

@@ -155,6 +155,27 @@ var DuckDBConnection = class extends MastraBase {
       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}
+${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,
@@ -191,5 +212,5 @@ var DuckDBConnection = class extends MastraBase {
 };
 
 export { DuckDBConnection, bindParam };
-//# sourceMappingURL=chunk-37GBWD4M.js.map
-//# sourceMappingURL=chunk-37GBWD4M.js.map
+//# sourceMappingURL=chunk-4LIZE4MC.js.map
+//# sourceMappingURL=chunk-4LIZE4MC.js.map

package/dist/chunk-4LIZE4MC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/db/index.ts"],"names":["result","rows","columns"],"mappings":"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","file":"chunk-4LIZE4MC.js","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\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\n  constructor(config: DuckDBStorageConfig = {}) {\n    super({ component: 'STORAGE', name: 'DUCKDB' });\n    this.path = config.path ?? 'mastra.duckdb';\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);\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"]}

package/dist/{chunk-S2AWBPTS.cjs → chunk-SMRZJTCI.cjs}

@@ -157,6 +157,27 @@ var DuckDBConnection = class extends base.MastraBase {
       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}
+${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,
@@ -194,5 +215,5 @@ var DuckDBConnection = class extends base.MastraBase {
 
 exports.DuckDBConnection = DuckDBConnection;
 exports.bindParam = bindParam;
-//# sourceMappingURL=chunk-S2AWBPTS.cjs.map
-//# sourceMappingURL=chunk-S2AWBPTS.cjs.map
+//# sourceMappingURL=chunk-SMRZJTCI.cjs.map
+//# sourceMappingURL=chunk-SMRZJTCI.cjs.map

package/dist/chunk-SMRZJTCI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/db/index.ts"],"names":["DuckDBTimestampValue","DuckDBTimestampTZValue","MastraBase","DuckDBInstance","result","rows","columns"],"mappings":"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","file":"chunk-SMRZJTCI.cjs","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\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\n  constructor(config: DuckDBStorageConfig = {}) {\n    super({ component: 'STORAGE', name: 'DUCKDB' });\n    this.path = config.path ?? 'mastra.duckdb';\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);\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"]}

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.3.0-alpha.1"
+  version: "1.3.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,10 +1,10 @@
 {
-  "version": "1.3.0-alpha.1",
+  "version": "1.3.1-alpha.0",
   "package": "@mastra/duckdb",
   "exports": {
     "DuckDBConnection": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-37GBWD4M.js",
+      "implementation": "dist/chunk-4LIZE4MC.js",
       "line": 40
     }
   },

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkS2AWBPTS_cjs = require('./chunk-S2AWBPTS.cjs');
+var chunkSMRZJTCI_cjs = require('./chunk-SMRZJTCI.cjs');
 var nodeApi = require('@duckdb/node-api');
 var error = require('@mastra/core/error');
 var storage = require('@mastra/core/storage');
@@ -253,7 +253,7 @@ var DuckDBVector = class extends vector.MastraVector {
       const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
       const stmt = await connection.prepare(preparedSql);
       for (let i = 0; i < params.length; i++) {
-        chunkS2AWBPTS_cjs.bindParam(stmt, i + 1, params[i]);
+        chunkSMRZJTCI_cjs.bindParam(stmt, i + 1, params[i]);
       }
       const result = await stmt.run();
       const rows = await result.getRows();
@@ -281,7 +281,7 @@ var DuckDBVector = class extends vector.MastraVector {
         const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
         const stmt = await connection.prepare(preparedSql);
         for (let i = 0; i < params.length; i++) {
-          chunkS2AWBPTS_cjs.bindParam(stmt, i + 1, params[i]);
+          chunkSMRZJTCI_cjs.bindParam(stmt, i + 1, params[i]);
         }
         await stmt.run();
       }
@@ -583,7 +583,7 @@ var ObservabilityStorageDuckDB = class extends storage.ObservabilityStorage {
       return null;
     }
     if (!this.loadPromise) {
-      this.loadPromise = import('./observability-2PJ44OVC.cjs').then(({ ObservabilityStorageDuckDB: ObservabilityStorageDuckDB2 }) => {
+      this.loadPromise = import('./observability-ZLFGMOSM.cjs').then(({ ObservabilityStorageDuckDB: ObservabilityStorageDuckDB2 }) => {
         const delegate = new ObservabilityStorageDuckDB2({ db: this.db });
         this.delegate = delegate;
         return delegate;
@@ -808,7 +808,7 @@ var DuckDBStore = class extends storage.MastraCompositeStore {
   constructor(config = {}) {
     const id = config.id ?? "duckdb";
     super({ id, name: "DuckDBStore" });
-    this.db = new chunkS2AWBPTS_cjs.DuckDBConnection({ path: config.path });
+    this.db = new chunkSMRZJTCI_cjs.DuckDBConnection({ path: config.path });
     this.observabilityStore = new ObservabilityStorageDuckDB({ db: this.db });
     this.stores = {
       observability: this.observabilityStore
@@ -822,7 +822,7 @@ var DuckDBStore = class extends storage.MastraCompositeStore {
 
 Object.defineProperty(exports, "DuckDBConnection", {
   enumerable: true,
-  get: function () { return chunkS2AWBPTS_cjs.DuckDBConnection; }
+  get: function () { return chunkSMRZJTCI_cjs.DuckDBConnection; }
 });
 exports.DuckDBStore = DuckDBStore;
 exports.DuckDBVector = DuckDBVector;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { bindParam, DuckDBConnection } from './chunk-37GBWD4M.js';
-export { DuckDBConnection } from './chunk-37GBWD4M.js';
+import { bindParam, DuckDBConnection } from './chunk-4LIZE4MC.js';
+export { DuckDBConnection } from './chunk-4LIZE4MC.js';
 import { DuckDBInstance } from '@duckdb/node-api';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import { createVectorErrorId, ObservabilityStorage, MastraCompositeStore } from '@mastra/core/storage';
@@ -582,7 +582,7 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
       return null;
     }
     if (!this.loadPromise) {
-      this.loadPromise = import('./observability-7LL4LLXY.js').then(({ ObservabilityStorageDuckDB: ObservabilityStorageDuckDB2 }) => {
+      this.loadPromise = import('./observability-MKVTGAKX.js').then(({ ObservabilityStorageDuckDB: ObservabilityStorageDuckDB2 }) => {
         const delegate = new ObservabilityStorageDuckDB2({ db: this.db });
         this.delegate = delegate;
         return delegate;

package/dist/{observability-7LL4LLXY.js → observability-MKVTGAKX.js}

@@ -1,4 +1,4 @@
-import { DuckDBConnection } from './chunk-37GBWD4M.js';
+import { DuckDBConnection } from './chunk-4LIZE4MC.js';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import { BRANCH_SPAN_TYPES, ObservabilityStorage, createStorageErrorId, toTraceSpans, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
 import { EntityType } from '@mastra/core/observability';
@@ -2949,12 +2949,7 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
         })
       });
     }
-    for (const ddl of ALL_DDL) {
-      await this.db.execute(ddl);
-    }
-    for (const migration of ALL_MIGRATIONS) {
-      await this.db.execute(migration);
-    }
+    await this.db.executeBatch([...ALL_DDL, ...ALL_MIGRATIONS]);
   }
   /**
    * Manually migrate legacy signal tables to the signal-ID primary-key schema.
@@ -3124,5 +3119,5 @@ var ObservabilityStorageDuckDB = class extends ObservabilityStorage {
 };
 
 export { ObservabilityStorageDuckDB };
-//# sourceMappingURL=observability-7LL4LLXY.js.map
-//# sourceMappingURL=observability-7LL4LLXY.js.map
+//# sourceMappingURL=observability-MKVTGAKX.js.map
+//# sourceMappingURL=observability-MKVTGAKX.js.map