From fb383030b9027b4af54dee54b7bcfa42f0815f4b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= <mbajtoss@gmail.com>
Date: Mon, 3 Aug 2020 17:07:08 +0200
Subject: [PATCH] docs: add a new page "Executing database commands"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>
---
 docs/site/Executing-database-commands.md | 61 ++++++++++++++++++++++++
 docs/site/Working-with-data.md           |  1 +
 docs/site/sidebars/lb4_sidebar.yml       |  4 ++
 3 files changed, 66 insertions(+)
 create mode 100644 docs/site/Executing-database-commands.md

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.
+
+<!-- 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)
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/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
index 6b54748f5ee9..1686eacd19b0 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: