@mastra/pg 1.30.0 → 1.31.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.30.0"
+  version: "1.31.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -411,11 +411,11 @@ PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an
 
 ```typescript
 import { Memory } from '@mastra/memory'
-import { PgStore, PgVector } from '@mastra/pg'
+import { PostgresStore, PgVector } from '@mastra/pg'
 
 const agent = new Agent({
   memory: new Memory({
-    storage: new PgStore({
+    storage: new PostgresStore({
       id: 'agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),

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

@@ -272,6 +272,22 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 - **Set a field to `null` to delete it:** This explicitly removes the field from memory
 - **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays aren't merged element-by-element)
 
+### Concurrent updates
+
+With `scope: 'resource'` and a storage adapter that supports atomic merges (currently `@mastra/pg`), each merge runs inside a row-locked database transaction. Concurrent updates to different fields from separate processes are all kept. Other adapters merge in the application, which only serializes writers inside a single process.
+
+To merge a partial update from your own code, call `memory.mergeWorkingMemory()`:
+
+```typescript
+await memory.mergeWorkingMemory({
+  threadId: 'thread-1',
+  resourceId: 'user-123',
+  workingMemory: { preferences: { tone: 'formal' } },
+})
+```
+
+It throws if working memory isn't schema-based and resource-scoped, or if the storage adapter doesn't support atomic merges. Check `await memory.supportsAtomicWorkingMemoryMerge()` first if you need to fall back.
+
 ## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.

package/dist/docs/references/reference-memory-memory-class.md

@@ -101,14 +101,14 @@ export const agent = new Agent({
 import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
-import { PgStore, PgVector } from '@mastra/pg'
+import { PostgresStore, PgVector } from '@mastra/pg'
 
 export const agent = new Agent({
   name: 'pg-agent',
   instructions: 'You are an agent with optimized PostgreSQL memory.',
   model: 'openai/gpt-5.6-sol',
   memory: new Memory({
-    storage: new PgStore({
+    storage: new PostgresStore({
       id: 'pg-agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),

package/dist/docs/references/reference-processors-message-history-processor.md

@@ -40,9 +40,10 @@ const processor = new MessageHistory({
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { MessageHistory } from '@mastra/core/processors'
-import { PostgresStorage } from '@mastra/pg'
+import { PostgresStore } from '@mastra/pg'
 
-const storage = new PostgresStorage({
+const storage = new PostgresStore({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 })
 

package/dist/docs/references/reference-processors-semantic-recall-processor.md

@@ -59,11 +59,10 @@ const processor = new SemanticRecall({
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { SemanticRecall, MessageHistory } from '@mastra/core/processors'
-import { PostgresStorage } from '@mastra/pg'
-import { PgVector } from '@mastra/pg'
+import { PostgresStore, PgVector } from '@mastra/pg'
 import { openai } from '@ai-sdk/openai'
 
-const storage = new PostgresStorage({
+const storage = new PostgresStore({
   id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 })

package/dist/docs/references/reference-processors-working-memory-processor.md

@@ -62,9 +62,10 @@ const processor = new WorkingMemory({
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { WorkingMemory, MessageHistory } from '@mastra/core/processors'
-import { PostgresStorage } from '@mastra/pg'
+import { PostgresStore } from '@mastra/pg'
 
-const storage = new PostgresStorage({
+const storage = new PostgresStore({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 })
 

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

@@ -231,7 +231,7 @@ await store.createIndex({
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
 - [OracleDB](https://mastra.ai/reference/vectors/oracledb)
-- [PgStore](https://mastra.ai/reference/vectors/pg)
+- [PgVector](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
 - [Upstash](https://mastra.ai/reference/vectors/upstash)

package/dist/docs/references/reference-rag-vector-databases.md

@@ -230,7 +230,7 @@ await store.upsert({
 **libSQL**:
 
 ```ts
