Improved Mongo recipe

cndreisbach · cndreisbach · commit 76ecc79053fa · 2013-08-21T19:23:08.000-04:00
* Fixed code blocks
* Added See Also section
* Moved some solution to discussion
diff --git a/databases/mongo/mongo.asciidoc b/databases/mongo/mongo.asciidoc
@@ -13,54 +13,41 @@ Use Monger to connect to MongoDB and search or manipulate the data. Monger is a
 First, add Monger to your `project.clj` file:
 
 [source,clojure]
----
+----
 (defproject mongo-time "1.0.0"
   :dependencies [[com.novemberain/monger "1.6.0"]])
----
+----
 
 To connect to MongoDB, use the `monger.core/connect!` function. This will store your connection in the `*mongodb-connection*` dynamic var. If you want to get a connection to use without storing it in a dynamic var, you can use `monger.core/connect` with the same options.
 
 [source,clojure]
----
+----
 (require '[monger.core :as mongo]))
 
-;; Connects to localhost, port 27017 by default.
-(mongo/connect!)
-
-;; Connects to another machine.
-(mongo/connect! {:host "192.168.1.100" :port 27017})
+;; Connect to localhost.
+(mongo/connect! {:host "127.0.0.1" :port 27017})
 
-;; Connects using more complex options.
-(let [options (mongo/mongo-options :auto-connect-retry true
-                                   :connect-timeout 15
-                                   :socket-timeout 15)
-      server (mongo/server-address "192.168.1.100" 27017)]
-  (mongo/connect! server options))
-
-;; Connects via a URI.
-(mongo/connect-via-uri! (System/genenv "MONGOHQ_URL"))
-
-;; Disconnects.
+;; Disconnect when you are done.
 (mongo/disconnect!)
----
+----
 
 Once you are connected, you can insert and query documents easily.
 
 [source,clojure]
----
+----
 (require '[monger.core :as mongo]
          '[monger.collection :as coll])
 (import '[org.bson.types ObjectId])
 
 ;; Sets the database in the *mongodb-database* var.
 (mongo/use-db! "mongo-time")
 
-;; Inserts one document. :_id is optional.
-(coll/insert "users" {:_id (ObjectId.) :name "Pete Killibrew" :state "KY"})
+;; Inserts one document.
 (coll/insert "users" {:name "Jeremiah Forthright" :state "TX"})
 
 ;; Inserts a batch of documents.
-(coll/insert-batch "users" [{:name "Wendy Perkins" :state "OK"}
+(coll/insert-batch "users" [{:name "Pete Killibrew" :state "KY"}
+                            {:name "Wendy Perkins" :state "OK"}
                             {:name "Steel Whitaker" :state "OK"}
                             {:name "Sarah LaRue" :state "WY"}])
 
@@ -81,16 +68,37 @@ Once you are connected, you can insert and query documents easily.
 ;; Finds one document and returns it as a Clojure map.
 (coll/find-one-as-map "users" {:name "Sarah LaRue"})
 ;; -> {:_id #<ObjectId 520...>, :state "WY", :name "Sarah LaRue"}
----
+----
 
 ===== Discussion
 
 MongoDB, especially with Monger, can be a natural choice for storing Clojure data. It stores data as BSON (binary JSON), which maps well to Clojure's own vectors and maps.
 
+There are several ways to connect to Mongo, depending on how much you need to customize your connection and whether you have a map of options or a URI.
+
+[source,clojure]
+----
+;; Connects to localhost, port 27017 by default.
+(mongo/connect!)
+
+;; Connects to another machine.
+(mongo/connect! {:host "192.168.1.100" :port 27017})
+
+;; Connects using more complex options.
+(let [options (mongo/mongo-options :auto-connect-retry true
+                                   :connect-timeout 15
+                                   :socket-timeout 15)
+      server (mongo/server-address "192.168.1.100" 27017)]
+  (mongo/connect! server options))
+
+;; Connects via a URI.
+(mongo/connect-via-uri! (System/genenv "MONGOHQ_URL"))
+----
+
 When inserting data, giving each document an `_id` is optional. One will be created for you if you do not have one in your document. It often makes sense to add it yourself, however, if you need to reference the document afterward.
 
 [source,clojure]
----
+----
 (require '[monger.collection :as coll])
 (import '[org.bson.types ObjectId])
 
@@ -100,12 +108,12 @@ When inserting data, giving each document an `_id` is optional. One will be crea
   ;; Later, look up your user by their id.
   (coll/find-map-by-id "users" id))
 ;; -> {:_id #<ObjectId 521...>, :name "Lola Morales"}
----
+----
 
 In its idiomatic usage, Monger is set up to work with one connection and one database, as `monger.core/connect!` and `monger.core/use-db!` set dynamic vars to hold their information. It is easy to work around this, though. You can use `binding` to set these explicitly around code. In addition, you can use the `monger.multi.collection` namespace instead of `monger.collection`. All functions in the `monger.multi.collection` namespace take a database as their first argument.
 
 [source,clojure]
----
+----
 (require '[monger.core :as mongo]
          '[monger.multi.collection :as multi])
 
@@ -130,11 +138,11 @@ In its idiomatic usage, Monger is set up to work with one connection and one dat
   (multi/insert geo-db "shapes"
                 {:name "square" :sides 4
                  :parallel true :equal true}))
----
+----
 
 The basic find functions in `monger.collection` will work for simple queries, but you will soon find yourself needing to make more complex queries, which is where `monger.query` comes in. This is a domain-specific language for MongoDB queries.
 
----
+----
 (require '[monger.query :as q])
 
 ;; Find users, skipping the first two and getting the next three.
@@ -153,6 +161,8 @@ The basic find functions in `monger.collection` will work for simple queries, bu
 (q/with-collection "users"
   (q/find {"$or" [{:state {"$ne" "OK"}}
                   {:name #"^S"}]}))
----
+----
+
+===== See Also
 
 CongoMongo is another Clojure library for working with MongoDB that you can consider.
