NAME

Mango - Pure-Perl non-blocking I/O MongoDB client

SYNOPSIS

  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;

DESCRIPTION

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.

EVENTS

Mango inherits all events from Mojo::EventEmitter and can emit the following new ones.

error

  $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";
  });

ATTRIBUTES

Mango implements the following attributes.

credentials

  my $credentials = $mango->credentials;
  $mango          = $mango->credentials([['test', 'sri', 's3cret']]);

Authentication credentials that will be used on every reconnect.

default_db

  my $name = $mango->default_db;
  $mango   = $mango->default_db('test');

Default database, defaults to admin.

hosts

  my $hosts = $mango->hosts;
  $mango    = $mango->hosts([['localhost', 3000]]);

Server to connect to, defaults to localhost and port 27017.

ioloop

  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.

j

  my $j  = $mango->j;
  $mango = $mango->j(1);

Wait for all operations to have reached the journal, defaults to 0.

protocol

  my $protocol = $mango->protocol;
  $mango       = $mango->protocol(Mango::Protocol->new);

Protocol handler, defaults to a Mango::Protocol object.

w

  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.

wtimeout

  my $timeout = $mango->wtimeout;
  $mango      = $mango->wtimeout(1);

Timeout for write propagation in milliseconds, defaults to 1000.

METHODS

Mango inherits all methods from Mojo::Base and implements the following new ones.

new

  my $mango = Mango->new;
  my $mango = Mango->new('mongodb://localhost:3000/mango_test?w=2');

Construct a new Mango object.

db

  my $db = $mango->db;
  my $db = $mango->db('test');

Get Mango::Database object for database, uses default_db if no name is provided.

delete

  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.

  $mango->delete(($name, $flags, $query) => sub {
    my ($mango, $err, $reply) = @_;
    ...
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

get_more

  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.

  $mango->get_more(($name, $return, $cursor) => sub {
    my ($mango, $err, $reply) = @_;
    ...
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

insert

  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.

  $mango->insert(($name, $flags, @docs) => sub {
    my ($mango, $err, $reply) = @_;
    ...
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

is_active

  my $success = $mango->is_active;

Check if there are still operations in progress.

kill_cursors

  $mango->kill_cursors(@ids);

Perform low level kill_cursors operation. You can also append a callback to perform operation non-blocking.

    $mango->kill_cursors(@ids => sub {
      my ($mango, $err) = @_;
      ...
    });
    Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

query

  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.

  $mango->query(($name, $flags, $skip, $return, $query, $fields) => sub {
    my ($mango, $err, $reply) = @_;
    ...
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

update

  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.

  $mango->update(($name, $flags, $query, $update) => sub {
    my ($mango, $err, $reply) = @_;
    ...
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

DEBUGGING

You can set the MANGO_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.

  MANGO_DEBUG=1

AUTHOR

Sebastian Riedel, sri@cpan.org.

COPYRIGHT AND LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.