> ## 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 en Square Cloud: conexión, límites y funciones compatibles

> MongoDB gestionado en Square Cloud: cadena de conexión, TLS con certificado de cliente, servidor standalone (sin transacciones ni change streams), roles del usuario, memoria, profiler y errores comunes.

Un servidor de MongoDB gestionado con conexión TLS por certificado de cliente y un usuario que administra sus propias bases de datos, colecciones e índices. Lo que comparten todos los motores (límites, snapshots, Insights) está en la [visión general de bases de datos](https://docs.squarecloud.app/es/services/databases.md).

## Conectarse

Copia la URL de conexión desde la página de la base de datos en el dashboard. Tiene esta forma, con el usuario `default` autenticándose en la base de datos `admin`:

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

MongoDB exige **TLS y el certificado de cliente**. Descarga el `.pem` en **Conexión** → **Certificado SSL/TLS** y pásalo como certificado de cliente y como CA: `tls=true`, `tlsCertificateKeyFile` y `tlsCAFile`.

> [!WARNING]
>
> Si añades un nombre de base de datos a la URL (`mongodb://...:PORT/mydb`), los drivers se autentican en `mydb` y el inicio de sesión falla con `Authentication failed`. En ese caso, mantén `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 servidor standalone

Cada base de datos es un único servidor **standalone**: sin replica set ni oplog, y no se puede convertir en uno. Eso significa:

| Función | Estado | Error que recibes |
| :- | :- | :- |
| Transacciones multidocumento | No disponible | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change streams (`watch()`) | No disponible | `The $changeStream stage is only supported on replica sets` |
| Prisma con MongoDB | No compatible (Prisma requiere un replica set) | |
| Drivers oficiales y Mongoose | Compatibles, sin transacciones | |

Las escrituras en un solo documento son atómicas: las actualizaciones con operadores como `$inc`, `$push` o `$set`, y `findOneAndUpdate`, cubren muchos casos que de otro modo necesitarían una transacción. Las librerías que abren sesiones con transacciones (por ejemplo `connection.transaction()` de Mongoose) fallan con el primer error de arriba.

## Conexiones

Cada base de datos acepta hasta 256 conexiones simultáneas. Cada `MongoClient` mantiene su propio pool (`maxPoolSize`) **más 2 conexiones de monitoreo**, así que crea **un cliente por proceso** y reutilízalo: un cliente por petición agota las conexiones rápidamente. La pestaña **Insights** muestra quién mantiene las conexiones abiertas.

## Tu usuario y permisos

El usuario `default` tiene los roles `readWriteAnyDatabase` y `dbAdminAnyDatabase`. Puedes crear y eliminar bases de datos, colecciones e índices, y leer `db.stats()`, `$collStats`, `explain()` y el profiler (`system.profile`).

No puede crear usuarios ni roles, ejecutar `db.serverStatus()`, ver las operaciones de otras conexiones (`currentOp`), ni ejecutar `top`, `hostInfo`, `setParameter` o `shutdown`. Las herramientas de monitoreo que dependen de `serverStatus` no funcionan; usa `db.stats()`, `$collStats` y el profiler en su lugar.

## Memoria

MongoDB dimensiona su caché de WiredTiger a partir de la RAM de la base de datos: **el mayor valor entre el 50% de (RAM menos 1 GB) y 256 MB**.

| RAM de la base de datos | Caché de WiredTiger |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1,5 GB |
| 8 GB | 3,5 GB |

* El tamaño se lee cuando el servidor inicia: reinicia la base de datos después de cambiar su RAM. No se puede ajustar.
* La caché solo guarda las páginas de datos e índices que tocaron tus consultas.
* Memoria fuera de la caché: cerca de 1 MB por conexión, la creación de índices y las agregaciones (una etapa de más de 100 MB se vuelca a disco).
* El asignador de memoria conserva la memoria liberada para reutilizarla, así que la RAM que muestra el dashboard sube y luego se mantiene alta. Es normal, no una fuga.

## Consultas lentas

El profiler registra las operaciones que tardan 100 ms o más en la colección `system.profile` de cada base de datos (limitada a 1 MB), y la pestaña **Insights** las lista:

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

Usa `explain("executionStats")` en una consulta lenta para ver si usa un índice.

## Almacenamiento

MongoDB guarda hasta 200 MB de sus propios datos de diagnóstico, que cuentan para los 10 GB de la base de datos. Cuando el almacenamiento se llena por completo, MongoDB se detiene y no vuelve por sí solo: inícialo desde el dashboard y libera espacio de inmediato (elimina las colecciones o los índices que no necesites). Consulta [disco lleno](https://docs.squarecloud.app/es/platform/troubleshooting/database-performance.md#el-disco-está-lleno).

## Snapshots

Un snapshot de MongoDB contiene todas las bases de datos, usuarios incluidos, comprimidas; el límite de tamaño se aplica a la exportación comprimida. Sin oplog, un snapshot tomado mientras hay escrituras no corresponde a un único momento. Consulta [snapshots y restauración](https://docs.squarecloud.app/es/services/databases.md#snapshots-y-restauración).

## Errores comunes

| Mensaje | Qué significa | Qué hacer |
| :- | :- | :- |
| El handshake TLS falla, o `MongoServerSelectionError` de inmediato | El cliente se conectó sin TLS o sin el certificado de cliente. | Configura `tls`, `tlsCAFile` y `tlsCertificateKeyFile` con el `.pem`. |
| `Authentication failed` | Contraseña incorrecta, o la URL nombra una base de datos sin `authSource=admin`. | Verifica la contraseña; añade `authSource=admin`. |
| `Transaction numbers are only allowed on a replica set member or mongos` | Las transacciones necesitan un replica set. | Usa actualizaciones atómicas en un solo documento. |
| `The $changeStream stage is only supported on replica sets` | Los change streams necesitan un replica set. | Notifica los cambios desde tu propio código (por ejemplo con pub/sub de Redis). |
| `not authorized on admin to execute command` | El comando necesita un rol que el usuario no tiene (`serverStatus`, `createUser`...). | Usa `db.stats()`, `$collStats` y el profiler. |

## Contáctanos

Si continúas enfrentando **dificultades técnicas**, nuestro **equipo de soporte especializado** está disponible para ayudarte. [**Contáctanos**](https://squarecloud.app/es/support) y estaremos encantados de ayudarte a resolver cualquier problema: la calidad del soporte es una gran parte de por qué los desarrolladores califican a Square Cloud con [**4.9/5 en 402 reseñas**](https://www.trustpilot.com/review/squarecloud.app) en Google y Trustpilot.


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