db.txt

====
Db()
====

------------------
Constructor
------------------


Create a new Db instance.


  .. js:class:: Db()

   :param string databaseName: name of the database.
   :param object serverConfig: server config object.
   :param object [options]: additional options for the collection.


Options
 - **strict** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, execute insert with a getLastError command returning the result of the insert command.
 - **native_parser** {Boolean, default:false}, use c++ bson parser.
 - **forceServerObjectId** {Boolean, default:false}, force server to create _id fields instead of client.
 - **pkFactory** {Object}, object overriding the basic ObjectID primary key generation.
 - **slaveOk** {Boolean, default:false}, allow reads from secondaries.
 - **serializeFunctions** {Boolean, default:false}, serialize functions.
 - **raw** {Boolean, default:false}, peform operations using raw bson buffers.
 - **recordQueryStats** {Boolean, default:false}, record query statistics during execution.
 - **reaper** {Boolean, default:false}, enables the reaper, timing out calls that never return.
 - **reaperInterval** {Number, default:10000}, number of miliseconds between reaper wakups.
 - **reaperTimeout** {Number, default:30000}, the amount of time before a callback times out.
 - **retryMiliSeconds** {Number, default:5000}, number of miliseconds between retries.
 - **numberOfRetries** {Number, default:5}, number of retries off connection.


------------------
Constants
------------------

.. csv-table:: 
   :header: "Constant Name", "Value", "Description"
   :widths: 15, 10, 30

   "Db.DEFAULT_URL", "'mongodb://localhost:27017/default'", "Default URL"

----
open
----


Initialize the database connection.

.. js:function:: open(callback)

   :param function callback: returns index information.
   :returns: null 


**Examples**

  
  
  An example of a simple single server db connection

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       db.close();
     });

  
  
  Simple replicaset connection setup, requires a running replicaset on the correct ports

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     // Replica configuration
     var replSet = new ReplSetServers([ 
         new Server('localhost', 30000, { auto_reconnect: true } ),
         new Server('localhost', 30001, { auto_reconnect: true } ),
         new Server('localhost', 30002, { auto_reconnect: true } )
       ] 
     );
     
     var db = new Db('integration_test_', replSet);
     db.open(function(err, p_db) {
       assert.equal(null, err);
       p_db.close();
     });


--
db
--


Create a new Db instance sharing the current socket connections.

.. js:function:: db(dbName)

   :param string dbName: the name of the database we want to use.
   :returns: db a db instance using the new database.


**Examples**

  
  
  Simple example connecting to two different databases sharing the socket connections below.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       assert.equal(null, err);
       
       // Reference a different database sharing the same connections
       // for the data transfer
       var secondDb = db.db("integration_tests_2");
       
       // Fetch the collections
       var multipleColl1 = db.collection("multiple_db_instances");
       var multipleColl2 = secondDb.collection("multiple_db_instances");
       
       // Write a record into each and then count the records stored
       multipleColl1.insert({a:1}, {safe:true}, function(err, result) {      
         multipleColl2.insert({a:1}, {safe:true}, function(err, result) {
           
           // Count over the results ensuring only on record in each collection
           multipleColl1.count(function(err, count) {
             assert.equal(1, count);
     
             multipleColl2.count(function(err, count) {
               assert.equal(1, count);
     
               db.close();
             });
           });
         });
       });
     });


-----
close
-----


Close the current db connection, including all the child db instances. Emits close event if no callback is provided.

.. js:function:: close([forceClose][, callback])

   :param boolean [forceClose]: connection can never be reused.
   :param function [callback]: returns the results.
   :returns: null 


**Examples**

  
  
  An example that shows how to force close a db connection so it cannot be reused.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 1}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Fetch a collection
       db.collection('shouldCorrectlyFailOnRetryDueToAppCloseOfDb', function(err, collection) {
     
         // Insert a document
         collection.insert({a:1}, {safe:true}, function(err, result) {
           assert.equal(null, err);
           
           // Force close the connection
           db.close(true, function(err, result) {
             
             // Attemp to insert should fail now with correct message 'db closed by application'
             collection.insert({a:2}, {safe:true}, function(err, result) {
               assert.equal('db closed by application', err.message);
             });          
           });
         });    
       });
     });

  
  
  An example of a simple single server db connection and close function

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Close the connection with a callback that is optional
       db.close(function(err, result) {
         assert.equal(null, err);
               
       });
     });


-----
admin
-----


Access the Admin database

.. js:function:: admin([callback])

   :param function [callback]: returns the results.
   :returns: admin the admin db object.


**Examples**

  
  
  Example showing how to access the Admin database for admin level operations.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
     
       // Use the admin database for the operation
       db.admin(function(err, adminDb) {
         assert.equal(null, err);
         
         db.close();
       });
     });


---------------
collectionsInfo
---------------


Returns a cursor to all the collection information.

.. js:function:: collectionsInfo([collectionName], callback)

   :param string [collectionName]: the collection name we wish to retrieve the information from.
   :param function callback: returns option results.
   :returns: null 


**Examples**

  
  
  An example of retrieveing the information of all the collections.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection('test_collections_info', function(err, r) {
         assert.equal(null, err);
         
         // Return the information of a single collection name
         db.collectionsInfo("test_collections_info").toArray(function(err, items) {
           assert.equal(1, items.length);
     
           // Return the information of a all collections, using the callback format
           db.collectionsInfo(function(err, cursor) {
     
             // Turn the cursor into an array of results
             cursor.toArray(function(err, items) {
               assert.ok(items.length > 0);
     
               db.close();
             });
           })
         });      
       });
     });


---------------
collectionNames
---------------


Get the list of all collection names for the specified db

.. js:function:: collectionNames([collectionName], callback)

   :param string [collectionName]: the collection name we wish to filter by.
   :param function callback: returns option results.
   :returns: null 


**Examples**

  
  
  An example of retrieveing the collection names for a database.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection('test_collections_info', function(err, r) {
         assert.equal(null, err);
         
         // Return the information of a single collection name
         db.collectionNames("test_collections_info", function(err, items) {
           assert.equal(1, items.length);
     
           // Return the information of a all collections, using the callback format
           db.collectionNames(function(err, items) {
             assert.ok(items.length > 0);
     
             db.close();
           });
         });      
       });
     });


----------
collection
----------


Fetch a specific collection (containing the actual collection information)



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.
 - **slaveOk** {Boolean, default:false}, Allow reads from secondaries.
 - **serializeFunctions** {Boolean, default:false}, serialize functions on the document.
 - **raw** {Boolean, default:false}, perform all operations using raw bson objects.
 - **pkFactory** {Object}, object overriding the basic ObjectID primary key generation.

.. js:function:: collection(collectionName[, options], [callback])

   :param string collectionName: the collection name we wish to access.
   :param object [options]: returns option results.
   :param function [callback]: returns the results.
   :returns: null 


**Examples**

  
  
  An example of retrieving a collection from a db using the collection function.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Grab a collection without a callback no safe mode
       var col1 = db.collection('test_correctly_access_collections');
       
       // Grab a collection with a callback but no safe operation
       db.collection('test_correctly_access_collections', function(err, col2) {
         assert.equal(null, err);
         
         // Grab a collection with a callback in safe mode, ensuring it exists (should fail as it's not created)
         db.collection('test_correctly_access_collections', {safe:true}, function(err, col3) {
           assert.ok(err != null);
           
           // Create the collection
           db.createCollection('test_correctly_access_collections', function(err, result) {
     
             // Retry to get the collection, should work as it's now created
             db.collection('test_correctly_access_collections', {safe:true}, function(err, col3) {
               assert.equal(null, err);
             
               db.close();        
             });
           });        
         });      
       });
     });


-----------
collections
-----------


Fetch all collections for the current db.

.. js:function:: collections(callback)

   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of retrieving all collections for a db as Collection objects

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
           
       // Create the collection
       db.createCollection('test_correctly_access_collections', function(err, result) {
     
         // Retry to get the collection, should work as it's now created
         db.collections(function(err, collections) {
           assert.equal(null, err);
           assert.ok(collections.length > 0);
         
           db.close();        
         });
       });        
     });


