1. Installation & Configuration

Installation & Configuration

1. Install MongoDB and start up an instance of mongod or sign up for a free account with a third party DB service like MongoLab
2. Create a Coldbox application ( box install coldbox && box coldbox create app ) or use an existing one
3. With CommmandBox just type box install cbmongodb from the root of your project.
4. Add your settings (with your own config) to config/Coldbox.cfc

Localhost Example Without Authentication

MongoDB = {
	//an array of servers to connect to
	hosts= [
	{
		serverName='127.0.0.1',
		serverPort='27017'
	}
  ],
  	//The default database to connect to
	db 	= "mydbname",
	//whether to permit viewing of the API documentation
	permitDocs = true,
	//whether to permit unit tests to run
	permitTests = true,
	//whether to permit API access to the Generic API (future implementation)
	permitAPI = true
};

Advanced Connections with Authentication Example

NOTE: Some third-party providers (e.g. MongoLab) use the connnection database as the authentication database. Nine times out of ten, however, the authenticationDB value will be "admin". If you omit that host key, the connection will default to "admin".*

MongoDB = {
	//an array of servers to connect to
	hosts= [

		{
			serverName='ds012345.mongolab.com',
			serverPort='12345',
			//Note that auth credentials are required for the first server only.  All other instances assume duplicate credentials
			username="myUsername",
			password="my53cUr3P455",
			authenticationDB="myremotedb"
		}
		
	  ],
  	//the default client options
	clientOptions = {
		//The connection timeout in ms (if omitted, the timeout is 30000ms)
		"connectTimeout":2000
	},

  	//The default database to connect to
	db 	= "mydbname",
	//whether to permit viewing of the API documentation
	permitDocs = true,
	//whether to permit unit tests to run
	permitTests = true,
	//whether to permit generic API
	permitAPI = true
};

*If using a connection which authenticates against an admin database, MongoDB will create your database if it doesn't exist automatically, so you can use any name you choose for your database (or collections) from the get-go.

Client Options: Advanced connection options may be specified, including readPreference and writeConcern. See the MongoClientOptions Builder documentation for details on available options. If an option is specified which is not available, the Config object will throw an error.

4. Extend your models to use the Active Entity service, add your collection attribute and, optionally, a database attribute - if not specified, the database from your configuration will be used

In your component attributes, you will also need to specify the collection to be used. For those coming from relational databases, for our purposes, a collection is equivalent to a table.

Now all of our operations will be performed on the "peoplecollection" collection (which will created if it doesn't exist).

component name="MyDocumentModel" extends="cbmongodb.models.ActiveEntity" collection="peoplecollection" database="MyNewDatabase" accessors=true{

}