Skip to content

Commit e370bc5

Browse files
AArdeevAArdeev
committed
Adds warnings on replication related issues
Issues may appear on space_object create index, alter index and space format operations Fixes #5146
1 parent c2a2d30 commit e370bc5

File tree

4 files changed

+191
-0
lines changed

4 files changed

+191
-0
lines changed

‎doc/reference/reference_lua/box_space.rst‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,62 @@ It has the data-manipulation functions ``select``, ``insert``, ``replace``,
1111
``update``, ``upsert``, ``delete``, ``get``, ``put``. It also has members,
1212
such as id, and whether or not a space is enabled.
1313

14+
.. WARNING::
15+
16+
Option 1 global Warning:
17+
The following operations involve full space traversal:
18+
19+
- :doc:`./box_space/create_index`;
20+
- :doc:`./box_space/alter`;
21+
- :doc:`./box_space/format`.
22+
23+
Full traversal is the process of processing every node or element in the space structure exactly once
24+
in a systematic manner. Full traversal may leadThese operations introduce replication lag for both
25+
synchronous and asynchronous replication and make writes with synchronous replication unavailable
26+
for the whole duration of operation when initiated at the following conditions:
27+
28+
- initiated on a space with over 10000 tuples AND
29+
- when the node is under any load (when it processes user requests/performs business operations).
30+
31+
To avoid issues:
32+
33+
- initiate named operations on spaces that do not exceed 10000 tuples OR
34+
- initiate named operations when the node is not under any load;
35+
- instead of the space format change operation, perform the :ref:`box_space-upgrade` operation.
36+
37+
Safe exceptions for named operations are:
38+
39+
- changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»);
40+
- turning a unique index into a non-unique one;
41+
- changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index).
42+
- changing space format to a more generic one.
43+
44+
Option 2 global Warning:
45+
The following operations involve full space traversal and introduce replication lag for both synchronous
46+
and asynchronous replication and make writes with synchronous replication unavailable for the whole duration
47+
of operation when initiated at certain conditions:
48+
49+
- :doc:`./box_space/create_index`;
50+
- :doc:`./box_space/alter`;
51+
- :doc:`./box_space/format`.
52+
53+
The issues occur when the operations are initiated at the following conditions:
54+
55+
- initiated on a space with over 10000 tuples AND
56+
- when the node is under any load (when it processes user requests/performs business operations).
57+
58+
To avoid issues:
59+
60+
- initiate named operations on spaces that do not exceed 10000 tuples OR
61+
- initiate named operations when the node is not under any load;
62+
- instead of the space format change operation, perform the :ref:`box_space-upgrade` operation.
63+
64+
Safe exceptions for named operations are:
65+
- changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»);
66+
- turning a unique index into a non-unique one;
67+
- changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index).
68+
- changing space format to a more generic one.
69+
1470
Below is a list of all ``box.space`` functions and members.
1571

1672
.. container:: table

‎doc/reference/reference_lua/box_space/alter.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,58 @@ space_object:alter()
1111
Since version :doc:`2.5.2 </release/2.5.2>`.
1212
Alter an existing space. This method changes certain space parameters.
1313

14+
.. WARNING::
15+
16+
Option 1 alter Warning:
17+
18+
The ``space_object:alter()`` operation involves full space traversal. Full traversal
19+
is the process of processing every node or element in the space structure exactly once
20+
in a systematic manner.
21+
22+
Full traversal may lead to replication lag for both synchronous and asynchronous replication
23+
and make writes with synchronous replication unavailable for the whole duration of operation
24+
when initiated at the following conditions:
25+
26+
- initiated on a space with over 10000 tuples AND
27+
- when the node is under any load (when it processes user requests/performs business operations).
28+
29+
To avoid issues:
30+
31+
- initiate the ``space_object:alter()`` operation on spaces that do not exceed 10000 tuples OR
32+
- initiate the ``space_object:alter()`` operation when the node is not under any load.
33+
34+
Safe exceptions for the ``space_object:alter()`` operation are:
35+
36+
- changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»);
37+
- turning a unique index into a non-unique one;
38+
- changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index).
39+
40+
In future releases, the ``space_object:alter()`` operation will be deprecated.
41+
42+
Option 2 alter Warning:
43+
44+
The ``space_object:alter()`` operation involve full space traversal and introduce replication lag for both
45+
synchronous and asynchronous replication and make writes with synchronous replication unavailable for the
46+
whole duration of operation when initiated at certain conditions.
47+
48+
The issues occur when the ``space_object:alter()`` operation is initiated at the following conditions:
49+
50+
- initiated on a space with over 10000 tuples AND
51+
- when the node is under any load (when it processes user requests/performs business operations).
52+
53+
To avoid issues:
54+
55+
- initiate the ``space_object:alter()`` operation on spaces that do not exceed 10000 tuples OR
56+
- initiate the ``space_object:alter()`` operation when the node is not under any load.
57+
58+
Safe exceptions for the ``space_object:alter()`` operation are:
59+
60+
- changing indexed field type to a more generic one («unsigned» to «number», «decimal» to «scalar»);
61+
- turning a unique index into a non-unique one;
62+
- changing some of the index parameters which do not require a rebuild (changing page_size of a vinyl space index).
63+
64+
In future releases, the ``space_object:alter()`` operation will be deprecated.
65+
1466
:param table options: the space options such as ``field_count``, ``user``,
1567
``format``, ``name``, and other. The full list of
1668
these options with descriptions parameters is provided in

‎doc/reference/reference_lua/box_space/create_index.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,43 @@ space_object:create_index()
1313
tuples into it or select tuples from it. The first created index
1414
will be used as the primary-key index, so it must be unique.
1515

16+
.. WARNING::
17+
18+
Option 1 create Warning:
19+
20+
The ``space_object:create_index()`` operation involves full space traversal. Full traversal
21+
is the process of processing every node or element in the space structure exactly once
22+
in a systematic manner.
23+
24+
Full traversal may lead to replication lag for both synchronous and asynchronous replication
25+
and make writes with synchronous replication unavailable for the whole duration of operation
26+
when initiated at the following conditions:
27+
28+
- initiated on a space with over 10000 tuples AND
29+
- when the node is under any load (when it processes user requests/performs business operations).
30+
31+
To avoid issues:
32+
33+
- initiate the ``space_object:create_index()`` operation on spaces that do not exceed 10000 tuples OR
34+
- initiate the ``space_object:create_index()`` operation when the node is not under any load.
35+
36+
Option 2 create Warning:
37+
38+
The ``space_object:create_index()`` operation involve full space traversal and introduce replication lag for both
39+
synchronous and asynchronous replication and make writes with synchronous replication unavailable for the
40+
whole duration of operation when initiated at certain conditions.
41+
42+
The issues occur when the ``space_object:create_index()`` operation is initiated at the following conditions:
43+
44+
- initiated on a space with over 10000 tuples AND
45+
- when the node is under any load (when it processes user requests/performs business operations).
46+
47+
To avoid issues:
48+
49+
- initiate the ``space_object:create_index()`` operation on spaces that do not exceed 10000 tuples OR
50+
- initiate the ``space_object:create_index()`` operation when the node is not under any load.
51+
52+
1653
:param space_object space_object: an :ref:`object reference
1754
<app_server-object_reference>`
1855
:param string index_name: name of index, which should conform to the

‎doc/reference/reference_lua/box_space/format.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,52 @@ space_object:format()
1010

1111
Declare field names and :ref:`types <index-box_data-types>`.
1212

13+
.. WARNING::
14+
15+
Option 1 format Warning:
16+
17+
The ``space_object:format()`` operation involves full space traversal. Full traversal
18+
is the process of processing every node or element in the space structure exactly once
19+
in a systematic manner.
20+
21+
Full traversal may lead to replication lag for both synchronous and asynchronous replication
22+
and make writes with synchronous replication unavailable for the whole duration of operation
23+
when initiated at the following conditions:
24+
25+
- initiated on a space with over 10000 tuples AND
26+
- when the node is under any load (when it processes user requests/performs business operations).
27+
28+
To avoid issues:
29+
30+
- initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR
31+
- initiate the ``space_object:format()`` operation when the node is not under any load;
32+
- instead of the space format change operation, perform the :ref:`box_space-upgrade` operation.
33+
34+
Safe exception for the ``space_object:format()`` operation is:
35+
36+
- changing space format to a more generic one.
37+
38+
Option 2 format Warning:
39+
40+
The ``space_object:format()`` operation involve full space traversal and introduce replication lag for both
41+
synchronous and asynchronous replication and make writes with synchronous replication unavailable for the
42+
whole duration of operation when initiated at certain conditions.
43+
44+
The issues occur when the ``space_object:format()`` operation is initiated at the following conditions:
45+
46+
- initiated on a space with over 10000 tuples AND
47+
- when the node is under any load (when it processes user requests/performs business operations).
48+
49+
To avoid issues:
50+
51+
- initiate the ``space_object:format()`` operation on spaces that do not exceed 10000 tuples OR
52+
- initiate the ``space_object:format()`` operation when the node is not under any load;
53+
- instead of the space format change operation, perform the :ref:`box_space-upgrade` operation.
54+
55+
Safe exception for the ``space_object:format()`` operation is:
56+
57+
- changing space format to a more generic one.
58+
1359
:param space_object space_object: an :ref:`object reference
1460
<app_server-object_reference>`
1561
:param table format-clause: a list of field names and types

0 commit comments

Comments
 (0)