Mastra Cloud から Mastra platform へ移行する

Mastra platform は、Mastra Cloud を独立した Studio 製品と Server 製品、CLI 主導のデプロイ、新しい Observability システムに置き換えます。このガイドでは、各移行手順を説明します。

変更点

領域	Mastra Cloud	Mastra platform
製品	単一プロジェクト	独立した Studio と Server
デプロイ	Push 時に自動デプロイ	CLI 主導（mastra studio deploy、mastra server deploy）
プロジェクト作成	GitHub から import	初回デプロイ時に CLI がプロジェクトを作成
Storage	マネージド LibSQL（Cloud Store）またはユーザー管理	ユーザーがホストするデータベース
Observability	Logger ベース	Exporter を使用する Observability クラス
環境変数	プロジェクトのセットアップ時に設定	初回デプロイ時に .env から初期設定し、以降は Dashboard で管理
URL	単一 URL	Studio と Server で別々の URL

始める前に

1. CLI をインストールまたは更新します。

   npm

   npm install -g mastra@latest

   pnpm

   pnpm add -g mastra@latest

   Yarn

   yarn global add mastra@latest

   Bun

   bun add --global mastra@latest

2. 認証します。

   mastra auth login

3. プロジェクトをローカルでビルドできることを確認します。

   mastra build

Mastra Cloud Store をホスト型データベースに置き換える

Mastra Cloud は、Turso を基盤とするマネージド libSQL データベースを提供していました。Mastra platform はデータベースをホストしないため、外部でホストするインスタンスを Storage に指定する必要があります。

すでにホスト型データベースを使用していた場合は、既存のデータベース設定を維持してください。接続文字列はハードコードせず、Dashboard の環境変数として設定します。

Cloud Store を使用していた場合は、以下の手順でデータを export し、ユーザーが管理する新しい libSQL データベースへ読み込みます。

Cloud Store のデータを export する

Cloud Store のデータを export する方法は 2 つあります。Dashboard からダウンロードするか、Turso CLI で手動 Dump を作成します。

方法 A：Dashboard から export する（推奨）

Mastra Dashboard でプロジェクトを開き、Runtime → Settings → Storage へ移動します。Export Database ボタンをクリックします。Dashboard が Cloud Store 全体の .sql Dump を生成し、Downloads フォルダーへ直接ダウンロードします。

ダウンロードが完了したら、Dump を SQLite データベースファイルへ変換します。

sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql

これで、ローカルでの確認やバックアップが可能で、以降の手順で新しいデータベースのソースとして使用できる、ポータブルな mydb.db ファイルが作成されます。

方法 B：Turso CLI で export する

コマンドラインで作業する場合や export をスクリプト化する場合は、Turso CLI でデータベースを直接 Dump できます。この方法には、Dashboard に表示されるデータベース URL と Auth Token が必要です。

1. Dashboard から Cloud Store の認証情報を取得します。

   Mastra Dashboard でプロジェクトを開き、Runtime → Settings → Env Variables へ移動します。Cloud Store を使用するプロジェクトでは、ユーザーの変数とともに以下の 2 つが追加されています。

   • MASTRA_STORAGE_URL：libSQL 接続文字列（例：libsql://<db-name>-<org>.turso.io）。
   • MASTRA_STORAGE_AUTH_TOKEN：そのデータベースに限定された、読み取り可能な Auth Token。

   各行では、目のアイコンによる表示/非表示、Edit、Delete、Copy Value という標準の環境変数操作を使用できます。Copy Value で両方の値をコピーし、以下の Dump コマンドに使用します。

   注記

   これらの変数は、Cloud Store がプロビジョニングされたプロジェクトにのみ表示されます。Mastra Cloud でユーザー管理のデータベースを使用していた場合は、すでにこれらの認証情報があるため、Mastra アプリで新しいデータベースを使用するへ進んでください。

   情報

   変数がない、値を復号できない、または Turso CLI が Token を拒否する場合は、Mastra Cloud アカウントに関連付けられたアドレスから support@mastra.ai へメールを送り、export するプロジェクトの libSQL URL と Auth Token を依頼してください。プロジェクト名/ID も記載します。ネットワーク上で CLI アクセスがブロックされる場合は、Support に Dump の実行を依頼することもできます。

2. Turso CLI をインストールします。

   macOS

   brew install tursodatabase/tap/turso

   Linux / WSL

   curl -sSfL https://get.tur.so/install.sh | bash

   Windows と Headless Install のオプションについては、Turso CLI の概要を参照してください。

