Provided by: libmongodb-perl_2.2.2-2_all 
NAME
MongoDB::Upgrading - Deprecations and behavior changes from v1 to v2
VERSION
version v2.2.2
DESCRIPTION
The v2 driver represents an evolutionary rather than revolutionary release, but with
enough differences to justify a major version bump.
The most significant change in v2 is a switch away from the embedded BSON encoder/decoder
to an external library, BSON and an optional optimization addon, BSON::XS. Many
applications will continue to work unmodified, but some may need changes.
This document is intended to help developers update their code to take into account API
changes from the v1 driver to the v2 driver.
RATIONALE
API Changes are never something to do lightly. Changes in the v2 driver were deemed
necessary to achieve certain goals, all of which echo themes of the v1 driver release:
• consistency – particularly with regards to 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 that 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 upgrading, you need to be sure that the old version doesn't shadow the new
one.
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.
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.
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.
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.
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.
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.
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.
DEPRECATIONS
Count method on collections
The "count" method is deprecated.
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); in
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.
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
Features deprecated in the v1 release have now been removed. Additionally,
"MongoDB::BSON" has been removed in favor of BSON, as described earlier.
Configuration options
• "dt_type"
• "query_timeout"
• "sasl"
• "sasl_mechanism"
• "timeout"
• $MongoDB::BSON::char
• $MongoDB::BSON::looks_like_number
Classes
• "MongoDB::BSON"
• "MongoDB::GridFS"
• "MongoDB::GridFS::File"
Functions/Methods
• 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"
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>
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