mongo 1.6.1 → 1.6.2

data/README.md

@@ -62,7 +62,7 @@ And for a significant performance boost, you'll want to install the C extensions
     $ gem install bson_ext
 
 Note that bson_ext isn't used with JRuby. Instead, some native Java extensions are bundled with the bson gem.
-If you ever need to modify these extenions, you can recompile with the following rake task:
+If you ever need to modify these extensions, you can recompile with the following rake task:
 
     $ rake build:java
 
@@ -103,7 +103,7 @@ See also the test code, especially test/test_db_api.rb.
 
 The Ruby driver include two abstractions for storing large files: Grid and GridFileSystem.
 The Grid class is a Ruby implementation of MongoDB's GridFS file storage
-specification. GridFileSystem is essentailly the same, but provides a more filesystem-like API
+specification. GridFileSystem is essentially the same, but provides a more filesystem-like API
 and assumes that filenames are unique.
 
 An instance of both classes represents an individual file store. See the API reference
@@ -264,9 +264,22 @@ If implementing higher-level timeouts, using tools like `Rack::Timeout`, it's ve
 to call `Mongo::Connection#close` to prevent the subsequent operation from receiving the previous
 request.
 
+### Test-Unit, Shoulda, and Mocha
+
+Running the test suite requires test-unit, shoulda, and mocha.  You can install them as follows:
+
+    $ gem install test-unit
+    $ gem install shoulda
+    $ gem install mocha
+
+The tests assume that the Mongo database is running on the default port. You
+can override the default host (localhost) and port (Connection::DEFAULT_PORT) by
+using the environment variables MONGO_RUBY_DRIVER_HOST and
+MONGO_RUBY_DRIVER_PORT.
+
 # Testing
 
-If you have the source code, you can run the tests.
+If you have the source code, you can run the tests.  Skip this test with the C extension if you're running JRuby.
 
     $ rake test:c
 
@@ -279,7 +292,7 @@ These will run both unit and functional tests. To run these tests alone:
     $ rake test:unit
     $ rake test:functional
 
