mongo 1.0 → 1.1.5

data/lib/mongo/collection.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -12,20 +14,27 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ++
 
 module Mongo
 
   # A named collection of documents in a database.
   class Collection
 
-    attr_reader :db, :name, :pk_factory, :hint
+    attr_reader :db, :name, :pk_factory, :hint, :safe
 
     # Initialize a collection object.
     #
     # @param [DB] db a MongoDB database instance.
     # @param [String, Symbol] name the name of the collection.
     #
+    # @option options [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
+    #   other than the default BSON::ObjectId.
+    #
+    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    #   for insert, update, and remove method called on this Collection instance. If no
+    #   value is provided, the default value set on this instance's DB will be used. This
+    #   default can be overridden for any invocation of insert, update, or remove.
+    #
     # @raise [InvalidNSName]
     #   if collection name is empty, contains '$', or starts or ends with '.'
     #
@@ -35,7 +44,7 @@ module Mongo
     # @return [Collection]
     #
     # @core collections constructor_details
-    def initialize(db, name, pk_factory=nil)
+    def initialize(db, name, options={})
       case name
       when Symbol, String
       else
@@ -54,9 +63,23 @@ module Mongo
         raise Mongo::InvalidNSName, "collection names must not start or end with '.'"
       end
 
+      if options.respond_to?(:create_pk) || !options.is_a?(Hash)
+        warn "The method for specifying a primary key factory on a Collection has changed.\n" +
+          "Please specify it as an option (e.g., :pk => PkFactory)."
+        pk_factory = options
+      else
+        pk_factory = nil
+      end
+
       @db, @name  = db, name
       @connection = @db.connection
-      @pk_factory = pk_factory || BSON::ObjectID
+      @logger     = @connection.logger
+      @cache_time = @db.cache_time
+      @cache = Hash.new(0)
+      unless pk_factory
+        @safe       = options.has_key?(:safe) ? options[:safe] : @db.safe
+      end
+      @pk_factory = pk_factory || options[:pk] || BSON::ObjectId
       @hint = nil
     end
 
@@ -105,7 +128,10 @@ module Mongo
     #
     # @param [Hash] selector
     #   a document specifying elements which must be present for a
-    #   document to be included in the result set.
+    #   document to be included in the result set. Note that in rare cases,
+    #   (e.g., with $near queries), the order of keys will matter. To preserve
+    #   key order on a selector, use an instance of BSON::OrderedHash (only applies
+    #   to Ruby 1.8).
     #
     # @option opts [Array, Hash] :fields field names that should be returned in the result
     #   set ("_id" will always be included). By limiting results to a certain subset of fields,
@@ -117,12 +143,12 @@ module Mongo
     # @option opts [Array]   :sort an array of [key, direction] pairs to sort by. Direction should
     #   be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
     # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if using MongoDB > 1.1
-    # @option opts [Boolean] :snapshot ('false') if true, snapshot mode will be used for this query.
+    # @option opts [Boolean] :snapshot (false) if true, snapshot mode will be used for this query.
     #   Snapshot mode assures no duplicates are returned, or objects missed, which were preset at both the start and
     #   end of the query's execution. For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
     # @option opts [Boolean] :batch_size (100) the number of documents to returned by the database per GETMORE operation. A value of 0
     #   will let the database server decide how many results to returns. This option can be ignored for most use cases.
-    # @option opts [Boolean] :timeout ('true') when +true+, the returned cursor will be subject to
+    # @option opts [Boolean] :timeout (true) when +true+, the returned cursor will be subject to
     #   the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
     #   that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
     #   close the cursor, as the cursor is explicitly closed when block code finishes.
@@ -141,24 +167,28 @@ module Mongo
       limit  = opts.delete(:limit) || 0
       sort   = opts.delete(:sort)
       hint   = opts.delete(:hint)
-      snapshot = opts.delete(:snapshot)
+      snapshot   = opts.delete(:snapshot)
       batch_size = opts.delete(:batch_size)
-      if opts[:timeout] == false && !block_given?
-        raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block."
+      timeout    = (opts.delete(:timeout) == false) ? false : true
+
+      if timeout == false && !block_given?
+        raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
       end
