MongoDB Academy · Aula

Conectando-se com o driver oficial do Node.js

Você criará um MongoClient, gerenciará o conjunto de conexões e executará operações CRUD em uma aplicação Node.js usando o driver nativo.

Aula 1 de 413 etapas

Conectando-se com o driver oficial do Node.js é uma aula grátis de MongoDB Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de MongoDB Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de MongoDB Academy inclui 4 aulas no total.

O driver oficial do MongoDB para Node.js

O driver do MongoDB para Node.js (o pacote npm mongodb) é a biblioteca oficial de baixo nível para conectar aplicações Node.js ao MongoDB. Ele fornece acesso direto a todos os recursos do MongoDB sem uma camada de abstração, o que o torna ideal para código crítico em termos de desempenho, microsserviços e scripts. O driver é mantido pela MongoDB, Inc. e acompanha de perto os novos recursos do servidor MongoDB.

// Install the driver
// npm install mongodb

// Or with yarn:
// yarn add mongodb

// The driver exports MongoClient as its main entry point
const { MongoClient, ObjectId, ServerApiVersion } = require('mongodb');
// or ES module:
// import { MongoClient, ObjectId } from 'mongodb';

Criando um MongoClient

A classe MongoClient é o ponto de entrada para todas as interações. Instancie-a com sua string de conexão (URI) e um objeto de opções opcional. A string de conexão codifica o host, a porta, as credenciais e os parâmetros de conexão. Para o MongoDB Atlas, copie a string de conexão da interface do Atlas e substitua a senha de exemplo. Crie um MongoClient por aplicação e reutilize-o — não crie um novo a cada solicitação.

const { MongoClient, ServerApiVersion } = require('mongodb');

const uri = process.env.MONGODB_URI;
// URI format: mongodb+srv://<user>:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true

const client = new MongoClient(uri, {
  serverApi: {
    version: ServerApiVersion.v1,
    strict: true,
    deprecationErrors: true
  }
});

// client is not yet connected — connecting happens lazily or via connect()

Conectando ao MongoDB

Chame client.connect() para estabelecer um conjunto de conexões. O driver mantém um conjunto de conexões — normalmente de 5 a 100 conexões com o servidor — e as reutiliza entre as operações. Você só precisa chamar connect() uma vez, na inicialização da aplicação. As operações também podem ser chamadas diretamente, sem um connect() explícito — o driver se conecta de forma tardia na primeira operação. Chame client.close() quando a aplicação for encerrada.

async function main() {
  try {
    await client.connect();
    console.log('Connected to MongoDB');

    // Get database reference
    const db = client.db('myDatabase');
    
    // Ping the server to verify connection
    await db.command({ ping: 1 });
    console.log('Ping successful');

    // Run your application logic here...
  } finally {
    // Always close when done
    await client.close();
  }
}

main().catch(console.error);

Padrão singleton para servidores Web

Em um servidor Web (Express, Fastify, NestJS), o MongoClient deve ser um singleton no nível do módulo, criado uma vez na inicialização e compartilhado por todos os manipuladores de solicitações. Criar um novo MongoClient por solicitação esgotaria as conexões disponíveis e degradaria gravemente o desempenho. O padrão comum é conectar-se na função de inicialização do servidor e exportar a referência do cliente ou do banco de dados.

// db.js — module-level singleton
const { MongoClient } = require('mongodb');

let client;
let db;

async function connectToDatabase() {
  if (db) return db; // return existing connection
  client = new MongoClient(process.env.MONGODB_URI);
  await client.connect();
  db = client.db(process.env.DB_NAME || 'myapp');
  return db;
}

module.exports = { connectToDatabase };

// In your Express app:
// const { connectToDatabase } = require('./db');
// const db = await connectToDatabase();
// app.locals.db = db;

Obtendo referências de coleções

Acesse uma coleção chamando db.collection('collectionName'). Isso retorna um objeto Collection sem fazer nenhuma chamada de rede — é apenas uma referência. Você pode obter referências de coleções na inicialização e armazená-las como variáveis no nível do módulo, ou obtê-las diretamente dentro de cada função. As referências de coleções são leves e podem ser reutilizadas com segurança entre as solicitações.

