diff --git a/docs/bin/build-preview-site.sh b/docs/bin/build-preview-site.sh index 76fa7e8b8d68..2bd15275ce7e 100755 --- a/docs/bin/build-preview-site.sh +++ b/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. diff --git a/docs/site/Cassandra-connector.md b/docs/site/Cassandra-connector.md new file mode 100644 index 000000000000..8bdf325cffd7 --- /dev/null +++ b/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. +--- diff --git a/docs/site/Cloudant-connector.md b/docs/site/Cloudant-connector.md new file mode 100644 index 000000000000..4571d048cb6c --- /dev/null +++ b/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/) + " %} diff --git a/docs/site/DB2-connector.md b/docs/site/DB2-connector.md new file mode 100644 index 000000000000..4fec082e6c80 --- /dev/null +++ b/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. +--- diff --git a/docs/site/DB2-for-i-connector.md b/docs/site/DB2-for-i-connector.md new file mode 100644 index 000000000000..cc4fe20f3d3b --- /dev/null +++ b/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. +--- diff --git a/docs/site/DB2-for-z-OS-connector.md b/docs/site/DB2-for-z-OS-connector.md new file mode 100644 index 000000000000..0b30fb60ea75 --- /dev/null +++ b/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. +--- diff --git a/docs/site/Example-kv-connector.md b/docs/site/Example-kv-connector.md new file mode 100644 index 000000000000..3354ea3f99d5 --- /dev/null +++ b/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. +--- diff --git a/docs/site/Executing-database-commands.md b/docs/site/Executing-database-commands.md new file mode 100644 index 000000000000..dd8c7fea3e66 --- /dev/null +++ b/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. + + + +- [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) diff --git a/docs/site/Installing-the-Oracle-connector.md b/docs/site/Installing-the-Oracle-connector.md new file mode 100644 index 000000000000..e1b73c34a7e1 --- /dev/null +++ b/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. +" %} diff --git a/docs/site/JSON-RPC-connector.md b/docs/site/JSON-RPC-connector.md new file mode 100644 index 000000000000..bae9aa1d7385 --- /dev/null +++ b/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. +--- diff --git a/docs/site/MQLight-connector.md b/docs/site/MQLight-connector.md new file mode 100644 index 000000000000..a4e7883103ae --- /dev/null +++ b/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. +--- diff --git a/docs/site/Memory-connector.md b/docs/site/Memory-connector.md new file mode 100644 index 000000000000..42674dd2d68c --- /dev/null +++ b/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 + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
nameStringName by which you refer to the data source.
connectorStringMust be "memory" to use the memory connector.
fileString +

Path to file where the connector will store data, relative to application root directory.

+

NOTE: The connector will create the file if necessary, but the directory containing the file must exist.

+
+ +{% 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. diff --git a/docs/site/MongoDB-connector.md b/docs/site/MongoDB-connector.md new file mode 100644 index 000000000000..dce4e79dd527 --- /dev/null +++ b/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. +--- diff --git a/docs/site/MySQL-connector.md b/docs/site/MySQL-connector.md new file mode 100644 index 000000000000..d0557577c3b4 --- /dev/null +++ b/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+. +" %} diff --git a/docs/site/OpenAPI-connector.md b/docs/site/OpenAPI-connector.md new file mode 100644 index 000000000000..f8ceb30a8a0b --- /dev/null +++ b/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. +--- diff --git a/docs/site/Oracle-connector.md b/docs/site/Oracle-connector.md new file mode 100644 index 000000000000..00901049c191 --- /dev/null +++ b/docs/site/Oracle-connector.md @@ -0,0 +1,20 @@ +--- +title: 'Oracle connector' +lang: en +layout: navgroup +navgroup: oracle +source: loopback-connector-oracle +keywords: LoopBack +tags: connectors +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Oracle-connector.html +summary: + The Oracle connector enables LoopBack applications to connect to Oracle data + sources. +--- + +{% 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. +" %} diff --git a/docs/site/PostgreSQL-connector.md b/docs/site/PostgreSQL-connector.md new file mode 100644 index 000000000000..7d4b57ae2f21 --- /dev/null +++ b/docs/site/PostgreSQL-connector.md @@ -0,0 +1,16 @@ +--- +title: 'PostgreSQL connector' +lang: en +layout: readme +source: loopback-connector-postgresql +keywords: LoopBack +tags: connectors +sidebar: lb4_sidebar +permalink: /doc/en/lb4/PostgreSQL-connector.html +summary: + The PostgreSQL connector enables LoopBack applications to connect to + PostgreSQL data sources. +--- + +{% include note.html content="The PostgreSQL connector requires PostgreSQL 8.x or 9.x. +" %} diff --git a/docs/site/REST-connector.md b/docs/site/REST-connector.md new file mode 100644 index 000000000000..b6611997e111 --- /dev/null +++ b/docs/site/REST-connector.md @@ -0,0 +1,13 @@ +--- +title: 'REST connector' +lang: en +layout: readme +source: loopback-connector-rest +keywords: LoopBack, REST +tags: [connectors, readme] +sidebar: lb4_sidebar +permalink: /doc/en/lb4/REST-connector.html +summary: + The REST connector enables LoopBack applications to interact with other (third + party) REST APIs. +--- diff --git a/docs/site/Redis-connector.md b/docs/site/Redis-connector.md new file mode 100644 index 000000000000..9893a737ebf5 --- /dev/null +++ b/docs/site/Redis-connector.md @@ -0,0 +1,102 @@ +--- +title: 'Redis connector' +lang: en +layout: page +toc: false +keywords: LoopBack +tags: connectors +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Redis-connector.html +summary: + The Redis connector enables LoopBack applications to connect to Redis data + sources. +--- + +{% include content/strongloop-labs.html lang=page.lang %} + +{% include toc.html %} + +{% include note.html content="The Redis connector requires Redis 3.0.3+. +" %} + +## Installation + +In your application root directory, enter this command to install the connector: + +```shell +$ npm install loopback-connector-redis --save +``` + +This will install the module and add it as a dependency to the +application's [`package.json`](package.json) file. + +## Creating a Redis data source + +Use the [data source generator](Data-source-generator.html) to add a Redis data +source to your application. When prompted for the connector, choose **other,** +then enter **redis** for the connector name. The entry in the application's +`server/datasources.json` will look like this: + +{% include code-caption.html content="server/datasources.json" %} + +```javascript +"redisDS": { + "name": "redisDS", + "connector": "redis", +} +``` + +Edit `datasources.json` to add other properties that enable you to connect the +data source to a Redis database. + +### Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
connectorString +

Connector name, either "loopback-connector-redis" or "redis"

+
databaseStringDatabase name
hostString + Database host name. For connector versions <= v0.1.0, when this property is set, + the port property **must also** be set. +
passwordStringPassword to connect to database
portNumberDatabase TCP port
urlStringUse instead host and port properties.
usernameStringUsername to connect to database
diff --git a/docs/site/SOAP-connector.md b/docs/site/SOAP-connector.md new file mode 100644 index 000000000000..c6b54be5464a --- /dev/null +++ b/docs/site/SOAP-connector.md @@ -0,0 +1,15 @@ +--- +title: 'SOAP connector' +lang: en +layout: readme +source: loopback-connector-soap +keywords: LoopBack, connector +tags: [connectors, readme] +sidebar: lb4_sidebar +permalink: /doc/en/lb4/SOAP-connector.html +summary: + The SOAP connector enables LoopBack applications to interact with SOAP-based + web services. +--- + +{% include navgroups/soap.md %} diff --git a/docs/site/SQL-Server-connector.md b/docs/site/SQL-Server-connector.md new file mode 100644 index 000000000000..4d7bbf7867de --- /dev/null +++ b/docs/site/SQL-Server-connector.md @@ -0,0 +1,16 @@ +--- +title: 'SQL Server connector' +lang: en +layout: readme +source: loopback-connector-mssql +keywords: LoopBack +tags: connectors +sidebar: lb4_sidebar +permalink: /doc/en/lb4/SQL-Server-connector.html +summary: + The SQL Server connector enables LoopBack applications to connect to Microsoft + SQL Server data sources. +--- + +{% include note.html content="The SQL Server connector requires SQL Server 2005+. +" %} diff --git a/docs/site/SQLite3.md b/docs/site/SQLite3.md new file mode 100644 index 000000000000..ecb630b4a26c --- /dev/null +++ b/docs/site/SQLite3.md @@ -0,0 +1,13 @@ +--- +title: 'SQLite3 connector' +lang: en +layout: readme +source: loopback-connector-sqlite3 +keywords: LoopBack, connector +tags: readme +sidebar: lb4_sidebar +permalink: /doc/en/lb4/SQLite3.html +summary: + The SQLite3 connector enables LoopBack applications to connect to SQLite3 data + sources. +--- diff --git a/docs/site/Working-with-data.md b/docs/site/Working-with-data.md index 0970fd5c5b62..f5ad1181b28c 100644 --- a/docs/site/Working-with-data.md +++ b/docs/site/Working-with-data.md @@ -79,3 +79,4 @@ See the following articles for more information: - [Skip filter](Skip-filter.html) - [Where filter](Where-filter.html) - [Using database transactions](Using-database-transactions.html) +- [Executing database commands](Executing-database-commands.md) diff --git a/docs/site/kv-redis-connector.md b/docs/site/kv-redis-connector.md new file mode 100644 index 000000000000..b79286d8d422 --- /dev/null +++ b/docs/site/kv-redis-connector.md @@ -0,0 +1,11 @@ +--- +title: 'Redis key-value connector' +lang: en +layout: readme +source: loopback-connector-kv-redis +keywords: LoopBack, connector +tags: [connectors, readme] +sidebar: lb4_sidebar +permalink: /doc/en/lb4/kv-redis-connector.html +summary: NOTE: This documentation page is an incomplete work in progress. +--- diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml index 167e32f19735..83fc42bf08a3 100644 --- a/docs/site/sidebars/lb4_sidebar.yml +++ b/docs/site/sidebars/lb4_sidebar.yml @@ -242,6 +242,10 @@ children: url: Database-migrations.html output: 'web, pdf' + - title: 'Executing database commands' + url: Executing-database-commands + output: 'web, pdf' + - title: 'Using TypeORM' output: 'web, pdf' children: