Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MongoDB::Upgrading::v1User Contributed Perl DocumentaMongoDB::Upgrading::v1(3)

       MongoDB::Upgrading::v1 -	Deprecations and behavior changes from v0 to

       version v2.2.2

       The v1 driver represents	a substantial step forward in functionality
       and consistency.	 There are many	areas where the	old API	has been
       deprecated or changed in	a backward breaking way.

       This document is	intended to help developers update their code to take
       into account API	changes	from the v0 driver to the v1 driver.

       Changes to the driver were deemed necessary to achieve certain goals:

       o   consistency (intra-driver) a	many parts of the v0 API were
	   inconsistent, behaving differently from method to method; the v1
	   API minimizes developer surprises by	improving consistency in
	   return types	and exception mechanisms.

       o   consistency (inter-driver) a	"next-generation" MongoDB drivers
	   across all languages	are converging on common APIs and common
	   behaviors; this simplifies developer	education and support, as
	   cross-language examples will	be similar.

       o   encapsulation a too many low-level, internal	operations were
	   exposed as part of the API, which complicates maintenance work; the
	   v1 API aims to minimize the "public surface"	available to
	   developers, allowing	faster future development keeping up with
	   MongoDB server enhancements with less risk of breakage.

       o   abstraction a many v0 methods returned raw server documents for
	   end-user code to inspect, which is brittle in the face of changes
	   in server responses over time; the v1 API uses result classes to
	   abstract the	details	behind standardized accessors.

       o   server compatibility	a some new features and	behavior changes in
	   the MongoDB server no longer	fit the	old driver design; the v1
	   driver transparently	supports both old and new servers.

       o   portability a the v0	driver had a large dependency tree and
	   substantial non-portable C code; the	v1 driver removes some
	   dependencies	and uses widely-used, well-tested CPAN modules in
	   place of custom C code where	possible; it lays the groundwork for a
	   future "pure-Perl optional" driver.

       o   round-trippable data	a the v0 BSON implementation could easily
	   change data types when round-tripping documents; the	v1 driver is
	   designed to round-trip data correctly whenever possible (within the
	   limits of Perl's dynamic typing).

   Moo instead of Moose
       The v1 driver uses Moo instead of Moose.	 This change results in	a
       slightly	faster driver and a significantly reduced deep dependency

   SSL and SASL
       The v0 driver required a	compiler and OpenSSL and libgsasl for SSL and
       SASL support, respectively.  The	v1 driver instead relies on CPAN
       modules "IO::Socket::SSL" and "Authen::SASL" for	SSL and	SASL support,

       SSL configuration is now	possible via the ssl attribute.

       Authentication configuration is described in "AUTHENTICATION" in

   MongoClient configuration
       New configuration options

       Several configuration options have been added, with particular emphasis
       on adding more granular control of timings and timeout behaviors.

       o   "auth_mechanism"

       o   "auth_mechanism_properties"

       o   "bson_codec"

       o   "connect_timeout_ms"

       o   "heartbeat_frequency_ms"

       o   "local_threshold_ms"

       o   "max_time_ms"

       o   "replica_set_name"

       o   "read_pref_mode"

       o   "read_pref_tag_sets"

       o   "server_selection_timeout_ms"

       o   "socket_check_interval_ms"

       o   "socket_timeout_ms"

       Replica set configuration

       Connecting to a replica set now requires	a replica set name, given
       either with the "replica_set_name" option for MongoDB::MongoClient or
       with the	"replicaSet" option in a connection string.  For example:

	   $client = MongoDB::MongoClient->new(
	       host => "mongodb://,",
	       replica_set_name	=> 'the_set',

	   $client = MongoDB::MongoClient->new(
	       host => "mongodb://,"

       Configuration options changed to	read-only

       Configuration options are changing to be	immutable to prevent
       surprising action-at-a-distance.	 (E.g. changing	an attribute value in
       some part of the	code changes it	for other parts	of the code that
       didn't expect it.)  Going forward, options may be set at
       MongoDB::MongoClient construction time only.

       The following options have changed to be	read-only:

       o   "db_name"

       o   "j"

       o   "password"

       o   "ssl"

       o   "username"

       o   "w"

       o   "wtimeout"

       Write concern may be overridden at the MongoDB::Database	and
       MongoDB::Collection level during	construction of	those objects.	For
       more details, see the later section on write concern changes.

       Mapping between connection string and configuration options

       Many configuration options may be set via a connection string URI in
       the "host" option.  In the v0 driver, the precedence between the
       connection string and constructor options was completely	inconsistent.
       In the v1 driver, options set via a connection string URI will take
       precedence over options passed to the constructor.  This	is consistent
       with with other MongoDB drivers (as well	as how DBI treats Data Source

       The list	of servers and ports as	well as	the optional "username",
       "password" and "db_name"	options	come directly from URI structure.
       Other options are parsed	as key-value parameters	at the end of the
       connection string.  The following table shows how connection string
       keys map	to configuration options in the	MongoDB::MongoClient:

	   Connection String Key	   MongoClient option
	   ---------------------------	   -----------------------------
	   authMechanism		   auth_mechanism
	   authMechanismProperties	   auth_mechanism_properties
	   connectTimeoutMS		   connect_timeout_ms
	   heartbeatFrequencyMS		   heartbeat_frequency_ms
	   journal			   j
	   localThresholdMS		   local_threshold_ms
	   maxTimeMS			   max_time_ms
	   readPreference		   read_pref_mode
	   readPreferenceTags		   read_pref_tag_sets
	   replicaSet			   replica_set_name
	   serverSelectionTimeoutMS	   server_selection_timeout_ms
	   socketCheckIntervalMS	   socket_check_interval_ms
	   socketTimeoutMS		   socket_timeout_ms
	   ssl				   ssl
	   w				   w
	   wTimeoutMS			   wtimeout

       The "readPreferenceTags"	and "authMechanismProperties" keys take	colon-
       delimited, comma-separated pairs:


       The "readPreferenceTags"	option may be repeated to build	up a list of
       tag set documents:


       Deprecated configuration	options

       Several options have been superseded, replaced or renamed for clarity
       and are thus deprecated and undocumented.  They are kept	for a limited
       degree of backwards compatibility.  They	will be	generally be used as
       fallbacks for other options.  If	any were read-write, they have also
       been changed to read-only.

       o   "dt_type" a see "BSON encoding changes" for details.

       o   "query_timeout" a replaced by "socket_timeout_ms"; if set, this
	   will	be used	as a fallback default for "socket_timeout_ms".

       o   "sasl" aA superseded	by "auth_mechanism"; if	set, this will be used
	   along with "sasl_mechanism" as a fallback default for

       o   "sasl_mechanism" aA superseded by "auth_mechanism"; if set, this
	   will	be used	as a fallback default for "auth_mechanism".

       o   "timeout" a replaced	by "connect_timeout_ms"; if set, this will be
	   used	as a fallback default for "connect_timeout_ms".

       These will be removed in	a future major release.

       Configuration options removed

       Some configuration options have been removed entirely, as they no
       longer serve any	purpose	given changes to server	discovery, server
       selection and connection	handling:

       o   "auto_connect"

       o   "auto_reconnect"

       o   "find_master"

       o   "max_bson_size"

       As described further below in the "BSON encoding	changes" section,
       these BSON encoding configuration options have been removed as well:

       o   "inflate_dbrefs"

       o   "inflate_regexps"

       Removed configuration options will be ignored if	passed to the
       MongoDB::MongoClient constructor.

   Lazy	connections and	reconnections on demand
       The improved approach to	server monitoring and selection	allows all
       connections to be lazy.	When the client	is constructed,	no connections
       are made	until the first	network	operation is needed.  At that time,
       the client will scan all	servers	in the seed list and begin regular
       monitoring.  Connections	that drop will be re-established when needed.

       IMPORTANT: Code that used to rely on a fatal exception from
       "MongoDB::MongoClient->new" when	no mongod is available will break.
       Instead,	users are advised to just conduct their	operations and be
       prepared	to handle errors.

       For testing, users may wish to run a simple command to check that a
       mongod is ready:

	   use Test::More;

	   plan	skip_all => 'no	mongod'	unless eval {

	   # NEW WAY 1:	with MongoDB::MongoClient
	   plan	skip_all => 'no	mongod'	unless eval {
		   [ ismaster => 1 ]

	   # NEW WAY 2:	with MongoDB and connect
	   plan	skip_all => 'no	mongod'	unless eval {
	       MongoDB->connect->db('admin')->run_command([ ismaster =>	1 ])

       MongoDB::MongoClient for	details.

   Exceptions are the preferred	error handling approach
       In the v0 driver, errors	could be indicated in various ways:

       o   boolean return value

       o   string return value is an error; hash ref is	success

       o   document that might contain an 'err', 'errmsg' or '$err' field

       o   thrown string exception

       Regardless of the documented error handling, every method that involved
       a network operation would throw an exception on various network errors.

       In the v1 driver, exceptions objects are	the standard way of indicating
       errors.	The exception hierarchy	is described in	MongoDB::Error.

   Cursors and query responses
       In v0, MongoDB::Cursor objects were used	for ordinary queries as	well
       as the query-like commands aggregation and parallel scan.  However,
       only cursor iteration commands worked for aggregation and parallel scan
       "cursors"; the rest of the MongoDB::Cursor API didn't apply and was

       In v1, all result iteration is done via the new MongoDB::QueryResult
       class.  MongoDB::Cursor is now just a thin wrapper that holds query
       parameters, instantiates	a MongoDB::QueryResult on demand, and passes
       iteration methods through to the	query result object.

       This significantly simplifies the code base and should have little end-
       user visibility unless users are	specifically checking the return type
       of queries and query-like methods.

       The "explain" cursor method no longer resets the	cursor.

       The "slave_okay"	cursor method now sets the "read_preference" to
       'secondaryPreferred' or clears it to 'primary'.

       The "snapshot" cursor method now	requires a boolean argument, allowing
       it to be	turned on or off before	executing the query.  Calling it
       without an argument (as it was in v0) is	a fatal	exception.

       Parallel	scan "cursors" are now QueryResult objects, with the same
       iteration methods as in v0.

       The $MongoDB::Cursor::slave_okay	global variable	has been removed as
       part of the revision to read preference handling.  See the read
       preferences section below for more details.

       The $MongoDB::Cursor::timeout global variable has also been removed.
       Timeouts	are set	during MongoDB::MongoClient configuration and are
       immutable.  See the section on configuration changes for	more.

   Aggregation API
       On MongoDB 2.6 or later,	"aggregate" always uses	a cursor to execute
       the query.  The "batchSize" option has been added (but has no effect
       prior to	2.6).  The "cursor" option is deprecated.

       The return types	for the	"aggregate" method are now always QueryResult
       objects,	regardless of whether the aggregation uses a cursor internally
       or is an	'explain'.

       NOTE: To	help users with	a 2.6 mongos and mixed version shards with
       versions	before 2.6, passing the	deprecated 'cursor' option with	a
       false value will	disable	the use	of a cursor.  This workaround is
       provided	for convenience	and will be removed when 2.4 is	no longer

   Read	preference objects and the read_preference method
       A new MongoDB::ReadPreference class is used to encapsulate read
       preference attributes.  In the v1 driver, it is constructed from	the
       "read_pref_mode"	and "read_pref_tag_sets" attributes on

	       read_pref_mode => 'primaryPreferred',
	       read_pref_tag_sets => [ { dc => 'useast'	}, {} ],

       The old "read_preference" method	to change the read preference has been
       removed and trying to set a read	preference after the client has	been
       created is a fatal error.  The old mode constants PRIMARY, SECONDARY,
       etc. have been removed.

       The "read_preference" method now	returns	the MongoDB::ReadPreference
       object generated	from "read_pref_mode" and "read_pref_tag_sets".

       It is inherited by MongoDB::Database, MongoDB::Collection, and
       MongoDB::GridFS objects unless provided as an option to the relevant
       factory methods:

	   my $coll = $db->get_collection(
	       "foo", {	read_preference	=> 'secondary' }

       Such "read_preference" arguments	may be a MongoDB::ReadPreference
       object, a hash reference	of arguments to	construct one, or a string
       that represents the read	preference mode.

       MongoDB::Database and MongoDB::Collection also have "clone" methods
       that allow easy alteration of a read preference for a limited scope.

	   my $coll2 = $coll->clone( read_preference =>	'secondaryPreferred' );

       For MongoDB::Cursor, the	"read_preference" method sets a	hidden read
       preference attribute that is used for the query in place	of the
       MongoDB::MongoClient default "read_preference" attribute.  This means
       that calling "read_preference" on a cursor object no longer changes the
       read preference globally	on the client a	the read preference change is
       scoped to the cursor object only.

   Write concern objects and removing the safe argument
       A new MongoDB::WriteConcern class is used to encapsulate	write concern
       attributes.  In the v1 driver, it is constructed	from the "w",
       "wtimeout" and "j" attributes on	MongoDB::MongoClient:

	   MongoDB::MongoClient->new( w	=> 'majority', wtimeout	=> 1000	);

       The "write_concern" method now returns the MongoDB::WriteConcern	object
       generated from "w", "wtimeout" and "j".

       It is inherited by MongoDB::Database, MongoDB::Collection, and
       MongoDB::GridFS objects unless provided as an option to the relevant
       factory methods:

	   $db = $client->get_database(
	       "test", { write_concern => { w => 'majority' } }

       Such "write_concern" arguments may be a MongoDB::WriteConcern object, a
       hash reference of arguments to construct	one, or	a string that
       represents the "w" mode.

       MongoDB::Database and MongoDB::Collection also have "clone" methods
       that allow easy alteration of a write concern for a limited scope.

	   my $coll2 = $coll->clone( write_concern => {	w => 1 } );

       The "safe" argument is no longer	used in	the new	CRUD API.

   Authentication based	only on	configuration options
       Authentication now happens automatically	on connection during the
       "handshake" with	any given server based on the auth_mechanism

       The old "authenticate" method in	MongoDB::MongoClient has been removed.

   Bulk	API
       Bulk method names changed to match CRUD API

       Method names match the new CRUD API, e.g. "insert_one" instead of
       "insert"	and so one.  The legacy	names are deprecated.

       Bulk insertion

       Insertion via the bulk API will NOT insert an "_id" into	the original
       document	if one does not	exist.	Previous documentation was not
       specific	whether	this was the case or if	the "_id" was added to the
       document	sent to	the server.

       Bulk write results

       The bulk	write results class has	been renamed to
       MongoDB::BulkWriteResult.  It keeps "MongoDB::WriteResult" as an	empty
       superclass for some backwards compatibility so that
       "$result->isa("MongoDB::WriteResult")" will continue to work as

       The attributes have been	renamed	to be consistent with the new CRUD
       API.  The legacy	names are deprecated, but are available	as aliases.

       The MongoDB::GridFS class now has explicit read preference and write
       concern attributes inherited from MongoDB::MongoClient or
       MongoDB::Database, just like MongoDB::Collection.  This means that
       GridFS operations now default to	an acknowledged	write concern, just
       like collection operations have been doing since	v0.502.0 in 2012.

       The use of "safe" is deprecated.

       Support for ancient, undocumented positional parameters circa 2010 has
       been removed.

   Low-level functions removed
       Low-level driver	functions have been removed from the public API.

   MongoDB::Connection removed
       The "MongoDB::Connection" module	was deprecated in v0.502.0 and has
       been removed.

   BSON	encoding changes
       In the v1 driver, BSON encoding and decoding have been encapsulated
       into a MongoDB::BSON codec object.  This	can be provided	at any level,
       from MongoDB::MongoClient to MongoDB::Collection.  If not provided, a
       default will be created that behaves similarly to the v0
       encoding/decoding functions, except for the following changes.

       $MongoDB::BSON::use_binary removed

       Historically, this defaulted to false, which corrupts binary data when
       round tripping.	Retrieving a binary data element and re-inserting it
       would have resulted in a	field with UTF-8 encoded string	of binary

       Going forward, binary data will be returned as a	MongoDB::BSON::Binary
       object.	A future driver	may add	the ability to control decoding	to
       allow alternative representations.

       $MongoDB::BSON::use_boolean removed

       This global variable never worked. BSON booleans	were always
       deserialized as boolean objects.	 A future driver may add the ability
       to control boolean representation.

       $MongoDB::BSON::utf8_flag_on removed

       In order	to ensure round-tripping of string data, this variable is
       removed.	 BSON strings will always be decoded to	Perl character
       strings.	 Anything else risks double-encoding a round-trip.

       $MongoDB::BSON::looks_like_number and $MongoDB::BSON::char deprecated
       and re-scoped

       In order	to allow a future driver to provide more flexible user-
       customized encoding and decoding, these global variables	are
       deprecated.  If set, they will be examined during
       "MongoDB::MongoClient->new()" to	set the	configuration of a default
       MongoDB::BSON codec (if one is not provided).  Changing them later will
       NOT change the behavior of the codec object.

       "MongoDB::MongoClient" option "inflate_regexps" removed

       Previously, BSON	regular	expressions decoded to "qr{}" references by
       default and the "MongoDB::MongoClient" "inflate_regexps"	option was
       available to decode instead to MongoDB::BSON::Regexps.

       Going forward in	the v1.0.0 driver, for safety and consistency with
       other drivers, BSON regular expressions always decode to
       MongoDB::BSON::Regexp objects.

       "MongoDB::MongoClient" option "inflate_dbrefs" removed

       The "inflate_dbrefs" configuration option has been removed and replaced
       with a "dbref_callback" option in MongoDB::BSON.

       By default, the "MongoDB::MongoClient" will create a MongoDB::BSON
       codec that will construct MongoDB::DBRef	objects.  This ensures that
       DBRefs properly round-trip.

       "MongoDB::MongoClient" option "dt_type" deprecated and changed to read-

       The "dt_type" option is now only	takes effect if	"MongoDB::MongoClient"
       constructs a MongoDB::BSON codec	object.	 It has	been changed to	a
       read-only attribute so that any code that relied	on changing "dt_type"
       after constructing a "MongoDB::MongoClient" object will fail instead of
       being silently ignored.

       Int32 vs	Int64 encoding changes

       On 64-bit Perls,	integers that fit in 32-bits will be encoded as	BSON
       Int32 (whereas previously these were always encoded as BSON Int64).

       Math::BigInt objects will always	be encoded as BSON Int64, which	allows
       users to	force 64-bit encoding if desired.

       Added support for Time::Moment

       Time::Moment is a much faster replacement for the venerable DateTime
       module.	The BSON codec will serialize Time::Moment objects correctly
       and can use that	module as an argument for the "dt_type"	codec

       Added support for encoding common JSON boolean classes

       Most JSON libraries on CPAN implement their own boolean classes.	 The
       following libraries boolean types will now encode correctly as BSON

       o   JSON::XS

       o   Cpanel::JSON::XS

       o   JSON::PP

       o   JSON::Tiny

       o   Mojo::JSON

   DBRef objects
       The "fetch" method and related attributes "client", "verify_db",	and
       "verify_coll" have been removed from MongoDB::DBRef.

       Providing a "fetch" method was inconsistent with	other MongoDB drivers,
       which either never provided it, or have dropped it in the next-
       generation drivers.  It requires	a "client" attribute, which tightly
       couples BSON decoding to	the client model, causing circular reference
       issues and triggering Perl memory bugs under threads.  Therefore, the
       v1.0.0 driver no	longer support fetching	directly from MongoDB::DBRef;
       users will need to implement their own methods for dereferencing.

       Additionally, the "db" attribute	is now optional, consistent with the
       specification for DBRefs.

       Also, all attributes ("ref", "id" and "db") are now read-only,
       consistent with the move	toward immutable objects throughout the

       To support round-tripping DBRefs	with additional	fields other than
       $ref, $id and $db, the DBRef class now has an attribute called "extra".
       As not all drivers support this feature,	using it for new DBRefs	is not

       Deprecated options and methods may be removed in	a future release.
       Their documentation has been removed to discourage ongoing use.	Unless
       otherwise stated, they will continue to behave as they previously did,
       allowing	a degree of backwards compatibility until code is updated to
       the new MongoDB driver API.

       o   eval	aA MongoDB 3.0 deprecated the '$eval' command, so this helper
	   method is deprecated	as well.

       o   last_error a	Errors are now indicated via exceptions	at the time
	   database commands are executed.

       o   insert, batch_insert, remove, update, save, query and
	   find_and_modify a A new common driver CRUD API replaces these
	   legacy methods.

       o   get_collection aA This method implied that collections could	be
	   contained inside collection.	 This doesn't actually happen so it's
	   confusing to	have a Collection be a factory for collections.	 Users
	   who want nested namespaces should be	explicit and create them off
	   Database objects instead.

       o   ensure_index, drop_indexes, drop_index, get_index a A new
	   MongoDB::IndexView class is accessible through the "indexes"
	   method, offering greater consistency	in behavior across drivers.

       o   validate a The return values	have changed over different server
	   versions, so	this method is risky to	use; it	has more use as	a one-
	   off tool, which can be accomplished via "run_command".

       o   result a has	been renamed to	'output' for clarity

       o   slave_ok a this modifier method is superseded by the
	   'read_preference' modifier method

       o   count a this	is superseded by the "MongoDB::Collection#count" in
	   MongoDB::Collection count method.  Previously, this ignored
	   skip/limit unless a true argument was passed, which was a bizarre,
	   non-intuitive and inconsistent API.

   MongoDB::BulkWrite and MongoDB::BulkWriteView
       o   insert a renamed to 'insert_one' for	consistency with CRUD API

       o   update a renamed to 'update_many' for consistency with CRUD API

       o   remove a renamed to 'delete_many' for consistency with CRUD API

       o   remove_one a	renamed	to 'delete_one'	for consistency	with CRUD API

       o   David Golden	<>

       o   Rassi <>

       o   Mike	Friedman <>

       o   Kristina Chodorow <>

       o   Florian Ragwitz <>

       This software is	Copyright (c) 2020 by MongoDB, Inc.

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.32.1			  2020-08-13	     MongoDB::Upgrading::v1(3)


Want to link to this manual page? Use this URL:

home | help