-To run any individual rake tasks with the C extension enabled, just pass C_EXT=true to the task:
+To run any individual rake tasks with the C extension enabled, just pass C_EXT=true to the task (don't do this with JRuby):
 
     $ rake test:unit C_EXT=true
 
@@ -287,18 +300,6 @@ If you want to test replica set, you can run the following task:
 
     $ rake test:rs
 
-### Shoulda and Mocha
-
-Running the test suite requires shoulda and mocha.  You can install them as follows:
-
-    $ gem install shoulda
-    $ gem install mocha
-
-The tests assume that the Mongo database is running on the default port. You
-can override the default host (localhost) and port (Connection::DEFAULT_PORT) by
-using the environment variables MONGO_RUBY_DRIVER_HOST and
-MONGO_RUBY_DRIVER_PORT.
-
 # Documentation
 
 This documentation is available online at [http://api.mongodb.org/ruby](http://api.mongodb.org/ruby). You can

data/Rakefile

@@ -160,7 +160,7 @@ end
 
 desc "Generate YARD documentation"
 task :ydoc do
-  require 'mongo'
+  require './lib/mongo/version.rb'
   out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
   system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e ./yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/READ_PREFERENCE.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md,docs/CREDITS.md,docs/TAILABLE_CURSORS.md"
@@ -188,7 +188,6 @@ namespace :jenkins do
 end
 
 namespace :gem do
-
   desc "Install the gem locally"
   task :install do
     `gem build bson.gemspec`
@@ -212,17 +211,6 @@ namespace :gem do
     `gem install --no-rdoc --no-ri bson_ext-*.gem`
     `rm bson_ext-*.gem`
   end
-
-  desc "Build all gems"
-  task :build_all do
-    `rm *.gem`
-    `gem build mongo.gemspec`
-    `gem build bson.gemspec`
-    `gem build bson.java.gemspec`
-    `gem build bson_ext.gemspec`
-    puts `ls *.gem`
-  end
-
 end
 
 namespace :ci do
@@ -271,6 +259,7 @@ end
 
 def change_version(new_version)
   version = current_version
+  puts "Changing version from #{version} to #{new_version}"
   VERSION_FILES.each do |filename|
     f = File.open(filename)
     str = f.read
@@ -283,30 +272,47 @@ def change_version(new_version)
 end
 
 namespace :deploy do
-  task :version, [:version] do |t, args|
-    check_version(args[:version])
-    puts args[:version]
+  desc "Change version to new release"
+  task :change_version, [:version] do |t, args|
+    check_version(args[:version]) 
     change_version(args[:version])
   end
 
-  task :git_prepare, [:version] do |t, args|
+  desc "Add version files, commit, tag release"
+  task :git_prepare do |t, args|
     g = Git.open(Dir.getwd())
-    version = args[:version]
-    check_version(version)
-    g.add(VERSION_FILES)
+    version = current_version
+    to_commit = VERSION_FILES << 'docs/HISTORY.md'
+    g.add(to_commit)
     g.commit "RELEASE #{version}"
     g.add_tag("#{version}")
   end
 
+  desc "Push release to github"
   task :git_push do
     g = Git.open(Dir.getwd())
     g.push
   end
 
-  task :gems, [:version] do |t, args|
-    check_version(args[:version])
-    check_gem_list_existence(args[:version])
-    gem_list
+  desc "Build all gems"
+  task :gem_build do
+    `rm *.gem`
+    `gem build mongo.gemspec`
+    `gem build bson.gemspec`
+    `gem build bson.java.gemspec`
+    `gem build bson_ext.gemspec`
+    puts `ls *.gem`
+  end
+
+  desc "Push all gems to RubyGems"
+  task :gem_push do |t, args|
+    check_gem_list_existence(current_version)
+    gem_list.each do |gem|
+      puts "Push #{gem} to RubyGems? (y/N)"
+      if gets.chomp! == 'y'
+        system "gem push #{gem}"
+      end
+    end
   end
 end
 

data/docs/HISTORY.md

@@ -1,5 +1,15 @@
 # MongoDB Ruby Driver History
 
+### 1.6.2
+2012-04-05
+
+* Implements socket timeouts via non-blocking IO instead of Timeout module
+which should greately increase performance in highly threaded applications
+* Added ability to authentication via secondary if primary node unavailable
+* Replica set refresh interval now enforces a lower bound of 60 seconds
+* Added documentation for dropping indexes, collections, databases
+* Test output cleanup (...)s unless failure occurs
+
 ### 1.6.1
 2012-03-07
 

data/docs/RELEASES.md

@@ -45,3 +45,10 @@ Before each relese to Rubygems.org, the following steps will be taken:
 11. Close out release in JIRA.
 
 12. Annouce release on mongodb-user and mongodb-dev.
+
+## Rake Deploy Tasks
+1. rake deploy:change_version[1.6.1]
+2. rake deploy:git_prepare
+3. rake deploy:git_push
+4. rake deploy:gem_build
+5. rake deploy:gem_push

data/docs/REPLICA_SETS.md

@@ -41,8 +41,8 @@ the state of any secondary node, the automated refresh will ensure that this sta
 
 There are two secenarios in which refresh is helpful and does not raise exceptions:
 
-# You add a new secondary node to an existing replica set
-# You remove an unused secondary from an existing replica set
+1. You add a new secondary node to an existing replica set
+2. You remove an unused secondary from an existing replica set
 
 If using MongoDB earlier than 2.0 any changes to replica set state will raise exceptions therefore refresh mode will not be useful.
 

data/docs/TUTORIAL.md

@@ -9,8 +9,11 @@ As always, the [latest source for the Ruby driver](http://github.com/mongodb/mon
 ## 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.
@@ -23,67 +26,68 @@ After installing, you may want to look at the [examples](http://github.com/mongo
 
 ## Getting started
 
-#### Using the gem
+Note that the output in the following has been updated to Ruby 1.9, so if you are using Ruby 1.8, you will see some minor differences.  To follow this tutorial interactively, at the command line, run the Interactive Ruby Shell.
 
-All of the code here assumes that you have already executed the following Ruby code:
+    irb
 
-    require 'rubygems'  # not necessary for Ruby 1.9
-    require 'mongo'
+As you execute commands, irb will output the result using the `inspect` method.  If you are editing and running a script for this tutorial, you can view output using the `puts` or `p` methods.
 
-#### Making a Connection
+### Using the gem
 
-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.
+Use the `mongo` gem via the `require` kernel method.
 
-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:
+    require 'rubygems'  # not necessary for Ruby 1.9
+    require 'mongo'
 
-    db = Mongo::Connection.new.db("mydb")
-    db = Mongo::Connection.new("localhost").db("mydb")
-    db = Mongo::Connection.new("localhost", 27017).db("mydb")
+### Making a Connection
 
-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.
+An `Mongo::Connection` instance represents a connection to MongoDB.  You can optionally specify the MongoDB server address and port when connecting. The following example shows three ways to connect to the local machine:
 
-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).
+    connection = Mongo::Connection.new # (optional host/port args)
+    connection = Mongo::Connection.new("localhost")
+    connection = Mongo::Connection.new("localhost", 27017)
 
-#### Listing All Databases
+### 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}
+    connection.database_names
+    connection.database_info.each { |info| puts info.inspect }
 
-    #### Dropping a Database
-    connection.drop_database('database_name')
+The `database_info` method returns a hash mapping database names to the size of the database in bytes.
 
-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:
+## Using a Database
 
-    auth = db.authenticate(my_user_name, my_password)
+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. The following examples use the database "mydb":
 
-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.
+    db = connection.db("mydb")
+    db = Mongo::Connection.new.db("mydb")
 
-#### Getting a List Of Collections
+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.
 
-Each database has zero or more collections.  You can retrieve a list of them from the db (and print out any that are there):
+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).
 
-    db.collection_names.each { |name| puts name }
+### Authentication
 
-and assuming that there are two collections, name and address, in the database, you would see
+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:
 
-    name
-    address
+    auth = db.authenticate(my_user_name, my_password)
 
-as the output.
+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 Collection
+## Using 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.
+Once you have this collection object, you can now do create, read, update, and delete (CRUD) functions on persistent storage.
 
-#### Inserting a Document
+### Creating Documents with `insert`
 
-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
+Once you have the collection object, you can create or `insert` documents into the collection.  For example, lets make a little document that in JSON would be represented as
 
       {
          "name" : "MongoDB",
@@ -95,115 +99,158 @@ Once you have the collection object, you can insert documents into the collectio
                    }
       }
 
-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.
+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)
+    doc = {"name" => "MongoDB", "type" => "database", "count" => 1, "info" => {"x" => 203, "y" => '102'}}
+    id = coll.insert(doc)
 
