Mango - Pure-Perl non-blocking I/O MongoDB driver
use Mango; # Insert document my $mango = Mango->new('mongodb://localhost:27017'); my $oid = $mango->db('test')->collection('foo')->insert({bar => 'baz'}); # Find document my $doc = $mango->db('test')->collection('foo')->find_one({bar => 'baz'}); say $doc->{bar}; # Update document $mango->db('test')->collection('foo') ->update({bar => 'baz'}, {bar => 'yada'}); # Remove document $mango->db('test')->collection('foo')->remove({bar => 'yada'}); # Insert document with special BSON types use Mango::BSON ':bson'; my $oid = $mango->db('test')->collection('foo') ->insert({data => bson_bin("\x00\x01"), now => bson_time}); # Blocking concurrent find (does not work inside a running event loop) my $delay = Mojo::IOLoop->delay; for my $name (qw(sri marty)) { my $end = $delay->begin(0); $mango->db('test')->collection('users')->find({name => $name})->all(sub { my ($cursor, $err, $docs) = @_; $end->(@$docs); }); } my @docs = $delay->wait; # Non-blocking concurrent find (does work inside a running event loop) my $delay = Mojo::IOLoop->delay(sub { my ($delay, @docs) = @_; ... }); for my $name (qw(sri marty)) { my $end = $delay->begin(0); $mango->db('test')->collection('users')->find({name => $name})->all(sub { my ($cursor, $err, $docs) = @_; $end->(@$docs); }); } $delay->wait unless Mojo::IOLoop->is_running; # Event loops such as AnyEvent are supported through EV use EV; use AnyEvent; my $cv = AE::cv; $mango->db('test')->command(buildInfo => sub { my ($db, $err, $doc) = @_; $cv->send($doc->{version}); }); say $cv->recv;
Mango is a pure-Perl non-blocking I/O MongoDB driver, optimized for use with the Mojolicious real-time web framework, and with multiple event loop support. Since MongoDB is still changing rapidly, only the latest stable version is supported.
To learn more about MongoDB you should take a look at the official documentation, the documentation included in this distribution is no replacement for it.
Note that this whole distribution is EXPERIMENTAL and will change without warning!
Most of the API is not changing much anymore, but you should wait for a stable 1.0 release before using any of the modules in this distribution in a production environment.
Many arguments passed to methods as well as values of attributes get serialized to BSON with Mango::BSON, which provides many helper functions you can use to generate data types that are not available natively in Perl. All connections will be reset automatically if a new process has been forked, this allows multiple processes to share the same Mango object safely.
For better scalability (epoll, kqueue) and to provide IPv6 as well as TLS support, the optional modules EV (4.0+), IO::Socket::IP (0.20+) and IO::Socket::SSL (1.84+) will be used automatically by Mojo::IOLoop if they are installed. Individual features can also be disabled with the MOJO_NO_IPV6 and MOJO_NO_TLS environment variables.
MOJO_NO_IPV6
MOJO_NO_TLS
Mango inherits all events from Mojo::EventEmitter and can emit the following new ones.
$mango->on(connection => sub { my ($mango, $id) = @_; ... });
Emitted when a new connection has been established.
$mango->on(error => sub { my ($mango, $err) = @_; ... });
Emitted if an error occurs that can't be associated with an operation.
$mango->on(error => sub { my ($mango, $err) = @_; say "This looks bad: $err"; });
Mango implements the following attributes.
my $credentials = $mango->credentials; $mango = $mango->credentials([['test', 'sri', 's3cret']]);
Authentication credentials that will be used on every reconnect.
my $name = $mango->default_db; $mango = $mango->default_db('test');
Default database, defaults to admin.
admin
my $hosts = $mango->hosts; $mango = $mango->hosts([['localhost', 3000], ['localhost', 4000]]);
Servers to connect to, defaults to localhost and port 27017.
localhost
27017
my $timeout = $mango->inactivity_timeout; $mango = $mango->inactivity_timeout(15);
Maximum amount of time in seconds a connection can be inactive before getting closed, defaults to 0. Setting the value to 0 will allow connections to be inactive indefinitely.
0
my $loop = $mango->ioloop; $mango = $mango->ioloop(Mojo::IOLoop->new);
Event loop object to use for blocking I/O operations, defaults to a Mojo::IOLoop object.
my $j = $mango->j; $mango = $mango->j(1);
Wait for all operations to have reached the journal, defaults to 0.
my $max = $mango->max_bson_size; $mango = $mango->max_bson_size(16777216);
Maximum size for BSON documents in bytes, defaults to 16777216.
16777216
my $max = $mango->max_connections; $mango = $mango->max_connections(5);
Maximum number of connections to use for non-blocking operations, defaults to 5.
5
my $max = $mango->max_write_batch_size; $mango = $mango->max_write_batch_size(1000); Maximum number of write operations to batch together, defaults to C<1000>.
my $protocol = $mango->protocol; $mango = $mango->protocol(Mango::Protocol->new);
Protocol handler, defaults to a Mango::Protocol object.
my $w = $mango->w; $mango = $mango->w(2);
Wait for all operations to have reached at least this many servers, 1 indicates just primary, 2 indicates primary and at least one secondary, defaults to 1.
1
2
my $timeout = $mango->wtimeout; $mango = $mango->wtimeout(1);
Timeout for write propagation in milliseconds, defaults to 1000.
1000
Mango inherits all methods from Mojo::Base and implements the following new ones.
my $num = $mango->backlog;
Number of queued operations that have not yet been assigned to a connection.
my $db = $mango->db; my $db = $mango->db('test');
Build Mango::Database object for database, uses "default_db" if no name is provided. Note that the reference "mango" in Mango::Database is weakened, so the Mango object needs to be referenced elsewhere as well.
$mango = $mango->from_string('mongodb://sri:s3cret@localhost:3000/test?w=2');
Parse configuration from connection string.
my $reply = $mango->get_more($namespace, $return, $cursor);
Perform low level GET_MORE operation. You can also append a callback to perform operation non-blocking.
GET_MORE
$mango->get_more(($namespace, $return, $cursor) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
$mango->kill_cursors(@ids);
Perform low level KILL_CURSORS operation. You can also append a callback to perform operation non-blocking.
KILL_CURSORS
$mango->kill_cursors(@ids => sub { my ($mango, $err) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $mango = Mango->new; my $mango = Mango->new('mongodb://sri:s3cret@localhost:3000/test?w=2');
Construct a new Mango object and parse connection string with "from_string" if necessary.
my $reply = $mango->query($namespace, $flags, $skip, $return, $query, $fields);
Perform low level QUERY operation. You can also append a callback to perform operation non-blocking.
QUERY
$mango->query(($namespace, $flags, $skip, $return, $query, $fields) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
You can set the MANGO_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.
MANGO_DEBUG
STDERR
MANGO_DEBUG=1
Some of the work on this distribution has been sponsored by Drip Depot, thank you!
Sebastian Riedel, sri@cpan.org.
sri@cpan.org
In alphabetical order:
Andrey Khozov
Colin Cyr
Copyright (C) 2013-2014, Sebastian Riedel.
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.
https://github.com/kraih/mango, Mojolicious::Guides, http://mojolicio.us.
To install Mango, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mango
CPAN shell
perl -MCPAN -e shell install Mango
For more information on module installation, please visit the detailed CPAN module installation guide.