isnode-mod-data v0.0.9

ISNode Data Module

Introduction

This is just a module for the ISNode Framework. To learn how to use the framework, we strongly suggest obtaining a copy of the Hello World example.

The Data Module provides an interface for the framework to access database services. It is model-centric, where the coder may create models and then use these to govern access to data.

Configuration of data connections is not done within the application server configuration file, but is rather done on a service by service basis within the service definition file (service.json). An optional "databaseConnections" array can be set at the root of the service definition file that defines a series of database connection objects. Each object is identified by a unique "name", and the type of database you are connecting to is defined by the "driver" (mongodb, mysql and postgres are supported). Further - the "host" and "database" should be defined. And optionally a "port" (if it differs from the default for that database), "user" and "pass" (if the database is password protected).

Where such an array has been defined against a service, the application server will attempt to connect to that database connection when loading the service at startup. It will then attempt to load all models present in the "./models" folder of the service and make them accessible by name within the "models" object - which is a direct child of the service object (that can be fetched from the services module).

Currently, the most supported database is MongoDB. MySQL has basic support (as long as the database exists and schema is fully defined). PostgreSQL implementation has begun but is not yet in a working state.

  "databaseConnections": [
    {
      "name": "everything",
      "driver": "mongodb",
      "host": "localhost",
      "database": "everything"
    }
  ]

Methods

connect(configObj, cb)

Asynchronous Function. Connects to a data source and loads models. No need to use this if you define your database connections within the service definition file, as connections will automatically occur and models will be automatically loaded.

Input Parameters:

1. configObj - (Object) Configuration Object. See example below
2. cb - (function) Callback function - called once DB is connected and models are loaded

Returns: This method does not return anything.

ConfigObj example

	isnode.module("data").connect({
		name: "DatabaseCxnName",
		service: "ServiceName",
		driver: DB Driver. Eg; "mongodb",
		host: "localhost",
		port: 1234,
		database: "DatabaseName",
		username: "username",
		password: "password"
	});

Example Model Usage

Once you have connected to a database (and models have been loaded) via one of the above methods, you will be able to access those models and run queries against them by using the "get" method on the "models" object - a child of the service object. Queries against models are based on the CaminteJS ORM library. Refer to the website for CaminteJS for more detail and further examples. See an example use case below.

	var service = isnode.module("services").service("example");
	var people = service.models.get("People");
	var query = { where: { gender: "male" } };
	people.find(query, function(err2,results){
		console.log(results);
		/*
			Expect an array of people records to be displayed here, each with all related attributes. Eg:

			[
				{
					"name": "John Smith",
					"gender": "male",
					"email": "john@gmail.com"
				},
				{
					"name": "Peter Peterson",
					"gender": "male",
					"email": "peter.peterson@live.com"
				}
			]
		*/
	}