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

# 託管資料庫

從 CLI 或 [platform](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview) 專案設定佈建全代管資料庫，並將其附加至專案。Mastra 會透過 Provider 建立資料庫並安全地儲存憑證；資料庫就緒後，也會將連線詳細資料注入為執行階段環境變數，因此不必複製或設定連線字串。

```bash
mastra env db create --kind turso
```

## 使用託管資料庫的時機

當專案需要由 platform 管理的持久儲存空間時，請使用託管資料庫，包括：

- **Agent 記憶體**：保存對話記錄與工作記憶體，並支援跨工作階段的語意回憶。
- **應用程式資料**：儲存及擷取專案在執行階段所需的關聯式或結構化資料。
- **向量搜尋**：儲存用於檢索增強生成與語意搜尋的嵌入向量。

## Provider

託管資料庫目前可透過 Turso 與 Postgres 這兩個 Provider 使用，MongoDB 即將推出。附加資料庫時選擇一個 Provider，再於程式碼中將其注入的變數連接至對應的 Mastra 儲存配接器。

每個 Provider 都會注入一組固定名稱的變數，例如 Postgres 使用單一 `DATABASE_URL`，Turso 則使用個別的 `TURSO_*` 變數。這些名稱在每個環境中必須是唯一的，亦即一個環境對每個 Provider 最多只能使用一個資料庫。若不同工作負載需要個別的儲存空間，可將 Turso 和 Postgres 附加至同一專案。

對大多數以 Agent 為主的專案而言，**Turso** 是最簡單的起點。它提供輕量且與 SQLite 相容的引擎，很適合 Agent 記憶體、對話記錄和租戶隔離。若工作負載需要完整 SQL、關聯式結構描述，或 Mastra 執行階段狀態以外的結構化應用程式資料，請選擇 **Postgres**。**MongoDB**（_即將推出_）將為不易對應至 SQL 的工作負載加入文件儲存和內建向量搜尋。

| Provider       | 引擎                  | 最適合用途             |
| -------------- | ------------------- | ----------------- |
| **Turso**      | LibSQL，與 SQLite 相容  | Agent 記憶體、租戶隔離    |
| **PostgreSQL** | Serverless Postgres | 關聯式工作負載、結構化資料     |
| **MongoDB**    | 文件與向量搜尋             | 文件儲存、向量搜尋（_即將推出_） |

## 資料庫範圍

資料庫會附加於以下兩種範圍之一：

- **環境範圍**：預設選項。附加至單一環境，讓不同環境的資料彼此隔離（例如分開的正式與預備資料庫）。專案只有一個環境時，`mastra env db create` 會自動選取；若有多個環境，CLI 會提示你選擇。
- **專案範圍**：由專案所有[環境](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/environments)共用的一個資料庫。使用 `--shared` 選用。其變數會注入每次部署。

範圍會在附加資料庫時設定，並顯示於 `mastra env db list`。

同一 Provider 的範圍不能重疊。由於專案範圍資料庫已將其變數注入每個環境，若再附加同一 Provider 的環境範圍資料庫，會因變數名稱衝突而遭拒。若要從共用資料庫改成各環境個別使用資料庫，請先刪除專案範圍資料庫，再為每個環境各附加一個資料庫。刪除資料庫會一併刪除 Provider 中的資料庫及其所有資料，因此切換範圍前請先匯出需要保留的內容。不同環境中的環境範圍資料庫絕不會衝突；每次部署只會收到所屬環境的變數。

## 使用 CLI 附加

你不必預先執行這個指令。如果專案需要託管資料庫但尚未建立，`mastra deploy` 會在部署前檢查執行時詢問是否要附加。接受後，部署會直接在 CLI 中繼續進行。

你也可以預先建立並附加資料庫。CLI 會輪詢直到資料庫就緒，通常只需幾秒：

```bash
# Scoped to a single environment (the CLI picks the only one, or prompts if there are several)
mastra env db create --kind turso

# Scoped to a specific environment
mastra env db create staging --kind turso

# Shared by all environments
mastra env db create --kind turso --shared
```

支援的種類為 `turso` 與 `neon`（Postgres）。實用旗標：

