mongo::DBClientWithCommands Class Reference

DB "commands" Basically just invocations of connection. More...

#include <dbclient.h>

Inheritance diagram for mongo::DBClientWithCommands:

List of all members.

Classes
struct	MROutput
	This implicitly converts from char*, string, and BSONObj to be an argument to mapreduce You shouldn't need to explicitly construct this. More...
Public Types
enum	ProfilingLevel { ProfileOff = 0, ProfileSlow = 1, ProfileAll = 2 }
	The Mongo database provides built-in performance profiling capabilities. More...
Public Member Functions
bool	simpleCommand (const string &dbname, BSONObj *info, const string &command)
	helper function.
virtual bool	runCommand (const string &dbname, const BSONObj &cmd, BSONObj &info, int options=0)
	Run a database command.
virtual bool	auth (const string &dbname, const string &username, const string &pwd, string &errmsg, bool digestPassword=true)
	Authorize access to a particular database.
virtual unsigned long long	count (const string &ns, const BSONObj &query=BSONObj(), int options=0, int limit=0, int skip=0)
	count number of objects in collection ns that match the query criteria specified throws UserAssertion if database returns an error
string	createPasswordDigest (const string &username, const string &clearTextPassword)
virtual bool	isMaster (bool &isMaster, BSONObj *info=0)
	returns true in isMaster parm if this db is the current master of a replica pair.
bool	createCollection (const string &ns, long long size=0, bool capped=false, int max=0, BSONObj *info=0)
	Create a new collection in the database.
string	getLastError ()
	Get error result from the last write operation (insert/update/delete) on this connection.
virtual BSONObj	getLastErrorDetailed ()
	Get error result from the last write operation (insert/update/delete) on this connection.
BSONObj	getPrevError ()
	Return the last error which has occurred, even if not the very last operation.
bool	resetError ()
	Reset the previous error state for this connection (accessed via getLastError and getPrevError).
virtual bool	dropCollection (const string &ns)
	Delete the specified collection.
bool	repairDatabase (const string &dbname, BSONObj *info=0)
	Perform a repair and compaction of the specified database.
bool	copyDatabase (const string &fromdb, const string &todb, const string &fromhost="", BSONObj *info=0)
	Copy database from one server or name to another server or name.
bool	setDbProfilingLevel (const string &dbname, ProfilingLevel level, BSONObj *info=0)
bool	getDbProfilingLevel (const string &dbname, ProfilingLevel &level, BSONObj *info=0)
BSONObj	mapreduce (const string &ns, const string &jsmapf, const string &jsreducef, BSONObj query=BSONObj(), MROutput output=MRInline)
	Run a map/reduce job on the server.
bool	eval (const string &dbname, const string &jscode, BSONObj &info, BSONElement &retValue, BSONObj *args=0)
	Run javascript code on the database server.
bool	validate (const string &ns, bool scandata=true)
	validate a collection, checking for errors and reporting back statistics.
bool	eval (const string &dbname, const string &jscode)
template<class T >
bool	eval (const string &dbname, const string &jscode, T parm1)
template<class T , class NumType >
bool	eval (const string &dbname, const string &jscode, T parm1, NumType &ret)
	eval invocation with one parm to server and one numeric field (either int or double) returned
list< string >	getDatabaseNames ()
	get a list of all the current databases uses the { listDatabases : 1 } command.
list< string >	getCollectionNames (const string &db)
	get a list of all the current collections in db
bool	exists (const string &ns)
virtual bool	ensureIndex (const string &ns, BSONObj keys, bool unique=false, const string &name="", bool cache=true, bool background=false, int v=-1)
	Create an index if it does not already exist.
virtual void	resetIndexCache ()
	clears the index cache, so the subsequent call to ensureIndex for any index will go to the server
virtual auto_ptr< DBClientCursor >	getIndexes (const string &ns)
virtual void	dropIndex (const string &ns, BSONObj keys)
virtual void	dropIndex (const string &ns, const string &indexName)
virtual void	dropIndexes (const string &ns)
	drops all indexes for the collection
virtual void	reIndex (const string &ns)
string	genIndexName (const BSONObj &keys)
virtual bool	dropDatabase (const string &dbname, BSONObj *info=0)
	Erase / drop an entire database.
virtual string	toString ()=0
string	nsGetDB (const string &ns)
string	nsGetCollection (const string &ns)
Static Public Member Functions
static string	getLastErrorString (const BSONObj &res)
	Can be called with the returned value from getLastErrorDetailed to extract an error string.
Public Attributes
int	_logLevel
	controls how chatty the client is about network errors & such.
Static Public Attributes
static MROutput	MRInline
Protected Member Functions
bool	isOk (const BSONObj &)
	if the result of a command is ok
bool	isNotMasterErrorString (const BSONElement &e)
	if the element contains a not master error
BSONObj	_countCmd (const string &ns, const BSONObj &query, int options, int limit, int skip)
enum QueryOptions	availableOptions ()

---

Detailed Description

DB "commands" Basically just invocations of connection.

$cmd.findOne({...});

---

Member Enumeration Documentation

enum mongo::DBClientWithCommands::ProfilingLevel

The Mongo database provides built-in performance profiling capabilities.

Uset setDbProfilingLevel() to enable. Profiling information is then written to the system.profiling collection, which one can then query.

---

Member Function Documentation

bool mongo::DBClientWithCommands::auth	(	const string &	dbname,
		const string &	username,
		const string &	pwd,
		string &	errmsg,
		bool	digestPassword = true
	)		[virtual]

Authorize access to a particular database.

Authentication is separate for each database on the server -- you may authenticate for any number of databases on a single connection. The "admin" database is special and once authenticated provides access to all databases on the server.

Parameters:

digestPassword

if password is plain text, set this to true. otherwise assumed to be pre-digested

Returns:

true if successful

Reimplemented in mongo::DBClientConnection, mongo::DBClientReplicaSet, and mongo::SyncClusterConnection.

bool mongo::DBClientWithCommands::copyDatabase	(	const string &	fromdb,
		const string &	todb,
		const string &	fromhost = "",
		BSONObj *	info = 0
	)

Copy database from one server or name to another server or name.

Generally, you should dropDatabase() first as otherwise the copied information will MERGE into whatever data is already present in this database.

For security reasons this function only works when you are authorized to access the "admin" db. However, if you have access to said db, you can copy any database from one place to another. TODO: this needs enhancement to be more flexible in terms of security.

This method provides a way to "rename" a database by copying it to a new db name and location. The copy is "repaired" and compacted.

fromdb database name from which to copy. todb database name to copy to. fromhost hostname of the database (and optionally, ":port") from which to copy the data. copies from self if "".

returns true if successful

bool mongo::DBClientWithCommands::createCollection	(	const string &	ns,
		long long	size = 0,
		bool	capped = false,
		int	max = 0,
		BSONObj *	info = 0
	)

Create a new collection in the database.

Normally, collection creation is automatic. You would use this function if you wish to specify special options on creation.

If the collection already exists, no action occurs.

Parameters:

ns	fully qualified collection name
size	desired initial extent size for the collection. Must be <= 1000000000 for normal collections. For fixed size (capped) collections, this size is the total/max size of the collection.
capped	if true, this is a fixed size collection (where old data rolls out).
max	maximum number of objects if capped (optional).

returns true if successful.

virtual bool mongo::DBClientWithCommands::dropCollection

(

const string &

ns

)

[inline, virtual]

Delete the specified collection.

bool mongo::DBClientWithCommands::ensureIndex	(	const string &	ns,
		BSONObj	keys,
		bool	unique = false,
		const string &	name = "",
		bool	cache = true,
		bool	background = false,
		int	v = -1
	)		[virtual]

Create an index if it does not already exist.

ensureIndex calls are remembered so it is safe/fast to call this function many times in your code.

Parameters:

ns	collection to be indexed
keys	the "key pattern" for the index. e.g., { name : 1 }
unique	if true, indicates that key uniqueness should be enforced for this index
name	if not specified, it will be created from the keys automatically (which is recommended)
cache	if set to false, the index cache for the connection won't remember this call
background	build index in the background (see mongodb docs/wiki for details)
v	index version. leave at default value. (unit tests set this parameter.)

Returns:

whether or not sent message to db. should be true on first call, false on subsequent unless resetIndexCache was called

bool mongo::DBClientWithCommands::eval	(	const string &	dbname,
		const string &	jscode,
		BSONObj &	info,
		BSONElement &	retValue,
		BSONObj *	args = 0
	)

Run javascript code on the database server.

dbname database SavedContext in which the code runs. The javascript variable 'db' will be assigned to this database when the function is invoked. jscode source code for a javascript function. info the command object which contains any information on the invocation result including the return value and other information. If an error occurs running the jscode, error information will be in info. (try "out() << info.toString()") retValue return value from the jscode function. args args to pass to the jscode function. when invoked, the 'args' variable will be defined for use by the jscode.

returns true if runs ok.

See testDbEval() in dbclient.cpp for an example of usage.

list< string > mongo::DBClientWithCommands::getDatabaseNames

(

)

get a list of all the current databases uses the { listDatabases : 1 } command.

throws on error

string mongo::DBClientWithCommands::getLastError

(

)

Get error result from the last write operation (insert/update/delete) on this connection.

Returns:

error message text, or empty string if no error.

BSONObj mongo::DBClientWithCommands::getLastErrorDetailed

(

)

[virtual]

Get error result from the last write operation (insert/update/delete) on this connection.

Returns:

full error object.

Reimplemented in mongo::SyncClusterConnection.

string mongo::DBClientWithCommands::getLastErrorString

(

const BSONObj &

res

)

[static]

Can be called with the returned value from getLastErrorDetailed to extract an error string.

If all you need is the string, just call getLastError() instead.

BSONObj mongo::DBClientWithCommands::getPrevError

(

)

Return the last error which has occurred, even if not the very last operation.

Returns:

{ err : <error message>="">, nPrev : <how_many_ops_back_occurred>, ok : 1 }

result.err will be null if no error has occurred.

bool mongo::DBClientWithCommands::isMaster	(	bool &	isMaster,
		BSONObj *	info = 0
	)		[virtual]

returns true in isMaster parm if this db is the current master of a replica pair.

pass in info for more details e.g.: { "ismaster" : 1.0 , "msg" : "not paired" , "ok" : 1.0 }

returns true if command invoked successfully.

BSONObj mongo::DBClientWithCommands::mapreduce	(	const string &	ns,
		const string &	jsmapf,
		const string &	jsreducef,
		BSONObj	query = BSONObj(),
		MROutput	output = MRInline
	)

Run a map/reduce job on the server.

See http://www.mongodb.org/display/DOCS/MapReduce

ns namespace (db+collection name) of input data jsmapf javascript map function code jsreducef javascript reduce function code. query optional query filter for the input output either a string collection name or an object representing output type if not specified uses inline output type

returns a result object which contains: { result : <collection_name>, numObjects : <number_of_objects_scanned>, timeMillis : <job_time>, ok : <1_if_ok>, [, err : <errmsg_if_error>] }

For example one might call: result.getField("ok").trueValue() on the result to check if ok.

string mongo::DBClientWithCommands::nsGetCollection

(

const string &

ns

)

[inline]

Returns:

the collection name portion of an ns string

string mongo::DBClientWithCommands::nsGetDB

(

const string &

ns

)

[inline]

Returns:

the database name portion of an ns string

bool mongo::DBClientWithCommands::repairDatabase	(	const string &	dbname,
		BSONObj *	info = 0
	)		[inline]

Perform a repair and compaction of the specified database.

May take a long time to run. Disk space must be available equal to the size of the database while repairing.

bool mongo::DBClientWithCommands::resetError

(

)

[inline]

Reset the previous error state for this connection (accessed via getLastError and getPrevError).

Useful when performing several operations at once and then checking for an error after attempting all operations.

bool mongo::DBClientWithCommands::runCommand	(	const string &	dbname,
		const BSONObj &	cmd,
		BSONObj &	info,
		int	options = 0
	)		[inline, virtual]

Run a database command.

Database commands are represented as BSON objects. Common database commands have prebuilt helper functions -- see below. If a helper is not available you can directly call runCommand.

Parameters:

dbname	database name. Use "admin" for global administrative commands.
cmd	the command object to execute. For example, { ismaster : 1 }
info	the result object the database returns. Typically has { ok : ..., errmsg : ... } fields set.
options	see enum QueryOptions - normally not needed to run a command

Returns:

true if the command returned "ok".

Reimplemented in mongo::DBClientConnection.

bool mongo::DBClientWithCommands::simpleCommand	(	const string &	dbname,
		BSONObj *	info,
		const string &	command
	)

helper function.

run a simple command where the command expression is simply { command : 1 }

Parameters:

info	-- where to put result object. may be null if caller doesn't need that info
command	-- command name

Returns:

true if the command returned "ok".

bool mongo::DBClientWithCommands::validate	(	const string &	ns,
		bool	scandata = true
	)		[inline]

validate a collection, checking for errors and reporting back statistics.

this operation is slow and blocking.

---

Member Data Documentation

int mongo::DBClientWithCommands::_logLevel

controls how chatty the client is about network errors & such.

See log.h

---

The documentation for this class was generated from the following files:

• dbclient.h
• dbclient.cpp