`MotorDatabase`¶

class motor.motor_tornado.MotorDatabase(client, name, **kwargs)¶

db[collection_name] || db.collection_name

Get the collection_name MotorCollection of MotorDatabase db.

Raises InvalidName if an invalid collection name is used.

add_son_manipulator(manipulator)¶

Add a new son manipulator to this database.

Newly added manipulators will be applied before existing ones.

Parameters:	manipulator: the manipulator to add

coroutine add_user(name, password=None, read_only=None, session=None, callback=None, **kwargs)¶

DEPRECATED: Create user name with password password.

Add a new user with permissions for this Database.

Note

Will change the password if user name already exists.

Note

add_user is deprecated and will be removed in PyMongo 4.0. Starting with MongoDB 2.6 user management is handled with four database commands, createUser, usersInfo, updateUser, and dropUser.

To create a user:

db.command("createUser", "admin", pwd="password", roles=["root"])

To create a read-only user:

db.command("createUser", "user", pwd="password", roles=["read"])

To change a password:

db.command("updateUser", "user", pwd="newpassword")

Or change roles:

db.command("updateUser", "user", roles=["readWrite"])

Parameters:

name: the name of the user to create
password (optional): the password of the user to create. Can not be used with the userSource argument.
read_only (optional): if True the user will be read only
callback (optional): function taking (result, error), executed when operation completes
**kwargs (optional): optional fields for the user document (e.g. userSource, otherDBRoles, or roles). See http://docs.mongodb.org/manual/reference/privilege-documents for more information.
session (optional): a ClientSession.

If a callback is passed, returns None, else returns a Future.

coroutine authenticate(name=None, password=None, source=None, mechanism='DEFAULT', callback=None, **kwargs)¶

DEPRECATED: Authenticate to use this database.

Warning

Starting in MongoDB 3.6, calling authenticate() invalidates all existing cursors. It may also leave logical sessions open on the server for up to 30 minutes until they time out.

Authentication lasts for the life of the underlying client instance, or until logout() is called.

Raises TypeError if (required) name, (optional) password, or (optional) source is not an instance of basestring (str in python 3).

Note

This method authenticates the current connection, and will also cause all new socket connections in the underlying client instance to be authenticated automatically.
Authenticating more than once on the same database with different credentials is not supported. You must call logout() before authenticating with new credentials.
When sharing a client instance between multiple threads, all threads will share the authentication. If you need different authentication profiles for different purposes you must use distinct client instances.

Parameters:

name: the name of the user to authenticate. Optional when mechanism is MONGODB-X509 and the MongoDB server version is >= 3.4.
password (optional): the password of the user to authenticate. Not used with GSSAPI or MONGODB-X509 authentication.
source (optional): the database to authenticate on. If not specified the current database is used.
mechanism (optional): See MECHANISMS for options. By default, use SCRAM-SHA-1 with MongoDB 3.0 and later, MONGODB-CR (MongoDB Challenge Response protocol) for older servers.
authMechanismProperties (optional): Used to specify authentication mechanism specific options. To specify the service name for GSSAPI authentication pass authMechanismProperties=’SERVICE_NAME:<service name>’
callback (optional): function taking (result, error), executed when operation completes

See general MongoDB documentation

authenticate

If a callback is passed, returns None, else returns a Future.

coroutine collection_names(include_system_collections=True, session=None, callback=None)¶

Get a list of all the collection names in this database.

Parameters:	include_system_collections (optional): if `False` list will not include system collections (e.g `system.indexes`) session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine command(command, value=1, check=True, allowable_errors=None, read_preference=Primary(), codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=None), session=None, callback=None, **kwargs)¶

Issue a MongoDB command.

Send command command to the database and return the response. If command is a string then the command {command: value} will be sent. Otherwise, command must be a dict and will be sent as-is.

Additional keyword arguments are added to the final command document before it is sent.

For example, a command like {buildinfo: 1} can be sent using:

result = yield db.command("buildinfo")

For a command where the value matters, like {collstats: collection_name} we can do:

result = yield db.command("collstats", collection_name)

For commands that take additional arguments we can use kwargs. So {filemd5: object_id, root: file_root} becomes:

