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

# 托管数据库

通过 CLI 或 [platform](https://mastra.zisheng.pro/docs/mastra-platform/overview) 项目设置预配完全托管的数据库，并将其关联到项目。Mastra 会通过 Provider 创建数据库并安全存储凭据；数据库就绪后，还会将连接详情作为运行时环境变量注入，因此无需复制或配置连接字符串。

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

## 何时使用托管数据库

当项目需要由 platform 管理的持久 Storage 时，请使用托管数据库，包括：

- **Agent Memory**：持久化对话历史记录和 working memory，并支持跨会话的 semantic recall。
- **应用数据**：存储并检索项目在运行时所需的关系型或结构化数据。
- **向量搜索**：存储用于检索增强生成和语义搜索的 embedding。

## Provider

目前，托管数据库可通过 Turso 和 Postgres 两种 Provider 使用，MongoDB 即将推出。关联数据库时选择一种 Provider，然后在代码中将其注入的变量连接到匹配的 Mastra Storage adapter。

每种 Provider 都会注入一组固定的变量名称，例如 Postgres 使用一个 `DATABASE_URL`，Turso 则使用多个 `TURSO_*` 变量。这些名称在每个环境中必须唯一，因此每个环境对每种 Provider 最多只能使用一个数据库。如果不同工作负载需要独立的 Store，可以将 Turso 和 Postgres 同时关联到同一个项目。

对于大多数以 Agent 为中心的项目，**Turso** 是最简单的起点。它提供轻量、兼容 SQLite 的引擎，非常适合 Agent Memory、对话历史记录和按租户隔离。当工作负载需要完整 SQL、关系 schema，或 Mastra 运行时状态以外的结构化应用数据时，请选择 **Postgres**。**MongoDB**（_即将推出_）将为难以映射到 SQL 的工作负载添加文档 Storage 和内置向量搜索。

| Provider       | 引擎                  | 最适合                     |
| -------------- | ------------------- | ----------------------- |
| **Turso**      | LibSQL，兼容 SQLite    | Agent Memory、按租户隔离      |
| **PostgreSQL** | Serverless Postgres | 关系型工作负载、结构化数据           |
| **MongoDB**    | 文档和向量搜索             | 文档 Storage、向量搜索（_即将推出_） |

## 数据库作用域

数据库会关联到以下两种作用域之一：

- **环境作用域**：默认选项。关联到单一环境，使数据在环境之间保持隔离（例如分别使用生产和预发布数据库）。当项目只有一个环境时，`mastra env db create` 会自动选择它；如果有多个环境，CLI 会提示选择。
- **项目作用域**：一个数据库由项目的所有[环境](https://mastra.zisheng.pro/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
```

支持的 kind 为 `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` 显示每个数据库的 kind、状态、scope 和注入的变量名称。`mastra env db show` 输出连接说明，其中密钥值默认隐藏。传入 `--show-secrets` 可显示这些值。`mastra env db delete` 会在 Provider 处永久删除数据库及其所有数据。创建和删除数据库需要组织中的 admin 角色。

## 从项目设置关联

1. 在 [platform](https://mastra.zisheng.pro/docs/mastra-platform/overview) 中打开项目，然后转到 **Project Settings**。

2. 打开 **Database** 部分，然后选择 **Add database**。

3. 选择 **Provider**（Turso 或 Postgres）。关联前可以切换 Provider。

4. 配置数据库：

   - **Name**：数据库在项目中的标签。
   - **Region**：数据库的托管位置。选择最靠近用户的区域。Turso 默认为 `sjc`（圣何塞），在全球提供 20 多个位置。Postgres 默认为 `aws-us-west-2`，覆盖美国、欧盟和亚太地区的 AWS 与 Azure 区域。

5. 选择 **Attach database**。预配过程会在后台运行。数据库最初处于 `provisioning` 状态，Provider 完成设置后转为 `ready`。连接详情会自动作为 Server 运行时环境变量注入项目。

从项目设置关联的数据库限定于项目。如需关联限定于环境的数据库，请使用 [CLI](#attach-with-the-cli)。

## 从代码连接

数据库处于 `ready` 状态时，表示 Provider 已完成预配，platform 也已将连接详情作为托管环境变量注入。可在 **Project Settings → Database** 中检查状态：每个已关联数据库在后台设置期间显示 `provisioning`，可连接时显示 `ready`。打开处于 `ready` 状态的数据库，可以查看其环境变量和可复制粘贴的代码片段。将这些变量连接到 Mastra Storage adapter 即可，无需手动配置。

### Turso（LibSQL）

Turso 提供两个环境变量：`TURSO_DATABASE_URL` 和 `TURSO_AUTH_TOKEN`。以下示例使用这些变量连接 [LibSQLStore](https://mastra.zisheng.pro/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!,
})
```

安装 adapter：

**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/reference/storage/postgresql)。

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

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

安装 adapter：

**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、Memory 和 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`                          |

> **注意:** 请将连接凭据视为密钥。Auth token（`TURSO_AUTH_TOKEN`）和 Postgres 连接字符串（`DATABASE_URL`）可授予数据的完整访问权限。Platform 默认会隐藏它们，只在请求时显示。

## 管理数据库

- **查看连接详情**：在项目设置中打开处于 `ready` 状态的数据库，查看其环境变量和可复制粘贴的代码片段。
- **删除**：从项目移除数据库会同时在 Provider 处删除它，并清除注入的环境变量。此操作无法撤销，因此请确保数据不再需要。