docs(admin): Clarify DB conversion steps and command usage (#11584)

Signed-off-by: Josh <josh.t.richards@gmail.com>
Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com>

admin_manual/configuration_database/db_conversion.rst

@@ -11,37 +11,72 @@ multiple-user production servers.
 Run the conversion
 ------------------
 
-First set up the new database, here called "new_db_name".
+Conversion consists of two steps:
-In Nextcloud root folder call
+
+1. Establishing the target database (including its credentials)
+2. Triggering the conversion tool which migrates the contents of the existing database to the target database
+
+Establishing the target database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First create up the target (new) database (along with its associated username and password) by following the manual database configuration instructions for your chosen target database type: 
+
+* :ref:`db-config-mysql-label`
+* :ref:`db-config-postgresql-label`
+
+Since the above db instructions uses the database name ``nextcloud`` for the newly created database we will do so here for consistency, but you are free to use whatever database name you prefer. Use
+the database name, database username, and database password you specified when creating the new database.
+
+Triggering the conversion
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``occ db:convert-type`` command handles all the tasks of the conversion. The following are the parameters available:
 
 ::
 
   php occ db:convert-type [options] type username hostname database
 
-The Options
+``type`` should be the target database type. The same values are available here as for the ``config.php`` ``dbtype`` parameter. It should be one of: ``mysql`` for MariaDB/MySQL, 
+``pgsql`` for PostgresSQL, or ``oci`` for Oracle.
 
-* ``--port="3306"``                       the database port (optional)
+The options:
+
+* ``--port="3306"``                       the database port (optional) [defaults to "3306"]
 * ``--password="mysql_user_password"``    password for the new database. If omitted the tool will ask you (optional)
 * ``--clear-schema``                      clear schema (optional)
 * ``--all-apps``                          by default, tables for enabled apps are converted, use to convert also tables of deactivated apps (optional)
 * ``-n, --no-interaction``                do not ask any interactive question
 
-*Note:* The converter searches for apps in your configured app folders and uses
+.. note:: The conversion tool searches for apps in your configured app folders and uses
-the schema definitions in the apps to create the new table. So tables of removed
+   the schema (table) definitions in the apps to create the new tables. Any tables that still exist for removed
-apps will not be converted even with option ``--all-apps``
+   apps will not be converted (even with option ``--all-apps``).
 
-For example
+Let's convert our existing (functioning) sqlite3 installation to be MariaDB/MySQL based:
 
 ::
 
-  php occ db:convert-type --all-apps mysql oc_mysql_user 127.0.0.1 new_db_name
+  php occ db:convert-type --password="<password>" --port="3306" --all-apps mysql <username> <hostname> nextcloud
 
-To successfully proceed with the conversion, you must type ``yes`` when prompted
+.. note:: It was unnecessary to specify the port in this example because ``3306`` is already the default. We did so 
-with the question ``Continue with the conversion?``
+   merely for demonstration purposes and completeness in case the reader is using a non-standard port on their target 
+   database server.
 
 On success the converter will automatically configure the new database in your
 Nextcloud config ``config.php``.
 
+If you are converting to a MySQL/MariaDB database, you will also want to set ``mysql.utf8mb4`` parameter to true in your ``config.php``:
+
+::
+
+   php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
+
+If you like, you can view the changes that were made by looking for the ``db*`` parameters in your ``config.php`` (you could also use this command before 
+doing the conversion to compare your configuration before/after):
+
+::
+
+   grep db config/config.php
+
 Inconvertible tables
 --------------------
 

admin_manual/configuration_database/linux_database_configuration.rst

@@ -36,6 +36,8 @@ Parameters
 ----------
 For setting up Nextcloud to use any database, use the instructions in :doc:`../installation/installation_wizard`. You should not have to edit the respective values in the :file:`config/config.php`.  However, in special cases (for example, if you want to connect your Nextcloud instance to a database created by a previous installation of Nextcloud), some modification might be required.
 
+.. _db-config-mysql-label:
+
 Configuring a MySQL or MariaDB database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -182,6 +184,8 @@ This just covers the SSL database configuration on the Nextcloud server. First y
 
 Adjust the paths to the pem files for your environment.
 
+.. _db-config-postgresql-label:
+
 PostgreSQL database
 ^^^^^^^^^^^^^^^^^^^