MongoDB Change Streams: Monitor Real-Time Database Changes

1. Introduction to MongoDB Change Streams

MongoDB Change Streams allow applications to monitor database changes in real time.

Whenever a document is inserted, updated, replaced or deleted, a Change Stream can generate an event that an application can listen to.

For example, imagine an e-commerce website.

When a customer places an order:

1. A new order document is inserted into MongoDB.

2. MongoDB generates a change event.

3. A subscribed application receives the event.

4. The application can send a notification or perform another action.

This helps developers build real-time applications without continuously checking the database manually.

2. What Are MongoDB Change Streams?

MongoDB Change Streams are a feature that allows applications to subscribe to changes in a collection, database or an entire deployment.

They provide notifications for database operations such as:

• Insert

• Update

• Replace

• Delete

Change Streams use MongoDB's aggregation framework and the deployment's oplog to provide change events.

Simple Example

Suppose an orders collection contains customer orders.

When a new order is inserted:

db.orders.insertOne({
    customerName: "Rahul",
    product: "Laptop",
    amount: 55000
})

A Change Stream watching the collection can receive an event describing that insertion.

3. How MongoDB Change Streams Work

The basic process works like this:

1. An application opens a Change Stream.

2. The application waits for database changes.

3. A user or application inserts, updates or deletes a document.

4. MongoDB produces a change event.

5. The Change Stream delivers that event to the subscriber.

6. The application processes the event.

Important: A Change Stream reports changes after they have been committed with majority durability. It is not a notification for an uncommitted write.

4. Requirements for MongoDB Change Streams

Before using Change Streams, understand the deployment requirement.

Change Streams are supported on:

• MongoDB replica sets.

• MongoDB sharded clusters.

They are not supported on a standalone mongod deployment because standalone mode does not have the oplog required for Change Streams.

For local practice, you can configure MongoDB as a single-node replica set.

For example, start MongoDB with a replica set name:

mongod --replSet rs0 --dbpath /data/db

Then connect using mongosh and initialize the replica set:

rs.initiate()

Wait for the replica set to become ready before opening a Change Stream.

On Windows, use the appropriate MongoDB data directory and configure replication.replSetName in your MongoDB configuration file.

5. Create a Database and Collection

Let's create a database named shopDB.

use shopDB

Create an orders collection:

db.createCollection("orders")

Insert some sample records:

db.orders.insertMany([
    {
        customerName: "Rahul",
        product: "Laptop",
        amount: 55000,
        status: "Pending"
    },
    {
        customerName: "Priya",
        product: "Mobile",
        amount: 25000,
        status: "Processing"
    }
])

Check the collection:

db.orders.find()

6. Open a Change Stream Using watch()

MongoDB provides the watch() method to open a Change Stream.

Run this command:

const changeStream = db.orders.watch()

This opens a Change Stream on the orders collection.

Now listen for events:

while (changeStream.hasNext()) {
    printjson(changeStream.next())
}

Keep this command running in one mongosh terminal.

Open another mongosh terminal connected to the same replica set and database. Perform an operation:

db.orders.insertOne({
    customerName: "Amit",
    product: "Keyboard",
    amount: 2000,
    status: "Pending"
})

The first terminal receives the insert event.

Note: The while loop waits for new events. Stop it with Ctrl+C when you want to finish the demonstration.

7. Understand MongoDB Change Stream Events

When a change occurs, MongoDB returns an event document.

A simplified insert event looks like this:

{
    _id: {
        // Resume token
    },
    operationType: "insert",
    clusterTime: Timestamp(...),
    ns: {
        db: "shopDB",
        coll: "orders"
    },
    documentKey: {
        _id: ObjectId("...")
    },
    fullDocument: {
        customerName: "Amit",
        product: "Keyboard",
        amount: 2000,
        status: "Pending"
    }
}

Important event fields:

Field	Description
_id	Resume token for the change event
operationType	Type of database operation
clusterTime	Time associated with the event
ns	Database and collection information
documentKey	Identifier of the affected document
fullDocument	Document content when available

The exact event fields depend on the operation and Change Stream options.

8. Monitor Insert Events

You can listen specifically for insert operations.

const insertStream = db.orders.watch([
    {
        $match: {
            operationType: "insert"
        }
    }
])

Now listen for new insert events:

while (insertStream.hasNext()) {
    printjson(insertStream.next())
}

When a new document is inserted into orders, the stream reports the insert event.

Update and delete events are excluded by this filter.

9. Monitor Update Events

To monitor only update operations, use the operationType field.

const updateStream = db.orders.watch([
    {
        $match: {
            operationType: "update"
        }
    }
])

In another terminal, update a document:

db.orders.updateOne(
    {
        customerName: "Rahul"
    },
    {
        $set: {
            status: "Delivered"
        }
    }
)

The Change Stream receives an update event.

An update event can contain an updateDescription field:

{
    operationType: "update",
    updateDescription: {
        updatedFields: {
            status: "Delivered"
        },
        removedFields: [],
        truncatedArrays: []
    }
}

This describes which fields were updated, removed or truncated.

10. Get the Updated Document Using fullDocument

By default, an update event does not necessarily contain the complete updated document.

If you want MongoDB to look up the latest version of the document, use fullDocument: "updateLookup".

const updateStream = db.orders.watch(
    [
        {
            $match: {
                operationType: "update"
            }
        }
    ],
    {
        fullDocument: "updateLookup"
    }
)

Listen for the event:

while (updateStream.hasNext()) {
    printjson(updateStream.next())
}

The event can now include the fullDocument field containing the document version found by the lookup.

Important: updateLookup returns the most current majority-committed version found at lookup time. It is not guaranteed to be the exact document image immediately after the particular update if further changes have occurred.

11. Monitor Delete Events

