> ## 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 na Square Cloud: conexão, limites e recursos suportados

> MongoDB gerenciado na Square Cloud: connection string, TLS com certificado do cliente, servidor standalone (sem transações nem change streams), roles do usuário, memória, profiler e erros comuns.

Um servidor MongoDB gerenciado com conexão TLS por certificado do cliente e um usuário que gerencia os próprios bancos de dados, coleções e índices. O que vale para todos os engines (limites, snapshots, Insights) está na [visão geral de Bancos de dados](https://docs.squarecloud.app/pt-br/services/databases.md).

## Conectar

Copie a URL de conexão da página do banco de dados no dashboard. Ela tem este formato, com o usuário `default` se autenticando no banco `admin`:

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

O MongoDB exige **TLS e o certificado do cliente**. Baixe o `.pem` em **Conexão** → **Certificado SSL/TLS** e passe-o como certificado do cliente e como CA: `tls=true`, `tlsCertificateKeyFile` e `tlsCAFile`.

> [!WARNING]
>
> Se você incluir um nome de banco na URL (`mongodb://...:PORT/mydb`), os drivers se autenticam no `mydb` e o login falha com `Authentication failed`. Nesse caso, mantenha `authSource=admin`: `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
> ```

## Um servidor standalone

Cada banco de dados é um único servidor **standalone**: sem replica set e sem oplog, e não pode ser convertido em um. Isso significa:

| Recurso | Situação | Erro que você recebe |
| :- | :- | :- |
| Transações com vários documentos | Indisponível | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change streams (`watch()`) | Indisponível | `The $changeStream stage is only supported on replica sets` |
| Prisma com MongoDB | Sem suporte (o Prisma exige um replica set) | |
| Drivers oficiais e Mongoose | Com suporte, sem transações | |

As escritas em um único documento são atômicas: updates com operadores como `$inc`, `$push` ou `$set`, e o `findOneAndUpdate`, cobrem muitos casos que de outro jeito precisariam de uma transação. Bibliotecas que abrem sessões com transações (por exemplo, o `connection.transaction()` do Mongoose) falham com o primeiro erro acima.

## Conexões

Cada banco de dados aceita até 256 conexões simultâneas. Cada `MongoClient` mantém o próprio pool (`maxPoolSize`) **mais 2 conexões de monitoramento**, então crie **um client por processo** e reutilize-o: um client por requisição esgota as conexões rapidamente. A aba **Insights** mostra quem está com as conexões abertas.

## Seu usuário e permissões

O usuário `default` tem os roles `readWriteAnyDatabase` e `dbAdminAnyDatabase`. Você pode criar e apagar bancos de dados, coleções e índices, e ler `db.stats()`, `$collStats`, `explain()` e o profiler (`system.profile`).

Ele não pode criar usuários nem roles, rodar `db.serverStatus()`, ver as operações de outras conexões (`currentOp`), nem rodar `top`, `hostInfo`, `setParameter` ou `shutdown`. Ferramentas de monitoramento que dependem do `serverStatus` não funcionam; use `db.stats()`, `$collStats` e o profiler no lugar.

## Memória

O MongoDB dimensiona o cache do WiredTiger a partir da RAM do banco de dados: **o maior entre 50% de (RAM menos 1 GB) e 256 MB**.

| RAM do banco de dados | Cache do WiredTiger |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1,5 GB |
| 8 GB | 3,5 GB |

* O tamanho é lido quando o servidor inicia: reinicie o banco depois de mudar a RAM. Ele não pode ser ajustado.
* O cache guarda só as páginas de dados e de índices que as suas queries tocaram.
* Memória fora do cache: cerca de 1 MB por conexão, criação de índices e aggregations (um estágio acima de 100 MB passa para o disco).
* O alocador de memória guarda a memória liberada para reutilizar, então a RAM exibida no dashboard sobe e depois fica alta. Isso é normal, não é um vazamento.

## Consultas lentas

O profiler registra as operações que levam 100 ms ou mais na coleção `system.profile` de cada banco (limitada a 1 MB), e a aba **Insights** as lista:

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

Use `explain("executionStats")` em uma query lenta para ver se ela usa um índice.

## Armazenamento

O MongoDB guarda até 200 MB dos próprios dados de diagnóstico, que contam nos 10 GB do banco. Quando o armazenamento fica totalmente cheio, o MongoDB para e não volta sozinho: inicie-o pelo dashboard e libere espaço na hora (apague coleções ou índices de que você não precisa). Veja [disco cheio](https://docs.squarecloud.app/pt-br/platform/troubleshooting/database-performance.md#o-disco-está-cheio).

## Snapshots

Um snapshot do MongoDB contém todos os bancos de dados, usuários incluídos, comprimidos; o limite de tamanho vale para a exportação comprimida. Sem oplog, um snapshot feito enquanto há escritas acontecendo não corresponde a um único ponto no tempo. Veja [snapshots e restauração](https://docs.squarecloud.app/pt-br/services/databases.md#snapshots-e-restauração).

## Erros comuns

| Mensagem | O que significa | O que fazer |
| :- | :- | :- |
| O handshake TLS falha, ou `MongoServerSelectionError` logo de cara | O cliente se conectou sem TLS ou sem o certificado do cliente. | Defina `tls`, `tlsCAFile` e `tlsCertificateKeyFile` com o `.pem`. |
| `Authentication failed` | Senha errada, ou a URL indica um banco sem `authSource=admin`. | Confira a senha; adicione `authSource=admin`. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Transações exigem um replica set. | Use updates atômicos em um único documento. |
| `The $changeStream stage is only supported on replica sets` | Change streams exigem um replica set. | Avise sobre as mudanças pelo seu próprio código (por exemplo, com pub/sub do Redis). |
| `not authorized on admin to execute command` | O comando exige um role que o usuário não tem (`serverStatus`, `createUser`...). | Use `db.stats()`, `$collStats` e o profiler. |

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


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