> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # 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**: ```bash npm install -g mastra@latest ``` **pnpm**: ```bash pnpm add -g mastra@latest ``` **Yarn**: ```bash yarn global add mastra@latest ``` **Bun**: ```bash bun add --global mastra@latest ``` 2. Authentifiez-vous : ```bash mastra auth login ``` 3. Vérifiez que votre projet se compile localement : ```bash 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](https://turso.tech). 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](https://projects.mastra.ai), 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 : ```bash 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](https://docs.turso.tech/cli). 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](https://projects.mastra.ai), 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://-.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](#point-your-mastra-app-at-the-new-database). > **Info:** Si les variables sont absentes, si les valeurs ne se déchiffrent pas ou si la CLI Turso rejette le jeton, écrivez à 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. ```bash brew install tursodatabase/tap/turso ``` ```bash curl -sSfL https://get.tur.so/install.sh | bash ``` Consultez l’[introduction à la CLI Turso](https://docs.turso.tech/cli/introduction) 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. ```bash export MASTRA_STORAGE_URL="https://-.turso.io" export MASTRA_STORAGE_AUTH_TOKEN="" 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 ".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. ```bash turso auth login ``` Si vous n’avez pas de compte Turso, la CLI vous invitera à en créer un. Consultez la [tarification de Turso](https://turso.tech/pricing) 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. ```bash 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 ` 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. ```bash 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 : ```bash TURSO_DATABASE_URL="libsql://mastra-migrated-.turso.io" TURSO_AUTH_TOKEN="" ``` Configurez `LibSQLStore` pour lire ces variables : ```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](https://mastra.zisheng.pro/fr/reference/storage/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](https://mastra.zisheng.pro/fr/docs/studio/observability). ## 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**: ```bash npm install @mastra/observability ``` **pnpm**: ```bash pnpm add @mastra/observability ``` **Yarn**: ```bash yarn add @mastra/observability ``` **Bun**: ```bash bun add @mastra/observability ``` **Avant (Mastra Cloud) :** ```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) :** ```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](https://mastra.zisheng.pro/fr/docs/studio/observability). - `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é](https://mastra.zisheng.pro/fr/docs/observability/overview) 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 : ```bash 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` : ```bash mastra studio deploy --project "my-new-project" --yes ``` Consultez le [déploiement de Studio](https://mastra.zisheng.pro/fr/docs/studio/deployment) 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](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments), tels que `production` et `staging`. Déployez vers chacun d’eux avec la commande unifiée [`mastra deploy`](https://mastra.zisheng.pro/fr/docs/mastra-platform/deploy) : ```bash 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 : ```bash 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](https://mastra.zisheng.pro/fr/docs/mastra-platform/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](https://projects.mastra.ai). 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 : ```bash 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 : ```yaml 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 : ```yaml 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](https://mastra.zisheng.pro/fr/docs/studio/observability). Supprimez votre ancien projet Mastra Cloud une fois le bon fonctionnement confirmé. ## À consulter également - [Vue d’ensemble de la plateforme Mastra](https://mastra.zisheng.pro/fr/docs/mastra-platform/overview) - [Vue d’ensemble de l’observabilité](https://mastra.zisheng.pro/fr/docs/mastra-platform/observability) - [Déploiement de Studio](https://mastra.zisheng.pro/fr/docs/mastra-platform/studio) - [Déploiement de Server](https://mastra.zisheng.pro/fr/docs/mastra-platform/server) - [Référence de la CLI](https://mastra.zisheng.pro/fr/reference/cli/mastra)