----
eval
----


Evaluate javascript on the server



Options
 - **nolock** {Boolean, default:false}, Tell MongoDB not to block on the evaulation of the javascript.

.. js:function:: eval(code[, parameters], [options], callback)

   :param code code: javascript to execute on server.
   :param object [parameters]: the parameters for the call.
   :param object [options]: the options
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A whole bunch of examples on how to use eval on the server.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 1}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Evaluate a function on the server with the parameter 3 passed in
       db.eval('function (x) {return x;}', [3], function(err, result) {      
         assert.equal(3, result);
       });
     
       // Evaluate a function on the server with the parameter 3 passed in no lock aquired for eval
       // on server
       db.eval('function (x) {return x;}', [3], {nolock:true}, function(err, result) {
         assert.equal(3, result);
       });
       
       // Evaluate a function on the server that writes to a server collection
       db.eval('function (x) {db.test_eval.save({y:x});}', [5], function(err, result) {
         // Locate the entry
         client.collection('test_eval', function(err, collection) {
           collection.findOne(function(err, item) {
             assert.equal(5, item.y);
           });
         });
       });
       
       // Evaluate a function with 2 parameters passed in
       db.eval('function (x, y) {return x + y;}', [2, 3], function(err, result) {
         assert.equal(5, result);
       });
       
       // Evaluate a function with no parameters passed in
       db.eval('function () {return 5;}', function(err, result) {
         assert.equal(5, result);
       });
       
       // Evaluate a statement
       db.eval('2 + 3;', function(err, result) {
         assert.equal(5, result);
       });
       
       // Evaluate a statement using the code object
       db.eval(new Code("2 + 3;"), function(err, result) {
         assert.equal(5, result);
       });
       
       // Evaluate a statement using the code object including a scope
       db.eval(new Code("return i;", {'i':2}), function(err, result) {
         assert.equal(2, result);
       });
       
       // Evaluate a statement using the code object including a scope
       db.eval(new Code("i + 3;", {'i':2}), function(err, result) {
         assert.equal(5, result);
       });
       
       // Evaluate an illegal statement
       db.eval("5 ++ 5;", function(err, result) {
         assert.ok(err instanceof Error);
         assert.ok(err.message != null);
         // Let's close the db
         test.done();
       });
       
       db.close();
       test.done();
     });


-----------
dereference
-----------


Dereference a dbref, against a db

.. js:function:: dereference(dbRef, callback)

   :param dbref dbRef: db reference object we wish to resolve.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of dereferencing values.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
     
       // Get a second db
       var secondDb = db.db('integration_tests_2');
     
       // Create a dereference example
       secondDb.createCollection('test_deref_examples', function(err, collection) {
         
         // Insert a document in the collection
         collection.insert({'a':1}, {safe:true}, function(err, ids) {
           
           // Let's build a db reference and resolve it
           var dbRef = new DBRef('test_deref_examples', ids[0]._id, 'integration_tests_2');
           
           // Resolve it including a db resolve
           db.dereference(dbRef, function(err, item) {          
             assert.equal(1, item.a);
     
             // Let's build a db reference and resolve it
             var dbRef = new DBRef('test_deref_examples', ids[0]._id);
     
             // Simple local resolve
             secondDb.dereference(dbRef, function(err, item) {          
               assert.equal(1, item.a);
     
               db.close();
             });
           });
         });
       });
     });


------
logout
------


Logout user from server, fire off on all connections and remove all auth info

.. js:function:: logout(callback)

   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of using the logout command for the database.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
     
       // Add a user to the database
       db.addUser('user', 'name', function(err, result) {
         assert.equal(null, err);
         
         // Authenticate
         db.authenticate('user', 'name', function(err, result) {
           assert.equal(true, result);
     
           // Logout the db
           db.logout(function(err, result) {
             assert.equal(true, result);
             
             db.close();
           });        
         });      
       });
     });


------------
authenticate
------------


Authenticate a user against the server.

