Mongoose Schemas & Models

Workplace Context

Your team is building a new feature that requires storing and managing user profiles. The data for each user needs to be structured, with specific fields like username, email, and age. To ensure data consistency and prevent errors, you need a way to define this structure and validate any data before it’s saved to the MongoDB database. Mongoose is the tool of choice for this task.

Learning Objectives

By the end of this lesson, you will be able to:

• Explain the purpose of Mongoose as an Object Data Modeling (ODM) library.
• Connect to a MongoDB database using Mongoose.
• Define a Mongoose schema with various data types and validation rules.
• Compile a schema into a model to interact with a database collection.

What is Mongoose?

Mongoose is an Object Data Modeling (ODM) library for MongoDB and Node.js. It acts as a layer between your application and the database. Think of it as an expert translator and a strict project manager combined. It translates your JavaScript objects into the proper format for MongoDB and ensures that the data being saved adheres to the rules you’ve defined.

While the native MongoDB driver is powerful, it can be very low-level. Mongoose provides several key benefits:

• Schema Definition: It allows you to enforce a structure on your documents. While one of MongoDB’s strengths is its flexibility, most applications benefit from having a predictable data shape. For example, a User schema can ensure that every user in your database has a username and an email, preventing bugs caused by missing data.
• Data Validation: It provides built-in validators (e.g., making a field required or ensuring a number is within a certain range). This helps maintain data integrity, so you don’t end up with invalid email addresses or negative prices in your database.
• Easier Abstractions: It provides convenient methods for creating, querying, and updating data that are often simpler and more intuitive than the raw driver commands. It simplifies complex database operations into single function calls.

Essentially, Mongoose lets you describe your data in your code, and it handles the complex communication with MongoDB for you, allowing you to write cleaner and more reliable code.

Connecting to MongoDB with Mongoose

Connecting with Mongoose is similar to using the native driver, but simpler. You use the mongoose.connect() method, passing it your MongoDB connection string.

First, install Mongoose in your project:

npm install mongoose

Then, you can connect like this. Behind the scenes, mongoose.connect() establishes a robust connection to your database. It also manages a connection pool, which is a cache of database connections maintained so that the connections can be reused for future requests. This is far more efficient than opening and closing a connection for every single query.

const mongoose = require('mongoose');
require('dotenv').config();
 
const uri = process.env.MONGO_URI;
 
// Connect to MongoDB and handle the promise
mongoose.connect(uri)
  .then(() => console.log('Successfully connected to MongoDB!'))
  .catch(err => console.error('Connection error', err));

Mongoose’s connect() method returns a promise, so you can use .then() to run code after the connection is successful or .catch() to handle any errors that occur.

Defining a Schema

The cornerstone of Mongoose is the Schema. Think of a schema as an architect’s blueprint for your data. It defines the structure of the documents within a collection, specifying the fields, their data types, and the rules they must follow (validation).

Let’s define a simple schema for a User.

const mongoose = require('mongoose');
const { Schema } = mongoose; // Destructure Schema from mongoose
 
const userSchema = new Schema({
  username: String,
  email: String,
  age: Number,
  isVerified: Boolean
});

Schema Types

Mongoose schemas support several data types to match the BSON types used by MongoDB.

Validation and Schema Options

This is where Mongoose truly shines. You can add rules directly into your schema by using an object for the field definition instead of just the type. This enforces data integrity at the application level.

Let’s create a more robust schema for a User that includes common validation.

const mongoose = require('mongoose');
const { Schema } = mongoose;
 
const userSchema = new Schema({
  username: {
    type: String,
    required: [true, 'Username is required'], // Field must be provided
    unique: true,                           // Must be unique in the collection
    trim: true,                             // Removes whitespace
    minlength: 3,                           // Minimum length
  },
  email: {
    type: String,
    required: [true, 'Email is required'],
    unique: true,
    lowercase: true,                       // Converts email to lowercase
    match: [/.+\@.+\..+/, 'Please enter a valid email address'] // Regex for email format
  },
  age: {
    type: Number,
    min: [18, 'Must be at least 18 years old'], // Minimum value
    max: 120                                  // Maximum value
  },
  role: {
    type: String,
    enum: {
      values: ['user', 'admin'],            // The value must be one of these strings
      message: '{VALUE} is not a supported role'
    },
    default: 'user'                         // If not provided, defaults to 'user'
  },
  createdAt: {
    type: Date,
    default: () => Date.now(),              // Sets the value to the current date/time
    immutable: true                         // Cannot be changed after creation
  }
});