-      timeout = block_given? ? (opts.delete(:timeout) || true) : true
+
       if hint
         hint = normalize_hint_fields(hint)
       else
         hint = @hint        # assumed to be normalized already
       end
+
       raise RuntimeError, "Unknown options [#{opts.inspect}]" unless opts.empty?
 
       cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit,
-                          :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout, :batch_size => batch_size)
+        :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout, :batch_size => batch_size)
+
       if block_given?
         yield cursor
-        cursor.close()
+        cursor.close
         nil
       else
         cursor
@@ -170,9 +200,9 @@ module Mongo
     # @return [OrderedHash, Nil]
     #   a single document or nil if no result is found.
     #
-    # @param [Hash, ObjectID, Nil] spec_or_object_id a hash specifying elements 
+    # @param [Hash, ObjectId, Nil] spec_or_object_id a hash specifying elements 
     #   which must be present for a document to be included in the result set or an 
-    #   instance of ObjectID to be used as the value for an _id query.
+    #   instance of ObjectId to be used as the value for an _id query.
     #   If nil, an empty selector, {}, will be used.
     #
     # @option opts [Hash]
@@ -184,12 +214,12 @@ module Mongo
       spec = case spec_or_object_id
              when nil
                {}
-             when BSON::ObjectID
+             when BSON::ObjectId
                {:_id => spec_or_object_id}
              when Hash
                spec_or_object_id
              else
-               raise TypeError, "spec_or_object_id must be an instance of ObjectID or Hash, or nil"
+               raise TypeError, "spec_or_object_id must be an instance of ObjectId or Hash, or nil"
              end
       find(spec, opts.merge(:limit => -1)).next_document
     end
@@ -201,19 +231,24 @@ module Mongo
     #   then an update (upsert) operation will be performed, and any existing
     #   document with that _id is overwritten. Otherwise an insert operation is performed.
     #
-    # @return [ObjectID] the _id of the saved document.
+    # @return [ObjectId] the _id of the saved document.
     #
-    # @option opts [Boolean] :safe (+false+) 
-    #   If true, check that the save succeeded. OperationFailure
-    #   will be raised on an error. Note that a safe check requires an extra
-    #   round-trip to the database.
-    def save(doc, options={})
+    # @option opts [Boolean, Hash] :safe (+false+)
+    #   run the operation in safe mode, which run a getlasterror command on the
+    #   database to report any assertion. In addition, a hash can be provided to
+    #   run an fsync and/or wait for replication of the save (>= 1.5.1). See the options
+    #   for DB#error.
+    #
+    # @raise [OperationFailure] when :safe mode fails.
+    #
+    # @see DB#remove for options that can be passed to :safe.
+    def save(doc, opts={})
       if doc.has_key?(:_id) || doc.has_key?('_id')
         id = doc[:_id] || doc['_id']
-        update({:_id => id}, doc, :upsert => true, :safe => options.delete(:safe))
+        update({:_id => id}, doc, :upsert => true, :safe => opts.fetch(:safe, @safe))
         id
       else
-        insert(doc, :safe => options.delete(:safe))
+        insert(doc, :safe => opts.fetch(:safe, @safe))
       end
     end
 
@@ -222,20 +257,25 @@ module Mongo
     # @param [Hash, Array] doc_or_docs
     #   a document (as a hash) or array of documents to be inserted.
     #
-    # @return [ObjectID, Array]
-    #   the _id of the inserted document or a list of _ids of all inserted documents.
-    #   Note: the object may have been modified by the database's PK factory, if it has one.
+    # @return [ObjectId, Array]
+    #   The _id of the inserted document or a list of _ids of all inserted documents.
     #
-    # @option opts [Boolean] :safe (+false+) 
-    #   If true, check that the save succeeded. OperationFailure
-    #   will be raised on an error. Note that a safe check requires an extra
-    #   round-trip to the database.
+    # @option opts [Boolean, Hash] :safe (+false+)
+    #   run the operation in safe mode, which run a getlasterror command on the
+    #   database to report any assertion. In addition, a hash can be provided to
+    #   run an fsync and/or wait for replication of the insert (>= 1.5.1). Safe
+    #   options provided here will override any safe options set on this collection,
+    #   its database object, or the current connection. See the options on
+    #   for DB#get_last_error.
+    #
+    # @see DB#remove for options that can be passed to :safe.
     #
     # @core insert insert-instance_method
     def insert(doc_or_docs, options={})
       doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array)
       doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
