1MongoDB::Upgrading(3) User Contributed Perl DocumentationMongoDB::Upgrading(3)
2
6 MongoDB::Upgrading - Deprecations and behavior changes from v1 to v2
7
9 version v2.2.2
10
12 The v2 driver represents an evolutionary rather than revolutionary
13 release, but with enough differences to justify a major version bump.
14 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 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
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 • 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 • 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 • 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
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 That's easy with "cpanm":
48 cpanm --uninst-shadows MongoDB
50 For the traditional CPAN client, you'll need to configure the
52 "make_install_arg" config argument like this:
53 $ perl -MCPAN -e shell
55 cpan> o conf make_install_arg UNINST=1
56 cpan> o conf commit
57 cpan> install MongoDB
58 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 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 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
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 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 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 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 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 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 The legacy type wrappers will be removed in a future major version
110 release of the driver.
111 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 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 Code that relied on date types being DateTime objects will need to
126 convert via the "as_datetime" method of BSON::Time.
127 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 • If the value has a valid double representation, it will be encoded
136 to BSON as a double.
137 • 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 • Otherwise, the value will be encoded as a UTF-8 string.
143 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 This is essentially the same as the legacy heuristic but some edge
149 cases have been made consistent.
150 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 use BSON::Types ':all';
157 $int32 = bson_int32(42);
159 $time = bson_time(); # now
160 $ordered = bson_doc( first => "John", last => "Doe );
161
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
173 Count method on collections
174 The "count" method is deprecated.
175 The reasons for this change are as follows:
177 • The performance and correctness characteristics of the "count"
179 method could vary widely depending on whether or not a predicate is
180 used.
181 • The "count" method could be incorrect on sharded clusters during
183 document migration between shards.
184 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 • "estimated_document_count" takes no predicate; it does not work in
192 transactions; performance is O(1).
193 • "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 NOTE: When upgrading from the deprecated "count" method, some legacy
199 operators are not supported and must be replaced:
200 +-------------+--------------------------------+
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 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 Query options
218 The following query options are deprecated:
219 • maxScan -- deprecated in MongoDB server 4.0
221 • modifiers -- the old "$" prefixed modifiers have been replaced with
223 explicit, equivalent options for "find"
224 • snapshot -- deprecated in MongoDB server 4.0
226 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 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 Classes
240 These classes are superseded by type wrappers from BSON, as described
241 earlier.
242 • MongoDB::BSON::Binary
244 • MongoDB::BSON::Regexp
246 • MongoDB::Code
248 • MongoDB::DBRef
250 • MongoDB::OID
252 • MongoDB::Timestamp
254
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 Configuration options
261 • "dt_type"
262 • "query_timeout"
264 • "sasl"
266 • "sasl_mechanism"
268 • "timeout"
270 • $MongoDB::BSON::char
272 • $MongoDB::BSON::looks_like_number
274 Classes
276 • "MongoDB::BSON"
277 • "MongoDB::GridFS"
279 • "MongoDB::GridFS::File"
281 Functions/Methods
283 • From "MongoDB" - "force_double", "force_int"
284 • From "MongoDB::BulkWrite" and "MongoDB::BulkWriteView" - "insert",
286 "update", "remove", "remove_one"
287 • 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 • From "MongoDB::Database" - "eval", "last_error", "get_gridfs"
294 • From "MongoDB::CommandResult" - "result"
296 • From "MongoDB::Cursor" - "slave_okay", "count"
298
300 • David Golden <david@mongodb.com>
301 • Rassi <rassi@mongodb.com>
303 • Mike Friedman <friedo@friedo.com>
305 • Kristina Chodorow <k.chodorow@gmail.com>
307 • Florian Ragwitz <rafl@debian.org>
309
311 This software is Copyright (c) 2020 by MongoDB, Inc.
312 This is free software, licensed under:
314 The Apache License, Version 2.0, January 2004
316perl v5.32.1 2021-01-27 MongoDB::Upgrading(3)