Class: Mongo::Database

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Retryable
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'
COMMAND =

The “collection” that database commands operate against.

Since:

  • 2.0.0

'$cmd'
DEFAULT_OPTIONS =

The default database options.

Since:

  • 2.0.0

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

Database name field constant.

Since:

  • 2.1.0

'name'
DATABASES =

Databases constant.

Since:

  • 2.1.0

'databases'
NAMESPACES =

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

Since:

  • 2.0.0

'system.namespaces'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Retryable

#read_worker, #select_server, #with_overload_retry, #write_worker

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.

Options Hash (options):

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the client.

Raises:

  • (Mongo::Database::InvalidName) —

    If the name is nil.

Since:

  • 2.0.0



365
366
367
368
369
370
371
372
373
374
 
# File 'lib/mongo/database.rb', line 365

def initialize(client, name, options = {})
  raise Error::InvalidDatabaseName.new unless name
  if Lint.enabled? && !(name.is_a?(String) || name.is_a?(Symbol))
    raise "Database name must be a string or a symbol: #{name}"
  end

  @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



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

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



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

def name
  @name
end

#options ⇒ Hash (readonly)

Returns options The options.

Returns:

  • (Hash) —

    options The options.

Since:

  • 2.0.0



66
67
68
 
# File 'lib/mongo/database.rb', line 66

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



546
547
548
549
 
# File 'lib/mongo/database.rb', line 546

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



93
94
95
96
97
 
# File 'lib/mongo/database.rb', line 93

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



110
111
112
113
114
115
116
117
 
# File 'lib/mongo/database.rb', line 110

def [](collection_name, options = {})
  if options[:server_api]
    raise ArgumentError,
          'The :server_api option cannot be specified for collection objects. It can only be specified on Client level'
  end

  Collection.new(self, collection_name, options)
end

#aggregate(pipeline, options = {}) ⇒ Collection::View::Aggregation

Perform an aggregation on the database.

Examples:

Perform an aggregation.

collection.aggregate([ { "$listLocalSessions" => {} } ])

Parameters:

  • pipeline (Array<Hash>) —

    The aggregation pipeline.

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

    The aggregation options.

Options Hash (options):

  • :allow_disk_use (true, false) —

    Set to true if disk usage is allowed during the aggregation.

  • :batch_size (Integer) —

    The number of documents to return per batch.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the query to run, in milliseconds. This option is deprecated, use :timeout_ms instead.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

  • :hint (String) —

    The index to use for the aggregation.

  • :session (Session) —

    The session to use.

Returns:

Since:

  • 2.10.0



454
455
456
 
# File 'lib/mongo/database.rb', line 454

def aggregate(pipeline, options = {})
  View.new(self, options).aggregate(pipeline, options)
end

#cluster ⇒ Mongo::Server

Returns Get the primary server from the cluster.

Returns:

Since:

  • 2.0.0



79
80
 
# File 'lib/mongo/database.rb', line 79

def_delegators :cluster,
:next_primary

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

Note:

The set of returned collection names depends on the version of MongoDB server that fulfills the request.

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

See https://mongodb.com/docs/manual/reference/command/listCollections/
for more information and usage.

Parameters:

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

Options Hash (options):

  • :filter (Hash) —

    A filter on the collections returned.

  • :authorized_collections (true, false) —

    A flag, when set to true and used with nameOnly: true, that allows a user without the required privilege to run the command when access control is enforced

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

Returns:

  • (Array<String>) —

    Names of the collections.

Since:

  • 2.0.0



144
145
146
 
# File 'lib/mongo/database.rb', line 144

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

#collections(options = {}) ⇒ Array<Mongo::Collection>

Note:

The set of returned collections depends on the version of MongoDB server that fulfills the request.

Get all the non-system collections that belong to this database.

See https://mongodb.com/docs/manual/reference/command/listCollections/
for more information and usage.

Parameters:

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

Options Hash (options):

  • :filter (Hash) —

    A filter on the collections returned.

  • :authorized_collections (true, false) —

    A flag, when set to true and used with name_only: true, that allows a user without the required privilege to run the command when access control is enforced.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

Returns:

Since:

  • 2.0.0



205
206
207
 
# File 'lib/mongo/database.rb', line 205

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

#command(operation, opts = {}) ⇒ Mongo::Operation::Result

Execute a command on the database.

Examples:

Execute a command.

database.command(:hello => 1)

Parameters:

  • operation (Hash) —

    The command to execute.

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

    The command options.

  • options (Hash) —

    a customizable set of options

Options Hash (opts):

  • :read (Hash) —

    The read preference for this command.

  • :session (Session) —

    The session to use for this command.

  • :execution_options (Hash) —

    Options to pass to the code that executes this command. This is an internal option and is subject to change.

    • :deserialize_as_bson [ Boolean ] Whether to deserialize the response to this command using BSON types instead of native Ruby types wherever possible.

Returns:

Since:

  • 2.0.0



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/mongo/database.rb', line 231

def command(operation, opts = {})
  opts = opts.dup
  execution_opts = opts.delete(:execution_options) || {}

  txn_read_pref = (opts[:session].txn_read_preference if opts[:session] && opts[:session].in_transaction?)
  txn_read_pref ||= opts[:read] || ServerSelector::PRIMARY
  Lint.validate_underscore_read_preference(txn_read_pref)
  selector = ServerSelector.get(txn_read_pref)

  client.with_session(opts) do |session|
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(opts)
    )
    op = Operation::Command.new(
      selector: operation,
      db_name: name,
      read: selector,
      session: session
    )

    retry_enabled = client.options[:retry_reads] != false &&
                    client.options[:retry_writes] != false
    with_overload_retry(context: context, retry_enabled: retry_enabled) do
      server = selector.select_server(cluster, nil, session)
      op.execute(server, context: context, options: execution_opts)
    end
  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.

  • :write_concern (Hash) —

    The write concern options.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

Returns:

  • (Result) —

    The result of the command.

Since:

  • 2.0.0



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/mongo/database.rb', line 325

def drop(options = {})
  operation = { dropDatabase: 1 }
  client.with_session(options) do |session|
    write_concern = if options[:write_concern]
                      WriteConcern.get(options[:write_concern])
                    else
                      self.write_concern
                    end
    Operation::DropDatabase.new({
                                  selector: operation,
                                  db_name: name,
                                  write_concern: write_concern,
                                  session: session
                                }).execute(
                                  next_primary(nil, session),
                                  context: Operation::Context.new(
                                    client: client,
                                    session: session,
                                    operation_timeouts: operation_timeouts(options)
                                  )
                                )
  end
end

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

Get the Grid “filesystem” for this database.

Parameters:

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

    The GridFS options.

Options Hash (options):

  • :bucket_name (String) —

    The prefix for the files and chunks collections.

  • :chunk_size (Integer) —

    Override the default chunk size.

  • :fs_name (String) —

    The prefix for the files and chunks collections.

  • :read (String) —

    The read preference.

  • :session (Session) —

    The session to use.

  • :write (Hash) —

    Deprecated. Equivalent to :write_concern option.

  • :write_concern (Hash) —

    The write concern options. Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

Returns:

Since:

  • 2.0.0



408
409
410
 
# File 'lib/mongo/database.rb', line 408

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



384
385
386
 
# File 'lib/mongo/database.rb', line 384

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

#list_collections(options = {}) ⇒ Array<Hash>

Note:

The set of collections returned, and the schema of the information hash per collection, depends on the MongoDB server version that fulfills the request.

Get info on all the non-system collections in the database.

See https://mongodb.com/docs/manual/reference/command/listCollections/
for more information and usage.

Parameters:

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

Options Hash (options):

  • :filter (Hash) —

    A filter on the collections returned.

  • :name_only (true, false) —

    Indicates whether command should return just collection/view names and type or return both the name and other information

  • :authorized_collections (true, false) —

    A flag, when set to true and used with nameOnly: true, that allows a user without the required privilege to run the command when access control is enforced.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

Returns:

  • (Array<Hash>) —

    Array of information hashes, one for each collection in the database.

Since:

  • 2.0.5



