mongo_client – Tools for connecting to MongoDB — PyMongo 2.5 documentation

### Navigation

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

# `mongo_client` – Tools for connecting to MongoDB

Tools for connecting to MongoDB.

See also

Module `master_slave_connection` for connecting to master-slave clusters, and High Availability and PyMongo for an example of how to connect to a replica set, or specify a list of mongos instances for automatic failover.

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

    >>> from pymongo import MongoClient
    >>> c = MongoClient()
    >>> c.test_database
    Database(MongoClient('localhost', 27017), u'test_database')
    >>> c['test-database']
    Database(MongoClient('localhost', 27017), u'test-database')

class `pymongo.mongo_client.``MongoClient`([host='localhost'[, port=27017[, max_pool_size=10[, document_class=dict[, tz_aware=False[, **kwargs]]]]]])

  Create a new connection to a single MongoDB instance at host:port.

  The resultant client 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 `TypeError` if port is not an instance of `int`. Raises `ConnectionFailure` if the connection cannot be made.

  The host parameter can be a full mongodb URI, in addition to a simple hostname. It can also be a list of hostnames or URIs. Any port specified in the host string(s) will override the port parameter. If multiple mongodb URIs containing database or auth information are passed, the last database, username, and password present will be used. For username and passwords reserved characters like ‘:’, ‘/’, ‘+’ and ‘@’ must be escaped following RFC 2396.

  Parameters : | host (optional): hostname or IP address of the instance to connect to, or a mongodb URI, or a list of hostnames / mongodb URIs. If host is an IPv6 literal it must be enclosed in ‘[‘ and ‘]’ characters following the RFC2732 URL syntax (e.g. ‘[::1]’ for localhost) port (optional): port number on which to connect max_pool_size (optional): The maximum number of idle connections to keep open in the pool for future use document_class (optional): default class to use for documents returned from queries on this client tz_aware (optional): if `True`, `datetime` instances returned as values in a document by this `MongoClient` will be timezone aware (otherwise they will be naive) Other optional parameters can be passed as keyword arguments: 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`, each thread that accesses this `MongoClient` has a socket allocated to it for the thread’s lifetime. This ensures consistent reads, even if you read after an unacknowledged write. Defaults to `False` use_greenlets: If `True`, `start_request()` will ensure that the current greenlet uses the same socket for all operations until `end_request()` Write Concern options: 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). Passing 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. Replica set keyword arguments for connecting with a replica set - either directly or via a mongos: (ignored by standalone mongod instances) replicaSet: (string) The name of the replica set to connect to. The driver will verify that the replica set it connects to matches this name. Implies that the hosts specified are a seed list and the driver should attempt to find all members of the set. Ignored by mongos. read_preference: The read preference for this client. If connecting to a secondary then a read preference mode other than PRIMARY is required - otherwise all queries will throw `AutoReconnect` “not master”. See `ReadPreference` for all available read preference options. tag_sets: Ignored unless connecting to a replica set via mongos. 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. SSL configuration: ssl: If `True`, create the connection to the server 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`.

  See also

  `end_request()`

  See general MongoDB documentation

  connections

  Changed in version 2.5: Added addtional ssl options

  New in version 2.4.

  `disconnect`()

    Disconnect from MongoDB.

    Disconnecting will close all underlying sockets in the connection pool. If this instance is used again it will be automatically re-opened. Care should be taken to make sure that `disconnect()` is not called in the middle of a sequence of operations in which ordering is important. This could lead to unexpected results.

    See also

    `end_request()`

    New in version 1.3.

  `close`()

    Alias for `disconnect()`

    Disconnecting will close all underlying sockets in the connection pool. If this instance is used again it will be automatically re-opened. Care should be taken to make sure that `disconnect()` is not called in the middle of a sequence of operations in which ordering is important. This could lead to unexpected results.

    See also

    `end_request()`

    New in version 2.1.

  `alive`()

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

    This method attempts to check the status of the server with minimal I/O. The current thread / greenlet retrieves a socket from the pool (its request socket if it’s in a request, or a random idle socket if it’s not in a request) and checks whether calling select on it raises an error. If there are currently no idle sockets, `alive()` will attempt to actually connect to the server.

    A more certain way to determine server availability is:

        client.admin.command('ping')

  `c[db_name] || c.db_name`

    Get the db_name `Database` on `MongoClient` c.

    Raises `InvalidName` if an invalid database name is used.

  `host`

    Current connected host.

    Changed in version 1.3: `host` is now a property rather than a method.

  `port`

    Current connected port.

    Changed in version 1.3: `port` is now a property rather than a method.

  `is_primary`

    If this instance is connected to a standalone, a replica set primary, or the master of a master-slave set.

    New in version 2.3.

  `is_mongos`

    If this instance is connected to mongos.

    New in version 2.3.

  `max_pool_size`

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

    Note

    `max_pool_size` does not cap the number of concurrent connections to the server; 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 the pool.

    New in version 1.11.

  `nodes`

    List of all known nodes.

    Includes both nodes specified when this instance was created, as well as nodes discovered through the replica set discovery mechanism.

    New in version 1.8.

  `auto_start_request`

    Is auto_start_request enabled?

  `document_class`

    Default class to use for documents returned from this client.

    New in version 1.7.

  `tz_aware`

    Does this client return timezone-aware datetimes?

    New in version 1.8.

  `max_bson_size`

    Return the maximum size BSON object the connected server accepts in bytes. Defaults to 4MB in server < 1.7.4.

    New in version 1.10.

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

  `is_locked`

    Is this server locked? While locked, all write operations are blocked, although read operations may still be allowed. Use `unlock()` to unlock.

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

    New in version 1.5.

  `server_info`()

    Get information about the MongoDB server we’re connected to.

  `start_request`()

    Ensure the current thread or greenlet always uses the same socket until it calls `end_request()`. This ensures consistent reads, even if you read after an unacknowledged write.

    In Python 2.6 and above, or in Python 2.5 with “from __future__ import with_statement”, `start_request()` can be used as a context manager:

        >>> client = pymongo.MongoClient(auto_start_request=False)
        >>> db = client.test
        >>> _id = db.test_collection.insert({})
        >>> with client.start_request():
        ...     for i in range(100):
        ...         db.test_collection.update({'_id': _id}, {'$set': {'i':i}})
        ...
        ...     # Definitely read the document after the final update completes
        ...     print db.test_collection.find({'_id': _id})

    If a thread or greenlet calls start_request multiple times, an equal number of calls to `end_request()` is required to end the request.

    Changed in version 2.4: Now counts the number of calls to start_request and doesn’t end request until an equal number of calls to end_request.

    New in version 2.2: The `Request` return value. `start_request()` previously returned None

  `end_request`()

    Undo `start_request()`. If `end_request()` is called as many times as `start_request()`, the request is over and this thread’s connection returns to the pool. Extra calls to `end_request()` have no effect.

    Ending a request allows the `socket` that has been reserved for this thread by `start_request()` to be returned to the pool. Other threads will then be able to re-use that `socket`. If your application uses many threads, or has long-running threads that infrequently perform MongoDB operations, then judicious use of this method can lead to performance gains. Care should be taken, however, to make sure that `end_request()` is not called in the middle of a sequence of operations in which ordering is important. This could lead to unexpected results.

  `close_cursor`(cursor_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

  `kill_cursors`(cursor_ids)

    Send a kill cursors message with the given ids.

    Raises `TypeError` if cursor_ids is not an instance of `list`.

    Parameters : | cursor_ids: list of cursor ids to kill

  `set_cursor_manager`(manager_class)

    Set this client’s cursor manager.

    Raises `TypeError` if manager_class is not a subclass of `CursorManager`. A cursor manager handles closing cursors. Different managers can implement different policies in terms of when to actually kill a cursor that has been closed.

    Parameters : | manager_class: cursor manager to use

    Changed in version 2.1+: Deprecated support for external cursor managers.

  `fsync`(**kwargs)

    Flush all pending writes to datafiles.

    Parameters : | Optional parameters can be passed as keyword arguments: lock: If True lock the server to disallow writes. async: If True don’t block while synchronizing. Warning async and lock can not be used together. Warning MongoDB does not support the async option on Windows and will raise an exception on that platform.

    New in version 2.0.

  `unlock`()

    Unlock a previously locked server.

    New in version 2.0.

### Navigation

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