.. js:function:: authenticate(username, password, callback)

   :param string username: username.
   :param string password: password.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of using the authenticate command.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
     
       // Add a user to the database
       db.addUser('user', 'name', function(err, result) {
         assert.equal(null, err);
         
         // Authenticate
         db.authenticate('user', 'name', function(err, result) {
           assert.equal(true, result);
     
           db.close();
         });      
       });
     });


-------
addUser
-------


Add a user to the database.



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.

.. js:function:: addUser(username, password[, options], callback)

   :param string username: username.
   :param string password: password.
   :param object [options]: additional options during update.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of adding a user to the database.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
     
       // Add a user to the database
       db.addUser('user', 'name', function(err, result) {
         assert.equal(null, err);
         
         db.close();
       });
     });


----------
removeUser
----------


Remove a user from a database



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.

.. js:function:: removeUser(username[, options], callback)

   :param string username: username.
   :param object [options]: additional options during update.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  An example of dereferencing values.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
     
       // Add a user to the database
       db.addUser('user', 'name', function(err, result) {
         assert.equal(null, err);
         
         // Authenticate
         db.authenticate('user', 'name', function(err, result) {
           assert.equal(true, result);
     
           // Logout the db
           db.logout(function(err, result) {
             assert.equal(true, result);
     
             // Remove the user from the db
             db.removeUser('user', function(err, result) {
                           
               // Authenticate
               db.authenticate('user', 'name', function(err, result) {
                 assert.equal(false, result);
     
                 db.close();
               });
             });
           });        
         });      
       });
     });


----------------
createCollection
----------------


Creates a collection on a server pre-allocating space, need to create f.ex capped collections.



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.
 - **slaveOk** {Boolean, default:false}, Allow reads from secondaries.
 - **serializeFunctions** {Boolean, default:false}, serialize functions on the document.
 - **raw** {Boolean, default:false}, perform all operations using raw bson objects.
 - **pkFactory** {Object}, object overriding the basic ObjectID primary key generation.
 - **capped** {Boolean, default:false}, create a capped collection.
 - **size** {Number}, the size of the capped collection in bytes.
 - **max** {Number}, the maximum number of documents in the capped collection.
 - **autoIndexId** {Boolean, default:false}, create an index on the _id field of the document, not created automatically on capped collections.

.. js:function:: createCollection(collectionName[, options], callback)

   :param string collectionName: the collection name we wish to access.
   :param object [options]: returns option results.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example showing the creation of a collection.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a capped collection with a maximum of 1000 documents
       db.createCollection("a_simple_collection", {capped:true, size:10000, max:1000, safe:true}, function(err, collection) {
         assert.equal(null, err);
         
         // Insert a document in the capped collection
         collection.insert({a:1}, {safe:true}, function(err, result) {
           assert.equal(null, err);
           
           db.close();
         });      
       });
     });


-------
command
-------


Execute a command hash against MongoDB. This lets you acess any commands not available through the api on the server.

.. js:function:: command(selector, callback)

   :param object selector: the command hash to send to the server, ex: {ping:1}.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example creating, dropping a collection and then verifying that the collection is gone.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Execute ping against the server
       db.command({ping:1}, function(err, result) {
         assert.equal(null, err);
         
         db.close();
       });    
     });


--------------
dropCollection
--------------


Drop a collection from the database, removing it permanently. New accesses will create a new collection.

.. js:function:: dropCollection(collectionName, callback)

   :param string collectionName: the name of the collection we wish to drop.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example executing a command against the server.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Execute ping against the server
       db.command({ping:1}, function(err, result) {
         assert.equal(null, err);
         
         // Create a capped collection with a maximum of 1000 documents
         db.createCollection("a_simple_create_drop_collection", {capped:true, size:10000, max:1000, safe:true}, function(err, collection) {
           assert.equal(null, err);
     
           // Insert a document in the capped collection
           collection.insert({a:1}, {safe:true}, function(err, result) {
             assert.equal(null, err);
     
             // Drop the collection from this world
             db.dropCollection("a_simple_create_drop_collection", function(err, result) {
               assert.equal(null, err);
     
               // Verify that the collection is gone
               db.collectionNames("a_simple_create_drop_collection", function(err, names) {
                 assert.equal(0, names.length);
                 
                 db.close();
               });
             });
           });      
         });
       });    
     });


