Migrer de Mastra Cloud vers la plateforme Mastra

La plateforme Mastra remplace Mastra Cloud par des produits Studio et Server distincts, des déploiements pilotés par la CLI et un nouveau système d’observabilité. Ce guide vous accompagne à chaque étape.

Changements apportés

Domaine	Mastra Cloud	Plateforme Mastra
Produits	Projet unique	Studio et Server distincts
Déploiements	Déploiement automatique lors d’un push	Pilotés par la CLI (mastra studio deploy, mastra server deploy)
Création de projet	Import GitHub	La CLI crée les projets au premier déploiement
Stockage	LibSQL géré (Cloud Store) ou base de données fournie par vos soins	Base de données hébergée fournie par vos soins
Observabilité	Basée sur un logger	Classe Observability avec exportateurs
Variables d’environnement	Définies lors de la configuration du projet	Initialisées à partir de .env au premier déploiement, puis gérées dans le tableau de bord
URL	URL unique	URL Studio et Server distinctes

Avant de commencer

1. Installez ou mettez à jour la 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. Authentifiez-vous :

   mastra auth login

3. Vérifiez que votre projet se compile localement :

   mastra build

Remplacer Mastra Cloud Store par une base de données hébergée

Mastra Cloud fournissait une base de données libSQL gérée, soutenue par Turso. La plateforme Mastra n’héberge pas de base de données pour vous : vous devez donc diriger votre stockage vers une instance hébergée en externe.

Si vous utilisiez déjà une base de données hébergée (fournie par vos soins), conservez la configuration existante. Assurez-vous que la chaîne de connexion est définie comme variable d’environnement dans le tableau de bord plutôt que codée en dur.

Si vous utilisiez Cloud Store, suivez les étapes ci-dessous pour exporter vos données et les charger dans une nouvelle base de données libSQL sous votre contrôle.

Exporter vos données Cloud Store

Vous pouvez exporter vos données Cloud Store de deux façons : en les téléchargeant depuis le tableau de bord ou en créant un dump manuel avec la CLI Turso.

Option A : exporter depuis le tableau de bord (recommandé)

Ouvrez votre projet dans le tableau de bord Mastra, puis accédez à Runtime → Settings → Storage. Cliquez sur le bouton Export Database. Le tableau de bord génère un dump .sql complet de votre Cloud Store et le télécharge directement dans votre dossier Téléchargements.

Une fois le téléchargement terminé, convertissez le dump en fichier de base de données SQLite :

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

Vous disposez maintenant d’un fichier mydb.db portable que vous pouvez examiner localement, sauvegarder ou utiliser comme source de la nouvelle base de données dans les étapes suivantes.

Option B : exporter avec la CLI Turso

Si vous préférez travailler en ligne de commande ou devez automatiser l’export, vous pouvez dumper directement la base de données avec la CLI Turso. Cette approche nécessite l’URL de la base de données et un jeton d’authentification, tous deux disponibles dans le tableau de bord.

