@mastra/pg 0.16.1 → 0.17.0

package/dist/index.js

@@ -5,9 +5,10 @@ import { Mutex } from 'async-mutex';
 import pg from 'pg';
 import xxhash from 'xxhash-wasm';
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
-import { MastraStorage, StoreOperations, TABLE_WORKFLOW_SNAPSHOT, TABLE_THREADS, TABLE_MESSAGES, TABLE_TRACES, TABLE_EVALS, ScoresStorage, TABLE_SCORERS, TracesStorage, safelyParseJSON, WorkflowsStorage, LegacyEvalsStorage, MemoryStorage, resolveMessageLimit, TABLE_RESOURCES } from '@mastra/core/storage';
+import { MastraStorage, StoreOperations, TABLE_SCHEMAS, TABLE_WORKFLOW_SNAPSHOT, TABLE_AI_SPANS, TABLE_THREADS, TABLE_MESSAGES, TABLE_TRACES, TABLE_EVALS, TABLE_SCORERS, ScoresStorage, TracesStorage, safelyParseJSON, WorkflowsStorage, LegacyEvalsStorage, MemoryStorage, resolveMessageLimit, TABLE_RESOURCES, ObservabilityStorage } from '@mastra/core/storage';
 import pgPromise from 'pg-promise';
 import { MessageList } from '@mastra/core/agent';
