Moose to MongoDB object mapper
Perl Perl 6
Latest commit d79d876 May 17, 2017 @rodrigolive rodrigolive Merge pull request #50 from NickHibma/patch-1
Fix documentation inconsistencies
Failed to load latest commit information.
t Keep dates and bools untouched when collapsing hashrefs Mar 23, 2017
xt/author author test for object and join-deep bug fix text Nov 4, 2012
.gitignore .gitignore file Apr 19, 2015
.perltidyrc relationships Aug 22, 2010
.proverc add -Ilib to tests via prove Sep 1, 2014
.travis.yml Updated travis file and prepare for next release Jul 8, 2016
Changes Keep dates and bools untouched when collapsing hashrefs Mar 23, 2017
INSTALL relationships Aug 22, 2010
README.pod Updated README Mar 12, 2017
dist.ini Fixed MongoDB min driver version on dist.ini Mar 12, 2017



Mongoose - MongoDB document to Moose object mapper


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

package main;
use Mongoose;


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

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

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



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.


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

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



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 wating for a return value

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

# or explicitly:

Mongoose->db( 'mydb' );

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
    db_name => 'my_remote_db',
    host    => 'mongodb://',
    class   => [qw/ Author Post /]


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


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( ... );


Sets/returns the current connection object, of class MongoDB::MongoClient.

Defaults to whatever MongoDB defaults.


Unsets the Mongoose connection handler.


Keep track of document classes config solving aliasing indirection.


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


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 exlained in Mongoose::Role::Naming.


Fork me on github:


This is a WIP, now *beta* quality software.

Report bugs via Github Issue reporting Test cases highly desired and appreciated.


* Better error control

* Finish-up multiple database support

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

* Cleanup internals.

* More tests and use cases.

* Better documentation.




Rodrigo de Oliveira (rodrigolive), C<>


Diego Kuperman (diegok)


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


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