Mango(3pm)

1Mango(3)              User Contributed Perl Documentation             Mango(3)
2
3
4

NAME

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

SYNOPSIS

9         use Mango;
10         use feature state;
11
12         # Declare a Mango helper
13         sub mango { state $m = Mango->new('mongodb://localhost:27017') }
14         # or in a Mojolicious::Lite app
15         helper mango => sub { state $m = Mango->new('mongodb://localhost:27017') };
16
17         # Insert document
18         my $oid   = mango->db('test')->collection('foo')->insert({bar => 'baz'});
19
20         # Find document
21         my $doc = mango->db('test')->collection('foo')->find_one({bar => 'baz'});
22         say $doc->{bar};
23
24         # Update document
25         mango->db('test')->collection('foo')
26           ->update({bar => 'baz'}, {bar => 'yada'});
27
28         # Remove document
29         mango->db('test')->collection('foo')->remove({bar => 'yada'});
30
31         # Insert document with special BSON types
32         use Mango::BSON ':bson';
33         my $oid = mango->db('test')->collection('foo')
34           ->insert({data => bson_bin("\x00\x01"), now => bson_time});
35
36         # Non-blocking concurrent find
37         my $delay = Mojo::IOLoop->delay(sub {
38           my ($delay, @docs) = @_;
39           ...
40         });
41         for my $name (qw(sri marty)) {
42           my $end = $delay->begin(0);
43           mango->db('test')->collection('users')->find({name => $name})->all(sub {
44             my ($cursor, $err, $docs) = @_;
45             $end->(@$docs);
46           });
47         }
48         $delay->wait;
49
50         # Event loops such as AnyEvent are supported through EV
51         use EV;
52         use AnyEvent;
53         my $cv = AE::cv;
54         mango->db('test')->command(buildInfo => sub {
55           my ($db, $err, $doc) = @_;
56           $cv->send($doc->{version});
57         });
58         say $cv->recv;
59

DESCRIPTION

61       Mango is a pure-Perl non-blocking I/O MongoDB driver, optimized for use
62       with the Mojolicious real-time web framework, and with multiple event
63       loop support. Since MongoDB is still changing rapidly, only the latest
64       stable version is supported.
65
66       For MongoDB 2.6 support, use Mango 1.16.
67
68       To learn more about MongoDB you should take a look at the official
69       documentation <http://docs.mongodb.org>, the documentation included in
70       this distribution is no replacement for it.
71
72       Look at Mango::Collection for CRUD operations.
73
74       Many arguments passed to methods as well as values of attributes get
75       serialized to BSON with Mango::BSON, which provides many helper
76       functions you can use to generate data types that are not available
77       natively in Perl.  All connections will be reset automatically if a new
78       process has been forked, this allows multiple processes to share the
79       same Mango object safely.
80
81       For better scalability (epoll, kqueue) and to provide IPv6, SOCKS5 as
82       well as TLS support, the optional modules EV (4.0+), IO::Socket::IP
83       (0.20+), IO::Socket::Socks (0.64+) and IO::Socket::SSL (1.84+) will be
84       used automatically if they are installed. Individual features can also
85       be disabled with the "MOJO_NO_IPV6", "MOJO_NO_SOCKS" and "MOJO_NO_TLS"
86       environment variables.
87

EVENTS

89       Mango inherits all events from Mojo::EventEmitter and can emit the
90       following new ones.
91
92   connection
93         $mango->on(connection => sub {
94           my ($mango, $id) = @_;
95           ...
96         });
97
98       Emitted when a new connection has been established.
99

ATTRIBUTES

101       Mango implements the following attributes.
102
103   default_db
104         my $name = $mango->default_db;
105         $mango   = $mango->default_db('test');
106
107       Default database, defaults to "admin".
108
109   hosts
110         my $hosts = $mango->hosts;
111         $mango    = $mango->hosts([['localhost', 3000], ['localhost', 4000]]);
112
113       Servers to connect to, defaults to "localhost" and port 27017.
114
115   inactivity_timeout
116         my $timeout = $mango->inactivity_timeout;
117         $mango      = $mango->inactivity_timeout(15);
118
119       Maximum amount of time in seconds a connection can be inactive before
120       getting closed, defaults to 0. Setting the value to 0 will allow
121       connections to be inactive indefinitely.
122
123   ioloop
124         my $loop = $mango->ioloop;
125         $mango   = $mango->ioloop(Mojo::IOLoop->new);
126
127       Event loop object to use for blocking I/O operations, defaults to a
128       Mojo::IOLoop object.
129
130   j
131         my $j  = $mango->j;
132         $mango = $mango->j(1);
133
134       Wait for all operations to have reached the journal, defaults to 0.
135
136   max_bson_size
137         my $max = $mango->max_bson_size;
138         $mango  = $mango->max_bson_size(16777216);
139
140       Maximum size for BSON documents in bytes, defaults to 16777216 (16MB).
141
142   max_connections
143         my $max = $mango->max_connections;
144         $mango  = $mango->max_connections(5);
145
146       Maximum number of connections to use for non-blocking operations,
147       defaults to 5.
148
149   max_write_batch_size
150         my $max = $mango->max_write_batch_size;
151         $mango  = $mango->max_write_batch_size(1000);
152
153       Maximum number of write operations to batch together, defaults to 1000.
154
155   protocol
156         my $protocol = $mango->protocol;
157         $mango       = $mango->protocol(Mango::Protocol->new);
158
159       Protocol handler, defaults to a Mango::Protocol object.
160
161   w
162         my $w  = $mango->w;
163         $mango = $mango->w(2);
164
165       Wait for all operations to have reached at least this many servers, 1
166       indicates just primary, 2 indicates primary and at least one secondary,
167       defaults to 1.
168
169   wtimeout
170         my $timeout = $mango->wtimeout;
171         $mango      = $mango->wtimeout(1);
172
173       Timeout for write propagation in milliseconds, defaults to 1000.
174

