mongo 1.0 → 1.1.5

data/lib/mongo/db.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -27,6 +29,7 @@ module Mongo
     SYSTEM_INDEX_COLLECTION = "system.indexes"
     SYSTEM_PROFILE_COLLECTION = "system.profile"
     SYSTEM_USER_COLLECTION = "system.users"
+    SYSTEM_JS_COLLECTION = "system.js"
     SYSTEM_COMMAND_COLLECTION = "$cmd"
 
     # Counter for generating unique request ids.
@@ -42,12 +45,15 @@ module Mongo
     # Returns the value of the +strict+ flag.
     def strict?; @strict; end
 
-    # The name of the database.
-    attr_reader :name
+    # The name of the database and the local safe option.
+    attr_reader :name, :safe
 
     # The Mongo::Connection instance connecting to the MongoDB server.
     attr_reader :connection
 
+    # The length of time that Collection.ensure_index should cache index calls
+    attr_accessor :cache_time
+
     # Instances of DB are normally obtained by calling Mongo#db.
     #
     # @param [String] db_name the database name.
@@ -57,17 +63,26 @@ module Mongo
     # @option options [Boolean] :strict (False) If true, collections must exist to be accessed and must
     #   not exist to be created. See DB#collection and DB#create_collection.
     #
-    # @option options [Object, #create_pk(doc)] :pk (Mongo::ObjectID) A primary key factory object,
+    # @option options [Object, #create_pk(doc)] :pk (Mongo::ObjectId) A primary key factory object,
     #   which should take a hash and return a hash which merges the original hash with any primary key
     #   fields the factory wishes to inject. (NOTE: if the object already has a primary key,
     #   the factory should not inject a new key).
     #
+    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    #   propogated to Collection objects instantiated off of this DB. If no
+    #   value is provided, the default value set on this instance's Connection object will be used. This
+    #   default can be overridden upon instantiation of any collection by explicity setting a :safe value
+    #   on initialization
+    # @option options [Integer] :cache_time (300) Set the time that all ensure_index calls should cache the command.
+    #
     # @core databases constructor_details
     def initialize(db_name, connection, options={})
       @name       = Mongo::Support.validate_db_name(db_name)
       @connection = connection
       @strict     = options[:strict]
       @pk_factory = options[:pk]
+      @safe       = options.has_key?(:safe) ? options[:safe] : @connection.safe
+      @cache_time = options[:cache_time] || 300 #5 minutes.
     end
 
     # Authenticate with the given username and password. Note that mongod
@@ -85,16 +100,16 @@ module Mongo
     #
     # @core authenticate authenticate-instance_method
     def authenticate(username, password, save_auth=true)
-      doc = command(:getnonce => 1)
+      doc = command({:getnonce => 1}, :check_response => false)
       raise "error retrieving nonce: #{doc}" unless ok?(doc)
       nonce = doc['nonce']
 
-      auth = OrderedHash.new
+      auth = BSON::OrderedHash.new
       auth['authenticate'] = 1
       auth['user'] = username
       auth['nonce'] = nonce
       auth['key'] = Mongo::Support.auth_key(username, password, nonce)
-      if ok?(command(auth))
+      if ok?(self.command(auth, :check_response => false))
         if save_auth
           @connection.add_auth(@name, username, password)
         end
@@ -104,6 +119,36 @@ module Mongo
       end
     end
 
+    # Adds a stored Javascript function to the database which can executed  
+    # server-side in map_reduce, db.eval and $where clauses.
+    # 
+    # @param [String] function_name
+    # @param [String] code
+    #
+    # @return [String] the function name saved to the database
+    def add_stored_function(function_name, code)
+      self[SYSTEM_JS_COLLECTION].save(
+        {
+          "_id" => function_name, 
+          :value => BSON::Code.new(code)
+        }
+      )
+    end
+
+    # Removes stored Javascript function from the database.  Returns
+    # false if the function does not exist
+    #
+    # @param [String] function_name
+    #
+    # @return [Boolean]
+    def remove_stored_function(function_name)
+      if self[SYSTEM_JS_COLLECTION].find_one({"_id" => function_name})
+        self[SYSTEM_JS_COLLECTION].remove({"_id" => function_name}, :safe => true)
+      else
+        return false
+      end
+    end
+
     # Adds a user to this database for use with authentication. If the user already
     # exists in the system, the password will be updated.
     #
