🦤 Mongoose Schemas & Models

Why Mongoose?

MongoDB is schema-less by design: one document in a collection can have ten fields and the next can have three, and the database won't complain. That flexibility is great for prototyping and terrible for a team that expects every user to have an email. Mongoose is an ODM — an Object Data Modeling library — that lets you declare the structure you want and then enforces it for you.

Think of Mongoose as a translator and a bouncer standing between your Node.js code and the database. As a translator, it converts your plain JavaScript objects into MongoDB documents and back, casting types along the way. As a bouncer, it checks every document against the rules you set before it lets anything into the collection.

Mongoose vs. the native driver

You can talk to MongoDB with the official driver directly. Mongoose builds on top of it and gives you structure, validation, and convenience for free.

Installing & Connecting

Install Mongoose from npm:

npm install mongoose

Then connect. In modern Mongoose the connection options object is optional — a clean connection string is usually all you need. Keep the URI in an environment variable so credentials never live in your source code.

// db.js — a small, reusable connection module
import mongoose from 'mongoose';
import 'dotenv/config';

export async function connectDB() {
  try {
    await mongoose.connect(process.env.MONGODB_URI);
    console.log('✅ MongoDB connected');
  } catch (err) {
    console.error('❌ MongoDB connection error:', err.message);
    process.exit(1); // fail fast — the app is useless without its database
  }
}

// Surface connection lifecycle events (helpful in production):
mongoose.connection.on('disconnected', () => console.warn('MongoDB disconnected'));
mongoose.connection.on('reconnected', () => console.log('MongoDB reconnected'));

// Close the connection cleanly on shutdown:
process.on('SIGINT', async () => {
  await mongoose.connection.close();
  console.log('MongoDB connection closed — exiting');
  process.exit(0);
});

Defining a Schema

A schema is a blueprint. It describes what fields a document has, what type each field is, and what rules those fields must obey. A schema by itself doesn't touch the database — it's just a description.

import mongoose from 'mongoose';
const { Schema } = mongoose;

const userSchema = new Schema({
  firstName: { type: String, required: true, trim: true },
  lastName:  { type: String, required: true, trim: true },
  email: {
    type: String,
    required: true,
    unique: true,      // builds a unique INDEX (see the caution below)
    lowercase: true,   // normalises "ADA@X.com" → "ada@x.com" on save
    trim: true
  },
  age:      { type: Number, min: 18, max: 120 },
  isActive: { type: Boolean, default: true },
  birthDate: Date,                    // shorthand: a plain type with no options

  // A nested object:
  address: {
    street: String,
    city:   String,
    country: { type: String, default: 'USA' }
  },

  // An array of strings, and an array of sub-objects:
  hobbies: [String],
  education: [{ school: String, degree: String, year: Number }]
}, {
  timestamps: true   // auto-adds createdAt & updatedAt — use this, don't hand-roll it
});

SchemaTypes & Options

Every field has a SchemaType that tells Mongoose how to cast and store the value. These are the ones you'll reach for constantly:

Common field options

The object after type configures the field. These appear everywhere:

const productSchema = new Schema({
  name:  { type: String, required: true, trim: true },
  slug:  { type: String, lowercase: true },
  price: { type: Number, required: true, min: 0, default: 0 },
  sku:   { type: String, immutable: true },          // can't change after creation
  role:  { type: String, enum: ['draft', 'live'], default: 'draft' },
  notes: { type: String, select: false }             // excluded from queries by default
});

Here's how those pieces fit together end to end: a schema definition is a collection of fields, each field is a SchemaType plus options, and the whole thing is what a model will enforce.

From Schema to Model

A schema is inert. To actually create, find, and update documents you compile the schema into a model with mongoose.model(). The model is a constructor bound to a MongoDB collection, and every document you make is an instance of that model.

// The model name 'User' → Mongoose pluralises & lowercases it to
// the collection 'users' automatically.
const User = mongoose.model('User', userSchema);

// One model, three concepts:
//   Schema   → the blueprint (userSchema)
//   Model    → the factory + query interface (User)
//   Document → a single instance (const u = new User({...}))

This three-step relationship is the mental model to lock in for the entire week:

CRUD with a Model

Once you have a model, the four basic operations — Create, Read, Update, Delete — are all one-liners. Every method returns a promise, so await it.

Create

// Option A: build then save (gives you the instance first)
const user = new User({ firstName: 'Ada', lastName: 'Lovelace', email: 'ada@x.com', age: 36 });
await user.save();

// Option B: create in one call (validates & saves)
const grace = await User.create({
  firstName: 'Grace', lastName: 'Hopper', email: 'grace@x.com', age: 40
});

