From bd0454de077d826a2c939ef1a8664a1ec913f0d5 Mon Sep 17 00:00:00 2001
From: Daniel <30466471+daniel0611@users.noreply.github.com>
Date: Sun, 1 Aug 2021 19:54:16 +0200
Subject: [PATCH] Add sample doc for SQL service

Adds docs for https://github.com/codeoverflow-org/nodecg-io/pull/237.
---
 docs/index.md       |  1 +
 docs/samples/sql.md | 48 +++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml          |  1 +
 3 files changed, 50 insertions(+)
 create mode 100644 docs/samples/sql.md

diff --git a/docs/index.md b/docs/index.md
index e4ae7a6a..f2a79af4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -41,6 +41,7 @@ If that's no problem you can head over to the [installation guide](./getting_sta
 -   [x] Serial Port (Arduino)
 -   [x] Slack WebAPI
 -   [x] Spotify
+-   [x] SQL (using [knex](https://knexjs.org/))
 -   [x] Elgato Stream Deck
 -   [x] StreamElements
 -   [x] Telegram
diff --git a/docs/samples/sql.md b/docs/samples/sql.md
new file mode 100644
index 00000000..39af69b9
--- /dev/null
+++ b/docs/samples/sql.md
@@ -0,0 +1,48 @@
+## Using the SQL sample bundle
+
+The SQL example bundle in `samples/sql` demonstrates the ability to access databases. Here is a guide to how to get it working.
+
+### Prerequisites
+
+-   Working NodeCG & nodecg-io installation
+-   A database supported by [knex](https://knexjs.org/#Installation)
+
+_Note:_ If you don't have a database yet and just want to test things you can use sqlite3 and don't need to setup a database server. You can always move to a different database type later.
+
+### Configure the SQL sample bundle
+
+1. Start nodecg with nodecg-io installed. The SQL sample bundle is currently part of it so it should also be loaded.
+
+2. Go to the `nodecg-io` tab in the nodecg dashboard.
+
+3. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials.
+
+4. Create a new SQL service instance using the left upper menu.
+
+5. Enter configuration for SQL.
+
+    The created instance should be automatically selected, if not select it in the upper left menu. Enter your used database client and a [knex connection object](https://knexjs.org/#Installation-client) in monaco (the text-editor on the right) in this format:
+
+    ```json
+    {
+        "client": "mysql",
+        "connection": {
+            "host": "localhost",
+            ...
+        }
+    }
+    ```
+
+    After entering it, click save.
+
+    _Note:_ If you don't see monaco on the right, try reloading the page.
+
+6. Set the created SQL service instance to the service dependency of the SQL sample bundle.
+
+    Select the SQL sample bundle and the SQL service in the left bottom menu and then select the service instance that should be used by the SQL sample bundle (in this case the name of the previously created SQL instance).
+
+7. Check the nodecg logs
+
+    Your first run of the sample bundle will probably fail because your database doesn't contain the used tables. 
+    Check `samples/sql/extension/index.ts` and create the tables as used or create your own tables and adapt the sample accordingly.
+    You can also use this code as a reference on how to use the sql client to do your queries.
diff --git a/mkdocs.yml b/mkdocs.yml
index 757d64ef..4845589e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -68,6 +68,7 @@ nav:
           - Serial sample: samples/serial.md
           - Slack sample: samples/slack.md
           - Spotify sample: samples/spotify.md
+          - SQL sample: samples/sql.md
           - Streamdeck sample: samples/streamdeck.md
           - StreamElements sample: samples/streamelements.md
           - Telegram sample: samples/telegram.md