1.3.1

This release corrects a minor error that occurred during the 1.3.0 release process, where v1.3.0 was inadvertently tagged before the version string the driver reports in its handshake with the server was updated. As a result, "1.3.0-beta.1" would be incorrectly reported as the driver version in MongoDB server logs.

There are no other changes from the 1.3.0 release.

1.3.0

We are pleased to announce the GA of our 1.3.0 release, which contains no changes from our last pre-release, 1.3.0-beta.1.

This release most notably adds the following features:

Async/Await APIs

This release adds a new async/await version of our entire API surface to allow you to start using the driver with Swift concurrency!

For example, to create a collection and insert a document:

let collection = try await db.createCollection("foo")
try await collection.insertOne(["x": 1])

We’ve also made MongoCursor and ChangeStream conform to AsyncSequence. This protocol provides a number of convenience methods for working with sequences, and enables you to consume their values via a for loop, for example:

for try await doc in try await collection.find() {
    print(doc)
}

We’ve written a blog post that discusses this in more detail, and have also updated all of our documentation and our Vapor example project to use Swift concurrency to help you get started using these new APIs.

These APIs are available for Swift 5.5.2+ developers on Linux and macOS 10.15+.

Please feel free to file an issue if you run into any problems or have suggestions for improving the new APIs!

New MongoConnectionString type

This release also adds a new MongoConnectionString type modeling a MongoDB connection string, and moves the driver logic for parsing and validating a connection string, which was previously handled by the C driver, into the Swift layer.

This type conforms to LosslessStringConvertible and so can be initialized via and converted to a String , and has mutable properties to allow setting/changing values. For example:

var connStr = MongoConnectionString("mongodb://localhost:27017")
connStr.readConcern = .local
print(connStr) // prints "mongodb://localhost:27017/?readconcernlevel=local"

You can now use this type to initialize a MongoClient:

var connStr = MongoConnectionString("mongodb://localhost:27017")
connStr.readConcern = .local
let client = try MongoClient(connStr, using: yourEventLoopGroup)

Included Tickets

Below are a selected list of tickets with user-facing implications; for a full list of completed tickets see this Jira query.

New Feature

• [ SWIFT-1160 ] - Introduce new MongoConnectionString type
• [ SWIFT-1161 ] - MongoConnectionString authentication options support
• [ SWIFT-1162 ] - MongoConnectionString TLS options support
• [ SWIFT-1163 ] - MongoConnectionString non-auth, non-TLS options support
• [ SWIFT-1165 ] - Initialization of MongoClient via MongoConnectionString
• [ SWIFT-1174 ] - MongoConnectionString Unix domain socket support
• [ SWIFT-1384 ] - Support ‘let’ option for multiple CRUD commands
• [ SWIFT-1389 ] - Implement MongoClient and ClientSession async/await APIs
• [ SWIFT-1390 ] - Implement MongoDatabase async/await API methods
• [ SWIFT-1391 ] - Implement MongoCollection async/await API methods
• [ SWIFT-1392 ] - Make MongoCursor and ChangeStream conform to AsyncSequence
• [ SWIFT-1405 ] - Implement description for MongoConnectionString
• [ SWIFT-1407 ] - Support ipv4 address parsing in MongoConnectionString

Improvement

• [ SWIFT-1451 ] - Use -cross-module-optimization flag in Vapor example

Task

• [ SWIFT-1493 ] - Update vendored libmongoc to 1.21.0

1.3.0-beta.1

We are pleased to announce the first beta for our 1.3.0 driver release, which follows two previous alphas. We have recently gained the capability to test our new async APIs on macOS in CI (previously, we only could on Linux) and are moving toward a stable 1.3.0 GA release in the near future.

Compared to the previous pre-release 1.3.0-alpha.2, this release contains a single bug fix, for SWIFT-1510.

The bug was that, although we document that MongoCursor, ChangeStream and ClientSession will be automatically cleaned up upon deinit on any platform and Swift version where concurrency is available, this automatic cleanup would not actually occur on macOS < 12.

Included Tickets

