mongo 1.6.4 → 1.7.0.rc0

data/README.md

@@ -25,18 +25,18 @@ For the reference manual, use the links in the upper-left and upper-right corner
 
 This documentation has other articles of interest, including:
 
-1. [A tutorial](docs/TUTORIAL.md).
-2. [Replica Sets in Ruby](docs/REPLICA_SETS.md).
-3. [Write Concern in Ruby](docs/WRITE_CONCERN.md).
-4. [Tailable Cursors in Ruby](docs/TAILABLE_CURSORS.md).
-5. [Read Preference in Ruby](docs/READ_PREFERENCE.md).
-6. [GridFS in Ruby](docs/GridFS.md).
-7. [Frequently Asked Questions](docs/FAQ.md).
-8. [History](docs/HISTORY.md).
-9. [Release plan](docs/RELEASES.md).
-10. [Credits](docs/CREDITS.md).
-
-Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](docs/TUTORIAL.md)
+1. [A tutorial](file.TUTORIAL.html).
+2. [Replica Sets in Ruby](file.REPLICA_SETS.html).
+3. [Write Concern in Ruby](file.WRITE_CONCERN.html).
+4. [Tailable Cursors in Ruby](file.TAILABLE_CURSORS.html).
+5. [Read Preference in Ruby](file.READ_PREFERENCE.html).
+6. [GridFS in Ruby](file.GRID_FS.html).
+7. [Frequently Asked Questions](file.FAQ.html).
+8. [History](file.HISTORY.html).
+9. [Release plan](file.RELEASES.html).
+10. [Credits](file.CREDITS.html).
+
+Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](file.TUTORIAL.html)
 for much more:
 
     require 'rubygems'
@@ -104,7 +104,7 @@ That's all there is to it!
 
 # Examples
 
-For extensive examples, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html).
+For extensive examples, see the [MongoDB Ruby Tutorial](file.TUTORIAL.html).
 
 Bundled with the driver are many examples, located in the "docs/examples" subdirectory. Samples include using
 the driver and using the GridFS class GridStore. MongoDB must be running for

data/Rakefile

@@ -99,56 +99,53 @@ namespace :test do
   desc "Run the replica set test suite"
   Rake::TestTask.new(:rs) do |t|
     t.test_files = FileList['test/replica_sets/*_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   desc "Run the replica set test suite"
   Rake::TestTask.new(:rs_no_threads) do |t|
     t.test_files = FileList['test/replica_sets/*_test.rb'] - ["test/replica_sets/refresh_with_threads_test.rb"]
-    t.verbose    = true
+    t.ruby_opts << '-w'
+  end
+
+  desc "Run the sharded cluster test suite"
+  Rake::TestTask.new(:sc) do |t|
+    t.test_files = FileList['test/sharded_cluster/*_test.rb']
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:unit) do |t|
     t.test_files = FileList['test/unit/*_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:functional) do |t|
     t.test_files = FileList['test/*_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:pooled_threading) do |t|
     t.test_files = FileList['test/threading/*_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:auto_reconnect) do |t|
     t.test_files = FileList['test/auxillary/autoreconnect_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:authentication) do |t|
     t.test_files = FileList['test/auxillary/authentication_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:new_features) do |t|
     t.test_files = FileList['test/auxillary/1.4_features.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
   Rake::TestTask.new(:bson) do |t|
     t.test_files = FileList['test/bson/*_test.rb']
-    t.verbose    = true
     t.ruby_opts << '-w'
   end
 
@@ -176,7 +173,7 @@ task :ydoc do
   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"
+  system "yardoc -o #{out} --title MongoRuby-#{Mongo::VERSION}"
 end
 
 namespace :jenkins do

data/docs/HISTORY.md

@@ -1,5 +1,21 @@
 # MongoDB Ruby Driver History
 
+### 1.7.0
+2012-08-20
+
+* Added testing and full support for MongoDB 2.1 & 2.2
+* Added Aggregation Framework helper method
+* Added support for Mongos high availability
+* Modified and added new read preferences (details in documentation)
+* Added support for data center awareness (tag_sets)
+* Fixed bug which attempted to close cursors on wrong replica set member
+
+### 1.6.4
+2012-06-06
+
+* Added ability to declare sort ordering via an ordered hash
+* Addresses major compatability issue with mongoid created by v1.6.3
+
 ### 1.6.3
 2012-06-05
 

data/docs/READ_PREFERENCE.md

@@ -1,15 +1,22 @@
 # Read Preference in Ruby
 
-## Setting the read preference
+## About Read Preference
 
-You can using the `:read` option to specify a query's read preference. There are for now two possible options:
+Read preferences determine the candidate replica set members to which a query or command can be sent. They consist of a *mode* specified as a symbol and an array of hashes known as *tag_sets*.
 
-    @collection.find({:doc => 'foo'}, :read => :primary)
-    @collection.find({:doc => 'foo'}, :read => :secondary)
+Read preference mode is configured by providing the read option to a connection, database, collection, or cursor.
 
-In the first case, the query will be directed to the primary node in a replica set. In the second, the query will be sent
-to a secondary node. The driver will attempt to choose a secondary node that's nearby, as determined by ping time. If more
-than one secondary node is closeby (e.g, responds to pings within 10ms), then a random node within this subset will be chosen.
+    @collection.find({:doc => 'foo'}, :read => :primary)    # read from primary only
+    @collection.find({:doc => 'foo'}, :read => :secondary)  # read from secondaries only
+
+Used in conjunction with tag_sets:
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => [{:continent => 'USA'}])
+
+*Please Note*: Behavior of some read preference modes have changed in version 1.7.0:
+
+* `:secondary_preferred` mode is now used to prefer reads from secondary members (before this was the behavior of `:secondary`).
+* `:secondary_only` mode (which only allowed reads from secondaries) is now called `:secondary`.
 
 ## Read preference inheritance
 
@@ -33,7 +40,60 @@ You can examine the read preference on any object by calling its `read_preferenc
     @db.read_preference
     @collection.read_preference
 
-## Future work
+## Modes
+
+You can using the `:read` option to specify a query's read preference mode. There are five possible options.
+
+### :primary
+
+With primary, all read operations from the client will use the primary member only. This is the default read preference.
+
+If the primary is unavailable, all operations with this preference produce an error or throw an exception. Primary read preference modes are not compatible with read preferences modes that use tag sets If you specify a tag set with primary, the driver will produce an error.
+
+### :primary_preferred
+
+With the primaryPreferred read preference mode, operations will read from the primary member of the set in most situations. However, if the primary is unavailable, as is the case during failover situations, then these read operations can read from secondary members.
+
+When the read preference includes a tag set, the client will first read from the primary, if it is available, and then from secondaries that match the specified tags. If there are no secondaries with tags that match the specified tags, this read operation will produce an error.
+
+### :secondary
+
+With the secondary read preference mode, operations will read from the secondary member of the set if available. However, if there are no secondaries available, then these operations will produce an error or exception.
+
+Most sets have at least one secondary, but there are situations where there may not be an available secondary. For example, a set with a primary, a secondary, and an arbiter may not have any secondaries if a member is ever in recovering mode.
+
+When the read preference includes a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group. If there are no secondaries with tags that match the specified tag set, this read operation will produce an error.
+
+### :secondary_preferred
+
+With the secondaryPreferred, operations will read from secondary members, but in situations where the set only has a primary instance, the read operation will use the set’s primary.
+
+When secondaryPreferred reads from a secondary and the read preference includes a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group. If there are no secondaries with tags that match the specified tag set, this read operation will produce an error.
+
+### :nearest
+
+With the nearest, the driver will read from the nearest member of the set according to the member selection process nearest read operations will not have any consideration for the type of the set member. Reads in nearest mode may read from both primaries and secondaries.
+
+Set this mode when you want minimize the effect of network latency on read operations without preference for current or stale data.
+
+If you specify a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group.
+
+## Tag Sets
+
+Tag sets can be used in for data center awareness by filtering secondary read operations. Primary reads occur independent of any tags.
+
+A member matches a tag set if its tags match all the tags in the set. For example, a member tagged "{ dc: 'ny', rack: 2, size: 'large' }" matches the tag set "{ dc: 'ny', rack: 2 }". A member's extra tags don't affect whether it's a match.
+
+Here is an example of a query which sends read operations to members in rack 2.
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => [{:rack => '2'}])
+
+Tag set keys may be symbols or strings. Tag set values should be specified using strings. The `to_s` method will be called on any values provided in the tag set.
+
+Tag sets are used in conjunction with read preference mode. In this example, because we specified a mode of secondary_preferred, if no secondaries can be found that match the tag_set `{:rack => '2'}` then the primary will be used for the query.
+
+If only one tag set is provided, the set can be passed as a single hash parameter iteself without the enclosing array.
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => {:rack => '2'})
 
-In the v2.0 release of the driver, you'll also be able to specify a read preference consisting of a set of tags. This way,
-you'll be able to direct reads to a replica set member. You can follow this issue's progress here: (https://jira.mongodb.org/browse/RUBY-326).
+Specifiying tag_sets for mode `:primary` is considered an error and will raise a MongoArgumentError as tag_sets do not affect selection of primary members and only primary members can be selected in that particular mode.

data/docs/TUTORIAL.md

@@ -180,7 +180,7 @@ Direction defaults to ascending order but can be specified as Mongo::ASCENDING,
     coll.find.sort(:i)
 
     # Sort in descending order by :i
-    coll.find.sort([:i, :desc])
+    coll.find.sort(:i => :desc)
 
 #### Counting Documents in a Collection
 
@@ -208,7 +208,7 @@ Use the `:fields` option to specify fields to return.
 
 #### Querying with Regular Expressions
 
-Regular expressions can be used to query MongoDB. To find all names that begin with 'a':
+Regular expressions can be used to query MongoDB. To find all names that begin with 'M':
 
     puts coll.find({"name" => /^M/}).to_a
 

data/lib/mongo.rb

@@ -59,6 +59,7 @@ require 'mongo/util/logging'
 require 'mongo/util/node'
 require 'mongo/util/pool'
 require 'mongo/util/pool_manager'
+require 'mongo/util/sharding_pool_manager'
 require 'mongo/util/server_version'
 require 'mongo/util/ssl_socket'
 require 'mongo/util/tcp_socket'
@@ -68,6 +69,7 @@ require 'mongo/collection'
 require 'mongo/networking'
 require 'mongo/connection'
 require 'mongo/repl_set_connection'
+require 'mongo/sharded_connection'
 require 'mongo/cursor'
 require 'mongo/db'
 require 'mongo/exceptions'

data/lib/mongo/collection.rb

@@ -23,6 +23,9 @@ module Mongo
 
     attr_reader :db, :name, :pk_factory, :hint, :safe
 
+    # Read Preference
+    attr_accessor :read_preference, :tag_sets, :acceptable_latency
+
     # Initialize a collection object.
     #
     # @param [String, Symbol] name the name of the collection.
@@ -97,6 +100,8 @@ module Mongo
           value = @db.read_preference
         end
         @read_preference = value.is_a?(Hash) ? value.dup : value
+        @tag_sets = opts.fetch(:tag_sets, @db.tag_sets)
+        @acceptable_latency = opts.fetch(:acceptable_latency, @db.acceptable_latency)
       end
       @pk_factory = pk_factory || opts[:pk] || BSON::ObjectId
       @hint = nil
@@ -109,7 +114,7 @@ module Mongo
     #
     # @return [Boolean]
     def capped?
-      @db.command({:collstats => @name})['capped'] == 1
+      [1, true].include? @db.command({:collstats => @name})['capped']
     end
 
     # Return a sub-collection of this collection by name. If 'users' is a collection, then
@@ -220,6 +225,8 @@ module Mongo
       transformer = opts.delete(:transformer)
       show_disk_loc = opts.delete(:show_disk_loc)
       read          = opts.delete(:read) || @read_preference
+      tag_sets      = opts.delete(:tag_sets) || @tag_sets
+      acceptable_latency = opts.delete(:acceptable_latency) || @acceptable_latency
 
       if timeout == false && !block_given?
         raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
@@ -247,7 +254,9 @@ module Mongo
         :max_scan    => max_scan,
         :show_disk_loc => show_disk_loc,
         :return_key    => return_key,
-        :read          => read
+        :read          => read,
+        :tag_sets      => tag_sets,
+        :acceptable_latency => acceptable_latency
       })
 
       if block_given?
@@ -432,9 +441,13 @@ module Mongo
       update_options  = 0
       update_options += 1 if opts[:upsert]
       update_options += 2 if opts[:multi]
+
+      # Determine if update document has modifiers and check keys if so
+      check_keys = document.keys.first.to_s.start_with?("$") ? false : true
+
       message.put_int(update_options)
       message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
-      message.put_binary(BSON::BSON_CODER.serialize(document, false, true, @connection.max_bson_size).to_s)
+      message.put_binary(BSON::BSON_CODER.serialize(document, check_keys, true, @connection.max_bson_size).to_s)
 
       instrument(:update, :database => @db.name, :collection => @name, :selector => selector, :document => document) do
         if safe
@@ -581,7 +594,52 @@ module Mongo
 
       @db.command(cmd)['value']
     end
+    
+    # Perform an aggregation using the aggregation framework on the current collection.
+    # @note Aggregate requires server version >= 2.1.1
+    # @note Field References: Within an expression, field names must be quoted and prefixed by a dollar sign ($).
+    #
+    # @example Define the pipeline as an array of operator hashes:
+    #   coll.aggregate([ {"$project" => {"last_name" => 1, "first_name" => 1 }}, {"$match" => {"last_name" => "Jones"}} ])
+    #
+    # @param [Array] pipeline Should be a single array of pipeline operator hashes.
+    #   
+    #   '$project' Reshapes a document stream by including fields, excluding fields, inserting computed fields, 
+    #   renaming fields,or creating/populating fields that hold sub-documents.
+    #
+    #   '$match' Query-like interface for filtering documents out of the aggregation pipeline.
+    #
+    #   '$limit' Restricts the number of documents that pass through the pipline.
+    #
+    #   '$skip' Skips over the specified number of documents and passes the rest along the pipeline.
+    #
+    #   '$unwind' Peels off elements of an array individually, returning one document for each member.
+    #
+    #   '$group' Groups documents for calculating aggregate values.
+    #
+    #   '$sort' Sorts all input documents and returns them to the pipeline in sorted order.
+    #
+    # @return [Array] An Array with the aggregate command's results.
+    #
+    # @raise MongoArgumentError if operators either aren't supplied or aren't in the correct format.
+    # @raise MongoOperationFailure if the aggregate command fails.
+    #
+    def aggregate(pipeline=nil)
+      raise MongoArgumentError, "pipeline must be an array of operators" unless pipeline.class == Array
+      raise MongoArgumentError, "pipeline operators must be hashes" unless pipeline.all? { |op| op.class == Hash }
 
+      hash = BSON::OrderedHash.new
+      hash['aggregate'] = self.name
+      hash['pipeline'] = pipeline
+
+      result = @db.command(hash)
+      unless Mongo::Support.ok?(result)
+        raise Mongo::OperationFailure, "aggregate failed: #{result['errmsg']}"
+      end
+      
+      return result["result"]
+    end
+    
     # Perform a map-reduce operation on the current collection.
     #
     # @param [String, BSON::Code] map a map function, written in JavaScript.
@@ -714,13 +772,6 @@ module Mongo
       end
     end
 
-    # The value of the read preference. This will be
-    # either +:primary+, +:secondary+, or an object
-    # representing the tags to be read from.
-    def read_preference
-      @read_preference
-    end
-
     private
 
     def new_group(opts={})
@@ -972,7 +1023,7 @@ module Mongo
             message.put_binary(BSON::BSON_CODER.serialize(doc, check_keys, true, @connection.max_bson_size).to_s)
           end
         end
-      raise InvalidOperation, "Exceded maximum insert size of 16,000,000 bytes" if message.size > 16_000_000
+      raise InvalidOperation, "Exceded maximum insert size of 16,777,216 bytes" if message.size > @connection.max_bson_size
 
       instrument(:insert, :database => @db.name, :collection => collection_name, :documents => documents) do
         if safe

data/lib/mongo/connection.rb

@@ -34,6 +34,7 @@ module Mongo
 
     DEFAULT_HOST = 'localhost'
     DEFAULT_PORT = 27017
+    DEFAULT_DB_NAME = 'test'
     GENERIC_OPTS = [:ssl, :auths, :pool_size, :pool_timeout, :timeout, :op_timeout, :connect_timeout, :safe, :logger, :connect]
     CONNECTION_OPTS = [:slave_ok]
 
@@ -41,7 +42,7 @@ module Mongo
 
     attr_reader :logger, :size, :auths, :primary, :safe, :host_to_try,
       :pool_size, :connect_timeout, :pool_timeout,
-      :primary_pool, :socket_class, :op_timeout
+      :primary_pool, :socket_class, :op_timeout, :tag_sets, :acceptable_latency
 
     # Create a connection to single MongoDB instance.
     #
@@ -101,11 +102,11 @@ module Mongo
     # @core self.connections
     def initialize(host=nil, port=nil, opts={})
       if host.nil? and ENV.has_key?('MONGODB_URI')
-        parser = URIParser.new ENV['MONGODB_URI'], opts
+        parser = URIParser.new ENV['MONGODB_URI']
         if parser.replicaset?
           raise MongoArgumentError, "Mongo::Connection.new called with no arguments, but ENV['MONGODB_URI'] implies a replica set."
         end
-        opts = parser.connection_options
+        opts = parser.connection_options.merge! opts
         @host_to_try = [parser.host, parser.port]
       elsif host.is_a?(String)
         @host_to_try = [host, (port || DEFAULT_PORT).to_i]
@@ -126,6 +127,10 @@ module Mongo
       @primary      = nil
       @primary_pool = nil
 
+      # Not set for direct connection
+      @tag_sets = {}
+      @acceptable_latency = 15
+
       check_opts(opts)
       setup(opts)
     end
@@ -173,8 +178,8 @@ module Mongo
     #
     # @return [Mongo::Connection, Mongo::ReplSetConnection]
     def self.from_uri(uri = ENV['MONGODB_URI'], extra_opts={})
-      parser = URIParser.new uri, extra_opts
-      parser.connection
+      parser = URIParser.new uri
+      parser.connection(extra_opts)
     end
 
     # The host name used for this connection.
@@ -206,7 +211,7 @@ module Mongo
     #
     # @return [Boolean]
     def locked?
-      self['admin']['$cmd.sys.inprog'].find_one['fsyncLock'] == 1
+      [1, true].include? self['admin']['$cmd.sys.inprog'].find_one['fsyncLock']
     end
 
     # Unlock a previously fsync-locked mongod process.
@@ -312,7 +317,13 @@ module Mongo
     # @return [Mongo::DB]
     #
     # @core databases db-instance_method
-    def db(db_name, opts={})
+    def db(db_name=nil, opts={})
+      if !db_name && uri = ENV['MONGODB_URI']
+        db_name = uri[%r{/([^/\?]+)(\?|$)}, 1]
+      end
+
+      db_name ||= DEFAULT_DB_NAME
+
       DB.new(db_name, self, opts)
     end
 
@@ -327,6 +338,15 @@ module Mongo
       DB.new(db_name, self)
     end
 
+    def refresh
+    end
+
+    def pin_pool(pool)
+    end
+
+    def unpin_pool(pool)
+    end
+
     # Drop a database.
     #
     # @param [String] name name of an existing database.
@@ -464,7 +484,7 @@ module Mongo
     # The value of the read preference.
     def read_preference
       if slave_ok?
-        :secondary
+        :secondary_preferred
       else
         :primary
       end
@@ -485,15 +505,9 @@ module Mongo
       @max_bson_size
     end
 
-    # Prefer primary pool but fall back to secondary
-    def checkout_best
-      connect unless connected?
-      @primary_pool.checkout
-    end
-
     # Checkout a socket for reading (i.e., a secondary node).
     # Note: this is overridden in ReplSetConnection.
-    def checkout_reader
+    def checkout_reader(mode=:primary, tag_sets={}, acceptable_latency=15)
       connect unless connected?
       @primary_pool.checkout
     end
@@ -505,38 +519,14 @@ module Mongo
       @primary_pool.checkout
     end
 
-    # Checkin a socket used for reading.
-    # Note: this is overridden in ReplSetConnection.
-    def checkin_reader(socket)
-      checkin(socket)
-    end
-
-    # Checkin a socket used for writing.
-    # Note: this is overridden in ReplSetConnection.
-    def checkin_writer(socket)
-      checkin(socket)
-    end
-
     # Check a socket back into its pool.
+    # Note: this is overridden in ReplSetConnection.
     def checkin(socket)
-      if @primary_pool && socket
+      if @primary_pool && socket && socket.pool
         socket.pool.checkin(socket)
       end
     end
 
-    # Excecutes block with the best available socket
-    def best_available_socket
-      socket = nil
-      begin
-        socket = checkout_best
-        yield socket
-      ensure
-        if socket
-          socket.pool.checkin(socket)
-        end
-      end
-    end
-
     protected
 
     def valid_opts