diff --git a/pages/en/lb2/Basic-model-object.md b/pages/en/lb2/Basic-model-object.md index cbed32e2e..1c17abdb2 100644 --- a/pages/en/lb2/Basic-model-object.md +++ b/pages/en/lb2/Basic-model-object.md @@ -22,8 +22,7 @@ the [RelationMixin object](http://apidocs.strongloop.com/loopback-datasource-ju ## Events -{% include important.html content=" -The following events are deprecated in favor of [operation hooks](Operation-hooks.html): +{% include note.html content="The following events are deprecated in favor of [operation hooks](Operation-hooks.html): * changed * deleted @@ -31,25 +30,23 @@ The following events are deprecated in favor of [operation hooks](Operation-hook " %} The following table summarizes the events that LoopBack models can emit. +For more information, see [Events](Events.html). - + - - + + - + + + - @@ -62,11 +59,8 @@ The following table summarizes the events that LoopBack models can emit. - @@ -75,8 +69,7 @@ The following table summarizes the events that LoopBack models can emit. - diff --git a/pages/en/lb3/Advanced-topics-data-sources.md b/pages/en/lb3/Advanced-topics-data-sources.md index d79d06226..723bf24f1 100644 --- a/pages/en/lb3/Advanced-topics-data-sources.md +++ b/pages/en/lb3/Advanced-topics-data-sources.md @@ -17,12 +17,9 @@ The diagram illustrates the relationship between LoopBack `Model`, `DataSource 1. Define the model. -2. Create an instance of `ModelBuilder` or `DataSource`. `DataSource` extends from `ModelBuilder`. - ModelBuilder is responsible for compiling model definitions to JavaScript constructors representing model classes. - DataSource inherits that function from ModelBuilder. +2. Create an instance of `ModelBuilder` or `DataSource`. `DataSource` extends from `ModelBuilder`. `ModelBuilder` is responsible for compiling model definitions to JavaScript constructors representing model classes. `DataSource` inherits that function from ModelBuilder. -3. Use `ModelBuilder` or `DataSource` to build a JavaScript constructor (i.e. the model class) from the model definition. - Model classes built from `ModelBuilder` can be later attached to a DataSource to receive the mixin of data access functions. +3. Use `ModelBuilder` or `DataSource` to build a JavaScript constructor (i.e. the model class) from the model definition. Model classes built from `ModelBuilder` can be later attached to a DataSource to receive the mixin of data access functions. 4. As part of step 2, `DataSource` initializes the underlying `Connector` with a settings object which provides configurations to the connector instance.  `Connector` collaborates with `DataSource` to define the functions as `DataAccessObject` to be mixed into the model class. @@ -35,6 +32,9 @@ It's a factory for data access logic around model classes. With the ability to p ## Creating a DataSource programmatically +{% include warning.html content="Don't put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) +"%} + The [`DataSource` constructor](http://apidocs.strongloop.com/loopback-datasource-juggler/#datasource) accepts the following arguments: * name: Optional name of the data source instance being created.  diff --git a/pages/en/lb3/Attaching-models-to-data-sources.md b/pages/en/lb3/Attaching-models-to-data-sources.md index 272b0013d..0b83f45e3 100644 --- a/pages/en/lb3/Attaching-models-to-data-sources.md +++ b/pages/en/lb3/Attaching-models-to-data-sources.md @@ -41,22 +41,22 @@ $ apic create --type datasource You can also add and modify data sources using the API Designer tool. -The tool will prompt you for the name of the new data source and the connector to use; for example, MySQL, Oracle, REST, and so on. +The tool will prompt you for the name of the new data source and the connector to use; for example, MongoDB, MySQL, Oracle, REST, and so on. The tool will then add an entry such as the following to `datasources.json`: {% include code-caption.html content="/server/datasources.json" %} ```javascript ... "corp1": { - "name": "corp1", - "connector": "mysql" + "name": "mongo1", + "connector": "mongodb" } ... ``` -This example creates a MySQL data source called "corp1". The identifier determines the name by which you refer to the data source and can be any string. +This example creates a MongoDB data source called "mongo1". The identifier determines the name by which you refer to the data source and can be any string. -## Add data source credentials +## Add database credentials Edit `datasources.json` to add the necessary authentication credentials for the data source; typically hostname, username, password, and database name. @@ -66,14 +66,66 @@ For example: ```javascript "corp1": { "name": "corp1", - "connector": "mysql", - "host": "your-mysql-server.foo.com", + "connector": "mongodb", + "host": "your-mongodb-server.foo.com", "user": "db-username", "password": "db-password", "database": "your-db-name" } ``` +{% include warning.html content="Putting production database credentials in a JSON file is not recommended for security reasons. +Instead, load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). +"%} + +### Specifying database credentials with environment variables + +Best practice is not to put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, define the values in environment variables and reference them in the data source configuration file. + +For example, assuming you have set a valid MongoDB username and password in the +environment variables MONGO_USER and MONGO_PASS, respectively: + +{% include code-caption.html content="datasources.json" %} +```javascript + ... + "accountDS": { + "name": "accountDS", + "connector": "mongodb", + "host": "demo.strongloop.com", + "port": 27017, + "database": "demo", + "username": "${MONGO_USER}", + "password": "${MONGO_PASS}" + } + ... + ``` + +You can use different data source definitions (including database credentials) for development and production by using the NODE_ENV +environment variable, as explained in [Environment-specific configuration](Environment-specific-configuration.html#data-source-configuration), +for example `datasources.production.json` for production environment when NODE_ENV is 'production'. + +### Using multiple data source configurations + +LoopBack merges environment-specific configurations (for example in `datasources.production.json`) with the baseline configuration in `datasources.json`. +Environment-specific configurations can override the top-level values with string and number values only. You cannot use objects or array values. + +It can be difficult to clear extra datasource settings inherited from the top-level `datasources.json` file in environment-specific files. To avoid issues, use a single `datasources.json` file that includes both individual settings such as `host`, `port`, and `database` for local environment and a `url` connection string setting that overrides the other settings for staging and production. For example: + +{% include code-caption.html content="datasources.json" %} +```js +{ + "db": { + "connector": "mongodb", + // The url setting will be used only when MONGODB_URL env var is defined + "url": "${MONGODB_URL}", + // configuration below is for development/staging environments only + "host": "localhost", + "database": "my-database-name", + ... + } +} +``` + ## Make the model use the data source When you create a new model with the [model generator](Model-generator.html), diff --git a/pages/en/lb3/Connecting-models-to-data-sources.md b/pages/en/lb3/Connecting-models-to-data-sources.md index ad5af8cbd..858a49645 100644 --- a/pages/en/lb3/Connecting-models-to-data-sources.md +++ b/pages/en/lb3/Connecting-models-to-data-sources.md @@ -11,7 +11,7 @@ summary: ## Overview -{% include image.html file="9830484.png" alt="" %}  +{% include image.html file="9830484.png" alt="Models, data sources, and connectors" %}  LoopBack models connect to backend systems such as databases via _data sources_ that provide create, retrieve, update, and delete (CRUD) functions. LoopBack also generalizes other backend services, such as REST APIs, SOAP web services, and storage services, and so on, as data sources. @@ -66,6 +66,9 @@ To connect a model to a data source, follow these steps: For information on the properties that each connector supports, see documentation for the specific connector under [Connectors reference](Connectors-reference). + {% include warning.html content="Don't put production database credentials in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) + "%} + 3. Install the corresponding connector as a dependency of your app with `npm`. For example:  @@ -274,17 +277,18 @@ However, data sources for database connectors (Oracle, MySQL, PostgreSQL, MongoD as described in the following table.
EventEmitted when...EventEmitted when... Arguments Argument type Class methods that emitInstance methods that emitInstance methods that emit
'attached' -

Model is attached to an app.

-
-

 

-
-


+
Model is attached to an app. Model class ObjectModel class Object   -
    -
  • DataSource.prototype.createModel
  • -
  • DataSource.prototype.define
  • -
+
DataSource.prototype
.createModel +
DataSource.prototype
.define
Model instance Object   -

Model.prototype.setAttributes()

+
Model.prototype
.setAttributes()
- + - - + + + + - - diff --git a/pages/en/lb3/Environment-specific-configuration.md b/pages/en/lb3/Environment-specific-configuration.md index ffc024e5c..a6a447158 100644 --- a/pages/en/lb3/Environment-specific-configuration.md +++ b/pages/en/lb3/Environment-specific-configuration.md @@ -54,21 +54,21 @@ The value set by the file with the highest priority will always take effect. The 3. **Default configuration file**; for example, `server/config.json`. " %} -Here are some examples of the application configuration files: +Examples of the application configuration files: * [config.json](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/config.json) * [config.local.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/config.local.js) -Here are some examples of data source configuration files: +Examples of data source configuration files: * [datasources.json](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.json) * [datasources.production.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.production.js) * [datasources.staging.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.staging.js) -Here are some examples of the middleware configuration files, the `server/middleware{._env_}.json` file: +Examples of the middleware configuration files: * [middleware.json](middleware.json.html) -* middleware.production.json +* [middleware.development.json](middleware.development.json.html) For an example application, see [https://github.com/strongloop/loopback-example-full-stack/tree/master/server](https://github.com/strongloop/loopback-example-full-stack/tree/master/server). @@ -157,8 +157,7 @@ You can override values set in `datasources.json` in the following files: * datasources.env.js or datasources.env.json, where _`env`_ is the value of `NODE_ENV` environment variable (typically `development` or `production`). For example, `datasources.production.json`. -{% include important.html content=" -The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. +{% include important.html content="The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. " %} Example data sources: @@ -166,9 +165,6 @@ Example data sources: {% include code-caption.html content="datasources.json" %} ```javascript { - // the key is the datasource name - // the value is the config object to pass to - // app.dataSource(name, config). db: { connector: 'memory' } @@ -187,9 +183,9 @@ Example data sources: } ``` -You can also configure your datasource._\_env\__.js file to use environment variables: +You can also configure your datasource.env.js file to use environment variables: -{% include code-caption.html content="datasources.production.json" %} +{% include code-caption.html content="datasources.production.js" %} ```javascript module.exports = { db: { @@ -207,7 +203,7 @@ the datasource. ## Getting values from environment variables -You can easily set an environment variable when you run an application. The command you use depends on your operating system. +You can easily get the value of an environment variable in an application. The command you use depends on your operating system. ### MacOS and Linux diff --git a/pages/en/lb3/datasources.json.md b/pages/en/lb3/datasources.json.md index 068533c45..ba6937b67 100644 --- a/pages/en/lb3/datasources.json.md +++ b/pages/en/lb3/datasources.json.md @@ -6,12 +6,13 @@ keywords: LoopBack tags: sidebar: lb3_sidebar permalink: /doc/en/lb3/datasources.json.html -summary: +summary: Configure data sources in datasources.json. --- ## Overview -Configure data sources in `/server/datasources.json`. You can set up as many data sources as you want in this file. +Configure data sources in `/server/datasources.json`. You can set up as many data sources as you want in this file. The easiest way to set up a new data source is to use the [data source generator](Data-source-generator.html), which will prompt your for all the +appropriate settings, add them to `/server/datasources.json`, and then install the connector from npm. For example: @@ -21,8 +22,8 @@ For example: "name": "db", "connector": "memory" }, - "myDB": { - "name": "myDB", + "mySQLdb": { + "name": "mySQLdb", "connector": "mysql", "host": "demo.strongloop.com", "port": 3306, @@ -33,22 +34,23 @@ For example: } ``` -To access data sources in application code, use `app.datasources._datasourceName_`. +To access data sources in application code, use app.datasources.datasourceName. ## Standard properties All data sources support a few standard properties. Beyond that, specific properties and defaults depend on the connector being used.
PropertyTypePropertyType Description
connector String -

Connector name; for example:

+
Connector name; for example:
  • "memory"
  • "loopback-connector-mongodb" or "mongodb"
  • @@ -324,9 +328,8 @@ as described in the following table.
url String -

Combines and overrides host, port, user, password, and database properties.

-

Only valid with MongoDB connector, PostgreSQL connector, and SQL Server connector.

+
Combines and overrides host, port, user, password, and database properties. + Only valid with certain connectors; see connector documentation.
- + + + - @@ -71,123 +72,65 @@ All data sources support a few standard properties. Beyond that, specific proper
Property Description
connector -

LoopBack connector to use; one of:

+
LoopBack connector to use:
  • memory
  • loopback-connector-oracle or just "oracle"
  • @@ -57,10 +59,9 @@ All data sources support a few standard properties. Beyond that, specific proper
  • loopback-connector-postgresql or just "postgresql"
  • loopback-connector-soap or just "soap"
  • loopback-connector-mssql or just "mssql"
  • -
  • -

    loopback-connector-rest or just "rest"

    -
  • +
  • loopback-connector-rest or just "rest"
  • loopback-storage-service
  • +
  • Another LoopBack data source connector
-## Properties for database connectors - -To connect a model to a data source, follow these steps: - -1. Use the [data source generator](Data-source-generator.html) to create a new data source. For example:  -
- ```shell - $ apic create --type datasource - ? Enter the data-source name: mysql-corp - ? Select the connector for mysql: MySQL (supported by StrongLoop) - ``` -
- ```shell - $ lb datasource - ? Enter the data-source name: mysql-corp - ? Select the connector for mysql: MySQL (supported by StrongLoop) - ``` - - Follow the prompts to name the datasource and select the connector to use. - This adds the new data source to `datasources.json` - -2. Edit `server/datasources.json` to add the necessary authentication credentials: typically hostname, username, password, and database name. - - For example: - - **server/datasources.json** - - ```javascript - "mysql-corp": { - "name": "mysql-corp", - "connector": "mysql", - "host": "your-mysql-server.foo.com", - "user": "db-username", - "password": "db-password", - "database": "your-db-name" - } - ``` - - For information on the properties that each connector supports, see - the specific connector documentation in [Database connectors](Database-connectors.html). - -3. Install the corresponding connector as a dependency of your app with `npm`, for example:  - - ```shell - $ cd - $ npm install --save loopback-connector-mysql - ``` - - See [Connectors](Connecting-models-to-data-sources.html) for the list of connectors. - -4. Use the [model generator](Using-the-model-generator.html) to create a model. -
- ``` - $ apic create --type model - ? Enter the model name: myModel - ? Select the data-source to attach myModel to: mysql (mysql) - ? Select model's base class: PersistedModel - ? Expose myModel via the REST API? Yes - ? Custom plural form (used to build REST URL): - Let's add some test2 properties now. - ... - ``` -
- ``` - $ lb model - ? Enter the model name: myModel - ? Select the data-source to attach myModel to: mysql (mysql) - ? Select model's base class: PersistedModel - ? Expose myModel via the REST API? Yes - ? Custom plural form (used to build REST URL): - Let's add some test2 properties now. - ... - ``` - - When prompted for the data source to attach to, select the one you just created.  - -{% include note.html content=" -The model generator lists the [memory connector](Memory-connector.html), \"no data source,\" and data sources listed in `datasources.json`. That's why you created the data source first in step 1. -" %} - -You can also create models from an existing database. -See [Creating models](Creating-models.html) for more information. - -## Environment-specific configuration - -You can override values set in `datasources.json` in the following files: - -* `datasources.local.js` or `datasources.local.json` -* `datasources._env_.js` or `datasources._env_.json`, where _`env`_ is the value of `NODE_ENV` environment variable (typically `development` or `production`). - For example, `datasources.production.json`. - -{% include important.html content=" -The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. -" %} - -Example data sources: - -{% include code-caption.html content="datasources.json" %} -```javascript -{ - // the key is the datasource name - // the value is the config object to pass to - // app.dataSource(name, config). - db: { - connector: 'memory' - } -} -``` +## Database connector properties -{% include code-caption.html content="datasources.production.json" %} -```javascript -{ - db: { - connector: 'mongodb', - database: 'myapp', - user: 'myapp', - password: 'secret' - } -} -``` +Although each data source connector has a different set of properties, +database connectors typically have properties that include +properties for the database server and credentials to log in to it. + +For information on the properties that each connector supports, see +the specific connector documentation in [Database connectors](Database-connectors.html). + +{% include warning.html content="Don't put production database credentials in configuration files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) +"%} + +The following table list common properties that most database connectors provide. +See documentation for the specific connector for full details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
databaseStringDatabase name
hostStringDatabase host name
passwordStringPassword to connect to database
portNumberDatabase TCP port
urlStringConnection URL that overrides other connection settings.
usernameStringUsername to connect to database