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=100[, 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 connections that the pool will open simultaneously. If this is set, operations will block if there are max_pool_size outstanding connections from the pool. Defaults to 100. Cannot be 0.
  • 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:
  • maxPoolSize (optional): Alias for max_pool_size. Takes precedence over max_pool_size.
  • 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).
  • connect: if True (the default), immediately connect to MongoDB in the foreground. Otherwise connect on the first operation.
Write Concern options:
(Only set if passed. No default values.)
  • 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. 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.
Replica set keyword arguments for connecting with a replica set - either directly or via a mongos:
(ignored by standalone mongod instances)
  • replicaSet: (string or None) 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. Defaults to None.
  • 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 read_preferences for options. Defaults to ReadPreference.PRIMARY.
  • localThresholdMS: (integer) Used with mongos high availability. Any known mongos whose ping time is within localThresholdMS of the nearest member may be chosen during a failover. 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 server 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.
  • ssl_match_hostname: If True (the default), and ssl_cert_reqs is not ssl.CERT_NONE, enables hostname verification using the match_hostname() function from python’s ssl module. Think very carefully before setting this to False as that could make your application vulnerable to man-in-the-middle attacks.

See also

end_request()

See also

See general MongoDB documentation

connections

Changed in version 2.5: Added additional ssl options

New in version 2.4.

close()

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 close() 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.

c[db_name] || c.db_name

Get the db_name Database on MongoClient c.

Raises InvalidName if an invalid database name is used.

address

(host, port) of the current standalone, primary, or mongos, or None.

New in version 2.9.

host

DEPRECATED Current connected host.

Warning

host is deprecated in this version of PyMongo and removed in PyMongo 3.0. Use address instead.

Changed in version 2.9: Deprecated host.

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

port

DEPRECATED Current connected port.

Warning

port is deprecated in this version of PyMongo and removed in PyMongo 3.0. Use address instead.

Changed in version 2.9: Deprecated 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 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.

New in version 1.11.

nodes

List of all known nodes.

Nodes are either specified when this instance was created, or discovered through the replica set discovery mechanism.

New in version 1.8.

auto_start_request

DEPRECATED Is auto_start_request enabled?

Changed in version 2.8: Deprecated auto_start_request.

use_greenlets

DEPRECATED Whether calling start_request() assigns greenlet-local, rather than thread-local, sockets.

Warning

use_greenlets is deprecated in this version of PyMongo and removed in PyMongo 3. Use Gevent’s monkey.patch_all() instead.

Changed in version 2.9: Deprecated use_greenlets.

New in version 2.4.2.

document_class

DEPRECATED Default class to use for documents returned from this client.

Warning

document_class is deprecated in this version of PyMongo and removed in PyMongo 3. Use CodecOptions with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.9: Deprecated document_class.

New in version 1.7.

tz_aware

DEPRECATED Does this client return timezone-aware datetimes?

Warning

tz_aware is deprecated in this version of PyMongo and removed in PyMongo 3. Use codec_options instead.

Changed in version 2.9: Deprecated tz_aware.

New in version 1.8.

max_bson_size

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

New in version 1.10.

max_message_size

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

New in version 2.6.

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.

codec_options

Read only access to the CodecOptions of this instance.

The value of codec_options can be changed through get_database(), get_collection(), or with_options(),

New in version 2.9.

read_preference

The read preference mode for this instance.

See ReadPreference for available options.

Warning

read_preference is read only in PyMongo 3. Use the read preference classes from read_preferences with get_database(), get_collection(), or with_options() to set read preference. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.9: Deprecated directly setting read_preference.

New in version 2.1.

tag_sets

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

Warning

tag_sets is deprecated in this version of PyMongo and removed in PyMongo 3. Use the read preference classes from read_preferences with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.9: Deprecated tag_sets.

New in version 2.3.

secondary_acceptable_latency_ms

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

Note

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

Warning

secondary_acceptable_latency_ms is deprecated in this version of PyMongo and removed in PyMongo 3. Use the localThresholdMS option with MongoClient or MongoReplicaSetClient instead. See the PyMongo 3 Migration Guide for more information.

Changed in version 2.9: Deprecated secondary_acceptable_latency_ms.

New in version 2.3.

local_threshold_ms

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

New in version 2.9.

write_concern

The default write concern for this instance.

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.

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.

