NAME
MongoDB::Async - Asynchronous Mongo Driver for Perl
ABOUT ASYNC DRIVER
Changes relative to MongoDB:
MongoDB::Async::Pool - pool of persistent connects
Added ->data method to MongoDB::Async::Cursor. Same as ->all, but returns array ref.
dt_type now $MongoDB::Async::BSON::dt_type global variable, not connection object property
inflate_dbrefs now $MongoDB::Async::Cursor::inflate_dbrefs global variable
This module is 20-100% (in single-(coro)threaded test , mulithreaded will be even faster) faster than original MongoDB. See benchmark http://pastebin.com/vFWENzW7 or run benchmark_compare.pl from archive. It might be 1-5% slower than original on many small queries because of overhead to start and get io callback, but usually it faster because of deserealization/cursor optimizations.
This driver NOT ithreads safe
SASL and SSL unsupported (ssl may work in blocking mode, not tested it).
PLEASE DON'T USE documentation of this module and refere to doc of original MongoDB module with corresponding version. Because I'm porting here only features and too lazy to copy-paste docs.
Don't work with this module inside Coro::unblock_sub, it leaks memory. Use separate coro thread to work with database, and if you need callback interface you need to write it yourself.
Please report bugs/suggestions to nyaknyan@gmail.com or cpan's RT.
TODO:
Make async connection - currently it may block for some time while trying to connect to node which is down.
Implement SSL support using normal SSL module object.
May (or may not, not tested it) segfault if intesively trying reconnect to servers under heavy load. Fix it.
Minimize Moose usage, because perl isn't C++ or Java and all this getter/setter shit if just slow.
VERSION
version 0.702.3
SYNOPSIS
use MongoDB::Async;
my $client = MongoDB::Async::MongoClient->new(host => 'localhost', port => 27017);
my $database = $client->get_database( 'foo' );
my $collection = $database->get_collection( 'bar' );
my $id = $collection->insert({ some => 'data' });
my $data = $collection->find_one({ _id => $id });DESCRIPTION
MongoDB is a database access module.
MongoDB (the database) store all strings as UTF-8. Non-UTF-8 strings will be forcibly converted to UTF-8. To convert something from another encoding to UTF-8, you can use Encode:
use Encode;
my $name = decode('cp932', "\x90\xbc\x96\xec\x81\x40\x91\xbe\x98\x59");
my $id = $coll->insert( { name => $name, } );
my $object = $coll->find_one( { name => $name } );Thanks to taronishino for this example.
Notation and Conventions
The following conventions are used in this document:
$client Database client object
$db Database
$coll Collection
undef C<null> values are represented by undefined values in Perl
\@arr Reference to an array passed to methods
\%attr Reference to a hash of attribute values passed to methodsNote that Perl will automatically close and clean up database connections if all references to them are deleted.
Outline Usage
To use MongoDB, first you need to load the MongoDB module:
use strict;
use warnings;
use MongoDB::Async;Then you need to connect to a MongoDB database server. By default, MongoDB listens for connections on port 27017. Unless otherwise noted, this documentation assumes you are running MongoDB locally on the default port.
MongoDB can be started in authentication mode, which requires clients to log in before manipulating data. By default, MongoDB does not start in this mode, so no username or password is required to make a fully functional connection. If you would like to learn more about authentication, see the authenticate method.
To connect to the database, create a new MongoClient object:
my $client = MongoDB::Async::MongoClient->new("host" => "localhost:27017");As this is the default, we can use the equivalent shorthand:
my $client = MongoDB::Async::MongoClient->new;Connecting is relatively expensive, so try not to open superfluous connections.
There is no way to explicitly disconnect from the database. However, the connection will automatically be closed and cleaned up when no references to the MongoDB::Async::MongoClient object exist, which occurs when $client goes out of scope (or earlier if you undefine it with undef).
INTERNALS
Class Hierarchy
The classes are arranged in a hierarchy: you cannot create a MongoDB::Async::Collection instance before you create MongoDB::Async::Database instance, for example. The full hierarchy is:
MongoDB::Async::MongoClient -> MongoDB::Async::Database -> MongoDB::Async::CollectionThis is because MongoDB::Async::Database has a field that is a MongoDB::Async::MongoClient and MongoDB::Async::Collection has a MongoDB::Async::Database field.
When you call a MongoDB::Async::Collection function, it "trickles up" the chain of classes. For example, say we're inserting $doc into the collection bar in the database foo. The calls made look like:
$collection->insert($doc)-
Calls MongoDB::Async::Database's implementation of
insert, passing along the collection name ("foo"). $db->insert($name, $doc)-
Calls MongoDB::Async::MongoClient's implementation of
insert, passing along the fully qualified namespace ("foo.bar"). $client->insert($ns, $doc)-
MongoDB::Async::MongoClient does the actual work and sends a message to the database.
INTRO TO MONGODB
This is the Perl driver for MongoDB, a document-oriented database. This section introduces some of the basic concepts of MongoDB. There's also a "Tutorial" in MongoDB::Async::Tutorial POD that introduces using the driver. For more documentation on MongoDB in general, check out http://www.mongodb.org.
GETTING HELP
If you have any questions, comments, or complaints, you can get through to the developers most dependably via the MongoDB user list: mongodb-user@googlegroups.com. You might be able to get someone quicker through the MongoDB IRC channel, irc.freenode.net#mongodb.
FUNCTIONS
These functions should generally not be used. They are very low level and have nice wrappers in MongoDB::Async::Collection.
write_insert($ns, \@objs)
my ($insert, $ids) = MongoDB::Async::write_insert("foo.bar", [{foo => 1}, {bar => -1}, {baz => 1}]);Creates an insert string to be used by MongoDB::Async::MongoClient::send. The second argument is an array of hashes to insert. To imitate the behavior of MongoDB::Async::Collection::insert, pass a single hash, for example:
my ($insert, $ids) = MongoDB::Async::write_insert("foo.bar", [{foo => 1}]);Passing multiple hashes imitates the behavior of MongoDB::Async::Collection::batch_insert.
This function returns the string and an array of the the _id fields that the inserted hashes will contain.
write_query($ns, $flags, $skip, $limit, $query, $fields?)
my ($query, $info) = MongoDB::Async::write_query('foo.$cmd', 0, 0, -1, {getlasterror => 1});Creates a database query to be used by MongoDB::Async::MongoClient::send. $flags are query flags to use (see MongoDB::Async::Cursor::Flags for possible values). $skip is the number of results to skip, $limit is the number of results to return, $query is the query hash, and $fields is the optional fields to return.
This returns the query string and a hash of information about the query that is used by MongoDB::Async::MongoClient::recv to get the database response to the query.
write_update($ns, $criteria, $obj, $flags)
my ($update) = MongoDB::Async::write_update("foo.bar", {age => {'$lt' => 20}}, {'$set' => {young => true}}, 0);Creates an update that can be used with MongoDB::Async::MongoClient::send. $flags can be 1 for upsert and/or 2 for updating multiple documents.
write_remove($ns, $criteria, $flags)
my ($remove) = MongoDB::Async::write_remove("foo.bar", {name => "joe"}, 0);Creates a remove that can be used with MongoDB::Async::MongoClient::send. $flags can be 1 for removing just one matching document.
read_documents($buffer)
my @documents = MongoDB::Async::read_documents($buffer);Decodes BSON documents from the given buffer.
SEE ALSO
MongoDB main website http://www.mongodb.org/
Core documentation http://www.mongodb.org/display/DOCS/Manual
MongoDB::Async::Tutorial, MongoDB::Async::Examples
AUTHORS
Florian Ragwitz <rafl@debian.org>
Kristina Chodorow <kristina@mongodb.org>
Mike Friedman <mike.friedman@10gen.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2012 by 10gen, Inc..
This is free software, licensed under:
The Apache License, Version 2.0, January 2004