database – Database level operations

Database level operations.

pymongo.OFF

No database profiling.

pymongo.SLOW_ONLY

Only profile slow operations.

pymongo.ALL

Profile all operations.

class pymongo.database.Database(connection, name)

Get a database by connection and name.

Raises TypeError if name is not an instance of basestring. Raises InvalidName if name is not a valid database name.

Parameters :

• connection: a Connection instance
• name: database name

See general MongoDB documentation

databases

db[collection_name] || db.collection_name

Get the collection_name Collection of Database db.

Raises InvalidName if an invalid collection name is used.

slave_okay

Is it OK to perform queries on a secondary or slave?

New in version 2.0.

safe

Use getlasterrer with every write operation?

New in version 2.0.

get_lasterror_options()

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

New in version 2.0.

set_lasterror_options(**kwargs)

Set getlasterror options for this instance.

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

Parameters :

• **kwargs: Options should be passed as keyword

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

New in version 2.0.

unset_lasterror_options(*options)

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.

New in version 2.0.

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

add_user(name, password)

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.

Parameters :

• name: the name of the user to create
• password: the password of the user to create

New in version 1.4.

authenticate(name, password)

Authenticate to use this database.

Once authenticated, the user has full read and write access to this database. Raises TypeError if either name or password is not an instance of (str, unicode). Authentication lasts for the life of the underlying Connection, or until logout() is called.

The “admin” database is special. Authenticating on “admin” gives access to all databases. Effectively, “admin” access means root access to the database.

Note

This method authenticates the current connection, and will also cause all new socket connections in the underlying Connection to be authenticated automatically.

• When sharing a Connection between multiple threads, all threads will share the authentication. If you need different authentication profiles for different purposes (e.g. admin users) you must use distinct instances of Connection.
• To get authentication to apply immediately to all existing sockets you may need to reset this Connection’s sockets using disconnect().

Warning

Currently, calls to end_request() will lead to unpredictable behavior in combination with auth. The socket owned by the calling thread will be returned to the pool, so whichever thread uses that socket next will have whatever permissions were granted to the calling thread.

Parameters :

• name: the name of the user to authenticate
• password: the password of the user to authenticate

See general MongoDB documentation

authenticate

collection_names()

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

command(command, value=1, check=True, allowable_errors=[], **kwargs)

Issue a MongoDB command.

Send command command to the database and return the response. If command is an instance of basestring then the command {command: value} will be sent. Otherwise, command must be an instance of dict and will be sent as is.

Any additional keyword arguments will be added to the final command document before it is sent.

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

>>> db.command("buildinfo")

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

>>> db.command("collstats", collection_name)

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

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

• **kwargs (optional): additional keyword arguments will be added to the command document before it is sent

Changed in version 1.6: Added the value argument for string commands, and keyword arguments for additional command options.

Changed in version 1.5: command can be a string in addition to a full document.

New in version 1.4.

See general MongoDB documentation

commands

connection

The Connection instance for this Database.

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

create_collection(name, options=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. Any of the following options are valid:

• “size”: desired initial size for the collection (in bytes). must be less than or equal to 10000000000. 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)

Parameters :

• name: the name of the collection to create
• options: DEPRECATED options to use on the new collection
• **kwargs (optional): additional keyword arguments will be passed as options for the create collection command

Changed in version 1.5: deprecating options in favor of kwargs

current_op()

Get information on operations currently running.

dereference(dbref)

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

drop_collection(name_or_collection)

Drop a collection.

Parameters :

• name_or_collection: the name of a collection to drop or the collection object itself

error()

Get a database error if one occured on the last operation.

Return None if the last operation was error-free. Otherwise return the error that occurred.

eval(code, *args)

Evaluate a JavaScript expression in MongoDB.

Useful if you need to touch a lot of data lightly; in such a scenario the network transfer of the data could be a bottleneck. The code argument must be a JavaScript function. Additional positional arguments will be passed to that function when it is run on the server.

Raises TypeError if code is not an instance of (str, unicode, Code). Raises OperationFailure if the eval fails. Returns the result of the evaluation.

Parameters :

• code: string representation of JavaScript code to be evaluated
• args (optional): additional positional arguments are passed to the code being evaluated

incoming_copying_manipulators

List all incoming SON copying manipulators installed on this instance.

New in version 2.0.

incoming_manipulators

List all incoming SON manipulators installed on this instance.

New in version 2.0.

last_status()

Get status information from the last operation.

Returns a SON object with status information.

logout()

Deauthorize use of this database for this connection and future connections.

Note

Other databases may still be authenticated, and other existing socket connections may remain authenticated for this database unless you reset all sockets with disconnect().

name

The name of this Database.

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

outgoing_copying_manipulators

List all outgoing SON copying manipulators installed on this instance.

New in version 2.0.

outgoing_manipulators

List all outgoing SON manipulators installed on this instance.

New in version 2.0.

previous_error()

Get the most recent error to have occurred on this database.

Only returns errors that have occurred since the last call to Database.reset_error_history. Returns None if no such errors have occurred.

profiling_info()

Returns a list containing current profiling information.

See general MongoDB documentation

profiling

profiling_level()

Get the database’s current profiling level.

Returns one of (OFF, SLOW_ONLY, ALL).

See general MongoDB documentation

profiling

remove_user(name)

Remove user name from this Database.

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

Parameters :

• name: the name of the user to remove

New in version 1.4.

reset_error_history()

Reset the error history of this database.

Calls to Database.previous_error will only return errors that have occurred since the most recent call to this method.

set_profiling_level(level)

Set the database’s profiling level.

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

Parameters :

• level: the profiling level to use

See general MongoDB documentation

profiling

system_js

A SystemJS helper for this Database.

See the documentation for SystemJS for more details.

New in version 1.5.

validate_collection(name_or_collection, scandata=False, full=False)

Validate a collection.

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

With MongoDB < 1.9 the result dict will include a result key with a string value that represents the validation results. With MongoDB >= 1.9 the result key no longer exists and the results are split into individual fields in the result dict.

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. Ignored in MongoDB versions before 1.9.

Changed in version 1.11: validate_collection previously returned a string.

New in version 1.11: Added scandata and full options.

class pymongo.database.SystemJS(database)

Get a system js helper for the database database.

An instance of SystemJS can be created with an instance of Database through Database.system_js, manual instantiation of this class should not be necessary.

SystemJS instances allow for easy manipulation and access to server-side JavaScript:

>>> db.system_js.add1 = "function (x) { return x + 1; }"
>>> db.system.js.find({"_id": "add1"}).count()
1
>>> db.system_js.add1(5)
6.0
>>> del db.system_js.add1
>>> db.system.js.find({"_id": "add1"}).count()
0

Note

Requires server version >= 1.1.1

New in version 1.5.

list()

Get a list of the names of the functions stored in this database.

New in version 1.9.