@@ -212,24 +257,29 @@ module Mongo
       end
 
       # Create a new collection.
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:create] = name
       doc = command(oh.merge(options || {}))
-      ok = doc['ok']
-      return Collection.new(self, name, @pk_factory) if ok.kind_of?(Numeric) && (ok.to_i == 1 || ok.to_i == 0)
+      return Collection.new(self, name, :pk => @pk_factory) if ok?(doc)
       raise MongoDBError, "Error creating collection: #{doc.inspect}"
     end
 
     # Get a collection by name.
     #
     # @param [String] name the collection name.
+    # @param [Hash] options any valid options that can me passed to Collection#new.
     #
     # @raise [MongoDBError] if collection does not already exist and we're in +strict+ mode.
     #
     # @return [Mongo::Collection]
-    def collection(name)
-      return Collection.new(self, name, @pk_factory) if !strict? || collection_names.include?(name)
-      raise Mongo::MongoDBError, "Collection #{name} doesn't exist. Currently in strict mode."
+    def collection(name, options={})
+      if strict? && !collection_names.include?(name)
+        raise Mongo::MongoDBError, "Collection #{name} doesn't exist. Currently in strict mode."
+      else
+        options[:safe] = options.has_key?(:safe) ? options[:safe] : @safe
+        options.merge!(:pk => @pk_factory) unless options[:pk]
+        Collection.new(self, name, options)
+      end
     end
     alias_method :[], :collection
 
@@ -237,29 +287,29 @@ module Mongo
     #
     # @param [String] name
     #
-    # @return [Boolean] True on success or if the collection names doesn't exist.
+    # @return [Boolean] +true+ on success or +false+ if the collection name doesn't exist.
     def drop_collection(name)
       return true unless collection_names.include?(name)
 
       ok?(command(:drop => name))
     end
 
-    # Get the error message from the most recently executed database
-    # operation for this connection.
+    # Run the getlasterror command with the specified replication options.
     #
-    # @return [String, Nil] either the text describing the error or nil if no 
-    #   error has occurred.
-    def error
-      doc = command(:getlasterror => 1)
-      raise MongoDBError, "error retrieving last error: #{doc}" unless ok?(doc)
-      doc['err']
-    end
-
-    # Get status information from the last operation on this connection.
+    # @option opts [Boolean] :fsync (false)
+    # @option opts [Integer] :w (nil)
+    # @option opts [Integer] :wtimeout (nil)
+    #
+    # @return [Hash] the entire response to getlasterror.
     #
-    # @return [Hash] a hash representing the status of the last db op.
-    def last_status
-      command(:getlasterror => 1)
+    # @raise [MongoDBError] if the operation fails.
+    def get_last_error(opts={})
+      cmd = BSON::OrderedHash.new
+      cmd[:getlasterror] = 1
+      cmd.merge!(opts)
+      doc = command(cmd, :check_response => false)
+      raise MongoDBError, "error retrieving last error: #{doc.inspect}" unless ok?(doc)
+      doc
     end
 
     # Return +true+ if an error was caused by the most recently executed
@@ -267,7 +317,7 @@ module Mongo
     #
     # @return [Boolean]
     def error?
-      error != nil
+      get_last_error['err'] != nil
     end
 
     # Get the most recent error to have occured on this database.
@@ -295,17 +345,6 @@ module Mongo
       command(:reseterror => 1)
     end
 
-    # @deprecated please use Collection#find to create queries.
-    #
-    # Returns a Cursor over the query results.
-    #
-    # Note that the query gets sent lazily; the cursor calls
-    # Connection#send_message when needed. If the caller never requests an
-    # object from the cursor, the query never gets sent.
-    def query(collection, query, admin=false)
-      Cursor.new(self, collection, query, admin)
-    end
-
     # Dereference a DBRef, returning the document it points to.
     #
     # @param [Mongo::DBRef] dbref
@@ -329,12 +368,11 @@ module Mongo
         code = BSON::Code.new(code)
       end
 
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:$eval] = code
-      oh[:args] = args
+      oh[:args]  = args
       doc = command(oh)
-      return doc['retval'] if ok?(doc)
-      raise OperationFailure, "eval failed: #{doc['errmsg']}"
+      doc['retval']
     end
 
     # Rename a collection.
@@ -343,13 +381,13 @@ module Mongo
     # @param [String] to new collection name.
     #
     # @return [True] returns +true+ on success.
-    # 
+    #
     # @raise MongoDBError if there's an error renaming the collection.
     def rename_collection(from, to)
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:renameCollection] = "#{@name}.#{from}"
       oh[:to] = "#{@name}.#{to}"
-      doc = command(oh, true)
+      doc = DB.new('admin', @connection).command(oh, :check_response => false)
       ok?(doc) || raise(MongoDBError, "Error renaming collection: #{doc.inspect}")
     end
 
@@ -363,10 +401,10 @@ module Mongo
     #
     # @raise MongoDBError if there's an error renaming the collection.
     def drop_index(collection_name, index_name)
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:deleteIndexes] = collection_name
       oh[:index] = index_name
-      doc = command(oh)
+      doc = command(oh, :check_response => false)
       ok?(doc) || raise(MongoDBError, "Error with drop_index command: #{doc.inspect}")
     end
 
@@ -386,7 +424,6 @@ module Mongo
       info
     end
 
-
     # Return stats on this database. Uses MongoDB's dbstats command.
     #
     # @return [Hash]
@@ -394,31 +431,13 @@ module Mongo
       self.command({:dbstats => 1})
     end
 
-    # Create a new index on the given collection.
-    # Normally called by Collection#create_index.
-    #
-    # @param [String] collection_name
-    # @param [String, Array] field_or_spec either either a single field name
-    #   or an array of [field name, direction] pairs. Directions should be specified as
-    #   Mongo::ASCENDING or Mongo::DESCENDING.
-    # @param [Boolean] unique if +true+, the created index will enforce a uniqueness constraint.
-    #
-    # @return [String] the name of the index created.
-    #
-    # @deprecated
-    def create_index(collection_name, field_or_spec, unique=false)
-      warn "DB#create_index is now deprecated. Please use Collection#create_index instead."
-      self.collection(collection_name).create_index(field_or_spec, :unique => unique)
-    end
-
     # Return +true+ if the supplied +doc+ contains an 'ok' field with the value 1.
     #
     # @param [Hash] doc
     #
     # @return [Boolean]
     def ok?(doc)
-      ok = doc['ok']
-      ok.kind_of?(Numeric) && ok.to_i == 1
+      Mongo::Support.ok?(doc)
     end
 
     # Send a command to the database.
@@ -431,29 +450,34 @@ module Mongo
     # to see how it works.
     #
     # @param [OrderedHash, Hash] selector an OrderedHash, or a standard Hash with just one
-    # key, specifying the command to be performed.
+    # key, specifying the command to be performed. In Ruby 1.9, OrderedHash isn't necessary since
+    # hashes are ordered by default.
     #
-    # @param [Boolean] admin If +true+, the command will be executed on the admin
-    # collection.
-    #
-    # @param [Boolean] check_response If +true+, will raise an exception if the
+    # @option opts [Boolean] :check_response (true) If +true+, raises an exception if the
     # command fails.
-    #
-    # @param [Socket] sock a socket to use. This is mainly for internal use.
+    # @option opts [Socket] :sock a socket to use for sending the command. This is mainly for internal use.
     #
     # @return [Hash]
     #
     # @core commands command_instance-method
-    def command(selector, admin=false, check_response=false, sock=nil)
+    def command(selector, opts={})
+      check_response = opts.fetch(:check_response, true)
+      sock           = opts[:sock]
       raise MongoArgumentError, "command must be given a selector" unless selector.is_a?(Hash) && !selector.empty?
-      if selector.class.eql?(Hash) && selector.keys.length > 1
+      if selector.keys.length > 1 && RUBY_VERSION < '1.9' && selector.class != BSON::OrderedHash
         raise MongoArgumentError, "DB#command requires an OrderedHash when hash contains multiple keys"
       end
 
-      result = Cursor.new(system_command_collection, :admin => admin,
-        :limit => -1, :selector => selector, :socket => sock).next_document
+      begin
+        result = Cursor.new(system_command_collection,
+          :limit => -1, :selector => selector, :socket => sock).next_document
+      rescue OperationFailure => ex
+        raise OperationFailure, "Database command '#{selector.keys.first}' failed: #{ex.message}"
+      end
 
-      if check_response && !ok?(result)
+      if result.nil?
+        raise OperationFailure, "Database command '#{selector.keys.first}' failed: returned null."
+      elsif (check_response && !ok?(result))
         raise OperationFailure, "Database command '#{selector.keys.first}' failed: #{result.inspect}"
       else
         result
@@ -494,9 +518,9 @@ module Mongo
     #
     # @core profiling profiling_level-instance_method
     def profiling_level
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:profile] = -1
-      doc = command(oh)
+      doc = command(oh, :check_response => false)
       raise "Error with profile command: #{doc.inspect}" unless ok?(doc) && doc['was'].kind_of?(Numeric)
       case doc['was'].to_i
       when 0
@@ -515,7 +539,7 @@ module Mongo
     #
     # @param [Symbol] level acceptable options are +:off+, +:slow_only+, or +:all+.
     def profiling_level=(level)
-      oh = OrderedHash.new
+      oh = BSON::OrderedHash.new
       oh[:profile] = case level
                      when :off
                        0
@@ -526,7 +550,7 @@ module Mongo
                      else
                        raise "Error: illegal profiling level value #{level}"
                      end
-      doc = command(oh)
+      doc = command(oh, :check_response => false)
       ok?(doc) || raise(MongoDBError, "Error with profile command: #{doc.inspect}")
     end
 
@@ -546,7 +570,7 @@ module Mongo
     # @raise [MongoDBError] if the command fails or there's a problem with the validation
     #   data, or if the collection is invalid.
     def validate_collection(name)
-      doc = command(:validate => name)
+      doc = command({:validate => name}, :check_response => false)
       raise MongoDBError, "Error with validate command: #{doc.inspect}" unless ok?(doc)
       result = doc['result']
       raise MongoDBError, "Error with validation data: #{doc.inspect}" unless result.kind_of?(String)

data/lib/mongo/exceptions.rb

@@ -1,3 +1,6 @@
+# encoding: UTF-8
+
+#
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -39,6 +42,9 @@ module Mongo
   # Raised on failures in connection to the database server.
   class ConnectionError < MongoRubyError; end
 
+  # Raised on failures in connection to the database server.
+  class ReplicaSetConnectionError < ConnectionError; end
+
   # Raised on failures in connection to the database server.
   class ConnectionTimeoutError < MongoRubyError; end
 

data/lib/mongo/gridfs/grid.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -18,6 +20,8 @@ module Mongo
 
   # Implementation of the MongoDB GridFS specification. A file store.
   class Grid
+    include GridExt::InstanceMethods
+
     DEFAULT_FS_NAME = 'fs'
 
     # Initialize a new Grid instance, consisting of a MongoDB database
@@ -34,30 +38,34 @@ module Mongo
       @chunks  = @db["#{fs_name}.chunks"]
       @fs_name = fs_name
 
-      @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]], :unique => true)
+      # Ensure indexes only if not connected to slave.
+      unless db.connection.slave_ok?
+        @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]], :unique => true)
+      end
     end
 
-    # Store a file in the file store.
+    # Store a file in the file store. This method is designed only for writing new files;
+    # if you need to update a given file, first delete it using Grid#delete.
     #
     # Note that arbitary metadata attributes can be saved to the file by passing
-    # them is as options.
+    # them in as options.
     #
     # @param [String, #read] data a string or io-like object to store.
     #
-    # @options opts [String] :filename (nil) a name for the file.
-    # @options opts [Hash] :metadata ({}) any additional data to store with the file.
-    # @options opts [ObjectID] :_id (ObjectID) a unique id for
+    # @option opts [String] :filename (nil) a name for the file.
+    # @option opts [Hash] :metadata ({}) any additional data to store with the file.
+    # @option opts [ObjectId] :_id (ObjectId) a unique id for
     #   the file to be use in lieu of an automatically generated one.
-    # @options opts [String] :content_type ('binary/octet-stream') If no content type is specified,
+    # @option opts [String] :content_type ('binary/octet-stream') If no content type is specified,
     #   the content type will may be inferred from the filename extension if the mime-types gem can be
     #   loaded. Otherwise, the content type 'binary/octet-stream' will be used.
-    # @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
-    # @options opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
+    # @option opts [Integer] (262144) :chunk_size size of file chunks in bytes.
+    # @option opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
     #   will be validated using an md5 hash. If validation fails, an exception will be raised.
     #
-    # @return [Mongo::ObjectID] the file's id.
+    # @return [Mongo::ObjectId] the file's id.
     def put(data, opts={})
-      filename = opts[:filename]
+      filename = opts.delete :filename
       opts.merge!(default_grid_io_opts)
       file = GridIO.new(@files, @chunks, filename, 'w', opts=opts)
       file.write(data)

data/lib/mongo/gridfs/grid_ext.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -15,16 +17,41 @@
 # ++
 
 module Mongo
