# MongoDB::Database - phpMan ## NAME [MongoDB::Database] - A MongoDB Database ## VERSION version v2.2.2 ## SYNOPSIS # get a Database object via [MongoDB::MongoClient] my $db = $client->get_database("foo"); # get a Collection via the Database object my $coll = $db->get_collection("people"); # run a command on a database my $res = $db->run_command([ismaster => 1]); ## DESCRIPTION This class models a MongoDB database. Use it to construct [MongoDB::Collection] objects. It also provides the "run_command" method and some convenience methods that use it. Generally, you never construct one of these directly with "new". Instead, you call "get_database" on a [MongoDB::MongoClient] object. ## USAGE Error handling Unless otherwise explicitly documented, all methods throw exceptions if an error occurs. The error types are documented in [MongoDB::Error]. To catch and handle errors, the [Try::Tiny] and [Safe::Isa] modules are recommended: use [Try::Tiny]; use [Safe::Isa]; # provides $_isa try { $db->run_command( @command ) } catch { if ( $_->$_isa("[MongoDB::DuplicateKeyError]" ) { ... } else { ... } }; To retry failures automatically, consider using [Try::Tiny::Retry]. ## ATTRIBUTES name The name of the database. read_preference A [MongoDB::ReadPreference] object. It may be initialized with a string corresponding to one of the valid read preference modes or a hash reference that will be coerced into a new [MongoDB::ReadPreference] object. By default it will be inherited from a [MongoDB::MongoClient] object. write_concern A [MongoDB::WriteConcern] object. It may be initialized with a hash reference that will be coerced into a new [MongoDB::WriteConcern] object. By default it will be inherited from a [MongoDB::MongoClient] object. read_concern A [MongoDB::ReadConcern] object. May be initialized with a hash reference or a string that will be coerced into the level of read concern. By default it will be inherited from a [MongoDB::MongoClient] object. max_time_ms Specifies the maximum amount of time in milliseconds that the server should use for working on a query. Note: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS meta-operator was introduced. bson_codec An object that provides the "encode_one" and "decode_one" methods, such as from BSON. It may be initialized with a hash reference that will be coerced into a new BSON object. By default it will be inherited from a [MongoDB::MongoClient] object. ## METHODS client $client = $db->client; Returns the [MongoDB::MongoClient] object associated with this object. list_collections $result = $coll->list_collections( $filter ); $result = $coll->list_collections( $filter, $options ); Returns a [MongoDB::QueryResult] object to iterate over collection description documents. These will contain "name" and "options" keys like so: use boolean; { name => "my_capped_collection", options => { capped => true, size => 10485760, } }, An optional filter document may be provided, which cause only collection description documents matching a filter expression to be returned. See the listCollections command documentation <> for more details on filtering for specific collections. A hash reference of options may be provided. Valid keys include: * "batchSize" – the number of documents to return per batch. * "maxTimeMS" – the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.) * "nameOnly" - query and return names of the collections only. Defaults to false. (Note, this will be ignored for servers before version 4.0) * "session" - the session to use for these operations. If not supplied, will use an implicit session. For more information see [MongoDB::ClientSession] NOTE: When using "nameOnly", the filter query must be empty or must only query the "name" field or else no documents will be found. collection_names my @collections = $database->collection_names; my @collections = $database->collection_names( $filter ); my @collections = $database->collection_names( $filter, $options ); Returns the list of collections in this database. An optional filter document may be provided, which cause only collection description documents matching a filter expression to be returned. See the listCollections command documentation <> for more details on filtering for specific collections. A hashref of options may also be provided. Valid options include: * "session" - the session to use for these operations. If not supplied, will use an implicit session. For more information see [MongoDB::ClientSession] Warning: if the number of collections is very large, this may return a very large result. Either pass an appropriate filter, or use "list_collections" to iterate over collections instead. get_collection, coll my $collection = $database->get_collection('foo'); my $collection = $database->get_collection('foo', $options); my $collection = $database->coll('foo', $options); Returns a [MongoDB::Collection] for the given collection name within this database. It takes an optional hash reference of options that are passed to the [MongoDB::Collection] constructor. The "coll" method is an alias for "get_collection". get_gridfsbucket, gfs my $grid = $database->get_gridfsbucket; my $grid = $database->get_gridfsbucket($options); my $grid = $database->gfs($options); This method returns a [MongoDB::GridFSBucket] object for storing and retrieving files from the database. It takes an optional hash reference of options that are passed to the [MongoDB::GridFSBucket] constructor. See [MongoDB::GridFSBucket] for more information. The "gfs" method is an alias for "get_gridfsbucket". drop $database->drop; Deletes the database. A hashref of options may also be provided. Valid options include: * "session" - the session to use for these operations. If not supplied, will use an implicit session. For more information see [MongoDB::ClientSession] run_command my $output = $database->run_command([ some_command => 1 ]); my $output = $database->run_command( [ some_command => 1 ], { mode => 'secondaryPreferred' } ); my $output = $database->run_command( [ some_command => 1 ], $read_preference, $options ); This method runs a database command. The first argument must be a document with the command and its arguments. It should be given as an array reference of key-value pairs or a [Tie::IxHash] object with the command name as the first key. An error will be thrown if the command is not an ordered document. By default, commands are run with a read preference of 'primary'. An optional second argument may specify an alternative read preference. If given, it must be a [MongoDB::ReadPreference] object or a hash reference that can be used to construct one. A hashref of options may also be provided. Valid options include: * "session" - the session to use for these operations. If not supplied, will use an implicit session. For more information see [MongoDB::ClientSession] It returns the output of the command (a hash reference) on success or throws a [MongoDB::DatabaseError] exception if the command fails. For a list of possible database commands, run: my $commands = $db->run_command([listCommands => 1]); There are a few examples of database commands in the "DATABASE COMMANDS" in [MongoDB::Examples] section. See also core documentation on database commands: <>. aggregate Runs a query using the MongoDB 3.6+ aggregation framework and returns a [MongoDB::QueryResult] object. The first argument must be an array-ref of aggregation pipeline <> documents. Each pipeline document must be a hash reference. The server supports several collection-less aggregation source stages like $currentOp and $listLocalSessions. $result = $database->aggregate( [ { "\$currentOp" => { allUsers => true, }, }, ] ); See Aggregation <> in the MongoDB manual for more information on how to construct aggregation queries. watch Watches for changes on this database. Perform an aggregation with an implicit initial $changeStream stage and returns a [MongoDB::ChangeStream] result which can be used to iterate over the changes in the database. This functionality is available since MongoDB 4.0. my $stream = $db->watch(); my $stream = $db->watch( \@pipeline ); my $stream = $db->watch( \@pipeline, \%options ); while (1) { # This inner loop will only run until no more changes are # available. while (my $change = $stream->next) { # process $change } } The returned stream will not block forever waiting for changes. If you want to respond to changes over a longer time use "maxAwaitTimeMS" and regularly call "next" in a loop. See "watch" in [MongoDB::Collection] for details on usage and available options. ## AUTHORS * David Golden <> * Rassi <> * Mike Friedman <> * Kristina Chodorow <> * Florian Ragwitz <> ## COPYRIGHT AND LICENSE This software is Copyright (c) 2020 by MongoDB, Inc. This is free software, licensed under: The Apache License, Version 2.0, January 2004