Mongoose - MongoDB document to Moose object mapper
version 0.28
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; my $person = Person->find_one( { name => 'Jack' } ); say $person->name; # Jack my $cursor = Person->find( { name => 'Jack' } ); die "Not found" unless defined $cursor; while ( my $person = $cursor->next ) { say "You're " . $person->name; } $person->delete;
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.
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, plus auth_db_name.
db
auth_db_name
my $db = Mongoose->db( host => 'mongodb://somehost:27017', query_timeout => 60, db_name => 'mydb', auth_db_name => 'admin', username => 'myuser', password => 'mypass', );
This will, in turn, instantiate a MongoDB::MongoClient instance after authenticating user vs admin with all given parameters, and return a MongoDB::Database object for mydb.
admin
mydb
auth_db_name defaults to the value of db_name.
db_name
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' ); 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 /] );
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.
require
All arguments will be sent to Module::Pluggable's import, except for Mongoose specific ones.
import
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( ... );
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.
::
_
aB
a_b
This method let's you change this behaviour, by setting the collection naming routine with a closure.
closure
The closure receives the package name as first parameter and should return the collection name.
# let me change the naming strategy # for my mongo collections # to plain lowercase Mongoose->naming( sub { lc(shift) } ); # if you prefer, use a predefined naming template Mongoose->naming( 'plural' ); # my favorite # or combine them Mongoose->naming( ['decamel','plural' ] ); # same as 'shorties'
Here are the templates available:
template | package name | collection --------------+--------------------------+--------------------------- short | MyApp::Schema::FooBar | foobar plural | MyApp::Schema::FooBar | foobars decamel | MyApp::Schema::FooBar | foo_bar lower | MyApp::Schema::FooBar | myapp::schema::author upper | MyApp::Schema::FooBar | MYAPP::SCHEMA::AUTHOR undercolon | MyApp::Schema::FooBar | myapp_schema_foobar default | MyApp::Schema::FooBar | myapp_schema_foo_bar none | MyApp::Schema::Author | MyApp::Schema::Author
BTW, you can just use the full package name (template none) as a collection in Mongo, as it won't complain about colons in the collection name.
none
Sets/returns the current connection object, of class MongoDB::MongoClient.
Defaults to whatever MongoDB defaults.
Unsets the Mongoose connection handler.
Fork me on github: http://github.com/rodrigolive/mongoose
This is a WIP, now *beta* quality software.
Report bugs via Github Issue reporting https://github.com/rodrigolive/mongoose/issues. 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.
KiokuDB
Rodrigo de Oliveira (rodrigolive), C<rodrigolive@gmail.com>
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.
To install Mongoose, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mongoose
CPAN shell
perl -MCPAN -e shell install Mongoose
For more information on module installation, please visit the detailed CPAN module installation guide.