-      result = insert_documents(doc_or_docs, @name, true, options[:safe])
+      safe = options.has_key?(:safe) ? options[:safe] : @safe
+      result = insert_documents(doc_or_docs, @name, true, safe)
       result.size > 1 ? result : result.first
     end
     alias_method :<<, :insert
@@ -245,8 +285,12 @@ module Mongo
     # @param [Hash] selector
     #   If specified, only matching documents will be removed.
     #
-    # @option opts [Boolean] :safe [false] run the operation in safe mode, which
-    #   will call :getlasterror on the database and report any assertions.
+    # @option opts [Boolean, Hash] :safe (+false+)
+    #   run the operation in safe mode, which will run a getlasterror command on the
+    #   database to report any assertion. In addition, a hash can be provided to
+    #   run an fsync and/or wait for replication of the remove (>= 1.5.1). Safe
+    #   options provided here will override any safe options set on this collection,
+    #   its database, or the current connection. See the options for DB#get_last_error for more details.
     #
     # @example remove all documents from the 'users' collection:
     #   users.remove
@@ -255,32 +299,33 @@ module Mongo
     # @example remove only documents that have expired:
     #   users.remove({:expire => {"$lte" => Time.now}})
     #
-    # @return [True]
+    # @return [Hash, true] Returns a Hash containing the last error object if running in safe mode.
+    #   Otherwise, returns true.
     #
     # @raise [Mongo::OperationFailure] an exception will be raised iff safe mode is enabled
     #   and the operation fails.
     #
+    # @see DB#remove for options that can be passed to :safe.
+    #
     # @core remove remove-instance_method
     def remove(selector={}, opts={})
       # Initial byte is 0.
-      message = BSON::ByteBuffer.new([0, 0, 0, 0])
+      safe = opts.has_key?(:safe) ? opts[:safe] : @safe
+      message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       message.put_int(0)
-      message.put_array(BSON::BSON_CODER.serialize(selector, false, true).to_a)
+      message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
 
-      if opts[:safe]
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name,
-          "#{@db.name}['#{@name}'].remove(#{selector.inspect})")
-        # the return value of send_message_with_safe_check isn't actually meaningful --
-        # only the fact that it didn't raise an error is -- so just return true
-        true
+      @logger.debug("MONGODB #{@db.name}['#{@name}'].remove(#{selector.inspect})") if @logger
+      if safe
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name, nil, safe)
       else
-        @connection.send_message(Mongo::Constants::OP_DELETE, message,
-          "#{@db.name}['#{@name}'].remove(#{selector.inspect})")
+        @connection.send_message(Mongo::Constants::OP_DELETE, message)
+        true
       end
     end
 
-    # Update a single document in this collection.
+    # Update one or more documents in this collection.
     #
     # @param [Hash] selector
     #   a hash specifying elements which must be present for a document to be updated. Note:
@@ -297,25 +342,30 @@ module Mongo
     # @option opts [Boolean] :safe (+false+) 
     #   If true, check that the save succeeded. OperationFailure
     #   will be raised on an error. Note that a safe check requires an extra
-    #   round-trip to the database.
+    #   round-trip to the database. Safe options provided here will override any safe
+    #   options set on this collection, its database object, or the current collection.
+    #   See the options for DB#get_last_error for details.
+    #
+    # @return [Hash, true] Returns a Hash containing the last error object if running in safe mode.
+    #   Otherwise, returns true.
     #
     # @core update update-instance_method
     def update(selector, document, options={})
       # Initial byte is 0.
-      message = BSON::ByteBuffer.new([0, 0, 0, 0])
+      safe = options.has_key?(:safe) ? options[:safe] : @safe
+      message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       update_options  = 0
       update_options += 1 if options[:upsert]
       update_options += 2 if options[:multi]
       message.put_int(update_options)
-      message.put_array(BSON::BSON_CODER.serialize(selector, false, true).to_a)
-      message.put_array(BSON::BSON_CODER.serialize(document, false, true).to_a)
-      if options[:safe]
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name,
-          "#{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})")
+      message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
+      message.put_binary(BSON::BSON_CODER.serialize(document, false, true).to_s)
+      @logger.debug("MONGODB #{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})") if @logger
+      if safe
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name, nil, safe)
       else
-        @connection.send_message(Mongo::Constants::OP_UPDATE, message,
-          "#{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})")
+        @connection.send_message(Mongo::Constants::OP_UPDATE, message, nil)
       end
     end
 
@@ -333,13 +383,16 @@ module Mongo
     #   Also note that it is permissible to create compound indexes that include a geospatial index as
     #   long as the geospatial index comes first.
     #
+    #   If your code calls create_index frequently, you can use Collection#ensure_index to cache these calls
+    #   and thereby prevent excessive round trips to the database.
+    #
     # @option opts [Boolean] :unique (false) if true, this index will enforce a uniqueness constraint.
     # @option opts [Boolean] :background (false) indicate that the index should be built in the background. This
     #   feature is only available in MongoDB >= 1.3.2.
-    # @option opts [Boolean] :dropDups If creating a unique index on a collection with pre-existing records,
+    # @option opts [Boolean] :drop_dups (nil) If creating a unique index on a collection with pre-existing records,
     #   this option will keep the first document the database indexes and drop all subsequent with duplicate values.
-    # @option opts [Integer] :min specify the minimum longitude and latitude for a geo index.
-    # @option opts [Integer] :max specify the maximum longitude and latitude for a geo index.
+    # @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:
     #   @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])
@@ -359,37 +412,46 @@ module Mongo
     #
     # @core indexes create_index-instance_method
     def create_index(spec, opts={})
-      opts.assert_valid_keys(:min, :max, :background, :unique, :dropDups)
-      field_spec = OrderedHash.new
-      if spec.is_a?(String) || spec.is_a?(Symbol)
-        field_spec[spec.to_s] = 1
-      elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
-        spec.each do |f|
-          if [Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D].include?(f[1])
-            field_spec[f[0].to_s] = f[1]
-          else
-            raise MongoArgumentError, "Invalid index field #{f[1].inspect}; " + 
-              "should be one of Mongo::ASCENDING (1), Mongo::DESCENDING (-1) or Mongo::GEO2D ('2d')."
-          end
-        end
-      else
-        raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " + 
-          "should be either a string, symbol, or an array of arrays."
-      end
+      opts[:dropDups] = opts.delete(:drop_dups) if opts[:drop_dups]
+      field_spec = parse_index_spec(spec)
+      name = opts.delete(:name) || generate_index_name(field_spec)
 
-      name = generate_index_name(field_spec)
+      generate_indexes(field_spec, name, opts)
+      name
+    end
 
-      selector = {
-        :name   => name,
-        :ns     => "#{@db.name}.#{@name}",
-        :key    => field_spec
-      }
-      selector.merge!(opts)
-      begin
-        response = insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
-      rescue Mongo::OperationFailure
-        raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following errors: #{response}"
+    # Calls create_index and sets a flag to not do so again for another X minutes.
+    # this time can be specified as an option when initializing a Mongo::DB object as options[:cache_time]
+    # Any changes to an index will be propogated through regardless of cache time (e.g., a change of index direction)
+    #
+    # The parameters and options for this methods are the same as those for Collection#create_index.
+    #
+    # @example Call sequence:
+    #   Time t: @posts.ensure_index([['subject', Mongo::ASCENDING])  -- calls create_index and
+    #     sets the 5 minute cache
+    #   Time t+2min : @posts.ensure_index([['subject', Mongo::ASCENDING])  -- doesn't do anything
+    #   Time t+3min : @posts.ensure_index([['something_else', Mongo::ASCENDING])  -- calls create_index
+    #     and sets 5 minute cache
+    #   Time t+10min : @posts.ensure_index([['subject', Mongo::ASCENDING])  -- calls create_index and
+    #     resets the 5 minute counter
+    #
+    # @return [String] the name of the index.
+    def ensure_index(spec, opts={})
+      valid = BSON::OrderedHash.new
+      now = Time.now.utc.to_i
+      field_spec = parse_index_spec(spec)
+
+      field_spec.each do |key, value|
+        cache_key = generate_index_name({key => value})
+        timeout = @cache[cache_key] || 0
+        valid[key] = value if timeout <= now
       end
