@mastra/mssql 0.0.0-iterate-traces-ui-again-20250912091900 → 0.0.0-jail-fs-20260105160110

package/README.md

@@ -17,78 +17,365 @@ npm install @mastra/mssql
 
 ### Storage
 
+#### Basic Configuration
+
+MSSQLStore supports multiple connection methods:
+
+**1. Connection String (Recommended)**
+
 ```typescript
 import { MSSQLStore } from '@mastra/mssql';
 
 const store = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString:
+    'Server=localhost,1433;Database=mastra;User Id=sa;Password=yourPassword;Encrypt=true;TrustServerCertificate=true',
+});
+```
+
+**2. Server/Port/Database Configuration**
+
+```typescript
+const store = new MSSQLStore({
+  id: 'mssql-storage',
   server: 'localhost',
   port: 1433,
   database: 'mastra',
   user: 'sa',
   password: 'yourStrong(!)Password',
-  // options: { encrypt: true, trustServerCertificate: true }, // Optional
+  options: { encrypt: true, trustServerCertificate: true }, // Optional
 });
+```
 
-// Create a thread
-await store.saveThread({
-  id: 'thread-123',
-  resourceId: 'resource-456',
-  title: 'My Thread',
-  metadata: { key: 'value' },
+#### Advanced Options
+
+```typescript
+const store = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString:
+    'Server=localhost,1433;Database=mastra;User Id=sa;Password=yourPassword;Encrypt=true;TrustServerCertificate=true',
+  schemaName: 'custom_schema', // Use custom schema (default: dbo)
+  options: {
+    encrypt: true,
+    trustServerCertificate: true,
+    connectTimeout: 30000,
+    requestTimeout: 30000,
+    pool: {
+      max: 20,
+      min: 0,
+      idleTimeoutMillis: 30000,
+    },
+  },
 });
+```
 
-// Add messages to thread
-await store.saveMessages([
-  {
-    id: 'msg-789',
-    threadId: 'thread-123',
-    role: 'user',
-    type: 'text',
-    content: [{ type: 'text', text: 'Hello' }],
+#### Usage Example
+
+```typescript
+// Create a thread
+await store.saveThread({
+  thread: {
+    id: 'thread-123',
     resourceId: 'resource-456',
+    title: 'My Thread',
+    metadata: { key: 'value' },
     createdAt: new Date(),
+    updatedAt: new Date(),
   },
-]);
+});
+
+// Add messages to thread
+await store.saveMessages({
+  messages: [
+    {
+      id: 'msg-789',
+      threadId: 'thread-123',
+      role: 'user',
+      type: 'text',
+      content: [{ type: 'text', text: 'Hello' }],
+      resourceId: 'resource-456',
+      createdAt: new Date(),
+    },
+  ],
+});
 
 // Query threads and messages
 const savedThread = await store.getThreadById({ threadId: 'thread-123' });
-const messages = await store.getMessages({ threadId: 'thread-123' });
+const messages = await store.listMessages({ threadId: 'thread-123' });
 ```
 
 ## Configuration
 
-The MSSQL store can be initialized with either:
+### Identifier
+
+- `id`: Unique identifier for this store instance (required)
+
+### Connection Methods
+
+MSSQLStore supports multiple connection methods:
+
+1. **Connection String**
+
+   ```typescript
+   {
+     id: 'mssql-storage',
+     connectionString: 'Server=localhost,1433;Database=mastra;User Id=sa;Password=yourPassword;Encrypt=true;TrustServerCertificate=true';
+   }
+   ```
+
+2. **Server/Port/Database**
+   ```typescript
+   {
+     id: 'mssql-storage',
+     server: 'localhost',
+     port: 1433,
+     database: 'mastra',
+     user: 'sa',
+     password: 'password'
+   }
+   ```
+
+### Optional Configuration
 
-- `connectionString`: Microsoft SQL Server connection string
-- Configuration object with server, port, database, user, and password
+- `schemaName`: Custom SQL Server schema (default: `dbo`)
+- `options.encrypt`: Enable encryption (default: `true`)
+- `options.trustServerCertificate`: Trust self-signed certificates (default: `true`)
+- `options.connectTimeout`: Connection timeout in milliseconds (default: `15000`)
+- `options.requestTimeout`: Request timeout in milliseconds (default: `15000`)
+- `options.pool.max`: Maximum pool connections (default: `10`)
+- `options.pool.min`: Minimum pool connections (default: `0`)
+- `options.pool.idleTimeoutMillis`: Idle connection timeout (default: `30000`)
 
-Connection pool settings are managed by the [mssql](https://www.npmjs.com/package/mssql) package.
+### Default Connection Pool Settings
+
+- Maximum connections: 10
+- Minimum connections: 0
+- Idle timeout: 30 seconds
+- Connection timeout: 15 seconds
+- Request timeout: 15 seconds
 
 ## Features
 
-- Thread and message storage with JSON support
-- Atomic transactions for data consistency
-- Efficient batch operations
-- Rich metadata support
-- Timestamp tracking
-- Cascading deletes (emulated)
+### Storage Features
+
+- **Thread and Message Management**
+  - Thread and message storage with JSON support
+  - Message format versioning (v1 and v2)
+  - Pagination support for threads and messages
+  - Atomic transactions for batch operations (save, update, delete)
+  - Automatic thread timestamp updates
+  - Cascading deletes
+- **Resources**
+  - Resource storage with working memory
+  - Rich metadata support
+  - Update working memory and metadata independently
+
+- **Tracing & Observability**
+  - Trace AI agent execution with spans
+  - Query traces with pagination and filtering
+  - Batch operations for high-volume tracing
+  - Parent-child span relationships
+  - Span metadata and timing information
+
+- **Workflow Management**
+  - Persist and restore workflow execution state
+  - Track workflow run history
+  - Step-by-step result tracking with row-level locking
+  - Workflow status management with row-level locking
+  - Query workflow runs by date range or resource
+  - Concurrent update protection for parallel workflow execution
+
+- **Scoring & Evaluation**
+  - Store evaluation scores and metrics
+  - Query scores by scorer, run, entity, or span
+  - Support for multiple scoring sources
+  - Pagination support for large score datasets
+
+- **Performance & Scalability**
+  - Connection pooling with configurable limits
+  - Atomic transactions for all batch operations
+  - Efficient batch insert/update/delete with transaction safety
+  - Row-level locking for concurrent updates
+  - Automatic performance indexes
+  - Index management (create, list, describe, drop)
+  - Timestamp tracking with high precision
+- **Data Management**
+  - Custom schema support
+  - Table operations (create, alter, clear, drop)
+  - Low-level insert and load operations
+  - JSON data type support
 
 ## Storage Methods
 
+### Initialization & Connection
+
+- `init()`: Initialize the store and create tables
+- `close()`: Close database connection pool
+
+### Threads
+
 - `saveThread({ thread })`: Create or update a thread
 - `getThreadById({ threadId })`: Get a thread by ID
+- `updateThread({ id, title, metadata })`: Update thread title and metadata
 - `deleteThread({ threadId })`: Delete a thread and its messages
-- `saveMessages({ messages })`: Save multiple messages in a transaction
-- `getMessages({ threadId })`: Get all messages for a thread
-- `updateMessages({ messages })`: Update messages by ID
-- `getThreadsByResourceIdPaginated({ resourceId, page, perPage })`: Paginated thread listing
-- `getMessagesPaginated({ threadId, selectBy })`: Paginated message listing
-- `clearTable({ tableName })`: Remove all rows from a table (with cascade)
-- `createTable({ tableName, schema })`: Create a table if it does not exist
-- `alterTable({ tableName, schema, ifNotExists })`: Add columns if they do not exist
-- `saveResource({ resource })`: Save a resource
+- `listThreadsByResourceId({ resourceId, offset, limit, orderBy? })`: List paginated threads for a resource
+
+### Messages
+
+- `saveMessages({ messages })`: Save multiple messages with atomic transaction
+- `listMessagesById({ messageIds })`: Get messages by their IDs
+- `listMessages({ threadId, resourceId?, page?, perPage?, orderBy?, filter? })`: Get paginated messages for a thread with filtering and sorting
+- `updateMessages({ messages })`: Update existing messages with atomic transaction
+- `deleteMessages(messageIds)`: Delete specific messages with atomic transaction
+
+### Resources
+
+- `saveResource({ resource })`: Save a resource with working memory
 - `getResourceById({ resourceId })`: Get a resource by ID
-- `updateResource({ resourceId, ... })`: Update a resource
+- `updateResource({ resourceId, workingMemory?, metadata? })`: Update resource working memory and metadata
+
+### Tracing & Observability
+
+- `createSpan(span)`: Create a trace span
+- `updateSpan({ spanId, traceId, updates })`: Update an existing span
+- `getTrace(traceId)`: Get complete trace with all spans
+- `getTracesPaginated({ filters?, pagination? })`: Query traces with pagination and filters
+- `batchCreateSpans({ records })`: Batch create multiple spans
+- `batchUpdateSpans({ records })`: Batch update multiple spans
+- `batchDeleteTraces({ traceIds })`: Batch delete traces
+
+### Index Management
+
+- `createIndex({ name, table, columns, unique?, where? })`: Create a new index
+- `listIndexes(tableName?)`: List all indexes or indexes for a specific table
+- `describeIndex(indexName)`: Get detailed index statistics and information
+- `dropIndex(indexName)`: Drop an existing index
+
+### Workflows
+
+- `persistWorkflowSnapshot({ workflowName, runId, resourceId?, snapshot })`: Save workflow execution state
+- `loadWorkflowSnapshot({ workflowName, runId })`: Load workflow execution state
+- `updateWorkflowResults({ workflowName, runId, stepId, result, runtimeContext })`: Update step results (transaction + row locking)
+- `updateWorkflowState({ workflowName, runId, opts })`: Update workflow run status (transaction + row locking)
+- `listWorkflowRuns({ workflowName?, fromDate?, toDate?, limit?, offset?, resourceId? })`: Query workflow runs
+- `getWorkflowRunById({ runId, workflowName? })`: Get specific workflow run
+
+### Scores & Evaluation
+
+- `saveScore(score)`: Save evaluation score
+- `getScoreById({ id })`: Get score by ID
+- `listScoresByScorerId({ scorerId, pagination, entityId?, entityType?, source? })`: Get scores by scorer
+- `listScoresByRunId({ runId, pagination })`: Get scores for a run
+- `listScoresByEntityId({ entityId, entityType, pagination })`: Get scores for an entity
+- `listScoresBySpan({ traceId, spanId, pagination })`: Get scores for a trace span
+
+### Traces (Legacy)
+
+- `getTracesPaginated({ filters?, pagination? })`: Get paginated legacy traces
+- `batchTraceInsert({ records })`: Batch insert legacy trace records
+
+### Evals (Legacy)
+
+- `getEvals({ agentName?, type?, page?, perPage? })`: Get paginated evaluations
+
+### Low-level Operations
+
+- `createTable({ tableName, schema })`: Create a new table
+- `alterTable({ tableName, schema, ifNotExists })`: Add columns to existing table
+- `clearTable({ tableName })`: Remove all rows from a table
+- `dropTable({ tableName })`: Drop a table
+- `insert({ tableName, record })`: Insert a single record
+- `batchInsert({ tableName, records })`: Batch insert multiple records
+- `load<R>({ tableName, keys })`: Load a record by key(s)
+
+## Index Management
+
+The MSSQL store provides comprehensive index management capabilities to optimize query performance.
+
+### Automatic Performance Indexes
+
+MSSQL storage automatically creates composite indexes during initialization for common query patterns. These indexes significantly improve performance for filtered queries with sorting.
+
+### Creating Custom Indexes
+
+```typescript
+// Basic index for common queries
+await store.createIndex({
+  name: 'idx_threads_resource',
+  table: 'mastra_threads',
+  columns: ['resourceId'],
+});
+
+// Composite index with sort order for filtering + sorting
+await store.createIndex({
+  name: 'idx_messages_composite',
+  table: 'mastra_messages',
+  columns: ['thread_id', 'seq_id DESC'],
+});
+
+// Unique index for constraints
+await store.createIndex({
+  name: 'idx_unique_constraint',
+  table: 'mastra_resources',
+  columns: ['id'],
+  unique: true,
+});
+
+// Filtered index (partial indexing)
+await store.createIndex({
+  name: 'idx_active_threads',
+  table: 'mastra_threads',
+  columns: ['resourceId'],
+  where: "status = 'active'",
+});
+```
+
+### Managing Indexes
+
+```typescript
+// List all indexes
+const allIndexes = await store.listIndexes();
+
+// List indexes for specific table
+const threadIndexes = await store.listIndexes('mastra_threads');
+
+// Get detailed statistics for an index
+const stats = await store.describeIndex('idx_threads_resource');
+console.log(stats);
+// {
+//   name: 'idx_threads_resource',
+//   table: 'mastra_threads',
+//   columns: ['resourceId', 'seq_id'],
+//   unique: false,
+//   size: '128 KB',
+//   method: 'nonclustered',
+//   scans: 1542,           // Number of index seeks
+//   tuples_read: 45230,    // Tuples read via index
+//   tuples_fetched: 12050  // Tuples fetched via index
+// }
+
+// Drop an index
+await store.dropIndex('idx_threads_resource');
+```
+
+### Monitoring Index Performance
+
+```typescript
+// Check index usage statistics
+const stats = await store.describeIndex('idx_threads_resource');
+
+// Identify unused indexes
+if (stats.scans === 0) {
+  console.log(`Index ${stats.name} is unused - consider removing`);
+  await store.dropIndex(stats.name);
+}
+
+// Monitor index efficiency
+const efficiency = stats.tuples_fetched / stats.tuples_read;
+if (efficiency < 0.5) {
+  console.log(`Index ${stats.name} has low efficiency: ${efficiency}`);
+}
+```
 
 ## Related Links
 

package/dist/docs/README.md

@@ -0,0 +1,31 @@
+# @mastra/mssql 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
+├── storage/ (1 files)
+```
+
+## Version
+
+Package: @mastra/mssql
+Version: 1.0.0-beta.9

package/dist/docs/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mastra-mssql-docs
+description: Documentation for @mastra/mssql. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/mssql Documentation
+
+> **Version**: 1.0.0-beta.9
+> **Package**: @mastra/mssql
+
+## 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
+
+- [Storage](storage/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

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

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

@@ -0,0 +1,141 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: MSSQL Storage
+
+> Documentation for the MSSQL storage implementation in Mastra.
+
+The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.
+
+## Installation
+
+```bash
+npm install @mastra/mssql@beta
+```
+
+## Usage
+
+```typescript
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## Parameters
+
+## Constructor Examples
+
+You can instantiate `MSSQLStore` in the following ways:
+
+```ts
+import { MSSQLStore } from "@mastra/mssql";
+
+// Using a connection string only
+const store1 = new MSSQLStore({
+  id: 'mssql-storage-1',
+  connectionString: "Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true",
+});
+
+// Using a connection string with a custom schema name
+const store2 = new MSSQLStore({
+  id: 'mssql-storage-2',
+  connectionString: "Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true",
+  schemaName: "custom_schema", // optional
+});
+
+// Using individual connection parameters
+const store4 = new MSSQLStore({
+  id: 'mssql-storage-3',
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+});
+
+// Individual parameters with schemaName
+const store5 = new MSSQLStore({
+  id: 'mssql-storage-4',
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+  schemaName: "custom_schema", // optional
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `mastra_workflow_snapshot`: Stores workflow state and execution data
+- `mastra_evals`: Stores evaluation results and metadata
+- `mastra_threads`: Stores conversation threads
+- `mastra_messages`: Stores individual messages
+- `mastra_traces`: Stores telemetry and tracing data
+- `mastra_scorers`: Stores scoring and evaluation data
+- `mastra_resources`: Stores resource working memory data
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+});
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Required when using storage directly
+await storage.init();
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+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.
+
+### Direct Database and Pool Access
+
+`MSSQLStore` exposes the mssql connection pool as public fields:
+
+```typescript
+store.pool; // mssql connection pool instance
+```
+
+This enables direct queries and custom transaction management. When using these fields:
+
+- You are responsible for proper connection and transaction handling.
+- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Direct access bypasses any additional logic or validation provided by MSSQLStore methods.
+
+This approach is intended for advanced scenarios where low-level access is required.