mongo 1.0 → 1.1.5

data/docs/HISTORY.md

@@ -0,0 +1,185 @@
+# MongoDB Ruby Driver History
+
+### 1.1.5
+2010-12-15
+
+* ReplSetConnection class. This must be used for replica set connections from
+  now on. You can still use Connection.multi, but that method has been deprecated.
+* Automated replica set tests. rake test:rs
+* Check that request and response ids match.
+* Several bug fixes. See the commit history for details.
+
+### 1.1.4
+2010-11-30
+
+* Important connection failure fix.
+* ObjectId#to_s optimization (David Cuadrado).
+
+### 1.1.3
+2010-11-29
+
+* Distributed reads for replica set secondaries. See /docs/examples/replica_set.rb and
+  http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html for details.
+* Note: when connecting to a replica set, you must use Connection#multi.
+* Cursor#count takes optional skip and limit
+* Collection#ensure_index for caching index creation calls
+* Collection#update and Collection#remove now return error object when using safe mode
+* Important fix for int/long serialization on bug introduced in 1.0.9
+* Numerous tweaks and bug fixes.
+
+### 1.1.2
+2010-11-4
+
+* Two critical fixes to automated failover and replica sets.
+* Bug passing :timeout to Cursor.
+* Permit safe mode specification on Connection, Collection, and DB levels.
+* Specify replica set name on connect to verify connection to the right set.
+* Misc. reorganization of project and docs.
+
+### 1.1.1
+2010-10-14
+
+* Several critical JRuby bug fixes
+* Fixes for JRuby in 1.9 mode
+* Check keys and move id only when necessary for JRuby encoder
+
+## 1.1
+2010-10-4
+
+* Official JRuby support via Java extensons for BSON (beta)
+* Connection#lock! and Connection#unlock! for easy fsync lock
+* Note: BSON::Code is no longer a subclass of String.
+
+### 1.0.9
+2010-9-20
+
+* Significant performance improvements (with a lot of help from Hongli Lai)
+
+### 1.0.8
+2010-8-27
+
+* Cursor#rewind! and more consistent Cursor Enumberable behavior
+* Deprecated ObjectID for ObjectId
+* Numerous minor bug fixes.
+
+### 1.0.7
+2010-8-4
+
+* A few minor test/doc fixes.
+* Better tests for replica sets and replication acknowledgment.
+* Deprecated DB#error and DB#last_status
+
+### 1.0.6
+2010-7-26
+
+* Replica set support.
+* Collection#map_reduce bug fix.
+
+### 1.0.5 
+2010-7-13
+
+* Fix for bug introduced in 1.0.4.
+
+### 1.0.4
+2010-7-13
+
+* Removed deprecated
+  * Cursor admin option
+  * DB#query
+  * DB#create_index (use Collection#create_index)
+  * DB#command only takes hash options now
+* j2bson executable (neomantra)
+* Fixed bson_ext compilation on Solaris (slyphon)
+* System JS helpers (neovintage)
+* Use one mutex per thread on pooled connections (cremes)
+* Check for CursorNotFound response flag
+* MapReduce can return raw command output using :raw
+* BSON::OrderedHash equality with other Ruby hashes (Ryan Angilly)
+* Fix for broken Socket.send with large payloads (Frédéric De Jaeger)
+* Lots of minor improvements. See commmits.
+
+### 1.0.3
+2010-6-15
+
+* Optimiztion for BSON::OrderedHash
+* Some important fixes.
+
+### 1.0.2
+2010-6-5
+
+This is a minor release for fixing an incompatibility with MongoDB v1.5.2
+
+* Fix for boolean response on commands for core server v1.5.2
+* BSON.read_bson_document and b2json executable (neomantra)
+* BSON::ObjectID() shortcut for BSON::ObjectID.from_string (tmm1)
+* Various bug fixes.
+
+### 1.0.1
+2010-5-7
+
+* set Encoding.default_internal
+* DEPRECATE JavaScript string on Collection#find. You now must specify $where explicitly.
+* Added Grid#exist? and GridFileSystem#exist?
+* Support for replication acknowledgment
+* Support for $slice
+* Namespaced OrderedHash under BSON (sleverbor)
+
+## 1.0
+2010-4-29
+Note: if upgrading from versions prior to 0.20, be sure to upgrade
+to 0.20 before upgrading to 1.0.
+
+* Inspected ObjectID is represented in MongoDB extended json format.
+* Support for tailable cursors.
+* Configurable query response batch size (thx. to Aman Gupta)
+
+* bson_ext installs on early release of Ruby 1.8.5 (dfitzgibbon)
+* Deprecated DB#create_index. Use Collection#create_index index.
+* Removed deprecated Grid#put syntax; no longer requires a filename.
+
+### 0.20.1
+2010-4-7
+
+* Added bson gem dependency.
+
+### 0.20
+2010-4-7
+
+If upgrading from a previous version of the Ruby driver, please read these notes carefully,
+along with the 0.20_UPGRADE doc.
+
+* Support for new commands:
+  * Collection#find_and_modify
+  * Collection#stats
+  * DB#stats
+* Query :fields options allows for values of 0 to exclude fields (houdini, railsjedi).
+* GridFS
+  * Option to delete old versions of GridFileSystem entries.
+  * Filename is now optional for Grid#put.
+  * Option to write arbitrary attributes to a file: @grid.put(@data, :favorite_phrase => "blimey!")
+  * Indexes created on the chunks collection are now unique. If you have an existing chunks collection,
+    you may want to remove 
+* Removed the following deprecated items:
+  * GridStore class
+  * RegexpOfHolding class
+  * Paired connections must now be initialized with Connection.paired
+
+* BSON-related code extracted into two separate gems: bson and bson_ext (thx to Chuck Remes).
+  * mongo_ext no longer exists.
+  * BSON::Binary constructor can now take a string, which will be packed into an array.
+  * Exception class adjustments:
+    * Mongo::InvalidObjectID moved to BSON::InvalidObjectID
+    * Mongo::InvalidDocument moved to BSON::InvalidDocument
+    * Mongo::InvalidStringEncoding moved to BSON::InvalidStringEncoding
+    * Mongo::InvalidName replaced by Mongo::InvalidNSName and BSON::InvalidKeyName
+  * BSON types are now namespaced under the BSON module. These types include:
+    * Binary
+    * ObjectID
+    * Code
+    * DBRef
+    * MinKey and MaxKey
+  * Extensions compile on Rubinius (Chuck Remes).
+
+## Prior to 0.20
+
+See git revisions.

