Tutorial: Introdução ao Mongoose

Verifique os pré-requisitos

Antes de iniciar este tutorial, verifique se você tem os seguintes componentes preparados:

• Uma conta do MongoDB Atlas com um cluster configurado. Para visualizar instruções, consulte o guia Introdução ao Atlas.

• Node.js v16.20.1 ou mais tarde.

Configure seu ambiente

Este tutorial usa nodemon para executar o código localmente. Execute os seguintes comandos no seu terminal para inicializar seu projeto e instalar as dependências necessárias:

mkdir mongodb-mongoose
cd mongodb-mongoose
npm init -y
npm i mongoose
npm i -D nodemon

Abra seu projeto no editor de código de sua preferência. Este tutorial usa módulos ES em vez de CommonJS. Você deve adicionar o tipo module para usar os módulos ES. Vá para o arquivo package.json e adicione o seguinte código:

...
"scripts": {
  "dev": "nodemon index.js"
},
"type": "module",
...

Inicie seu aplicação com nodemon executando o seguinte comando:

npm run dev

Conecte-se ao MongoDB

No nível raiz do seu projeto, crie um arquivo denominado index.js e adicione o seguinte código ao topo do arquivo:

import mongoose from 'mongoose';
mongoose.connect("<connection string>")

Substitua o placeholder <connection string> pela string de conexão do MongoDB Atlas . Para mais informações sobre como localizar sua string de conexão, consulte o tutorial Connect to Your Cluster na documentação do Atlas.

Criar um esquema e um modelo

Antes de começar a adicionar e atualizar dados no MongoDB, você deve criar um esquema e um modelo.

Com o Mongoose, você cria um arquivo de modelo de esquema para cada esquema necessário. Primeiro, crie uma pasta chamada model para colocar todos os seus arquivos de esquema e, em seguida, crie seu primeiro arquivo de esquema chamado Blog.js. Abra este arquivo e adicione o seguinte código:

import mongoose from 'mongoose';
const { Schema, model } = mongoose;
const blogSchema = new Schema({
  title: String,
  slug: String,
  published: Boolean,
  author: String,
  content: String,
  tags: [String],
  comments: [{
    user: String,
    content: String,
    votes: Number
  }]
}, {
  timestamps: true
});
const Blog = model('Blog', blogSchema);
export default Blog;

Esse esquema habilita uma opção timestamps, que adiciona campos createdAt e updatedAt gerenciados por mongoose ao esquema que são atualizados automaticamente. Para obter mais informações, consulte a página Registros de data e hora na documentação do Mongoose.

Realizar operações CRUD

Agora você tem seu primeiro modelo e esquema configurados e pode começar a inserir dados no banco de dados. As seções a seguir mostram como realizar operações CRUD usando o Mongoose.

import Blog from './model/Blog.js';

// Creates a new blog post and inserts it into database
const article = await Blog.create({
  title: 'Awesome Post!',
  slug: 'awesome-post',
  published: true,
  content: 'This is the best post ever',
  tags: ['featured', 'announcement'],
});
console.log('Created article:', article);

// Updates the title of the article
article.title = "The Most Awesomest Post!!";
await article.save();
console.log('Updated Article:', article);

Updated Article: {
   title: 'The Most Awesomest Post!!',
   slug: 'awesome-post',
   published: true,
   content: 'This is the best post ever',
   tags: [ 'featured', 'announcement' ],
   _id: new ObjectId('...'),
   comments: [],
   __v: 0
}

// Finds the article by its ID. Replace <object id> with the objectId of the article.
const articleFound = await Blog.findById("<object id>").exec();
console.log('Found Article by ID:', articleFound);

Found Article by ID: {
   _id: new ObjectId('68261c9dae39e390341c367c'),
   title: 'The Most Awesomest Post!!',
   slug: 'awesome-post',
   published: true,
   content: 'This is the best post ever',
   tags: [ 'featured', 'announcement' ],
   comments: [],
   __v: 0
}

