3.8 KiB

Raw Blame History

loopback-data-datasource

Everything about datasource, data types and model definition.

DESCRIPTION

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 different databases.

EVENTS

Instances of DataSource are event emitters, events supported by default:

.on('connected', function() {}): Fired when db connection established. Params: none.
.on('log', function(msg, duration) {}): Fired when connector logged line. Params: String message, Number duration

USAGE

Creating dataSource

DataSource constructor available on loopback-data module:

var DataSource = require('loopback-data').DataSource;

DataSource constructor accepts two arguments. First argument is connector. It could be connector name or connector package:

var dataSourceByConnectorName = new DataSource('memory');
var dataSourceByConnectorModule = new DataSource(require('redis'));

Settings

Second argument is optional settings. Settings object format and defaults depends on specific connector, but common fields are:

host: Database host
port: Database port
username: Username to connect to database
password: Password to connect to database
database: Database name
debug: Turn on verbose mode to debug db queries and lifecycle

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.

Model definition

To define model dataSource have single method dataSource.define. It accepts three argumets:

model name: String name in camel-case with first upper-case letter. This name will be used later to access model.
properties: Object with property type definitions. Key is property name, value is type definition. Type definition can be function representing type of property (String, Number, Date, Boolean), or object with {type: String|Number|..., index: true|false} format.
settings: Object with model-wide settings such as tableName or so.

Examples of model definition:

var User = dataSource.define('User', {
    email: String,
    password: String,
    birthDate: Date,
    activated: Boolean
});

var User = dataSource.define('User', {
    email: { type: String, limit: 150, index: true },
    password: { type: String, limit: 50 },
    birthDate: Date,
    registrationDate: {
        type: Date,
        default: function () { return new Date }
    },
    activated: { type: Boolean, default: false }
}, {
    tableName: 'users'
});

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();
    }
});

3.8 KiB Raw Blame History