1. Récupérez vos identifiants Cloud Store depuis le tableau de bord.

   Ouvrez votre projet dans le tableau de bord Mastra, puis accédez à Runtime → Settings → Env Variables. Pour les projets soutenus par Cloud Store, deux variables sont injectées en plus des vôtres :

   • MASTRA_STORAGE_URL : une chaîne de connexion libSQL (par exemple, libsql://<db-name>-<org>.turso.io).
   • MASTRA_STORAGE_AUTH_TOKEN : un jeton d’authentification avec droit de lecture, limité à cette base de données.

   Chaque ligne offre les actions standard sur les variables d’environnement : afficher ou masquer avec l’icône en forme d’œil, modifier, supprimer et copier la valeur. Utilisez Copy Value pour récupérer les deux valeurs nécessaires à la commande de dump ci-dessous.

   remarque

   Ces variables n’apparaissent que pour les projets provisionnés avec Cloud Store. Si vous avez fourni votre propre base de données à Mastra Cloud, vous possédez déjà ces identifiants et pouvez passer directement à Diriger votre application Mastra vers la nouvelle base de données.

   info

   Si les variables sont absentes, si les valeurs ne se déchiffrent pas ou si la CLI Turso rejette le jeton, écrivez à support@mastra.ai depuis l’adresse associée à votre compte Mastra Cloud et demandez l’URL libSQL ainsi que le jeton d’authentification du projet à exporter. Incluez le nom ou l’ID du projet. L’assistance peut aussi effectuer le dump pour vous si l’accès à la CLI est bloqué sur votre réseau.

2. Installez la CLI Turso.

   macOS

   brew install tursodatabase/tap/turso

   Linux / WSL

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

   Consultez l’introduction à la CLI Turso pour les options Windows et d’installation sans interface.

3. Exportez la base de données vers un dump SQL.

   Définissez comme variables d’environnement les identifiants fournis par l’assistance (ou utilisez les valeurs du tableau de bord si vous les avez déjà copiées), puis exportez la base de données dans un fichier local. Si vous avez copié l’URL depuis le tableau de bord, remplacez le schéma libsql:// par https:// : la CLI Turso attend la forme HTTPS lorsque l’URL est transmise avec un jeton d’authentification.

   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

   attention

   Intégrer le jeton d’authentification dans la chaîne de connexion est moins sûr que le modèle recommandé par Turso : l’URL complète, jeton compris, peut se retrouver dans l’historique du shell, les listes de processus et les journaux du terminal. Turso recommande officiellement d’exécuter turso auth login, puis de dumper uniquement par nom de base de données : turso db shell <database-name> ".dump" > mastra-cloud-dump.sql. Ce flux impose que la base de données se trouve dans un compte Turso qui vous appartient, ce qui n’est pas le cas de Cloud Store. L’exemple utilisant des variables d’environnement ci-dessus est donc proposé pour cet export unique. Si vous préférez éviter entièrement l’interpolation du jeton, demandez à l’assistance d’effectuer le dump pour vous et de vous envoyer le fichier SQL obtenu.

   Le fichier mastra-cloud-dump.sql obtenu contient le schéma et les données complets : historique des threads et des messages, instantanés de Workflow, traces et scores d’évaluations. Conservez-le dans un endroit sûr avant de continuer.

Charger le dump dans une nouvelle base de données libSQL

Le dump est un fichier SQL standard qui peut être chargé dans n’importe quelle base de données compatible libSQL. L’exemple ci-dessous utilise une nouvelle base de données hébergée par Turso, ce qui conserve une migration à l’identique et évite toute traduction de schéma.

1. Authentifiez la CLI Turso auprès de votre propre compte Turso.

   turso auth login

   Si vous n’avez pas de compte Turso, la CLI vous invitera à en créer un. Consultez la tarification de Turso pour connaître les détails des forfaits.

2. Créez une nouvelle base de données et chargez le dump en une seule étape.

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

   --from-dump restaure un dump SQLite/libSQL local à la création, ce qui est plus rapide et plus sûr que de transmettre ensuite les instructions à turso db shell par un pipe. Choisissez une région proche de celle où s’exécute votre Mastra Server afin de minimiser la latence : listez les régions disponibles avec turso db locations et transmettez --group <group-name> si vous gérez plusieurs groupes.

   Pour les dumps de plusieurs gigaoctets, ajoutez --wait afin que la CLI attende que la base de données soit entièrement disponible.

3. Générez les identifiants de connexion de la nouvelle base de données.

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

   La première commande affiche l’URL libSQL. La seconde affiche un jeton d’authentification. LibSQLStore a besoin des deux.

Diriger votre application Mastra vers la nouvelle base de données

Définissez les nouveaux identifiants comme variables d’environnement, localement dans .env ou dans le tableau de bord de la plateforme Mastra :

.env

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

Configurez LibSQLStore pour lire ces variables :

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

Consultez la référence du stockage libSQL pour l’ensemble des options.

Vérifier la migration

Avant de mettre votre projet Cloud hors service, confirmez que la nouvelle base de données fournit les données attendues par votre application.

• Exécutez turso db shell mastra-migrated "SELECT name FROM sqlite_master WHERE type='table';" pour lister les tables. La sortie doit inclure les tables gérées par Mastra, par exemple mastra_threads, mastra_messages, mastra_workflow_snapshot et mastra_traces.
• Comptez les lignes d’une table dont vous savez qu’elle est remplie, par exemple avec turso db shell mastra-migrated "SELECT COUNT(*) FROM mastra_messages;", et comparez ce nombre au résultat de la même requête sur l’URL Cloud Store.
• Démarrez votre application Mastra avec les nouveaux identifiants et vérifiez qu’un thread existant ou une exécution de Workflow se charge comme prévu dans Studio.

Mettre à jour la configuration d’observabilité

Mastra Cloud utilisait un traçage basé sur un logger. La plateforme Mastra utilise la classe Observability avec des exportateurs explicites.

Installez le package d’observabilité :

npm

npm install @mastra/observability

pnpm

pnpm add @mastra/observability

Yarn

yarn add @mastra/observability

Bun

bun add @mastra/observability

Avant (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
})

