README
sails-mongo
Sails.js/Waterline adapter for MongoDB.
Heads up
sails-mongo
maps the logicalid
attribute to the required_id
physical-layer mongo id. In the current version ofsails-mongo
, you should not sort byid
.
Installation
Install from NPM.
$ npm install sails-mongo --save
Usage
Note: The following instructions are for apps using at least Sails v0.10.x, up through v0.12.x.
- For help with legacy versions of Sails, see #Legacy Usage below.
- To use sails-mongo with the Sails v1 / Waterline 0.13 prerelease, see the 1.0 branch of sails-docs.
After installing this adapter as a dependency of your Sails app, make this particular Mongo database your default datastore by adding the following settings to the files in your config folder:
// config/connections.js
module.exports.connections = {
localMongoDb: {
adapter: 'sails-mongo',
host: 'localhost', // defaults to `localhost` if omitted
port: 27017, // defaults to 27017 if omitted
user: 'username_here', // or omit if not relevant
password: 'password_here', // or omit if not relevant
database: 'database_name_here' // or omit if not relevant
}
};
// config/models.js
module.exports.models = {
'connection': 'localMongoDb'
};
For more information about configuring datastores in your Sails app, click here.
What about production?
In production, use config/env/production.js and/or environment variables.
For more about getting your Sails app ready for production, see Concepts > Deployment.
Bugs
To report a bug, click here.
Help
If you have questions or need help, click here.
FAQ
What about MongoDB urls?
You can follow MongoDB URI Connection Settings specification on how to define a connection string URI.
Following there is an example on how to configure the connection to your MongoDB server using a URL. e.g.:
module.exports.connections = {
localMongoDb: {
adapter: 'sails-mongo',
url: 'mongodb://heroku_12345678:random_password@ds029017.mLab.com:29017/heroku_12345678'
}
};
You could also use an environment variable, to ease your deployments, for example, to Heroku , as follows:
module.exports.connections = {
localMongoDb: {
adapter: 'sails-mongo',
url: process.env.MONGODB_URI
}
};
This would be useful if, for instance, your Heroku env variables looked like:
MONGODB_URI=mongodb://heroku_12345678:random_password@ds029017.mLab.com:29017/heroku_12345678
It must be noted though, that if you provide a url
configuration, then, database
, user
, password
, host
and port
configuration options are ignored.
What about a MongoDB deployment that is part of a Replica Set?
For example:
MONGODB_URI=mongodb://mongodbserver01:27017,mongodbserver02:27017,mongodbserver03:27017/my-app-datatabase?replSet=my-replica-set-name&readPreference=nearest&slaveOk=true
The previous configuration will set three MongoDB servers, named mongodbserver01
, mongodbserver02
and mongodbserver03
, all using port 27017
, connecting to the my-app-database
and using my-replica-set-name
as the replica set. It also sets the readPreference
to nearest
and allows slave connections, with slaveOk
set to true
Legacy usage
Using with Sails v0.9.x
Add the mongo config to the config/adapters.js
file.
module.exports.adapters = {
'default': 'mongo',
mongo: {
module: 'sails-mongo',
host: 'localhost',
port: 27017,
user: 'username',
password: 'password',
database: 'your mongo db name here',
wlNext: {
caseSensitive: false
}
}
};
Note: You can also use the old v0.8.x
syntax as well, see next section for details.
Replication/Replica Set can be setup by adding the following options to the mongo
object,
with your own replica details specified:
replSet: {
servers: [
{
host: 'secondary1.localhost',
port: 27017 // Will override port from default config (optional)
},
{
host: 'secondary2.localhost',
port: 27017
}
],
options: {} // See http://mongodb.github.io/node-mongodb-native/api-generated/replset.html (optional)
}
Note: Replica set configuration is optional.
Using with Sails v0.8.x
module.exports.adapters = {
'default': 'mongo',
mongo: {
module: 'sails-mongo',
url: 'mongodb://USER:PASSWORD@HOST:PORT/DB'
}
};
Don't forget that Mongo uses the ObjectId type for ids.
Contributing
Please observe the guidelines and conventions laid out in the Sails project contribution guide when opening issues or submitting pull requests.
Special thanks
Thanks so much to Ted Kulp (@tedkulp) and Robin Persson (@prssn) for building the first version of this adapter back in 2013. Since then, it has evolved into a core adapter within the framework.
License
MIT
© 2013 Ted Kulp, Robin Persson, Cody Stoltman, Mike McNeil, Balderdash Design Co. © 2014 Balderdash Design Co. © 2015-2016 The Treeline Co.
Like the Sails framework, this adapter is free and open-source under the MIT License.