----------------
renameCollection
----------------


Rename a collection.

.. js:function:: renameCollection(fromCollection, toCollection, callback)

   :param string fromCollection: the name of the current collection we wish to rename.
   :param string toCollection: the new name of the collection.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example creating, dropping a collection and then verifying that the collection is gone.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection("simple_rename_collection", {safe:true}, function(err, collection) {
         assert.equal(null, err);
         
         // Insert a document in the collection
         collection.insert({a:1}, {safe:true}, function(err, result) {
           assert.equal(null, err);
           
           // Rename the collection
           db.renameCollection("simple_rename_collection", "simple_rename_collection_2", function(err, collection2) {
             assert.equal(null, err);          
             
             // Retrieve the number of documents from the collection
             collection2.count(function(err, count) {
               assert.equal(1, count);
               
               // Verify that the collection is gone
               db.collectionNames("simple_rename_collection", function(err, names) {
                 assert.equal(0, names.length);
                 
                 // Verify that the new collection exists
                 db.collectionNames("simple_rename_collection_2", function(err, names) {
                   assert.equal(1, names.length);
     
                   db.close();
                 });
               });
             });          
           });
         });      
       });
     });


---------
lastError
---------


Return last error message for the given connection, note options can be combined.



Options
 - **fsync** {Boolean, default:false}, option forces the database to fsync all files before returning.
 - **j** {Boolean, default:false}, awaits the journal commit before returning, > MongoDB 2.0.
 - **w** {Number}, until a write operation has been replicated to N servers.
 - **wtimeout** {Number}, number of miliseconds to wait before timing out.



Connection Options
 - **connection** {Connection}, fire the getLastError down a specific connection.

.. js:function:: lastError([options][, connectionOptions], callback)

   :param object [options]: returns option results.
   :param object [connectionOptions]: returns option results.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example using lastError on a single connection with a pool of 1.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 1}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection("simple_rename_collection", {safe:true}, function(err, collection) {
         assert.equal(null, err);
         
         // Insert a document in the collection
         collection.insert({a:1}, function(err, result) {
           assert.equal(null, err);
     
           // Execute lastError
           db.lastError(function(err, result) {
             assert.equal(null, err);
             assert.equal(null, result[0].err);
             
             // Pick a specific connection and execute lastError against it
             var connection = db.serverConfig.checkoutWriter();
             // Execute lastError
             db.lastError({}, {connection:connection}, function(err, result) {
               assert.equal(null, err);
               assert.equal(null, result[0].err);
               
               db.close();
             });                    
           });
         });      
       });
     });


--------------
previousErrors
--------------


Return all errors up to the last time db reset_error_history was called.



Options
 - **connection** {Connection}, fire the getLastError down a specific connection.

.. js:function:: previousErrors([options], callback)

   :param object [options]: returns option results.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example using previousError to return the list of all errors, might be deprecated in the future.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 1}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection("simple_previous_error_coll", {safe:true}, function(err, collection) {
         assert.equal(null, err);
         
         // Force a unique index
         collection.ensureIndex({a:1}, {unique:true, safe:true}, function(err, result) {
           assert.equal(null, err);
           
           // Force some errors
           collection.insert([{a:1}, {a:1}, {a:1}, {a:2}], function(err, result) {
             
             // Pick a specific connection and execute lastError against it
             var connection = db.serverConfig.checkoutWriter();
     
             // Execute previousErrors
             db.previousErrors({connection:connection}, function(err, result) {
               assert.equal(null, err);
               assert.equal(1, result.length);
               assert.ok(result[0].err != null);
     
               db.close();
             });          
           });        
         });
       });
     });


-----------------
resetErrorHistory
-----------------


Resets the error history of the mongo instance.



Options
 - **connection** {Connection}, fire the getLastError down a specific connection.

