MongoDB::Database - A MongoDB Database
version v2.2.2
# 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
the MongoDB::Collection manpage 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 the MongoDB::MongoClient manpage object.
Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs. The error types are documented in the MongoDB::Error manpage.
To catch and handle errors, the the Try::Tiny manpage and the Safe::Isa manpage 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 the Try::Tiny::Retry manpage.
The name of the database.
A the MongoDB::ReadPreference manpage 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 the MongoDB::MongoClient manpage object.
A the MongoDB::WriteConcern manpage 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 the MongoDB::MongoClient manpage object.
A the MongoDB::ReadConcern manpage 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 the MongoDB::MongoClient manpage 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.
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 the MongoDB::MongoClient manpage object.
$client = $db->client;
Returns the the MongoDB::MongoClient manpage object associated with this
object.
$result = $coll->list_collections( $filter );
$result = $coll->list_collections( $filter, $options );
Returns a the MongoDB::QueryResult manpage 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 the MongoDB::ClientSession manpage
NOTE: When using nameOnly, the filter query must be empty or must only
query the name field or else no documents will be found.
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:
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.
my $collection = $database->get_collection('foo');
my $collection = $database->get_collection('foo', $options);
my $collection = $database->coll('foo', $options);
Returns a the MongoDB::Collection manpage for the given collection name within this
database.
It takes an optional hash reference of options that are passed to the
the MongoDB::Collection manpage constructor.
The coll method is an alias for get_collection.
my $grid = $database->get_gridfsbucket;
my $grid = $database->get_gridfsbucket($options);
my $grid = $database->gfs($options);
This method returns a the MongoDB::GridFSBucket manpage object for storing and
retrieving files from the database.
It takes an optional hash reference of options that are passed to the
the MongoDB::GridFSBucket manpage constructor.
See the MongoDB::GridFSBucket manpage for more information.
The gfs method is an alias for get_gridfsbucket.
$database->drop;
Deletes the database.
A hashref of options may also be provided.
Valid options include:
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 the Tie::IxHash manpage 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 the MongoDB::ReadPreference manpage object or a hash reference that can be used to
construct one.
A hashref of options may also be provided.
Valid options include:
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 the MongoDB::Examples manpage section. See also core documentation
on database commands: http://dochub.mongodb.org/core/commands.
Runs a query using the MongoDB 3.6+ aggregation framework and returns a
the MongoDB::QueryResult manpage 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.
Watches for changes on this database.
Perform an aggregation with an implicit initial $changeStream stage
and returns a the MongoDB::ChangeStream manpage 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 the MongoDB::Collection manpage for details on usage and available
options.
This software is Copyright (c) 2020 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
|