Cómo conectar MongoDB a Node.js (y a tu hosting)

Conectar MongoDB a Node.js lleva pocas líneas, pero es donde aparecen los errores que más frenan a quien está empezando: una contraseña con un carácter especial, un cliente nuevo en cada solicitud, la cadena de conexión escrita directamente en el código. Los ejemplos usan el driver oficial mongodb con ESM y async/await.

Si todavía no conoces el modelo de documentos, lee antes qué es MongoDB. Aquí el foco está en la conexión y en lo que cambia cuando la base de datos está en un servidor remoto.

¿Qué necesitas antes de empezar?#

• Node.js instalado y un proyecto con package.json. Para usar import, añade "type": "module" al package.json.
• Un servidor MongoDB accesible: local, en un proveedor o en un hosting de bases de datos.
• La cadena de conexión, el usuario y la contraseña de ese servidor.

Instala el driver:

npm install mongodb

¿Cómo es la cadena de conexión de MongoDB?#

La cadena de conexión indica dónde está el servidor y cómo autenticarse. El formato estándar es:

mongodb://[usuario:contraseña@]host[:puerto][/basededatos][?opciones]

• Sin puerto, el driver usa 27017.
• El /basededatos define qué base de datos abre client.db() cuando no pasas un nombre. Sin él, las credenciales se verifican en la base de datos admin. Si el usuario se creó en otra base de datos, usa la opción authSource.
• Las opciones van como clave=valor separadas por &, por ejemplo tls=true.
• También existe el formato mongodb+srv://, que obtiene la lista de servidores por DNS y es común en clústeres de proveedores. El proveedor te indica qué formato usar.

Los caracteres reservados en el usuario y la contraseña ($, :, /, ?, #, [, ], @) necesitan percent-encoding. p@ss/word pasa a ser p%40ss%2Fword. En Node.js, encodeURIComponent("p@ss/word") hace la conversión.

¿Cómo guardar la cadena de conexión de forma segura?#

Nunca escribas el usuario y la contraseña en el código ni los subas a Git. Usa una variable de entorno llamada, por convención, MONGODB_URI. Para saber más, mira qué son las variables de entorno.

Crea un archivo .env (y añádelo al .gitignore):

MONGODB_URI=mongodb://usuario:contraseña@host:27017/mibasededatos

Las versiones recientes de Node.js cargan ese archivo sin paquetes extra, con la flag --env-file:

node --env-file=.env index.js

¿Cómo conectar, insertar y buscar documentos?#

Crea index.js:

import { MongoClient } from "mongodb";

const uri = process.env.MONGODB_URI;
if (!uri) throw new Error("Define la variable MONGODB_URI");

const client = new MongoClient(uri);

async function main() {
  await client.connect(); // opcional, pero falla pronto si algo está mal
  const db = client.db(); // usa la base de datos de la cadena de conexión
  const usuarios = db.collection("usuarios");

  await usuarios.insertOne({ nombre: "Alice", creadoEn: new Date() });

  const alice = await usuarios.findOne({ nombre: "Alice" });
  console.log(alice);
}

main()
  .catch((error) => {
    console.error("Fallo al usar MongoDB:", error);
    process.exitCode = 1;
  })
  .finally(() => client.close());

Ejecútalo con node --env-file=.env index.js. Si aparece el documento con un _id generado por MongoDB, la conexión funciona. Para comprobar solo la conectividad, sin escribir nada, usa await client.db("admin").command({ ping: 1 }).

En una API o un bot que se ejecuta durante mucho tiempo, no llames a client.close() al final de cada operación. Ese finally existe solo porque el script de arriba termina por sí mismo.

¿Cómo reutilizar la conexión en una API o un bot?#

Cada MongoClient mantiene un pool de conexiones, así que crea uno por proceso y reutilízalo. Crea el cliente en un módulo e impórtalo donde lo necesites:

// db.js
import { MongoClient } from "mongodb";

const client = new MongoClient(process.env.MONGODB_URI);

export const db = client.db();
export { client };

// en cualquier otro archivo
import { db } from "./db.js";

const total = await db.collection("usuarios").countDocuments();

Como el driver se conecta en la primera operación, aquí no necesitas await client.connect(). El tamaño máximo predeterminado del pool es de 100 conexiones (maxPoolSize); cámbialo solo si tienes un motivo medido. Crear un cliente nuevo en cada solicitud o comando gasta conexiones y lo vuelve todo más lento.

¿Cuáles son los errores de conexión más comunes?#

Timeout en la selección de servidor. Mensaje de ejemplo, con la base de datos local apagada:

MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

Causas, de la más común a la menos: el host de la cadena es incorrecto (por ejemplo localhost cuando la base de datos es remota), el servidor está apagado o un firewall bloquea el puerto. Revisa primero el host y el puerto. Puedes acortar la espera con new MongoClient(uri, { serverSelectionTimeoutMS: 5000 }).

Fallo de autenticación.

MongoServerError: Authentication failed.

Revisa el usuario y la contraseña, el percent-encoding de la contraseña y el authSource. Un usuario creado en la base de datos admin necesita ?authSource=admin en la cadena cuando la ruta apunta a otra base de datos.

Error de TLS. Si el servidor exige una conexión cifrada, añade tls=true a la cadena. Si usa un certificado propio, apunta la opción tlsCAFile al archivo de la autoridad certificadora.

Variable vacía. Sin MONGODB_URI, el código de arriba se detiene con el mensaje "Define la variable MONGODB_URI" en index.js. Ejecútalo con --env-file o revisa si la variable se definió en el entorno.

Antes de guardar datos reales, planifica las copias de la base: mira cómo hacer una copia de seguridad de una base de datos.

Cómo hacerlo en Square Cloud#

Square Cloud ofrece hosting de MongoDB a partir del plan Standard (el Hobby no incluye bases de datos). La base de datos queda lista en segundos, en el mismo datacenter que las aplicaciones, con una latencia media de alrededor de 1 ms. Es un nodo único (standalone, sin replica set) y acepta hasta 512 conexiones.

Para conectar tu app Node.js:

1. Crea la base de datos MongoDB en el panel (nombre y memoria, desde 1024 MB) y copia la URL de conexión completa que te entrega. Se muestra solo una vez, al crearla; si la pierdes, restablece la contraseña para verla de nuevo.
2. Descarga el certificado. TLS es obligatorio y el cliente también presenta el certificado: pasa tls: true, tlsCAFile con la CA descargada y tlsCertificateKeyFile con el .pem en las opciones del MongoClient.
3. Define MONGODB_URI como variable de entorno de la aplicación, en el panel, la API, la CLI o VS Code. El cambio se aplica en el siguiente reinicio, sin rebuild.
4. Haz el deploy del código con el mismo MongoClient de esta guía, añadiendo esas opciones de TLS. El archivo squarecloud.app es opcional: el panel lo genera en el deploy, o puedes escribirlo en la raíz del proyecto.

La base también acepta conexiones desde fuera, así que puedes probar la misma URL y el mismo certificado en tu máquina. Puedes tomar snapshots manuales cuando quieras, y todo plan que incluye bases de datos tiene también un snapshot automático diario. Puedes restaurar un snapshot en la misma base, en otra del mismo motor o en una base nueva. Más detalles en hosting de MongoDB.