Add documentation for executing native database commands

docs/bin/build-preview-site.sh

@@ -23,6 +23,9 @@ else
   (cd $SOURCE_DIR && git pull)
 fi
 
+echo "Pulling README files (connectors, etc.)"
+(cd $SOURCE_DIR && ./update-readmes.sh)
+
 echo "Installing setup dependencies"
 npm install --no-save js-yaml
 
@@ -59,6 +62,9 @@ rm -rf $JEKYLL_DIR/pages
 mkdir $JEKYLL_DIR/pages
 (TARGET="$PWD/$JEKYLL_DIR/pages" && cd "$PWD/site" && pax -rwlpe . $TARGET)
 
+echo "Copying external README pages"
+cp $SOURCE_DIR/pages/en/lb4/readmes/*.md $JEKYLL_DIR/pages/readmes/
+
 echo "Setting up sidebar(s)"
 rm -rf $JEKYLL_DIR/_data/sidebars
 # Create hardlinks because Jekyll does not support symbolic links any more.

docs/site/Cassandra-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'Cassandra connector'
+lang: en
+layout: readme
+source: loopback-connector-cassandra
+keywords: LoopBack, connector
+tags: readme
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Cassandra-connector.html
+summary:
+  The Cassandra connector enables LoopBack applications to connect to Cassandra
+  data sources.
+---

docs/site/Cloudant-connector.md

@@ -0,0 +1,18 @@
+---
+title: 'Cloudant connector'
+lang: en
+layout: readme
+source: loopback-connector-cloudant
+keywords: LoopBack, connector
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Cloudant-connector.html
+summary:
+  The Cloudant connector enables LoopBack applications to connect to Cloudant
+  data sources.
+---
+
+{% include see-also.html content="
+
+- [Getting Started with LoopBack and IBM Cloudant](https://developer.ibm.com/bluemix/2015/09/10/getting-started-node-js-loopback-framework-ibm-cloudant/)
+  " %}

docs/site/DB2-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'IBM Db2 connector'
+lang: en
+layout: readme
+source: loopback-connector-db2
+keywords: LoopBack
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/DB2-connector.html
+summary:
+  The Db2 connector enables LoopBack applications to connect to Db2 data
+  sources.
+---

docs/site/DB2-for-i-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'IBM Db2 for i connector'
+lang: en
+layout: readme
+source: loopback-connector-ibmi
+keywords: LoopBack
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/DB2-for-i-connector.html
+summary:
+  The loopback-connector-ibmi connector enables LoopBack applications to connect
+  to IBM® Db2® for i data sources.
+---

docs/site/DB2-for-z-OS-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'IBM Db2 for z/OS connector'
+lang: en
+layout: readme
+source: loopback-connector-db2z
+keywords: LoopBack
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/DB2-for-z-OS-connector.html
+summary:
+  The loopback-connector-db2z connector enables LoopBack applications to connect
+  to IBM® Db2® for z/OS® data sources.
+---

docs/site/Example-kv-connector.md

@@ -0,0 +1,11 @@
+---
+title: 'KV connector example'
+lang: en
+layout: readme
+source: loopback-example-kv-connectors
+keywords: LoopBack
+tags: example_app
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Example-kv-connector.html
+summary: A simple example of using the LoopBack KV connectors.
+---

docs/site/Executing-database-commands.md

@@ -0,0 +1,61 @@
+---
+lang: en
+title: 'Executing database commands'
+keywords: LoopBack 4.0, LoopBack 4, Node.js, TypeScript
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Executing-database-commands.html
+---
+
+## Overview
+
+{% include warning.html content="In general, it is always better to perform
+database actions through `Repository` methods. Directly executing native database
+commands may lead to unexpected results and other issues." %}
+
+When you project outgrows built-in `Repository` methods, you can execute native
+database commands to implement more complex data queries and manipulations, for
+example execute a custom SQL query or invoke a MongoDB command.
+
+LoopBack provides two APIs:
+
+- DataSource-level `execute()` method
+- Repository-level `execute()` method
+
+Both methods offer the same set of signatures, the implementation in Repository
+is just a thin wrapper delegating the task to DataSource.
+
+Example use:
+
+```ts
+const result = await repository.execute('SELECT * FROM Products');
+```
+
+See API docs for parameter reference, additional information and examples:
+
+- [SQL variant](./apidocs/repository.defaultcrudrepository.execute.md)
+- [MongoDB variant](./apidocs/repository.defaultcrudrepository.execute_1.md)
+- [Generic variant](./apidocs/repository.defaultcrudrepository.execute_2.md)
+
+{% include important.html content="Each connector implements a slightly
+different flavor of `execute()` to match the capabilities supported by the
+database engine. Please refer to connector documentation to learn more about
+the expected parameters and command/query syntax to use.
+" %}
+
+## Supported connectors
+
+Not all connectors support execution of native database commands. Check your
+connector's documentation to learn more. The following connectors are known to
+support `execute` method.
+
+<!-- Keep the entries sorted lexicographically (A-Z) -->
+
+- [IBM DB2](./DB2-connector.md)
+- [IBM DB2 for i](./DB2-for-i-connector.md)
+- [IBM DB2 for z/OS](./DB2-for-z-OS-connector.md)
+- [Oracle](./Oracle-connector.md)
+- [Microsoft SQL](./SQL-Server-connector.md)
+- [MongoDB](./MongoDB-connector.md)
+- [MySQL](./MySQL-connector.md)
+- [PostgreSQL](./PostgreSQL-connector.md)
+- [SQLite3](./SQLite3.md)

docs/site/Installing-the-Oracle-connector.md

@@ -0,0 +1,20 @@
+---
+title: 'Installing the Oracle connector'
+lang: en
+layout: navgroup
+navgroup: oracle
+source: loopback-oracle-installer
+keywords: LoopBack
+tags:
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Installing-the-Oracle-connector.html
+summary:
+  The loopback-oracle-installer module takes care of binary dependencies
+  and simplifies the process of installing the Oracle connector.
+---
+
+{% include tip.html content="
+Use the [Oracle installer command](Oracle-installer-command.html), `lb oracle`,
+to easily install and troubleshoot installing `loopback-oracle-installer`
+and the Oracle data source connector.
+" %}

docs/site/JSON-RPC-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'JSON-RPC connector'
+lang: en
+layout: readme
+source: loopback-connector-jsonrpc
+keywords: LoopBack, connector
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/JSON-RPC-connector.html
+summary:
+  The LoopBack JSON-RPC Connector enables LoopBack applications to call JSON-RPC
+  services.
+---

docs/site/MQLight-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'MQLight connector'
+lang: en
+layout: readme
+source: loopback-connector-mqlight
+keywords: LoopBack, connector
+tags: [connectors, readme]
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/MQLight-connector.html
+summary:
+  The MQ Light connector enables LoopBack applications to use the MQ Light
+  messaging API.
+---

docs/site/Memory-connector.md

@@ -0,0 +1,125 @@
+---
+title: 'Memory connector'
+lang: en
+layout: page
+keywords: LoopBack
+tags: connectors
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Memory-connector.html
+summary:
+  The built-in memory connector is a persistent data source for development and
+  testing.
+---
+
+## Overview
+
+LoopBack's built-in memory connector enables you to test your application
+without connecting to an actual persistent data source such as a database.
+Although the memory connector is very well tested it is not suitable for
+production.
+
+The memory connector supports:
+
+- Standard query and create, read, update, and delete operations, so you can
+  test models against an in-memory data source.
+- Geo-filtering when using the `find()` operation with an attached model.
+  See [GeoPoint class](http://apidocs.loopback.io/loopback-datasource-juggler/#geopoint) for
+  more information on geo-filtering.
+
+{% include important.html content=" The memory connector is designed for
+development and testing of a single-process application without setting up a
+database. It cannot be used in a cluster as the worker processes will have their
+own isolated data not shared in the cluster.
+
+You can persist data between application restarts using the `file` property. See
+[Data persistence](#data-persistence) for more information. " %}
+
+## Creating a data source
+
+By default, an application created with the
+[Application generator](Application-generator.html) has a memory data source
+defined; for example:
+
+{% include code-caption.html content="/server/datasources.json" %}
+
+```javascript
+"db": {
+    "name": "db",
+    "connector": "memory"
+}
+```
+
+Use the [Data source generator](Data-source-generator.html) to add a new memory
+data source to your application.
+
+### Memory connector properties
+
+<table>
+  <tbody>
+    <tr>
+      <th>Property</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+    <tr>
+      <td>name</td>
+      <td>String</td>
+      <td>Name by which you refer to the data source.</td>
+    </tr>
+    <tr>
+      <td>connector</td>
+      <td>String</td>
+      <td>Must be "memory" to use the memory connector.</td>
+    </tr>
+    <tr>
+      <td>file</td>
+      <td>String</td>
+      <td>
+        <p>Path to file where the connector will store data, relative to application root directory.</p>
+        <p>NOTE: The connector will create the file if necessary, but the directory containing the file must exist.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+{% include important.html content="
+If you specify the file property, the connector will save data there that will persist when you restart the application.
+Otherwise, the memory connector does not persist data after an application stops.
+" %}
+
+## Data persistence
+
+By default, data in the memory connector are transient. When an application
+using the memory connector exits, all model instances are lost. To maintain data
+across application restarts, specify a JSON file in which to store the data with
+the `file` property when creating the data source.
+
+The simplest way to do this is by editing `server/datasources.json`; for
+example:
+
+{% include code-caption.html content="server/datasources.json" %}
+
+```javascript
+{
+  "db": {
+    "name": "db",
+    "connector": "memory",
+    "file": "mydata.json"
+  }
+}
+```
+
+You can also set the persistence file in a boot script; for example:
+
+{% include code-caption.html content="server/boot/script.js" %}
+
+```javascript
+var memory = loopback.createDataSource({
+  connector: loopback.Memory,
+  file: 'mydata.json',
+});
+```
+
+When the application exits, the memory connector will then store data in the
+`mydata.json` file, and when it restarts will load the saved data from that
+file.

docs/site/MongoDB-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'MongoDB connector'
+lang: en
+layout: readme
+source: loopback-connector-mongodb
+keywords: LoopBack, connector
+tags: readme
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/MongoDB-connector.html
+summary:
+  The MongoDB connector enables LoopBack applications to connect to MongoDB data
+  sources.
+---

docs/site/MySQL-connector.md

@@ -0,0 +1,16 @@
+---
+title: 'MySQL connector'
+lang: en
+layout: readme
+source: loopback-connector-mysql
+keywords: LoopBack
+tags: connectors
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/MySQL-connector.html
+summary:
+  The MySQL connector enables LoopBack applications to connect to MySQL  data
+  sources.
+---
+
+{% include important.html content="The MySQL connector requires MySQL 5.0+.
+" %}

docs/site/OpenAPI-connector.md

@@ -0,0 +1,13 @@
+---
+title: 'OpenAPI connector'
+lang: en
+layout: readme
+source: loopback-connector-openapi
+keywords: LoopBack, connector
+tags: readme
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/OpenAPI-connector.html
+summary:
+  The OpenAPI connector enables LoopBack applications to connect to OpenAPI data
+  sources.
+---