MongoD...eStream(3pm)

💅 MongoDB::ChangeStream(3pm) — like, the manual, but make it make sense

okay bestie, so this is the User Contributed Perl Documentation page for MongoDB::ChangeStream(3pm), and I'm about to explain it to you the way it deserves to be explained. no cap. 🦋

✨ NAME ✨

MongoDB::ChangeStream — a stream that serves up update info for collections, like a lil news feed but for your database. 📰

---

🌸 VERSION 🌸

version v2.2.2

---

🎀 SYNOPSIS 🎀

$stream = $collection->watch( $pipeline, $options );
while(1) {

    # This inner loop will only iterate until there are no more
    # changes available.
    while (my $change = $stream->next) {
        ...
    }
}

notice the nesting, bestie — the outer while(1) keeps you alive, the inner one drains whatever's there and then dips. 💀

---

🦋 DESCRIPTION 🦋

This class is the whole vibe of change stream results — literally exactly what comes back from the watch method over in MongoDB::Collection. That's the tea. ☕

---

💖 STREAM METHODS 💖

👑 next

$change_stream = $collection->watch(...);
$change = $change_stream->next;

It waits for the next change to happen in the collection, and then hands it to you. iconic behavior, honestly. 🫶

Note: this method will wait for however many milliseconds you passed as maxAwaitTimeMS to watch in MongoDB::Collection — or the server's default wait-time if you didn't. It will not wait indefinitely. so like, don't build your whole life around it hanging around forever. 😭

🧚 get_resume_token

So here's the situation: you can peek at the _id on each ChangeDocument and use that as a resume token. BUT — and this is the glow-up — since MongoDB 4.2, aggregate and getMore responses also include a postBatchResumeToken. Drivers pick one or the other when they're auto-resuming. two tokens, one job, messy. 🙈

This method grabs the same resume token that would be used to automatically resume. So if you're the kind of person who wants to store that token somewhere — and you are, you organized queen — use this method, because it gives you the most up to date one. periodt. ⭐

For instance:

if ($local_change) {
    process_change($local_change);
}

eval {
    my $change_stream = $coll->watch([], { resumeAfter => $local_resume_token });
    while ( my $change = $change_stream->next) {
        $local_resume_token = $change_stream->get_resume_token;
        $local_change = $change;
        process_change($local_change);
    }
};
if (my $err = $@) {
    $log->error($err);
}

In this case the current change is always persisted locally, resume token included — so on restart your app can still process that change while making sure the change stream picks up from the right logical time in the oplog. chef's kiss. 🔥

Important though: it is the application's responsibility to make sure process_change is idempotent. This design merely makes a reasonable effort to process each change at least once. translation: it tries its best, it does not pinky-promise. 💅

---

🌈 SEE ALSO 🌈

The Change Streams manual section — https://docs.mongodb.com/manual/changeStreams/.

The Change Streams specification — https://github.com/mongodb/specifications/blob/master/source/change-streams.rst.

iykyk, go read them. 📚

---

💜 AUTHORS 💜

• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>

look at this roster. legends only. 👑

---

🍓 COPYRIGHT AND LICENSE 🍓

This software is Copyright (c) 2020 by MongoDB, Inc.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

free software, slay. 🎀

---

and that's the whole page, bestie — no crumbs left. this was MongoD...eStream(3pm) from perl v5.40.1, dated 2025-04-03. go forth and stream your changes. 💖✨