From 0bdc5bc67015d964bad839df12cd57c8b288e30d Mon Sep 17 00:00:00 2001
From: Frederick Muriuki Muriithi
Date: Sun, 13 Nov 2022 04:11:30 +0300
Subject: Documentation: Explain how to run migrations

* .gitignore: ignore all yoyo configuration files
* README.md: Update documentation
* yoyo.auth.ini: stop tracking the yoyo configuration file.
---
 .gitignore    |  5 ++++-
 README.md     | 48 ++++++++++++++++++++++++++++++++++++++++++------
 yoyo.auth.ini |  6 ------
 3 files changed, 46 insertions(+), 13 deletions(-)
 delete mode 100644 yoyo.auth.ini

diff --git a/.gitignore b/.gitignore
index c5cf3e2..eff1d77 100644
--- a/.gitignore
+++ b/.gitignore
@@ -181,4 +181,7 @@ dmypy.json
 .pyre/
 
 # emacs temporary files
-/**/*~
\ No newline at end of file
+/**/*~
+
+# yoyo configs
+/**/yoyo*.ini
\ No newline at end of file
diff --git a/README.md b/README.md
index 36084c4..27326ba 100644
--- a/README.md
+++ b/README.md
@@ -103,27 +103,63 @@ See also instructions in [.guix.scm](.guix.scm).
 
 The migration scripts for the authentication and authorisation system are in the *migrations/auth* folder in the root of the repository.
 
-To create an new migration, do:
+To create an new migration script for the, do:
 
 ```bash
-$ yoyo new --config=yoyo.auth.ini -m "<description of the migration>"
+$ yoyo new -m "<description of the migration>" ./migrations/auth/
 ```
 
-That initialises an new migration script under the *migrations/auth* folder and gives it a name derived from the date, the sequence for that day, and the provided description.
-
-e.g.
+The command will ask whether you want to save the migration configuration, e.g.
 
 ```bash
 $ yoyo new --config=yoyo.auth.ini -m "testing a new migration"
 Error: could not open editor!
 Created file ./migrations/auth/20221103_02_HBzwk-testing-a-new-migration.py
+Save migration configuration to yoyo.ini?
+This is saved in plain text and contains your database password.
+
+Answering 'y' means you do not have to specify the migration source or database connection for future runs [yn]:
 ```
 
+If you specify `y` then a file named yoyo.ini will be created in your current working directory, and you can refer to it to avoid providing the `./migrations/auth` explicitly.
+
 Now you can open and edit the scripts to provide the appropriate SQL statements to update or rollback your schema.
 
 ### Running the Migrations
 
-**TODO**: Document how to run the migrations
+To apply the migrations, you can do something like:
+
+```bash
+$ yoyo apply --database="sqlite:////tmp/test-auth.db" ./migrations/auth/
+
+[20221103_01_js9ub-initialise-the-auth-entic-oris-ation-database]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221103_02_sGrIs-create-user-credentials-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221108_01_CoxYh-create-the-groups-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+[20221108_02_wxTr9-create-privileges-table]
+Shall I apply this migration? [Ynvdaqjk?]: Y
+
+...
+```
+
+If you have previously initialised the yoyo config file, you can put the database uri in the configuration file and just provide it to avoid the prompt to save the configuration.
+
+As a convenience, and to enable the CI/CD to apply the migrations automatically, I have provided a flask cli command that can be run with:
+
+```bash
+$ export FLASK_APP=main.py
+$ flask apply-migrations
+```
+
+This expects that the following two configuration variables are set in the application:
+
+* `AUTH_MIGRATIONS`: path to the migration scripts
+* `AUTH_DB`: path to the sqlite database file (will be created if absent)
 
 ## Running Tests
 
diff --git a/yoyo.auth.ini b/yoyo.auth.ini
deleted file mode 100644
index 097c17b..0000000
--- a/yoyo.auth.ini
+++ /dev/null
@@ -1,6 +0,0 @@
-[DEFAULT]
-sources = ./migrations/auth/
-migration_table = _yoyo_migration
-batch_mode = off
-verbosity = 0
-
-- 
cgit v1.2.3