From 306f8d1fa8c70719684db06ded41cc0453fc089b Mon Sep 17 00:00:00 2001
From: Michael Hoennig <michael@hoennig.de>
Date: Thu, 28 Jul 2022 10:43:49 +0200
Subject: [PATCH] improved README.md with aliases for pg-sql-...

---
 .aliases  |  8 ++++++++
 README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 59 insertions(+), 5 deletions(-)
 create mode 100644 .aliases

diff --git a/.aliases b/.aliases
new file mode 100644
index 00000000..483931c5
--- /dev/null
+++ b/.aliases
@@ -0,0 +1,8 @@
+alias pg-sql-run='docker run --name hsadmin-ng-postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:13.7-bullseye'
+alias pg-sql-stop='docker stop hsadmin-ng-postgres'
+alias pg-sql-start='docker container start hsadmin-ng-postgres'
+alias pg-sql-remove='docker rm hsadmin-ng-postgres'
+alias pg-sql-reset='pg-sql-stop; pg-sql-remove; pg-sql-run'
+alias pg-sql-backup='docker exec -i hsadmin-ng-postgres /usr/bin/pg_dump --clean --create -U postgres postgres | gzip -9'
+alias pg-sql-restore='gunzip --stdout | docker exec -i hsadmin-ng-postgres psql -U postgres -d postgres'
+
diff --git a/README.md b/README.md
index 227a0eb6..cfcafc09 100644
--- a/README.md
+++ b/README.md
@@ -6,43 +6,69 @@
 
 So far the spike contains almost only PostgreSQL Code. 
 All you need so far, is a PostgreSQL database, for now with full admin rights.
-The easiest way to set it up is using docker:
+The easiest way to set it up is using docker.
+
+(Find the mentioned aliases in `.aliases`.)
 
 Initially, pull an image compatible to current PostgreSQL version of Hostsharing:
 
     docker pull postgres:13.7-bullseye
 
+<big>**&#9888;**</big>
+If we switch the version, please also amend the documentation as well as the aliases file. Thanks! 
+
 Create and run a container with the given PostgreSQL version:
 
     docker run --name hsadmin-ng-postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:13.7-bullseye
 
+    # or via alias: 
+    pg-sql-run
+
 To check if the PostgreSQL container is running, the following command should list a container with the name "hsadmin-ng-postgres": 
 
-    docker container ls
+    docker container ls 
 
 Stop the PostgreSQL container:
     
     docker stop hsadmin-ng-postgres
+    # or via alias: pg-sql-stop
 
 Start the PostgreSQL container again:
 
     docker container start hsadmin-ng-postgres
+    # or via alias: pg-sql-start
 
 Remove the PostgreSQL container:
 
     docker rm hsadmin-ng-postgres
+    
+    # or via alias:
+    pg-sql-remove
+
+To reset to a clean database, use:
+
+    pg-sql-stop; pg-sql-remove; pg-sql-run
+
+    # or via alias:
+    pg-sql-reset
 
 After the PostgreSQL container is removed, you need to create it again as shown in "Create and run ..." above.
 
 Given the container is running, to create a backup in ~/backup, run:
 
-    docker exec -i hsadmin-ng-postgres /usr/bin/pg_dump --clean --create -U postgres postgres | gzip -9 > ~/backup/hsadmin-ng-postgres2.sql.gz 
+    docker exec -i hsadmin-ng-postgres /usr/bin/pg_dump --clean --create -U postgres postgres | gzip -9 > ~/backup/hsadmin-ng-postgres.sql.gz
+
+    # or via alias:
+    pg-sql-backup >~/backup/hsadmin-ng-postgres.sql.gz
 
 
 Again, given the container is running, to restore the backup from ~/backup, run:
 
     gunzip --stdout --keep ~/backup/hsadmin-ng-postgres.sql.gz | docker exec -i hsadmin-ng-postgres psql -U postgres -d postgres
 
+    # or via alias:
+    pg-sql-restore <~/backup/hsadmin-ng-postgres.sql.gz
+
 
 ### Markdown with PlantUML plugin
 
@@ -72,7 +98,7 @@ sudo apt install graphviz
 ```
 
 
-### Ubuntu Linux command line
+#### Ubuntu Linux command line
 
 ```sh
 sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive-extra-utils texlive-latex-extra pandoc-plantuml-filter
@@ -82,6 +108,26 @@ sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive
 pandoc --filter pandoc-plantuml rbac.md -o rbac.pdf
 ```
 
-### for other IDEs / operating systems
+#### for other IDEs / operating systems
 
 If you have figured out how it works, please add instructions above this section.
+
+
+## Running the SQL files
+
+### For RBAC
+
+If you run the numbered SQL files from the `sql` folder in the defined order, a working RBAC system is built up in the database including test data and some simple tests.
+
+To increase the amount of test data, simply increase the number of generated customers in `21-hs-customer.sql`.
+
+If you already have data, e.g. for customers 0..999 (thus with reference numbers 10000..10999) and want to add another 1000 customers, amend the for loop to 1000...1999 and also uncomment and amend the `CONTINUE WHEN` or `WHERE` conditions in the other test data generators, using the first new customer reference number (in the example that's 11000).
+
+### For Historization
+
+You can explore the historization prototype as follows:
+
+- start with an empty database
+  (the example tables are currently not compatible with RBAC),
+- then run `historization.sql,`
+- finally run `examples.sql`.