Here is a breakdown of the most common options:

• required: If true, the document cannot be saved without this field. You can also provide a custom error message.
• unique: This is not a validator, but a helper to build a MongoDB unique index. It ensures no two documents in the collection have the same value for this path.
• trim: true: Automatically removes whitespace from the start and end of a string.
• lowercase: true: Automatically converts a string to lowercase.
• min/max (for Numbers) or minlength/maxlength (for Strings): Enforces range constraints.
• enum: For strings, restricts the value to be one of the strings in the provided array.
• match: A regular expression that the string value must match. Great for formats like emails or phone numbers.
• default: Provides a default value if one isn’t given when creating a new document.
• immutable: true: Prevents a field from being updated after the document has been created. Useful for fields like createdAt or an original orderId.

If you try to save a document that violates a validation rule, Mongoose will throw a ValidationError and the document will not be saved.

Creating a Model

A schema is just a blueprint. To actually create, read, update, or delete documents, you need to compile your schema into a Model. If the schema is the blueprint, a Model is the factory that produces documents based on that blueprint. A model is a class that gives you an interface to the database collection.

You create a model using the mongoose.model() method.

mongoose.model('ModelName', schema)

• ModelName: The singular name of the collection your model is for. Mongoose will automatically look for the plural, lowercased version of this name in the database. For example, a User model will use the users collection.
• schema: The schema you want to use.

Let’s compile our userSchema into a User model.

// ... (userSchema definition from above) ...
 
// Compile the schema into a model and export it
const User = mongoose.model('User', userSchema);
module.exports = User;

Now, the User model is a class. You can create new users (new User(...)) and call static methods on it (like User.find(...)) to interact with the users collection in your database. An instance of a model is called a document.

Using Models

Once you have a model, you can use it to interact with the database. The model becomes your primary tool for all CRUD (Create, Read, Update, Delete) operations.

Creating a New Document

You can create a new document by creating an instance of your model and then calling the .save() method on it.

const newUser = new User({
  username: 'jane_doe',
  email: 'jane.doe@example.com',
  age: 28
});
 
// This will validate and save the newUser document to the 'users' collection
await newUser.save();

Querying for Documents

Models provide static helper methods for finding, updating, and deleting documents from the collection.

// Find all users in the collection
const allUsers = await User.find({});
 
// Find one user by their username
const specificUser = await User.findOne({ username: 'jane_doe' });

This is just a small glimpse of what’s possible. In our next lesson, we will dive deep into all the ways you can use models to perform CRUD operations on your data.

Activities

Activity 1: Define a Book Schema

1. In a new project, install mongoose.
2. Create a file to define your Book model (e.g., models/Book.js).
3. In this file, define a bookSchema with the following fields and validations:
   • title: A required string.
   • author: A required string.
   • publicationYear: A number.
   • genres: An array of strings.
   • inStock: A boolean with a default value of true.
4. Compile the schema into a model named Book.
5. Export the Book model.

Activity 2: Connect and Use the Model

1. Create a main application file (e.g., index.js).
2. In this file, set up a connection to your MongoDB Atlas database using mongoose.connect().
3. Import your Book model.
4. After the database connection is successful, log a message to the console confirming that the Book model is ready to be used.
5. Experiment with the model by creating a new book, querying for books you have created, and updating or deleting them.

Activity 3: Large Data Sets

1. Using the read-only sample connection string from lesson one, connect to the database.
2. Choose one of the sample datasets and create a schema for it based on the existing data.
3. Create a model for the dataset.
4. Experiment with the model by querying for documents using the .find() method and various query parameters.

Note: The sample connection string accesses a free-tier cluster, so it will only be available for limited practice when usage is high. You can import sample data into your own database through the MongoDB Atlas UI.

Knowledge Check

Summary

In this lesson, you were introduced to Mongoose, the most popular ODM for Node.js and MongoDB. You learned that Mongoose provides a powerful abstraction layer for data modeling, validation, and interaction. You saw how to connect to a database, how to define a Schema with various data types and validation rules, and how to compile that schema into a Model. This model is your primary tool for all database operations, which you will explore in the next lesson.

References

• Mongoose Docs: Schemas 
• Mongoose Docs: Models 
• Mongoose Docs: Validation 
• Mongoose Docs: Connections 

Additional Resources

• Getting Staarted with MongoDB & Mongoose ODM Library - YouTube 
• How to Write Cleaner Code Using Mongoose Schemas