@mastra/pg 1.22.3 → 1.23.0-alpha.1

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.22.3"
+  version: "1.23.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.3",
+  "version": "1.23.0-alpha.1",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-deployment-workers.md

@@ -285,6 +285,8 @@ curl http://localhost:4111/api/agents
 
 ### Kubernetes
 
+> **Helm:** On Kubernetes, the [`mastra-projects` Helm chart](https://mastra.ai/integrations/deploy/kubernetes-helm) renders these deployments for you, with the workers on the same image and environment as the server. It also refuses to install combinations that would run every worker twice. The manifests below are for writing them by hand.
+
 Create separate Deployments for the API, orchestration worker, scheduler worker, and background task worker. Use the same image and Secret for each Deployment. Set only the role-specific environment variables directly on each container.
 
 The orchestration worker Deployment has the following shape:
@@ -391,4 +393,5 @@ If the API crashes while a step is executing, that work can be lost and the work
 - [Workers reference](https://mastra.ai/reference/workers/overview): Details about worker environment variables and types, with a list of supported storage backends
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
+- [Kubernetes (Helm)](https://mastra.ai/integrations/deploy/kubernetes-helm): Deploy worker roles with the official chart
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): Declare cron schedules on workflows

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

@@ -205,6 +205,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [libSQL](https://mastra.ai/integrations/databases/libsql)
 - [Mastra](https://mastra.ai/docs/mastra-platform/database)
 - [MongoDB](https://mastra.ai/integrations/databases/mongodb)
+- [MySQL](https://mastra.ai/integrations/databases/mysql)
 - [MSSQL](https://mastra.ai/integrations/databases/mssql)
 - [Neon Postgres](https://mastra.ai/integrations/databases/neon)
 - [OracleDB](https://mastra.ai/integrations/databases/oracledb)

package/dist/docs/references/reference-rag-metadata-filters.md

@@ -176,6 +176,7 @@ const results = await store.query({
 - Special handling for null and empty values
 - Vector-specific filtering capabilities
 - Datetime values must be in RFC 3339 format
+- `$regex` is translated to Qdrant's full-text match, which matches whole tokens rather than arbitrary regular expressions or substrings (e.g. `{ name: { $regex: "item" } }` doesn't match `"item1"`). On unindexed payload fields, Qdrant versions before v1.19.1 fall back to substring matching
 
 ### Upstash
 

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let _mastra_core_error = require("@mastra/core/error");
 let _mastra_core_storage = require("@mastra/core/storage");
+_mastra_core_storage = __toESM(_mastra_core_storage, 1);
 let _mastra_core_utils = require("@mastra/core/utils");
 let _mastra_core_vector = require("@mastra/core/vector");
 let async_mutex = require("async-mutex");
@@ -12169,12 +12170,20 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 			};
 			const lastBufferedAtTime = input.lastBufferedAtTime ? input.lastBufferedAtTime.toISOString() : null;
 			if ((await this.#db.client.query(`UPDATE ${tableName} SET
-          "bufferedObservationChunks" = COALESCE("bufferedObservationChunks", '[]'::jsonb) || $1::jsonb,
-          "lastBufferedAtTime" = COALESCE($2, "lastBufferedAtTime"),
-          "updatedAt" = $3,
-          "updatedAtZ" = $4
-        WHERE id = $5`, [
+          "bufferedObservationChunks" = CASE
+            WHEN EXISTS (
+              SELECT 1
+              FROM jsonb_array_elements(COALESCE("bufferedObservationChunks", '[]'::jsonb)) AS chunk
+              WHERE chunk->>'cycleId' = $2
+            ) THEN COALESCE("bufferedObservationChunks", '[]'::jsonb)
+            ELSE COALESCE("bufferedObservationChunks", '[]'::jsonb) || $1::jsonb
+          END,
+          "lastBufferedAtTime" = COALESCE($3, "lastBufferedAtTime"),
+          "updatedAt" = $4,
+          "updatedAtZ" = $5
+        WHERE id = $6`, [
 				JSON.stringify([newChunk]),
+				input.chunk.cycleId,
 				lastBufferedAtTime,
 				nowStr,
 				nowStr,
@@ -13504,6 +13513,7 @@ var ObservabilityPG = class ObservabilityPG extends _mastra_core_storage.Observa
 		}
 	}
 	async batchDeleteTraces(args) {
+		this.assertUnscopedBatchDeleteTraces(args);
 		try {
 			const tableName = getTableName$5({
 				indexName: _mastra_core_storage.TABLE_SPANS,
@@ -16739,6 +16749,304 @@ async function getScorePercentiles(client, schema, args) {
 	return { series: percentileSeriesFromRows(await client.manyOrNone(sql, acc.params), args.percentiles) };
 }
 //#endregion
+//#region src/storage/domains/observability/v-next/trace-query.ts
+const TRACE_STATUS_SQL = `CASE WHEN r."error" IS NOT NULL THEN 'error' ELSE 'success' END`;
+const TRACE_FIELDS = {
+	traceId: "r.\"traceId\"",
+	threadId: "r.\"threadId\"",
+	resourceId: "r.\"resourceId\"",
+	startedAt: "r.\"startedAt\"",
+	endedAt: "r.\"endedAt\"",
+	entityName: "r.\"entityName\"",
+	entityType: "r.\"entityType\"",
+	environment: "r.\"environment\"",
+	status: TRACE_STATUS_SQL
+};
+const SPAN_FIELDS = {
+	spanType: "s.\"spanType\"",
+	error: "s.\"error\""
+};
+const SCORE_FIELDS = {
+	scorerId: "s.\"scorerId\"",
+	score: "s.\"score\""
+};
+const TRACE_SELECT = `
+  r."traceId" AS "traceId",
+  r."spanId" AS "rootSpanId",
+  r."threadId" AS "threadId",
+  r."resourceId" AS "resourceId",
+  r."startedAt" AS "startedAt",
+  r."endedAt" AS "endedAt",
+  r."entityName" AS "entityName",
+  r."entityType" AS "entityType",
+  r."environment" AS "environment",
+  ${TRACE_STATUS_SQL} AS "status"`;
+function fieldSql(registry, field) {
+	const sql = registry[field];
+	if (sql === void 0) throw new Error(`Unsupported trusted trace-query field: ${field}`);
+	return sql;
+}
+function placeholders(values, offset) {
+	return values.map((_, index) => `$${offset + index}`).join(", ");
+}
+function compileScalarPredicate(predicate, registry, parameterOffset) {
+	if (predicate.type === "boolean") {
+		const values = [];
+		return {
+			sql: predicate.args.map((arg) => {
+				const compiled = compileScalarPredicate(arg, registry, parameterOffset + values.length);
+				values.push(...compiled.values);
+				return `(${compiled.sql})`;
+			}).join(predicate.operator === "and" ? " AND " : " OR "),
+			values
+		};
+	}
+	if (predicate.type === "not") {
+		const compiled = compileScalarPredicate(predicate.arg, registry, parameterOffset);
+		return {
+			sql: `NOT (${compiled.sql})`,
+			values: compiled.values
+		};
+	}
+	const field = fieldSql(registry, predicate.field);
+	if (predicate.type === "presence") return {
+		sql: `${field} IS ${predicate.operator === "exists" ? "NOT " : ""}NULL`,
+		values: []
+	};
+	if (predicate.type === "membership") {
+		const list = placeholders(predicate.values, parameterOffset);
+		if (predicate.operator === "in") return {
+			sql: `${field} IS NOT NULL AND ${field} IN (${list})`,
+			values: predicate.values
+		};
+		return {
+			sql: `${field} IS NULL OR ${field} NOT IN (${list})`,
+			values: predicate.values
+		};
+	}
+	const parameter = `$${parameterOffset}`;
+	const operators = {
+		lt: "<",
+		lte: "<=",
+		gt: ">",
+		gte: ">="
+	};
+	if (predicate.operator === "eq") return {
+		sql: `${field} IS NOT DISTINCT FROM ${parameter}`,
+		values: [predicate.value]
+	};
+	if (predicate.operator === "ne") return {
+		sql: `${field} IS DISTINCT FROM ${parameter}`,
+		values: [predicate.value]
+	};
+	const operator = operators[predicate.operator];
+	if (operator === void 0) throw new Error(`Unsupported trusted trace-query operator: ${predicate.operator}`);
+	return {
+		sql: `${field} IS NOT NULL AND ${field} ${operator} ${parameter}`,
+		values: [predicate.value]
+	};
+}
+function latestRootPredicate$1(spanTable) {
+	return `NOT EXISTS (
+    SELECT 1 FROM ${spanTable} newer
+    WHERE newer."traceId" = r."traceId"
+      AND newer."parentSpanId" IS NULL
+      AND newer."cursorId" > r."cursorId"
+  )`;
+}
+function latestSpanPredicate$1(spanTable) {
+	return `NOT EXISTS (
+    SELECT 1 FROM ${spanTable} newer
+    WHERE newer."traceId" = s."traceId"
+      AND newer."spanId" = s."spanId"
+      AND (newer."isPending" < s."isPending" OR (newer."isPending" = s."isPending" AND newer."cursorId" > s."cursorId"))
+  )`;
+}
+function latestScorePredicate(scoreTable) {
+	return `NOT EXISTS (
+    SELECT 1 FROM ${scoreTable} newer
+    WHERE newer."scoreId" = s."scoreId"
+      AND newer."cursorId" > s."cursorId"
+  )`;
+}
+function collectRelationCollections(predicate, collections = /* @__PURE__ */ new Set()) {
+	if (!predicate) return collections;
+	if (predicate.type === "relation") collections.add(predicate.collection);
+	else if (predicate.type === "boolean") for (const arg of predicate.args) collectRelationCollections(arg, collections);
+	else if (predicate.type === "not") collectRelationCollections(predicate.arg, collections);
+	return collections;
+}
+function compilePredicate(predicate, parameterOffset) {
+	if (predicate.type === "relation") {
+		const registry = predicate.collection === "spans" ? SPAN_FIELDS : SCORE_FIELDS;
+		const compiled = compileScalarPredicate(predicate.predicate, registry, parameterOffset);
+		const existence = `EXISTS (
+      SELECT 1 FROM ${predicate.collection === "spans" ? "current_spans" : "current_scores"} s
+      WHERE s."traceId" = r."traceId"
+        AND (${compiled.sql})
+    )`;
+		return {
+			sql: predicate.quantifier === "some" ? existence : `NOT ${existence}`,
+			values: compiled.values
+		};
+	}
+	if (predicate.type === "boolean") {
+		const values = [];
+		return {
+			sql: predicate.args.map((arg) => {
+				const compiled = compilePredicate(arg, parameterOffset + values.length);
+				values.push(...compiled.values);
+				return `(${compiled.sql})`;
+			}).join(predicate.operator === "and" ? " AND " : " OR "),
+			values
+		};
+	}
+	if (predicate.type === "not") {
+		const compiled = compilePredicate(predicate.arg, parameterOffset);
+		return {
+			sql: `NOT (${compiled.sql})`,
+			values: compiled.values
+		};
+	}
+	return compileScalarPredicate(predicate, TRACE_FIELDS, parameterOffset);
+}
+function compilePostgresTraceQuery(schema, plan) {
+	const spanTable = qualifiedTable(schema, TABLE_SPAN_EVENTS);
+	const scoreTable = qualifiedTable(schema, TABLE_SCORE_EVENTS);
+	const values = [plan.timeRange.from, plan.timeRange.to];
+	const relationCollections = collectRelationCollections(plan.where);
+	const ctes = [`root_scope AS MATERIALIZED (
+    SELECT *
+    FROM ${spanTable} r
+    WHERE ${[
+		`r."parentSpanId" IS NULL`,
+		latestRootPredicate$1(spanTable),
+		`NOT r."isPending"`,
+		`r."endedAt" IS NOT NULL`,
+		`r."startedAt" >= $1`,
+		`r."startedAt" < $2`
+	].join("\n      AND ")}
+  )`];
+	if (relationCollections.has("spans")) ctes.push(`current_spans AS MATERIALIZED (
+    SELECT s."traceId", s."spanType", s."error"
+    FROM ${spanTable} s
+    WHERE s."traceId" IS NOT NULL
+      AND s."traceId" IN (SELECT "traceId" FROM root_scope)
+      AND ${latestSpanPredicate$1(spanTable)}
+  )`);
+	if (relationCollections.has("scores")) ctes.push(`current_scores AS MATERIALIZED (
+    SELECT s."traceId", s."scorerId", s."score"
+    FROM ${scoreTable} s
+    WHERE s."traceId" IS NOT NULL
+      AND s."traceId" IN (SELECT "traceId" FROM root_scope)
+      AND ${latestScorePredicate(scoreTable)}
+  )`);
+	let predicateSql = "TRUE";
+	if (plan.where) {
+		const predicate = compilePredicate(plan.where, values.length + 1);
+		predicateSql = predicate.sql;
+		values.push(...predicate.values);
+	}
+	ctes.push(`candidates AS (
+    SELECT ${TRACE_SELECT}
+    FROM root_scope r
+    WHERE ${predicateSql}
+  )`);
+	const candidates = `WITH ${ctes.join(",\n")}`;
+	if (plan.result === "groups") {
+		const pageCondition = plan.cursor ? `AND "threadId" > $${values.length + 1}` : "";
+		if (plan.cursor) values.push(plan.cursor.threadId);
+		values.push(plan.limit + 1);
+		return {
+			text: `${candidates}
+SELECT "threadId"
+FROM candidates
+WHERE "threadId" IS NOT NULL ${pageCondition}
+GROUP BY "threadId"
+ORDER BY "threadId" ASC
+LIMIT $${values.length}`,
+			values
+		};
+	}
+	const orderField = plan.orderBy.field === "startedAt" ? "\"startedAt\"" : "\"endedAt\"";
+	const direction = plan.orderBy.direction === "asc" ? "ASC" : "DESC";
+	let pageCondition = "";
+	if (plan.cursor) {
+		const comparison = plan.orderBy.direction === "asc" ? ">" : "<";
+		const sortParameter = `$${values.length + 1}`;
+		pageCondition = `WHERE (${orderField} ${comparison} ${sortParameter} OR (${orderField} = ${sortParameter} AND "traceId" > ${`$${values.length + 2}`}))`;
+		values.push(plan.cursor.sortValue, plan.cursor.traceId);
+	}
+	values.push(plan.limit + 1);
+	return {
+		text: `${candidates}
+SELECT *
+FROM candidates
+${pageCondition}
+ORDER BY ${orderField} ${direction}, "traceId" ASC
+LIMIT $${values.length}`,
+		values
+	};
+}
+function asIsoTimestamp$1(value) {
+	if (value === null || value === void 0) throw new Error("Trace query returned a null timestamp");
+	return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+function isPostgresStatementTimeout(error) {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate.code === "57014" && String(candidate.message ?? "").includes("statement timeout");
+}
+async function runWithPostgresTraceQueryTimeout(client, timeoutMs, execute) {
+	const resolvedTimeoutMs = _mastra_core_storage.resolveTraceQueryTimeoutMs(timeoutMs);
+	try {
+		return await client.tx(async (transaction) => {
+			await transaction.query(`SELECT set_config('statement_timeout', $1, true)`, [`${resolvedTimeoutMs}ms`]);
+			return execute(transaction);
+		});
+	} catch (error) {
+		if (isPostgresStatementTimeout(error)) throw new _mastra_core_storage.TraceQueryExecutionError();
+		throw error;
+	}
+}
+async function queryTraces(client, schema, plan, timeoutMs) {
+	const query = compilePostgresTraceQuery(schema, plan);
+	const rows = await runWithPostgresTraceQueryTimeout(client, timeoutMs, (transaction) => transaction.any(query.text, query.values));
+	const visibleRows = rows.slice(0, plan.limit);
+	if (plan.result === "groups") {
+		const groups = visibleRows.map((row) => ({ threadId: String(row.threadId) }));
+		const last = groups.at(-1);
+		return _mastra_core_storage.traceQueryResponseSchema.parse({
+			groups,
+			page: { next: rows.length > plan.limit && last ? _mastra_core_storage.encodeTraceQueryCursor(plan, {
+				result: "groups",
+				threadId: last.threadId
+			}) : null }
+		});
+	}
+	const traces = visibleRows.map((row) => ({
+		traceId: String(row.traceId),
+		rootSpanId: String(row.rootSpanId),
+		threadId: row.threadId == null ? null : String(row.threadId),
+		resourceId: row.resourceId == null ? null : String(row.resourceId),
+		startedAt: asIsoTimestamp$1(row.startedAt),
+		endedAt: asIsoTimestamp$1(row.endedAt),
+		entityName: row.entityName == null ? null : String(row.entityName),
+		entityType: row.entityType == null ? null : String(row.entityType),
+		environment: row.environment == null ? null : String(row.environment),
+		status: row.status
+	}));
+	const last = traces.at(-1);
+	return _mastra_core_storage.traceQueryResponseSchema.parse({
+		traces,
+		page: { next: rows.length > plan.limit && last ? _mastra_core_storage.encodeTraceQueryCursor(plan, {
+			result: "traces",
+			sortValue: last[plan.orderBy.field],
+			traceId: last.traceId
+		}) : null }
+	});
+}
+//#endregion
 //#region src/storage/domains/observability/v-next/traces.ts
 /**
 * Trace / branch list reads for the v-next Postgres observability domain.
@@ -17388,11 +17696,39 @@ async function getTraceLight(client, schema, args) {
 		spans: rows.map(rowToLightSpanRecord)
 	};
 }
+/**
+* Delete traces by traceId, cascading to trace-linked signal events
+* (metrics, logs, scores, feedback). Signal rows with a NULL traceId are
+* never affected. When the optional tenant scope (`organizationId` /
+* `resourceId`) is set, every DELETE additionally requires the row's tenant
+* columns to match.
+*/
 async function batchDeleteTraces(client, schema, args) {
 	if (args.traceIds.length === 0) return;
-	const span = qualifiedTable(schema, TABLE_SPAN_EVENTS);
+	const params = [...args.traceIds];
 	const placeholders = args.traceIds.map((_, i) => `$${i + 1}`).join(", ");
-	await client.query(`DELETE FROM ${span} WHERE "traceId" IN (${placeholders})`, args.traceIds);
+	let scopeCondition = "";
+	if (args.organizationId !== void 0) {
+		params.push(args.organizationId);
+		scopeCondition += ` AND "organizationId" = $${params.length}`;
+	}
+	if (args.resourceId !== void 0) {
+		params.push(args.resourceId);
+		scopeCondition += ` AND "resourceId" = $${params.length}`;
+	}
+	const tables = [
+		TABLE_SPAN_EVENTS,
+		TABLE_METRIC_EVENTS,
+		TABLE_LOG_EVENTS,
+		TABLE_SCORE_EVENTS,
+		TABLE_FEEDBACK_EVENTS
+	];
+	await client.tx(async (t) => {
+		for (const tableName of tables) {
+			const table = qualifiedTable(schema, tableName);
+			await t.query(`DELETE FROM ${table} WHERE "traceId" IN (${placeholders})${scopeCondition}`, params);
+		}
+	});
 }
 /** Truncate the span_events table. */
 async function dangerouslyClearTracing(client, schema) {
@@ -17425,7 +17761,7 @@ async function dangerouslyClearTracing(client, schema) {
 * Use it through `MastraCompositeStore` with a dedicated Postgres connection.
 */
 function wrapError(op, error, details) {
-	if (error instanceof _mastra_core_error.MastraError) throw error;
+	if (error instanceof _mastra_core_error.MastraError || error instanceof _mastra_core_storage.TraceQueryExecutionError) throw error;
 	throw new _mastra_core_error.MastraError({
 		id: (0, _mastra_core_storage.createStorageErrorId)("PG", op, "FAILED"),
 		domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -17438,6 +17774,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 	#schema;
 	#partitioning;
 	#discoveryConfig;
+	#traceQueryTimeoutMs;
 	#partitionMode;
 	constructor(config) {
 		super();
@@ -17446,6 +17783,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 		this.#schema = schemaName ?? "public";
 		this.#partitioning = config.partitioning ?? {};
 		this.#discoveryConfig = config.discovery ?? {};
+		this.#traceQueryTimeoutMs = _mastra_core_storage.resolveTraceQueryTimeoutMs(config.traceQueryTimeoutMs);
 	}
 	/**
 	* Build the discovery config used at each call site, with the framework
@@ -17597,11 +17935,16 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 		};
 	}
 	getFeatures() {
-		if (!deltaPollingFeatureEnabled()) return ["metrics", "logs"];
+		if (!deltaPollingFeatureEnabled()) return [
+			"metrics",
+			"logs",
+			"trace-query"
+		];
 		return [
 			"metrics",
 			"logs",
-			"delta-polling"
+			"delta-polling",
+			"trace-query"
 		];
 	}
 	async #run(op, fn, details) {
@@ -17644,6 +17987,9 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 	async listTraces(args) {
 		return this.#run("LIST_TRACES", () => listTraces(this.#client, this.#schema, args));
 	}
+	async queryTraces(plan) {
+		return this.#run("QUERY_TRACES", () => queryTraces(this.#client, this.#schema, plan, this.#traceQueryTimeoutMs));
+	}
 	async listBranches(args) {
 		return this.#run("LIST_BRANCHES", () => listBranches(this.#client, this.#schema, args));
 	}
@@ -22843,7 +23189,8 @@ var PostgresStoreVNext = class extends PostgresStore {
 			client: observabilityClient,
 			schemaName: obsConfig.schemaName ?? config.schemaName,
 			partitioning: obsConfig.partitioning,
-			discovery: obsConfig.discovery
+			discovery: obsConfig.discovery,
+			traceQueryTimeoutMs: obsConfig.traceQueryTimeoutMs
 		});
 		this.stores = {
 			...this.stores,