• SWIFT-1510: Update #available statements for automatic cleanup logic in deinits to macOS 10.15+

1.3.0-alpha.2

We are pleased to announce the second alpha of our 1.3.0 release.

The primary changes in this release from the previous alpha:

• The minimum Swift version required to use the new async APIs has increased to Swift 5.5.2 from Swift 5.5.0, and the new async APIs are now available on macOS 10.15+, rather than macOS 12+. Thank you to @atultw for contributing these changes!
• The driver’s vendors copy of libmongoc has been updated from version 1.19.2 to version 1.21.0. Please see the libmongoc release notes for details on the included changes.

Contributors

Thanks to everyone who contributed to this release!

• @atultw
• @isabelatkinson
• @kmahar

1.3.0-alpha.1

We are pleased to announce the first alpha of our 1.3.0 release, containing the following new features:

Async/Await APIs

This release adds a new async/await version of our entire API surface to allow you to start using the driver with Swift concurrency!

For example, to create a collection and insert a document:

let collection = try await db.createCollection("foo")
try await collection.insertOne(["x": 1])

We’ve also made MongoCursor and ChangeStream conform to AsyncSequence. This protocol provides a number of convenience methods for working with sequences, and enables you to consume their values via a for loop, for example:

for try await doc in try await collection.find() {
    print(doc)
}

We’ve written a blog post that discusses this in more detail, and have also updated all of our documentation and our Vapor example project to use Swift concurrency to help you get started using these new APIs.

Currently, these APIs are available for Swift 5.5.0+ developers on Linux and macOS 12. For future alpha releases we are exploring making these APIs available on older macOS versions as well where concurrency has recently become available.

Please feel free to file an issue if you run into any problems or have suggestions for improving the new APIs!

New MongoConnectionString type

This release also adds a new MongoConnectionString type modeling a MongoDB connection string, and moves the driver logic for parsing and validating a connection string, which was previously handled by the C driver, into the Swift layer.

This type conforms to LosslessStringConvertible and so can be initialized via and converted to a String , and has mutable properties to allow setting/changing values. For example:

var connStr = MongoConnectionString("mongodb://localhost:27017")
connStr.readConcern = .local
print(connStr) // prints "mongodb://localhost:27017/?readconcernlevel=local"

You can now use this type to initialize a MongoClient:

var connStr = MongoConnectionString("mongodb://localhost:27017")
connStr.readConcern = .local
let client = try MongoClient(connStr, using: yourEventLoopGroup)

Included Tickets

Below are a selected list of tickets with user-facing implications; for a full list of completed tickets see this Jira query.

New Feature

• [ SWIFT-1160 ] - Introduce new MongoConnectionString type
• [ SWIFT-1161 ] - MongoConnectionString authentication options support
• [ SWIFT-1162 ] - MongoConnectionString TLS options support
• [ SWIFT-1163 ] - MongoConnectionString non-auth, non-TLS options support
• [ SWIFT-1165 ] - Initialization of MongoClient via MongoConnectionString
• [ SWIFT-1174 ] - MongoConnectionString Unix domain socket support
• [ SWIFT-1384 ] - Support ‘let’ option for multiple CRUD commands
• [ SWIFT-1389 ] - Implement MongoClient and ClientSession async/await APIs
• [ SWIFT-1390 ] - Implement MongoDatabase async/await API methods
• [ SWIFT-1391 ] - Implement MongoCollection async/await API methods
• [ SWIFT-1392 ] - Make MongoCursor and ChangeStream conform to AsyncSequence
• [ SWIFT-1405 ] - Implement description for MongoConnectionString
• [ SWIFT-1407 ] - Support ipv4 address parsing in MongoConnectionString

Improvement

• [ SWIFT-1451 ] - Use -cross-module-optimization flag in Vapor example

v1.2.0

We are pleased to announce the 1.2.0 release of the Swift driver.

This release most notably adds support for the following features:

MongoDB Versioned API

MongoDB 5.0 introduced supported for the versioned API, which will make it much easier for users to upgrade their server versions without experiencing backward-breaking changes.

To specify an API version for your application, provide a version via MongoClientOptions (currently, the only supported API version is 1):

let opts = MongoClientOptions(
    serverAPI: MongoServerAPI(version: .v1)
)

// Create an async client
let client = try MongoClient("mongodb://localhost:27017", using: myEventLoopGroup, options: opts)

// Or, create a sync client
let client = try MongoClient("mongodb://localhost:27017", options: opts)

Serverless MongoDB Support / Load Balancer Support

This release adds support for using the driver with Serverless MongoDB, which is currently in preview.

This is enabled via new support for connecting to a MongoDB cluster behind a TCP load balancer, which is supported via the loadBalanced connection string option or by setting the loadBalanced property on MongoClientOptions.

MongoDB 5.0 Support

This release adds full support for using new MongoDB 5.0 features, including creating and working with time series collections as well as extended support for the “snapshot” read concern; see the MongoDB 5.0 release notes for more details.

OCSP Support

The driver previously had implicit support for the Online Certificate Status Protocol (OCSP) via the underlying C driver, however as part of this release we have added explicit testing for this from Swift along with support for configuring it programmatically via MongoClientOptions, using the tlsDisableCertificateRevocationCheck and tlsDisableOCSPEndpointCheck options.

Please see our TLS Guide for more information.

Below are a selected list of tickets with user-facing implications; for a full list of completed tickets see this Jira query.

Included Tickets

Bug

• SWIFT-1322 - listCollections does not respect batchSize option
• SWIFT-1347 - ClientSession.pinnedServerAddress leaks memory (in tests only)

New Feature

• SWIFT-787 - OCSP Support
• SWIFT-1025 - Versioned MongoDB API for Drivers
• SWIFT-1094 - Load Balancer Support
• SWIFT-797 - Allow hinting the delete command
• SWIFT-801 - support ability to pass hint to update
• SWIFT-788 - Allow passing hint to findAndModify update and replace operations
• SWIFT-904 - Add connectTimeoutMS option to MongoClientOptions
• SWIFT-1157 - Implement ExpressibleByXLiteral for IndexHint
• SWIFT-1102 - Snapshot reads on Secondaries
• SWIFT-560 - Add the ability to specify a pipeline to an update command
• SWIFT-1108 - Time-series Collections
• SWIFT-1225 - Support ‘let’ option for aggregate command
• SWIFT-1100 - Support truncatedArrays field in ChangeStream update descriptions
• SWIFT-1307 - Expose serviceId in command monitoring events

Improvement

• SWIFT-910 - Lift restriction on authSource without credentials
• SWIFT-1099 - Change estimatedDocumentCount() to use the $collStats Agg Stage Instead of Count Command
• SWIFT-1107 - Mitigate pain of using field names with dots and dollars
• SWIFT-1211 - Use “hello” command for monitoring if supported
• SWIFT-1173 - Use “hello” command when API version is declared

Task

• SWIFT-1256 - Vendor libmongoc 1.19.0
• SWIFT-1363 - Vendor libmongoc 1.19.1
• SWIFT-1409 - Vendor libmongoc 1.19.2
• SWIFT-1224 - Increase maxWireVersion for MongoDB 5.0

Contributors

Thanks to everyone who contributed to this release!

• @agolin95
• @bynn
• @isabelatkinson
• @kmahar
• @patrickfreed

1.2.0-beta.1

We are pleased to announce our first beta release for the upcoming 1.2.0 release of the Swift driver. We would love for you to try it out!

This release most notably adds support for the following features:

MongoDB Versioned API

MongoDB 5.0 introduced supported for the versioned API, which will make it much easier for users to upgrade their server versions without experiencing backward-breaking changes.

To specify an API version for your application, provide a version via MongoClientOptions (currently, the only supported API version is 1):

let opts = MongoClientOptions(
    serverAPI: MongoServerAPI(version: .v1)
)

// Create an async client
let client = try MongoClient("mongodb://localhost:27017", using: myEventLoopGroup, options: opts)

