Class Mongo::DB
In: lib/mongo/db.rb
Parent: Object

A MongoDB database.

Methods

Included Modules

Mongo::WriteConcern

Constants

SYSTEM_NAMESPACE_COLLECTION = 'system.namespaces'
SYSTEM_INDEX_COLLECTION = 'system.indexes'
SYSTEM_PROFILE_COLLECTION = 'system.profile'
SYSTEM_USER_COLLECTION = 'system.users'
SYSTEM_JS_COLLECTION = 'system.js'
SYSTEM_COMMAND_COLLECTION = '$cmd'

Attributes

acceptable_latency  [RW]  Read Preference
cache_time  [RW]  The length of time that Collection.ensure_index should cache index calls
connection  [R]  The Mongo::MongoClient instance connecting to the MongoDB server.
name  [R]  The name of the database and the local write concern options.
read  [RW]  Read Preference
strict  [W]  Strict mode enforces collection existence checks. When true, asking for a collection that does not exist, or trying to create a collection that already exists, raises an error.

Strict mode is disabled by default, but enabled (true) at any time.

tag_sets  [RW]  Read Preference
write_concern  [R]  The name of the database and the local write concern options.

Public Class methods

Instances of DB are normally obtained by calling Mongo#db.

@param [String] name the database name. @param [Mongo::MongoClient] client a connection object pointing to MongoDB. Note

  that databases are usually instantiated via the MongoClient class. See the examples below.