You can also monitor delete operations.

const deleteStream = db.orders.watch([
    {
        $match: {
            operationType: "delete"
        }
    }
])

Now delete a document from another terminal:

db.orders.deleteOne({
    customerName: "Priya"
})

The Change Stream receives a delete event.

Delete events normally contain the document key rather than the complete deleted document.

12. Monitor Multiple Event Types

You can monitor insert, update and delete events using one Change Stream.

const allChanges = db.orders.watch([
    {
        $match: {
            operationType: {
                $in: [
                    "insert",
                    "update",
                    "delete"
                ]
            }
        }
    }
])

Listen for events:

while (allChanges.hasNext()) {
    const event = allChanges.next()

    print("Operation: " + event.operationType)

    printjson(event)
}

This is useful when an application needs to react to multiple types of database changes.

13. Watch an Entire Database

You can watch changes across collections in a database using db.watch().

const databaseStream = db.watch()

Listen for events:

while (databaseStream.hasNext()) {
    printjson(databaseStream.next())
}

This stream monitors eligible collection changes across the current database.

For example, changes in orders, customers and products can be observed through the database-level stream.

14. Watch an Entire MongoDB Deployment

MongoDB also provides Mongo.watch() to monitor eligible changes across an entire deployment.

const deploymentStream = db.getMongo().watch()

Listen for events:

while (deploymentStream.hasNext()) {
    printjson(deploymentStream.next())
}

This is useful when an application needs to monitor changes across multiple databases in a replica set or sharded cluster.

15. What Is a Resume Token in MongoDB?

Every Change Stream event contains an _id field that acts as a resume token.

A resume token works like a bookmark. It identifies a position in the stream so a consumer can attempt to continue from that point after an interruption.

Example:

const stream = db.orders.watch()

const event = stream.next()

const resumeToken = event._id

printjson(resumeToken)

Store the complete resume token safely if you need to resume later.

Do not modify the token or treat its internal structure as a format your application should interpret.

16. Resume a Change Stream Using resumeAfter

You can use resumeAfter to reopen a stream after a previously received event.

Example:

const resumedStream = db.orders.watch(
    [],
    {
        resumeAfter: resumeToken
    }
)

Listen for the next events:

while (resumedStream.hasNext()) {
    printjson(resumedStream.next())
}

The resume token must still be available in the oplog history.

Use the same Change Stream pipeline and options when resuming, as changing them can lead to unexpected results.

Important: In mongosh, you need to handle reopening the stream yourself after an error. MongoDB drivers provide automatic resume behavior for certain resumable errors.

17. Close a Change Stream

When you no longer need a Change Stream, close its cursor.

changeStream.close()

Closing the stream releases its cursor resources.

If you have opened multiple streams, close each one when finished.

18. MongoDB Change Streams vs Polling

Feature	Change Streams	Polling
Monitoring	Event-based	Repeated queries
Notifications	Change events	Found by checking
Database queries	Waits for events	Runs queries repeatedly
Real-time applications	Useful	Can introduce delay
Resume support	Resume tokens	Requires custom tracking

Change Streams are often more suitable when an application needs to react to database changes without repeatedly querying the collection.

19. Real-World Applications of Change Streams

MongoDB Change Streams are useful in many applications:

1. E-commerce notifications – notify customers when an order status changes.

2. Live dashboards – update dashboard information when database records change.

3. Inventory management – monitor stock updates.

4. Chat applications – react when new messages are stored.

5. Audit systems – capture database changes for tracking.

6. Data synchronization – send database changes to other services.

20. Important MongoDB Change Stream Best Practices

• Use a replica set or sharded cluster.

• Filter events with $match when you only need specific operations.

• Store resume tokens safely for recovery.

• Keep the Change Stream pipeline efficient.

• Close unused Change Stream cursors.

• Do not modify or remove the event _id field in the pipeline.

• Monitor connection pool capacity when opening many streams.

• Make event processing safe to retry, especially when your application performs external side effects.

21. Practical Exercise

Try these tasks:

1. Create a database named shopDB.

2. Create an orders collection.

3. Insert sample order documents.

4. Open a Change Stream using watch().

5. Insert a new order from another terminal.

6. Monitor only insert events.

7. Update an order and monitor update events.

8. Use fullDocument: "updateLookup".

9. Delete an order and monitor delete events.

10. Store a resume token and try reopening the stream using resumeAfter.

22. Frequently Asked Questions (FAQs)

Q1. What are MongoDB Change Streams?

MongoDB Change Streams allow applications to monitor database changes in real time.

Q2. Which operations can Change Streams monitor?

They can monitor insert, update, replace and delete operations, along with other supported database events.

Q3. What is watch() in MongoDB?

The watch() method opens a Change Stream cursor on a collection, database or deployment, depending on the method used.

Q4. Can MongoDB Change Streams work on a standalone server?

No. Change Streams require a replica set or sharded cluster.

Q5. What is a resume token?

A resume token is the event's _id value. It acts as a bookmark that can be used to resume a Change Stream.

Q6. What is fullDocument: "updateLookup"?

It asks MongoDB to look up the latest majority-committed version of the updated document for an update event.

Q7. Where are Change Streams used?

They are used in real-time notifications, live dashboards, inventory systems, audit systems and data synchronization.

23. Conclusion

MongoDB Change Streams provide a powerful way to monitor database changes in real time.

In this tutorial, we learned how to:

• Understand MongoDB Change Streams.

• Create a Change Stream using watch().

• Monitor insert, update and delete events.

• Filter events using $match.

• Retrieve updated documents using fullDocument.

• Store and use resume tokens.

• Resume a stream using resumeAfter.

• Close a Change Stream cursor.

By understanding Change Streams, you can build real-time applications that respond automatically whenever important database changes occur.