replica_set_connection – Tools for connecting to a MongoDB replica set

Tools for connecting to a MongoDB replica set.

Warning

DEPRECATED: Please use mongo_replica_set_client instead.

See also

High Availability and PyMongo 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=None[, document_class=dict[, tz_aware=False[, **kwargs]]]]])

Create a new connection to a MongoDB replica set.

Warning

DEPRECATED: ReplicaSetConnection is deprecated. Please use MongoReplicaSetClient instead

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.

Note

Instances of ReplicaSetConnection start a background task to monitor the state of the replica set. This allows it to quickly respond to changes in replica set configuration. Before discarding an instance of ReplicaSetConnection make sure you call close() to ensure that the monitor task is cleanly shut down.

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 number of connections each pool will open simultaneously. If this is set, operations will block if there are max_pool_size outstanding connections from the pool. By default the pool size is unlimited.
  • 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:
  • 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 specified network_timeout takes precedence, matching connection.Connection.
  • socketTimeoutMS: (integer or None) How long (in milliseconds) a send or receive on a socket can take before timing out. Defaults to None (no timeout).
  • connectTimeoutMS: (integer or None) How long (in milliseconds) a connection can take to be opened before timing out. Defaults to 20000.
  • waitQueueTimeoutMS: (integer or None) How long (in milliseconds) a thread will wait for a socket from the pool if the pool has no free sockets. Defaults to None (no timeout).
  • waitQueueMultiple: (integer or None) Multiplied by max_pool_size to give the number of threads allowed to wait for a socket at one time. Defaults to None (no waiters).
  • socketKeepAlive: (boolean) Whether to send periodic keep-alive packets on connected sockets. Defaults to False (do not send keep-alive packets).
  • auto_start_request: If True (the default), each thread that accesses this ReplicaSetConnection has a socket allocated to it for each member of the set until the thread calls end_request() or terminates.
  • use_greenlets: if True, use a background Greenlet instead of a background thread to monitor state of replica set. Additionally, start_request() will ensure that the current greenlet uses the same socket for all operations until end_request(). Defaults to False. use_greenlets with ReplicaSetConnection requires Gevent to be installed.
Write Concern options:
  • safe: ReplicaSetConnection disables acknowledgement of write operations. Use safe=True to enable write acknowledgement.
  • w: (integer or string) Write operations will block until they have been replicated to the specified number or tagged set of servers. w=<int> always includes the replica set primary (e.g. w=3 means write to the primary and wait until replicated to two secondaries). Implies safe=True.
  • wtimeout: (integer) Used in conjunction with w. Specify a value in milliseconds to control how long to wait for write propagation to complete. If replication does not complete in the given timeframe, a timeout exception is raised. Implies safe=True.
  • j: If True block until write operations have been committed to the journal. Cannot be used in combination with fsync. Prior to MongoDB 2.6 this option was ignored if the server was running without journaling. Starting with MongoDB 2.6 write operations will fail with an exception if this option is used when the server is running without journaling. Implies safe=True.
  • fsync: If True and the server is running without journaling, blocks until the server has synced all data files to disk. If the server is running with journaling, this acts the same as the j option, blocking until write operations have been committed to the journal. Cannot be used in combination with j. Implies safe=True.
Read preference options:
  • slave_okay or slaveOk (deprecated): Use read_preference instead.
  • read_preference: The read preference for this connection. See ReadPreference for available options. Defaults to PRIMARY.
  • tag_sets: Read from replica-set members with these tags. To specify a priority-order for tag sets, provide a list of tag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tag set, {}, means “read from any member that matches the mode, ignoring tags.” MongoReplicaSetClient tries each set of tags in turn until it finds a set of tags with at least one matching member. Defaults to [{}], meaning “ignore members’ tags.”
  • secondary_acceptable_latency_ms: (integer) Any replica-set member whose ping time is within secondary_acceptable_latency_ms of the nearest member may accept reads. Default 15 milliseconds. Ignored by mongos and must be configured on the command line. See the localThreshold option for more information.
SSL configuration:
  • ssl: If True, create the connection to the servers using SSL. Defaults to False.
  • ssl_keyfile: The private keyfile used to identify the local connection against mongod. If included with the certfile` then only the ``ssl_certfile is needed. Implies ssl=True. Defaults to None.
  • ssl_certfile: The certificate file used to identify the local connection against mongod. Implies ssl=True. Defaults to None.
  • ssl_cert_reqs: Specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided. It must be one of the three values ssl.CERT_NONE (certificates ignored), ssl.CERT_OPTIONAL (not required, but validated if provided), or ssl.CERT_REQUIRED (required and validated). If the value of this parameter is not ssl.CERT_NONE, then the ssl_ca_certs parameter must point to a file of CA certificates. Implies ssl=True. Defaults to ssl.CERT_NONE.
  • ssl_ca_certs: The ca_certs file contains a set of concatenated “certification authority” certificates, which are used to validate certificates passed from the other end of the connection. Implies ssl=True. Defaults to None.

Changed in version 2.5: Added additional ssl options

Changed in version 2.3: Added tag_sets and secondary_acceptable_latency_ms options.

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, unpin all members, and refresh our view of the replica set.

close()

Close this client instance.

This method first terminates the replica set monitor, then disconnects from all members of the replica set. No further operations are permitted on this client.

Warning

This method stops the replica set monitor task. The replica set monitor is required to properly handle replica set configuration changes, including a failure of the primary. Once close() is called this client instance must not be reused.

Changed in version 2.2.1: The close() method now terminates the replica set monitor.

alive()

Return False if there has been an error communicating with the primary, else True.

This method attempts to check the status of the primary with minimal I/O. The current thread / greenlet retrieves a socket from the primary’s connection pool and checks whether calling select on it raises an error. If there are currently no idle sockets, alive() attempts to connect a new socket.

A more certain way to determine primary availability is to ping it:

client.admin.command('ping')
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.

A sequence of (host, port) pairs.

hosts

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

A sequence of (host, port) pairs.

primary

The (host, port) of the current primary of the replica set.

Returns None if there is no primary.

secondaries

The secondary members known to this client.

A sequence of (host, port) pairs.

arbiters

The arbiters known to this client.

A sequence of (host, port) pairs.

is_mongos

If this instance is connected to mongos (always False).

New in version 2.3.

max_pool_size

The maximum number of sockets the pool will open concurrently.

When the pool has reached max_pool_size, operations block waiting for a socket to be returned to the pool. If waitQueueTimeoutMS is set, a blocked operation will raise ConnectionFailure after a timeout. By default waitQueueTimeoutMS is not set.

Warning

SIGNIFICANT BEHAVIOR CHANGE in 2.6. Previously, this parameter would limit only the idle sockets the pool would hold onto, not the number of open sockets. The default has also changed to 100.

Changed in version 2.6.

document_class

Default class to use for documents returned from this client.

tz_aware

Does this client return timezone-aware datetimes?

max_bson_size

Returns the maximum size BSON object the connected primary accepts in bytes. Defaults to 16MB if not connected to a primary.

max_message_size

Returns the maximum message size the connected primary accepts in bytes. Defaults to 32MB if not connected to a primary.

min_wire_version

The minWireVersion reported by the server.

Returns 0 when connected to server versions prior to MongoDB 2.6.

New in version 2.7.

max_wire_version

The maxWireVersion reported by the server.

Returns 0 when connected to server versions prior to MongoDB 2.6.

New in version 2.7.

auto_start_request

DEPRECATED Is auto_start_request enabled?

read_preference

The read preference mode for this instance.

See ReadPreference for available options.

New in version 2.1.

tag_sets

Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc tag has the value "ny". To specify a priority-order for tag sets, provide a list of tag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tag set, {}, means “read from any member that matches the mode, ignoring tags.” ReplicaSetConnection tries each set of tags in turn until it finds a set of tags with at least one matching member.

New in version 2.3.

secondary_acceptable_latency_ms

Any replica-set member whose ping time is within secondary_acceptable_latency_ms of the nearest member may accept reads. Defaults to 15 milliseconds.

See ReadPreference.

New in version 2.3.

Note

secondary_acceptable_latency_ms is ignored when talking to a replica set through a mongos. The equivalent is the localThreshold command line option.

write_concern

The default write concern for this instance.

Supports dict style access for getting/setting write concern options. Valid options include:

  • w: (integer or string) If this is a replica set, write operations will block until they have been replicated to the specified number or tagged set of servers. w=<int> always includes the replica set primary (e.g. w=3 means write to the primary and wait until replicated to two secondaries). Setting w=0 disables write acknowledgement and all other write concern options.
  • wtimeout: (integer) Used in conjunction with w. Specify a value in milliseconds to control how long to wait for write propagation to complete. If replication does not complete in the given timeframe, a timeout exception is raised.
  • j: If True block until write operations have been committed to the journal. Cannot be used in combination with fsync. Prior to MongoDB 2.6 this option was ignored if the server was running without journaling. Starting with MongoDB 2.6 write operations will fail with an exception if this option is used when the server is running without journaling.
  • fsync: If True and the server is running without journaling, blocks until the server has synced all data files to disk. If the server is running with journaling, this acts the same as the j option, blocking until write operations have been committed to the journal. Cannot be used in combination with j.
>>> m = pymongo.MongoClient()
>>> m.write_concern
{}
>>> m.write_concern = {'w': 2, 'wtimeout': 1000}
>>> m.write_concern
{'wtimeout': 1000, 'w': 2}
>>> m.write_concern['j'] = True
>>> m.write_concern
{'wtimeout': 1000, 'j': True, 'w': 2}
>>> m.write_concern = {'j': True}
>>> m.write_concern
{'j': True}
>>> # Disable write acknowledgement and write concern
...
>>> m.write_concern['w'] = 0

Note

Accessing write_concern returns its value (a subclass of dict), not a copy.

Warning

If you are using Connection or ReplicaSetConnection make sure you explicitly set w to 1 (or a greater value) or safe to True. Unlike calling set_lasterror_options(), setting an option in write_concern does not implicitly set safe to True.

safe

DEPRECATED: Use the ‘w’ write_concern option instead.

Use getlasterror with every write operation?

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]]])

DEPRECATED: Copy a database, potentially from another host.

copy_database() will be removed in PyMongo 3.0. See the copy_database examples for alternatives.

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. By default, use SCRAM-SHA-1 with MongoDB 2.8 and later, MONGODB-CR (MongoDB Challenge Response protocol) for older servers.

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
  • mechanism (optional): auth method, ‘MONGODB-CR’ or ‘SCRAM-SHA-1’

See also

The copy_database examples.

New in version 2.8: Deprecated copy_database, and added SCRAM-SHA-1 support.

get_default_database()

Get the database named in the MongoDB connection URI.

>>> uri = 'mongodb://host/my_database'
>>> client = MongoReplicaSetClient(uri)
>>> db = client.get_default_database()
>>> assert db.name == 'my_database'

Useful in scripts where you want to choose which database to use based only on the URI in a configuration file.

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 client’s cursor manager.

Parameters:
  • cursor_id: id of cursor to close
get_lasterror_options()

DEPRECATED: Use write_concern instead.

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

Changed in version 2.4: Deprecated get_lasterror_options.

New in version 2.0.

set_lasterror_options(**kwargs)

DEPRECATED: Use write_concern instead.

Set getlasterror options for this instance.

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

Parameters:
  • **kwargs: Options should be passed as keyword

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

Changed in version 2.4: Deprecated set_lasterror_options.

New in version 2.0.

unset_lasterror_options(*options)

DEPRECATED: Use write_concern instead.

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.

Changed in version 2.4: Deprecated unset_lasterror_options.

New in version 2.0.

Previous topic

pool – Pool module for use with a MongoDB client.

Next topic

son_manipulator – Manipulators that can edit SON documents as they are saved or retrieved

This Page