data/docs/REPLICA_SETS.md

@@ -0,0 +1,75 @@
+# Replica Sets in Ruby
+
+Here follow a few considerations for those using the MongoDB Ruby driver with [replica sets](http://www.mongodb.org/display/DOCS/Replica+Sets).
+
+### Setup
+
+First, make sure that you've configured and initialized a replica set.
+
+Use `ReplSetConnection.new` to connect to a replica set:
+
+    @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017])
+
+The driver will attempt to connect to a master node and, when found, will replace all seed nodes with known members of the replica set.
+
+### Read slaves
+
+If you want to read from a seconday node, you can pass :read_secondary => true to ReplSetConnection#new.
+
+    @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017],
+                  :read_secondary => true)
+
+A random secondary will be chosen to be read from. In a typical multi-process Ruby application, you'll have a good distribution of reads across secondary nodes.
+
+### Connection Failures
+
+Imagine that either the master node or one of the read nodes goes offline. How will the driver respond?
+
+If any read operation fails, the driver will raise a *ConnectionFailure* exception. It then becomes the client's responsibility to decide how to handle this.
+
+If the client decides to retry, it's not guaranteed that another member of the replica set will have been promoted to master right away, so it's still possible that the driver will raise another *ConnectionFailure*. However, once a member has been promoted to master, typically within a few seconds, subsequent operations will succeed.
+
+The driver will essentially cycle through all known seed addresses until a node identifies itself as master.
+
+### Recovery
+
+Driver users may wish to wrap their database calls with failure recovery code. Here's one possibility, which will attempt to connection
+every half second and time out after thirty seconds.
+
+    # Ensure retry upon failure
+    def rescue_connection_failure(max_retries=60)
+        success = false
+        retries = 0
+        while !success
+          begin
+            yield
+            success = true
+          rescue Mongo::ConnectionFailure => ex
+            retries += 1
+            raise ex if retries >= max_retries
+            sleep(0.5)
+          end
+        end
+      end
+    end
+
+    # Wrapping a call to #count()
+    rescue_connection_failure do
+      @db.collection('users').count()
+    end
+
+Of course, the proper way to handle connection failures will always depend on the individual application. We encourage object-mapper and application developers to publish any promising results.
+
+### Testing
+
+The Ruby driver (>= 1.1.5) includes unit tests for verifying replica set behavior. They reside in *tests/replica_sets*. You can run them as a group with the following rake task:
+
+    rake test:rs
+
+The suite will set up a five-node replica set by itself and ensure that driver behaves correctly even in the face
+of individual node failures. Node that the `mongod` executable must be in the search path for this to work.
+
+### Further Reading
+
+* [Replica Sets](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)
+* [Replics Set Configuration](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)

