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.

1 files changed, 42 insertions, 6 deletions

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