3. データベースを SQL Dump へ export します。

   Support から提供された認証情報（または先ほど Dashboard からコピーした値）を環境変数として設定し、データベースをローカルファイルへ Dump します。Dashboard から URL をコピーした場合は、libsql:// Scheme を https:// に置き換えてください。Auth Token とともに URL を渡す場合、Turso CLI は HTTPS 形式を要求します。

   export MASTRA_STORAGE_URL="https://<db-name>-<org>.turso.io"
   export MASTRA_STORAGE_AUTH_TOKEN="<token-from-dashboard-or-support>"
   
   turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql

   警告

   Auth Token を接続文字列に埋め込む方法は、Turso が推奨するパターンより安全性が低くなります。Token を含む完全な URL が Shell History、Process List、Terminal Log に残る可能性があります。Turso は、turso auth login を実行してから、データベース名のみで turso db shell <database-name> ".dump" > mastra-cloud-dump.sql を実行する方法を公式に推奨しています。この手順ではユーザー所有の Turso アカウントにデータベースが存在する必要がありますが、Cloud Store は該当しないため、上記の環境変数を使う例を今回限りの export 手段として示しています。Token の展開自体を避ける場合は、Support に Dump の実行を依頼し、生成された SQL ファイルを送付してもらってください。

   生成された mastra-cloud-dump.sql には、Thread と Message の履歴、Workflow Snapshot、Trace、Eval Score など、完全なスキーマとデータが含まれます。続行する前に安全な場所へ保管してください。

Dump を新しい libSQL データベースへ読み込む

Dump は標準の SQL ファイルで、libSQL 互換の任意のデータベースへ読み込めます。以下の例では、新しい Turso ホスト型データベースを使用します。移行前後の構成を同等に保ち、スキーマ変換を避けられます。

1. ユーザー自身の Turso アカウントで Turso CLI を認証します。

   turso auth login

   Turso アカウントがない場合は、CLI に作成を求められます。プランの詳細は Turso の料金を参照してください。

2. 新しいデータベースを作成し、1 回の操作で Dump を読み込みます。

   turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql

   --from-dump は作成時にローカルの SQLite/libSQL Dump を復元します。後から turso db shell へ Statement を Pipe するより高速で安全です。Latency を最小限に抑えるため、Mastra Server の実行場所に近い Region を選択してください。利用可能な Region は turso db locations で一覧表示できます。複数の Group を管理する場合は --group <group-name> を指定します。

   数 GB の Dump では --wait を追加し、データベースが完全に利用可能になるまで CLI を待機させます。

3. 新しいデータベースの接続認証情報を生成します。

   turso db show mastra-migrated --url
   turso db tokens create mastra-migrated

   最初のコマンドは libSQL URL、2 番目のコマンドは Auth Token を出力します。LibSQLStore には両方が必要です。

Mastra アプリで新しいデータベースを使用する

新しい認証情報を、ローカルの .env または Mastra platform Dashboard の環境変数として設定します。

.env

TURSO_DATABASE_URL="libsql://mastra-migrated-<org>.turso.io"
TURSO_AUTH_TOKEN="<token-from-turso-db-tokens-create>"

これらの変数を読み取るよう LibSQLStore を設定します。

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'libsql-storage',
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN,
  }),
})

すべてのオプションについては、libSQL Storage リファレンスを参照してください。

移行を確認する

Cloud プロジェクトを停止する前に、新しいデータベースからアプリが必要とするデータを取得できることを確認します。

• turso db shell mastra-migrated "SELECT name FROM sqlite_master WHERE type='table';" を実行してテーブルを一覧表示します。出力には Mastra 管理のテーブル（mastra_threads、mastra_messages、mastra_workflow_snapshot、mastra_traces など）が含まれている必要があります。
• データが存在する既知のテーブルで行数を取得します。たとえば turso db shell mastra-migrated "SELECT COUNT(*) FROM mastra_messages;" を実行し、Cloud Store URL に対して同じクエリを実行した結果と比較します。
• 新しい認証情報で Mastra アプリを起動し、既存の Thread または Workflow Run が Studio で想定どおり読み込まれることを確認します。

Observability 設定を更新する

Mastra Cloud は Logger ベースの Tracing を使用していました。Mastra platform は、明示的な Exporter を指定する Observability クラスを使用します。

Observability パッケージをインストールします。

