> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB sur Square Cloud : connexion, limites et fonctionnalités

> MongoDB géré sur Square Cloud : chaîne de connexion, TLS avec certificat client, serveur autonome (sans transactions ni change streams), rôles de l'utilisateur, mémoire, profileur et erreurs courantes.

Un serveur MongoDB géré avec une connexion TLS par certificat client et un utilisateur qui gère ses propres bases de données, collections et index. Les informations communes à tous les moteurs (limites, snapshots, Insights) se trouvent dans la [vue d'ensemble des bases de données](https://docs.squarecloud.app/fr/services/databases.md).

## Se connecter

Copiez l'URL de connexion depuis la page de la base de données dans le tableau de bord. Elle a cette forme, avec l'utilisateur `default` qui s'authentifie sur la base de données `admin` :

```
mongodb://default:PASSWORD@HOST:PORT
```

MongoDB exige **TLS et le certificat client**. Téléchargez le `.pem` sous **Connexion** → **Certificat SSL/TLS** et passez-le à la fois comme certificat client et comme CA : `tls=true`, `tlsCertificateKeyFile` et `tlsCAFile`.

> [!WARNING]
>
> Si vous ajoutez un nom de base de données à l'URL (`mongodb://...:PORT/mydb`), les pilotes s'authentifient sur `mydb` et la connexion échoue avec `Authentication failed`. Gardez `authSource=admin` dans ce cas : `mongodb://default:PASSWORD@HOST:PORT/mydb?authSource=admin`.

> [tab] Node.js
>
> ```javascript theme={"system"}
> import { MongoClient } from "mongodb";
>
> // One client for the whole process, created once and reused.
> export const client = new MongoClient(process.env.MONGO_URL, {
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
>   maxPoolSize: 10,
> });
>
> await client.connect();
> const users = client.db("app").collection("users");
> ```

> [tab] Mongoose
>
> ```javascript theme={"system"}
> import mongoose from "mongoose";
>
> await mongoose.connect(process.env.MONGO_URL, {
>   dbName: "app",
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> from pymongo import MongoClient
>
> client = MongoClient(
>     os.environ["MONGO_URL"],
>     tls=True,
>     tlsCAFile="certificate.pem",
>     tlsCertificateKeyFile="certificate.pem",
> )
> db = client["app"]
> ```

> [tab] mongosh
>
> ```bash theme={"system"}
> mongosh "mongodb://default:PASSWORD@HOST:PORT" \
>   --tls --tlsCAFile certificate.pem --tlsCertificateKeyFile certificate.pem
> ```

## Un serveur autonome

Chaque base de données est un seul serveur **autonome** (standalone) : pas de replica set ni d'oplog, et il ne peut pas être converti en replica set. Cela signifie :

| Fonctionnalité | Statut | Erreur obtenue |
| :- | :- | :- |
| Transactions multi-documents | Non disponible | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change streams (`watch()`) | Non disponible | `The $changeStream stage is only supported on replica sets` |
| Prisma avec MongoDB | Non pris en charge (Prisma exige un replica set) | |
| Pilotes officiels et Mongoose | Pris en charge, sans transactions | |

Les écritures sur un seul document sont atomiques : les mises à jour avec des opérateurs comme `$inc`, `$push` ou `$set`, et `findOneAndUpdate`, couvrent de nombreux cas qui nécessiteraient sinon une transaction. Les bibliothèques qui ouvrent des sessions avec transactions (par exemple `connection.transaction()` de Mongoose) échouent avec la première erreur ci-dessus.

## Connexions

Chaque base de données accepte jusqu'à 256 connexions simultanées. Chaque `MongoClient` garde son propre pool (`maxPoolSize`) **plus 2 connexions de surveillance**, donc créez **un seul client par processus** et réutilisez-le : un client par requête épuise vite les connexions. L'onglet **Insights** montre qui détient les connexions ouvertes.

## Votre utilisateur et ses permissions

L'utilisateur `default` a les rôles `readWriteAnyDatabase` et `dbAdminAnyDatabase`. Vous pouvez créer et supprimer des bases de données, des collections et des index, et lire `db.stats()`, `$collStats`, `explain()` et le profileur (`system.profile`).

Il ne peut pas créer d'utilisateurs ni de rôles, exécuter `db.serverStatus()`, voir les opérations des autres connexions (`currentOp`), ni exécuter `top`, `hostInfo`, `setParameter` ou `shutdown`. Les outils de supervision qui dépendent de `serverStatus` ne fonctionnent pas ; utilisez plutôt `db.stats()`, `$collStats` et le profileur.

## Mémoire

MongoDB dimensionne son cache WiredTiger à partir de la RAM de la base de données : **la plus grande valeur entre 50 % de (RAM moins 1 Go) et 256 Mo**.

| RAM de la base de données | Cache WiredTiger |
| :- | :- |
| 1 Go | 256 Mo |
| 2 Go | 512 Mo |
| 4 Go | 1,5 Go |
| 8 Go | 3,5 Go |

* La taille est lue au démarrage du serveur : redémarrez la base de données après avoir modifié sa RAM. Elle ne peut pas être ajustée.
* Le cache ne contient que les pages de données et d'index touchées par vos requêtes.
* Mémoire hors du cache : environ 1 Mo par connexion, les constructions d'index et les agrégations (une étape qui dépasse 100 Mo déborde sur le disque).
* L'allocateur de mémoire garde la mémoire libérée pour la réutiliser, donc la RAM affichée dans le tableau de bord monte puis reste élevée. C'est normal, ce n'est pas une fuite.

## Requêtes lentes

Le profileur enregistre les opérations qui prennent 100 ms ou plus dans la collection `system.profile` de chaque base de données (plafonnée à 1 Mo), et l'onglet **Insights** les liste :

```javascript theme={"system"}
db.system.profile.find().sort({ ts: -1 }).limit(5)
```

Utilisez `explain("executionStats")` sur une requête lente pour voir si elle utilise un index.

## Stockage

MongoDB conserve jusqu'à 200 Mo de ses propres données de diagnostic, qui comptent dans les 10 Go de la base de données. Quand le stockage est complètement plein, MongoDB s'arrête et ne redémarre pas de lui-même : démarrez-le depuis le tableau de bord et libérez de l'espace immédiatement (supprimez les collections ou les index dont vous n'avez pas besoin). Voir [disque plein](https://docs.squarecloud.app/fr/platform/troubleshooting/database-performance.md#le-disque-est-plein).

## Snapshots

Un snapshot MongoDB contient toutes les bases de données, utilisateurs compris, compressées ; la limite de taille s'applique à l'export compressé. Sans oplog, un snapshot pris pendant des écritures ne correspond pas à un instant unique. Voir [snapshots et restauration](https://docs.squarecloud.app/fr/services/databases.md#snapshots-et-restauration).

## Erreurs courantes

| Message | Ce que ça signifie | Que faire |
| :- | :- | :- |
| La poignée de main TLS échoue, ou `MongoServerSelectionError` immédiatement | Le client s'est connecté sans TLS ou sans le certificat client. | Définissez `tls`, `tlsCAFile` et `tlsCertificateKeyFile` sur le `.pem`. |
| `Authentication failed` | Mot de passe erroné, ou l'URL nomme une base de données sans `authSource=admin`. | Vérifiez le mot de passe ; ajoutez `authSource=admin`. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Les transactions exigent un replica set. | Utilisez des mises à jour atomiques sur un seul document. |
| `The $changeStream stage is only supported on replica sets` | Les change streams exigent un replica set. | Notifiez les changements depuis votre propre code (par exemple avec le pub/sub de Redis). |
| `not authorized on admin to execute command` | La commande exige un rôle que l'utilisateur n'a pas (`serverStatus`, `createUser`...). | Utilisez `db.stats()`, `$collStats` et le profileur. |

## Contactez-nous

Si vous rencontrez toujours des **difficultés techniques**, notre **équipe de support spécialisée** est disponible pour vous aider. [**Contactez-nous**](https://squarecloud.app/fr/support) et nous serons ravis de vous aider à résoudre tout problème. La qualité du support compte pour beaucoup dans la note que les développeurs donnent à Square Cloud, [**4,9/5 sur 402 avis**](https://www.trustpilot.com/review/squarecloud.app) sur Google et Trustpilot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.