Mercurial > kallithea
comparison docs/dev/dbmigrations.rst @ 6023:9fd64dd2617d
docs: document how to use Alembic for database migrations
| author | Søren Løvborg <sorenl@unity3d.com> |
|---|---|
| date | Mon, 25 Jul 2016 15:33:21 +0200 |
| parents | |
| children | 2c3d30095d5e |
comparison
equal
deleted
inserted
replaced
| 6022:e36bc85e3ecb | 6023:9fd64dd2617d |
|---|---|
| 1 ======================= | |
| 2 Database schema changes | |
| 3 ======================= | |
| 4 | |
| 5 Kallithea uses Alembic for :ref:`database migrations <upgrade_db>` | |
| 6 (upgrades and downgrades). | |
| 7 | |
| 8 If you are developing a Kallithea feature that requires database schema | |
| 9 changes, you should make a matching Alembic database migration script: | |
| 10 | |
| 11 1. :ref:`Create a Kallithea configuration and database <setup>` for testing | |
| 12 the migration script, or use existing ``development.ini`` setup. | |
| 13 | |
| 14 Ensure that this database is up to date with the latest database | |
| 15 schema *before* the changes you're currently developing. (Do not | |
| 16 create the database while your new schema changes are applied.) | |
| 17 | |
| 18 2. Create a separate throwaway configuration for iterating on the actual | |
| 19 database changes:: | |
| 20 | |
| 21 paster make-config Kallithea temp.ini | |
| 22 | |
| 23 Edit the file to change database settings. SQLite is typically fine, | |
| 24 but make sure to change the path to e.g. ``temp.db``, to avoid | |
| 25 clobbering any existing database file. | |
| 26 | |
| 27 3. Make your code changes (including database schema changes in ``db.py``). | |
| 28 | |
| 29 4. After every database schema change, recreate the throwaway database | |
| 30 to test the changes:: | |
| 31 | |
| 32 rm temp.db | |
| 33 paster setup-db temp.ini --repos=/var/repos --user=doe --email doe@example.com --password=123456 --no-public-access --force-yes | |
| 34 paster repo-scan temp.ini | |
| 35 | |
| 36 5. Once satisfied with the schema changes, auto-generate a draft Alembic | |
| 37 script using the development database that has *not* been upgraded. | |
| 38 (The generated script will upgrade the database to match the code.) | |
| 39 | |
| 40 :: | |
| 41 | |
| 42 alembic -c development.ini revision -m "area: add cool feature" --autogenerate | |
| 43 | |
| 44 6. Edit the script to clean it up and fix any problems. | |
| 45 | |
| 46 Note that for changes that simply add columns, it may be appropriate | |
| 47 to not remove them in the downgrade script (and instead do nothing), | |
| 48 to avoid the loss of data. Unknown columns will simply be ignored by | |
| 49 Kallithea versions predating your changes. | |
| 50 | |
| 51 7. Run ``alembic -c development.ini upgrade head`` to apply changes to | |
| 52 the (non-throwaway) database, and test the upgrade script. Also test | |
| 53 downgrades. | |
| 54 | |
| 55 The included ``development.ini`` has full SQL logging enabled. If | |
| 56 you're using another configuration file, you may want to enable it | |
| 57 by setting ``level = DEBUG`` in section ``[handler_console_sql]``. | |
| 58 | |
| 59 The Alembic migration script should be committed in the same revision as | |
| 60 the database schema (``db.py``) changes. | |
| 61 | |
| 62 See the `Alembic documentation`__ for more information, in particular | |
| 63 the tutorial and the section about auto-generating migration scripts. | |
| 64 | |
| 65 .. __: http://alembic.zzzcomputing.com/en/latest/ | |
| 66 | |
| 67 | |
| 68 Troubleshooting | |
| 69 --------------- | |
| 70 | |
| 71 * If ``alembic --autogenerate`` responds "Target database is not up to | |
| 72 date", you need to either first use Alembic to upgrade the database | |
| 73 to the most recent version (before your changes), or recreate the | |
| 74 database from scratch (without your schema changes applied). |