@mastra/pg 1.0.0-beta.10 → 1.0.0-beta.12

package/CHANGELOG.md

@@ -1,5 +1,148 @@
 # @mastra/pg
 
+## 1.0.0-beta.12
+
+### Patch Changes
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Added `startExclusive` and `endExclusive` options to `dateRange` filter for message queries. ([#11479](https://github.com/mastra-ai/mastra/pull/11479))
+
+  **What changed:** The `filter.dateRange` parameter in `listMessages()` and `Memory.recall()` now supports `startExclusive` and `endExclusive` boolean options. When set to `true`, messages with timestamps exactly matching the boundary are excluded from results.
+
+  **Why this matters:** Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using `endExclusive: true` with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
+
+  **Example:**
+
+  ```typescript
+  // Get first page
+  const page1 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+  });
+
+  // Get next page using cursor-based pagination
+  const oldestMessage = page1.messages[page1.messages.length - 1];
+  const page2 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+    filter: {
+      dateRange: {
+        end: oldestMessage.createdAt,
+        endExclusive: true, // Excludes the cursor message
+      },
+    },
+  });
+  ```
+
+- Fix thread timestamps being returned in incorrect timezone from listThreadsByResourceId ([#11498](https://github.com/mastra-ai/mastra/pull/11498))
+
+  The method was not using the timezone-aware columns (createdAtZ/updatedAtZ), causing timestamps to be interpreted in local timezone instead of UTC. Now correctly uses TIMESTAMPTZ columns with fallback for legacy data.
+
+- Adds thread cloning to create independent copies of conversations that can diverge. ([#11517](https://github.com/mastra-ai/mastra/pull/11517))
+
+  ```typescript
+  // Clone a thread
+  const { thread, clonedMessages } = await memory.cloneThread({
+    sourceThreadId: 'thread-123',
+    title: 'My Clone',
+    options: {
+      messageLimit: 10, // optional: only copy last N messages
+    },
+  });
+
+  // Check if a thread is a clone
+  if (memory.isClone(thread)) {
+    const source = await memory.getSourceThread(thread.id);
+  }
+
+  // List all clones of a thread
+  const clones = await memory.listClones('thread-123');
+  ```
+
+  Includes:
+  - Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
+  - API endpoint: `POST /api/memory/threads/:threadId/clone`
+  - Embeddings created for cloned messages (semantic recall)
+  - Clone button in playground UI Memory tab
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
+## 1.0.0-beta.11
+
+### Minor Changes
+
+- Remove pg-promise dependency and use pg.Pool directly ([#11450](https://github.com/mastra-ai/mastra/pull/11450))
+
+  **BREAKING CHANGE**: This release replaces pg-promise with vanilla node-postgres (`pg`).
+
+  ### Breaking Changes
+  - **Removed `store.pgp`**: The pg-promise library instance is no longer exposed
+  - **Config change**: `{ client: pgPromiseDb }` is no longer supported. Use `{ pool: pgPool }` instead
+  - **Cloud SQL config**: `max` and `idleTimeoutMillis` must now be passed via `pgPoolOptions`
+
+  ### New Features
+  - **`store.pool`**: Exposes the underlying `pg.Pool` for direct database access or ORM integration (e.g., Drizzle)
+  - **`store.db`**: Provides a `DbClient` interface with methods like `one()`, `any()`, `tx()`, etc.
+  - **`store.db.connect()`**: Acquire a client for session-level operations
+
+  ### Migration
+
+  ```typescript
+  // Before (pg-promise)
+  import pgPromise from 'pg-promise';
+  const pgp = pgPromise();
+  const client = pgp(connectionString);
+  const store = new PostgresStore({ id: 'my-store', client });
+
+  // After (pg.Pool)
+  import { Pool } from 'pg';
+  const pool = new Pool({ connectionString });
+  const store = new PostgresStore({ id: 'my-store', pool });
+
+  // Use store.pool with any library that accepts a pg.Pool
+  ```
+
+### Patch Changes
+
+- Added `exportSchemas()` function to generate Mastra database schema as SQL DDL without a database connection. ([#11448](https://github.com/mastra-ai/mastra/pull/11448))
+
+  **What's New**
+
+  You can now export your Mastra database schema as SQL DDL statements without connecting to a database. This is useful for:
+  - Generating migration scripts
+  - Reviewing the schema before deployment
+  - Creating database schemas in environments where the application doesn't have CREATE privileges
+
+  **Example**
+
+  ```typescript
+  import { exportSchemas } from '@mastra/pg';
+
+  // Export schema for default 'public' schema
+  const ddl = exportSchemas();
+  console.log(ddl);
+
+  // Export schema for a custom schema
+  const customDdl = exportSchemas('my_schema');
+  // Creates: CREATE SCHEMA IF NOT EXISTS "my_schema"; and all tables within it
+  ```
+
+- Updated dependencies [[`e54953e`](https://github.com/mastra-ai/mastra/commit/e54953ed8ce1b28c0d62a19950163039af7834b4), [`7d56d92`](https://github.com/mastra-ai/mastra/commit/7d56d9213886e8353956d7d40df10045fd12b299), [`fdac646`](https://github.com/mastra-ai/mastra/commit/fdac646033a0930a1a4e00d13aa64c40bb7f1e02), [`d07b568`](https://github.com/mastra-ai/mastra/commit/d07b5687819ea8cb1dffa776d0c1765faf4aa1ae), [`68ec97d`](https://github.com/mastra-ai/mastra/commit/68ec97d4c07c6393fcf95c2481fc5d73da99f8c8), [`4aa55b3`](https://github.com/mastra-ai/mastra/commit/4aa55b383cf06043943359ea316572fd969861a7)]:
+  - @mastra/core@1.0.0-beta.19
+
 ## 1.0.0-beta.10
 
 ### Patch Changes

package/dist/docs/README.md

@@ -0,0 +1,36 @@
+# @mastra/pg Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── memory/ (4 files)
+├── processors/ (3 files)
+├── rag/ (4 files)
+├── storage/ (3 files)
+├── tools/ (1 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/pg
+Version: 1.0.0-beta.12

package/dist/docs/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: mastra-pg-docs
+description: Documentation for @mastra/pg. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/pg Documentation
+
+> **Version**: 1.0.0-beta.12
+> **Package**: @mastra/pg
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Memory](memory/) - 4 file(s)
+- [Processors](processors/) - 3 file(s)
+- [Rag](rag/) - 4 file(s)
+- [Storage](storage/) - 3 file(s)
+- [Tools](tools/) - 1 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0-beta.12",
+  "package": "@mastra/pg",
+  "exports": {},
+  "modules": {}
+}

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

@@ -0,0 +1,181 @@
+> Configure storage for Mastra
+
+# Storage
+
+For Mastra to remember previous interactions, you must configure a storage adapter. Mastra is designed to work with your preferred database provider - choose from the [supported providers](#supported-providers) and pass it to your Mastra instance.
+
+```typescript 
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+
+const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: "file:./mastra.db",
+  }),
+});
+```
+On first interaction, Mastra automatically creates the necessary tables following the [core schema](https://mastra.ai/reference/v1/storage/overview#core-schema). This includes tables for messages, threads, resources, workflows, traces, and evaluation datasets.
+
+## Supported Providers
+
+Each provider page includes installation instructions, configuration parameters, and usage examples:
+
+- [libSQL Storage](https://mastra.ai/reference/v1/storage/libsql)
+- [PostgreSQL Storage](https://mastra.ai/reference/v1/storage/postgresql)
+- [MongoDB Storage](https://mastra.ai/reference/v1/storage/mongodb)
+- [Upstash Storage](https://mastra.ai/reference/v1/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/v1/storage/cloudflare-d1)
+- [Cloudflare Durable Objects](https://mastra.ai/reference/v1/storage/cloudflare)
+- [Convex](https://mastra.ai/reference/v1/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/v1/storage/dynamodb)
+- [LanceDB](https://mastra.ai/reference/v1/storage/lance)
+- [Microsoft SQL Server](https://mastra.ai/reference/v1/storage/mssql)
+
+> **Note:**
+libSQL is the easiest way to get started because it doesn’t require running a separate database server
+
+## Configuration Scope
+
+You can configure storage at two different scopes:
+
+### Instance-level storage
+
+Add storage to your Mastra instance so all agents share the same memory provider:
+
+```typescript 
+import { Mastra } from "@mastra/core";
+import { PostgresStore } from "@mastra/pg";
+
+const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+});
+
+// All agents automatically use this storage
+const agent1 = new Agent({ memory: new Memory() });
+const agent2 = new Agent({ memory: new Memory() });
+```
+
+### Agent-level storage
+
+Add storage to a specific agent when you need data boundaries or compliance requirements:
+
+```typescript 
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
+
+const agent = new Agent({
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'agent-storage',
+      connectionString: process.env.AGENT_DATABASE_URL,
+    }),
+  }),
+});
+```
+
+This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
+
+## Threads and Resources
+
+Mastra organizes memory into threads using two identifiers:
+
+- **Thread**: A conversation session containing a sequence of messages (e.g., `convo_123`)
+- **Resource**: An identifier for the entity the thread belongs to, typically a user (e.g., `user_123`)
+
+Both identifiers are required for agents to store and recall information:
+
+```typescript 
+const stream = await agent.stream("message for agent", {
+  memory: {
+    thread: "convo_123",
+    resource: "user_123",
+  },
+});
+```
+
+> **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 title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message.
+
+Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
+
+```typescript 
+export const testAgent = new Agent({
+  memory: new Memory({
+    options: {
+      generateTitle: true,
+    },
+  }),
+});
+```
+
+Title generation runs asynchronously after the agent responds and does not affect response time.
+
+To optimize cost or behavior, provide a smaller `model` and custom `instructions`:
+
+```typescript
+export const testAgent = new Agent({
+  memory: new Memory({
+    options: {
+      threads: {
+        generateTitle: {
+          model: "openai/gpt-4o-mini",
+          instructions: "Generate a concise title based on the user's first message",
+        },
+      },
+    },
+  }),
+});
+```
+
+## Semantic recall
+
+Semantic recall uses vector embeddings to retrieve relevant past messages based on meaning rather than recency. This requires a vector database instance, which can be configured at the instance or agent level.
+
+The vector database doesn't have to be the same as your storage provider. For example, you might use PostgreSQL for storage and Pinecone for vectors:
+
+```typescript 
+import { Mastra } from "@mastra/core";
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
+import { PineconeVector } from "@mastra/pinecone";
+
+// Instance-level vector configuration
+const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+});
+
+// Agent-level vector configuration
+const agent = new Agent({
+  memory: new Memory({
+    vector: new PineconeVector({
+      id: 'agent-vector',
+      apiKey: process.env.PINECONE_API_KEY,
+      environment: process.env.PINECONE_ENVIRONMENT,
+      indexName: 'agent-embeddings',
+    }),
+    options: {
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+We support all popular vector providers including [Pinecone](https://mastra.ai/reference/v1/vectors/pinecone), [Chroma](https://mastra.ai/reference/v1/vectors/chroma), [Qdrant](https://mastra.ai/reference/v1/vectors/qdrant), and many more.
+
+For more information on configuring semantic recall, see the [Semantic Recall](./semantic-recall) documentation.