-NOTE: This package is deprecated in favour of the official [Mongo Swift Driver](https://github.com/mongodb/mongo-swift-driver). We advise users to switch to that package if possible.
-
---
+A Swift wrapper around MongoDB's C driver, [libmongoc](https://github.com/mongodb/mongo-c-driver). It covers
+clients and connection pools, databases, collections, cursors, BSON documents and GridFS.
+
+MongoDB stopped developing its official server-side Swift driver in 2023. libmongoc is the driver MongoDB
+still maintains and keeps compliant with its specifications (server discovery, retryable writes,
+authentication, TLS), so this package builds on it.
+
+**Version 4 modernizes this package for Swift 6.** It builds in Swift 6 language mode against libmongoc 2.x,
+keeps the existing public API, and adds Codable and async/await APIs. A few behaviour changes, forced by
+libmongoc 2, are listed in [Documentation/modernization-plan.md](Documentation/modernization-plan.md).
+
+The pre-4.0 version (Swift 4/5, libmongoc 1.x) is preserved on the [`legacy`](../../tree/legacy) branch and
+the 3.x tags.
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/PerfectlySoft/Perfect-MongoDB.git", from: "4.0.0")
+],
+targets: [
+ .target(name: "MyTarget", dependencies: [
+ .product(name: "PerfectMongoDB", package: "Perfect-MongoDB")
+ ])
+]
+```
-This project provides a Swift wrapper around the mongo-c client library,
-enabling access to MongoDB servers.
+## Requirements
-This package builds with Swift Package Manager and is part of the
-[Perfect](https://github.com/PerfectlySoft/Perfect) project. It was written to
-be stand-alone and so does not require PerfectLib or any other components.
+libmongoc **2.x** must be installed where pkg-config can find `mongoc2` and `bson2`.
-Ensure you have installed and activated the latest Swift 4.0 tool chain.
+**macOS** ([Homebrew](https://brew.sh)):
-macOS Build Notes
-----------------
+```sh
+brew install mongo-c-driver
+```
-This package requires the [Homebrew](http://brew.sh) build of mongo-c.
+On Apple silicon, if SwiftPM can't find the library, set `PKG_CONFIG_PATH=/opt/homebrew/lib/pkgconfig`.
-To install Homebrew:
+**Linux:** most distributions still package libmongoc 1.x (for example Ubuntu's `libmongoc-dev`), which
+this version doesn't support. Build libmongoc 2 from source, as the CI workflow in
+`.github/workflows/ci.yml` does:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```sh
+apt-get install cmake libssl-dev libsasl2-dev libzstd-dev
+curl -fsSL https://github.com/mongodb/mongo-c-driver/releases/download/2.5.5/mongo-c-driver-2.5.5.tar.gz | tar xz
+cmake -S mongo-c-driver-2.5.5 -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTS=OFF -DENABLE_EXAMPLES=OFF
+cmake --build build --parallel && sudo cmake --install build
+```
-To install mongo-c:
+## Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-brew install mongo-c-driver
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```swift
+import PerfectMongoDB
-Linux Build Notes
------------------
+let client = try MongoClient(uri: "mongodb://localhost")
+let users = client.getDatabase(name: "app").getCollection(name: "users")!
-Ensure that you have installed components below:
+_ = users.insert(document: try BSON(json: #"{"name": "Ada", "age": 36}"#))
+if let cursor = users.find(query: try BSON(json: #"{"age": {"$gt": 30}}"#)) {
+ for user in cursor {
+ print(user.asString)
+ }
+}
```
-apt-get install libmongoc-dev libbson-dev libssl-dev
+
+### Codable and async/await
+
+`BSONEncoder` and `BSONDecoder` map `Codable` types to BSON documents, keeping dates, binary data, UUIDs and
+ObjectIds as native BSON types. Collections have typed, throwing methods built on them. For concurrency,
+share one `MongoClientPool`. `withClient` runs blocking driver work off Swift's cooperative thread pool,
+and `find` streams results as an `AsyncSequence`:
+
+```swift
+struct User: Codable, Sendable {
+ var _id: BSON.OID
+ var name: String
+ var age: Int
+ var joined: Date
+}
+
+let pool = try MongoClientPool(validatingURI: "mongodb://localhost")
+
+try await pool.withClient { client in
+ let users = client.getCollection(databaseName: "app", collectionName: "users")
+ try users.insert(User(_id: BSON.OID(), name: "Ada", age: 36, joined: Date()))
+ try users.updateOne(filter: try BSON(json: #"{"name": "Ada"}"#),
+ update: try BSON(json: #"{"$inc": {"age": 1}}"#))
+}
+
+for try await user in pool.find(User.self, database: "app", collection: "users",
+ filter: try BSON(json: #"{"age": {"$gt": 30}}"#)) {
+ print(user.name)
+}
```
-Building
---------
+A `MongoClient` and the collections and cursors made from it are not thread-safe: use each from one task at
+a time, which `withClient` and `find` do for you.
+
+## Testing
-Add this project as a dependency in your Package.swift file.
+The tests expect a MongoDB server on `mongodb://localhost`:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.package(url: "https://github.com/PerfectlySoft/Perfect-MongoDB.git", from: "3.0.0")
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```sh
+mongod --dbpath /tmp/mongo-test
+swift test
+```
+
+To run the suite on Linux locally the way CI does (Swift 6.4, libmongoc 2.5.5, MongoDB 8), use Apple's
+[`container`](https://github.com/apple/container) tool:
+
+```sh
+container system start # once
+Scripts/test-linux.sh # extra arguments go to swift test, e.g. --filter Phase4Tests
+```
-Documentation
---------
-Further information can be found at [perfect.org](http://www.perfect.org/docs/MongoDB.html).
+The first run compiles libmongoc into a cached volume (under a minute); later runs take seconds.
diff --git a/README.zh_CN.md b/README.zh_CN.md
index ab9cf89..e5f299d 100644
--- a/README.zh_CN.md
+++ b/README.zh_CN.md
@@ -1,97 +1,123 @@
-Perfect - MongoDB 数据库连接器 [English](README.md)
-===========================
+# Perfect MongoDB
-
Allocates a new doc structure. Call the various append() functions to add fields to the bson. You can iterate the doc at any time using a bson_iter_t and bson_iter_init().
Creates a new doc structure using the data provided. bytes should contain bytes that can be copied into the new doc structure.
- *
- *- parameter bytes: A byte array containing a serialized bson document.
Appends a new field to self.doc of type BSON_TYPE_REGEX. @regex should
- be the regex string. @options should contain the options for the regex.
-
-
Valid options for @options are:
-
-
‘i’ for case-insensitive.
- ’m’ for multiple matching.
- ‘x’ for verbose mode.
- 'l’ to make \w and \W locale dependent.
- ’s’ for dotall mode (’.’ matches everything)
- 'u’ to make \w and \W match unicode.
-
-
For more information on what comprimises a BSON regex, see bsonspec.org.
Appends a new field named key to self.doc, the field is, however,
- incomplete. @child will be initialized so that you may add fields to the
- child array. Child will use a memory buffer owned by self.doc and
- therefore grow the parent buffer as additional space is used. This allows
- a single malloc’d buffer to be used when building arrays which can help
- reduce memory fragmentation.
-
-
The type of @child will be BSON_TYPE_ARRAY and therefore the keys inside
- of it MUST be 0, 1, etc.
Appends a BSON array to self.doc. BSON arrays are like documents where the
- key is the string version of the index. For example, the first item of the
- array would have the key 0. The second item would have the index 1.
Renames the collection using newDbName and newCollectionName, with option to drop existing collection immediately instead of after the move, returning a result status
Validates a collection. The method scans a collection’s data structures for correctness and returns a single document that describes the relationship between the logical collection and the physical representation of the data.
-
-
-
-
Declaration
-
-
Swift
-
publicfuncvalidate(options:BSON)->Result
-
-
-
-
-
Parameters
-
-
-
-
-
- options
-
-
-
-
-
Optional. Specify true to enable a full validation and to return full statistics. MongoDB disables full validation by default because it is a potentially resource-intensive operation.
-
-
-
-
-
-
-
-
-
Return Value
-
BSON document describing the relationship between the collection and its physical representation
Returns statistics about the collection formatted according to the options document.
-
-
-
The options document can contain the following fields and values:
-
scale: number, Optional. The scale used in the output to display the sizes of items. By default, output displays sizes in bytes. To display kilobytes rather than bytes, specify a scale value of 1024.
-
indexDetails: boolean, Optional. If true, stats() returns index details in addition to the collection stats. Only works for WiredTiger storage engine. Defaults to false.
-
indexDetailsKey: document, Optional. If indexDetails is true, you can use indexDetailsKey to filter index details by specifying the index key specification. Only the index that exactly matches indexDetailsKey will be returned. If no match is found, indexDetails will display statistics for all indexes.
-
indexDetailsName: string, Optional. If indexDetails is true, you can use indexDetailsName to filter index details by specifying the index name. Only the index name that exactly matches indexDetailsName will be returned. If no match is found, indexDetails will display statistics for all indexes.
-
-
-
-
-
Declaration
-
-
Swift
-
publicfuncstats(options:BSON)->Result
-
-
-
-
-
Parameters
-
-
-
-
-
- options
-
-
-
-
-
a BSON document defining the format of return.
-
-
-
-
-
-
-
-
-
Return Value
-
BSON document with formatted statistics or Results error document
Optional. Specifies selection filter using query operators. To return all documents in a collection, omit this- Parameter or pass an empty document ({}).
-
-
-
-
-
-
-
- fields
-
-
-
-
-
Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, omit this parameter.
-
-
-
-
-
-
-
- flags
-
-
-
-
-
Optional. set queryFlags for the current search
-
-
-
-
-
-
-
- skip
-
-
-
-
-
Optional. Skip the supplied number of records.
-
-
-
-
-
-
-
- limit
-
-
-
-
-
Optional. return no more than the supplied number of records.
-
-
-
-
-
-
-
- batchSize
-
-
-
-
-
Optional. Change number of automatically iterated documents.
-
-
-
-
-
-
-
-
-
Return Value
-
A cursor to the documents that match the query criteria. When the find() method “returns documents,” the method is actually returning a cursor to the documents.
A document that conains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.
-
-
-
-
-
-
-
- options
-
-
-
-
-
Optional. A document that contains a set of options that controls the creation of the index. see MongoIndexOptions for details.
Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, omit this parameter.
-
-
-
-
-
-
-
- flags
-
-
-
-
-
Optional. set queryFlags for the current search
-
-
-
-
-
-
-
- skip
-
-
-
-
-
Optional. Skip the supplied number of records.
-
-
-
-
-
-
-
- limit
-
-
-
-
-
Optional. return no more than the supplied number of records.
-
-
-
-
-
-
-
- batchSize
-
-
-
-
-
Optional. Change number of automatically iterated documents.
-
-
-
-
-
-
-
-
-
Return Value
-
the count of documents that would match a find() query. The count() method does not perform the find() operation but instead counts and returns the number of results that match a query.
Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify() will only select one document to modify.
-
-
-
-
-
-
-
- sort
-
-
-
-
-
Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify() modifies the first document in the sort order specified by this argument.
-
-
-
-
-
-
-
- update
-
-
-
-
-
Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.
-
-
-
-
-
-
-
- fields
-
-
-
-
-
Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { : 1, : 1, … }.
-
-
-
-
-
-
-
- remove
-
-
-
-
-
Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.
-
-
-
-
-
-
-
- upsert
-
-
-
-
-
Optional. Used in conjunction with the update field. When true, findAndModify() creates a new document if no document matches the query, or if documents match the query, findAndModify() performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed. The default is false.
-
-
-
-
-
-
-
- new
-
-
-
-
-
Optional. When true, returns the modified document rather than the original. The findAndModify() method ignores the new option for remove operations. The default is false.
-
-
-
-
-
-
-
-
-
Return Value
-
Modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the new option.
Allocates a new doc structure. Call the various append() functions to add fields to the bson. You can iterate the doc at any time using a bson_iter_t and bson_iter_init().
Creates a new doc structure using the data provided. bytes should contain bytes that can be copied into the new doc structure.
- *
- *- parameter bytes: A byte array containing a serialized bson document.
Appends a new field to self.doc of type BSON_TYPE_REGEX. @regex should
- be the regex string. @options should contain the options for the regex.
-
-
Valid options for @options are:
-
-
‘i’ for case-insensitive.
- ’m’ for multiple matching.
- ‘x’ for verbose mode.
- 'l’ to make \w and \W locale dependent.
- ’s’ for dotall mode (’.’ matches everything)
- 'u’ to make \w and \W match unicode.
-
-
For more information on what comprimises a BSON regex, see bsonspec.org.
Appends a new field named key to self.doc, the field is, however,
- incomplete. @child will be initialized so that you may add fields to the
- child array. Child will use a memory buffer owned by self.doc and
- therefore grow the parent buffer as additional space is used. This allows
- a single malloc’d buffer to be used when building arrays which can help
- reduce memory fragmentation.
-
-
The type of @child will be BSON_TYPE_ARRAY and therefore the keys inside
- of it MUST be 0, 1, etc.
Appends a BSON array to self.doc. BSON arrays are like documents where the
- key is the string version of the index. For example, the first item of the
- array would have the key 0. The second item would have the index 1.
Renames the collection using newDbName and newCollectionName, with option to drop existing collection immediately instead of after the move, returning a result status
Validates a collection. The method scans a collection’s data structures for correctness and returns a single document that describes the relationship between the logical collection and the physical representation of the data.
-
-
-
-
Declaration
-
-
Swift
-
publicfuncvalidate(options:BSON)->Result
-
-
-
-
-
Parameters
-
-
-
-
-
- options
-
-
-
-
-
Optional. Specify true to enable a full validation and to return full statistics. MongoDB disables full validation by default because it is a potentially resource-intensive operation.
-
-
-
-
-
-
-
-
-
Return Value
-
BSON document describing the relationship between the collection and its physical representation
Returns statistics about the collection formatted according to the options document.
-
-
-
The options document can contain the following fields and values:
-
scale: number, Optional. The scale used in the output to display the sizes of items. By default, output displays sizes in bytes. To display kilobytes rather than bytes, specify a scale value of 1024.
-
indexDetails: boolean, Optional. If true, stats() returns index details in addition to the collection stats. Only works for WiredTiger storage engine. Defaults to false.
-
indexDetailsKey: document, Optional. If indexDetails is true, you can use indexDetailsKey to filter index details by specifying the index key specification. Only the index that exactly matches indexDetailsKey will be returned. If no match is found, indexDetails will display statistics for all indexes.
-
indexDetailsName: string, Optional. If indexDetails is true, you can use indexDetailsName to filter index details by specifying the index name. Only the index name that exactly matches indexDetailsName will be returned. If no match is found, indexDetails will display statistics for all indexes.
-
-
-
-
-
Declaration
-
-
Swift
-
publicfuncstats(options:BSON)->Result
-
-
-
-
-
Parameters
-
-
-
-
-
- options
-
-
-
-
-
a BSON document defining the format of return.
-
-
-
-
-
-
-
-
-
Return Value
-
BSON document with formatted statistics or Results error document
Optional. Specifies selection filter using query operators. To return all documents in a collection, omit this- Parameter or pass an empty document ({}).
-
-
-
-
-
-
-
- fields
-
-
-
-
-
Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, omit this parameter.
-
-
-
-
-
-
-
- flags
-
-
-
-
-
Optional. set queryFlags for the current search
-
-
-
-
-
-
-
- skip
-
-
-
-
-
Optional. Skip the supplied number of records.
-
-
-
-
-
-
-
- limit
-
-
-
-
-
Optional. return no more than the supplied number of records.
-
-
-
-
-
-
-
- batchSize
-
-
-
-
-
Optional. Change number of automatically iterated documents.
-
-
-
-
-
-
-
-
-
Return Value
-
A cursor to the documents that match the query criteria. When the find() method “returns documents,” the method is actually returning a cursor to the documents.
A document that conains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.
-
-
-
-
-
-
-
- options
-
-
-
-
-
Optional. A document that contains a set of options that controls the creation of the index. see MongoIndexOptions for details.
Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, omit this parameter.
-
-
-
-
-
-
-
- flags
-
-
-
-
-
Optional. set queryFlags for the current search
-
-
-
-
-
-
-
- skip
-
-
-
-
-
Optional. Skip the supplied number of records.
-
-
-
-
-
-
-
- limit
-
-
-
-
-
Optional. return no more than the supplied number of records.
-
-
-
-
-
-
-
- batchSize
-
-
-
-
-
Optional. Change number of automatically iterated documents.
-
-
-
-
-
-
-
-
-
Return Value
-
the count of documents that would match a find() query. The count() method does not perform the find() operation but instead counts and returns the number of results that match a query.
Optional. The selection criteria for the modification. The query field employs the same query selectors as used in the db.collection.find() method. Although the query may match multiple documents, findAndModify() will only select one document to modify.
-
-
-
-
-
-
-
- sort
-
-
-
-
-
Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify() modifies the first document in the sort order specified by this argument.
-
-
-
-
-
-
-
- update
-
-
-
-
-
Must specify either the remove or the update field. Performs an update of the selected document. The update field employs the same update operators or field: value specifications to modify the selected document.
-
-
-
-
-
-
-
- fields
-
-
-
-
-
Optional. A subset of fields to return. The fields document specifies an inclusion of a field with 1, as in: fields: { : 1, : 1, … }.
-
-
-
-
-
-
-
- remove
-
-
-
-
-
Must specify either the remove or the update field. Removes the document specified in the query field. Set this to true to remove the selected document . The default is false.
-
-
-
-
-
-
-
- upsert
-
-
-
-
-
Optional. Used in conjunction with the update field. When true, findAndModify() creates a new document if no document matches the query, or if documents match the query, findAndModify() performs an update. To avoid multiple upserts, ensure that the query fields are uniquely indexed. The default is false.
-
-
-
-
-
-
-
- new
-
-
-
-
-
Optional. When true, returns the modified document rather than the original. The findAndModify() method ignores the new option for remove operations. The default is false.
-
-
-
-
-
-
-
-
-
Return Value
-
Modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the new option.
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
+ 
+ 
- 
- Classes Reference
- 
- BSON Class Reference
-