跳到主要内容

托管数据库

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

mastra env db create --kind turso

何时使用托管数据库
何时使用托管数据库的直接链接

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

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

Provider
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引擎最适合
TursoLibSQL，兼容 SQLiteAgent Memory、按租户隔离
PostgreSQLServerless Postgres关系型工作负载、结构化数据
MongoDB文档和向量搜索文档 Storage、向量搜索（即将推出）

数据库作用域
数据库作用域的直接链接

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

  • 环境作用域：默认选项。关联到单一环境，使数据在环境之间保持隔离（例如分别使用生产和预发布数据库）。当项目只有一个环境时，mastra env db create 会自动选择它；如果有多个环境，CLI 会提示选择。
  • 项目作用域：一个数据库由项目的所有环境共享。通过 --shared 选择加入。其变量会注入到每次部署中。

作用域在关联数据库时确定，并显示在 mastra env db list 中。

同一 Provider 的两种作用域不能重叠。由于限定于项目的数据库已经向每个环境注入变量，再关联同一 Provider 且限定于环境的数据库会因变量名冲突而被拒绝。若要从共享数据库迁移到每个环境各自的数据库，请先删除限定于项目的数据库，然后每个环境关联一个数据库。删除数据库会同时在 Provider 处销毁数据库及其所有数据，因此切换作用域前请导出需要保留的内容。不同环境中限定于环境的数据库不会发生冲突，因为每次部署只会收到所属环境的变量。

使用 CLI 关联
使用 CLI 关联的直接链接

无需预先运行此命令。如果项目需要托管数据库但尚未关联，mastra deploy 会在部署前检查运行时提出关联数据库。接受后，部署会直接在 CLI 中继续。

也可以提前创建并关联数据库。CLI 会轮询直至数据库就绪，通常需要几秒：

# 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（不会显示交互式提示）。

检查和管理已关联的数据库：

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 中打开项目，然后转到 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。

从代码连接
从代码连接的直接链接

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

Turso（LibSQL）
Turso（LibSQL）的直接链接

Turso 提供两个环境变量：TURSO_DATABASE_URL 和 TURSO_AUTH_TOKEN。以下示例使用这些变量连接 LibSQLStore。

src/mastra/storage.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 install @mastra/libsql@latest

PostgreSQL
PostgreSQL的直接链接

PostgreSQL 提供单个 DATABASE_URL 连接字符串。以下示例使用该变量连接 PostgresStore。

src/mastra/storage.ts
import { PostgresStore } from '@mastra/pg'

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

安装 adapter：

npm install @mastra/pg@latest

将 storage 实例传给 Mastra 配置，以便 Agent、Memory 和 Workflow 使用：

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

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

环境变量
环境变量的直接链接

每种 Provider 都会注入一组固定的托管环境变量。数据库处于 ready 状态后，项目可在运行时使用这些变量。无需自行定义。

Provider变量
TursoTURSO_DATABASE_URL、TURSO_AUTH_TOKEN
PostgresDATABASE_URL
注意

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

管理数据库
管理数据库的直接链接

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