NAME
    MongoDBx::Class - Flexible ORM for MongoDB databases

VERSION
    version 0.5

SYNOPSIS
            use MongoDBx::Class;

            # create a new instance of the module and load a model schema
            my $dbx = MongoDBx::Class->new(namespace => 'MyApp::Model::DB');

            # connect to a MongoDB server
            $dbx->connect(host => 'localhost', port => 27017);

            # be safe by default
            $dbx->conn->safe(1);

            # get a MongoDB database
            my $db = $dbx->conn->get_database('people');

            # insert a person
            my $person = $db->insert({ name => 'Some Guy', birth_date => '1984-06-12', _class => 'Person' });

            print "Created person ".$person->name." (".$person->id.")\n";

            $person->update({ name => 'Some Smart Guy' });

            $person->delete;

DESCRIPTION
    WARNING: THIS IS ALPHA SOFTWARE.

    MongoDBx::Class is a flexible object relational mapper (ORM) 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.

    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
    "isa('MongoDB::Collection')", a database in MongoDBx::Class
    "isa('MongoDB::Database')", etc.

    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 SQL
    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 "hall monitor". With
    MongoDBx::Class, you can create a common base class, say "People", and
    two more classes that extend it - "Teacher" and "Student" with
    attributes that are only relevant to each one. You also create a role
    called "HallMonitor", possibly with some methods of its own. You can
    save all these "people documents" 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).

  COMPARISON WITH OTHER MongoDB ORMs
    As MongoDB is rather young, there aren't many options out there, though
    CPAN has some pretty good ones, and will probably have more as MongoDB
    popularity rises.

    The first MongoDB ORM in CPAN was Mongoose, and while it's a very good
    ORM, 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.

    Other differences from Mongoose include:

    *   Mongoose creates its own syntax, MongoDBx::Class doesn't, you use
        MongoDB's syntax directly.

    *   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.

    *   Mongoose has limited support for multiple database usage. With
        MongoDBx::Class, you can use as many databases as you want.

    *   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.

    *   In Mongoose, your document class attributes are expected to be
        read-write (i.e. "is => 'rw'" in Moose), otherwise expansion will
        fail. This is not the case with MongoDBx::Class, your attributes can
        safely be read-only.

    Another ORM 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.

    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.

  CAVEATS AND THINGS TO CONSIDER
    There are a few caveats and important facts to take note of when using
    MongoDBx::Class as of today:

    *   It's alpha software. This is an early release, and bugs are found
        (and fixed) all the time. Don't rely on it for production use yet.
        You have been warned.

    *   MongoDBx::Class's flexibility is dependant 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 "_class" 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 "_class" attribute.

    *   References (representing joins) are expected to be in the DBRef
        format, as defined in
        <http://www.mongodb.org/display/DOCS/Database+References>. If your
        database references aren't in this format, you'll have to convert
        them first.

    *   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.

  TUTORIAL
    To start using MongoDBx::Class, please read MongoDBx::Class::Tutorial.
    It also contains a list of frequently asked questions.

ATTRIBUTES
  namespace
    A string representing the namespace of the MongoDB schema used (e.g.
    "MyApp::Schema"). Your document classes, structurally speaking, should
    be descendants of this namespace (e.g. "MyApp::Schema::Article",
    "MyApp::Schema::Post").

  conn
    The object's connection to a MongoDB server. This is a
    MongoDBx::Class::Connection object (which extends MongoDB::Connection).
    This is set only after the "connect()" method is called.

  doc_classes
    A hash-ref of document classes found when loading the schema.

CLASS METHODS
  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.

OBJECT METHODS
  connect( [ host => $host, [ port => $port ] ] )
    Initiates a new connection to a MongoDB server running on a certain host
    and listening to a certain port. If a host is not provided, 'localhost'
    is used. If a port is not provided, 27017 (MongoDB's default port) is
    used. The database name is required. The created MongoDBx::Connection
    object is both returned, and also saved in the calling object's 'conn'
    attribute.

INTERNAL METHODS
    The following methods are only to be used internally.

  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.

TODO
    *     Improve the tests.

    *     Make the "isa" option in MongoDBx::Class::Moose's relationship
          types consistent. Either use the full package names or the short
          class names.

    *     Add support for the AnyMongo driver.

    *     Add support for document attributes which are not to be saved in
          the database.

    *     Try to find a way to not require documents to have the _class
          attribute.

AUTHOR
    Ido Perlmuter, "<ido at ido50.net>"

BUGS
    Please report any bugs or feature requests to "bug-mongodbx-class at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MongoDBx-Class>. I will
    be notified, and then you'll automatically be notified of progress on
    your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

            perldoc MongoDBx::Class

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MongoDBx::Class>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/MongoDBx::Class>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/MongoDBx::Class>

    *   Search CPAN

        <http://search.cpan.org/dist/MongoDBx::Class/>

SEE ALSO
    MongoDB, Mongoose, Mongrel, KiokuDB::Backend::MongoDB.

ACKNOWLEDGEMENTS
    Rodrigo de Oliveira, author of Mongoose, whose code greatly assisted me
    in writing MongoDBx::Class.

LICENSE AND COPYRIGHT
    Copyright 2010 Ido Perlmuter.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.

