See also: See also: API reference documentation for loopback-datasource-juggler.

Overview

LoopBack provides a unified API to discover model definition information from relational databases. The same discovery API is available when using any of these connectors:

  • Oracle: loopback-connector-oracle
  • MySQL: loopback-connector-mysql
  • PostgreSQL: loopback-connector-postgresql
  • SQL Server: loopback-connector-mssql

Synchronous methods

The methods described below are asynchronous. For Oracle, there are also corresponding synchronous methods that accomplish the same things and return the same results:

  • discoverModelDefinitionsSync(options)
  • discoverModelPropertiesSync(table, options)
  • discoverPrimaryKeysSync(table, options)
  • discoverForeignKeysSync(table, options)
  • discoverExportedForeignKeysSync(table, options)

Note there are performance implications in using synchronous methods.

Methods

Icon
In general, schema/owner is the name of the table schema. It’s a namespace that contains a list of tables.  Each database uses slightly different terminology:
  • MySQL: databases and schemas are exactly the same thing.
  • Oracle: the schema is the user/owner.
  • PostgreSQL: a database contains one or more named schemas, which in turn contain tables. The schema defaults to "public".
  • MS SQL Server: the schema defaults to "dbo".

discoverAndBuildModels

 

Discover and build models from the specified owner/modelName.

dataSource.discoverAndBuildModels(modelName [, options] [, cb])

 

 

Arguments
NameTypeDescription
modelNameString

The model name.

[options]Object

Options; see below.

[cb]Function

The callback function

 

Options 

NameTypeDescription
owner / schemaString

Database owner or schema name.

relationsBoolean

True if relations (primary key/foreign key) are navigated; false otherwise.

allBoolean

True if all owners are included; false otherwise.

viewsBoolean

True if views are included; false otherwise.

discoverModelDefinitions

Call discoverModelDefinitions() to discover model definitions (table or collection names), based on tables or collections in a data source.   This method returns list of table/view names.

discoverModelDefinitions(options, cb)

Parameters

optionsObject with properties described below.
cbGet a list of table/view names; see example below.
Parameter
Description

Options

PropertyTypeDescription
allBooleanIf true, include tables/views from all schemas/owners
owner/schemaStringSchema/owner name
viewsBooleanIf true, include views.

Example of callback function return value:

{type: 'table', name: 'INVENTORY', owner: 'STRONGLOOP' }
{type: 'table', name: 'LOCATION', owner: 'STRONGLOOP' }
{type: 'view', name: 'INVENTORY_VIEW', owner: 'STRONGLOOP' }

Example

For example:

datasource.discoverModelDefinitions(function (err, models) {
  models.forEach(function (def) {
    // def.name ~ the model name
    datasource.discoverSchema(null, def.name, function (err, schema) {
      console.log(schema);
    });
  });
});

discoverModelProperties

Call discoverModelProperties() to discover metadata on columns (properties) of a database table.  This method returns column information for a given table/view.

discoverModelProperties(table, options, cb)
tableThe name of a table or view
optionsOptions object that can have only the "owner/schema" property to specify the owner or schema name.
cbCallback function to return a list of model property definitions; see example below.
Parameter
Description

Example return value of callback function:

      { owner: 'STRONGLOOP',
        tableName: 'PRODUCT',
        columnName: 'ID',
        dataType: 'VARCHAR2',
        dataLength: 20,
        nullable: 'N',
        type: 'String' }
      { owner: 'STRONGLOOP',
        tableName: 'PRODUCT',
        columnName: 'NAME',
        dataType: 'VARCHAR2',
        dataLength: 64,
        nullable: 'Y',
        type: 'String' }

discoverPrimaryKeys

Call discoverPrimaryKeys() to discover primary key definitions in a database.

discoverPrimaryKeys(table, options, cb)
tableThe name of a table or view
optionsOptions object that can have only the "owner/schema" property to specify the owner or schema name.
cbCallback function to return a list of model property definitions; see example below.
Parameter
Description

Example return value of callback function:

{
  { owner: 'STRONGLOOP',
    tableName: 'INVENTORY',
    columnName: 'PRODUCT_ID',
    keySeq: 1,
    pkName: 'ID_PK' },
  { owner: 'STRONGLOOP',
    tableName: 'INVENTORY',
    columnName: 'LOCATION_ID',
    keySeq: 2,
    pkName: 'ID_PK' }, 
...
}

discoverForeignKeys

Call discoverForeignKeys() to discover foreign key definitions from a database. 

