MongoDB - Mongo Driver for Perl
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 });
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.
Florian Ragwitz <rafl@debian.org> Kristina Chodorow <kristina@mongodb.org>
This software is Copyright (c) 2009 by 10Gen.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
MongoDB 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.
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.
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.)
use strict;
use warnings;
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.
authenticate
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.
$conn
The classes are arranged in a heirarchy: you cannot create a MongoDB::Collection instance before you create MongoDB::Database instance, for example. The full heirarchy 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:
$doc
bar
foo
$collection-
Calls MongoDB::Database's implementation of insert, passing along the collection name ("foo").
insert
$db-
Calls MongoDB::Connection's implementation of insert, passing along the fully qualified namespace ("foo.bar").
$connection-
MongoDB::Connection does the actual work and sends a message to the database.
These functions should generally not be used. They are very low level and have nice wrappers in MongoDB::Collection.
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:
MongoDB::Connection::send
MongoDB::Collection::insert
my ($insert, $ids) = MongoDB::write_insert("foo.bar", [{foo => 1}]);
Passing multiple hashes imitates the behavior of MongoDB::Collection::batch_insert.
MongoDB::Collection::batch_insert
This function returns the string and an array of the the _id fields that the inserted hashes will contain.
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.
$flags
MongoDB::Cursor::Flags
$skip
$limit
$query
$fields
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.
MongoDB::Connection::recv
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.
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.
MongoDB main website http://www.mongodb.org/
Core documentation http://www.mongodb.org/display/DOCS/Manual
MongoDB::Tutorial, MongoDB::Examples
To install MongoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDB
CPAN shell
perl -MCPAN -e shell install MongoDB
For more information on module installation, please visit the detailed CPAN module installation guide.