NAME

MongoDB::Upgrading - Deprecations and behavior changes from the v0 driver

VERSION

version v0.999.998.4

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:

• ssl

• read_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::Collection removed

The MongoDB::Collection 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_preference method 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.

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

cpanm MongoDB

perl -MCPAN -e shell
install MongoDB