From cdb855ef3fe190a8fdd14e3c50b54e0876b693e4 Mon Sep 17 00:00:00 2001
From: Pierre-Yves Chibon <pingou@pingoured.fr>
Date: Jul 30 2018 07:57:29 +0000
Subject: Improve/rework the documentation about database upgrade


Fixes https://pagure.io/pagure/issue/2379

Signed-off-by: Pierre-Yves Chibon <pingou@pingoured.fr>

---

diff --git a/doc/usage/upgrade_db.rst b/doc/usage/upgrade_db.rst
index dafa2d0..d16166f 100644
--- a/doc/usage/upgrade_db.rst
+++ b/doc/usage/upgrade_db.rst
@@ -2,16 +2,7 @@ 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/>`_.
+For changes to the database schema, 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.
 
@@ -20,6 +11,14 @@ To upgrade the database to the latest version simply run:
 
     alembic upgrade head
 
+.. note:: if pagure's configuration file isn't in ``/etc/pagure/pagure.cfg``
+        you will have to specify it to alembic using the command: ::
+
+            PAGURE_CONFIG=/path/to/pagure.cfg alembic upgrade head
+
+        This allow applies for the command specified below.
+
+
 This may fail for different reasons:
 
 * The change was already made in the database
@@ -27,12 +26,18 @@ This may fail for different reasons:
 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``
+  * 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>``.
+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