> ## 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 on Square Cloud: Connection, Limits and Supported Features

> Managed MongoDB on Square Cloud: connection string, TLS with a client certificate, standalone server (no transactions or change streams), user roles, memory, profiler and common errors.

A managed MongoDB server with a client-certificate TLS connection and a user that manages its own databases, collections and indexes. Facts shared by every engine (limits, snapshots, Insights) are on the [Databases overview](https://docs.squarecloud.app/en/services/databases.md).

## Connect

Copy the connection URL from the database's page in the dashboard. It has this shape, with the `default` user authenticating against the `admin` database:

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

MongoDB requires **TLS and the client certificate**. Download the `.pem` under **Connection** → **SSL/TLS certificate** and pass it as both the client certificate and the CA: `tls=true`, `tlsCertificateKeyFile` and `tlsCAFile`.

> [!WARNING]
>
> If you add a database name to the URL (`mongodb://...:PORT/mydb`), drivers authenticate against `mydb` and the login fails with `Authentication failed`. Keep `authSource=admin` in that case: `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
> ```

## A standalone server

Each database is a single **standalone** server: no replica set and no oplog, and it can't be converted into one. That means:

| Feature | Status | Error you get |
| :- | :- | :- |
| Multi-document transactions | Not available | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change streams (`watch()`) | Not available | `The $changeStream stage is only supported on replica sets` |
| Prisma with MongoDB | Not supported (Prisma requires a replica set) | |
| Official drivers and Mongoose | Supported, without transactions | |

Single-document writes are atomic: updates with operators such as `$inc`, `$push` or `$set`, and `findOneAndUpdate`, cover many cases that would otherwise need a transaction. Libraries that open sessions with transactions (for example Mongoose's `connection.transaction()`) fail with the first error above.

## Connections

Each database accepts up to 256 simultaneous connections. Every `MongoClient` keeps its own pool (`maxPoolSize`) **plus 2 monitoring connections**, so create **one client per process** and reuse it: a client per request runs out of connections quickly. The **Insights** tab shows who holds the open connections.

## Your user and permissions

The `default` user has the `readWriteAnyDatabase` and `dbAdminAnyDatabase` roles. You can create and drop databases, collections and indexes, and read `db.stats()`, `$collStats`, `explain()` and the profiler (`system.profile`).

It can't create users or roles, run `db.serverStatus()`, see other connections' operations (`currentOp`), or run `top`, `hostInfo`, `setParameter` or `shutdown`. Monitoring tools that depend on `serverStatus` don't work; use `db.stats()`, `$collStats` and the profiler instead.

## Memory

MongoDB sizes its WiredTiger cache from the database's RAM: **the larger of 50% of (RAM minus 1 GB) and 256 MB**.

| Database RAM | WiredTiger cache |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1.5 GB |
| 8 GB | 3.5 GB |

* The size is read when the server starts: restart the database after changing its RAM. It can't be tuned.
* The cache holds only the data and index pages your queries touched.
* Memory outside the cache: about 1 MB per connection, index builds, and aggregations (a stage above 100 MB spills to disk).
* The memory allocator keeps freed memory for reuse, so the RAM shown in the dashboard climbs and then stays high. That is normal, not a leak.

## Slow queries

The profiler records operations that take 100 ms or more in each database's `system.profile` collection (capped at 1 MB), and the **Insights** tab lists them:

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

Use `explain("executionStats")` on a slow query to see whether it uses an index.

## Storage

MongoDB keeps up to 200 MB of its own diagnostic data, which counts toward the database's 10 GB. When the storage is completely full, MongoDB stops and does not come back by itself: start it from the dashboard and free space right away (drop collections or indexes you don't need). See [disk full](https://docs.squarecloud.app/en/platform/troubleshooting/database-performance.md#the-disk-is-full).

## Snapshots

A MongoDB snapshot holds every database, users included, compressed; the size limit applies to the compressed export. Without an oplog, a snapshot taken while writes are happening is not a single point in time. See [snapshots and restore](https://docs.squarecloud.app/en/services/databases.md#snapshots-and-restore).

## Common errors

| Message | What it means | What to do |
| :- | :- | :- |
| TLS handshake fails, or `MongoServerSelectionError` right away | The client connected without TLS or without the client certificate. | Set `tls`, `tlsCAFile` and `tlsCertificateKeyFile` to the `.pem`. |
| `Authentication failed` | Wrong password, or the URL names a database without `authSource=admin`. | Check the password; add `authSource=admin`. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Transactions need a replica set. | Use single-document atomic updates. |
| `The $changeStream stage is only supported on replica sets` | Change streams need a replica set. | Notify changes from your own code (for example with Redis pub/sub). |
| `not authorized on admin to execute command` | The command needs a role the user doesn't have (`serverStatus`, `createUser`...). | Use `db.stats()`, `$collStats` and the profiler. |

## Contact us

If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot.


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