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

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/pg
 
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- Added new `listThreads` method for flexible thread filtering across all storage adapters. ([#11832](https://github.com/mastra-ai/mastra/pull/11832))
+
+  **New Features**
+  - Filter threads by `resourceId`, `metadata`, or both (with AND logic for metadata key-value pairs)
+  - All filter parameters are optional, allowing you to list all threads or filter as needed
+  - Full pagination and sorting support
+
+  **Example Usage**
+
+  ```typescript
+  // List all threads
+  const allThreads = await memory.listThreads({});
+
+  // Filter by resourceId only
+  const userThreads = await memory.listThreads({
+    filter: { resourceId: 'user-123' },
+  });
+
+  // Filter by metadata only
+  const supportThreads = await memory.listThreads({
+    filter: { metadata: { category: 'support' } },
+  });
+
+  // Filter by both with pagination
+  const filteredThreads = await memory.listThreads({
+    filter: {
+      resourceId: 'user-123',
+      metadata: { priority: 'high', status: 'open' },
+    },
+    orderBy: { field: 'updatedAt', direction: 'DESC' },
+    page: 0,
+    perPage: 20,
+  });
+  ```
+
+  **Security Improvements**
+  - Added validation to prevent SQL injection via malicious metadata keys
+  - Added pagination parameter validation to prevent integer overflow attacks
+
+- Updated dependencies [[`ed3e3dd`](https://github.com/mastra-ai/mastra/commit/ed3e3ddec69d564fe2b125e083437f76331f1283), [`6833c69`](https://github.com/mastra-ai/mastra/commit/6833c69607418d257750bbcdd84638993d343539), [`47b1c16`](https://github.com/mastra-ai/mastra/commit/47b1c16a01c7ffb6765fe1e499b49092f8b7eba3), [`3a76a80`](https://github.com/mastra-ai/mastra/commit/3a76a80284cb71a0faa975abb3d4b2a9631e60cd), [`8538a0d`](https://github.com/mastra-ai/mastra/commit/8538a0d232619bf55dad7ddc2a8b0ca77c679a87), [`9312dcd`](https://github.com/mastra-ai/mastra/commit/9312dcd1c6f5b321929e7d382e763d95fdc030f5)]:
+  - @mastra/core@1.0.0-beta.25
+
 ## 1.0.0-beta.13
 
 ### Minor Changes

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/pg
-Version: 1.0.0-beta.13
+Version: 1.0.0-beta.14

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/pg. Includes links to type definitions an
 
 # @mastra/pg Documentation
 
-> **Version**: 1.0.0-beta.13
+> **Version**: 1.0.0-beta.14
 > **Package**: @mastra/pg
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/memory/01-storage.md

@@ -115,6 +115,9 @@ export const agent = new Agent({
 
 This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
 
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
 ## Threads and resources
 
 Mastra organizes memory into threads using two identifiers:
@@ -136,6 +139,21 @@ const stream = await agent.stream("message for agent", {
 > **Note:**
 [Studio](https://mastra.ai/docs/v1/getting-started/studio) automatically generates a thread and resource ID for you. Remember to  to pass these explicitly when calling `stream` or `generate` yourself.
 
+### Thread and resource relationship
+
+Each thread has an owner (its `resourceId`) that is set when the thread is created and cannot be changed. When you query a thread, you must use the correct owner's resource ID. Attempting to query a thread with a different resource ID will result in an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+Note that while each thread has one owner, messages within that thread can have different `resourceId` values. This is used for message attribution and filtering (e.g., distinguishing between different agents in a multi-agent system, or filtering messages for analytics).
+
+**Security:** Memory is a storage layer, not an authorization layer. Your application must implement access control before calling memory APIs. The `resourceId` parameter controls both validation and filtering - provide it to validate ownership and filter messages, or omit it for server-side access without validation.
+
+To avoid accidentally reusing thread IDs across different owners, use UUIDs: `crypto.randomUUID()`
+
 ### Thread title generation
 
 Mastra can automatically generate descriptive thread titles based on the user's first message.

package/dist/docs/memory/04-reference.md

@@ -127,7 +127,7 @@ export const agent = new Agent({
 - [createThread](https://mastra.ai/reference/v1/memory/createThread)
 - [recall](https://mastra.ai/reference/v1/memory/recall)
 - [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/v1/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
 - [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)

package/dist/docs/rag/02-vector-databases.md

@@ -27,7 +27,7 @@ await store.upsert({
 });
 ```
 
-### Using MongoDB Atlas Vector search
+<h3>Using MongoDB Atlas Vector search</h3>
 
 For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=mastra-docs).
 
@@ -55,7 +55,7 @@ await store.upsert({
 });
 ```
 
-### Using PostgreSQL with pgvector
+<h3>Using PostgreSQL with pgvector</h3>
 
 PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity.
 For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
@@ -323,7 +323,7 @@ await store.upsert({
 });
 ```
 
-### Using LanceDB
+<h3>Using LanceDB</h3>
 
 LanceDB is an embedded vector database built on the Lance columnar format, suitable for local development or cloud deployment.
 For detailed setup instructions and best practices, see the [official LanceDB documentation](https://lancedb.github.io/lancedb/).

package/dist/index.cjs

@@ -3219,27 +3219,52 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       );
     }
   }
-  async listThreadsByResourceId(args) {
-    const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
-    if (page < 0) {
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
       throw new error.MastraError({
-        id: storage.createStorageErrorId("PG", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
+        id: storage.createStorageErrorId("PG", "LIST_THREADS", "INVALID_PAGE"),
         domain: error.ErrorDomain.STORAGE,
         category: error.ErrorCategory.USER,
-        text: "Page number must be non-negative",
-        details: {
-          resourceId,
-          page
-        }
+        text: error$1 instanceof Error ? error$1.message : "Invalid pagination parameters",
+        details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
       });
     }
-    const { field, direction } = this.parseOrderBy(orderBy);
     const perPage = storage.normalizePerPage(perPageInput, 100);
+    try {
+      this.validateMetadataKeys(filter?.metadata);
+    } catch (error$1) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "LIST_THREADS", "INVALID_METADATA_KEY"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: error$1 instanceof Error ? error$1.message : "Invalid metadata key",
+        details: { metadataKeys: filter?.metadata ? Object.keys(filter.metadata).join(", ") : "" }
+      });
+    }
+    const { field, direction } = this.parseOrderBy(orderBy);
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
     try {
       const tableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
-      const baseQuery = `FROM ${tableName} WHERE "resourceId" = $1`;
-      const queryParams = [resourceId];
+      const whereClauses = [];
+      const queryParams = [];
+      let paramIndex = 1;
+      if (filter?.resourceId) {
+        whereClauses.push(`"resourceId" = $${paramIndex}`);
+        queryParams.push(filter.resourceId);
+        paramIndex++;
+      }
+      if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+        for (const [key, value] of Object.entries(filter.metadata)) {
+          whereClauses.push(`metadata::jsonb @> $${paramIndex}::jsonb`);
+          queryParams.push(JSON.stringify({ [key]: value }));
+          paramIndex++;
+        }
+      }
+      const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+      const baseQuery = `FROM ${tableName} ${whereClause}`;
       const countQuery = `SELECT COUNT(*) ${baseQuery}`;
       const countResult = await this.#db.client.one(countQuery, queryParams);
       const total = parseInt(countResult.count, 10);
@@ -3253,7 +3278,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         };
       }
       const limitValue = perPageInput === false ? total : perPage;
-      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $2 OFFSET $3`;
+      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
       const rows = await this.#db.client.manyOrNone(
         dataQuery,
         [...queryParams, limitValue, offset]
@@ -3277,11 +3302,12 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     } catch (error$1) {
       const mastraError = new error.MastraError(
         {
-          id: storage.createStorageErrorId("PG", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: storage.createStorageErrorId("PG", "LIST_THREADS", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: {
-            resourceId,
+            ...filter?.resourceId && { resourceId: filter.resourceId },
+            hasMetadataFilter: !!filter?.metadata,
             page
           }
         },