Como conectar MongoDB ao Node.js (e à sua hospedagem)

Conectar o MongoDB ao Node.js leva poucas linhas, mas é onde aparecem os erros que mais travam quem está começando: senha com caractere especial, um cliente novo a cada requisição, string de conexão escrita direto no código. Os exemplos usam o driver oficial mongodb com ESM e async/await.

Se você ainda não conhece o modelo de documentos, leia antes o que é MongoDB. Aqui o foco é a conexão e o que muda quando o banco fica em um servidor remoto.

O que você precisa antes de começar?#

• Node.js instalado e um projeto com package.json. Para usar import, adicione "type": "module" ao package.json.
• Um servidor MongoDB acessível: local, em um provedor ou em uma hospedagem de banco de dados.
• A string de conexão, o usuário e a senha desse servidor.

Instale o driver:

npm install mongodb

Como é a string de conexão do MongoDB?#

A string de conexão diz onde está o servidor e como autenticar. O formato padrão é:

mongodb://[usuario:senha@]host[:porta][/banco][?opcoes]

• Sem porta, o driver usa 27017.
• O /banco define qual banco client.db() abre quando você não passa um nome. Sem ele, as credenciais são verificadas no banco admin. Se o usuário foi criado em outro banco, use a opção authSource.
• As opções vêm como chave=valor separadas por &, por exemplo tls=true.
• Existe também o formato mongodb+srv://, que busca a lista de servidores por DNS e é comum em clusters de provedores. O provedor informa qual formato usar.

Caracteres reservados no usuário e na senha ($, :, /, ?, #, [, ], @) precisam de percent-encoding. p@ss/word vira p%40ss%2Fword. No Node.js, encodeURIComponent("p@ss/word") faz a conversão.

Como guardar a string de conexão com segurança?#

Nunca escreva usuário e senha no código nem os envie para o Git. Use uma variável de ambiente chamada, por convenção, MONGODB_URI. Para saber mais, veja o que são variáveis de ambiente.

Crie um arquivo .env (e coloque-o no .gitignore):

MONGODB_URI=mongodb://usuario:senha@host:27017/meubanco

As versões recentes do Node.js carregam esse arquivo sem pacote extra, com a flag --env-file:

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

Como conectar, inserir e buscar documentos?#

Crie index.js:

import { MongoClient } from "mongodb";

const uri = process.env.MONGODB_URI;
if (!uri) throw new Error("Defina a variável MONGODB_URI");

const client = new MongoClient(uri);

async function main() {
  await client.connect(); // opcional, mas falha cedo se algo estiver errado
  const db = client.db(); // usa o banco da string de conexão
  const usuarios = db.collection("usuarios");

  await usuarios.insertOne({ nome: "Alice", criadoEm: new Date() });

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

main()
  .catch((erro) => {
    console.error("Falha ao usar o MongoDB:", erro);
    process.exitCode = 1;
  })
  .finally(() => client.close());

Rode com node --env-file=.env index.js. Se aparecer o documento com um _id gerado pelo MongoDB, a conexão funciona. Para checar só a conectividade, sem gravar nada, use await client.db("admin").command({ ping: 1 }).

Em uma API ou bot que roda por muito tempo, não chame client.close() ao fim de cada operação. Esse finally existe só porque o script acima termina sozinho.

Como reutilizar a conexão em uma API ou bot?#

Cada MongoClient mantém um pool de conexões, então crie um por processo e reutilize-o. Crie o cliente em um módulo e importe-o onde precisar:

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

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

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

// em qualquer outro arquivo
import { db } from "./db.js";

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

Como o driver conecta na primeira operação, você não precisa de await client.connect() aqui. O tamanho máximo padrão do pool é 100 conexões (maxPoolSize); só mude isso se tiver um motivo medido. Criar um cliente novo a cada requisição ou comando gasta conexões e deixa tudo mais lento.

Quais erros de conexão são mais comuns?#

Timeout na seleção de servidor. Mensagem de exemplo, com o banco local desligado:

MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

Causas, da mais comum para a menos comum: o host na string está errado (por exemplo localhost quando o banco é remoto), o servidor está desligado, ou um firewall bloqueia a porta. Confira host e porta primeiro. Dá para encurtar a espera com new MongoClient(uri, { serverSelectionTimeoutMS: 5000 }).

Falha de autenticação.

MongoServerError: Authentication failed.

Verifique usuário e senha, o percent-encoding da senha e o authSource. Um usuário criado no banco admin precisa de ?authSource=admin na string quando o caminho aponta para outro banco.

Erro de TLS. Se o servidor exige conexão criptografada, adicione tls=true à string. Se ele usa certificado próprio, aponte a opção tlsCAFile para o arquivo da autoridade certificadora.

Variável vazia. Sem MONGODB_URI, o código acima para logo com a mensagem "Defina a variável MONGODB_URI" no index.js. Rode com --env-file ou confira se a variável foi definida no ambiente.

Antes de guardar dados reais, planeje as cópias do banco: veja como fazer backup de um banco de dados.

Como fazer isso na Square Cloud#

A Square Cloud oferece hospedagem de MongoDB a partir do plano Standard (o Hobby não inclui bancos). O banco fica pronto em segundos, no mesmo datacenter das aplicações, com latência média de cerca de 1 ms. Ele é um nó único (standalone, sem replica set) e aceita até 512 conexões.

Para conectar o seu app Node.js:

1. Crie o banco MongoDB no painel (nome e memória, a partir de 1024 MB) e copie a URL de conexão completa que ele entrega. Ela aparece só uma vez, na criação; se você a perder, redefina a senha para vê-la de novo.
2. Baixe o certificado. O TLS é obrigatório e o cliente também apresenta o certificado: passe tls: true, tlsCAFile com a CA baixada e tlsCertificateKeyFile com o .pem nas opções do MongoClient.
3. Defina MONGODB_URI como variável de ambiente da aplicação, no painel, na API, na CLI ou no VS Code. A mudança vale no próximo restart, sem rebuild.
4. Faça o deploy do código com o mesmo MongoClient deste guia, acrescentando essas opções de TLS. O arquivo squarecloud.app é opcional: o painel o gera no deploy, ou você pode escrevê-lo na raiz do projeto.

O banco também aceita conexões de fora, então você pode testar a mesma URL e o mesmo certificado na sua máquina. Você tira snapshots manuais quando quiser, e todo plano com bancos inclui também um snapshot automático diário. Dá para restaurar um snapshot no mesmo banco, em outro do mesmo motor ou num banco novo. Mais detalhes em hospedagem de MongoDB.