> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# MSSQL 儲存空間

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

## 安裝

**npm**:

```bash
npm install @mastra/mssql@latest
```

**pnpm**:

```bash
pnpm add @mastra/mssql@latest
```

**Yarn**:

```bash
yarn add @mastra/mssql@latest
```

**Bun**:

```bash
bun add @mastra/mssql@latest
```

## 使用方式

```typescript
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` 執行個體：

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

## 其他注意事項

### 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()`：

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

若不透過 Mastra 而直接使用 storage，必須明確呼叫 `init()` 來建立資料表：

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

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

### 直接存取資料庫與連線池

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

```typescript
store.pool // mssql connection pool instance
```

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

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

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