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

# 託管數據庫

透過 CLI 或 [platform](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/overview) 項目設定佈建全託管數據庫，並連接至你的項目。Mastra 會透過你的 Provider 建立數據庫並安全儲存憑證；數據庫準備就緒後，亦會將連線資料注入為執行階段環境變數，因此你毋須複製或設定連線字串。

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

## 何時使用託管數據庫

當項目需要由 platform 管理的持久儲存空間時，可使用託管數據庫，包括：

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

## Provider

託管數據庫目前由 Turso 及 Postgres 兩個 Provider 提供，MongoDB 則即將推出。連接數據庫時選擇其中一個，然後在程式碼中將注入的變數接駁至相應的 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-HK/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-HK/docs/mastra-platform/overview) 開啟項目，然後前往 **Project Settings**。

2. 開啟 **Database** 部分，然後選擇 **Add database**。

3. 選擇 **Provider**（Turso 或 Postgres）。連接前可切換 Provider。

4. 設定數據庫：

   - **名稱**：數據庫在項目內的標籤。
   - **區域**：託管數據庫的位置。請選擇最接近用戶的區域。Turso 預設為 `sjc`（聖荷西），在全球逾 20 個地點提供服務。Postgres 預設為 `aws-us-west-2`，並在美國、歐盟及亞太地區的 AWS 和 Azure 區域提供服務。

5. 選擇 **Attach database**。佈建程序會在背景執行。數據庫最初處於 `provisioning` 狀態；Provider 完成設定後，便會轉為 `ready`。連線資料會自動以伺服器執行階段環境變數注入項目。

從項目設定連接的數據庫均屬項目範圍。要連接環境範圍數據庫，請使用 [CLI](#attach-with-the-cli)。

## 從程式碼連線

數據庫變為 `ready` 時，表示 Provider 已完成佈建，而 platform 亦已將連線資料注入為受管理的環境變數。你可在 **Project Settings → Database** 查看狀態；設定在背景執行期間，每個已連接數據庫會顯示 `provisioning`，可供連線時則顯示 `ready`。開啟 `ready` 數據庫，即可查看其環境變數及可直接複製貼上的程式碼片段。將這些變數接駁至 Mastra 儲存適配器即可，毋須手動設定。

### Turso（LibSQL）

Turso 提供兩個環境變數：`TURSO_DATABASE_URL` 及 `TURSO_AUTH_TOKEN`。以下範例使用這些變數連接 [LibSQLStore](https://mastra.zisheng.pro/zh-HK/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-HK/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 端將其刪除，並清除已注入的環境變數。此操作無法復原，請確定不再需要相關數據。