1MongoDB::Upgrading(3) User Contributed Perl DocumentationMongoDB::Upgrading(3)
2
3
4

NAME

6       MongoDB::Upgrading - Deprecations and behavior changes from v1 to v2
7

VERSION

9       version v2.2.2
10

DESCRIPTION

12       The v2 driver represents an evolutionary rather than revolutionary
13       release, but with enough differences to justify a major version bump.
14
15       The most significant change in v2 is a switch away from the embedded
16       BSON encoder/decoder to an external library, BSON and an optional
17       optimization addon, BSON::XS.  Many applications will continue to work
18       unmodified, but some may need changes.
19
20       This document is intended to help developers update their code to take
21       into account API changes from the v1 driver to the v2 driver.
22

RATIONALE

24       API Changes are never something to do lightly.  Changes in the v2
25       driver were deemed necessary to achieve certain goals, all of which
26       echo themes of the v1 driver release:
27
28       •   consistency – particularly with regards to Perl <-> BSON data
29           conversion, the v2 driver provides a complete, consistently-
30           designed set of BSON type wrappers, and significantly improved
31           round-trip capabilities.
32
33       •   server compatibility – as the MongoDB server deprecates or removes
34           functionality, the driver must be updated to match so that users
35           don't develop apps around features that are going away.
36
37       •   portability – the switch to an external library that has both pure-
38           Perl and XS optimized versions allows the MongoDB driver to support
39           environments without a C compiler available.
40

INSTALLATION AND DEPENDENCY CHANGES

42   Installing v2 over v1
43       Because the v2 driver is pure-Perl capable (see below), its Perl
44       installation directory is different.  If upgrading, you need to be sure
45       that the old version doesn't shadow the new one.
46
47       That's easy with "cpanm":
48
49           cpanm --uninst-shadows MongoDB
50
51       For the traditional CPAN client, you'll need to configure the
52       "make_install_arg" config argument like this:
53
54           $ perl -MCPAN -e shell
55           cpan> o conf make_install_arg UNINST=1
56           cpan> o conf commit
57           cpan> install MongoDB
58
59   BSON library
60       The MongoDB driver uses a newer version of the BSON library.
61       Previously, BSON was already required for BSON::Decimal128, so this is
62       a version bump rather than an entirely new dependency.
63
64   Minimum Perl version
65       The MongoDB driver now requires Perl v5.10.1 or later.  This provides
66       better pure-Perl support, several core dependencies, and many fewer
67       bugs involving Unicode and threads.  While threads are discouraged,
68       threads under Perl v5.8 were so broken that driver tests were regularly
69       failing.
70
71   Pure-perl capable
72       The MongoDB driver can now be installed without needing a compiler.  If
73       a compiler is detected, additional XS-based dependencies will be added
74       to the prerequisites list for improved performance.  You can also
75       specify "PUREPERL_ONLY=1" as a "Makefile.PL" argument to disable
76       compiler detection.
77

BSON BEHAVIOR CHANGES

