diff --git a/doc/admin/admin-upgrade.rst b/doc/admin/admin-upgrade.rst new file mode 100644 index 000000000..74cc82180 --- /dev/null +++ b/doc/admin/admin-upgrade.rst @@ -0,0 +1,30 @@ +.. _admin-upgrade: + +Instructins for upgrading Qserv to newer releases +================================================= + +.. _admin-upgrade-mariadb-11-4-4: + +Upgrading Qserv to MariaDB 11.4.4 +--------------------------------- + +MariaDB 11.4.4 is a major release that introduces a number of new features and +improvements. If your instance of Qserv is still based on MariaDB 10.6.8, you +need to upgrade your data to the new version. + +To upgrade your Qserv installation to MariaDB 11.4.4, follow these steps: + +- Read the `MariaDB 11.4.4 release notes `_ to learn about the new features and improvements. +- Read the guide `Upgrading from MariaDB 10.6 to MariaDB 10.11 `_ to learn how to upgrade your databases. +- Turn Qserv into the database-only mode by ensuring that all but the MariaDB services are being run. +- Log into the MariaDB containers and run the database upgrade command as shown below: + + .. code-block:: bash + + mariadb-upgrade -P3306 -h127.0.0.1 --protocol=tcp -uroot -p****** + + Where ``-P`` specifies the port number, ``-h`` specifies the host, ``-u`` specifies the user, and ``-p`` specifies the password. + Note that the port number may be different in your installation. + +Experiments with the production databases at USDF (SLAC) have shown that the upgrade process is safe and reliable. +However, it is still recommended to make a backup of your data before proceeding with the upgrade. diff --git a/doc/admin/index.rst b/doc/admin/index.rst index 24bb3322b..fb13e2702 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -5,6 +5,13 @@ Administrator's Guide ##################### +.. warning:: + + This version of Qserv uses MariaDB version 11.4.4. If you still have an older release based on + MariaDB 10.6.8 then you should upgrade your databases as described in the following section: + + - :ref:`admin-upgrade-mariadb-11-4-4` + .. toctree:: :maxdepth: 4 @@ -12,3 +19,4 @@ Administrator's Guide row-counters data-table-indexes director-index + admin-upgrade