// Or, create a sync client
let client = try MongoClient("mongodb://localhost:27017", options: opts)

Serverless MongoDB Support / Load Balancer Support

This release adds support for using the driver with Serverless MongoDB, which is currently in preview.

This is enabled via new support for connecting to a MongoDB cluster behind a TCP load balancer, which is supported via the loadBalanced connection string option or by setting the loadBalanced property on MongoClientOptions.

OCSP Support

The driver previously had implicit support for the Online Certificate Status Protocol (OCSP) via the underlying C driver, however as part of this release we have added explicit testing for this from Swift along with support for configuring it programmatically via MongoClientOptions, using the tlsDisableCertificateRevocationCheck and tlsDisableOCSPEndpointCheck options.

Please see our TLS Guide for more information.

Below are a selected list of tickets with user-facing implications; for a full list of completed tickets see this Jira query.

Included Tickets

Bug

• SWIFT-1322 - listCollections does not respect batchSize option
• SWIFT-1347 - ClientSession.pinnedServerAddress leaks memory (in tests only)

New Feature

• SWIFT-787 - OCSP Support
• SWIFT-1025 - Versioned MongoDB API for Drivers
• SWIFT-1094 - Load Balancer Support
• SWIFT-797 - Allow hinting the delete command
• SWIFT-801 - support ability to pass hint to update
• SWIFT-904 - Add connectTimeoutMS option to MongoClientOptions
• SWIFT-1157 - Implement ExpressibleByXLiteral for IndexHint
• SWIFT-788 - Allow passing hint to findAndModify update and replace operations

Improvement

• SWIFT-910 - Lift restriction on authSource without credentials
• SWIFT-1099 - Change estimatedDocumentCount() to use the $collStats Agg Stage Instead of Count Command
• SWIFT-1100 - Implement change stream oplog parsing code for delta oplog entries
• SWIFT-1107 - Mitigate pain of using field names with dots and dollars
• SWIFT-1224 - Bump maxWireVersion for MongoDB 5.0
• SWIFT-1307 - Expose serviceId in command monitoring events

Task

• SWIFT-1256 - Vendor libmongoc 1.19.0

1.1.1

The MongoDB Swift driver team is pleased to announce our 1.1.1 release.

This patch release is a recommended upgrade which updates the vendored MongoDB C driver code from version 1.17.4 to 1.17.7 and thus pulls in a number of bug fixes. You can find the details of the fixes included in the following C driver release notes: 1.17.7, 1.17.6, 1.17.5.

1.1.0

The MongoDB Swift driver team is pleased to announce our 1.1.0 release.

Highlights

New BSON Library

Last week, we released version 3.0.0 of SwiftBSON. This is a brand new, pure Swift BSON library. While the internals are all-new, the API is identical to the one that previously lived in the driver with a few additions as described in the release notes, and we've now switched the driver to depend on this library.
For convenience, we re-export all symbols from SwiftBSON from MongoSwift and MongoSwiftSync, so you can continue to use BSON types as if they were defined directly in the driver with no breaking changes.

Event Loop "Binding" for Core Async Driver Types

Previously, there was no way to specify at the API level a particular EventLoop that a core driver type (client, database, or collection) should return EventLoopFutures on. We've now introduced a special EventLoopBoundClient type to support this for clients, and added support directly to MongoDatabase and MongoCollection for it as well. Please see our Multithreaded Usage Guide for more details.

Aggregation Improvements

We've added a new helper method to MongoDatabase via SWIFT-577 to support performing database-level aggregations.

We've also added support via SWIFT-506 to both MongoDatabase.aggregate and MongoCollection.aggregate for specifying a Codable type that the returned MongoCursor should decode resulting documents into. Previously, these methods could only return MongoCursor<BSONDocument>s. For example:

/// Collection type.
struct Person: Codable {
    let _id: BSONObjectID
    let name: String
    let age: Int
    let favoriteColor: String
}

