This guide covers:
This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.
This guide covers Monger 3.1 (including preview releases).
Before using Monger, you need to connect to MongoDB and choose a database to work with. Monger supports working with multiple connections and databases.
To connect, use monger.core/connect function which returns a connection:
(ns my.service.server
(:require [monger.core :as mg])
(:import [com.mongodb MongoOptions ServerAddress]))
;; localhost, default port
(let [conn (mg/connect)])
;; given host, default port
(let [conn (mg/connect {:host "db.megacorp.internal"})])
;; given host, given port
(let [conn (mg/connect {:host "db.megacorp.internal" :port 7878})])
To choose a database, use monger.core/get-db:
(ns my.service.server
(:require [monger.core :as mg]))
(let [conn (mg/connect)
db (mg/get-db conn "monger-test")])
Passing no arguments to monger.core/connect is very common for
development but production environments typically require connection
options tweaks.
This is done by using 2-arity form of monger.core/connect! that
takes a server address and connection options. Because MongoDB
connections have a good dozen of tunable parameters, Monger provides a
function that takes a map of them and produces an object that can be
used as connection options:
(ns my.service.server
(:require [monger.core :as mg])
(:import [com.mongodb MongoOptions ServerAddress]))
;; using MongoOptions allows fine-tuning connection parameters,
;; like automatic reconnection (highly recommended for production environment)
(let [^MongoOptions opts (mg/mongo-options :threads-allowed-to-block-for-connection-multiplier 300)
^ServerAddress sa (mg/server-address "127.0.0.1" 27017)
conn (mg/connect sa opts)]
)
The maximum number of connections allowed per host for this Mongo instance. Those connections will be kept in a pool when idle. Once the pool is exhausted, any operation requiring a connection will block waiting for an available connection.
This multiplier, multiplied with the connectionsPerHost setting, gives the maximum number of threads that may be waiting for a connection to become available from the pool. All further threads will get an exception right away. For example if connectionsPerHost is 10 and threadsAllowedToBlockForConnectionMultiplier is 5, then up to 50 threads can wait for a connection.
The maximum wait time in milliseconds that a thread may wait for a connection to become available. A value of 0 means that it will not wait. A negative value means to wait indefinitely.
The connection timeout in milliseconds. Only used for new connections. A value of 0 means no timeout.
The socket timeout in milliseconds. A value of 0 means no timeout.
This flag controls the socket keep alive feature that keeps a connection alive through firewalls.
If true, the client will keep trying to connect to the same server in case that the socket cannot be established.
he maximum amount of time in milliseconds to spend retrying to open connection to the same server.
:w value of the default write concern of the connection. With Monger, setting default write concern using
monger.core/set-default-write-concern! largely eliminates the need for this option.
:w-timeout value of the default write concern of the connection. With Monger, setting default write concern using
monger.core/set-default-write-concern! largely eliminates the need for this option.
:fsync value of the default write concern of the connection: should all operations wait for server to sync changes to disk?
With Monger, setting default write concern using monger.core/set-default-write-concern! largely eliminates the need for this option.
In certain environments, for example, Heroku or other PaaS providers, the only way to connect to MongoDB is via connection URI.
Monger provides monger.core/connect-via-uri function that combines
monger.core/connect, monger.core/get-db, and
monger.core/authenticate and works with string URIs like
mongodb://userb71148a:0da0a696f23a4ce1ecf6d11382633eb2049d728e@cluster1.mongohost.com:27034/app81766662.
monger.core/connect-via-uri returns a map with two keys:
:conn:dbIt can be used to connect with or without authentication, for example:
;; connect without authentication
(let [uri "mongodb://127.0.0.1/monger-test4"
{:keys [conn db]} (mg/connect-via-uri uri)])
;; connect with authentication
(let [uri "mongodb://clojurewerkz/monger!:monger!@127.0.0.1/monger-test4"
{:keys [conn db]} (mg/connect-via-uri "mongodb://127.0.0.1/monger-test4")])
;; connect using connection URI stored in an env variable, in this case, MONGOHQ_URL
(let [uri (System/genenv "MONGOHQ_URL")
{:keys [conn db]} (mg/connect-via-uri "mongodb://127.0.0.1/monger-test4")])
It is also possible to pass connection options as query parameters:
(let [uri "mongodb://localhost/test?maxPoolSize=128&waitQueueMultiple=5;waitQueueTimeoutMS=150;socketTimeoutMS=5500&autoConnectRetry=true;safe=false&w=1;wtimeout=2500;fsync=true"
{:keys [conn db]} (mg/connect-via-uri "mongodb://127.0.0.1/monger-test4")])
Monger supports connecting to replica sets using one or more seeds
when calling monger.core/connect with a collection of server
addresses instead of just a single one:
(ns my.service
(:require monger.core :as mg))
;; Connect to a single MongoDB instance
(mg/connect (mg/server-address "127.0.0.1" 27017) (mg/mongo-options))
;; Connect to a replica set
(mg/connect [(mg/server-address "127.0.0.1" 27017)
(mg/server-address "127.0.0.1" 27018)]
(mg/mongo-options))
monger.core/connect! function works exactly the same way.
Monger supports authenticated connections. Authentication uses
a set of credentials and happens against a database.
monger.core/connect-with-credentials is the function that opens
a connection with authentication. Some monger.core/connect overloads
accept a set of credentials as well.
Starting with version 3.0, MongoDB Java client supports multiple credential types. Monger provides convenient helpers for two most commonly used ones:
monger.credentials is the namespace with functions that return
credentials accepted by monger.core/connect-with-credentials.
In the example above, a connection is opened with a set of plain credentials:
username "username", password "password", and database "some-db":
(ns monger.docs.examples
(:require [monger.core :as mg]
[monger.credentials :as mcred]))
(let [db "some-db"
u "username"
p "password"]
(mg/connect-with-credentials "127.0.0.1" (mcred/create u db p))
monger.core/connect-with-credentials will return a connection if authentication succeeds and
throw an exception otherwise.
To connect to a replicate set that requires authentication with
Monger, use monger.core/connect with 3 arguments: a set of endpoints,
connection optoins, and a set of credentials. See the "Connecting to a Replica Set"
section above.
To disconnect, use monger.core/disconnect:
(ns my.service.server
(:require [monger.core :as mg]))
(let [conn (mg/connect)]
(mg/disconnect conn))
The documentation is organized as a number of guides, covering all kinds of topics.
We recommend that you read the following guides first, if possible, in this order:
Please take a moment to tell us what you think about this guide on Twitter or the Monger mailing list
Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.