From 4238738b120de58e23a04a6164c1452329869518 Mon Sep 17 00:00:00 2001
From: Ralf Zerres <ralf.zerres@networkx.de>
Date: Sun, 28 Jun 2020 17:43:50 +0200
Subject: [PATCH] README.md: Describe how to setup and use diesel

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..016e12f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+<!-- README.md -->
+<!-- version: 1.0 -->
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+<!-- markdown-toc end -->
+
+# advotracker - database handling
+
+`advotracker` will make use of Diesel to handle SQL access functions.
+Diesel will requires Rust 1.24 or later.
+
+# Diesel Setup
+
+First of all, add the required dependencies to your projects Cargo.toml
+
+```bash
+[dependencies]
+diesel = { version = "1.4.4", features = ["sqlite" "chrono"] }
+dotenv = "0.15.0"
+```
+
+## CLI helper
+
+Diesel provides a separete CLI tool to help manage the project.
+This CLI should be installed on your system
+
+```bash
+cargo install diesel_cli
+cargo install diesel_cli --no-default-features --features sqlite3
+```
+
+## Database location
+
+We do uses `sqlite` for now. Use your distro package for sqlite3.
+
+Now direct diesel to the correct database instance. We can create an
+environment variable `DATABASE_URL`, that will point to the instance.
+For the test setup, we take advantage of an .env file:
+
+```.env
+DATABASE_URL=sqlite://username:password@localhost/advotracker
+#DATABASE_URL=postgres://username:password@localhost/advotracker
+```
+
+## Setup
+
+When managing the database schema, it will evolve over the time.
+Diesel takes that into account and supports a bundles called `Migrations`.
+They allow us define states that can be applied (up.sql) or reverted (down.sql).
+Applying and immediately reverting a migration should leave your database schema unchanged.
+
+```bash
+diesel setup
+diesel migration generate advotracker
+```
+
+The call will create the needed structure with as a subfolder `migrations`,
+holding a timstamp based subfolder with the migration name and to empty files.
+You'll see output that looks something like this:
+
+```bash
+Creating migrations/20200625133000_advotracker/up.sql
+Creating migrations/20200625133000_advotracker/down.sql
+```
+
+We can apply our new migration:
+
+```bash
+diesel migration run
+```
+
+To test out, that our sql scripts are working out as expected try the `redo`
+function. This will drop the given schema and create a new one using the
+adopted files in the migration path.
+
+```bash
+diesel migration run
+```
+
+Further infomation can be optained from [Diesel's project page][^1].
+
+---
+
+[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png "Creative Common Logo"
+[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode "Creative Common License"
+This work is licensed under a [Creative Common License 4.0][License-CC_BY]
+
+![Creative Common Logo][Logo-CC_BY]
+
+© 2020 Ralf Zerres, Networkx GmbH
+
+---
+
+Foodnotes
+
+[^1]: Diesel Guides:  https://diesel.rs/guides/getting-started/