+import { saveScorePayloadSchema } from '@mastra/core/scores';
 
 // src/vector/index.ts
 var PGFilterTranslator = class extends BaseFilterTranslator {
@@ -1258,6 +1259,68 @@ function getTableName({ indexName, schemaName }) {
   const quotedSchemaName = schemaName;
   return quotedSchemaName ? `${quotedSchemaName}.${quotedIndexName}` : quotedIndexName;
 }
+function buildDateRangeFilter(dateRange, fieldName) {
+  const filters = {};
+  if (dateRange?.start) {
+    filters[`${fieldName}_gte`] = dateRange.start;
+  }
+  if (dateRange?.end) {
+    filters[`${fieldName}_lte`] = dateRange.end;
+  }
+  return filters;
+}
+function prepareWhereClause(filters, _schema) {
+  const conditions = [];
+  const args = [];
+  let paramIndex = 1;
+  Object.entries(filters).forEach(([key, value]) => {
+    if (value === void 0) return;
+    if (key.endsWith("_gte")) {
+      const fieldName = key.slice(0, -4);
+      conditions.push(`"${parseSqlIdentifier(fieldName, "field name")}" >= $${paramIndex++}`);
+      args.push(value instanceof Date ? value.toISOString() : value);
+    } else if (key.endsWith("_lte")) {
+      const fieldName = key.slice(0, -4);
+      conditions.push(`"${parseSqlIdentifier(fieldName, "field name")}" <= $${paramIndex++}`);
+      args.push(value instanceof Date ? value.toISOString() : value);
+    } else if (value === null) {
+      conditions.push(`"${parseSqlIdentifier(key, "field name")}" IS NULL`);
+    } else {
+      conditions.push(`"${parseSqlIdentifier(key, "field name")}" = $${paramIndex++}`);
+      args.push(value instanceof Date ? value.toISOString() : value);
+    }
+  });
+  return {
+    sql: conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "",
+    args
+  };
+}
+function transformFromSqlRow({
+  tableName,
+  sqlRow
+}) {
+  const schema = TABLE_SCHEMAS[tableName];
+  const result = {};
+  Object.entries(sqlRow).forEach(([key, value]) => {
+    const columnSchema = schema?.[key];
+    if (columnSchema?.type === "jsonb" && typeof value === "string") {
+      try {
+        result[key] = JSON.parse(value);
+      } catch {
+        result[key] = value;
+      }
+    } else if (columnSchema?.type === "timestamp" && value && typeof value === "string") {
+      result[key] = new Date(value);
+    } else if (columnSchema?.type === "timestamp" && value instanceof Date) {
+      result[key] = value;
+    } else if (columnSchema?.type === "boolean") {
+      result[key] = Boolean(value);
+    } else {
+      result[key] = value;
+    }
+  });
+  return result;
+}
 
 // src/storage/domains/legacy-evals/index.ts
 function transformEvalRow(row) {
@@ -2193,6 +2256,316 @@ var MemoryPG = class extends MemoryStorage {
     return updatedResource;
   }
 };
+var ObservabilityPG = class extends ObservabilityStorage {
+  client;
+  operations;
+  schema;
+  constructor({
+    client,
+    operations,
+    schema
+  }) {
+    super();
+    this.client = client;
+    this.operations = operations;
+    this.schema = schema;
+  }
+  get aiTracingStrategy() {
+    return {
+      preferred: "batch-with-updates",
+      supported: ["batch-with-updates", "insert-only"]
+    };
+  }
+  async createAISpan(span) {
+    try {
+      const startedAt = span.startedAt instanceof Date ? span.startedAt.toISOString() : span.startedAt;
+      const endedAt = span.endedAt instanceof Date ? span.endedAt.toISOString() : span.endedAt;
+      const record = {
+        ...span,
+        startedAt,
+        endedAt,
+        startedAtZ: startedAt,
+        endedAtZ: endedAt
+        // Note: createdAt/updatedAt will be set by database triggers
+      };
+      return this.operations.insert({ tableName: TABLE_AI_SPANS, record });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_CREATE_AI_SPAN_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: {
+            spanId: span.spanId,
+            traceId: span.traceId,
+            spanType: span.spanType,
+            spanName: span.name
+          }
+        },
+        error
+      );
+    }
+  }
+  async getAITrace(traceId) {
+    try {
+      const tableName = getTableName({
+        indexName: TABLE_AI_SPANS,
+        schemaName: getSchemaName(this.schema)
+      });
+      const spans = await this.client.manyOrNone(
+        `SELECT
+          "traceId", "spanId", "parentSpanId", "name", "scope", "spanType",
+          "attributes", "metadata", "links", "input", "output", "error", "isEvent",
+          "startedAtZ" as "startedAt", "endedAtZ" as "endedAt",
+          "createdAtZ" as "createdAt", "updatedAtZ" as "updatedAt"
+        FROM ${tableName}
+        WHERE "traceId" = $1
+        ORDER BY "startedAtZ" DESC`,
+        [traceId]
+      );
+      if (!spans || spans.length === 0) {
+        return null;
+      }
+      return {
+        traceId,
+        spans: spans.map(
+          (span) => transformFromSqlRow({
+            tableName: TABLE_AI_SPANS,
+            sqlRow: span
+          })
+        )
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_GET_AI_TRACE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: {
+            traceId
+          }
+        },
+        error
+      );
+    }
+  }
+  async updateAISpan({
+    spanId,
+    traceId,
+    updates
+  }) {
+    try {
+      const data = { ...updates };
+      if (data.endedAt instanceof Date) {
+        data.endedAt = data.endedAt.toISOString();
+      }
+      if (data.startedAt instanceof Date) {
+        data.startedAt = data.startedAt.toISOString();
+      }
+      await this.operations.update({
+        tableName: TABLE_AI_SPANS,
+        keys: { spanId, traceId },
+        data
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_UPDATE_AI_SPAN_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: {
+            spanId,
+            traceId
+          }
+        },
+        error
+      );
+    }
+  }
+  async getAITracesPaginated({
+    filters,
+    pagination
+  }) {
+    const page = pagination?.page ?? 0;
+    const perPage = pagination?.perPage ?? 10;
+    const { entityId, entityType, ...actualFilters } = filters || {};
+    const filtersWithDateRange = {
+      ...actualFilters,
+      ...buildDateRangeFilter(pagination?.dateRange, "startedAtZ"),
+      parentSpanId: null
+      // Only get root spans for traces
+    };
+    const whereClause = prepareWhereClause(filtersWithDateRange);
+    let actualWhereClause = whereClause.sql;
+    let currentParamIndex = whereClause.args.length + 1;
+    if (entityId && entityType) {
+      let name = "";
+      if (entityType === "workflow") {
+        name = `workflow run: '${entityId}'`;
+      } else if (entityType === "agent") {
+        name = `agent run: '${entityId}'`;
+      } else {
+        const error = new MastraError({
+          id: "PG_STORE_GET_AI_TRACES_PAGINATED_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: {
+            entityType
+          },
+          text: `Cannot filter by entity type: ${entityType}`
+        });
+        this.logger?.trackException(error);
+        throw error;
+      }
+      whereClause.args.push(name);
+      const statement = `"name" = $${currentParamIndex++}`;
+      if (actualWhereClause) {
+        actualWhereClause += ` AND ${statement}`;
+      } else {
+        actualWhereClause = ` WHERE ${statement}`;
+      }
+    }
+    const tableName = getTableName({
+      indexName: TABLE_AI_SPANS,
+      schemaName: getSchemaName(this.schema)
+    });
+    try {
+      const countResult = await this.client.oneOrNone(
+        `SELECT COUNT(*) FROM ${tableName}${actualWhereClause}`,
+        whereClause.args
+      );
+      const count = Number(countResult?.count ?? 0);
+      if (count === 0) {
+        return {
+          pagination: {
+            total: 0,
+            page,
+            perPage,
+            hasMore: false
+          },
+          spans: []
+        };
+      }
+      const spans = await this.client.manyOrNone(
+        `SELECT
+          "traceId", "spanId", "parentSpanId", "name", "scope", "spanType",
+          "attributes", "metadata", "links", "input", "output", "error", "isEvent",
+          "startedAtZ" as "startedAt", "endedAtZ" as "endedAt",
+          "createdAtZ" as "createdAt", "updatedAtZ" as "updatedAt"
+        FROM ${tableName}${actualWhereClause}
+        ORDER BY "startedAtZ" DESC
+        LIMIT $${currentParamIndex} OFFSET $${currentParamIndex + 1}`,
+        [...whereClause.args, perPage, page * perPage]
+      );
+      return {
+        pagination: {
+          total: count,
+          page,
+          perPage,
+          hasMore: spans.length === perPage
+        },
+        spans: spans.map(
+          (span) => transformFromSqlRow({
+            tableName: TABLE_AI_SPANS,
+            sqlRow: span
+          })
+        )
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_GET_AI_TRACES_PAGINATED_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER
+        },
+        error
+      );
+    }
+  }
+  async batchCreateAISpans(args) {
+    try {
+      const records = args.records.map((record) => {
+        const startedAt = record.startedAt instanceof Date ? record.startedAt.toISOString() : record.startedAt;
+        const endedAt = record.endedAt instanceof Date ? record.endedAt.toISOString() : record.endedAt;
+        return {
+          ...record,
+          startedAt,
+          endedAt,
+          startedAtZ: startedAt,
+          endedAtZ: endedAt
+          // Note: createdAt/updatedAt will be set by database triggers
+        };
+      });
+      return this.operations.batchInsert({
+        tableName: TABLE_AI_SPANS,
+        records
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_BATCH_CREATE_AI_SPANS_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER
+        },
+        error
+      );
+    }
+  }
+  async batchUpdateAISpans(args) {
+    try {
+      return this.operations.batchUpdate({
+        tableName: TABLE_AI_SPANS,
+        updates: args.records.map((record) => {
+          const data = {
+            ...record.updates
+          };
+          if (data.endedAt instanceof Date) {
+            const endedAt = data.endedAt.toISOString();
+            data.endedAt = endedAt;
+            data.endedAtZ = endedAt;
+          }
+          if (data.startedAt instanceof Date) {
+            const startedAt = data.startedAt.toISOString();
+            data.startedAt = startedAt;
+            data.startedAtZ = startedAt;
+          }
+          return {
+            keys: { spanId: record.spanId, traceId: record.traceId },
+            data
+          };
+        })
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_BATCH_UPDATE_AI_SPANS_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER
+        },
+        error
+      );
+    }
+  }
+  async batchDeleteAITraces(args) {
+    try {
+      const tableName = getTableName({
+        indexName: TABLE_AI_SPANS,
+        schemaName: getSchemaName(this.schema)
+      });
+      const placeholders = args.traceIds.map((_, i) => `$${i + 1}`).join(", ");
+      await this.client.none(`DELETE FROM ${tableName} WHERE "traceId" IN (${placeholders})`, args.traceIds);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "PG_STORE_BATCH_DELETE_AI_TRACES_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER
+        },
+        error
+      );
+    }
+  }
+};
 var StoreOperationsPG = class extends StoreOperations {
   client;
   schemaName;
@@ -2211,6 +2584,45 @@ var StoreOperationsPG = class extends StoreOperations {
     );
     return !!result;
   }
