diff options
Diffstat (limited to 'migrations/README')
-rw-r--r-- | migrations/README | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/migrations/README b/migrations/README new file mode 100644 index 00000000..301d0e54 --- /dev/null +++ b/migrations/README @@ -0,0 +1,48 @@ +This directory contains Alembic's environment for managing database migrations. + +From Alembic's documentation: Alembic is a lightweight database migration tool +for usage with the SQLAlchemy Database Toolkit for Python. +https://alembic.sqlalchemy.org/en/latest/index.html + + +Upgrading to the latest version +------------------------------- + +Simply run `alembic upgrade head` from aurweb's root. + + +Creating new migrations +----------------------- + +When working with Alembic and SQLAlchemy, you should never edit the database +schema manually. Please proceed like this instead: + +1. Edit `aurweb/schema.py` to your liking. +2. Run `alembic revision --autogenerate -m "your message"` +3. Proofread the generated migration. +4. Run `alembic upgrade head` to apply the changes to the database. +5. Commit the new migration. + +To revert a migration, you may run `alembic downgrade -1` and then manually +delete the migration file. Note that SQLite is limited and that it's sometimes +easier to recreate the database. + +For anything more complicated, please read Alembic's documentation. + + +Troubleshooting +--------------- + +- `ModuleNotFoundError: No module named 'aurweb'` + + You may either install the aurweb module with pip, or set PYTHONPATH to your + aurweb repository. Since alembic must be run from the aurweb root, you may + simply use: `PYTHONPATH=. alembic [...]`. + +- `FAILED: No config file 'alembic.ini' found, or file has no '[alembic]' section` + + You need to run Alembic from the project's root, and not from `migrations/`. + +- `configparser.NoSectionError: No section: 'database'` + + You need to set AUR_CONFIG, as explained in `TESTING`. |