loopback-models
Role | Name | Email | Slack
---- | ---- | ----- | -----
Product Owner | Ryan Borker | borker@gigster.com | @borker
Maintainer | Jerome Curlier | jerome@gigster.com | @jerome
Contributor | Mark Miyashita | mark.miyashita@gigster.com | @markOverview
This module maps the project models defined ingig.yaml to the Loopback model format.Usage
- name: loopback-models
location: https://github.com/liquidlabs-co/gig-modules/tree/master/block/loopback-models
spec:
defaultDatasource: fileDs
defaultEmailDatasource: email
generateTests: true
models:
- name: user
methods:
enabled:
- create
- patchOrCreate
- replaceOrCreateSpecification
Name | Status ---- | ----- defaultDatasource | Default datasource to be used by the models when no datasource is defined for them defaultEmailDatasource | Default email datasource generateTests | Set to true to generate model tests (unit + API tests) enabled | Methods to enable, disable all others, see Method visibility. disabled | Methods to disable, enable all others, see Method visibility.Endpoints
The modules generate the endpoinds for the CRUD opertations on the models:Endpoint | Method | Description ---- | ---- | ----- POST /users | create | Create a new instance of the model and persist it into the data source PATCH /users | patchOrCreate | Patch an existing model instance or insert a new one into the data source PUT /users | replaceOrCreate | Replace an existing model instance or insert a new one into the data source POST /users/{id} | replaceOrCreate | Replace an existing model instance or insert a new one into the data source HEAD /users/{id} | exists | Check whether a model instance exists in the data source GET /users/{id} | exists | Check whether a model instance exists in the data source GET /users/{id} | findById | Find a model instance by {{id}} from the data source PUT /users/{id} | replaceById | Replace attributes for a model instance and persist it into the data source. POST /users/{id}/replace | replaceById | Replace attributes for a model instance and persist it into the data source GET /users | find | Find all instances of the model matched by filter from the data source. GET /users/{id} | findOne | Find first instance of the model matched by filter from the data source. POST /users/{id} | updateAll | Update instances of the model matched by {{where}} from the data source. DELETE /users/{id} | deleteById | Delete a model instance by {{id}} from the data source GET /users/count | count | Count instances of the model matched by where from the data source PATCH /users/{id} | prototype.patchAttributes | Patch attributes for a model instance and persist it into the data source
The list does not show the Loopback streaming endpoints, as well as the endpoints provided by the relationship between models (see Loopback documentation).
The Loopback explorer provides a Swagger interface to the endpoints.
Note: Methods can be enabled and disabled through the module configuration.
Method visibility
By default all the methods generated by Loopback and defined in the project are enabled.- If you would like to disable one or several methods, set the name of the methods in the
disabledspecification for a given model. - If you would like to only enable one or several methods, set the name of the methods in the
enabledspecification for a given model.
You can only use either
disabled or enabled. disabled configuration will take precedence over enabled.See the section Find the enable method names to log the name of the methods. The Loopback explorer interface provides the method name on mouseover.
Dependencies
The following npm packages are used (only if one of the datasource defined requires it):npm | version ---- | ----- loopback-connector-mongodb | ^3.3.0 loopback-connector-mysql | ^5.2.0 loopback-connector-postgresql | ^3.2.0
Database
The datasources section specify the database used by the model.Name | Status ---- | ----- name | Name of the datasource type | Type of the datasource (one of email, file, memory, mongodb, mysql, postgresql spec | Configuration for the datasource
See Creating a database schema from models
Sample datasources configuration
datasources:
- name: mysqlDs
type: mysql
spec:
host: DATABASE_MYSQL_HOST
port: DATABASE_MYSQL_PORT
database: DATABASE_MYSQL_DATABASE
user: DATABASE_MYSQL_USER
password: DATABASE_MYSQL_PASSWORD
- name: mongoDs
type: mongodb
spec:
url: DATABASE_MONGODB_URL
- name: postgresqlDs
type: postgresql
spec:
host: DATABASE_POSTGRESQL_HOST
port: DATABASE_POSTGRESQL_PORT
database: DATABASE_POSTGRESQL_DATABASE
user: DATABASE_POSTGRESQL_USER
password: DATABASE_POSTGRESQL_PASSWORD
- name: email
type: email
spec:
host: EMAIL_HOST
port: EMAIL_PORT
secure: EMAIL_SECURE
user: EMAIL_USER
password: EMAIL_PASSWORD
- name: memoryDs
type: memory
- name: fileDs
type: fileNote that:
- we can have a default datasource as specified by the module specification.
- we can have a different datasource for each model even if the models are related.
Utilities
Name | Description | Command ---- | ----- | -----create.js | Uses Loopback automigrate to create a database | DEBUG=loopback:models node ./database/create.js
update.js | Uses Loopback autoupdate to update a database schmea| DEBUG=loopback:models node ./database/update.jsSee Creating a database schema from models
MongoDB
Configuration
- name: mongodbDs
type: mongodb
spec:
host: GIG_HOST
port: GIG_PORT
url: GIG_URL
database: GIG_DATABASE
```
The values in uppercase are the name of the environment variables to get the information at runtime.
##### Docker
```bash
docker pull mongo
docker run -p 27017:27017 --name mongo -d mongoMySQL
Configuration
- name: myqlDs
type: mysql
spec:
host: GIG_HOST
port: GIG_PORT
url: GIG_URL
database: GIG_DATABASE
```
The values in uppercase are the name of the environment variables to get the information at runtime.
##### Docker
```bash
docker pull mysql
docker run -p 3306:3306 --name some-mysql -e MYSQL_ROOT_PASSWORD=passw0rd -d mysqlNote: A databse needs to be ceated first.
mysql --protocol=TCP -u root -pCREATE SCHEMA `test` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;PostgreSQL
- name: postgreslqDs
type: postgreslq
spec:
host: GIG_HOST
port: GIG_PORT
url: GIG_URL
database: GIG_DATABASE
```
The values in uppercase are the name of the environment variables to get the information at runtime.
##### Docker
```sql
docker pull postgres:latest
docker run -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgresPlease login into postgres using the user
postgrespsql postgres://127.0.0.1:5432 -U postgresCREATE DATABASE `test`;Memory
This datasource uses the memory to maintain the data, and therefore the data is lost when the application is stopped.Configuration
- name: memoryDs
type: memoryFile
The datasource uses the filedb.json to maintain the data. The file is located at the root of the project.Configuration
- name: fileDs
type: fileConfiguration
- name: email
type: email
spec:
host: EMAIL_HOST
port: EMAIL_PORT
secure: EMAIL_SECURE
user: EMAIL_USER
password: EMAIL_PASSWORDThe name must be email and only one configuration is supported.
The values in uppercase are the name of the environment variables to get the information at runtime.
Generation
Models
For each model, the module generates the Loopback model.json and model.jsm a file for each custom method - using the method skeleton of the model - and one validation file.Database
The module generates two files in the database folder to create and update database schemas.Name | Status ---- | ----- create.js | Uses Loopback automigrate to create a database update.js | Uses Loopback autoupdate to update a database schmea
The configuration for the datasources is generated in the file datasources.local.js.
Tests
Module tests are defined using atest/scenarios.yaml file. This file defines the set of example gigs that we generate as part of integration testing. To run all tests, run yarn test at the root of this module.Each scenario is generated in
test/scenario/<name> which you can then cd into and run the actual app. For a scenario called default, this is done via:cd test/scenario/default
yarn install
# Run tests.
yarn test
# Start the app.
yarn startTroubleshooting
DEBUG=gdt:loopback:models npm startFind the enable method names
DEBUG=loopback:contrib:setup-remote-methods-mixin npm startAppendix
Project definition support
The following table list the attributes from the project defintion that are mapped by the module.Name | Status ---- | ----- name | :whitecheckmark: datasource | :whitecheckmark: description | :whitecheckmark: type | :whitecheckmark: default | :whitecheckmark: defaultFn | :whitecheckmark: unique | :whitecheckmark: id | :whitecheckmark: obscured| :x: nullable| :x: hidden | :whitecheckmark:
