/ 
MongoDB-0.31
River stage two • 48 direct dependents • 56 total dependents
/ MongoDB::Connection

NAME

MongoDB::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', port => 12345);

It can also be used to connect to a replication pair of database servers:

my $connection = MongoDB::Connection->new(left_host => '192.0.2.0', right_host => '192.0.2.1');

If ports aren't given, they default to 27017.

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 that it succeeded 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. 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.

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.

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".

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.

find_master

$master = $connection->find_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>