MongoDB-v1.0.0

Changes for version v1.0.0 - 2015-09-21

!!! Incompatible Changes !!!
- The v1.0.0 driver includes numerous incompatible changes; users are STRONGLY encouraged to read MongoDB::Upgrading for advice on upgrading applications written for the 'v0' driver.
- PERL-221 The 'inflate_regexps' MongoDB::MongoClient option has been removed. BSON regular expressions always decode to MongoDB::BSON::Regexp objects. This ensure safety and consistency with other drivers.
- PERL-330 The driver now uses pure-Perl networking; SSL and SASL now implemented via optional CPAN modules IO::Socket::SSL and Authen::SASL.
- PERL-442 Connection string options have revised to match MongoClient options; connection string options always take precedence over MongoClient constructor arguments.
- PERL-470 The MongoDB::Cursor globals "slave_ok" and "timeout" no longer have any effect and have been removed.
- PERL-471 The MongoDB::Cursor 'snapshot' method now requires a boolean argument.
- PERL-505 When bulk inserting a document without an '_id' field, the _id will be added during BSON encoding, but the original document will NOT be changed. (This was the case for regular insertion in the v0.x series, but not for the Bulk API.)
- PERL-519 The $MongoDB::BSON::use_binary global variable has been removed. Binary data always decodes to MongoDB::BSON::Binary objects (which now overload stringification). This ensures that binary data will correctly round-trip.
- PERL-520 The $MongoDB::BSON::utf8_flag_on global variable has been removed. BSON strings will always be decoded to Perl character strings. This ensures that string data will correctly round-trip.
- PERL-523 Requires a replica set name explicitly to connect to a replica set. Connecting to a single host is always in a 'direct' mode otherwise.
- PERL-546 MongoDB::DBRef objects no longer have a 'fetch' method or 'client' attribute. This is consistent with the design of the MongoDB drivers for other language. For the Perl driver, specifically, it decouples the BSON model from the MongoClient model, eliminates a circular reference, and avoid Perl memory bugs using weak references under threads.
- MongoDB::MongoClient configuration options are now read-only and may not be modified after client construction.
- The $MongoDB::BSON::looks_like_number and $MongoDB::BSON::char global variables now ONLY have an effect at MongoDB::MongoClient construction. Changing them later does not change BSON encoding. Both are deprecated as well and should not be used in new code. Instead, the enhanced MongoDB::BSON codec class has attributes that encapsulate these behaviors.
- The 'dt_type' MongoDB::MongoClient option has been deprecated and made read-only. It now only takes effect if C<MongoDB::MongoClient> constructs a MongoDB::BSON codec object and is read-only so that any code that relied on changing it after client construction will fail rather that being silently ignored.
- The 'inflate_dbrefs' MongoDB::MongoClient option has been removed. By default, dbrefs are always inflated to MongoDB::DBRef objects.
- The MongoDB::MongoClient 'read_preference' method is no longer a mutator. It is now only an accessor for a MongoDB::ReadPreference object constructed from 'read_preference_mode' and 'read_preference_tag_sets'.
- The legacy read preference constants in MongoDB::MongoClient have been removed, as they are no longer are used with the new MongoDB::ReadPreference class.
- The MongoDB::MongoClient 'authenticate' method has been removed; credentials now must be passed via configuration options and authentication is automatic on server connection.
- The MongoDB::Cursor class has been split. Actual result iteration is done via a new MongoDB::QueryResult class.
- MongoDB::Error exception objects are now used consistently throughout the driver, replacing other error mechanism and raw "die" calls.
- The MongoDB::WriteResult class was renamed to MongoDB::BulkWriteResult.
- The long-deprecated MongoDB::Connection class has been removed.
- Low-level client functions have been removed.
*** Deprecations ***
- PERL-398 The MongoDB::MongoClient 'timeout' and 'query_timeout' options are deprecated in favor of new, more explicit 'connect_timeout_ms' and 'socket_timeout_ms' options.
- PERL-424 The MongoDB::Cursor 'count' method has been deprecated.
- PERL-464 The MongoDB::Database 'last_error' method has been deprecated.
- PERL-507 MongoDB::Collection 'get_collection' method is deprecated; it implied sub-collections, which don't actually exist in MongoDB.
- PERL-511 The old CRUD method names for the MongoDB::Bulk API have been deprecated in favor of names that match the new MongoDB::Collection CRUD API.
- PERL-516 The MongoDB::Collection index management methods have been deprecated in favor of the new MongoDB::IndexView API.
- PERL-533 The MongoDB::Collection 'save' method has been deprecated.
- PERL-534 The MongoDB::Collection 'validate' method has been deprecated.
- PERL-559 The MongoDB::Database 'eval' method has been deprecated, as the MongoDB server version 3.0 deprecated the '$eval' command.
- The MongoDB::MongoClient 'sasl' and 'sasl_mechanism' config options have been deprecated in favor of the more generic 'auth_mechanism' option.
- Legacy MongoDB::Collection CRUD methods (insert, update, etc.) have been deprecated in favor of new CRUD API methods.
- MongoDB::CommandResult changed the name of the accessor for the document returned by the server to 'output' instead of 'result' for clarity. The 'result' method is deprecated.
- As mentioned above, 'dt_type', '$MongoDB::BSON::looks_like_number' and '$MongoDB::BSON::char' have been deprecated in addition to their other behavior changes.
Additions
- PERL-93 Implemented awaitData cursor support.
- PERL-135 Added the ability to set write_concern at database and collection level, rather than only in MongoDB::MongoClient.
- PERL-233 Implemented SSL certificate support via IO::Socket::SSL options.
- PERL-375 Added support for cursor options to the MongoDB::Collection 'find_one' method.
- PERL-378 Implemented the cross-driver Server Discovery and Monitoring specification.
- PERL-379 Implemented the cross-driver Server Selection specification.
- PERL-406 Allowed count methods to work with query hints.
- PERL-408 Implemented SCRAM-SHA-1 and revised handshake for MongoDB 3.0 and later.
- PERL-413 Added max_time_ms as a MongoDB::MongoClient configuration option to set a default for database and collection objects.
- PERL-422 Added support for specifying read preferences in the connection string URI.
- PERL-465 Added support for arbitrary options on index creation.
- PERL-466 Added the ability to set read preference at the database and collection level.
- PERL-486 Added 'has_modified_count' method to MongoDB::UpdateResult and MongoDB::BulkWriteResult to ease detection of when that attribute is supported by a server or not.
- PERL-490 Added 'list_collections' method to MongoDB::Database.
- PERL-500 Added 'topology_status' method to MongoDB::MongoClient.
- PERL-502 and PERL-503 Implemented new common driver CRUD API specification in MongoDB::Collection.
- PERL-506 Added support for serializing/deserializing Time::Moment objects.
- PERL-515 Added new MongoDB::IndexView API.
- PERL-554 Implemented 'server_selection_try_once' configuration option on MongoDB::MongoClient.
- Added an optional read preference argument to 'run_command'.
- Added 'db' and 'coll' methods as aliases for 'get_database' and 'get_collection' on MongoDB::MongoClient and MongoDB::Database, respectively.
- Added the 'get_namespace' method to MongoDB::MongoClient (with the alias 'ns'), to get a MongoDB::Collection object directly from a MongoDB::MongoClient object.
- Added a 'connect' class method to the MongoDB class for syntactic sugar to create a client object.
- Added a 'with_codec' method to MongoDB::Collection for easier localized changes to BSON codec attributes.
- Added a 'reconnect' method to MongoClient to handle reconnection after a fork or thread spawn.
- Added support for correctly encoding boolean objects from JSON::XS, Cpanel::JSON::XS, JSON::PP, JSON::Tiny and Mojo::JSON.
Bug Fixes
- PERL-146 Normalized server addresses to lower case.
- PERL-401 Fixed index creation to always have a non-zero write concern.
- PERL-409 Added missing declarations for MinGW on Windows.
- PERL-410 Fixed BSON encoding/decoding to detect and throw and error if invalid UTF-8 is detected.
- PERL-429 Fixed read preference tag sets logic.
- PERL-435 Switched to http-style SSL certificate name validation.
- PERL-454 Prevented warnings when creating BSON datetimes at the epoch.
- PERL-477 Fixed list_indexes and list_collections when responses are too big to fit in a single database response.
- PERL-480 Fixed GridFS bug: retrieving a GridFS file now throws an error if no chunks exist instead of returning an empty string.
- PERL-489 Fixed fatal BSON encoding bug serializing references to dual-vars.
- PERL-531 Bulk update/replace documents would not validate properly when $MongoDB::BSON::char was not '$'. While that functionality has moved to the MongoDB::BSON codec instead of the global variable, all update/replace documents (bulk and CRUD API) are now validated after key munging.
- PERL-536 Fixed GridFS to stop throwing an error when a known empty file has no chunks; errors will still be thrown if a non-empty file has no chunks.
- PERL-540 Fixed memory leak in DateTime::Tiny inflation.
- PERL-543 Fixed a bug serializing undef from Tie::IxHash objects.
- PERL-556 Fixed serialization of thread-shared variables.
- Fixed t/cursor.t for new explain format.
- Removed storage engine dependent code and tests.
- Fixed MSVC compilation: fix unused vars and statements before declarations; removed unused, but problematic bcon.c and bcon.h; use Perl memory alloc functions instead of malloc.
- Made conflicting 'multi' and 'multiple' update options fatal.
- Fixed use of slave_ok and $readPreference for communicating read preferences to a mongos.
- Fixed t/database.t for change in server error message.
- Ensured topology type is correct whenever a server is marked unavailable.
- Fixed incorrect 'matched_count' result attribute for upserts.
- Fixed failing BSON element tests on 32-bit perls.
- Fixed bug in MongoDB::MongoClient::database_names error handling.
- Use of -Wall compiler flag during smoke testing has been restricted to gcc compilers, only.
- Fixed encoding to raise an error if an array-reference document contains duplicate keys.
- Stopped encoding scalar-ref objects as BSON BINARY type. (Throws an error instead about an unhandled type.)
- Fixed incorrect configuration test for GCC atomic operations.
- Fixed bug numifying wtimeout in write concern serialization.
- Fixed BSON double tests on Perls with long-doubles enabled.
- Fixed t/gridfs to work around a bug in MongoDB 3.1.2.
- Fixed a number of XS memory leaks from non-mortalized variables during BSON encoding.
Changes
- PERL-127 Integers that fit in 32-bits are now encoded as BSON Int32; larger integers are encoded as BSON Int64; Math::BigInt objects are always encoded as BSON Int64.
- PERL-331 The MongoDB::BSON package is now a full class, implementing a BSON encoder-decoder (codec). It can be supplied as an attribute to MongoDB::MongoClient, MongoDB::Database and MongoDB::Collection objects.
- PERL-488 MongoDB::WriteConcern method 'is_safe' renamed to 'is_acknowledged'.
- PERL-527 A database name is now optional for MongoDB::DBRef, which is consistent with the DBRef specification.
- PERL-529 Connection string option keys are now parsed case-insensitively.
- PERL-530 The driver now warns on unsupported connection options.
- PERL-550 DBRefs allow extra fields (for compatibility); this is not recommended for new DBRefs.
- Renamed DocumentSizeError to a more general general DocumentError.
- MongoDB::Collection attributes that should not be set in the constructor have been made private, but with public accessors for backwards compatibility. Private attributes that are set in the constructor (e.g. 'database') are now public.
- Failure to create indexes when constructing a GridFS object are ignored rather than a fatal error.
- Calls to Carp::confess() or die() have been replaced with exceptions from MongoDB::Error subclasses, typically MongoDB::UsageError.
- Generic MongoDB::Error exceptions have been replaced with subclasses that have a specific, documented purpose, including: MongoDB::AuthError, MongoDB::GridFSError, MongoDB::InternalError and MongoDB::UsageError.
- Configuration options representing times have stricter validation such that options that should be non-negative will raise exceptions when given negative numbers.
- BSON code derived from libbson has been updated to libbson 1.1.7.
- Returns MongoDB::UnacknowledgedResult from unacknowledged writes (i.e. { w => 0 } write concern) instead of the corresponding result object (i.e. MongoDB::InsertResult for inserts).
- Loads Authen::SCRAM::Client only on demand, as its Unicode module dependencies are costly when not needed.
- MongoDB::QueryResult attributes have become private, as they are an implementation detail and not intended for end-users to inspect.
- Aborts Makefile.PL on Windows before Vista/2008 for better error message than subsequent compilation/test failures.
- Changes default connect_timeout_ms to 10,000.
- Credential details omitted from usage error messages.
Documentation
- PERL-423 Improved documentation of cursor snapshot mode, as it doesn't do what many people think it does.
- PERL-425 Documented deprecation of the 'drop_dups' option for index creation.
- PERL-524 Updated legacy author emails in docs and metadata.
- Added contributors section to MongoDB main documentation based on git commit logs.
- Added MongoDB::Upgrading document with changes from v0.x.
- Documented how to disable returning _id from queries.
- Rearranged Collection and Database documentation.
- Corrected errors in MongoDB::Cursor documentation.
Prerequisites
- Added core modules IO::Socket and MIME::Base64 to the dependency list for completeness.
- Added Class::XSAccessor, Moo and Type::Tiny::XS.
- Enforced minimum versions for configuration requirements.
- Moved DateTime::Tiny from a test_requires dependency to a test_recommends dependency.
- Removed core modules File::Copy, File::Path and File::Spec from the list of test dependencies.
- Removed Class::MOP::Class as an explicit dependency (still used internally by Moose).
- Removed Data::Types and Data::Dump as test dependencies.
- Removed File::Slurp.
- Removed JSON module in favor of JSON::MaybeXS.
- Removed Moose, Syntax::Keyword::Junction and Throwable.
- Removed Test::Warn.
- Updated Path::Tiny minimum version to 0.054 (rather than unspecified).
- Updated IO::Socket requirement on Windows to 1.31.
- Updated Authen::SCRAM::Client minimum version to 0.003.
Removals
- PERL-467 Removed outdated MongoDB::Indexing document.
- PERL-497 The $MongoDB::BSON::use_boolean never worked; BSON boolean values were always deserialized as boolean.pm objects. Rather than "fix" this and break people's code, the option has been removed and documented as such.
- The MongoDB::MongoClient 'auto_connect', 'auto_reconnect', and 'find_master' methods have been removed, as server discovery and selection is now automatic.
Testing
- PERL-371 Added tests for parsing localhost:port.
- PERL-492 Implemented server selection tests.
- PERL-513 Added maxTimeMS tests for CRUD API methods.
- Changed text index test to use $text operator, not text command (which was removed in MongoDB 3.0).
- Changed t/max_time_ms.t to skip unless $ENV{FAILPOINT_TESTING} is true.
- Reduced number of threads used in threads testing to avoid out of memory errors on memory constrained systems.
~ Internal changes ~
- PERL-133 Implemented a test that client can connect to replica sets without primary.
- PERL-259 Implemented write commands for MongoDB 2.6+ (i.e. doing writes via database commands versus via the wire protocol with OP_INSERT, OP_UPDATE, etc.).
- PERL-325 Updated vendored ppport.h to version 3.31.
- PERL-433 Updated listCollections to use command form on 3.0 servers.
- PERL-434 Updated listIndexes to use command form on 3.0 servers.
- PERL-436 Bumped maxWireProtocolVersion for 3.0 support.
- PERL-455 Changed to use connect timeout as the socket timeout for topology scans.
- Implemented a 5 second "cooldown" period after a network error during topology scanning during which new connection attempts will not be made. This avoids excessive blocking in the driver when it's unlikely that the server will be available right away.
- Removed unused vendored libyajl files.
- Refactored and reorganized perl-mongo.h and perl_mongo.c. Removed unused functions and macros.
- Disabled many internal class type constraints and runtime assertions unless the PERL_MONGO_WITH_ASSERTS environment variable is true.
- Changed use of 'strerror_s' to 'strerror' to attempt to get C/XS linking on Windows XP.
- Changed all Moose classes to Moo classes for speed and to minimize the deep dependency tree.
- Changed argument handling for CRUD API methods to stop coercing inputs to Tie::IxHash. This makes them significantly faster.
- Optimized networking code paths substantially.
- Consolidated various constants to MongoDB::_Constants.
- Inlined and adapted the Throwable CPAN module to avoid deep dependencies for MongoDB::Error.