// Finds the article by its ID and projects only the title, slug, and content fields.
// Replace <object id> with the objectId of the article.
const articleProject = await Blog.findById("<object id>", "title slug content").exec();
console.log('Projected Article:', articleProject);

Projected Article: {
   _id: new ObjectId('...'),
   title: 'The Most Awesomest Post!!',
   slug: 'awesome-post',
   content: 'This is the best post ever'
}

// Deletes one article with the slug "awesome-post".
const blogOne = await Blog.deleteOne({ slug: "awesome-post" });
console.log('Deleted One Blog:', blogOne);

Deleted One Blog: { acknowledged: true, deletedCount: 1 }

// Deletes all articles with the slug "awesome-post".
const blogMany = await Blog.deleteMany({ slug: "awesome-post" });
console.log('Deleted Many Blogs:', blogMany);

Deleted Many Blogs: { acknowledged: true, deletedCount: 4 }

Validar seus dados

Os artigos inseridos nas etapas anteriores não contêm os campos author, dates ou comments, embora esses campos estejam incluídos no esquema. Isso ocorre porque, embora você tenha definido a estrutura do documento, não definiu quais campos são obrigatórios. Qualquer campo que não seja definido como obrigatório pode ser omitido.

No Mongoose, quando você inclui a validação em um campo, você deve passar um objeto como seu valor.

Você pode usar vários métodos de validação com o Mongoose. Por exemplo, você pode definir required como true em quaisquer campos que queira exigir. Você também pode validar o tipo e a formatação. No código a seguir, o campo slug é definido como string com minLength de 4. Isso significa que fornecer um slug com menos de 4 caracteres resultará em um ValidationError.

Para adicionar validação de dados e definir esses requisitos, atualize o esquema em Blog.js conforme mostrado no exemplo a seguir :

const blogSchema = new Schema({
  title:  {
    type: String,
    required: true,
  },
  slug:  {
    type: String,
    required: true,
    minLength: 4,
  },
  published: {
    type: Boolean,
    default: false,
  },
  author: {
    type: String,
    required: true,
  },
  content: String,
  tags: [String],
  comments: [{
    user: String,
    content: String,
    votes: Number
  }]
}, {
  timestamps: true
});

Depois de adicionar essa validação, seu aplicação falhará. Adicione um campo author à chamada create() em seu arquivo index.js para atender ao novo requisito de validação:

// Creates a new blog post and inserts it into database
const article = await Blog.create({
  title: 'Awesome Post!',
  slug: 'awesome-post',
  published: true,
  author: 'A.B. Cee',
  content: 'This is the best post ever',
  tags: ['featured', 'announcement'],
});

Para obter mais informações, consulte a página Validação na documentação do Mongoose.

Introduzir vários esquemas

Em seguida, você pode adicionar mais complexidade ao seu campo author criando um outro esquema e aninhando-o no esquema de blog.

Na pasta model, crie um novo arquivo denominado User.js. Adicione o seguinte código a este arquivo:

import mongoose from 'mongoose';
const {Schema, model} = mongoose;
const userSchema = new Schema({
  name: {
    type: String,
    required: true,
  },
  email: {
    type: String,
    minLength: 10,
    required: true,
    lowercase: true
  },
});
const User = model('User', userSchema);
export default User;

Para utilizar seu novo modelo de usuário para definir o campo author no esquema do blog, atualize o arquivo Blog.js com as seguintes alterações:

• Adicione SchemaTypes à lista de propriedades extraídas da biblioteca Mongoose.

• Altere o campo author type para SchemaTypes.ObjectId e adicione uma referência (ref) ao modelo 'User'.

O seguinte código mostra essas atualizações:

const { Schema, SchemaTypes, model } = mongoose;
... // Inside Schema block:
   author: {
      type: SchemaTypes.ObjectId,
      ref: 'User',
      required: true,
   },
...

Você pode reutilizar o mesmo modelo User para o campo comment.user alterando a definição blogSchema:

... // Inside Schema block:
   comments: [{
      user: {
         type: SchemaTypes.ObjectId,
         ref: 'User',
         required: true,
      },
...

Para usar o novo modelo de usuário em seu aplicação, acesse o arquivo index.js. Adicione o seguinte código ao topo do arquivo para importar o modelo de usuário:

import User from './model/User.js';

Como você adicionou a validação de campo ao esquema de blog, o código anterior para inserir, atualizar e excluir blogs e especificar campos para projeto, não passará na validação e o aplicação apresentará erro.

Crie um novo usuário adicionando a seguinte chamada create():

// Create a new user
const user = await User.create({
  name: 'Jess Garica',
  email: 'jgarcia@email.com',
});

Atualize a chamada create() existente com o seguinte código para criar um novo artigo que use o novo usuário como autor, conforme mostrado no código a seguir:

// Creates a new blog post that references the user as the author
const articleAuthor = await Blog.create({
  title: 'Awesome Post!',
  slug: 'Awesome-Post',
  author: user._id,
  content: 'This is the best post ever',
  tags: ['featured', 'announcement'],
});
console.log('Article with Author:', articleAuthor);

Article with Author: {
   title: 'Awesome Post!',
   slug: 'awesome-post',
   published: false,
   author: new ObjectId('...'),
   content: 'This is the best post ever',
   tags: [ 'featured', 'announcement' ],
   _id: new ObjectId('...'),
   createdAt: 2025-05-15T18:05:23.780Z,
   comments: [],
   __v: 0
}

O código anterior adiciona uma coleção users com a coleção blogs no banco de dados MongoDB . Este código adiciona o campo author exigido e define seu valor para user._id.

Para adicionar os valores dos campos name e email ao campo author do artigo, você pode anexar o método Mongoose populate() à sua query do Blog. O método populate() executará uma segunda query para o documento do usuário referenciado por user._id.

Adicione o seguinte código ao index.js para preencher estes dados:

// Populates the author field with user data
const articlePopulate = await Blog.findOne({ title: "Awesome Post!" }).populate("author");
console.log('Article Populated:', articlePopulate);

Article Populated: {
   _id: new ObjectId('...'),
   title: 'Awesome Post!',
   slug: 'awesome-post',
   published: false,
   author: {
      _id: new ObjectId('...'),
      name: 'Jess Garica',
      email: 'jgarcia@email.com',
      __v: 0
   },
   content: 'This is the best post ever',
   tags: [ 'featured', 'announcement' ],
   createdAt: 2025-05-15T18:04:28.590Z,
   comments: [],
   __v: 0
}

Para obter mais informações, consulte o Document.populate() página da documentação da API Mongoose.

Adicionar middleware

No Mongoose, middleware são funções executadas antes ou durante a execução de funções assíncronas no nível do esquema.

Um exemplo de middleware é uma função que valida o campo email de uma instância User antes de salvar ou atualizar.

Este exemplo utiliza o pacote validator. Você pode instalar o pacote validator executando o seguinte comando:

npm install validator

Para adicionar essa função de middleware, adicione o seguinte código à declaração userSchema em seu arquivo User.js:

import validator from 'validator';

userSchema.pre('save', function (next) {
  const user = this;
  // Normalize email
  if (user.email) {
    user.email = user.email.trim().toLowerCase();
  }
  // Validate email format
  if (!validator.isEmail(user.email)) {
    return next(new Error('Invalid email format'));
  }
  next();
});

Para ver o efeito dessa função, modifique o campo user.email em seu arquivo index.js para torná-lo um endereço de e-mail inválido:

const user = await User.create({
  name: 'Jess Garica',
  email: 'jgarciaemail.com',
});

Error: Invalid email format

Se você corrigir o endereço de e-mail, poderá ver que o erro não será gerado.

Além da função de middleware pre(), o Mongoose também oferece uma função de middleware post(). Para obter mais informações sobre middleware, consulte a página Middleware na documentação do Mongoose.