The Timezynk/mongo wrapper

This is a Clojure wrapper utilizing the modern (as of 2022), synchronous java API driver for MongoDB.

Installation

The intended way of use is to add the clojar to your project.clj file:

 :dependencies [[com.timezynk/mongo "0.6.17"]]

In order for all API function calls to work properly, you need to have at least MongoDB version 4.4 installed.

Connecting to MongoDB

A MongoDB server can be connected to using a connection string or a connection object:

(require '[com.timezynk.mongo :as m])

(def connection-string "mongodb://mongodb/my-db")

; Creates a connection here
(def connection-object (m/create-connection! "mongodb://mongodb/my-db-2"
                                             :write-concern :unacknowledged))

; Creates a local connection that is closed when running out of scope
(m/with-mongo connection-string
  (m/create-collection! :new-coll)
  (m/insert! :new-coll {:key "value"}))

(m/with-mongo connection-object
  (m/create-collection! :new-coll-2)
  (m/insert! :new-coll-2 {:key "value"}))

(m/close-connecion! connection-object)

A call to create-connection! sets up a physical connection that can be reused. A call to with-mongo will not close it upon completion. A call using a connection string will create a local, physical connection that is then closed when completed.

There are utility functions for reusing a process-local connection:

(require '[com.timezynk.mongo.util :as mu])

(mu/set-mongo-uri! "mongodb://mongodb/my-db" :write-concern :w1)

(mu/wrap-mongo
 (m/create-collection! :new-coll)
 (m/insert! :new-coll {:key "value"}))

The first call to wrap-mongo will create a persistent connection object. Subsequent calls in the same process will reuse the same connection object.

When creating the persistent connection object, the connecion string and options passed by set-mongo-uri! will be used first. If no such call has been made, wrap-mongo will look for a connection string stored in the MONGO_URI environment variable. Failing that, a MongoClientException will be thrown.

Database function calls

Most function calls are variadic, i.e. accept optional parameters. The optional parameters are labelled:

(def collation (m/collation "se" :alternate :shifted))

In the example above, "se" is a required parameter, setting the collation language to Swedish, and :alternate :shifted is an optional, labelled parameter, where :shifted is an enum value, setting this collation to ignore white-space and back-space in ordering and searches.