mongo 1.8.0 → 1.8.2

data/README.md

@@ -1,4 +1,7 @@
-[![Build Status][travis-img]][travis-url] [![Jenkins Status][jenkins-img]][jenkins-url] [![Code Climate][codeclimate-img]][codeclimate-url]
+[![Build Status][travis-img]][travis-url]
+[![Jenkins Status][jenkins-img]][jenkins-url]
+[![Code Climate][codeclimate-img]][codeclimate-url]
+[![Latest Version][version-img]][version-url]
 
 [travis-img]: https://secure.travis-ci.org/mongodb/mongo-ruby-driver.png
 [travis-url]: http://travis-ci.org/mongodb/mongo-ruby-driver
@@ -6,6 +9,8 @@
 [codeclimate-url]: https://codeclimate.com/github/mongodb/mongo-ruby-driver
 [jenkins-img]: https://jenkins.10gen.com/job/mongo-ruby-driver/badge/icon
 [jenkins-url]: https://jenkins.10gen.com/job/mongo-ruby-driver/
+[version-img]: https://badge.fury.io/rb/mongo.png
+[version-url]: http://badge.fury.io/rb/mongo
 [api-url]: http://api.mongodb.org/ruby/current
 
 # Documentation
@@ -97,30 +102,14 @@ you can install it as a gem from the source by typing:
 
 For extensive examples, see the [MongoDB Ruby Tutorial](https://github.com/mongodb/mongo-ruby-driver/wiki/Tutorial).
 
-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
-these examples to work, of course.
-
-Here's how to start MongoDB and run the "simple.rb" example:
-
-      $ cd path/to/mongo
-      $ ./mongod run
-      ... then in another window ...
-      $ cd path/to/mongo-ruby-driver
-      $ ruby docs/examples/simple.rb
-
-See also the test code, especially test/test_db_api.rb.
-
 # GridFS
 
 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 essentially the same, but provides a more filesystem-like API
-and assumes that filenames are unique.
+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
-for details, and see examples/gridfs.rb for code that uses many of the Grid
-features (metadata, content type, seek, tell, etc).
+An instance of both classes represents an individual file store. See the API reference for details.
 
 Examples:
 
@@ -302,26 +291,22 @@ Before running the tests, make sure you install all test dependencies by running
 
     $ gem install bundler; bundle install
 
-To run all default test suites, just type:
+To run all default test suites (without the BSON extensions) just type:
 
     $ rake test
 
-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
-
-If you want to test the basic Ruby encoder, without the C extension, or if you're running JRuby:
+If you want to run the default test suite using the BSON extensions:
 
-    $ rake test:ruby
+    $ rake test:ext
 
 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 (don't do this with JRuby):
+To run any individual rake tasks with the BSON extension disabled, just pass BSON_EXT_DISABLED=true to the task:
 
-    $ rake test:unit C_EXT=true
+    $ rake test:unit BSON_EXT_DISABLED=true
 
 If you want to test replica set, you can run the following task:
 

data/VERSION

@@ -1 +1 @@
-1.8.0
+1.8.2

data/lib/mongo.rb

@@ -50,8 +50,10 @@ end
 
 require 'bson'
 
+require 'mongo/util/thread_local_variable_manager'
 require 'mongo/util/conversions'
 require 'mongo/util/support'
+require 'mongo/util/read_preference'
 require 'mongo/util/write_concern'
 require 'mongo/util/core_ext'
 require 'mongo/util/logging'
@@ -62,6 +64,7 @@ require 'mongo/util/sharding_pool_manager'
 require 'mongo/util/server_version'
 require 'mongo/util/ssl_socket'
 require 'mongo/util/tcp_socket'
+require 'mongo/util/unix_socket'
 require 'mongo/util/uri_parser'
 
 

data/lib/mongo/collection.rb

@@ -29,7 +29,7 @@ module Mongo
                 :write_concern
 
     # Read Preference
-    attr_accessor :read_preference,
+    attr_accessor :read,
                   :tag_sets,
                   :acceptable_latency
 
@@ -37,15 +37,21 @@ module Mongo
     #
     # @param [String, Symbol] name the name of the collection.
     # @param [DB] db a MongoDB database instance.
+    # 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #   
+    #   Notes about write concern:
+    #     These write concern options will be used for insert, update, and remove methods called on this  
+    #     Collection instance. If no value is provided, the default values set on this instance's DB will be used. 
+    #     These option values can be overridden for any invocation of insert, update, or remove.
     #
     # @option opts [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
-    #   other than the default BSON::ObjectId.
-    #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the default write concern
-    #   for +insert+, +update+, and +remove+ method called on this Collection instance. If no
-    #   value is provided, the default values set on this instance's DB will be used. These option 
-    #   values can be overridden for any invocation of +insert+, +update+, or +remove+.
-    # @option options [:primary, :secondary] :read The default read preference for queries
+    #   other than the default BSON::ObjectId. 
+    # @option opts [:primary, :secondary] :read The default read preference for queries
     #   initiates from this connection object. If +:secondary+ is chosen, reads will be sent
     #   to one of the closest available secondary nodes. If a secondary node cannot be located, the
     #   read will be sent to the primary. If this option is left unspecified, the value of the read
@@ -101,12 +107,8 @@ module Mongo
       @cache      = Hash.new(0)
       unless pk_factory
         @write_concern = get_write_concern(opts, db)
-        if value = opts[:read]
-          Mongo::Support.validate_read_preference(value)
-        else
-          value = @db.read_preference
-        end
-        @read_preference    = value.is_a?(Hash) ? value.dup : value
+        @read =  opts[:read] || @db.read
+        Mongo::ReadPreference::validate(@read)
         @tag_sets           = opts.fetch(:tag_sets, @db.tag_sets)
         @acceptable_latency = opts.fetch(:acceptable_latency, @db.acceptable_latency)
       end
@@ -233,7 +235,7 @@ module Mongo
       transformer        = opts.delete(:transformer)
       show_disk_loc      = opts.delete(:show_disk_loc)
       comment            = opts.delete(:comment)
-      read               = opts.delete(:read) || @read_preference
+      read               = opts.delete(:read) || @read
       tag_sets           = opts.delete(:tag_sets) || @tag_sets
       acceptable_latency = opts.delete(:acceptable_latency) || @acceptable_latency
 
@@ -326,7 +328,7 @@ module Mongo
     #   :fsync will confirm that a write has been fsynced. 
     #   Options provided here will override any write concern options set on this collection,
     #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+.
+    #   for DB#get_last_error.
     #
     # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     def save(doc, opts={})
@@ -351,14 +353,15 @@ module Mongo
     #   2nd, a list of invalid documents.
     #   Return this result format only when :collect_on_error is true.
     #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #   
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+. 
     #
     # @option opts [Boolean] :continue_on_error (+false+) If true, then
     #   continue a bulk insert even if one of the documents inserted
@@ -388,14 +391,15 @@ module Mongo
     # @param [Hash] selector
     #   If specified, only matching documents will be removed.
     #
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+. 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+.  
     #
     # @example remove all documents from the 'users' collection:
     #   users.remove
@@ -441,14 +445,15 @@ module Mongo
     # @option opts [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
     # @option opts [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
     #   just the first matching document. Note: only works in MongoDB 1.1.3 or later.
-    # @option opts [Hash] :w, :j, :wtimeout, :fsync Set the write concern for this operation.
-    #   :w > 0 will run a +getlasterror+ command on the database to report any assertion. 
-    #   :j will confirm a write has been committed to the journal,
-    #   :wtimeout specifies how long to wait for write confirmation,
-    #   :fsync will confirm that a write has been fsynced. 
-    #   Options provided here will override any write concern options set on this collection,
-    #   its database object, or the current connection. See the options
-    #   for +DB#get_last_error+. 
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged
+    # @option opts [Boolean] :j (false) Set journal acknowledgement
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout
+    # @option opts [Boolean] :fsync (false) Set fsync acknowledgement.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for DB#get_last_error. 
     #
     # @return [Hash, true] Returns a Hash containing the last error object if acknowledging writes.
     #   Otherwise, returns true.
@@ -506,6 +511,9 @@ module Mongo
     # @option opts [Integer] :min (nil) specify the minimum longitude and latitude for a geo index.
     # @option opts [Integer] :max (nil) specify the maximum longitude and latitude for a geo index.
     #
+    # @example Creating a compound index using a hash: (Ruby 1.9 and above)
+    #   @posts.create_index({'subject' => Mongo::ASCENDING, 'created_at' => Mongo::DESCENDING})
+    #
     # @example Creating a compound index:
     #   @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])
     #
@@ -640,12 +648,16 @@ module Mongo
     #
     #   '$sort' Sorts all input documents and returns them to the pipeline in sorted order.
     #
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this query
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
+    #
     # @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)
+    def aggregate(pipeline=nil, opts={})
       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 }
 
@@ -653,7 +665,7 @@ module Mongo
       hash['aggregate'] = self.name
       hash['pipeline'] = pipeline
 
-      result = @db.command(hash)
+      result = @db.command(hash, command_options(opts))
       unless Mongo::Support.ok?(result)
         raise Mongo::OperationFailure, "aggregate failed: #{result['errmsg']}"
       end
@@ -683,6 +695,9 @@ module Mongo
     #   the instantiated collection that's returned by default. Note if a collection name isn't returned in the
     #   map-reduce output (as, for example, when using :out => { :inline => 1 }), then you must specify this option
     #   or an ArgumentError will be raised.
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to run this map-reduce
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @return [Collection, Hash] a Mongo::Collection object or a Hash with the map-reduce command's results.
     #
@@ -705,7 +720,7 @@ module Mongo
         hash[:sort] = Mongo::Support.format_order_clause(hash[:sort])
       end
 
-      result = @db.command(hash)
+      result = @db.command(hash, command_options(opts))
       unless Mongo::Support.ok?(result)
         raise Mongo::OperationFailure, "map-reduce failed: #{result['errmsg']}"
       end
@@ -740,6 +755,9 @@ module Mongo
     # @option opts [String, BSON::Code] :finalize (nil) a JavaScript function that receives and modifies
     #   each of the resultant grouped objects. Available only when group is run with command
     #   set to true.
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this group
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @return [Array] the command response consisting of grouped items.
     def group(opts, condition={}, initial={}, reduce=nil, finalize=nil)
@@ -829,7 +847,7 @@ module Mongo
         cmd["group"]["$keyf"] = keyf.to_bson_code
       end
 
-      result = @db.command(cmd)
+      result = @db.command(cmd, command_options(opts))
       result["retval"]
     end
 
@@ -841,6 +859,11 @@ module Mongo
     #
     # @param [String, Symbol, OrderedHash] key or hash to group by.
     # @param [Hash] query a selector for limiting the result set over which to group.
+    # @param [Hash] opts the options for this distinct operation.
+    #
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this query
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @example Saving zip codes and ages and returning distinct results.
     #   @collection.save({:zip => 10010, :name => {:age => 27}})
@@ -860,13 +883,14 @@ module Mongo
     #     [27]
     #
     # @return [Array] an array of distinct values.
-    def distinct(key, query=nil)
+    def distinct(key, query=nil, opts={})
       raise MongoArgumentError unless [String, Symbol].include?(key.class)
       command            = BSON::OrderedHash.new
       command[:distinct] = @name
       command[:key]      = key.to_s
       command[:query]    = query
-      @db.command(command)["values"]
+
+      @db.command(command, command_options(opts))["values"]
     end
 
     # Rename this collection.
@@ -931,18 +955,38 @@ module Mongo
     # @option opts [Hash] :query ({}) A query selector for filtering the documents counted.
     # @option opts [Integer] :skip (nil) The number of documents to skip.
     # @option opts [Integer] :limit (nil) The number of documents to limit.
+    # @option opts [:primary, :secondary] :read Read preference for this command. See Collection#find for
+    #  more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @return [Integer]
     def count(opts={})
       find(opts[:query],
-           :skip => opts[:skip],
-           :limit => opts[:limit]).count(true)
+           :skip  => opts[:skip],
+           :limit => opts[:limit],
+           :read  => opts[:read],
+           :comment => opts[:comment]).count(true)
     end
 
     alias :size :count
 
     protected
 
