# HG changeset patch
# User Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
# Date 1546033082 -3600
# Node ID 14e8dcffd279274429473ec1880dca06bc86b822
# Parent  445d6875c2eefdd8d10676e761cfe1e82581f78a
docs: upgrade: clarify database upgrade instructions

Alembic should be called with the new configuration file, which the
instructions already created as 'new.ini'.

diff -r 445d6875c2ee -r 14e8dcffd279 docs/upgrade.rst
--- a/docs/upgrade.rst	Wed Dec 26 21:39:32 2018 +0100
+++ b/docs/upgrade.rst	Fri Dec 28 22:38:02 2018 +0100
@@ -88,6 +88,8 @@
     pip install --upgrade -e .
     kallithea-cli front-end-build
 
+.. _upgrade_config:
+
 
 5. Upgrade your configuration
 -----------------------------
@@ -116,7 +118,7 @@
 
 First, run the following command to see your current database version::
 
-    alembic -c my.ini current
+    alembic -c new.ini current
 
 Typical output will be something like "9358dc3d6828 (head)", which is
 the current Alembic database "revision ID". Write down the entire output
@@ -129,12 +131,12 @@
 Next, if you are performing an *upgrade*: Run the following command to
 upgrade your database to the current Kallithea version::
 
-    alembic -c my.ini upgrade head
+    alembic -c new.ini upgrade head
 
 If you are performing a *downgrade*: Run the following command to
 downgrade your database to the given version::
 
-    alembic -c my.ini downgrade 0.4
+    alembic -c new.ini downgrade 0.4
 
 Alembic will show the necessary migrations (if any) as it executes them.
 If no "ERROR" is displayed, the command was successful.
@@ -151,6 +153,13 @@
 
     FAILED: No config file 'my.ini' found, or file has no '[alembic]' section
 
+.. note::
+    If you followed this upgrade guide correctly, you will have created a
+    new configuration file in section :ref:`Upgrading your configuration
+    <upgrade_config>`. When calling Alembic, make
+    sure to use this new config file. In this case, you should not get any
+    errors and the below manual steps should not be needed.
+
 If Alembic complains specifically about a missing ``alembic.ini``, it is
 likely because you did not specify a config file using the ``-c`` option.
 On the other hand, if the mentioned config file actually exists, you