+
+      name = opts.delete(:name) || generate_index_name(valid)
+      generate_indexes(valid, name, opts) if valid.any?
+
+      # Reset the cache here in case there are any errors inserting. Best to be safe.
+      @cache[name] = now + @cache_time
       name
     end
 
@@ -399,6 +461,7 @@ module Mongo
     #
     # @core indexes
     def drop_index(name)
+      @cache[name] = nil
       @db.drop_index(@name, name)
     end
 
@@ -406,6 +469,7 @@ module Mongo
     #
     # @core indexes
     def drop_indexes
+      @cache = {}
 
       # Note: calling drop_indexes with no args will drop them all.
       @db.drop_index(@name, '*')
@@ -416,11 +480,10 @@ module Mongo
       @db.drop_collection(@name)
     end
 
-
     # Atomically update and return a document using MongoDB's findAndModify command. (MongoDB > 1.3.0)
     #
-    # @option opts [Hash] :update (nil) the update operation to perform on the matched document.
     # @option opts [Hash] :query ({}) a query selector document for matching the desired document.
+    # @option opts [Hash] :update (nil) the update operation to perform on the matched document.
     # @option opts [Array, String, OrderedHash] :sort ({}) specify a sort option for the query using any
     #   of the sort options available for Cursor#sort. Sort order is important if the query will be matching
     #   multiple documents since only the first matching document will be updated and returned.
@@ -432,12 +495,12 @@ module Mongo
     #
     # @core findandmodify find_and_modify-instance_method
     def find_and_modify(opts={})
-      cmd = OrderedHash.new
+      cmd = BSON::OrderedHash.new
       cmd[:findandmodify] = @name
       cmd.merge!(opts)
       cmd[:sort] = Mongo::Support.format_order_clause(opts[:sort]) if opts[:sort]
 
-      @db.command(cmd, false, true)['value']
+      @db.command(cmd)['value']
     end
 
     # Perform a map/reduce operation on the current collection.
@@ -455,6 +518,8 @@ module Mongo
     # @option opts [String] :out (nil) the name of the output collection. If specified, the collection will not be treated as temporary.
     # @option opts [Boolean] :keeptemp (false) if true, the generated collection will be persisted. default is false.
     # @option opts [Boolean ] :verbose (false) if true, provides statistics on job execution time.
+    # @option opts [Boolean] :raw (false) if true, return the raw result object from the map_reduce command, and not
+    #   the instantiated collection that's returned by default.
     #
     # @return [Collection] a collection containing the results of the operation.
     #
@@ -464,18 +529,24 @@ module Mongo
     def map_reduce(map, reduce, opts={})
       map    = BSON::Code.new(map) unless map.is_a?(BSON::Code)
       reduce = BSON::Code.new(reduce) unless reduce.is_a?(BSON::Code)
+      raw    = opts.delete(:raw)
 
-      hash = OrderedHash.new
+      hash = BSON::OrderedHash.new
       hash['mapreduce'] = self.name
       hash['map'] = map
       hash['reduce'] = reduce
       hash.merge! opts
 
       result = @db.command(hash)
-      unless result["ok"] == 1
+      unless Mongo::Support.ok?(result)
         raise Mongo::OperationFailure, "map-reduce failed: #{result['errmsg']}"
       end
-      @db[result["result"]]
+
+      if raw
+        result
+      else
+        @db[result["result"]]
+      end
     end
     alias :mapreduce :map_reduce
 
@@ -521,9 +592,9 @@ module Mongo
         group_command['group']['finalize'] = finalize
       end
 
-      result = @db.command group_command
+      result = @db.command(group_command)
 
