Use the loopback-connector module to build a LoopBack connector to back-end data sources such as databases or web services. There are many existing connectors for the most popular data sources; see:
To build a new data source connector that doesn't yet exist, see Building a connector.
Base class for LoopBack connector. This is more a collection of useful methods for connectors than a super class
Helper function to get nested property definition
Name | Type | Description |
---|---|---|
definition |
Object
|
Model name |
propPath |
Array
|
Name | Type | Description |
---|---|---|
result |
Object
|
Property definition |
Hook to be called by DataSource for defining a model
Name | Type | Description |
---|---|---|
modelDefinition |
Object
|
The model definition |
Hook to be called by DataSource for defining a model property
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
propertyName |
String
|
The property name |
propertyDefinition |
Object
|
The object for property definition |
Disconnect from the connector
Name | Type | Description |
---|---|---|
[cb] |
Function
|
Callback function |
Execute a command with given parameters
Name | Type | Description |
---|---|---|
command |
String or Object
|
The command such as SQL |
[params] |
Array
|
An array of parameter values |
[options] |
Object
|
Options object |
[callback] |
Function
|
The callback function |
Generate random id. Each data source model must override this method.
Name | Type | Description |
---|---|---|
modelName |
String
|
Model name |
Name | Type | Description |
---|---|---|
result |
|
Data type varies from model to model, |
Get connector specific settings for a given model, for example,
{
"postgresql": {
"schema": "xyz"
}
}
Name | Type | Description |
---|---|---|
modelName |
String
|
Model name |
Name | Type | Description |
---|---|---|
result |
Object
|
The connector specific settings |
Return the DataAccessObject interface implemented by the connector
Name | Type | Description |
---|---|---|
result |
Object
|
An object containing all methods implemented by the connector that can be mixed into the model class. It should be considered as the interface. |
Look up the data source by model name
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
DataSource
|
The data source |
Get the id value for the given model
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model instance data |
Name | Type | Description |
---|---|---|
result |
|
The id value |
Get the metadata for the connector
Name | Type | Description |
---|---|---|
type |
String
|
The type for the backend |
defaultIdType |
Function
|
The default id type |
[isRelational] |
Boolean
|
If the connector represents a relational database |
schemaForSettings |
Object
|
The schema for settings object |
Name | Type | Description |
---|---|---|
result |
Object
|
The metadata object |
Get the model definition by name
Name | Type | Description |
---|---|---|
modelName |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
ModelDefinition
|
The model definition |
Get model property definition
Name | Type | Description |
---|---|---|
modelName |
String
|
Model name |
propName |
String
|
Property name |
Name | Type | Description |
---|---|---|
result |
Object
|
Property definition |
Get types associated with the connector
Name | Type | Description |
---|---|---|
result |
Array.<String>
|
The types for the connector |
Get the id index (sequence number, starting from 1)
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
prop |
String
|
The property name |
Name | Type | Description |
---|---|---|
result |
Number
|
The id index, undefined if the property is not part of the primary key |
Get the id property name
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
String
|
The id property name |
Get the id property names
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
Array.<String>
|
The id property names |
Test if a property is nullable
Name | Type | Description |
---|---|---|
prop |
Object
|
The property definition |
Name | Type | Description |
---|---|---|
result |
boolean
|
true if nullable |
Check if the connector is for a relational DB
Name | Type | Description |
---|---|---|
result |
Boolean
|
true for relational DB |
Set the id value for the given model
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model instance data |
value |
|
The id value |
Base class for connectors that connect to relational databases using SQL
Replace all instances that match the where clause with the given data
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
data |
Object
|
The property/value object representing changes to be made |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
Find matching model instances by the filter
Please also note the name all
is confusing. Model.find
is to find all
matching instances while Model.findById
is to find an instance by id. On
the other hand, Connector.prototype.all
implements Model.find
while
Connector.prototype.find
implements Model.findById
due to the bad
naming convention we inherited from juggling-db.
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
filter |
Object
|
The filter |
[cb] |
Function
|
The cb function |
Alters a table
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
fields |
Object
|
Fields of the table |
indexes |
Object
|
Indexes of the table |
cb |
Function
|
The callback function |
Build a new SQL statement with pagination support by wrapping the given sql
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
stmt |
ParameterizedSQL
|
The sql statement |
filter |
Object
|
The filter object from the query |
Recreate the tables for the given models
Name | Type | Description |
---|---|---|
[models] |
String or Array.<String>
|
A model name or an array of model names, if not present, apply to all models defined in the connector |
[cb] |
Function
|
The callback function |
Perform autoupdate for the given models
Name | Type | Description |
---|---|---|
[models] |
Array.<String>
|
A model name or an array of model names. If not present, apply to all models |
[cb] |
Function
|
The callback function |
Build a list of escaped column names for the given model and fields filter
Name | Type | Description |
---|---|---|
model |
string
|
Model name |
filter |
object
|
The filter object |
Name | Type | Description |
---|---|---|
result |
string
|
Comma separated string of escaped column names |
Build the DELETE FROM
SQL statement
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
options |
Object
|
Options object |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The SQL DELETE FROM statement |
Build SQL expression
Name | Type | Description |
---|---|---|
columnName |
String
|
Escaped column name |
operator |
String
|
SQL operator |
columnValue |
|
Column value |
propertyValue |
|
Property value |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The SQL expression |
Build an array of fields for the database operation
Name | Type | Description |
---|---|---|
model |
String
|
Model name |
data |
Object
|
Model data object |
excludeIds |
Boolean
|
Exclude id properties or not, default to false |
Name | Type | Description |
---|---|---|
result |
[object Object]
|
Build the SET clause for database replace through update query.
Name | Type | Description |
---|---|---|
model |
String
|
Model name. |
data |
Object
|
The model data object. |
excludeIds |
Boolean
|
Exclude id properties or not, default to true. |
Name | Type | Description |
---|---|---|
result |
string
|
The list of fields for update query. |
Build the SET clause for database update.
Name | Type | Description |
---|---|---|
model |
String
|
Model name. |
data |
Object
|
The model data object. |
excludeIds |
Boolean
|
Exclude id properties or not, default to true. |
Name | Type | Description |
---|---|---|
result |
string
|
The list of fields for update query. |
Build INSERT SQL statement
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model data object |
options |
Object
|
The options object |
Name | Type | Description |
---|---|---|
result |
string
|
The INSERT SQL statement |
Build the clause for default values if the fields is empty
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model data object |
options |
Object
|
Options object |
Name | Type | Description |
---|---|---|
result |
string
|
'DEFAULT VALUES' |
Build the the INSERT INTO
statement
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
fields |
Object
|
Fields to be inserted |
options |
Object
|
Options object |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
Build the clause to return id values after insert
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model data object |
options |
Object
|
Options object |
Name | Type | Description |
---|---|---|
result |
string
|
Build the ORDER BY clause
Name | Type | Description |
---|---|---|
model |
string
|
Model name |
order |
Array.<string>
|
An array of sorting criteria |
Name | Type | Description |
---|---|---|
result |
string
|
The ORDER BY clause |
Map the property type from database to loopback
Name | Type | Description |
---|---|---|
columnDefinition |
Object
|
The columnDefinition of the table/schema |
options |
Object
|
The options for the connector |
Build sql for listing schemas
Name | Type | Description |
---|---|---|
options |
Object
|
Options for discoverDatabaseSchemas |
Build the UPDATE statement for replacing
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
data |
Object
|
The data to be changed |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The UPDATE SQL statement for replacing fields |
Build an array of fields for the replace database operation
Name | Type | Description |
---|---|---|
model |
String
|
Model name |
data |
Object
|
Model data object |
excludeIds |
Boolean
|
Exclude id properties or not, default to false |
Name | Type | Description |
---|---|---|
result |
[object Object]
|
Build a SQL SELECT statement
Name | Type | Description |
---|---|---|
model |
String
|
Model name |
filter |
Object
|
Filter object |
options |
Object
|
Options object |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
Statement object {sql: ..., params: ...} |
Build the UPDATE statement
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
data |
Object
|
The data to be changed |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The UPDATE SQL statement |
Build the SQL WHERE clause for the where object
Name | Type | Description |
---|---|---|
model |
string
|
Model name |
where |
object
|
An object for the where conditions |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The SQL WHERE clause |
Get the column name for the given model property. The column name can be
customized at the model property definition level as column
or
columnName
. For example,
"name": {
"type": "string",
"mysql": {
"column": "NAME"
}
}
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
property |
String
|
The property name |
Name | Type | Description |
---|---|---|
result |
String
|
The column name |
Get the escaped column name for a given model property
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
property |
String
|
The property name |
Name | Type | Description |
---|---|---|
result |
String
|
The escaped column name |
Get the column metadata for the given model property
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
property |
String
|
The property name |
Name | Type | Description |
---|---|---|
result |
Object
|
The column metadata |
Count all model instances by the where filter
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
Create the data model in MySQL
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model instance data |
options |
Object
|
Options object |
[callback] |
Function
|
The callback function |
Create the table for the given model
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
[cb] |
Function
|
The callback function |
Delete all matching model instances
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
Discover database schemas
Name | Type | Description |
---|---|---|
options |
Object
|
Options for discovery |
[cb] |
Function
|
The callback function |
Discover foreign keys that reference to the primary key of this table
Name | Type | Description |
---|---|---|
table |
String
|
The table name |
options |
Object
|
The options for discovery |
[cb] |
Function
|
The callback function |
Discover foreign keys for a given table
Name | Type | Description |
---|---|---|
table |
String
|
The table name |
options |
Object
|
The options for discovery |
[cb] |
Function
|
The callback function |
Discover model definitions
Name | Type | Description |
---|---|---|
options |
Object
|
Options for discovery |
[cb] |
Function
|
The callback function |
Discover model properties from a table
Name | Type | Description |
---|---|---|
table |
String
|
The table name |
options |
Object
|
The options for discovery |
[cb] |
Function
|
The callback function |
Discover primary keys for a given table
Name | Type | Description |
---|---|---|
table |
String
|
The table name |
options |
Object
|
The options for discovery |
[cb] |
Function
|
The callback function |
Drop the table for the given model from the database
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
[cb] |
Function
|
The callback function |
Escape the name for the underlying database
Name | Type | Description |
---|---|---|
name |
String
|
The name |
Name | Type | Description |
---|---|---|
result |
String
|
An escaped name for SQL |
Escape the name for the underlying database
Name | Type | Description |
---|---|---|
value |
String
|
The value to be escaped |
Name | Type | Description |
---|---|---|
result |
|
An escaped value for SQL |
Execute a SQL statement with given parameters.
Name | Type | Description |
---|---|---|
sql |
String
|
The SQL statement |
An |
Array
|
array of parameter values |
[options] |
Object
|
Options object |
[callback] |
Function
|
The callback function |
Execute a SQL statement with given parameters
Name | Type | Description |
---|---|---|
sql |
String
|
The SQL statement |
[params] |
Array
|
An array of parameter values |
[options] |
Object
|
Options object |
[callback] |
Function
|
The callback function |
Check if a model instance exists for the given id value
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
id |
|
The id value |
options |
Object
|
Options object |
cb |
Function
|
The callback function |
Convert the data from database column to model property
Name | Type | Description |
---|---|---|
propertyDef |
object
|
Model property definition |
{*) value Column value |
|
Name | Type | Description |
---|---|---|
result |
|
Model property value |
Transform the row data into a model data object
Name | Type | Description |
---|---|---|
model |
string
|
Model name |
rowData |
object
|
An object representing the row data from DB |
Name | Type | Description |
---|---|---|
result |
object
|
Model data object |
Parse the result for SQL UPDATE/DELETE/INSERT for the number of rows affected
Name | Type | Description |
---|---|---|
model |
String
|
Model name |
info |
Object
|
Status object |
Name | Type | Description |
---|---|---|
result |
Number
|
Number of rows affected |
Get the default data type for ID
Name | Type | Description |
---|---|---|
prop |
|
Property definition Returns {Function} |
Discover default schema of a database
Name | Type | Description |
---|---|---|
options |
Object
|
The options for discovery |
Get the default database schema name
Name | Type | Description |
---|---|---|
result |
string
|
The default schema name, such as 'public' or 'dbo' |
Parse the result for SQL INSERT for newly inserted id
Name | Type | Description |
---|---|---|
model |
String
|
Model name |
info |
Object
|
The status object from driver |
Name | Type | Description |
---|---|---|
result |
|
The inserted id value |
Get the place holder in SQL for identifiers, such as ??
Name | Type | Description |
---|---|---|
key |
String
|
Optional key, such as 1 or id |
Name | Type | Description |
---|---|---|
result |
String
|
The place holder |
Get the place holder in SQL for values, such as :1 or ?
Name | Type | Description |
---|---|---|
key |
String
|
Optional key, such as 1 or id |
Name | Type | Description |
---|---|---|
result |
String
|
The place holder |
Get the status of a table
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
cb |
Function
|
The callback function |
Get types associated with the connector Returns {String[]} The types for the connector
Get the id column name.
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
String
|
The id column name |
Get the escaped id column name
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
String
|
the escaped id column name |
Convert the id value to the form required by database column
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
idValue |
|
The id property value |
Name | Type | Description |
---|---|---|
result |
|
The escaped id column value |
Invoke a prototype method on the super class
Name | Type | Description |
---|---|---|
methodName |
String
|
Method name |
Check if the models exist
Name | Type | Description |
---|---|---|
[models] |
Array.<String>
|
A model name or an array of model names. If not present, apply to all models |
[cb] |
Function
|
The callback function |
Paginate the results returned from database
Name | Type | Description |
---|---|---|
sql |
String
|
The sql to execute |
orderBy |
Object
|
The property name by which results are ordered |
options |
Object
|
Options for discoverDatabaseSchemas |
Replace ?
with connector specific placeholders. For example,
{sql: 'SELECT * FROM CUSTOMER WHERE NAME=?', params: ['John']}
==>
{sql: 'SELECT * FROM CUSTOMER WHERE NAME=:1', params: ['John']}
LIMITATION: We don't handle the ? inside escaped values, for example,
SELECT * FROM CUSTOMER WHERE NAME='J?hn'
will not be parameterized
correctly.
Name | Type | Description |
---|---|---|
ps |
ParameterizedSQL or Object
|
Parameterized SQL |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
Parameterized SQL with the connector specific placeholders |
Get the corresponding property name for the given column name
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
column |
String
|
The column name |
Name | Type | Description |
---|---|---|
result |
String
|
The property name for a given column |
Save the model instance into the database
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
data |
Object
|
The model instance data |
options |
Object
|
Options object |
cb |
Function
|
The callback function |
Get the database schema name for the given model. The schema name can be
customized at model settings or connector configuration level as schema
or
schemaName
. For example,
"Customer": {
"name": "Customer",
"mysql": {
"schema": "MYDB",
"table": "CUSTOMER"
}
}
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
String
|
The database schema name |
Serialize an object into JSON string or other primitive types so that it can be saved into a RDB column
Name | Type | Description |
---|---|---|
obj |
Object
|
The object value |
Name | Type | Description |
---|---|---|
result |
|
Set default options for the connector
Name | Type | Description |
---|---|---|
options |
Object
|
The options for discovery |
Set the nullable value for the property
Name | Type | Description |
---|---|---|
property |
Object
|
The property to set nullable |
Get fields from a table
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
cb |
Function
|
The callback function |
Get indexes from a table
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
cb |
Function
|
The callback function |
Get the table name for the given model. The table name can be customized
at model settings as table
or tableName
. For example,
"Customer": {
"name": "Customer",
"mysql": {
"table": "CUSTOMER"
}
}
Returns the table name (String).
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Get the escaped table name
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
Name | Type | Description |
---|---|---|
result |
String
|
the escaped table name |
Converts a model property value into the form required by the database column. The result should be one of following forms:
Name | Type | Description |
---|---|---|
propertyDef |
Object
|
Model property definition |
value |
|
Model property value |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
Database column value. |
Update all instances that match the where clause with the given data
Name | Type | Description |
---|---|---|
model |
String
|
The model name |
where |
Object
|
The where object |
data |
Object
|
The property/value object representing changes to be made |
options |
Object
|
The options object |
cb |
Function
|
The callback function |
A class for parameterized SQL clauses
Name | Type | Description |
---|---|---|
sql |
String or Object
|
The SQL clause. If the value is a string, treat it as the template using |
params |
Array
|
An array of parameter values. The length should match the number of placeholders in the template |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
A new instance of ParameterizedSQL |
Append the statement into the current statement
Name | Type | Description |
---|---|---|
currentStmt |
Object
|
The current SQL statement |
stmt |
Object
|
The statement to be appended |
[separator] |
String
|
Separator, default to |
Name | Type | Description |
---|---|---|
result |
|
The merged statement |
Join multiple parameterized SQLs into one
Name | Type | Description |
---|---|---|
sqls |
Array.<Object>
|
An array of parameterized SQLs |
[separator] |
String
|
Separator, default to |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
Merge the parameterized sqls into the current instance
Name | Type | Description |
---|---|---|
ps |
Object or Array.<Object>
|
A parametered SQL or an array of parameterized SQLs |
[separator] |
String
|
Separator, default to |
Name | Type | Description |
---|---|---|
result |
ParameterizedSQL
|
The current instance |