Skip to content

Migration guide for model relations #4058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bajtos merged 2 commits into from
Nov 14, 2019
Merged

Migration guide for model relations #4058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3fa9ca6
fix(docs): remove forgotten FIXME comment
bajtos Nov 7, 2019
12179b5
feat(docs): migration guide for model relations
bajtos Nov 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/site/migration/models/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,6 @@ sidebar: lb4_sidebar
permalink: /doc/en/lb4/migration-models-overview.html
---

**FIXME:** Explain at high level how to migrate models from a LB3 app to a LB4
project. Refer to sub-sections for model details.

In LoopBack 3, models are the cornerstone. They describe shape of data (schema),
provide persistence-related behavior and implement public (REST) API. Besides
this core functionality, there are many ways how to extend the built-in
Expand Down
77 changes: 72 additions & 5 deletions docs/site/migration/models/relations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,75 @@ sidebar: lb4_sidebar
permalink: /doc/en/lb4/migration-models-relations.html
---

{% include note.html content="
This is a placeholder page, the task of adding content is tracked by the
following GitHub issue:
[loopback-next#3948](https://github.com/strongloop/loopback-next/issues/3948).
" %}
When you define a relation in a LoopBack 3 model JSON file, the framework will
create the following artifacts for you automatically:

- Relation metadata defining the target model, foreign key column/property, and
so on.
- Repository-like methods for accessing related model instance(s), for example
`Category.prototype.products`.
- An inclusion resolver to allow clients to request relation traversal in
queries and include related models, e.g.
`Product.find({include: ['category']})`
- REST API endpoints for querying a modifying models on the other side of the
relation, e.g. `GET /api/categories/1/products`.

In LoopBack 4, these building blocks are typically provided by the application
developer.

- Relation metadata is defined via model decorators like `@hasMany`.
- Relation repositories implement APIs for accessing and modifying data of
related models.
- Inclusion resolvers implement relation traversal in queries.
- Relation controllers implement REST APIs for model relations.

At the moment, all of these artifacts are defined via source code files which
are typically created by running `lb4 relation`. With source code files ready to
be edited, developers get a lot of power and flexibility in customizing the
default behavior offered by the framework.

In the future, we would like to provide a declarative approach for building
model relations: the developer defines relation metadata, and the framework
builds all required artifacts at runtime, similar to how LoopBack 3 works. You
can join the discussion in the GitHub issue
[loopback-next#2483](https://github.com/strongloop/loopback-next/issues/2483).

## Migration path

Follow these steps to migrate a model relation from LoopBack 3 to LoopBack 4:

1. Make sure to complete all steps described in
[Migrating model definitions and built-in APIs](./core.md), especially the
creation of Repository classes for models on both sides of the relation.

2. Run `lb4 relation` to define the model relation in your model class, generate
Copy link
Contributor

@jannyHou jannyHou Nov 12, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe make it more clear like:

Run `lb4 relation` to create the model relations according to the relation definitions defined in lb3 model json files.

so that people understand where to find the relation definitions.
And we can link to the generator doc as well: https://loopback.io/doc/en/lb4/Relation-generator.html

Copy link
Member Author

@bajtos bajtos Nov 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

according to the relation definitions defined in lb3 model json files.

Copy link
Member Author

@bajtos bajtos Nov 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

according to the relation definitions defined in lb3 model json files.

I am concerned that this is not entirely correct. Relations can be defined from JS code too, e.g. Product.belongsTo(Category).

I am not sure how to best incorporate this information into the migration guide. Let's leave it out of scope of this pull request. If you have some ideas how to improve the current text, then can you please open a follow-up pull request yourself? 

And we can link to the generator doc as well: https://loopback.io/doc/en/lb4/Relation-generator.html

Great idea 👍

code for the relation repository and optionally register inclusion resolver.
This command will also create a new Controller class implementing public REST
API for your relation.

You can learn more about `lb4 relation` command in
[Relation generator](../../Relation-generator.md).

## Relation types

The following relations are supported by LoopBack 4 and can be migrated from
LoopBack 3:

- [HasMany](../../HasMany-relation.md)
- [HasOne](../../hasOne-relation.md)
- [BelongsTo](../../BelongsTo-relation.md)

Other relations types are not supported yet, you can subscribe to our progress
in the high-level tracking issue
[loopback-next#1450](https://github.com/strongloop/loopback-next/issues/1450).
See also issues for individual relation types as mentioned in the tracking
issue, for example:

- HasManyThrough -
[loopback-next#2264](https://github.com/strongloop/loopback-next/issues/2264)
- HasAndBelongsToMany -
[loopback-next#2308](https://github.com/strongloop/loopback-next/issues/2308)
- Polymorphic relations -
[loopback-next#2487](https://github.com/strongloop/loopback-next/issues/2487)
- ReferencesMany -
[loopback-next#2488](https://github.com/strongloop/loopback-next/issues/1450)