MSSQL 存储

🌐 MSSQL Storage

MSSQL 存储实现提供了一个可用于生产的存储解决方案，使用 Microsoft SQL Server 数据库。

🌐 The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.

安装

🌐 Installation

npm

npm install @mastra/mssql@latest

pnpm

pnpm add @mastra/mssql@latest

Yarn

yarn add @mastra/mssql@latest

Bun

bun add @mastra/mssql@latest

用法

🌐 Usage

import { MSSQLStore } from "@mastra/mssql";

const storage = new MSSQLStore({
  id: 'mssql-storage',
  connectionString: process.env.DATABASE_URL,
});

参数

🌐 Parameters

connectionString:

string

MSSQL connection string (e.g., Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true)

schemaName?:

string

The name of the schema you want the storage to use. Will use the default schema if not provided.

构造函数示例

🌐 Constructor Examples

你可以通过以下方式实例化 MSSQLStore：

🌐 You can instantiate MSSQLStore in the following ways:

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：存储工作流状态和执行数据
• mastra_evals：存储评估结果和元数据
• mastra_threads：存储对话线程
• mastra_messages：存储单条消息
• mastra_traces：存储遥测和跟踪数据
• mastra_scorers：存储评分和评估数据
• mastra_resources：存储资源工作内存数据

初始化

🌐 Initialization

当你将存储传递给 Mastra 类时，init() 会在任何存储操作之前自动调用：

🌐 When you pass storage to the Mastra class, init() is called automatically before any storage operation:

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
});

如果你直接使用存储而不使用 Mastra，必须显式调用 init() 来创建表格：

🌐 If you're using storage directly without Mastra, you must call init() explicitly to create the tables:

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: "..." });

warning

如果未调用 init()，表将不会被创建，存储操作可能会静默失败或抛出错误。

直接数据库和连接池访问

🌐 Direct Database and Pool Access

MSSQLStore 将 mssql 连接池作为公共字段公开：

store.pool; // mssql connection pool instance

这使得可以进行直接查询和自定义事务管理。使用这些字段时：

🌐 This enables direct queries and custom transaction management. When using these fields:

• 你负责正确的连接和事务处理。
• 关闭存储（store.close()）将会销毁相关的连接池。
• 直接访问会绕过 MSSQLStore 方法提供的任何额外逻辑或验证。

这种方法适用于需要低级访问的高级场景。

🌐 This approach is intended for advanced scenarios where low-level access is required.