npm

npm install @mastra/observability

pnpm

pnpm add @mastra/observability

Yarn

yarn add @mastra/observability

Bun

bun add @mastra/observability

変更前（Mastra Cloud）：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'my-app', level: 'info' }),
  // traces appear in Cloud dashboard automatically
})

変更後（Mastra platform）：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

• MastraStorageExporter は Observability Event を Mastra Storage に永続化し、Studio で利用できるようにします。
• MastraPlatformExporter は、MASTRA_PLATFORM_ACCESS_TOKEN が設定されている場合に Observability Event を Mastra platform へ送信します。
• SensitiveDataFilter は、export 前に Span データから Password、Token、Key をマスクします。

DuckDB を使用した Metric 向けの Composite Storage など、すべての設定については、Observability の概要を参照してください。

Studio をデプロイする

ホスト型 Studio インスタンスをデプロイします。

mastra studio deploy

CLI はプロジェクトをビルドし、Artifact をアップロードしてからデプロイします。初回デプロイ時に、ローカルプロジェクトを Platform に関連付ける .mastra-project.json ファイルが作成されます。このファイルをリポジトリへ Commit してください。

ローカルの Env ファイルは任意です。プロジェクトディレクトリに .env または .env.* ファイルがある場合、デプロイ時にその環境変数がバンドルされます。

mastra studio projects create を別途実行せず、非対話形式の 1 Step で新しい Platform プロジェクトを作成するには、--project で名前を渡し、--yes でデフォルトを受け入れます。

mastra studio deploy --project "my-new-project" --yes

詳しくは、Studio のデプロイを参照してください。

複数の環境

1 つの Mastra platform プロジェクトでは、production や staging など、複数の環境で同じコードベースを実行します。統一された mastra deploy コマンドで各環境へデプロイします。

mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes

各環境には専用の URL と環境変数があり、デプロイ履歴も分かれています。

Server をデプロイする（任意）

本番 API エンドポイントが必要な場合は、Server をデプロイします。

mastra server deploy

これにより、安定した API URL、環境変数管理、カスタムドメイン対応を備えた独立したデプロイが作成されます。すべての手順については、Server デプロイガイドを参照してください。

注記

.env、.env.local、.env.production の環境変数は、初回デプロイ時に自動的に含まれます。以降は Web Dashboard で環境変数を管理します。 開発専用または個人の Secret をアップロードしないよう、初回デプロイ前にこれらのファイルを確認し、不要な値を削除してください。

CI を設定する（任意）

Mastra Cloud は Push 時に自動デプロイしていました。Mastra platform は CLI 主導のデプロイを使用し、任意の CI Provider から実行できます。

前提条件

1. API Token を作成します。

   mastra auth tokens create ci-deploy

2. Token を GitHub Actions の Secret（MASTRA_API_TOKEN など）として保存します。

3. 最初の手動デプロイで生成された .mastra-project.json をリポジトリへ Commit します。

MASTRA_API_TOKEN が設定されている場合、CLI は Headless Mode で実行され、すべての対話 Prompt を省略します。

main への Push 時に Server をデプロイする

Server のデプロイは .mastra-project.json から Organization と Project を取得するため、Token 以外の環境変数は不要です。

.github/workflows/deploy-server.yml

name: Deploy to Mastra Server

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: pnpm install
      - run: pnpm mastra server deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}

main への Push 時に Studio をデプロイする

Studio のデプロイでは、--config を指定していても、Headless Mode で MASTRA_ORG_ID と MASTRA_PROJECT_ID の環境変数が必要です。

.github/workflows/deploy-studio.yml

name: Deploy to Mastra Studio

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: pnpm install
      - run: pnpm mastra studio deploy --yes --config .mastra-project.json
        env:
          MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
          MASTRA_ORG_ID: ${{ secrets.MASTRA_ORG_ID }}
          MASTRA_PROJECT_ID: ${{ secrets.MASTRA_PROJECT_ID }}

以前の Cloud プロジェクトを停止する

以前の Mastra Cloud URL を参照する Client を、新しい Server URL または Studio URL へ更新します。Studio の Observability Dashboardで Trace を確認し、新しい Platform に表示されることを確認します。すべてが正常に動作することを確認したら、以前の Mastra Cloud プロジェクトを削除してください。

関連項目

• Mastra platform の概要
• Observability の概要
• Studio のデプロイ
• Server のデプロイ
• CLI リファレンス