177
178
179
 
# File 'lib/mongo/database.rb', line 177

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

#operation_timeouts(opts) ⇒ Hash

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.

Returns timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Returns:

  • (Hash) —

    timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Since:

  • 2.0.0



563
564
565
566
567
568
569
570
571
572
 
# File 'lib/mongo/database.rb', line 563

def operation_timeouts(opts)
  # TODO: We should re-evaluate if we need two timeouts separately.
  {}.tap do |result|
    if opts[:timeout_ms].nil?
      result[:inherited_timeout_ms] = timeout_ms
    else
      result[:operation_timeout_ms] = opts.delete(:timeout_ms)
    end
  end
end

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

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.

Execute a read command on the database, retrying the read if necessary.

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.

  • :session (Session) —

    The session to use for this command.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the database or the client.

  • :op_name (String | nil) —

    The name of the operation for tracing purposes.

Returns:

  • (Hash) —

    The result of the command execution.

Since:

  • 2.0.0



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/mongo/database.rb', line 280

def read_command(operation, opts = {})
  txn_read_pref = (opts[:session].txn_read_preference if opts[:session] && opts[:session].in_transaction?)
  txn_read_pref ||= opts[:read] || ServerSelector::PRIMARY
  Lint.validate_underscore_read_preference(txn_read_pref)
  preference = ServerSelector.get(txn_read_pref)

  client.with_session(opts) do |session|
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(opts)
    )
    operation = Operation::Command.new(
      selector: operation.dup,
      db_name: name,
      read: preference,
      session: session,
      comment: opts[:comment]
    )
    op_name = opts[:op_name] || 'command'
    tracer.trace_operation(operation, context, op_name: op_name) do
      read_with_retry(session, preference, context) do |server|
        operation.execute(server, context: context)
      end
    end
  end
end

#timeout_ms ⇒ Integer | nil

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.

Returns Operation timeout that is for this database or for the corresponding client.

Returns:

  • (Integer | nil) —

    Operation timeout that is for this database or for the corresponding client.

Since:

  • 2.0.0



555
556
557
 
# File 'lib/mongo/database.rb', line 555

def timeout_ms
  options[:timeout_ms] || client.timeout_ms
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



420
421
422
 
# File 'lib/mongo/database.rb', line 420

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.

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: nil, ‘default’, ‘updateLookup’, ‘whenAvailable’, ‘required’.

    The default is to not send a value (i.e. nil), which is equivalent to ‘default’. By default, the change notification for partial updates will include a delta describing the changes to the document.

    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.

    When set to ‘whenAvailable’, configures the change stream to return the post-image of the modified document for replace and update change events if the post-image for this event is available.

    When set to ‘required’, the same behavior as ‘whenAvailable’ except that an error is raised if the post-image is not available.

  • :full_document_before_change (String) —

    Allowed values: nil, ‘whenAvailable’, ‘required’, ‘off’.

    The default is to not send a value (i.e. nil), which is equivalent to ‘off’.

    When set to ‘whenAvailable’, configures the change stream to return the pre-image of the modified document for replace, update, and delete change events if it is available.

    When set to ‘required’, the same behavior as ‘whenAvailable’ except that an error is raised if the pre-image is not available.

  • :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.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :show_expanded_events (Boolean) —

    Enables the server to send the ‘expanded’ list of change stream events. The list of additional events included with this flag set are: createIndexes, dropIndexes, modify, create, shardCollection, reshardCollection, refineCollectionShardKey.

Returns:

  • (ChangeStream) —

    The change stream object.

Since:

  • 2.6.0



521
522
523
524
525
526
527
528
529
530
531
 
# File 'lib/mongo/database.rb', line 521

def watch(pipeline = [], options = {})
  view_options = options.dup
  view_options[:cursor_type] = :tailable_await if options[:max_await_time_ms]

  Mongo::Collection::View::ChangeStream.new(
    Mongo::Collection::View.new(collection("#{COMMAND}.aggregate"), {}, view_options),
    pipeline,
    Mongo::Collection::View::ChangeStream::DATABASE,
    options
  )
end