+    # Parse common options for read-only commands from an input @opts
+    # hash and return a hash suitable for passing to DB#command.
+    def command_options(opts)
+      out = {}
+
+      if read = opts[:read]
+        Mongo::ReadPreference::validate(read)
+      else
+        read = @read
+      end
+      out[:read] = read
+      out[:comment] = opts[:comment] if opts[:comment]
+      out
+    end
+
     def normalize_hint_fields(hint)
       case hint
       when String
@@ -972,6 +1016,12 @@ module Mongo
       field_spec = BSON::OrderedHash.new
       if spec.is_a?(String) || spec.is_a?(Symbol)
         field_spec[spec.to_s] = 1
+      elsif spec.is_a?(Hash)
+          if RUBY_VERSION < '1.9' && !spec.is_a?(BSON::OrderedHash)
+              raise MongoArgumentError, "Must use OrderedHash in Ruby < 1.9.0"
+          else
+              field_spec = spec.is_a?(BSON::OrderedHash) ? spec : BSON::OrderedHash.try_convert(spec)
+          end
       elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
         spec.each do |f|
           if [Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D, Mongo::GEOHAYSTACK].include?(f[1])
@@ -983,7 +1033,7 @@ module Mongo
         end
       else
         raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " +
-          "should be either a string, symbol, or an array of arrays."
+          "should be either a hash (OrderedHash), string, symbol, or an array of arrays."
       end
       field_spec
     end

data/lib/mongo/cursor.rb

@@ -27,7 +27,7 @@ module Mongo
       :order, :hint, :snapshot, :timeout,
       :full_collection_name, :transformer,
       :options, :cursor_id, :show_disk_loc,
-      :comment
+      :comment, :read, :tag_sets
 
     # Create a new cursor.
     #
@@ -72,14 +72,10 @@ module Mongo
       @query_run    = false
 
       @transformer = opts[:transformer]
-      if value = opts[:read]
-        Mongo::Support.validate_read_preference(value)
-      else
-        value = collection.read_preference
-      end
-      @read_preference = value.is_a?(Hash) ? value.dup : value
-      @tag_sets = opts.fetch(:tag_sets, @collection.tag_sets)
-      @acceptable_latency = opts.fetch(:acceptable_latency, @collection.acceptable_latency)
+      @read =  opts[:read] || @collection.read
+      Mongo::ReadPreference::validate(@read)
+      @tag_sets = opts[:tag_sets] || @collection.tag_sets
+      @acceptable_latency = opts[:acceptable_latency] || @collection.acceptable_latency
 
       batch_size(opts[:batch_size] || 0)
 
@@ -90,7 +86,7 @@ module Mongo
       if(!@timeout)
         add_option(OP_QUERY_NO_CURSOR_TIMEOUT)
       end