discoverForeignKeys(table, options, cb)
tableThe name of a table or view
optionsOptions object that can have only the "owner/schema" property to specify the owner or schema name.
cbCallback function to return a list of model property definitions; see example below.
Parameter
Description

Example return value of callback function:

{ fkOwner: 'STRONGLOOP',
      fkName: 'PRODUCT_FK',
      fkTableName: 'INVENTORY',
      fkColumnName: 'PRODUCT_ID',
      keySeq: 1,
      pkOwner: 'STRONGLOOP',
      pkName: 'PRODUCT_PK',
      pkTableName: 'PRODUCT',
      pkColumnName: 'ID' }

discoverExportedForeignKeys

Call discoverExportedForeignKeys() to discover foreign key definitions that are exported from a database. 

discoverExportedForeignKeys(table, options, cb)
tableThe name of a table or view
optionsOptions object that can have only the "owner/schema" property to specify the owner or schema name.
cbCallback function to return a list of model property definitions; see example below.
Parameter
Description

Example return value of callback function:

 { fkName: 'PRODUCT_FK',
      fkOwner: 'STRONGLOOP',
      fkTableName: 'INVENTORY',
      fkColumnName: 'PRODUCT_ID',
      keySeq: 1,
      pkName: 'PRODUCT_PK',
      pkOwner: 'STRONGLOOP',
      pkTableName: 'PRODUCT',
      pkColumnName: 'ID' }

discoverSchemas

Use discoverSchema to discover LDL models from a database.  Starting with one table/view, if the relations option is set to true, it follows foreign keys to discover related models.

discoverSchema(modelName [, options] [, cb])

Properties of options parameter:

PropertyTypeDescription
modelNameStringName of model to define
optionsObject 
cbFunctionCallback function

Options

NameTypeDescription
owner / schemaString

Database owner or schema name.

relationsBoolean

If true, the function will follow foreign key relations to discover related tables.

allBoolean

True to include all owners; false otherwise.

viewsBoolean

True to include views; false otherwise.

Example

/server/script.js
dataSource.discoverSchema('INVENTORY', {owner: 'STRONGLOOP'}, function (err, schema) {
    ...
}

The result is shown below.

Icon

The result below is an example for MySQL that contains MySQL-specific properties in addition to the regular LDL model options and properties. The 'mysql' objects contain the MySQL-specific mappings. For other databases, the key 'mysql' would be replaced by the database type, for example 'oracle', and the data type mappings would be different.

/common/models/model.json
{
  "name":"Inventory",
  "options":{
    "idInjection":false,
    "mysql":{
      "schema":"STRONGLOOP",
      "table":"INVENTORY"
    }
  },
  "properties":{
    "productId":{
      "type":"String",
      "required":false,
      "length":60,
      "precision":null,
      "scale":null,
      "id":1,
      "mysql":{
        "columnName":"PRODUCT_ID",
        "dataType":"varchar",
        "dataLength":60,
        "dataPrecision":null,
        "dataScale":null,
        "nullable":"NO"
      }
    },
    "locationId":{
      "type":"String",
      "required":false,
      "length":60,
      "precision":null,
      "scale":null,
      "id":2,
      "mysql":{
        "columnName":"LOCATION_ID",
        "dataType":"varchar",
        "dataLength":60,
        "dataPrecision":null,
        "dataScale":null,
        "nullable":"NO"
      }
    },
    "available":{
      "type":"Number",
      "required":false,
      "length":null,
      "precision":10,
      "scale":0,
      "mysql":{
        "columnName":"AVAILABLE",
        "dataType":"int",
        "dataLength":null,
        "dataPrecision":10,
        "dataScale":0,
        "nullable":"YES"
      }
    },
    "total":{
      "type":"Number",
      "required":false,
      "length":null,
      "precision":10,
      "scale":0,
      "mysql":{
        "columnName":"TOTAL",
        "dataType":"int",
        "dataLength":null,
        "dataPrecision":10,
        "dataScale":0,
        "nullable":"YES"
      }
    }
  }
}

Example of building models via discovery

The following example uses discoverAndBuildModels() to discover, build and try the models.

Note that the string arguments to this function are case-sensitive; specifically the table name (in the example below, 'account') and the owner (schema) name (in the example below, 'demo'). 

 

/server/script.js
dataSource.discoverAndBuildModels('account', {owner: 'demo'}, function (err, models) {
    models.Account.find(function (err, act) {
        if (err) {
            console.error(err);
        } else {
            console.log(act);
        }
        dataSource.disconnect();
    });
});