.. js:function:: resetErrorHistory([options], callback)

   :param object [options]: returns option results.
   :param function callback: returns the results.
   :returns: null 


**Examples**

  
  
  A simple example using resetErrorHistory to clean up the history of errors.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
      {auto_reconnect: false, poolSize: 1}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {    
       assert.equal(null, err);
       
       // Create a collection
       db.createCollection("simple_reset_error_history_coll", {safe:true}, function(err, collection) {
         assert.equal(null, err);
         
         // Force a unique index
         collection.ensureIndex({a:1}, {unique:true, safe:true}, function(err, result) {
           assert.equal(null, err);
           
           // Force some errors
           collection.insert([{a:1}, {a:1}, {a:1}, {a:2}], function(err, result) {                    
             // Pick a specific connection and execute lastError against it
             var connection = db.serverConfig.checkoutWriter();
     
             // Reset the error history
             db.resetErrorHistory({connection:connection}, function(err, result) {
               
               // Execute previousErrors and validate that there are no errors left
               db.previousErrors({connection:connection}, function(err, result) {
                 assert.equal(null, err);
                 assert.equal(1, result.length);
                 assert.equal(null, result[0].err);
     
                 db.close();
               });          
             });
           });        
         });
       });
     });


-----------
createIndex
-----------


Creates an index on the collection.



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.
 - **unique** {Boolean, default:false}, creates an unique index.
 - **sparse** {Boolean, default:false}, creates a sparse index.
 - **background** {Boolean, default:false}, creates the index in the background, yielding whenever possible.
 - **dropDups** {Boolean, default:false}, a unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value
 - **min** {Number}, for geospatial indexes set the lower bound for the co-ordinates.
 - **max** {Number}, for geospatial indexes set the high bound for the co-ordinates.

.. js:function:: createIndex(collectionName, fieldOrSpec[, options], callback)

   :param string collectionName: name of the collection to create the index on.
   :param object fieldOrSpec: fieldOrSpec that defines the index.
   :param object [options]: additional options during update.
   :param function callback: for results.
   :returns: null 


**Examples**

  
  
  A more complex createIndex using a compound unique index in the background and dropping duplicated documents

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
     
       // Create a collection we want to drop later
       db.createCollection('more_complex_index_test', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
     
           // Create an index on the a field
           db.createIndex('more_complex_index_test', {a:1, b:1}
             , {unique:true, background:true, dropDups:true, safe:true}, function(err, indexName) {
       
             // Show that duplicate records got dropped
             collection.find({}).toArray(function(err, items) {
               assert.equal(null, err);
               assert.equal(4, items.length);
         
               // Peform a query, with explain to show we hit the query
               collection.find({a:2}, {explain:true}).toArray(function(err, explanation) {
                 assert.equal(null, err);
                 assert.ok(explanation[0].indexBounds.a != null);
                 assert.ok(explanation[0].indexBounds.b != null);
     
                 db.close();
               });
             })
           });
         });
       });
     });


-----------
ensureIndex
-----------


Ensures that an index exists, if it does not it creates it



Options
 - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a 
 - **unique** {Boolean, default:false}, creates an unique index.
 - **sparse** {Boolean, default:false}, creates a sparse index.
 - **background** {Boolean, default:false}, creates the index in the background, yielding whenever possible.
 - **dropDups** {Boolean, default:false}, a unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value
 - **min** {Number}, for geospatial indexes set the lower bound for the co-ordinates.
 - **max** {Number}, for geospatial indexes set the high bound for the co-ordinates.
 - **v** {Number}, specify the format version of the indexes.

.. js:function:: ensureIndex(collectionName, fieldOrSpec[, options], callback)

   :param string collectionName: name of the collection to create the index on.
   :param object fieldOrSpec: fieldOrSpec that defines the index.
   :param object [options]: additional options during update.
   :param function callback: for results.
   :returns: null 


**Examples**

  
  
  A more complex ensureIndex using a compound unique index in the background and dropping duplicated documents.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
     
       // Create a collection we want to drop later
       db.createCollection('more_complex_ensure_index_test', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
       
           // Create an index on the a field
           db.ensureIndex('more_complex_ensure_index_test', {a:1, b:1}
             , {unique:true, background:true, dropDups:true, safe:true}, function(err, indexName) {
         
             // Show that duplicate records got dropped
             collection.find({}).toArray(function(err, items) {
               assert.equal(null, err);
               assert.equal(4, items.length);
           
               // Peform a query, with explain to show we hit the query
               collection.find({a:2}, {explain:true}).toArray(function(err, explanation) {
                 assert.equal(null, err);
                 assert.ok(explanation[0].indexBounds.a != null);
                 assert.ok(explanation[0].indexBounds.b != null);
     
                 db.close();
               });
             })
           });
         });
       });
     });


----------
cursorInfo
----------


Returns the information available on allocated cursors.

.. js:function:: cursorInfo(callback)

   :param function callback: for results.
   :returns: null 


**Examples**

  
  
  A Simple example of returning current cursor information in MongoDB

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
     
       // Create a collection we want to drop later
       db.createCollection('cursor_information_collection', function(err, collection) {      
         assert.equal(null, err);
     
         // Create a bunch of documents so we can force the creation of a cursor
         var docs = [];      
         for(var i = 0; i < 1000; i++) {
           docs.push({a:'hello world hello world hello world hello world hello world hello world hello world hello world'});
         }
     
         // Insert a bunch of documents for the index
         collection.insert(docs, {safe:true}, function(err, result) {
           assert.equal(null, err);
     
           // Let's set a cursor
           var cursor = collection.find({}, {batchSize:10});
           cursor.nextObject(function(err, item) {
             assert.equal(null, err);
             
             // Let's grab the information about the cursors on the database
             db.cursorInfo(function(err, cursorInformation) {
               assert.ok(cursorInformation.totalOpen > 0);
               
               db.close();
             });          
           });    
         });
       });
     });


---------
dropIndex
---------


Drop an index on a collection.

.. js:function:: dropIndex(collectionName, indexName, callback)

   :param string collectionName: the name of the collection where the command will drop an index.
   :param string indexName: name of the index to drop.
   :param function callback: for results.
   :returns: null 


**Examples**

  
  
  An examples showing the creation and dropping of an index

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Create a collection we want to drop later
       db.createCollection('create_and_drop_an_index', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
       
           // Create an index on the a field
           collection.ensureIndex({a:1, b:1}
             , {unique:true, background:true, dropDups:true, safe:true}, function(err, indexName) {
         
             // Drop the index
             db.dropIndex("create_and_drop_an_index", "a_1_b_1", function(err, result) {
               assert.equal(null, err);
           
               // Verify that the index is gone
               collection.indexInformation(function(err, indexInformation) {              
                 assert.deepEqual([ [ '_id', 1 ] ], indexInformation._id_);
                 assert.equal(null, indexInformation.a_1_b_1);
     
                 db.close();              
               });
             });
           });
         });
       });
     });


-------
reIndex
-------


Reindex all indexes on the collection
Warning: reIndex is a blocking operation (indexes are rebuilt in the foreground) and will be slow for large collections.

.. js:function:: reIndex(collectionName, callback)

   :param string collectionName: the name of the collection.
   :param function callback: returns the results.

**Examples**

  
  
  An example showing how to force a reindex of a collection.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Create a collection we want to drop later
       db.createCollection('create_and_drop_all_indexes', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4, c:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
       
           // Create an index on the a field
           collection.ensureIndex({a:1, b:1}
             , {unique:true, background:true, dropDups:true, safe:true}, function(err, indexName) {
     
             // Force a reindex of the collection
             db.reIndex('create_and_drop_all_indexes', function(err, result) {
               assert.equal(null, err);
               assert.equal(true, result);
           
               // Verify that the index is gone
               collection.indexInformation(function(err, indexInformation) {
                 assert.deepEqual([ [ '_id', 1 ] ], indexInformation._id_);
                 assert.deepEqual([ [ 'a', 1 ], [ 'b', 1 ] ], indexInformation.a_1_b_1);
     
                 db.close();              
               });
             });
           });
         });
       });
     });