-      if result["ok"] == 1
+      if Mongo::Support.ok?(result)
         result["retval"]
       else
         raise OperationFailure, "group command failed: #{result['errmsg']}"
@@ -557,7 +628,7 @@ module Mongo
     # @return [Array] an array of distinct values.
     def distinct(key, query=nil)
       raise MongoArgumentError unless [String, Symbol].include?(key.class)
-      command = OrderedHash.new
+      command = BSON::OrderedHash.new
       command[:distinct] = @name
       command[:key]      = key.to_s
       command[:query]    = query
@@ -568,10 +639,12 @@ module Mongo
     # Rename this collection.
     #
     # Note: If operating in auth mode, the client must be authorized as an admin to
-    # perform this operation. 
+    # perform this operation.
     #
     # @param [String] new_name the new name for this collection
     #
+    # @return [String] the name of the new collection.
+    #
     # @raise [Mongo::InvalidNSName] if +new_name+ is an invalid collection name.
     def rename(new_name)
       case new_name
@@ -593,6 +666,7 @@ module Mongo
       end
 
       @db.rename_collection(@name, new_name)
+      @name = new_name
     end
 
     # Get information on the indexes for this collection.
@@ -639,7 +713,7 @@ module Mongo
       when nil
         nil
       else
-        h = OrderedHash.new
+        h = BSON::OrderedHash.new
         hint.to_a.each { |k| h[k] = 1 }
         h
       end
@@ -647,20 +721,66 @@ module Mongo
 
     private
 
+    def parse_index_spec(spec)
+      field_spec = BSON::OrderedHash.new
+      if spec.is_a?(String) || spec.is_a?(Symbol)
+        field_spec[spec.to_s] = 1
+      elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
+        spec.each do |f|
+          if [Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D].include?(f[1])
+            field_spec[f[0].to_s] = f[1]
+          else
+            raise MongoArgumentError, "Invalid index field #{f[1].inspect}; " + 
+              "should be one of Mongo::ASCENDING (1), Mongo::DESCENDING (-1) or Mongo::GEO2D ('2d')."
+          end
+        end
+      else
+        raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " + 
+          "should be either a string, symbol, or an array of arrays."
+      end
+      field_spec
+    end
+
+    def generate_indexes(field_spec, name, opts)
+      selector = {
+        :name   => name,
+        :ns     => "#{@db.name}.#{@name}",
+        :key    => field_spec
+      }
+      selector.merge!(opts)
+
+      begin
+      insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
+
+      rescue Mongo::OperationFailure => e
+        if selector[:dropDups] && e.message =~ /^11000/
+          # NOP. If the user is intentionally dropping dups, we can ignore duplicate key errors.
+        else
+          raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following error: " +
+           "#{e.message}"
+        end
+      end
+
+      nil
+    end
+
     # Sends a Mongo::Constants::OP_INSERT message to the database.
     # Takes an array of +documents+, an optional +collection_name+, and a
     # +check_keys+ setting.
     def insert_documents(documents, collection_name=@name, check_keys=true, safe=false)
       # Initial byte is 0.
-      message = BSON::ByteBuffer.new([0, 0, 0, 0])
+      message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{collection_name}")
-      documents.each { |doc| message.put_array(BSON::BSON_CODER.serialize(doc, check_keys, true).to_a) }
+      documents.each do |doc|
+        message.put_binary(BSON::BSON_CODER.serialize(doc, check_keys, true).to_s)
+      end
+      raise InvalidOperation, "Exceded maximum insert size of 16,000,000 bytes" if message.size > 16_000_000
+
+      @logger.debug("MONGODB #{@db.name}['#{collection_name}'].insert(#{documents.inspect})") if @logger
       if safe
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name,
-          "#{@db.name}['#{collection_name}'].insert(#{documents.inspect})")
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name, nil, safe)
       else
-        @connection.send_message(Mongo::Constants::OP_INSERT, message,
-          "#{@db.name}['#{collection_name}'].insert(#{documents.inspect})")
+        @connection.send_message(Mongo::Constants::OP_INSERT, message, nil)
       end
       documents.collect { |o| o[:_id] || o['_id'] }
     end