view release on metacpan or  search on metacpan

lib/MongoDB/Upgrading/v1.pod  view on Meta::CPAN

=head1 VERSION

version v2.2.2

=head1 DESCRIPTION

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.

=head1 RATIONALE

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

=over 4

=item *

consistency (intra-driver) – 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.

=item *

consistency (inter-driver) — "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.

=item *

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 wit...

=item *

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.

=item *

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.

=item *

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...

=item *

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).

=back

=head1 INSTALLATION AND DEPENDENCY CHANGES

=head2 Moo instead of Moose

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

=head2 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
C<IO::Socket::SSL> and C<Authen::SASL> for SSL and SASL support,
respectively.

SSL configuration is now possible via the L<ssl
attribute|MongoDB::MongoClient/ssl>.

Authentication configuration is described in L<MongoDB::MongoClient/AUTHENTICATION>.

=head1 BEHAVIOR CHANGES

=head2 MongoClient configuration

=head3 New configuration options

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

=over 4

=item *

C<auth_mechanism>

=item *

C<auth_mechanism_properties>

=item *

C<bson_codec>

=item *

C<connect_timeout_ms>

=item *

C<heartbeat_frequency_ms>

=item *

C<local_threshold_ms>

=item *

C<max_time_ms>

=item *

C<replica_set_name>

=item *

C<read_pref_mode>

=item *

C<read_pref_tag_sets>

=item *