@mastra/pg 1.20.1-alpha.0 → 1.20.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/pg
 
+## 1.20.1-alpha.1
+
+### Patch Changes
+
+- Make `listWorkflowRuns` status filtering indexable on Postgres. The status predicate previously wrapped every snapshot in a `regexp_replace(snapshot::text, ...)::jsonb` sanitization step, which forced a sequential scan over the whole `mastra_workflow_snapshot` table. On `jsonb` snapshot columns Postgres already rejects the problematic Unicode escape sequences at insert time, so the sanitization was a no-op there and the query now uses a plain `snapshot->>'status'` comparison backed by a new default expression index on `(workflow_name, snapshot->>'status', "createdAt" DESC)`. Legacy tables whose snapshot column is still `json` or `text` keep the sanitizing path. ([#21684](https://github.com/mastra-ai/mastra/pull/21684))
+
+- Updated dependencies [[`4e7a421`](https://github.com/mastra-ai/mastra/commit/4e7a421dce8a48742f785d1e93ad2f43a572b282), [`242e324`](https://github.com/mastra-ai/mastra/commit/242e3241e73cbd5c9bb86a31ebb49ca0256488d4), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`d774e89`](https://github.com/mastra-ai/mastra/commit/d774e8930c781df8c9effe3763e6b501c099b6cc), [`9c27a53`](https://github.com/mastra-ai/mastra/commit/9c27a53cd9d3de4f3f025bc387d94ce371c33f95), [`dff25a1`](https://github.com/mastra-ai/mastra/commit/dff25a1103fa72ee082a9b6f805ebeb5ce400753), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`7f78585`](https://github.com/mastra-ai/mastra/commit/7f785857e401570e2ffb316911f126ed363aa537), [`f2a4afd`](https://github.com/mastra-ai/mastra/commit/f2a4afd7e37e809669001ed17724b341a5c1f45e), [`d438148`](https://github.com/mastra-ai/mastra/commit/d438148e222c1e2fb3c652725ce75680962ebec4), [`ba05fe0`](https://github.com/mastra-ai/mastra/commit/ba05fe0738f70cb686777546e968237d09269142), [`d26a8d4`](https://github.com/mastra-ai/mastra/commit/d26a8d4281f28414715b333c85bedaf70d0b2890), [`677cdc6`](https://github.com/mastra-ai/mastra/commit/677cdc6af564dec29a13464d12b7ab2a4efc22e9), [`a318490`](https://github.com/mastra-ai/mastra/commit/a318490e17da32f338d50929c770d901a9b3dd72), [`763e0c6`](https://github.com/mastra-ai/mastra/commit/763e0c61e04d76ad9a9efd301aa57525ca0cbea9), [`23e0be2`](https://github.com/mastra-ai/mastra/commit/23e0be261381e49534b4ff3101c60ee64a946cbf), [`7fc8806`](https://github.com/mastra-ai/mastra/commit/7fc880627d3cbf995d31ea0e8b807bf15417e651), [`0e02eac`](https://github.com/mastra-ai/mastra/commit/0e02eacdb2e30e1697a41910b41163742a181dc1), [`4df174c`](https://github.com/mastra-ai/mastra/commit/4df174c32bddf093a82f273070b8380aef7c9e90), [`f7c25b5`](https://github.com/mastra-ai/mastra/commit/f7c25b5106ddfb48e591f98df7a51e0f2dd01dba), [`dc09cc1`](https://github.com/mastra-ai/mastra/commit/dc09cc1083d861cde192c1cd235324dc75b8c731), [`36b4649`](https://github.com/mastra-ai/mastra/commit/36b4649045a3a380cbab8ceca866db4086223aff), [`377eb81`](https://github.com/mastra-ai/mastra/commit/377eb81ce43b964e3a6b541df172da74a8ff3716)]:
+  - @mastra/core@1.60.0-alpha.8
+
 ## 1.20.1-alpha.0
 
 ### Patch Changes

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.20.1-alpha.0"
+  version: "1.20.1-alpha.1"
 ---
 
 ## When to use
@@ -19,7 +19,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Workers](references/docs-deployment-workers.md) - Separate background processing from the API layer by running workflow execution, cron schedules, and background tasks in dedicated worker processes.
 - [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
 - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
-- [Storage](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
+- [Storage](references/docs-storage.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
 
 ### Integrations
 

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -339,7 +339,7 @@ MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 
 Without this variable, the orchestration worker attempts to execute steps in its own process, which doesn't have access to the full Mastra runtime in a split deployment.
 
-The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers) for server configuration and other credential formats.
+The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/auth/workers) for server configuration and other credential formats.
 
 ### Scale workers
 
@@ -365,18 +365,18 @@ A distributed PubSub backend persists unacknowledged events, which lets orchestr
 
 The scheduler calculates the next fire time from the current time after it restarts. It doesn't replay schedules that elapsed while it was unavailable.
 
-If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents).
+If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/harness/durable-agents).
 
 ## Known limitations
 
 - **No dead-letter queue**: Failed events are nacked and retried, but there's no DLQ for events that fail after all retries.
 - **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
 - **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
-- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
+- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/harness/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/harness/durable-agents) for details.
 
 ## Related
 
-- [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
+- [Worker authentication](https://mastra.ai/docs/auth/workers): Secure worker-to-API communication
 - [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

package/dist/docs/references/docs-memory-working-memory.md

@@ -400,7 +400,7 @@ const response = await agent.generate('What do you know about me?', {
 
 ## Opt in to state signals (experimental)
 
-By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/long-running-agents/signals) instead by setting `useStateSignals: true`:
+By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/harness/signals) instead by setting `useStateSignals: true`:
 
 ```typescript
 const memory = new Memory({

package/dist/docs/references/{docs-storage-overview.md → docs-storage.md}

@@ -10,7 +10,7 @@ Storage powers:
 - [Workflows](https://mastra.ai/docs/workflows/overview): Durable snapshots for suspended and resumed workflow runs.
 - [Observability](https://mastra.ai/docs/observability/overview): Traces, spans, metrics, logs, and feedback.
 - [Evals](https://mastra.ai/docs/evals/overview): Scores, datasets, experiments, and evaluation results.
-- [Long-running agents](https://mastra.ai/docs/long-running-agents/durable-agents): Background tasks, schedules, goals, and thread state.
+- [Long-running agents](https://mastra.ai/docs/harness/durable-agents): Background tasks, schedules, goals, and thread state.
 
 ## When to configure storage
 

package/dist/docs/references/integrations-databases-postgresql.md

@@ -408,6 +408,7 @@ PostgreSQL storage creates composite indexes during initialization for common qu
 - `mastra_ai_spans_scope_startedat_idx`: (scope, startedAt DESC)
 - `mastra_scores_trace_id_span_id_created_at_idx`: (traceId, spanId, createdAt DESC)
 - `mastra_workflow_snapshot_name_createdat_idx`: (workflow\_name, createdAt DESC)
+- `mastra_workflow_snapshot_name_status_createdat_idx`: (workflow\_name, snapshot->>'status', createdAt DESC), created only when the `snapshot` column is `jsonb`
 
 These indexes improve performance for filtered queries with sorting, including `dateRange` filters on message queries and Studio's workflow runs-list.
 

package/dist/index.cjs

@@ -2176,7 +2176,7 @@ async function loadSchemaSnapshot(client, schemaName) {
 	const schema = schemaName || "public";
 	const [tableRows, columnRows, indexRows] = await Promise.all([
 		client.manyOrNone(`SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname = $1`, [schema]),
-		client.manyOrNone(`SELECT c.relname AS table_name, a.attname AS column_name
+		client.manyOrNone(`SELECT c.relname AS table_name, a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS data_type
          FROM pg_catalog.pg_class c
          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
          JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
@@ -2191,6 +2191,7 @@ async function loadSchemaSnapshot(client, schemaName) {
         WHERE n.nspname = $1`, [schema])
 	]);
 	const columns = /* @__PURE__ */ new Map();
+	const columnTypes = /* @__PURE__ */ new Map();
 	for (const row of columnRows) {
 		let set = columns.get(row.table_name);
 		if (!set) {
@@ -2198,6 +2199,12 @@ async function loadSchemaSnapshot(client, schemaName) {
 			columns.set(row.table_name, set);
 		}
 		set.add(row.column_name);
+		let types = columnTypes.get(row.table_name);
+		if (!types) {
+			types = /* @__PURE__ */ new Map();
+			columnTypes.set(row.table_name, types);
+		}
+		types.set(row.column_name, row.data_type);
 	}
 	const indexes = /* @__PURE__ */ new Set();
 	const replicaIdentityIndexes = /* @__PURE__ */ new Set();
@@ -2211,6 +2218,7 @@ async function loadSchemaSnapshot(client, schemaName) {
 		schemaName: schema,
 		tables: new Set(tableRows.map((r) => r.tablename)),
 		columns,
+		columnTypes,
 		indexes,
 		replicaIdentityIndexes,
 		primaryKeyIndexes
@@ -2464,6 +2472,8 @@ var PgDB = class extends _mastra_core_base.MastraBase {
 	skipDefaultIndexes;
 	/** Cache of actual table columns: tableName -> Set<columnName> */
 	tableColumnsCache = /* @__PURE__ */ new Map();
+	/** Cache of column Postgres data types: tableName -> columnName -> data_type */
+	columnTypeCache = /* @__PURE__ */ new Map();
 	constructor(config) {
 		super({
 			component: "STORAGE",
@@ -2538,7 +2548,9 @@ var PgDB = class extends _mastra_core_base.MastraBase {
 			}
 		}
 		this.tableColumnsCache.delete(oldName);
+		this.columnTypeCache.delete(oldName);
 		this.tableColumnsCache.delete(newName);
+		this.columnTypeCache.delete(newName);
 	}
 	/**
 	* Records an out-of-band `DROP TABLE` in the init snapshot. See
@@ -2554,8 +2566,10 @@ var PgDB = class extends _mastra_core_base.MastraBase {
 		if (snapshot) {
 			snapshot.tables.delete(tableName);
 			snapshot.columns.delete(tableName);
+			snapshot.columnTypes.delete(tableName);
 		}
 		this.tableColumnsCache.delete(tableName);
+		this.columnTypeCache.delete(tableName);
 	}
 	/**
 	* Records an out-of-band `ALTER TABLE … ADD COLUMN` in the init snapshot.
@@ -2565,6 +2579,7 @@ var PgDB = class extends _mastra_core_base.MastraBase {
 		const snapshot = this.schemaSnapshot;
 		if (snapshot) this.snapshotColumns(snapshot, tableName).add(column);
 		this.tableColumnsCache.delete(tableName);
+		this.columnTypeCache.delete(tableName);
 	}
 	/**
 	* Gets the set of column names that actually exist in the database table.
@@ -2607,6 +2622,50 @@ var PgDB = class extends _mastra_core_base.MastraBase {
 		]);
 	}
 	/**
+	* Returns the Postgres data type of a column (e.g. `jsonb`, `json`, `text`),
+	* or null when the table or column does not exist.
+	*
+	* Answered from the init snapshot when one is installed, so a warm `init()`
+	* issues no catalog probe. Outside init, results are cached per instance and
+	* the cache is invalidated alongside {@link tableColumnsCache} whenever DDL
+	* changes a table.
+	*/
+	async getColumnType(table, column) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot) {
+			const types = snapshot.columnTypes.get(table);
+			const known = types?.get(column) ?? types?.get(column.toLowerCase());
+			if (known) return known;
+			if (types) return null;
+		}
+		const cached = this.columnTypeCache.get(table)?.get(column);
+		if (cached !== void 0) return cached;
+		const schema = this.schemaName || "public";
+		const dataType = (await this.client.oneOrNone(`SELECT data_type FROM information_schema.columns WHERE table_schema = $1 AND table_name = $2 AND (column_name = $3 OR column_name = $4)`, [
+			schema,
+			table,
+			column,
+			column.toLowerCase()
+		]))?.data_type ?? null;
+		if (dataType) {
+			if (snapshot) {
+				let snapshotTypes = snapshot.columnTypes.get(table);
+				if (!snapshotTypes) {
+					snapshotTypes = /* @__PURE__ */ new Map();
+					snapshot.columnTypes.set(table, snapshotTypes);
+				}
+				snapshotTypes.set(column, dataType);
+			}
+			let types = this.columnTypeCache.get(table);
+			if (!types) {
+				types = /* @__PURE__ */ new Map();
+				this.columnTypeCache.set(table, types);
+			}
+			types.set(column, dataType);
+		}
+		return dataType;
+	}
+	/**
 	* Prepares values for insertion, handling JSONB columns by stringifying them
 	*/
 	prepareValuesForInsert(record, tableName) {
@@ -2805,6 +2864,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			}, error);
 		} finally {
 			this.tableColumnsCache.delete(tableName);
+			this.columnTypeCache.delete(tableName);
 		}
 	}
 	async setupTimestampTriggers(tableName) {
@@ -3127,6 +3187,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			}, error);
 		} finally {
 			this.tableColumnsCache.delete(tableName);
+			this.columnTypeCache.delete(tableName);
 		}
 	}
 	async load({ tableName, keys }) {
@@ -3190,6 +3251,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			}, error);
 		} finally {
 			this.tableColumnsCache.delete(tableName);
+			this.columnTypeCache.delete(tableName);
 		}
 	}
 	async createIndex(options) {
@@ -19322,6 +19384,29 @@ function getTableName({ indexName, schemaName }) {
 	const quotedIndexName = `"${indexName}"`;
 	return schemaName ? `${schemaName}.${quotedIndexName}` : quotedIndexName;
 }
+/** Base name (before any schema prefix) of the expression index backing the status filter. */
+const WORKFLOW_SNAPSHOT_STATUS_INDEX = "mastra_workflow_snapshot_name_status_createdat_idx";
+/**
+* Schema-prefixed name of the status index, lowercased and truncated the same way Postgres
+* stores it, so the init snapshot's index set answers "does it exist?" without a probe or a
+* no-op `CREATE INDEX` (schema-prefixed names routinely exceed the 63-byte limit).
+*/
+function workflowSnapshotStatusIndexName(schemaName) {
+	return buildConstraintName({
+		baseName: WORKFLOW_SNAPSHOT_STATUS_INDEX,
+		schemaName: schemaName && schemaName !== "public" ? schemaName : void 0
+	});
+}
+/**
+* Expression index on `(workflow_name, snapshot->>'status', "createdAt" DESC)` so
+* listWorkflowRuns() status filters can use an index instead of scanning every snapshot.
+*/
+function workflowSnapshotStatusIndexSQL(indexName, schemaName) {
+	return `CREATE INDEX IF NOT EXISTS "${indexName}" ON ${getTableName({
+		indexName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
+		schemaName: getSchemaName(schemaName)
+	})} (workflow_name, (snapshot ->> 'status'), "createdAt" DESC)`;
+}
 /**
 * Sanitizes JSON string for PostgreSQL jsonb:
 * - Removes problematic Unicode sequences:
@@ -19404,6 +19489,7 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 			includeAllConstraints: true
 		}));
 		for (const idx of WorkflowsPG.getDefaultIndexDefs(schemaPrefix)) statements.push(generateIndexSQL(idx, schemaName));
+		statements.push(`${workflowSnapshotStatusIndexSQL(workflowSnapshotStatusIndexName(parsedSchema), schemaName)};`);
 		return statements;
 	}
 	/**
@@ -19423,6 +19509,13 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 		} catch (error) {
 			this.logger?.warn?.(`Failed to create index ${indexDef.name}:`, error);
 		}
+		if (await this.#db.getColumnType(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "snapshot") !== "jsonb") return;
+		const indexName = workflowSnapshotStatusIndexName(this.#schema);
+		try {
+			await this.#db.createIndexFromStatement(indexName, workflowSnapshotStatusIndexSQL(indexName, this.#schema));
+		} catch (error) {
+			this.logger?.warn?.(`Failed to create index ${indexName}:`, error);
+		}
 	}
 	async init() {
 		await this.#db.createTable({
@@ -19712,7 +19805,8 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 				paramIndex++;
 			}
 			if (status) {
-				conditions.push(`regexp_replace(snapshot::text, '\\\\u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})', '', 'g')::jsonb ->> 'status' = $${paramIndex}`);
+				const statusExpr = await this.#db.getColumnType(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "snapshot") === "jsonb" ? `snapshot ->> 'status'` : `regexp_replace(snapshot::text, '\\\\u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})', '', 'g')::jsonb ->> 'status'`;
+				conditions.push(`${statusExpr} = $${paramIndex}`);
 				values.push(status);
 				paramIndex++;
 			}