let coll = db.collection("people", withType: Person.self)
try coll.insertMany([
    Person(_id: BSONObjectID(),  name: "Kaitlin", age: 26, favoriteColor: "blue")
    Person(_id: BSONObjectID(),  name: "Buffalo", age: 27, favoriteColor: "green")
]).wait()


/// Transformed aggregation output type.
struct PersonOutput: Codable {
    let name: String
    let age: Int
}

let resultsFuture = coll.aggregate([
    ["$project": ["age": 1, "name": 1, "_id": 0]] // only keep the age and name fields
], withOutputType: PersonOutput.self).flatMap { cursor in
    cursor.toArray()
}

// prints [PersonOutput(name: "Kaitlin", age: 26), PersonOutput(name: "Buffalo", age: 27)]
print(try resultsFuture.wait())

MongoClientOptions Improvements

Previously, a number of driver options were only specifiable via connection string, and not supported via MongoClientOptions. We've now added support for specifying a number of options via the options struct as well, such as replicaSet and serverSelectionTimeoutMS.

Included Tickets

Bug

• [SWIFT-957] - DecodingError when encountering dropDatabase event in change stream
• [SWIFT-958] - Ensure nil is returned from cursor before returning LogicError
• [SWIFT-969] - Manually clean up mongoc_uri_t when ConnectionString options validation fails
• [SWIFT-974] - Cursor gets leaked in findOne after DecodingError
• [SWIFT-1045] - MongoClient initializer performs blocking DNS lookup

New Feature

• [SWIFT-481] - Support index all paths
• [SWIFT-828] - Hidden Indexes
• [SWIFT-577] - Add database aggregation helper
• [SWIFT-1028] - Create EventLoopBoundMongoClient type
• [SWIFT-1029] - Implement EventLoop binding support for database and collection objects
• [SWIFT-1030] - Implement EventLoop binding support for change streams and cursors
• [SWIFT-1031] - Implement EventLoop binding support for sessions
• [SWIFT-459] - Add a renameCollection helper
• [SWIFT-519] - Support startAfter option for change streams
• [SWIFT-506] - Allow users to specify the output type of an aggregation

Task

• [SWIFT-734] - Maintain multiple versions of the documentation
• [SWIFT-791] - Support shorter SCRAM conversation
• [SWIFT-854] - Organize API documentation in a more useful way
• [SWIFT-936] - Update the driver to use the new BSON library
• [SWIFT-1010] - Test against Swift 5.3 + Linux on Evergreen
• [SWIFT-1034] - Update readme with how to sort all records after running collection.find()
• [SWIFT-1092] - Vendor libmongoc 1.17.4
• [SWIFT-763] - Deprecate geoHaystack and geoSearch

Improvement

• [SWIFT-805] - Make ExceededTimeLimit retryable writes error
• [SWIFT-872] - Reduce default keepalive time to align with Azure defaults
• [SWIFT-903] - Add compressors option to MongoClientOptions
• [SWIFT-905] - Add heartbeatFrequencyMS option to MongoClientOptions
• [SWIFT-906] - Add localThresholdMS option to MongoClientOptions
• [SWIFT-907] - Add serverSelectionTimeoutMS option to MongoClientOptions
• [SWIFT-909] - Add zLibCompressionLevel option to MongoClientOptions
• [SWIFT-897] - Add appname option to MongoClientOptions
• [SWIFT-898] - Add replicaSet option to MongoClientOptions
• [SWIFT-901] - Add tlsInsecure option to MongoClientOptions
• [SWIFT-912] - Error if minPoolSize option is provided in connection string
• [SWIFT-929] - Validate options provided via MongoClientOptions
• [SWIFT-1015] - Only create monitoring events if the user is actually subscribing to them
• [SWIFT-1072] - Improve performance of insertion

1.0.2

I'm pleased to announce our 1.0.2 release.

This contains a fix (14afd20) for a memory leak on Linux: SWIFT-1051 / #571. Thank you to @NikolayJuly for bringing this to our attention.

This leak was due to our usage of String.cString(using:), a Foundation method whose Linux implementation has apparently had a longstanding, known memory leak (see SR-4036, and the source code).