MongoDB(3pm)

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

NAME

6       MongoDB - Mongo Driver for Perl
7

SYNOPSIS

9           use MongoDB;
10
11           my $connection = MongoDB::Connection->new(host => 'localhost', port => 27017);
12           my $database   = $connection->foo;
13           my $collection = $database->bar;
14           my $id         = $collection->insert({ some => 'data' });
15           my $data       = $collection->find_one({ _id => $id });
16

GETTING HELP

18       If you have any questions, comments, or complaints, you can get through
19       to the developers most dependably via the MongoDB user list:
20       mongodb-user@googlegroups.com.  You might be able to get someone
21       quicker through the MongoDB IRC channel, irc.freenode.net#mongodb.
22

AUTHORS

24         Florian Ragwitz <rafl@debian.org>
25         Kristina Chodorow <kristina@mongodb.org>
26

COPYRIGHT AND LICENSE

28       This software is Copyright (c) 2009 by 10Gen.
29
30       This is free software, licensed under:
31
32         The Apache License, Version 2.0, January 2004
33

DESCRIPTION

35       MongoDB is a database access module.
36
37       MongoDB (the database) store all strings as UTF-8.  Non-UTF-8 strings
38       will be forcibly converted to UTF-8.  To convert something from another
39       encoding to UTF-8, you can use Encode:
40
41           use Encode;
42
43           my $name = decode('cp932', "\x90\xbc\x96\xec\x81\x40\x91\xbe\x98\x59");
44           my $id = $coll->insert( { name => $name, } );
45
46           my $object = $coll->find_one( { name => $name } );
47
48       Thanks to taronishino for this example.
49
50   Notation and Conventions
51       The following conventions are used in this document:
52
53           $conn   Database connection
54           $db     Database
55           $coll   Collection
56           undef   NULL values are represented by undefined values in Perl
57           \@arr   Reference to an array passed to methods
58           \%attr  Reference to a hash of attribute values passed to methods
59
60       Note that Perl will automatically close and clean up database
61       connections if all references to them are deleted.
62
63   Outline Usage
64       To use MongoDB, first you need to load the MongoDB module:
65
66           use MongoDB;
67           use strict;
68           use warnings;
69
70       (The "use strict;" and "use warnings;" isn't required, but it's
71       strongly recommended.)
72
73       Then you need to connect to a Mongo database server.  By default, Mongo
74       listens for connections on port 27017.  Unless otherwise noted, this
75       documentation assumes you are running MongoDB locally on the default
76       port.
77
78       Mongo can be started in authentication mode, which requires clients to
79       log in before manipulating data.  By default, Mongo does not start in
80       this mode, so no username or password is required to make a fully
81       functional connection.  If you would like to learn more about
82       authentication, see the "authenticate" method.
83
84       To connect to the database, create a new MongoDB Connection object:
85
86           $conn = MongoDB::Connection->new("host" => "localhost:27017");
87
88       As this is the default, we can use the equivalent shorthand:
89
90           $conn = MongoDB::Connection->new;
91
92       Connecting is relatively expensive, so try not to open superfluous
93       connections.
94
95       There is no way to explicitly disconnect from the database.  When $conn
96       goes out of scope, the connection will automatically be closed and
97       cleaned up.
98
99   INTERNALS
100       Class Hierarchy
101
102       The classes are arranged in a hierarchy: you cannot create a
103       MongoDB::Collection instance before you create MongoDB::Database
104       instance, for example.  The full hierarchy is:
105
106           MongoDB::Connection -> MongoDB::Database -> MongoDB::Collection
107
108       This is because MongoDB::Database has a field that is a
109       MongoDB::Connection and MongoDB::Collection has a MongoDB::Database
110       field.
111
112       When you call a MongoDB::Collection function, it "trickles up" the
113       chain of classes.  For example, say we're inserting $doc into the
114       collection "bar" in the database "foo".  The calls made look like:
115
116       "$collection->insert($doc)"
117           Calls MongoDB::Database's implementation of "insert", passing along
118           the collection name ("foo").
119
120       "$db->insert($name, $doc)"
121           Calls MongoDB::Connection's implementation of "insert", passing
122           along the fully qualified namespace ("foo.bar").
123
124       "$connection->insert($ns, $doc)"
125           MongoDB::Connection does the actual work and sends a message to the
126           database.
127

FUNCTIONS

129       These functions should generally not be used.  They are very low level
130       and have nice wrappers in MongoDB::Collection.
131
132   write_insert($ns, \@objs)
133           my ($insert, $ids) = MongoDB::write_insert("foo.bar", [{foo => 1}, {bar => -1}, {baz => 1}]);
134
135       Creates an insert string to be used by "MongoDB::Connection::send".
136       The second argument is an array of hashes to insert.  To imitate the
137       behavior of "MongoDB::Collection::insert", pass a single hash, for
138       example:
139
140           my ($insert, $ids) = MongoDB::write_insert("foo.bar", [{foo => 1}]);
141
142       Passing multiple hashes imitates the behavior of
143       "MongoDB::Collection::batch_insert".
144
145       This function returns the string and an array of the the _id fields
146       that the inserted hashes will contain.
147
148   write_query($ns, $flags, $skip, $limit, $query, $fields?)
149           my ($query, $info) = MongoDB::write_query('foo.$cmd', 0, 0, -1, {getlasterror => 1});
150
151       Creates a database query to be used by "MongoDB::Connection::send".
152       $flags are query flags to use (see "MongoDB::Cursor::Flags" for
153       possible values).  $skip is the number of results to skip, $limit is
154       the number of results to return, $query is the query hash, and $fields
155       is the optional fields to return.
156
157       This returns the query string and a hash of information about the query
158       that is used by "MongoDB::Connection::recv" to get the database
159       response to the query.
160
161   write_update($ns, $criteria, $obj, $flags)
162           my ($update) = MongoDB::write_update("foo.bar", {age => {'$lt' => 20}}, {'$set' => {young => true}}, 0);
163
164       Creates an update that can be used with "MongoDB::Connection::send".
165       $flags can be 1 for upsert and/or 2 for updating multiple documents.
166
167   write_remove($ns, $criteria, $flags)
168           my ($remove) = MongoDB::write_remove("foo.bar", {name => "joe"}, 0);
169
170       Creates a remove that can be used with "MongoDB::Connection::send".
171       $flags can be 1 for removing just one matching document.
172
173   read_documents($buffer)
174         my @documents = MongoDB::read_documents($buffer);
175
176       Decodes BSON documents from the given buffer
177