data/docs/TUTORIAL.md

@@ -0,0 +1,247 @@
+# MongoDB Ruby Driver Tutorial
+
+This tutorial gives many common examples of using MongoDB with the Ruby driver. If you're looking for information on data modeling, see [MongoDB Data Modeling and Rails](http://www.mongodb.org/display/DOCS/MongoDB+Data+Modeling+and+Rails). Links to the various object mappers are listed on our [object mappers page](http://www.mongodb.org/display/DOCS/Object+Mappers+for+Ruby+and+MongoDB).
+
+Interested in GridFS? See [GridFS in Ruby](file.GridFS.html).
+
+As always, the [latest source for the Ruby driver](http://github.com/mongodb/mongo-ruby-driver) can be found on [github](http://github.com/mongodb/mongo-ruby-driver/).
+
+## Installation
+
+The mongo-ruby-driver gem is served through Rubygems.org. To install, make sure you have the latest version of rubygems.
+    gem update --system
+Next, install the mongo rubygem:
+    gem install mongo
+
+The required `bson` gem will be installed automatically.
+
+For optimum performance, install the bson_ext gem:
+
+    gem install bson_ext
+
+After installing, you may want to look at the [examples](http://github.com/mongodb/mongo-ruby-driver/tree/master/examples) directory included in the source distribution. These examples walk through some of the basics of using the Ruby driver.
+
+## Getting started
+
+#### Using the gem
+
+All of the code here assumes that you have already executed the following Ruby code:
+
+    require 'rubygems'  # not necessary for Ruby 1.9
+    require 'mongo'
+
+#### Making a Connection
+
+An `Mongo::Connection` instance represents a connection to MongoDB. You use a Connection instance to obtain an Mongo:DB instance, which represents a named database. The database doesn't have to exist - if it doesn't, MongoDB will create it for you.
+
+You can optionally specify the MongoDB server address and port when connecting. The following example shows three ways to connect to the database "mydb" on the local machine:
+
+    db = Mongo::Connection.new.db("mydb")
+    db = Mongo::Connection.new("localhost").db("mydb")
+    db = Mongo::Connection.new("localhost", 27017).db("mydb")
+
+At this point, the `db` object will be a connection to a MongoDB server for the specified database. Each DB instance uses a separate socket connection to the server.
+
+If you're trying to connect to a replica set, see [Replica Sets in Ruby](http://www.mongodb.org/display/DOCS/Replica+Sets+in+Ruby).
+
+#### Listing All Databases
+
+    connection = Mongo::Connection.new # (optional host/port args)
+    connection.database_names.each { |name| puts name }
+    connection.database_info.each { |info| puts info.inspect}
+
+    #### Dropping a Database
+    connection.drop_database('database_name')
+
+MongoDB can be run in a secure mode where access to databases is controlled through name and password authentication.  When run in this mode, any client application must provide a name and password before doing any operations.  In the Ruby driver, you simply do the following with the connected mongo object:
+
+    auth = db.authenticate(my_user_name, my_password)
+
+If the name and password are valid for the database, `auth` will be `true`.  Otherwise, it will be `false`.  You should look at the MongoDB log for further information if available.
+
+#### Getting a List Of Collections
+
+Each database has zero or more collections.  You can retrieve a list of them from the db (and print out any that are there):
+
+    db.collection_names.each { |name| puts name }
+
+and assuming that there are two collections, name and address, in the database, you would see
+
+    name
+    address
+
+as the output.
+
+#### Getting a Collection
+
+You can get a collection to use using the `collection` method:
+    coll = db.collection("testCollection")
+This is aliased to the \[\] method:
+    coll = db["testCollection"]
+
+Once you have this collection object, you can now do things like insert data, query for data, etc.
+
+#### Inserting a Document
+
+Once you have the collection object, you can insert documents into the collection.  For example, lets make a little document that in JSON would be represented as
+
+      {
+         "name" : "MongoDB",
+         "type" : "database",
+         "count" : 1,
+         "info" : {
+                     x : 203,
+                     y : 102
+                   }
+      }
+
+Notice that the above has an "inner" document embedded within it.  To do this, we can use a Hash or the driver's OrderedHash (which preserves key order) to create the document (including the inner document), and then just simply insert it into the collection using the `insert()` method.
+
+    doc = {"name" => "MongoDB", "type" => "database", "count" => 1,
+           "info" => {"x" => 203, "y" => '102'`
+    coll.insert(doc)
+
+#### Updating a Document
+
+We can update the previous document using the `update` method. There are a couple ways to update a document. We can rewrite it:
+
+    doc["name"] = "MongoDB Ruby"
+    coll.update({"_id" => doc["_id"]}, doc)
+
+Or we can use an atomic operator to change a single value:
+
+    coll.update({"_id" => doc["_id"]}, {"$set" => {"name" => "MongoDB Ruby"`)
+
+Read [more about updating documents|Updating].
+
+#### Finding the First Document In a Collection using `find_one()`
+
+To show that the document we inserted in the previous step is there, we can do a simple `find_one()` operation to get the first document in the collection.  This method returns a single document (rather than the `Cursor` that the `find()` operation returns).
+
+    my_doc = coll.find_one()
+    puts my_doc.inspect
+
+and you should see:
+
+    {"_id"=>#<BSON::ObjectID:0x118576c ...>, "name"=>"MongoDB",
+     "info"=>{"x"=>203, "y"=>102}, "type"=>"database", "count"=>1}
+
+Note the `\_id` element has been added automatically by MongoDB to your document.
+
+#### Adding Multiple Documents
+
+To demonstrate some more interesting queries, let's add multiple simple documents to the collection.  These documents will have the following form:
+    {
+       "i" : value
+    }
+
+Here's how to insert them:
+
+    100.times { |i| coll.insert("i" => i) }
+
+Notice that we can insert documents of different "shapes" into the same collection. These records are in the same collection as the complex record we inserted above.  This aspect is what we mean when we say that MongoDB is "schema-free".
+
+#### Counting Documents in a Collection
+
+Now that we've inserted 101 documents (the 100 we did in the loop, plus the first one), we can check to see if we have them all using the `count()` method.
+
+    puts coll.count()
+
+and it should print `101`.
+
+#### Using a Cursor to get all of the Documents
+
+To get all the documents from the collection, we use the `find()` method. `find()` returns a `Cursor` object, which allows us to iterate over the set of documents that matches our query.  The Ruby driver's Cursor implemented Enumerable, which allows us to use `Enumerable#each`, `Enumerable#map}, etc. For instance:
+
+    coll.find().each { |row| puts row.inspect }
+
+and that should print all 101 documents in the collection.
+
+#### Getting a Single Document with a Query
+
+We can create a _query_ hash to pass to the `find()` method to get a subset of the documents in our collection.  For example, if we wanted to find the document for which the value of the "i" field is 71, we would do the following ;
+
+    coll.find("i" => 71).each { |row| puts row.inspect }
+
+and it should just print just one document:
+
+    {"_id"=>#<BSON::ObjectID:0x117de90 ...>, "i"=>71}
+
+#### Getting a Set of Documents With a Query
+
+We can use the query to get a set of documents from our collection.  For example, if we wanted to get all documents where "i" > 50, we could write:
+
+    coll.find("i" => {"$gt" => 50}).each { |row| puts row }
+
+which should print the documents where i > 50.  We could also get a range, say   20 < i <= 30:
+
+    coll.find("i" => {"$gt" => 20, "$lte" => 30}).each { |row| puts row }
+
+#### Selecting a subset of fields for a query
+
+Use the `:fields` option. If you just want fields "a" and "b":
+
+    coll.find("i" => {"$gt" => 50}, :fields => ["a", "b"]).each { |row| puts row }
+
+#### Querying with Regular Expressions
+
+Regular expressions can be used to query MongoDB. To find all names that begin with 'a':
+
+    coll.find({"name" => /^a/})
+
+You can also construct a regular expression dynamically. To match a given search string:
+
+    search_string = params['search']
+
+    # Constructor syntax
+    coll.find({"name" => Regexp.new(search_string)})
+
+    # Literal syntax
+    coll.find({"name" => /#{search_string}/})
+
+Although MongoDB isn't vulnerable to anything like SQL-injection, it may be worth checking the search string for anything malicious.
+
+## Indexing
+
+#### Creating An Index
+
+MongoDB supports indexes, and they are very easy to add on a collection.  To create an index, you specify an index name and an array of field names to be indexed, or a single field name. The following creates an ascending index on the "i" field:
+
+    # create_index assumes ascending order; see method docs
+    # for details
+    coll.create_index("i")
+To specify complex indexes or a descending index you need to use a slightly more complex syntax - the index specifier must be an Array of [field name, direction] pairs. Directions should be specified as Mongo::ASCENDING or Mongo::DESCENDING:
+
+    # Explicit "ascending"
+    coll.create_index([["i", Mongo::ASCENDING]])
+
+#### Creating and querying on a geospatial index
+
+First, create the index on a field containing long-lat values:
+
+    people.create_index([["loc", Mongo::GEO2D]])
+
+Then get a list of the twenty locations nearest to the point 50, 50:
+
+    people.find({"loc" => {"$near" => [50, 50]}}, {:limit => 20}).each do |p|
+      puts p.inspect 
+    end
+
+#### Getting a List of Indexes on a Collection
+
+You can get a list of the indexes on a collection using `coll.index_information()`.
+
+## Database Administration
+
+A database can have one of three profiling levels: off (:off), slow queries only (:slow_only), or all (:all). To see the database level:
+
+    puts db.profiling_level   # => off (the symbol :off printed as a string)
+    db.profiling_level = :slow_only
+
+Validating a collection will return an interesting hash if all is well or raise an exception if there is a problem.
+    p db.validate_collection('coll_name')
+
+## See Also
+
+* [MongoDB Koans](http://github.com/chicagoruby/MongoDB_Koans) A path to MongoDB enlightenment via the Ruby driver.
+* [MongoDB Manual](http://www.mongodb.org/display/DOCS/Developer+Zone)

data/docs/WRITE_CONCERN.md

@@ -0,0 +1,28 @@
+# Write Concern in Ruby
+
+## Setting the write concern
+
+Write concern is set using the `:safe` option. There are several possible options:
+
+    @collection.save({:doc => 'foo'}, :safe => true)
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2})
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2, :wtimeout => 200})
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2, :wtimeout => 200, :fsync => true})
+
+The first, `true`, simply indicates that we should request a response from the server to ensure that to errors have occurred. The second, `{:w => 2}`forces the server to wait until at least two servers have recorded the write. The third does the same but will time out if the replication can't be completed in 200 milliseconds. The fourth forces an fsync on each server being written to (note: this option is rarely necessary and will have a dramaticly negative effect on performance).
+
+## Write concern inheritance
+
+The Ruby driver allows you to set write concern on each of four levels: the connection, database, collection, and write operation.
+Objects will inherit the default write concern from their parents. Thus, if you set a write concern of `{:w => 1}` when creating
+a new connection, then all databases and collections created from that connection will inherit the same setting. See this code example:
+
+    @con = Mongo::Connection.new('localhost', 27017, :safe => {:w => 2})
+    @db  = @con['test']
+    @collection = @db['foo']
+    @collection.save({:name => 'foo'})
+
+    @collection.save({:name => 'bar'}, :safe => false)
+
+Here, the first call to Collection#save will use the inherited write concern, `{:w => 2}`. But notice that the second call
+to Collection#save overrides this setting.