From 474cdf11e0f53d96c46edafc5d7ec92028ab5e48 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 2 Jun 2023 12:22:23 +0700 Subject: [PATCH 1/7] Add fetch_schema, reorder functions --- doc/reference/reference_lua/net_box.rst | 116 +++++++++++++----------- 1 file changed, 62 insertions(+), 54 deletions(-) diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst index 91806242f9..f76e9b0f4f 100644 --- a/doc/reference/reference_lua/net_box.rst +++ b/doc/reference/reference_lua/net_box.rst @@ -160,29 +160,21 @@ Below is a list of all ``net.box`` functions. .. function:: connect(URI [, {option[s]}]) - The names ``connect()`` and ``new()`` are synonyms: ``connect()`` is - preferred; ``new()`` is retained for backward compatibility. For more - information, see the description of ``net_box.new()`` below. - -.. _net_box-new: - -.. function:: new(URI [, {option[s]}]) - Create a new connection. The connection is established on demand, at the time of the first request. It can be re-established automatically after a disconnect (see ``reconnect_after`` option below). The returned ``conn`` object supports methods for making remote requests, such as select, update or delete. - + :param string URI: the :ref:`URI ` of the target for the connection :param options: the supported options are shown below: - - * ``user/password``: two options to connect to a remote host other than through - :ref:`URI `. For example, instead of ``connect('username:userpassword@localhost:3301')`` + + * ``user/password``: two options to connect to a remote host other than through + :ref:`URI `. For example, instead of ``connect('username:userpassword@localhost:3301')`` you can write ``connect('localhost:3301', {user = 'username', password='userpassword'})``. - * ``wait_connected``: a connection timeout. By default, the connection is blocked until the connection - is established, but if you specify ``wait_connected=false``, the connection returns immediately. + * ``wait_connected``: a connection timeout. By default, the connection is blocked until the connection + is established, but if you specify ``wait_connected=false``, the connection returns immediately. If you specify this timeout, it will wait before returning (``wait_connected=1.5`` makes it wait at most 1.5 seconds). .. NOTE:: @@ -191,43 +183,52 @@ Below is a list of all ``net.box`` functions. The wait completes once the connection is established or is closed explicitly. - * ``reconnect_after``: a number of seconds to wait before reconnecting. - The default value, as with the other ``connect`` options, is ``nil``. If ``reconnect_after`` - is greater than zero, then a ``net.box`` instance will attempt to reconnect if a connection - is lost or a connection attempt fails. This makes transient network failures transparent to the application. - Reconnection happens automatically in the background, so requests that initially fail due to connection drops - fail, are transparently retried. The number of retries is unlimited, connection retries are made after - any specified interval (for example, ``reconnect_after=5`` means that reconnect attempts are made every 5 seconds). - When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop. - + * ``reconnect_after``: a number of seconds to wait before reconnecting. + The default value, as with the other ``connect`` options, is ``nil``. If ``reconnect_after`` + is greater than zero, then a ``net.box`` instance will attempt to reconnect if a connection + is lost or a connection attempt fails. This makes transient network failures transparent to the application. + Reconnection happens automatically in the background, so requests that initially fail due to connection drops + fail, are transparently retried. The number of retries is unlimited, connection retries are made after + any specified interval (for example, ``reconnect_after=5`` means that reconnect attempts are made every 5 seconds). + When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop. + - * ``call_16``: [since 1.7.2] a new binary protocol command for CALL in ``net.box`` connections by default. - The new CALL is not backward compatible with previous versions. It no longer restricts a function to - returning an array of tuples and allows returning an arbitrary MsgPack/JSON result, - including scalars, nil and void (nothing). The old CALL is left intact for backward compatibility. - It will not be present in the next major release. All programming language drivers will gradually be switched + * ``call_16``: [since 1.7.2] a new binary protocol command for CALL in ``net.box`` connections by default. + The new CALL is not backward compatible with previous versions. It no longer restricts a function to + returning an array of tuples and allows returning an arbitrary MsgPack/JSON result, + including scalars, nil and void (nothing). The old CALL is left intact for backward compatibility. + It will not be present in the next major release. All programming language drivers will gradually be switched to the new CALL. To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``. - * ``console``: an option to use different connection support methods (as if instances of different - classes are returned). With ``console = true``, you can use the ``conn`` methods ``close()``, - ``is_connected()``, ``wait_state()``, ``eval()`` (in this case both binary and Lua console - network protocols are supported). - With ``console = false`` (default), you can also use ``conn`` database methods (in this case only the - binary protocol is supported). Deprecation note: ``console = true`` is deprecated, users should use + * ``console``: an option to use different connection support methods (as if instances of different + classes are returned). With ``console = true``, you can use the ``conn`` methods ``close()``, + ``is_connected()``, ``wait_state()``, ``eval()`` (in this case both binary and Lua console + network protocols are supported). + With ``console = false`` (default), you can also use ``conn`` database methods (in this case only the + binary protocol is supported). Deprecation note: ``console = true`` is deprecated, users should use :ref:`console.connect() ` instead. * ``connect_timeout``: a number of seconds to wait before returning "error: Connection timed out". - * ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol ` - supported by the server. If the version of the :ref:`IPROTO protocol ` supported - by the server is lower than specified, the connection will fail with an error message. - With ``required_protocol_version = 1``, all connections fail where the :ref:`IPROTO protocol ` - version is lower than ``1``. + * ``fetch_schema``: a boolean option that controls fetching schema changes from the server. Default: ``true``. + If you don't operate with remote spaces, for example, run only ``call`` or ``eval``, set ``fetch_schema`` to + ``false`` to avoid fetching schema changes which is not needed in this case. + + .. important:: + + If ``fetch_schema`` is ``false``, remote spaces are unavailable and the :ref:``on_schema_reload `` + trigger won't work. - * ``required_protocol_features``: specified :ref:`IPROTO protocol features ` supported by the server. - You can specify one or more ``net.box`` features from the table below. If the server does not - support the specified features, the connection will fail with an error message. - With ``required_protocol_features = {'transactions'}``, all connections fail where the + * ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol ` + supported by the server. If the version of the :ref:`IPROTO protocol ` supported + by the server is lower than specified, the connection will fail with an error message. + With ``required_protocol_version = 1``, all connections fail where the :ref:`IPROTO protocol ` + version is lower than ``1``. + + * ``required_protocol_features``: specified :ref:`IPROTO protocol features ` supported by the server. + You can specify one or more ``net.box`` features from the table below. If the server does not + support the specified features, the connection will fail with an error message. + With ``required_protocol_features = {'transactions'}``, all connections fail where the server has ``transactions: false``. .. container:: table @@ -240,26 +241,26 @@ Below is a list of all ``net.box`` functions. - Use - IPROTO feature ID - IPROTO versions supporting the feature - * - ``streams`` + * - ``streams`` - Requires streams support on the server - - IPROTO_FEATURE_STREAMS + - IPROTO_FEATURE_STREAMS - 1 and newer * - ``transactions`` - Requires transactions support on the server - - IPROTO_FEATURE_TRANSACTIONS + - IPROTO_FEATURE_TRANSACTIONS - 1 and newer * - ``error_extension`` - Requires support for :ref:`MP_ERROR ` MsgPack extension on the server - - IPROTO_FEATURE_ERROR_EXTENSION + - IPROTO_FEATURE_ERROR_EXTENSION - 2 and newer * - ``watchers`` - Requires remote :ref:`watchers ` support on the server - - IPROTO_FEATURE_WATCHERS - - 3 and newer - + - IPROTO_FEATURE_WATCHERS + - 3 and newer + To learn more about IPROTO features, see :ref:`IPROTO_ID ` and the :ref:`IPROTO_FEATURES ` key. - + :return: conn object :rtype: userdata @@ -268,12 +269,19 @@ Below is a list of all ``net.box`` functions. .. code-block:: lua net_box = require('net.box') - + conn = net_box.connect('localhost:3301') conn = net_box.connect('127.0.0.1:3302', {wait_connected = false}) conn = net_box.connect('127.0.0.1:3303', {reconnect_after = 5, call_16 = true}) conn = net_box.connect('127.0.0.1:3304', {required_protocol_version = 4, required_protocol_features = {'transactions', 'streams'}, }) +.. _net_box-new: + +.. function:: new(URI [, {option[s]}]) + + ``new()`` is a synonym for ``connect()``. It is retained for backward compatibility. + For more information, see the description of :ref:`net_box.connect() `. + .. _net_box-self: .. class:: self @@ -562,13 +570,13 @@ Below is a list of all ``net.box`` functions. The method has the same syntax as the :doc:`box.watch() ` function, which is used for subscribing to events locally. - Watchers survive reconnection (see the ``reconnect_after`` connection :ref:`option `). + Watchers survive reconnection (see the ``reconnect_after`` connection :ref:`option `). All registered watchers are automatically resubscribed when the connection is reestablished. If a remote host supports watchers, the ``watchers`` key will be set in the connection ``peer_protocol_features``. - For details, check the :ref:`net.box features table `. + For details, check the :ref:`net.box features table `. .. note:: From 460d4d2d03f348d7b5808321b7ed58fb87c20a0c Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 2 Jun 2023 14:59:15 +0700 Subject: [PATCH 2/7] Remove console param of net.box.connect --- doc/reference/reference_lua/net_box.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst index f76e9b0f4f..d1904ddade 100644 --- a/doc/reference/reference_lua/net_box.rst +++ b/doc/reference/reference_lua/net_box.rst @@ -200,14 +200,6 @@ Below is a list of all ``net.box`` functions. It will not be present in the next major release. All programming language drivers will gradually be switched to the new CALL. To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``. - * ``console``: an option to use different connection support methods (as if instances of different - classes are returned). With ``console = true``, you can use the ``conn`` methods ``close()``, - ``is_connected()``, ``wait_state()``, ``eval()`` (in this case both binary and Lua console - network protocols are supported). - With ``console = false`` (default), you can also use ``conn`` database methods (in this case only the - binary protocol is supported). Deprecation note: ``console = true`` is deprecated, users should use - :ref:`console.connect() ` instead. - * ``connect_timeout``: a number of seconds to wait before returning "error: Connection timed out". * ``fetch_schema``: a boolean option that controls fetching schema changes from the server. Default: ``true``. From 4e6885f3445215b92017b0a75b44da002c425dfe Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 2 Jun 2023 15:12:57 +0700 Subject: [PATCH 3/7] Fix translation or reconnect_after --- locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po b/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po index 4f3b3ff04e..63c15bfa61 100644 --- a/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po +++ b/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po @@ -355,7 +355,7 @@ msgid "" msgstr "" "`reconnect_after`: ``net.box`` автоматически подключается повторно в случае " "разрыва соединения или провала попытки подключения. В таком случае " -"неустойчивые сетевые отказы становятся очевидными. Повторное подключение " +"точечные сетевые проблемы не влияют на работу приложения. Повторное подключение " "выполняется автоматически в фоновом режиме, поэтому запросы/обращения, не " "выполненные по причине потери соединения, явным образом выполняются " "повторно. Количество повторов не ограничено, попытки подключения выполняются" From cb69b24b18ae2da3c2a803e720dd857ac0a2259a Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 2 Jun 2023 17:41:06 +0700 Subject: [PATCH 4/7] Remove conn.timeout() from reference --- doc/reference/reference_lua/net_box.rst | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst index d1904ddade..22bd9acf5a 100644 --- a/doc/reference/reference_lua/net_box.rst +++ b/doc/reference/reference_lua/net_box.rst @@ -603,28 +603,6 @@ Below is a list of all ``net.box`` functions. w:unregister() - .. _conn-timeout: - - .. method:: timeout(timeout) - - ``timeout(...)`` is a wrapper which sets a timeout for the request that - follows it. Since version 1.7.4 this method is deprecated -- it is better - to pass a timeout value for a method's ``{options}`` parameter. - - **Example:** - - .. code-block:: lua - - conn:timeout(0.5).space.tester:update({1}, {{'=', 2, 15}}) - - Although ``timeout(...)`` is deprecated, all - remote calls support its use. Using a wrapper object makes - the remote connection API compatible with the local one, removing the need - for a separate ``timeout`` argument, which the local version would ignore. Once - a request is sent, it cannot be revoked from the remote server even if a - timeout expires: the timeout expiration only aborts the wait for the remote - server response, not the request itself. - .. _net_box-is_async: .. method:: request(... {is_async=...}) From 5e9df5ef1b2ada470043d91021aabdf72d493a2e Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 2 Jun 2023 17:58:34 +0700 Subject: [PATCH 5/7] Fix vshard bucket parameters --- .../reference_rock/vshard/vshard_router.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/reference/reference_rock/vshard/vshard_router.rst b/doc/reference/reference_rock/vshard/vshard_router.rst index 6f6e3929b3..353acb8a56 100644 --- a/doc/reference/reference_rock/vshard/vshard_router.rst +++ b/doc/reference/reference_rock/vshard/vshard_router.rst @@ -710,19 +710,19 @@ Router public API Bucket parameters: - * ``available_ro``—the number of buckets known to the ``router`` and available for read requests - * ``available_rw``—the number of buckets known to the ``router`` and available for read and write requests - * ``unavailable``—the number of buckets known to the ``router`` but unavailable for any requests - * ``unreachable``—the number of buckets whose replica sets are not known to the ``router`` + * ``available_ro`` -- the number of buckets known to the ``router`` and available for read requests + * ``available_rw`` -- the number of buckets known to the ``router`` and available for read and write requests + * ``unreachable`` -- the number of buckets known to the ``router`` but unavailable for any requests + * ``unknown`` -- the number of buckets whose replica sets are not known to the ``router`` Service parameters: - * ``name`` — service name. Possible values: ``discovery``, ``failover``, ``master_search``. - * ``status`` — service status. Possible values: ``ok``, ``error``. - * ``error`` — error message that appears on the ``error`` status. - * ``activity`` — service state. It shows what the service is currently doing + * ``name`` -- service name. Possible values: ``discovery``, ``failover``, ``master_search``. + * ``status`` -- service status. Possible values: ``ok``, ``error``. + * ``error`` -- error message that appears on the ``error`` status. + * ``activity`` -- service state. It shows what the service is currently doing (for example, ``updating replicas``). - * ``status_idx`` — incrementing counter of the status changes. + * ``status_idx`` -- incrementing counter of the status changes. The ``ok`` status is updated on every successful iteration of the service. The ``error`` status is updated only when it is fixed. From 3e8e485c46634349c1a2ddfdadcd752536dfeaa1 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 5 Jun 2023 09:28:09 +0300 Subject: [PATCH 6/7] Fix mertics description and link --- doc/book/admin/server_introspection.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/book/admin/server_introspection.rst b/doc/book/admin/server_introspection.rst index 94178c05ef..af5d4a6cde 100644 --- a/doc/book/admin/server_introspection.rst +++ b/doc/book/admin/server_introspection.rst @@ -107,7 +107,7 @@ To check the boot log, on systems with ``systemd``, say: Jan 21 21:17:47 localhost.localdomain tarantoolctl[5969]: /usr/bin/tarantoolctl: Starting instance... Jan 21 21:17:47 localhost.localdomain systemd[1]: Started Tarantool Database Server -For more details, use the reports provided by functions in the following submodules: +For more specific checks, use the reports provided by functions in the following submodules: * :doc:`/reference/reference_lua/box_cfg` (check and specify all configuration parameters for the Tarantool server) @@ -121,10 +121,10 @@ For more details, use the reports provided by functions in the following submodu * :doc:`/reference/reference_lua/box_stat` (introspect Tarantool request and network statistics) -You can also try `prometheus `_, -a plugin that makes it easy to collect metrics (e.g. memory usage or number -of requests) from Tarantool applications and databases and expose them via the -Prometheus protocol. +Finally, there is the `metrics `_ +library, which enables collecting metrics (such as memory usage or number +of requests) from Tarantool applications and expose them via various +protocols, including Prometheus. Check :ref:`Monitoring ` for more details. **Example** From 23e26f2daae3ad32f960283d168c6cf72202544a Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 5 Jun 2023 15:10:49 +0300 Subject: [PATCH 7/7] Fixes --- doc/book/admin/server_introspection.rst | 2 +- doc/reference/reference_lua/net_box.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/book/admin/server_introspection.rst b/doc/book/admin/server_introspection.rst index af5d4a6cde..2ac9c95f59 100644 --- a/doc/book/admin/server_introspection.rst +++ b/doc/book/admin/server_introspection.rst @@ -121,7 +121,7 @@ For more specific checks, use the reports provided by functions in the following * :doc:`/reference/reference_lua/box_stat` (introspect Tarantool request and network statistics) -Finally, there is the `metrics `_ +Finally, there is the `metrics `_ library, which enables collecting metrics (such as memory usage or number of requests) from Tarantool applications and expose them via various protocols, including Prometheus. Check :ref:`Monitoring ` for more details. diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst index 22bd9acf5a..fb111d2ce2 100644 --- a/doc/reference/reference_lua/net_box.rst +++ b/doc/reference/reference_lua/net_box.rst @@ -208,8 +208,8 @@ Below is a list of all ``net.box`` functions. .. important:: - If ``fetch_schema`` is ``false``, remote spaces are unavailable and the :ref:``on_schema_reload `` - trigger won't work. + In connections with ``fetch_schema == false``, remote spaces are unavailable + and the :ref:`on_schema_reload ` triggers don't work. * ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol ` supported by the server. If the version of the :ref:`IPROTO protocol ` supported