View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Rodrigo de Oliveira Gonzalez > Mongoose-0.20 > Mongoose::Intro


Annotate this POD



New  3
Open  0
View/Report Bugs
Source   Latest Release: Mongoose-1.02


Mongoose::Intro - an introduction


version 0.20


This module is an attempt to bring together the full power of Moose into one of the hottest new databases out there: MongoDB.

Before using this module you should take a little time to read on MongoDB.

Why not use KiokuDB? ^

KiokuDB is an awesome module that maps objects to data and caters to a wide variety of backends. Currently there's even a MongoDB backend that may suit your needs.

So, why use Mongoose instead?

If you don't need any of this, go grab KiokuDB instead. It's much more configurable, stable and you can painlessly switch backends in the future.


To use this module, you need:

MongoDB installed somewhere in your network.

Grab a pre-built copy for your OS from here, or build it from sources.

After intalling the software, start the Mongo daemon:

    mongod -dbpath /path/to/data

The MongoDB Perl driver

    cpan MongoDB
    cpan Mongoose

Set the MONGOOSEDB environment variable to your MongoDB connection in case it's not standard (localhost).

    export MONGOOSEDB=host,mongodb://localhost,db_name,mytestdb
    make test
    make install

Moose classes

Create some Moose classes to start using Mongoose;

    package MyClass;
    use Moose;
    with 'Mongoose::Document';
    has 'yada' => ( is=>'rw', isa=>'Str' );


Some of Mongoose features:



There are only two steps to start using Mongoose in your code:

1) Create at least one class that consumes a Mongoose::Document role.

2) Connect to a Mongo database in your main program.

MongoDB does not require you to previously create a database, a collection or a document schema for your collection. This is done on the fly for you.

To make your Moose classes "Mongoable", all they need is to consume either one of two roles: Mongoose::Document or Mongoose::EmbeddedDocument. Read on for details on the difference.

Turning your classes into Mongo Documents

There are two roles to make your Moose class a Mongoose document:

* Mongoose::Document

* Mongoose::EmbeddedDocument

The difference between these roles lies in the way objects of different classes will be joined and stored (collapsed) into the DB.

Read the MongoDB docs if you don't understand the difference.


Akin to a row in the relational model. Objects are stored into independent collections. Relationships are stored using references, MongoDB's foreign key system.


Tells Mongoose to store your class as an embedded document, inside a parent document.

This is usually faster than using document-to-document reference joins. But it's not meant for object reuse by foreign documents.

Methods you get when using the Document roles

Both Document and EmbeddedDocument will import into your class the following methods:


Saves the current object to the database, inserting the document if needed.



Deletes the correspondind document from the database.



Wraps MongoDB's find method to return a cursor that expands data into objects.


    my $cursor = Person->query({ age => { '$lt' => 30 } });


Finds exactly one document.

    my $jack = Person->find_one({ first_name => 'Jack' });


Returns the MongoDB::Collection object supporting this class. It's a way to switch quickly back to MongoDB hash documents.

    Person->find_one({ name=>'thyself' }); # isa Person

    # whereas

    Person->collection->find_one({ name=>'thyself' }); # ref = HASH


Not really a method but an attribute used by Mongoose (and MongoDB). Contains a unique MongoDB::OID instance.

Deleting or modifying this attribute may cause your object to be re-inserted on the next save, instead of being updated.

The Default Engine

Mongoose comes with a default engine, Mongoose::Engine::Base that takes care of expanding and collapsing objects to and from the Mongo database.


Collapsing is the process of serializing classes.

Your Moose objects are collapsed by unblessing them until they become a hash. Relationships are mantained in the process.


Expansion is the process of inflating Mongo documents (plain hashes) into Moose objects.

This is done by inspecting the class attribute metadata. The base engine tries to do it's best identifying data types. The document is then blessed into your class. This is faster than calling new, but also means that no special class or attribute methods will be fired, such as default values, setters, triggers or coercion. You've been warned.

Naturally, there are many cases where this guesswork is not enough. These may be addressed in the future using attribute traits, but should be fine for most trivial classes.


Mongoose roles are role parameterized for greater flexibility.

Collection naming

You can control the collection name for an individual class this way:

    package My::Mumbo::Jumbo::Class;
    use Moose;
    with 'Mongoose::Document' => {
        -collection_name => 'mumbo_jumbo'   

Global collection naming stategy

By default, Mongoose will turn package names into collections this way:

    Package name          | Collection name
    Person                | person
    Humpty::Dumpty        | humpty_dumpty
    HumptyDumpty          | humpty_dumpty
    MyApp::Schema::Jumbo  | my_app_schema_jumbo

You can change this standard anytime, by setting the Mongoose::naming anonymous sub to something of your liking:

    # remove prefix and return
    #  a lower case collection name

    Mongoose->naming( sub{
        my $pkg = shift;
        $pkg =~ s{^MyApp::Schema::}{}g;
        return lc $pkg;

Primary keys

The standard way MongoDB deals with primary keys is by using the _id attribute. By default, a MongoDB::OID is assigned to each object you commit to the database with save.

Checkout this Devel::REPL example:

    > use Person;

    > my $hurley = Person->new(name=>'Hurley');                                                                                                                                         
    $Person1 = Person=HASH(0x102099d08);

    > $hurley->dump;                                                                                                                                                                    
    $VAR1 = bless( {
                     'name' => 'Hurley'
                   }, 'Person' );

    > $hurley->save;                                                                                                                                                                    
    4c683525a74100a8df000000                                                                                                                                                            $ $hurley->dump;         

    > $hurley->dump;                                                                                                                                                                    
    $VAR1 = bless( {
                     '_id' => bless( {
                           'value' => '4c683525a74100a8df000000'
                             }, 'MongoDB::OID' ),
                     'name' => 'Hurley'
                   }, 'Person' );

This is pretty standard MongoDB stuff.

Now, for a more control over your primary key, use the role parameter -pk.

    package BankAccount;
    use Moose;
    with 'Mongoose::Document' => {
        -pk    => [qw/ drivers_license /]
    has 'drivers_license' => (is=>'rw', isa=>'Int' );

That way, with every insert or update, the drivers_license field is checked with the help of the upsert feature of Mongo.

Schema Changes

If you first had a class definition as such:

    package Author;
    use Moose; with 'Mongoose::Document';

    has 'name' => ( is=>'rw', isa=>'Str' );

Saved some objects into the DB:

    Author->new( name=>'Mike Old Schema' )->save;

Then, later on, changed it to:

    has 'first_name' => ( is=>'rw', isa=>'Str' );

When reading from the database, at expansion time, since the MongoDB document is just blessed into your class the old attribute will be loaded as if nothing had happened:

    # load old schema document using the new schema:

    my $obj = Author->find_one({ name => 'Mike Old Schema' });
    print Dump $obj;

    # prints

    --- !!perl/hash:MyTestApp::Schema::Author
    _id: !!perl/hash:MongoDB::OID
          value: 4c723348a741001455000000
    name: Mike Old Schema

At this time, no BUILD or BUILDARGS methods are called, which could be used to rearrange the object into the new schema. This will be probably fixed soon.

On the meanwhile, you can always invoke an "alignment" method after loading the data, or do a bulk migration:

    Author->find->each( sub{
        my $obj = shift;
        $obj->first_name( delete $obj->{name} );


Now head on to the Mongoose::Cookbook.

syntax highlighting: