Document box.schema.downgrade (#3434)

Author: andreyaksenov

doc/book/admin/upgrades.rst

@@ -3,6 +3,9 @@
 Upgrades
 ========
 
+This topic outlines the general upgrade process for Tarantool.
+If required, you can also downgrade to one of the previous versions using a similar procedure.
+
 For information about backwards compatibility,
 see the :ref:`compatibility guarantees <compatibility_guarantees>` description.
 
@@ -30,6 +33,10 @@ replication cluster (see :ref:`below <admin-upgrades_replication_cluster>`).
     There is no need  to run ``box.schema.upgrade()`` on every node:
     changes are propagated to other nodes via the regular replication mechanism.
 
+    .. NOTE::
+
+        To undo schema upgrade in a case of failed upgrade, you can use :ref:`box.schema.downgrade() <box_schema-downgrade>`.
+
 #.  Update your application files, if needed.
 
 #.  Launch the updated Tarantool server using ``tarantoolctl``, ``tt``, or ``systemctl``.
@@ -96,6 +103,10 @@ Upgrade procedure
     There is no need  to run ``box.schema.upgrade()`` on every node:
     changes are propagated to other nodes via the regular replication mechanism.
 
+    .. NOTE::
+
+        To undo schema upgrade in a case of failed upgrade, you can use :ref:`box.schema.downgrade() <box_schema-downgrade>`.
+
 8.  Run ``box.snapshot()`` on every node in the replica set
     to make sure that the replicas immediately see the upgraded database state in case of restart.
 

doc/reference/reference_lua/box_schema.rst

@@ -17,7 +17,7 @@ Below is a list of all ``box.schema`` functions.
     ..  rst-class:: left-align-column-2
 
     ..  list-table::
-        :widths: 25 75
+        :widths: 35 65
         :header-rows: 1
 
         *   - Name
@@ -29,6 +29,15 @@ Below is a list of all ``box.schema`` functions.
         *  - :doc:`./box_schema/upgrade`
            - Upgrade a database
 
+        *  - :doc:`./box_schema/downgrade`
+           - Downgrade a database
+
+        *  - :doc:`./box_schema/downgrade_issues`
+           - List downgrade issues for the specified Tarantool version
+
+        *  - :doc:`./box_schema/downgrade_versions`
+           - List Tarantool versions available for downgrade
+
         *  - :doc:`./box_schema/user_create`
            - Create a user
 
@@ -88,6 +97,9 @@ Below is a list of all ``box.schema`` functions.
 
     box_schema/space_create
     box_schema/upgrade
+    box_schema/downgrade
+    box_schema/downgrade_versions
+    box_schema/downgrade_issues
     box_schema/user_create
     box_schema/user_drop
     box_schema/user_exists

doc/reference/reference_lua/box_schema/downgrade.rst

@@ -0,0 +1,43 @@
+..  _box_schema-downgrade:
+
+box.schema.downgrade()
+======================
+
+..  module:: box.schema
+
+..  function:: box.schema.downgrade(version)
+
+    Allows you to downgrade a database to the specified Tarantool version.
+    This might be useful if you need to run a database on older Tarantool versions.
+
+    To prepare a database for using it on an older Tarantool instance,
+    call ``box.schema.downgrade`` and pass the desired Tarantool version:
+
+    ..  code-block:: tarantoolsession
+
+        tarantool> box.schema.downgrade('2.8.4')
+
+    .. NOTE::
+
+        The Tarantool's downgrade procedure is similar to the upgrade process that is described in the :ref:`Upgrades <admin-upgrades>` topic.
+        You need to run ``box.schema.downgrade()`` only on master and execute `box.shapshot()` on every instance in a replica set before restart to an older version.
+
+    To see Tarantool versions available for downgrade, call :ref:`box.schema.downgrade_versions() <box_schema-downgrade_versions>`. The oldest release available for downgrade is ``2.8.2``.
+
+    Note that the downgrade process might fail if the database enables specific features not supported
+    in the target Tarantool version.
+    You can see all such issues using the :ref:`box.schema.downgrade_issues() <box_schema-downgrade_issues>` method,
+    which accepts the target version.
+    For example, ``downgrade`` to the ``2.8.4`` version fails if you use `tuple compression <https://www.tarantool.io/en/enterprise_doc/tuple_compression/>`__ or field :ref:`constraints <index-constraint_functions>` in your database:
+
+    ..  code-block:: tarantoolsession
+
+        tarantool> box.schema.downgrade_issues('2.8.4')
+        ---
+        - - Tuple compression is found in space 'bands', field 'band_name'. It is supported
+            starting from version 2.10.0.
+          - Field constraint is found in space 'bands', field 'year'. It is supported starting
+            from version 2.10.0.
+        ...
+
+    See also: :ref:`box.schema.upgrade() <box_schema-upgrade>`

doc/reference/reference_lua/box_schema/downgrade_issues.rst

@@ -0,0 +1,14 @@
+..  _box_schema-downgrade_issues:
+
+box.schema.downgrade_issues()
+=============================
+
+..  module:: box.schema
+
+..  function:: box.schema.downgrade_issues(version)
+
+    Return a list of downgrade issues for the specified Tarantool version.
+    To learn how to downgrade a database to the specified Tarantool version, see :ref:`box.schema.downgrade() <box_schema-downgrade>`.
+
+    :return: a list of downgrade issues
+    :rtype: table

doc/reference/reference_lua/box_schema/downgrade_versions.rst

@@ -0,0 +1,14 @@
+..  _box_schema-downgrade_versions:
+
+box.schema.downgrade_versions()
+===============================
+
+..  module:: box.schema
+
+..  function:: box.schema.downgrade_versions()
+
+    Return a list of Tarantool versions available for downgrade.
+    To learn how to downgrade a database to the specified Tarantool version, see :ref:`box.schema.downgrade() <box_schema-downgrade>`.
+
+    :return: a list of Tarantool versions
+    :rtype: table

doc/reference/reference_lua/box_schema/upgrade.rst

@@ -10,6 +10,7 @@ box.schema.upgrade()
     If you created a database with an older Tarantool version and have now installed
     a newer version, make the request ``box.schema.upgrade()``. This updates
     Tarantool system spaces to match the currently installed version of Tarantool.
+    You can learn about the general upgrade process from the :ref:`Upgrades <admin-upgrades>` topic.
 
     For example, here is what happens when you run ``box.schema.upgrade()`` with a
     database created with Tarantool version 1.6.4 to version 1.7.2 (only a small
@@ -31,3 +32,5 @@ box.schema.upgrade()
     :ref:`initialization file <index-init_label>`.
     On startup, this will create new system spaces, update data type names (for example,
     ``num`` -> ``unsigned``, ``str`` -> ``string``) and options in Tarantool system spaces.
+
+    See also: :ref:`box.schema.downgrade() <box_schema-downgrade>`