-      if(@read_preference != :primary)
+      if(@read != :primary)
         add_option(OP_QUERY_SLAVE_OK)
       end
       if(@tailable)
@@ -188,7 +184,7 @@ module Mongo
 
       command.merge!(BSON::OrderedHash["fields", @fields])
 
-      response = @db.command(command)
+      response = @db.command(command, :read => @read, :comment => @comment)
       return response['n'].to_i if Mongo::Support.ok?(response)
       return 0 if response['errmsg'] == "ns missing"
       raise OperationFailure.new("Count failed: #{response['errmsg']}", response['code'], response)
@@ -406,7 +402,8 @@ module Mongo
     #
     # @return [Hash]
     def query_options_hash
-      { :selector => @selector,
+      BSON::OrderedHash[
+        :selector => @selector,
         :fields   => @fields,
         :skip     => @skip,
         :limit    => @limit,
@@ -417,7 +414,7 @@ module Mongo
         :max_scan => @max_scan,
         :return_key => @return_key,
         :show_disk_loc => @show_disk_loc,
-        :comment  => @comment }
+        :comment  => @comment ]
     end
 
     # Clean output for inspect.
@@ -485,7 +482,7 @@ module Mongo
             Mongo::Constants::OP_QUERY, message, nil, sock, @command,
             nil, @options & OP_QUERY_EXHAUST != 0)
         rescue ConnectionFailure => ex
-          if tries < 3 && !@socket && (!@command || Mongo::Support.secondary_ok?(@selector))
+          if tries < 3 && !@socket && (!@command || Mongo::Support::secondary_ok?(@selector))
             @connection.unpin_pool(sock.pool) if sock
             @connection.refresh
             retry
@@ -545,7 +542,7 @@ module Mongo
         if @command && !Mongo::Support::secondary_ok?(@selector)
           @connection.checkout_reader(:primary)
         else
-          @connection.checkout_reader(@read_preference, @tag_sets, @acceptable_latency)
+          @connection.checkout_reader(@read, @tag_sets, @acceptable_latency)
         end
       rescue SystemStackError, NoMemoryError, SystemCallError => ex
         @connection.close
@@ -590,13 +587,16 @@ module Mongo
       spec['$returnKey']   = true if @return_key
       spec['$showDiskLoc'] = true if @show_disk_loc
       spec['$comment']  = @comment if @comment
+      if @connection.mongos? && @read != :primary
+        read_pref = Mongo::ReadPreference::mongos(@read, @tag_sets)
+        spec['$readPreference'] = read_pref if read_pref
+      end
       spec
     end
 
-    # Returns true if the query contains order, explain, hint, or snapshot.
     def query_contains_special_fields?
       @order || @explain || @hint || @snapshot || @show_disk_loc ||
-        @max_scan || @return_key || @comment
+        @max_scan || @return_key || @comment || @connection.mongos?
     end
 
     def close_cursor_if_query_complete