Class: Mongo::Database

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/mongo/database.rb,
lib/mongo/database/view.rb

Overview

Represents a database on the db server and operations that can execute on it at this level.

Since:

  • 2.0.0

Defined Under Namespace

Classes: View

Constant Summary collapse

ADMIN =

The admin database name.

Since:

  • 2.0.0

'admin'.freeze
COMMAND =

The “collection” that database commands operate against.

Since:

  • 2.0.0

'$cmd'.freeze
DEFAULT_OPTIONS =

The default database options.

Since:

  • 2.0.0

Options::Redacted.new(:database => ADMIN).freeze
NAME =

Database name field constant.

Since:

  • 2.1.0

'name'.freeze
DATABASES =

Databases constant.

Since:

  • 2.1.0

'databases'.freeze
NAMESPACES =

The name of the collection that holds all the collection names.

Since:

  • 2.0.0

'system.namespaces'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, name, options = {}) ⇒ Database

Instantiate a new database object.

Examples:

Instantiate the database.

Mongo::Database.new(client, :test)

Parameters:

  • client (Mongo::Client) —

    The driver client.

  • name (String, Symbol) —

    The name of the database.

  • options (Hash) (defaults to: {}) —

    The options.

Raises:

  • (Mongo::Database::InvalidName) —

    If the name is nil.

Since:

  • 2.0.0



207
208
209
210
211
212
 
# File 'lib/mongo/database.rb', line 207

def initialize(client, name, options = {})
  raise Error::InvalidDatabaseName.new unless name
  @client = client
  @name = name.to_s.freeze
  @options = options.freeze
end

Instance Attribute Details

#client ⇒ Client (readonly)

Returns client The database client.

Returns:

  • (Client) —

    client The database client.

Since:

  • 2.0.0



57
58
59
 
# File 'lib/mongo/database.rb', line 57

def client
  @client
end

#name ⇒ String (readonly)

Returns name The name of the database.

Returns:

  • (String) —

    name The name of the database.

Since:

  • 2.0.0



60
61
62
 
# File 'lib/mongo/database.rb', line 60

def name
  @name
end

#options ⇒ Hash (readonly)

Returns options The options.

Returns:

  • (Hash) —

    options The options.

Since:

  • 2.0.0



63
64
65
 
# File 'lib/mongo/database.rb', line 63

def options
  @options
end

Class Method Details

.create(client) ⇒ Database

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create a database for the provided client, for use when we don’t want the client’s original database instance to be the same.

Examples:

Create a database for the client.

Database.create(client)

Parameters:

  • client (Client) —

    The client to create on.

Returns:

Since:

  • 2.0.0



304
305
306
307
 
# File 'lib/mongo/database.rb', line 304

def self.create(client)
  database = Database.new(client, client.options[:database], client.options)
  client.instance_variable_set(:@database, database)
end

Instance Method Details

#==(other) ⇒ true, false

Check equality of the database object against another. Will simply check if the names are the same.

Examples:

Check database equality.

database == other

Parameters:

  • other (Object) —

    The object to check against.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.0.0



87
88
89
90
 
# File 'lib/mongo/database.rb', line 87

def ==(other)
  return false unless other.is_a?(Database)
  name == other.name
end

#[](collection_name, options = {}) ⇒ Mongo::Collection Also known as: collection

Get a collection in this database by the provided name.

Examples:

Get a collection.

database[:users]

Parameters:

  • collection_name (String, Symbol) —

    The name of the collection.

  • options (Hash) (defaults to: {}) —

    The options to the collection.

Returns:

Since:

  • 2.0.0



103
104
105
 
# File 'lib/mongo/database.rb', line 103

def [](collection_name, options = {})
  Collection.new(self, collection_name, options)
end

#cluster ⇒ Mongo::Server

Returns Get the primary server from the cluster.

Returns:

Since:

  • 2.0.0



73
74
 
# File 'lib/mongo/database.rb', line 73

def_delegators :cluster,
:next_primary

#collection_names(options = {}) ⇒ Array<String>

Get all the names of the non-system collections in the database.

Examples:

Get the collection names.

database.collection_names

Returns:

  • (Array<String>) —

    The names of all non-system collections.

Since:

  • 2.0.0



116
117
118
 
# File 'lib/mongo/database.rb', line 116

def collection_names(options = {})
  View.new(self).collection_names(options)
end

#collections ⇒ Array<Mongo::Collection>

Get all the collections that belong to this database.

Examples:

Get all the collections.

database.collections

Returns:

Since:

  • 2.0.0



140
141
142
 
# File 'lib/mongo/database.rb', line 140

def collections
  collection_names.map { |name| collection(name) }
end

#command(operation, opts = {}) ⇒ Hash

Execute a command on the database.

Examples:

Execute a command.

database.command(:ismaster => 1)

Parameters:

  • operation (Hash) —

    The command to execute.

  • opts (Hash) (defaults to: {}) —

    The command options.