Warning

write_concern is read only in PyMongo 3. Use WriteConcern with get_database(), get_collection(), or with_options() to set write concern. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.9: Deprecated directly setting write_concern.

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

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

Note

mongos does not support copying a database from a server with authentication, see SERVER-6427.

Warning

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

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’

Changed 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 = MongoClient(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.

get_database(name, codec_options=None, read_preference=None, write_concern=None)

Get a Database with the given name and options.

Useful for creating a Database with different codec options, read preference, and/or write concern from this MongoClient.

>>> from pymongo import ReadPreference
>>> client.read_preference == ReadPreference.PRIMARY
True
>>> db1 = client.test
>>> db1.read_preference == ReadPreference.PRIMARY
True
>>> db2 = client.get_database(
...     'test', read_preference=ReadPreference.SECONDARY)
>>> db2.read_preference == ReadPreference.SECONDARY
True
Parameters:

New in version 2.9.

server_info()

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

start_request()

DEPRECATED: start_request is removed in PyMongo 3.0.

When doing w=0 writes to MongoDB 2.4 or earlier, start_request() was sometimes useful to ensure the current thread always used the same socket until it called end_request(). This made consistent reads more likely after an unacknowledged write. Requests are no longer useful in modern MongoDB applications, see PYTHON-785.

Warning

start_request(), in_request(), and end_request() are deprecated, and removed in PyMongo 3. See the PyMongo 3 Migration Guide for more information.

Changed in version 2.8: Deprecated start_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

in_request()

DEPRECATED: True if this thread is in a request, meaning it has a socket reserved for its exclusive use.

Warning

start_request(), in_request(), and end_request() are deprecated in this version of PyMongo and removed in PyMongo 3. See the PyMongo 3 Migration Guide for more information.

Changed in version 2.8: Deprecated in_request.

end_request()

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

Warning

start_request(), in_request(), and end_request() are deprecated in this version of PyMongo and removed in PyMongo 3. See the PyMongo 3 Migration Guide for more information.

Changed in version 2.8: Deprecated end_request.

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.9: Unedprecated.

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.

disconnect()

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

Warning

disconnect() is deprecated in this version of PyMongo and removed in PyMongo 3. Use close() instead.

See also

end_request()

Changed in version 2.9: Deprecated.

New in version 1.3.

alive()

DEPRECATED 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')
uuid_subtype

DEPRECATED This attribute specifies which BSON Binary subtype is used when storing UUIDs. Historically UUIDs have been stored as BSON Binary subtype 3. This attribute is used to switch to the newer BSON Binary subtype 4. It can also be used to force legacy byte order and subtype compatibility with the Java and C# drivers. See the bson.binary module for all options.

Warning

uuid_subtype is deprecated in this version of PyMongo and removed in PyMongo 3. Use CodecOptions with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.9: Deprecated uuid_subtype.

slave_okay

DEPRECATED Use read preference “secondaryPreferred” instead.

Warning

slave_okay is deprecated in this version of PyMongo and removed in PyMongo 3. Use read preference SecondaryPreferred with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.1: Deprecated slave_okay.

New in version 2.0.

safe

DEPRECATED Use getlasterror with every write operation?

Warning

safe is deprecated in this version of PyMongo and removed in PyMongo 3. Use WriteConcern with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.4: Deprecated safe.

New in version 2.0.

get_lasterror_options()

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

Warning

get_lasterror_options() is deprecated in this version of PyMongo and removed in PyMongo 3. Use write_concern instead.

Changed in version 2.4: Deprecated get_lasterror_options.

New in version 2.0.

set_lasterror_options(**kwargs)

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

Warning

set_lasterror_options() is deprecated in this version of PyMongo and removed in PyMongo 3. Use WriteConcern with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.4: Deprecated set_lasterror_options.

New in version 2.0.

unset_lasterror_options(*options)

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

Warning

unset_lasterror_options() is deprecated in this version of PyMongo and removed in PyMongo 3. Use WriteConcern with get_database(), get_collection(), or with_options() instead. See the PyMongo 3 Migration Guide for examples.

Changed in version 2.4: Deprecated unset_lasterror_options.

New in version 2.0.

Previous topic

message – Tools for creating messages to be sent to MongoDB

Next topic

mongo_replica_set_client – Tools for connecting to a MongoDB replica set

This Page