> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/mastra-platform/overview), 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.

```bash
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](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments) 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 :

```bash
# 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 :

```bash
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](https://mastra.zisheng.pro/fr/docs/mastra-platform/overview), 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](#attach-with-the-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](https://mastra.zisheng.pro/fr/reference/storage/libsql) à l’aide de ces variables.

```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**:

```bash
npm install @mastra/libsql@latest
```

**pnpm**:

```bash
pnpm add @mastra/libsql@latest
```

**Yarn**:

```bash
yarn add @mastra/libsql@latest
```

**Bun**:

```bash
bun add @mastra/libsql@latest
```

### PostgreSQL

PostgreSQL expose une seule chaîne de connexion `DATABASE_URL`. L’exemple suivant connecte un [PostgresStore](https://mastra.zisheng.pro/fr/reference/storage/postgresql) à l’aide de cette variable.

```ts
import { PostgresStore } from '@mastra/pg'

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

Installez l’adaptateur :

**npm**:

```bash
npm install @mastra/pg@latest
```

**pnpm**:

```bash
pnpm add @mastra/pg@latest
```

**Yarn**:

```bash
yarn add @mastra/pg@latest
```

**Bun**:

```bash
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 :

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