+  /**
+   * Prepares values for insertion, handling JSONB columns by stringifying them
+   */
+  prepareValuesForInsert(record, tableName) {
+    return Object.entries(record).map(([key, value]) => {
+      const schema = TABLE_SCHEMAS[tableName];
+      const columnSchema = schema?.[key];
+      if (columnSchema?.type === "jsonb" && value !== null && typeof value === "object") {
+        return JSON.stringify(value);
+      }
+      return value;
+    });
+  }
+  /**
+   * Adds timestamp Z columns to a record if timestamp columns exist
+   */
+  addTimestampZColumns(record) {
+    if (record.createdAt) {
+      record.createdAtZ = record.createdAt;
+    }
+    if (record.created_at) {
+      record.created_atZ = record.created_at;
+    }
+    if (record.updatedAt) {
+      record.updatedAtZ = record.updatedAt;
+    }
+  }
+  /**
+   * Prepares a value for database operations, handling Date objects and JSON serialization
+   */
+  prepareValue(value) {
+    if (value instanceof Date) {
+      return value.toISOString();
+    } else if (typeof value === "object" && value !== null) {
+      return JSON.stringify(value);
+    } else {
+      return value;
+    }
+  }
   async setupSchema() {
     if (!this.schemaName || this.schemaSetupComplete) {
       return;
@@ -2254,18 +2666,10 @@ var StoreOperationsPG = class extends StoreOperations {
   }
   async insert({ tableName, record }) {
     try {
-      if (record.createdAt) {
-        record.createdAtZ = record.createdAt;
-      }
-      if (record.created_at) {
-        record.created_atZ = record.created_at;
-      }
-      if (record.updatedAt) {
-        record.updatedAtZ = record.updatedAt;
-      }
+      this.addTimestampZColumns(record);
       const schemaName = getSchemaName(this.schemaName);
       const columns = Object.keys(record).map((col) => parseSqlIdentifier(col, "column name"));
-      const values = Object.values(record);
+      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})`,
@@ -2360,6 +2764,9 @@ var StoreOperationsPG = class extends StoreOperations {
         schema,
         ifNotExists: timeZColumnNames
       });
+      if (tableName === TABLE_AI_SPANS) {
+        await this.setupTimestampTriggers(tableName);
+      }
     } catch (error) {
       throw new MastraError(
         {
@@ -2374,6 +2781,48 @@ var StoreOperationsPG = class extends StoreOperations {
       );
     }
   }
+  /**
+   * Set up timestamp triggers for a table to automatically manage createdAt/updatedAt
+   */
+  async setupTimestampTriggers(tableName) {
+    const fullTableName = getTableName({ indexName: tableName, schemaName: getSchemaName(this.schemaName) });
+    try {
+      const triggerSQL = `
+        -- Create or replace the trigger function
+        CREATE OR REPLACE FUNCTION trigger_set_timestamps()
+        RETURNS TRIGGER AS $$
+        BEGIN
+            IF TG_OP = 'INSERT' THEN
+                NEW."createdAt" = NOW();
+                NEW."updatedAt" = NOW();
+                NEW."createdAtZ" = NOW();
+                NEW."updatedAtZ" = NOW();
+            ELSIF TG_OP = 'UPDATE' THEN
+                NEW."updatedAt" = NOW();
+                NEW."updatedAtZ" = NOW();
+                -- Prevent createdAt from being changed
+                NEW."createdAt" = OLD."createdAt";
+                NEW."createdAtZ" = OLD."createdAtZ";
+            END IF;
+            RETURN NEW;
+        END;
+        $$ LANGUAGE plpgsql;
+
+        -- Drop existing trigger if it exists
+        DROP TRIGGER IF EXISTS ${tableName}_timestamps ON ${fullTableName};
+
+        -- Create the trigger
+        CREATE TRIGGER ${tableName}_timestamps
+            BEFORE INSERT OR UPDATE ON ${fullTableName}
+            FOR EACH ROW
+            EXECUTE FUNCTION trigger_set_timestamps();
+      `;
+      await this.client.none(triggerSQL);
+      this.logger?.debug?.(`Set up timestamp triggers for table ${fullTableName}`);
+    } catch (error) {
+      this.logger?.warn?.(`Failed to set up timestamp triggers for ${fullTableName}:`, error);
+    }
+  }
   /**
    * Alters table schema to add columns if they don't exist
    * @param tableName Name of the table
@@ -2516,8 +2965,8 @@ var StoreOperationsPG = class extends StoreOperations {
         schemaName: getSchemaName(this.schemaName)
       });
       const indexExists = await this.client.oneOrNone(
-        `SELECT 1 FROM pg_indexes 
-         WHERE indexname = $1 
+        `SELECT 1 FROM pg_indexes
+         WHERE indexname = $1
          AND schemaname = $2`,
         [name, schemaName]
       );
@@ -2574,8 +3023,8 @@ var StoreOperationsPG = class extends StoreOperations {
     try {
       const schemaName = this.schemaName || "public";
       const indexExists = await this.client.oneOrNone(
-        `SELECT 1 FROM pg_indexes 
-         WHERE indexname = $1 
+        `SELECT 1 FROM pg_indexes
+         WHERE indexname = $1
          AND schemaname = $2`,
         [indexName, schemaName]
       );
@@ -2608,7 +3057,7 @@ var StoreOperationsPG = class extends StoreOperations {
       let params;
       if (tableName) {
         query = `
-          SELECT 
+          SELECT
             i.indexname as name,
             i.tablename as table,
             i.indexdef as definition,
@@ -2619,14 +3068,14 @@ var StoreOperationsPG = class extends StoreOperations {
           JOIN pg_class c ON c.relname = i.indexname AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = i.schemaname)
           JOIN pg_index ix ON ix.indexrelid = c.oid
           JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = ANY(ix.indkey)
-          WHERE i.schemaname = $1 
+          WHERE i.schemaname = $1
           AND i.tablename = $2
           GROUP BY i.indexname, i.tablename, i.indexdef, ix.indisunique, c.oid
         `;
         params = [schemaName, tableName];
       } else {
         query = `
-          SELECT 
+          SELECT
             i.indexname as name,
             i.tablename as table,
             i.indexdef as definition,
@@ -2705,6 +3154,33 @@ var StoreOperationsPG = class extends StoreOperations {
           name: `${schemaPrefix}mastra_evals_agent_name_created_at_idx`,
           table: TABLE_EVALS,
           columns: ["agent_name", "created_at DESC"]
+        },
+        // Composite index for scores (filter + sort)
+        {
+          name: `${schemaPrefix}mastra_scores_trace_id_span_id_created_at_idx`,
+          table: TABLE_SCORERS,
+          columns: ["trace_id", "span_id", "created_at DESC"]
+        },
+        // AI Spans indexes for optimal trace querying
+        {
+          name: `${schemaPrefix}mastra_ai_spans_traceid_startedat_idx`,
+          table: TABLE_AI_SPANS,
+          columns: ["traceId", "startedAt DESC"]
+        },
+        {
+          name: `${schemaPrefix}mastra_ai_spans_parentspanid_startedat_idx`,
+          table: TABLE_AI_SPANS,
+          columns: ["parentSpanId", "startedAt DESC"]
+        },
+        {
+          name: `${schemaPrefix}mastra_ai_spans_name_idx`,
+          table: TABLE_AI_SPANS,
+          columns: ["name"]
+        },
+        {
+          name: `${schemaPrefix}mastra_ai_spans_spantype_startedat_idx`,
+          table: TABLE_AI_SPANS,
+          columns: ["spanType", "startedAt DESC"]
         }
       ];
       for (const indexOptions of indexes) {
@@ -2732,7 +3208,7 @@ var StoreOperationsPG = class extends StoreOperations {
     try {
       const schemaName = this.schemaName || "public";
       const query = `
-        SELECT 
+        SELECT
           i.indexname as name,
           i.tablename as table,
           i.indexdef as definition,
@@ -2749,7 +3225,7 @@ var StoreOperationsPG = class extends StoreOperations {
         JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = ANY(ix.indkey)
         JOIN pg_am am ON c.relam = am.oid
         LEFT JOIN pg_stat_user_indexes s ON s.indexrelname = i.indexname AND s.schemaname = i.schemaname
-        WHERE i.schemaname = $1 
+        WHERE i.schemaname = $1
         AND i.indexname = $2
         GROUP BY i.indexname, i.tablename, i.indexdef, ix.indisunique, c.oid, am.amname, s.idx_scan, s.idx_tup_read, s.idx_tup_fetch
       `;
@@ -2790,6 +3266,121 @@ var StoreOperationsPG = class extends StoreOperations {
       );
     }
   }
+  /**
+   * Update a single record in the database
+   */
+  async update({
+    tableName,
+    keys,
+    data
+  }) {
+    try {
+      const setColumns = [];
+      const setValues = [];
+      let paramIndex = 1;
+      Object.entries(data).forEach(([key, value]) => {
+        const parsedKey = parseSqlIdentifier(key, "column name");
+        setColumns.push(`"${parsedKey}" = $${paramIndex++}`);
+        setValues.push(this.prepareValue(value));
+      });
+      const whereConditions = [];
+      const whereValues = [];
+      Object.entries(keys).forEach(([key, value]) => {
+        const parsedKey = parseSqlIdentifier(key, "column name");
+        whereConditions.push(`"${parsedKey}" = $${paramIndex++}`);
+        whereValues.push(this.prepareValue(value));
+      });
+      const tableName_ = getTableName({
+        indexName: tableName,
+        schemaName: getSchemaName(this.schemaName)
+      });
+      const sql = `UPDATE ${tableName_} SET ${setColumns.join(", ")} WHERE ${whereConditions.join(" AND ")}`;
+      const values = [...setValues, ...whereValues];
+      await this.client.none(sql, values);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_UPDATE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName
+          }
+        },
+        error
+      );
+    }
+  }
+  /**
+   * Update multiple records in a single batch transaction
+   */
+  async batchUpdate({
+    tableName,
+    updates
+  }) {
+    try {
+      await this.client.query("BEGIN");
+      for (const { keys, data } of updates) {
+        await this.update({ tableName, keys, data });
+      }
+      await this.client.query("COMMIT");
+    } catch (error) {
+      await this.client.query("ROLLBACK");
+      throw new MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_BATCH_UPDATE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+            numberOfRecords: updates.length
+          }
+        },
+        error
+      );
+    }
+  }
+  /**
+   * Delete multiple records by keys
+   */
+  async batchDelete({ tableName, keys }) {
+    try {
+      if (keys.length === 0) {
+        return;
+      }
+      const tableName_ = getTableName({
+        indexName: tableName,
+        schemaName: getSchemaName(this.schemaName)
+      });
+      await this.client.tx(async (t) => {
+        for (const keySet of keys) {
+          const conditions = [];
+          const values = [];
+          let paramIndex = 1;
+          Object.entries(keySet).forEach(([key, value]) => {
+            const parsedKey = parseSqlIdentifier(key, "column name");
+            conditions.push(`"${parsedKey}" = $${paramIndex++}`);
+            values.push(value);
+          });
+          const sql = `DELETE FROM ${tableName_} WHERE ${conditions.join(" AND ")}`;
+          await t.none(sql, values);
+        }
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_BATCH_DELETE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            tableName,
+            numberOfRecords: keys.length
+          }
+        },
+        error
+      );
+    }
+  }
 };
 function transformScoreRow(row) {
   return {
@@ -2903,6 +3494,26 @@ var ScoresPG = class extends ScoresStorage {
     }
   }
   async saveScore(score) {
+    let parsedScore;
+    try {
+      parsedScore = saveScorePayloadSchema.parse(score);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_SAVE_SCORE_FAILED_INVALID_SCORE_PAYLOAD",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: {
+            scorer: score.scorer.name,
+            entityId: score.entityId,
+            entityType: score.entityType,
+            traceId: score.traceId || "",
+            spanId: score.spanId || ""
+          }
+        },
+        error
+      );
+    }
     try {
       const id = crypto.randomUUID();
       const {
@@ -2916,7 +3527,7 @@ var ScoresPG = class extends ScoresStorage {
         runtimeContext,
         entity,
         ...rest
-      } = score;
+      } = parsedScore;
       await this.operations.insert({
         tableName: TABLE_SCORERS,
         record: {
@@ -3037,6 +3648,44 @@ var ScoresPG = class extends ScoresStorage {
       );
     }
   }
+  async getScoresBySpan({
+    traceId,
+    spanId,
+    pagination
+  }) {
+    try {
+      const tableName = getTableName({ indexName: TABLE_SCORERS, schemaName: this.schema });
+      const countSQLResult = await this.client.oneOrNone(
+        `SELECT COUNT(*) as count FROM ${tableName} WHERE "traceId" = $1 AND "spanId" = $2`,
+        [traceId, spanId]
+      );
+      const total = Number(countSQLResult?.count ?? 0);
+      const result = await this.client.manyOrNone(
+        `SELECT * FROM ${tableName} WHERE "traceId" = $1 AND "spanId" = $2 ORDER BY "createdAt" DESC LIMIT $3 OFFSET $4`,
+        [traceId, spanId, pagination.perPage + 1, pagination.page * pagination.perPage]
+      );
+      const hasMore = result.length > pagination.perPage;
+      const scores = result.slice(0, pagination.perPage).map((row) => transformScoreRow(row)) ?? [];
+      return {
+        scores,
+        pagination: {
+          total,
+          page: pagination.page,
+          perPage: pagination.perPage,
+          hasMore
+        }
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "MASTRA_STORAGE_PG_STORE_GET_SCORES_BY_SPAN_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
+  }
 };
 var TracesPG = class extends TracesStorage {
   client;
@@ -3432,7 +4081,8 @@ var PostgresStore = class extends MastraStorage {
         this.#config = {
           connectionString: config.connectionString,
           max: config.max,
-          idleTimeoutMillis: config.idleTimeoutMillis
+          idleTimeoutMillis: config.idleTimeoutMillis,
+          ssl: config.ssl
         };
       } else if (isCloudSqlConfig(config)) {
         this.#config = {
@@ -3452,11 +4102,9 @@ var PostgresStore = class extends MastraStorage {
           idleTimeoutMillis: config.idleTimeoutMillis
         };
       } else {
-        this.#config = {
-          ...config,
-          max: config.max,
-          idleTimeoutMillis: config.idleTimeoutMillis
-        };
+        throw new Error(
+          "PostgresStore: invalid config. Provide either {connectionString}, {host,port,database,user,password}, or a pg ClientConfig (e.g., Cloud SQL connector with `stream`)."
+        );
       }
       this.stores = {};
     } catch (e) {
@@ -3484,13 +4132,15 @@ var PostgresStore = class extends MastraStorage {
       const workflows = new WorkflowsPG({ client: this.#db, operations, schema: this.schema });
       const legacyEvals = new LegacyEvalsPG({ client: this.#db, schema: this.schema });
       const memory = new MemoryPG({ client: this.#db, schema: this.schema, operations });
+      const observability = new ObservabilityPG({ client: this.#db, operations, schema: this.schema });
       this.stores = {
         operations,
         scores,
         traces,
         workflows,
         legacyEvals,
-        memory
+        memory,
+        observability
       };
       await super.init();
       try {
@@ -3529,8 +4179,9 @@ var PostgresStore = class extends MastraStorage {
       hasColumn: true,
       createTable: true,
       deleteMessages: true,
-      aiTracing: false,
-      indexManagement: true
+      aiTracing: true,
+      indexManagement: true,
+      getScoresBySpan: true
     };
   }
   /** @deprecated use getEvals instead */
@@ -3696,11 +4347,95 @@ var PostgresStore = class extends MastraStorage {
   async close() {
     this.pgp.end();
   }
+  /**
+   * AI Tracing / Observability
+   */
+  async createAISpan(span) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.createAISpan(span);
+  }
+  async updateAISpan({
+    spanId,
+    traceId,
+    updates
+  }) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.updateAISpan({ spanId, traceId, updates });
+  }
+  async getAITrace(traceId) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.getAITrace(traceId);
+  }
+  async getAITracesPaginated(args) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.getAITracesPaginated(args);
+  }
+  async batchCreateAISpans(args) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.batchCreateAISpans(args);
+  }
+  async batchUpdateAISpans(args) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.batchUpdateAISpans(args);
+  }
+  async batchDeleteAITraces(args) {
+    if (!this.stores.observability) {
+      throw new MastraError({
+        id: "PG_STORE_OBSERVABILITY_NOT_INITIALIZED",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: "Observability storage is not initialized"
+      });
+    }
+    return this.stores.observability.batchDeleteAITraces(args);
+  }
   /**
    * Scorers
    */
-  async getScoreById({ id: _id }) {
-    return this.stores.scores.getScoreById({ id: _id });
+  async getScoreById({ id }) {
+    return this.stores.scores.getScoreById({ id });
   }
   async getScoresByScorerId({
     scorerId,
@@ -3711,26 +4446,33 @@ var PostgresStore = class extends MastraStorage {
   }) {
     return this.stores.scores.getScoresByScorerId({ scorerId, pagination, entityId, entityType, source });
   }
-  async saveScore(_score) {
-    return this.stores.scores.saveScore(_score);
+  async saveScore(score) {
+    return this.stores.scores.saveScore(score);
   }
   async getScoresByRunId({
-    runId: _runId,
-    pagination: _pagination
+    runId,
+    pagination
   }) {
-    return this.stores.scores.getScoresByRunId({ runId: _runId, pagination: _pagination });
+    return this.stores.scores.getScoresByRunId({ runId, pagination });
   }
   async getScoresByEntityId({
-    entityId: _entityId,
-    entityType: _entityType,
-    pagination: _pagination
+    entityId,
+    entityType,
+    pagination
   }) {
     return this.stores.scores.getScoresByEntityId({
-      entityId: _entityId,
-      entityType: _entityType,
-      pagination: _pagination
+      entityId,
+      entityType,
+      pagination
     });
   }
+  async getScoresBySpan({
+    traceId,
+    spanId,
+    pagination
+  }) {
+    return this.stores.scores.getScoresBySpan({ traceId, spanId, pagination });
+  }
 };
 
 // src/vector/prompt.ts