-import { LibSQLVector } from '@mastra/core/vector/libsql'
+import { LibSQLVector } from '@mastra/libsql'
 
 const store = new LibSQLVector({
   id: 'libsql-vector',

package/dist/index.cjs

@@ -2507,7 +2507,7 @@ async function loadSchemaSnapshot(client, schemaName) {
           AND c.relkind IN ('r', 'p')
           AND a.attnum > 0
           AND NOT a.attisdropped`, [schema]),
-		client.manyOrNone(`SELECT c.relname AS indexname, i.indisreplident AS is_replica_identity, i.indisprimary AS is_primary
+		client.manyOrNone(`SELECT c.relname AS indexname, i.indisreplident AS is_replica_identity, i.indisprimary AS is_primary, i.indisvalid AS is_valid
          FROM pg_catalog.pg_index i
          JOIN pg_catalog.pg_class c ON c.oid = i.indexrelid
          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
@@ -2532,8 +2532,10 @@ async function loadSchemaSnapshot(client, schemaName) {
 	const indexes = /* @__PURE__ */ new Set();
 	const replicaIdentityIndexes = /* @__PURE__ */ new Set();
 	const primaryKeyIndexes = /* @__PURE__ */ new Set();
+	const invalidIndexes = /* @__PURE__ */ new Set();
 	for (const row of indexRows) {
-		indexes.add(row.indexname);
+		if (row.is_valid) indexes.add(row.indexname);
+		else invalidIndexes.add(row.indexname);
 		if (row.is_replica_identity) replicaIdentityIndexes.add(row.indexname);
 		if (row.is_primary) primaryKeyIndexes.add(row.indexname.toLowerCase());
 	}
@@ -2544,7 +2546,8 @@ async function loadSchemaSnapshot(client, schemaName) {
 		columnTypes,
 		indexes,
 		replicaIdentityIndexes,
-		primaryKeyIndexes
+		primaryKeyIndexes,
+		invalidIndexes
 	};
 }
 //#endregion
@@ -3692,11 +3695,8 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 				schemaName: getSchemaName$6(this.schemaName)
 			});
 			const snapshot = this.schemaSnapshot;
-			if (snapshot) {
-				if (snapshot.indexes.has(name)) return;
-			} else if (await this.client.oneOrNone(`SELECT 1 FROM pg_indexes
-         WHERE indexname = $1
-         AND schemaname = $2`, [name, schemaName])) return;
+			if (snapshot?.indexes.has(name)) return;
+			if (!await this.prepareIndexBuild(name, schemaName)) return;
 			const uniqueStr = unique ? "UNIQUE " : "";
 			const concurrentStr = concurrent ? "CONCURRENTLY " : "";
 			const methodStr = method !== "btree" ? `USING ${method} ` : "";
@@ -3715,16 +3715,9 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			let withStr = "";
 			if (storage && Object.keys(storage).length > 0) withStr = ` WITH (${Object.entries(storage).map(([key, value]) => `${key} = ${value}`).join(", ")})`;
 			const sql = `CREATE ${uniqueStr}INDEX ${concurrentStr}${`"${(0, _mastra_core_utils.parseSqlIdentifier)(name, "index name")}"`} ON ${fullTableName} ${methodStr}(${columnsStr})${withStr}${tablespaceStr}${whereStr}`;
-			await this.client.none(sql);
+			await this.timedIndexBuild(name, sql);
 			snapshot?.indexes.add(name);
 		} catch (error) {
-			if (error instanceof Error && error.message.includes("CONCURRENTLY")) {
-				const retryOptions = {
-					...options,
-					concurrent: false
-				};
-				return this.createIndex(retryOptions);
-			}
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "INDEX_CREATE", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -3748,9 +3741,43 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 	async createIndexFromStatement(indexName, sql) {
 		const snapshot = this.schemaSnapshot;
 		if (snapshot?.indexes.has(indexName)) return;
-		await this.client.none(sql);
+		if (!await this.prepareIndexBuild(indexName, this.schemaName || "public")) return;
+		await this.timedIndexBuild(indexName, sql);
 		snapshot?.indexes.add(indexName);
 	}
+	/**
+	* Decides whether `indexName` still needs building. Returns false when a valid
+	* index already exists, or when another session is currently building it.
+	* An invalid index left by an interrupted `CREATE INDEX CONCURRENTLY` is
+	* dropped (concurrently) so the caller rebuilds it — `IF NOT EXISTS` would
+	* otherwise keep the broken index forever.
+	*/
+	async prepareIndexBuild(indexName, schemaName) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot && !snapshot.invalidIndexes.has(indexName)) return true;
+		const existing = await this.client.oneOrNone(`SELECT i.indisvalid AS is_valid,
+              EXISTS (SELECT 1 FROM pg_stat_progress_create_index p WHERE p.index_relid = c.oid) AS building
+         FROM pg_catalog.pg_index i
+         JOIN pg_catalog.pg_class c ON c.oid = i.indexrelid
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relname = $1 AND n.nspname = $2`, [indexName, schemaName]);
+		if (!existing) return true;
+		if (existing.is_valid) return false;
+		if (existing.building) {
+			this.logger.warn(`Index ${indexName} is being built by another session; skipping`);
+			return false;
+		}
+		this.logger.warn(`Dropping invalid index ${indexName} left by an interrupted build; rebuilding it`);
+		const quotedIndexName = `"${(0, _mastra_core_utils.parseSqlIdentifier)(indexName, "index name")}"`;
+		await this.client.none(`DROP INDEX CONCURRENTLY IF EXISTS ${getSchemaName$6(this.schemaName)}.${quotedIndexName}`);
+		return true;
+	}
+	async timedIndexBuild(indexName, sql) {
+		const startedAt = Date.now();
+		this.logger.info(`Creating index ${indexName}`);
+		await this.client.none(sql);
+		this.logger.info(`Created index ${indexName} in ${Date.now() - startedAt}ms`);
+	}
 	async dropIndex(indexName) {
 		try {
 			const schemaName = this.schemaName || "public";
@@ -10495,6 +10522,7 @@ function dedupeMessagesForSave(messages) {
 var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 	supportsPartialThreadUpdate = true;
 	supportsObservationalMemory = true;
+	supportsAtomicWorkingMemoryMerge = true;
 	supportsObservationalMemoryHistorySearch = true;
 	/**
 	* Retention-eligible tables. `threads`, `messages`, and `resources` all anchor
@@ -11841,6 +11869,57 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 			metadata: metadataJson ? JSON.parse(metadataJson) : resource.metadata
 		};
 	}
+	async mergeResourceWorkingMemory({ resourceId, merge }) {
+		const tableName = getTableName$3({
+			indexName: _mastra_core_storage.TABLE_RESOURCES,
+			schemaName: getSchemaName$3(this.#schema)
+		});
+		const callbackError = {};
+		try {
+			return await this.#db.client.tx(async (t) => {
+				const now = (/* @__PURE__ */ new Date()).toISOString();
+				await t.none(`INSERT INTO ${tableName} (id, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ")
+         VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (id) DO NOTHING`, [
+					resourceId,
+					toPgJson({}),
+					now,
+					now,
+					now,
+					now
+				]);
+				await t.one(`SELECT id FROM ${tableName} WHERE id = $1 FOR UPDATE`, [resourceId]);
+				const existing = await this.#getResourceById(t, resourceId);
+				let workingMemory;
+				try {
+					workingMemory = merge(existing.workingMemory ?? void 0);
+				} catch (error) {
+					callbackError.error = error;
+					throw error;
+				}
+				const updatedAt = /* @__PURE__ */ new Date();
+				const updatedAtStr = updatedAt.toISOString();
+				await t.none(`UPDATE ${tableName} SET "workingMemory" = $1, "updatedAt" = $2, "updatedAtZ" = $3 WHERE id = $4`, [
+					workingMemory,
+					updatedAtStr,
+					updatedAtStr,
+					resourceId
+				]);
+				return {
+					...existing,
+					workingMemory,
+					updatedAt
+				};
+			});
+		} catch (error) {
+			if (error === callbackError.error || error instanceof _mastra_core_error.MastraError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "MERGE_RESOURCE_WORKING_MEMORY", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { resourceId }
+			}, error);
+		}
+	}
 	async updateResource({ resourceId, workingMemory, metadata }) {
 		const existingResource = await this.#getResourceById(this.#db.client, resourceId);
 		if (!existingResource) {
@@ -17540,6 +17619,35 @@ function isMetadataField(field) {
 function placeholders(values, offset) {
 	return values.map((_, index) => `$${offset + index}`).join(", ");
 }
+/**
+* Unicode letters, marks, and digits as PostgreSQL bracket ranges, so `[^<ranges>]` splits words
+* like the planner's `[^\p{L}\p{M}\p{N}]`. PostgreSQL regexes have no `\p{…}` classes, and
+* `[[:alnum:]]` depends on the locale: it leaves out digits such as `² ½ ₂ ①`, and glibc files
+* some marks, such as the Devanagari virama, under punct. Derived once from the runtime's own
+* Unicode tables. A run may also absorb unassigned code points, which are never stored.
+* Private-use code points are not absorbed: the other stores treat them as separators.
+*/
+let pgWordRanges;
+function getPgWordRanges() {
+	if (pgWordRanges !== void 0) return pgWordRanges;
+	const escape = (cp) => cp > 65535 ? `\\U${cp.toString(16).padStart(8, "0")}` : `\\u${cp.toString(16).padStart(4, "0")}`;
+	const chunks = [];
+	for (let start = 0; start <= 1114111; start += 8192) {
+		const codePoints = [];
+		for (let cp = start; cp < start + 8192 && cp <= 1114111; cp++) if (cp < 55296 || cp > 57343) codePoints.push(cp);
+		chunks.push(String.fromCodePoint(...codePoints));
+	}
+	const text = chunks.join("");
+	const ranges = [];
+	for (const match of text.matchAll(/[\p{L}\p{M}\p{N}\p{Cn}]+/gu)) {
+		const first = match[0].codePointAt(0);
+		const lastUnit = match.index + match[0].length - 1;
+		const last = text.codePointAt(text.charCodeAt(lastUnit) >= 56320 && text.charCodeAt(lastUnit) <= 57343 ? lastUnit - 1 : lastUnit);
+		ranges.push(first === last ? escape(first) : `${escape(first)}-${escape(last)}`);
+	}
+	pgWordRanges = ranges.join("");
+	return pgWordRanges;
+}
 function compileScalarPredicate(predicate, registry, parameterOffset, allowMetadata = false) {
 	if (predicate.type === "boolean") {
 		const values = [];
@@ -17583,6 +17691,13 @@ function compileScalarPredicate(predicate, registry, parameterOffset, allowMetad
 			values: fieldValues
 		};
 	}
+	if (predicate.type === "text") {
+		const found = `strpos(${`' ' || replace(lower(regexp_replace(normalize(${field}), '[^${getPgWordRanges()}]+', ' ', 'g')), 'ς', 'σ') || ' '`}, $${parameterOffset}) > 0`;
+		return {
+			sql: `COALESCE(${predicate.operator === "matches" ? found : `NOT (${found})`}, false)`,
+			values: [...fieldValues, ` ${predicate.value} `]
+		};
+	}
 	if (predicate.type === "membership") {
 		const list = placeholders(predicate.values, parameterOffset);
 		if (predicate.operator === "in") return {
@@ -23172,12 +23287,17 @@ function workflowSnapshotStatusIndexName(schemaName) {
 /**
 * Expression index on `(workflow_name, snapshot->>'status', "createdAt" DESC)` so
 * listWorkflowRuns() status filters can use an index instead of scanning every snapshot.
+*
+* `concurrently` is set by init, which may build the index on a large existing table while
+* other processes keep writing to it. The exported DDL stays plain because migration
+* tooling often wraps statements in a transaction, where CONCURRENTLY is rejected.
 */
-function workflowSnapshotStatusIndexSQL(indexName, schemaName) {
-	return `CREATE INDEX IF NOT EXISTS "${indexName}" ON ${getTableName({
+function workflowSnapshotStatusIndexSQL(indexName, schemaName, concurrently = false) {
+	const tableName = getTableName({
 		indexName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 		schemaName: getSchemaName(schemaName)
-	})} (workflow_name, (snapshot ->> 'status'), "createdAt" DESC)`;
+	});
+	return `CREATE INDEX ${concurrently ? "CONCURRENTLY " : ""}IF NOT EXISTS "${indexName}" ON ${tableName} (workflow_name, (snapshot ->> 'status'), "createdAt" DESC)`;
 }
 /** Base name (before any schema prefix) of the expression index backing the threadId filter. */
 const WORKFLOW_SNAPSHOT_THREAD_ID_INDEX = "mastra_workflow_snapshot_threadid_idx";
@@ -23214,12 +23334,14 @@ const WORKFLOW_SNAPSHOT_THREAD_ID_EXPR = `COALESCE(jsonb_path_query_first(snapsh
 /**
 * Expression index on the snapshot-embedded thread id so listWorkflowRuns() threadId filters
 * (Agent.listSuspendedRuns) can use an index instead of detoasting every snapshot.
+* See {@link workflowSnapshotStatusIndexSQL} for `concurrently`.
 */
-function workflowSnapshotThreadIdIndexSQL(indexName, schemaName) {
-	return `CREATE INDEX IF NOT EXISTS "${indexName}" ON ${getTableName({
+function workflowSnapshotThreadIdIndexSQL(indexName, schemaName, concurrently = false) {
+	const tableName = getTableName({
 		indexName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 		schemaName: getSchemaName(schemaName)
-	})} ((${WORKFLOW_SNAPSHOT_THREAD_ID_EXPR}))`;
+	});
+	return `CREATE INDEX ${concurrently ? "CONCURRENTLY " : ""}IF NOT EXISTS "${indexName}" ON ${tableName} ((${WORKFLOW_SNAPSHOT_THREAD_ID_EXPR}))`;
 }
 var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorage {
 	#db;
@@ -23316,13 +23438,13 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 		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));
+			await this.#db.createIndexFromStatement(indexName, workflowSnapshotStatusIndexSQL(indexName, this.#schema, true));
 		} catch (error) {
 			this.logger?.warn?.(`Failed to create index ${indexName}:`, error);
 		}
 		const threadIdIndexName = workflowSnapshotThreadIdIndexName(this.#schema);
 		try {
-			await this.#db.createIndexFromStatement(threadIdIndexName, workflowSnapshotThreadIdIndexSQL(threadIdIndexName, this.#schema));
+			await this.#db.createIndexFromStatement(threadIdIndexName, workflowSnapshotThreadIdIndexSQL(threadIdIndexName, this.#schema, true));
 		} catch (error) {
 			this.logger?.warn?.(`Failed to create index ${threadIdIndexName}:`, error);
 		}