Options Hash (opts):

  • :read (Hash) —

    The read preference for this command.

Returns:

  • (Hash) —

    The result of the command execution.

Since:

  • 2.0.0



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/mongo/database.rb', line 155

def command(operation, opts = {})
  txn_read_pref = opts[:session] && opts[:session].in_transaction? && opts[:session].txn_read_preference
  Mongo::Lint.validate_underscore_read_preference(txn_read_pref)
  preference = ServerSelector.get(txn_read_pref || opts[:read] || ServerSelector::PRIMARY)
  server = preference.select_server(cluster)

  client.send(:with_session, opts) do |session|
    Operation::Command.new({
      :selector => operation.dup,
      :db_name => name,
      :read => preference,
      :session => session
    }).execute(server)
  end
end

#drop(options = {}) ⇒ Result

Drop the database and all its associated information.

Examples:

Drop the database.

database.drop

Parameters:

  • options (Hash) (defaults to: {}) —

    The options for the operation.

Options Hash (options):

  • :session (Session) —

    The session to use for the operation.

Returns:

  • (Result) —

    The result of the command.

Since:

  • 2.0.0



183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/mongo/database.rb', line 183

def drop(options = {})
  operation = { :dropDatabase => 1 }
  client.send(:with_session, options) do |session|
    Operation::DropDatabase.new({
      selector: operation,
      db_name: name,
      write_concern: write_concern,
      session: session
    }).execute(next_primary)
  end
end

#fs(options = {}) ⇒ Grid::FSBucket

Get the Grid “filesystem” for this database.

Examples:

Get the GridFS.

database.fs

Returns:

Since:

  • 2.0.0



234
235
236
 
# File 'lib/mongo/database.rb', line 234

def fs(options = {})
  Grid::FSBucket.new(self, options)
end

#inspect ⇒ String

Get a pretty printed string inspection for the database.

Examples:

Inspect the database.

database.inspect

Returns:

  • (String) —

    The database inspection.

Since:

  • 2.0.0



222
223
224
 
# File 'lib/mongo/database.rb', line 222

def inspect
  "#<Mongo::Database:0x#{object_id} name=#{name}>"
end

#list_collections ⇒ Array<Hash>

Get info on all the collections in the database.

Examples:

Get info on each collection.

database.list_collections

Returns:

  • (Array<Hash>) —

    Info for each collection in the database.

Since:

  • 2.0.5



128
129
130
 
# File 'lib/mongo/database.rb', line 128

def list_collections
  View.new(self).list_collections
end

#users ⇒ View::User

Get the user view for this database.

Examples:

Get the user view.

database.users

Returns:

  • (View::User) —

    The user view.

Since:

  • 2.0.0



246
247
248
 
# File 'lib/mongo/database.rb', line 246

def users
  Auth::User::View.new(self)
end

#watch(pipeline = [], options = {}) ⇒ ChangeStream

Note:

A change stream only allows ‘majority’ read concern.

Note:

This helper method is preferable to running a raw aggregation with a $changeStream stage, for the purpose of supporting resumability.

As of version 3.6 of the MongoDB server, a “$changeStream“ pipeline stage is supported in the aggregation framework. As of version 4.0, this stage allows users to request that notifications are sent for all changes that occur in the client’s database.

Examples:

Get change notifications for a given database..

database.watch([{ '$match' => { operationType: { '$in' => ['insert', 'replace'] } } }])

Parameters:

  • pipeline (Array<Hash>) (defaults to: []) —

    Optional additional filter operators.

  • options (Hash) (defaults to: {}) —

    The change stream options.

Options Hash (options):

  • :full_document (String) —

    Allowed values: ‘default’, ‘updateLookup’. Defaults to ‘default’. When set to ‘updateLookup’, the change notification for partial updates will include both a delta describing the changes to the document, as well as a copy of the entire document that was changed from some time after the change occurred.

  • :resume_after (BSON::Document, Hash) —

    Specifies the logical starting point for the new change stream.

  • :max_await_time_ms (Integer) —

    The maximum amount of time for the server to wait on new documents to satisfy a change stream query.

  • :batch_size (Integer) —

    The number of documents to return per batch.

  • :collation (BSON::Document, Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :start_at_operation_time (BSON::Timestamp) —

    Only return changes that occurred after the specified timestamp. Any command run against the server will return a cluster time that can be used here. Only recognized by server versions 4.0+.

Returns:

  • (ChangeStream) —

    The change stream object.

Since:

  • 2.6.0



283
284
285
286
287
288
289
 
# File 'lib/mongo/database.rb', line 283

def watch(pipeline = [], options = {})
  Mongo::Collection::View::ChangeStream.new(
    Mongo::Collection::View.new(collection("#{COMMAND}.aggregate")),
    pipeline,
    Mongo::Collection::View::ChangeStream::DATABASE,
    options)
end