From 761c0df7165453cd5acaa4c23d611bc18e0fc517 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Fri, 21 Feb 2020 14:16:28 -0500 Subject: [PATCH 1/3] wip --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 50 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b2a249daf..1725be790 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Code Coverage](https://codecov.io/gh/mongodb/mongo-swift-driver/branch/master/graph/badge.svg)](https://codecov.io/gh/mongodb/mongo-swift-driver/branch/master) # MongoSwift -The official [MongoDB](https://www.mongodb.com/) driver for Swift. +The official [MongoDB](https://www.mongodb.com/) driver for Swift applications on macOS and Linux. ### Index - [Documentation](#documentation) @@ -43,7 +43,9 @@ The driver vendors and wraps the MongoDB C driver (`libmongoc`), which depends o To install those libraries, please follow the [instructions](http://mongoc.org/libmongoc/current/installing.html#prerequisites-for-libmongoc) from `libmongoc`'s documentation. ### Step 2: Install MongoSwift -Add MongoSwift to your dependencies in `Package.swift`: +The driver contains two modules to support a variety of use cases: an asynchronous API in `MongoSwift`, and a synchronous API in `MongoSwiftSync`. The modules share a BSON implementation and a number of core types such as options `struct`s. + +To install the driver, add the package and relevant module as a dependency in your project's `Package.swift` file: ```swift // swift-tools-version:5.0 @@ -55,7 +57,10 @@ let package = Package( .package(url: "https://github.com/mongodb/mongo-swift-driver.git", from: "VERSION.STRING.HERE"), ], targets: [ - .target(name: "MyPackage", dependencies: ["MongoSwift"]) + // Async module + .target(name: "MyAsyncTarget", dependencies: ["MongoSwift"]), + // Sync module + .target(name: "MySyncTarget", dependencies: ["MongoSwiftSync"]) ] ) ``` @@ -67,20 +72,59 @@ Then run `swift build` to download, compile, and link all your dependencies. Note: You should call `cleanupMongoSwift()` exactly once at the end of your application to release all memory and other resources allocated by `libmongoc`. ### Connect to MongoDB and Create a Collection + +**Async**: ```swift import MongoSwift +import NIO + +let elg = MultithreadedEventLoopGroup(numberOfThreads: 4) +let client = try MongoClient("mongodb://localhost:27017", using: elg) + +defer { + // clean up driver resources + client.syncShutdown() + cleanupMongoSwift() + + // shut down EventLoopGroup + try? elg.syncShutdownGracefully() +} + +let db = client.db("myDB") +db.createCollection("myCollection").flatMap { collection in + // use collection... +} +``` + +**Sync**: +```swift +import MongoSwiftSync + +defer { + // free driver resources + cleanupMongoSwift() +} let client = try MongoClient("mongodb://localhost:27017") + let db = client.db("myDB") let collection = try db.createCollection("myCollection") -// free all resources -cleanupMongoSwift() +// use collection... ``` -Note: we have included the client `connectionString` parameter for clarity, but if connecting to the default `"mongodb://localhost:27017"`it may be omitted: `let client = try MongoClient()`. +Note: we have included the client `connectionString` parameter for clarity, but if connecting to the default `"mongodb://localhost:27017"`it may be omitted. ### Create and Insert a Document +**Async**: +```swift +let doc: Document = ["_id": 100, "a": 1, "b": 2, "c": 3] +collection.insertOne(doc).whenSuccess { result in + print(result?.insertedId ?? "") // prints `.int64(100)` +} +``` + +**Sync**: ```swift let doc: Document = ["_id": 100, "a": 1, "b": 2, "c": 3] let result = try collection.insertOne(doc) From da4b0947b73a0511f64d4743d615c7185edfc31e Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Sun, 23 Feb 2020 20:26:20 -0500 Subject: [PATCH 2/3] Update README.md --- README.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1725be790..be7f045b8 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Note: You should call `cleanupMongoSwift()` exactly once at the end of your appl import MongoSwift import NIO -let elg = MultithreadedEventLoopGroup(numberOfThreads: 4) +let elg = MultiThreadedEventLoopGroup(numberOfThreads: 4) let client = try MongoClient("mongodb://localhost:27017", using: elg) defer { @@ -91,7 +91,7 @@ defer { } let db = client.db("myDB") -db.createCollection("myCollection").flatMap { collection in +let result = db.createCollection("myCollection").flatMap { collection in // use collection... } ``` @@ -132,15 +132,22 @@ print(result?.insertedId ?? "") // prints `.int64(100)` ``` ### Find Documents +**Async**: +```swift +let query: Document = ["a": 1] +let result = collection.find(query).flatMap { cursor in + cursor.forEach { doc in + print(doc) + } +} +``` + +**Sync**: ```swift let query: Document = ["a": 1] let documents = try collection.find(query) for d in documents { - print(d) -} -// check if an error occurred while iterating the cursor -if let error = documents.error { - throw error + print(try d.get()) } ``` From ea1637d6ca183cb109e993e4740f252ffb042991 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Mon, 24 Feb 2020 15:53:12 -0500 Subject: [PATCH 3/3] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index be7f045b8..82d18890b 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,8 @@ methods. ### Usage With Kitura, Vapor, and Perfect The `Examples/` directory contains sample projects that use the driver with [Kitura](https://github.com/mongodb/mongo-swift-driver/tree/master/Examples/Kitura), [Vapor](https://github.com/mongodb/mongo-swift-driver/tree/master/Examples/Vapor), and [Perfect](https://github.com/mongodb/mongo-swift-driver/tree/master/Examples/Perfect). +Please note that the driver is built using SwiftNIO 2, and therefore is incompatible with frameworks built upon SwiftNIO 1. SwiftNIO 2 is used as of Vapor 4.0 and Kitura 2.5. + ## Development Instructions See our [development guide](https://mongodb.github.io/mongo-swift-driver/development.html) for instructions for building and testing the driver.