{
    "mode": "perldoc",
    "parameter": "MongoDB::Upgrading",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/MongoDB%3A%3AUpgrading/json",
    "generated": "2026-06-13T21:25:26Z",
    "sections": {
        "NAME": {
            "content": "MongoDB::Upgrading - Deprecations and behavior changes from v1 to v2\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version v2.2.2\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The v2 driver represents an evolutionary rather than revolutionary release, but with enough\ndifferences to justify a major version bump.\n\nThe most significant change in v2 is a switch away from the embedded BSON encoder/decoder to an\nexternal library, BSON and an optional optimization addon, BSON::XS. Many applications will\ncontinue to work unmodified, but some may need changes.\n\nThis document is intended to help developers update their code to take into account API changes\nfrom the v1 driver to the v2 driver.\n",
            "subsections": []
        },
        "RATIONALE": {
            "content": "API Changes are never something to do lightly. Changes in the v2 driver were deemed necessary to\nachieve certain goals, all of which echo themes of the v1 driver release:\n\n*   consistency – particularly with regards to Perl <-> BSON data conversion, the v2 driver\nprovides a complete, consistently-designed set of BSON type wrappers, and significantly\nimproved round-trip capabilities.\n\n*   server compatibility – as the MongoDB server deprecates or removes functionality, the driver\nmust be updated to match so that users don't develop apps around features that are going\naway.\n\n*   portability – the switch to an external library that has both pure-Perl and XS optimized\nversions allows the MongoDB driver to support environments without a C compiler available.\n",
            "subsections": []
        },
        "INSTALLATION AND DEPENDENCY CHANGES": {
            "content": "",
            "subsections": [
                {
                    "name": "Installing v2 over v1",
                    "content": "Because the v2 driver is pure-Perl capable (see below), its Perl installation directory is\ndifferent. If upgrading, you need to be sure that the old version doesn't shadow the new one.\n\nThat's easy with \"cpanm\":\n\ncpanm --uninst-shadows MongoDB\n\nFor the traditional CPAN client, you'll need to configure the \"makeinstallarg\" config argument\nlike this:\n\n$ perl -MCPAN -e shell\ncpan> o conf makeinstallarg UNINST=1\ncpan> o conf commit\ncpan> install MongoDB\n\nBSON library\nThe MongoDB driver uses a newer version of the BSON library. Previously, BSON was already\nrequired for BSON::Decimal128, so this is a version bump rather than an entirely new dependency.\n"
                },
                {
                    "name": "Minimum Perl version",
                    "content": "The MongoDB driver now requires Perl v5.10.1 or later. This provides better pure-Perl support,\nseveral core dependencies, and many fewer bugs involving Unicode and threads. While threads are\ndiscouraged, threads under Perl v5.8 were so broken that driver tests were regularly failing.\n"
                },
                {
                    "name": "Pure-perl capable",
                    "content": "The MongoDB driver can now be installed without needing a compiler. If a compiler is detected,\nadditional XS-based dependencies will be added to the prerequisites list for improved\nperformance. You can also specify \"PUREPERLONLY=1\" as a \"Makefile.PL\" argument to disable\ncompiler detection.\n"
                }
            ]
        },
        "BSON BEHAVIOR CHANGES": {
            "content": "For detailed information on handling MongoDB data types in Perl, see MongoDB::DataTypes. The\nfollowing sections provide an overview of major changes from past versions.\n",
            "subsections": [
                {
                    "name": "MongoDB::BSON is removed",
                    "content": "Code that customized behavior by instantiating this class will need to use BSON instead. Options\nare generally similar, though BSON provides much more flexibility.\n"
                },
                {
                    "name": "New type wrapper classes",
                    "content": "The BSON module provides a complete set of classes mapping to every BSON type. When decoding,\nthese types will be returned for types that don't map by default to Perl types.\n\nCode that uses \"ref\" to check documents returned from the database for legacy types (e.g.\nMongoDB::BSON::Regexp) will need to be updated for the new type wrappers.\n"
                },
                {
                    "name": "Legacy type wrappers",
                    "content": "All the legacy type wrappers have been updated to be subclasses of their corresponding BSON\nlibrary equivalents. For example, MongoDB::BSON::Regexp is a subclass of BSON::Regex. Most of\nthem are empty subclasses -- the BSON-library versions provide the same API -- but some have\nsome additional constructor argument behaviors for backwards compatibility.\n\nThe BSON library knows how to encode legacy types, so code that uses legacy types for encoding\nvalues should be able to work without modification.\n\nThe legacy type wrappers will be removed in a future major version release of the driver.\n"
                },
                {
                    "name": "Default date type decoding",
                    "content": "The legacy driver defaulted to decoding the BSON date type as a DateTime object. Unfortunately,\nthat type is very heavy-weight and slow to construct; it's a poor choice as a default as it\ninflicts that cost whether or not users ultimately need or want objects of that type.\n\nThe previously-deprecated \"dttype\" configuration argument has been removed from\nMongoDB::MongoClient and the default date type of the BSON library is BSON::Time, which is\nextremely lightweight and provides convenience methods to convert to various popular time\nclasses. It also works well with Time::HiRes for recording datetimes with millisecond precision.\n\nCode that relied on date types being DateTime objects will need to convert via the \"asdatetime\"\nmethod of BSON::Time.\n\nMore consistent string/number heuristics\nDepending on their history of use, non-reference Perl scalars may have both string and number\nrepresentations internally and the MongoDB driver wasn't always clear on how it treated them.\nMoreover, this treatment could vary slightly by Perl version. The heuristics are now\nstandardized as follows:\n\n*   If the value has a valid double representation, it will be encoded to BSON as a double.\n\n*   Otherwise, if the value has a valid integer interpretation, it will be encoded as either\nInt32 or Int64; the smallest type that the value fits will be used; a value that overflows\nwill error.\n\n*   Otherwise, the value will be encoded as a UTF-8 string.\n\nThe BSON library provides the \"prefernumeric\" attribute to more aggressively coerce number-like\nstrings that don't already have a numeric representation into a numeric form.\n\nThis is essentially the same as the legacy heuristic but some edge cases have been made\nconsistent.\n"
                },
                {
                    "name": "Type helper functions",
                    "content": "To make it easy to use type wrappers (and to avoid unintentionally using a deprecated one), the\nBSON::Types module has a standard set of type helper functions:\n\nuse BSON::Types ':all';\n\n$int32    = bsonint32(42);\n$time     = bsontime(); # now\n$ordered  = bsondoc( first => \"John\", last => \"Doe );\n"
                }
            ]
        },
        "NON-BSON BEHAVIOR CHANGES": {
            "content": "runcommand requires an ordered document\nThe MongoDB database uses the first key of the document provided to \"runcommand\" as the name of\nthe command. Due to Perl's hash order randomization, use of a hash reference with more than one\nkey as an argument to \"runcommand\" is not reliable. This restriction is now enforced. The\nargument must be a BSON::Doc object, a Tie::IxHash object, an array reference with an even\nnumber of keys, or a hash reference with a single key.\n",
            "subsections": []
        },
        "DEPRECATIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "Count method on collections",
                    "content": "The \"count\" method is deprecated.\n\nThe reasons for this change are as follows:\n\n*   The performance and correctness characteristics of the \"count\" method could vary widely\ndepending on whether or not a predicate is used.\n\n*   The \"count\" method could be incorrect on sharded clusters during document migration between\nshards.\n\nMany users are unaware of these considerations in the use of \"count\". As any change to \"count\"\ncould surprise users with unexpected differences in either performance or correctness, the\n\"count\" method has been replaced with two new API methods, which more directly convey\nperformance and correctness expectations:\n\n*   \"estimateddocumentcount\" takes no predicate; it does not work in transactions; performance\nis O(1).\n\n*   \"countdocuments\" takes a predicate (even if \"empty\", meaning count all documents); in can\nbe used with or without transactions; performance is O(N) in the worst case.\n\nNOTE: When upgrading from the deprecated \"count\" method, some legacy operators are not supported\nand must be replaced:\n\n+-------------+--------------------------------+\n| Legacy      | Modern Replacement             |\n+=============+================================+\n| $where      | $expr (Requires MongoDB 3.6+)  |\n+-------------+--------------------------------+\n| $near       | $geoWithin with $center        |\n+-------------+--------------------------------+\n| $nearSphere | $geoWithin with $centerSphere  |\n+-------------+--------------------------------+\n"
                },
                {
                    "name": "Authentication",
                    "content": "The MONGODB-CR authentication mechanism was deprecated in MongoDB server 3.6 and removed in\nMongoDB server 4.0. The Perl driver is deprecating MONGODB-CR, but will not remove it until it\nno longer supports older servers.\n"
                },
                {
                    "name": "Query options",
                    "content": "The following query options are deprecated:\n\n*   maxScan -- deprecated in MongoDB server 4.0\n\n*   modifiers -- the old \"$\" prefixed modifiers have been replaced with explicit, equivalent\noptions for \"find\"\n\n*   snapshot -- deprecated in MongoDB server 4.0\n\nMD5 checksum for GridFS files\nThe \"md5\" field of GridFS documents is deprecated. Use of a checksum like MD5 has been redundant\nsince MongoDB added write concern and MD5 itself is no longer considered a secure digest\nfunction. A future release will remove the use of MD5 entirely. In the meantime, users can\ndisable MD5 digesting with the \"disablemd5\" option in MongoDB::GridFSBucket.\n\nUsers who wish to continue storing a digest are encouraged to compute their own digest using a\nfunction of their choice and store it under a user-defined key in the \"metadata\" field of the\nfile document.\n"
                },
                {
                    "name": "Classes",
                    "content": "These classes are superseded by type wrappers from BSON, as described earlier.\n\n*   MongoDB::BSON::Binary\n\n*   MongoDB::BSON::Regexp\n\n*   MongoDB::Code\n\n*   MongoDB::DBRef\n\n*   MongoDB::OID\n\n*   MongoDB::Timestamp\n"
                }
            ]
        },
        "REMOVED FEATURES": {
            "content": "Features deprecated in the v1 release have now been removed. Additionally, \"MongoDB::BSON\" has\nbeen removed in favor of BSON, as described earlier.\n",
            "subsections": [
                {
                    "name": "Configuration options",
                    "content": "*   \"dttype\"\n\n*   \"querytimeout\"\n\n*   \"sasl\"\n\n*   \"saslmechanism\"\n\n*   \"timeout\"\n\n*   $MongoDB::BSON::char\n\n*   $MongoDB::BSON::lookslikenumber\n"
                },
                {
                    "name": "Classes",
                    "content": "*   \"MongoDB::BSON\"\n\n*   \"MongoDB::GridFS\"\n\n*   \"MongoDB::GridFS::File\"\n\nFunctions/Methods\n*   From \"MongoDB\" - \"forcedouble\", \"forceint\"\n\n*   From \"MongoDB::BulkWrite\" and \"MongoDB::BulkWriteView\" - \"insert\", \"update\", \"remove\",\n\"removeone\"\n\n*   From \"MongoDB::Collection\" - \"insert\", \"batchinsert\", \"remove\", \"update\", \"save\", \"query\",\n\"findandmodify\", \"getcollection\", \"ensureindex\", \"dropindexes\", \"dropindex\",\n\"getindex\", \"validate\"\n\n*   From \"MongoDB::Database\" - \"eval\", \"lasterror\", \"getgridfs\"\n\n*   From \"MongoDB::CommandResult\" - \"result\"\n\n*   From \"MongoDB::Cursor\" - \"slaveokay\", \"count\"\n"
                }
            ]
        },
        "AUTHORS": {
            "content": "*   David Golden <david@mongodb.com>\n\n*   Rassi <rassi@mongodb.com>\n\n*   Mike Friedman <friedo@friedo.com>\n\n*   Kristina Chodorow <k.chodorow@gmail.com>\n\n*   Florian Ragwitz <rafl@debian.org>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n",
            "subsections": []
        }
    },
    "summary": "MongoDB::Upgrading - Deprecations and behavior changes from v1 to v2",
    "flags": [],
    "examples": [],
    "see_also": []
}