From b264e8c6df46fa8275c482d6f731e8f75247a93d Mon Sep 17 00:00:00 2001
From: Pavel Semyonov
Date: Tue, 20 Aug 2024 18:11:15 +0700
Subject: [PATCH] Add TCM migrations doc (#4463)
Resolves #4349
Co-authored-by: Elena Shebunyaeva
---
doc/tooling/tcm/index.rst | 1 +
doc/tooling/tcm/tcm_cluster_migrations.rst | 109 +++++++++++++++++++++
2 files changed, 110 insertions(+)
create mode 100644 doc/tooling/tcm/tcm_cluster_migrations.rst
diff --git a/doc/tooling/tcm/index.rst b/doc/tooling/tcm/index.rst
index d7584c352..08983d482 100644
--- a/doc/tooling/tcm/index.rst
+++ b/doc/tooling/tcm/index.rst
@@ -40,6 +40,7 @@ to read data. LDAP authorization is supported as well.
tcm_connect_clusters
tcm_cluster_management/index
tcm_cluster_data_access
+ tcm_cluster_migrations
tcm_access_control
tcm_audit_log
tcm_configuration
diff --git a/doc/tooling/tcm/tcm_cluster_migrations.rst b/doc/tooling/tcm/tcm_cluster_migrations.rst
new file mode 100644
index 000000000..daa3827ca
--- /dev/null
+++ b/doc/tooling/tcm/tcm_cluster_migrations.rst
@@ -0,0 +1,109 @@
+.. _tcm_cluster_migrations:
+
+Performing migrations
+=====================
+
+.. include:: index.rst
+ :start-after: ee_note_tcm_start
+ :end-before: ee_note_tcm_end
+
+|tcm_full_name| provides a web interface for managing and performing migrations
+in connected clusters. To learn more about migrations in Tarantool, see :ref:`migrations`.
+
+Migrations are named Lua files with code that alters the cluster data schema, for example,
+creates a space, changes its format, or adds indexes. In |tcm|, there is a dedicated
+page where you can organize migrations, edit their code, and apply them to the cluster.
+
+.. _tcm_cluster_migrations_manage:
+
+Managing migrations
+-------------------
+
+The tools for managing migrations from |tcm| are located on the **Cluster** > **Migrations** page.
+
+To create a migration:
+
+#. Click **Add** (the **+** icon) on the **Migrations** page.
+#. Enter the migration name.
+
+ .. important::
+
+ When naming migrations, remember that they are applied in the lexicographical order.
+ Use ordered numbers as filename prefixes to define the migrations order.
+ For example, ``001_create_table``, ``002_add_column``, ``003_create_index``.
+
+#. Write the migration code in the editor window. Use the :ref:`box.schema module reference `
+ to learn how to work with Tarantool data schema.
+
+Once you complete writing the migration, save it by clicking **Save**.
+This saves the migration that is currently opened in the editor.
+
+.. _tcm_cluster_migrations_apply:
+
+Appliyng migrations
+-------------------
+
+After you prepare a set of migrations, apply it to the cluster.
+To apply all saved migrations to the cluster at once, click **Apply**.
+
+.. important::
+
+ Applying all saved migrations **at once, in the lexicographical order** is the
+ only way to apply migrations in |tcm|. There is no way to select a single or
+ several migrations to apply.
+ The migrations that are already applied are skipped. To learn how to check
+ a migration status, see :ref:`tcm_cluster_migrations_check`.
+
+Migrations that were created but not saved yet are not applied when you click **Apply**.
+
+.. _tcm_cluster_migrations_check:
+
+Checking migrations status
+--------------------------
+
+To check the migration results on the cluster, use the **Migrated** widget on the
+:ref:`cluster stateboard `. It reflects the general result
+of the last applied migration set:
+
+- If all saved migration are applied successfully,
+ the widget is green.
+- If any migration from this set fails on certain instances, the widget color changes to yellow.
+- If there are saved migrations that are not applied yet, the widget becomes gray.
+
+Hovering a cursor over the widget shows the number of instances on which the currently
+saved migration set is successfully applied.
+
+You can also check the status of each particular migration on the **Migrations** page.
+The migrations that are successfully applied are marked with green check marks.
+Failed migrations are marked with exclamation mark icons (**!**). Hover the cursor over
+the icon to see the information about the error. To reapply a failed migration,
+click **Force apply** in the pop-up with the error information.
+
+.. _tcm_cluster_migrations_example:
+
+Migration file example
+----------------------
+
+The following migration code creates a formatted space with two indexes in a
+sharded cluster:
+
+.. code-block:: lua
+
+ local function apply_scenario()
+ local space = box.schema.space.create('customers')
+
+ space:format {
+ { name = 'id', type = 'number' },
+ { name = 'bucket_id', type = 'number' },
+ { name = 'name', type = 'string' },
+ }
+
+ space:create_index('primary', { parts = { 'id' } })
+ space:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false })
+ end
+
+ return {
+ apply = {
+ scenario = apply_scenario,
+ },
+ }
\ No newline at end of file