GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MANGO (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



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

  # Non-blocking concurrent find
  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;

  # 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;



DESCRIPTION

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.

For MongoDB 2.6 support, use Mango 1.16.

To learn more about MongoDB you should take a look at the official documentation <http://docs.mongodb.org>, the documentation included in this distribution is no replacement for it.

Look at Mango::Collection for CRUD operations.

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, SOCKS5 as well as TLS support, the optional modules EV (4.0+), IO::Socket::IP (0.20+), IO::Socket::Socks (0.64+) and IO::Socket::SSL (1.84+) will be used automatically if they are installed. Individual features can also be disabled with the MOJO_NO_IPV6, MOJO_NO_SOCKS and MOJO_NO_TLS environment variables.

EVENTS

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

    connection



  $mango->on(connection => sub {
    my ($mango, $id) = @_;
    ...
  });



Emitted when a new connection has been established.

ATTRIBUTES

Mango implements the following attributes.

    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], [localhost, 4000]]);



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

    inactivity_timeout



  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.

    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.

    max_bson_size



  my $max = $mango->max_bson_size;
  $mango  = $mango->max_bson_size(16777216);



Maximum size for BSON documents in bytes, defaults to 16777216 (16MB).

    max_connections



  my $max = $mango->max_connections;
  $mango  = $mango->max_connections(5);



Maximum number of connections to use for non-blocking operations, defaults to 5.

    max_write_batch_size



  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>.



    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(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.

    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.

    backlog



  my $num = $mango->backlog;



Number of queued operations that have not yet been assigned to a connection.

    db



  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.

    from_string



  $mango
    = $mango->from_string(mongodb://sri:s3cret@localhost:3000/test?w=2);



Parse configuration from connection string.

    get_more



  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.



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



    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;



    new



  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.

If a username and password are provided, Mango will try to authenticate using SCRAM-SHA1. <B>Warning:B> this will require Authen::SCRAM which is not installed by default.

    query



  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.



  $mango->query(($namespace, $flags, $skip, $return, $query, $fields) => 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



SPONSORS

Some of the work on this distribution has been sponsored by Drip Depot <http://www.dripdepot.com>, thank you!

AUTHOR

Sebastian Riedel, sri@cpan.org.

Current maintainer: Olivier Duclos odc@cpan.org.

CREDITS

In alphabetical order:

alexbyk

Andrey Khozov

Colin Cyr

COPYRIGHT AND LICENSE

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.

SEE ALSO

<https://github.com/oliwer/mango>, Mojolicious::Guides, <http://mojolicio.us>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MANGO (3) 2016-02-29

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.