> ## 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 su Square Cloud: connessione, limiti e funzionalità supportate

> MongoDB gestito su Square Cloud: connection string, TLS con certificato client, server standalone (senza transazioni né change stream), ruoli dell'utente, memoria, profiler ed errori comuni.

Un server MongoDB gestito con connessione TLS tramite certificato client e un utente che gestisce i propri database, collection e indici. Le informazioni comuni a tutti i motori (limiti, snapshot, Insights) si trovano nella [panoramica dei database](https://docs.squarecloud.app/it/services/databases.md).

## Connettersi

Copia l'URL di connessione dalla pagina del database nella dashboard. Ha questa forma, con l'utente `default` che si autentica sul database `admin`:

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

MongoDB richiede **TLS e il certificato client**. Scarica il `.pem` in **Connessione** → **Certificato SSL/TLS** e passalo sia come certificato client sia come CA: `tls=true`, `tlsCertificateKeyFile` e `tlsCAFile`.

> [!WARNING]
>
> Se aggiungi un nome di database all'URL (`mongodb://...:PORT/mydb`), i driver si autenticano su `mydb` e l'accesso fallisce con `Authentication failed`. In quel caso mantieni `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
> ```

## Un server standalone

Ogni database è un singolo server **standalone**: niente replica set né oplog, e non può essere convertito in uno. Questo significa:

| Funzionalità | Stato | Errore che ricevi |
| :- | :- | :- |
| Transazioni multi-documento | Non disponibili | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change stream (`watch()`) | Non disponibili | `The $changeStream stage is only supported on replica sets` |
| Prisma con MongoDB | Non supportato (Prisma richiede un replica set) | |
| Driver ufficiali e Mongoose | Supportati, senza transazioni | |

Le scritture su un singolo documento sono atomiche: gli aggiornamenti con operatori come `$inc`, `$push` o `$set`, e `findOneAndUpdate`, coprono molti casi che altrimenti richiederebbero una transazione. Le librerie che aprono sessioni con transazioni (per esempio `connection.transaction()` di Mongoose) falliscono con il primo errore qui sopra.

## Connessioni

Ogni database accetta fino a 256 connessioni simultanee. Ogni `MongoClient` mantiene il proprio pool (`maxPoolSize`) **più 2 connessioni di monitoraggio**, quindi crea **un solo client per processo** e riutilizzalo: un client per ogni richiesta esaurisce rapidamente le connessioni. La scheda **Insights** mostra chi tiene aperte le connessioni.

## Il tuo utente e i permessi

L'utente `default` ha i ruoli `readWriteAnyDatabase` e `dbAdminAnyDatabase`. Puoi creare ed eliminare database, collection e indici, e leggere `db.stats()`, `$collStats`, `explain()` e il profiler (`system.profile`).

Non può creare utenti o ruoli, eseguire `db.serverStatus()`, vedere le operazioni di altre connessioni (`currentOp`), né eseguire `top`, `hostInfo`, `setParameter` o `shutdown`. Gli strumenti di monitoraggio che dipendono da `serverStatus` non funzionano; usa invece `db.stats()`, `$collStats` e il profiler.

## Memoria

MongoDB dimensiona la sua cache WiredTiger in base alla RAM del database: **il valore maggiore tra il 50% di (RAM meno 1 GB) e 256 MB**.

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

* La dimensione viene letta all'avvio del server: riavvia il database dopo averne cambiato la RAM. Non può essere regolata.
* La cache contiene solo le pagine di dati e di indici toccate dalle tue query.
* Memoria fuori dalla cache: circa 1 MB per connessione, la creazione degli indici e le aggregazioni (uno stage oltre i 100 MB viene riversato su disco).
* L'allocatore di memoria conserva la memoria liberata per riutilizzarla, quindi la RAM mostrata nella dashboard sale e poi resta alta. È normale, non un memory leak.

## Query lente

Il profiler registra le operazioni che richiedono 100 ms o più nella collection `system.profile` di ogni database (limitata a 1 MB), e la scheda **Insights** le elenca:

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

Usa `explain("executionStats")` su una query lenta per vedere se usa un indice.

## Storage

MongoDB conserva fino a 200 MB di propri dati diagnostici, che contano nei 10 GB del database. Quando lo storage è completamente pieno, MongoDB si arresta e non riparte da solo: avvialo dalla dashboard e libera subito spazio (elimina le collection o gli indici che non ti servono). Vedi [disco pieno](https://docs.squarecloud.app/it/platform/troubleshooting/database-performance.md#il-disco-è-pieno).

## Snapshot

Uno snapshot di MongoDB contiene tutti i database, utenti inclusi, in forma compressa; il limite di dimensione si applica all'esportazione compressa. Senza oplog, uno snapshot creato mentre sono in corso scritture non corrisponde a un singolo istante. Vedi [snapshot e ripristino](https://docs.squarecloud.app/it/services/databases.md#snapshot-e-ripristino).

## Errori comuni

| Messaggio | Cosa significa | Cosa fare |
| :- | :- | :- |
| L'handshake TLS fallisce, oppure `MongoServerSelectionError` subito | Il client si è connesso senza TLS o senza il certificato client. | Imposta `tls`, `tlsCAFile` e `tlsCertificateKeyFile` sul `.pem`. |
| `Authentication failed` | Password errata, oppure l'URL indica un database senza `authSource=admin`. | Controlla la password; aggiungi `authSource=admin`. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Le transazioni richiedono un replica set. | Usa aggiornamenti atomici su un singolo documento. |
| `The $changeStream stage is only supported on replica sets` | I change stream richiedono un replica set. | Notifica le modifiche dal tuo codice (per esempio con il pub/sub di Redis). |
| `not authorized on admin to execute command` | Il comando richiede un ruolo che l'utente non ha (`serverStatus`, `createUser`...). | Usa `db.stats()`, `$collStats` e il profiler. |

## Contattaci

Se continui a riscontrare **difficoltà tecniche**, il nostro **team di supporto specializzato** è disponibile ad assisterti. [**Contattaci**](https://squarecloud.app/it/support) e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud [**4,9/5 su 402 recensioni**](https://www.trustpilot.com/review/squarecloud.app) su Google e Trustpilot.


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