From e370bc519580ca9db20f1ccb43573e3781944d2c Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Fri, 25 Jul 2025 11:26:41 +0300 Subject: [PATCH 1/2] Adds warnings on replication related issues Issues may appear on space_object create index, alter index and space format operations Fixes #5146 --- doc/reference/reference_lua/box_space.rst | 56 +++++++++++++++++++ .../reference_lua/box_space/alter.rst | 52 +++++++++++++++++ .../reference_lua/box_space/create_index.rst | 37 ++++++++++++ .../reference_lua/box_space/format.rst | 46 +++++++++++++++ 4 files changed, 191 insertions(+) diff --git a/doc/reference/reference_lua/box_space.rst b/doc/reference/reference_lua/box_space.rst index 5795ec8489..98364f95dc 100644 --- a/doc/reference/reference_lua/box_space.rst +++ b/doc/reference/reference_lua/box_space.rst @@ -11,6 +11,62 @@ It has the data-manipulation functions ``select``, ``insert``, ``replace``, ``update``, ``upsert``, ``delete``, ``get``, ``put``. It also has members, such as id, and whether or not a space is enabled. +.. WARNING:: + + Option 1 global Warning: + The following operations involve full space traversal: + + - :doc:`./box_space/create_index`; + - :doc:`./box_space/alter`; + - :doc:`./box_space/format`. + + Full traversal is the process of processing every node or element in the space structure exactly once + in a systematic manner. Full traversal may leadThese operations introduce replication lag for both + synchronous and asynchronous replication and make writes with synchronous replication unavailable + for the whole duration of operation when initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate named operations on spaces that do not exceed 10000 tuples OR + - initiate named operations when the node is not under any load; + - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + + Safe exceptions for named operations are: + + - changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»); + - turning a unique index into a non-unique one; + - changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index). + - changing space format to a more generic one. + + Option 2 global Warning: + The following operations involve full space traversal and introduce replication lag for both synchronous + and asynchronous replication and make writes with synchronous replication unavailable for the whole duration + of operation when initiated at certain conditions: + + - :doc:`./box_space/create_index`; + - :doc:`./box_space/alter`; + - :doc:`./box_space/format`. + + The issues occur when the operations are initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate named operations on spaces that do not exceed 10000 tuples OR + - initiate named operations when the node is not under any load; + - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + + Safe exceptions for named operations are: + - changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»); + - turning a unique index into a non-unique one; + - changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index). + - changing space format to a more generic one. + Below is a list of all ``box.space`` functions and members. .. container:: table diff --git a/doc/reference/reference_lua/box_space/alter.rst b/doc/reference/reference_lua/box_space/alter.rst index 996d49f2bb..2d9d7d42bf 100644 --- a/doc/reference/reference_lua/box_space/alter.rst +++ b/doc/reference/reference_lua/box_space/alter.rst @@ -11,6 +11,58 @@ space_object:alter() Since version :doc:`2.5.2 `. Alter an existing space. This method changes certain space parameters. + .. WARNING:: + + Option 1 alter Warning: + + The ``space_object:alter()`` operation involves full space traversal. Full traversal + is the process of processing every node or element in the space structure exactly once + in a systematic manner. + + Full traversal may lead to replication lag for both synchronous and asynchronous replication + and make writes with synchronous replication unavailable for the whole duration of operation + when initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:alter()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:alter()`` operation when the node is not under any load. + + Safe exceptions for the ``space_object:alter()`` operation are: + + - changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»); + - turning a unique index into a non-unique one; + - changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index). + + In future releases, the ``space_object:alter()`` operation will be deprecated. + + Option 2 alter Warning: + + The ``space_object:alter()`` operation involve full space traversal and introduce replication lag for both + synchronous and asynchronous replication and make writes with synchronous replication unavailable for the + whole duration of operation when initiated at certain conditions. + + The issues occur when the ``space_object:alter()`` operation is initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:alter()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:alter()`` operation when the node is not under any load. + + Safe exceptions for the ``space_object:alter()`` operation are: + + - changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»); + - turning a unique index into a non-unique one; + - changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index). + + In future releases, the ``space_object:alter()`` operation will be deprecated. + :param table options: the space options such as ``field_count``, ``user``, ``format``, ``name``, and other. The full list of these options with descriptions parameters is provided in diff --git a/doc/reference/reference_lua/box_space/create_index.rst b/doc/reference/reference_lua/box_space/create_index.rst index 3283cb0dd4..a0e5c7323d 100644 --- a/doc/reference/reference_lua/box_space/create_index.rst +++ b/doc/reference/reference_lua/box_space/create_index.rst @@ -13,6 +13,43 @@ space_object:create_index() tuples into it or select tuples from it. The first created index will be used as the primary-key index, so it must be unique. + .. WARNING:: + + Option 1 create Warning: + + The ``space_object:create_index()`` operation involves full space traversal. Full traversal + is the process of processing every node or element in the space structure exactly once + in a systematic manner. + + Full traversal may lead to replication lag for both synchronous and asynchronous replication + and make writes with synchronous replication unavailable for the whole duration of operation + when initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:create_index()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:create_index()`` operation when the node is not under any load. + + Option 2 create Warning: + + The ``space_object:create_index()`` operation involve full space traversal and introduce replication lag for both + synchronous and asynchronous replication and make writes with synchronous replication unavailable for the + whole duration of operation when initiated at certain conditions. + + The issues occur when the ``space_object:create_index()`` operation is initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:create_index()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:create_index()`` operation when the node is not under any load. + + :param space_object space_object: an :ref:`object reference ` :param string index_name: name of index, which should conform to the diff --git a/doc/reference/reference_lua/box_space/format.rst b/doc/reference/reference_lua/box_space/format.rst index e53a56a0ec..fb40bc3d22 100644 --- a/doc/reference/reference_lua/box_space/format.rst +++ b/doc/reference/reference_lua/box_space/format.rst @@ -10,6 +10,52 @@ space_object:format() Declare field names and :ref:`types `. + .. WARNING:: + + Option 1 format Warning: + + The ``space_object:format()`` operation involves full space traversal. Full traversal + is the process of processing every node or element in the space structure exactly once + in a systematic manner. + + Full traversal may lead to replication lag for both synchronous and asynchronous replication + and make writes with synchronous replication unavailable for the whole duration of operation + when initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:format()`` operation when the node is not under any load; + - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + + Safe exception for the ``space_object:format()`` operation is: + + - changing space format to a more generic one. + + Option 2 format Warning: + + The ``space_object:format()`` operation involve full space traversal and introduce replication lag for both + synchronous and asynchronous replication and make writes with synchronous replication unavailable for the + whole duration of operation when initiated at certain conditions. + + The issues occur when the ``space_object:format()`` operation is initiated at the following conditions: + + - initiated on a space with over 10000 tuples AND + - when the node is under any load (when it processes user requests/performs business operations). + + To avoid issues: + + - initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR + - initiate the ``space_object:format()`` operation when the node is not under any load; + - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + + Safe exception for the ``space_object:format()`` operation is: + + - changing space format to a more generic one. + :param space_object space_object: an :ref:`object reference ` :param table format-clause: a list of field names and types From e76dd70d8cef2d32cd14f24699132613165b9eff Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Fri, 25 Jul 2025 11:42:33 +0300 Subject: [PATCH 2/2] Fix syntax --- doc/reference/reference_lua/box_space.rst | 4 ++-- doc/reference/reference_lua/box_space/format.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/reference/reference_lua/box_space.rst b/doc/reference/reference_lua/box_space.rst index 98364f95dc..46fb5af2fe 100644 --- a/doc/reference/reference_lua/box_space.rst +++ b/doc/reference/reference_lua/box_space.rst @@ -32,7 +32,7 @@ such as id, and whether or not a space is enabled. - initiate named operations on spaces that do not exceed 10000 tuples OR - initiate named operations when the node is not under any load; - - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + - instead of the ``space_object:format()`` operation, perform the :ref:`box_space-upgrade` operation. Safe exceptions for named operations are: @@ -59,7 +59,7 @@ such as id, and whether or not a space is enabled. - initiate named operations on spaces that do not exceed 10000 tuples OR - initiate named operations when the node is not under any load; - - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + - instead of the ``space_object:format()`` operation, perform the :ref:`box_space-upgrade` operation. Safe exceptions for named operations are: - changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»); diff --git a/doc/reference/reference_lua/box_space/format.rst b/doc/reference/reference_lua/box_space/format.rst index fb40bc3d22..c653a5be5a 100644 --- a/doc/reference/reference_lua/box_space/format.rst +++ b/doc/reference/reference_lua/box_space/format.rst @@ -29,7 +29,7 @@ space_object:format() - initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR - initiate the ``space_object:format()`` operation when the node is not under any load; - - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + - instead of the ``space_object:format()`` operation, perform the :ref:`box_space-upgrade` operation. Safe exception for the ``space_object:format()`` operation is: @@ -50,7 +50,7 @@ space_object:format() - initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR - initiate the ``space_object:format()`` operation when the node is not under any load; - - instead of the space format change operation, perform the :ref:`box_space-upgrade` operation. + - instead of the ``space_object:format()`` operation, perform the :ref:`box_space-upgrade` operation. Safe exception for the ``space_object:format()`` operation is: