Migration tutorial draft

p7nov · p7nov · commit 4b30f691c386 · 2024-09-27T18:20:04.000+07:00
diff --git a/doc/platform/ddl_dml/centralized_migrations_tt.rst b/doc/platform/ddl_dml/centralized_migrations_tt.rst
@@ -10,7 +10,7 @@ implemented in the Enterprise Edition of the :ref:`tt <tt-cli>` utility.
 
 See also:
 
--   :ref:`tt migrations <tt-migrations>` reference to see the full list of command-line options.
+-   :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|.
 
 ..  _centralized_migrations_tt_prereq:
@@ -46,7 +46,7 @@ First, start up an etcd instance to use as a configuration storage:
 
 etcd runs on the default port 2379.
 
-Optionally, you can enable etcd authentication by running the following script:
+Optionally, enable etcd authentication by executing the following script:
 
 .. code-block:: bash
 
@@ -93,17 +93,17 @@ Creating a cluster
             :language: yaml
             :dedent:
 
-    -   ``app-scm-1.rockspec``:
+    -   ``myapp-scm-1.rockspec``:
 
-        ..  literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/pp-scm-1.rockspec
+        ..  literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/myapp-scm-1.rockspec
             :dedent:
 
 4.  Create the ``source.yaml`` with a cluster configuration to publish to etcd:
 
     .. note::
 
         This configuration describes a typical CRUD-enabled sharded cluster with
-        one router and two storages, each including one master and one read-only replica.
+        one router and two storage replica sets, each including one master and one read-only replica.
 
     ..  literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/source.yaml
         :language: yaml
@@ -322,7 +322,7 @@ tuples into the space before proceeding to the next steps:
 The next migration changes the space format incompatibly: instead of one ``name``
 field, the new format includes two fields ``first_name`` and ``last_name``.
 To apply this migration, you need to change each tuple's structure preserving the stored
-data. The :ref:`space.upgrade <enterprise-space_upgrade>` helps with this task.
+data. The :ref:`space.upgrade <enterprise-space_upgrade>` function helps with this task.
 
 Create a new file ``000003_alter_writers_space.lua`` in ``/migrations/scenario``.
 Prepare its initial structure the same way as in previous migrations:
@@ -370,7 +370,7 @@ 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()`` execution in :ref:`enterprise-space_upgrade`.
 
 Publish the new migration to etcd. Migrations that already exist in the storage are skipped.
 
@@ -392,7 +392,7 @@ Publish the new migration to etcd. Migrations that already exist in the storage
 
 Apply the migrations:
 
-.. code-block::
+.. code-block:: console
 
     $ tt migrations apply http://app_user:config_pass@localhost:2379/myapp \
                           --tarantool-username=client --tarantool-password=secret
@@ -414,12 +414,13 @@ Connect to the router instance and check that the space and its tuples have the
 
 ..  _centralized_migrations_tt_new_instances:
 
-Applying migrations on new instances
-------------------------------------
+Extending the cluster
+---------------------
 
-Having all migrations in a centralized etcd storage, you can apply
+Having all migrations in a centralized etcd storage, you can extend the cluster
+and consistently define the data schema on new instances on the fly.
 
-To add one more storage, edit the cluster files in ``instances.enabled/myapp``:
+Add one more storage replica set to the cluster. To do this, edit the cluster files in ``instances.enabled/myapp``:
 
 -   ``instances.yml``: add the lines below to the end.
 
@@ -430,7 +431,7 @@ To add one more storage, edit the cluster files in ``instances.enabled/myapp``:
 
 -   ``source.yaml``: add the lines below to the end.
 
-    ..  literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yml
+    ..  literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yaml
         :language: yaml
         :start-at: storage-003:
         :dedent:
@@ -491,3 +492,40 @@ and check ``box.space.writers``:
     ---
     - true
     ...
