NAME
MongoDB::Upgrading - Deprecations and behavior changes from the v0 driver
VERSION
version v0.999.998.5
DESCRIPTION
While the v1 driver preserves backwards compatibility in most of the API, there are still some 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.
WORK-IN-PROGRESS
This document is a work in progress during the v1 development cycle. It offers a best-efforts snapshot of changes at a point in time.
RATIONALE
While backwards-compatibility is important, changes to the driver were sometimes deemed necessary to achieve certain goals:
consistency – 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 types.
simplification – many configuration settings, like write concern, were split across multiple attributes, making them hard to manage collectively or consistently as semantics changed across server versions.
encapsulation – 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.
abstraction – many methods returned raw server documents for end-user code to inspect, which is brittle in the face of changes by the server over time; the v1 API uses objects to abstract the details behind standard method calls.
compatibility – some new features or changes in the MongoDB server, like the client authentication model, no longer fit the old driver design.
portability – the v0 driver had a large dependency tree and required a compiler and various libraries; the v1 driver shrinks the dependency tree substantially and uses widely-used CPAN modules in place of custom C code when possible.
INSTALLATION AND DEPENDENCY CHANGES
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, respectively.
SSL configuration is now possible via the ssl attribute.
Authentication configuration is described in "AUTHENTICATION" in MongoDB::MongoClient.
BEHAVIOR CHANGES
MongoClient configuration immutability
Attributes are changing to be immutable to prevent global behavior changes. (E.g. changing an attribute value in some part of the code changes it for all parts of the code.)
As of Alpha 2, the following attributes are now immutable:
sslread_preference– but read preference can be set at the database and collection level for localized needs. See a subsequent section for more.
Other attributes will be made immutable in subsequent alpha releases as internal options handling is revised.
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.
See SERVER SELECTION and SERVER MONITORING in MongoDB::MongoClient for details.
Exceptions are the preferred error handling approach
In the v0 driver, errors could be indicated in various ways:
boolean return value
string return value is an error; hash ref is success
document that might contain an 'err', 'errmsg' or '$err' field
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 fatal.
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 simplifes 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_ok cursor method now sets the read_preference to 'secondaryPreferred' or clears it to 'primary'.
Parallel scan "cursors" are now QueryResult objects, with the same iteration methods as in v0.
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 supported.
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 set as an immutable attribute on MongoDB::MongoClient:
MongoDB::MongoClient->new( ..., read_preference => { ... } );If provided as a hash reference, it will be coerced to a MongoDB::ReadPreference object (and validated). You can also provide it as a string that will be coerced to a read preference mode.
MongoDB::MongoClient->new( ..., read_preference => 'primaryPreferred' );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.
As read_preference is now the name of an attribute, the return value is the value of the attribute.
For localized changes, the get_database and get_collection methods both take optional parameters that allow setting a read preference.
my $coll = $db->get_collection(
"foo", { read_preference => 'secondary' }
);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 – the read preference change is scoped to the cursor object only.
Write concern objects and removing the safe option
A new MongoDB::WriteConcern class is used to encapsulate write concern attributes. In the v1 driver, it is set as an immutable attribute on MongoDB::MongoClient:
MongoDB::MongoClient->new( ..., write_concern => { ... } );If provided as a hash reference, it will be coerced to a MongoDB::WriteConcern object (and validated).
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' } }
);
$coll = $db->get_collection(
"people", { write_concern => { w => 1 } }
);
$gridfs = $db->get_gridfs(
"fs", { write_concern => { w => 0 } }
);The safe option is no longer used in new method APIs.
Authentication
Authentication now happens automatically on connection during the "handshake" with any given server based on the auth_mechanism attribute.
The authenticate method in MongoDB::MongoClient is deprecated and the behavior has changed slightly. When called, all connections are closed, and the authentication configuration is reset as if the arguments had been used in the constructor initially, and at least one connection is reopened to ensure authentication succeeds (or else an exception is thrown).
In a future release, this method will be removed entirely and authentication options will only be allowed as constructor arguments.
Bulk insertion
Insertion via the bulk API will 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 a clone.
As the regular insertion methods from MongoDB::Collection modified the original, that was adopted for the Bulk API as well.
All methods are now specifically documented as modifying the original.
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 expected.
The attributes have been renamed to be consistent with the new CRUD API. The legacy names are deprecated, but are available as aliases.
GridFS
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.
$MongoDB::BSON::use_boolean removed
This global variable never worked. BSON booleans were always deserialized as boolean objects. A future driver will add the ability to control boolean deserialization without relying on global variables.
DEPRECATIONS
Deprecated options and methods may be removed in a future release.
Configuration options
auto_connect, auto_reconnect, find_master
These attributes no longer have any effect. The driver always attempts to connect or reconnect on demand and to find an appropriate server.
sasl, sasl_mechanism
There are a richer set of authentication options than these legacy options allowed. They are controlled through the auth_mechanism and auth_mechanism_properties attributes. These are kept for backwards compatibility only.
Methods by module
MongoDB::MongoClient
authenticate – Authentication parameters should now be given as client attributes. See "AUTHENTICATED" in MongoDB::MongoClient for more.
read_preference — Read preferences should now be given as a client attribute. The use of the
read_preferencemethod as a mutator is deprecated.
MongoDB::Database
last_error — Errors are now indicated via exceptions at the time database commands are executed.
MongoDB::Collection
insert, batch_insert, remove, update, query and find_and_modify — A new common driver CRUD API replaces these legacy methods.
get_collection — 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 will be explicit and create them off Database objects instead.
MongoDB::CommandResult
result — has been renamed to 'output' for clarity
AUTHORS
David Golden <david@mongodb.com>
Mike Friedman <friedo@mongodb.com>
Kristina Chodorow <kristina@mongodb.com>
Florian Ragwitz <rafl@debian.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2015 by MongoDB, Inc..
This is free software, licensed under:
The Apache License, Version 2.0, January 2004