NAME

Mongoose - MongoDB document to Moose object mapper

SYNOPSIS

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

    package main;
    use Mongoose;

    Mongoose->db('mydb');

    my $person = Person->new( name => 'Jack' );
    $person->save;

    $person = Person->find_one({ name => 'Jack' });
    say $person->name; # Jack

    Person->find({ name => qr/^J/' })->each(sub{
        say "Found ", $person->name;
    });

    $person->delete;

DESCRIPTION

This is a MongoDB to Moose object mapper. This module allows you to use the full power of MongoDB within your Moose classes, without sacrificing MongoDB's power, flexibility and speed.

It's loosely inspired by Ruby's MongoMapper, which is in turn loosely based on the ActiveRecord pattern.

Start by reading the introduction Mongoose::Intro.

Or proceed directly to the Mongoose::Cookbook for many day-to-day recipes.

WARNING

Since version 2.00 Mongoose only support the new MongoDB driver v2.x.x which it's now required.

Please let me know if you find anything strange using this new driver.

METHODS

db

Sets the current MongoDB connection and/or db name.

    Mongoose->db( 'mydb' );

The connection defaults to whatever MongoDB defaults are (typically localhost:27017).

For more control over the connection, db takes the same parameters as MongoDB::MongoClient.

    my $db = Mongoose->db(
        host           => 'mongodb://somehost:27017',
        read_pref_mode => 'secondaryPreferred',
        db_name        => 'mydb',
        username       => 'myuser',
        password       => 'mypass',
        ssl            => 1
    );

This will, in turn, instantiate a MongoDB::MongoClient and return a MongoDB::Database object for mydb.

Important: Mongoose will always defer connecting to Mongo until the last possible moment. This is done to prevent using the MongoDB driver in a forked environment (ie. with a prefork appserver like Starman, Hypnotoad or Catalyst's HTTP::Prefork).

If you prefer to connect while setting the connection string, use one of these options:

    Mongoose->db( db_name=>'mydb', -now=>1 );  # connect now

    # or by waiting for a return value

    my $db = Mongoose->db( 'mydb' );

    # or explicitly:

    Mongoose->db( 'mydb' );
    Mongoose->connect;

You can separate your classes storage on multiple hosts/databases by calling db() several times:

    # Default host/database (connect now!)
    my $db = Mongoose->db( 'mydb' );

    # Other database for some class (defer connection)
    Mongoose->db( db_name => 'my_other_db', class => 'Log' );

    # Other database on other host for several classes
    Mongoose->db(
        db_name => 'my_remote_db',
        host    => 'mongodb://192.168.1.23:27017',
        class   => [qw/ Author Post /]
    );

There is one more level of abstraction called namespace so you can implement multitenant schemas, with that you can map different database configuration to your clases and your schema will select the ones corresponding to the current namespace. In most of the use cases it will just defalt to the "default" namespace.

    # Default host/database for all loaded classes
    Mongoose->db( 'mydb' );

    # Other database for some classes on a different namespace
    Mongoose->db(
        db_name   => 'other_db',
        class     => [qw/ Category Post /],
        namespace => 'blog_b'
    );

connect

Connects to Mongo using the connection arguments passed to the db method.

connection

Returns a connection to the database for the provided class name or the default connection when no class name is provided.

load_schema

Uses Module::Pluggable to require all modules under a given search path or search dir.

All arguments will be sent to Module::Pluggable's import, except for Mongoose specific ones.

    package main;
    use Mongoose;

    # to load a schema from a namespace path:
    Mongoose->load_schema( search_path=>'MyApp::Schema' );

This method can be used to shorten class names, aliasing them for convenience if you wish:

    Mongoose->load_schema( search_path=>'MyApp::Schema', shorten=>1 );

Will shorten the module name to it's last bit:

    MyApp::Schema::Author->new( ... );

    # becomes

    Author->new( ... );

disconnect

Unsets the Mongoose connection handler/s.

namespace

The current namespace. You will use this in case your schema db's are configured using namespaces as described in db. You can switch the namespace by setting it like:

   Mongoose->namespace('my_namespace');

It defauls to the "default" namespace.

class_config

Keep track of document classes config solving aliasing indirection.

aliased

Keep track of aliasing classes. Useful to retrieve full document class from a shortened one.

COLLECTION NAMING

By default, Mongoose composes the Mongo collection name from your package name by replacing double-colon :: with underscores _, separating camel-case, such as aB with a_b and uppercase with lowercase letters.

This behaviour can be changed by choosing other named method or by setting the collection naming routine with a closure as explained in Mongoose::Role::Naming.

REPOSITORY

Fork me on github: http://github.com/rodrigolive/mongoose

BUGS

This is a WIP. Please report bugs via Github Issue reporting https://github.com/rodrigolive/mongoose/issues. Test cases highly desired and appreciated.

TODO

* Better error control

* Allow query->fields to control which fields get expanded into the object.

* Better documentation.

AUTHOR

    Rodrigo de Oliveira (rodrigolive), C<rodrigolive@gmail.com>

MAINTAINER

    Diego Kuperman (diegok)

CONTRIBUTORS

    Arthur Wolf
    Solli Moreira Honorio (shonorio)
    Michael Gentili (gentili)
    Kang-min Liu (gugod)
    Allan Whiteford (allanwhiteford)
    Kartik Thakore (kthakore)
    David Golden (dagolden)
    Mohammad S Anwar (manwar)

LICENSE

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Mongoose

perl -MCPAN -e shell
install Mongoose