Bases de données hébergées

Provisionnez une base de données entièrement gérée depuis la CLI ou les paramètres de votre projet sur la plateforme, puis associez-la à votre projet. Mastra la crée auprès de votre fournisseur et stocke les identifiants de connexion de manière sécurisée. Lorsque la base de données est prête, Mastra injecte également les informations de connexion sous forme de variables d’environnement d’exécution : aucune chaîne de connexion n’est donc à copier ni à configurer.

mastra env db create --kind turso

Quand utiliser des bases de données hébergées

Utilisez une base de données hébergée lorsque votre projet a besoin d’un stockage persistant géré par la plateforme, notamment pour :

• Mémoire de l’Agent : conserver l’historique des conversations et la mémoire de travail, ainsi que le rappel sémantique entre les sessions.
• Données applicatives : stocker et récupérer les données relationnelles ou structurées dont votre projet a besoin lors de son exécution.
• Recherche vectorielle : stocker des embeddings pour la génération augmentée par récupération (RAG) et la recherche sémantique.

Fournisseurs

Les bases de données hébergées sont actuellement proposées par deux fournisseurs, Turso et Postgres. MongoDB sera bientôt disponible. Choisissez un fournisseur lorsque vous associez une base de données, puis utilisez les variables injectées avec l’adaptateur de stockage Mastra correspondant dans votre code.

Chaque fournisseur injecte un ensemble fixe de noms de variables : par exemple, une seule variable DATABASE_URL pour Postgres et plusieurs variables TURSO_* distinctes pour Turso. Ces noms doivent être uniques dans chaque environnement, ce qui signifie qu’un environnement ne peut utiliser qu’une seule base de données par fournisseur. Associez Turso et Postgres au même projet si vous avez besoin de stockages distincts pour différentes charges de travail.

Pour la plupart des projets axés sur les Agents, Turso constitue le point de départ le plus simple. Son moteur léger et compatible avec SQLite convient parfaitement à la mémoire des Agents, à l’historique des conversations et à l’isolation par locataire. Choisissez Postgres si votre charge de travail nécessite l’ensemble des fonctionnalités SQL, des schémas relationnels ou des données applicatives structurées qui dépassent l’état d’exécution de Mastra. MongoDB (bientôt disponible) apportera le stockage de documents et la recherche vectorielle intégrée aux charges de travail qui ne s’adaptent pas aisément à SQL.

Fournisseur	Moteur	Idéal pour
Turso	LibSQL, compatible avec SQLite	Mémoire des Agents, isolation par locataire
PostgreSQL	Postgres serverless	Charges de travail relationnelles, données structurées
MongoDB	Recherche documentaire et vectorielle	Stockage de documents, recherche vectorielle (bientôt disponible)

Portée de la base de données

Une base de données est associée selon l’une des deux portées suivantes :

• Portée d’environnement : il s’agit de la portée par défaut. La base de données est associée à un seul environnement afin que les données restent isolées entre les environnements (par exemple, avec des bases distinctes pour la production et la préproduction). Lorsque votre projet ne comporte qu’un environnement, mastra env db create le sélectionne automatiquement ; s’il en comporte plusieurs, la CLI vous invite à en choisir un.
• Portée de projet : une même base de données est partagée par tous les environnements du projet. Activez cette portée avec --shared. Ses variables sont injectées dans chaque déploiement.

La portée est définie lorsque vous associez la base de données et s’affiche dans mastra env db list.

Les portées ne peuvent pas se chevaucher pour un même fournisseur. Comme une base de données à l’échelle du projet injecte déjà ses variables dans chaque environnement, l’association d’une base de données du même fournisseur à l’échelle d’un environnement est refusée en raison d’un conflit de noms de variables. Pour passer d’une base de données partagée à une base par environnement, supprimez d’abord la base à l’échelle du projet, puis associez une base de données à chaque environnement. La suppression d’une base de données la détruit chez le fournisseur avec toutes ses données : exportez tout ce que vous souhaitez conserver avant de changer de portée. Les bases associées à des environnements différents n’entrent jamais en conflit, car chaque déploiement ne reçoit que les variables de son propre environnement.

Associer une base de données avec la CLI

Vous n’avez pas besoin d’exécuter cette commande au préalable. Si votre projet nécessite une base de données hébergée, mais n’en possède pas encore, mastra deploy vous propose d’en associer une lors du contrôle préalable au déploiement. Acceptez et le déploiement se poursuit sans quitter la CLI.

Vous pouvez également créer et associer une base de données à l’avance. La CLI interroge son état jusqu’à ce qu’elle soit prête, ce qui prend quelques secondes :

# 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

Les types pris en charge sont turso et neon (Postgres). Options utiles :

• --shared : associe une base de données à l’échelle du projet et la partage avec chaque environnement. Cette option ne peut pas être combinée avec un argument d’environnement.
• --name <name> : nom de la base de données. Par défaut, il est dérivé du slug du projet.
• --region <region> : identifiant de région du fournisseur pour les bases de données à l’échelle du projet (par exemple fra). Les bases à l’échelle d’un environnement sont automatiquement placées près de la région de cet environnement ; une option --region explicite est alors ignorée.
• --no-wait : rend immédiatement la main au lieu d’interroger l’état. Consultez l’avancement ultérieurement avec mastra env db show.
• --json : produit une sortie lisible par une machine. Lorsque le projet comporte plusieurs environnements, --json nécessite un argument d’environnement ou --shared (aucune invite interactive).

Inspectez et gérez les bases de données associées :

mastra env db list
mastra env db show <database>
mastra env db delete <database>

mastra env db list affiche le type, l’état, la portée et les noms des variables injectées pour chaque base de données. mastra env db show affiche les instructions de connexion en masquant les valeurs secrètes. Utilisez --show-secrets pour les révéler. mastra env db delete supprime définitivement la base de données et toutes ses données chez le fournisseur. La création et la suppression de bases de données nécessitent le rôle d’administrateur dans votre organisation.

Associer une base de données depuis les paramètres du projet

1. Ouvrez votre projet dans la plateforme, puis accédez à Project Settings.

2. Ouvrez la section Database, puis sélectionnez Add database.

3. Sélectionnez un fournisseur (Turso ou Postgres). Vous pouvez changer de fournisseur avant l’association.

4. Configurez la base de données :

   • Name : libellé de la base de données au sein de votre projet.
   • Region : emplacement d’hébergement de la base de données. Sélectionnez la région la plus proche de vos utilisateurs. Turso utilise sjc (San José) par défaut et est disponible dans plus de 20 emplacements à travers le monde. Postgres utilise aws-us-west-2 par défaut et est disponible dans les régions AWS et Azure des États-Unis, de l’Union européenne et de l’Asie-Pacifique.

5. Sélectionnez Attach database. Le provisionnement s’effectue en arrière-plan. La base de données commence à l’état provisioning, puis passe à ready lorsque le fournisseur termine la configuration. Les informations de connexion sont automatiquement injectées dans votre projet sous forme de variables d’environnement d’exécution côté serveur.

Les bases de données associées depuis les paramètres du projet ont une portée de projet. Utilisez la CLI pour associer une base de données à un environnement.

Se connecter depuis votre code

Lorsqu’une base de données est à l’état ready, le fournisseur a terminé son provisionnement et la plateforme a injecté les informations de connexion sous forme de variables d’environnement gérées. Consultez son état dans Project Settings → Database : chaque base associée affiche provisioning pendant la configuration en arrière-plan, puis ready lorsqu’elle est accessible. Ouvrez une base à l’état ready pour afficher ses variables d’environnement et un extrait de code prêt à être copié-collé. Utilisez ces variables avec un adaptateur de stockage Mastra, sans aucune configuration manuelle.

Turso (LibSQL)

Turso expose deux variables d’environnement : TURSO_DATABASE_URL et TURSO_AUTH_TOKEN. L’exemple suivant connecte un LibSQLStore à l’aide de ces variables.

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

Installez l’adaptateur :

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

PostgreSQL

PostgreSQL expose une seule chaîne de connexion DATABASE_URL. L’exemple suivant connecte un PostgresStore à l’aide de cette variable.

src/mastra/storage.ts

import { PostgresStore } from '@mastra/pg'

export const storage = new PostgresStore({
  connectionString: process.env.DATABASE_URL!,
})

Installez l’adaptateur :

npm

npm install @mastra/pg@latest

pnpm

pnpm add @mastra/pg@latest

Yarn

yarn add @mastra/pg@latest

Bun

bun add @mastra/pg@latest

Transmettez l’instance storage à votre configuration Mastra afin que les Agents, la mémoire et les Workflows puissent l’utiliser :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { storage } from './storage'

export const mastra = new Mastra({
  storage,
})

Variables d’environnement

Chaque fournisseur injecte un ensemble fixe de variables d’environnement gérées. Elles sont accessibles à votre projet lors de son exécution dès que la base de données est à l’état ready. Vous n’avez pas à les définir vous-même.

Fournisseur	Variables
Turso	TURSO_DATABASE_URL, TURSO_AUTH_TOKEN
Postgres	DATABASE_URL

attention

Traitez les identifiants de connexion comme des secrets. Le jeton d’authentification (TURSO_AUTH_TOKEN) et la chaîne de connexion Postgres (DATABASE_URL) donnent un accès complet à vos données. La plateforme les masque par défaut et ne les révèle que sur demande.

Gérer une base de données

• Afficher les informations de connexion : ouvrez une base de données à l’état ready dans les paramètres de votre projet pour consulter ses variables d’environnement et un extrait de code prêt à être copié-collé.
• Supprimer : retirer une base de données d’un projet la supprime chez le fournisseur et efface les variables d’environnement injectées. Cette opération est irréversible ; assurez-vous donc de ne plus avoir besoin des données.