postgres automatic schema management roughly working

README.md

@@ -0,0 +1,41 @@
+# capsulflask
+
+Python Flask web application for capsul.org
+
+## postgres database schema management
+
+capsulflask has a concept of a schema version. When the application starts, it will query the database for a table named
+`schemaversion` that has one row and one column (`version`). If the `version` it finds is not equal to the `desiredSchemaVersion` variable set in `db.py`, it will run  migration scripts from the `schema_migrations` folder one by one until the `schemaversion` table shows the correct version.
+
+For example, the script named `02_up_xyz.sql` should contain code that migrates the database in a reverse-able fashion from schema version 1 to schema version 2. Likewise, the script `02_down_xyz.sql` should contain code that migrates from schema version 2 back to schema version 1.
+
+**IMPORTANT: if you need to make changes to the schema, make a NEW schema version. DO NOT EDIT the existing schema versions.**
+
+## how to run locally
+
+Ensure you have the pre-requisites for the psycopg2 Postgres database adapter package
+
+```
+sudo apt-get install python3-dev libpq-dev
+pg_config --version
+```
+
+Create python virtual environment and install packages
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Run an instance of Postgres (I used docker for this, point is its listening on localhost:5432)
+
+```
+docker run -it -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres
+```
+
+Run the app 
+
+```
+FLASK_APP=capsulflask flask run
+```