-  module ClassMethods
-
-    def exists?(criteria)
-      BSON::ObjectID:
-      @files.find_one(query)
-    end
+  module GridExt
+    module InstanceMethods
 
-    def list(query={})
-      @files.find(query)
+      # Check the existence of a file matching the given query selector.
+      #
+      # Note that this method can be used with both the Grid and GridFileSystem classes. Also
+      # keep in mind that if you're going to be performing lots of existence checks, you should
+      # keep an instance of Grid or GridFileSystem handy rather than instantiating for each existence
+      # check. Alternatively, simply keep a reference to the proper files collection and query that
+      # as needed. That's exactly how this methods works.
+      #
+      # @param [Hash] selector a query selector.
+      #
+      # @example
+      #
+      #   # Check for the existence of a given filename
+      #   @grid = GridFileSystem.new(@db)
+      #   @grid.exist?(:filename => 'foo.txt')
+      #
+      #   # Check for existence filename and content type
+      #   @grid = GridFileSystem.new(@db)
+      #   @grid.exist?(:filename => 'foo.txt', :content_type => 'image/jpg')
+      #
+      #   # Check for existence by _id
+      #   @grid = Grid.new(@db)
+      #   @grid.exist?(:_id => BSON::ObjectId.from_string('4bddcd24beffd95a7db9b8c8'))
+      #
+      #   # Check for existence by an arbitrary attribute.
+      #   @grid = Grid.new(@db)
+      #   @grid.exist?(:tags => {'$in' => ['nature', 'zen', 'photography']})
+      #
+      # @return [nil, Hash] either nil for the file's metadata as a hash.
+      def exist?(selector)
+        @files.find_one(selector)
+      end
     end
-
   end
 end

data/lib/mongo/gridfs/grid_file_system.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 # --
 # Copyright (C) 2008-2010 10gen Inc.
 #
@@ -19,8 +21,9 @@ module Mongo
   # A file store built on the GridFS specification featuring
   # an API and behavior similar to that of a traditional file system.
   class GridFileSystem
+    include GridExt::InstanceMethods
 
-    # Initialize a new Grid instance, consisting of a MongoDB database
+    # Initialize a new GridFileSystem instance, consisting of a MongoDB database
     # and a filesystem prefix if not using the default.
     #
     # @param [Mongo::DB] db a MongoDB database.
@@ -36,8 +39,11 @@ module Mongo
 
       @default_query_opts = {:sort => [['filename', 1], ['uploadDate', -1]], :limit => 1}
 
-      @files.create_index([['filename', 1], ['uploadDate', -1]])
-      @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]], :unique => true)
+      # Ensure indexes only if not connected to slave.
+      unless db.connection.slave_ok?
+        @files.create_index([['filename', 1], ['uploadDate', -1]])
+        @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]], :unique => true)
+      end
     end
 
     # Open a file for reading or writing. Note that the options for this method only apply
@@ -51,17 +57,17 @@ module Mongo
     #   or writing to the file.
     # @param [Hash] opts see GridIO#new
     #
-    # @options opts [Hash] :metadata ({}) any additional data to store with the file.
-    # @options opts [ObjectID] :_id (ObjectID) a unique id for
+    # @option opts [Hash] :metadata ({}) any additional data to store with the file.
+    # @option opts [ObjectId] :_id (ObjectId) a unique id for
     #   the file to be use in lieu of an automatically generated one.
-    # @options opts [String] :content_type ('binary/octet-stream') If no content type is specified,
+    # @option opts [String] :content_type ('binary/octet-stream') If no content type is specified,
     #   the content type will may be inferred from the filename extension if the mime-types gem can be
     #   loaded. Otherwise, the content type 'binary/octet-stream' will be used.
-    # @options opts [Integer] (262144) :chunk_size size of file chunks in bytes.
-    # @options opts [Boolean] :delete_old (false) ensure that old versions of the file are deleted. This option
+    # @option opts [Integer] (262144) :chunk_size size of file chunks in bytes.
+    # @option opts [Boolean] :delete_old (false) ensure that old versions of the file are deleted. This option
     #  only work in 'w' mode. Certain precautions must be taken when deleting GridFS files. See the notes under
     #  GridFileSystem#delete.
-    # @options opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
+    # @option opts [Boolean] :safe (false) When safe mode is enabled, the chunks sent to the server
     #   will be validated using an md5 hash. If validation fails, an exception will be raised.
     #
     # @example