.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::Database 3pm"
.TH MongoDB::Database 3pm "2020-08-15" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::Database \- A MongoDB Database
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 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]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class models a MongoDB database.  Use it to construct
MongoDB::Collection objects. It also provides the \*(L"run_command\*(R" method and
some convenience methods that use it.
.PP
Generally, you never construct one of these directly with \f(CW\*(C`new\*(C'\fR.  Instead, you
call \f(CW\*(C`get_database\*(C'\fR on a MongoDB::MongoClient object.
.SH "USAGE"
.IX Header "USAGE"
.SS "Error handling"
.IX Subsection "Error handling"
Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs.  The error types are documented in MongoDB::Error.
.PP
To catch and handle errors, the Try::Tiny and Safe::Isa modules
are recommended:
.PP
.Vb 2
\&    use Try::Tiny;
\&    use Safe::Isa; # provides $_isa
\&
\&    try {
\&        $db\->run_command( @command )
\&    }
\&    catch {
\&        if ( $_\->$_isa("MongoDB::DuplicateKeyError" ) {
\&            ...
\&        }
\&        else {
\&            ...
\&        }
\&    };
.Ve
.PP
To retry failures automatically, consider using Try::Tiny::Retry.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "name"
.IX Subsection "name"
The name of the database.
.SS "read_preference"
.IX Subsection "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.
.SS "write_concern"
.IX Subsection "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.
.SS "read_concern"
.IX Subsection "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.
.PP
By default it will be inherited from a MongoDB::MongoClient object.
.SS "max_time_ms"
.IX Subsection "max_time_ms"
Specifies the maximum amount of time in milliseconds that the server should use
for working on a query.
.PP
\&\fBNote\fR: this will only be used for server versions 2.6 or greater, as that
was when the \f(CW$maxTimeMS\fR meta-operator was introduced.
.SS "bson_codec"
.IX Subsection "bson_codec"
An object that provides the \f(CW\*(C`encode_one\*(C'\fR and \f(CW\*(C`decode_one\*(C'\fR methods, such as
from \s-1BSON\s0.  It may be initialized with a hash reference that will
be coerced into a new \s-1BSON\s0 object.  By default it will be inherited
from a MongoDB::MongoClient object.
.SH "METHODS"
.IX Header "METHODS"
.SS "client"
.IX Subsection "client"
.Vb 1
\&    $client = $db\->client;
.Ve
.PP
Returns the MongoDB::MongoClient object associated with this
object.
.SS "list_collections"
.IX Subsection "list_collections"
.Vb 2
\&    $result = $coll\->list_collections( $filter );
\&    $result = $coll\->list_collections( $filter, $options );
.Ve
.PP
Returns a MongoDB::QueryResult object to iterate over collection description
documents.  These will contain \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`options\*(C'\fR keys like so:
.PP
.Vb 1
\&    use boolean;
\&
\&    {
\&        name => "my_capped_collection",
\&        options => {
\&            capped => true,
\&            size => 10485760,
\&        }
\&    },
.Ve
.PP
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.
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`batchSize\*(C'\fR – the number of documents to return per batch.
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR – the maximum amount of time in milliseconds to allow the command to run.  (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`nameOnly\*(C'\fR \- query and return names of the collections only. Defaults to false. (Note, this will be ignored for servers before version 4.0)
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
\&\fB\s-1NOTE\s0\fR: When using \f(CW\*(C`nameOnly\*(C'\fR, the filter query must be empty or must only
query the \f(CW\*(C`name\*(C'\fR field or else no documents will be found.
.SS "collection_names"
.IX Subsection "collection_names"
.Vb 3
\&    my @collections = $database\->collection_names;
\&    my @collections = $database\->collection_names( $filter );
\&    my @collections = $database\->collection_names( $filter, $options );
.Ve
.PP
Returns the list of collections in this database.
.PP
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.
.PP
A hashref of options may also be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
\&\fBWarning:\fR if the number of collections is very large, this may return
a very large result.  Either pass an appropriate filter, or use
\&\*(L"list_collections\*(R" to iterate over collections instead.
.SS "get_collection, coll"
.IX Subsection "get_collection, coll"
.Vb 3
\&    my $collection = $database\->get_collection(\*(Aqfoo\*(Aq);
\&    my $collection = $database\->get_collection(\*(Aqfoo\*(Aq, $options);
\&    my $collection = $database\->coll(\*(Aqfoo\*(Aq, $options);
.Ve
.PP
Returns a MongoDB::Collection for the given collection name within this
database.
.PP
It takes an optional hash reference of options that are passed to the
MongoDB::Collection constructor.
.PP
The \f(CW\*(C`coll\*(C'\fR method is an alias for \f(CW\*(C`get_collection\*(C'\fR.
.SS "get_gridfsbucket, gfs"
.IX Subsection "get_gridfsbucket, gfs"
.Vb 3
\&    my $grid = $database\->get_gridfsbucket;
\&    my $grid = $database\->get_gridfsbucket($options);
\&    my $grid = $database\->gfs($options);
.Ve
.PP
This method returns a MongoDB::GridFSBucket object for storing and
retrieving files from the database.
.PP
It takes an optional hash reference of options that are passed to the
MongoDB::GridFSBucket constructor.
.PP
See MongoDB::GridFSBucket for more information.
.PP
The \f(CW\*(C`gfs\*(C'\fR method is an alias for \f(CW\*(C`get_gridfsbucket\*(C'\fR.
.SS "drop"
.IX Subsection "drop"
.Vb 1
\&    $database\->drop;
.Ve
.PP
Deletes the database.
.PP
A hashref of options may also be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.SS "run_command"
.IX Subsection "run_command"
.Vb 1
\&    my $output = $database\->run_command([ some_command => 1 ]);
\&
\&    my $output = $database\->run_command(
\&        [ some_command => 1 ],
\&        { mode => \*(AqsecondaryPreferred\*(Aq }
\&    );
\&
\&    my $output = $database\->run_command(
\&        [ some_command => 1 ],
\&        $read_preference,
\&        $options
\&    );
.Ve
.PP
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.
.PP
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.
.PP
A hashref of options may also be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
It returns the output of the command (a hash reference) on success or throws a
MongoDB::DatabaseError exception if
the command fails.
.PP
For a list of possible database commands, run:
.PP
.Vb 1
\&    my $commands = $db\->run_command([listCommands => 1]);
.Ve
.PP
There are a few examples of database commands in the
\&\*(L"\s-1DATABASE COMMANDS\*(R"\s0 in MongoDB::Examples section.  See also core documentation
on database commands: <http://dochub.mongodb.org/core/commands>.
.SS "aggregate"
.IX Subsection "aggregate"
Runs a query using the MongoDB 3.6+ aggregation framework and returns a
MongoDB::QueryResult object.
.PP
The first argument must be an array-ref of aggregation
pipeline <http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents.
Each pipeline document must be a hash reference.
.PP
The server supports several collection-less aggregation source stages like
\&\f(CW$currentOp\fR and \f(CW$listLocalSessions\fR.
.PP
.Vb 7
\&    $result = $database\->aggregate( [
\&        {
\&            "\e$currentOp" => {
\&                allUsers => true,
\&            },
\&        },
\&    ] );
.Ve
.PP
See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the MongoDB manual
for more information on how to construct aggregation queries.
.SS "watch"
.IX Subsection "watch"
Watches for changes on this database.
.PP
Perform an aggregation with an implicit initial \f(CW$changeStream\fR 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.
.PP
.Vb 3
\&    my $stream = $db\->watch();
\&    my $stream = $db\->watch( \e@pipeline );
\&    my $stream = $db\->watch( \e@pipeline, \e%options );
\&
\&    while (1) {
\&
\&        # This inner loop will only run until no more changes are
\&        # available.
\&        while (my $change = $stream\->next) {
\&            # process $change
\&        }
\&    }
.Ve
.PP
The returned stream will not block forever waiting for changes. If you
want to respond to changes over a longer time use \f(CW\*(C`maxAwaitTimeMS\*(C'\fR and
regularly call \f(CW\*(C`next\*(C'\fR in a loop.
.PP
See \*(L"watch\*(R" in MongoDB::Collection for details on usage and available
options.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve