MooseX::Role::MongoDB - Provide MongoDB connections, databases and collections
version 1.000
In your module:
package MyData; use Moose; with 'MooseX::Role::MongoDB'; has database => ( is => 'ro', isa => 'Str', required => 1, ); has client_options => ( is => 'ro', isa => 'HashRef', default => sub { {} }, ); sub _build__mongo_default_database { return $_[0]->database } sub _build__mongo_client_options { return $_[0]->client_options } sub do_stuff { my ($self) = @_; # get "test" database my $db = $self->_mongo_database("test"); # get "books" collection from default database my $books = $self->_mongo_collection("books"); # get "books" collection from another database my $other = $self->_mongo_collection("otherdb" => "books"); # ... do stuff with them }
In your code:
my $obj = MyData->new( database => 'MyDB', client_options => { host => "mongodb://example.net:27017", username => "willywonka", password => "ilovechocolate", }, ); $obj->do_stuff;
This role helps create and manage MongoDB objects. All MongoDB objects will be generated lazily on demand and cached. The role manages a single MongoDB::MongoClient connection, but many MongoDB::Database and MongoDB::Collection objects.
The role also compensates for dropped connections and forks. If these are detected, the object caches are cleared and new connections and objects will be generated in the new process.
Note that a lost connection will not be detectable until after an exception is thrown due to a failed operation.
When using this role, you should not hold onto MongoDB objects for long if there is a chance of your code forking. Instead, request them again each time you need them.
You must provide a private method that returns a logging object. It must implement at least the info and debug methods. MooseX::Role::Logger version 0.002 or later is recommended, but other logging roles may be sufficient.
info
debug
$obj->_mongo_database( $database_name );
Returns a MongoDB::Database. The argument is the database name. With no argument, the default database name is used.
$obj->_mongo_collection( $database_name, $collection_name ); $obj->_mongo_collection( $collection_name );
Returns a MongoDB::Collection. With two arguments, the first argument is the database name and the second is the collection name. With a single argument, the argument is the collection name from the default database name.
$obj->_mongo_clear_caches;
Clears the MongoDB client, database and collection caches. The next request for a database or collection will reconnect to the MongoDB.
The role uses several private attributes to configure itself:
_mongo_client_class — name of the client class
_mongo_client_class
_mongo_client_options — passed to client constructor
_mongo_client_options
_mongo_default_database — default name used if not specified
_mongo_default_database
Each of these have lazy builders that you can override in your class to customize behavior of the role.
The builders are:
_build__mongo_client_class — default is MongoDB::MongoClient
_build__mongo_client_class
MongoDB::MongoClient
_build__mongo_client_options — default is an empty hash reference
_build__mongo_client_options
_build__mongo_default_database — default is the string 'test'
_build__mongo_default_database
You will generally want to at least override _build__mongo_client_options to allow connecting to different hosts. You may want to set it explicitly or you may want to have your own public attribute for users to set (as shown in the "SYNOPSIS"). The choice is up to you.
If a MongoDB host string is provided in the client options hash, any host names will be converted to IP addresses to avoid known bugs using authentication over SSL.
host
Note that the _mongo_default_database is also used as the default database for authentication, unless a db_name is provided to _mongo_client_options.
db_name
Currently, only 'debug' level logs messages are generated for tracing MongoDB interaction activity across forks. See the tests for an example of how to enable it.
Moose
MongoDB
Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/MooseX-Role-MongoDB/issues. You will be notified automatically of any progress on your issue.
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/dagolden/MooseX-Role-MongoDB
git clone https://github.com/dagolden/MooseX-Role-MongoDB.git
David Golden <dagolden@cpan.org>
Alexandr Ciornii <alexchorny@gmail.com>
David Golden <xdg@xdg.me>
Todd Bruner <tbruner@sandia.gov>
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install MooseX::Role::MongoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MooseX::Role::MongoDB
CPAN shell
perl -MCPAN -e shell install MooseX::Role::MongoDB
For more information on module installation, please visit the detailed CPAN module installation guide.