Review fixes

p7nov · p7nov · commit 6f9be5e40bca · 2024-10-01T14:15:44.000+07:00
diff --git a/doc/platform/ddl_dml/migrations/basic_migrations_tt.rst b/doc/platform/ddl_dml/migrations/basic_migrations_tt.rst
@@ -26,7 +26,8 @@ Preparing a cluster
 The centralized migration mechanism works with Tarantool EE clusters that:
 
 -   use etcd as a centralized configuration storage
--   use the `CRUD <https://github.com/tarantool/crud>`__ module for data distribution
+-   use the `CRUD <https://github.com/tarantool/crud>`__ module or its Enterprise
+    version for data distribution
 
 ..  _basic_migrations_tt_cluster_etcd:
 
@@ -268,7 +269,9 @@ Check the migrations status with ``tt migration status``:
 To make sure that the space and indexes are created in the cluster, connect to the router
 instance and retrieve the space information:
 
-.. code-block:: $ tt connect myapp:router-001
+.. code-block:: console
+
+    $ tt connect myapp:router-001-a
 
 .. code-block:: tarantoolsession
 
diff --git a/doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst b/doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst
@@ -59,10 +59,14 @@ the ``--force-reapply`` option:
 If execution of the incorrect migration version has failed, you may also need to add
 the ``--ignore-preceding-status`` option:
 
+When you reapply a migration, ``tt`` checks the statuses of preceding migrations
+to ensure consistency. To skip this check, add the ``--ignore-preceding-status`` option:
+
 .. code-block:: console
 
-    $ tt migrations apply http://app_user:config_pass@localhost:2379/myapp \
+    $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \
                           --tarantool-username=client --tarantool-password=secret \
+                          --migration=00003_alter_space.lua
                           --force-reapply --ignore-preceding-status
 
 ..  _centralized_migrations_tt_troubleshoot_stop:
@@ -77,11 +81,16 @@ To interrupt migration execution on the cluster, use ``tt migrations stop``:
     $ tt migrations stop "http://app_user:config_pass@localhost:2379/myapp" \
                           --tarantool-username=client --tarantool-password=secret
 
-To avoid such situations in the future, restrict the maximum migration execution time
-using the ``--execution-timeout`` option of ``tt migrations apply``:
+You can adjust the maximum migration execution time using the ``--execution-timeout``
+option of ``tt migrations apply``:
 
 .. code-block:: console
 
     $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \
                           --tarantool-username=client --tarantool-password=secret \
-                          --execution-timeout=60
+                          --execution-timeout=60
+
+.. note::
+
+    If a migration timeout is reached, you may need to call ``tt migrations stop``
+    to cancel requests that were sent when applying migrations.
diff --git a/doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst b/doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst
@@ -25,7 +25,7 @@ Writing a complex migration
 Complex migrations require data migration along with schema migration. Connect to
 the router instance and insert some tuples into the space before proceeding to the next steps.
 
-.. code-block:: $ tt connect myapp:router-001
+.. code-block:: $ tt connect myapp:router-001-a
 
 .. code-block:: tarantoolsession
 
@@ -125,13 +125,15 @@ Apply the published migrations:
 
 Connect to the router instance and check that the space and its tuples have the new format:
 
-.. code-block:: $ tt connect myapp:router-001
+.. code-block:: console
+
+    $ tt connect myapp:router-001-a
 
 .. code-block:: tarantoolsession
 
     myapp:router-001-a> require('crud').get('writers', 2)
     ---
-    - rows: []
+    - rows: [2, 401, 'Douglas', 'Adams', 49]
       metadata: [{'name': 'id', 'type': 'number'}, {'name': 'bucket_id', 'type': 'number'},
         {'name': 'first_name', 'type': 'string'}, {'name': 'last_name', 'type': 'string'},
         {'name': 'age', 'type': 'number'}]
diff --git a/doc/tooling/tt_cli/migrations.rst b/doc/tooling/tt_cli/migrations.rst
@@ -22,56 +22,14 @@ on using the centralized migrations mechanism.
 
 ``COMMAND`` is one of the following:
 
-*   :ref:`apply <tt-migrations-apply>`
+
 *   :ref:`publish <tt-migrations-publish>`
