MongoDB::Connection(3)User Contributed Perl DocumentatioMongoDB::Connection(3)NAMEMongoDB::Connection - A connection to a Mongo server
SYNOPSIS
The MongoDB::Connection class creates a connection to the MongoDB
server.
By default, it connects to a single server running on the local machine
listening on the default port:
# connects to localhost:27017
my $connection = MongoDB::Connection->new;
It can connect to a database server running anywhere, though:
my $connection = MongoDB::Connection->new(host => 'example.com:12345');
See the "host" section for more options for connecting to MongoDB.
Multithreading
Cloning instances of this class is disabled in Perl 5.8.7+, so forked
threads will have to create their own connections to the database.
SEE ALSO
Core documentation on connections:
<http://dochub.mongodb.org/core/connections>.
ATTRIBUTES
host
Server or servers to connect to. Defaults to
"mongodb://localhost:27017".
To connect to more than one database server, use the format:
mongodb://host1[:port1][,host2[:port2],...[,hostN[:portN]]]
An arbitrary number of hosts can be specified.
The connect method will return success if it can connect to at least
one of the hosts listed. If it cannot connect to any hosts, it will
die.
If a port is not specified for a given host, it will default to 27017.
For example, to connecting to "localhost:27017" and "localhost:27018":
$conn = MongoDB::Connection->new("host" => "mongodb://localhost,localhost:27018");
This will succeed if either "localhost:27017" or "localhost:27018" are
available.
The connect method will also try to determine who is master if more
than one server is given. It will try the hosts in order from left to
right. As soon as one of the hosts reports that it is master, the
connect will return success. If no hosts report themselves as masters,
the connect will die, reporting that it could not find a master.
If username and password are given, success is conditional on being
able to log into the database as well as connect. By default, the
driver will attempt to authenticate with the admin database. If a
different database is specified using the "db_name" property, it will
be used instead.
w
Only supported in MongoDB server version 1.5+.
The default number of mongod slaves to replicate a change to before
reporting success for all operations on this collection.
Defaults to 1 (just the current master).
If this is not set, a safe insert will wait for 1 machine (the master)
to ack the operation, then return that it was successful. If the
master has slaves, the slaves may not yet have a record of the
operation when success is reported. Thus, if the master goes down, the
slaves will never get this operation.
To prevent this, you can set "w" to a value greater than 1. If you set
"w" to <N>, it means that safe operations must have succeeded on the
master and "N-1" slaves before the client is notified that the
operation succeeded. If the operation did not succeed or could not be
replicated to "N-1" slaves within the timeout (see "wtimeout" below),
the safe operation will fail (croak).
Some examples of a safe insert with "w" set to 3 and "wtimeout" set to
100:
The master inserts the document, but 100 milliseconds pass before the
slaves have a chance to replicate it. The master returns failure and
the client croaks.
The master inserts the document and two or more slaves replicate the
operation within 100 milliseconds. The safe insert returns success.
The master inserts the document but there is only one slave up. The
safe insert times out and croaks.
wtimeout
The number of milliseconds an operation should wait for "w" slaves to
replicate it.
Defaults to 1000 (1 second).
See "w" above for more information.
auto_reconnect
Boolean indicating whether or not to reconnect if the connection is
interrupted. Defaults to 1.
auto_connect
Boolean indication whether or not to connect automatically on object
construction. Defaults to 1.
timeout
Connection timeout in milliseconds. Defaults to 20000.
username
Username for this connection. Optional. If this and the password
field are set, the connection will attempt to authenticate on
connection/reconnection.
password
Password for this connection. Optional. If this and the username
field are set, the connection will attempt to authenticate on
connection/reconnection.
db_name
Database to authenticate on for this connection. Optional. If this,
the username, and the password fields are set, the connection will
attempt to authenticate against this database on
connection/reconnection. Defaults to "admin".
query_timeout
# set query timeout to 1 second
my $conn = MongoDB::Connection->new(query_timeout => 1000);
# set query timeout to 6 seconds
$conn->query_timeout(6000);
This will cause all queries (including "find_one"s and "run_command"s)
to die after this period if the database has not responded.
This value is in milliseconds and defaults to the value of "timeout" in
MongoDB::Cursor.
$MongoDB::Cursor::timeout = 5000;
# query timeout for $conn will be 5 seconds
my $conn = MongoDB::Connection->new;
A value of -1 will cause the driver to wait forever for responses and 0
will cause it to die immediately.
This value overrides "timeout" in MongoDB::Cursor.
$MongoDB::Cursor::timeout = 1000;
my $conn = MongoDB::Connection->new(query_timeout => 10);
# timeout for $conn is 10 milliseconds
max_bson_size
This is the largest document, in bytes, storable by MongoDB. The driver
queries MongoDB on connection to determine this value. It defaults to
4MB.
find_master
If this is true, the driver will attempt to find a master given the
list of hosts. The master-finding algorithm looks like:
for host in hosts
if host is master
return host
else if host is a replica set member
master := replica set's master
return master
If no master is found, the connection will fail.
If this is not set (or set to the default, 0), the driver will simply
use the first host in the host list for all connections. This can be
useful for directly connecting to slaves for reads.
If you are connecting to a slave, you should check out the "slave_okay"
in MongoDB::Cursor documentation for information on reading from a
slave.
You can use the "ismaster" command to find the members of a replica
set:
my $result = $db->run_command({ismaster => 1});
The primary and secondary hosts are listed in the "hosts" field, the
slaves are in the "passives" field, and arbiters are in the "arbiters"
field.
port [deprecated]
Use "host" instead.
Port to use when connecting. Defaults to 27017.
left_host [deprecated]
Use "host" instead.
Paired connection host to connect to. Can be master or slave.
left_port [deprecated]
Use "host" instead.
Port to use when connecting to left_host. Defaults to 27017.
right_host [deprecated]
Use "host" instead.
Paired connection host to connect to. Can be master or slave.
right_port [deprecated]
Use "host" instead.
Port to use when connecting to right_host. Defaults to 27017.
METHODS
connect
$connection->connect;
Connects to the mongo server. Called automatically on object
construction if "auto_connect" is true.
database_names
my @dbs = $connection->database_names;
Lists all databases on the mongo server.
get_database($name)
my $database = $connection->get_database('foo');
Returns a MongoDB::Database instance for database with the given $name.
get_master
$master = $connection->get_master
Determines which host of a paired connection is master. Does nothing
for a non-paired connection. This need never be invoked by a user, it
is called automatically by internal functions. Returns the index of
the master connection in the list of connections or -1 if it cannot be
determined.
authenticate ($dbname, $username, $password, $is_digest?)
$connection->authenticate('foo', 'username', 'secret');
Attempts to authenticate for use of the $dbname database with $username
and $password. Passwords are expected to be cleartext and will be
automatically hashed before sending over the wire, unless $is_digest is
true, which will assume you already did the hashing on yourself.
See also the core documentation on authentication:
<http://dochub.mongodb.org/core/authentication>.
send($str)
my ($insert, $ids) = MongoDB::write_insert('foo.bar', [{name => "joe", age => 40}]);
$conn->send($insert);
Low-level function to send a string directly to the database. Use
MongoDB::write_insert, MongoDB::write_update, MongoDB::write_remove, or
MongoDB::write_query to create a valid string.
recv(\%info)
my $cursor = $conn->recv({ns => "foo.bar"});
Low-level function to receive a response from the database. Returns a
"MongoDB::Cursor". At the moment, the only required field for $info is
"ns", although "request_id" is likely to be required in the future.
The $info hash will be automatically created for you by
MongoDB::write_query.
AUTHOR
Kristina Chodorow <kristina@mongodb.org>
perl v5.14.2 2011-09-07 MongoDB::Connection(3)