-#### Updating a Document
+We have saved the `id` for future use below.  Now the collection has been created and you can list it.
 
-We can update the previous document using the `update` method. There are a couple ways to update a document. We can rewrite it:
+#### Getting a List Of Collections
 
-    doc["name"] = "MongoDB Ruby"
-    coll.update({"_id" => doc["_id"]}, doc)
+Each database has zero or more collections.  You can retrieve a list of them from the db (and print out any that are there):
 
-Or we can use an atomic operator to change a single value:
+	db.collection_names
 
-    coll.update({"_id" => doc["_id"]}, {"$set" => {"name" => "MongoDB Ruby"}})
+You should see
 
-Read [more about updating documents|Updating].
+	\["testCollection", "system.indexes"\]
 
-#### Finding the First Document In a Collection using `find_one()`
+#### Adding Multiple Documents
 
-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).
+To demonstrate some more interesting queries, let's add multiple simple documents to the collection.  These documents will have the following form:
 
-    my_doc = coll.find_one()
-    puts my_doc.inspect
+	{
+	    "i" : value
+	}
 
-and you should see:
+Here's how to insert them:
 
-    {"_id"=>#<BSON::ObjectID:0x118576c ...>, "name"=>"MongoDB",
-     "info"=>{"x"=>203, "y"=>102}, "type"=>"database", "count"=>1}
+	100.times { |i| coll.insert("i" => i) }
 
-Note the `_id` element has been added automatically by MongoDB to your document.
+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".
 
-#### Adding Multiple Documents
+### Reading Documents with `find_one` and `find`
 
-To demonstrate some more interesting queries, let's add multiple simple documents to the collection.  These documents will have the following form:
-    {
-       "i" : value
-    }
+#### Reading the First Document in a Collection using `find_one`
 
-Here's how to insert them:
+To retrieve the document that we inserted, we can do a simple `find_one` method to get the first document in the collection.  This method returns a single document directly.
 
-    100.times { |i| coll.insert("i" => i) }
+	coll.find_one
 
-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".
+and you should something like:
 
-#### Counting Documents in a Collection
+	{"_id"=>BSON::ObjectId('4f7b1ea6e4d30b35c9000001'), "name"=>"MongoDB", "type"=>"database", "count"=>1, "info"=>{"x"=>203, "y"=>"102"}}
 
-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.
+Note the `_id` element has been added automatically by MongoDB to your document.
 
-    puts coll.count()
+#### Reading All of the Documents with a Cursor using `find`
 
-and it should print `101`.
+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 }
 
-#### Using a Cursor to get all of the Documents
+and that should print all 101 documents in the collection.  You can take advantage of `Enumerable#to_a`.
 
-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:
+    puts coll.find.to_a
 
-    coll.find().each { |row| puts row.inspect }
+Important note - using `to_a` pulls all of the full result set into memory and is inefficient if you can process by each individual document.  To process with more memory efficiency, use the `each` method with a code block for the cursor.
 
-and that should print all 101 documents in the collection.
+#### Specific Queries
 
-#### 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.  To check that our update worked, find the document by id:
 
-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("_id" => id).to_a
 
