Changes in Version 3.10.1
-------------------------
Version 3.10.1 fixes the following issues discovered since the release of
3.10.0:
- Fix a TypeError logged to stderr that could be triggered during server
maintenance or during :meth:`pymongo.mongo_client.MongoClient.close`.
- Avoid creating new connections during
:meth:`pymongo.mongo_client.MongoClient.close`.
Issues Resolved
...............
See the `PyMongo 3.10.1 release notes in JIRA`_ for the list of resolved issues
in this release.
.. _PyMongo 3.10.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=25039
Changes in Version 3.10.0
-------------------------
Version 3.10 includes a number of improvements and bug fixes. Highlights
include:
- Support for Client-Side Field Level Encryption with MongoDB 4.2. See
:doc:`examples/encryption` for examples.
- Support for Python 3.8.
- Added :attr:`pymongo.client_session.ClientSession.in_transaction`.
- Do not hold the Topology lock while creating connections in a MongoClient's
background thread. This change fixes a bug where application operations would
block while the background thread ensures that all server pools have
minPoolSize connections.
- Fix a UnicodeDecodeError bug when coercing a PyMongoError with a non-ascii
error message to unicode on Python 2.
- Fix an edge case bug where PyMongo could exceed the server's
maxMessageSizeBytes when generating a compressed bulk write command.
Issues Resolved
...............
See the `PyMongo 3.10 release notes in JIRA`_ for the list of resolved issues
in this release.
.. _PyMongo 3.10 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=23944
Changes in Version 3.9.0
------------------------
Version 3.9 adds support for MongoDB 4.2. Highlights include:
- Support for MongoDB 4.2 sharded transactions. Sharded transactions have
the same API as replica set transactions. See :ref:`transactions-ref`.
- New method :meth:`pymongo.client_session.ClientSession.with_transaction` to
support conveniently running a transaction in a session with automatic
retries and at-most-once semantics.
- Initial support for client side field level encryption. See the docstring for
:class:`~pymongo.mongo_client.MongoClient`,
:class:`~pymongo.encryption_options.AutoEncryptionOpts`,
and :mod:`~pymongo.encryption` for details. **Note: Support for client side
encryption is in beta. Backwards-breaking changes may be made before the
final release.**
- Added the ``max_commit_time_ms`` parameter to
:meth:`~pymongo.client_session.ClientSession.start_transaction`.
- Implement the `URI options specification`_ in the
:meth:`~pymongo.mongo_client.MongoClient` constructor. Consequently, there are
a number of changes in connection options:
- The ``tlsInsecure`` option has been added.
- The ``tls`` option has been added. The older ``ssl`` option has been retained
as an alias to the new ``tls`` option.
- ``wTimeout`` has been deprecated in favor of ``wTimeoutMS``.
- ``wTimeoutMS`` now overrides ``wTimeout`` if the user provides both.
- ``j`` has been deprecated in favor of ``journal``.
- ``journal`` now overrides ``j`` if the user provides both.
- ``ssl_cert_reqs`` has been deprecated in favor of ``tlsAllowInvalidCertificates``.
Instead of ``ssl.CERT_NONE``, ``ssl.CERT_OPTIONAL`` and ``ssl.CERT_REQUIRED``, the
new option expects a boolean value - ``True`` is equivalent to ``ssl.CERT_NONE``,
while ``False`` is equivalent to ``ssl.CERT_REQUIRED``.
- ``ssl_match_hostname`` has been deprecated in favor of ``tlsAllowInvalidHostnames``.
- ``ssl_ca_certs`` has been deprecated in favor of ``tlsCAFile``.
- ``ssl_certfile`` has been deprecated in favor of ``tlsCertificateKeyFile``.
- ``ssl_pem_passphrase`` has been deprecated in favor of ``tlsCertificateKeyFilePassword``.
- ``waitQueueMultiple`` has been deprecated without replacement. This option
was a poor solution for putting an upper bound on queuing since it didn't
affect queuing in other parts of the driver.
- The ``retryWrites`` URI option now defaults to ``True``. Supported write
operations that fail with a retryable error will automatically be retried one
time, with at-most-once semantics.
- Support for retryable reads and the ``retryReads`` URI option which is
enabled by default. See the :class:`~pymongo.mongo_client.MongoClient`
documentation for details. Now that supported operations are retried
automatically and transparently, users should consider adjusting any custom
retry logic to prevent an application from inadvertently retrying for too
long.
- Support zstandard for wire protocol compression.
- Support for periodically polling DNS SRV records to update the mongos proxy
list without having to change client configuration.
- New method :meth:`pymongo.database.Database.aggregate` to support running
database level aggregations.
- Support for publishing Connection Monitoring and Pooling events via the new
:class:`~pymongo.monitoring.ConnectionPoolListener` class. See
:mod:`~pymongo.monitoring` for an example.
- :meth:`pymongo.collection.Collection.aggregate` and
:meth:`pymongo.database.Database.aggregate` now support the ``$merge`` pipeline
stage and use read preference
:attr:`~pymongo.read_preferences.ReadPreference.PRIMARY` if the ``$out`` or
``$merge`` pipeline stages are used.
- Support for specifying a pipeline or document in
:meth:`~pymongo.collection.Collection.update_one`,
:meth:`~pymongo.collection.Collection.update_many`,
:meth:`~pymongo.collection.Collection.find_one_and_update`,
:meth:`~pymongo.operations.UpdateOne`, and
:meth:`~pymongo.operations.UpdateMany`.
- New BSON utility functions :func:`~bson.encode` and :func:`~bson.decode`
- :class:`~bson.binary.Binary` now supports any bytes-like type that implements
the buffer protocol.
- Resume tokens can now be accessed from a ``ChangeStream`` cursor using the
:attr:`~pymongo.change_stream.ChangeStream.resume_token` attribute.
- Connections now survive primary step-down when using MongoDB 4.2+.
Applications should expect less socket connection turnover during
replica set elections.
Unavoidable breaking changes:
- Applications that use MongoDB with the MMAPv1 storage engine must now
explicitly disable retryable writes via the connection string
(e.g. ``MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")``) or
the :class:`~pymongo.mongo_client.MongoClient` constructor's keyword argument
(e.g. ``MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)``)
to avoid running into :class:`~pymongo.errors.OperationFailure` exceptions
during write operations. The MMAPv1 storage engine is deprecated and does
not support retryable writes which are now turned on by default.
- In order to ensure that the ``connectTimeoutMS`` URI option is honored when
connecting to clusters with a ``mongodb+srv://`` connection string, the
minimum required version of the optional ``dnspython`` dependency has been
bumped to 1.16.0. This is a breaking change for applications that use
PyMongo's SRV support with a version of ``dnspython`` older than 1.16.0.
.. _URI options specification: https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.rst
Issues Resolved
...............
See the `PyMongo 3.9 release notes in JIRA`_ for the list of resolved issues
in this release.
.. _PyMongo 3.9 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21787
Changes in Version 3.8.0
------------------------
.. warning:: PyMongo no longer supports Python 2.6. RHEL 6 users should install
Python 2.7 or newer from `Red Hat Software Collections
<https://www.softwarecollections.org>`_. CentOS 6 users should install Python
2.7 or newer from `SCL
<https://wiki.centos.org/AdditionalResources/Repositories/SCL>`_
.. warning:: PyMongo no longer supports PyPy3 versions older than 3.5. Users
must upgrade to PyPy3.5+.
- :class:`~bson.objectid.ObjectId` now implements the `ObjectID specification
version 0.2 <https://github.com/mongodb/specifications/blob/master/source/objectid.rst>`_.
- For better performance and to better follow the GridFS spec,
:class:`~gridfs.grid_file.GridOut` now uses a single cursor to read all the
chunks in the file. Previously, each chunk in the file was queried
individually using :meth:`~pymongo.collection.Collection.find_one`.
- :meth:`gridfs.grid_file.GridOut.read` now only checks for extra chunks after
reading the entire file. Previously, this method would check for extra
chunks on every call.
- :meth:`~pymongo.database.Database.current_op` now always uses the
``Database``'s :attr:`~pymongo.database.Database.codec_options`
when decoding the command response. Previously the codec_options
was only used when the MongoDB server version was <= 3.0.
- Undeprecated :meth:`~pymongo.mongo_client.MongoClient.get_default_database`
and added the ``default`` parameter.
- TLS Renegotiation is now disabled when possible.
- Custom types can now be directly encoded to, and decoded from MongoDB using
the :class:`~bson.codec_options.TypeCodec` and
:class:`~bson.codec_options.TypeRegistry` APIs. For more information, see
the :doc:`custom type example <examples/custom_type>`.
- Attempting a multi-document transaction on a sharded cluster now raises a
:exc:`~pymongo.errors.ConfigurationError`.
- :meth:`pymongo.cursor.Cursor.distinct` and
:meth:`pymongo.cursor.Cursor.count` now send the Cursor's
:meth:`~pymongo.cursor.Cursor.comment` as the "comment" top-level
command option instead of "$comment". Also, note that "comment" must be a
string.
- Add the ``filter`` parameter to
:meth:`~pymongo.database.Database.list_collection_names`.
- Changes can now be requested from a ``ChangeStream`` cursor without blocking
indefinitely using the new
:meth:`pymongo.change_stream.ChangeStream.try_next` method.
- Fixed a reference leak bug when splitting a batched write command based on
maxWriteBatchSize or the max message size.
- Deprecated running find queries that set :meth:`~pymongo.cursor.Cursor.min`
and/or :meth:`~pymongo.cursor.Cursor.max` but do not also set a
:meth:`~pymongo.cursor.Cursor.hint` of which index to use. The find command
is expected to require a :meth:`~pymongo.cursor.Cursor.hint` when using
min/max starting in MongoDB 4.2.
- Documented support for the uuidRepresentation URI option, which has been
supported since PyMongo 2.7. Valid values are `pythonLegacy` (the default),
`javaLegacy`, `csharpLegacy` and `standard`. New applications should consider
setting this to `standard` for cross language compatibility.
- :class:`~bson.raw_bson.RawBSONDocument` now validates that the ``bson_bytes``
passed in represent a single bson document. Earlier versions would mistakenly
accept multiple bson documents.
- Iterating over a :class:`~bson.raw_bson.RawBSONDocument` now maintains the
same field order of the underlying raw BSON document.
- Applications can now register a custom server selector. For more information
see the :doc:`server selector example <examples/server_selection>`.
- The connection pool now implements a LIFO policy.
Unavoidable breaking changes:
- In order to follow the ObjectID Spec version 0.2, an ObjectId's 3-byte
machine identifier and 2-byte process id have been replaced with a single
5-byte random value generated per process. This is a breaking change for any
application that attempts to interpret those bytes.
0aa5815adb