Database — Documentation by YARD 0.9.37 (original) (raw)

Class: Mongo::Database

Inherits:

Object

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.

Defined Under Namespace

Classes: View

Constant Summarycollapse

ADMIN =

'admin'.freeze

COMMAND =

The “collection” that database commands operate against.

'$cmd'.freeze

DEFAULT_OPTIONS =

The default database options.

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

NAME =

Database name field constant.

'name'.freeze

DATABASES =

'databases'.freeze

NAMESPACES =

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

'system.namespaces'.freeze

Instance Attribute Summary collapse

Class Method Summarycollapse

Instance Method Summarycollapse

Methods included from Retryable

#read_worker, #select_server, #write_worker

Constructor Details

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

Instantiate a new database object.

| 362 363 364 365 366 367 368 369 370 | # File 'lib/mongo/database.rb', line 362 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

Returns client The database client.

62 63 64 # File 'lib/mongo/database.rb', line 62 def client @client end

#name ⇒ String

Returns name The name of the database.

65 66 67 # File 'lib/mongo/database.rb', line 65 def name @name end

#options ⇒ Hash

Returns options The options.

68 69 70 # File 'lib/mongo/database.rb', line 68 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.

543 544 545 546 # File 'lib/mongo/database.rb', line 543 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.

94 95 96 97 # File 'lib/mongo/database.rb', line 94 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.

110 111 112 113 114 115 # 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.

450 451 452 # File 'lib/mongo/database.rb', line 450 def aggregate(pipeline, options = {}) View.new(self, options).aggregate(pipeline, options) end

#cluster ⇒ Mongo::Server

Returns Get the primary server from the cluster.

80 81 # File 'lib/mongo/database.rb', line 80 def_delegators :cluster, :next_primary

#collection_names(options = {}) ⇒ Array

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.
142 143 144 # File 'lib/mongo/database.rb', line 142 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.

| 203 204 205 | # File 'lib/mongo/database.rb', line 203 def collections(options = {}) collection_names(options).map { |name| collection(name) } end | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |

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

Execute a command on the database.

| 229 230 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 | # File 'lib/mongo/database.rb', line 229 def command(operation, opts = {}) opts = opts.dup execution_opts = opts.delete(:execution_options) || {} txn_read_pref = if opts[:session] && opts[:session].in_transaction? opts[:session].txn_read_preference else nil end 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| server = selector.select_server(cluster, nil, session) op = Operation::Command.new( :selector => operation, :db_name => name, :read => selector, :session => session ) op.execute(server, context: Operation::Context.new( client: client, session: session, operation_timeouts: operation_timeouts(opts) ), options: execution_opts) end end | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

#drop(options = {}) ⇒ Result

Drop the database and all its associated information.

| 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | # File 'lib/mongo/database.rb', line 322 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.

404 405 406 # File 'lib/mongo/database.rb', line 404 def fs(options = {}) Grid::FSBucket.new(self, options) end

#inspect ⇒ String

Get a pretty printed string inspection for the database.

380 381 382 # File 'lib/mongo/database.rb', line 380 def inspect "#<Mongo::Database:0x#{object_id} name=#{name}>" end

#list_collections(options = {}) ⇒ Array

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.
175 176 177 # File 'lib/mongo/database.rb', line 175 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).

| 560 561 562 563 564 565 566 567 568 569 | # File 'lib/mongo/database.rb', line 560 def operation_timeouts(opts) {}.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.

| 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 | # File 'lib/mongo/database.rb', line 277 def read_command(operation, opts = {}) txn_read_pref = if opts[:session] && opts[:session].in_transaction? opts[:session].txn_read_preference else nil end 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) ) read_with_retry(session, preference, context) do | server| Operation::Command.new( selector: operation.dup, db_name: name, read: preference, session: session, comment: opts[:comment], ).execute(server, context: context) 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.

| 552 553 554 | # File 'lib/mongo/database.rb', line 552 def timeout_ms options[:timeout_ms] || client.timeout_ms end | | ----------- | -------------------------------------------------------------------------------------------------------------- |

#users ⇒ View::User

Get the user view for this database.

416 417 418 # File 'lib/mongo/database.rb', line 416 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.