-    coll.find("i" => 71).each { |row| puts row.inspect }
+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).to_a
 
 and it should just print just one document:
 
-    {"_id"=>#<BSON::ObjectID:0x117de90 ...>, "i"=>71}
+    {"_id"=>BSON::ObjectId('4f7b20b4e4d30b35c9000049'), "i"=>71}
+
+#### 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.
+
+    coll.count
+
+and it should print `101`.
 
 #### 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 }
+    puts coll.find("i" => {"$gt" => 50}).to_a
 
 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 }
+    puts coll.find("i" => {"$gt" => 20, "$lte" => 30}).to_a
 
-#### Selecting a subset of fields for a query
+#### Selecting a Subset of Fields for a Query
 
-Use the `:fields` option. If you just want fields "a" and "b":
+Use the `:fields` option to specify fields to return.
 
-    coll.find("i" => {"$gt" => 50}, :fields => ["a", "b"]).each { |row| puts row }
+    puts coll.find("_id" => id, :fields => ["name", "type"]).to_a
 
 #### Querying with Regular Expressions
 
 Regular expressions can be used to query MongoDB. To find all names that begin with 'a':
 
-    coll.find({"name" => /^a/})
+    puts coll.find({"name" => /^M/}).to_a
 
 You can also construct a regular expression dynamically. To match a given search string:
 
+    params = {'search' => 'DB'}
     search_string = params['search']
 
     # Constructor syntax
-    coll.find({"name" => Regexp.new(search_string)})
+    puts coll.find({"name" => Regexp.new(search_string)}).to_a
 
     # Literal syntax
-    coll.find({"name" => /#{search_string}/})
+    puts coll.find({"name" => /#{search_string}/}).to_a
 
 Although MongoDB isn't vulnerable to anything like SQL-injection, it may be worth checking the search string for anything malicious.
 
+### Updating Documents with `update`
+
+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" => id}, doc)
+
+Or we can use an atomic operator to change a single value:
+
+    coll.update({"_id" => id}, {"$set" => {"name" => "MongoDB Ruby"}})
+
+Verify the update.
+
+    puts coll.find("_id" => id).to_a
+
+Read [more about updating documents|Updating].
+
+### Deleting Documents with `remove`
+
+Use the `remove` method to delete documents.
+
+    coll.count
+    coll.remove("i" => 71)
+    coll.count
+    puts coll.find("i" => 71).to_a
+
+The above shows that the count has been reduced and that the document can no longer be found.
+
+Without arguments, the `remove` method deletes all documents.
+
+    coll.remove
+    coll.count
+
+Please program carefully.
+
 ## Indexing
 
-#### Creating An Index
+### 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:
 
@@ -215,7 +262,21 @@ To specify complex indexes or a descending index you need to use a slightly more
     # Explicit "ascending"
     coll.create_index([["i", Mongo::ASCENDING]])
 
-#### Creating and querying on a geospatial index
+Use the `explain` method on the cursor to show how MongoDB will run the query.
+
+    coll.find("_id" => id).explain
+    coll.find("i" => 71).explain
+    coll.find("type" => "database").explain
+
+The above shows that the query by `_id` and `i` will use faster indexed BtreeCursor, while the query by `type` will use a slower BasicCursor.
+
+### Getting a List of Indexes on a Collection
+
+You can get a list of the indexes on a collection.
+
+    coll.index_information
+
+### Creating and Querying on a Geospatial Index
 
 First, create the index on a field containing long-lat values:
 
@@ -224,12 +285,48 @@ First, create the index on a field containing long-lat values:
 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 
+      puts p.inspect
     end
 
-#### Getting a List of Indexes on a Collection
+## Dropping
+
+### Drop an Index
+
+To drop a secondary index, use the `drop_index` method on the collection.
+
+    coll.drop_index("i_1")
+    coll.index_information
+
+The dropped index is no longer listed.
+
+### Drop All Indexes
+
+To drop all secondary indexes, use the `drop_indexes` method on the collection.
+
+    coll.drop_indexes
+    coll.index_information
+
+Only the primary index "_id_" is listed.
+
+### Drop a Collection
+
+To drop a collection, use the `drop` method on the collection.
+
+    coll.drop
+    db.collection_names
+
+The dropped collection is no longer listed.  The `drop_collection` method can be used on the database as an alternative.
+
+    db.drop_collection("testCollection")
+
+### Drop a Database
+
+To drop a database, use the `drop_database` method on the connection.
+
+    connection.drop_database("mydb")
+    connection.database_names
 
-You can get a list of the indexes on a collection using `coll.index_information()`.
+The dropped database is no longer listed.
 
 ## Database Administration