+
+..  _centralized_migrations_tt_troubleshoot:
+
+Troubleshooting migrations
+--------------------------
+
+.. warning::
+
+    The options used for migration troubleshooting can cause migration inconsistency in the cluster.
+
+Incorrect migration published
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Problem: an incorrect migration is published to etcd.
+Solution: 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 --overwrite
+
+If there are several migrations and the erroneous one isn't the last, add also ``--ignore-order-violation``:
+
+.. code-block:: console
+
+    $ tt migrations publish http://app_user:config_pass@localhost:2379/myapp --overwrite --ignore-order-violation
+
+Incorrect migration applied
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the migration is already applied, publish the fixed version and apply it with
+the ``--force-reapply`` option:
+
+.. code-block:: console
+
+    $ tt migrations apply http://app_user:config_pass@localhost:2379/myapp \
+                          --tarantool-username=client --tarantool-password=secret \
+                          --force-reapply
diff --git a/doc/tooling/tt_cli/migrations.rst b/doc/tooling/tt_cli/migrations.rst
@@ -12,8 +12,9 @@ Managing centralized migrations
 
     $ tt migrations COMMAND [COMMAND_OPTION ...]
 
-``tt migrations`` manages :ref:`centralized migrations <centralized_migrations_tt>` in a Tarantool EE cluster.
-See :ref:`centralized_migrations_tt` for a detailed guide on using centralized migrations.
+``tt migrations`` manages :ref:`centralized migrations <centralized_migrations_tt>`
+in a Tarantool EE cluster. See :ref:`centralized_migrations_tt` for a detailed guide
+on using the centralized migrations mechanism.
 
 .. important::
 
@@ -37,32 +38,32 @@ apply
 
     $ tt migrations apply ETCD_URI [OPTION ...]
 
-``tt migrations apply`` applies migrations :ref:`published <tt-migrations-publish>`
-to the cluster to the cluster. It executes all migrations from the cluster's centralized
+``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
 
-You can select a single migration for execution by adding the ``--migration`` option:
+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
 
-You can select a single replica set to apply migrations to:
+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
 
--- migration - single migration. --order violation
+--order violation
 
 
 ?? diff --force-reapply  --ignore-preceding-status
@@ -101,14 +102,14 @@ To publish a single migration from a file, use its name or path as the command a
 
     $ tt migrations publish https://user:pass@localhost:2379/myapp migrations/000001_create_space.lua
 
-Optionally, you can provide a key to use as a migration identifier instead of the file name:
+Optionally, you can provide a key to use as a migration identifier instead of the filename:
 
 ..  code-block:: console
 
     $ tt migrations publish https://user:pass@localhost:2379/myapp file.lua  \
                             --key=000001_create_space.lua
 
-When publishing migrations, ``tt`` performs several checks for:
+When publishing migrations, ``tt`` performs checks for:
 
 -   Syntax errors in migration files. To skip syntax check, add the ``--skip-syntax-check`` option.
 -   Existence of migrations with same names. To overwrite an existing migration with
@@ -246,7 +247,7 @@ stop
 
     $ tt migrations stop ETCD_URI [OPTION ...]
 
-``tt migrations stop`` stops the execution of migrations in the cluster
+``tt migrations stop`` stops the execution of migrations in the cluster.
 
 .. warning::
 
@@ -284,15 +285,12 @@ If the cluster uses SSL traffic encryption, provide the necessary connection
 parameters in the ``--tarantool-ssl*`` options: ``--tarantool-sslcertfile``,
 ``--tarantool-sslkeyfile``, and other. All options are listed in :ref:`tt-migrations-options`.
 
-?auth type
-?example
-
 .. _tt-migrations-options:
 
 Options
 -------
 
-.. option:: --acquire-lock-timeout int
+.. option:: --acquire-lock-timeout INT
 
     **Applicable to:** ``apply``
 
@@ -321,7 +319,7 @@ Options
 
     See also: :ref:`tt-migrations-status`.
 
-.. option:: --execution-timeout int
+.. option:: --execution-timeout INT
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
@@ -359,21 +357,29 @@ Options
 
     **Applicable to:** ``apply``, ``publish``
 
-    Skip migration scenarios order check before publish. Using this flag may result in cluster migrations inconsistency
+    Skip migration scenarios order check before publish.
+
+    .. warning::
+
+        Using this option may result in cluster migrations inconsistency.
 
 .. option:: --ignore-preceding-status
 
     **Applicable to:** ``apply``
 
-    skip preceding migrations status check on apply. Using this flag may result in cluster migrations inconsistency
+    Skip preceding migrations status check on apply.
+
+    .. warning::
+
+        Using this option may result in cluster migrations inconsistency.
 
 .. option:: --key STRING
 
     **Applicable to:** ``publish``
 
     put scenario to /<prefix>/migrations/scenario/<key> etcd key instead. Only for single file publish
 
-.. option:: --migration string
+.. option:: --migration STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``
 
@@ -383,9 +389,13 @@ Options
 
     **Applicable to:** ``publish``
 
-    overwrite existing migration storage keys. Using this flag may result in cluster migrations inconsistency
+    overwrite existing migration storage keys.
+
+    .. warning::
+
+        Using this option may result in cluster migrations inconsistency.
 
-.. option:: --replicaset string
+.. option:: --replicaset STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
@@ -395,69 +405,73 @@ Options
 
     **Applicable to:** ``publish``
 
-    Skip syntax check before publish. Using this flag may cause other tt migrations operations to fail
+    Skip syntax check before publish.
+
+    .. warning::
+
+        Using this option may cause further ``tt migrations`` calls to fail.
 
-.. option:: --tarantool-auth string
+.. option:: --tarantool-auth STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    authentication type (used only to connect to Tarantool cluster instances)
+    Authentication type used to connect to the cluster instances.
 
-.. option:: --tarantool-connect-timeout int
+.. option:: --tarantool-connect-timeout INT
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    Tarantool cluster instances connection timeout,in seconds. Default: 3.
+    Tarantool cluster instances connection timeout, in seconds. Default: 3.
 
-.. option:: --tarantool-password string
+.. option:: --tarantool-password STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    A password used for connecting to the Tarantool cluster instances.
+    A password used to connect to the cluster instances.
 
-.. option:: --tarantool-sslcafile string
+.. option:: --tarantool-sslcafile STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    SSL CA file (used only to connect to Tarantool cluster instances)
+    SSL CA file used to connect to the cluster instances.
 
-.. option:: --tarantool-sslcertfile string
+.. option:: --tarantool-sslcertfile STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    SSL cert file (used only to connect to Tarantool cluster instances)
+    SSL cert file used to connect to the cluster instances.
 
-.. option:: --tarantool-sslciphers string
+.. option:: --tarantool-sslciphers STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    Colon-separated list of SSL ciphers (used only to connect to Tarantool cluster instances)
+    Colon-separated list of SSL ciphers used to connect to the cluster instances.
 
-.. option:: --tarantool-sslkeyfile string
+.. option:: --tarantool-sslkeyfile STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    SSL key file (used only to connect to Tarantool cluster instances)
+    SSL key file used to connect to the cluster instances.
 
-.. option:: --tarantool-sslpassword string
+.. option:: --tarantool-sslpassword STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    SSL key file password (used only to connect to Tarantool cluster instances)
+    SSL key file password used to connect to the cluster instances.
 
-.. option:: --tarantool-sslpasswordfile string
+.. option:: --tarantool-sslpasswordfile STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    File with list of password to SSL key file (used only to connect to Tarantool cluster instances)
+    File with list of password to SSL key file used to connect to the cluster instances.
 
 .. option:: --tarantool-use-ssl
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
-    use SSL without providing any additional SSL info (used only to connect to Tarantool cluster instances)
+    Whether SSL is used to connect to the  cluster instances.
 
-.. option:: --tarantool-username string
+.. option:: --tarantool-username STRING
 
     **Applicable to:** ``apply``, ``remove``, ``status``, ``stop``
 
