Loopback-next: Add the doc for datasource migration

[andenis]

this feature works?

---

Update by @jannyhou

Description

We are missing the datasource migration doc in loopback.io.

Acceptance criteria:

• [ ] Add the doc for how to call datasource functions in LB4 as the same way in LB3.
• [ ] Add a section for running ds.automigrate() / ds.autoupdate() and other datasource methods (include a list of what it is and what they do).
• [ ] Make sure the doc is verified by a working code.

[jannyHou]

@andenis I believe migrating models to postgreSQL works. Please make sure you run db.automigrate() or db.autoupdate()to generate the tables.

And if it still doesn't work we may need more detailed steps to help you reproduce the error.

[andenis]

Hi @jannyHou, thanks for your help.
It could be, I went through the documentation of loopback 4 but I didn't find a clear example of how to use it, I went through the examples but they are with a mocked base.
Maybe I should rely on the documentation for loopback 3?.
I'm starting on loopback and I would like to use version 4 since I use typescript.

[jannyHou]

@andenis You are right...The migration part is missing in LB4's datasource doc.

If you don't mind, I would like to modify this issue's title to "Add the doc for datasource migration". And turn it to a doc story :)

Acceptance criteria:

• [ ] Add the doc for how to call datasource functions in LB4 as the same way in LB3.
• [ ] Add a section for running ds.automigrate()/ds.autoupdate().
• [ ] Make sure the doc is verified by a working code.

[andenis]

@jannyHou, yes modify this issue. I changed the title.
Thanks!

[andenis]

@jannyHou or @dhmlau, can you attach any example to connect a real database and sync models in this issue?
To continue my investigation and test loopback 4.
Thanks.
Andres

[dhmlau]

@jannyHou , is it something we can provide here quickly? I'll see if we can put that in the Sept milestone.

[bajtos]

An outline how to write auto-update/auto-migrate script:

1. Create a new .ts file
2. Import the datasource, e.g.
   ts import {DbDataSource} from './datasources/db.datasource'
3. Create a new instance of your datasource. This assumes your datasource constructor provides a default configuration, which is the case for datasources created by lb4 tooling.
   ts const db = new DbDataSource();

1. Run autoupdate or automigrate
   ts await db.autoupdate(/*...*/);

For longer term, we would like to implement (or enable our community to implement) a better migration tool that give more control to developers - see https://github.com/strongloop/loopback-next/issues/487

[codematix]

@bajtos Thanks for pointing out the way migration can be done with lb4. However, I am unable to get autoupdate to work. Not able to understand how I can specify my models the method as the first argument.

I had a Todo model. When I tried the following:

import {DbDataSource} from './datasources/db.datasource';

const db = new DbDataSource();

db.autoupdate('Todo', (err, result) => {
  if (err) return console.log(err);
  console.log(result);
});

I get the error:

Error: Cannot migrate models not attached to this datasource: Todo
    at /Users/codematix/Projects/todo-app/node_modules/loopback-datasource-juggler/lib/datasource.js:1104:12
    at _combinedTickCallback (internal/process/next_tick.js:131:7)
    at process._tickCallback (internal/process/next_tick.js:180:9)
    at Function.Module.runMain (module.js:695:11)
    at startup (bootstrap_node.js:191:16)
    at bootstrap_node.js:612:3

Unsure how to proceed. Please provide some idea of how I can get the migrations to work. The 3.x version uses the JSON schema definition. How would it work with 4 version.

[gms1]

I think something like that is missing:

    new DefaultCrudRepository(Todo, ds);

instantiating the DefaultCrudRepository will setup the (juggler) model-definition and attach it to the provided datasource
Note: the first parameter for the DefaultCrudRepository is the entity class not a string

[dreamdevil00]

currently, I managed to migrate, but it seems cubersome

import {TodoRepository} from '../repositories/todo.repository';
import {DataSource} from 'loopback-datasource-juggler';

const dsConfig = require('../datasources/dev-my-sql.datasource.json');

const ds = new DataSource(dsConfig);

const repo = new TodoRepository(ds);

ds.autoupdate('Todo', err => {
  if (err) throw err;
  ds.disconnect();
});

[gms1]

yes, attaching the model twice should no be required (first attached in the Repo-ctor)

[bajtos]

currently, I managed to migrate, but it seems cubersome

I think you have discovered a missing repository API. How about adding a new method to our CrudRepository interface and implementation?

Intended usage:

const repo = new TodoRepository()
await repo.updateDatabaseSchema();

Implementation:

updateDatabaseSchema(): Promise<void> {
  return this.dataSource.autoupdate([
    this.modelClass.modelName,
  ]);
}

Personally, I'd much rather see a solution that will give more control to app developers, see the discussion in https://github.com/strongloop/loopback-next/issues/487, but I think the proposal I have outlined here is a reasonable workaround for now.

@raymondfeng @strongloop/sq-lb-apex thoughts?

[raymondfeng]

IMO, there will be two flavors of the migration apis:

• DataSource.prototype.* ==> It can take a list of models to be migrated
• Repository.prototype.* ==> It uses the model name from the repo itself

We probably want to define a separate mixin/interface for the migration capability.

To test out the minimum viable feature, we can improve loopback4-example-shopping with mysql as the database for user model so that we can create tables for user in mysql.

[dougal83]

Could this please include the example TodoListRepository? I'm finding the Getter element confusing without an example. Thanks.

EDIT: automigrate for todo-list example

[dhmlau]

@nabdelgadir , could you please take a look? After you've verified the working steps, can create a page in our docs. Thanks.