const db = client.db('ecommerce');

// Get collection references
const usersCollection = db.collection('users');
const ordersCollection = db.collection('orders');
const productsCollection = db.collection('products');

// TypeScript: provide a document type for type safety
// const users = db.collection<UserDocument>('users');

// Collections can also be retrieved inline:
async function getUser(id) {
  return client.db('ecommerce').collection('users').findOne({ _id: id });
}

Operações CRUD: inserção

Insira documentos usando insertOne() ou insertMany(). O driver gera automaticamente um _id se ele não for fornecido e retorna os identificadores inseridos. A propriedade insertedId do objeto de resultado (para insertOne) ou o mapa insertedIds (para insertMany) permite acompanhar o que foi criado. As duas operações aceitam um objeto options, no qual você pode especificar writeConcern.

const db = client.db('shop');
const products = db.collection('products');

// Insert one document
const insertResult = await products.insertOne({
  name: 'Mechanical Keyboard',
  price: 149.99,
  category: 'Electronics',
  stock: 50
});
console.log('Inserted ID:', insertResult.insertedId);

// Insert multiple documents
const bulkResult = await products.insertMany([
  { name: 'Mouse Pad', price: 19.99, category: 'Accessories' },
  { name: 'USB Hub', price: 39.99, category: 'Electronics' }
]);
console.log('Inserted count:', bulkResult.insertedCount);

Operações CRUD: leitura

Use findOne(filter) para recuperar um único documento ou find(filter) para obter um cursor sobre todos os documentos correspondentes. Converta um cursor em uma matriz com .toArray() para conjuntos pequenos de resultados, ou percorra-o com for await...of para conjuntos grandes. Ambos os métodos aceitam um segundo argumento de opções para projection, sort, skip, limit e outros modificadores de consulta.

const users = db.collection('users');

// Find a single user by email
const user = await users.findOne(
  { email: 'alice@example.com' },
  { projection: { password: 0 } }  // exclude sensitive fields
);

// Find multiple documents with options
const activeUsers = await users.find(
  { active: true, role: 'admin' },
  {
    projection: { name: 1, email: 1 },
    sort: { createdAt: -1 },
    limit: 50
  }
).toArray();

// Iterate large results without loading all into memory
const cursor = users.find({ active: true });
for await (const user of cursor) {
  await processUser(user);
}

Operações CRUD: atualização

Atualize documentos com updateOne(), updateMany() ou findOneAndUpdate(). O filtro seleciona quais documentos serão atualizados, e o documento de atualização especifica as alterações usando operadores como $set, $inc e $push. updateOne() e updateMany() retornam um resultado com matchedCount e modifiedCount. Use upsert: true para criar o documento caso ele não exista.

const orders = db.collection('orders');

// Update one order's status
const updateResult = await orders.updateOne(
  { _id: orderId },
  { $set: { status: 'shipped', shippedAt: new Date() } }
);
console.log('Modified:', updateResult.modifiedCount);

// Atomic: find, update, and return the updated document
const updatedOrder = await orders.findOneAndUpdate(
  { _id: orderId },
  { $set: { status: 'delivered' }, $push: { statusHistory: { status: 'delivered', at: new Date() } } },
  { returnDocument: 'after' }  // return the document AFTER update
);

Operações CRUD: exclusão

Exclua documentos usando deleteOne() ou deleteMany(). O filtro determina quais documentos serão removidos. O resultado contém deletedCount. Por segurança em produção, sempre teste primeiro o filtro com um find antes de executar deleteMany — excluir acidentalmente todos os documentos de uma coleção é um erro comum e catastrófico. Considere exclusões lógicas (definindo um campo deletedAt) em vez da exclusão física para manter trilhas de auditoria.

const sessions = db.collection('sessions');

// Delete one session
const deleteResult = await sessions.deleteOne({ _id: sessionId });
console.log('Deleted:', deleteResult.deletedCount);

// Delete all expired sessions — test filter first!
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

// 1. Test: how many would be deleted?
const count = await sessions.countDocuments({ expiresAt: { $lt: thirtyDaysAgo } });
console.log('Would delete:', count);

// 2. Only delete after confirming the count looks right
if (count < 10000) { // sanity check
  await sessions.deleteMany({ expiresAt: { $lt: thirtyDaysAgo } });
}

Executando pipelines de agregação

Execute pipelines de agregação usando collection.aggregate(pipeline). Isso retorna um cursor que você pode converter em uma matriz ou percorrer. Os estágios do pipeline são fornecidos como uma matriz de objetos. O driver envia o pipeline ao mecanismo de agregação do MongoDB e transmite os resultados de volta. Para conjuntos de resultados muito grandes, percorra o cursor diretamente em vez de chamar .toArray(), para evitar carregar tudo na memória de uma só vez.

const orders = db.collection('orders');

// Revenue report by category
const report = await orders.aggregate([
  { $match: { status: 'completed', createdAt: { $gte: new Date('2024-01-01') } } },
  { $group: { _id: '$category', total: { $sum: '$amount' }, count: { $sum: 1 } } },
  { $sort: { total: -1 } }
]).toArray();

console.log('Revenue report:', report);

// For large aggregations, iterate the cursor:
const cursor = orders.aggregate([...largeComplexPipeline]);
for await (const doc of cursor) {
  await writeToReport(doc);
}

Configurando o conjunto de conexões

O MongoClient mantém um conjunto de conexões que gerencia automaticamente as conexões com o servidor. Opções principais: maxPoolSize (número máximo de conexões, padrão de 5 por host), minPoolSize (quantidade mínima mantida ativa), connectTimeoutMS e socketTimeoutMS. Para APIs com tráfego intenso, aumente maxPoolSize, mas equilibre esse valor com a sobrecarga de memória por conexão do MongoDB. Monitore a utilização do conjunto usando as métricas do Atlas.

const client = new MongoClient(uri, {
  maxPoolSize: 20,           // max 20 connections to the server
  minPoolSize: 5,            // keep at least 5 connections warm
  connectTimeoutMS: 5000,   // fail fast if can't connect in 5s
  socketTimeoutMS: 45000,   // idle socket timeout
  serverSelectionTimeoutMS: 5000  // how long to wait to find an available server
});

Verificação rápida

Teste sua compreensão dos conceitos de MongoDB e bancos de dados NoSQL apresentados nesta lição.

Resumo da lição

Nesta lição, você aprendeu que: deve criar um MongoClient na inicialização e reutilizá-lo como singleton — nunca crie um por solicitação; deve obter referências de bancos de dados e coleções com client.db() e db.collection() — elas são referências de objetos leves; e deve usar insertOne/insertMany, findOne/find, updateOne/updateMany/findOneAndUpdate e deleteOne/deleteMany para operações CRUD. A seguir, exploraremos os esquemas, modelos e virtuais do Mongoose como uma abstração de nível mais alto sobre o driver nativo.

Grátis para começar

Aprenda JavaScript com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos
30
Aulas
120

Perguntas Frequentes

A aula “Conectando-se com o driver oficial do Node.js” é grátis?

Sim — o texto completo de “Conectando-se com o driver oficial do Node.js” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de MongoDB Academy, atualize para CoddyKit PRO. O curso de MongoDB Academy inclui 4 aulas no total.

O que vou aprender em “Conectando-se com o driver oficial do Node.js”?

Você criará um MongoClient, gerenciará o conjunto de conexões e executará operações CRUD em uma aplicação Node.js usando o driver nativo. Você pratica MongoDB Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar MongoDB Academy?

Nenhuma experiência prévia é necessária. MongoDB Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Conectando-se com o driver oficial do Node.js”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de MongoDB Academy?

Sim. Cada aula de MongoDB Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Conectando-se com o driver oficial do Node.js
  2. Esquemas, modelos e virtuais do Mongoose
  3. Consultas do Mongoose, encadeamento e documentos enxutos
  4. Middleware do Mongoose: ganchos anteriores e posteriores
← Voltar para MongoDB Academy