METHODS

176       Mango inherits all methods from Mojo::Base and implements the following
177       new ones.
178
179   backlog
180         my $num = $mango->backlog;
181
182       Number of queued operations that have not yet been assigned to a
183       connection.
184
185   db
186         my $db = $mango->db;
187         my $db = $mango->db('test');
188
189       Build Mango::Database object for database, uses "default_db" if no name
190       is provided. Note that the reference "mango" in Mango::Database is
191       weakened, so the Mango object needs to be referenced elsewhere as well.
192
193   from_string
194         $mango
195           = $mango->from_string('mongodb://sri:s3cret@localhost:3000/test?w=2');
196
197       Parse configuration from connection string.
198
199   get_more
200         my $reply = $mango->get_more($namespace, $return, $cursor);
201
202       Perform low level "GET_MORE" operation. You can also append a callback
203       to perform operation non-blocking.
204
205         $mango->get_more(($namespace, $return, $cursor) => sub {
206           my ($mango, $err, $reply) = @_;
207           ...
208         });
209         Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
210
211   kill_cursors
212         $mango->kill_cursors(@ids);
213
214       Perform low level "KILL_CURSORS" operation. You can also append a
215       callback to perform operation non-blocking.
216
217           $mango->kill_cursors(@ids => sub {
218             my ($mango, $err) = @_;
219             ...
220           });
221           Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
222
223   new
224         my $mango = Mango->new;
225         my $mango = Mango->new('mongodb://sri:s3cret@localhost:3000/test?w=2');
226
227         # Using TLS encryption
228         my $mango = Mango->new('mongodb://127.0.0.1:27017', tls => 1,
229           tls_cert => '/path/to/certificate.pem');
230
231       Construct a new Mango object and parse connection string with
232       "from_string" if necessary.
233
234       Not that is is strongly recommended to build your Mango object inside a
235       helper function like shown in the synopsis. This is because the Mango's
236       object reference inside Mango::Database objects is weakened to avoid
237       memory leaks. This means your Mango instance is quickly going to get
238       undefined after you use the "db" method. So, use a helper to prevent
239       that.
240
241       If a username and password are provided, Mango will try to authenticate
242       using SCRAM-SHA1. Warning: this will require Authen::SCRAM which is not
243       installed by default.
244
245       Any extra arguments given after the connection string will be passed to
246       the "connect" method from Mojo::IOLoop::Client. To connect to a server
247       using TLS, use the options "tls" (boolean), "tls_cert" and optionally
248       "tls_ca".
249
250   query
251         my $reply
252           = $mango->query($namespace, $flags, $skip, $return, $query, $fields);
253
254       Perform low level "QUERY" operation. You can also append a callback to
255       perform operation non-blocking.
256
257         $mango->query(($namespace, $flags, $skip, $return, $query, $fields) => sub {
258           my ($mango, $err, $reply) = @_;
259           ...
260         });
261         Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
262

DEBUGGING

264       You can set the "MANGO_DEBUG" environment variable to get some advanced
265       diagnostics information printed to "STDERR".
266
267         MANGO_DEBUG=1
268

AUTHOR

274       Sebastian Riedel, "sri@cpan.org".
275
276       Current maintainer: Olivier Duclos "odc@cpan.org".
277

CREDITS

279       In alphabetical order:
280
281         alexbyk
282
283         Andrey Khozov
284
285         Colin Cyr
286

COPYRIGHT AND LICENSE

288       Copyright (C) 2013-2014, Sebastian Riedel.
289
290       This program is free software, you can redistribute it and/or modify it
291       under the terms of the Artistic License version 2.0.
292

NAME

SYNOPSIS

DESCRIPTION

EVENTS

ATTRIBUTES

METHODS

DEBUGGING

SPONSORS

AUTHOR

CREDITS

COPYRIGHT AND LICENSE

SEE ALSO