GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MONGODB::DATABASE (3)

.ds Aq ’

NAME

MongoDB::Database - A MongoDB Database

CONTENTS

VERSION

version v1.2.3

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.

    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.

By default it will be inherited from a MongoDB::MongoClient object.

    max_time_ms

Specifies the maximum amount of time in milliseconds that the server should use for working on a query.

<B>NoteB>: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS meta-operator was introduced.

    bson_codec

An object that provides the encode_one and decode_one methods, such as from MongoDB::BSON. It may be initialized with a hash reference that will be coerced into a new MongoDB::BSON object. By default it will be inherited from a MongoDB::MongoClient object.

METHODS

    list_collections



    $result = $coll->list_collections( $filter );
    $result = $coll->list_collections( $filter, $options );



Returns a MongoDB::QueryResult 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 <http://docs.mongodb.org/manual/reference/command/listCollections/> for more details on filtering for specific collections.

A hash reference of options may be provided. Valid keys include:
o batchSize X the number of documents to return per batch.
o maxTimeMS X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)

    collection_names



    my @collections = $database->collection_names;



Returns the list of collections in this database.

<B>Warning:B> if the number of collections is very large, this will return a very large result. Use list_collections to iterate over collections instead.

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

DEPRECATIONS

The methods still exist, but are no longer documented. In a future version they will warn when used, then will eventually be removed.
o last_error

AUTHORS

o David Golden <david@mongodb.com>
o Mike Friedman <friedo@friedo.com>
o Kristina Chodorow <k.chodorow@gmail.com>
o Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:



  The Apache License, Version 2.0, January 2004



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MONGODB::DATABASE (3) 2016-03-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.