Update docs
This commit is contained in:
Raymond Feng
parent
27065a0505
commit
94a9e8e9e7
139
README.md
139
README.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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. But it's possible to use more than one datasource to connect with
|
||||
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,15 +142,14 @@ 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 data source.
|
||||
|
|
@ -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
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue