Hosted 数据库

通过 CLI 或 platform 项目设置创建一个完全托管的数据库，并将其附加到你的项目。Mastra 会使用你的提供器创建数据库并安全存储凭据，还会在数据库就绪后将连接信息作为运行时环境变量注入，因此无需复制或配置连接字符串。

mastra env db create --kind turso

何时使用托管数据库

当你的项目需要由平台管理的持久存储时，请使用托管数据库，包括：

• Agent memory：持久化对话历史和工作记忆，以及跨会话的语义召回。
• 应用数据：存储和检索项目在运行时需要的关系型或结构化数据。
• 向量搜索：存储用于 Retrieval-Augmented Generation（RAG）和语义搜索的 embeddings。

提供器

托管数据库目前支持三个提供器：Turso、Neon 和 Postgres，MongoDB 即将推出。附加数据库时选择一个提供器，然后将注入的变量接入对应的 Mastra 存储适配器。

每个提供器都会注入一组固定的变量名，例如 Neon 和 Postgres 都使用单个 DATABASE_URL，而 Turso 使用单独的 TURSO_* 变量。这些名称在每个环境中必须唯一，因此单个环境最多只能使用一个同名变量的数据库。由于 Neon 和 Postgres 都会注入 DATABASE_URL，它们在同一环境中互斥。Turso 可以与其中任意一个一起附加。

对于大多数以 agent 为中心的项目，Turso 是最简单的起点。它提供轻量、兼容 SQLite 的引擎，非常适合 agent memory、对话历史和按租户隔离。选择 Neon 时，你可以获得可从笔记本电脑、其他服务或迁移工具访问的公共无服务器 Postgres。选择 Postgres 时，工作负载需要保留在部署的私有网络中：它与你的服务器一起运行，并且只能从服务器访问。MongoDB（即将推出）将为不适合 SQL 的工作负载提供文档存储和内置向量搜索。

提供器	引擎	网络	最适合
Turso	LibSQL，兼容 SQLite	公共	Agent memory、按租户隔离
Neon	支持分支的无服务器 Postgres	公共	可从部署外部访问的关系型工作负载
Postgres	托管 PostgreSQL	VPC（私有）	必须保留在部署私有网络中的关系型工作负载
MongoDB	文档和向量搜索	待定	文档存储、向量搜索（即将推出）

数据库作用域

数据库会以两种作用域之一附加：

• 环境作用域：默认值。附加到单个环境，使数据在各环境之间保持隔离（例如单独的 production 和 staging 数据库）。当项目只有一个环境时，mastra env db create 会自动选择它；如果有多个环境，CLI 会提示你选择。
• 项目作用域：一个数据库由项目的所有环境共享。使用 --shared 选择加入。其变量会注入到每次部署。

作用域在附加数据库时设置，并显示在 mastra env db list 中。

同一提供器的两种作用域不能重叠。由于项目作用域数据库已经将其变量注入每个环境，附加同一提供器的环境作用域数据库会被拒绝，并返回变量名冲突错误。要从共享数据库迁移到按环境数据库，请先删除项目作用域数据库，然后为每个环境附加一个数据库。删除数据库会连同其所有数据一起在提供器端销毁，切换作用域前请导出需要保留的内容。不同环境上的环境作用域数据库永远不会冲突，每次部署只会收到自己环境的变量。

使用 CLI 附加

你不必提前运行此命令。如果你的项目需要托管数据库但还没有，mastra deploy 会在部署预检运行时主动提供附加一个数据库的选项。确认后，部署将在不离开 CLI 的情况下继续。当你的组织同时可用 Neon 和 Postgres，且缺少的变量是 DATABASE_URL 时，提示会让你选择要创建哪一个。

或者，提前创建并附加数据库。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）和 postgres（VPC 隔离的 Postgres）。常用 flags：

• --shared：附加项目作用域数据库，由所有环境共享。不能与环境参数一起使用。
• --name <name>：数据库名称。默认值派生自项目 slug。
• --region <region>：项目作用域数据库的提供器区域 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、状态、作用域和注入的变量名。mastra env db show 打印连接说明，密钥值默认隐藏。传入 --show-secrets 可显示它们。mastra env db delete 会连同所有数据一起永久删除数据库。创建和删除数据库需要组织中的 admin 角色。

从项目设置附加

1. 在 platform 中打开你的项目，然后进入 Project Settings。

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

3. 选择 提供器（Turso、Neon 或 Postgres）。附加前可以切换提供器。

4. 配置数据库：

   • Name：数据库在项目内的标签。
   • Region：数据库的托管位置。选择最接近用户的区域。Turso 默认为 sjc（圣何塞），并在全球 20 多个位置可用。Neon 默认为 aws-us-west-2，并在美国、欧盟和亚太地区的 AWS 与 Azure 区域可用。Postgres 与部署运行在同一私有网络上。其区域跟随环境的 Railway 区域（US、EU 或 APAC）。

5. 选择 Attach database。创建在后台运行。数据库会从 provisioning 状态开始，并在提供器完成设置后变为 ready。连接信息会自动作为服务器运行时环境变量注入到你的项目。

从项目设置附加的数据库是项目作用域的。使用 CLI 附加环境作用域数据库。

从代码连接

在 Project Settings → Database 中检查数据库状态。已附加的数据库在后台设置期间显示 provisioning。一旦变为 ready，平台就已将其连接信息作为托管环境变量注入。

打开 ready 状态的数据库，查看这些变量和代码片段。使用这些变量配置 Mastra 存储适配器，如下所示。

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!,
})

安装适配器：

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

Neon 和 Postgres

Neon（公共无服务器）和 Postgres（VPC 隔离）都暴露单个 DATABASE_URL 连接字符串，因此相同的 PostgresStore 代码对两者都适用。一个环境只能有其中一个，不能同时拥有两者。

src/mastra/storage.ts

import { PostgresStore } from '@mastra/pg'

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

安装适配器：

npm

npm install @mastra/pg@latest

pnpm

pnpm add @mastra/pg@latest

Yarn

yarn add @mastra/pg@latest

Bun

bun add @mastra/pg@latest

VPC 隔离的 Postgres 只能从已部署的服务器访问，因此本地开发无法直接连接它。开发期间请将 DATABASE_URL 指向本地 Postgres（或 Neon 分支），部署时再让平台注入托管值。

将 storage 实例传给 Mastra 配置，使 agents、memory 和 workflows 可以使用它：

src/mastra/index.ts

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

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

环境变量

每个提供器都会注入一组固定的托管环境变量。当数据库处于 ready 状态时，这些变量在运行时对你的项目可用。你无需自行定义它们。

提供器	变量
Turso	TURSO_DATABASE_URL、TURSO_AUTH_TOKEN
Neon	DATABASE_URL
Postgres	DATABASE_URL

注意

请将连接凭据视为密钥。auth token（TURSO_AUTH_TOKEN）和 Postgres 连接字符串（DATABASE_URL）授予对数据的完全访问权限。平台默认会遮蔽它们，仅在请求时显示。

管理数据库

• 查看连接详情：在项目设置中打开 ready 状态的数据库，查看其环境变量和可复制的代码片段。
• 删除：从项目中移除数据库会连同提供器端一起删除它，并清除注入的环境变量。此操作不可逆，请确保你不再需要这些数据。