Provided by: libmongodb-perl_0.702.1+ds-1ubuntu1_amd64 
NAME
MongoDB::MongoClient - A connection to a MongoDB server
VERSION
version 0.702.1
SYNOPSIS
The MongoDB::MongoClient class creates a client 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 $client = MongoDB::MongoClient->new;
It can connect to a database server running anywhere, though:
my $client = MongoDB::MongoClient->new(host => 'example.com:12345');
See the "host" section for more options for connecting to MongoDB.
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":
my $client = MongoDB::MongoClient->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 the primary 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 the primary, the connect will return success. If no hosts report
themselves as a primary, the connect will die.
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
The client write concern.
• "-1" Errors ignored. Do not use this.
• 0 Unacknowledged. MongoClient will NOT wait for an acknowledgment that the server has
received and processed the request. Older documentation may refer to this as "fire-
and-forget" mode. You must call "getLastError" manually to check if a request
succeeds. This option is not recommended.
• 1 Acknowledged. This is the default. MongoClient will wait until the primary MongoDB
acknowledges the write.
• 2 Replica acknowledged. MongoClient will wait until at least two replicas (primary and
one secondary) acknowledge the write. You can set a higher number for more replicas.
• "all" All replicas acknowledged.
• "majority" A majority of replicas acknowledged.
In MongoDB v2.0+, you can "tag" replica members. With "tagging" you can specify a new
"getLastErrorMode" where you can create new rules on how your data is replicated. To used
you getLastErrorMode, you pass in the name of the mode to the "w" parameter. For more
infomation see: http://www.mongodb.org/display/DOCS/Data+Center+Awareness
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.
j
If true, awaits the journal commit before returning. If the server is running without
journaling, it returns immediately, and successfully.
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 client connection. Optional. If this and the password field are set,
the client will attempt to authenticate on connection/reconnection.
password
Password for this connection. Optional. If this and the username field are set, the
client 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 client will attempt to authenticate against this database
on connection/reconnection. Defaults to "admin".
query_timeout
# set query timeout to 1 second
my $client = MongoDB::MongoClient->new(query_timeout => 1000);
# set query timeout to 6 seconds
$client->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 $client = MongoDB::MongoClient->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 $client = MongoDB::MongoClient->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 primary given the list of hosts. The
primary-finding algorithm looks like:
for host in hosts
if host is the primary
return host
else if host is a replica set member
primary := replica set's primary
return primary
If no primary 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
secondaries for reads.
If you are connecting to a secondary, you should read "slave_okay" in MongoDB::Cursor.
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.
ssl
This tells the driver that you are connecting to an SSL mongodb instance.
This option will be ignored if the driver was not compiled with the SSL flag. You must
also be using a database server that supports SSL.
The driver must be built as follows for SSL support:
perl Makefile.PL --ssl
make
make install
Alternatively, you can set the "PERL_MONGODB_WITH_SSL" environment variable before
installing:
PERL_MONGODB_WITH_SSL=1 cpan MongoDB
The "libcrypto" and "libssl" libraries are required for SSL support.
sasl
This attribute is experimental.
If set to 1, the driver will attempt to negotiate SASL authentication upon connection. See
"sasl_mechanism" for a list of the currently supported mechanisms. The driver must be
built as follows for SASL support:
perl Makefile.PL --sasl
make
make install
Alternatively, you can set the "PERL_MONGODB_WITH_SASL" environment variable before
installing:
PERL_MONGODB_WITH_SASL=1 cpan MongoDB
The "libgsasl" library is required for SASL support. RedHat/CentOS users can find it in
the EPEL repositories.
Future versions of this driver may switch to Cyrus SASL
<http://www.cyrusimap.org/docs/cyrus-sasl/2.1.25/> in order to be consistent with the
MongoDB server, which now uses Cyrus.
sasl_mechanism
This attribute is experimental.
This specifies the SASL mechanism to use for authentication with a MongoDB server. (See
"sasl".) The default is GSSAPI. The supported SASL mechanisms are:
• "GSSAPI". This is the default. GSSAPI will attempt to authenticate against Kerberos
for MongoDB Enterprise 2.4+. You must run your program from within a "kinit" session
and set the "username" attribute to the Kerberos principal name, e.g.
"user@EXAMPLE.COM".
• "PLAIN". The SASL PLAIN mechanism will attempt to authenticate against LDAP for
MongoDB Enterprise 2.6+. Because the password is not encrypted, you should only use
this mechanism over a secure connection. You must set the "username" and "password"
attributes to your LDAP credentials.
dt_type
Sets the type of object which is returned for DateTime fields. The default is DateTime.
Other acceptable values are DateTime::Tiny and "undef". The latter will give you the raw
epoch value rather than an object.
inflate_dbrefs
Controls whether DBRef <http://docs.mongodb.org/manual/applications/database-
references/#dbref>s are automatically inflated into MongoDB::DBRef objects. Defaults to
true. Set this to 0 if you don't want to auto-inflate them.
METHODS
connect
$client->connect;
Connects to the MongoDB server. Called automatically on object construction if
"auto_connect" is true.
database_names
my @dbs = $client->database_names;
Lists all databases on the MongoDB server.
get_database($name)
my $database = $client->get_database('foo');
Returns a MongoDB::Database instance for the database with the given $name.
get_master
$master = $client->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?)
$client->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://docs.mongodb.org/manual/core/access-control/>.
send($str)
my ($insert, $ids) = MongoDB::write_insert('foo.bar', [{name => "joe", age => 40}]);
$client->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 = $client->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.
fsync(\%args)
$client->fsync();
A function that will forces the server to flush all pending writes to the storage layer.
The fsync operation is synchronous by default, to run fsync asynchronously, use the
following form:
$client->fsync({async => 1});
The primary use of fsync is to lock the database during backup operations. This will flush
all data to the data storage layer and block all write operations until you unlock the
database. Note: you can still read while the database is locked.
$conn->fsync({lock => 1});
fsync_unlock
$conn->fsync_unlock();
Unlocks a database server to allow writes and reverses the operation of a
$conn->fsync({lock => 1}); operation.
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://docs.mongodb.org/manual/reference/connection-string/>.
AUTHORS
• Florian Ragwitz <rafl@debian.org>
• Kristina Chodorow <kristina@mongodb.org>
• Mike Friedman <mike.friedman@10gen.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by 10gen, Inc..
This is free software, licensed under:
The Apache License, Version 2.0, January 2004