aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFrederick Muriuki Muriithi2022-11-13 04:11:30 +0300
committerFrederick Muriuki Muriithi2022-11-13 04:11:30 +0300
commit0bdc5bc67015d964bad839df12cd57c8b288e30d (patch)
tree26cbb291b52878830801d3d130cb1f0cc3ba3b6d
parent3bc52c3c6fb86f599f1f086fb62009a0af562f41 (diff)
downloadgenenetwork3-0bdc5bc67015d964bad839df12cd57c8b288e30d.tar.gz
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.
-rw-r--r--.gitignore5
-rw-r--r--README.md48
-rw-r--r--yoyo.auth.ini6
3 files changed, 46 insertions, 13 deletions
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
-