result = yield db.command("filemd5", object_id, root=file_root)

Parameters:

command: document representing the command to be issued, or the name of the command (for simple commands only).

Note

the order of keys in the command document is significant (the “verb” must come first), so commands which require multiple keys (e.g. findandmodify) should use an instance of SON or a string and kwargs instead of a Python dict.
value (optional): value to use for the command verb when command is passed as a string
check (optional): check the response for errors, raising OperationFailure if there are any
allowable_errors: if check is True, error messages in this list will be ignored by error-checking
read_preference: The read preference for this operation. See read_preferences for options.
session (optional): a ClientSession, created with start_session().
callback (optional): function taking (result, error), executed when operation completes
**kwargs (optional): additional keyword arguments will be added to the command document before it is sent

Changed in version 1.2: Added session parameter.

See general MongoDB documentation

commands

If a callback is passed, returns None, else returns a Future.

coroutine create_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None, session=None, callback=None, **kwargs)¶

Create a new Collection in this database.

Normally collection creation is automatic. This method should only be used to specify options on creation. CollectionInvalid will be raised if the collection already exists.

Options should be passed as keyword arguments to this method. Supported options vary with MongoDB release. Some examples include:

“size”: desired initial size for the collection (in bytes). For capped collections this size is the max size of the collection.

“capped”: if True, this is a capped collection

“max”: maximum number of objects if capped (optional)

See the MongoDB documentation for a full list of supported options by server version.

Parameters:

name: the name of the collection to create
codec_options (optional): An instance of CodecOptions. If None (the default) the codec_options of this Database is used.
read_preference (optional): The read preference to use. If None (the default) the read_preference of this Database is used.
write_concern (optional): An instance of WriteConcern. If None (the default) the write_concern of this Database is used.
read_concern (optional): An instance of ReadConcern. If None (the default) the read_concern of this Database is used.
collation (optional): An instance of Collation.
session (optional): a ClientSession.
callback (optional): function taking (result, error), executed when operation completes
**kwargs (optional): additional keyword arguments will be passed as options for the create collection command

If a callback is passed, returns None, else returns a Future.

coroutine current_op(include_all=False, session=None, callback=None)¶

Get information on operations currently running.

Parameters:	include_all (optional): if `True` also list currently idle operations in the result session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine dereference(dbref, session=None, callback=None, **kwargs)¶

Dereference a DBRef, getting the document it points to.

Raises TypeError if dbref is not an instance of DBRef. Returns a document, or None if the reference does not point to a valid document. Raises ValueError if dbref has a database specified that is different from the current database.

Parameters:	dbref: the reference session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes **kwargs (optional): any additional keyword arguments are the same as the arguments to `find()`.

If a callback is passed, returns None, else returns a Future.

coroutine drop_collection(name_or_collection, session=None, callback=None)¶

Drop a collection.

Parameters:	name_or_collection: the name of a collection to drop or the collection object itself session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

Note

The write_concern of this database is automatically applied to this operation when using MongoDB >= 3.4.

If a callback is passed, returns None, else returns a Future.

coroutine error(callback=None)¶

OBSOLETE

Parameters :	`callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine eval(code, callback=None, *args)¶

DEPRECATED: Evaluate a JavaScript expression in MongoDB.

Parameters:	code: string representation of JavaScript code to be evaluated args (optional): additional positional arguments are passed to the code being evaluated `callback` (optional): function taking (result, error), executed when operation completes

Warning

the eval command is deprecated in MongoDB 3.0 and will be removed in a future server version.

If a callback is passed, returns None, else returns a Future.

get_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None)¶

Get a Collection with the given name and options.

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

>>> db.read_preference
Primary()
>>> coll1 = db.test
>>> coll1.read_preference
Primary()
>>> from pymongo import ReadPreference
>>> coll2 = db.get_collection(
...     'test', read_preference=ReadPreference.SECONDARY)
>>> coll2.read_preference
Secondary(tag_sets=None)

Parameters:

name: The name of the collection - a string.
codec_options (optional): An instance of CodecOptions. If None (the default) the codec_options of this Database is used.
read_preference (optional): The read preference to use. If None (the default) the read_preference of this Database is used. See read_preferences for options.
write_concern (optional): An instance of WriteConcern. If None (the default) the write_concern of this Database is used.
read_concern (optional): An instance of ReadConcern. If None (the default) the read_concern of this Database is used.

coroutine last_status(callback=None)¶

OBSOLETE

Parameters :	`callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine list_collection_names(session=None, callback=None)¶

