MongoDB::Database - A MongoDB Database
version v1.4.5
# 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]);
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.
new
get_database
Unless otherwise explictly 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.
The name of the database.
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.
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.
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.
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.
$maxTimeMS
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.
encode_one
decode_one
$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:
name
options
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.
batchSize
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.)
maxTimeMS
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.
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.
coll
get_collection
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.
gfs
get_gridfsbucket
my $grid = $database->get_gridfs; my $grid = $database->get_gridfs("fs"); my $grid = $database->get_gridfs("fs", $options);
The MongoDB::GridFS class has been deprecated in favor of the new MongoDB driver-wide standard GridFS API, available via MongoDB::GridFSBucket and the get_gridfsbucket/gfs methods.
This method 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".
$grid->files
$grid->chunks
It takes an optional hash reference of options that are passed to the MongoDB::GridFS constructor.
See MongoDB::GridFS for more information.
$database->drop;
Deletes the database.
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.
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
David Golden <david@mongodb.com>
Mike Friedman <friedo@friedo.com>
Kristina Chodorow <k.chodorow@gmail.com>
Florian Ragwitz <rafl@debian.org>
This software is Copyright (c) 2016 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install MongoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDB
CPAN shell
perl -MCPAN -e shell install MongoDB
For more information on module installation, please visit the detailed CPAN module installation guide.