Mango - Pure-Perl non-blocking I/O MongoDB client
use Mango; my $mango = Mango->new('mongodb://localhost:27017'); # Insert document 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 parallel find (does not work inside a running event loop) my $delay = Mojo::IOLoop->delay; for my $name (qw(sri marty)) { $delay->begin; $mango->db('test')->collection('users')->find({name => $name})->all(sub { my ($cursor, $err, $docs) = @_; $delay->end(@$docs); }); } my @docs = $delay->wait; # Non-blocking parallel find (does work inside a running event loop) my $delay = Mojo::IOLoop->delay(sub { my ($delay, @docs) = @_; ... }); for my $name (qw(sri marty)) { $delay->begin; $mango->db('test')->collection('users')->find({name => $name})->all(sub { my ($cursor, $err, $docs) = @_; $delay->end(@$docs); }); } $delay->wait unless Mojo::IOLoop->is_running;
Mango is a pure-Perl non-blocking I/O MongoDB client, optimized for use with the Mojolicious real-time web framework, and with multiple event loop support.
To learn more about MongoDB you should take a look at the official documentation.
Note that this whole distribution is EXPERIMENTAL and will change without warning!
Many features are still incomplete or missing, so you should wait for a stable 1.0 release before using any of the modules in this distribution in a production environment. Unsafe operations are not supported, so far this is considered a feature.
This is a Mojolicious spin-off project, so we follow the same rules.
Optional modules EV (4.0+), IO::Socket::IP (0.16+) and IO::Socket::SSL (1.75+) are supported transparently through Mojo::IOLoop, and used if 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(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]]);
Server to connect to, defaults to localhost and port 27017.
localhost
27017
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.
0
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(1);
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 $mango = Mango->new; my $mango = Mango->new('mongodb://localhost:3000/mango_test?w=2');
Construct a new Mango object.
my $db = $mango->db; my $db = $mango->db('test');
Get Mango::Database object for database, uses default_db if no name is provided.
default_db
my $reply = $mango->delete($name, $flags, $query);
Perform low level delete operation followed by getLastError command. You can also append a callback to perform operation non-blocking.
delete
getLastError
$mango->delete(($name, $flags, $query) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $reply = $mango->get_more($name, $return, $cursor);
Perform low level get_more operation. You can also append a callback to perform operation non-blocking.
get_more
$mango->get_more(($name, $return, $cursor) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $reply = $mango->insert($name, $flags, @docs);
Perform low level insert operation followed by getLastError command. You can also append a callback to perform operation non-blocking.
insert
$mango->insert(($name, $flags, @docs) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $success = $mango->is_active;
Check if there are still operations in progress.
$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 $reply = $mango->query($name, $flags, $skip, $return, $query, $fields);
Perform low level query operation. You can also append a callback to perform operation non-blocking.
query
$mango->query(($name, $flags, $skip, $return, $query, $fields) => sub { my ($mango, $err, $reply) = @_; ... }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $reply = $mango->update($name, $flags, $query, $update);
Perform low level update operation followed by getLastError command. You can also append a callback to perform operation non-blocking.
update
$mango->update(($name, $flags, $query, $update) => 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 an anonymous donor, thank you!
Sebastian Riedel, sri@cpan.org.
sri@cpan.org
Copyright (C) 2013, 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.
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.