diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst
index 59bd8f782..1cc854e15 100644
--- a/doc/getting_started/upgrade.rst
+++ b/doc/getting_started/upgrade.rst
@@ -165,6 +165,18 @@ Several modifications need to be done into *settings.py*.
         }
     }
 
+Postfix and Dovecot configuration update
+----------------------------------------
+
+It is necessary to update the queries used to retrieve users and mailboxes:
+
+#. Replace all occurences of ``auth_user`` by ``admin_user``
+
+#. Into *dovecot-sql.conf*, update the ``user_query`` query, refer to
+   :ref:`dovecot_mysql_queries` or :ref:`dovecot_pg_queries`
+
+#. Update dovecot's configuration to activate the new :ref:`quota related features <dovecot_quota>`
+
 Migration issues
 ----------------
 
diff --git a/doc/integration/imap_and_smtp.rst b/doc/integration/imap_and_smtp.rst
index 2c274da9e..885570356 100644
--- a/doc/integration/imap_and_smtp.rst
+++ b/doc/integration/imap_and_smtp.rst
@@ -81,7 +81,15 @@ content inside::
 Make sure to activate only one backend (per type) inside your configuration
 (just comment the other ones).
 
-*MySQL* users, edit the *dovecot-sql.conf.ext* file and modify following lines::
+Edit the *dovecot-sql.conf.ext* and modify the configuration according
+to your database engine.
+
+.. _dovecot_mysql_queries:
+
+*MySQL* users
+-------------
+
+::
 
   driver = mysql
 
@@ -95,7 +103,12 @@ Make sure to activate only one backend (per type) inside your configuration
 
   iterate_query = SELECT email AS username FROM admin_user
 
-*PostgreSQL* users, here is your version::
+.. _dovecot_pg_queries:
+
+*PostgreSQL* users
+------------------
+
+::
 
   driver = postgresql
 
@@ -121,6 +134,8 @@ address. Open the *conf.d/15-lda.conf* file modify the following line::
 
   postmaster_address = postmaster@<domain>
 
+.. _dovecot_quota:
+
 Quota
 =====