Après (plateforme Mastra) :

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 conserve les événements d’observabilité dans Mastra Storage pour Studio.
• MastraPlatformExporter envoie les événements d’observabilité à la plateforme Mastra lorsque MASTRA_PLATFORM_ACCESS_TOKEN est défini.
• SensitiveDataFilter masque les mots de passe, jetons et clés dans les données de span avant l’export.

Consultez la vue d’ensemble de l’observabilité pour la configuration complète, notamment le stockage composite avec DuckDB pour les métriques.

Déployer Studio

Déployez votre instance Studio hébergée :

mastra studio deploy

La CLI compile votre projet et charge l’artefact avant de le déployer. Au premier déploiement, un fichier .mastra-project.json est créé pour relier votre projet local à la plateforme. Validez ce fichier dans votre dépôt.

Un fichier d’environnement local est facultatif. Lorsqu’un fichier .env ou .env.* est présent dans le répertoire du projet, le déploiement inclut ses variables d’environnement.

Pour créer un projet de plateforme en une étape non interactive, au lieu d’exécuter séparément mastra studio projects create, fournissez un nom avec --project et acceptez les valeurs par défaut avec --yes :

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

Consultez le déploiement de Studio pour plus de détails.

Plusieurs environnements

Un même projet de plateforme Mastra exécute la même base de code dans plusieurs environnements, tels que production et staging. Déployez vers chacun d’eux avec la commande unifiée mastra deploy :

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

Chaque environnement dispose d’une URL et de variables d’environnement dédiées, ainsi que d’un historique de déploiement distinct.

Déployer Server (facultatif)

Si vous avez besoin d’un point de terminaison API de production, déployez un Server :

mastra server deploy

Cela crée un déploiement distinct avec une URL d’API stable, une gestion des variables d’environnement et la prise en charge des domaines personnalisés. Consultez le guide de déploiement de Server pour la procédure complète.

remarque

Les variables d’environnement de .env, .env.local et .env.production sont incluses automatiquement au premier déploiement. Ensuite, gérez-les depuis le tableau de bord web. Examinez et assainissez ces fichiers avant le premier déploiement afin d’éviter de charger des secrets réservés au développement ou personnels.

Configurer l’intégration continue (facultatif)

Mastra Cloud déployait automatiquement lors d’un push. La plateforme Mastra utilise des déploiements pilotés par la CLI, que vous pouvez exécuter depuis n’importe quel fournisseur d’intégration continue.

Prérequis

1. Créez un jeton d’API :

   mastra auth tokens create ci-deploy

2. Stockez le jeton comme secret GitHub Actions, par exemple MASTRA_API_TOKEN.

3. Validez .mastra-project.json dans votre dépôt ; il est généré lors de votre premier déploiement manuel.

Lorsque MASTRA_API_TOKEN est défini, la CLI s’exécute sans interface et ignore toutes les invites interactives.

Déployer Server lors d’un push vers main

Le déploiement Server prend l’organisation et le projet dans .mastra-project.json ; aucune variable d’environnement supplémentaire n’est donc nécessaire en plus du jeton :

.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 }}

Déployer Studio lors d’un push vers main

Le déploiement Studio exige les variables d’environnement MASTRA_ORG_ID et MASTRA_PROJECT_ID en mode sans interface, même lorsque --config est fourni :

.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 }}

Mettre l’ancien projet Cloud hors service

Mettez à jour tous les clients qui pointent vers votre ancienne URL Mastra Cloud afin qu’ils utilisent la nouvelle URL Server ou Studio. Vérifiez que les traces apparaissent dans la nouvelle plateforme en consultant le tableau de bord d’observabilité Studio. Supprimez votre ancien projet Mastra Cloud une fois le bon fonctionnement confirmé.

À consulter également

• Vue d’ensemble de la plateforme Mastra
• Vue d’ensemble de l’observabilité
• Déploiement de Studio
• Déploiement de Server
• Référence de la CLI