-*   :ref:`remove <tt-migrations-remove>`
+*   :ref:`apply <tt-migrations-apply>`
 *   :ref:`status <tt-migrations-status>`
 *   :ref:`stop <tt-migrations-stop>`
+*   :ref:`remove <tt-migrations-remove>`
 
 
-.. _tt-migrations-apply:
-
-apply
------
-
-..  code-block:: console
-
-    $ tt migrations apply ETCD_URI [OPTION ...]
-
-``tt migrations apply`` applies :ref:`published <tt-migrations-publish>` migrations
-to the cluster. It executes all migrations from the cluster's centralized
-configuration storage on all its read-write instances (replica set leaders).
-
-.. code-block:: console
-
-    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
-                        --tarantool-username=admin --tarantool-password=pass
-
-To apply a single published migration, pass its name in the ``--migration`` option:
-
-.. code-block:: console
-
-    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
-                        --tarantool-username=admin --tarantool-password=pass  \
-                        --migration=000001_create_space.lua
-
-To apply migrations on a single replica set, specify the ``replicaset`` option:
-
-.. code-block:: console
-
-    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
-                        --tarantool-username=admin --tarantool-password=pass  \
-                        --replicaset=storage-001
-
-The command also provides options for migration troubleshooting: ``--ignore-order-violation``,
-``--force-reapply``, and ``--ignore-preceding-status``. Learn to use them in
-:ref:`centralized_migrations_tt_troubleshoot`.
-
-.. warning::
-
-    The use of migration troubleshooting options may lead to migration inconsistency
-    in the cluster. Use them only for local development and testing purposes.
-
 .. _tt-migrations-publish:
 
 publish
@@ -125,66 +83,52 @@ When publishing migrations, ``tt`` performs checks for:
 .. warning::
 
     Using the options that ignore checks when publishing migration may cause
-    migration inconsistency in the etcd storage.
+    migration inconsistency in the cluster.
 
-.. _tt-migrations-remove:
 
-remove
-------
+.. _tt-migrations-apply:
 
-..  code-block:: console
+apply
+-----
 
-    $ tt migrations remove ETCD_URI [OPTION ...]
+..  code-block:: console
 
-``tt migrations remove`` removes published migrations from the centralized storage.
-With additional options, it can also remove the information about the migration execution
-on the cluster instances.
+    $ tt migrations apply ETCD_URI [OPTION ...]
 
-To remove all migrations from a specified centralized storage:
+``tt migrations apply`` applies :ref:`published <tt-migrations-publish>` migrations
+to the cluster. It executes all migrations from the cluster's centralized
+configuration storage on all its read-write instances (replica set leaders).
 
 .. code-block:: console
 
-    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
-                           --tarantool-username=admin --tarantool-password=pass
+    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
+                        --tarantool-username=admin --tarantool-password=pass
 
-To remove a specific migration, pass its name in the ``--migration`` option:
+To apply a single published migration, pass its name in the ``--migration`` option:
 
 .. code-block:: console
 
-    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
-                           --tarantool-username=admin --tarantool-password=pass  \
-                           --migration=000001_create_writers_space.lua
+    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
+                        --tarantool-username=admin --tarantool-password=pass  \
+                        --migration=000001_create_space.lua
 
-Before removing migrations, the command checks their :ref:`status <tt-migrations-status>`
-on the cluster. To ignore the status and remove migrations anyway, add the
-``--force-remove-on=config-storage`` option:
+To apply migrations on a single replica set, specify the ``replicaset`` option:
 
 .. code-block:: console
 
-    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
-                            --force-remove-on=config-storage
-
-.. note::
-
-    In this case, cluster credentials are not required.
-
-To remove migration execution information from the cluster (clear the migration status),
-use the ``--force-remove-on=cluster`` option:
-
-.. code-block:: console
+    $ tt migrations apply "https://user:pass@localhost:2379/myapp"  \
+                        --tarantool-username=admin --tarantool-password=pass  \
+                        --replicaset=storage-001
 
-    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
-                           --tarantool-username=admin --tarantool-password=pass  \
-                           --force-remove-on=cluster
+The command also provides options for migration troubleshooting: ``--ignore-order-violation``,
+``--force-reapply``, and ``--ignore-preceding-status``. Learn to use them in
+:ref:`centralized_migrations_tt_troubleshoot`.
 
-To clear all migration information from the centralized storage and cluster,
-use the ``--force-remove-on=all`` option:
+.. warning::
 
-.. code-block:: console
+    The use of migration troubleshooting options may lead to migration inconsistency
+    in the cluster. Use them only for local development and testing purposes.
 
-    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
-                           --tarantool-username=admin --tarantool-password=pass  \
-                           --force-remove-on=all
 
 .. _tt-migrations-status:
 
@@ -201,6 +145,7 @@ storage and the result of their execution on the cluster instances.
 Possible migration statuses are:
 
 -  ``APPLY_STARTED`` -- the migration execution has started but not completed yet
+    or has been interrupted with :ref:`tt migrations stop <tt-migrations-stop>``
 -  ``APPLIED`` -- the migration is successfully applied on the instance
 -  ``FAILED`` -- there were errors during the migration execution on the instance
 
@@ -254,16 +199,76 @@ stop
 
     Calling ``tt migration stop`` may cause migration inconsistency in the cluster.
 
-To stop execution of migrations currently running in the cluster:
+To stop the execution of a migration currently running in the cluster:
 
 ..  code-block:: console
 
     $ tt migrations stop "https://user:pass@localhost:2379/myapp"  \
                          --tarantool-username=admin --tarantool-password=pass
 
-Q: can any migrations in a batch complete successfully? If I apply 2 migrations and call
-`tt migrations stop` after the first one is finished without errors, what are migration statuses?
+``tt migrations stop`` interrupts a single migration. If you call it to interrupt
+the process that applies multiple migrations, the ones completed before the call
+receive the ``APPLIED`` status. The migration is interrupted by the call remains in
+``APPLY_STARTED``.
+
+.. _tt-migrations-remove:
+
+remove
+------
+
+..  code-block:: console
+
+    $ tt migrations remove ETCD_URI [OPTION ...]
+
+``tt migrations remove`` removes published migrations from the centralized storage.
+With additional options, it can also remove the information about the migration execution
+on the cluster instances.
+
+To remove all migrations from a specified centralized storage:
+
+.. code-block:: console
+
+    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
+                           --tarantool-username=admin --tarantool-password=pass
+
+To remove a specific migration, pass its name in the ``--migration`` option:
+
+.. code-block:: console
+
+    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
+                           --tarantool-username=admin --tarantool-password=pass  \
+                           --migration=000001_create_writers_space.lua
+
+Before removing migrations, the command checks their :ref:`status <tt-migrations-status>`
+on the cluster. To ignore the status and remove migrations anyway, add the
+``--force-remove-on=config-storage`` option:
+
+.. code-block:: console
+
+    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
+                            --force-remove-on=config-storage
 
+.. note::
+
+    In this case, cluster credentials are not required.
+
+To remove migration execution information from the cluster (clear the migration status),
+use the ``--force-remove-on=cluster`` option:
+
+.. code-block:: console
+
+    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
+                           --tarantool-username=admin --tarantool-password=pass  \
+                           --force-remove-on=cluster
+
+To clear all migration information from the centralized storage and cluster,
+use the ``--force-remove-on=all`` option:
+
+.. code-block:: console
+
+    $ tt migrations remove "https://user:pass@localhost:2379/myapp"  \
+                           --tarantool-username=admin --tarantool-password=pass  \
+                           --force-remove-on=all
 
 .. _tt-migrations-auth:
 
@@ -273,10 +278,10 @@ Authentication
 Since ``tt migrations`` operates migrations via a centralizes etcd storage, it
 needs credentials to access this storage. There are two ways to pass etcd credentials:
 
--   command options ``--config-storage-username`` and ``--config-storage-password``
+-   command-line options ``--config-storage-username`` and ``--config-storage-password``
 -   the etcd URI, for example, ``https://user:pass@localhost:2379/myapp``
 
-Q: which way has a higher priority?
+Credentials specified in the URI have a higher priority.
 
 For commands that connect to the cluster (that is, all except ``publish``), Tarantool
 credentials are also required. The are passed in the ``--tarantool-username`` and
@@ -386,7 +391,7 @@ Options
 
     **Applicable to:** ``apply``, ``remove``, ``status``
 
-    migration to remove
+    A migration to apply, remove, or check status.
 
 .. option:: --overwrite
 
