From 316e88aeb8f210804950f766fd9b5abc334da45f Mon Sep 17 00:00:00 2001
From: Ralf Zerres <ralf.zerres@networkx.de>
Date: Tue, 30 Jun 2020 08:48:07 +0200
Subject: [PATCH] update README.md

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
---
 README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 93 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 016e12f..d2b7d63 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,15 @@
 
 # advotracker - database handling
 
-`advotracker` will make use of Diesel to handle SQL access functions.
-Diesel will requires Rust 1.24 or later.
+`advotracker` make use of [Diesel][^1] to handle all SQL access functionality.
+Diesel requires to be compiled with Rust version 1.24 or later.
 
-# Diesel Setup
+The actual version is tested with the `sqlite3` backend. All following documentation
+will reference to this constellation.
 
-First of all, add the required dependencies to your projects Cargo.toml
+# Diesel
+
+First of all, add the required dependencies to the projects Cargo.toml
 
 ```bash
 [dependencies]
@@ -21,15 +24,16 @@ 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
+Diesel provides a separate CLI tool to help manage the project.
+This CLI should be installed on your system. I you don't have that
+already available on you system, go and install it like this:
 
 ```bash
 cargo install diesel_cli
 cargo install diesel_cli --no-default-features --features sqlite3
 ```
 
-## Database location
+## Database Setup
 
 We do uses `sqlite` for now. Use your distro package for sqlite3.
 
@@ -38,46 +42,115 @@ 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=sqlite://localhost/advotracker
 #DATABASE_URL=postgres://username:password@localhost/advotracker
 ```
 
-## Setup
+- **Instantiate a new database**
 
-When managing the database schema, it will evolve over the time.
+In the beginning, there is .... nothing!
+We will create an empty database to get started:
+
+```bash
+$ sqlite3 <absolute_path_to>/advotracker.sqlite3>
+sqlite3 advotracker.sqlite3
+```
+
+- **Test availability**
+
+Sqlite will drop us in the CLI shell. Try to get available
+databases, which should response a `main` pointing to the
+absolute path of the created database.
+
+```bash
+
+SQLite version 3.32.3 2020-06-18 14:00:33
+Enter ".help" for usage hints.
+sqlite> .databases
+main: /<the_absolute_path>/advotracker.sqlite3
+.quit
+```
+
+All fine.
+
+## Diesel Setup
+
+When managing the database schema, probably 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.
+They allow us to define states, that can be applied (up.sql) or reverted (down.sql).
+Applying and immediately reverting a migration is a good test, to make sure you
+that the used migration leaves your database schema in the requested state.
+
+- **Instantiate a migration**
+
+The following command will crate the basic `advotracker` structure.
 
 ```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:
+You can review the generated structure in the subfolder `migrations`. It
+holds a timestamp based subfolder, named `<timestamp-advotracker`, that provides
+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:
+- **Update the SQL-files**
+
+Both files have to be updated to meet our target structure. `up.sql` will
+create tables, beside their constraints, indices and views. `down.sql` work
+delete the database schema providing a virgin state.
+If you leave this scripts empty, diesel can't generate the target `schema` file,
+that is used to provide the API consumed by you rust code.
+You are free to edit and apply this in a manual fashion, but this is not
+recommended.
+
+- **Migration run**
+
+We can apply the new migration like this:
 
 ```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
+Using the the `redo` command will prove the expected functionality: Run down and
+up scrips in a sequence. This will drop the given schema and create a new one using the
 adopted files in the migration path.
 
 ```bash
 diesel migration run
 ```
+- **Test our generated structure**
 
-Further infomation can be optained from [Diesel's project page][^1].
+As a basic success test, we the CLI interface should respond with a list of indices,
+if we call a query. Go ahead an run:
+
+```bash
+$ sqlite3 <abolute_path_to>/advotracker.sqlite3>
+SQLite version 3.32.3 2020-06-18 14:00:33
+Enter ".help" for usage hints.
+sqlite> .index
+claims_ix_id_user
+harms_ix_number_harm
+sqlite_autoindex___diesel_schema_migrations_1
+sqlite_autoindex_roles_1
+sqlite_autoindex_user_roles_1
+user_roles_ix_id_role
+user_roles_ix_id_user
+users_ix_email
+.quit
+```
+
+You are done. The database is ready to be accessed for the
+advotracker rust code.
+
+## Reference
+
+Any further information can be obtained from [Diesel's project page][^1].
 
 ---
 
@@ -91,6 +164,6 @@ This work is licensed under a [Creative Common License 4.0][License-CC_BY]
 
 ---
 
-Foodnotes
+Footnotes
 
 [^1]: Diesel Guides:  https://diesel.rs/guides/getting-started/