@mastra/pg 1.0.0-beta.14 → 1.0.0-beta.15

package/dist/index.cjs

@@ -285,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
@@ -364,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 ");
@@ -441,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 ");
@@ -711,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");
       }
@@ -798,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 {
@@ -1873,7 +1968,8 @@ function mapToSqlType(type) {
 function generateTableSQL({
   tableName,
   schema,
-  schemaName
+  schemaName,
+  includeAllConstraints = false
 }) {
   const timeZColumns = Object.entries(schema).filter(([_, def]) => def.type === "timestamp").map(([name]) => {
     const parsedName = utils.parseSqlIdentifier(name, "column name");
@@ -1897,9 +1993,9 @@ function generateTableSQL({
             ${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'
+                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 = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
+                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
@@ -1907,10 +2003,11 @@ function generateTableSQL({
               END IF;
             END $$;
             ` : ""}
-          ${tableName === storage.TABLE_SPANS ? `
+          ${// 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 = '${constraintPrefix}mastra_ai_spans_traceid_spanid_pk'
+                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
@@ -1934,7 +2031,9 @@ function exportSchemas(schemaName) {
     const sql = generateTableSQL({
       tableName,
       schema,
-      schemaName
+      schemaName,
+      includeAllConstraints: true
+      // Include all constraints for exports/documentation
     });
     statements.push(sql.trim());
     statements.push("");
@@ -2075,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(
         {
@@ -2140,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"),
@@ -2234,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
@@ -4271,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 });
   }
@@ -5441,7 +5829,7 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
 // src/storage/index.ts
 var DEFAULT_MAX_CONNECTIONS = 20;
 var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
-var PostgresStore = class extends storage.MastraStorage {
+var PostgresStore = class extends storage.MastraCompositeStore {
   #pool;
   #db;
   #ownsPool;
@@ -5520,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"),