Mercurial > kallithea
comparison docs/dev/dbmigrations.rst @ 7626:19af3fef3b34 stable
merge default to stable for 0.4.0
author | Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> |
---|---|
date | Sun, 31 Mar 2019 21:28:56 +0200 |
parents | 3158cf0dafb7 |
children |
comparison
equal
deleted
inserted
replaced
7558:fdee9a036bee | 7626:19af3fef3b34 |
---|---|
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 kallithea-cli config-create 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 kallithea-cli db-create -c temp.ini --repos=/var/repos --user=doe --email doe@example.com --password=123456 --no-public-access --force-yes | |
34 kallithea-cli repo-scan -c 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). |