Overview
The diagram illustrates the relationship between LoopBack Model
, DataSource
, and Connector
.
Define the model using LoopBack Definition Language (LDL). This provides a model definition in JSON or as a JavaScript object.
Create an instance of
ModelBuilder
orDataSource
.DataSource
extends fromModelBuilder
. ModelBuilder is responsible for compiling model definitions to JavaScript constructors representing model classes. DataSource inherits that function from ModelBuilder.Use
ModelBuilder
orDataSource
to build a JavaScript constructor (i.e. the model class) from the model definition. Model classes built fromModelBuilder
can be later attached to a DataSource to receive the mixin of data access functions.As part of step 2,
DataSource
initializes the underlyingConnector
with a settings object which provides configurations to the connector instance.Connector
collaborates withDataSource
to define the functions asDataAccessObject
to be mixed into the model class. TheDataAccessObject
consists of a list of static and prototype methods. It can be CRUD operations or other specific functions depending on the connector's capabilities.
The DataSource
object is the unified interface for LoopBack applications to integrate with backend systems. It's a factory for data access logic around model classes. With the ability to plug in various connectors, DataSource
provides the necessary abstraction to interact with databases or services to decouple the business logic from plumbing technologies.
Creating a DataSource programmatically
The DataSource
constructor is in loopback-datasource-juggler
. The DataSource constructor accepts two arguments:
- connector: The name or instance of the connector module.
- settings: An object of properties to configure the connector.
For example:
var DataSource = require('loopback-datasource-juggler').DataSource; var dataSource = new DataSource({ connector: require('loopback-connector-mongodb'), host: 'localhost', port: 27017, database: 'mydb' });
The connector
argument passed the DataSource
constructor can be one of the following:
- The connector module from
require(connectorName)
- The full name of the connector module, such as 'loopback-connector-oracle'
- The short name of the connector module, such as 'oracle', which will be converted to 'loopback-connector-'
- A local module under ./connectors/ folder
var ds1 = new DataSource('memory'); var ds2 = new DataSource('loopback-connector-mongodb')); var ds3 = new DataSource(require('loopback-connector-oracle'));
LoopBack provides the built-in memory connector that uses in-memory store for CRUD operations.
The settings
argument configures the connector. Settings object format and defaults depends on specific connector, but common fields are:
host
: Database hostport
: Database portusername
: Username to connect to databasepassword
: Password to connect to databasedatabase
: Database namedebug
: Turn on verbose mode to debug db queries and lifecycle
For connector-specific settings, see the connector's documentation.
Creating a model from a data source
DataSource
extends from ModelBuilder
, which is a factory for plain model classes that only have properties. DataSource
connects to databases and other backend systems using Connector
.
var DataSource = require('loopback-datasource-juggler').DataSource; 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 share the same connector type and one database connection or connection pool. But it's possible to use more than one data source to connect to different databases.
ModelBuilder
to a DataSource
.var ModelBuilder = require('loopback-datasource-juggler').ModelBuilder; var builder = new ModelBuilder(); var User = builder.define('User', { name: String, bio: String, approved: Boolean, joinedAt: Date, age: Number }); var DataSource = require('loopback-datasource-juggler').DataSource; var ds = new DataSource('memory'); User.attachTo(ds); // The CRUD methods will be mixed into the User constructor
Creating a data source for a connector
Application code does not directly use a connector. Rather, you create a DataSource to interact with the connector.
The simplest example is for the in-memory connector:
var memory = loopback.createDataSource({ connector: loopback.Memory });
Here is another example, this time for the Oracle connector:
var DataSource = require('loopback-datasource-juggler').DataSource; var oracleConnector = require('loopback-connector-oracle'); var ds = new DataSource(oracleConnector, { host : 'localhost', database : 'XE', username : 'username', password : 'password', debug : true });
The connector argument passed the DataSource constructor can be one of the following:
- The connector module from
require('connectorName')
- The full name of the connector module, such as
'loopback-connector-oracle'
. - The short name of the connector module, such as
'oracle'
, that LoopBack converts to'loopback-connector-oracle'
(for example). - A local module in the
/connectors
folder
Initializing a connector
The connector module can export an initialize
function to be called by the owning DataSource instance.
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 ... };
The DataSource calls the initialize
method with itself and an optional postInit
callback function. The connector receives the settings from the dataSource
argument and use it to configure connections to backend systems.
Please note connector and dataSource set up a reference to each other.
Upon initialization, the connector might connect 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 is forwarded to the connector if the connector have ability to connect/disconnect.