Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
31 changes: 12 additions & 19 deletions pages/en/lb2/Basic-model-object.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,34 +22,31 @@ 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
* deletedAll
" %}

The following table summarizes the events that LoopBack models can emit.
For more information, see [Events](Events.html).

<table>
<tbody>
<thead>
<tr>
<th>Event</th>
<th>Emitted when...</th>
<th width="150">Event</th>
<th width="180">Emitted when...</th>
<th>Arguments</th>
<th>Argument type</th>
<th>Class methods that emit</th>
<th>Instance methods that emit</th>
<th width="230">Instance methods that emit</th>
</tr>
</thead>
<tbody style="font-size: 90%;">
<tr>
<td>'attached'</td>
<td>
<p>Model is attached to an app.</p>
<div style="width: 120px;">
<p>&nbsp;</p>
</div>
<p><br></p>
<td>Model is attached to an app.
</td>
<td>Model class</td>
<td>Object</td>
Expand All @@ -62,11 +59,8 @@ The following table summarizes the events that LoopBack models can emit.
<td>Model class</td>
<td>Object</td>
<td>&nbsp;</td>
<td>
<ul>
<li>DataSource.prototype.createModel </li>
<li>DataSource.prototype.define</li>
</ul>
<td>DataSource.prototype<br/>.createModel
<br/>DataSource.prototype<br/>.define
</td>
</tr>
<tr>
Expand All @@ -75,8 +69,7 @@ The following table summarizes the events that LoopBack models can emit.
<td>Model instance</td>
<td>Object</td>
<td>&nbsp;</td>
<td>
<p>Model.prototype.setAttributes()</p>
<td>Model.prototype<br/>.setAttributes()
</td>
</tr>
</tbody>
Expand Down
10 changes: 5 additions & 5 deletions pages/en/lb3/Advanced-topics-data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
"%}

@ebarault ebarault Mar 17, 2017 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

ok for the warning but it stands that the problem expressed in this comment is still not covered by the doc.

The doc explains how to create a datasource programmatically but some info should be added on where to use this snippet, and how to connect models on these datasources (programmatically I suppose, but one could assume that they could reference datasources created programmatically in the model-config.json

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I opened a new issue for this: #331

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. 
Expand Down
66 changes: 59 additions & 7 deletions pages/en/lb3/Attaching-models-to-data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,22 +41,22 @@ $ apic create --type datasource
You can also add and modify data sources using the API Designer tool.
</div>

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.

Expand All @@ -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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is not true - AFAIK, one can override object values with object values, array values with array values too.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

well this is copy/paste from the current doc


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),
Expand Down
21 changes: 12 additions & 9 deletions pages/en/lb3/Connecting-models-to-data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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: 
Expand Down Expand Up @@ -274,17 +277,18 @@ However, data sources for database connectors (Oracle, MySQL, PostgreSQL, MongoD
as described in the following table.

<table>
<tbody>
<thead>
<tr>
<th>Property</th>
<th>Type</th>
<th width="100">Property</th>
<th width="80">Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>connector</td>
<td>String</td>
<td>
<p>Connector name; for example:</p>
<td>Connector name; for example:
<ul>
<li>"memory"</li>
<li>"loopback-connector-mongodb" or "mongodb"</li>
Expand Down Expand Up @@ -324,9 +328,8 @@ as described in the following table.
<tr>
<td>url</td>
<td>String</td>
<td>
<p>Combines and overrides <code>host</code>,&nbsp;<code>port</code>,&nbsp;<code>user</code>,&nbsp;<code>password</code>, and&nbsp;<code>database</code>&nbsp;properties.</p>
<p>Only valid with <a href="MongoDB-connector.html">MongoDB connector</a>, <a href="PostgreSQL-connector.html">PostgreSQL connector</a>, and <a href="SQL-Server-connector.html">SQL Server connector</a>.</p>
<td>Combines and overrides <code>host</code>, <code>port</code>, <code>user</code>, <code>password</code>, and <code>database</code> properties.
Only valid with certain connectors; see connector documentation.
</td>
</tr>
<tr>
Expand Down
20 changes: 8 additions & 12 deletions pages/en/lb3/Environment-specific-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -157,18 +157,14 @@ You can override values set in `datasources.json` in the following files:
* <code>datasources.<i>env</i>.js</code> or <code>datasources.<i>env</i>.json</code>, 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:

{% 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'
}
Expand All @@ -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 <code>datasource.<i>env</i>.js</code> 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: {
Expand All @@ -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

Expand Down
Loading