.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MongoDBx::Class 3pm" .TH MongoDBx::Class 3pm "2014-05-13" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MongoDBx::Class \- Flexible ORM for MongoDB databases .SH "VERSION" .IX Header "VERSION" version 1.030002 .SH "SYNOPSIS" .IX Header "SYNOPSIS" Normal usage: .PP .Vb 1 \& use MongoDBx::Class; \& \& # create a new instance of the module and load a model schema \& my $dbx = MongoDBx::Class\->new(namespace => \*(AqMyApp::Model::DB\*(Aq); \& \& # if MongoDBx::Class can\*(Aqt find your model schema (possibly because \& # it exists in some different location), you can do this: \& my $dbx = MongoDBx::Class\->new(namespace => \*(AqMyApp::Model::DB\*(Aq, search_dirs => [\*(Aq/path/to/model/dir\*(Aq]); \& \& # connect to a MongoDB server \& my $conn = $dbx\->connect(host => \*(Aqlocalhost\*(Aq, port => 27017); \& \& # be safe by default \& $conn\->safe(1); # we could\*(Aqve also just passed "safe => 1" to $dbx\->connect() above \& \& # get a MongoDB database \& my $db = $conn\->get_database(\*(Aqmyapp\*(Aq); \& \& # insert a person \& my $person = $db\->get_collection(\*(Aqpeople\*(Aq)\->insert({ name => \*(AqSome Guy\*(Aq, birth_date => \*(Aq1984\-06\-12\*(Aq, _class => \*(AqPerson\*(Aq }); \& \& print "Created person ".$person\->name." (".$person\->id.")\en"; \& \& $person\->update({ name => \*(AqSome Smart Guy\*(Aq }); \& \& $person\->delete; .Ve .PP See MongoDBx::Class::ConnectionPool for simple connection pool usage. .SH "DESCRIPTION" .IX Header "DESCRIPTION" MongoDBx::Class is a flexible object relational mapper (\s-1ORM\s0) for MongoDB databases. Given a schema-like collection of document classes, MongoDBx::Class expands MongoDB objects (hash-refs in Perl) from the database into objects of those document classes, and collapses such objects back to the database. .PP MongoDBx::Class takes advantage of the fact that Perl's MongoDB driver is Moose\-based to extend and tweak the driver's behavior, instead of wrapping it. This means MongoDBx::Class does not define its own syntax, so you simply use it exactly as you would the MongoDB driver directly. That said, MongoDBx::Class adds some sugar that enhances and simplifies the syntax unobtrusively (either use it or don't). Thus, it is relatively easy to convert your current MongoDB applications to MongoDBx::Class. A collection in MongoDBx::Class \f(CW\*(C`isa(\*(AqMongoDB::Collection\*(Aq)\*(C'\fR, a database in MongoDBx::Class \f(CW\*(C`isa(\*(AqMongoDB::Database\*(Aq)\*(C'\fR, etc. .PP As opposed to other ORMs (even non-MongoDB ones), MongoDBx::Class attempts to stay as close as possible to MongoDB's non-schematic nature. While most ORMs enforce using a single collection (or table in the \s-1SQL\s0 world) for every object class, MongoDBx::Class allows you to store documents of different classes in different collections (and even databases). A collection can hold documents of many different classes. Not only that, as MongoDBx::Class is Moose based, you can easily create very flexible schemas by using concepts such as inheritance and roles. For example, say you have a collection called 'people' with documents representing, well, people, but these people can either be teachers or students. Also, students may assume the role \*(L"hall monitor\*(R". With MongoDBx::Class, you can create a common base class, say \*(L"People\*(R", and two more classes that extend it \- \&\*(L"Teacher\*(R" and \*(L"Student\*(R" with attributes that are only relevant to each one. You also create a role called \*(L"HallMonitor\*(R", possibly with some methods of its own. You can save all these \*(L"people documents\*(R" into a single MongoDB collection, and when fetching documents from that collection, they will be properly expanded to their correct classes (though you will have to apply roles yourself \- at least for now). .SS "\s-1COMPARISON WITH OTHER\s0 MongoDB ORMs" .IX Subsection "COMPARISON WITH OTHER MongoDB ORMs" As MongoDB is rather young, there aren't many options out there, though \&\s-1CPAN\s0 has some pretty good ones, and will probably have more as MongoDB popularity rises. .PP The first MongoDB \s-1ORM\s0 in \s-1CPAN\s0 was Mongoose, and while it's a very good \&\s-1ORM,\s0 MongoDBx::Class was mainly written to overcome some limitations of Mongoose. The biggest of these limitations is that in order to provide a more comfortable syntax than MongoDB's native syntax, Mongoose makes the unfortunate decision of being implemented as a singleton, meaning only one instance of a Mongoose-based schema can be used in an application. That essentially kills multithreaded applications. Say you have a Plack\-based (doesn't have to be Plack-based though) web application deployed via Starman (or any other web server for that matter), which is a pre-forking web server \- you're pretty much doomed. As MongoDB's driver states, it doesn't support connection pooling, so every fork has to have its own connection to the MongoDB server. Mongoose being a singleton means your threads will not have a connection to the server, and you're screwed. MongoDBx::Class does not suffer this limitation. You can start as many connections as you like. If you're running in a pre-forking environment, you don't have to worry about it at all. .PP Other differences from Mongoose include: .IP "\(bu" 4 Mongoose creates its own syntax, MongoDBx::Class doesn't, you use MongoDB's syntax directly. .IP "\(bu" 4 A document class in Mongoose is connected to a single collection only, and a collection can only have documents of that class. MongoDBx::Class doesn't have that limitation. Do what you like. .IP "\(bu" 4 Mongoose has limited support for multiple database usage. With MongoDBx::Class, you can use as many databases as you want. .IP "\(bu" 4 MongoDBx::Class is way faster. While I haven't performed any real benchmarks, an application converted from Mongoose to MongoDBx::Class showed an increase of speed in orders of magnitude. .IP "\(bu" 4 In Mongoose, your document class attributes are expected to be read-write (i.e. \f(CW\*(C`is => \*(Aqrw\*(Aq\*(C'\fR in Moose), otherwise expansion will fail. This is not the case with MongoDBx::Class, your attributes can safely be read-only. .PP Another \s-1ORM\s0 for MongoDB is Mongrel, which doesn't use Moose and is thus lighter (though as MongoDB is already Moose-based, I see no benefit here). It uses Oogly for data validation (while Moose has its own type validation), and seems to define its own syntax as well. Unfortunately, documentation is currently lacking, and I haven't given it a try, so I can't draw specific comparisons here. .PP Even before Mongoose was born, you could use MongoDB as a backend for KiokuDB, by using KiokuDB::Backend::MongoDB. However, KiokuDB is considered a database of its own and uses some conventions which doesn't fit well with MongoDB. Mongoose::Intro already gives a pretty convincing case when and why you should or shouldn't want to use KiokuDB. .SS "\s-1CONNECTION POOLING\s0" .IX Subsection "CONNECTION POOLING" Since version 0.9, \f(CW\*(C`MongoDBx::Class\*(C'\fR provides experimental, simple connection pooling for applications. Take a look at MongoDBx::Class::ConnectionPool for more information. .SS "\s-1CAVEATS AND THINGS TO CONSIDER\s0" .IX Subsection "CAVEATS AND THINGS TO CONSIDER" There are a few caveats and important facts to take note of when using MongoDBx::Class as of today: .IP "\(bu" 4 MongoDBx::Class's flexibility is dependent on its ability to recognize which class a document in a MongoDB collection expands to. Currently, MongoDBx::Class requires every document to have an attribute called \*(L"_class\*(R" that contains the name of the document class to use. This isn't very comfortable, but works. I'm still thinking of ways to expand documents without this. This pretty much means that you will have to perform some preparations to use existing MongoDB database with MongoDBx::Class \- you will have to update every document in the database with the \*(L"_class\*(R" attribute. .IP "\(bu" 4 References (representing joins) are expected to be in the DBRef format, as defined in . If your database references aren't in this format, you'll have to convert them first. .IP "\(bu" 4 The '_id' attribute of all your documents has to be an internally generated MongoDB::OID. This limitation may or may not be lifted in the future. .SS "\s-1TUTORIAL\s0" .IX Subsection "TUTORIAL" To start using MongoDBx::Class, please read MongoDBx::Class::Tutorial. It also contains a list of frequently asked questions. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "namespace" .IX Subsection "namespace" A string representing the namespace of the MongoDB schema used (e.g. \&\f(CW\*(C`MyApp::Schema\*(C'\fR). Your document classes, structurally speaking, should be descendants of this namespace (e.g. \f(CW\*(C`MyApp::Schema::Article\*(C'\fR, \&\f(CW\*(C`MyApp::Schema::Post\*(C'\fR). .SS "search_dirs" .IX Subsection "search_dirs" An array-ref of directories in which to search for the document classes. Not required, useful if for some reason MongoDBx::Class can't find your document classes. .SS "doc_classes" .IX Subsection "doc_classes" A hash-ref of document classes found when loading the schema. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .ie n .SS "new( namespace => $namespace )" .el .SS "new( namespace => \f(CW$namespace\fP )" .IX Subsection "new( namespace => $namespace )" Creates a new instance of this module. Requires the namespace of the database schema to use. The schema will be immediately loaded, but no connection to a MongoDB server is made yet. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" .ie n .SS "connect( %options )" .el .SS "connect( \f(CW%options\fP )" .IX Subsection "connect( %options )" Initiates a new connection to a MongoDB server running on a certain host and listening to a certain port. \f(CW%options\fR is the hash of attributes that can be passed to \f(CW\*(C`new()\*(C'\fR in MongoDB::Connection, plus the 'safe' attribute from MongoDBx::Class::Connection. You're mostly expected to provide the 'host' and 'port' options. If a host is not provided, 'localhost' is used. If a port is not provided, 27017 (MongoDB's default port) is used. Returns a MongoDBx::Class::Connection object. .PP \&\s-1NOTE:\s0 Since version 0.7, the created connection object isn't saved in the top MongoDBx::Class object, but only returned, in order to be more like how connection is made in MongoDB (and to allow multiple connections). This change breaks backwords compatibility. .ie n .SS "pool( [ type => $type, max_conns => $max_conns, params => \e%params, ... ] )" .el .SS "pool( [ type => \f(CW$type\fP, max_conns => \f(CW$max_conns\fP, params => \e%params, ... ] )" .IX Subsection "pool( [ type => $type, max_conns => $max_conns, params => %params, ... ] )" Creates a new connection pool (see MongoDBx::Class::ConnectionPool for more info) and returns it. \f(CW\*(C`type\*(C'\fR is either 'rotated' or 'backup' (the default). \f(CW\*(C`params\*(C'\fR is a hash-ref of parameters that can be passed to \&\f(CW\*(C`MongoDB::Connection\->new()\*(C'\fR when creating connections in the pool. See \*(L"\s-1ATTRIBUTES\*(R"\s0 in MongoDBx::Class::ConnectionPool for a complete list of attributes that can be passed. .SH "INTERNAL METHODS" .IX Header "INTERNAL METHODS" The following methods are only to be used internally. .SS "\s-1\fIBUILD\s0()\fP" .IX Subsection "BUILD()" Automatically called when creating a new instance of this module. This loads the schema and saves a hash-ref of document classes found in the object. Automatic loading courtesy of Module::Pluggable. .SH "AUTHOR" .IX Header "AUTHOR" Ido Perlmuter, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-mongodbx\-class at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc MongoDBx::Class .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" MongoDB, Mongoose, Mongrel, KiokuDB::Backend::MongoDB. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" .IP "\(bu" 4 Rodrigo de Oliveira, author of Mongoose, whose code greatly assisted me in writing MongoDBx::Class. .IP "\(bu" 4 Thomas Mu\*:ller, for adding support for the Transient trait. .IP "\(bu" 4 Dan Dascalescu, for fixing typos and other problems in the documentation. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2010\-2014 Ido Perlmuter. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information.