--- name: "MongoDB::Database" section: "3pm" platform: "linux" package: "libmongodb-perl" version: "2.2.2-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/MongoDB::Database" --- # MongoDB::Database(3pm) A MongoDB Database ## 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 ```