replica_set_connection – Tools for connecting to a MongoDB replica set — PyMongo 2.5 documentation

### Navigation

- index
- modules |
- next |
- previous |
- PyMongo 2.5 documentation »
- API Documentation »
- `pymongo` – Python driver for MongoDB »

# `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=10[, 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 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: 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. socketTimeoutMS: (integer) How long (in milliseconds) a send or receive on a socket can take before timing out. connectTimeoutMS: (integer) How long (in milliseconds) a connection can take to be opened before timing out. 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. 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()`. 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. Ignored if the server is running without journaling. Implies safe=True. fsync: If `True` 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. Read preference options: slave_okay or slaveOk (deprecated): Use read_preference instead. read_preference: The read preference for this connection. See `ReadPreference` for available 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. 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. 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`. ssl_certfile: The certificate file used to identify the local connection against mongod. Implies `ssl=True`. 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`. 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`.

  Changed in version 2.5: Added addtional 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 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. Once called this instance should 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 (its request socket if it’s in a request, or a random idle socket if it’s not in a request) from the primary’s connection pool and checks whether calling select on it raises an error. If there are currently no idle sockets, or if there is no known primary, `alive()` will attempt to actually find and connect to the primary.

    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.

  `hosts`

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

  `primary`

    The current primary of the replica set.

    Returns None if there is no primary.

  `secondaries`

    The secondary members known to this client.

  `arbiters`

    The arbiters known to this client.

  `is_mongos`

    If this instance is connected to mongos (always False)

    New in version 2.3.

  `max_pool_size`

    The maximum number of idle connections kept open in each pool for future use.

    Note

    `max_pool_size` does not cap the number of concurrent connections to a replica set member; there is currently no way to limit the number of connections. `max_pool_size` only limits the number of idle connections kept open when they are returned to a pool.

  `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 4MB in server < 1.7.4. Returns 0 if no primary is available.

  `auto_start_request`

    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.

    > See also

    > Data-Center Awareness

    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. Ignored if the server is running without journaling.
    - fsync: If `True` force the database to fsync all files before returning. When used with j the server awaits the next group commit before returning.

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

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

### Navigation

- index
- modules |
- next |
- previous |
- PyMongo 2.5 documentation »
- API Documentation »
- `pymongo` – Python driver for MongoDB »