The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
MongoDB-v0.999.998.6-TRIAL
River stage two • 48 direct dependents • 56 total dependents
/ MongoDB::Database

NAME

MongoDB::Database - A MongoDB Database

VERSION

version v0.999.998.6

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 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.

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.

bson_codec

An object that provides the encode_one and decode_one methods, such as from MongoDB::BSON.

METHODS

collection_names

my @collections = $database->collection_names;

Returns the list of collections in this database.

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.

eval ($code, $args?, $nolock?)

my $output = $database->eval('function(x) { return "hello, "+x; }', ["world"]);

Evaluate a JavaScript expression on the Mongo server. The $code argument can be a string or an instance of MongoDB::Code. The $args are an optional array of arguments to be passed to the $code function. $nolock (default false) prevents the eval command from taking the global write lock before evaluating the JavaScript.

eval is useful if you need to touch a lot of data lightly; in such a scenario the network transfer of the data could be a bottleneck. The $code argument must be a JavaScript function. $args is an array of parameters that will be passed to the function. $nolock is a boolean value. For more examples of using eval see http://www.mongodb.org/display/DOCS/Server-side+Code+Execution#Server-sideCodeExecution-Using{{db.eval%28%29}}.

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@mongodb.com>

  • Kristina Chodorow <kristina@mongodb.com>

  • Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004