----------------
indexInformation
----------------


Retrieves this collections index info.



Options
 - **full** {Boolean, default:false}, returns the full raw index information.

.. js:function:: indexInformation(collectionName[, options], callback)

   :param string collectionName: the name of the collection.
   :param object [options]: additional options during update.
   :param function callback: returns the index information.
   :returns: null 


**Examples**

  
  
  An example showing the information returned by indexInformation

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Create a collection we want to drop later
       db.createCollection('more_index_information_test', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
       
           // Create an index on the a field
           collection.ensureIndex({a:1, b:1}
             , {unique:true, background:true, dropDups:true, safe:true}, function(err, indexName) {
         
             // Fetch basic indexInformation for collection
             db.indexInformation('more_index_information_test', function(err, indexInformation) {
               assert.deepEqual([ [ '_id', 1 ] ], indexInformation._id_);
               assert.deepEqual([ [ 'a', 1 ], [ 'b', 1 ] ], indexInformation.a_1_b_1);
     
               // Fetch full index information
               collection.indexInformation({full:true}, function(err, indexInformation) {
                 assert.deepEqual({ _id: 1 }, indexInformation[0].key);
                 assert.deepEqual({ a: 1, b: 1 }, indexInformation[1].key);
     
                 db.close();              
               });
             });
           });
         });
       });
     });


------------
dropDatabase
------------


Drop a database.

.. js:function:: dropDatabase(callback)

   :param function callback: returns the index information.
   :returns: null 


**Examples**

  
  
  An examples showing the dropping of a database

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     var db = new Db('integration_tests_to_drop', new Server("127.0.0.1", 27017, 
       {auto_reconnect: false, poolSize: 4}), {native_parser: false});
     
     // Establish connection to db  
     db.open(function(err, db) {
       
       // Create a collection
       db.createCollection('more_index_information_test', function(err, collection) {      
         assert.equal(null, err);
     
         // Insert a bunch of documents for the index
         collection.insert([{a:1, b:1}, {a:1, b:1}
           , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {safe:true}, function(err, result) {
           assert.equal(null, err);
       
           // Let's drop the database
           db.dropDatabase(function(err, result) {
             assert.equal(null, err);
             
             // Wait to seconds to let it replicate across
             setTimeout(function() {
               // Get the admin database
               db.admin().listDatabases(function(err, dbs) {
                 // Grab the databases
                 dbs = dbs.databases;
                 // Did we find the db
                 var found = false;
     
                 // Check if we have the db in the list
                 for(var i = 0; i < dbs.length; i++) {
                   if(dbs[i].name == 'integration_tests_to_drop') found = true;
                 }
     
                 // We should not find the databases
                 if(process.env['JENKINS'] == null) assert.equal(false, found);
     
                 db.close();
               });                        
             }, 2000);          
           });    
         });
       });
     });


----------
Db.connect
----------


Connect to MongoDB using a url as documented at



www.mongodb.org/display/DOCS/Connections



Options
 - **uri_decode_auth** {Boolean, default:false} uri decode the user name and password for authentication

.. js:function:: Db.connect(url[, options], callback)

   :param string url: connection url for MongoDB.
   :param object [options]: optional options for insert command
   :param function callback: callback returns the initialized db.
   :returns: null 


**Examples**

  
  
  Example of a simple url connection string.

  .. code-block:: javascript

     var Db = require('mongodb').Db,
         Server = require('mongodb').Server,
         ReplSetServers = require('mongodb').ReplSetServers,
         ObjectID = require('mongodb').ObjectID,
         Binary = require('mongodb').Binary,
         GridStore = require('mongodb').GridStore,
         Code = require('mongodb').Code,
         BSON = require('mongodb').pure().BSON,
         assert = require('assert');

     // Connect to the server
     Db.connect('mongodb://localhost:27017/integration_tests' + (useSSL == true ? '?ssl=true' : ''), function(err, db) {
       assert.equal(null, err);
       
       db.close();
     });