view release on metacpan or  search on metacpan

lib/MongoDBx/Class.pm  view on Meta::CPAN

Another ORM for MongoDB is L<Mongrel>, which doesn't use Moose and is thus
lighter (though as L<MongoDB> is already Moose-based, I see no benefit here).
It uses L<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
L<KiokuDB>, by using L<KiokuDB::Backend::MongoDB>. However, KiokuDB is
considered a database of its own and uses some conventions which doesn't
fit well with MongoDB. L<Mongoose::Intro|Mongoose::Intro/"Why not use KiokuDB?">
already gives a pretty convincing case when and why you should or shouldn't
want to use KiokuDB.

=head2 CONNECTION POOLING

Since version 0.9, C<MongoDBx::Class> provides experimental, simple connection pooling for
applications. Take a look at L<MongoDBx::Class::ConnectionPool> for more
information.

=head2 CAVEATS AND THINGS TO CONSIDER

There are a few caveats and important facts to take note of when using
MongoDBx::Class as of today:

=over

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

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

=item * The '_id' attribute of all your documents has to be an internally
generated L<MongoDB::OID>. This limitation may or may not be lifted in
the future.

=back

=head2 TUTORIAL

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

=head1 ATTRIBUTES

=cut

has 'namespace' => (is => 'ro', isa => 'Str', required => 1);

has 'search_dirs' => (is => 'ro', isa => 'ArrayRef[Str]', default => sub { [] });

has 'doc_classes' => (is => 'ro', isa => 'HashRef', default => sub { {} });

=head2 namespace

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

=head2 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.

=head2 doc_classes

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

=head1 CLASS METHODS

=head2 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.

=head1 OBJECT METHODS

=head2 connect( %options )

Initiates a new connection to a MongoDB server running on a certain host
and listening to a certain port. C<%options> is the hash of attributes
that can be passed to C<new()> in L<MongoDB::Connection>, plus the 'safe'
attribute from L<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 L<MongoDBx::Class::Connection> object.

NOTE: 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 L<MongoDB> (and to allow multiple connections). This
change breaks backwords compatibility.

=cut

sub connect {
	my ($self, %opts) = @_;

	$opts{namespace} = $self->namespace;
	$opts{doc_classes} = $self->doc_classes;

	return MongoDBx::Class::Connection->new(%opts);
}

=head2 pool( [ type => $type, max_conns => $max_conns, params => \%params, ... ] )

Creates a new connection pool (see L<MongoDBx::Class::ConnectionPool> for
more info) and returns it. C<type> is either 'rotated' or 'backup' (the
default). C<params> is a hash-ref of parameters that can be passed to
C<< MongoDB::Connection->new() >> when creating connections in the pool.