MongoDB(3) User Contributed Perl Documentation MongoDB(3)NAMEMongoDB - Mongo Driver for Perl
SYNOPSIS
use MongoDB;
my $connection = MongoDB::Connection->new(host => 'localhost', port => 27017);
my $database = $connection->foo;
my $collection = $database->bar;
my $id = $collection->insert({ some => 'data' });
my $data = $collection->find_one({ _id => $id });
INTRO TO MONGODB
This is the Perl driver for MongoDB, a document-oriented database.
This section introduces some of the basic concepts of MongoDB. There's
also a Tutorial pod that introduces using the driver. For more
documentation on MongoDB in general, check out
<http://www.mongodb.org>.
GETTING HELP
If you have any questions, comments, or complaints, you can get through
to the developers most dependably via the MongoDB user list:
mongodb-user@googlegroups.com. You might be able to get someone
quicker through the MongoDB IRC channel, irc.freenode.net#mongodb.
AUTHORS
Florian Ragwitz <rafl@debian.org>
Kristina Chodorow <kristina@mongodb.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2009 by 10Gen.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
DESCRIPTIONMongoDB is a database access module.
MongoDB (the database) store all strings as UTF-8. Non-UTF-8 strings
will be forcibly converted to UTF-8. To convert something from another
encoding to UTF-8, you can use Encode:
use Encode;
my $name = decode('cp932', "\x90\xbc\x96\xec\x81\x40\x91\xbe\x98\x59");
my $id = $coll->insert( { name => $name, } );
my $object = $coll->find_one( { name => $name } );
Thanks to taronishino for this example.
Notation and Conventions
The following conventions are used in this document:
$conn Database connection
$db Database
$coll Collection
undef NULL values are represented by undefined values in Perl
\@arr Reference to an array passed to methods
\%attr Reference to a hash of attribute values passed to methods
Note that Perl will automatically close and clean up database
connections if all references to them are deleted.
Outline Usage
To use MongoDB, first you need to load the MongoDB module:
use MongoDB;
use strict;
use warnings;
(The "use strict;" and "use warnings;" isn't required, but it's
strongly recommended.)
Then you need to connect to a Mongo database server. By default, Mongo
listens for connections on port 27017. Unless otherwise noted, this
documentation assumes you are running MongoDB locally on the default
port.
Mongo can be started in authentication mode, which requires clients to
log in before manipulating data. By default, Mongo does not start in
this mode, so no username or password is required to make a fully
functional connection. If you would like to learn more about
authentication, see the "authenticate" method.
To connect to the database, create a new MongoDB Connection object:
$conn = MongoDB::Connection->new("host" => "localhost:27017");
As this is the default, we can use the equivalent shorthand:
$conn = MongoDB::Connection->new;
Connecting is relatively expensive, so try not to open superfluous
connections.
There is no way to explicitly disconnect from the database. When $conn
goes out of scope, the connection will automatically be closed and
cleaned up.
INTERNALS
Class Hierarchy
The classes are arranged in a hierarchy: you cannot create a
MongoDB::Collection instance before you create MongoDB::Database
instance, for example. The full hierarchy is:
MongoDB::Connection -> MongoDB::Database -> MongoDB::Collection
This is because MongoDB::Database has a field that is a
MongoDB::Connection and MongoDB::Collection has a MongoDB::Database
field.
When you call a MongoDB::Collection function, it "trickles up" the
chain of classes. For example, say we're inserting $doc into the
collection "bar" in the database "foo". The calls made look like:
"$collection->insert($doc)"
Calls MongoDB::Database's implementation of "insert", passing along
the collection name ("foo").
"$db->insert($name, $doc)"
Calls MongoDB::Connection's implementation of "insert", passing
along the fully qualified namespace ("foo.bar").
"$connection->insert($ns, $doc)"
MongoDB::Connection does the actual work and sends a message to the
database.
FUNCTIONS
These functions should generally not be used. They are very low level
and have nice wrappers in MongoDB::Collection.
write_insert($ns, \@objs)
my ($insert, $ids) = MongoDB::write_insert("foo.bar", [{foo => 1}, {bar => -1}, {baz => 1}]);
Creates an insert string to be used by "MongoDB::Connection::send".
The second argument is an array of hashes to insert. To imitate the
behavior of "MongoDB::Collection::insert", pass a single hash, for
example:
my ($insert, $ids) = MongoDB::write_insert("foo.bar", [{foo => 1}]);
Passing multiple hashes imitates the behavior of
"MongoDB::Collection::batch_insert".
This function returns the string and an array of the the _id fields
that the inserted hashes will contain.
write_query($ns, $flags, $skip, $limit, $query, $fields?)
my ($query, $info) = MongoDB::write_query('foo.$cmd', 0, 0, -1, {getlasterror => 1});
Creates a database query to be used by "MongoDB::Connection::send".
$flags are query flags to use (see "MongoDB::Cursor::Flags" for
possible values). $skip is the number of results to skip, $limit is
the number of results to return, $query is the query hash, and $fields
is the optional fields to return.
This returns the query string and a hash of information about the query
that is used by "MongoDB::Connection::recv" to get the database
response to the query.
write_update($ns, $criteria, $obj, $flags)
my ($update) = MongoDB::write_update("foo.bar", {age => {'$lt' => 20}}, {'$set' => {young => true}}, 0);
Creates an update that can be used with "MongoDB::Connection::send".
$flags can be 1 for upsert and/or 2 for updating multiple documents.
write_remove($ns, $criteria, $flags)
my ($remove) = MongoDB::write_remove("foo.bar", {name => "joe"}, 0);
Creates a remove that can be used with "MongoDB::Connection::send".
$flags can be 1 for removing just one matching document.
read_documents($buffer)
my @documents = MongoDB::read_documents($buffer);
Decodes BSON documents from the given buffer
SEE ALSOMongoDB main website <http://www.mongodb.org/>
Core documentation <http://www.mongodb.org/display/DOCS/Manual>
MongoDB::Tutorial, MongoDB::Examples
perl v5.14.2 2011-09-07 MongoDB(3)