79       For detailed information on handling MongoDB data types in Perl, see
80       MongoDB::DataTypes.  The following sections provide an overview of
81       major changes from past versions.
82
83   MongoDB::BSON is removed
84       Code that customized behavior by instantiating this class will need to
85       use BSON instead.  Options are generally similar, though BSON provides
86       much more flexibility.
87
88   New type wrapper classes
89       The BSON module provides a complete set of classes mapping to every
90       BSON type.  When decoding, these types will be returned for types that
91       don't map by default to Perl types.
92
93       Code that uses "ref" to check documents returned from the database for
94       legacy types (e.g.  MongoDB::BSON::Regexp) will need to be updated for
95       the new type wrappers.
96
97   Legacy type wrappers
98       All the legacy type wrappers have been updated to be subclasses of
99       their corresponding BSON library equivalents.  For example,
100       MongoDB::BSON::Regexp is a subclass of BSON::Regex.  Most of them are
101       empty subclasses -- the BSON-library versions provide the same API --
102       but some have some additional constructor argument behaviors for
103       backwards compatibility.
104
105       The BSON library knows how to encode legacy types, so code that uses
106       legacy types for encoding values should be able to work without
107       modification.
108
109       The legacy type wrappers will be removed in a future major version
110       release of the driver.
111
112   Default date type decoding
113       The legacy driver defaulted to decoding the BSON date type as a
114       DateTime object.  Unfortunately, that type is very heavy-weight and
115       slow to construct; it's a poor choice as a default as it inflicts that
116       cost whether or not users ultimately need or want objects of that type.
117
118       The previously-deprecated  "dt_type" configuration argument has been
119       removed from MongoDB::MongoClient and the default date type of the BSON
120       library is BSON::Time, which is extremely lightweight and provides
121       convenience methods to convert to various popular time classes.  It
122       also works well with Time::HiRes for recording datetimes with
123       millisecond precision.
124
125       Code that relied on date types being DateTime objects will need to
126       convert via the "as_datetime" method of BSON::Time.
127
128   More consistent string/number heuristics
129       Depending on their history of use, non-reference Perl scalars may have
130       both string and number representations internally and the MongoDB
131       driver wasn't always clear on how it treated them. Moreover, this
132       treatment could vary slightly by Perl version.  The heuristics are now
133       standardized as follows:
134
135       •   If the value has a valid double representation, it will be encoded
136           to BSON as a double.
137
138       •   Otherwise, if the value has a valid integer interpretation, it will
139           be encoded as either Int32 or Int64; the smallest type that the
140           value fits will be used; a value that overflows will error.
141
142       •   Otherwise, the value will be encoded as a UTF-8 string.
143
144       The BSON library provides the "prefer_numeric" attribute to more
145       aggressively coerce number-like strings that don't already have a
146       numeric representation into a numeric form.
147
148       This is essentially the same as the legacy heuristic but some edge
149       cases have been made consistent.
150
151   Type helper functions
152       To make it easy to use type wrappers (and to avoid unintentionally
153       using a deprecated one), the BSON::Types module has a standard set of
154       type helper functions:
155
156           use BSON::Types ':all';
157
158           $int32    = bson_int32(42);
159           $time     = bson_time(); # now
160           $ordered  = bson_doc( first => "John", last => "Doe );
161

NON-BSON BEHAVIOR CHANGES

163   run_command requires an ordered document
164       The MongoDB database uses the first key of the document provided to
165       "run_command" as the name of the command.  Due to Perl's hash order
166       randomization, use of a hash reference with more than one key as an
167       argument to "run_command" is not reliable.  This restriction is now
168       enforced.  The argument must be a BSON::Doc object, a Tie::IxHash
169       object, an array reference with an even number of keys, or a hash
170       reference with a single key.
171

DEPRECATIONS

173   Count method on collections
174       The "count" method is deprecated.
175
176       The reasons for this change are as follows:
177
178       •   The performance and correctness characteristics of the "count"
179           method could vary widely depending on whether or not a predicate is
180           used.
181
182       •   The "count" method could be incorrect on sharded clusters during
183           document migration between shards.
184
185       Many users are unaware of these considerations in the use of "count".
186       As any change to "count" could surprise users with unexpected
187       differences in either performance or correctness, the "count" method
188       has been replaced with two new API methods, which more directly convey
189       performance and correctness expectations:
190
191       •   "estimated_document_count" takes no predicate; it does not work in
192           transactions; performance is O(1).
193
194       •   "count_documents" takes a predicate (even if "empty", meaning count
195           all documents); in can be used with or without transactions;
196           performance is O(N) in the worst case.
197
198       NOTE: When upgrading from the deprecated "count" method, some legacy
199       operators are not supported and must be replaced:
200
201           +-------------+--------------------------------+
202           | Legacy      | Modern Replacement             |
203           +=============+================================+
204           | $where      | $expr (Requires MongoDB 3.6+)  |
205           +-------------+--------------------------------+
206           | $near       | $geoWithin with $center        |
207           +-------------+--------------------------------+
208           | $nearSphere | $geoWithin with $centerSphere  |
209           +-------------+--------------------------------+
210
211   Authentication
212       The MONGODB-CR authentication mechanism was deprecated in MongoDB
213       server 3.6 and removed in MongoDB server 4.0.  The Perl driver is
214       deprecating MONGODB-CR, but will not remove it until it no longer
215       supports older servers.
216
217   Query options
218       The following query options are deprecated:
219
220       •   maxScan -- deprecated in MongoDB server 4.0
221
222       •   modifiers -- the old "$" prefixed modifiers have been replaced with
223           explicit, equivalent options for "find"
224
225       •   snapshot -- deprecated in MongoDB server 4.0
226
227   MD5 checksum for GridFS files
228       The "md5" field of GridFS documents is deprecated.  Use of a checksum
229       like MD5 has been redundant since MongoDB added write concern and MD5
230       itself is no longer considered a secure digest function.  A future
231       release will remove the use of MD5 entirely.  In the meantime, users
232       can disable MD5 digesting with the "disable_md5" option in
233       MongoDB::GridFSBucket.
234
235       Users who wish to continue storing a digest are encouraged to compute
236       their own digest using a function of their choice and store it under a
237       user-defined key in the "metadata" field of the file document.
238
239   Classes
240       These classes are superseded by type wrappers from BSON, as described
241       earlier.
242
243       •   MongoDB::BSON::Binary
244
245       •   MongoDB::BSON::Regexp
246
247       •   MongoDB::Code
248
249       •   MongoDB::DBRef
250
251       •   MongoDB::OID
252
253       •   MongoDB::Timestamp
254

REMOVED FEATURES

256       Features deprecated in the v1 release have now been removed.
257       Additionally, "MongoDB::BSON" has been removed in favor of BSON, as
258       described earlier.
259
260   Configuration options
261       •   "dt_type"
262
263       •   "query_timeout"
264
265       •   "sasl"
266
267       •   "sasl_mechanism"
268
269       •   "timeout"
270
271       •   $MongoDB::BSON::char
272
273       •   $MongoDB::BSON::looks_like_number
274
275   Classes
276       •   "MongoDB::BSON"
277
278       •   "MongoDB::GridFS"
279
280       •   "MongoDB::GridFS::File"
281
282   Functions/Methods
283       •   From "MongoDB" - "force_double", "force_int"
284
285       •   From "MongoDB::BulkWrite" and "MongoDB::BulkWriteView" - "insert",
286           "update", "remove", "remove_one"
287
288       •   From "MongoDB::Collection" - "insert", "batch_insert", "remove",
289           "update", "save", "query", "find_and_modify", "get_collection",
290           "ensure_index", "drop_indexes", "drop_index", "get_index",
291           "validate"
292
293       •   From "MongoDB::Database" - "eval", "last_error", "get_gridfs"
294
295       •   From "MongoDB::CommandResult" - "result"
296
297       •   From "MongoDB::Cursor" - "slave_okay", "count"
298

AUTHORS

300       •   David Golden <david@mongodb.com>
301
302       •   Rassi <rassi@mongodb.com>
303
304       •   Mike Friedman <friedo@friedo.com>
305
306       •   Kristina Chodorow <k.chodorow@gmail.com>
307
308       •   Florian Ragwitz <rafl@debian.org>
309
311       This software is Copyright (c) 2020 by MongoDB, Inc.
312
313       This is free software, licensed under:
314
315         The Apache License, Version 2.0, January 2004
316
317
318
319perl v5.34.0                      2022-01-21             MongoDB::Upgrading(3)
Impressum