Get a list of all the collection names in this database.

Parameters:	session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine list_collections(session=None, callback=None, **kwargs)¶

Get a cursor over the collectons of this database.

Parameters:	session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes **kwargs (optional): Optional parameters of the listCollections command can be passed as keyword arguments to this method. The supported options differ by server version.
Returns:	An instance of `CommandCursor`.

If a callback is passed, returns None, else returns a Future.

coroutine logout(callback=None)¶

DEPRECATED: Deauthorize use of this database.

Warning

Starting in MongoDB 3.6, calling logout() invalidates all existing cursors. It may also leave logical sessions open on the server for up to 30 minutes until they time out.

Parameters :	`callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine previous_error(callback=None)¶

OBSOLETE

Parameters :	`callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine profiling_info(session=None, callback=None)¶

Returns a list containing current profiling information.

Parameters:	session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

See general MongoDB documentation

profiling

If a callback is passed, returns None, else returns a Future.

coroutine profiling_level(session=None, callback=None)¶

Get the database’s current profiling level.

Returns one of (OFF, SLOW_ONLY, ALL).

Parameters:	session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

See general MongoDB documentation

profiling

If a callback is passed, returns None, else returns a Future.

coroutine remove_user(name, session=None, callback=None)¶

DEPRECATED: Remove user name from this Database.

User name will no longer have permissions to access this Database.

Note

remove_user is deprecated and will be removed in PyMongo 4.0. Use the dropUser command instead:

db.command("dropUser", "user")

Parameters:	name: the name of the user to remove session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine reset_error_history(callback=None)¶

OBSOLETE

Parameters :	`callback` (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine set_profiling_level(level, slow_ms=None, session=None, callback=None)¶

Set the database’s profiling level.

Parameters:	level: Specifies a profiling level, see list of possible values below. slow_ms: Optionally modify the threshold for the profile to consider a query or operation. Even if the profiler is off queries slower than the slow_ms level will get written to the logs. session (optional): a `ClientSession`. `callback` (optional): function taking (result, error), executed when operation completes

Possible level values:

Level	Setting
`OFF`	Off. No profiling.
`SLOW_ONLY`	On. Only includes slow operations.
`ALL`	On. Includes all operations.

Raises ValueError if level is not one of (OFF, SLOW_ONLY, ALL).

See general MongoDB documentation

profiling

If a callback is passed, returns None, else returns a Future.

coroutine validate_collection(name_or_collection, scandata=False, full=False, session=None, callback=None)¶

Validate a collection.

Returns a dict of validation info. Raises CollectionInvalid if validation fails.

Parameters:

name_or_collection: A Collection object or the name of a collection to validate.
scandata: Do extra checks beyond checking the overall structure of the collection.
full: Have the server do a more thorough scan of the collection. Use with scandata for a thorough scan of the structure of the collection and the individual documents.
session (optional): a ClientSession.
callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

client¶: This MotorDatabase’s MotorClient.

codec_options¶: Read only access to the CodecOptions of this instance.

incoming_copying_manipulators¶: DEPRECATED: All incoming SON copying manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

incoming_manipulators¶: DEPRECATED: All incoming SON manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

name¶: The name of this Database.

outgoing_copying_manipulators¶: DEPRECATED: All outgoing SON copying manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

outgoing_manipulators¶: DEPRECATED: All outgoing SON manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

read_concern¶: Read only access to the ReadConcern of this instance.

New in version 3.2.

read_preference¶: Read only access to the read preference of this instance.

Changed in version 3.0: The read_preference attribute is now read only.

write_concern¶: Read only access to the WriteConcern of this instance.

Changed in version 3.0: The write_concern attribute is now read only.

`MotorDatabase`¶

Previous topic

Next topic

MotorDatabase¶

`MotorDatabase`¶