MongoD...rading(3pm)

📦
version 2.2.2 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay bestie, gather round — this is the MongoDB::Upgrading manual page, the MongoDB::Upgrading(3pm) one from the User Contributed Perl Documentation collection. It's literally the deprecations and behavior changes from v1 to v2. Periodt. 👑

✨ VERSION ✨

version v2.2.2

🌸 DESCRIPTION 🌸

The v2 driver is giving evolutionary, not revolutionary, release energy 💅 — but the differences are big enough to justify a major version bump, no cap.

The most iconic glow-up in v2? It switches away from the embedded BSON encoder/decoder to an external library, BSON, plus an optional optimization addon, BSON::XS. Many apps will keep working unmodified, but some may need changes. This doc is here to help devs update their code for the API changes from v1 to v2. 🫶

🧠 RATIONALE 🧠

API changes are never something to do lightly — fr fr. Changes in the v2 driver were deemed necessary to achieve certain goals, all echoing themes from the v1 driver release:

  • consistency — particularly with Perl <-> BSON data conversion. The v2 driver provides a complete, consistently-designed set of BSON type wrappers, and significantly improved round-trip capabilities. ✨
  • server compatibility — as the MongoDB server deprecates or removes functionality, the driver must be updated to match so users don't develop apps around features that are going away. 💀
  • portability — the switch to an external library that has both pure-Perl and XS optimized versions allows the MongoDB driver to support environments without a C compiler available. 💖

📦 INSTALLATION AND DEPENDENCY CHANGES 📦

🎀 Installing v2 over v1 🎀

Because the v2 driver is pure-Perl capable (see below), its Perl installation directory is different. If you're upgrading, you need to be sure the old version doesn't shadow the new one. Lowkey important.

That's easy with cpanm:

cpanm --uninst-shadows MongoDB

For the traditional CPAN client, you'll need to configure the make_install_arg config argument like this:

$ perl -MCPAN -e shell
cpan> o conf make_install_arg UNINST=1
cpan> o conf commit
cpan> install MongoDB

🦋 BSON library 🦋

The MongoDB driver uses a newer version of the BSON library. Previously, BSON was already required for BSON::Decimal128, so this is a version bump rather than an entirely new dependency. Not me being dramatic, it's just facts. 💅

🌈 Minimum Perl version 🌈

The MongoDB driver now requires Perl v5.10.1 or later. This provides better pure-Perl support, several core dependencies, and many fewer bugs involving Unicode and threads. While threads are discouraged, threads under Perl v5.8 were so broken that driver tests were regularly failing. 😭

💜 Pure-perl capable 💜

The MongoDB driver can now be installed without needing a compiler. If a compiler is detected, additional XS-based dependencies will be added to the prerequisites list for improved performance. You can also specify PUREPERL_ONLY=1 as a Makefile.PL argument to disable compiler detection. Slay. ✨

🧬 BSON BEHAVIOR CHANGES 🧬

For detailed information on handling MongoDB data types in Perl, see MongoDB::DataTypes. The following sections provide an overview of major changes from past versions.

💀 MongoDB::BSON is removed 💀

Code that customized behavior by instantiating this class will need to use BSON instead. Options are generally similar, though BSON provides much more flexibility. It's giving upgraded. 👑

🌟 New type wrapper classes 🌟

The BSON module provides a complete set of classes mapping to every BSON type. When decoding, these types will be returned for types that don't map by default to Perl types.

Code that uses ref to check documents returned from the database for legacy types (e.g. MongoDB::BSON::Regexp) will need to be updated for the new type wrappers. Periodt.

🎀 Legacy type wrappers 🎀

All the legacy type wrappers have been updated to be subclasses of their corresponding BSON library equivalents. For example, MongoDB::BSON::Regexp is a subclass of BSON::Regex. Most of them are empty subclasses — the BSON-library versions provide the same API — but some have some additional constructor argument behaviors for backwards compatibility.

The BSON library knows how to encode legacy types, so code that uses legacy types for encoding values should be able to work without modification. 🫶

The legacy type wrappers will be removed in a future major version release of the driver. ⚠️

⏰ Default date type decoding ⏰

The legacy driver defaulted to decoding the BSON date type as a DateTime object. Unfortunately, that type is very heavy-weight and slow to construct; it's a poor choice as a default as it inflicts that cost whether or not users ultimately need or want objects of that type. It's giving expensive for no reason. 💀

The previously-deprecated dt_type configuration argument has been removed from MongoDB::MongoClient and the default date type of the BSON library is BSON::Time, which is extremely lightweight and provides convenience methods to convert to various popular time classes. It also works well with Time::HiRes for recording datetimes with millisecond precision.

Code that relied on date types being DateTime objects will need to convert via the as_datetime method of BSON::Time. No cap.

🔢 More consistent string/number heuristics 🔢

Depending on their history of use, non-reference Perl scalars may have both string and number representations internally, and the MongoDB driver wasn't always clear on how it treated them. Moreover, this treatment could vary slightly by Perl version. The heuristics are now standardized as follows:

  • If the value has a valid double representation, it will be encoded to BSON as a double. 💅
  • Otherwise, if the value has a valid integer interpretation, it will be encoded as either Int32 or Int64; the smallest type that the value fits will be used; a value that overflows will error. 🚨
  • Otherwise, the value will be encoded as a UTF-8 string. 🌈

The BSON library provides the prefer_numeric attribute to more aggressively coerce number-like strings that don't already have a numeric representation into a numeric form.

This is essentially the same as the legacy heuristic but some edge cases have been made consistent. ✨

🛠️ Type helper functions 🛠️

