Fix

Author: p7nov

doc/platform/ddl_dml/migrations/basic_migrations_tt.rst

@@ -26,7 +26,7 @@ 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 sharding
+-   use the `CRUD <https://github.com/tarantool/crud>`__ module for data distribution
 
 ..  _basic_migrations_tt_cluster_etcd:
 
@@ -207,7 +207,7 @@ To publish migrations to the etcd configuration storage, run ``tt migrations pub
 
 .. code-block:: console
 
-    $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp
+    $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp"
        • 000001_create_writes_space.lua: successfully published to key "000001_create_writes_space.lua"
        • 000002_create_writers_index.lua: successfully published to key "000002_create_writers_index.lua"
 
@@ -221,7 +221,7 @@ a cluster user's credentials:
 
 .. 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
 
 .. important::
@@ -249,7 +249,8 @@ Check the migrations status with ``tt migration status``:
 
 .. code-block:: console
 
-    $ tt migrations status http://app_user:config_pass@localhost:2379/myapp --tarantool-username=client --tarantool-password=secret
+    $ tt migrations status "http://app_user:config_pass@localhost:2379/myapp" \
+                           --tarantool-username=client --tarantool-password=secret
        • migrations centralized storage scenarios:
        •   000001_create_writes_space.lua
        •   000002_create_writers_index.lua
@@ -297,3 +298,10 @@ instance and retrieve the space information:
       format: [{'name': 'id', 'type': 'number'}, {'type': 'number', 'name': 'bucket_id',
           'is_nullable': true}, {'name': 'name', 'type': 'string'}, {'name': 'age', 'type': 'number'}]
     ...
+
+..  _basic_migrations_tt_next:
+
+Next steps
+----------
+
+Learn to write and perform data migration in :ref:`upgrade_migrations_tt`.

doc/platform/ddl_dml/migrations/extend_migrations_tt.rst

@@ -73,9 +73,9 @@ Apply all stored migrations to the cluster to load the same data schema to the n
 
 .. 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
-                           --replicaset storage-003
+                           --replicaset=storage-003
 
 .. note::
 
@@ -85,7 +85,7 @@ Apply all stored migrations to the cluster to load the same data schema to the n
 
     .. 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
 
 To make sure that the space exists on the new instances, connect to ``storage-003-a``

doc/platform/ddl_dml/migrations/index.rst

@@ -4,28 +4,26 @@ Migrations
 ==========
 
 **Migration** refers to any change in a data schema: adding or removing a field,
-creating or dropping an index, changing a field format, an so on. Space creation
-is also a schema migration. You can use this fact to track the evolution of your
-data schema since its initial state.
+creating or dropping an index, changing a field format, and so on. Space creation
+is also a migration. Using migrations, you can track the evolution of your
+data schema since its initial state. In Tarantool, migrations are presented as Lua
+code that alters the data schema using the built-in Lua API.
 
 There are two types of migrations:
 
 -   *simple migrations* don't require additional actions on existing data
 -   *complex migrations* include both schema and data changes
 
-In Tarantool, migrations are presented as Lua code that alters the data schema
-using the built-in Lua API.
-
 .. _migrations_simple:
 
 Simple migrations
 -----------------
 
-In Tarantool, there are two types of schema migration that do not require data migration:
+There are two types of schema migration that do not require data migration:
 
--   Creating an index. A new index can be created at any time. To learn more about
+-   *Creating an index*. A new index can be created at any time. To learn more about
     index creation, see :ref:`concepts-data_model_indexes` and the :ref:`box_space-create_index` reference.
--   Adding a field to the end of a space. To add a field, update the space format so
+-   *Adding a field to the end of a space*. To add a field, update the space format so
     that it includes all its fields and also the new field. For example:
 
     .. code-block:: lua
@@ -79,17 +77,17 @@ its availability requirements.
 
 Tarantool offers the following features that make migrations easier and safer:
 
--   Transaction mechanism. It is useful when writing a migration,
+-   *Transaction mechanism*. It is useful when writing a migration,
     because it allows you to work with the data atomically. But before using
     the transaction mechanism, you should explore its limitations.
     For details, see the section about :ref:`transactions <atomic-atomic_execution>`.
 
--   ``space:upgrade()`` function (EE only). With the help of ``space:upgrade()``,
+-   ``space:upgrade()`` *function* (EE only). With the help of ``space:upgrade()``,
     you can enable compression and migrate, including already created tuples.
     For details, check the :ref:`Upgrading space schema <enterprise-space_upgrade>` section.
 
--   Centralized migration management mechanism (EE only). Implemented
-    in the Enterprise version of the :ref:`tt <tt-cli>` utility and :ref:`tcm`,
+-   *Centralized migration management mechanism* (EE only). Implemented
+    in the Enterprise version of the :ref:`tt <tt-cli>` utility and in :ref:`tcm`,
     this mechanism enables migration execution and tracking in the replication
     clusters. For details, see :ref:`migrations_centralized`.
 
@@ -159,9 +157,6 @@ To learn how to manage migrations in Tarantool EE clusters from the command line
 see :ref:`centralized_migrations_tt`. To learn how to use the mechanism from the |tcm|
 web interface, see the :ref:`tcm_migrations` |tcm| documentation page.
 
-The ``tt`` implementation of the mechanism additionally includes commands for
-troubleshooting migration issues. :ref:`troubleshooting_migrations_tt`.
-
 ..  toctree::
     :maxdepth: 1
 

doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst

@@ -3,9 +3,15 @@
 Troubleshooting migrations
 --------------------------
 
+The centralized migrations mechanism allows troubleshooting migration issues using
+dedicated ``tt migration`` options. When troubleshooting migrations, remember that
+any unfinished or failed migration can bring the data schema into to inconsistency.
+Additional steps may be needed to fix this.
+
 .. warning::
 
-    The options used for migration troubleshooting can cause migration inconsistency in the cluster.
+    The options used for migration troubleshooting can cause migration inconsistency
+    in the cluster. Use them only for local development and testing purposes.
 
 ..  _centralized_migrations_tt_troubleshoot_publish:
 
@@ -17,23 +23,23 @@ fix the migration file and publish it again with the ``--overwrite`` option:
 
 .. code-block:: console
 
-    $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp \
+    $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" \
                             000001_create_space.lua --overwrite
 
 If the migration that needs a fix isn't the last in the lexicographical order,
 add also ``--ignore-order-violation``:
 
 .. code-block:: console
 
-    $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp \
+    $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" \
                             000001_create_space.lua --overwrite --ignore-order-violation
 
 If a migration was published by mistake and wasn't applied yet, you can delete it
 from etcd using ``tt migrations remove``:
 
 .. code-block:: console
 
-    $ tt migrations remove http://app_user:config_pass@localhost:2379/myapp \
+    $ tt migrations remove "http://app_user:config_pass@localhost:2379/myapp" \
                         --migration 000003_not_needed.lua
 
 ..  _centralized_migrations_tt_troubleshoot_apply:
@@ -46,7 +52,7 @@ the ``--force-reapply`` 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 \
                           --force-reapply
 
@@ -68,14 +74,14 @@ To interrupt migration execution on the cluster, use ``tt migrations stop``:
 
 .. code-block:: console
 
-    $ tt migrations stop http://app_user:config_pass@localhost:2379/myapp \
+    $ 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 ``--executions-timeout`` option of ``tt migrations apply``:
 
 .. 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 \
                           --execution-timeout=60

doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst

@@ -1,18 +1,13 @@
 ..  _upgrade_migrations_tt:
 
-Complex migrations with space.upgrade()
-=======================================
+Data migrations with space.upgrade()
+====================================
 
 **Example on GitHub:** `migrations <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/migrations>`_
 
 In this tutorial, you learn to write migrations that include data migration using
 the ``space.upgrade()`` function.
 
-See also:
-
--   :ref:`tt migrations <tt-migrations>` for the full list of command-line options.
--   :ref:`tcm_cluster_migrations` to learn about managing migrations from |tcm_full_name|.
-
 ..  _upgrade_migrations_tt:
 
 Prerequisites
@@ -75,7 +70,7 @@ Start the migration function with the new format description:
     new format.
 
 Next, create a stored function that transforms tuples to fit the new format.
-In this case, the functions extracts the first and the last name from the ``name`` field
+In this case, the function extracts the first and the last name from the ``name`` field
 and returns a tuple of the new format:
 
 ..  literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua
@@ -91,18 +86,18 @@ as its arguments. Here is the complete migration code:
     :language: lua
     :dedent:
 
-Learn more about ``space.upgrade()`` execution in :ref:`enterprise-space_upgrade`.
+Learn more about ``space.upgrade()`` in :ref:`enterprise-space_upgrade`.
 
 ..  _upgrade_migrations_tt_publish:
 
 Publishing the migration
 ------------------------
 
-Publish the new migration to etcd. Migrations that already exist in the storage are skipped.
+Publish the new migration to etcd.
 
 .. code-block:: console
 
-    $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp \
+    $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" \
                             migrations/scenario/000003_alter_writers_space.lua
 
 .. note::
@@ -113,7 +108,7 @@ Publish the new migration to etcd. Migrations that already exist in the storage
 
     .. code-block:: console
 
-        $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp
+        $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp"
 
 
 ..  _upgrade_migrations_tt_apply:
@@ -125,7 +120,7 @@ Apply the published migrations:
 
 .. 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
 
 Connect to the router instance and check that the space and its tuples have the new format:
@@ -142,3 +137,12 @@ Connect to the router instance and check that the space and its tuples have the
         {'name': 'age', 'type': 'number'}]
     - null
     ...
+
+
+..  _upgrade_migrations_tt_next:
+
+Next steps
+----------
+
+Learn to use migrations for data schema definition on new instances added to the cluster
+in :ref:`extend_migrations_tt`.