Blame doc/usage/upgrade_db.rst

Pierre-Yves Chibon 651b34
Upgrade a database
Pierre-Yves Chibon 651b34
==================
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
Database schema migration are handled in two ways:
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
* New tables
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
For this we simply rely on the ``createdb`` script used when creating the
Pierre-Yves Chibon 651b34
database the first time.
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
* Changes to existing tables
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
For changes to existing tables, we rely on `Alembic <http: alembic.readthedocs.org="">`_.</http:>
Pierre-Yves Chibon 651b34
This allows us to do upgrade and downgrade of schema migration, kind of like
Pierre-Yves Chibon 651b34
one would do commits in a system like git.
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
To upgrade the database to the latest version simply run:
Pierre-Yves Chibon 651b34
::
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
    alembic upgrade head
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
This may fail for different reasons:
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
* The change was already made in the database
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
This can be because the version of the database schema saved is incorrect.
Pierre-Yves Chibon 651b34
It can be debugged using the following commands:
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
  * Find the current revision: ``alembic current``
Pierre-Yves Chibon 651b34
  * See the entire history: ``alembic history``
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
Once the revision at which your database should be is found (in the history)
Pierre-Yves Chibon 651b34
you can declare that your database is at this given revision using:
Pierre-Yves Chibon 651b34
``alembic stamp <revision id="">``.</revision>
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
Eventually, if you do not know where your database is or should be, you can
Pierre-Yves Chibon 651b34
do an iterative process stamping the database for every revision, one by one
Pierre-Yves Chibon 651b34
trying everytime to ``alembic upgrade`` until it works.
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
* The database used does not support some of the changes
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
SQLite is handy for development but does not support all the features of a
Pierre-Yves Chibon 651b34
real database server. Upgrading a SQLite database might therefore not work,
Pierre-Yves Chibon 651b34
depending on the changes done.
Pierre-Yves Chibon 651b34
Pierre-Yves Chibon 651b34
In some cases, if you are using a SQLite database, you will have to destroy
Pierre-Yves Chibon 651b34
it and create a new one.