replica_set_connection – Tools for connecting to a MongoDB replica set

Tools for connecting to a MongoDB replica set.

See also

Connecting to a Replica Set for more examples of how to connect to a replica set.

To get a Database instance from a ReplicaSetConnection use either dictionary-style or attribute-style access:

>>> from pymongo import ReplicaSetConnection
>>> c = ReplicaSetConnection('localhost:27017', replicaSet='repl0')
>>> c.test_database
Database(ReplicaSetConnection([u'...', u'...']), u'test_database')
>>> c['test_database']
Database(ReplicaSetConnection([u'...', u'...']), u'test_database')

class pymongo.replica_set_connection.ReplicaSetConnection([hosts_or_uri[, max_pool_size=10[, document_class=dict[, tz_aware=False[, **kwargs]]]]])

Create a new connection to a MongoDB replica set.

The resultant connection object has connection-pooling built in. It also performs auto-reconnection when necessary. If an operation fails because of a connection error, ConnectionFailure is raised. If auto-reconnection will be performed, AutoReconnect will be raised. Application code should handle this exception (recognizing that the operation failed) and then continue to execute.

Raises ConnectionFailure if the connection cannot be made.

The hosts_or_uri parameter can be a full mongodb URI, in addition to a string of host:port pairs (e.g. ‘host1:port1,host2:port2’). If hosts_or_uri is None ‘localhost:27017’ will be used.

Parameters :

• hosts_or_uri (optional): A MongoDB URI or string of host:port pairs. If a host is an IPv6 literal it must be enclosed in ‘[‘ and ‘]’ characters following the RFC2732 URL syntax (e.g. ‘[::1]’ for localhost)
• max_pool_size (optional): The maximum size limit for each connection pool.
• document_class (optional): default class to use for documents returned from queries on this connection
• tz_aware (optional): if True, datetime instances returned as values in a document by this ReplicaSetConnection will be timezone aware (otherwise they will be naive)
• replicaSet: (required) The name of the replica set to connect to. The driver will verify that each host it connects to is a member of this replica set. Can be passed as a keyword argument or as a MongoDB URI option.

Other optional parameters can be passed as keyword arguments:

• safe: Use getlasterror for each write operation?
• j or journal: Block until write operations have been commited to the journal. Ignored if the server is running without journaling. Implies safe=True.
• w: (integer or string) If this is a replica set write operations won’t return until they have been replicated to the specified number or tagged set of servers. Implies safe=True.
• wtimeoutMS: Used in conjunction with j and/or w. Wait this many milliseconds for journal acknowledgement and/or write replication. Implies safe=True.
• fsync: Force the database to fsync all files before returning When used with j the server awaits the next group commit before returning. Implies safe=True.
• socketTimeoutMS: How long a send or receive on a socket can take before timing out.
• connectTimeoutMS: How long a connection can take to be opened before timing out.
• ssl: If True, create the connection to the servers using SSL.
• read_preference: The read preference for this connection. See ReadPreference for available options.
• auto_start_request: If True (the default), each thread that accesses this ReplicaSetConnection has a socket allocated to it for the thread’s lifetime, for each member of the set. For ReadPreference PRIMARY, auto_start_request=True ensures consistent reads, even if you read after an unsafe write. For read preferences other than PRIMARY, there are no consistency guarantees. (The semantics of auto_start_request, ReadPreference, and ReplicaSetConnection may change in future releases of PyMongo.)
• use_greenlets (optional): if True, use a background Greenlet instead of a background thread to monitor state of replica set. start_request() will ensure that the current greenlet uses the same socket for all operations until end_request(). use_greenlets with ReplicaSetConnection requires Gevent to be installed.
• slave_okay or slaveOk (deprecated): Use read_preference instead.
• host: For compatibility with connection.Connection. If both host and hosts_or_uri are specified host takes precedence.
• port: For compatibility with connection.Connection. The default port number to use for hosts.
• network_timeout: For compatibility with connection.Connection. The timeout (in seconds) to use for socket operations - default is no timeout. If both network_timeout and socketTimeoutMS are are specified network_timeout takes precedence, matching connection.Connection.

Changed in version 2.2: Added auto_start_request and use_greenlets options. Added support for host, port, and network_timeout keyword arguments for compatibility with connection.Connection.

New in version 2.1.

disconnect()

Disconnect from the replica set primary.

close()

Disconnect from all set members.

c[db_name] || c.db_name

Get the db_name Database on ReplicaSetConnection c.

Raises InvalidName if an invalid database name is used.

seeds

The seed list used to connect to this replica set.

hosts

All active and passive (priority 0) replica set members known to this connection. This does not include hidden or slaveDelay members, or arbiters.

arbiters

The arbiters known to this connection.

primary

The current primary of the replica set.

Returns None if there is no primary.

secondaries

The secondary members known to this connection.

read_preference

The read preference for this instance.

See ReadPreference for available options.

New in version 2.1.

max_pool_size

The maximum pool size limit set for this connection.

document_class

Default class to use for documents returned on this connection.

tz_aware

Does this connection return timezone-aware datetimes?

safe

Use getlasterror with every write operation?

New in version 2.0.

get_lasterror_options()

Returns a dict of the getlasterror options set on this instance.

New in version 2.0.

set_lasterror_options(**kwargs)

Set getlasterror options for this instance.

Valid options include j=<bool>, w=<int>, wtimeout=<int>, and fsync=<bool>. Implies safe=True.

Parameters :

• **kwargs: Options should be passed as keyword

  arguments (e.g. w=2, fsync=True)

New in version 2.0.

unset_lasterror_options(*options)

Unset getlasterror options for this instance.

If no options are passed unsets all getlasterror options. This does not set safe to False.

Parameters :

• *options: The list of options to unset.

New in version 2.0.

database_names()

Get a list of the names of all databases on the connected server.

drop_database(name_or_database)

Drop a database.

Raises TypeError if name_or_database is not an instance of basestring (str in python 3) or Database

Parameters :

• name_or_database: the name of a database to drop, or a Database instance representing the database to drop

copy_database(from_name, to_name[, from_host=None[, username=None[, password=None]]])

Copy a database, potentially from another host.

Raises TypeError if from_name or to_name is not an instance of basestring (str in python 3). Raises InvalidName if to_name is not a valid database name.

If from_host is None the current host is used as the source. Otherwise the database is copied from from_host.

If the source database requires authentication, username and password must be specified.

Parameters :

• from_name: the name of the source database
• to_name: the name of the target database
• from_host (optional): host name to copy from
• username (optional): username for source database
• password (optional): password for source database

Note

Specifying username and password requires server version >= 1.3.3+.

close_cursor(cursor_id, _conn_id)

Close a single database cursor.

Raises TypeError if cursor_id is not an instance of (int, long). What closing the cursor actually means depends on this connection’s cursor manager.

Parameters :

• cursor_id: id of cursor to close