verdnatura-mirror
/
loopback-datasource-juggler
mirror of https://github.com/loopbackio/loopback-datasource-juggler
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs

This commit is contained in:
Raymond Feng 2013-08-20 17:05:13 -07:00
parent 27065a0505
commit 94a9e8e9e7
2 changed files with 45 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
README.md
View File

@ -1,7 +1,7 @@
# LoopBack DataSource Juggler
LoopBack DataSource Juggler is an ORM that provides a common set of interfaces for interacting with databases, REST APIs, and other data sources.
It was initially forked from [JugglingDB](https://github.com/1602/jugglingdb).
LoopBack DataSource Juggler is an ORM that provides a common set of interfaces for interacting with databases, REST APIs,
and other data sources. It was initially forked from [JugglingDB](https://github.com/1602/jugglingdb).
## Overview
@ -86,36 +86,6 @@ depends on specific connector, but common fields are:
For connector-specific settings refer to connector's readme file.
#### Connecting to database
DataSource connecting to database automatically. Once connection established dataSource
object emit 'connected' event, and set `connected` flag to true, but it is not
necessary to wait for 'connected' event because all queries cached and executed
when dataSource emit 'connected' event.
To disconnect from database server call `dataSource.disconnect` method. This call
forwarded to connector if connector have ability to connect/disconnect.
#### DB structure syncronization
DataSource instance have two methods for updating db structure: automigrate and
autoupdate.
The `automigrate` method drop table (if exists) and create it again,
`autoupdate` method generates ALTER TABLE query. Both method accepts callback
called when migration/update done.
To check if any db changes required use `isActual` method. It accepts single
`callback` argument, which receive boolean value depending on db state: false if
db structure outdated, true when dataSource and db is in sync:
dataSource.isActual(function(err, actual) {
if (!actual) {
dataSource.autoupdate();
}
});
## LoopBack Connectors
| Type | Package Name |
@ -124,7 +94,6 @@ db structure outdated, true when dataSource and db is in sync:
| Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) |
| MySQL | [loopback-connector-mysql](https://github.com/strongloop/loopback-connector-mysql) |
## Build your own connector
LoopBack connectors provide access to backend systems including databases, REST APIs
and other services. Connectors are not used directly by application code. We create
@ -150,110 +119,6 @@ The connector argument passed the DataSource constructor can be one of the follo
* The short name of the connector module, such as 'oracle', which will be converted to 'loopback-connector-<shortName>'
* A local module under ./connectors/<connectorName> folder
## Generic connector implmentations
A connector module can implement the following methods to interact with the datasource.
exports.initialize = function (dataSource, postInit) {
var settings = dataSource.settings || {}; // The settings is passed in from the dataSource
var connector = new MyConnector(settings); // Construct the connector instance
dataSource.connector = connector; // Attach connector to dataSource
connector.dataSource = dataSource; // Hold a reference to dataSource
/**
* Connector instance can have an optional property named as DataAccessObject that provides
* static and prototype methods to be mixed into the model constructor. The property can be defined
* on the prototype.
*/
connector.DataAccessObject = function {};
/**
* Connector instance can have an optional function to be called to handle data model definitions.
* The function can be defined on the prototype too.
* @param model The name of the model
* @param properties An object for property definitions keyed by propery names
* @param settings An object for the model settings
*/
connector.define = function(model, properties, settings) {
...
};
connector.connect(..., postInit); // Run some async code for initialization
// process.nextTick(postInit);
}
Another way is to directly export the connection function which takes a settings object.
module.exports = function(settings) {
...
}
## CRUD connector implmentations
To support CRUD operations for a model class that is attached to the dataSource/connector, the connector needs to provide
the following functions:
/**
* Create a new model instance
*/
CRUDConnector.prototype.create = function (model, data, callback) {
};
/**
* Save a model instance
*/
CRUDConnector.prototype.save = function (model, data, callback) {
};
/**
* Check if a model instance exists by id
*/
CRUDConnector.prototype.exists = function (model, id, callback) {
};
/**
* Find a model instance by id
*/
CRUDConnector.prototype.find = function find(model, id, callback) {
};
/**
* Update a model instance or create a new model instance if it doesn't exist
*/
CRUDConnector.prototype.updateOrCreate = function updateOrCreate(model, data, callback) {
};
/**
* Delete a model instance by id
*/
CRUDConnector.prototype.destroy = function destroy(model, id, callback) {
};
/**
* Query model instances by the filter
*/
CRUDConnector.prototype.all = function all(model, filter, callback) {
};
/**
* Delete all model instances
*/
CRUDConnector.prototype.destroyAll = function destroyAll(model, callback) {
};
/**
* Count the model instances by the where criteria
*/
CRUDConnector.prototype.count = function count(model, callback, where) {
};
/**
* Update the attributes for a model instance by id
*/
CRUDConnector.prototype.updateAttributes = function updateAttrs(model, id, data, callback) {
};
## Installation

72
docs/datasource-connector.md
View File

@ -29,6 +29,7 @@ The `DataSource` constructor available from `loopback-datasource-juggler` module
});
#### Connector
The connector argument passed the DataSource constructor can be one of the following:
* The connector module from `require(connectorName)`
@ -43,6 +44,7 @@ The connector argument passed the DataSource constructor can be one of the follo
#### Settings
The settings argument configures the connector. Settings object format and defaults
depends on specific connector, but common fields are:
@ -62,14 +64,31 @@ For connector-specific settings refer to connector's readme file.
DataSource is a factory for model classes. DataSource connected with specific database or other
backend system using connector.
All model classes within single datasource shares same connector type and one database
connection. But it's possible to use more than one datasource to connect with
var ds = new DataSource('memory');
var User = ds.define('User', {
name: String,
bio: String,
approved: Boolean,
joinedAt: Date,
age: Number
});
All model classes within single data source shares same connector type and one database
connection or connection pool. But it's possible to use more than one data source to connect with
different databases.
### Data Access Object
Alternatively, a plain model constructor created from `ModelBuilder` can be attached a `DataSource`.
var ds = new DataSource('memory');
User.attachTo(ds); // The CRUD methods will be mixed into the User constructor
What behaviors does data source add to the model? The methods are contributed by the underlying connector
through the data access object.
### Injecting behaviors to the model
#### Connecting to database
### Connecting to database
DataSource connecting to database automatically. Once connection established dataSource
object emit 'connected' event, and set `connected` flag to true, but it is not
@ -80,22 +99,26 @@ To disconnect from database server call `dataSource.disconnect` method. This cal
forwarded to connector if connector have ability to connect/disconnect.
#### DB structure syncronization
### Synchronizing model definitions and database tables
DataSource instance have two methods for updating db structure: automigrate and
autoupdate.
DataSource instance have two methods for updating db structure: `automigrate` and `autoupdate` for relational
databases.
The `automigrate` method drop table (if exists) and create it again,
`autoupdate` method generates ALTER TABLE query. Both method accepts callback
called when migration/update done.
The `automigrate` method drop table (if exists) and create it again, `autoupdate` method generates
ALTER TABLE query. Both method accepts an optional array of model names and a callback function to be
called when migration/update done. If the `models` argument is not present, all models are checked.
To check if any db changes required use `isActual` method. It accepts single
`callback` argument, which receive boolean value depending on db state: false if
db structure outdated, true when dataSource and db is in sync:
To check if any db changes required use `isActual` method. It accepts
and a `callback` argument, which receive boolean value depending on db state:
dataSource.isActual(function(err, actual) {
- false if db structure outdated
- true when dataSource and db is in sync
dataSource.isActual(models, function(err, actual) {
if (!actual) {
dataSource.autoupdate();
dataSource.autoupdate(models, function(err, result) {
...
});
}
});
@ -119,18 +142,17 @@ For example,
var oracleConnector = require('loopback-connector-oracle');
var ds = new DataSource(oracleConnector, {
host : '166.78.158.45',
host : 'localhost',
database : 'XE',
username : 'strongloop',
password : 'str0ng100pjs',
password : 'strongloop',
debug : true
});
## Generic connector implementations
A connector module can implement the following methods to interact with the datasource.
A connector module can implement the following methods to interact with the data source.
exports.initialize = function (dataSource, postInit) {
@ -168,7 +190,7 @@ Another way is to directly export the connection function which takes a settings
...
}
## CRUD connector implmentations
## CRUD connector implementations
To support CRUD operations for a model class that is attached to the dataSource/connector, the connector needs to provide
the following functions:
@ -233,15 +255,7 @@ the following functions:
CRUDConnector.prototype.updateAttributes = function updateAttrs(model, id, data, callback) {
};
## Installation
npm install loopback-datasource-juggler
Also install the appropriated connector, for example for mongodb:
npm install loopback-connector-mongodb
check following list of available connectors