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