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.2-TRIAL
River stage two • 48 direct dependents • 56 total dependents
88 ++
/ MongoDB::Database

NAME

MongoDB::Database - A MongoDB Database

VERSION

version v0.999.998.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.

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.

write_concern

A MongoDB::WriteConcern object. It may be initialized with a hash reference that will be coerced into a new MongoDB::WriteConcern object.

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 ($prefix?)

    my $grid = $database->get_gridfs;

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

See MongoDB::GridFS for more information.

drop

    $database->drop;

Deletes the database.

run_command

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

    my $result = $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 result 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 $result = $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}}.

last_error (DEPRECATED)

    my $err = $db->last_error({w => 2});

Because write operations now return result information, this function is deprecated.

Finds out if the last database operation completed successfully. If a hash reference of options is provided, they are included with the database command. Throws an exception if getLastError itself fails.

See the getLastError documentation for more on valid options and results.

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