NAME

MongoDB::Database - A Mongo database

SYNOPSIS

The MongoDB::Database class accesses to a database.

    # accesses the foo database
    my $db = $connection->foo;

You can also access databases with the get_database($name) in the MongoDB::Connection manpage method.

ATTRIBUTES

METHODS

collection_names

    my @collections = $database->collection_names;

Returns the list of collections in this database.

get_collection ($name)

    my $collection = $database->get_collection('foo');

Returns a the MongoDB::Collection manpage for the collection called $name within this database.

get_gridfs ($prefix?)

    my $grid = $database->get_gridfs;

Returns a the MongoDB::GridFS manpage for storing and retrieving files from the database. Default prefix is "fs", making $grid->files "fs.files" and $grid->chunks "fs.chunks".

See the MongoDB::GridFS manpage for more information.

`last_error($options?)`

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

Finds out if the last database operation completed successfully. If the last operation did not complete successfully, returns a hash reference of information about the error that occured.

The optional $options parameter is a hash reference that can contain any of the following:

w: Guarantees that the previous operation will be replicated to w servers before this command will return success. See MongoDB::Connection::w for more information.
wtimeout: Milliseconds to wait for w copies of the data to be made. This parameter should generally be specified, as the database will otherwise wait forever if w copies cannot be made.
fsync: If true, the database will fsync to disk before returning.

last_error returns a hash with fields that vary, depending on what the previous operation was and if it succeeded or failed. If the last operation (before the last_error call) failed, either:

err will be set or =item errmsg will be set and ok will be 0.

If err is null and ok is 1, the previous operation succeeded.

The fields in the hash returned can include (but are not limited to):

ok: This should almost be 1 (unless last_error itself failed).
err: If this field is non-null, an error occurred on the previous operation. If this field is set, it will be a string describing the error that occurred.
code: If a database error occurred, the relevant error code will be passed back to the client.
errmsg: This field is set if something goes wrong with a database command. It is coupled with ok being 0. For example, if w is set and times out, errmsg will be set to "timed out waiting for slaves" and ok will be 0. If this field is set, it will be a string describing the error that occurred.
n: If the last operation was an insert, an update or a remove, the number of objects affected will be returned.
wtimeout: If the previous option timed out waiting for replication.
waited: How long the operation waited before timing out.
wtime: If w was set and the operation succeeded, how long it took to replicate to w servers.
upserted: If an upsert occured, this field will contain the new record's _id field. For upserts, either this field or updatedExisting will be present (unless an error occurred).
updatedExisting: If an upsert updated an existing element, this field will be true. For upserts, either this field or upserted will be present (unless an error occurred).

See w in the MongoDB::Connection manpage for more information.

run_command ($command)

    my $result = $database->run_command({ some_command => 1 });

Runs a database command. Throws an exception with an error message if the command fails. Returns the result of the command on success. 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.

eval ($code, $args?)

    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 the MongoDB::Code manpage. The $args are an optional array of arguments to be passed to the $code function.

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. For more examples of using eval see http://www.mongodb.org/display/DOCS/Server-side+Code+Execution#Server-sideCodeExecution-Using{{db.eval%28%29}}.

AUTHOR

  Kristina Chodorow <kristina@mongodb.org>

MongoDB::Database - A Mongo database