# Officially supported MongoDB Driver

**URL:** <https://forums.swift.org/t/officially-supported-mongodb-driver/30324>\
**Category:** Pitches\
**Created:** [October 30, 2019, 4:38pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324 "2019-10-30T16:38:29Z")\
**Posts on this page:** 15\
**Page:** 1

<div class="post-metadata">

**Author:** ![kmahar](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/kmahar/32/5380_2.png) [@kmahar](https://forums.swift.org/u/kmahar)\
**Post date:** [October 30, 2019, 4:38pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/1 "2019-10-30T16:38:29Z")

</div>

# Introduction

Hi all! My name is Kaitlin Mahar, and I’m a software engineer at MongoDB on the drivers team. We build the official client libraries for using MongoDB in just about every popular programming language.

I work on our driver for Swift, [MongoSwift](https://www.github.com/mongodb/mongo-swift-driver). My team (@mbroadst, @patrick) and I would like to pitch the driver to SSWG and the community for consideration.

We’re currently working on adding an asynchronous SwiftNIO-based version of our API to meet the SSWG incubation process minimal requirements. This is still in the design phase, and we’d love to hear feedback from the community on what we’ve come up with so far.

# Current State and Future Plans

We initially developed MongoSwift about 18 months ago with a synchronous API for use with the mobile/embedded version of MongoDB. However, we’ve increasingly shifted our focus toward providing a great server-side experience. We did work over the summer to implement automatic connection pooling in the driver and are now tackling the crucial asynchronous API.

The driver complies with nearly all of the MongoDB driver [specifications](https://www.github.com/mongodb/specifications), which are documents our team writes detailing everything from what a driver’s CRUD API should look like to how it should select which server to send a command to. These specs ensure consistent experiences using MongoDB across languages, while still allowing room for implementations and public APIs to vary in language-appropriate ways.

MongoDB stores data in [BSON](http://bsonspec.org) (binary JSON) documents, and the driver includes a `Document` type which supports inserting and retrieving a number of built-in Swift types (e.g. `Int`, `String`, `Bool`) as well as various BSON-specific types we’ve implemented such as `ObjectId`. We also have a `BSONEncoder` and `BSONDecoder` that support converting between `Codable` types and `Document`s.

The latest release we’ve tagged is 0.1.3. We are aiming to do a 1.0 release once the async API is ready.

## libmongoc

The driver currently wraps the [MongoDB C driver](https://www.github.com/mongodb/mongo-c-driver), a.k.a. libmongoc. So far, this choice has allowed us to focus a lot on the API and ergonomics of the driver and less on internals. After our API is stabilized we plan to start on rewriting the internals in pure Swift using SwiftNIO.

In the meantime, we’ll be able to provide an asynchronous API that uses SwiftNIO primitives by wrapping all blocking libmongoc calls in an `NIOThreadPool`. We plan to continue maintaining the synchronous API to provide a great experience when using the driver in scripts or the Swift REPL.

At the moment, users are required to install libmongoc separately on their system, but we have work in progress to vendor libmongoc and build it with SwiftPM instead to provide a better user experience.

## Testing/Supported Usage

MongoSwift supports Swift 5.0+ and MongoDB 3.6+, and is tested in CI on MongoDB's in-house CI system Evergreen on MacOS and Linux against a variety of MongoDB deployments (standalone, replica set, sharded cluster) both with and without SSL enabled.

# Sample Usage of Async API

```swift
// Option 1: initialize a client that will lazily connect upon first I/O
let client = try MongoClient("mongodb://127.0.0.1/", using: myEventLoop)

// Option 2: initialize a client and attempt to ping the server with it.
// this provides consistency with other DB drivers e.g. PostgresNIO
let futureClient = try MongoClient.connect("mongodb://127.0.0.1/", on: myEventLoop)

// Create a collection and use it with a `Codable` type of your choice
struct Cat {
    let _id: ObjectId
    let name: String
    let color: String
}

// these methods perform no I/O, they just set up local objects containing
// the state necessary to construct commands
let db = client.db("home")
let collection = db.collection("cats", withType: Cat.self)

// insert a `Cat` with a randomly generated _id and print the 
// resulting `InsertOneResult`
let chester = Cat(_id: ObjectId(), name: "Chester", color: "tan")
try collection.insertOne(chester).whenSuccess { result in
    print("result: \(result)") // InsertOneResult(insertedId: .objectId("..."))
}

// Get a count of documents in a collection
try collection.countDocuments().whenSuccess { count in
    print("count: \(count)") // 1
}

// Retrieve all documents from a collection
let result = try collection.find().flatMap { cursor in
    cursor.all()
}
result.whenSuccess { documents in
    print(documents) // [Cat(_id: "...", name: "Chester", color: "tan")]
}

// Perform an operation for each document in a collection, querying
// the server as-needed rather than holding all the documents in memory
let result = try collection.find().flatMap { cursor in
    cursor.forEach { cat in
        // do something with cat
    }
}
result.whenSuccess {
    print("finished processing all documents")
}
result.whenFailure { error in
	print("error processing documents: \(error)")
}

```

Thanks for reading, we very much look forward to hearing any thoughts or feedback you have on the driver so far and our future plans!

---

<div class="post-metadata">

**Author:** ![valeriomazzeo](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/valeriomazzeo/32/2763_2.png) [@valeriomazzeo](https://forums.swift.org/u/valeriomazzeo)\
**Post date:** [October 30, 2019, 6:33pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/2 "2019-10-30T18:33:08Z")

</div>

> In the meantime, we’ll be able to provide an asynchronous API that uses SwiftNIO primitives by wrapping all blocking libmongoc calls in an `NIOThreadPool` .

I think I have already done what you just described - here:  
[https://github.com/asensei/vapor-fluent-mongo/tree/feature/fluent-4/Sources/FluentMongo](https://github.com/asensei/vapor-fluent-mongo/tree/feature/fluent-4/Sources/FluentMongo)

Perhaps it helps to get an idea.

---

<div class="post-metadata">

**Author:** ![johannesweiss](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/johannesweiss/32/38183_2.png) [@johannesweiss](https://forums.swift.org/u/johannesweiss)\
**Post date:** [October 31, 2019, 3:54pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/3 "2019-10-31T15:54:08Z")

</div>

Thanks very much for your pitch! A MongoDB driver is definitely in scope for the SSWG and therefore I very much support going forward towards a proposal.

I also think your approach of starting with asynchronous APIs right now (wrapping the blocking C library on a background thread) and then doing an ‘undercover’ rewrite in pure SwiftNIO is sensible. I’m sure @Joannis_Orlandos could give some valuable input here too and maybe you could even collaborate.

One question I have about the C driver you’re wrapping right now is: is that driver being compiled with SwiftPM or do you have to install the C driver into your system before you can use MongoSwift.

---

<div class="post-metadata">

**Author:** ![Mordil](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/mordil/32/5840_2.png) [@Mordil](https://forums.swift.org/u/Mordil)\
**Post date:** [October 31, 2019, 6:00pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/4 "2019-10-31T18:00:42Z")

</div>

@johannesweiss

> [@kmahar](#):
>
> At the moment, users are required to install libmongoc separately on their system, but we have work in progress to vendor libmongoc and build it with SwiftPM instead to provide a better user experience.

---

<div class="post-metadata">

**Author:** ![IanPartridge](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ianpartridge/32/434_2.png) [@IanPartridge](https://forums.swift.org/u/IanPartridge)\
**Post date:** [October 31, 2019, 9:26pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/6 "2019-10-31T21:26:37Z")

</div>

+1!

I'm thrilled to see this pitch come forwards from MongoDB themselves.

It would also be great to hear your thoughts on connection pooling design and whether there is any potential to reuse/share code in this area between MongoSwift and other database drivers.

---

<div class="post-metadata">

**Author:** ![johannesweiss](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/johannesweiss/32/38183_2.png) [@johannesweiss](https://forums.swift.org/u/johannesweiss)\
**Post date:** [October 31, 2019, 10:04pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/7 "2019-10-31T22:04:00Z")

</div>

> [@Mordil](#):
>
> @johannesweiss
> 
> ![](https://global.discourse-cdn.com/swift/original/2X/7/7ad2e0a203612cba655d8c12e23fab0031e386a1.jpeg) kmahar:
> 
> > At the moment, users are required to install libmongoc separately on their system, but we have work in progress to vendor libmongoc and build it with SwiftPM instead to provide a better user experience.

Whoops, thank you. Sounds great!

---

<div class="post-metadata">

**Author:** ![Joannis\_Orlandos](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/joannis_orlandos/32/732_2.png) [@Joannis\_Orlandos](https://forums.swift.org/u/Joannis_Orlandos)\
**Post date:** [November 1, 2019, 8:11am UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/8 "2019-11-01T08:11:56Z")

</div>

I'd be open to a collaboration if it would be a Swift driver (like MongoKitten). I wouldn't be interested in collaborating on a C based driver. I've got a load of feedback on API design & internals design. Mostly based on the [official MongoDB specification](https://github.com/mongodb/specifications) and my experience implementing it.

---

<div class="post-metadata">

**Author:** ![Joannis\_Orlandos](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/joannis_orlandos/32/732_2.png) [@Joannis\_Orlandos](https://forums.swift.org/u/Joannis_Orlandos)\
**Post date:** [November 1, 2019, 8:18am UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/9 "2019-11-01T08:18:27Z")

</div>

As an added note:  
I like the new API design, although I have my concerns with the enum for BSON Values. MongoDB tends to add new types to BSON when needed. [Decimal128](https://bsonspec.org/spec.html) being a recent example of this. That's why I think an enum is a burden to the driver and user.

---

<div class="post-metadata">

**Author:** ![kmahar](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/kmahar/32/5380_2.png) [@kmahar](https://forums.swift.org/u/kmahar)\
**Post date:** [November 7, 2019, 4:39pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/10 "2019-11-07T16:39:13Z")

</div>

Thanks for the link, @valeriomazzeo!

> [@IanPartridge](#):
>
> It would also be great to hear your thoughts on connection pooling design and whether there is any potential to reuse/share code in this area between MongoSwift and other database drivers.

I think there is definitely potential for this!

Earlier this year our team published a [connection monitoring and pooling](https://github.com/mongodb/specifications/blob/master/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst) specification. This defines a standardized approach for how all MongoDB drivers should pool connections. (The monitoring bit involves publishing events in some language-specific manner when e.g. a connection is checked out or back into a pool.)

As libmongoc doesn't comply with this specification right now, we don't either, though we've mostly retrofitted the desired pool API atop their version of pooling. When we get to writing the SwiftNIO-based implementation, we'll want it to fully comply with this spec.

We'd be very interested in taking part in any discussions on this going forward and seeing where pooling needs overlap and differ across drivers and whether it makes sense to share any/all of a pooling implementation.

> [@Joannis\_Orlandos](#):
>
> I'd be open to a collaboration if it would be a Swift driver (like MongoKitten). I wouldn't be interested in collaborating on a C based driver. I've got a load of feedback on API design & internals design.

As I noted in the pitch above, the pure Swift implementation won't be coming for a while longer, and when it does it will occur in pieces rather than being a complete rewrite all at once.

Along the way, we'd certainly like to collaborate with you and the rest of the community on components that are useful to DB drivers and the server-side ecosystem as a whole, e.g. the DNS client you pitched a while back, connection pooling, etc. On the driver code itself, in general the official MongoDB drivers are owned by our team, but welcome collaboration via pull requests, GitHub issues, JIRA, etc.

> [@Joannis\_Orlandos](#):
>
> I like the new API design, although I have my concerns with the enum for BSON Values. MongoDB tends to add new types to BSON when needed. [Decimal128](https://bsonspec.org/spec.html) being a recent example of this. That's why I think an enum is a burden to the driver and user.

We considered this, however, adding new BSON types is a pretty rare occurrence (e.g. the last addition Decimal128 was 3.5 years ago). We felt that the benefits of the new approach (being able to exhaustively switch on BSON types, less verbose construction of document literals, being able to fully hide implementation details that were previously on the public protocol, removal of "placeholder" structs containing no data such as `BSONNull`) far outweighed the potential risk of some potential breaking change.

---

<div class="post-metadata">

**Author:** ![kaishin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/kaishin/32/10616_2.png) [@kaishin](https://forums.swift.org/u/kaishin)\
**Post date:** [November 8, 2019, 7:13pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/11 "2019-11-08T19:13:17Z")

</div>

I’m very +1 on this.

I have used the official driver in the past and MongoKitten more recently due to the Swift-NIO interop requirement in the project I was working on.

From my stand point as a driver user, the async aspect is more crucial than pure Swift internals.

---

<div class="post-metadata">

**Author:** ![tomerd](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tomerd/32/3402_2.png) [@tomerd](https://forums.swift.org/u/tomerd)\
**Post date:** [November 14, 2019, 5:06pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/12 "2019-11-14T17:06:26Z")

</div>

late +1, the gradual approach is sensible

---

<div class="post-metadata">

**Author:** ![Eli\_Hini](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/eli_hini/32/529_2.png) [@Eli\_Hini](https://forums.swift.org/u/Eli_Hini)\
**Post date:** [December 2, 2019, 11:00pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/13 "2019-12-02T23:00:58Z")

</div>

- 1

---

<div class="post-metadata">

**Author:** ![jjatie](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jjatie/32/24428_2.png) [@jjatie](https://forums.swift.org/u/jjatie)\
**Post date:** [December 6, 2019, 11:26am UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/14 "2019-12-06T11:26:23Z")

</div>

Strong +1

---

<div class="post-metadata">

**Author:** ![kmahar](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/kmahar/32/5380_2.png) [@kmahar](https://forums.swift.org/u/kmahar)\
**Post date:** [February 27, 2020, 4:58pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/15 "2020-02-27T16:58:23Z")

</div>

Hi all! Just wanted to provide a status update: [we've just released 1.0.0-rc0](https://github.com/mongodb/mongo-swift-driver/releases/tag/v1.0.0-rc0), which includes the new async API, vendored libmongoc, and a bunch of other improvements. We'd love for you all to check it out!

Now that the code is written, we are putting together a proposal to post on the forums in the very near future 🙂

---

<div class="post-metadata">

**Author:** ![kmahar](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/kmahar/32/5380_2.png) [@kmahar](https://forums.swift.org/u/kmahar)\
**Post date:** [December 19, 2020, 6:16pm UTC](https://forums.swift.org/t/officially-supported-mongodb-driver/30324/17 "2020-12-19T18:16:32Z")

</div>

Your message seems to be a copy-paste from the [documentation](https://docs.mongodb.com/drivers/java#ref-driver-support-id1) for the MongoDB Java driver. Not sure why you're posting it here (seems like maybe you're a bot) but it is certainly not relevant to the Swift driver.