loopback-models

Role | Name | Email | Slack ---- | ---- | ----- | ----- Product Owner | Ryan Borker | [email protected] | [@borker] Maintainer | Jerome Curlier | [email protected] | [@jerome] Contributor | Mark Miyashita | [email protected] | [@mark]

Overview

This module maps the project models defined in gig.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
            - replaceOrCreate

Specification

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 disabled specification for a given model.
• If you would like to only enable one or several methods, set the name of the methods in the enabled specification 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: file

Note 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.js

See 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

docker pull mongo
docker run -p 27017:27017 --name mongo -d mongo

MySQL

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

docker pull mysql
docker run -p 3306:3306 --name some-mysql -e MYSQL_ROOT_PASSWORD=passw0rd -d mysql

Note: A databse needs to be ceated first.

mysql --protocol=TCP -u root -p

CREATE 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

docker pull postgres:latest
docker run -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgres

Please login into postgres using the user postgres

psql postgres://127.0.0.1:5432 -U postgres

CREATE 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: memory

File

The datasource uses the file db.json to maintain the data. The file is located at the root of the project.

Configuration

  - name: fileDs
    type: file

Email

Configuration

- name: email
    type: email
    spec:
      host: EMAIL_HOST
      port: EMAIL_PORT
      secure: EMAIL_SECURE
      user: EMAIL_USER
      password: EMAIL_PASSWORD

The 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 a test/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 start

Troubleshooting

DEBUG=gdt:loopback:models npm start

Find the enable method names

DEBUG=loopback:contrib:setup-remote-methods-mixin npm start

Appendix

Project definition support

The following table list the attributes from the project defintion that are mapped by the module.

Name | Status ---- | ----- name | :white_check_mark: datasource | :white_check_mark: description | :white_check_mark: type | :white_check_mark: default | :white_check_mark: defaultFn | :white_check_mark: unique | :white_check_mark: id | :white_check_mark: obscured| :x: nullable| :x: hidden | :white_check_mark:

Validation

Name | Status ---- | ----- required | :white_check_mark: min | :white_check_mark: max | :white_check_mark: pattern | :white_check_mark: enum | :white_check_mark: format| :x:

ACLs

Name | Status ---- | ----- accessType | :white_check_mark: method | :white_check_mark: permission | :white_check_mark: principalId | :white_check_mark: principalType | :white_check_mark:

Datasources

Name | Status ---- | ----- name | :white_check_mark: type | :white_check_mark: spec | :white_check_mark:

Indexes

Name | Status ---- | ----- name | :white_check_mark: keys | :white_check_mark: unique | :white_check_mark:

Methods

Name | Status ---- | ----- description | :white_check_mark: input | :white_check_mark: name | :white_check_mark: notes | :white_check_mark: output | :white_check_mark:

Options for API

Name | Status ---- | ----- method | :white_check_mark: description | :white_check_mark: errorStatus | :white_check_mark: input | :white_check_mark: input name | :white_check_mark: input source | :white_check_mark: name | :white_check_mark: path | :white_check_mark: status | :white_check_mark: verb | :white_check_mark:

Relations

Name | Status ---- | ----- name | :white_check_mark: type | :white_check_mark: model | :white_check_mark: primaryKey | :white_check_mark: foreignKey | :white_check_mark: through | :white_check_mark: keyThrough | :white_check_mark: