Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

How Mongoose Works: Buffering, Casting and Queries

Understand what happens inside Mongoose: command buffering before connect, query objects versus promises, casting, lean results and the document lifecycle.

Most Mongoose surprises come from four internal behaviors: commands are buffered until the connection is ready, queries are lazy objects until you execute them, values are cast to schema types, and results are hydrated into documents. Knowing these four makes the library predictable. This lesson explains each one and uses stand-ins that you can run to see them in action.

Buffering: why a query waits

If you call a model method before the connection finishes opening, Mongoose does not fail. It queues the command and runs it as soon as the connection becomes ready:

JavaScript
mongoose.connect(uri);          // not awaited, still connecting
const users = await User.find(); // waits in a buffer, then runs

That is convenient in small scripts, but it hides problems. If the connection never succeeds, the buffered command fails after bufferTimeoutMS (default 10 seconds) with an error like "Operation users.find() buffering timed out after 10000ms". That message nearly always means "your connection is not established", not "the query is slow".

Two good habits follow:

  1. await mongoose.connect(...) before starting your server or running code that uses models.
  2. Know the settings: mongoose.set('bufferCommands', false) turns buffering off so calls fail immediately when disconnected, and bufferTimeoutMS changes the wait.
Node.js A command buffer (stand-in, not Mongoose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first call is buffered and released when the connection is ready; the second runs straight away.

Queries are lazy

Methods like find(), findOne() and updateOne() return a Query object, not a promise and not results. Nothing is sent to the database until the query is executed, which happens when you await it, call .then(), or call .exec().

JavaScript
const query = User.find({ active: true });   // nothing sent yet
query.sort({ name: 1 }).limit(10);            // still nothing sent
const users = await query;                    // now it runs

This is what allows chaining, the topic of Query operators and chaining. A query is thenable: it has a then method, so await works, but it is not a real Promise. If you need a real promise (for stack traces or Promise.all typing), call .exec():

JavaScript
const users = await User.find({ active: true }).exec();

A consequence worth remembering: executing the same query twice runs it twice, and passing a callback together with await can run it twice by accident. Await once.

Node.js A lazy query builder (stand-in, not Mongoose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Casting

Before sending a query or saving a document, Mongoose casts values to the schema's type. For a field age: Number, the string "42" becomes 42, and "abc" fails with a CastError. Casting happens in filters too:

JavaScript
// _id is an ObjectId in the schema; the string is cast for you
const user = await User.findOne({ _id: '6733a1f2c0ffee0012345678' });

Without casting you would compare a string with an ObjectId and find nothing. If you want to see how the filter was cast, query.getFilter() returns it. Casting is skipped for fields not in the schema (when strictQuery is on, which is the default for new versions, such fields are removed from the filter).

Hydration: documents versus lean objects

A normal query returns hydrated results: full Mongoose documents with change tracking, save(), virtuals, getters and validation. Building these costs memory and CPU. When you only need to read data and send it somewhere, ask for plain objects with .lean():

JavaScript
const docs = await User.find();           // Mongoose documents
const plain = await User.find().lean();   // plain JavaScript objects

Lean results are typically several times faster and lighter for large result sets, but they have no save(), no virtuals and no getters. Pagination and lean queries returns to this trade-off.

The life of a save

flowchart TD
  A["new Model(data)"] --> B["Apply defaults, cast values,<br/>drop unknown fields"]
  B --> C["doc.save()"]
  C --> D["Run pre-validate and validators"]
  D -->|errors| E["Reject with ValidationError"]
  D -->|ok| F["Run pre-save hooks"]
  F --> G["Send insert or update to MongoDB"]
  G --> H["Run post-save hooks"]
  H --> I["Promise resolves with the document"]

Validation and hooks run in your process before and after the single database round trip.

For an existing document, Mongoose tracks which paths changed and sends only those as $set operations, not the whole document. That is why you should modify a document with normal assignments and then call save().

Models are tied to a connection

mongoose.connect() opens the default connection, and mongoose.model() attaches models to it. If you need two databases, create separate connections with mongoose.createConnection(uri) and register models on each (conn.model('User', schema)). Most applications never need that.

Common mistakes in this area

  • Assuming a query ran because you built it. Without await or exec() it never executes.
  • Reading a "buffering timed out" error as a slow query.
  • Awaiting a query twice, executing it twice.
  • Using .lean() and then expecting doc.save() or virtuals to exist.
  • Mutating a lean object and expecting the database to change.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a 'buffering timed out' error usually mean?

    Commands wait in a buffer until the connection is ready. If it never becomes ready, they fail after bufferTimeoutMS.
  2. 2. What does User.find({ active: true }) return?

    find() builds a Query. The database is contacted only when the query is executed.
  3. 3. What does .lean() change about the results?

    Lean skips hydration, so you get faster, lighter plain objects with no save(), virtuals or getters.
  4. 4. How does Mongoose update an existing document on save()?

    Mongoose tracks modified paths and sends them as a $set update.

Summary

  • Commands are buffered until the connection is open; await connect() and treat buffering timeouts as connection problems.
  • Queries are lazy objects that run when awaited or when exec() is called, and each execution is a separate database call.
  • Values are cast to schema types in documents and filters.
  • Results are hydrated documents; .lean() returns plain objects for speed.
  • A save runs validation and hooks in Node, then makes one write, sending only changed paths.

Next: Schema types