> ## 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 auf Square Cloud: Verbindung, Limits und unterstützte Funktionen

> Verwaltetes MongoDB auf Square Cloud: Connection String, TLS mit Client-Zertifikat, Standalone-Server (ohne Transaktionen oder Change Streams), Benutzerrollen, Speicher, Profiler und häufige Fehler.

Ein verwalteter MongoDB-Server mit TLS-Verbindung per Client-Zertifikat und einem Benutzer, der seine eigenen Datenbanken, Collections und Indizes verwaltet. Was für alle Engines gilt (Limits, Snapshots, Insights), steht in der [Datenbank-Übersicht](https://docs.squarecloud.app/de/services/databases.md).

## Verbinden

Kopiere die Verbindungs-URL von der Seite der Datenbank im Dashboard. Sie hat diese Form, mit dem Benutzer `default`, der sich gegen die Datenbank `admin` authentifiziert:

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

MongoDB verlangt **TLS und das Client-Zertifikat**. Lade die `.pem` unter **Verbindung** → **SSL/TLS-Zertifikat** herunter und übergib sie sowohl als Client-Zertifikat als auch als CA: `tls=true`, `tlsCertificateKeyFile` und `tlsCAFile`.

> [!WARNING]
>
> Wenn du der URL einen Datenbanknamen hinzufügst (`mongodb://...:PORT/mydb`), authentifizieren sich die Treiber gegen `mydb`, und die Anmeldung schlägt mit `Authentication failed` fehl. Behalte in diesem Fall `authSource=admin` bei: `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
> ```

## Ein Standalone-Server

Jede Datenbank ist ein einzelner **Standalone**-Server: kein Replica Set und kein Oplog, und er lässt sich nicht in eines umwandeln. Das bedeutet:

| Funktion | Status | Fehler, den du bekommst |
| :- | :- | :- |
| Transaktionen über mehrere Dokumente | Nicht verfügbar | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change Streams (`watch()`) | Nicht verfügbar | `The $changeStream stage is only supported on replica sets` |
| Prisma mit MongoDB | Nicht unterstützt (Prisma erfordert ein Replica Set) | |
| Offizielle Treiber und Mongoose | Unterstützt, ohne Transaktionen | |

Schreibvorgänge auf ein einzelnes Dokument sind atomar: Updates mit Operatoren wie `$inc`, `$push` oder `$set` sowie `findOneAndUpdate` decken viele Fälle ab, die sonst eine Transaktion bräuchten. Bibliotheken, die Sitzungen mit Transaktionen öffnen (zum Beispiel `connection.transaction()` von Mongoose), schlagen mit dem ersten Fehler oben fehl.

## Verbindungen

Jede Datenbank akzeptiert bis zu 256 gleichzeitige Verbindungen. Jeder `MongoClient` hält seinen eigenen Pool (`maxPoolSize`) **plus 2 Monitoring-Verbindungen**, also erstelle **einen Client pro Prozess** und verwende ihn wieder: Mit einem Client pro Request gehen dir schnell die Verbindungen aus. Der Tab **Insights** zeigt, wer die offenen Verbindungen hält.

## Dein Benutzer und seine Berechtigungen

Der Benutzer `default` hat die Rollen `readWriteAnyDatabase` und `dbAdminAnyDatabase`. Du kannst Datenbanken, Collections und Indizes erstellen und löschen und `db.stats()`, `$collStats`, `explain()` und den Profiler (`system.profile`) lesen.

Er kann keine Benutzer oder Rollen erstellen, kein `db.serverStatus()` ausführen, keine Operationen anderer Verbindungen sehen (`currentOp`) und weder `top`, `hostInfo`, `setParameter` noch `shutdown` ausführen. Monitoring-Tools, die von `serverStatus` abhängen, funktionieren nicht; nutze stattdessen `db.stats()`, `$collStats` und den Profiler.

## Arbeitsspeicher

MongoDB bemisst seinen WiredTiger-Cache anhand des RAM der Datenbank: **der größere Wert von 50 % von (RAM minus 1 GB) und 256 MB**.

| RAM der Datenbank | WiredTiger-Cache |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1,5 GB |
| 8 GB | 3,5 GB |

* Die Größe wird beim Start des Servers gelesen: Starte die Datenbank neu, nachdem du ihren RAM geändert hast. Sie lässt sich nicht anpassen.
* Der Cache enthält nur die Daten- und Indexseiten, die deine Abfragen berührt haben.
* Speicher außerhalb des Caches: etwa 1 MB pro Verbindung, Index-Builds und Aggregationen (eine Stage über 100 MB lagert auf die Festplatte aus).
* Der Speicher-Allocator behält freigegebenen Speicher zur Wiederverwendung, daher steigt der im Dashboard angezeigte RAM und bleibt dann hoch. Das ist normal, kein Leak.

## Langsame Abfragen

Der Profiler zeichnet Operationen, die 100 ms oder länger dauern, in der Collection `system.profile` jeder Datenbank auf (auf 1 MB begrenzt), und der Tab **Insights** listet sie auf:

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

Nutze `explain("executionStats")` bei einer langsamen Abfrage, um zu sehen, ob sie einen Index verwendet.

## Speicherplatz

MongoDB behält bis zu 200 MB eigener Diagnosedaten, die zu den 10 GB der Datenbank zählen. Wenn der Speicherplatz komplett voll ist, stoppt MongoDB und kommt nicht von selbst zurück: Starte die Datenbank im Dashboard und gib sofort Platz frei (lösche Collections oder Indizes, die du nicht brauchst). Siehe [Speicherplatz voll](https://docs.squarecloud.app/de/platform/troubleshooting/database-performance.md#der-speicherplatz-ist-voll).

## Snapshots

Ein MongoDB-Snapshot enthält jede Datenbank, einschließlich der Benutzer, komprimiert; das Größenlimit gilt für den komprimierten Export. Ohne Oplog bildet ein Snapshot, der während laufender Schreibvorgänge erstellt wird, keinen einzelnen Zeitpunkt ab. Siehe [Snapshots und Wiederherstellung](https://docs.squarecloud.app/de/services/databases.md#snapshots-und-wiederherstellung).

## Häufige Fehler

| Meldung | Bedeutung | Was zu tun ist |
| :- | :- | :- |
| TLS-Handshake schlägt fehl, oder sofort `MongoServerSelectionError` | Der Client hat sich ohne TLS oder ohne Client-Zertifikat verbunden. | Setze `tls`, `tlsCAFile` und `tlsCertificateKeyFile` auf die `.pem`. |
| `Authentication failed` | Falsches Passwort, oder die URL nennt eine Datenbank ohne `authSource=admin`. | Prüfe das Passwort; füge `authSource=admin` hinzu. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Transaktionen brauchen ein Replica Set. | Nutze atomare Updates auf einzelne Dokumente. |
| `The $changeStream stage is only supported on replica sets` | Change Streams brauchen ein Replica Set. | Melde Änderungen aus deinem eigenen Code (zum Beispiel mit Redis Pub/Sub). |
| `not authorized on admin to execute command` | Der Befehl braucht eine Rolle, die der Benutzer nicht hat (`serverStatus`, `createUser`...). | Nutze `db.stats()`, `$collStats` und den Profiler. |

## Kontaktiere uns

Falls du weiterhin **technische Schwierigkeiten** hast, steht dir unser **spezialisiertes Support-Team** zur Verfügung. [**Kontaktiere uns**](https://squarecloud.app/de/support) und wir helfen dir gerne, jedes Problem zu lösen: die Qualität unseres Supports ist ein wichtiger Grund, warum Entwickler Square Cloud mit [**4,9/5 bei 402 Bewertungen**](https://www.trustpilot.com/review/squarecloud.app) auf Google und Trustpilot bewerten.


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