{ "name": "mongodb", "description": "A node.js driver for MongoDB", "keywords": [ "mongodb", "mongo", "driver", "db" ], "version": "1.2.14", "author": { "name": "Christian Amor Kvalheim", "email": "christkv@gmail.com" }, "contributors": [ { "name": "Aaron Heckmann" }, { "name": "Christoph Pojer" }, { "name": "Pau Ramon Revilla" }, { "name": "Nathan White" }, { "name": "Emmerman" }, { "name": "Seth LaForge" }, { "name": "Boris Filipov" }, { "name": "Stefan Schärmeli" }, { "name": "Tedde Lundgren" }, { "name": "renctan" }, { "name": "Sergey Ukustov" }, { "name": "Ciaran Jessup" }, { "name": "kuno" }, { "name": "srimonti" }, { "name": "Erik Abele" }, { "name": "Pratik Daga" }, { "name": "Slobodan Utvic" }, { "name": "Kristina Chodorow" }, { "name": "Yonathan Randolph" }, { "name": "Brian Noguchi" }, { "name": "Sam Epstein" }, { "name": "James Harrison Fisher" }, { "name": "Vladimir Dronnikov" }, { "name": "Ben Hockey" }, { "name": "Henrik Johansson" }, { "name": "Simon Weare" }, { "name": "Alex Gorbatchev" }, { "name": "Shimon Doodkin" }, { "name": "Kyle Mueller" }, { "name": "Eran Hammer-Lahav" }, { "name": "Marcin Ciszak" }, { "name": "François de Metz" }, { "name": "Vinay Pulim" }, { "name": "nstielau" }, { "name": "Adam Wiggins" }, { "name": "entrinzikyl" }, { "name": "Jeremy Selier" }, { "name": "Ian Millington" }, { "name": "Public Keating" }, { "name": "andrewjstone" }, { "name": "Christopher Stott" }, { "name": "Corey Jewett" }, { "name": "brettkiefer" }, { "name": "Rob Holland" }, { "name": "Senmiao Liu" }, { "name": "heroic" }, { "name": "gitfy" }, { "name": "Andrew Stone" }, { "name": "John Le Drew" }, { "name": "Lucasfilm Singapore" }, { "name": "Roman Shtylman" }, { "name": "Matt Self" } ], "repository": { "type": "git", "url": "http://github.com/mongodb/node-mongodb-native.git" }, "bugs": { "mail": "node-mongodb-native@googlegroups.com", "url": "http://github.com/mongodb/node-mongodb-native/issues" }, "dependencies": { "bson": "0.1.8" }, "devDependencies": { "dox": "0.2.0", "uglify-js": "1.2.5", "ejs": "0.6.1", "nodeunit": "0.7.4", "github3": ">=0.3.0", "markdown": "0.3.1", "gleak": "0.2.3", "step": "0.0.5", "async": "0.1.22", "integra": "0.0.1", "optimist": "latest" }, "config": { "native": false }, "main": "./lib/mongodb/index", "homepage": "http://mongodb.github.com/node-mongodb-native/", "directories": { "lib": "./lib/mongodb" }, "engines": { "node": ">=0.6.19" }, "scripts": { "test": "make test_functional" }, "licenses": [ { "type": "Apache License, Version 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" } ], "readme": "Up to date documentation\n========================\n\n[Documentation](http://mongodb.github.com/node-mongodb-native/)\n\nInstall\n=======\n\nTo install the most recent release from npm, run:\n\n npm install mongodb\n\nThat may give you a warning telling you that bugs['web'] should be bugs['url'], it would be safe to ignore it (this has been fixed in the development version)\n\nTo install the latest from the repository, run::\n\n npm install path/to/node-mongodb-native\n\nCommunity\n=========\nCheck out the google group [node-mongodb-native](http://groups.google.com/group/node-mongodb-native) for questions/answers from users of the driver.\n\nTry it live\n============\n\n\nIntroduction\n============\n\nThis is a node.js driver for MongoDB. It's a port (or close to a port) of the library for ruby at http://github.com/mongodb/mongo-ruby-driver/.\n\nA simple example of inserting a document.\n\n```javascript\n var client = new Db('test', new Server(\"127.0.0.1\", 27017, {}), {w: 1}),\n test = function (err, collection) {\n collection.insert({a:2}, function(err, docs) {\n\n collection.count(function(err, count) {\n test.assertEquals(1, count);\n });\n\n // Locate all the entries using find\n collection.find().toArray(function(err, results) {\n test.assertEquals(1, results.length);\n test.assertTrue(results[0].a === 2);\n\n // Let's close the db\n client.close();\n });\n });\n };\n\n client.open(function(err, p_client) {\n client.collection('test_insert', test);\n });\n```\n\nData types\n==========\n\nTo store and retrieve the non-JSON MongoDb primitives ([ObjectID](http://www.mongodb.org/display/DOCS/Object+IDs), Long, Binary, [Timestamp](http://www.mongodb.org/display/DOCS/Timestamp+data+type), [DBRef](http://www.mongodb.org/display/DOCS/Database+References#DatabaseReferences-DBRef), Code).\n\nIn particular, every document has a unique `_id` which can be almost any type, and by default a 12-byte ObjectID is created. ObjectIDs can be represented as 24-digit hexadecimal strings, but you must convert the string back into an ObjectID before you can use it in the database. For example:\n\n```javascript\n // Get the objectID type\n var ObjectID = require('mongodb').ObjectID;\n\n var idString = '4e4e1638c85e808431000003';\n collection.findOne({_id: new ObjectID(idString)}, console.log) // ok\n collection.findOne({_id: idString}, console.log) // wrong! callback gets undefined\n```\n\nHere are the constructors the non-Javascript BSON primitive types:\n\n```javascript\n // Fetch the library\n var mongo = require('mongodb');\n // Create new instances of BSON types\n new mongo.Long(numberString)\n new mongo.ObjectID(hexString)\n new mongo.Timestamp() // the actual unique number is generated on insert.\n new mongo.DBRef(collectionName, id, dbName)\n new mongo.Binary(buffer) // takes a string or Buffer\n new mongo.Code(code, [context])\n new mongo.Symbol(string)\n new mongo.MinKey()\n new mongo.MaxKey()\n new mongo.Double(number)\t// Force double storage\n```\n\nThe C/C++ bson parser/serializer\n--------------------------------\n\nIf you are running a version of this library has the C/C++ parser compiled, to enable the driver to use the C/C++ bson parser pass it the option native_parser:true like below\n\n```javascript\n // using native_parser:\n var client = new Db('integration_tests_20',\n new Server(\"127.0.0.1\", 27017),\n {native_parser:true});\n```\n\nThe C++ parser uses the js objects both for serialization and deserialization.\n\nGitHub information\n==================\n\nThe source code is available at http://github.com/mongodb/node-mongodb-native.\nYou can either clone the repository or download a tarball of the latest release.\n\nOnce you have the source you can test the driver by running\n\n $ make test\n\nin the main directory. You will need to have a mongo instance running on localhost for the integration tests to pass.\n\nExamples\n========\n\nFor examples look in the examples/ directory. You can execute the examples using node.\n\n $ cd examples\n $ node queries.js\n\nGridStore\n=========\n\nThe GridStore class allows for storage of binary files in mongoDB using the mongoDB defined files and chunks collection definition.\n\nFor more information have a look at [Gridstore](https://github.com/mongodb/node-mongodb-native/blob/master/docs/gridfs.md)\n\nReplicasets\n===========\nFor more information about how to connect to a replicaset have a look at [Replicasets](https://github.com/mongodb/node-mongodb-native/blob/master/docs/replicaset.md)\n\nPrimary Key Factories\n---------------------\n\nDefining your own primary key factory allows you to generate your own series of id's\n(this could f.ex be to use something like ISBN numbers). The generated the id needs to be a 12 byte long \"string\".\n\nSimple example below\n\n```javascript\n // Custom factory (need to provide a 12 byte array);\n CustomPKFactory = function() {}\n CustomPKFactory.prototype = new Object();\n CustomPKFactory.createPk = function() {\n return new ObjectID(\"aaaaaaaaaaaa\");\n }\n\n var p_client = new Db('integration_tests_20', new Server(\"127.0.0.1\", 27017, {}), {'pk':CustomPKFactory});\n p_client.open(function(err, p_client) {\n p_client.dropDatabase(function(err, done) {\n p_client.createCollection('test_custom_key', function(err, collection) {\n collection.insert({'a':1}, function(err, docs) {\n collection.find({'_id':new ObjectID(\"aaaaaaaaaaaa\")}, function(err, cursor) {\n cursor.toArray(function(err, items) {\n test.assertEquals(1, items.length);\n\n // Let's close the db\n p_client.close();\n });\n });\n });\n });\n });\n });\n```\n\nStrict mode\n-----------\n\nEach database has an optional strict mode. If it is set then asking for a collection\nthat does not exist will return an Error object in the callback. Similarly if you\nattempt to create a collection that already exists. Strict is provided for convenience.\n\n```javascript\n var error_client = new Db('integration_tests_', new Server(\"127.0.0.1\", 27017, {auto_reconnect: false}), {strict:true});\n test.assertEquals(true, error_client.strict);\n\n error_client.open(function(err, error_client) {\n error_client.collection('does-not-exist', function(err, collection) {\n test.assertTrue(err instanceof Error);\n test.assertEquals(\"Collection does-not-exist does not exist. Currently in strict mode.\", err.message);\n });\n\n error_client.createCollection('test_strict_access_collection', function(err, collection) {\n error_client.collection('test_strict_access_collection', function(err, collection) {\n test.assertTrue(collection instanceof Collection);\n // Let's close the db\n error_client.close();\n });\n });\n });\n```\n\nDocumentation\n=============\n\nIf this document doesn't answer your questions, see the source of\n[Collection](https://github.com/mongodb/node-mongodb-native/blob/master/lib/mongodb/collection.js)\nor [Cursor](https://github.com/mongodb/node-mongodb-native/blob/master/lib/mongodb/cursor.js),\nor the documentation at MongoDB for query and update formats.\n\nFind\n----\n\nThe find method is actually a factory method to create\nCursor objects. A Cursor lazily uses the connection the first time\nyou call `nextObject`, `each`, or `toArray`.\n\nThe basic operation on a cursor is the `nextObject` method\nthat fetches the next matching document from the database. The convenience\nmethods `each` and `toArray` call `nextObject` until the cursor is exhausted.\n\nSignatures:\n\n```javascript\n var cursor = collection.find(query, [fields], options);\n cursor.sort(fields).limit(n).skip(m).\n\n cursor.nextObject(function(err, doc) {});\n cursor.each(function(err, doc) {});\n cursor.toArray(function(err, docs) {});\n\n cursor.rewind() // reset the cursor to its initial state.\n```\n\nUseful chainable methods of cursor. These can optionally be options of `find` instead of method calls:\n\n* `.limit(n).skip(m)` to control paging.\n* `.sort(fields)` Order by the given fields. There are several equivalent syntaxes:\n * `.sort({field1: -1, field2: 1})` descending by field1, then ascending by field2.\n * `.sort([['field1', 'desc'], ['field2', 'asc']])` same as above\n * `.sort([['field1', 'desc'], 'field2'])` same as above\n * `.sort('field1')` ascending by field1\n\nOther options of `find`:\n\n* `fields` the fields to fetch (to avoid transferring the entire document)\n* `tailable` if true, makes the cursor [tailable](http://www.mongodb.org/display/DOCS/Tailable+Cursors).\n* `batchSize` The number of the subset of results to request the database\nto return for every request. This should initially be greater than 1 otherwise\nthe database will automatically close the cursor. The batch size can be set to 1\nwith `batchSize(n, function(err){})` after performing the initial query to the database.\n* `hint` See [Optimization: hint](http://www.mongodb.org/display/DOCS/Optimization#Optimization-Hint).\n* `explain` turns this into an explain query. You can also call\n`explain()` on any cursor to fetch the explanation.\n* `snapshot` prevents documents that are updated while the query is active\nfrom being returned multiple times. See more\n[details about query snapshots](http://www.mongodb.org/display/DOCS/How+to+do+Snapshotted+Queries+in+the+Mongo+Database).\n* `timeout` if false, asks MongoDb not to time out this cursor after an\ninactivity period.\n\n\nFor information on how to create queries, see the\n[MongoDB section on querying](http://www.mongodb.org/display/DOCS/Querying).\n\n```javascript\n var mongodb = require('mongodb');\n var server = new mongodb.Server(\"127.0.0.1\", 27017, {});\n new mongodb.Db('test', server, {}).open(function (error, client) {\n if (error) throw error;\n var collection = new mongodb.Collection(client, 'test_collection');\n collection.find({}, {limit:10}).toArray(function(err, docs) {\n console.dir(docs);\n });\n });\n```\n\nInsert\n------\n\nSignature:\n\n```javascript\n collection.insert(docs, options, [callback]);\n```\n\nwhere `docs` can be a single document or an array of documents.\n\nUseful options:\n\n* `safe:true` Should always set if you have a callback.\n\nSee also: [MongoDB docs for insert](http://www.mongodb.org/display/DOCS/Inserting).\n\n```javascript\n var mongodb = require('mongodb');\n var server = new mongodb.Server(\"127.0.0.1\", 27017, {});\n new mongodb.Db('test', server, {w: 1}).open(function (error, client) {\n if (error) throw error;\n var collection = new mongodb.Collection(client, 'test_collection');\n collection.insert({hello: 'world'}, {safe:true},\n function(err, objects) {\n if (err) console.warn(err.message);\n if (err && err.message.indexOf('E11000 ') !== -1) {\n // this _id was already inserted in the database\n }\n });\n });\n```\n\nNote that there's no reason to pass a callback to the insert or update commands\nunless you use the `safe:true` option. If you don't specify `safe:true`, then\nyour callback will be called immediately.\n\nUpdate; update and insert (upsert)\n----------------------------------\n\nThe update operation will update the first document that matches your query\n(or all documents that match if you use `multi:true`).\nIf `safe:true`, `upsert` is not set, and no documents match, your callback will return 0 documents updated.\n\nSee the [MongoDB docs](http://www.mongodb.org/display/DOCS/Updating) for\nthe modifier (`$inc`, `$set`, `$push`, etc.) formats.\n\nSignature:\n\n```javascript\n collection.update(criteria, objNew, options, [callback]);\n```\n\nUseful options:\n\n* `safe:true` Should always set if you have a callback.\n* `multi:true` If set, all matching documents are updated, not just the first.\n* `upsert:true` Atomically inserts the document if no documents matched.\n\nExample for `update`:\n\n```javascript\n var mongodb = require('mongodb');\n var server = new mongodb.Server(\"127.0.0.1\", 27017, {});\n new mongodb.Db('test', server, {w: 1}).open(function (error, client) {\n if (error) throw error;\n var collection = new mongodb.Collection(client, 'test_collection');\n collection.update({hi: 'here'}, {$set: {hi: 'there'}}, {safe:true},\n function(err) {\n if (err) console.warn(err.message);\n else console.log('successfully updated');\n });\n });\n```\n\nFind and modify\n---------------\n\n`findAndModify` is like `update`, but it also gives the updated document to\nyour callback. But there are a few key differences between findAndModify and\nupdate:\n\n 1. The signatures differ.\n 2. You can only findAndModify a single item, not multiple items.\n\nSignature:\n\n```javascript\n collection.findAndModify(query, sort, update, options, callback)\n```\n\nThe sort parameter is used to specify which object to operate on, if more than\none document matches. It takes the same format as the cursor sort (see\nConnection.find above).\n\nSee the\n[MongoDB docs for findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command)\nfor more details.\n\nUseful options:\n\n* `remove:true` set to a true to remove the object before returning\n* `new:true` set to true if you want to return the modified object rather than the original. Ignored for remove.\n* `upsert:true` Atomically inserts the document if no documents matched.\n\nExample for `findAndModify`:\n\n```javascript\n var mongodb = require('mongodb');\n var server = new mongodb.Server(\"127.0.0.1\", 27017, {});\n new mongodb.Db('test', server, {w: 1}).open(function (error, client) {\n if (error) throw error;\n var collection = new mongodb.Collection(client, 'test_collection');\n collection.findAndModify({hello: 'world'}, [['_id','asc']], {$set: {hi: 'there'}}, {},\n function(err, object) {\n if (err) console.warn(err.message);\n else console.dir(object); // undefined if no matching object exists.\n });\n });\n```\n\nSave\n----\n\nThe `save` method is a shorthand for upsert if the document contains an\n`_id`, or an insert if there is no `_id`.\n\nSponsors\n========\nJust as Felix Geisendörfer I'm also working on the driver for my own startup and this driver is a big project that also benefits other companies who are using MongoDB.\n\nIf your company could benefit from a even better-engineered node.js mongodb driver I would appreciate any type of sponsorship you may be able to provide. All the sponsors will get a lifetime display in this readme, priority support and help on problems and votes on the roadmap decisions for the driver. If you are interested contact me on [christkv AT g m a i l.com](mailto:christkv@gmail.com) for details.\n\nAnd I'm very thankful for code contributions. If you are interested in working on features please contact me so we can discuss API design and testing.\n\nRelease Notes\n=============\n\nSee HISTORY\n\nCredits\n=======\n\n1. [10gen](http://github.com/mongodb/mongo-ruby-driver/)\n2. [Google Closure Library](http://code.google.com/closure/library/)\n3. [Jonas Raoni Soares Silva](http://jsfromhell.com/classes/binary-parser)\n\nContributors\n============\n\nAaron Heckmann, Christoph Pojer, Pau Ramon Revilla, Nathan White, Emmerman, Seth LaForge, Boris Filipov, Stefan Schärmeli, Tedde Lundgren, renctan, Sergey Ukustov, Ciaran Jessup, kuno, srimonti, Erik Abele, Pratik Daga, Slobodan Utvic, Kristina Chodorow, Yonathan Randolph, Brian Noguchi, Sam Epstein, James Harrison Fisher, Vladimir Dronnikov, Ben Hockey, Henrik Johansson, Simon Weare, Alex Gorbatchev, Shimon Doodkin, Kyle Mueller, Eran Hammer-Lahav, Marcin Ciszak, François de Metz, Vinay Pulim, nstielau, Adam Wiggins, entrinzikyl, Jeremy Selier, Ian Millington, Public Keating, andrewjstone, Christopher Stott, Corey Jewett, brettkiefer, Rob Holland, Senmiao Liu, heroic, gitfy\n\nLicense\n=======\n\n Copyright 2009 - 2012 Christian Amor Kvalheim.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n\n", "_id": "mongodb@1.2.14", "_from": "mongodb" }