NAME

       MongoDB::Database - A MongoDB Database

VERSION

       version v1.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
       MongoDB::BSON.  It may be initialized with a hash reference that will be coerced into a
       new MongoDB::BSON object.  By default it will be inherited from a MongoDB::MongoClient
       object.

METHODS

   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 <http://docs.mongodb.org/manual/reference/command/listCollections/> 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.)

   collection_names
           my @collections = $database->collection_names;

       Returns the list of collections in this database.

       Warning: if the number of collections is very large, this will return a very large result.
       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_gridfs
           my $grid = $database->get_gridfs;
           my $grid = $database->get_gridfs("fs");
           my $grid = $database->get_gridfs("fs", $options);

       Returns a MongoDB::GridFS for storing and retrieving files from the database.  Default
       prefix is "fs", making "$grid->files" "fs.files" and "$grid->chunks" "fs.chunks".

       It takes an optional hash reference of options that are passed to the MongoDB::GridFS
       constructor.

       See MongoDB::GridFS for more information.

   drop
           $database->drop;

       Deletes the database.

   run_command
           my $output = $database->run_command([ some_command => 1 ]);

           my $output = $database->run_command(
               [ some_command => 1 ],
               { mode => 'secondaryPreferred' }
           );

       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.  The use of a hash reference
       will only reliably work for commands without additional parameters.

       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.

       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:
       <http://dochub.mongodb.org/core/commands>.

DEPRECATIONS

       The methods still exist, but are no longer documented.  In a future version they will warn
       when used, then will eventually be removed.

       •   last_error

AUTHORS

       •   David Golden <david@mongodb.com>

       •   Mike Friedman <friedo@friedo.com>

       •   Kristina Chodorow <k.chodorow@gmail.com>

       •   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2016 by MongoDB, Inc..

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004