@mastra/pg 1.0.0-beta.9 → 1.0.0

package/dist/index.cjs

@@ -8,7 +8,6 @@ var asyncMutex = require('async-mutex');
 var pg = require('pg');
 var xxhash = require('xxhash-wasm');
 var filter = require('@mastra/core/vector/filter');
-var pgPromise = require('pg-promise');
 var base = require('@mastra/core/base');
 var agent = require('@mastra/core/agent');
 var evals = require('@mastra/core/evals');
@@ -35,13 +34,15 @@ function _interopNamespace(e) {
 
 var pg__namespace = /*#__PURE__*/_interopNamespace(pg);
 var xxhash__default = /*#__PURE__*/_interopDefault(xxhash);
-var pgPromise__default = /*#__PURE__*/_interopDefault(pgPromise);
 
 // src/vector/index.ts
 
 // src/shared/config.ts
+var isPoolConfig = (cfg) => {
+  return "pool" in cfg;
+};
 var isConnectionStringConfig = (cfg) => {
-  return "connectionString" in cfg;
+  return "connectionString" in cfg && typeof cfg.connectionString === "string";
 };
 var isHostConfig = (cfg) => {
   return "host" in cfg && "database" in cfg && "user" in cfg && "password" in cfg;
@@ -49,16 +50,13 @@ var isHostConfig = (cfg) => {
 var isCloudSqlConfig = (cfg) => {
   return "stream" in cfg || "password" in cfg && typeof cfg.password === "function";
 };
-var isClientConfig = (cfg) => {
-  return "client" in cfg;
-};
 var validateConfig = (name, config) => {
   if (!config.id || typeof config.id !== "string" || config.id.trim() === "") {
     throw new Error(`${name}: id must be provided and cannot be empty.`);
   }
-  if (isClientConfig(config)) {
-    if (!config.client) {
-      throw new Error(`${name}: client must be provided when using client config.`);
+  if (isPoolConfig(config)) {
+    if (!config.pool) {
+      throw new Error(`${name}: pool must be provided when using pool config.`);
     }
     return;
   }
@@ -79,7 +77,7 @@ var validateConfig = (name, config) => {
     }
   } else {
     throw new Error(
-      `${name}: invalid config. Provide either {client}, {connectionString}, {host,port,database,user,password}, or a pg ClientConfig (e.g., Cloud SQL connector with \`stream\`).`
+      `${name}: invalid config. Provide either {pool}, {connectionString}, {host,port,database,user,password}, or a pg ClientConfig (e.g., Cloud SQL connector with \`stream\`).`
     );
   }
 };
@@ -287,8 +285,14 @@ var FILTER_OPERATORS = {
     };
   },
   // Element Operators
-  $exists: (key) => {
+  $exists: (key, paramIndex, value) => {
     const jsonPathKey = parseJsonPathKey(key);
+    if (value === false) {
+      return {
+        sql: `NOT (metadata ? '${jsonPathKey}')`,
+        needsValue: false
+      };
+    }
     return {
       sql: `metadata ? '${jsonPathKey}'`,
       needsValue: false
@@ -366,17 +370,62 @@ function buildDeleteFilterQuery(filter) {
       values.push(value);
       return `metadata#>>'{${parseJsonPathKey(key)}}' = $${values.length}`;
     }
-    const [[operator, operatorValue] = []] = Object.entries(value);
+    const entries = Object.entries(value);
+    if (entries.length > 1) {
+      const conditions2 = entries.map(([operator2, operatorValue2]) => {
+        if (operator2 === "$not") {
+          const nestedEntries = Object.entries(operatorValue2);
+          const nestedConditions = nestedEntries.map(([nestedOp, nestedValue]) => {
+            if (!FILTER_OPERATORS[nestedOp]) {
+              throw new Error(`Invalid operator in $not condition: ${nestedOp}`);
+            }
+            const operatorFn3 = FILTER_OPERATORS[nestedOp];
+            const operatorResult3 = operatorFn3(key, values.length + 1, nestedValue);
+            if (operatorResult3.needsValue) {
+              const transformedValue = operatorResult3.transformValue ? operatorResult3.transformValue() : nestedValue;
+              if (Array.isArray(transformedValue) && nestedOp === "$elemMatch") {
+                values.push(...transformedValue);
+              } else {
+                values.push(transformedValue);
+              }
+            }
+            return operatorResult3.sql;
+          }).join(" AND ");
+          return `NOT (${nestedConditions})`;
+        }
+        if (!FILTER_OPERATORS[operator2]) {
+          throw new Error(`Invalid operator: ${operator2}`);
+        }
+        const operatorFn2 = FILTER_OPERATORS[operator2];
+        const operatorResult2 = operatorFn2(key, values.length + 1, operatorValue2);
+        if (operatorResult2.needsValue) {
+          const transformedValue = operatorResult2.transformValue ? operatorResult2.transformValue() : operatorValue2;
+          if (Array.isArray(transformedValue) && operator2 === "$elemMatch") {
+            values.push(...transformedValue);
+          } else {
+            values.push(transformedValue);
+          }
+        }
+        return operatorResult2.sql;
+      });
+      return conditions2.join(" AND ");
+    }
+    const [[operator, operatorValue] = []] = entries;
     if (operator === "$not") {
-      const entries = Object.entries(operatorValue);
-      const conditions2 = entries.map(([nestedOp, nestedValue]) => {
+      const nestedEntries = Object.entries(operatorValue);
+      const conditions2 = nestedEntries.map(([nestedOp, nestedValue]) => {
         if (!FILTER_OPERATORS[nestedOp]) {
           throw new Error(`Invalid operator in $not condition: ${nestedOp}`);
         }
         const operatorFn2 = FILTER_OPERATORS[nestedOp];
         const operatorResult2 = operatorFn2(key, values.length + 1, nestedValue);
         if (operatorResult2.needsValue) {
-          values.push(nestedValue);
+          const transformedValue = operatorResult2.transformValue ? operatorResult2.transformValue() : nestedValue;
+          if (Array.isArray(transformedValue) && nestedOp === "$elemMatch") {
+            values.push(...transformedValue);
+          } else {
+            values.push(transformedValue);
+          }
         }
         return operatorResult2.sql;
       }).join(" AND ");
@@ -443,17 +492,62 @@ function buildFilterQuery(filter, minScore, topK) {
       values.push(value);
       return `metadata#>>'{${parseJsonPathKey(key)}}' = $${values.length}`;
     }
-    const [[operator, operatorValue] = []] = Object.entries(value);
+    const entries = Object.entries(value);
+    if (entries.length > 1) {
+      const conditions2 = entries.map(([operator2, operatorValue2]) => {
+        if (operator2 === "$not") {
+          const nestedEntries = Object.entries(operatorValue2);
+          const nestedConditions = nestedEntries.map(([nestedOp, nestedValue]) => {
+            if (!FILTER_OPERATORS[nestedOp]) {
+              throw new Error(`Invalid operator in $not condition: ${nestedOp}`);
+            }
+            const operatorFn3 = FILTER_OPERATORS[nestedOp];
+            const operatorResult3 = operatorFn3(key, values.length + 1, nestedValue);
+            if (operatorResult3.needsValue) {
+              const transformedValue = operatorResult3.transformValue ? operatorResult3.transformValue() : nestedValue;
+              if (Array.isArray(transformedValue) && nestedOp === "$elemMatch") {
+                values.push(...transformedValue);
+              } else {
+                values.push(transformedValue);
+              }
+            }
+            return operatorResult3.sql;
+          }).join(" AND ");
+          return `NOT (${nestedConditions})`;
+        }
+        if (!FILTER_OPERATORS[operator2]) {
+          throw new Error(`Invalid operator: ${operator2}`);
+        }
+        const operatorFn2 = FILTER_OPERATORS[operator2];
+        const operatorResult2 = operatorFn2(key, values.length + 1, operatorValue2);
+        if (operatorResult2.needsValue) {
+          const transformedValue = operatorResult2.transformValue ? operatorResult2.transformValue() : operatorValue2;
+          if (Array.isArray(transformedValue) && operator2 === "$elemMatch") {
+            values.push(...transformedValue);
+          } else {
+            values.push(transformedValue);
+          }
+        }
+        return operatorResult2.sql;
+      });
+      return conditions2.join(" AND ");
+    }
+    const [[operator, operatorValue] = []] = entries;
     if (operator === "$not") {
-      const entries = Object.entries(operatorValue);
-      const conditions2 = entries.map(([nestedOp, nestedValue]) => {
+      const nestedEntries = Object.entries(operatorValue);
+      const conditions2 = nestedEntries.map(([nestedOp, nestedValue]) => {
         if (!FILTER_OPERATORS[nestedOp]) {
           throw new Error(`Invalid operator in $not condition: ${nestedOp}`);
         }
         const operatorFn2 = FILTER_OPERATORS[nestedOp];
         const operatorResult2 = operatorFn2(key, values.length + 1, nestedValue);
         if (operatorResult2.needsValue) {
-          values.push(nestedValue);
+          const transformedValue = operatorResult2.transformValue ? operatorResult2.transformValue() : nestedValue;
+          if (Array.isArray(transformedValue) && nestedOp === "$elemMatch") {
+            values.push(...transformedValue);
+          } else {
+            values.push(transformedValue);
+          }
         }
         return operatorResult2.sql;
       }).join(" AND ");
@@ -544,8 +638,8 @@ var PgVector = class extends vector.MastraVector {
       } else if (isCloudSqlConfig(config)) {
         poolConfig = {
           ...config,
-          max: config.max ?? 20,
-          idleTimeoutMillis: config.idleTimeoutMillis ?? 3e4,
+          max: config.pgPoolOptions?.max ?? 20,
+          idleTimeoutMillis: config.pgPoolOptions?.idleTimeoutMillis ?? 3e4,
           connectionTimeoutMillis: 2e3,
           ...config.pgPoolOptions
         };
@@ -713,9 +807,7 @@ var PgVector = class extends vector.MastraVector {
     probes
   }) {
     try {
-      if (!Number.isInteger(topK) || topK <= 0) {
-        throw new Error("topK must be a positive integer");
-      }
+      vector.validateTopK("PG", topK);
       if (!Array.isArray(queryVector) || !queryVector.every((x) => typeof x === "number" && Number.isFinite(x))) {
         throw new Error("queryVector must be an array of finite numbers");
       }
@@ -800,6 +892,7 @@ var PgVector = class extends vector.MastraVector {
     ids,
     deleteFilter
   }) {
+    vector.validateUpsertInput("PG", vectors, metadata, ids);
     const { tableName } = this.getTableName(indexName);
     const client = await this.pool.connect();
     try {
@@ -1687,6 +1780,132 @@ var PgVector = class extends vector.MastraVector {
     }
   }
 };
+
+// src/storage/client.ts
+function truncateQuery(query, maxLength = 100) {
+  const normalized = query.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return normalized.slice(0, maxLength) + "...";
+}
+var PoolAdapter = class {
+  constructor($pool) {
+    this.$pool = $pool;
+  }
+  connect() {
+    return this.$pool.connect();
+  }
+  async none(query, values) {
+    await this.$pool.query(query, values);
+    return null;
+  }
+  async one(query, values) {
+    const result = await this.$pool.query(query, values);
+    if (result.rows.length === 0) {
+      throw new Error(`No data returned from query: ${truncateQuery(query)}`);
+    }
+    if (result.rows.length > 1) {
+      throw new Error(`Multiple rows returned when one was expected: ${truncateQuery(query)}`);
+    }
+    return result.rows[0];
+  }
+  async oneOrNone(query, values) {
+    const result = await this.$pool.query(query, values);
+    if (result.rows.length === 0) {
+      return null;
+    }
+    if (result.rows.length > 1) {
+      throw new Error(`Multiple rows returned when one or none was expected: ${truncateQuery(query)}`);
+    }
+    return result.rows[0];
+  }
+  async any(query, values) {
+    const result = await this.$pool.query(query, values);
+    return result.rows;
+  }
+  async manyOrNone(query, values) {
+    return this.any(query, values);
+  }
+  async many(query, values) {
+    const result = await this.$pool.query(query, values);
+    if (result.rows.length === 0) {
+      throw new Error(`No data returned from query: ${truncateQuery(query)}`);
+    }
+    return result.rows;
+  }
+  async query(query, values) {
+    return this.$pool.query(query, values);
+  }
+  async tx(callback) {
+    const client = await this.$pool.connect();
+    try {
+      await client.query("BEGIN");
+      const txClient = new TransactionClient(client);
+      const result = await callback(txClient);
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      try {
+        await client.query("ROLLBACK");
+      } catch (rollbackError) {
+        console.error("Transaction rollback failed:", rollbackError);
+      }
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+};
+var TransactionClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async none(query, values) {
+    await this.client.query(query, values);
+    return null;
+  }
+  async one(query, values) {
+    const result = await this.client.query(query, values);
+    if (result.rows.length === 0) {
+      throw new Error(`No data returned from query: ${truncateQuery(query)}`);
+    }
+    if (result.rows.length > 1) {
+      throw new Error(`Multiple rows returned when one was expected: ${truncateQuery(query)}`);
+    }
+    return result.rows[0];
+  }
+  async oneOrNone(query, values) {
+    const result = await this.client.query(query, values);
+    if (result.rows.length === 0) {
+      return null;
+    }
+    if (result.rows.length > 1) {
+      throw new Error(`Multiple rows returned when one or none was expected: ${truncateQuery(query)}`);
+    }
+    return result.rows[0];
+  }
+  async any(query, values) {
+    const result = await this.client.query(query, values);
+    return result.rows;
+  }
+  async manyOrNone(query, values) {
+    return this.any(query, values);
+  }
+  async many(query, values) {
+    const result = await this.client.query(query, values);
+    if (result.rows.length === 0) {
+      throw new Error(`No data returned from query: ${truncateQuery(query)}`);
+    }
+    return result.rows;
+  }
+  async query(query, values) {
+    return this.client.query(query, values);
+  }
+  async batch(promises) {
+    return Promise.all(promises);
+  }
+};
 function resolvePgConfig(config) {
   if ("client" in config) {
     return {
@@ -1696,10 +1915,32 @@ function resolvePgConfig(config) {
       indexes: config.indexes
     };
   }
-  const pgp = pgPromise__default.default();
-  const client = pgp(config);
+  if ("pool" in config) {
+    return {
+      client: new PoolAdapter(config.pool),
+      schemaName: config.schemaName,
+      skipDefaultIndexes: config.skipDefaultIndexes,
+      indexes: config.indexes
+    };
+  }
+  let pool;
+  if ("connectionString" in config) {
+    pool = new pg.Pool({
+      connectionString: config.connectionString,
+      ssl: config.ssl
+    });
+  } else {
+    pool = new pg.Pool({
+      host: config.host,
+      port: config.port,
+      database: config.database,
+      user: config.user,
+      password: config.password,
+      ssl: config.ssl
+    });
+  }
   return {
-    client,
+    client: new PoolAdapter(pool),
     schemaName: config.schemaName,
     skipDefaultIndexes: config.skipDefaultIndexes,
     indexes: config.indexes
@@ -1714,6 +1955,91 @@ function getTableName({ indexName, schemaName }) {
   const quotedSchemaName = schemaName;
   return quotedSchemaName ? `${quotedSchemaName}.${quotedIndexName}` : quotedIndexName;
 }
+function mapToSqlType(type) {
+  switch (type) {
+    case "uuid":
+      return "UUID";
+    case "boolean":
+      return "BOOLEAN";
+    default:
+      return storage.getSqlType(type);
+  }
+}
+function generateTableSQL({
+  tableName,
+  schema,
+  schemaName,
+  includeAllConstraints = false
+}) {
+  const timeZColumns = Object.entries(schema).filter(([_, def]) => def.type === "timestamp").map(([name]) => {
+    const parsedName = utils.parseSqlIdentifier(name, "column name");
+    return `"${parsedName}Z" TIMESTAMPTZ DEFAULT NOW()`;
+  });
+  const columns = Object.entries(schema).map(([name, def]) => {
+    const parsedName = utils.parseSqlIdentifier(name, "column name");
+    const constraints = [];
+    if (def.primaryKey) constraints.push("PRIMARY KEY");
+    if (!def.nullable) constraints.push("NOT NULL");
+    return `"${parsedName}" ${mapToSqlType(def.type)} ${constraints.join(" ")}`;
+  });
+  const finalColumns = [...columns, ...timeZColumns].join(",\n");
+  const parsedSchemaName = schemaName ? utils.parseSqlIdentifier(schemaName, "schema name") : "";
+  const constraintPrefix = parsedSchemaName ? `${parsedSchemaName}_` : "";
+  const quotedSchemaName = getSchemaName(schemaName);
+  const sql = `
+            CREATE TABLE IF NOT EXISTS ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })} (
+              ${finalColumns}
+            );
+            ${tableName === storage.TABLE_WORKFLOW_SNAPSHOT ? `
+            DO $$ BEGIN
+              IF NOT EXISTS (
+                SELECT 1 FROM pg_constraint WHERE conname = lower('${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key')
+              ) AND NOT EXISTS (
+                SELECT 1 FROM pg_indexes WHERE indexname = lower('${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key')
+              ) THEN
+                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })}
+                ADD CONSTRAINT ${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key
+                UNIQUE (workflow_name, run_id);
+              END IF;
+            END $$;
+            ` : ""}
+          ${// For spans table: Include PRIMARY KEY in exports, but not in runtime (handled after deduplication)
+  tableName === storage.TABLE_SPANS && includeAllConstraints ? `
+            DO $$ BEGIN
+              IF NOT EXISTS (
+                SELECT 1 FROM pg_constraint WHERE conname = lower('${constraintPrefix}mastra_ai_spans_traceid_spanid_pk')
+              ) THEN
+                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })}
+                ADD CONSTRAINT ${constraintPrefix}mastra_ai_spans_traceid_spanid_pk
+                PRIMARY KEY ("traceId", "spanId");
+              END IF;
+            END $$;
+            ` : ""}
+          `;
+  return sql;
+}
+function exportSchemas(schemaName) {
+  const statements = [];
+  if (schemaName) {
+    const quotedSchemaName = getSchemaName(schemaName);
+    statements.push(`-- Create schema if it doesn't exist`);
+    statements.push(`CREATE SCHEMA IF NOT EXISTS ${quotedSchemaName};`);
+    statements.push("");
+  }
+  for (const [tableName, schema] of Object.entries(storage.TABLE_SCHEMAS)) {
+    statements.push(`-- Table: ${tableName}`);
+    const sql = generateTableSQL({
+      tableName,
+      schema,
+      schemaName,
+      includeAllConstraints: true
+      // Include all constraints for exports/documentation
+    });
+    statements.push(sql.trim());
+    statements.push("");
+  }
+  return statements.join("\n");
+}
 var schemaSetupRegistry = /* @__PURE__ */ new Map();
 var PgDB = class extends base.MastraBase {
   client;
@@ -1831,16 +2157,6 @@ var PgDB = class extends base.MastraBase {
     }
     await registryEntry.promise;
   }
-  getSqlType(type) {
-    switch (type) {
-      case "uuid":
-        return "UUID";
-      case "boolean":
-        return "BOOLEAN";
-      default:
-        return storage.getSqlType(type);
-    }
-  }
   getDefaultValue(type) {
     switch (type) {
       case "timestamp":
@@ -1858,10 +2174,27 @@ var PgDB = class extends base.MastraBase {
       const columns = Object.keys(record).map((col) => utils.parseSqlIdentifier(col, "column name"));
       const values = this.prepareValuesForInsert(record, tableName);
       const placeholders = values.map((_, i) => `$${i + 1}`).join(", ");
-      await this.client.none(
-        `INSERT INTO ${getTableName({ indexName: tableName, schemaName })} (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})`,
-        values
-      );
+      const fullTableName = getTableName({ indexName: tableName, schemaName });
+      const columnList = columns.map((c) => `"${c}"`).join(", ");
+      if (tableName === storage.TABLE_SPANS) {
+        const updateColumns = columns.filter((c) => c !== "traceId" && c !== "spanId");
+        if (updateColumns.length > 0) {
+          const updateClause = updateColumns.map((c) => `"${c}" = EXCLUDED."${c}"`).join(", ");
+          await this.client.none(
+            `INSERT INTO ${fullTableName} (${columnList}) VALUES (${placeholders})
+             ON CONFLICT ("traceId", "spanId") DO UPDATE SET ${updateClause}`,
+            values
+          );
+        } else {
+          await this.client.none(
+            `INSERT INTO ${fullTableName} (${columnList}) VALUES (${placeholders})
+             ON CONFLICT ("traceId", "spanId") DO NOTHING`,
+            values
+          );
+        }
+      } else {
+        await this.client.none(`INSERT INTO ${fullTableName} (${columnList}) VALUES (${placeholders})`, values);
+      }
     } catch (error$1) {
       throw new error.MastraError(
         {
@@ -1885,7 +2218,7 @@ var PgDB = class extends base.MastraBase {
           SELECT 1 FROM information_schema.tables
           WHERE table_schema = $1 AND table_name = $2
         )`,
-        [this.schemaName || "mastra", tableName]
+        [this.schemaName || "public", tableName]
       );
       if (tableExists?.exists) {
         await this.client.none(`TRUNCATE TABLE ${tableNameWithSchema} CASCADE`);
@@ -1910,52 +2243,10 @@ var PgDB = class extends base.MastraBase {
   }) {
     try {
       const timeZColumnNames = Object.entries(schema).filter(([_, def]) => def.type === "timestamp").map(([name]) => name);
-      const timeZColumns = Object.entries(schema).filter(([_, def]) => def.type === "timestamp").map(([name]) => {
-        const parsedName = utils.parseSqlIdentifier(name, "column name");
-        return `"${parsedName}Z" TIMESTAMPTZ DEFAULT NOW()`;
-      });
-      const columns = Object.entries(schema).map(([name, def]) => {
-        const parsedName = utils.parseSqlIdentifier(name, "column name");
-        const constraints = [];
-        if (def.primaryKey) constraints.push("PRIMARY KEY");
-        if (!def.nullable) constraints.push("NOT NULL");
-        return `"${parsedName}" ${this.getSqlType(def.type)} ${constraints.join(" ")}`;
-      });
       if (this.schemaName) {
         await this.setupSchema();
       }
-      const finalColumns = [...columns, ...timeZColumns].join(",\n");
-      const constraintPrefix = this.schemaName ? `${this.schemaName}_` : "";
-      const schemaName = getSchemaName(this.schemaName);
-      const sql = `
-            CREATE TABLE IF NOT EXISTS ${getTableName({ indexName: tableName, schemaName })} (
-              ${finalColumns}
-            );
-            ${tableName === storage.TABLE_WORKFLOW_SNAPSHOT ? `
-            DO $$ BEGIN
-              IF NOT EXISTS (
-                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
-              ) AND NOT EXISTS (
-                SELECT 1 FROM pg_indexes WHERE indexname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
-              ) THEN
-                ALTER TABLE ${getTableName({ indexName: tableName, schemaName })}
-                ADD CONSTRAINT ${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key
-                UNIQUE (workflow_name, run_id);
-              END IF;
-            END $$;
-            ` : ""}
-          ${tableName === storage.TABLE_SPANS ? `
-            DO $$ BEGIN
-              IF NOT EXISTS (
-                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_ai_spans_traceid_spanid_pk'
-              ) THEN
-                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: getSchemaName(this.schemaName) })}
-                ADD CONSTRAINT ${constraintPrefix}mastra_ai_spans_traceid_spanid_pk
-                PRIMARY KEY ("traceId", "spanId");
-              END IF;
-            END $$;
-            ` : ""}
-          `;
+      const sql = generateTableSQL({ tableName, schema, schemaName: this.schemaName });
       await this.client.none(sql);
       await this.alterTable({
         tableName,
@@ -1965,8 +2256,46 @@ var PgDB = class extends base.MastraBase {
       if (tableName === storage.TABLE_SPANS) {
         await this.setupTimestampTriggers(tableName);
         await this.migrateSpansTable();
+        const pkExists = await this.spansPrimaryKeyExists();
+        if (!pkExists) {
+          const duplicateInfo = await this.checkForDuplicateSpans();
+          if (duplicateInfo.hasDuplicates) {
+            const errorMessage = `
+===========================================================================
+MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}
+===========================================================================
+
+Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations.
+
+The spans table requires a unique constraint on (traceId, spanId), but your
+database contains duplicate entries that must be resolved first.
+
+To fix this, run the manual migration command:
+
+  npx mastra migrate
+
+This command will:
+  1. Remove duplicate spans (keeping the most complete/recent version)
+  2. Add the required unique constraint
+
+Note: This migration may take some time for large tables.
+===========================================================================
+`;
+            throw new error.MastraError({
+              id: storage.createStorageErrorId("PG", "MIGRATION_REQUIRED", "DUPLICATE_SPANS"),
+              domain: error.ErrorDomain.STORAGE,
+              category: error.ErrorCategory.USER,
+              text: errorMessage
+            });
+          } else {
+            await this.addSpansPrimaryKey();
+          }
+        }
       }
     } catch (error$1) {
+      if (error$1 instanceof error.MastraError) {
+        throw error$1;
+      }
       throw new error.MastraError(
         {
           id: storage.createStorageErrorId("PG", "CREATE_TABLE", "FAILED"),
@@ -2029,12 +2358,29 @@ var PgDB = class extends base.MastraBase {
         const columnExists = await this.hasColumn(storage.TABLE_SPANS, columnName);
         if (!columnExists) {
           const parsedColumnName = utils.parseSqlIdentifier(columnName, "column name");
-          const sqlType = this.getSqlType(columnDef.type);
+          const sqlType = mapToSqlType(columnDef.type);
           const nullable = columnDef.nullable ? "" : "NOT NULL";
           const defaultValue = !columnDef.nullable ? this.getDefaultValue(columnDef.type) : "";
           const alterSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}" ${sqlType} ${nullable} ${defaultValue}`.trim();
           await this.client.none(alterSql);
           this.logger?.debug?.(`Added column '${columnName}' to ${fullTableName}`);
+          if (sqlType === "TIMESTAMP") {
+            const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}Z" TIMESTAMPTZ DEFAULT NOW()`.trim();
+            await this.client.none(timestampZSql);
+            this.logger?.debug?.(`Added timezone column '${columnName}Z' to ${fullTableName}`);
+          }
+        }
+      }
+      for (const [columnName, columnDef] of Object.entries(schema)) {
+        if (columnDef.type === "timestamp") {
+          const tzColumnName = `${columnName}Z`;
+          const tzColumnExists = await this.hasColumn(storage.TABLE_SPANS, tzColumnName);
+          if (!tzColumnExists) {
+            const parsedTzColumnName = utils.parseSqlIdentifier(tzColumnName, "column name");
+            const timestampZSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedTzColumnName}" TIMESTAMPTZ DEFAULT NOW()`.trim();
+            await this.client.none(timestampZSql);
+            this.logger?.debug?.(`Added timezone column '${tzColumnName}' to ${fullTableName}`);
+          }
         }
       }
       this.logger?.info?.(`Migration completed for ${fullTableName}`);
@@ -2042,6 +2388,224 @@ var PgDB = class extends base.MastraBase {
       this.logger?.warn?.(`Failed to migrate spans table ${fullTableName}:`, error);
     }
   }
+  /**
+   * Deduplicates spans in the mastra_ai_spans table before adding the PRIMARY KEY constraint.
+   * Keeps spans based on priority: completed (endedAt NOT NULL) > most recent updatedAt > most recent createdAt.
+   *
+   * Note: This prioritizes migration completion over perfect data preservation.
+   * Old trace data may be lost, which is acceptable for this use case.
+   */
+  async deduplicateSpans() {
+    const fullTableName = getTableName({ indexName: storage.TABLE_SPANS, schemaName: getSchemaName(this.schemaName) });
+    try {
+      const duplicateCheck = await this.client.oneOrNone(`
+        SELECT EXISTS (
+          SELECT 1
+          FROM ${fullTableName}
+          GROUP BY "traceId", "spanId"
+          HAVING COUNT(*) > 1
+          LIMIT 1
+        ) as has_duplicates
+      `);
+      if (!duplicateCheck?.has_duplicates) {
+        this.logger?.debug?.(`No duplicate spans found in ${fullTableName}`);
+        return;
+      }
+      this.logger?.info?.(`Duplicate spans detected in ${fullTableName}, starting deduplication...`);
+      const result = await this.client.query(`
+        DELETE FROM ${fullTableName} t1
+        USING ${fullTableName} t2
+        WHERE t1."traceId" = t2."traceId"
+          AND t1."spanId" = t2."spanId"
+          AND (
+            -- Keep completed spans over incomplete
+            (t1."endedAt" IS NULL AND t2."endedAt" IS NOT NULL)
+            OR
+            -- If both have same completion status, keep more recent updatedAt
+            (
+              (t1."endedAt" IS NULL) = (t2."endedAt" IS NULL)
+              AND (
+                (t1."updatedAt" < t2."updatedAt")
+                OR (t1."updatedAt" IS NULL AND t2."updatedAt" IS NOT NULL)
+                OR
+                -- If updatedAt is the same, keep more recent createdAt
+                (
+                  (t1."updatedAt" = t2."updatedAt" OR (t1."updatedAt" IS NULL AND t2."updatedAt" IS NULL))
+                  AND (
+                    (t1."createdAt" < t2."createdAt")
+                    OR (t1."createdAt" IS NULL AND t2."createdAt" IS NOT NULL)
+                    OR
+                    -- If all else equal, use ctid as tiebreaker
+                    (
+                      (t1."createdAt" = t2."createdAt" OR (t1."createdAt" IS NULL AND t2."createdAt" IS NULL))
+                      AND t1.ctid < t2.ctid
+                    )
+                  )
+                )
+              )
+            )
+          )
+      `);
+      this.logger?.info?.(
+        `Deduplication complete: removed ${result.rowCount ?? 0} duplicate spans from ${fullTableName}`
+      );
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("PG", "DEDUPLICATE_SPANS", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName: storage.TABLE_SPANS
+          }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Checks for duplicate (traceId, spanId) combinations in the spans table.
+   * Returns information about duplicates for logging/CLI purposes.
+   */
+  async checkForDuplicateSpans() {
+    const fullTableName = getTableName({ indexName: storage.TABLE_SPANS, schemaName: getSchemaName(this.schemaName) });
+    try {
+      const result = await this.client.oneOrNone(`
+        SELECT COUNT(*) as duplicate_count
+        FROM (
+          SELECT "traceId", "spanId"
+          FROM ${fullTableName}
+          GROUP BY "traceId", "spanId"
+          HAVING COUNT(*) > 1
+        ) duplicates
+      `);
+      const duplicateCount = parseInt(result?.duplicate_count ?? "0", 10);
+      return {
+        hasDuplicates: duplicateCount > 0,
+        duplicateCount,
+        tableName: fullTableName
+      };
+    } catch (error) {
+      this.logger?.debug?.(`Could not check for duplicates: ${error}`);
+      return { hasDuplicates: false, duplicateCount: 0, tableName: fullTableName };
+    }
+  }
+  /**
+   * Checks if the PRIMARY KEY constraint on (traceId, spanId) already exists on the spans table.
+   * Used to skip deduplication when the constraint already exists (migration already complete).
+   */
+  async spansPrimaryKeyExists() {
+    const parsedSchemaName = this.schemaName ? utils.parseSqlIdentifier(this.schemaName, "schema name") : "";
+    const constraintPrefix = parsedSchemaName ? `${parsedSchemaName}_` : "";
+    const constraintName = `${constraintPrefix}mastra_ai_spans_traceid_spanid_pk`;
+    const result = await this.client.oneOrNone(
+      `SELECT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = $1) as exists`,
+      [constraintName]
+    );
+    return result?.exists ?? false;
+  }
+  /**
+   * Adds the PRIMARY KEY constraint on (traceId, spanId) to the spans table.
+   * Should be called AFTER deduplication to ensure no duplicate key violations.
+   */
+  async addSpansPrimaryKey() {
+    const fullTableName = getTableName({ indexName: storage.TABLE_SPANS, schemaName: getSchemaName(this.schemaName) });
+    const parsedSchemaName = this.schemaName ? utils.parseSqlIdentifier(this.schemaName, "schema name") : "";
+    const constraintPrefix = parsedSchemaName ? `${parsedSchemaName}_` : "";
+    const constraintName = `${constraintPrefix}mastra_ai_spans_traceid_spanid_pk`;
+    try {
+      const constraintExists = await this.client.oneOrNone(
+        `
+        SELECT EXISTS (
+          SELECT 1 FROM pg_constraint WHERE conname = $1
+        ) as exists
+      `,
+        [constraintName]
+      );
+      if (constraintExists?.exists) {
+        this.logger?.debug?.(`PRIMARY KEY constraint ${constraintName} already exists on ${fullTableName}`);
+        return;
+      }
+      await this.client.none(`
+        ALTER TABLE ${fullTableName}
+        ADD CONSTRAINT ${constraintName}
+        PRIMARY KEY ("traceId", "spanId")
+      `);
+      this.logger?.info?.(`Added PRIMARY KEY constraint ${constraintName} to ${fullTableName}`);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("PG", "ADD_SPANS_PRIMARY_KEY", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName: storage.TABLE_SPANS,
+            constraintName
+          }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Manually run the spans migration to deduplicate and add the unique constraint.
+   * This is intended to be called from the CLI when duplicates are detected.
+   *
+   * @returns Migration result with status and details
+   */
+  async migrateSpans() {
+    const fullTableName = getTableName({ indexName: storage.TABLE_SPANS, schemaName: getSchemaName(this.schemaName) });
+    const pkExists = await this.spansPrimaryKeyExists();
+    if (pkExists) {
+      return {
+        success: true,
+        alreadyMigrated: true,
+        duplicatesRemoved: 0,
+        message: `Migration already complete. PRIMARY KEY constraint exists on ${fullTableName}.`
+      };
+    }
+    const duplicateInfo = await this.checkForDuplicateSpans();
+    if (duplicateInfo.hasDuplicates) {
+      this.logger?.info?.(
+        `Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations. Starting deduplication...`
+      );
+      await this.deduplicateSpans();
+    } else {
+      this.logger?.info?.(`No duplicate spans found.`);
+    }
+    await this.addSpansPrimaryKey();
+    return {
+      success: true,
+      alreadyMigrated: false,
+      duplicatesRemoved: duplicateInfo.duplicateCount,
+      message: duplicateInfo.hasDuplicates ? `Migration complete. Removed duplicates and added PRIMARY KEY constraint to ${fullTableName}.` : `Migration complete. Added PRIMARY KEY constraint to ${fullTableName}.`
+    };
+  }
+  /**
+   * Check migration status for the spans table.
+   * Returns information about whether migration is needed.
+   */
+  async checkSpansMigrationStatus() {
+    const fullTableName = getTableName({ indexName: storage.TABLE_SPANS, schemaName: getSchemaName(this.schemaName) });
+    const pkExists = await this.spansPrimaryKeyExists();
+    if (pkExists) {
+      return {
+        needsMigration: false,
+        hasDuplicates: false,
+        duplicateCount: 0,
+        constraintExists: true,
+        tableName: fullTableName
+      };
+    }
+    const duplicateInfo = await this.checkForDuplicateSpans();
+    return {
+      needsMigration: true,
+      hasDuplicates: duplicateInfo.hasDuplicates,
+      duplicateCount: duplicateInfo.duplicateCount,
+      constraintExists: false,
+      tableName: fullTableName
+    };
+  }
   /**
    * Alters table schema to add columns if they don't exist
    * @param tableName Name of the table
@@ -2059,7 +2623,7 @@ var PgDB = class extends base.MastraBase {
         if (schema[columnName]) {
           const columnDef = schema[columnName];
           const parsedColumnName = utils.parseSqlIdentifier(columnName, "column name");
-          const sqlType = this.getSqlType(columnDef.type);
+          const sqlType = mapToSqlType(columnDef.type);
           const nullable = columnDef.nullable ? "" : "NOT NULL";
           const defaultValue = !columnDef.nullable ? this.getDefaultValue(columnDef.type) : "";
           const alterSql = `ALTER TABLE ${fullTableName} ADD COLUMN IF NOT EXISTS "${parsedColumnName}" ${sqlType} ${nullable} ${defaultValue}`.trim();
@@ -2379,9 +2943,9 @@ var PgDB = class extends base.MastraBase {
         size: result.size || "0",
         definition: result.definition || "",
         method: result.method || "btree",
-        scans: parseInt(result.scans) || 0,
-        tuples_read: parseInt(result.tuples_read) || 0,
-        tuples_fetched: parseInt(result.tuples_fetched) || 0
+        scans: parseInt(String(result.scans)) || 0,
+        tuples_read: parseInt(String(result.tuples_read)) || 0,
+        tuples_fetched: parseInt(String(result.tuples_fetched)) || 0
       };
     } catch (error$1) {
       throw new error.MastraError(
@@ -2898,6 +3462,9 @@ function getTableName3({ indexName, schemaName }) {
   const quotedIndexName = `"${indexName}"`;
   return schemaName ? `${schemaName}.${quotedIndexName}` : quotedIndexName;
 }
+function inPlaceholders(count, startIndex = 1) {
+  return Array.from({ length: count }, (_, i) => `$${i + startIndex}`).join(", ");
+}
 var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
   #db;
   #schema;
@@ -3024,27 +3591,52 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       );
     }
   }
-  async listThreadsByResourceId(args) {
-    const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
-    if (page < 0) {
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
       throw new error.MastraError({
-        id: storage.createStorageErrorId("PG", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
+        id: storage.createStorageErrorId("PG", "LIST_THREADS", "INVALID_PAGE"),
         domain: error.ErrorDomain.STORAGE,
         category: error.ErrorCategory.USER,
-        text: "Page number must be non-negative",
-        details: {
-          resourceId,
-          page
-        }
+        text: error$1 instanceof Error ? error$1.message : "Invalid pagination parameters",
+        details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
       });
     }
-    const { field, direction } = this.parseOrderBy(orderBy);
     const perPage = storage.normalizePerPage(perPageInput, 100);
+    try {
+      this.validateMetadataKeys(filter?.metadata);
+    } catch (error$1) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "LIST_THREADS", "INVALID_METADATA_KEY"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: error$1 instanceof Error ? error$1.message : "Invalid metadata key",
+        details: { metadataKeys: filter?.metadata ? Object.keys(filter.metadata).join(", ") : "" }
+      });
+    }
+    const { field, direction } = this.parseOrderBy(orderBy);
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
     try {
       const tableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
-      const baseQuery = `FROM ${tableName} WHERE "resourceId" = $1`;
-      const queryParams = [resourceId];
+      const whereClauses = [];
+      const queryParams = [];
+      let paramIndex = 1;
+      if (filter?.resourceId) {
+        whereClauses.push(`"resourceId" = $${paramIndex}`);
+        queryParams.push(filter.resourceId);
+        paramIndex++;
+      }
+      if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+        for (const [key, value] of Object.entries(filter.metadata)) {
+          whereClauses.push(`metadata::jsonb @> $${paramIndex}::jsonb`);
+          queryParams.push(JSON.stringify({ [key]: value }));
+          paramIndex++;
+        }
+      }
+      const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+      const baseQuery = `FROM ${tableName} ${whereClause}`;
       const countQuery = `SELECT COUNT(*) ${baseQuery}`;
       const countResult = await this.#db.client.one(countQuery, queryParams);
       const total = parseInt(countResult.count, 10);
@@ -3058,13 +3650,19 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         };
       }
       const limitValue = perPageInput === false ? total : perPage;
-      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "updatedAt" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $2 OFFSET $3`;
-      const rows = await this.#db.client.manyOrNone(dataQuery, [...queryParams, limitValue, offset]);
+      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
+      const rows = await this.#db.client.manyOrNone(
+        dataQuery,
+        [...queryParams, limitValue, offset]
+      );
       const threads = (rows || []).map((thread) => ({
-        ...thread,
+        id: thread.id,
+        resourceId: thread.resourceId,
+        title: thread.title,
         metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata,
-        createdAt: thread.createdAt,
-        updatedAt: thread.updatedAt
+        // Use timezone-aware columns (*Z) for correct UTC timestamps, with fallback for legacy data
+        createdAt: thread.createdAtZ || thread.createdAt,
+        updatedAt: thread.updatedAtZ || thread.updatedAt
       }));
       return {
         threads,
@@ -3076,11 +3674,12 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     } catch (error$1) {
       const mastraError = new error.MastraError(
         {
-          id: storage.createStorageErrorId("PG", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: storage.createStorageErrorId("PG", "LIST_THREADS", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: {
-            resourceId,
+            ...filter?.resourceId && { resourceId: filter.resourceId },
+            hasMetadataFilter: !!filter?.metadata,
             page
           }
         },
@@ -3169,17 +3768,18 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       ...metadata
     };
     try {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
       const thread = await this.#db.client.one(
         `UPDATE ${threadTableName}
                     SET
                         title = $1,
                         metadata = $2,
                         "updatedAt" = $3,
-                        "updatedAtZ" = $3
-                    WHERE id = $4
+                        "updatedAtZ" = $4
+                    WHERE id = $5
                     RETURNING *
                 `,
-        [title, mergedMetadata, (/* @__PURE__ */ new Date()).toISOString(), id]
+        [title, mergedMetadata, now, now, id]
       );
       return {
         id: thread.id,
@@ -3322,7 +3922,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       const tableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
       const query = `
         ${selectStatement} FROM ${tableName}
-        WHERE id IN (${messageIds.map((_, i) => `$${i + 1}`).join(", ")})
+        WHERE id IN (${inPlaceholders(messageIds.length)})
         ORDER BY "createdAt" DESC
       `;
       const resultRows = await this.#db.client.manyOrNone(query, messageIds);
@@ -3383,8 +3983,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       const orderByStatement = `ORDER BY "${field}" ${direction}`;
       const selectStatement = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId"`;
       const tableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
-      const threadPlaceholders = threadIds.map((_, i) => `$${i + 1}`).join(", ");
-      const conditions = [`thread_id IN (${threadPlaceholders})`];
+      const conditions = [`thread_id IN (${inPlaceholders(threadIds.length)})`];
       const queryParams = [...threadIds];
       let paramIndex = threadIds.length + 1;
       if (resourceId) {
@@ -3392,11 +3991,13 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         queryParams.push(resourceId);
       }
       if (filter?.dateRange?.start) {
-        conditions.push(`"createdAt" >= $${paramIndex++}`);
+        const startOp = filter.dateRange.startExclusive ? ">" : ">=";
+        conditions.push(`"createdAt" ${startOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.start);
       }
       if (filter?.dateRange?.end) {
-        conditions.push(`"createdAt" <= $${paramIndex++}`);
+        const endOp = filter.dateRange.endExclusive ? "<" : "<=";
+        conditions.push(`"createdAt" ${endOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.end);
       }
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
@@ -3541,14 +4142,15 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
           );
         });
         const threadTableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
+        const nowStr = (/* @__PURE__ */ new Date()).toISOString();
         const threadUpdate = t.none(
           `UPDATE ${threadTableName}
                         SET
                             "updatedAt" = $1,
-                            "updatedAtZ" = $1
-                        WHERE id = $2
+                            "updatedAtZ" = $2
+                        WHERE id = $3
                     `,
-          [(/* @__PURE__ */ new Date()).toISOString(), threadId]
+          [nowStr, nowStr, threadId]
         );
         await Promise.all([...messageInserts, threadUpdate]);
       });
@@ -3585,8 +4187,8 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       return [];
     }
     const messageIds = messages.map((m) => m.id);
-    const selectQuery = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId" FROM ${getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) })} WHERE id IN ($1:list)`;
-    const existingMessagesDb = await this.#db.client.manyOrNone(selectQuery, [messageIds]);
+    const selectQuery = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId" FROM ${getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) })} WHERE id IN (${inPlaceholders(messageIds.length)})`;
+    const existingMessagesDb = await this.#db.client.manyOrNone(selectQuery, messageIds);
     if (existingMessagesDb.length === 0) {
       return [];
     }
@@ -3647,10 +4249,11 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         }
       }
       if (threadIdsToUpdate.size > 0) {
+        const threadIds = Array.from(threadIdsToUpdate);
         queries.push(
           t.none(
-            `UPDATE ${getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) })} SET "updatedAt" = NOW(), "updatedAtZ" = NOW() WHERE id IN ($1:list)`,
-            [Array.from(threadIdsToUpdate)]
+            `UPDATE ${getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) })} SET "updatedAt" = NOW(), "updatedAtZ" = NOW() WHERE id IN (${inPlaceholders(threadIds.length)})`,
+            threadIds
           )
         );
       }
@@ -3658,7 +4261,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         await t.batch(queries);
       }
     });
-    const updatedMessages = await this.#db.client.manyOrNone(selectQuery, [messageIds]);
+    const updatedMessages = await this.#db.client.manyOrNone(selectQuery, messageIds);
     return (updatedMessages || []).map((row) => {
       const message = this.normalizeMessageRow(row);
       if (typeof message.content === "string") {
@@ -3770,15 +4373,159 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       values.push(JSON.stringify(updatedResource.metadata));
       paramIndex++;
     }
-    updates.push(`"updatedAt" = $${paramIndex}`);
-    values.push(updatedResource.updatedAt.toISOString());
+    const updatedAtStr = updatedResource.updatedAt.toISOString();
+    updates.push(`"updatedAt" = $${paramIndex++}`);
+    values.push(updatedAtStr);
     updates.push(`"updatedAtZ" = $${paramIndex++}`);
-    values.push(updatedResource.updatedAt.toISOString());
-    paramIndex++;
+    values.push(updatedAtStr);
     values.push(resourceId);
     await this.#db.client.none(`UPDATE ${tableName} SET ${updates.join(", ")} WHERE id = $${paramIndex}`, values);
     return updatedResource;
   }
+  async cloneThread(args) {
+    const { sourceThreadId, newThreadId: providedThreadId, resourceId, title, metadata, options } = args;
+    const sourceThread = await this.getThreadById({ threadId: sourceThreadId });
+    if (!sourceThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "CLONE_THREAD", "SOURCE_NOT_FOUND"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Source thread with id ${sourceThreadId} not found`,
+        details: { sourceThreadId }
+      });
+    }
+    const newThreadId = providedThreadId || crypto.randomUUID();
+    const existingThread = await this.getThreadById({ threadId: newThreadId });
+    if (existingThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "CLONE_THREAD", "THREAD_EXISTS"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Thread with id ${newThreadId} already exists`,
+        details: { newThreadId }
+      });
+    }
+    const threadTableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
+    const messageTableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
+    try {
+      return await this.#db.client.tx(async (t) => {
+        let messageQuery = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId"
+                            FROM ${messageTableName} WHERE thread_id = $1`;
+        const messageParams = [sourceThreadId];
+        let paramIndex = 2;
+        if (options?.messageFilter?.startDate) {
+          messageQuery += ` AND "createdAt" >= $${paramIndex++}`;
+          messageParams.push(options.messageFilter.startDate);
+        }
+        if (options?.messageFilter?.endDate) {
+          messageQuery += ` AND "createdAt" <= $${paramIndex++}`;
+          messageParams.push(options.messageFilter.endDate);
+        }
+        if (options?.messageFilter?.messageIds && options.messageFilter.messageIds.length > 0) {
+          messageQuery += ` AND id IN (${options.messageFilter.messageIds.map(() => `$${paramIndex++}`).join(", ")})`;
+          messageParams.push(...options.messageFilter.messageIds);
+        }
+        messageQuery += ` ORDER BY "createdAt" ASC`;
+        if (options?.messageLimit && options.messageLimit > 0) {
+          const limitQuery = `SELECT * FROM (${messageQuery.replace('ORDER BY "createdAt" ASC', 'ORDER BY "createdAt" DESC')} LIMIT $${paramIndex}) AS limited ORDER BY "createdAt" ASC`;
+          messageParams.push(options.messageLimit);
+          messageQuery = limitQuery;
+        }
+        const sourceMessages = await t.manyOrNone(messageQuery, messageParams);
+        const now = /* @__PURE__ */ new Date();
+        const lastMessageId = sourceMessages.length > 0 ? sourceMessages[sourceMessages.length - 1].id : void 0;
+        const cloneMetadata = {
+          sourceThreadId,
+          clonedAt: now,
+          ...lastMessageId && { lastMessageId }
+        };
+        const newThread = {
+          id: newThreadId,
+          resourceId: resourceId || sourceThread.resourceId,
+          title: title || (sourceThread.title ? `Clone of ${sourceThread.title}` : void 0),
+          metadata: {
+            ...metadata,
+            clone: cloneMetadata
+          },
+          createdAt: now,
+          updatedAt: now
+        };
+        await t.none(
+          `INSERT INTO ${threadTableName} (
+            id,
+            "resourceId",
+            title,
+            metadata,
+            "createdAt",
+            "createdAtZ",
+            "updatedAt",
+            "updatedAtZ"
+          ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+          [
+            newThread.id,
+            newThread.resourceId,
+            newThread.title,
+            newThread.metadata ? JSON.stringify(newThread.metadata) : null,
+            now,
+            now,
+            now,
+            now
+          ]
+        );
+        const clonedMessages = [];
+        const targetResourceId = resourceId || sourceThread.resourceId;
+        for (const sourceMsg of sourceMessages) {
+          const newMessageId = crypto.randomUUID();
+          const normalizedMsg = this.normalizeMessageRow(sourceMsg);
+          let parsedContent = normalizedMsg.content;
+          try {
+            parsedContent = JSON.parse(normalizedMsg.content);
+          } catch {
+          }
+          await t.none(
+            `INSERT INTO ${messageTableName} (id, thread_id, content, "createdAt", "createdAtZ", role, type, "resourceId")
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+            [
+              newMessageId,
+              newThreadId,
+              typeof normalizedMsg.content === "string" ? normalizedMsg.content : JSON.stringify(normalizedMsg.content),
+              normalizedMsg.createdAt,
+              normalizedMsg.createdAt,
+              normalizedMsg.role,
+              normalizedMsg.type || "v2",
+              targetResourceId
+            ]
+          );
+          clonedMessages.push({
+            id: newMessageId,
+            threadId: newThreadId,
+            content: parsedContent,
+            role: normalizedMsg.role,
+            type: normalizedMsg.type,
+            createdAt: new Date(normalizedMsg.createdAt),
+            resourceId: targetResourceId
+          });
+        }
+        return {
+          thread: newThread,
+          clonedMessages
+        };
+      });
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) {
+        throw error$1;
+      }
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("PG", "CLONE_THREAD", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { sourceThreadId, newThreadId }
+        },
+        error$1
+      );
+    }
+  }
 };
 var ObservabilityPG = class _ObservabilityPG extends storage.ObservabilityStorage {
   #db;
@@ -3896,6 +4643,22 @@ var ObservabilityPG = class _ObservabilityPG extends storage.ObservabilityStorag
       }
     }
   }
+  /**
+   * Manually run the spans migration to deduplicate and add the unique constraint.
+   * This is intended to be called from the CLI when duplicates are detected.
+   *
+   * @returns Migration result with status and details
+   */
+  async migrateSpans() {
+    return this.#db.migrateSpans();
+  }
+  /**
+   * Check migration status for the spans table.
+   * Returns information about whether migration is needed.
+   */
+  async checkSpansMigrationStatus() {
+    return this.#db.checkSpansMigrationStatus();
+  }
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.TABLE_SPANS });
   }
@@ -4408,6 +5171,11 @@ var ScoresPG = class _ScoresPG extends storage.ScoresStorage {
   }
   async init() {
     await this.#db.createTable({ tableName: storage.TABLE_SCORERS, schema: storage.TABLE_SCHEMAS[storage.TABLE_SCORERS] });
+    await this.#db.alterTable({
+      tableName: storage.TABLE_SCORERS,
+      schema: storage.TABLE_SCHEMAS[storage.TABLE_SCORERS],
+      ifNotExists: ["spanId", "requestContext"]
+    });
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
@@ -4759,23 +5527,8 @@ function getTableName5({ indexName, schemaName }) {
   const quotedIndexName = `"${indexName}"`;
   return schemaName ? `${schemaName}.${quotedIndexName}` : quotedIndexName;
 }
-function parseWorkflowRun(row) {
-  let parsedSnapshot = row.snapshot;
-  if (typeof parsedSnapshot === "string") {
-    try {
-      parsedSnapshot = JSON.parse(row.snapshot);
-    } catch (e) {
-      console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
-    }
-  }
-  return {
-    workflowName: row.workflow_name,
-    runId: row.run_id,
-    snapshot: parsedSnapshot,
-    resourceId: row.resourceId,
-    createdAt: new Date(row.createdAtZ || row.createdAt),
-    updatedAt: new Date(row.updatedAtZ || row.updatedAt)
-  };
+function sanitizeJsonForPg(jsonString) {
+  return jsonString.replace(/\\u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})/g, "");
 }
 var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
   #db;
@@ -4792,6 +5545,24 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
     this.#skipDefaultIndexes = skipDefaultIndexes;
     this.#indexes = indexes?.filter((idx) => _WorkflowsPG.MANAGED_TABLES.includes(idx.table));
   }
+  parseWorkflowRun(row) {
+    let parsedSnapshot = row.snapshot;
+    if (typeof parsedSnapshot === "string") {
+      try {
+        parsedSnapshot = JSON.parse(row.snapshot);
+      } catch (e) {
+        this.logger.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+      }
+    }
+    return {
+      workflowName: row.workflow_name,
+      runId: row.run_id,
+      snapshot: parsedSnapshot,
+      resourceId: row.resourceId,
+      createdAt: new Date(row.createdAtZ || row.createdAt),
+      updatedAt: new Date(row.updatedAtZ || row.updatedAt)
+    };
+  }
   /**
    * Returns default index definitions for the workflows domain tables.
    * Currently no default indexes are defined for workflows.
@@ -4864,12 +5635,13 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
       const now = /* @__PURE__ */ new Date();
       const createdAtValue = createdAt ? createdAt : now;
       const updatedAtValue = updatedAt ? updatedAt : now;
+      const sanitizedSnapshot = sanitizeJsonForPg(JSON.stringify(snapshot));
       await this.#db.client.none(
         `INSERT INTO ${getTableName5({ indexName: storage.TABLE_WORKFLOW_SNAPSHOT, schemaName: getSchemaName5(this.#schema) })} (workflow_name, run_id, "resourceId", snapshot, "createdAt", "updatedAt")
                  VALUES ($1, $2, $3, $4, $5, $6)
                  ON CONFLICT (workflow_name, run_id) DO UPDATE
                  SET "resourceId" = $3, snapshot = $4, "updatedAt" = $6`,
-        [workflowName, runId, resourceId, JSON.stringify(snapshot), createdAtValue, updatedAtValue]
+        [workflowName, runId, resourceId, sanitizedSnapshot, createdAtValue, updatedAtValue]
       );
     } catch (error$1) {
       throw new error.MastraError(
@@ -4932,7 +5704,7 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
       if (!result) {
         return null;
       }
-      return parseWorkflowRun(result);
+      return this.parseWorkflowRun(result);
     } catch (error$1) {
       throw new error.MastraError(
         {
@@ -4988,7 +5760,9 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
         paramIndex++;
       }
       if (status) {
-        conditions.push(`snapshot::jsonb ->> 'status' = $${paramIndex}`);
+        conditions.push(
+          `regexp_replace(snapshot::text, '\\\\u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})', '', 'g')::jsonb ->> 'status' = $${paramIndex}`
+        );
         values.push(status);
         paramIndex++;
       }
@@ -5033,7 +5807,7 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
       const queryValues = usePagination ? [...values, normalizedPerPage, offset] : values;
       const result = await this.#db.client.manyOrNone(query, queryValues);
       const runs = (result || []).map((row) => {
-        return parseWorkflowRun(row);
+        return this.parseWorkflowRun(row);
       });
       return { runs, total: total || runs.length };
     } catch (error$1) {
@@ -5053,9 +5827,12 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
 };
 
 // src/storage/index.ts
-var PostgresStore = class extends storage.MastraStorage {
+var DEFAULT_MAX_CONNECTIONS = 20;
+var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
+var PostgresStore = class extends storage.MastraCompositeStore {
+  #pool;
   #db;
-  #pgp;
+  #ownsPool;
   schema;
   isInitialized = false;
   stores;
@@ -5063,60 +5840,27 @@ var PostgresStore = class extends storage.MastraStorage {
     try {
       validateConfig("PostgresStore", config);
       super({ id: config.id, name: "PostgresStore", disableInit: config.disableInit });
-      this.schema = config.schemaName || "public";
-      this.#pgp = pgPromise__default.default();
-      if (isClientConfig(config)) {
-        this.#db = config.client;
+      this.schema = utils.parseSqlIdentifier(config.schemaName || "public", "schema name");
+      if (isPoolConfig(config)) {
+        this.#pool = config.pool;
+        this.#ownsPool = false;
       } else {
-        let pgConfig;
-        if (isConnectionStringConfig(config)) {
-          pgConfig = {
-            id: config.id,
-            connectionString: config.connectionString,
-            max: config.max,
-            idleTimeoutMillis: config.idleTimeoutMillis,
-            ssl: config.ssl
-          };
-        } else if (isCloudSqlConfig(config)) {
-          pgConfig = {
-            ...config,
-            id: config.id,
-            max: config.max,
-            idleTimeoutMillis: config.idleTimeoutMillis
-          };
-        } else if (isHostConfig(config)) {
-          pgConfig = {
-            id: config.id,
-            host: config.host,
-            port: config.port,
-            database: config.database,
-            user: config.user,
-            password: config.password,
-            ssl: config.ssl,
-            max: config.max,
-            idleTimeoutMillis: config.idleTimeoutMillis
-          };
-        } else {
-          throw new Error(
-            "PostgresStore: invalid config. Provide either {client}, {connectionString}, {host,port,database,user,password}, or a pg ClientConfig (e.g., Cloud SQL connector with `stream`)."
-          );
-        }
-        this.#db = this.#pgp(pgConfig);
-      }
-      const skipDefaultIndexes = config.skipDefaultIndexes;
-      const indexes = config.indexes;
-      const domainConfig = { client: this.#db, schemaName: this.schema, skipDefaultIndexes, indexes };
-      const scores = new ScoresPG(domainConfig);
-      const workflows = new WorkflowsPG(domainConfig);
-      const memory = new MemoryPG(domainConfig);
-      const observability = new ObservabilityPG(domainConfig);
-      const agents = new AgentsPG(domainConfig);
+        this.#pool = this.createPool(config);
+        this.#ownsPool = true;
+      }
+      this.#db = new PoolAdapter(this.#pool);
+      const domainConfig = {
+        client: this.#db,
+        schemaName: this.schema,
+        skipDefaultIndexes: config.skipDefaultIndexes,
+        indexes: config.indexes
+      };
       this.stores = {
-        scores,
-        workflows,
-        memory,
-        observability,
-        agents
+        scores: new ScoresPG(domainConfig),
+        workflows: new WorkflowsPG(domainConfig),
+        memory: new MemoryPG(domainConfig),
+        observability: new ObservabilityPG(domainConfig),
+        agents: new AgentsPG(domainConfig)
       };
     } catch (e) {
       throw new error.MastraError(
@@ -5129,6 +5873,32 @@ var PostgresStore = class extends storage.MastraStorage {
       );
     }
   }
+  createPool(config) {
+    if (isConnectionStringConfig(config)) {
+      return new pg.Pool({
+        connectionString: config.connectionString,
+        ssl: config.ssl,
+        max: config.max ?? DEFAULT_MAX_CONNECTIONS,
+        idleTimeoutMillis: config.idleTimeoutMillis ?? DEFAULT_IDLE_TIMEOUT_MS
+      });
+    }
+    if (isHostConfig(config)) {
+      return new pg.Pool({
+        host: config.host,
+        port: config.port,
+        database: config.database,
+        user: config.user,
+        password: config.password,
+        ssl: config.ssl,
+        max: config.max ?? DEFAULT_MAX_CONNECTIONS,
+        idleTimeoutMillis: config.idleTimeoutMillis ?? DEFAULT_IDLE_TIMEOUT_MS
+      });
+    }
+    if (isCloudSqlConfig(config)) {
+      return new pg.Pool(config);
+    }
+    throw new Error("PostgresStore: invalid config");
+  }
   async init() {
     if (this.isInitialized) {
       return;
@@ -5138,6 +5908,9 @@ var PostgresStore = class extends storage.MastraStorage {
       await super.init();
     } catch (error$1) {
       this.isInitialized = false;
+      if (error$1 instanceof error.MastraError) {
+        throw error$1;
+      }
       throw new error.MastraError(
         {
           id: storage.createStorageErrorId("PG", "INIT", "FAILED"),
@@ -5148,32 +5921,32 @@ var PostgresStore = class extends storage.MastraStorage {
       );
     }
   }
+  /**
+   * Database client for executing queries.
+   *
+   * @example
+   * ```typescript
+   * const rows = await store.db.any('SELECT * FROM users WHERE active = $1', [true]);
+   * const user = await store.db.one('SELECT * FROM users WHERE id = $1', [userId]);
+   * ```
+   */
   get db() {
     return this.#db;
   }
-  get pgp() {
-    return this.#pgp;
-  }
-  get supports() {
-    return {
-      selectByIncludeResourceScope: true,
-      resourceWorkingMemory: true,
-      hasColumn: true,
-      createTable: true,
-      deleteMessages: true,
-      observability: true,
-      indexManagement: true,
-      listScoresBySpan: true,
-      agents: true
-    };
+  /**
+   * The underlying pg.Pool for direct database access or ORM integration.
+   */
+  get pool() {
+    return this.#pool;
   }
   /**
-   * Closes the pg-promise connection pool.
-   *
-   * This will close ALL connections in the pool, including pre-configured clients.
+   * Closes the connection pool if it was created by this store.
+   * If a pool was passed in via config, it will not be closed.
    */
   async close() {
-    this.pgp.end();
+    if (this.#ownsPool) {
+      await this.#pool.end();
+    }
   }
 };
 
@@ -5276,8 +6049,15 @@ Example Complex Query:
   ]
 }`;
 
+exports.AgentsPG = AgentsPG;
+exports.MemoryPG = MemoryPG;
+exports.ObservabilityPG = ObservabilityPG;
 exports.PGVECTOR_PROMPT = PGVECTOR_PROMPT;
 exports.PgVector = PgVector;
+exports.PoolAdapter = PoolAdapter;
 exports.PostgresStore = PostgresStore;
+exports.ScoresPG = ScoresPG;
+exports.WorkflowsPG = WorkflowsPG;
+exports.exportSchemas = exportSchemas;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map