Read

await User.find();                          // every user (an array)
await User.find({ isActive: true });        // filtered
await User.findById(id);                     // by _id, or null
await User.findOne({ email: 'ada@x.com' });  // first match, or null

// Chainable query building:
const adults = await User.find({ age: { $gte: 18 } })
  .select('firstName email')   // only these fields
  .sort({ firstName: 1 })      // A→Z
  .limit(10)
  .lean();                     // plain objects, faster (see best practices)

Update

// Find, mutate, save — runs full document validation & hooks:
const u = await User.findById(id);
u.age = 41;
await u.save();

// Or update in place. Pass { new: true } to return the UPDATED doc,
// and { runValidators: true } to apply schema validation to the update.
const updated = await User.findByIdAndUpdate(
  id,
  { age: 41 },
  { new: true, runValidators: true }
);

Delete

await User.findByIdAndDelete(id);
await User.deleteOne({ email: 'ada@x.com' });
await User.deleteMany({ isActive: false });

{
  _id: ObjectId("6650f1..."),
  firstName: "Grace",
  lastName: "Hopper",
  email: "grace@x.com",
  age: 40,
  isActive: true,          // filled from the schema default
  hobbies: [],
  createdAt: 2026-07-31T...,  // added by timestamps:true
  updatedAt: 2026-07-31T...,
  __v: 0
}

Methods, Statics & Virtuals

Because a model bundles behaviour with data, you can attach reusable logic right to the schema. There are three flavours, and beginners mix them up constantly — so anchor them by who calls them.

Instance methods — called on one document

userSchema.methods.getFullName = function () {
  return `${this.firstName} ${this.lastName}`; // 'this' = the document
};

const u = await User.findById(id);
u.getFullName();  // "Ada Lovelace"

Statics — called on the model itself

userSchema.statics.findByEmail = function (email) {
  return this.findOne({ email }); // 'this' = the model
};

await User.findByEmail('ada@x.com');

Virtuals — computed properties that aren't stored

A virtual is a field that is calculated on the fly and never written to MongoDB. Perfect for derived values like a full name.

userSchema.virtual('fullName').get(function () {
  return `${this.firstName} ${this.lastName}`;
});

// Virtuals are hidden from JSON by default — opt them in on the schema:
const userSchema = new Schema({ /* ... */ }, {
  timestamps: true,
  toJSON:   { virtuals: true },
  toObject: { virtuals: true }
});

Practice & Quiz

import mongoose from 'mongoose';
const { Schema } = mongoose;

const bookSchema = new Schema({
  title:   { type: String, required: true, trim: true },
  author:  { type: String, required: true },
  pages:   { type: Number, min: 1 },
  genre:   { type: String, enum: ['fiction', 'nonfiction', 'poetry', 'reference'] },
  inStock: { type: Boolean, default: true }
}, { timestamps: true });

const Book = mongoose.model('Book', bookSchema);
export default Book;

// Create
const book = await Book.create({
  title: 'Structure and Interpretation of Computer Programs',
  author: 'Abelson & Sussman', pages: 657, genre: 'reference'
});

// Read
const found = await Book.findById(book._id);
console.log(found.title);

// Update (return the updated doc, run validators)
const updated = await Book.findByIdAndUpdate(
  book._id, { pages: 660 }, { new: true, runValidators: true }
);
console.log(updated.pages); // 660

// Delete
await Book.findByIdAndDelete(book._id);

Best Practices & Pitfalls

✅ Do

• Keep one model per file and import it wherever needed
• Use { timestamps: true } instead of hand-managing createdAt/updatedAt
• Pass { new: true, runValidators: true } to findByIdAndUpdate
• Use .lean() for read-only queries that don't need document methods
• Store your connection string in an environment variable

❌ Don't

• Rely on unique: true to reject duplicates gracefully — catch E11000 yourself
• Compile the same model name twice (causes OverwriteModelError)
• Use arrow functions for methods/virtuals — they break this
• Forget that findByIdAndUpdate skips validators unless you ask for them

doc.meta = doc.meta || {};
doc.meta.views = 10;
doc.markModified('meta');  // required — Mongoose can't detect changes on Mixed
await doc.save();

Summary

📚 Additional Resources

• Mongoose — Schemas guide
• Mongoose — SchemaTypes reference
• Mongoose — Models
• Mongoose — Queries

🚀 What's Next?

Your schema can describe shape, but real apps need to reject bad data and run logic at key moments. Next up: Validation & Middleware — built-in and custom validators, and the pre/post hooks that fire around save, find, and update.