MongoDB::Connection - A connection to a Mongo server

MongoDB documentation Contained in the MongoDB distribution.

Index

Code Index:

NAME

Top

MongoDB::Connection - A connection to a Mongo server

SYNOPSIS

Top

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

Top

Core documentation on connections: http://dochub.mongodb.org/core/connections.

ATTRIBUTES

Top

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_ones and run_commands) 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

Top

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

Top

  Kristina Chodorow <kristina@mongodb.org>
MongoDB documentation Contained in the MongoDB distribution. 
#
#  Copyright 2009 10gen, Inc.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#

package MongoDB::Connection;
our $VERSION = '0.43';

# ABSTRACT: A connection to a Mongo server

use MongoDB;
use MongoDB::Cursor;

use Any::Moose;
use Any::Moose 'Util::TypeConstraints';
use Digest::MD5;
use Tie::IxHash;
use boolean;


has host => (
    is       => 'ro',
    isa      => 'Str',
    required => 1,
    default  => 'mongodb://localhost:27017',
);


has w => (
    is      => 'rw',
    isa     => 'Int',
    default => 1,
);


has wtimeout => (
    is      => 'rw',
    isa     => 'Int',
    default => 1000,
);

has port => (
    is       => 'ro',
    isa      => 'Int',
    required => 1,
    default  => 27017,
);

has left_host => (
    is       => 'ro',
    isa      => 'Str',
);

has left_port => (
    is       => 'ro',
    isa      => 'Int',
    default  => 27017,
);

has right_host => (
    is       => 'ro',
    isa      => 'Str',
);

has right_port => (
    is       => 'ro',
    isa      => 'Int',
    default  => 27017,
);


has auto_reconnect => (
    is       => 'ro',
    isa      => 'Bool',
    required => 1,
    default  => 1,
);


has auto_connect => (
    is       => 'ro',
    isa      => 'Bool',
    required => 1,
    default  => 1,
);


has timeout => (
    is       => 'ro',
    isa      => 'Int',
    required => 1,
    default  => 20000,
);


has username => (
    is       => 'rw',
    isa      => 'Str',
    required => 0,
);


has password => (
    is       => 'rw',
    isa      => 'Str',
    required => 0,
);


has db_name => (
    is       => 'rw',
    isa      => 'Str',
    required => 1,
    default  => 'admin',
);


has query_timeout => (
    is       => 'rw',
    isa      => 'Int',
    required => 1,
    default  => sub { return $MongoDB::Cursor::timeout; },
);


has max_bson_size => (
    is       => 'ro',
    isa      => 'Int',
    lazy     => 1,
    builder  => '_get_max_bson_size'
);


has find_master => (
    is       => 'ro',
    isa      => 'Bool',
    required => 1,
    default  => 0,
);

# hash of servers in a set
# call connected() to determine if a connection is enabled
has _servers => (
    is       => 'rw',
    isa      => 'HashRef',
    default => sub { {} },
);

# actual connection to a server in the set
has _master => (
    is       => 'rw',
#    isa      => 'MongoDB::Connection',
    required => 0,
);

has ts => (
    is      => 'rw',
    isa     => 'Int',
    default => 0
);



sub AUTOLOAD {
    my $self = shift @_;
    our $AUTOLOAD;

    my $db = $AUTOLOAD;
    $db =~ s/.*:://;

    return $self->get_database($db);
}

sub BUILD {
    my ($self, $opts) = @_;
    eval "use ${_}" # no Any::Moose::load_class becase the namespaces already have symbols from the xs bootstrap
        for qw/MongoDB::Database MongoDB::Cursor MongoDB::OID MongoDB::Timestamp/;

    my @pairs;

    # deprecated syntax
    if (!($self->host =~ /^mongodb:\/\//)) {
        push @pairs, $self->host.":".$self->port;
    }
    # even more deprecated syntax
    elsif ($self->left_host && $self->right_host) {
        push @pairs, $self->left_host.":".$self->left_port;
        push @pairs, $self->right_host.":".$self->right_port;
    }
    # supported syntax
    else {
        my $str = substr $self->host, 10;
        @pairs = split ",", $str;
    }

    # a simple single server is special-cased (so we don't recurse forever)
    if (@pairs == 1 && !$self->find_master) {
        my @hp = split ":", $pairs[0];

        if (!exists $hp[1]) {
            $hp[1] = 27017;
        }

        $self->_init_conn($hp[0], $hp[1]);
        if ($self->auto_connect) {
            $self->connect;
        }
        return;
    }

    # multiple servers
    my $connected = 0;
    $opts->{find_master} = 0;
    $opts->{auto_connect} = 0;
    foreach (@pairs) {
        $opts->{host} = "mongodb://$_";

        $self->_servers->{$_} = MongoDB::Connection->new($opts);

        next unless $self->auto_connect;

        # it's okay if we can't connect, so long as someone can
        eval {
            $self->_servers->{$_}->connect;
        };

        # at least one connection worked
        if (!$@) {
            $connected = 1;
        }
    }

    my $master;

    if ($self->auto_connect) {

        # if we still aren't connected to anyone, give up
        if (!$connected) {
            die "couldn't connect to any servers listed: ".join(",", @pairs);
        }

        $master = $self->get_master;
        if ($master == -1) {
            die "couldn't find master";
        }
    }
    else {
        # no auto-connect so just pick one. if auto-reconnect is set then it will connect as needed
        ($master) = values %{$self->_servers};
    }

    # create a struct that just points to the master's connection
    $self->_init_conn_holder($master);
}

sub _get_max_bson_size {
    my $self = shift;
    my $buildinfo = $self->get_database('admin')->run_command({buildinfo => 1});
    my $max = $buildinfo->{'maxBsonObjectSize'};
    if ($max) {
        return $max;
    }
    # default: 4MB
    return 4194304;
}


sub database_names {
    my ($self) = @_;
    my $ret = $self->get_database('admin')->run_command({ listDatabases => 1 });
    return map { $_->{name} } @{ $ret->{databases} };
}


sub get_database {
    my ($self, $database_name) = @_;
    return MongoDB::Database->new(
        _connection => $self,
        name        => $database_name,
    );
}

sub _get_a_specific_connection {
    my ($self, $host) = @_;

    if ($self->_servers->{$host}->connected) {
        return $self->_servers->{$host};
    }

    eval {
        $self->_servers->{$host}->connect;
    };

    if (!$@) {
        return $self->_servers->{$host};
    }
    return 0;
}

sub _get_any_connection {
    my ($self) = @_;

    while ((my $key, my $value) = each(%{$self->_servers})) {
        my $conn = $self->_get_a_specific_connection($key);
        if ($conn) {
            return $conn;
        }
    }

    return 0;
}




sub get_master {
    my ($self) = @_;

    # return if the connection is paired the stupid old way
    if (defined $self->left_host && defined $self->right_host) {
        return $self->_old_stupid_paired_conn;
    }

    my $conn = $self->_get_any_connection();
    # if we couldn't connect to anything, just return
    if (!$conn) {
        return -1;
    }

    # a single server or list of servers
    if (!$self->find_master) {
        $self->_master($conn);
        return $self->_master;
    }
    # auto-detect master
    else {
        my $master = $conn->get_database('admin')->run_command({"ismaster" => 1});

        # check for errors
        if (ref($master) eq 'SCALAR') {
            return -1;
        }

        # if this is a replica set & we haven't renewed the host list in 1 sec
        if ($master->{'hosts'} && time() > $self->ts) {
            # update (or set) rs list
            for (@{$master->{'hosts'}}) {
                if (!$self->_servers->{$_}) {
                    $self->_servers->{$_} = MongoDB::Connection->new("host" => "mongodb://$_", auto_connect => 0);
                }
            }
            $self->ts(time());
        }

        # if this is the master, whether or not it's a replica set, return it
        if ($master->{'ismaster'}) {
            $self->_master($conn);
            return $self->_master;
        }
        elsif ($self->find_master && exists $master->{'primary'}) {
            my $primary = $self->_get_a_specific_connection($master->{'primary'});
            if (!$primary) {
                return -1;
            }

            # double-check that this is master
            my $result = $primary->get_database("admin")->run_command({"ismaster" => 1});
            if ($result->{'ismaster'}) {
                $self->_master($primary);
                return $self->_master;
            }
        }
    }

    return -1;
}

sub _old_stupid_paired_conn {
    my $self = shift;

    my ($left, $right, $master);

    # check the left host
    eval {
        $left = MongoDB::Connection->new("host" => $self->left_host, "port" => $self->left_port, timeout => $self->timeout);
    };
    if (!($@ =~ m/couldn't connect to server/)) {
        $master = $left->find_one('admin.$cmd', {ismaster => 1});
        if ($master->{'ismaster'}) {
            return 0;
        }
    }

    # check the right_host
    eval {
        $right = MongoDB::Connection->new("host" => $self->right_host, "port" => $self->right_port, timeout => $self->timeout);
    };
    if (!($@ =~ m/couldn't connect to server/)) {
        $master = $right->find_one('admin.$cmd', {ismaster => 1});
        if ($master->{'ismaster'}) {
            return 1;
        }
    }

    # something went wrong
    return -1;
}


sub authenticate {
    my ($self, $dbname, $username, $password, $is_digest) = @_;
    my $hash = $password;

    # create a hash if the password isn't yet encrypted
    if (!$is_digest) {
        $hash = Digest::MD5::md5_hex("${username}:mongo:${password}");
    }

    # get the nonce
    my $db = $self->get_database($dbname);
    my $result = $db->run_command({getnonce => 1});
    if (!$result->{'ok'}) {
        return $result;
    }

    my $nonce = $result->{'nonce'};
    my $digest = Digest::MD5::md5_hex($nonce.$username.$hash);

    # run the login command
    my $login = tie(my %hash, 'Tie::IxHash');
    %hash = (authenticate => 1,
             user => $username,
             nonce => $nonce,
             key => $digest);
    $result = $db->run_command($login);

    return $result;
}


no Any::Moose;
__PACKAGE__->meta->make_immutable (inline_destructor => 0);

1;