@option opts [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 opts [Object, create_pk(doc)] :pk (BSON::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 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:
    These write concern options are propagated to Collection objects instantiated off of this DB. If no
    options are provided, the default write concern set on this instance's MongoClient object will be used. This
    default can be overridden upon instantiation of any collection by explicitly setting write concern options
    on initialization or at the time of an operation.

@option opts [Integer] :cache_time (300) Set the time that all ensure_index calls should cache the command.

@core databases constructor_details

Public Instance methods

[](name, opts={})

Alias for collection

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

Adds a user to this database for use with authentication. If the user already exists in the system, the password will be updated.

@param [String] username @param [String] password @param [Boolean] read_only

  Create a read-only user.

@return [Hash] an object representing the user.

Authenticate with the given username and password. Note that mongod must be started with the —auth option for authentication to be enabled.

@param [String] username @param [String] password @param [Boolean] save_auth

  Save this authentication to the client object using MongoClient#add_auth. This
  will ensure that the authentication will be applied on database reconnect. Note
  that this value must be true when using connection pooling.

@return [Boolean]

@raise [AuthenticationError]

@core authenticate authenticate-instance_method

Get a collection by name.

@param [String, Symbol] name the collection name. @param [Hash] opts any valid options that can be passed to Collection#new.

@raise [MongoDBError] if collection does not already exist and we‘re in

  +strict+ mode.

@return [Mongo::Collection]

Get an array of collection names in this database.

@return [Array]

Get an array of Collection instances, one for each collection in this database.

@return [Array<Mongo::Collection>]

Get info on system namespaces (collections). This method returns a cursor which can be iterated over. For each collection, a hash will be yielded containing a ‘name’ string and, optionally, an ‘options’ hash.

@param [String] coll_name return info for the specified collection only.

@return [Mongo::Cursor]

Send a command to the database.

Note: DB commands must start with the "command" key. For this reason, any selector containing more than one key must be an OrderedHash.

Note also that a command in MongoDB is just a kind of query that occurs on the system command collection ($cmd). Examine this method‘s implementation 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. In Ruby 1.9, OrderedHash isn‘t necessary since hashes are ordered by default.

@option opts [Boolean] :check_response (true) If true, raises an exception if the

  command fails.

@option opts [Socket] :socket a socket to use for sending the command. This is mainly for internal use. @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 [Hash]

@core commands command_instance-method

Create a collection.

new collection. If strict is true, will raise an error if collection name already exists.

@param [String, Symbol] name the name of the new collection.

@option opts [Boolean] :capped (False) created a capped collection.

@option opts [Integer] :size (Nil) If capped is true,

  specifies the maximum number of bytes for the capped collection.
  If +false+, specifies the number of bytes allocated
  for the initial extent of the collection.

@option opts [Integer] :max (Nil) If capped is true, indicates

  the maximum number of records in a capped collection.

@raise [MongoDBError] raised under two conditions:

  either we're in +strict+ mode and the collection
  already exists or collection creation fails on the server.

@return [Mongo::Collection]

Dereference a DBRef, returning the document it points to.

@param [Mongo::DBRef] dbref

@return [Hash] the document indicated by the db reference.

@see www.mongodb.org/display/DOCS/DB+Ref MongoDB DBRef spec.

Drop a collection by name.

@param [String, Symbol] name

@return [Boolean] true on success or false if the collection name doesn‘t exist.

Drop an index from a given collection. Normally called from Collection#drop_index or Collection#drop_indexes.

@param [String] collection_name @param [String] index_name

@return [True] returns true on success.

@raise MongoDBError if there‘s an error dropping the index.

Return true if an error was caused by the most recently executed database operation.

@return [Boolean]

Evaluate a JavaScript expression in MongoDB.

@param [String, Code] code a JavaScript expression to evaluate server-side. @param [Integer, Hash] args any additional argument to be passed to the code expression when

  it's run on the server.

@return [String] the return value of the function.

A shortcut returning db plus dot plus collection name.

@param [String] collection_name

@return [String]

Run the getlasterror command with the specified replication options.

@option opts [Boolean] :fsync (false) @option opts [Integer] :w (nil) @option opts [Integer] :wtimeout (nil) @option opts [Boolean] :j (false)

@return [Hash] the entire response to getlasterror.

@raise [MongoDBError] if the operation fails.

Get information on the indexes for the given collection. Normally called by Collection#index_information.

@param [String] collection_name

@return [Hash] keys are index names and the values are lists of [key, direction] pairs

  defining the index.

Deauthorizes use for this database for this client connection. Also removes any saved authentication in the MongoClient class associated with this database.

@raise [MongoDBError] if logging out fails.

@return [Boolean]

Return true if the supplied doc contains an ‘ok’ field with the value 1.

@param [Hash] doc

@return [Boolean]

The primary key factory object (or nil).

@return [Object, Nil]

Specify a primary key factory if not already set.

@raise [MongoArgumentError] if the primary key factory has already been set.

Get the most recent error to have occurred on this database.

This command only returns errors that have occurred since the last call to DB#reset_error_history - returns nil if there is no such error.

@return [String, Nil] the text of the error or nil if no error has occurred.

Get the current profiling information.

@return [Array] a list of documents containing profiling information.

Return the current database profiling level. If profiling is enabled, you can get the results using DB#profiling_info.

@return [Symbol] :off, :slow_only, or :all

@core profiling profiling_level-instance_method

Set this database‘s profiling level. If profiling is enabled, you can get the results using DB#profiling_info.

@param [Symbol] level acceptable options are +:off+, +:slow_only+, or +:all+.

Removes stored Javascript function from the database. Returns false if the function does not exist

@param [String] function_name

@return [Boolean]

Remove the given user from this database. Returns false if the user doesn‘t exist in the system.

@param [String] username

@return [Boolean]

Rename a collection.

@param [String] from original collection name. @param [String] to new collection name.

@return [True] returns true on success.

@raise MongoDBError if there‘s an error renaming the collection.

Reset the error history of this database

Calls to DB#previous_error will only return errors that have occurred since the most recent call to this method.

@return [Hash]

Return stats on this database. Uses MongoDB‘s dbstats command.

@return [Hash]

Returns the value of the strict flag.

Validate a named collection.

@param [String] name the collection name.

@return [Hash] validation information.

@raise [MongoDBError] if the command fails or there‘s a problem with the validation

  data, or if the collection is invalid.

[Validate]