跳至主要內容

託管數據庫

透過 CLI 或 platform 項目設定佈建全託管數據庫，並連接至你的項目。Mastra 會透過你的 Provider 建立數據庫並安全儲存憑證；數據庫準備就緒後，亦會將連線資料注入為執行階段環境變數，因此你毋須複製或設定連線字串。

mastra env db create --kind turso

何時使用託管數據庫
何時使用託管數據庫 的直接連結

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

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

Provider
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引擎最適合用途
TursoLibSQL，兼容 SQLiteAgent 記憶、按租戶隔離
PostgreSQLServerless Postgres關聯式工作負載、結構化數據
MongoDB文件及向量搜尋文件儲存、向量搜尋（即將推出）

數據庫範圍
數據庫範圍 的直接連結

數據庫會連接至以下兩種範圍之一：

  • 環境範圍：預設選項。數據庫只連接至單一環境，讓不同環境的數據互相隔離（例如分開的生產及預備環境數據庫）。如果項目只有一個環境，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

支援的種類為 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 會顯示每個數據庫的種類、狀態、範圍及注入的變數名稱。mastra env db show 會輸出連線指示，並遮蔽秘密值；傳入 --show-secrets 可顯示這些值。mastra env db delete 會在 Provider 端永久刪除數據庫及其所有數據。建立及刪除數據庫需要你在組織內擁有管理員角色。

從項目設定連接
從項目設定連接 的直接連結

  1. 在 platform 開啟項目，然後前往 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。

從程式碼連線
從程式碼連線 的直接連結

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

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

安裝適配器：

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

安裝適配器：

npm install @mastra/pg@latest

將 storage 實例傳入 Mastra 設定，讓 Agent、記憶及 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
注意

請將連線憑證視為機密。驗證權杖（TURSO_AUTH_TOKEN）及 Postgres 連線字串（DATABASE_URL）可授予數據的完整存取權。platform 預設會遮蔽這些資料，只會按要求顯示。

管理數據庫
管理數據庫 的直接連結

  • 查看連線資料：在項目設定開啟 ready 數據庫，即可查看其環境變數及可直接複製貼上的程式碼片段。
  • 刪除：從項目移除數據庫會同時在 Provider 端將其刪除，並清除已注入的環境變數。此操作無法復原，請確定不再需要相關數據。
On this page