MongoD...ference(3pm)

💖 MongoDB::ReadPreference 💖

okay bestie, so the page header says this is MongoD...ference(3pm) from the User Contributed Perl Documentation section, and honestly? It's giving "short but mighty." Let's get into it. ✨

✨ NAME ✨

MongoDB::ReadPreference — literally just here to encapsulate and validate read preferences. That's the whole job. Iconic behavior, no notes. 💅

🎀 VERSION 🎀

version v2.2.2 — yes, she's on v2.2.2, periodt.

🦋 SYNOPSIS 🦋

use MongoDB::ReadPreference;

$rp = MongoDB::ReadPreference->new(); # mode: primary

$rp = MongoDB::ReadPreference->new(
    mode     => 'primaryPreferred',
    tag_sets => [ { dc => 'useast' }, {} ],
);

see how the first one with no args just defaults to mode: primary? lowkey perfect. And look at that second example with two tag sets — one specific, one empty for the "idk, anywhere" fallback. 🫶

🌸 DESCRIPTION 🌸

So a read preference is the thing that tells MongoDB which servers should be used for read operations. That's it, that's the vibe check.

For the core docs on read preference, the original points you here: <http://docs.mongodb.org/manual/core/read-preference/>. go read it, iykyk. 📚

💜 USAGE 💜

Read preferences run on two attributes: "mode" and "tag_sets". The "mode" parameter is the main character here — it controls which types of servers are even candidates for a read operation, plus the logic for how "tag_sets" gets applied to narrow that list down even further. ✨

Here's the terminology the original lays out, and bestie, you're gonna want these words in your vocabulary:

• candidates — based on "mode", these are the servers that could be suitable, based on "tag_sets" and other logic
• eligible — these are the candidates that actually match "tag_sets"
• suitable — servers that meet all the criteria for a read operation 👑

---

🔥 Read preference modes 🔥

okay here come the modes, this is the good part:

primary

Only an available primary is suitable. And importantly — "tag_sets" do not apply here, so you must not provide them, or an exception gets thrown. 🚨 like, don't even try it.

secondary

All secondaries (and only secondaries) are candidates — but only the eligible candidates (i.e. after applying "tag_sets") are suitable.

primaryPreferred

Try to find a server using mode "primary" (with no "tag_sets"). If that fails, try to find one using mode "secondary" and the "tag_sets" attribute. Backup plan energy. 💅

secondaryPreferred

Try to find a server using mode "secondary" and the "tag_sets" attribute. If that fails, try to find one using mode "primary" (with no "tag_sets"). Same idea, flipped. 🔄

nearest

The primary and all secondaries are candidates, but only eligible candidates (i.e. after applying "tag_sets" to all candidates) are suitable.

⚠️ NOTE: in retrospect, the name "nearest" is misleading, because it implies a choice based on lowest absolute latency or geographic proximity — and neither of those are true. 😭

The "nearest" mode merely includes both primaries and secondaries without any preference between the two. All of them get filtered on "tag_sets". And because of that filtering, servers might not be "closest" in any sense. And if multiple servers are suitable, one is randomly chosen based on the rules for server selection — which, again, might not be the closest in absolute latency terms. so the name is basically lying to you, bestie. 🙈

---

🧚 Tag set matching 🧚

The "tag_sets" parameter is a list of tag sets (i.e. key/value pairs) to try in order. The first tag set in the list that matches any candidate server gets used as the filter for all candidate servers. Any subsequent tag sets? ignored. bye. 👋

A read preference tag set ("T") matches a server tag set ("S") — or equivalently, a server tag set ("S") matches a read preference tag set ("T") — if "T" is a subset of "S" (i.e. "T ⊆ S"). math girlies rise. 📐

For example, the read preference tag set { dc => 'ny', rack => 2 } matches a secondary server with tag set { dc => 'ny', rack => 2, size => 'large' }. see? subset. slay.

And a tag set that's an empty document — {} — matches any server, because the empty tag set is a subset of any tag set. it's the universal donor of tag sets fr fr. 🩸✨

---

👑 ATTRIBUTES 👑

💫 mode

The read preference mode determines which server types are candidates for a read operation. Valid values are:

• primary
• primaryPreferred
• secondary
• secondaryPreferred
• nearest

💫 tag_sets

The "tag_sets" parameter is an ordered list of tag sets used to restrict the eligibility of servers — such as for data center awareness. 🌍

The application of "tag_sets" varies depending on the "mode" parameter. And heads up: if the "mode" is 'primary', then "tag_sets" must not be supplied. 🚨

💫 max_staleness_seconds

The "max_staleness_seconds" parameter represents the maximum replication lag in seconds (wall clock time) that a secondary can suffer and still be eligible for reads. The default is -1, which disables staleness checks.

And same rule as before: if the "mode" is 'primary', then "max_staleness_seconds" must not be supplied. 🚫

---

🌈 AUTHORS 🌈

shoutout to the girlies and guys who built this:

• 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>

---

📜 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

---

and that's the whole page, bestie!! 🎀 everything you need, nothing missing. this was written up with perl v5.40.1, dated 2025-04-03, and the page footer would normally say MongoD...ference(3pm) again but you already know. go set your read preferences responsibly, mwah 💖🦋✨