跳至主要內容

MSSQL 儲存空間

MSSQL 儲存空間實作採用 Microsoft SQL Server 資料庫，提供可用於正式環境的儲存解決方案。

安裝
「安裝」的直接連結

npm install @mastra/mssql@latest

使用方式
「使用方式」的直接連結

import { MSSQLStore } from '@mastra/mssql'

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

參數
「參數」的直接連結

connectionString:

string
MSSQL 連線字串（例如 Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true）

schemaName?:

string
希望儲存空間使用的 schema 名稱。若未提供，將使用預設 schema。

建構函式範例
「建構函式範例」的直接連結

你可以使用下列方式建立 MSSQLStore 執行個體：

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

其他注意事項
「其他注意事項」的直接連結

Schema 管理
「Schema 管理」的直接連結

儲存空間實作會自動處理 schema 的建立與更新，並建立下列資料表：

  • mastra_workflow_snapshot：儲存 Workflow 狀態與執行資料
  • mastra_evals：儲存評估結果與 metadata
  • mastra_threads：儲存對話 thread
  • mastra_messages：儲存個別訊息
  • mastra_traces：儲存遙測與 tracing 資料
  • mastra_scorers：儲存評分與評估資料
  • mastra_resources：儲存資源的 working memory 資料

初始化
「初始化」的直接連結

將 storage 傳入 Mastra 類別時，系統會在進行任何儲存操作前自動呼叫 init()：

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 而直接使用 storage，必須明確呼叫 init() 來建立資料表：

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: '...' })
警告

若未呼叫 init()，系統不會建立資料表，儲存操作將會無聲失敗或擲回錯誤。

直接存取資料庫與連線池
「直接存取資料庫與連線池」的直接連結

MSSQLStore 以公開欄位提供 mssql 連線池：

store.pool // mssql connection pool instance

它支援直接查詢與自訂交易管理。使用這些欄位時：

  • 你必須負責正確處理連線與交易。
  • 關閉 store（store.close()）會銷毀相關連線池。
  • 直接存取會略過 MSSQLStore 方法提供的任何額外邏輯或驗證。

此方式適用於需要低階存取的進階情境。

On this page