diff --git a/admin_manual/configuration_database/db_conversion.rst b/admin_manual/configuration_database/db_conversion.rst index b70e7e8c0..6df0b2c0f 100644 --- a/admin_manual/configuration_database/db_conversion.rst +++ b/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". -In Nextcloud root folder call +Conversion consists of two steps: + +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 -the schema definitions in the apps to create the new table. So tables of removed -apps will not be converted even with option ``--all-apps`` +.. note:: The conversion tool searches for apps in your configured app folders and uses + 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``). -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="" --port="3306" --all-apps mysql nextcloud -To successfully proceed with the conversion, you must type ``yes`` when prompted -with the question ``Continue with the conversion?`` +.. note:: It was unnecessary to specify the port in this example because ``3306`` is already the default. We did so + 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 -------------------- diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index d0bba8376..c71eda8e4 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^