.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::Upgrading 3pm"
.TH MongoDB::Upgrading 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::Upgrading \- Deprecations and behavior changes from v1 to v2
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The v2 driver represents an evolutionary rather than revolutionary release,
but with enough differences to justify a major version bump.
.PP
The most significant change in v2 is a switch away from the embedded \s-1BSON\s0
encoder/decoder to an external library, \s-1BSON\s0 and an optional
optimization addon, \s-1BSON::XS\s0.  Many applications will continue to work
unmodified, but some may need changes.
.PP
This document is intended to help developers update their code to take into
account \s-1API\s0 changes from the v1 driver to the v2 driver.
.SH "RATIONALE"
.IX Header "RATIONALE"
\&\s-1API\s0 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:
.IP "\(bu" 4
consistency – particularly with regards to Perl <\-> \s-1BSON\s0 data conversion, the v2 driver provides a complete, consistently-designed set of \s-1BSON\s0 type wrappers, and significantly improved round-trip capabilities.
.IP "\(bu" 4
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.
.IP "\(bu" 4
portability – the switch to an external library that has both pure-Perl and \s-1XS\s0 optimized versions allows the MongoDB driver to support environments without a C compiler available.
.SH "INSTALLATION AND DEPENDENCY CHANGES"
.IX Header "INSTALLATION AND DEPENDENCY CHANGES"
.SS "Installing v2 over v1"
.IX Subsection "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.
.PP
That's easy with \f(CW\*(C`cpanm\*(C'\fR:
.PP
.Vb 1
\&    cpanm \-\-uninst\-shadows MongoDB
.Ve
.PP
For the traditional \s-1CPAN\s0 client, you'll need to configure the
\&\f(CW\*(C`make_install_arg\*(C'\fR config argument like this:
.PP
.Vb 4
\&    $ perl \-MCPAN \-e shell
\&    cpan> o conf make_install_arg UNINST=1
\&    cpan> o conf commit
\&    cpan> install MongoDB
.Ve
.SS "\s-1BSON\s0 library"
.IX Subsection "BSON library"
The MongoDB driver uses a newer version of the \s-1BSON\s0 library.
Previously, \s-1BSON\s0 was already required for BSON::Decimal128, so this
is a version bump rather than an entirely new dependency.
.SS "Minimum Perl version"
.IX Subsection "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.
.SS "Pure-perl capable"
.IX Subsection "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
\&\f(CW\*(C`PUREPERL_ONLY=1\*(C'\fR as a \f(CW\*(C`Makefile.PL\*(C'\fR argument to disable compiler
detection.
.SH "BSON BEHAVIOR CHANGES"
.IX Header "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.
.SS "MongoDB::BSON is removed"
.IX Subsection "MongoDB::BSON is removed"
Code that customized behavior by instantiating this class will need to
use \s-1BSON\s0 instead.  Options are generally similar, though \s-1BSON\s0
provides much more flexibility.
.SS "New type wrapper classes"
.IX Subsection "New type wrapper classes"
The \s-1BSON\s0 module provides a complete set of classes mapping to every \s-1BSON\s0
type.  When decoding, these types will be returned for types that don't map
by default to Perl types.
.PP
Code that uses \f(CW\*(C`ref\*(C'\fR 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.
.SS "Legacy type wrappers"
.IX Subsection "Legacy type wrappers"
All the legacy type wrappers have been updated to be subclasses of their
corresponding \s-1BSON\s0 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 \s-1API\s0 \*(-- but
some have some additional constructor argument behaviors for backwards
compatibility.
.PP
The \s-1BSON\s0 library knows how to encode legacy types, so code that uses
legacy types for encoding values should be able to work without
modification.
.PP
The legacy type wrappers will be removed in a future major version release
of the driver.
.SS "Default date type decoding"
.IX Subsection "Default date type decoding"
The legacy driver defaulted to decoding the \s-1BSON\s0 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.
.PP
The previously-deprecated  \f(CW\*(C`dt_type\*(C'\fR configuration argument has been
removed from MongoDB::MongoClient and the default date type of the
\&\s-1BSON\s0 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.
.PP
Code that relied on date types being DateTime objects will need to
convert via the \f(CW\*(C`as_datetime\*(C'\fR method of BSON::Time.
.SS "More consistent string/number heuristics"
.IX Subsection "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:
.IP "\(bu" 4
If the value has a valid double representation, it will be encoded to \s-1BSON\s0 as a double.
.IP "\(bu" 4
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.
.IP "\(bu" 4
Otherwise, the value will be encoded as a \s-1UTF\-8\s0 string.
.PP
The \s-1BSON\s0 library provides the \f(CW\*(C`prefer_numeric\*(C'\fR attribute to more
aggressively coerce number-like strings that don't already have a numeric
representation into a numeric form.
.PP
This is essentially the same as the legacy heuristic but some edge cases
have been made consistent.
.SS "Type helper functions"
.IX Subsection "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:
.PP
.Vb 1
\&    use BSON::Types \*(Aq:all\*(Aq;
\&
\&    $int32    = bson_int32(42);
\&    $time     = bson_time(); # now
\&    $ordered  = bson_doc( first => "John", last => "Doe );
.Ve
.SH "NON-BSON BEHAVIOR CHANGES"
.IX Header "NON-BSON BEHAVIOR CHANGES"
.SS "run_command requires an ordered document"
.IX Subsection "run_command requires an ordered document"
The MongoDB database uses the first key of the document provided to
\&\f(CW\*(C`run_command\*(C'\fR 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 \f(CW\*(C`run_command\*(C'\fR 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.
.SH "DEPRECATIONS"
.IX Header "DEPRECATIONS"
.SS "Count method on collections"
.IX Subsection "Count method on collections"
The \f(CW\*(C`count\*(C'\fR method is deprecated.
.PP
The reasons for this change are as follows:
.IP "\(bu" 4
The performance and correctness characteristics of the \f(CW\*(C`count\*(C'\fR method could vary widely depending on whether or not a predicate is used.
.IP "\(bu" 4
The \f(CW\*(C`count\*(C'\fR method could be incorrect on sharded clusters during document migration between shards.
.PP
Many users are unaware of these considerations in the use of \f(CW\*(C`count\*(C'\fR.  As
any change to \f(CW\*(C`count\*(C'\fR could surprise users with unexpected differences in
either performance or correctness, the \f(CW\*(C`count\*(C'\fR method has been replaced
with two new \s-1API\s0 methods, which more directly convey performance and
correctness expectations:
.IP "\(bu" 4
\&\f(CW\*(C`estimated_document_count\*(C'\fR takes no predicate; it does not work in transactions; performance is O(1).
.IP "\(bu" 4
\&\f(CW\*(C`count_documents\*(C'\fR takes a predicate (even if \*(L"empty\*(R", meaning count all documents); in can be used with or without transactions; performance is O(N) in the worst case.
.PP
\&\fB\s-1NOTE\s0\fR: When upgrading from the deprecated \f(CW\*(C`count\*(C'\fR method, some legacy
operators are not supported and must be replaced:
.PP
.Vb 9
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&    | Legacy      | Modern Replacement             |
\&    +=============+================================+
\&    | $where      | $expr (Requires MongoDB 3.6+)  |
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&    | $near       | $geoWithin with $center        |
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&    | $nearSphere | $geoWithin with $centerSphere  |
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.SS "Authentication"
.IX Subsection "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.
.SS "Query options"
.IX Subsection "Query options"
The following query options are deprecated:
.IP "\(bu" 4
maxScan \*(-- deprecated in MongoDB server 4.0
.IP "\(bu" 4
modifiers \*(-- the old \f(CW\*(C`$\*(C'\fR prefixed modifiers have been replaced with explicit, equivalent options for \f(CW\*(C`find\*(C'\fR
.IP "\(bu" 4
snapshot \*(-- deprecated in MongoDB server 4.0
.SS "\s-1MD5\s0 checksum for GridFS files"
.IX Subsection "MD5 checksum for GridFS files"
The \f(CW\*(C`md5\*(C'\fR field of GridFS documents is deprecated.  Use of a checksum like
\&\s-1MD5\s0 has been redundant since MongoDB added write concern and \s-1MD5\s0 itself is
no longer considered a secure digest function.  A future release will
remove the use of \s-1MD5\s0 entirely.  In the meantime, users can disable \s-1MD5\s0
digesting with the \f(CW\*(C`disable_md5\*(C'\fR option in MongoDB::GridFSBucket.
.PP
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 \f(CW\*(C`metadata\*(C'\fR field of the file document.
.SS "Classes"
.IX Subsection "Classes"
These classes are superseded by type wrappers from \s-1BSON\s0, as described
earlier.
.IP "\(bu" 4
MongoDB::BSON::Binary
.IP "\(bu" 4
MongoDB::BSON::Regexp
.IP "\(bu" 4
MongoDB::Code
.IP "\(bu" 4
MongoDB::DBRef
.IP "\(bu" 4
MongoDB::OID
.IP "\(bu" 4
MongoDB::Timestamp
.SH "REMOVED FEATURES"
.IX Header "REMOVED FEATURES"
Features deprecated in the v1 release have now been removed.  Additionally,
\&\f(CW\*(C`MongoDB::BSON\*(C'\fR has been removed in favor of \s-1BSON\s0, as described
earlier.
.SS "Configuration options"
.IX Subsection "Configuration options"
.IP "\(bu" 4
\&\f(CW\*(C`dt_type\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`query_timeout\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`sasl\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`sasl_mechanism\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`timeout\*(C'\fR
.IP "\(bu" 4
\&\f(CW$MongoDB::BSON::char\fR
.IP "\(bu" 4
\&\f(CW$MongoDB::BSON::looks_like_number\fR
.SS "Classes"
.IX Subsection "Classes"
.IP "\(bu" 4
\&\f(CW\*(C`MongoDB::BSON\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`MongoDB::GridFS\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`MongoDB::GridFS::File\*(C'\fR
.SS "Functions/Methods"
.IX Subsection "Functions/Methods"
.IP "\(bu" 4
From \f(CW\*(C`MongoDB\*(C'\fR \- \f(CW\*(C`force_double\*(C'\fR, \f(CW\*(C`force_int\*(C'\fR
.IP "\(bu" 4
From \f(CW\*(C`MongoDB::BulkWrite\*(C'\fR and \f(CW\*(C`MongoDB::BulkWriteView\*(C'\fR \- \f(CW\*(C`insert\*(C'\fR, \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, \f(CW\*(C`remove_one\*(C'\fR
.IP "\(bu" 4
From \f(CW\*(C`MongoDB::Collection\*(C'\fR \- \f(CW\*(C`insert\*(C'\fR, \f(CW\*(C`batch_insert\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`save\*(C'\fR, \f(CW\*(C`query\*(C'\fR, \f(CW\*(C`find_and_modify\*(C'\fR, \f(CW\*(C`get_collection\*(C'\fR, \f(CW\*(C`ensure_index\*(C'\fR, \f(CW\*(C`drop_indexes\*(C'\fR, \f(CW\*(C`drop_index\*(C'\fR, \f(CW\*(C`get_index\*(C'\fR, \f(CW\*(C`validate\*(C'\fR
.IP "\(bu" 4
From \f(CW\*(C`MongoDB::Database\*(C'\fR \- \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`last_error\*(C'\fR, \f(CW\*(C`get_gridfs\*(C'\fR
.IP "\(bu" 4
From \f(CW\*(C`MongoDB::CommandResult\*(C'\fR \- \f(CW\*(C`result\*(C'\fR
.IP "\(bu" 4
From \f(CW\*(C`MongoDB::Cursor\*(C'\fR \- \f(CW\*(C`slave_okay\*(C'\fR, \f(CW\*(C`count\*(C'\fR
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve