跳至主要內容

託管資料庫

從 CLI 或 platform 專案設定佈建全代管資料庫，並將其附加至專案。Mastra 會透過 Provider 建立資料庫並安全地儲存憑證；資料庫就緒後，也會將連線詳細資料注入為執行階段環境變數，因此不必複製或設定連線字串。

mastra env db create --kind turso

使用託管資料庫的時機
「使用託管資料庫的時機」的直接連結

當專案需要由 platform 管理的持久儲存空間時，請使用託管資料庫，包括：

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

Provider
「Provider」的直接連結

託管資料庫目前可透過 Turso 與 Postgres 這兩個 Provider 使用，MongoDB 即將推出。附加資料庫時選擇一個 Provider，再於程式碼中將其注入的變數連接至對應的 Mastra 儲存配接器。

每個 Provider 都會注入一組固定名稱的變數，例如 Postgres 使用單一 DATABASE_URL，Turso 則使用個別的 TURSO_* 變數。這些名稱在每個環境中必須是唯一的，亦即一個環境對每個 Provider 最多只能使用一個資料庫。若不同工作負載需要個別的儲存空間，可將 Turso 和 Postgres 附加至同一專案。

對大多數以 Agent 為主的專案而言，Turso 是最簡單的起點。它提供輕量且與 SQLite 相容的引擎，很適合 Agent 記憶體、對話記錄和租戶隔離。若工作負載需要完整 SQL、關聯式結構描述，或 Mastra 執行階段狀態以外的結構化應用程式資料，請選擇 Postgres。MongoDB（即將推出）將為不易對應至 SQL 的工作負載加入文件儲存和內建向量搜尋。

Provider引擎最適合用途
TursoLibSQL，與 SQLite 相容Agent 記憶體、租戶隔離
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 中開啟專案，然後前往專案設定。

  2. 開啟資料庫區段，然後選取新增資料庫。

  3. 選取 Provider（Turso 或 Postgres）。附加前仍可切換 Provider。

  4. 設定資料庫：

    • 名稱：資料庫在專案內的標籤。
    • 區域：資料庫的託管位置。請選取最靠近使用者的區域。Turso 預設為 sjc（聖荷西），在全球 20 多個地點提供服務。Postgres 預設為 aws-us-west-2，可在美國、歐盟和亞太地區的 AWS 與 Azure 區域使用。

  5. 選取附加資料庫。佈建會在背景執行。資料庫一開始處於 provisioning 狀態，Provider 完成設定後便會變成 ready。連線詳細資料會自動以 Server 執行階段環境變數的形式注入專案。

從專案設定附加的資料庫屬於專案範圍。若要附加環境範圍資料庫，請使用 CLI。

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

資料庫為 ready 時，表示 Provider 已完成佈建，platform 也已將連線詳細資料注入為受管理的環境變數。請在專案設定 → 資料庫中查看狀態；設定於背景執行時，每個已附加的資料庫都會顯示 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