To make it easy to use type wrappers (and to avoid unintentionally using a deprecated one), the BSON::Types module has a standard set of type helper functions:

use BSON::Types ':all';

$int32    = bson_int32(42);
$time     = bson_time(); # now
$ordered  = bson_doc( first => "John", last => "Doe );

🚫 NON-BSON BEHAVIOR CHANGES 🚫

📜 run_command requires an ordered document 📜

The MongoDB database uses the first key of the document provided to run_command as the name of the command. Due to Perl's hash order randomization, use of a hash reference with more than one key as an argument to run_command is not reliable. This restriction is now enforced. The argument must be a BSON::Doc object, a Tie::IxHash object, an array reference with an even number of keys, or a hash reference with a single key. Periodt. 💅

⚠️ DEPRECATIONS ⚠️

🔢 Count method on collections 🔢

The count method is deprecated. Not me crying. 😭

The reasons for this change are as follows:

  • The performance and correctness characteristics of the count method could vary widely depending on whether or not a predicate is used.
  • The count method could be incorrect on sharded clusters during document migration between shards.

Many users are unaware of these considerations in the use of count. As any change to count could surprise users with unexpected differences in either performance or correctness, the count method has been replaced with two new API methods, which more directly convey performance and correctness expectations:

  • estimated_document_count takes no predicate; it does not work in transactions; performance is O(1). 👑
  • count_documents takes a predicate (even if empty, meaning count all documents); it can be used with or without transactions; performance is O(N) in the worst case. 💀
NOTE: When upgrading from the deprecated count method, some legacy operators are not supported and must be replaced:
+-------------+--------------------------------+
| Legacy      | Modern Replacement             |
+=============+================================+
| $where      | $expr (Requires MongoDB 3.6+)  |
+-------------+--------------------------------+
| $near       | $geoWithin with $center        |
+-------------+--------------------------------+
| $nearSphere | $geoWithin with $centerSphere  |
+-------------+--------------------------------+

🔐 Authentication 🔐

The MONGODB-CR authentication mechanism was deprecated in MongoDB server 3.6 and removed in MongoDB server 4.0. The Perl driver is deprecating MONGODB-CR, but will not remove it until it no longer supports older servers. Iykyk. 💅

🔍 Query options 🔍

The following query options are deprecated:

  • maxScan — deprecated in MongoDB server 4.0
  • modifiers — the old $ prefixed modifiers have been replaced with explicit, equivalent options for find
  • snapshot — deprecated in MongoDB server 4.0

🧾 MD5 checksum for GridFS files 🧾

The md5 field of GridFS documents is deprecated. Use of a checksum like MD5 has been redundant since MongoDB added write concern and MD5 itself is no longer considered a secure digest function. A future release will remove the use of MD5 entirely. In the meantime, users can disable MD5 digesting with the disable_md5 option in MongoDB::GridFSBucket. 🫶

Users who wish to continue storing a digest are encouraged to compute their own digest using a function of their choice and store it under a user-defined key in the metadata field of the file document. ✨

🗂️ Classes 🗂️

These classes are superseded by type wrappers from BSON, as described earlier.

  • MongoDB::BSON::Binary
  • MongoDB::BSON::Regexp
  • MongoDB::Code
  • MongoDB::DBRef
  • MongoDB::OID
  • MongoDB::Timestamp

💀 REMOVED FEATURES 💀

Okay bestie, sit down, because this is the part where the stuff that got deprecated back in v1 is now fully gone. Not deprecated. Not "we'll fix it later." GONE gone. They packed their bags and left the group chat. 🙈

Also — and I need you to hear me on this — MongoDB::BSON has been removed in favor of BSON, exactly like we talked about earlier. No cap. 💅

🎀 Configuration options

These little config cuties are no longer a thing:

  • dt_type — removed. bye 💀
  • query_timeout — removed. she's not coming back 🫶
  • sasl — removed. gone girl energy ✨
  • sasl_mechanism — removed. also gone 🌸
  • timeout — removed. the audacity of her to leave 😭
  • $MongoDB::BSON::char — removed. rest in peace queen 👑
  • $MongoDB::BSON::looks_like_number — removed. truly iconic of her to go 🦋

🌈 Classes

These whole entire classes have left the building:

  • MongoDB::BSON — removed 💔
  • MongoDB::GridFS — removed 💔
  • MongoDB::GridFS::File — removed 💔

🧚 Functions/Methods

This is the long list, bestie, and I'm listing every single one because we don't do skipping here:

  • From MongoDB — force_double, force_int 🚫
  • From MongoDB::BulkWrite and MongoDB::BulkWriteView — insert, update, remove, remove_one 🚫
  • From MongoDB::Collection — insert, batch_insert, remove, update, save, query, find_and_modify, get_collection, ensure_index, drop_indexes, drop_index, get_index, validate 🚫
  • From MongoDB::Database — eval, last_error, get_gridfs 🚫
  • From MongoDB::CommandResult — result 🚫
  • From MongoDB::Cursor — slave_okay, count 🚫
💀 real talk: if your code is still calling any single one of these, that code is broken and it's giving "living in 2015." Migrate, bestie. I'm begging. 🙏

👑 AUTHORS

The absolute legends who built this thing:

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

Five icons. Main character energy from all of them, fr fr. 🌟

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

aaaand that's the whole page, bestie!! 🎉 you read the entire thing, that's dedication and I'm obsessed with you for it. 🫶 this version was built from perl v5.40.1 and dated 2025-04-03, and it lives under the name MongoD...rading(3pm) — go forth and write some extremely correct MongoDB code, you gorgeous genius. mwah 💋✨

📦 where this page comes from