- `--shared`：附加由每個環境共用的專案範圍資料庫。不能與環境引數併用。
- `--name <name>`：資料庫名稱。預設為衍生自專案 slug 的名稱。
- `--region <region>`：專案範圍資料庫的 Provider 區域 ID（例如 `fra`）。環境範圍資料庫會自動放在靠近環境區域的位置，明確指定的 `--region` 會被忽略。
- `--no-wait`：立即返回而不輪詢。之後可使用 `mastra env db show` 查看進度。
- `--json`：機器可讀的輸出。專案有多個環境時，`--json` 必須搭配環境引數或 `--shared`（不會顯示互動式提示）。

檢視及管理已附加的資料庫：

```bash
mastra env db list
mastra env db show <database>
mastra env db delete <database>
```

`mastra env db list` 會顯示每個資料庫的種類、狀態、範圍和注入的變數名稱。`mastra env db show` 會列出連線指示，並遮蔽密鑰值。傳入 `--show-secrets` 即可顯示密鑰。`mastra env db delete` 會永久刪除 Provider 中的資料庫及其所有資料。建立及刪除資料庫需要組織中的管理員角色。

## 從專案設定附加

1. 在 [platform](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview) 中開啟專案，然後前往**專案設定**。

2. 開啟**資料庫**區段，然後選取**新增資料庫**。

3. 選取 **Provider**（Turso 或 Postgres）。附加前仍可切換 Provider。

4. 設定資料庫：

   - **名稱**：資料庫在專案內的標籤。
   - **區域**：資料庫的託管位置。請選取最靠近使用者的區域。Turso 預設為 `sjc`（聖荷西），在全球 20 多個地點提供服務。Postgres 預設為 `aws-us-west-2`，可在美國、歐盟和亞太地區的 AWS 與 Azure 區域使用。

5. 選取**附加資料庫**。佈建會在背景執行。資料庫一開始處於 `provisioning` 狀態，Provider 完成設定後便會變成 `ready`。連線詳細資料會自動以 Server 執行階段環境變數的形式注入專案。

從專案設定附加的資料庫屬於專案範圍。若要附加環境範圍資料庫，請使用 [CLI](#attach-with-the-cli)。

## 從程式碼連線

資料庫為 `ready` 時，表示 Provider 已完成佈建，platform 也已將連線詳細資料注入為受管理的環境變數。請在**專案設定 → 資料庫**中查看狀態；設定於背景執行時，每個已附加的資料庫都會顯示 `provisioning`，可以連線時則顯示 `ready`。開啟 `ready` 資料庫即可查看其環境變數和可直接複製貼上的程式碼片段。將這些變數連接至 Mastra 儲存配接器即可，不需手動設定。

### Turso (LibSQL)

Turso 會公開兩個環境變數：`TURSO_DATABASE_URL` 與 `TURSO_AUTH_TOKEN`。以下範例使用這些變數連接 [LibSQLStore](https://mastra.zisheng.pro/zh-TW/reference/storage/libsql)。

```ts
import { LibSQLStore } from '@mastra/libsql'

export const storage = new LibSQLStore({
  id: 'mastra-storage',
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
})
```

安裝配接器：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

### PostgreSQL

PostgreSQL 會公開單一 `DATABASE_URL` 連線字串。以下範例使用該變數連接 [PostgresStore](https://mastra.zisheng.pro/zh-TW/reference/storage/postgresql)。

```ts
import { PostgresStore } from '@mastra/pg'

export const storage = new PostgresStore({
  connectionString: process.env.DATABASE_URL!,
})
```

安裝配接器：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

將 `storage` 執行個體傳入 `Mastra` 設定，讓 Agent、記憶體和 Workflow 可以使用它：

```ts
import { Mastra } from '@mastra/core'
import { storage } from './storage'

export const mastra = new Mastra({
  storage,
})
```

## 環境變數

每個 Provider 都會注入一組固定的受管理環境變數。資料庫為 `ready` 時，專案可在執行階段使用這些變數。你不必自行定義。

| Provider | 變數                                       |
| -------- | ---------------------------------------- |
| Turso    | `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN` |
| Postgres | `DATABASE_URL`                           |

> **警告:** 請將連線憑證視為密鑰。驗證權杖 (`TURSO_AUTH_TOKEN`) 和 Postgres 連線字串 (`DATABASE_URL`) 可完整存取你的資料。platform 預設會遮蔽這些值，只有在要求時才會顯示。

## 管理資料庫

- **檢視連線詳細資料**：在專案設定中開啟 `ready` 資料庫，查看其環境變數和可直接複製貼上的程式碼片段。
- **刪除**：從專案移除資料庫會一併刪除 Provider 中的資料庫，並清除注入的環境變數。此操作無法復原，請確認不再需要資料。