@mastra/pg 1.0.0 → 1.1.0-alpha.1

package/dist/docs/processors/01-reference.md

@@ -75,7 +75,7 @@ export const agent = new Agent({
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
 
 ---
 
@@ -172,7 +172,7 @@ When `scope` is set to `'resource'`, the processor can recall messages from othe
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
 
 ---
 
@@ -276,10 +276,9 @@ const processor = new WorkingMemory({
    - Thread metadata (`scope: 'thread'`)
    - Resource record (`scope: 'resource'`)
 3. Resolves the template (from provider, options, or default)
-4. Generates system instructions that include:
-   - Guidelines for the LLM on storing and updating information
-   - The template structure
-   - Current working memory data
+4. Generates system instructions based on mode:
+   - **Normal mode**: Includes guidelines for storing/updating information, template structure, and current data
+   - **Read-only mode** (`readOnly: true`): Includes only the current data as context without update instructions
 5. Adds the instruction as a system message with `source: 'memory'` tag
 
 ### Working memory updates
@@ -294,4 +293,4 @@ If no template is provided, the processor uses a default markdown template with
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

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

@@ -376,7 +376,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 
 - OpenAI text-embedding-3-small: 1536 dimensions (or custom, e.g., 256)
 - Cohere embed-multilingual-v3: 1024 dimensions
-- Google text-embedding-004: 768 dimensions (or custom)
+- Google gemini-embedding-001: 768 dimensions (or custom)
 
 > **Note:**
 Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.

package/dist/docs/rag/03-retrieval.md

@@ -73,7 +73,7 @@ Filter results based on metadata fields to narrow down the search space. This ap
 
 This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
 
-For detailed information about available operators and syntax, see the [Metadata Filters Reference](https://mastra.ai/reference/v1/rag/metadata-filters).
+For detailed information about available operators and syntax, see the [Metadata Filters Reference](https://mastra.ai/reference/rag/metadata-filters).
 
 Basic filtering examples:
 
@@ -264,7 +264,7 @@ await pineconeQueryTool.execute(
 );
 ```
 
-For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).
+For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/tools/vector-query-tool).
 
 ### Vector Store Prompts
 
@@ -543,6 +543,6 @@ const relevanceProvider = new ZeroEntropyRelevanceScorer("zerank-1");
 
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
-For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/v1/rag/rerankWithScorer) method.
+For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/v1/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/rag/graph-rag) documentation.

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

@@ -357,13 +357,13 @@ const results = await store.query({
 
 ## Related
 
-- [Astra](https://mastra.ai/reference/v1/vectors/astra)
-- [Chroma](https://mastra.ai/reference/v1/vectors/chroma)
-- [Cloudflare Vectorize](https://mastra.ai/reference/v1/vectors/vectorize)
-- [libSQL](https://mastra.ai/reference/v1/vectors/libsql)
-- [MongoDB](https://mastra.ai/reference/v1/vectors/mongodb)
-- [PgStore](https://mastra.ai/reference/v1/vectors/pg)
-- [Pinecone](https://mastra.ai/reference/v1/vectors/pinecone)
-- [Qdrant](https://mastra.ai/reference/v1/vectors/qdrant)
-- [Upstash](https://mastra.ai/reference/v1/vectors/upstash)
-- [Amazon S3 Vectors](https://mastra.ai/reference/v1/vectors/s3vectors)
+- [Astra](https://mastra.ai/reference/vectors/astra)
+- [Chroma](https://mastra.ai/reference/vectors/chroma)
+- [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
+- [libSQL](https://mastra.ai/reference/vectors/libsql)
+- [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [PgStore](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)
+- [Amazon S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)

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

@@ -15,14 +15,14 @@
 
 `MastraCompositeStore` is included in `@mastra/core`:
 
-```bash
-npm install @mastra/core@beta
+```bash npm2yarn
+npm install @mastra/core@latest
 ```
 
 You'll also need to install the storage providers you want to compose:
 
-```bash
-npm install @mastra/pg@beta @mastra/libsql@beta
+```bash npm2yarn
+npm install @mastra/pg@latest @mastra/libsql@latest
 ```
 
 ## Storage domains
@@ -159,7 +159,9 @@ const storage = new MastraCompositeStore({
 
 ### Specialized storage for observability
 
-Use a time-series database for traces while keeping other data in PostgreSQL:
+Observability data can quickly overwhelm general-purpose databases in production. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day.
+
+**ClickHouse** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
 
 ```typescript
 import { MastraCompositeStore } from "@mastra/core/storage";
@@ -181,6 +183,10 @@ const storage = new MastraCompositeStore({
 });
 ```
 
+> **Note:**
+
+This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [DefaultExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/default#storage-provider-support) for the full list of supported providers.
+
 ---
 
 ## Reference: DynamoDB Storage
@@ -189,24 +195,26 @@ const storage = new MastraCompositeStore({
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
+> **Observability Not Supported**
+DynamoDB storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+> **Item Size Limit**
+DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage#handling-large-attachments) for workarounds including uploading attachments to external storage.
+
 ## Features
 
 - Efficient single-table design for all Mastra storage needs
 - Based on ElectroDB for type-safe DynamoDB access
 - Support for AWS credentials, regions, and endpoints
 - Compatible with AWS DynamoDB Local for development
-- Stores Thread, Message, Trace, Eval, and Workflow data
+- Stores Thread, Message, Eval, and Workflow data
 - Optimized for serverless environments
 - Configurable TTL (Time To Live) for automatic data expiration per entity type
 
 ## Installation
 
-```bash
-npm install @mastra/dynamodb@beta
-# or
-pnpm add @mastra/dynamodb@beta
-# or
-yarn add @mastra/dynamodb@beta
+```bash npm2yarn
+npm install @mastra/dynamodb@latest
 ```
 
 ## Prerequisites
@@ -440,8 +448,8 @@ The PostgreSQL storage implementation provides a production-ready storage soluti
 
 ## Installation
 
-```bash
-npm install @mastra/pg@beta
+```bash npm2yarn
+npm install @mastra/pg@latest
 ```
 
 ## Usage
@@ -463,22 +471,26 @@ You can instantiate `PostgresStore` in the following ways:
 
 ```ts
 import { PostgresStore } from "@mastra/pg";
+import { Pool } from "pg";
 
-// Using a connection string only
+// Using a connection string
 const store1 = new PostgresStore({
   id: 'pg-storage-1',
   connectionString: "postgresql://user:password@localhost:5432/mydb",
 });
 
-// Using a connection string with a custom schema name
+// Using a connection string with pool options
 const store2 = new PostgresStore({
   id: 'pg-storage-2',
   connectionString: "postgresql://user:password@localhost:5432/mydb",
-  schemaName: "custom_schema", // optional
+  schemaName: "custom_schema",
+  max: 30,                    // Max pool connections
+  idleTimeoutMillis: 60000,   // Idle timeout
+  ssl: { rejectUnauthorized: false },
 });
 
 // Using individual connection parameters
-const store4 = new PostgresStore({
+const store3 = new PostgresStore({
   id: 'pg-storage-3',
   host: "localhost",
   port: 5432,
@@ -487,14 +499,16 @@ const store4 = new PostgresStore({
   password: "password",
 });
 
-// Individual parameters with schemaName
-const store5 = new PostgresStore({
+// Using a pre-configured pg.Pool (recommended for pool reuse)
+const existingPool = new Pool({
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  max: 20,
+  // ... your custom pool configuration
+});
+
+const store4 = new PostgresStore({
   id: 'pg-storage-4',
-  host: "localhost",
-  port: 5432,
-  database: "mydb",
-  user: "user",
-  password: "password",
+  pool: existingPool,
   schemaName: "custom_schema", // optional
 });
 ```
@@ -513,6 +527,14 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Observability
+
+PostgreSQL supports observability and can handle low trace volumes. Throughput capacity depends on deployment factors such as hardware, schema design, indexing, and retention policies, and should be validated for your specific environment. For high-volume production environments, consider:
+
+- Using the `insert-only` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/default#tracing-strategies) to reduce database write operations
+- Setting up table partitioning for efficient data retention
+- Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) if you need to scale further
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
@@ -552,19 +574,74 @@ const thread = await memoryStore?.getThreadById({ threadId: "..." });
 > **Note:**
 If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
 
+### Using an Existing Pool
+
+If you already have a `pg.Pool` in your application (e.g., shared with an ORM or for Row Level Security), you can pass it directly to `PostgresStore`:
+
+```typescript
+import { Pool } from "pg";
+import { PostgresStore } from "@mastra/pg";
+
+// Your existing pool (shared across your application)
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+});
+
+const storage = new PostgresStore({
+  id: "shared-storage",
+  pool: pool,
+});
+```
+
+**Pool lifecycle behavior:**
+
+- When you **provide a pool**: Mastra uses your pool but does **not** close it when `store.close()` is called. You manage the pool lifecycle.
+- When Mastra **creates a pool**: Mastra owns the pool and will close it when `store.close()` is called.
+
 ### Direct Database and Pool Access
 
-`PostgresStore` exposes both the underlying database object and the pg-promise instance as public fields:
+`PostgresStore` exposes the underlying database client and pool for advanced use cases:
+
+```typescript
+store.db;   // DbClient - query interface with helpers (any, one, tx, etc.)
+store.pool; // pg.Pool - the underlying connection pool
+```
+
+**Using `store.db` for queries:**
 
 ```typescript
-store.db; // pg-promise database instance
-store.pgp; // pg-promise main instance
+// Execute queries with helper methods
+const users = await store.db.any("SELECT * FROM users WHERE active = $1", [true]);
+const user = await store.db.one("SELECT * FROM users WHERE id = $1", [userId]);
+const maybeUser = await store.db.oneOrNone("SELECT * FROM users WHERE email = $1", [email]);
+
+// Use transactions
+const result = await store.db.tx(async (t) => {
+  await t.none("INSERT INTO logs (message) VALUES ($1)", ["Started"]);
+  const data = await t.any("SELECT * FROM items");
+  return data;
+});
+```
+
+**Using `store.pool` directly:**
+
+```typescript
+// Get a client for manual connection management
+const client = await store.pool.connect();
+try {
+  await client.query("SET LOCAL app.user_id = $1", [userId]);
+  const result = await client.query("SELECT * FROM protected_table");
+  return result.rows;
+} finally {
+  client.release();
+}
 ```
 
-This enables direct queries and custom transaction management. When using these fields:
+When using these fields:
 
 - You are responsible for proper connection and transaction handling.
-- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Closing the store (`store.close()`) will destroy the pool only if Mastra created it.
 - Direct access bypasses any additional logic or validation provided by PostgresStore methods.
 
 This approach is intended for advanced scenarios where low-level access is required.

package/dist/docs/tools/01-reference.md

@@ -340,8 +340,8 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](https://mastra.ai/docs/v1/server/request-context)
-- [Request Context](https://mastra.ai/docs/v1/server/request-context#accessing-values-with-tools)
+- [Agent Request Context](https://mastra.ai/docs/server/request-context)
+- [Request Context](https://mastra.ai/docs/server/request-context#accessing-values-with-tools)
 
 ## Usage Without a Mastra Server
 

package/dist/docs/vectors/01-reference.md

@@ -263,8 +263,8 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash
-npm install @mastra/fastembed@beta
+```bash npm2yarn
+npm install @mastra/fastembed@latest
 ```
 
 Add the following to your agent: