Skip to content

Commit 27065a0

Browse files
author
Raymond Feng
committed
Update docs
1 parent cf07563 commit 27065a0

File tree

4 files changed

+250
-2
lines changed

4 files changed

+250
-2
lines changed

‎docs.json

+3-2
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
1010
"depth": 3
1111
},
1212

13-
1413
"lib/model-builder.js",
1514
"lib/types.js",
1615
"lib/geo.js",
@@ -36,7 +35,9 @@
3635
"title": "Base class for SQL connectors",
3736
"depth": 3
3837
},
39-
"lib/sql.js"
38+
"lib/sql.js",
39+
"docs/definition-language.md",
40+
"docs/datasource-connector.md"
4041
],
4142
"codeSectionDepth": 4
4243
}

‎docs/datasource-connector.md

+247
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
## LoopBack DataSource
2+
3+
LoopBack is centered around models, which represent data and behaviors. The concept of `DataSource` is introduced to
4+
encapsulate business logic to exchange data between models and various sources. Data sources are typically databases
5+
that provide create, retrieve, update, and delete (CRUD) functions. LoopBack also generalize other backend services,
6+
such as REST APIs, SOAP Web Services, and Storage Services, as data sources.
7+
8+
Data sources are backed by connectors which implement the data exchange logic. Connectors are not used directly by
9+
application code. The `DataSource` class provides APIs to configure a connector and exposes functions via `DataSource`
10+
or model classes.
11+
12+
![model-datasource-connector](datasource-connector.png "LoopBack Model, DataSource, and Connector")
13+
14+
### Creating dataSource
15+
16+
The `DataSource` constructor available from `loopback-datasource-juggler` module:
17+
18+
var DataSource = require('loopback-datasource-juggler').DataSource;
19+
20+
`DataSource` constructor accepts two arguments:
21+
- connector: The name or instance of the connector module
22+
- settings: An object of properties to configure the connector
23+
24+
var dataSource = new DataSource({
25+
connector: require('loopback-connector-mongodb'),
26+
host: 'localhost',
27+
port: 27017,
28+
database: 'mydb'
29+
});
30+
31+
#### Connector
32+
The connector argument passed the DataSource constructor can be one of the following:
33+
34+
* The connector module from `require(connectorName)`
35+
* The full name of the connector module, such as 'loopback-connector-oracle'
36+
* The short name of the connector module, such as 'oracle', which will be converted to 'loopback-connector-<shortName>'
37+
* A local module under ./connectors/<connectorName> folder
38+
39+
40+
var ds1 = new DataSource('memory');
41+
var ds2 = new DataSource('loopback-connector-mongodb'));
42+
var ds3 = new DataSource(require('loopback-connector-oracle'));
43+
44+
45+
#### Settings
46+
The settings argument configures the connector. Settings object format and defaults
47+
depends on specific connector, but common fields are:
48+
49+
* `host`: Database host
50+
* `port`: Database port
51+
* `username`: Username to connect to database
52+
* `password`: Password to connect to database
53+
* `database`: Database name
54+
* `debug`: Turn on verbose mode to debug db queries and lifecycle
55+
56+
For connector-specific settings refer to connector's readme file.
57+
58+
### Using DataSource to create models
59+
60+
`DataSource` extends from `ModelBuilder`, which is a factory for plain model classes that only have properties.
61+
62+
DataSource is a factory for model classes. DataSource connected with specific database or other
63+
backend system using connector.
64+
65+
All model classes within single datasource shares same connector type and one database
66+
connection. But it's possible to use more than one datasource to connect with
67+
different databases.
68+
69+
### Data Access Object
70+
71+
72+
#### Connecting to database
73+
74+
DataSource connecting to database automatically. Once connection established dataSource
75+
object emit 'connected' event, and set `connected` flag to true, but it is not
76+
necessary to wait for 'connected' event because all queries cached and executed
77+
when dataSource emit 'connected' event.
78+
79+
To disconnect from database server call `dataSource.disconnect` method. This call
80+
forwarded to connector if connector have ability to connect/disconnect.
81+
82+
83+
#### DB structure syncronization
84+
85+
DataSource instance have two methods for updating db structure: automigrate and
86+
autoupdate.
87+
88+
The `automigrate` method drop table (if exists) and create it again,
89+
`autoupdate` method generates ALTER TABLE query. Both method accepts callback
90+
called when migration/update done.
91+
92+
To check if any db changes required use `isActual` method. It accepts single
93+
`callback` argument, which receive boolean value depending on db state: false if
94+
db structure outdated, true when dataSource and db is in sync:
95+
96+
dataSource.isActual(function(err, actual) {
97+
if (!actual) {
98+
dataSource.autoupdate();
99+
}
100+
});
101+
102+
## LoopBack Connectors
103+
104+
| Type | Package Name |
105+
| --------- |:--------------------------------------------------------------------------------------:|
106+
| MongoDB | [loopback-connector-mongodb](https://github.com/strongloop/loopback-connector-mongodb) |
107+
| Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) |
108+
| MySQL | [loopback-connector-mysql](https://github.com/strongloop/loopback-connector-mysql) |
109+
110+
## Build your own connector
111+
112+
LoopBack connectors provide access to backend systems including databases, REST APIs
113+
and other services. Connectors are not used directly by application code. We create
114+
a DataSource to interact with the connector.
115+
116+
For example,
117+
118+
var DataSource = require('loopback-datasource-juggler').DataSource;
119+
var oracleConnector = require('loopback-connector-oracle');
120+
121+
var ds = new DataSource(oracleConnector, {
122+
host : '166.78.158.45',
123+
database : 'XE',
124+
username : 'strongloop',
125+
password : 'str0ng100pjs',
126+
debug : true
127+
});
128+
129+
130+
131+
## Generic connector implementations
132+
133+
A connector module can implement the following methods to interact with the datasource.
134+
135+
exports.initialize = function (dataSource, postInit) {
136+
137+
var settings = dataSource.settings || {}; // The settings is passed in from the dataSource
138+
139+
var connector = new MyConnector(settings); // Construct the connector instance
140+
dataSource.connector = connector; // Attach connector to dataSource
141+
connector.dataSource = dataSource; // Hold a reference to dataSource
142+
143+
/**
144+
* Connector instance can have an optional property named as DataAccessObject that provides
145+
* static and prototype methods to be mixed into the model constructor. The property can be defined
146+
* on the prototype.
147+
*/
148+
connector.DataAccessObject = function {};
149+
150+
/**
151+
* Connector instance can have an optional function to be called to handle data model definitions.
152+
* The function can be defined on the prototype too.
153+
* @param model The name of the model
154+
* @param properties An object for property definitions keyed by propery names
155+
* @param settings An object for the model settings
156+
*/
157+
connector.define = function(model, properties, settings) {
158+
...
159+
};
160+
161+
connector.connect(..., postInit); // Run some async code for initialization
162+
// process.nextTick(postInit);
163+
}
164+
165+
Another way is to directly export the connection function which takes a settings object.
166+
167+
module.exports = function(settings) {
168+
...
169+
}
170+
171+
## CRUD connector implmentations
172+
173+
To support CRUD operations for a model class that is attached to the dataSource/connector, the connector needs to provide
174+
the following functions:
175+
176+
/**
177+
* Create a new model instance
178+
*/
179+
CRUDConnector.prototype.create = function (model, data, callback) {
180+
};
181+
182+
/**
183+
* Save a model instance
184+
*/
185+
CRUDConnector.prototype.save = function (model, data, callback) {
186+
};
187+
188+
/**
189+
* Check if a model instance exists by id
190+
*/
191+
CRUDConnector.prototype.exists = function (model, id, callback) {
192+
};
193+
194+
/**
195+
* Find a model instance by id
196+
*/
197+
CRUDConnector.prototype.find = function find(model, id, callback) {
198+
};
199+
200+
/**
201+
* Update a model instance or create a new model instance if it doesn't exist
202+
*/
203+
CRUDConnector.prototype.updateOrCreate = function updateOrCreate(model, data, callback) {
204+
};
205+
206+
/**
207+
* Delete a model instance by id
208+
*/
209+
CRUDConnector.prototype.destroy = function destroy(model, id, callback) {
210+
};
211+
212+
/**
213+
* Query model instances by the filter
214+
*/
215+
CRUDConnector.prototype.all = function all(model, filter, callback) {
216+
};
217+
218+
/**
219+
* Delete all model instances
220+
*/
221+
CRUDConnector.prototype.destroyAll = function destroyAll(model, callback) {
222+
};
223+
224+
/**
225+
* Count the model instances by the where criteria
226+
*/
227+
CRUDConnector.prototype.count = function count(model, callback, where) {
228+
};
229+
230+
/**
231+
* Update the attributes for a model instance by id
232+
*/
233+
CRUDConnector.prototype.updateAttributes = function updateAttrs(model, id, data, callback) {
234+
};
235+
236+
## Installation
237+
238+
npm install loopback-datasource-juggler
239+
240+
Also install the appropriated connector, for example for mongodb:
241+
242+
npm install loopback-connector-mongodb
243+
244+
check following list of available connectors
245+
246+
247+

‎docs/datasource-connector.png

53 KB
Loading

‎docs/ldl.md renamed to ‎docs/definition-language.md

File renamed without changes.

0 commit comments

Comments
 (0)