From 3e0afc31c3ea0f73711b74c198e63310d8a85b20 Mon Sep 17 00:00:00 2001 From: Agnes Lin Date: Mon, 1 Jun 2020 18:19:15 -0400 Subject: [PATCH] docs: adding mongodb connector tutorial --- docs/site/decorators/Decorators_openapi.md | 2 +- .../tutorials/connectors/Mongodb-tutorial.md | 221 ++++++++++++++++++ .../connectors/Postgresql-tutorial.md | 26 ++- 3 files changed, 237 insertions(+), 12 deletions(-) create mode 100644 docs/site/tutorials/connectors/Mongodb-tutorial.md diff --git a/docs/site/decorators/Decorators_openapi.md b/docs/site/decorators/Decorators_openapi.md index d17419cddafd..7cc2999d743a 100644 --- a/docs/site/decorators/Decorators_openapi.md +++ b/docs/site/decorators/Decorators_openapi.md @@ -440,7 +440,7 @@ export class MyController { The `x-ts-type` can be used for array and object properties too: {% include note.html content="Arrays should be defined with -[`@requestBody.array`](#@requestBody.array) instead."} +[`@requestBody.array`](#@requestBody.array) instead." %} ```ts const schemaWithArrayOfMyModel = { diff --git a/docs/site/tutorials/connectors/Mongodb-tutorial.md b/docs/site/tutorials/connectors/Mongodb-tutorial.md new file mode 100644 index 000000000000..4bf40cd2f7fd --- /dev/null +++ b/docs/site/tutorials/connectors/Mongodb-tutorial.md @@ -0,0 +1,221 @@ +--- +lang: en +title: 'MongoDB connector tutorial' +keywords: LoopBack 4.0, LoopBack 4, connector, MongoDB +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Connecting-to-MongoDB.html +--- + +# Connecting to MongoDB + +The following tutorial introduces how to set up MongoDB as the data source of +LoopBack 4 applications with +[LoopBack MongoDB connector](https://github.com/strongloop/loopback-connector-mongodb). + +## Prerequisites + +Before starting this tutorial, make sure you have the following installed: + +- Node.js version 10 or higher +- LoopBack 4 CLI; see + [Getting Started with LoopBack 4](../../Getting-started.md) + +## Tutorial - MongoDB + +### 1. Create a new LoopBack 4 app + +Let's use the [LB4 CLI](../../Command-line-interface.md) `lb4 app` to create a +LoopBack 4 application called `MyApp`: + +```bash +$ lb4 app +? Project name: my-app +? Project description: MongoDB connector tutorial +? Project root directory: my-app +? Application class name: MyAppApplication +? Select features to enable in the project (Press to select, to togg +le all, to invert selection) +❯◉ Enable eslint: add a linter with pre-configured lint rules + ◉ Enable prettier: install prettier to format code conforming to rules + ◉ Enable mocha: install mocha to run tests + ◉ Enable loopbackBuild: use @loopback/build helpers (e.g. lb-eslint) + ◉ Enable vscode: add VSCode config files + ◉ Enable docker: include Dockerfile and .dockerignore + ◉ Enable repositories: include repository imports and RepositoryMixin +(Move up and down to reveal more choices) +``` + +### 2. Create models + +Let's create a simple model `User`. To keep the tutorial short, the prompts of +`lb4 model` are skipped: + +{% include code-caption.html content="user.model.ts" %} + +```ts +// imports +@model() +export class User extends Entity { + @property({ + type: 'number', + id: true, + generated: true, + }) + id?: number; + + @property({ + type: 'string', + }) + name?: string; + + @property({ + type: 'boolean', + required: true, + }) + hasAccount: boolean; + + constructor(data?: Partial) { + super(data); + } +} +``` + +### 3. Create a data source + +Next, let's create a DataSource `db` using the MongoDB connector by the prompts +below: + +```bash +$ lb4 datasource +? Datasource name: db +? Select the connector for db: + ... + Redis key-value connector (supported by StrongLoop) +❯ MongoDB (supported by StrongLoop) + MySQL (supported by StrongLoop) + ... +? Connection String url to override other settings (eg: mongodb://username:passw +ord@hostname:port/database): +? host: localhost +? port: 27017 +? user: +? password: [hidden] +? database: demo +? Feature supported by MongoDB v3.1.0 and above: Yes + +Datasource Db was created in src/datasources/ +``` + +Under `src/datasources/db.datasource.ts`, we can find the `DBDataSource` class +and the config we just set: + +```ts +const config = { + name: 'db', + connector: 'mongodb', + url: '', + host: 'localhost', + port: 27017, + user: '', + password: '', + database: 'demo', +}; +``` + +{% include important.html content="please make sure you are using `loopback-connector-mongodb` package version 5.2.1 +or above to handle `ObjectId` properly." %} + +### 4. Create repositories + +A [Repository](../../Repository.md) is an artifact that ties the model and the +datasource. We will need to create the repository for the `User` class to access +the database. The steps of creating `UserRepository` by running `lb4 repository` +are skipped here: + +{% include code-caption.html content="user.repository.ts" %} + +```ts +// imports +export class UserRepository extends DefaultCrudRepository< + User, + typeof User.prototype.id, + UserRelations +> { + constructor(@inject('datasources.db') dataSource: DbDataSource) { + super(User, dataSource); + } +} +``` + +### 5. Create endpoints and view data using API Explorer + +Once we built a [controller](../../Controllers.md) with `lb4 controller` to +handle requests, from the project root, start the app: + +```bash +$ npm start +``` + +We can verify what we just created with API Explorer +[`http://localhost:3000/explorer/`](http://localhost:3000/explorer/). + +## Data Mapping Properties + +If you'd like to use different names for the collection/fields and the +model/properties, it can be achieved by configuring the model +definition/property definition. Take the `User` model as an example, if we'd +like to name the collection as `MY_USER` in the database and also use uppercase +for properties `name` and `hasAccount`, the following settings would allow us to +do so: + +```ts +@model({ + settings: { + // add it to the model definition + mongodb: {collection: 'MY_USER'}, + }, +}) +export class User extends Entity { + @property({ + type: 'string', + id: true, + generated: true, + }) + id: string; + + @property({ + type: 'string', + // add it to the property definition + mongodb: { + fieldName: 'NAME', + }, + }) + name?: string; + + @property({ + type: 'boolean', + required: true, + // add it to the property definition + mongodb: { + fieldName: 'HASACCOUNT', + }, + }) + hasAccount: boolean; +} +``` + +{% include important.html content="Since in MongoDB `_id` is reserved for the primary key, LoopBack **does not** allow customization of the field name for the id property. Please use `id` as is." %} + +## Handling ObjectId + +MongoDB uses `ObjectId` for its primary key, which is an object instead of a +string. In queries, string values must be cast to ObjectID, otherwise they are +not considered as the same value. Therefore, you might want to specify the data +type of properties to enforce ObjectId coercion. Such coercion would make sure +the property value converts from ObjectId-like string to `ObjectId` when it +accesses to the database and converts `ObjectId` to ObjectId-like string when +the app gets back the value. + +Please check section +[Handling ObjectId](https://loopback.io/doc/en/lb4/MongoDB-connector.html#handling-objectid) +for details. diff --git a/docs/site/tutorials/connectors/Postgresql-tutorial.md b/docs/site/tutorials/connectors/Postgresql-tutorial.md index 6452ef11e439..d4516d15ce94 100644 --- a/docs/site/tutorials/connectors/Postgresql-tutorial.md +++ b/docs/site/tutorials/connectors/Postgresql-tutorial.md @@ -16,8 +16,8 @@ LoopBack 4 applications with Before starting this tutorial, make sure you have the following installed: -- Node -- LoopBack CLI tools; see +- Node.js version 10 or higher +- LoopBack 4 CLI; see [Getting Started with LoopBack 4](../../Getting-started.md) ## Tutorial - PostgreSQL @@ -50,6 +50,8 @@ le all, to invert selection) Let's create a simple model `User`. To keep the tutorial short, the prompts of `lb4 model` are skipped: +{% include code-caption.html content="user.model.ts" %} + ```ts // imports @model() @@ -59,7 +61,7 @@ export class User extends Entity { id: true, generated: true, }) - id?: number; + id: number; @property({ type: 'string', @@ -80,11 +82,11 @@ export class User extends Entity { ### 3. Create a data source -Next, let's create a dataSource `db` using PostgreSQL connector with the -following setups: +Next, let's create a DataSource `db` using the PostgreSQL connector by the +prompts below: ```bash -agnes:my-app agnes$ lb4 datasource +$ lb4 datasource ? Datasource name: db ? Select the connector for db: ... @@ -121,10 +123,12 @@ const config = { ### 4. Create repositories -[Repository](../../Repository.md) is a artifact that ties the model and the -datasource. We will need to create the repository for the `User` class before -accessing the database. The steps of creating `UserRepository` by running -`lb4 repository` are skipped here: +A [Repository](../../Repository.md) is an artifact that ties the model and the +datasource. We will need to create the repository for the `User` class to access +the database. The steps of creating `UserRepository` by running `lb4 repository` +are skipped here: + +{% include code-caption.html content="user.repository.ts" %} ```ts // imports @@ -181,7 +185,7 @@ $ npm start ``` We can verify what we just created with API Explorer -`http://localhost:3000/explorer/`. +[`http://localhost:3000/explorer/`](http://localhost:3000/explorer/). ## Database Migration