@mastra/pg 1.31.1-alpha.0 → 1.31.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.31.1-alpha.0"
+  version: "1.31.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -146,7 +146,7 @@ Workers are internal infrastructure. They're not exposed to end users and don't
 In a split deployment:
 
 - **The API server is the only public-facing process**: It serves all client HTTP requests. These requests include REST endpoints and agent interactions, plus workflow triggers and custom routes.
-- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **Workers don't serve client traffic**: They pull events from the distributed PubSub backend and read/write to the shared storage database. Each worker process also listens on `PORT` (default `4111`) for internal health checks. `/health` reports readiness and `/config` returns the worker configuration to authorized callers. Keep this port on the private network.
 - **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. HTTP routes for worker-related features run on the API server rather than the worker process. One example is creating a token for a voice integration.

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

@@ -210,6 +210,40 @@ export const mastra = new Mastra({
 
 **domains.experiments** (`ExperimentsStorage`): Storage for experiment runs and per-item experiment results.
 
+**domains.workflowDefinitions** (`WorkflowDefinitionsStorage`): Storage for persisted workflow definitions.
+
+**domains.promptBlocks** (`PromptBlocksStorage`): Storage for stored prompt blocks and their versions.
+
+**domains.scorerDefinitions** (`ScorerDefinitionsStorage`): Storage for stored scorer definitions and their versions.
+
+**domains.mcpClients** (`MCPClientsStorage`): Storage for stored MCP client configurations and their versions.
+
+**domains.mcpServers** (`MCPServersStorage`): Storage for stored MCP server configurations and their versions.
+
+**domains.workspaces** (`WorkspacesStorage`): Storage for stored workspace configurations and their versions.
+
+**domains.skills** (`SkillsStorage`): Storage for stored skill definitions and their versions.
+
+**domains.favorites** (`FavoritesStorage`): Storage for user favorites on stored entities.
+
+**domains.blobs** (`BlobStore`): Content-addressable storage for file contents used by skill versioning.
+
+**domains.backgroundTasks** (`BackgroundTasksStorage`): Storage for background task state.
+
+**domains.schedules** (`SchedulesStorage`): Storage for schedules that the scheduler fires.
+
+**domains.channels** (`ChannelsStorage`): Storage for channel installations and configuration.
+
+**domains.harness** (`HarnessStorage`): Storage for harness sessions.
+
+**domains.toolProviderConnections** (`ToolProviderConnectionsStorage`): Storage for authorized tool provider connections.
+
+**domains.notifications** (`NotificationsStorage`): Storage for notifications and their delivery state.
+
+**domains.threadState** (`ThreadStateStorage`): Storage for per-thread agent state, such as task lists and goals.
+
+**domains.knowledge** (`KnowledgeStorage`): Storage for knowledge nodes and records. Experimental.
+
 ## Initialization
 
 `MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -21,13 +21,13 @@ const queryTool = createVectorQueryTool({
 
 ## Parameters
 
-> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
+> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `id` and `description` can only be set at creation time.
 
-**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool', where {vectorStoreName} is 'DirectVectorStore' when a vectorStore instance is passed without a vectorStoreName. (Set at creation only.)
 
 **description** (`string`): Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions' (Set at creation only.)
 
-**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Can be set at creation or overridden at runtime via the request context.)
 
 **vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
@@ -47,7 +47,7 @@ const queryTool = createVectorQueryTool({
 
 **reranker.options.weights** (`WeightConfig`): Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)
 
-**reranker.options.topK** (`number`): Number of top results to return
+**reranker.options.topK** (`number`): Number of top results to return after reranking. Falls back to the query's topK (from the request context, the tool input, or 10) when unset or 0.
 
 **databaseConfig** (`DatabaseConfig`): Database-specific configuration options for optimizing queries. (Can be set at creation or overridden at runtime.)
 

package/dist/docs/references/reference-vectors-pg.md

@@ -82,7 +82,9 @@ const vectorStore = new PgVector({
 
 **dimension** (`number`): Vector dimension (must match your embedding model)
 
-**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search. 'hamming' and 'jaccard' are only valid with vectorType 'bit', and 'jaccard' requires an HNSW index. (Default: `'cosine' ('hamming' when vectorType is 'bit')`)
+
+**vectorType** (`'vector' | 'halfvec' | 'bit' | 'sparsevec'`): pgvector storage type for the embeddings (Default: `vector`)
 
 **indexConfig** (`IndexConfig`): Index configuration (Default: `{ type: 'ivfflat' }`)
 
@@ -142,13 +144,11 @@ Higher M values or efConstruction values will increase memory requirements subst
 
 **includeVector** (`boolean`): Whether to include the vector in the result (Default: `false`)
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
-
-**options** (`{ ef?: number; probes?: number }`): Additional options for HNSW and IVF indexes
+**minScore** (`number`): Minimum similarity score threshold (Default: `-1`)
 
-**options.ef** (`number`): HNSW search parameter
+**ef** (`number`): HNSW search parameter. Higher values improve accuracy at the cost of speed.
 
-**options.probes** (`number`): IVF search parameter
+**probes** (`number`): IVFFlat search parameter. Number of lists to visit during search.
 
 ### `listIndexes()`
 
@@ -164,8 +164,9 @@ Returns:
 interface PGIndexStats {
   dimension: number
   count: number
-  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  metric: 'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'
   type: 'flat' | 'hnsw' | 'ivfflat'
+  vectorType: 'vector' | 'halfvec' | 'bit' | 'sparsevec'
   config: {
     m?: number
     efConstruction?: number
@@ -246,7 +247,7 @@ Closes the database connection pool. Should be called when done using the store.
 
 **indexName** (`string`): Name of the index to define
 
-**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search (Default: `cosine`)
 
 **indexConfig** (`IndexConfig`): Configuration for the index type and parameters
 
@@ -291,17 +292,21 @@ interface QueryResult {
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_PG_QUERY_FAILED'
+    console.log(error.domain) // 'MASTRA_VECTOR'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }

package/dist/index.cjs

@@ -25151,25 +25151,9 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 					schemaName: getSchemaName(this.#schema)
 				});
 				const existingSnapshotResult = await t.oneOrNone(`SELECT snapshot FROM ${tableName} WHERE workflow_name = $1 AND run_id = $2 FOR UPDATE`, [workflowName, runId]);
-				let snapshot;
-				if (!existingSnapshotResult) snapshot = {
-					context: {},
-					activePaths: [],
-					timestamp: Date.now(),
-					suspendedPaths: {},
-					activeStepsPath: {},
-					resumeLabels: {},
-					serializedStepGraph: [],
-					status: "pending",
-					value: {},
-					waitingPaths: {},
-					runId,
-					requestContext: {}
-				};
-				else {
-					const existingSnapshot = existingSnapshotResult.snapshot;
-					snapshot = typeof existingSnapshot === "string" ? JSON.parse(existingSnapshot) : existingSnapshot;
-				}
+				if (!existingSnapshotResult) return {};
+				const existingSnapshot = existingSnapshotResult.snapshot;
+				const snapshot = typeof existingSnapshot === "string" ? JSON.parse(existingSnapshot) : existingSnapshot;
 				(0, _mastra_core_storage.mergeWorkflowStepResult)({
 					snapshot,
 					stepId,