I’m very happy to announce the release of the MongoDB Perl driver v1.0.0 Release Candidate 1 to CPAN!
This next-generation driver is a substantial rewrite of the original and has been my primary project as lead engineer for the Perl driver since last summer.
Rationale for a rewrite 🔗︎
Over the last year, MongoDB engineers rewrote most of the language drivers maintained in-house. As mentioned in the next-generation drivers announcement, we’ve built the next-generation drivers on a common set of specification documents. Whereas previous drivers were written idiosyncratically, each driver now aims to deliver similar underlying behaviors through similar APIs, while still striving to be idiomatic for its language.
For the Perl driver, however, we had several goals that went above and beyond cross-driver consistency. In particular, we wanted to address some fundamental deficiencies in the “v0.x” series of drivers:
- intra-driver 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 mechanisms.
- 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, allowing faster future development keeping up with MongoDB server enhancements with less risk of breakage.
- abstraction – 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.
- server compatibility – 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.
- portability – 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.
- round-trippable data – 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).
Summary of changes 🔗︎
As you might imagine, there are an enormous number of changes, listed in detail in the MongoDB::Upgrading document.
Here is a summary of some of the more substantial changes:
- Configuration – MongoDB::MongoClient gains a number of new configuration options to control server selection and timeouts; configurations are now always read-only; some existing options are deprecated; others are removed entirely where they no longer fit the new paradigms of the client
- Lazy connection – creating a MongoDB::MongoClient object no longer connects to a server right away. This is the new standard for all official MongoDB drivers, but might break code that expected an immediate error from
new! - Failover – when a networking error occurs or a server goes away, an error is throw. If handled, the next attempt at communicating with the server will automatically reconnect. For a replica set, this means it will failover to a new primary when a new primary is ready.
- Exceptions – All errors now throw exceptions rather than relying on inconsistent ways of returning errors from methods
- Read preferences and write concerns – these are now expressed as objects; they can be set at the client, database or collection object level
- Authentication – this is now based only on configuration options and occurs immediately when any server connection is made. This is another change for all official drivers that harmonizes the behavior of MongoDB’s different authentication mechanisms, some of which could only happen at connection time and some of which could be done later.
- Deprecations – pretty much the entire MongoDB::Collection API was deprecated and replaced with the new official-driver-wide CRUD API. The deprecated methods are now undocumented, but still mostly work as they used to. A handful of methods in other classes were deprecated as well.
BSON encoding changes 🔗︎
BSON encoding was substantially overhauled. The various $MongoDB::BSON::... global variables have been removed, as BSON encoding is now encapsulated and can be set per-client, per-database or per-collection.
Integers will now be encoded to the smallest BSON integer type that fits rather than always taking up a fixed size (equal to the compiled integer size of the interpreter). This means that storing zero no longer takes up 64 bits on a 64-bit perl.
All common JSON boolean classes will now encode correctly. Time::Moment is supported for both encoding and decoding datetimes.
Testing the release candidate 🔗︎
If you use the MongoDB Perl driver, I strongly encourage you to read MongoDB::Upgrading and test your code with the release candidate driver.
You can install it from CPAN like this:
$ cpan MONGODB/MongoDB-v0.999.999.4-TRIAL.tar.gz
If you encounter problem or have questions, please open tickets on the MongoDB Perl driver bug tracker.
Barring any show-stoppers or urgent changes, the stable v1.0.0 MongoDB Perl driver will be shipped to CPAN in mid-to-late August.