luciano/mongo-driver-3
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More docs

Browse source
This commit is contained in:
George Narroway 2019-11-17 14:00:30 +08:00
parent e6d935c47e
commit ac1f598f4f
4 changed files with 114 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
CHANGELOG.md
View file

@ -1,6 +1,10 @@
# Change Log
All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/).
## [Unreleased]
### Added
- More documentation
## [0.3.0] - 2019-11-15
### Added
- Added aggregate function
@ -20,5 +24,6 @@ All notable changes to this project will be documented in this file. This change
### Added
- Initial release
[0.3.0]: https://github.com/gnarroway/mongo-driver-3/compare/v0.2.0...HEAD
[Unreleased]: https://github.com/gnarroway/mongo-driver-3/compare/v0.3.0...HEAD
[0.3.0]: https://github.com/gnarroway/mongo-driver-3/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/gnarroway/hato/compare/v0.1.0...v0.2.0

84
README.md
View file

@ -10,11 +10,12 @@ tasks convenient, whilst still allowing the underlying client to be configured v
It was developed with the following goals:
- Simple
- Up to date with the latest driver versions
- Minimal layer that doesn't block any functionality
- Minimal layer that does not prevent access to the underlying driver
- Consistent API across all functions
- Configuration over macros
- Simple
## Status
@ -34,6 +35,85 @@ For Leinengen, add this to your project.clj:
[mongo-driver-3 "0.3.0"]
```
## Getting started
We usually start by creating a client and connecting to a database with a connection string.
`connect-to-db` is a convenience function that allows you to do this directly.
```clojure
(ns my.app
(:require [mongo-driver-3.client :as mcl]))
(mcl/connect-to-db "mongodb://localhost:27017/my-db")
; =>
; {
; :client - a MongoClient instance
; :db - a Database that you can pass to all the collection functions
; }
```
You can also create a client and get a DB manually:
```clojure
;; Calling create without an arg will try and connect to the default host/port.
(def client (mcl/create "mongodb://localhost:27017"))
;; Create a db that you can pass around.
(def db (mcl/get-db client "my-db:))
```
### Collection functions
All the collection functions closely mirror the name of the corresponding java driver
[module](https://mongodb.github.io/mongo-java-driver/3.11/javadoc/com/mongodb/client/MongoCollection.html).
They always take a db as the first argument, collection name as the second,
and an optional map of options as the last. Full documentation of options can be found on
[cljdoc](https://cljdoc.org/d/mongo-driver-3/mongo-driver-3/CURRENT/api/mongo-driver-3.collection).
As an example:
```clojure
(ns my.app
(:require [mongo-driver-3.collection :as mc]))
;; Insert some documents
(mc/insert-many db "test" [{:v "hello"} {:v "world"}])
;; Count all documents
(mc/count-documents db "test")
; => 2
;; Count with a query
(mc/count-documents db "test" {:v "hello"})
; => 1
;; Find the documents, returning a seq
(mc/find db "test' {} {:limit 1 :projection {:_id 0}})
; => ({:v "hello"})
;; Find the documents, returning the raw FindIterable response
(mc/find db "test' {} {:raw? true})
; => a MongoIterable
;; Find a single document or return nil
(mc/find-one db "test' {:v "world"} {:keywordize? false})
; => {"v" "world"}
```
While most options are supported directly, sometimes you may need to configure an operation directly.
In such cases, you can pass in the java options object.
```clojure
;; These are equivalent
(mc/rename db "test" "new-test" {:drop-target? true})
(mc/rename db "test" "new-test" {:rename-collection-options (.dropTarget (RenameCollectionOptions.) true)})
```
Again, read the [docs](https://cljdoc.org/d/mongo-driver-3/mongo-driver-3/CURRENT/api/mongo-driver-3.collection)
for full API documentation.
## License
Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

2
project.clj
View file

@ -1,4 +1,4 @@
(defproject mongo-driver-3 "0.3.0"
(defproject mongo-driver-3 "0.3.1-SNAPSHOT"
:description "A Clojure wrapper for the Java MongoDB driver 3.11+."
:url "https://github.com/gnarroway/mongo-driver-3"
:license {:name "The MIT License"

64
src/mongo_driver_3/collection.clj
View file

@ -12,7 +12,7 @@
;;; Conversions
(defprotocol ConvertToDocument
(^Document document [input] "Convert some clojure to a Mongo Document"))
(^Document document [input] "Convert from clojure to Mongo Document"))
(extend-protocol ConvertToDocument
nil
@ -47,7 +47,7 @@
input))
(defprotocol ConvertFromDocument
(from-document [input keywordize?] "Converts given Document to Clojure"))
(from-document [input keywordize?] "Converts Mongo Document to Clojure"))
(extend-protocol ConvertFromDocument
nil
@ -87,12 +87,7 @@
:snapshot (ReadConcern/SNAPSHOT)})
(defn ->ReadConcern
"Coerce `rc` into a ReadConcern if not nil.
Accepts a ReadConcern or kw corresponding to one:
[:available, :default, :linearizable, :local, :majority, :snapshot]
Invalid values will throw an exception."
"Coerce `rc` into a ReadConcern if not nil. See `collection` for usage."
[rc]
(when rc
(if (instance? ReadConcern rc)
@ -101,12 +96,7 @@
(str "No match for read concern of " (name rc))))))))
(defn ->ReadPreference
"Coerce `rp` into a ReadPreference if not nil.
Accepts a ReadPreference or a kw corresponding to one:
[:primary, :primaryPreferred, :secondary, :secondaryPreferred, :nearest]
Invalid values will throw an exception."
"Coerce `rp` into a ReadPreference if not nil. See `collection` for usage."
[rp]
(when rp
(if (instance? ReadPreference rp)
@ -114,17 +104,7 @@
(ReadPreference/valueOf (name rp)))))
(defn ->WriteConcern
"Coerce write-concern related options to a WriteConcern.
Accepts an options map:
:write-concern A WriteConcern or kw corresponding to one:
[:acknowledged, :journaled, :majority, :unacknowledged, :w1, :w2, :w3],
defaulting to :acknowledged, if some invalid option is provided.
:write-concern/w an int >= 0, controlling the number of replicas to acknowledge
:write-concern/w-timeout-ms How long to wait for secondaries to acknowledge before failing,
in milliseconds (0 means indefinite).
:write-concern/journal? If true, block until write operations have been committed to the journal."
"Coerces write-concern related options to a WriteConcern. See `collection` for usage."
[{:keys [write-concern write-concern/w write-concern/w-timeout-ms write-concern/journal?]}]
(when (some some? [write-concern w w-timeout-ms journal?])
(let [wc (when write-concern
@ -139,20 +119,25 @@
(defn collection
"Coerces `coll` to a MongoCollection with some options.
`db` is a MongoDatabase
`coll` is a collection name or a MongoCollection. This is to provide flexibility in the use of
higher-level fns (e.g. `find-maps`), either in reuse of instances or in some more complex
configuration we do not directly support.
Arguments:
Accepts an options map:
:read-preference
:read-concern
:write-concern
:write-concern/w
:write-concern/w-timeout-ms
:write-concern/journal?
See respective coercion functions for details (->ReadPreference, ->ReadConcern, ->WriteConcern)."
- `db` is a MongoDatabase
- `coll` is a collection name or a MongoCollection. This is to provide flexibility, either in reuse of
instances or in some more complex configuration we do not directly support.
- `opts` (optional), a map of:
- `:read-preference` Accepts a ReadPreference or a kw corresponding to one:
[:primary, :primaryPreferred, :secondary, :secondaryPreferred, :nearest]
Invalid values will throw an exception.
- `:read-concern` Accepts a ReadConcern or kw corresponding to one:
[:available, :default, :linearizable, :local, :majority, :snapshot]
Invalid values will throw an exception.
- `:write-concern` A WriteConcern or kw corresponding to one:
[:acknowledged, :journaled, :majority, :unacknowledged, :w1, :w2, :w3],
defaulting to :acknowledged, if some invalid option is provided.
- `:write-concern/w` an int >= 0, controlling the number of replicas to acknowledge
- `:write-concern/w-timeout-ms` How long to wait for secondaries to acknowledge before failing,
in milliseconds (0 means indefinite).
- `:write-concern/journal?` If true, block until write operations have been committed to the journal."
([^MongoDatabase db coll]
(collection db coll {}))
([^MongoDatabase db coll opts]
@ -166,7 +151,8 @@
;;; CRUD functions
(defn aggregate
"Aggregates documents according to the specified aggregation pipeline and returns an AggregateIterable.
"Aggregates documents according to the specified aggregation pipeline and return a seq of maps,
unless configured otherwise..
Arguments: