diff --git a/.github/workflows/push-pot.yml b/.github/workflows/push-pot.yml new file mode 100644 index 0000000000..410dd2a482 --- /dev/null +++ b/.github/workflows/push-pot.yml @@ -0,0 +1,34 @@ +name: Push POTs +on: + push: + branches: + - 'latest' +permissions: + contents: write +jobs: + generate-pot: + runs-on: ubuntu-latest + container: tarantool/doc-builder:fat-4.3 + steps: + - uses: actions/checkout@v3 + + - name: Generate Portable Object Templates + run: | + cmake . + make update-pot + + - name: Commit generated pots + run: | + git config --global --add safe.directory /__w/doc/doc + git config --global user.name 'TarantoolBot' + git config --global user.email 'tarantoolbot@mail.ru' + + if [[ $(git status) =~ .*"nothing to commit".* ]]; then + echo "status=nothing-to-commit" + exit 0 + fi + + git add locale/en + git commit -m "updated pot" + git push origin 3.0 + diff --git a/.github/workflows/upload-docx.yml b/.github/workflows/upload-docx.yml index 6564331d0a..3c6b7770b7 100644 --- a/.github/workflows/upload-docx.yml +++ b/.github/workflows/upload-docx.yml @@ -1,11 +1,11 @@ name: Generate DOCX on: + workflow_dispatch: push: branches: - 'latest' - - '3.0' - - 'fix-docx' + - '2.11' jobs: generate-singlehtml: @@ -28,7 +28,7 @@ jobs: make singlehtml - name: save singlehtml-en - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: singlehtml-en path: output/singlehtml/en/alternate_build_master.html @@ -37,13 +37,13 @@ jobs: run: make singlehtml-ru - name: save singlehtml-ru - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: singlehtml-ru path: output/singlehtml/ru/alternate_build_master.html - name: save pandoc filters from the repo - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: pandoc path: pandoc/filter-espd.py @@ -60,7 +60,7 @@ jobs: S3_UPLOAD_PATH: ${{secrets.S3_DOCX_PATH}} steps: - name: download artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 - name: generate docx-en run: | diff --git a/.gitignore b/.gitignore index 6625ca321a..6a6dae1690 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,7 @@ webhooks/.env locale/* !locale/ru +!locale/en # redundant folders created by sphinx @@ -75,6 +76,6 @@ locale/* # tntcxx submodule -/doc/how-to/getting_started_cxx.rst -/doc/how-to/_includes -/doc/book/connectors/cxx/ +/doc/getting_started_cxx.rst +/doc/_includes +/doc/connector/cxx/ diff --git a/.gitmodules b/.gitmodules index cd300b8328..abba677814 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,18 +1,6 @@ -[submodule "modules/cartridge"] - path = modules/cartridge - url = https://github.com/tarantool/cartridge.git -[submodule "modules/cartridge-cli"] - path = modules/cartridge-cli - url = https://github.com/tarantool/cartridge-cli.git -[submodule "modules/metrics"] - path = modules/metrics - url = https://github.com/tarantool/metrics.git [submodule "modules/luatest"] path = modules/luatest url = https://github.com/tarantool/luatest -[submodule "modules/grafana-dashboard"] - path = modules/grafana-dashboard - url = https://github.com/tarantool/grafana-dashboard [submodule "modules/tntcxx"] path = modules/tntcxx url = https://github.com/tarantool/tntcxx.git diff --git a/README.rst b/README.rst index fb1e486c6a..0ce3224297 100644 --- a/README.rst +++ b/README.rst @@ -159,7 +159,7 @@ Its configuration is placed in the ``vale.ini`` file located in the root project To enable RST support in Vale, you need to install Sphinx. Then, you can enable Vale integration in your IDE, for example: -* `VS Code `_ +* `VS Code `_ * `IntelliJ-based IDEs `_ diff --git a/build_submodules.sh b/build_submodules.sh index a083ebfc47..acf9c28609 100755 --- a/build_submodules.sh +++ b/build_submodules.sh @@ -11,62 +11,6 @@ po_dest="${project_root}/locale/ru/LC_MESSAGES" # Copy Building Tarantool Docs guide cp README.rst doc/contributing/docs/_includes/README.rst - -# Cartridge -cartridge_root="${project_root}/modules/cartridge" - -# Build Cartridge to extract docs -cd "${cartridge_root}" || exit -CMAKE_DUMMY_WEBUI=true tarantoolctl rocks make - -# Copy Cartridge docs, including diagrams and images -cartridge_rst_src="${cartridge_root}/build.luarocks/build.rst" -cartridge_rst_dest="${project_root}/doc/book/cartridge" -cd "${cartridge_rst_src}" || exit -mkdir -p "${cartridge_rst_dest}" -find . -iregex '.*\.\(rst\|png\|puml\|svg\)$' -exec cp -r --parents {} "${cartridge_rst_dest}" \; - -# Copy translation templates -cartridge_pot_src="${cartridge_root}/build.luarocks/build.rst/locale" -cartridge_pot_dest="${project_root}/locale/book/cartridge" -cd "${cartridge_pot_src}" || exit -mkdir -p "${cartridge_pot_dest}" -find . -name '*.pot' -exec cp -rv --parents {} "${cartridge_pot_dest}" \; - -# Copy translations -cartridge_po_src="${cartridge_root}/build.luarocks/build.rst/locale/ru/LC_MESSAGES" -cartridge_po_dest="${po_dest}/book/cartridge" -cd "${cartridge_po_src}" || exit -mkdir -p "${cartridge_po_dest}" -find . -name '*.po' -exec cp -rv --parents {} "${cartridge_po_dest}" \; - - -# Cartridge CLI -cartridge_cli_root="${project_root}/modules/cartridge-cli/doc" -cartridge_cli_dest="${cartridge_rst_dest}/cartridge_cli" -cartridge_cli_po_dest="${po_dest}/book/cartridge/cartridge_cli" - -# Copy Cartridge CLI docs, including diagrams and images -mkdir -p "${cartridge_cli_dest}" -cd ${cartridge_cli_root} || exit -find . -iregex '.*\.\(rst\|png\|puml\|svg\)$' -exec cp -rv --parents {} "${cartridge_cli_dest}" \; - -# Copy translations -mkdir -p "${cartridge_cli_po_dest}" -cd "${cartridge_cli_root}/locale/ru/LC_MESSAGES/doc/" || exit -find . -name '*.po' -exec cp -rv --parents {} "${cartridge_cli_po_dest}" \; - -# Monitoring -monitoring_root="${project_root}/modules/metrics/doc/monitoring" -monitoring_dest="${project_root}/doc/book" -monitoring_grafana_root="${project_root}/modules/grafana-dashboard/doc/monitoring" - -# Copy monitoring docs to the right destination -mkdir -p "${monitoring_dest}" -cp -rfv "${monitoring_root}" "${monitoring_dest}/" -cp -rfv "${monitoring_grafana_root}" "${monitoring_dest}/" - - # Luatest luatest_root="${project_root}/modules/luatest" luatest_dest="${project_root}/doc/reference/reference_rock/luatest" @@ -84,12 +28,13 @@ mv -fv "${luatest_dest}/index.rst" "${luatest_dest}/_includes/" # Tarantool C++ connector tntcxx_root="${project_root}/modules/tntcxx" -tntcxx_howto_dest="${project_root}/doc/how-to" -tntcxx_api_dest="${project_root}/doc/book/connectors" +tntcxx_howto_dest="${project_root}/doc/connector" +tntcxx_api_dest="${project_root}/doc/connector" # Copy Tarantool C++ connector docs to the right places mkdir -p "${tntcxx_api_dest}/cxx/" -mkdir -p "${tntcxx_howto_dest}/_includes" -cp -rfv "${tntcxx_root}/doc/tntcxx_getting_started.rst" "${tntcxx_howto_dest}/getting_started_cxx.rst" -cp -rfv "${tntcxx_root}/examples/" "${tntcxx_howto_dest}/_includes/examples/" +mkdir -p "${tntcxx_howto_dest}/cxx/" +mkdir -p "${tntcxx_howto_dest}/cxx/_includes/" +cp -rfv "${tntcxx_root}/doc/tntcxx_getting_started.rst" "${tntcxx_howto_dest}/cxx/" +cp -rfv "${tntcxx_root}/examples/" "${tntcxx_howto_dest}/cxx/_includes/examples/" cp -rfv "${tntcxx_root}/doc/tntcxx_api.rst" "${tntcxx_api_dest}/cxx/" diff --git a/conf.py b/conf.py index a053d601d2..dfce50f509 100644 --- a/conf.py +++ b/conf.py @@ -61,7 +61,7 @@ project = u'Tarantool' # |release| The full version, including alpha/beta/rc tags. -release = "2.11.1" +release = "3.0.0" # |version| The short X.Y version. version = '.'.join(release.split('.')[0:2]) @@ -73,10 +73,6 @@ 'how-to/using_docker.rst', 'reference/configuration/cfg_*', 'images', - 'book/cartridge/cartridge_overview.rst', - 'book/cartridge/CONTRIBUTING.rst', - 'book/cartridge/topics', - 'book/cartridge/cartridge_api/modules/cartridge.test-helpers.rst', 'reference/reference_rock/luatest/README.rst', 'reference/reference_rock/luatest/modules/luatest.rst', '**/_includes/*' diff --git a/doc/book/admin/_includes/1.6-to-2.x-condition.rst b/doc/admin/_includes/1.6-to-2.x-condition.rst similarity index 100% rename from doc/book/admin/_includes/1.6-to-2.x-condition.rst rename to doc/admin/_includes/1.6-to-2.x-condition.rst diff --git a/doc/book/admin/_includes/script_check_type_names.rst b/doc/admin/_includes/script_check_type_names.rst similarity index 100% rename from doc/book/admin/_includes/script_check_type_names.rst rename to doc/admin/_includes/script_check_type_names.rst diff --git a/doc/book/admin/_includes/script_find_indices.rst b/doc/admin/_includes/script_find_indices.rst similarity index 100% rename from doc/book/admin/_includes/script_find_indices.rst rename to doc/admin/_includes/script_find_indices.rst diff --git a/doc/book/admin/_includes/script_fix_type_names.rst b/doc/admin/_includes/script_fix_type_names.rst similarity index 100% rename from doc/book/admin/_includes/script_fix_type_names.rst rename to doc/admin/_includes/script_fix_type_names.rst diff --git a/doc/book/admin/_includes/script_rebuild_indices.rst b/doc/admin/_includes/script_rebuild_indices.rst similarity index 100% rename from doc/book/admin/_includes/script_rebuild_indices.rst rename to doc/admin/_includes/script_rebuild_indices.rst diff --git a/doc/book/admin/_includes/upgrade_check_app.rst b/doc/admin/_includes/upgrade_check_app.rst similarity index 100% rename from doc/book/admin/_includes/upgrade_check_app.rst rename to doc/admin/_includes/upgrade_check_app.rst diff --git a/doc/book/admin/_includes/upgrade_checks_pre.rst b/doc/admin/_includes/upgrade_checks_pre.rst similarity index 100% rename from doc/book/admin/_includes/upgrade_checks_pre.rst rename to doc/admin/_includes/upgrade_checks_pre.rst diff --git a/doc/book/admin/_includes/upgrade_storages.rst b/doc/admin/_includes/upgrade_storages.rst similarity index 100% rename from doc/book/admin/_includes/upgrade_storages.rst rename to doc/admin/_includes/upgrade_storages.rst diff --git a/doc/admin/access_control.rst b/doc/admin/access_control.rst new file mode 100644 index 0000000000..8e5d641de6 --- /dev/null +++ b/doc/admin/access_control.rst @@ -0,0 +1,1096 @@ +.. _authentication: +.. _access_control: + +Access control +============== + +Tarantool enables flexible management of access to various database resources. +The main concepts of Tarantool access control system are as follows: + +* A *user* is a person or program that interacts with a Tarantool instance. +* An *object* is an entity to which access can be granted, for example, a space, an index, or a function. +* A *privilege* allows a user to perform certain operations on specific objects, for example, creating spaces, reading or updating data. +* A *role* is a named collection of privileges that can be granted to a user. + + + +.. _access_control_overview: + +Overview +-------- + +.. _authentication-users: +.. _access_control_concepts_users: + +Users +~~~~~ + +A user identifies a person or program that interacts with a Tarantool instance. +There might be different types of users, for example: + +* A database administrator responsible for the overall management and administration of a database. + An administrator can create other users and grant them specified privileges. +* A user with limited access to certain data and stored functions. + Such users can get their privileges from the database administrator. +* Users used in communications between Tarantool instances. For example, such users can be created to maintain replication and sharding in a Tarantool cluster. + +There are two built-in users in Tarantool: + +* ``admin`` is a user with all available administrative privileges. + If the connection uses an :ref:`admin-console port `, the current user is ``admin``. + For example, ``admin`` is used when connecting to an instance using :ref:`tt connect ` locally using the instance name: + + .. code-block:: console + + $ tt connect app:instance001 + + To allow remote :ref:`binary port ` connections using the ``admin`` user, you need to :ref:`set a password `. + +* ``guest`` is a user with minimum privileges used by default for remote :ref:`binary port ` connections. + For example, ``guest`` is used when connecting to an instance using :ref:`tt connect ` using the IP address and port without specifying the name of a user: + + .. code-block:: console + + $ tt connect 192.168.10.10:3301 + + .. WARNING:: + + Given that the ``guest`` user allows unauthenticated access to Tarantool instances, it is not recommended to grant additional privileges to this user. + For example, granting the ``execute`` access to :ref:`universe ` allows *remote code execution* on instances. + +.. NOTE:: + + Information about users is stored in the :ref:`_user ` space. + + + + +.. _authentication-passwords: + +Passwords +~~~~~~~~~ + +Any user (except ``guest``) may have a password. +If a password is not set, a user cannot connect to Tarantool instances. + +Tarantool :ref:`password hashes ` are stored in the :ref:`_user ` system space. +By default, Tarantool uses the ``CHAP`` protocol to authenticate users and applies ``SHA-1`` hashing to +:ref:`passwords `. +So, if the password is '123456', the stored hash is a string like 'a7SDfrdDKRBe5FaN2n3GftLKKtk='. +In the Enterprise Edition, you can enable ``PAP`` :ref:`authentication ` with the ``SHA256`` hashing algorithm. + +Tarantool Enterprise Edition allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. +Learn more from the :ref:`configuration_authentication` topic. + + + +.. _access_control_concepts_objects: + +Objects +~~~~~~~ + +An object is a securable entity to which access can be granted. +Tarantool has a number of objects that enable flexible management of access to data, stored functions, specific actions, and so on. + +Below are a few examples of objects: + +* ``universe`` represents a database (:ref:`box.schema `) that contains database objects, including spaces, indexes, users, roles, sequences, and functions. + Granting privileges to ``universe`` gives a user access to any object in a database. +* ``space`` enables granting privileges to user-created or system :ref:`spaces `. +* ``function`` enables granting privileges to :ref:`functions `. + +.. NOTE:: + + The full list of object types is available in the :ref:`access_control_list_objects` section. + + +.. _authentication-owners_privileges: + +Privileges +~~~~~~~~~~ + +The privileges granted to a user determine which operations the user can perform, for example: + +* The ``read`` and ``write`` permissions granted to the ``space`` :ref:`object ` allow a user to read or modify data in the specified space. +* The ``create`` permission granted to the ``space`` object allows a user to create new spaces. +* The ``execute`` permission granted to the ``function`` object allows a user to execute the specified function. +* The ``session`` permission granted to a user allows connecting to an instance over IPROTO. + +Note that some privileges might require read and write access to certain system spaces. +For example, the ``create`` permission granted to the ``space`` object requires ``read`` and ``write`` permissions to the :ref:`_space ` system space. +Similarly, granting the ability to create functions requires ``read`` and ``write`` access to the :ref:`_func ` space. + +.. NOTE:: + + Information about privileges is stored in the :ref:`_priv ` space. + + + +.. _access_control_concepts_roles: + +Roles +~~~~~ +A role is a container for :ref:`privileges ` that can be granted to users. +Roles can also be assigned to other roles, creating a role hierarchy. + +There are the following built-in roles in Tarantool: + +* ``super`` has all available administrative permissions. +* ``public`` has certain read permissions. This role is automatically granted to new users when they are created. +* ``replication`` can be granted to a user used to maintain :ref:`replication ` in a cluster. +* ``sharding`` can be granted to a user used to maintain :ref:`sharding ` in a cluster. + + .. NOTE:: + + The ``sharding`` role is created only if an instance is managed using :ref:`YAML configuration `. + +Below are a few diagrams that demonstrate how privileges can be granted to a user without and with using roles. + +* In this example, a user gets privileges directly without using roles. + + .. code-block:: none + + user1 ── privilege1 + ├─── privilege2 + └─── privilege3 + +* In this example, a user gets all privileges provided by ``role1`` and specific privileges assigned directly. + + .. code-block:: none + + user1 ── role1 ── privilege1 + │ └─── privilege2 + ├─── privilege3 + └─── privilege4 + +* In this example, ``role2`` is granted to ``role1``. + This means that a user with ``role1`` subsequently gets all privileges from both roles ``role1`` and ``role2``. + + .. code-block:: none + + user1 ── role1 ── privilege1 + │ ├─── privilege2 + │ └─── role2 + │ ├─── privilege3 + │ └─── privilege4 + ├─── privilege5 + └─── privilege6 + +.. NOTE:: + + Information about roles is stored in the :ref:`_user ` space. + + + +.. _authentication-owners: + +Object owners +~~~~~~~~~~~~~ + +An owner of a database :ref:`object ` is the user who created it. +The owner of the database and the owner of objects that are created initially (the system spaces and the default users) is the ``admin`` :ref:`user `. + +Owners automatically have :ref:`privileges ` for objects they create. +They can :ref:`share these privileges ` with other users or roles using ``box.schema.user.grant()`` and ``box.schema.role.grant()``. + +.. NOTE:: + + Information about users who gave the specified privileges is stored in the :ref:`_priv ` space. + + + +.. _authentication-sessions: + +Sessions +~~~~~~~~ + +A session is the state of a connection to Tarantool. +The session contains: + +* An integer ID identifying the connection. +* The current :ref:`user ` associated with the connection. +* The text description of the connected peer. +* A session's local state, such as Lua variables and functions. + +In Tarantool, a single session can execute multiple concurrent transactions. +Each transaction is identified by a unique integer ID, which can be queried +at the start of the transaction using :doc:`/reference/reference_lua/box_session/sync`. + +.. NOTE:: + + To track all connects and disconnects, you can use :ref:`connection and authentication triggers `. + + + + +.. _access_control_users: + +Managing users +-------------- + +.. _access_control_user_creating: + +Creating a user +~~~~~~~~~~~~~~~ + +To create a new user, call :ref:`box.schema.user.create() `. +In the example below, a user is created without a password: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Create a user without a password + :end-before: End: Create a user without a password + :dedent: + + +In this example, the password is specified in the ``options`` parameter: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Create a user with a password + :end-before: End: Create a user with a password + :dedent: + + +.. _access_control_user_changing_passwords: + +Changing passwords +~~~~~~~~~~~~~~~~~~ + +To set or change a user's password, use :ref:`box.schema.user.passwd() `. +In the example below, a user password is set for a currently logged-in user: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Set a password for the current user + :end-before: End: Set a password for the current user + :dedent: + +To set the password for the specified user, pass a username and password as shown below: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Set a password for the specified user + :end-before: End: Set a password for the specified user + :dedent: + +.. NOTE:: + + :doc:`/reference/reference_lua/box_schema/user_password` returns a hash of the specified password. + + + +.. _access_control_user_granting_privileges: + +Granting privileges to a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To grant the specified privileges to a user, use the :ref:`box.schema.user.grant() ` function. +In the example below, ``testuser`` gets read permissions to the ``writers`` space and read/write permissions to the ``books`` space: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Grant privileges to the specified user + :end-before: End: Grant privileges to the specified user + :dedent: + +Learn more about granting privileges to different types of objects from :ref:`access_control_granting_privileges`. + + + +.. _access_control_user_info: + +Getting a user's information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To check whether the specified user exists, call :ref:`box.schema.user.exists() `: + +.. code-block:: lua + + box.schema.user.exists('testuser') + --[[ + - true + --]] + +To get information about privileges granted to a user, call :ref:`box.schema.user.info() `: + +.. code-block:: lua + + box.schema.user.info('testuser') + --[[ + - - - execute + - role + - public + - - read + - space + - writers + - - read,write + - space + - books + - - session,usage + - universe + - + - - alter + - user + - testuser + --]] + +In the example above, ``testuser`` has the following privileges: + +* The ``execute`` permission to the ``public`` role means that this role is :ref:`assigned to the user `. + +* The ``read`` permission to the ``writers`` space means that the user can read data from this space. + +* The ``read,write`` permissions to the ``books`` space mean that the user can read and modify data in this space. + +* The ``session,usage`` permissions to ``universe`` mean the following: + + * ``session``: the user can authenticate over an IPROTO connection. + * ``usage``: lets the user use their privileges on database objects (for example, read and modify data in a space). + +* The ``alter`` permission lets ``testuser`` modify its own settings, for example, a password. + + + +.. _access_control_user_revoking_privileges: + +Revoking user's privileges +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To revoke the specified privileges, use the :ref:`box.schema.user.revoke() ` function. +In the example below, write access to the ``books`` space is revoked: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Revoke space reading + :end-before: End: Revoke space reading + :dedent: + +Revoking the ``session`` permission to ``universe`` can be used to disallow a user to connect to a Tarantool instance: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Revoke session + :end-before: End: Revoke session + :dedent: + + +.. _access_control_users_current_user: + +Changing the current user +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The current user name can be found using :ref:`box.session.user() `. + +.. code-block:: lua + + box.session.user() + --[[ + - admin + --]] + +The current user can be changed: + +* For an :ref:`admin-console ` connection: using :doc:`/reference/reference_lua/box_session/su`: + + .. code-block:: lua + + box.session.su('testuser') + box.session.user() + --[[ + - testuser + --]] + +* For a binary port connection: using the + :ref:`AUTH protocol command `, supported by most clients. + +* For a binary-port connection invoking a stored function with the CALL command: + if the :doc:`SETUID ` + property is enabled for the function, + Tarantool temporarily replaces the current user with the + function's creator, with all the creator's privileges, during function execution. + + + +.. _access_control_users_dropping: + +Dropping users +~~~~~~~~~~~~~~ + +To drop the specified user, call :ref:`box.schema.user.drop() `: + +.. literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua + :language: lua + :start-after: Drop a user + :end-before: End: Drop a user + :dedent: + + + + +.. _authentication-roles: +.. _access_control_roles: + +Managing roles +-------------- + +.. _access_control_roles_creating: + +Creating a role +~~~~~~~~~~~~~~~ + +To create a new role, call :ref:`box.schema.role.create() `. +In the example below, two roles are created: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Create roles + :end-before: End: Create roles + :dedent: + + +.. _access_control_roles_granting_privileges: + +Granting privileges to a role +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To grant the specified privileges to a role, use the :ref:`box.schema.role.grant() ` function. +In the example below, the ``books_space_manager`` role gets read and write permissions to the ``books`` space: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Grant read/write privileges to a role + :end-before: Grant write privileges to a role + :dedent: + +The ``writers_space_reader`` role gets read permissions to the ``writers`` space: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Grant write privileges to a role + :end-before: End: Grant privileges to roles + :dedent: + +Learn more about granting privileges to different types of objects from :ref:`access_control_granting_privileges`. + +.. NOTE:: + + Not all privileges can be granted to roles. + Learn more from :ref:`access_control_list_privileges`. + + +.. _access_control_roles_granting_role: + +Granting a role to a role +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Roles can be assigned to other roles. +In the example below, the newly created ``all_spaces_manager`` role gets all privileges granted to ``books_space_manager`` and ``writers_space_reader``: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Grant a role to a role + :end-before: End: Grant a role to a role + :dedent: + + +.. _access_control_roles_granting_user: + +Granting a role to a user +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To grant the specified role to a :ref:`user `, use the ``box.schema.user.grant()`` function. +In the example below, ``testuser`` gets privileges granted to the ``books_space_manager`` and ``writers_space_reader`` roles: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Grant a role to a user + :end-before: End: Grant a role to a user + :dedent: + + +.. _access_control_roles_info: + +Getting a role's information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To check whether the specified role exists, call :ref:`box.schema.role.exists() `: + +.. code-block:: lua + + box.schema.role.exists('books_space_manager') + --[[ + - true + --]] + +To get information about privileges granted to a role, call :ref:`box.schema.role.info() `: + +.. code-block:: lua + + box.schema.role.info('books_space_manager') + --[[ + - - - read,write + - space + - books + --]] + +If a role has the ``execute`` permission to other roles, this means that these roles are :ref:`granted to this parent role `: + +.. code-block:: lua + + box.schema.role.info('all_spaces_manager') + --[[ + - - - execute + - role + - books_space_manager + - - execute + - role + - writers_space_reader + --]] + + + + +.. _access_control_roles_revoking_role: + +Revoking a role from a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To revoke the specified role from a user, revoke the ``execute`` privilege for this role using the :ref:`box.schema.user.revoke() ` function. +In the example below, the ``books_space_reader`` role is revoked from ``testuser``: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Revoking a role from a user + :end-before: End: Revoking a role from a user + :dedent: + +To revoke role's privileges, use :ref:`box.schema.role.revoke() `. + + +.. _access_control_roles_dropping: + +Dropping roles +~~~~~~~~~~~~~~ + +To drop the specified role, call :ref:`box.schema.role.drop() `: + +.. literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua + :language: lua + :start-after: Dropping a role + :end-before: End: Dropping a role + :dedent: + + + +.. _access_control_granting_privileges: + +Granting privileges +------------------- + +To grant the specified privileges to a user or role, use the :ref:`box.schema.user.grant() ` and :ref:`box.schema.role.grant() ` functions, +which have similar signatures and accept the same set of arguments. +For example, the ``box.schema.user.grant()`` signature looks as follows: + +.. code-block:: lua + + box.schema.user.grant(username, permissions, object-type, object-name[, {options}]) + +* ``username``: the name of the user that gets the specified privileges. +* ``permissions``: a string value that represents :ref:`permissions ` granted to the user. If there are several permissions, they should be separated by commas without a space. +* ``object-type``: a type of :ref:`object ` to which permissions are granted. +* ``object-name``: the name of the object to which permissions are granted. + An empty string (``""``) or ``nil`` provided instead of ``object-name`` grants the specified permissions to all objects of the specified type. + + .. NOTE:: + + ``object-name`` is ignored for the following combinations of permissions and object types: + + * Any permission granted to ``universe``. + * The ``create`` and ``drop`` permissions for the following object types: ``user``, ``role``, ``space``, ``function``, ``sequence``. + * The ``execute`` permission for the following object types: ``lua_eval``, ``lua_call``, ``sql``. + + +.. _access_control_grant_creating_any_obj: + +Any object +~~~~~~~~~~ + +In the example below, ``testuser`` gets privileges allowing them to create any object of any type: + +.. code-block:: lua + + box.schema.user.grant('testuser','read,write,create','universe') + +In this example, ``testuser`` can grant access to objects that ``testuser`` created: + +.. code-block:: lua + + box.schema.user.grant('testuser','write','space','_priv') + + + + +.. _access_control_grant_spaces: + +Spaces +~~~~~~ + +.. _access_control_grant_spaces_create: + +Creating and altering spaces +**************************** + +In the example below, ``testuser`` gets privileges allowing them to create :ref:`spaces `: + +.. code-block:: lua + + box.schema.user.grant('testuser','create','space') + box.schema.user.grant('testuser','write', 'space', '_schema') + box.schema.user.grant('testuser','write', 'space', '_space') + +As you can see, the ability to create spaces also requires ``write`` access to certain system spaces. + +To allow ``testuser`` to drop a space that has associated objects, add the following privileges: + +.. code-block:: lua + + box.schema.user.grant('testuser','create,drop','space') + box.schema.user.grant('testuser','write','space','_schema') + box.schema.user.grant('testuser','write','space','_space') + box.schema.user.grant('testuser','write','space','_space_sequence') + box.schema.user.grant('testuser','read','space','_trigger') + box.schema.user.grant('testuser','read','space','_fk_constraint') + box.schema.user.grant('testuser','read','space','_ck_constraint') + box.schema.user.grant('testuser','read','space','_func_index') + + +.. _access_control_grant_spaces_indexes: + +Creating and altering indexes +***************************** + +In the example below, ``testuser`` gets privileges allowing them to create :ref:`indexes ` in the 'writers' space: + +.. code-block:: lua + + box.schema.user.grant('testuser','create,read','space','writers') + box.schema.user.grant('testuser','read,write','space','_space_sequence') + box.schema.user.grant('testuser','write', 'space', '_index') + +To allow ``testuser`` to alter indexes in the ``writers`` space, grant the privileges below. +This example assumes that indexes in the ``writers`` space are not created by ``testuser``. + +.. code-block:: lua + + box.schema.user.grant('testuser','alter','space','writers') + box.schema.user.grant('testuser','read','space','_space') + box.schema.user.grant('testuser','read','space','_index') + box.schema.user.grant('testuser','read','space','_space_sequence') + box.schema.user.grant('testuser','write','space','_index') + +If ``testuser`` created indexes in the ``writers`` space, granting the following privileges is enough to alter indexes: + +.. code-block:: lua + + box.schema.user.grant('testuser','read','space','_space_sequence') + box.schema.user.grant('testuser','read,write','space','_index') + + +.. _access_control_grant_spaces_crud: + +CRUD operations +*************** + +In this example, ``testuser`` gets privileges allowing them to :ref:`select data ` from the 'writers' space: + +.. code-block:: lua + + box.schema.user.grant('testuser','read','space','writers') + +In this example, ``testuser`` is allowed to read and modify data in the 'books' space: + +.. code-block:: lua + + box.schema.user.grant('testuser','read,write','space','books') + + + + +.. _access_control_grant_sequences: + +Sequences +~~~~~~~~~ + +.. _access_control_grant_sequences_create_drop: + +Creating and dropping sequences +******************************* + +In this example, ``testuser`` gets privileges to create :ref:`sequence ` generators: + +.. code-block:: lua + + box.schema.user.grant('testuser','create','sequence') + box.schema.user.grant('testuser', 'read,write', 'space', '_sequence') + +To let ``testuser`` drop a sequence, grant them the following privileges: + +.. code-block:: lua + + box.schema.user.grant('testuser','drop','sequence') + box.schema.user.grant('testuser','write','space','_sequence_data') + box.schema.user.grant('testuser','write','space','_sequence') + +.. _access_control_grant_sequences_functions: + +Using sequence functions +************************ + +In this example, ``testuser`` is allowed to use the ``id_seq:next()`` function with a sequence named 'id_seq': + +.. code-block:: lua + + box.schema.user.grant('testuser','read,write','sequence','id_seq') + +In the next example, ``testuser`` is allowed to use the ``id_seq:set()`` or ``id_seq:reset()`` functions with a sequence named 'id_seq': + +.. code-block:: lua + + box.schema.user.grant('testuser','write','sequence','id_seq') + + + +.. _access_control_grant_functions: + +Functions +~~~~~~~~~ + +.. _access_control_grant_functions_create_drop: + +Creating and dropping functions +******************************* + +In this example, ``testuser`` gets privileges to create :ref:`functions `: + +.. code-block:: lua + + box.schema.user.grant('testuser','create','function') + box.schema.user.grant('testuser','read,write','space','_func') + +To let ``testuser`` drop a function, grant them the following privileges: + +.. code-block:: lua + + box.schema.user.grant('testuser','drop','function') + box.schema.user.grant('testuser','write','space','_func') + + +.. _access_control_grant_functions_execute: + +Executing functions +******************* + +To give the ability to execute a function named 'sum', grant the following privileges: + +.. code-block:: lua + + box.schema.user.grant('testuser','execute','function','sum') + +.. _access_control_grant_lua_functions_execute: + +Executing lua functions +*********************** + +Granting the 'execute' privilege on ``lua_call`` permits the user to call any global (accessible via the ``_G`` Lua table) +user-defined Lua function with the ``IPROTO_CALL`` request. To grant permission to any non-persistent function, you need to +specify its name when granting the ``lua_call`` privilege. + +.. NOTE:: + + The function doesn't need to be defined at the time privileges are granted, meaning that the access to the function will be provided for the user once this function is defined. + +.. code-block:: lua + + function my_func_1() end + function my_func_2() end + box.cfg({listen = 3301}) + box.schema.user.create('alice', {password = 'secret'}) + conn = require('net.box').connect(box.cfg.listen, {user = 'alice', password = 'secret'}) + box.schema.user.grant('alice', 'execute', 'lua_call', 'my_func_1') + conn:call('my_func_1') -- ok + conn:call('my_func_2') -- access denied + box.schema.user.grant('alice', 'execute', 'lua_call', 'box.session.su') + conn:call('box.session.su', {'admin'}) -- ok + + + +.. _access_control_grant_users: + +Users +~~~~~ + +In this example, ``testuser`` gets privileges to create other users: + +.. code-block:: lua + + box.schema.user.grant('testuser','create','user') + box.schema.user.grant('testuser', 'read,write', 'space', '_user') + box.schema.user.grant('testuser', 'write', 'space', '_priv') + +.. _access_control_grant_roles: + +Roles +~~~~~ + +To let ``testuser`` create new roles, grant the following privileges: + +.. code-block:: lua + + box.schema.user.grant('testuser','create','role') + box.schema.user.grant('testuser', 'read,write', 'space', '_user') + box.schema.user.grant('testuser', 'write', 'space', '_priv') + + +.. _access_control_grant_execute_code: + +Executing code +~~~~~~~~~~~~~~ + +To let ``testuser`` execute Lua code, grant the ``execute`` privilege to the ``lua_eval`` object: + +.. code-block:: lua + + box.schema.user.grant('testuser','execute','lua_eval') + +Similarly, executing an arbitrary SQL expression requires the ``execute`` privilege to the ``sql`` object: + +.. code-block:: lua + + box.schema.user.grant('testuser','execute','sql') + + + + + +.. _creating_users_and_objects_granting_privileges: + +Example +~~~~~~~ + +In the example below, the :ref:`created Lua function ` is executed on behalf of its +creator, even if called by another user. + +First, the two spaces (``space1`` and ``space2``) are created, and a no-password user (``private_user``) +is granted full access to them. Then ``read_and_modify`` is defined and ``private_user`` becomes this function's creator. +Finally, another user (``public_user``) is granted access to execute Lua functions created by ``private_user``. + +.. code-block:: lua + + box.schema.space.create('space1') + box.schema.space.create('space2') + box.space.space1:create_index('pk') + box.space.space2:create_index('pk') + + box.schema.user.create('private_user') + + box.schema.user.grant('private_user', 'read,write', 'space', 'space1') + box.schema.user.grant('private_user', 'read,write', 'space', 'space2') + box.schema.user.grant('private_user', 'create', 'universe') + box.schema.user.grant('private_user', 'read,write', 'space', '_func') + + function read_and_modify(key) + local space1 = box.space.space1 + local space2 = box.space.space2 + local fiber = require('fiber') + local t = space1:get{key} + if t ~= nil then + space1:put{key, box.session.uid()} + space2:put{key, fiber.time()} + end + end + + box.session.su('private_user') + box.schema.func.create('read_and_modify', {setuid= true}) + box.session.su('admin') + box.schema.user.create('public_user', {password = 'secret'}) + box.schema.user.grant('public_user', 'execute', 'function', 'read_and_modify') + +Whenever ``public_user`` calls the function, it is executed on behalf of its creator, ``private_user``. + + + + +.. _access_control_list: + +All object types and permissions +-------------------------------- + +.. _access_control_list_objects: + +Object types +~~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Object type + - Description + * - ``universe`` + - A database (:ref:`box.schema `) that contains database objects, including spaces, indexes, users, roles, sequences, and functions. Granting privileges to ``universe`` gives a user access to any object in the database. + * - ``user`` + - A :ref:`user `. + * - ``role`` + - A :ref:`role `. + * - ``space`` + - A :ref:`space `. + * - ``function`` + - A :ref:`function `. + * - ``sequence`` + - A :ref:`sequence `. + * - ``lua_eval`` + - Executing arbitrary Lua code. + * - ``lua_call`` + - Calling any global user-defined Lua function. + * - ``sql`` + - Executing an arbitrary SQL expression. + + + +.. _access_control_list_privileges: + +Permissions +~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :header-rows: 1 + :widths: 15 15 15 55 + + * - Permission + - Object type + - Granted to roles + - Description + * - ``read`` + - All + - Yes + - Allows reading data of the specified object. + For example, this permission can be used to allow a user to select data from the specified space. + * - ``write`` + - All + - Yes + - Allows updating data of the specified object. + For example, this permission can be used to allow a user to modify data in the specified space. + * - ``create`` + - All + - Yes + - Allows creating objects of the specified type. + For example, this permission can be used to allow a user to create new spaces. + + Note that this permission requires read and write access to certain system spaces. + * - ``alter`` + - All + - Yes + - Allows altering objects of the specified type. + + Note that this permission requires read and write access to certain system spaces. + * - ``drop`` + - All + - Yes + - Allows dropping objects of the specified type. + + Note that this permission requires read and write access to certain system spaces. + * - ``execute`` + - ``role``, ``universe``, ``function``, ``lua_eval``, ``lua_call``, ``sql`` + - Yes + - For ``role``, allows using the specified role. + For other object types, allows calling a function. + * - ``session`` + - ``universe`` + - No + - Allows a user to connect to an instance over IPROTO. + * - ``usage`` + - ``universe`` + - No + - Allows a user to use their privileges on database objects (for example, read, write, and alter spaces). + + +.. _access_control_list_objects_and_privileges: + +Object types and permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :header-rows: 1 + :widths: 15 85 + + * - Object type + - Details + * - ``universe`` + - * ``read``: Allows reading any object types, including all spaces or sequence objects. + * ``write``: Allows modifying any object types, including all spaces or sequence objects. + * ``execute``: Allows execute functions, Lua code, or SQL expressions, including IPROTO calls. + * ``session``: Allows a user to connect to an instance over IPROTO. + * ``usage``: Allows a user to use their privileges on database objects (for example, read, write, and alter space). + * ``create``: Allows creating users, roles, functions, spaces, and sequences. + This permission requires read and write access to certain system spaces. + * ``drop``: Allows creating users, roles, functions, spaces, and sequences. + This permission requires read and write access to certain system spaces. + * ``alter``: Allows altering user settings or space objects. + * - ``user`` + - * ``alter``: Allows modifying a user description, for example, change the password. + * ``create``: Allows creating new users. + This permission requires read and write access to the ``_user`` system space. + * ``drop``: Allows dropping users. + This permission requires read and write access to the ``_user`` system space. + * - ``role`` + - * ``execute``: Indicates that a role is assigned to the user or another role. + * ``create``: Allows creating new roles. + This permission requires read and write access to the ``_user`` system space. + * ``drop``: Allows dropping roles. + This permission requires read and write access to the ``_user`` system space. + * - ``space`` + - * ``read``: Allows selecting data from a space. + * ``write``: Allows modifying data in a space. + * ``create``: Allows creating new spaces. + This permission requires read and write access to the ``_space`` system space. + * ``drop``: Allows dropping spaces. + This permission requires read and write access to the ``_space`` system space. + * ``alter``: Allows modifying spaces. + This permission requires read and write access to the ``_space`` system space. + + If a space is created by a user, they can read and write it without granting explicit permission. + * - ``function`` + - * ``execute``: Allows calling a function. + * ``create``: Allows creating a function. + This permission requires read and write access to the ``_func`` system space. + + If a function is created by a user, they can execute it without granting explicit permission. + * ``drop``: Allows dropping a function. + This permission requires read and write access to the ``_func`` system space. + * - ``sequence`` + - * ``read``: Allows using sequences in ``space_obj:create_index()``. + * ``write``: Allows all operations for a sequence object. + + ``seq_obj:drop()`` requires a write permission to the ``_priv`` system space. + * ``create``: Allows creating sequences. + This permission requires read and write access to the ``_sequence`` system space. + + If a sequence is created by a user, they can read/write it without explicit permission. + * ``drop``: Allows dropping sequences. + This permission requires read and write access to the ``_sequence`` system space. + * ``alter``: Has no effect. + ``seq_obj:alter()`` and other methods require the ``write`` permission. + * - ``lua_eval`` + - * ``execute``: Allows executing arbitrary Lua code using the IPROTO_EVAL request. + * - ``lua_call`` + - * ``execute``: Allows executing any user-defined function using the IPROTO_CALL request. + This permission doesn't allow a user to call built-in Lua functions (for example, ``loadstring()`` or ``box.session.su()``) and functions defined in the ``_func`` system space. + * - ``sql`` + - * ``execute``: Allows executing arbitrary SQL expression using the IPROTO_PREPARE and IPROTO_EXECUTE requests. diff --git a/doc/admin/admin_instances_dev.png b/doc/admin/admin_instances_dev.png new file mode 100644 index 0000000000..7461ae40f0 Binary files /dev/null and b/doc/admin/admin_instances_dev.png differ diff --git a/doc/admin/admin_instances_prod.png b/doc/admin/admin_instances_prod.png new file mode 100644 index 0000000000..143cd9f832 Binary files /dev/null and b/doc/admin/admin_instances_prod.png differ diff --git a/doc/book/admin/backups.rst b/doc/admin/backups.rst similarity index 95% rename from doc/book/admin/backups.rst rename to doc/admin/backups.rst index 6e34d4c396..a2829db05f 100644 --- a/doc/book/admin/backups.rst +++ b/doc/admin/backups.rst @@ -37,15 +37,15 @@ that are made after the last snapshot are incremental backups. Therefore taking a backup is a matter of copying the snapshot and WAL files. 1. Use ``tar`` to make a (possibly compressed) copy of the latest .snap and .xlog - files on the :ref:`memtx_dir ` and - :ref:`wal_dir ` directories. + files on the :ref:`snapshot.dir ` and + :ref:`wal.dir ` directories. 2. If there is a security policy, encrypt the .tar file. 3. Copy the .tar file to a safe place. Later, restoring the database is a matter of taking the .tar file and putting -its contents back in the ``memtx_dir`` and ``wal_dir`` directories. +its contents back in the ``snapshot.dir`` and ``wal.dir`` directories. .. _admin-backups-hot_backup_vinyl_memtx: diff --git a/doc/book/admin/bug_reports.rst b/doc/admin/bug_reports.rst similarity index 100% rename from doc/book/admin/bug_reports.rst rename to doc/admin/bug_reports.rst diff --git a/doc/book/admin/daemon_supervision.rst b/doc/admin/daemon_supervision.rst similarity index 100% rename from doc/book/admin/daemon_supervision.rst rename to doc/admin/daemon_supervision.rst diff --git a/doc/admin/disaster_recovery.rst b/doc/admin/disaster_recovery.rst new file mode 100644 index 0000000000..e9ff332a5d --- /dev/null +++ b/doc/admin/disaster_recovery.rst @@ -0,0 +1,161 @@ +.. _admin-disaster_recovery: + +Disaster recovery +================= + +The minimal fault-tolerant Tarantool configuration would be a :ref:`replica set ` +that includes a master and a replica, or two masters. +The basic recommendation is to configure all Tarantool instances in a replica set to create :ref:`snapshot files ` on a regular basis. + +Here are action plans for typical crash scenarios. + + +.. _admin-disaster_recovery-master_replica: + +Master-replica +-------------- + +.. _admin-disaster_recovery-master_replica_manual_failover: + +Master crash: manual failover +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Configuration:** master-replica (:ref:`manual failover `). + +**Problem:** The master has crashed. + +**Actions:** + +1. Ensure the master is stopped. + For example, log in to the master machine and use ``tt stop``. + +2. Configure a new replica set leader using the :ref:`.leader ` option. + +3. Reload configuration on all instances using :ref:`config:reload() `. + +4. Make sure that a new replica set leader is a master using :ref:`box.info.ro `. + +5. On a new master, :ref:`remove a crashed instance from the '_cluster' space `. + +6. Set up a replacement for the crashed master on a spare host. + +See also: :ref:`Performing manual failover `. + + +.. _admin-disaster_recovery-master_replica_auto_failover: + +Master crash: automated failover +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Configuration:** master-replica (:ref:`automated failover `). + +**Problem:** The master has crashed. + +**Actions:** + +1. Use ``box.info.election`` to make sure a new master is elected automatically. + +2. On a new master, :ref:`remove a crashed instance from the '_cluster' space `. + +3. Set up a replacement for the crashed master on a spare host. + +See also: :ref:`Testing automated failover `. + + +.. _admin-disaster_recovery-master_replica_data_loss: + +Data loss +~~~~~~~~~ + +**Configuration:** master-replica. + +**Problem:** Some transactions are missing on a replica after the master has crashed. + +**Actions:** + +You lose a few transactions in the master +:ref:`write-ahead log file `, which may have not +transferred to the replica before the crash. If you were able to salvage the master +``.xlog`` file, you may be able to recover these. + +1. Find out instance UUID from the crashed master :ref:`xlog `: + + .. code-block:: console + + $ head -5 var/lib/instance001/*.xlog | grep Instance + Instance: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + +2. On the new master, use the UUID to find the position: + + .. code-block:: tarantoolsession + + app:instance002> box.info.vclock[box.space._cluster.index.uuid:select{'9bb111c2-3ff5-36a7-00f4-2b9a573ea660'}[1][1]] + --- + - 999 + ... + +3. :ref:`Play the records ` from the crashed ``.xlog`` to the new master, starting from the + new master position: + + .. code-block:: console + + $ tt play 127.0.0.1:3302 var/lib/instance001/00000000000000000000.xlog \ + --from 1000 \ + --replica 1 \ + --username admin --password secret + + +.. _admin-disaster_recovery-master_master: + +Master-master +------------- + +**Configuration:** :ref:`master-master `. + +**Problem:** one master has crashed. + +**Actions:** + +1. Let the load be handled by another master alone. + +2. Remove a crashed master from a replica set. + +3. Set up a replacement for the crashed master on a spare host. + Learn more from :ref:`Adding and removing instances `. + + +.. _admin-disaster_recovery-data_loss: + +Master-replica/master-master: data loss +--------------------------------------- + +**Configuration:** master-replica or master-master. + +**Problem:** Data was deleted at one master and this data loss was propagated to the other node (master or replica). + +**Actions:** + +1. Put all nodes in read-only mode. + Depending on the :ref:`replication.failover ` mode, this can be done as follows: + + - ``manual``: change a replica set leader to ``null``. + - ``election``: set :ref:`replication.election_mode ` to ``voter`` or ``off`` at the replica set level. + - ``off``: set ``database.mode`` to ``ro``. + + Reload configurations on all instances using the ``reload()`` function provided by the :ref:`config ` module. + +2. Turn off deletion of expired checkpoints with :doc:`/reference/reference_lua/box_backup/start`. + This prevents the Tarantool garbage collector from removing files + made with older checkpoints until :doc:`/reference/reference_lua/box_backup/stop` is called. + +3. Get the latest valid :ref:`.snap file ` and + use ``tt cat`` command to calculate at which LSN the data loss occurred. + +4. Start a new instance and use :ref:`tt play ` command to + play to it the contents of ``.snap`` and ``.xlog`` files up to the calculated LSN. + +5. Bootstrap a new replica from the recovered master. + +.. NOTE:: + + The steps above are applicable only to data in the memtx storage engine. diff --git a/doc/admin/flight_recorder.rst b/doc/admin/flight_recorder.rst new file mode 100644 index 0000000000..a0407790b9 --- /dev/null +++ b/doc/admin/flight_recorder.rst @@ -0,0 +1,78 @@ +.. _enterprise-flight-recorder: + +Flight recorder +=============== + +.. admonition:: Enterprise Edition + :class: fact + + The flight recorder is available in the `Enterprise Edition `_ only. + +**Example on GitHub**: `flightrec `_ + +The flight recorder is an event collection tool that gathers various information about a working Tarantool instance, such as: + +* logs +* metrics +* requests and responses + +This information helps you investigate incidents related +to :ref:`crashing ` a Tarantool instance. + +.. _enterprise-flight-recorder_enable: + +Enable the flight recorder +-------------------------- + +The flight recorder is disabled by default and can be enabled and configured for +a specific Tarantool instance. +To enable the flight recorder, set the :ref:`flightrec.enabled ` +configuration option to ``true``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: enabled: true + :dedent: + + +After ``flightrec.enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. +This file is stored in the :ref:`snapshot.dir ` directory. +By default, the directory is ``var/lib/{{ instance_name }}/.ttfr``. + +If the instance crashes and reboots, Tarantool rotates the flight recording: +``current.ttfr`` is renamed to ``.ttfr`` (for example, ``20230411T050721.ttfr``) +and the new ``current.ttfr`` file is created for collecting data. +In the case of correct shutdown (for example, using ``os.exit()``), +Tarantool continues writing to the existing ``current.ttfr`` file after restart. + +.. NOTE:: + + Note that old flight recordings should be removed manually. + + +.. _enterprise-flight-recorder_configure: + +Configure the flight recorder +----------------------------- + +When the flight recorder is enabled, you can set the options related to :ref:`logging `, +:ref:`metrics `, and storing the :ref:`request and response ` data. + +The ``flightrec`` configuration might look as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/flightrec/config.yaml + :language: yaml + :start-at: flightrec: + :end-at: 10485780 + :dedent: + +In the example, the following options are set: + +* :ref:`flightrec.logs_size ` -- a log storage size in bytes. +* :ref:`flightrec.logs_log_level ` -- a :ref:`log_level `. +* :ref:`flightrec.metrics_period ` -- the number of seconds to store metrics after the dump. +* :ref:`flightrec.metrics_interval ` -- the frequency of metrics dumps in seconds. +* :ref:`flightrec.requests_size ` -- a storage size for the request and response data in bytes. + +Read more: :ref:`Flight recorder configuration options `. diff --git a/doc/admin/index.rst b/doc/admin/index.rst new file mode 100644 index 0000000000..3cdff5bc34 --- /dev/null +++ b/doc/admin/index.rst @@ -0,0 +1,42 @@ +:noindex: +:fullwidth: + +.. _admin: + +Administration +============== + +Tarantool is designed to have multiple running instances on the same host. + +Here we show how to administer Tarantool instances using any of the following +utilities: + +* ``systemd`` native utilities, or +* :ref:`tt `, a command-line utility for managing Tarantool-based applications. + +.. NOTE:: + + * Unlike the rest of this manual, here we use system-wide paths. + * Console examples here are for Fedora. + +This chapter includes the following sections: + +.. toctree:: + :maxdepth: 1 + :numbered: 0 + + modules + logs + security + access_control + replication/index + server_introspection + daemon_supervision + disaster_recovery + backups + upgrades + bug_reports + flight_recorder + monitoring + os_notes + troubleshoot diff --git a/doc/admin/logs.rst b/doc/admin/logs.rst new file mode 100644 index 0000000000..067a93a3de --- /dev/null +++ b/doc/admin/logs.rst @@ -0,0 +1,90 @@ +.. _admin-logs: + +Logs +==== + +Each Tarantool instance logs important events to its own log file. +For instances started with :ref:`tt `, the log location is defined by +the ``log_dir`` parameter in the :ref:`tt configuration `. +By default, it's ``/var/log/tarantool`` in the ``tt`` :ref:`system mode `, +and the ``var/log`` subdirectory of the ``tt`` working directory in the :ref:`local mode `. +In the specified location, ``tt`` creates separate directories for each instance's logs. + +To check how logging works, write something to the log using the :ref:`log ` module: + +.. code-block:: console + + $ tt connect application + • Connecting to the instance... + • Connected to application + + application> require('log').info("Hello for the manual readers") + --- + ... + +Then check the logs: + +.. code-block:: console + + $ tail instances.enabled/application/var/log/instance001/tt.log + 2024-04-09 17:34:29.489 [49502] main/106/gc I> wal/engine cleanup is resumed + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'instance_name' configuration option to "instance001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'custom_proc_title' configuration option to "tarantool - instance001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'log_nonblock' configuration option to false + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'replicaset_name' configuration option to "replicaset001" + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'listen' configuration option to [{"uri":"127.0.0.1:3301"}] + 2024-04-09 17:34:29.489 [49502] main/107/checkpoint_daemon I> scheduled next checkpoint for Tue Apr 9 19:08:04 2024 + 2024-04-09 17:34:29.489 [49502] main/104/interactive/box.load_cfg I> set 'metrics' configuration option to {"labels":{"alias":"instance001"},"include":["all"],"exclude":[]} + 2024-04-09 17:34:29.489 [49502] main I> entering the event loop + 2024-04-09 17:34:38.905 [49502] main/116/console/unix/:/tarantool I> Hello for the manual readers + +.. _admin-logs-rotation: + +Log rotation +------------ + +When :ref:`logging to a file `, the system administrator must ensure +logs are rotated timely and do not take up all the available disk space. +The recommended way to prevent log files from growing infinitely is using an external +log rotation program, for example, ``logrotate``, which is pre-installed on most +mainstream Linux distributions. + +A Tarantool log rotation configuration for ``logrotate`` can look like this: + +.. code-block:: text + + # /var/log/tarantool////*.log + /var/log/tarantool/*/*/*/*.log { + daily + size 512k + missingok + rotate 10 + compress + delaycompress + sharedscripts # Run tt logrotate only once after all logs are rotated. + postrotate + /usr/bin/tt -S logrotate + endscript + } + +In this configuration, :ref:`tt logrotate ` is called after each log +rotation to reopen the instance log files after they are moved by the ``logrotate`` +program. + +There is also the built-in function :ref:`log.rotate() `, which you +can call on an instance to reopen its log file after rotation. + + +.. _admin-logs-destination: + +Log destination +--------------- + +Tarantool can write its logs to a log file, to ``syslog``, or to a specified program through a pipe. +For example, to send logs to ``syslog``, specify the :ref:`log.to ` parameter as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml + :language: yaml + :start-at: log: + :end-at: 127.0.0.1:514 + :dedent: diff --git a/doc/book/admin/modules.rst b/doc/admin/modules.rst similarity index 100% rename from doc/book/admin/modules.rst rename to doc/admin/modules.rst diff --git a/doc/admin/monitoring.rst b/doc/admin/monitoring.rst new file mode 100644 index 0000000000..24a696f3fc --- /dev/null +++ b/doc/admin/monitoring.rst @@ -0,0 +1,17 @@ +.. _monitoring: + +Monitoring +========== + +Monitoring is the process of capturing runtime information about the instances of a Tarantool cluster using metrics. +Metrics can indicate various characteristics, such as memory usage, the number of records in spaces, replication status, and so on. +Typically, metrics are monitored in real time, allowing for the identification of current issues or the prediction of potential ones. + +.. toctree:: + :maxdepth: 1 + :numbered: 0 + + monitoring/getting_started + monitoring/grafana_dashboard + monitoring/alerting + monitoring/metrics_reference diff --git a/doc/admin/monitoring/alerting.rst b/doc/admin/monitoring/alerting.rst new file mode 100644 index 0000000000..9e65949150 --- /dev/null +++ b/doc/admin/monitoring/alerting.rst @@ -0,0 +1,420 @@ +.. _monitoring-alerting-page: + +=============================================================================== +Alerting +=============================================================================== + +You can set up alerts on metrics to get a notification when something went +wrong. We will use `Prometheus alert rules `_ +as an example here. You can get full ``alerts.yml`` file at +`tarantool/grafana-dashboard GitHub repo `_. + +.. _monitoring-alerting-tarantool: + +------------------------------------------------------------------------------- +Tarantool metrics +------------------------------------------------------------------------------- + +You can use internal Tarantool metrics to monitor detailed RAM consumption, +replication state, database engine status, track business logic issues (like +HTTP 4xx and 5xx responses or low request rate) and external modules statistics +(like ``CRUD`` errors). Evaluation timeouts, severity +levels and thresholds (especially ones for business logic) are placed here for +the sake of example: you may want to increase or decrease them for your +application. Also, don't forget to set sane rate time ranges based on your +Prometheus configuration. + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Lua memory +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Monitoring ``tnt_info_memory_lua`` metric may prevent memory overflow and detect the presence of bad Lua code practices. + +.. NOTE:: + + The Lua memory is limited to 2 GB per instance if Tarantool doesn't have the GC64 mode enabled for LuaJIT. + +.. code-block:: yaml + + - alert: HighLuaMemoryWarning + expr: tnt_info_memory_lua >= (512 * 1024 * 1024) + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') Lua runtime warning" + description: "'{{ $labels.alias }}' instance of job '{{ $labels.job }}' uses too much Lua memory + and may hit threshold soon." + + - alert: HighLuaMemoryAlert + expr: tnt_info_memory_lua >= (1024 * 1024 * 1024) + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') Lua runtime alert" + description: "'{{ $labels.alias }}' instance of job '{{ $labels.job }}' uses too much Lua memory + and likely to hit threshold soon." + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Memtx arena memory +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +By monitoring :ref:`slab allocation statistics ` you can see +how many free RAM is remaining to store memtx tuples and indexes for an +instance. If Tarantool hit the limits, the instance will become unavailable +for write operations, so this alert may help you see when it's time to increase +your ``memtx_memory`` limit or to add a new storage to a vshard cluster. + +.. code-block:: yaml + + - alert: LowMemtxArenaRemainingWarning + expr: (tnt_slab_quota_used_ratio >= 80) and (tnt_slab_arena_used_ratio >= 80) + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') low arena memory remaining" + description: "Low arena memory (tuples and indexes) remaining for '{{ $labels.alias }}' instance of job '{{ $labels.job }}'. + Consider increasing memtx_memory or number of storages in case of sharded data." + + - alert: LowMemtxArenaRemaining + expr: (tnt_slab_quota_used_ratio >= 90) and (tnt_slab_arena_used_ratio >= 90) + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') low arena memory remaining" + description: "Low arena memory (tuples and indexes) remaining for '{{ $labels.alias }}' instance of job '{{ $labels.job }}'. + You are likely to hit limit soon. + It is strongly recommended to increase memtx_memory or number of storages in case of sharded data." + + - alert: LowMemtxItemsRemainingWarning + expr: (tnt_slab_quota_used_ratio >= 80) and (tnt_slab_items_used_ratio >= 80) + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') low items memory remaining" + description: "Low items memory (tuples) remaining for '{{ $labels.alias }}' instance of job '{{ $labels.job }}'. + Consider increasing memtx_memory or number of storages in case of sharded data." + + - alert: LowMemtxItemsRemaining + expr: (tnt_slab_quota_used_ratio >= 90) and (tnt_slab_items_used_ratio >= 90) + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') low items memory remaining" + description: "Low items memory (tuples) remaining for '{{ $labels.alias }}' instance of job '{{ $labels.job }}'. + You are likely to hit limit soon. + It is strongly recommended to increase memtx_memory or number of storages in case of sharded data." + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Vinyl engine status +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +You can monitor :ref:`vinyl regulator ` +performance to track possible scheduler or disk issues. + +.. code-block:: yaml + + - alert: LowVinylRegulatorRateLimit + expr: tnt_vinyl_regulator_rate_limit < 100000 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') have low vinyl regulator rate limit" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' have low vinyl engine regulator rate limit. + This indicates issues with the disk or the scheduler." + + +:ref:`Vinyl transactions ` errors are likely +to lead to user requests errors. + +.. code-block:: yaml + + - alert: HighVinylTxConflictRate + expr: rate(tnt_vinyl_tx_conflict[5m]) / rate(tnt_vinyl_tx_commit[5m]) > 0.05 + for: 1m + labels: + severity: critical + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') have high vinyl tx conflict rate" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' have + high vinyl transactions conflict rate. It indicates that vinyl is not healthy." + +:ref:`Vinyl scheduler ` failed tasks +are a good signal of disk issues and may be the reason of increasing RAM +consumption. + +.. code-block:: yaml + + - alert: HighVinylSchedulerFailedTasksRate + expr: rate(tnt_vinyl_scheduler_tasks{status="failed"}[5m]) > 0.1 + for: 1m + labels: + severity: critical + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') have high vinyl scheduler failed tasks rate" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' have + high vinyl scheduler failed tasks rate." + + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Replication state +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +If ``tnt_replication_status`` is equal to ``0``, instance :ref:`replication ` +status is not equal to ``"follows"``: replication is either not ready yet or +has been stopped due to some reason. + +.. code-block:: yaml + + - alert: ReplicationNotRunning + expr: tnt_replication_status == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') {{ $labels.stream }} (id {{ $labels.id }}) + replication is not running" + description: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') {{ $labels.stream }} (id {{ $labels.id }}) + replication is not running." + +Even if async replication is ``"follows"``, it could be considered malfunctioning +if the lag is too high. It also may affect Tarantool garbage collector work, +see :ref:`box.info.gc() `. + +.. code-block:: yaml + + - alert: HighReplicationLag + expr: tnt_replication_lag > 1 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') have high replication lag (id {{ $labels.id }})" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' have high replication lag + (id {{ $labels.id }}), check up your network and cluster state." + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Event loop +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +High :ref:`fiber ` event loop time leads to bad application +performance, timeouts and various warnings. The reason could be a high quantity +of working fibers or fibers that spend too much time without any yields or +sleeps. + +.. code-block:: yaml + + - alert: HighEVLoopTime + expr: tnt_ev_loop_time > 0.1 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') event loop has high cycle duration" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' event loop has high cycle duration. + Some high loaded fiber has too little yields. It may be the reason of 'Too long WAL write' warnings." + + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Configuration status +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +:ref:`Configuration status ` displays +Tarantool 3 configuration apply state. Additional metrics display the count +of apply warnings and errors. + +.. code-block:: yaml + + - alert: ConfigWarningAlerts + expr: tnt_config_alerts{level="warn"} > 0 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') has configuration 'warn' alerts" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' has configuration 'warn' alerts. + Please, check config:info() for detailed info." + + - alert: ConfigErrorAlerts + expr: tnt_config_alerts{level="error"} > 0 + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') has configuration 'error' alerts" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' has configuration 'error' alerts. + Latest configuration has not been applied. + Please, check config:info() for detailed info." + + - alert: ConfigStatusNotReady + expr: tnt_config_status{status="ready"} == 0 + for: 5m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') configuration is not ready" + description: "Instance '{{ $labels.alias }}' of job '{{ $labels.job }}' configuration is not ready. + Please, check config:info() for detailed info." + + + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +HTTP server statistics +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +:ref:`metrics ` allows to monitor `tarantool/http `_ +handles, see :ref:`"Collecting HTTP request latency statistics" `. +Here we use a ``summary`` collector with a default name and 0.99 quantile +computation. + +Too many responses with error codes usually is a sign of API issues or +application malfunction. + +.. code-block:: yaml + + - alert: HighInstanceHTTPClientErrorRate + expr: sum by (job, instance, method, path, alias) (rate(http_server_request_latency_count{ job="tarantool", status=~"^4\\d{2}$" }[5m])) > 10 + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') high rate of client error responses" + description: "Too many {{ $labels.method }} requests to {{ $labels.path }} path + on '{{ $labels.alias }}' instance of job '{{ $labels.job }}' get client error (4xx) responses." + + - alert: HighHTTPClientErrorRate + expr: sum by (job, method, path) (rate(http_server_request_latency_count{ job="tarantool", status=~"^4\\d{2}$" }[5m])) > 20 + for: 1m + labels: + severity: page + annotations: + summary: "Job '{{ $labels.job }}' high rate of client error responses" + description: "Too many {{ $labels.method }} requests to {{ $labels.path }} path + on instances of job '{{ $labels.job }}' get client error (4xx) responses." + + - alert: HighHTTPServerErrorRate + expr: sum by (job, instance, method, path, alias) (rate(http_server_request_latency_count{ job="tarantool", status=~"^5\\d{2}$" }[5m])) > 0 + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') server error responses" + description: "Some {{ $labels.method }} requests to {{ $labels.path }} path + on '{{ $labels.alias }}' instance of job '{{ $labels.job }}' get server error (5xx) responses." + +Responding with high latency is a synonym of insufficient performance. It may +be a sign of application malfunction. Or maybe you need to add more routers to +your cluster. + +.. code-block:: yaml + + - alert: HighHTTPLatency + expr: http_server_request_latency{ job="tarantool", quantile="0.99" } > 0.1 + for: 5m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') high HTTP latency" + description: "Some {{ $labels.method }} requests to {{ $labels.path }} path with {{ $labels.status }} response status + on '{{ $labels.alias }}' instance of job '{{ $labels.job }}' are processed too long." + +Having too little requests when you expect them may detect balancer, external +client or network malfunction. + +.. code-block:: yaml + + - alert: LowRouterHTTPRequestRate + expr: sum by (job, instance, alias) (rate(http_server_request_latency_count{ job="tarantool", alias=~"^.*router.*$" }[5m])) < 10 + for: 5m + labels: + severity: warning + annotations: + summary: "Router '{{ $labels.alias }}' ('{{ $labels.job }}') low activity" + description: "Router '{{ $labels.alias }}' instance of job '{{ $labels.job }}' gets too little requests. + Please, check up your balancer middleware." + + +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +CRUD module statistics +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +If your application uses `CRUD `_ module +requests, monitoring module statistics may track internal errors caused by +invalid process of input and internal parameters. + +.. code-block:: yaml + + - alert: HighCRUDErrorRate + expr: rate(tnt_crud_stats_count{ job="tarantool", status="error" }[5m]) > 0.1 + for: 1m + labels: + severity: critical + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') too many CRUD {{ $labels.operation }} errors." + description: "Too many {{ $labels.operation }} CRUD requests for '{{ $labels.name }}' space on + '{{ $labels.alias }}' instance of job '{{ $labels.job }}' get module error responses." + +Statistics could also monitor requests performance. Too high request latency +will lead to high latency of client responses. It may be caused by network +or disk issues. Read requests with bad (with respect to space indexes and +sharding schema) conditions may lead to full-scans or map reduces and also +could be the reason of high latency. + +.. code-block:: yaml + + - alert: HighCRUDLatency + expr: tnt_crud_stats{ job="tarantool", quantile="0.99" } > 0.1 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') too high CRUD {{ $labels.operation }} latency." + description: "Some {{ $labels.operation }} {{ $labels.status }} CRUD requests for '{{ $labels.name }}' space on + '{{ $labels.alias }}' instance of job '{{ $labels.job }}' are processed too long." + +You also can directly monitor map reduces and scan rate. + +.. code-block:: yaml + + - alert: HighCRUDMapReduceRate + expr: rate(tnt_crud_map_reduces{ job="tarantool" }[5m]) > 0.1 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance '{{ $labels.alias }}' ('{{ $labels.job }}') too many CRUD {{ $labels.operation }} map reduces." + description: "There are too many {{ $labels.operation }} CRUD map reduce requests for '{{ $labels.name }}' space on + '{{ $labels.alias }}' instance of job '{{ $labels.job }}'. + Check your request conditions or consider changing sharding schema." + + +.. _monitoring-alerting-server: + +------------------------------------------------------------------------------- +Server-side monitoring +------------------------------------------------------------------------------- + +If there are no Tarantool metrics, you may miss critical conditions. Prometheus +provide ``up`` metric to monitor the health of its targets. + +.. code-block:: yaml + + - alert: InstanceDown + expr: up == 0 + for: 1m + labels: + severity: page + annotations: + summary: "Instance '{{ $labels.instance }}' ('{{ $labels.job }}') down" + description: "'{{ $labels.instance }}' of job '{{ $labels.job }}' has been down for more than a minute." + +Do not forget to monitor your server's CPU, disk and RAM from server side with +your favorite tools. For example, on some high CPU consumption cases Tarantool +instance may stop to send metrics, so you can track such breakdowns only from +the outside. diff --git a/doc/admin/monitoring/getting_started.rst b/doc/admin/monitoring/getting_started.rst new file mode 100644 index 0000000000..e36b1dbe3f --- /dev/null +++ b/doc/admin/monitoring/getting_started.rst @@ -0,0 +1,111 @@ +.. _monitoring-getting_started: + +Getting started with monitoring +=============================== + +Example on GitHub: `sharded_cluster_crud_metrics `_ + +Tarantool allows you to configure and expose its :ref:`metrics ` using a :ref:`YAML configuration `. +You can also use the built-in :ref:`metrics ` module to create and collect custom metrics. + + + + +.. _monitoring_configuring_metrics: + +Configuring metrics +------------------- + +To configure metrics, use the :ref:`metrics ` section in a cluster configuration. +The configuration below enables all metrics excluding :ref:`vinyl `-specific ones: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml + :start-at: metrics: + :end-at: instance_name + :language: yaml + :dedent: + +The ``metrics.labels`` option accepts the predefined :ref:`{{ instance_name }} ` variable. +This adds an instance name as a :ref:`label ` to every observation. + +Third-party Lua modules, like `crud `_ or `expirationd `_, offer their own metrics. +You can enable these metrics by :ref:`configuring the corresponding role `. +The example below shows how to enable statistics on called operations by providing the ``roles.crud-router`` role's configuration: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml + :language: yaml + :start-after: routers: + :end-at: stats_quantiles + :dedent: + +``expirationd`` metrics can be enabled as follows: + +.. code-block:: yaml + + expirationd: + cfg: + metrics: true + + + +.. _monitoring_exposing_metrics: + +Exposing metrics +---------------- + +To expose metrics in different formats, you can use a third-party `metrics-export-role `__ role. +In the following example, the metrics of ``storage-a-001`` are provided on two endpoints: + +- ``/metrics/prometheus``: exposes metrics in the Prometheus format. +- ``/metrics/json``: exposes metrics in the JSON format. + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml + :start-at: storage-a-001: + :end-at: format: json + :language: yaml + :dedent: + +Example on GitHub: `sharded_cluster_crud_metrics `_ + +.. NOTE:: + + The ``metrics`` module provides a set of plugins that can be used to collect and expose metrics in different formats. Learn more in :ref:`metrics-api_reference_collecting_using_plugins`. + + + +.. _monitoring_create_metrics: + +Creating custom metrics +----------------------- + +The ``metrics`` module allows you to create and collect custom metrics. +The example below shows how to collect the number of data operations performed on the specified space by increasing a ``counter`` value inside the :ref:`on_replace() ` trigger function: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_replace_count.lua + :start-after: -- Collect a custom metric + :end-before: -- End + :language: lua + :dedent: + +Learn more in :ref:`metrics-api_reference_custom_metrics`. + + + +.. _monitoring_collecting_metrics: + +Collecting metrics +------------------ + +When metrics are configured and exposed, you can use the desired third-party tool to collect them. +Below is the example of a Prometheus scrape configuration that collects metrics of multiple Tarantool instances: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/prometheus/prometheus.yml + :language: yaml + :dedent: + +For more information on collecting and visualizing metrics, refer to :ref:`monitoring-grafana_dashboard-page`. + +.. NOTE:: + + |tcm_full_name| allows you to view metrics of connected clusters in real time. + Learn more in :ref:`tcm_cluster_metrics`. diff --git a/doc/admin/monitoring/grafana_dashboard.rst b/doc/admin/monitoring/grafana_dashboard.rst new file mode 100644 index 0000000000..fb596fbd88 --- /dev/null +++ b/doc/admin/monitoring/grafana_dashboard.rst @@ -0,0 +1,171 @@ +.. _monitoring-grafana_dashboard-page: + +Grafana dashboard +================= + +After :ref:`enabling and configuring metrics `, you can visualise them using Tarantool Grafana dashboards. +These dashboards are available as part of +`Grafana official & community-built dashboards `_: + +.. container:: table + + .. list-table:: + :widths: 50 50 + :header-rows: 0 + + * - Tarantool 3 + - `Prometheus `_, `InfluxDB `_ + + * - Tarantool Cartridge and Tarantool 1.10—2.x + - `Prometheus `_, `InfluxDB `_ + + * - Tarantool Data Grid 2 + - `Prometheus `_, `InfluxDB `_ + +The Tarantool Grafana dashboard is a ready for import template with basic memory, +space operations, and HTTP load panels, based on default `metrics `_ +package functionality. + +.. image:: images/Prometheus_dashboard_1.png + :width: 30% + +.. image:: images/Prometheus_dashboard_2.png + :width: 30% + +.. image:: images/Prometheus_dashboard_3.png + :width: 30% + +.. _monitoring-grafana_dashboard-monitoring_stack: + + +Prepare a monitoring stack +-------------------------- + +Since there are Prometheus and InfluxDB data source Grafana dashboards, +you can use one of the following: + +- `Telegraf `_ + as a server agent for collecting metrics, `InfluxDB `_ + as a time series database for storing metrics, and `Grafana `_ + as a visualization platform. +- `Prometheus `_ as both a server agent for collecting metrics + and a time series database for storing metrics, and `Grafana `_ + as a visualization platform. + +For issues related to setting up Prometheus, Telegraf, InfluxDB, or Grafana instances, refer to the corresponding project's documentation. + +.. _monitoring-grafana_dashboard-collect_metrics: + +Collect metrics with server agents +---------------------------------- + +.. _monitoring-grafana_dashboard-collect_metrics_prometheus: + +Prometheus +~~~~~~~~~~ + +To collect metrics for Prometheus, first set up metrics output with ``prometheus`` format. +You can use the :ref:`roles.metrics-export ` configuration or set up the :ref:`Prometheus plugin ` manually. +To start collecting metrics, `add a job `_ +to Prometheus configuration with each Tarantool instance URI as a target and +metrics path as it was configured on Tarantool instances: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/prometheus/prometheus.yml + :language: yaml + :dedent: + +.. _monitoring-grafana_dashboard-collect_metrics_influxdb: + +InfluxDB +~~~~~~~~ + +To collect metrics for InfluxDB, use the Telegraf agent. +First off, configure Tarantool metrics output in ``json`` format +with :ref:`roles.metrics-export ` configuration or corresponding :ref:`JSON plugin `. +To start collecting metrics, add `http input `_ +to Telegraf configuration including each Tarantool instance metrics URL: + +.. code-block:: toml + + [[inputs.http]] + urls = [ + "http://example_project:8081/metrics/json", + "http://example_project:8082/metrics/json", + "http://example_project:8083/metrics/json", + "http://example_project:8084/metrics/json", + "http://example_project:8085/metrics/json" + ] + timeout = "30s" + tag_keys = [ + "metric_name", + "label_pairs_alias", + "label_pairs_quantile", + "label_pairs_path", + "label_pairs_method", + "label_pairs_status", + "label_pairs_operation", + "label_pairs_level", + "label_pairs_id", + "label_pairs_engine", + "label_pairs_name", + "label_pairs_index_name", + "label_pairs_delta", + "label_pairs_stream", + "label_pairs_thread", + "label_pairs_kind" + ] + insecure_skip_verify = true + interval = "10s" + data_format = "json" + name_prefix = "tarantool_" + fieldpass = ["value"] + +Be sure to include each label key as ``label_pairs_`` to extract it +with the plugin. +For example, if you use :code:`{ state = 'ready' }` labels somewhere in metric collectors, add ``label_pairs_state`` tag key. + + + +.. _monitoring-grafana_dashboard-import: + +Import the dashboard +-------------------- + +Open Grafana import menu. + +.. image:: images/grafana_import.png + :align: left + +To import a specific dashboard, choose one of the following options: + +- paste the dashboard id (``21474`` for Prometheus dashboard, ``21484`` for InfluxDB dashboard) +- paste a link to the dashboard (https://grafana.com/grafana/dashboards/21474 for Prometheus dashboard, https://grafana.com/grafana/dashboards/21484 for InfluxDB dashboard) +- paste the dashboard JSON file contents +- upload the dashboard JSON file + +Set dashboard name, folder and uid (if needed). + +.. image:: images/grafana_import_setup.png + :align: left + +You can choose the data source and data source variables after import. + +.. image:: images/grafana_variables_setup.png + :align: left + +.. _monitoring-grafana_dashboard-troubleshooting: + +Troubleshooting +--------------- + +- If there are no data on the graphs, make sure that you picked datasource and job/measurement correctly. + +- If there are no data on the graphs, make sure that you have ``info`` group of Tarantool metrics + (in particular, ``tnt_info_uptime``). + +- If some Prometheus graphs show no data because of ``parse error: missing unit character in duration``, + ensure that you use Grafana 7.2 or newer. + +- If some Prometheus graphs display ``parse error: bad duration syntax "1m0"`` or similar error, you need + to update your Prometheus version. See + `grafana/grafana#44542 `_ for more details. diff --git a/doc/admin/monitoring/images/Prometheus_dashboard_1.png b/doc/admin/monitoring/images/Prometheus_dashboard_1.png new file mode 100644 index 0000000000..3ea5fed7ce Binary files /dev/null and b/doc/admin/monitoring/images/Prometheus_dashboard_1.png differ diff --git a/doc/admin/monitoring/images/Prometheus_dashboard_2.png b/doc/admin/monitoring/images/Prometheus_dashboard_2.png new file mode 100644 index 0000000000..5cf04310ce Binary files /dev/null and b/doc/admin/monitoring/images/Prometheus_dashboard_2.png differ diff --git a/doc/admin/monitoring/images/Prometheus_dashboard_3.png b/doc/admin/monitoring/images/Prometheus_dashboard_3.png new file mode 100644 index 0000000000..c03c0e7f03 Binary files /dev/null and b/doc/admin/monitoring/images/Prometheus_dashboard_3.png differ diff --git a/doc/admin/monitoring/images/grafana_import.png b/doc/admin/monitoring/images/grafana_import.png new file mode 100644 index 0000000000..1260367d93 Binary files /dev/null and b/doc/admin/monitoring/images/grafana_import.png differ diff --git a/doc/admin/monitoring/images/grafana_import_setup.png b/doc/admin/monitoring/images/grafana_import_setup.png new file mode 100644 index 0000000000..23400abb14 Binary files /dev/null and b/doc/admin/monitoring/images/grafana_import_setup.png differ diff --git a/doc/admin/monitoring/images/grafana_variables_setup.png b/doc/admin/monitoring/images/grafana_variables_setup.png new file mode 100644 index 0000000000..4737b4ee69 Binary files /dev/null and b/doc/admin/monitoring/images/grafana_variables_setup.png differ diff --git a/doc/admin/monitoring/metrics_reference.rst b/doc/admin/monitoring/metrics_reference.rst new file mode 100644 index 0000000000..e78c657e7e --- /dev/null +++ b/doc/admin/monitoring/metrics_reference.rst @@ -0,0 +1,986 @@ +.. _metrics-reference: + +Metrics reference +================= + +This page provides a detailed description of metrics from the ``metrics`` module. + +General metrics +--------------- + +General instance information: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_cfg_current_time`` + - Instance system time in the Unix timestamp format + * - ``tnt_info_uptime`` + - Time in seconds since the instance has started + * - ``tnt_read_only`` + - Indicates if the instance is in read-only mode (``1`` if true, ``0`` if false) + +.. _metrics-reference-memory_general: + +Memory general +-------------- + +The following metrics provide a picture of memory usage by the Tarantool process. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_info_memory_cache`` + - Number of bytes in the cache used to store + tuples with the vinyl storage engine. + * - ``tnt_info_memory_data`` + - Number of bytes used to store user data (tuples) + with the memtx engine and with level 0 of the vinyl engine, + without regard for memory fragmentation. + * - ``tnt_info_memory_index`` + - Number of bytes used for indexing user data. + Includes memtx and vinyl memory tree extents, + the vinyl page index, and the vinyl bloom filters. + * - ``tnt_info_memory_lua`` + - Number of bytes used for the Lua runtime. + Monitoring this metric can prevent memory overflow. + * - ``tnt_info_memory_net`` + - Number of bytes used for network input/output buffers. + * - ``tnt_info_memory_tx`` + - Number of bytes in use by active transactions. + For the vinyl storage engine, + this is the total size of all allocated objects + (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) + and tuples pinned for those objects. + +.. _metrics-reference-memory_allocation: + +Memory allocation +----------------- + +Provides a memory usage report for the slab allocator. +The slab allocator is the main allocator used to store tuples. +The following metrics help monitor the total memory usage and memory fragmentation. +To learn more about use cases, refer to the +:ref:`box.slab submodule documentation `. + +Available memory, bytes: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_slab_quota_size`` + - Amount of memory available to store tuples and indexes. + Is equal to ``memtx_memory``. + * - ``tnt_slab_arena_size`` + - Total memory available to store both tuples and indexes. + Includes allocated but currently free slabs. + * - ``tnt_slab_items_size`` + - Total amount of memory available to store only tuples and not indexes. + Includes allocated but currently free slabs. + +Memory usage, bytes: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_slab_quota_used`` + - The amount of memory that is already reserved by the slab allocator. + * - ``tnt_slab_arena_used`` + - The effective memory used to store both tuples and indexes. + Disregards allocated but currently free slabs. + * - ``tnt_slab_items_used`` + - The effective memory used to store only tuples and not indexes. + Disregards allocated but currently free slabs. + +Memory utilization, %: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_slab_quota_used_ratio`` + - ``tnt_slab_quota_used / tnt_slab_quota_size`` + * - ``tnt_slab_arena_used_ratio`` + - ``tnt_slab_arena_used / tnt_slab_arena_size`` + * - ``tnt_slab_items_used_ratio`` + - ``tnt_slab_items_used / tnt_slab_items_size`` + +.. _metrics-reference-spaces: + +Spaces +------ + +The following metrics provide specific information +about each individual space in a Tarantool instance. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_space_len`` + - Number of records in the space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. + * - ``tnt_space_bsize`` + - Total number of bytes in all tuples. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space + and ``engine`` is the engine of the space. + * - ``tnt_space_index_bsize`` + - Total number of bytes taken by the index. + This metric always has 2 labels: ``{name="test", index_name="pk"}``, + where ``name`` is the name of the space and + ``index_name`` is the name of the index. + * - ``tnt_space_total_bsize`` + - Total size of tuples and all indexes in the space. + This metric always has 2 labels: ``{name="test", engine="memtx"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. + * - ``tnt_vinyl_tuples`` + - Total tuple count for vinyl. + This metric always has 2 labels: ``{name="test", engine="vinyl"}``, + where ``name`` is the name of the space and + ``engine`` is the engine of the space. For vinyl this metric is disabled + by default and can be enabled only with global variable setup: + ``rawset(_G, 'include_vinyl_count', true)``. + +.. _metrics-reference-network: + +Network +------- + +Network activity stats. +These metrics can be used to monitor network load, usage peaks, and traffic drops. + +Sent bytes: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_sent_total`` + - Bytes sent from the instance over the network since the instance's start time + +Received bytes: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_received_total`` + - Bytes received by the instance since start time + +Connections: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_connections_total`` + - Number of incoming network connections since the instance's start time + * - ``tnt_net_connections_current`` + - Number of active network connections + +Requests: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_requests_total`` + - Number of network requests the instance has handled since its start time + * - ``tnt_net_requests_current`` + - Number of pending network requests + +Requests in progress: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_requests_in_progress_total`` + - Total count of requests processed by tx thread + * - ``tnt_net_requests_in_progress_current`` + - Count of requests currently being processed in the tx thread + +Requests placed in queues of streams: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_net_requests_in_stream_total`` + - Total count of requests, which was placed in queues of streams + for all time + * - ``tnt_net_requests_in_stream_current`` + - Count of requests currently waiting in queues of streams + +Since Tarantool 2.10 in each network metric has the label ``thread``, showing per-thread network statistics. + +.. _metrics-reference-fibers: + +Fibers +------ + +Provides the statistics for :ref:`fibers `. +If your application creates a lot of fibers, +you can use the metrics below to monitor fiber count and memory usage. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_fiber_amount`` + - Number of fibers + * - ``tnt_fiber_csw`` + - Overall number of fiber context switches + * - ``tnt_fiber_memalloc`` + - Amount of memory reserved for fibers + * - ``tnt_fiber_memused`` + - Amount of memory used by fibers + +.. _metrics-reference-operations: + +Operations +---------- + +You can collect iproto requests an instance has processed +and aggregate them by request type. +This may help you find out what operations your clients perform most often. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_stats_op_total`` + - Total number of calls since server start + +To distinguish between request types, this metric has the ``operation`` label. +For example, it can look as follows: ``{operation="select"}``. +For the possible request types, check the table below. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``auth`` + - Authentication requests + * - ``call`` + - Requests to execute stored procedures + * - ``delete`` + - Delete calls + * - ``error`` + - Requests resulted in an error + * - ``eval`` + - Calls to evaluate Lua code + * - ``execute`` + - Execute SQL calls + * - ``insert`` + - Insert calls + * - ``prepare`` + - SQL prepare calls + * - ``replace`` + - Replace calls + * - ``select`` + - Select calls + * - ``update`` + - Update calls + * - ``upsert`` + - Upsert calls + +.. _metrics-reference-replication: + +Replication +----------- + +Provides the current replication status. +Learn more about :ref:`replication in Tarantool `. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_info_lsn`` + - LSN of the instance. + * - ``tnt_info_vclock`` + - LSN number in vclock. + This metric always has the label ``{id="id"}``, + where ``id`` is the instance's number in the replica set. + * - ``tnt_replication_lsn`` + - LSN of the tarantool instance. + This metric always has labels ``{id="id", type="type"}``, where + ``id`` is the instance's number in the replica set, + ``type`` is ``master`` or ``replica``. + * - ``tnt_replication_lag`` + - Replication lag value in seconds. + This metric always has labels ``{id="id", stream="stream"}``, + where ``id`` is the instance's number in the replica set, + ``stream`` is ``downstream`` or ``upstream``. + * - ``tnt_replication_status`` + - This metrics equals 1 when replication status is "follow" and 0 otherwise. + This metric always has labels ``{id="id", stream="stream"}``, + where ``id`` is the instance's number in the replica set, + ``stream`` is ``downstream`` or ``upstream``. + +.. _metrics-reference-runtime: + +Runtime +------- + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_runtime_lua`` + - Lua garbage collector size in bytes + * - ``tnt_runtime_used`` + - Number of bytes used for the Lua runtime + * - ``tnt_runtime_tuple`` + - Number of bytes used for the tuples (except tuples owned by memtx and vinyl) + + + +.. _metrics-reference-luajit: + +LuaJIT metrics +-------------- + +LuaJIT metrics provide an insight into the work of the Lua garbage collector. +These metrics are available in Tarantool 2.6 and later. + +General JIT metrics: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_jit_snap_restore_total`` + - Overall number of snap restores + * - ``lj_jit_trace_num`` + - Number of JIT traces + * - ``lj_jit_trace_abort_total`` + - Overall number of abort traces + * - ``lj_jit_mcode_size`` + - Total size of allocated machine code areas + +JIT strings: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_strhash_hit_total`` + - Number of strings being interned + * - ``lj_strhash_miss_total`` + - Total number of string allocations + +GC steps: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_gc_steps_atomic_total`` + - Count of incremental GC steps (atomic state) + * - ``lj_gc_steps_sweepstring_total`` + - Count of incremental GC steps (sweepstring state) + * - ``lj_gc_steps_finalize_total`` + - Count of incremental GC steps (finalize state) + * - ``lj_gc_steps_sweep_total`` + - Count of incremental GC steps (sweep state) + * - ``lj_gc_steps_propagate_total`` + - Count of incremental GC steps (propagate state) + * - ``lj_gc_steps_pause_total`` + - Count of incremental GC steps (pause state) + +Allocations: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``lj_gc_strnum`` + - Number of allocated ``string`` objects + * - ``lj_gc_tabnum`` + - Number of allocated ``table`` objects + * - ``lj_gc_cdatanum`` + - Number of allocated ``cdata`` objects + * - ``lj_gc_udatanum`` + - Number of allocated ``udata`` objects + * - ``lj_gc_freed_total`` + - Total amount of freed memory + * - ``lj_gc_memory`` + - Current allocated Lua memory + * - ``lj_gc_allocated_total`` + - Total amount of allocated memory + +.. _metrics-reference-psutils: +.. _metrics-api_reference-cpu_usage_metrics: + +CPU metrics +----------- + +The following metrics provide CPU usage statistics. +They are only available on Linux. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_cpu_number`` + - Total number of processors configured by the operating system + * - ``tnt_cpu_time`` + - Host CPU time + * - ``tnt_cpu_thread`` + - Tarantool thread CPU time. + This metric always has the labels + ``{kind="user", thread_name="tarantool", thread_pid="pid", file_name="init.lua"}``, + where: + + * ``kind`` can be either ``user`` or ``system`` + * ``thread_name`` is ``tarantool``, ``wal``, ``iproto``, or ``coio`` + * ``file_name`` is the entrypoint file name, for example, ``init.lua``. + +There are also two cross-platform metrics, which can be obtained with a ``getrusage()`` call. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_cpu_user_time`` + - Tarantool CPU user time + * - ``tnt_cpu_system_time`` + - Tarantool CPU system time + +.. _metrics-reference-vinyl: + +Vinyl +----- + +Vinyl metrics provide :ref:`vinyl engine ` statistics. + +.. _metrics-reference-vinyl-disk: + +Disk +~~~~ + +The disk metrics are used to monitor overall data size on disk. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_disk_data_size`` + - Amount of data in bytes stored in the ``.run`` files + located in :ref:`vinyl_dir ` + * - ``tnt_vinyl_disk_index_size`` + - Amount of data in bytes stored in the ``.index`` files + located in :ref:`vinyl_dir ` + +.. _metrics-reference-vinyl_regulator: + +Regulator +~~~~~~~~~ + +The vinyl regulator decides when to commence disk IO actions. +It groups activities in batches so that they are more consistent and +efficient. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_regulator_dump_bandwidth`` + - Estimated average dumping rate, bytes per second. + The rate value is initially 10485760 (10 megabytes per second). + It is recalculated depending on the the actual rate. + Only significant dumps that are larger than 1 MB are used for estimating. + * - ``tnt_vinyl_regulator_write_rate`` + - Actual average rate of performing write operations, bytes per second. + The rate is calculated as a 5-second moving average. + If the metric value is gradually going down, + this can indicate disk issues. + * - ``tnt_vinyl_regulator_rate_limit`` + - Write rate limit, bytes per second. + The regulator imposes the limit on transactions + based on the observed dump/compaction performance. + If the metric value is down to approximately ``10^5``, + this indicates issues with the disk + or the :ref:`scheduler `. + * - ``tnt_vinyl_regulator_dump_watermark`` + - Maximum amount of memory in bytes used + for in-memory storing of a vinyl LSM tree. + When this maximum is accessed, a dump must occur. + For details, see :ref:`engines-algorithm_filling_lsm`. + The value is slightly smaller + than the amount of memory allocated for vinyl trees, + reflected in the :ref:`vinyl_memory ` parameter. + * - ``tnt_vinyl_regulator_blocked_writers`` + - The number of fibers that are blocked waiting + for Vinyl level0 memory quota. + +.. _metrics-reference-transactional-activity: + +Transactional activity +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_tx_commit`` + - Counter of commits (successful transaction ends) + Includes implicit commits: for example, any insert operation causes a + commit unless it is within a + :doc:`/reference/reference_lua/box_txn_management/begin`\ --\ :doc:`/reference/reference_lua/box_txn_management/commit` + block. + * - ``tnt_vinyl_tx_rollback`` + - Сounter of rollbacks (unsuccessful transaction ends). + This is not merely a count of explicit + :doc:`/reference/reference_lua/box_txn_management/rollback` + requests -- it includes requests that ended with errors. + * - ``tnt_vinyl_tx_conflict`` + - Counter of conflicts that caused transactions to roll back. + The ratio ``tnt_vinyl_tx_conflict / tnt_vinyl_tx_commit`` + above 5% indicates that vinyl is not healthy. + At that moment, you'll probably see a lot of other problems with vinyl. + * - ``tnt_vinyl_tx_read_views`` + - Current number of read views -- that is, transactions + that entered the read-only state to avoid conflict temporarily. + Usually the value is ``0``. + If it stays non-zero for a long time, it is indicative of a memory leak. + + +.. _metrics-reference-memory: + +Memory +~~~~~~ + +The following metrics show state memory areas used by vinyl for caches and write buffers. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_memory_tuple_cache`` + - Amount of memory in bytes currently used to store tuples (data) + * - ``tnt_vinyl_memory_level0`` + - "Level 0" (L0) memory area, bytes. + L0 is the area that vinyl can use for in-memory storage of an LSM tree. + By monitoring this metric, you can see when L0 is getting close to its + maximum (``tnt_vinyl_regulator_dump_watermark``), + at which time a dump will occur. + You can expect L0 = 0 immediately after the dump operation is completed. + * - ``tnt_vinyl_memory_page_index`` + - Amount of memory in bytes currently used to store indexes. + If the metric value is close to :ref:`vinyl_memory `, + this indicates that :ref:`vinyl_page_size ` + was chosen incorrectly. + * - ``tnt_vinyl_memory_bloom_filter`` + - Amount of memory in bytes used by + :ref:`bloom filters `. + * - ``tnt_vinyl_memory_tuple`` + - Total size of memory in bytes occupied by Vinyl tuples. + It includes cached tuples and tuples pinned by the Lua world. + +.. _metrics-reference-vinyl_scheduler: + +Scheduler +~~~~~~~~~ + +The vinyl scheduler invokes the :ref:`regulator ` and +updates the related variables. This happens once per second. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_vinyl_scheduler_tasks`` + - Number of scheduler dump/compaction tasks. + The metric always has label ``{status = }``, + where ```` can be one of the following: + + * ``inprogress`` for currently running tasks + * ``completed`` for successfully completed tasks + * ``failed`` for tasks aborted due to errors. + + * - ``tnt_vinyl_scheduler_dump_time`` + - Total time in seconds spent by all worker threads performing dumps. + * - ``tnt_vinyl_scheduler_dump_total`` + - Counter of dumps completed. + +.. _metrics-reference-memory_event_loop: + +Event loop metrics +------------------ + +Event loop tx thread information: + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_ev_loop_time`` + - Event loop time (ms) + * - ``tnt_ev_loop_prolog_time`` + - Event loop prolog time (ms) + * - ``tnt_ev_loop_epilog_time`` + - Event loop epilog time (ms) + + +.. _metrics-reference-synchro: + +Synchro +------- + +Shows the current state of a synchronous replication. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_synchro_queue_owner`` + - Instance ID of the current synchronous replication master. + + * - ``tnt_synchro_queue_term`` + - Current queue term. + + * - ``tnt_synchro_queue_len`` + - How many transactions are collecting confirmations now. + + * - ``tnt_synchro_queue_busy`` + - Whether the queue is processing any system entry (CONFIRM/ROLLBACK/PROMOTE/DEMOTE). + +.. _metrics-reference-election: + +Election +-------- + +Shows the current state of a replica set node in regards to leader election. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_election_state`` + - Election state (mode) of the node. + When election is enabled, the node is writable only in the leader state. + Possible values: + + * 0 (``follower``): all the non-leader nodes are called followers + * 1 (``candidate``): the nodes that start a new election round are called candidates. + * 2 (``leader``): the node that collected a quorum of votes becomes the leader + + * - ``tnt_election_vote`` + - ID of a node the current node votes for. + If the value is 0, it means the node hasn’t voted in the current term yet. + + * - ``tnt_election_leader`` + - Leader node ID in the current term. + If the value is 0, it means the node doesn’t know which node is the leader in the current term. + + * - ``tnt_election_term`` + - Current election term. + + * - ``tnt_election_leader_idle`` + - Time in seconds since the last interaction with the known leader. + +Memtx +----- + +Memtx mvcc memory statistics. +Transaction manager consists of two parts: + +- the transactions themselves (TXN section) +- MVCC + +.. _metrics-reference-memtx_txn: + +TXN +~~~ + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_memtx_tnx_statements`` are the transaction statements. + - For example, the user started a transaction and made an action in it `space:replace{0, 1}`. + Under the hood, this operation will turn into ``statement`` for the current transaction. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``total``: the number of bytes that are allocated for the statements of all current transactions. + * ``average``: average bytes used by transactions for statements + (`txn.statements.total` bytes / number of open transactions). + * ``max``: the maximum number of bytes used by one the current transaction for statements. + + * - ``tnt_memtx_tnx_user`` + - In Tarantool C API there is a function `box_txn_alloc()`. + By using this function user can allocate memory for the current transaction. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``total``: memory allocated by the `box_txn_alloc()` function on all current transactions. + * ``average``: transaction average (total allocated bytes / number of all current transactions). + * ``max``: the maximum number of bytes allocated by `box_txn_alloc()` function per transaction. + + * - ``tnt_memtx_tnx_system`` + - There are internals: logs, savepoints. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``total``: memory allocated by internals on all current transactions. + * ``average``: average allocated memory by internals (total memory / number of all current transactions). + * ``max``: the maximum number of bytes allocated by internals per transaction. + +.. _metrics-reference-memtx_mvcc: + +MVCC +~~~~ + +``mvcc`` is responsible for the isolation of transactions. +It detects conflicts and makes sure that tuples that are no longer in the space, but read by some transaction +(or can be read) have not been deleted. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_memtx_mvcc_trackers`` + - Trackers that keep track of transaction reads. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``total``: trackers of all current transactions are allocated in total (in bytes). + * ``average``: average for all current transactions (total memory bytes / number of transactions). + * ``max``: maximum trackers allocated per transaction (in bytes). + + * - ``tnt_memtx_mvcc_conflicts`` + - Allocated in case of transaction conflicts. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``total``: bytes allocated for conflicts in total. + * ``average``: average for all current transactions (total memory bytes / number of transactions). + * ``max``: maximum bytes allocated for conflicts per transaction. + + +.. _metrics-reference-tuples: + +~~~~~~ +Tuples +~~~~~~ + +Saved tuples are divided into 3 categories: ``used``, ``read_view``, ``tracking``. + +Each category has two metrics: + +- ``retained`` tuples - they are no longer in the index, but MVCC does not allow them to be removed. +- ``stories`` - MVCC is based on the story mechanism, almost every tuple has a story. + This is a separate metric because even the tuples that are in the index can have a story. + So ``stories`` and ``retained`` need to be measured separately. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_memtx_mvcc_tuples_used_stories`` + - Tuples that are used by active read-write transactions. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of ``used`` tuples / number of stories. + * ``total``: amount of bytes used by stories ``used`` tuples. + + * - ``tnt_memtx_mvcc_tuples_used_retained`` + - Tuples that are used by active read-write transactions. + But they are no longer in the index, but MVCC does not allow them to be removed. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of retained ``used`` tuples / number of stories. + * ``total``: amount of bytes used by retained ``used`` tuples. + + * - ``tnt_memtx_mvcc_tuples_read_view_stories`` + - Tuples that are not used by active read-write transactions, + but are used by read-only transactions (i.e. in read view). + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of ``read_view`` tuples / number of stories. + * ``total``: amount of bytes used by stories ``read_view`` tuples. + + * - ``tnt_memtx_mvcc_tuples_read_view_retained`` + - Tuples that are not used by active read-write transactions, + but are used by read-only transactions (i.e. in read view). + This tuples are no longer in the index, but MVCC does not allow them to be removed. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of retained ``read_view`` tuples / number of stories. + * ``total``: amount of bytes used by retained ``read_view`` tuples. + + * - ``tnt_memtx_mvcc_tuples_tracking_stories`` + - Tuples that are not directly used by any transactions, but are used by MVCC to track reads. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of ``tracking`` tuples / number of tracking stories. + * ``total``: amount of bytes used by stories ``tracking`` tuples. + + * - ``tnt_memtx_mvcc_tuples_tracking_retained`` + - Tuples that are not directly used by any transactions, but are used by MVCC to track reads. + This tuples are no longer in the index, but MVCC does not allow them to be removed. + This metric always has the label ``{kind="..."}``, + which has the following possible values: + + * ``count``: number of retained ``tracking`` tuples / number of stories. + * ``total``: amount of bytes used by retained ``tracking`` tuples. + + +.. _metrics-reference-read-view: + +~~~~~~~~~~~~~~~~~~~~ +Read view statistics +~~~~~~~~~~~~~~~~~~~~ + + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_memtx_tuples_data_total`` + - Total amount of memory (in bytes) allocated for data tuples. + This includes ``tnt_memtx_tuples_data_read_view`` and + ``tnt_memtx_tuples_data_garbage`` metric values plus tuples that + are actually stored in memtx spaces. + + * - ``tnt_memtx_tuples_data_read_view`` + - Memory (in bytes) held for read views. + + * - ``tnt_memtx_tuples_data_garbage`` + - Memory (in bytes) that is unused and scheduled to be freed + (freed lazily on memory allocation). + + * - ``tnt_memtx_index_total`` + - Total amount of memory (in bytes) allocated for indexing data. + This includes ``tnt_memtx_index_read_view`` metric value + plus memory used for indexing tuples + that are actually stored in memtx spaces. + + * - ``tnt_memtx_index_read_view`` + - Memory (in bytes) held for read views. + + +.. _metrics-reference-tarantool-config: + +Tarantool configuration +----------------------- + +**Since:** :doc:`3.0.0 `. + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``tnt_config_alerts`` + - Count of current instance :ref:`configuration apply alerts `. + ``{level="warn"}`` label covers warnings and + ``{level="error"}`` covers errors. + + * - ``tnt_config_status`` + - The status of current instance :ref:`configuration apply `. + ``status`` label contains possible status name. + Current status has metric value ``1``, inactive statuses have metric value ``0``. + + .. code-block:: none + + # HELP tnt_config_status Tarantool 3 configuration status + # TYPE tnt_config_status gauge + tnt_config_status{status="reload_in_progress",alias="router-001-a"} 0 + tnt_config_status{status="uninitialized",alias="router-001-a"} 0 + tnt_config_status{status="check_warnings",alias="router-001-a"} 0 + tnt_config_status{status="ready",alias="router-001-a"} 1 + tnt_config_status{status="check_errors",alias="router-001-a"} 0 + tnt_config_status{status="startup_in_progress",alias="router-001-a"} 0 + + For example, this set of metrics means that current configuration + for ``router-001-a`` status is ``ready``. \ No newline at end of file diff --git a/doc/book/admin/os_notes.rst b/doc/admin/os_notes.rst similarity index 86% rename from doc/book/admin/os_notes.rst rename to doc/admin/os_notes.rst index e7c8ba7a10..954007ede5 100644 --- a/doc/book/admin/os_notes.rst +++ b/doc/admin/os_notes.rst @@ -38,12 +38,3 @@ Checking that it works: $ /etc/init.d/your_service_name start $ tail -f -n 100 /var/log/tarantool/your_service_name.log - - -.. _admin-os_notes-freebsd: - -FreeBSD -------- - -To learn about specifics of using the deprecated ``tarantoolctl`` utility on FreeBSD, -check its :ref:`documentation `. \ No newline at end of file diff --git a/doc/admin/replication/_images/box_info_replication_instance001.png b/doc/admin/replication/_images/box_info_replication_instance001.png new file mode 100644 index 0000000000..d071cbccc0 Binary files /dev/null and b/doc/admin/replication/_images/box_info_replication_instance001.png differ diff --git a/doc/admin/replication/_images/box_info_replication_instance002.png b/doc/admin/replication/_images/box_info_replication_instance002.png new file mode 100644 index 0000000000..3c393b1d31 Binary files /dev/null and b/doc/admin/replication/_images/box_info_replication_instance002.png differ diff --git a/doc/admin/replication/index.rst b/doc/admin/replication/index.rst new file mode 100644 index 0000000000..10cebdee8c --- /dev/null +++ b/doc/admin/replication/index.rst @@ -0,0 +1,10 @@ +Replication administration +========================== + +.. toctree:: + :maxdepth: 1 + + repl_monitoring + repl_recover + repl_reseed + repl_problem_solving diff --git a/doc/book/admin/replication/mr-degraded.svg b/doc/admin/replication/mr-degraded.svg similarity index 100% rename from doc/book/admin/replication/mr-degraded.svg rename to doc/admin/replication/mr-degraded.svg diff --git a/doc/admin/replication/repl_monitoring.rst b/doc/admin/replication/repl_monitoring.rst new file mode 100644 index 0000000000..ee68f3c3f5 --- /dev/null +++ b/doc/admin/replication/repl_monitoring.rst @@ -0,0 +1,54 @@ +.. _replication-monitoring: + +Monitoring a replica set +======================== + +To learn what instances belong to the replica set and obtain statistics for all +these instances, execute a :ref:`box.info.replication ` request. +The output below shows the replication status for a replica set containing one :ref:`master and two replicas `: + +.. include:: /platform/replication/replication_tutorials/repl_bootstrap.rst + :start-after: box_info_replication_manual_leader_start + :end-before: box_info_replication_manual_leader_end + +The following diagram illustrates the ``upstream`` and ``downstream`` connections if ``box.info.replication`` executed at the master instance (``instance001``): + +.. image:: _images/box_info_replication_instance001.png + :width: 600 + :align: center + :alt: replication status on master + +If ``box.info.replication`` is executed on ``instance002``, the ``upstream`` and ``downstream`` connections look as follows: + +.. image:: _images/box_info_replication_instance002.png + :width: 600 + :align: center + :alt: replication status on replica + +This means that statistics for replicas are given in regard to the instance on which ``box.info.replication`` is executed. + +The primary indicators of replication health are: + +.. _heartbeat: + +* :ref:`idle `: the time (in seconds) since + the instance received the last event from a master. + + If the master has no updates to send to the replicas, it sends heartbeat messages + every :ref:`replication_timeout ` seconds. The master + is programmed to disconnect if it does not see acknowledgments of the heartbeat messages + within ``replication_timeout`` * 4 seconds. + + Therefore, in a healthy replication setup, ``idle`` should never exceed + ``replication_timeout``: if it does, either the replication is lagging + seriously behind, because the master is running ahead of the replica, or the + network link between the instances is down. + +* :ref:`lag `: the time difference between + the local time at the instance, recorded when the event was received, and the + local time at another master recorded when the event was written to the + :ref:`write-ahead log ` on that master. + + Since the ``lag`` calculation uses the operating system clocks from two different + machines, do not be surprised if it’s negative: a time drift may lead to the + remote master clock being consistently behind the local instance's clock. diff --git a/doc/book/admin/replication/repl_problem_solving.rst b/doc/admin/replication/repl_problem_solving.rst similarity index 82% rename from doc/book/admin/replication/repl_problem_solving.rst rename to doc/admin/replication/repl_problem_solving.rst index 8774b94c0c..a72a833e8b 100644 --- a/doc/book/admin/replication/repl_problem_solving.rst +++ b/doc/admin/replication/repl_problem_solving.rst @@ -1,36 +1,33 @@ .. _replication-problem_solving: -================================================================================ -Resolving replication conflicts -================================================================================ --------------------------------------------------------------------------------- -Solving problems with master-master replication --------------------------------------------------------------------------------- +Resolving replication conflicts +=============================== Tarantool guarantees that every update is applied only once on every replica. -However, due to the asynchronous nature of replication, the order of updates is -not guaranteed. We now analyze this problem with more details, provide examples -of replication going out of sync, and suggest solutions. +However, due to the asynchronous nature of replication, the order of updates is not guaranteed. +This topic describes how to solve problems in :ref:`master-master ` replication. + + +.. _replication-problem_solving_replacing_primary_key: -******************************* Replacing the same primary key -******************************* +------------------------------ **Case 1:** You have two instances of Tarantool. For example, you try to make a -``replace`` operation with the same primary key on both instances in the same time. -This will cause a conflict over which tuple to save and which one to discard. +``replace`` operation with the same primary key on both instances at the same time. +This causes a conflict over which tuple to save and which one to discard. Tarantool :ref:`trigger functions ` can help here to implement the rules of conflict resolution on some condition. For example, if you have a timestamp, you can declare saving the tuple with the bigger one. First, you need a :ref:`before_replace() ` trigger on -the space which may have conflicts. In this trigger you can compare the old and new +the space which may have conflicts. In this trigger, you can compare the old and new replica records and choose which one to use (or skip the update entirely, or merge two records together). -Then you need to set the trigger at the right time, before the space starts +Then you need to set the trigger at the right time before the space starts to receive any updates. The way you usually set the ``before_replace`` trigger is right when the space is created, so you need a trigger to set another trigger on the system space ``_space``, to capture the moment when your space is created @@ -45,7 +42,7 @@ To set a ``_space:on_replace()`` trigger correctly, you also need the right timi timing to use it is when ``_space`` is just created, which is the :ref:`box.ctl.on_schema_init() ` trigger. -You will also need to utilize ``box.on_commit`` to get access to the space being +You also need to utilize ``box.on_commit`` to get access to the space being created. The resulting snippet would be the following: .. code-block:: lua @@ -62,16 +59,16 @@ created. The resulting snippet would be the following: end) end) + + .. _replication-duplicates: -**************************** Preventing duplicate insert -**************************** +--------------------------- .. _replication-replication_stops: -**Case 2:** In a replica set of two masters, suppose master #1 tries to -``insert`` a tuple with the same unique key: +**Case 2:** In a replica set of two masters, both of them try to insert data by the same unique key: .. code-block:: tarantoolsession @@ -150,20 +147,14 @@ report), because the downstream has encountered the same error: uuid: e826a667-eed7-48d5-a290-64299b159571 ... -When replication is later manually resumed: - -.. code-block:: tarantoolsession - # resuming stopped replication (at all masters) - tarantool> original_value = box.cfg.replication - tarantool> box.cfg{replication={}} - tarantool> box.cfg{replication=original_value} +To learn how to resolve a replication conflict by reseeding a replica, see :ref:`Resolving replication conflicts `. -... the faulty row in the write-ahead-log files is skipped. .. _replication-runs_out_of_sync: -**Solution #1: replication runs out of sync** +Replication runs out of sync +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In a master-master cluster of two instances, suppose we make the following operation: @@ -189,10 +180,11 @@ When this operation is applied on both instances in the replica set: .. _replication-commutative_changes: -**Solution #2: commutative changes** +Commutative changes +~~~~~~~~~~~~~~~~~~~ The cases described in the previous paragraphs represent examples of -**non-commutative** operations, i.e. operations whose result depends on the +**non-commutative** operations, that is operations whose result depends on the execution order. On the contrary, for **commutative operations**, the execution order does not matter. @@ -205,10 +197,14 @@ Consider for example the following command: This operation is commutative: we get the same result no matter in which order the update is applied on the other masters. -**Solution #3: trigger usage** +.. _replication_trigger_usage: + +Trigger usage +~~~~~~~~~~~~~ -The logic and the snippet setting a trigger will be the same here as in case 1. -But the trigger function will differ: +The logic and the snippet setting a trigger will be the same here as in :ref:`case 1 `. +But the trigger function will differ. +Note that the trigger below assumes that tuple has a timestamp in the second field. .. code-block:: lua diff --git a/doc/admin/replication/repl_recover.rst b/doc/admin/replication/repl_recover.rst new file mode 100644 index 0000000000..a9af04d815 --- /dev/null +++ b/doc/admin/replication/repl_recover.rst @@ -0,0 +1,53 @@ +.. _replication-recover: + +Recovering from a degraded state +================================ + +"Degraded state" is a situation when the master becomes unavailable -- due to +hardware or network failure, or due to a programming bug. + +.. image:: mr-degraded.svg + :align: center + +- In a master-replica set with :ref:`manual failover `, if a master disappears, error messages appear on the + replicas stating that the connection is lost: + + .. code-block:: console + + 2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 I> can't read row + 2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 19, aka 127.0.0.1:55932, peer of 127.0.0.1:3301: Broken pipe + 2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 I> will retry every 1.00 second + 2023-12-04 13:19:04.724 [16755] relay/127.0.0.1:55940/101/main coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 23, aka 127.0.0.1:3302, peer of 127.0.0.1:55940: Broken pipe + 2023-12-04 13:19:04.724 [16755] relay/127.0.0.1:55940/101/main I> exiting the relay loop + +- In a master-replica set with :ref:`automated failover `, a log also includes Raft messages showing the process of a new master's election: + + .. code-block:: console + + 2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 I> can't read row + 2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 24, aka 127.0.0.1:55687, peer of 127.0.0.1:3302: Broken pipe + 2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 I> will retry every 1.00 second + 2023-12-04 13:16:56.340 [16615] relay/127.0.0.1:55695/101/main coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 25, aka 127.0.0.1:3301, peer of 127.0.0.1:55695: Broken pipe + 2023-12-04 13:16:56.340 [16615] relay/127.0.0.1:55695/101/main I> exiting the relay loop + 2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: message {term: 3, vote: 2, state: candidate, vclock: {1: 9}} from 2 + 2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: received a newer term from 2 + 2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: bump term to 3, follow + 2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: vote for 2, follow + 2023-12-04 13:16:59.691 [16615] main/119/raft_worker I> RAFT: persisted state {term: 3} + 2023-12-04 13:16:59.691 [16615] main/119/raft_worker I> RAFT: persisted state {term: 3, vote: 2} + 2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: message {term: 3, vote: 2, leader: 2, state: leader} from 2 + 2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: vote request is skipped - this is a notification about a vote for a third node, not a request + 2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: leader is 2, follow + + + +The master's upstream status is reported as ``disconnected`` when executing :ref:`box.info.replication ` on a replica: + +.. include:: /platform/replication/replication_tutorials/repl_bootstrap_auto.rst + :start-after: box_info_replication_auto_leader_disconnected_start + :end-before: box_info_replication_auto_leader_disconnected_end + + +To learn how to perform manual failover in a master-replica set, see the :ref:`Performing manual failover ` section. + +In a master-replica configuration with automated failover, a new master should be elected :ref:`automatically `. diff --git a/doc/admin/replication/repl_reseed.rst b/doc/admin/replication/repl_reseed.rst new file mode 100644 index 0000000000..9725156d65 --- /dev/null +++ b/doc/admin/replication/repl_reseed.rst @@ -0,0 +1,22 @@ +.. _replication-reseed: + +================================================================================ +Reseeding a replica +================================================================================ + +If any of a replica's write-ahead log or snapshot files are corrupted or deleted, you can reseed the replica. +This procedure works only if the master's write-ahead logs are present. + +1. Stop the replica using the :ref:`tt stop ` command. + +2. Delete write-ahead logs and snapshots stored in the ``var/lib/`` directory. + + .. NOTE:: + + ``var/lib`` is the default directory used by tt to store write-ahead logs and snapshots. + Learn more from :ref:`Configuration `. + +3. Start the replica using the :ref:`tt start ` command. + The replica should catch up with the master by retrieving all the master's tuples. + +4. (Optional) If you're reseeding a replica after a replication conflict, you also need to :ref:`restart replication `. diff --git a/doc/book/admin/security.rst b/doc/admin/security.rst similarity index 100% rename from doc/book/admin/security.rst rename to doc/admin/security.rst diff --git a/doc/book/admin/server_introspection.rst b/doc/admin/server_introspection.rst similarity index 99% rename from doc/book/admin/server_introspection.rst rename to doc/admin/server_introspection.rst index 6c38d98a57..b74f853fc4 100644 --- a/doc/book/admin/server_introspection.rst +++ b/doc/admin/server_introspection.rst @@ -79,8 +79,6 @@ To check the instance status, run: .. code-block:: console $ tt status my_app - INSTANCE STATUS PID - my_app RUNNING 67172 $ # - OR - diff --git a/doc/book/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst similarity index 97% rename from doc/book/admin/troubleshoot.rst rename to doc/admin/troubleshoot.rst index a084f93ab5..ec1ec63cc2 100644 --- a/doc/book/admin/troubleshoot.rst +++ b/doc/admin/troubleshoot.rst @@ -249,22 +249,17 @@ error message like **Solution** -Restart replication with the following commands (at each master instance): +This issue can be fixed in two ways: -.. code-block:: console +- Manually: :ref:`reseed ` one master from another by removing write-ahead logs and snapshots. +- Programmatically: set up a :ref:`conflict resolution trigger `. - $ # attaching to a Tarantool instance - $ tt connect +.. NOTE:: -.. code-block:: tarantoolsession + If one of the instances must be isolated during troubleshooting, it can be put to the :ref:`isolated mode <_configuration_reference_isolated_mode>`. - -- restarting replication - tarantool> original_value = box.cfg.replication - tarantool> box.cfg{replication={}} - tarantool> box.cfg{replication=original_value} +Then, restart replication as described in :ref:`Restarting replication `. -We also recommend using text primary keys or setting up -:ref:`master-slave replication `. .. _admin-troubleshoot-slow-tarantool: diff --git a/doc/book/admin/upgrades.rst b/doc/admin/upgrades.rst similarity index 89% rename from doc/book/admin/upgrades.rst rename to doc/admin/upgrades.rst index 08ca65e40a..43b462b47b 100644 --- a/doc/book/admin/upgrades.rst +++ b/doc/admin/upgrades.rst @@ -3,6 +3,10 @@ Upgrades ======== +.. important:: + + This section contains instructions for upgrading Tarantool clusters to versions up to 2.11.x. + This section describes the general upgrade process for Tarantool. There are two main upgrade scenarios for different use cases: diff --git a/doc/book/admin/upgrades/1.6-1.10.rst b/doc/admin/upgrades/1.6-1.10.rst similarity index 100% rename from doc/book/admin/upgrades/1.6-1.10.rst rename to doc/admin/upgrades/1.6-1.10.rst diff --git a/doc/book/admin/upgrades/1.6-2.0-downtime.rst b/doc/admin/upgrades/1.6-2.0-downtime.rst similarity index 100% rename from doc/book/admin/upgrades/1.6-2.0-downtime.rst rename to doc/admin/upgrades/1.6-2.0-downtime.rst diff --git a/doc/book/admin/upgrades/2.10.1.rst b/doc/admin/upgrades/2.10.1.rst similarity index 100% rename from doc/book/admin/upgrades/2.10.1.rst rename to doc/admin/upgrades/2.10.1.rst diff --git a/doc/book/admin/upgrades/2.10.4.rst b/doc/admin/upgrades/2.10.4.rst similarity index 100% rename from doc/book/admin/upgrades/2.10.4.rst rename to doc/admin/upgrades/2.10.4.rst diff --git a/doc/book/admin/upgrades/2.11.0.rst b/doc/admin/upgrades/2.11.0.rst similarity index 100% rename from doc/book/admin/upgrades/2.11.0.rst rename to doc/admin/upgrades/2.11.0.rst diff --git a/doc/book/admin/upgrades/upgrade_cluster.rst b/doc/admin/upgrades/upgrade_cluster.rst similarity index 96% rename from doc/book/admin/upgrades/upgrade_cluster.rst rename to doc/admin/upgrades/upgrade_cluster.rst index 7444cfd63a..3185e60a6d 100644 --- a/doc/book/admin/upgrades/upgrade_cluster.rst +++ b/doc/admin/upgrades/upgrade_cluster.rst @@ -98,11 +98,11 @@ Upgrading storages Before upgrading **storage** instances: -* Disable :doc:`Cartridge failover `: run +* Disable Cartridge failover: run .. code-block:: bash - cartridge failover disable + tt cartridge failover disable or use the Cartridge web interface (**Cluster** tab, **Failover: ** button). @@ -112,8 +112,7 @@ Before upgrading **storage** instances: tarantool> vshard.storage.rebalancer_disable() -* Make sure that the Cartridge ``upgrade_schema`` :doc:`option ` - is ``false``. +* Make sure that the Cartridge ``upgrade_schema`` option is ``false``. .. include:: ../_includes/upgrade_storages.rst @@ -130,11 +129,11 @@ Before upgrading **storage** instances: Once you complete the steps, enable failover or rebalancer back: -* Enable :doc:`Cartridge failover `: run +* Enable Cartridge failover: run .. code-block:: bash - cartridge failover set [mode] + tt cartridge failover set [mode] or use the Cartridge web interface (**Cluster** tab, **Failover: Disabled** button). diff --git a/doc/book/admin/upgrades/upgrade_standalone.rst b/doc/admin/upgrades/upgrade_standalone.rst similarity index 100% rename from doc/book/admin/upgrades/upgrade_standalone.rst rename to doc/admin/upgrades/upgrade_standalone.rst diff --git a/doc/alternate_build_master.rst b/doc/alternate_build_master.rst index 6effb4edc0..7ab2f43125 100644 --- a/doc/alternate_build_master.rst +++ b/doc/alternate_build_master.rst @@ -11,13 +11,10 @@ overview_index getting_started/index - how-to/index - concepts/index - CRUD operations - book/cartridge/index - book/admin/index - book/connectors - enterprise/index + platform/index + tooling/index + admin/index + connector/index reference/index contributing/index release/index diff --git a/doc/book/admin/access_control.rst b/doc/book/admin/access_control.rst deleted file mode 100644 index 18f5d82219..0000000000 --- a/doc/book/admin/access_control.rst +++ /dev/null @@ -1,377 +0,0 @@ -.. _authentication: - -================================================================================ -Access control -================================================================================ - -This section explains how Tarantool makes it possible for administrators -to prevent unauthorized access to the database and to certain functions. - -Briefly: - -* There is a method to guarantee with password checks that users really are - who they say they are (“authentication”). - -* There is a :ref:`_user ` system space, where usernames and - password-hashes are stored. - -* There are functions for saying that certain users are allowed to do certain - things (“privileges”). - -* There is a :ref:`_priv ` system space, where privileges are - stored. Whenever a user tries to do an operation, there is a check whether - the user has the privilege to do the operation (“access control”). - -Details follow. - -.. _authentication-users: - --------------------------------------------------------------------------------- -Users --------------------------------------------------------------------------------- - -There is a **current user** for any program working with Tarantool, -local or remote. -If a remote connection is using a :ref:`binary port `, -the current user, by default, is '**guest**'. -If the connection is using an :ref:`admin-console port `, -the current user is '**admin**'. -When executing a :ref:`Lua initialization script `, -the current user is also ‘**admin**’. - -The current user name can be found with -:doc:`/reference/reference_lua/box_session/user`. - -The current user can be changed: - -* For a binary port connection -- with the - :ref:`AUTH protocol command `, supported - by most clients; - -* For an admin-console connection and in a Lua initialization script -- - with :doc:`/reference/reference_lua/box_session/su`; - -* For a binary-port connection invoking a stored function with the CALL command -- - if the :doc:`SETUID ` - property is enabled for the function, - Tarantool temporarily replaces the current user with the - function’s creator, with all the creator's privileges, during function execution. - -.. _authentication-passwords: - --------------------------------------------------------------------------------- -Passwords --------------------------------------------------------------------------------- - -Each user (except 'guest') may have a **password**. -The password is any alphanumeric string. - -Tarantool passwords are stored in the :ref:`_user ` -system space with a -`cryptographic hash function `_ -so that, if the password is ‘x’, the stored hash-password is a long string -like ‘lL3OvhkIPOKh+Vn9Avlkx69M/Ck=‘. -Tarantool supports two protocols for authenticating users: - -* `CHAP `_ with ``SHA-1`` hashing - - In this case, password hashes are stored in the ``_user`` space `unsalted `_. - If an attacker gains access to the database, they may crack a password using, for example, a `rainbow table `_. - -* `PAP `_ with ``SHA256`` hashing (Enterprise Edition) - - For PAP, a password is salted with a user-unique salt before saving it in the ``_user`` space. - This keeps the database protected from cracking using a rainbow table. - Note that PAP sends a password as plain text, so you need to configure SSL/TLS for a connection. - -There are two functions for managing passwords in Tarantool: - -* :doc:`/reference/reference_lua/box_schema/user_passwd` allows you to change a user's password. - -* :doc:`/reference/reference_lua/box_schema/user_password` returns a hash of a user's password. - -Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`Access control ` section. - - - -.. _authentication-owners_privileges: - --------------------------------------------------------------------------------- -Owners and privileges --------------------------------------------------------------------------------- - -Tarantool has one database. It may be called "box.schema" or "universe". -The database contains database objects, including -spaces, indexes, users, roles, sequences, and functions. - -The **owner** of a database object is the user who created it. -The owner of the database itself, and the owner of objects that -are created initially (the system spaces and the default users) -is '**admin**'. - -Owners automatically have **privileges** for what they create. -They can share these privileges with other users or with roles, -using :doc:`/reference/reference_lua/box_schema/user_grant` requests. -The following privileges can be granted: - -* 'read', e.g. allow select from a space -* 'write', e.g. allow update on a space -* 'execute', e.g. allow call of a function, or (less commonly) allow use of a role -* 'create', e.g. allow - :doc:`box.schema.space.create ` - (access to certain system spaces is also necessary) -* 'alter', e.g. allow - :doc:`box.space.x.index.y:alter ` - (access to certain system spaces is also necessary) -* 'drop', e.g. allow - :doc:`box.sequence.x:drop ` - (access to certain system spaces is also necessary) -* 'usage', e.g. whether any action is allowable regardless of other - privileges (sometimes revoking 'usage' is a convenient way to - block a user temporarily without dropping the user) -* 'session', e.g. whether the user can 'connect'. - -To **create** objects, users need the 'create' privilege and -at least 'read' and 'write' privileges -on the system space with a similar name (for example, on the -:ref:`_space ` if the user needs to create spaces). - -To **access** objects, users need an appropriate privilege -on the object (for example, the 'execute' privilege on function F -if the users need to execute function F). See below some -:ref:`examples for granting specific privileges ` -that a grantor -- that is, 'admin' or the object creator -- can make. - -To drop an object, a user must be an 'admin' or have the 'super' role. -Some objects may also be dropped by their creators. -As the owner of the entire database, any 'admin' can drop any object, -including other users. - -To grant privileges to a user, the object owner says -:doc:`/reference/reference_lua/box_schema/user_grant`. -To revoke privileges from a user, the object owner says -:doc:`/reference/reference_lua/box_schema/user_revoke`. -In either case, there are up to five parameters: - -.. code-block:: lua - - (user-name, privilege, object-type [, object-name [, options]]) - -* ``user-name`` is the user (or role) that will receive or lose the privilege; -* ``privilege`` is any of 'read', 'write', 'execute', 'create', 'alter', 'drop', - 'usage', or 'session' (or a comma-separated list); -* ``object-type`` is any of 'space', 'index', - 'sequence', 'function', 'user', 'role', or 'universe'; -* ``object-name`` is what the privilege is for - (omitted if ``object-type`` is 'universe') - (may be omitted or ``nil`` if the intent is to grant for all objects of the same type); -* ``options`` is a list inside braces, for example ``{if_not_exists=true|false}`` - (usually omitted because the default is acceptable). - - All updates of user privileges are reflected immediately in the existing sessions - and objects, e.g. functions. - -**Example for granting many privileges at once** - -In this example an 'admin' user grants many privileges on -many objects to user 'U', using a single request. - -.. code-block:: lua - - box.schema.user.grant('U','read,write,execute,create,drop','universe') - -.. _authentication-owners_privileges-examples-specific: - -**Examples for granting privileges for specific operations** - -In these examples an administrator grants strictly -the minimal privileges necessary for particular operations, -to user 'U'. - -.. code-block:: lua - - -- So that 'U' can create spaces: - box.schema.user.grant('U','create','space') - box.schema.user.grant('U','write', 'space', '_schema') - box.schema.user.grant('U','write', 'space', '_space') - -- So that 'U' can create indexes on space T - box.schema.user.grant('U','create,read','space','T') - box.schema.user.grant('U','read,write','space','_space_sequence') - box.schema.user.grant('U','write', 'space', '_index') - -- So that 'U' can alter indexes on space T (assuming 'U' did not create the index) - box.schema.user.grant('U','alter','space','T') - box.schema.user.grant('U','read','space','_space') - box.schema.user.grant('U','read','space','_index') - box.schema.user.grant('U','read','space','_space_sequence') - box.schema.user.grant('U','write','space','_index') - -- So that 'U' can alter indexes on space T (assuming 'U' created the index) - box.schema.user.grant('U','read','space','_space_sequence') - box.schema.user.grant('U','read,write','space','_index') - -- So that 'U' can create users: - box.schema.user.grant('U','create','user') - box.schema.user.grant('U', 'read,write', 'space', '_user') - box.schema.user.grant('U', 'write', 'space', '_priv') - -- So that 'U' can create roles: - box.schema.user.grant('U','create','role') - box.schema.user.grant('U', 'read,write', 'space', '_user') - box.schema.user.grant('U', 'write', 'space', '_priv') - -- So that 'U' can create sequence generators: - box.schema.user.grant('U','create','sequence') - box.schema.user.grant('U', 'read,write', 'space', '_sequence') - -- So that 'U' can create functions: - box.schema.user.grant('U','create','function') - box.schema.user.grant('U','read,write','space','_func') - -- So that 'U' can create any object of any type - box.schema.user.grant('U','read,write,create','universe') - -- So that 'U' can grant access on objects that 'U' created - box.schema.user.grant('U','write','space','_priv') - -- So that 'U' can select or get from a space named 'T' - box.schema.user.grant('U','read','space','T') - -- So that 'U' can update or insert or delete or truncate a space named 'T' - box.schema.user.grant('U','write','space','T') - -- So that 'U' can execute a function named 'F' - box.schema.user.grant('U','execute','function','F') - -- So that 'U' can use the "S:next()" function with a sequence named S - box.schema.user.grant('U','read,write','sequence','S') - -- So that 'U' can use the "S:set()" or "S:reset() function with a sequence named S - box.schema.user.grant('U','write','sequence','S') - -- So that 'U' can drop a sequence (assuming 'U' did not create it) - box.schema.user.grant('U','drop','sequence') - box.schema.user.grant('U','write','space','_sequence_data') - box.schema.user.grant('U','write','space','_sequence') - -- So that 'U' can drop a function (assuming 'U' did not create it) - box.schema.user.grant('U','drop','function') - box.schema.user.grant('U','write','space','_func') - -- So that 'U' can drop a space that has some associated objects - box.schema.user.grant('U','create,drop','space') - box.schema.user.grant('U','write','space','_schema') - box.schema.user.grant('U','write','space','_space') - box.schema.user.grant('U','write','space','_space_sequence') - box.schema.user.grant('U','read','space','_trigger') - box.schema.user.grant('U','read','space','_fk_constraint') - box.schema.user.grant('U','read','space','_ck_constraint') - box.schema.user.grant('U','read','space','_func_index') - -- So that 'U' can drop any space (ignore if the privilege exists already) - box.schema.user.grant('U','drop','space',nil,{if_not_exists=true}) - -**Example for creating users and objects then granting privileges** - -Here a Lua function is created that will be executed under the user ID of its -creator, even if called by another user. - -First, the two spaces ('u' and 'i') are created, and a no-password user ('internal') -is granted full access to them. Then a ('read_and_modify') is defined and the -no-password user becomes this function's creator. Finally, another user -('public_user') is granted access to execute Lua functions created by the no-password user. - -.. code-block:: lua - - box.schema.space.create('u') - box.schema.space.create('i') - box.space.u:create_index('pk') - box.space.i:create_index('pk') - - box.schema.user.create('internal') - - box.schema.user.grant('internal', 'read,write', 'space', 'u') - box.schema.user.grant('internal', 'read,write', 'space', 'i') - box.schema.user.grant('internal', 'create', 'universe') - box.schema.user.grant('internal', 'read,write', 'space', '_func') - - function read_and_modify(key) - local u = box.space.u - local i = box.space.i - local fiber = require('fiber') - local t = u:get{key} - if t ~= nil then - u:put{key, box.session.uid()} - i:put{key, fiber.time()} - end - end - - box.session.su('internal') - box.schema.func.create('read_and_modify', {setuid= true}) - box.session.su('admin') - box.schema.user.create('public_user', {password = 'secret'}) - box.schema.user.grant('public_user', 'execute', 'function', 'read_and_modify') - -.. _authentication-roles: - --------------------------------------------------------------------------------- -Roles --------------------------------------------------------------------------------- - -A **role** is a container for privileges which can be granted to regular users. -Instead of granting or revoking individual privileges, you can put all the -privileges in a role and then grant or revoke the role. - -Role information is stored in the :ref:`_user ` space, but -the third field in the tuple -- the type field -- is ‘role’ rather than ‘user’. - -An important feature in role management is that roles can be **nested**. -For example, role R1 can be granted a privileged "role R2", so users with the -role R1 will subsequently get all privileges from both roles R1 and R2. -In other words, a user gets all the privileges granted to a user’s roles, -directly or indirectly. - -There are actually two ways to grant or revoke a role: -:samp:`box.schema.user.grant-or-revoke({user-name-or-role-name},'execute', 'role',{role-name}...)` -or -:samp:`box.schema.user.grant-or-revoke({user-name-or-role-name},{role-name}...)`. -The second way is preferable. - -The 'usage' and 'session' privileges cannot be granted to roles. - -**Example** - -.. code-block:: lua - - -- This example will work for a user with many privileges, such as 'admin' - -- or a user with the pre-defined 'super' role - -- Create space T with a primary index - box.schema.space.create('T') - box.space.T:create_index('primary', {}) - -- Create the user U1 so that later the current user can be changed to U1 - box.schema.user.create('U1') - -- Create two roles, R1 and R2 - box.schema.role.create('R1') - box.schema.role.create('R2') - -- Grant role R2 to role R1 and role R1 to user U1 (order doesn't matter) - -- There are two ways to grant a role; here the shorter way is used - box.schema.role.grant('R1', 'R2') - box.schema.user.grant('U1', 'R1') - -- Grant read/write privileges for space T to role R2 - -- (but not to role R1, and not to user U1) - box.schema.role.grant('R2', 'read,write', 'space', 'T') - -- Change the current user to user U1 - box.session.su('U1') - -- An insertion to space T will now succeed because (due to nested roles) - -- user U1 has write privilege on space T - box.space.T:insert{1} - -More details are to be found in -:doc:`/reference/reference_lua/box_schema/user_grant` and -:doc:`/reference/reference_lua/box_schema/role_grant` in -the built-in modules reference. - -.. _authentication-sessions: - --------------------------------------------------------------------------------- -Sessions and security --------------------------------------------------------------------------------- - -A **session** is the state of a connection to Tarantool. It contains: - -* An integer ID identifying the connection, -* the :ref:`current user ` associated with the connection, -* text description of the connected peer, and -* session local state, such as Lua variables and functions. - -In Tarantool, a single session can execute multiple concurrent transactions. -Each transaction is identified by a unique integer ID, which can be queried -at start of the transaction using :doc:`/reference/reference_lua/box_session/sync`. - -.. NOTE:: - - To track all connects and disconnects, you can use - :ref:`connection and authentication triggers `. diff --git a/doc/book/admin/disaster_recovery.rst b/doc/book/admin/disaster_recovery.rst deleted file mode 100644 index 0a696ca9cf..0000000000 --- a/doc/book/admin/disaster_recovery.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. _admin-disaster_recovery: - -================================================================================ -Disaster recovery -================================================================================ - -The minimal fault-tolerant Tarantool configuration would be a -:ref:`replication cluster` -that includes a master and a replica, or two masters. - -The basic recommendation is to configure all Tarantool instances in a cluster to -create :ref:`snapshot files ` at a regular basis. - -Here follow action plans for typical crash scenarios. - -.. _admin-disaster_recovery-master_replica: - --------------------------------------------------------------------------------- -Master-replica --------------------------------------------------------------------------------- - -Configuration: One master and one replica. - -Problem: The master has crashed. - -Your actions: - -1. Ensure the master is stopped for good. For example, log in to the master - machine and use ``systemctl stop tarantool@``. - -2. Switch the replica to master mode by setting - :ref:`box.cfg.read_only ` parameter to *false* and let - the load be handled by the replica (effective master). - -3. Set up a replacement for the crashed master on a spare host, with - :ref:`replication ` parameter set to replica - (effective master), so it begins to catch up with the new master’s state. - The new instance should have :ref:`box.cfg.read_only ` - parameter set to *true*. - -You lose the few transactions in the master -:ref:`write ahead log file `, which it may have not -transferred to the replica before crash. If you were able to salvage the master -.xlog file, you may be able to recover these. In order to do it: - -1. Find out the position of the crashed master, as reflected on the new master. - - a. Find out instance UUID from the crashed master :ref:`xlog `: - - .. code-block:: console - - $ head -5 *.xlog | grep Instance - Instance: ed607cad-8b6d-48d8-ba0b-dae371b79155 - - b. On the new master, use the UUID to find the position: - - .. code-block:: tarantoolsession - - tarantool> box.info.vclock[box.space._cluster.index.uuid:select{'ed607cad-8b6d-48d8-ba0b-dae371b79155'}[1][1]] - --- - - 23425 - <...> - -2. Play the records from the crashed .xlog to the new master, starting from the - new master position: - - a. Issue this request locally at the new master's machine to find out - instance ID of the new master: - - .. code-block:: tarantoolsession - - tarantool> box.space._cluster:select{} - --- - - - [1, '88580b5c-4474-43ab-bd2b-2409a9af80d2'] - ... - - b. Play the records to the new master: - - .. code-block:: console - - $ tt play --from 23425 --replica 1 - -.. _admin-disaster_recovery-master_master: - --------------------------------------------------------------------------------- -Master-master --------------------------------------------------------------------------------- - -Configuration: Two masters. - -Problem: Master#1 has crashed. - -Your actions: - -1. Let the load be handled by master#2 (effective master) alone. - -2. Follow the same steps as in the -:ref:`master-replica ` recovery scenario -to create a new master and salvage lost data. - -.. _admin-disaster_recovery-data_loss: - --------------------------------------------------------------------------------- -Data loss --------------------------------------------------------------------------------- - -Configuration: Master-master or master-replica. - -Problem: Data was deleted at one master and this data loss was propagated to the -other node (master or replica). - -The following steps are applicable only to data in memtx storage engine. -Your actions: - -1. Put all nodes in :ref:`read-only mode ` and disable - deletion of expired checkpoints with :doc:`/reference/reference_lua/box_backup/start`. - This will prevent the Tarantool garbage collector from removing files - made with older checkpoints until :doc:`/reference/reference_lua/box_backup/stop` is called. - -2. Get the latest valid :ref:`.snap file ` and - use ``tt cat`` command to calculate at which lsn the data loss occurred. - -3. Start a new instance (instance#1) and use ``tt play`` command to - play to it the contents of .snap/.xlog files up to the calculated lsn. - -4. Bootstrap a new replica from the recovered master (instance#1). diff --git a/doc/book/admin/index.rst b/doc/book/admin/index.rst deleted file mode 100644 index 0396a88f28..0000000000 --- a/doc/book/admin/index.rst +++ /dev/null @@ -1,44 +0,0 @@ -:noindex: -:fullwidth: - -.. _admin: - -Administration -============== - -Tarantool is designed to have multiple running instances on the same host. - -Here we show how to administer Tarantool instances using any of the following -utilities: - -* ``systemd`` native utilities, or -* :ref:`tt `, a command-line utility for managing Tarantool-based applications. - -.. NOTE:: - - * Unlike the rest of this manual, here we use system-wide paths. - * Console examples here are for Fedora. - -This chapter includes the following sections: - -.. toctree:: - :maxdepth: 2 - :numbered: 0 - - instance_config - start_stop_instance - modules - logs - security - access_control - vshard_admin - replication/index - server_introspection - daemon_supervision - disaster_recovery - backups - upgrades - os_notes - bug_reports - troubleshoot - ../monitoring/index diff --git a/doc/book/admin/instance_config.rst b/doc/book/admin/instance_config.rst deleted file mode 100644 index 2e4df21b38..0000000000 --- a/doc/book/admin/instance_config.rst +++ /dev/null @@ -1,177 +0,0 @@ -.. _admin-instance_config: - -Instance configuration -====================== - -For each Tarantool instance, you need two files: - -* [Optional] An :ref:`application file ` with - instance-specific logic. Put this file into the ``/usr/share/tarantool/`` - directory. - - For example, ``/usr/share/tarantool/my_app.lua`` (here we implement it as a - :ref:`Lua module ` that bootstraps the database and - exports ``start()`` function for API calls): - - .. code-block:: lua - - local function start() - box.schema.space.create("somedata") - box.space.somedata:create_index("primary") - <...> - end - - return { - start = start; - } - -* An :ref:`instance file ` with - instance-specific initialization logic and parameters. Put this file, or a - symlink to it, into the **instance directory** - (see ``instances_enabled`` parameter in :ref:`tt configuration file `). - - For example, ``/etc/tarantool/instances.enabled/my_app.lua`` (here we load - ``my_app.lua`` module and make a call to ``start()`` function from that - module): - - .. code-block:: lua - - #!/usr/bin/env tarantool - - box.cfg { - listen = 3301; - } - - -- load my_app module and call start() function - -- with some app options controlled by sysadmins - local m = require('my_app').start({...}) - -.. _admin-instance_file: - -Instance file -------------- - -After this short introduction, you may wonder what an instance file is, what it -is for, and how ``tt`` uses it. After all, Tarantool is an application -server, so why not start the application stored in ``/usr/share/tarantool`` -directly? - -A typical Tarantool application is not a script, but a daemon running in -background mode and processing requests, usually sent to it over a TCP/IP -socket. This daemon needs to be started automatically when the operating system -starts, and managed with the operating system standard tools for service -management -- such as ``systemd`` or ``init.d``. To serve this very purpose, we -created **instance files**. - -You can have more than one instance file. For example, a single application in -``/usr/share/tarantool`` can run in multiple instances, each of them having its -own instance file. Or you can have multiple applications in -``/usr/share/tarantool`` -- again, each of them having its own instance file. - -An instance file is typically created by a system administrator. An application -file is often provided by a developer, in a Lua rock or an rpm/deb package. - -An instance file is designed to not differ in any way from a Lua application. -It must, however, configure the database, i.e. contain a call to -:doc:`box.cfg{} ` somewhere in it, because it’s the -only way to turn a Tarantool script into a background process, and -``tt`` is a tool to manage background processes. Other than that, an -instance file may contain arbitrary Lua code, and, in theory, even include the -entire application business logic in it. We, however, do not recommend this, -since it clutters the instance file and leads to unnecessary copy-paste when -you need to run multiple instances of an application. - -.. _admin-tt-preload: - -Preloading Lua scripts and modules ----------------------------------- - -Tarantool supports loading and running chunks of Lua code before the loading instance file. -To load or run Lua code immediately upon Tarantool startup, specify the ``TT_PRELOAD`` -environment variable. Its value can be either a path to a Lua script or a Lua module name: - -* To run the Lua script ``script.lua`` from the ``preload/path/`` directory inside - the working directory in Tarantool before ``main.lua``, set ``TT_PRELOAD`` as follows: - - .. code-block:: console - - $ TT_PRELOAD=/preload/path/script.lua tarantool main.lua - - Tarantool runs the ``script.lua`` code, waits for it to complete, and - then starts running ``main.lua``. - -* To load the ``preload.module`` into the Tarantool Lua interpreter - executing ``main.lua``, set ``TT_PRELOAD`` as follows: - - .. code-block:: console - - $ TT_PRELOAD=preload.module tarantool main.lua - - Tarantool loads the ``preload.module`` code into the interpreter and - starts running ``main.lua`` as if its first statement was ``require('preload.module')``. - - .. warning:: - - ``TT_PRELOAD`` values that end with ``.lua`` are considered scripts, - so avoid module names with this ending. - -To load several scripts or modules, pass them in a single quoted string, separated -by semicolons: - -.. code-block:: console - - $ TT_PRELOAD="/preload/path/script.lua;preload.module" tarantool main.lua - -In the preload script, the three dots (``...``) value contains the module name -if you're preloading a module or the path to the script if you're running a script. - -The :ref:`arg ` value from the main script is visible in -the preload script or module. - -For example, when preloading this script: - -.. code-block:: lua - - -- preload.lua -- - print("Preloading:") - print("... arg is:", ...) - print("Passed args:", arg[1], arg[2]) - -You get the following output: - -.. code-block:: console - - $ TT_PRELOAD=preload.lua tarantool main.lua arg1 arg2 - Preloading: - ... arg is: preload.lua - Passed args: arg1 arg2 - 'strip_core' is set but unsupported - ... main/103/main.lua I> Tarantool 2.11.0-0-g247a9a4 Darwin-x86_64-Release - ... main/103/main.lua I> log level 5 - ... main/103/main.lua I> wal/engine cleanup is paused - < ... > - -If an error happens during the execution of the preload script or module, Tarantool -reports the problem and exits. - -.. _admin-tt_config_file: - -tt configuration file ---------------------- - -While instance files contain instance configuration, the :ref:`tt ` configuration file -contains the configuration that ``tt`` uses to set up the application environment. -This includes the path to instance files, various working directories, and other -parameters that connect the application to the system. - -To create a default ``tt`` configuration, run ``tt init``. This creates a ``tt.yaml`` -configuration file. Its location depends on the :ref:`tt launch mode ` -(system or local). - -Some ``tt`` configuration parameters are similar to those used by -:doc:`box.cfg{} `, for example, ``memxt_dir`` -or ``wal_dir``. Other parameters define the ``tt`` environment, for example, -paths to installation files used by ``tt`` or to connected :ref:`external modules `. - -Find the detailed information about the ``tt`` configuration parameters and launch modes -on the :ref:`tt configuration page `. diff --git a/doc/book/admin/logs.rst b/doc/book/admin/logs.rst deleted file mode 100644 index 176948fa77..0000000000 --- a/doc/book/admin/logs.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _admin-logs: - -Logs -==== - -Each Tarantool instance logs important events to its own log file ``.log``. -For instances started with :ref:`tt `, the log location is defined by -the ``log_dir`` parameter in the :ref:`tt configuration `. -By default, it's ``/var/log/tarantool`` in the ``tt`` :ref:`system mode `, -and the ``var/log/`` subdirectory of the ``tt`` working directory in the :ref:`local mode `. -In the specified location, ``tt`` creates separate directories for each instance's logs. - -To check how logging works, write something to the log using the :ref:`log ` module: - -.. code-block:: console - - $ tt connect my_app - • Connecting to the instance... - • Connected to /var/run/tarantool/my_app.control - - /var/run/tarantool/my_app.control> require('log').info("Hello for the manual readers") - -Then check the logs: - -.. code-block:: console - - $ tail /var/log/tarantool/my_app.log - 2023-09-12 18:13:00.396 [67173] main/111/guard of feedback_daemon/box.feedback_daemon V> metrics_collector restarted - 2023-09-12 18:13:00.396 [67173] main/103/-/box.feedback_daemon V> feedback_daemon started - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(14) = 0x1090077b4 - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(26) = 0x1090077ec - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007824 - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(24) = 0x10900785c - 2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007894 - 2023-09-12 18:13:00.396 [67173] main/106/checkpoint_daemon I> scheduled next checkpoint for Tue Sep 12 19:44:34 2023 - 2023-09-12 18:13:00.396 [67173] main I> entering the event loop - 2023-09-12 18:13:11.656 [67173] main/114/console/unix/:/tarantool I> Hello for the manual readers - -.. _admin-logs-rotation: - -Log rotation ------------- - -When :ref:`logging to a file `, the system administrator must ensure logs are -rotated timely and do not take up all the available disk space. -To prevent log files from growing infinitely, ``tt`` automatically rotates instance -logs. The following ``tt`` configuration parameters define the log rotation: -``log_maxsize`` (in megabytes) and ``log_maxage`` (in days). When any of these -limits is reached, the log is rotated. -Additionally, there is the ``log_maxbackups`` parameter (the number of stored log -files for an instance), which enables automatic removal of old log files. - -.. code-block:: yaml - - # tt.yaml - tt: - app: - log_maxsize: 100 - log_maxage: 3 - log_maxbackups: 50 - # ... - -There is also the :ref:`tt logrotate ` command that performs log -rotation on demand. - -.. code-block:: bash - - tt logrotate my_app - -To learn about log rotation in the deprecated ``tarantoolctl`` utility, -check its :ref:`documentation `. - - -.. _admin-logs-formats: - -Log formats ------------ - -Tarantool can write its logs to a log file, to ``syslog``, or to a specified program -through a pipe. - -File is the default log format for ``tt``. To send logs to a pipe or ``syslog``, -specify the :ref:`box.cfg.log ` parameter, for example: - -.. code-block:: lua - - box.cfg{log = '| cronolog tarantool.log'} - -- or - box.cfg{log = 'syslog:identity=tarantool,facility=user'} - -In such configurations, log rotation is usually handled by the external program -used for logging. \ No newline at end of file diff --git a/doc/book/admin/replication/index.rst b/doc/book/admin/replication/index.rst deleted file mode 100644 index f8a8a409fc..0000000000 --- a/doc/book/admin/replication/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Replication administration -========================== - -.. toctree:: - :maxdepth: 2 - - repl_monitoring - repl_recover - repl_reseed - repl_problem_solving diff --git a/doc/book/admin/replication/repl_monitoring.rst b/doc/book/admin/replication/repl_monitoring.rst deleted file mode 100644 index 9170e3142a..0000000000 --- a/doc/book/admin/replication/repl_monitoring.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _replication-monitoring: - -Monitoring a replica set -======================== - -To learn what instances belong to the replica set and obtain statistics for all -these instances, issue a :doc:`/reference/reference_lua/box_info/replication` request: - -.. code-block:: tarantoolsession - - tarantool> box.info.replication - --- - replication: - 1: - id: 1 - uuid: b8a7db60-745f-41b3-bf68-5fcce7a1e019 - lsn: 88 - 2: - id: 2 - uuid: cd3c7da2-a638-4c5d-ae63-e7767c3a6896 - lsn: 31 - upstream: - status: follow - idle: 43.187747001648 - peer: replicator@192.168.0.102:3301 - lag: 0 - downstream: - vclock: {1: 31} - 3: - id: 3 - uuid: e38ef895-5804-43b9-81ac-9f2cd872b9c4 - lsn: 54 - upstream: - status: follow - idle: 43.187621831894 - peer: replicator@192.168.0.103:3301 - lag: 2 - downstream: - vclock: {1: 54} - ... - -This report is for a master-master replica set of three instances, each having -its own instance id, UUID and log sequence number. - -.. image:: /concepts/replication/images/mm-3m-mesh.svg - :align: center - -The request was issued at master #1, and the reply includes statistics for the -other two masters, given in regard to master #1. - -The primary indicators of replication health are: - -.. _heartbeat: - -* :ref:`idle `: the time (in seconds) since - the instance received the last event from a master. - - If the master has no updates to send to the replicas, it sends heartbeat messages - every :ref:`replication_timeout ` seconds. The master - is programmed to disconnect if it does not see acknowledgments of the heartbeat messages - within ``replication_timeout`` * 4 seconds. - - Therefore, in a healthy replication setup, ``idle`` should never exceed - ``replication_timeout``: if it does, either the replication is lagging - seriously behind, because the master is running ahead of the replica, or the - network link between the instances is down. - -* :ref:`lag `: the time difference between - the local time at the instance, recorded when the event was received, and the - local time at another master recorded when the event was written to the - :ref:`write ahead log ` on that master. - - Since the ``lag`` calculation uses the operating system clocks from two different - machines, do not be surprised if it’s negative: a time drift may lead to the - remote master clock being consistently behind the local instance's clock. - - For multi-master configurations, ``lag`` is the maximal lag. - -For better understanding, see the following diagram illustrating the ``upstream`` and ``downstream`` connections within the replica set of three instances: - -.. image:: /concepts/replication/images/replication.svg - :align: left diff --git a/doc/book/admin/replication/repl_recover.rst b/doc/book/admin/replication/repl_recover.rst deleted file mode 100644 index 5a03219930..0000000000 --- a/doc/book/admin/replication/repl_recover.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _replication-recover: - -================================================================================ -Recovering from a degraded state -================================================================================ - -"Degraded state" is a situation when the master becomes unavailable -- due to -hardware or network failure, or due to a programming bug. - -.. image:: mr-degraded.svg - :align: center - -In a master-replica set, if a master disappears, error messages appear on the -replicas stating that the connection is lost: - -.. code-block:: console - - $ # messages from a replica's log - 2017-06-14 16:23:10.993 [19153] main/105/applier/replicator@192.168.0. I> can't read row - 2017-06-14 16:23:10.993 [19153] main/105/applier/replicator@192.168.0. coio.cc:349 !> SystemError - unexpected EOF when reading from socket, called on fd 17, aka 192.168.0.101:57815, - peer of 192.168.0.101:3301: Broken pipe - 2017-06-14 16:23:10.993 [19153] main/105/applier/replicator@192.168.0. I> will retry every 1 second - 2017-06-14 16:23:10.993 [19153] relay/[::ffff:192.168.0.101]:/101/main I> the replica has closed its socket, exiting - 2017-06-14 16:23:10.993 [19153] relay/[::ffff:192.168.0.101]:/101/main C> exiting the relay loop - -... and the master's status is reported as "disconnected": - -.. code-block:: tarantoolsession - - # report from replica #1 - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: 70e8e9dc-e38d-4046-99e5-d25419267229 - lsn: 542 - upstream: - peer: replicator@192.168.0.101:3301 - lag: 0.00026607513427734 - status: disconnected - idle: 182.36929893494 - message: connect, called on fd 13, aka 192.168.0.101:58244 - 2: - id: 2 - uuid: fb252ac7-5c34-4459-84d0-54d248b8c87e - lsn: 0 - 3: - id: 3 - uuid: fd7681d8-255f-4237-b8bb-c4fb9d99024d - lsn: 0 - downstream: - vclock: {1: 542} - ... - -.. code-block:: tarantoolsession - - # report from replica #2 - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: 70e8e9dc-e38d-4046-99e5-d25419267229 - lsn: 542 - upstream: - peer: replicator@192.168.0.101:3301 - lag: 0.00027203559875488 - status: disconnected - idle: 186.76988101006 - message: connect, called on fd 13, aka 192.168.0.101:58253 - 2: - id: 2 - uuid: fb252ac7-5c34-4459-84d0-54d248b8c87e - lsn: 0 - upstream: - status: follow - idle: 186.76960110664 - peer: replicator@192.168.0.102:3301 - lag: 0.00020599365234375 - 3: - id: 3 - uuid: fd7681d8-255f-4237-b8bb-c4fb9d99024d - lsn: 0 - ... - -To declare that one of the replicas must now take over as a new master: - -1. Make sure that the old master is gone for good: - - * change network routing rules to avoid any more packets being delivered to - the master, or - * shut down the master instance, if you have access to the machine, or - * power off the container or the machine. - -2. Say ``box.cfg{read_only=false, listen=URI}`` on the replica, and - ``box.cfg{replication=URI}`` on the other replicas in the set. - -.. NOTE:: - - If there are updates on the old master that were not propagated before the - old master went down, - :ref:`re-apply them manually ` to the - new master using ``tt cat`` and ``tt play`` commands. - -There is no automatic way for a replica to detect that the master is gone -forever, since sources of failure and replication environments vary -significantly. So the detection of degraded state requires an external observer. diff --git a/doc/book/admin/replication/repl_reseed.rst b/doc/book/admin/replication/repl_reseed.rst deleted file mode 100644 index f725d8542f..0000000000 --- a/doc/book/admin/replication/repl_reseed.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _replication-reseed: - -================================================================================ -Reseeding a replica -================================================================================ - -If any of a replica's .xlog/.snap/.run files are corrupted or deleted, you can -"re-seed" the replica: - -1. Stop the replica and destroy all local database files (the ones with - extensions .xlog/.snap/.run/.inprogress). - -2. Delete the replica's record from the following locations: - - a. the ``replication`` parameter at all running instances in the replica set. - b. the ``box.space._cluster`` tuple on the master instance. - - See section :ref:`Removing instances ` for - details. - -3. Restart the replica with the same instance file to contact the master again. - The replica will then catch up with the master by retrieving all the master’s - tuples. - -.. NOTE:: - - Remember that this procedure works only if the master’s WAL files are - present. diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst deleted file mode 100644 index 759e16f784..0000000000 --- a/doc/book/admin/start_stop_instance.rst +++ /dev/null @@ -1,335 +0,0 @@ -.. _admin-start_stop_instance: - -Starting and stopping instances -=============================== - -To start a Tarantool instance from an :ref:`instance file ` -using the :ref:`tt ` utility: - -1. Place the instance file (for example, ``my_app.lua``) into ``/etc/tarantool/instances.enabled/``. - This is the default location where ``tt`` searches for instance files. - -2. Run ``tt start``: - - .. code-block:: console - - $ tt start - • Starting an instance [my_app]... - -In this case, ``tt`` starts an instance from any ``*.lua`` file it finds in ``/etc/tarantool/instances.enabled/``. - -Starting instances ------------------- - -All the instance files or directories placed in the ``instances_enabled`` directory -specified in :ref:`tt configuration ` are called *enabled instances*. -If there are several enabled instances, ``tt start`` starts a separate Tarantool -instance for each of them. - -Learn more about working with multiple Tarantool instances in -:ref:`Multi-instance applications `. - -To start a specific enabled instance, specify its name in the ``tt start`` argument: - -.. code-block:: console - - $ tt start my_app - • Starting an instance [my_app]... - -When starting an instance, ``tt`` uses its :ref:`configuration file ` -``tt.yaml`` to set up a :ref:`tt environment ` in which the instance runs. -The default ``tt`` configuration file is created automatically in ``/etc/tarantool/``. -Learn how to set up a ``tt`` environment in a directory of your choice in -:ref:`Running Tarantool locally `. - -After the instance has started and worked for some time, you can find its artifacts -in the directories specified in the ``tt`` configuration. These are the default -locations: - -* ``/var/log/tarantool/.log`` -- instance :ref:`logs `. -* ``/var/lib/tarantool//`` -- snapshots and write-ahead logs. -* ``/var/run/tarantool/.control`` -- a control socket. This is - a Unix socket with the Lua console attached to it. This file is used to connect - to the instance console. -* ``/var/run/tarantool/.pid`` -- a PID file that ``tt`` uses to - check the instance status and send control commands. - -Basic instance management -------------------------- - -.. note:: - - These commands can be called without an instance name. In this case, they are - executed for all enabled instances. - -``tt`` provides a set of commands for performing basic operations over instances: - -* ``tt check`` -- check the instance file for syntax errors: - - .. code-block:: console - - $ tt check my_app - • Result of check: syntax of file '/etc/tarantool/instances.enabled/my_app.lua' is OK - -* ``tt status`` -- check the instance status: - - .. code-block:: console - - $ tt status my_app - INSTANCE STATUS PID - my_app NOT RUNNING - -* ``tt restart`` -- restart the instance: - - .. code-block:: console - - $ tt restart my_app -y - • The Instance my_app (PID = 729) has been terminated. - • Starting an instance [my_app]... - - The ``-y`` option responds "yes" to the confirmation prompt automatically. - -* ``tt stop`` -- stop the instance: - - .. code-block:: console - - $ tt stop my_app - • The Instance my_app (PID = 639) has been terminated. - -* ``tt clean`` -- remove instance artifacts: logs, snapshots, and other files. - - .. code-block:: console - - $ tt clean my_app -f - • List of files to delete: - - • /var/log/tarantool/my_app.log - • /var/lib/tarantool/my_app/00000000000000000000.snap - • /var/lib/tarantool/my_app/00000000000000000000.xlog - - The ``-f`` option removes the files without confirmation. - -.. _admin-start_stop_instance-multi-instance: - -Multi-instance applications ---------------------------- - -Tarantool applications can include multiple instances that run different code. -A typical example is a cluster application that includes router and storage -instances. The ``tt`` utility enables managing such applications. -With a single ``tt`` call, you can: - -* start an application on multiple instances -* check the status of application instances -* connect to a specific instance of an application -* stop a specific instance of an application or all its instances - -Application layout -~~~~~~~~~~~~~~~~~~ - -To create a multi-instance application, prepare its layout -in a directory inside ``instances_enabled``. The directory name is used as -the application identifier. - -This directory should contain the following files: - -* The default instance file named ``init.lua``. This file is used for all - instances of the application unless there are specific instance files (see below). -* The instances configuration file ``instances.yml`` with instance names followed by colons: - - .. code-block:: yaml - - : - : - ... - - .. note:: - - Do not use the dot (``.``) and dash (``-``) characters in the instance names. - They are reserved for system use. - -* (Optional) Specific instances files. - These files should have names ``.init.lua``, where ```` - is the name specified in ``instances.yml``. - For example, if your application has separate source files for the ``router`` and ``storage`` - instances, place the router code in the ``router.init.lua`` file. - -For example, take a ``demo`` application that has three instances:``storage1``, -``storage2``, and ``router``. Storage instances share the same code, and ``router`` has its own. -The application directory ``demo`` inside ``instances_enabled`` must contain the following files: - -* ``instances.yml`` -- the instances configuration: - - .. code-block:: yaml - - storage1: - storage2: - router: - -* ``init.lua`` -- the code of ``storage1`` and ``storage2`` -* ``router.init.lua`` -- the code of ``router`` - - -Identifying instances in code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When the application is working, each instance has associated environment variables -``TARANTOOL_INSTANCE_NAME`` and ``TARANTOOL_APP_NAME``. You can use them in the application -code to identify the instance on which the code runs. - -To obtain the instance and application names, use the following code: - -.. code:: lua - - local inst_name = os.getenv('TARANTOOL_INSTANCE_NAME') - local app_name = os.getenv('TARANTOOL_APP_NAME') - - -Managing multi-instance applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start all three instances of the ``demo`` application: - -.. code-block:: console - - $ tt start demo - • Starting an instance [demo:router]... - • Starting an instance [demo:storage1]... - • Starting an instance [demo:storage2]... - -Check the status of ``demo`` instances: - -.. code-block:: console - - $ tt status demo - INSTANCE STATUS PID - demo:router RUNNING 55 - demo:storage1 RUNNING 56 - demo:storage2 RUNNING 57 - -Check the status of a specific instance: - -.. code-block:: console - - $ tt status demo:router - INSTANCE STATUS PID - demo:router RUNNING 55 - -Connect to an instance: - -.. code-block:: console - - $ tt connect demo:router - • Connecting to the instance... - • Connected to /var/run/tarantool/demo/router/router.control - - /var/run/tarantool/demo/router/router.control> - -Stop a specific instance: - -.. code-block:: console - - $ tt stop demo:storage1 - • The Instance demo:storage1 (PID = 56) has been terminated. - -Stop all running instances of the ``demo`` application: - -.. code-block:: console - - $ tt stop demo - • The Instance demo:router (PID = 55) has been terminated. - • can't "stat" the PID file. Error: "stat /var/run/tarantool/demo/storage1/storage1.pid: no such file or directory" - • The Instance demo:storage2 (PID = 57) has been terminated. - -.. note:: - - The error message indicates that ``storage1`` is already not running. - -.. _admin-start_stop_instance-running_locally: - -Running Tarantool locally -------------------------- - -Sometimes you may need to run a Tarantool instance locally, for example, for test -purposes. ``tt`` runs in a local environment if it finds a ``tt.yaml`` configuration -file in the current directory or any of its enclosing directories. - -To set up a local environment for ``tt``: - -1. Create a home directory for the environment. - -2. Run ``tt init`` in this directory: - - .. code-block:: console - - $ tt init - • Environment config is written to 'tt.yaml' - -This command creates a default ``tt`` configuration file ``tt.yaml`` for a local -environment and the directories for instance files, control sockets, logs, and other -artifacts: - -.. code-block:: console - - $ ls - bin distfiles include instances.enabled modules templates tt.yaml - -To run a Tarantool instance in the local environment: - -1. Place the instance file into the ``instances.enabled/`` directory inside the - current directory. - -2. Run ``tt start``: - - .. code-block:: console - - $ tt start - -After the instance is started, you can find its artifacts in their locations inside -the current directory: - -* logs in ``var/log/`` -* snapshots and write-ahead logs in ``var/lib/`` -* control sockets and PID files in ``var/run/`` - -To work with a local environment from a directory outside it, issue ``tt`` calls with -the ``-L`` or ``--local`` argument with the path to this environment as its value: - -.. code-block:: console - - $ tt --local=/usr/tt/env/ start - -.. _admin-start_stop_instance-systemd: - -Using systemd tools -------------------- - -If you start an instance using ``systemd`` tools, like this (the instance name -is ``my_app``): - -.. code-block:: console - - $ systemctl start tarantool@my_app - $ ps axuf|grep my_app - taranto+ 5350 1.3 0.3 1448872 7736 ? Ssl 20:05 0:28 tarantool my_app.lua - -This actually calls ``tarantoolctl`` like in case of -``tarantoolctl start my_app``. - -To enable ``my_app`` instance for auto-load during system startup, say: - -.. code-block:: console - - $ systemctl enable tarantool@my_app - -To stop a running ``my_app`` instance with ``systemctl``, run: - -.. code-block:: console - - $ systemctl stop tarantool@my_app - -To restart a running ``my_app`` instance with ``systemctl``, run: - -.. code-block:: console - - $ systemctl restart tarantool@my_app diff --git a/doc/book/admin/vshard_admin.rst b/doc/book/admin/vshard_admin.rst deleted file mode 100644 index 59a66795b0..0000000000 --- a/doc/book/admin/vshard_admin.rst +++ /dev/null @@ -1,615 +0,0 @@ -.. _vshard-admin: - -Sharding with vshard -==================== - -Sharding in Tarantool is implemented in the ``vshard`` module. -For a quick start with ``vshard``, refer to the :ref:`guide `. - -.. _vshard-install: - -Installation ------------- - -The ``vshard`` module is distributed separately from the main Tarantool package. -To install the module, execute the following command: - -.. code-block:: console - - $ tt rocks install vshard - -.. note:: - - The ``vshard`` module requires Tarantool of the version 1.10.1 or higher, - :ref:`Tarantool development package `, - ``git``, ``cmake`` and ``gcc`` packages installed. - -.. _vshard-config-cluster: - -Configuration -------------- - -Any viable sharded cluster consists of: - -* one or more replica sets, each containing two or more - :ref:`storage ` instances, -* one or more :ref:`router ` instances. - -The number of ``storage`` instances in a replica set defines the redundancy factor -of the data. The recommended value is 3 or more. The number of ``router`` instances -is not limited, because routers are completely stateless. We recommend increasing -the number of routers when an existing ``router`` instance becomes CPU or I/O bound. - -``vshard`` supports multiple ``router`` instances on a single Tarantool -instance. Each ``router`` can be connected to any ``vshard`` cluster. Multiple -``router`` instances can be connected to the same cluster. - -As the ``router`` and ``storage`` applications perform completely different sets of functions, -they should be deployed to different Tarantool instances. Although it is technically -possible to place the router application on every ``storage`` node, this approach is -highly discouraged and should be avoided on production deployments. - -All ``storage`` instances can be deployed using identical instance (configuration) -files. - -All ``router`` instances can also be deployed using identical instance (configuration) -files. - -All cluster nodes must share a common topology. An administrator must -ensure that the configurations are identical. We suggest using a configuration -management tool like Ansible or Puppet to deploy the cluster. - -Sharding is not integrated into any system for centralized configuration management. -It is expected that the application itself is responsible for interacting with such -a system and passing the sharding parameters. - -The configuration example of a simple sharded cluster is available -:ref:`here `. - -.. _vshard-replica-weights: - -Replica weights -~~~~~~~~~~~~~~~ - -The ``router`` sends all read-write requests to the master instance only. Setting replica -weights allows sending read-only requests not only to the master instance, but to any -available replica that is the 'nearest' to the ``router``. Weights are used to define -distances between replicas within a replica set. - -Weights can be used, for example, to define the physical distance between the -``router`` and each replica in each replica set. In this case read requests -are sent to the nearest replica (with the lowest weight). - -Setting weights can also help to define the most powerful replicas: the ones that -can process the largest number of requests per second. - -The idea is to specify the zone for every ``router`` and every replica, therefore -filling a matrix of relative zone weights. This approach allows setting different -weights in different zones for the same replica set. - -To set weights, use the zone attribute for each replica during configuration: - -.. code-block:: kconfig - - local cfg = { - sharding = { - ['...replicaset_uuid...'] = { - replicas = { - ['...replica_uuid...'] = { - ..., - zone = - } - } - } - } - } - -Then, specify relative weights for each zone pair in the ``weights`` parameter of -``vshard.router.cfg``. For example: - -.. code-block:: kconfig - - weights = { - [1] = { - [2] = 1, -- Routers of the 1st zone see the weight of the 2nd zone as 1. - [3] = 2, -- Routers of the 1st zone see the weight of the 3rd zone as 2. - [4] = 3, -- ... - }, - [2] = { - [1] = 10, - [2] = 0, - [3] = 10, - [4] = 20, - }, - [3] = { - [1] = 100, - [2] = 200, -- Routers of the 3rd zone see the weight of the 2nd zone as 200. - -- Mind that it is not equal to the weight of the 2nd zone visible - -- from the 1st zone (= 1). - [4] = 1000, - } - } - - local cfg = vshard.router.cfg({weights = weights, sharding = ...}) - -.. _vshard-replica-set-weights: - -Replica set weights -~~~~~~~~~~~~~~~~~~~ - -A replica set weight is not the same as the replica weight. The weight of a replica -set defines the capacity of the replica set: the larger the weight, the more -buckets the replica set can store. The total size of all sharded spaces in the -replica set is also its capacity metric. - -You can consider replica set weights as the relative amount of data within a -replica set. For example, if ``replicaset_1 = 100``, and ``replicaset_2 = 200``, -the second replica set stores twice as many buckets as the first one. By default, -all weights of all replica sets are equal. - -You can use weights, for example, to store the prevailing amount of data on a -replica set with more memory space. - -.. _vshard-rebalancing: - -Rebalancing process -~~~~~~~~~~~~~~~~~~~ - -There is an **etalon number** of buckets for a replica set. -(Etalon in this context means "ideal".) -If there is no deviation -from this number in the whole replica set, then the buckets are distributed evenly. - -The etalon number is calculated automatically considering the number of buckets -in the cluster and weights of the replica sets. - -Rebalancing starts if the **disbalance threshold of a replica set** -exceeds the disbalance threshold -:ref:`specified in the configuration `. - -The disbalance threshold of a replica set is calculated as follows: - -.. code-block:: none - - |etalon_bucket_number - real_bucket_number| / etalon_bucket_number * 100 - -For example: The user specified the number of buckets is 3000, and weights -of 3 replica sets are 1, 0.5, and 1.5. The resulting etalon numbers of buckets -for the replica sets are: 1st replica set – 1000, 2nd replica set – 500, 3rd -replica set – 1500. - -This approach allows assigning a zero weight to a replica set, which initiates -migration of its buckets to the remaining cluster nodes. It also allows adding -a new zero-load replica set, which initiates migration of the buckets from the -loaded replica sets to the zero-load replica set. - -.. note:: - - A new zero-load replica set should be assigned a weight for rebalancing to start. - -When a new shard is added, the configuration can be updated dynamically: - -1. The configuration should be updated on all the ``routers`` first, and then on all - the ``storages``. -2. The new shard becomes available for rebalancing in the ``storage`` layer. -3. As a result of rebalancing, buckets are migrated to the new shard. -4. If a migrated bucket is requested, ``router`` receives an error code containing - information about the new location of the bucket. - -At this time, the new shard is already present in the ``router``'s pool of -connections, so redirection is transparent for the application. - -.. _vshard-parallel-rebalancing: - -Parallel rebalancing -~~~~~~~~~~~~~~~~~~~~ - -Originally, ``vshard`` had quite a simple ``rebalancer`` – -one process on one node that calculated *routes* which should send buckets, how -many, and to whom. The nodes applied these routes one by -one sequentially. - -Unfortunately, such a simple schema worked not fast enough, -especially for Vinyl, where costs of reading disk were comparable -with network costs. In fact, with Vinyl the ``rebalancer`` routes -applier was sleeping most of the time. - -Now each node can send multiple buckets in parallel in a -round-robin manner to multiple destinations, or to just one. - -To set the degree of parallelism, a new option was added -- -:ref:`rebalancer_max_sending `. -You can specify it in a storage configuration in the root table: - -.. code-block:: lua - - cfg.rebalancer_max_sending = 5 - vshard.storage.cfg(cfg, box.info.uuid) - -In routers, this option is ignored. - -.. note:: - - Specifying ``cfg.rebalancer_max_sending = N`` probably won't give N times - speed up. It depends on network, disk, number of other fibers in the system. - -**Example #1:** - - You have 10 replica sets and a new one is added. - Now all the 10 replica sets will try to send buckets to the new one. - - Assume that each replica set can send up to 5 buckets at once. In that case, - the new replica set will experience a rather big load of 50 buckets - being downloaded at once. If the node needs to do some other - work, perhaps such a big load is undesirable. Also too many - parallel buckets can cause timeouts in the rebalancing process - itself. - - To fix the problem, you can set a lower value for ``rebalancer_max_sending`` - for old replica sets, or decrease ``rebalancer_max_receiving`` for the new one. - In the latter case some workers on old nodes will be throttled, - and you will see that in the logs. - -``rebalancer_max_sending`` is important, if you have restrictions for -the maximal number of buckets that can be read-only at once in the cluster. As you -remember, when a bucket is being sent, it does not accept new -write requests. - -**Example #2:** - - You have 100000 buckets and each - bucket stores ~0.001% of your data. The cluster has 10 - replica sets. And you never can afford > 0.1% of data locked on - write. Then you should not set ``rebalancer_max_sending`` > 10 on - these nodes. It guarantees that the rebalancer won't send more - than 100 buckets at once in the whole cluster. - -If ``max_sending`` is too high and ``max_receiving`` is too low, -then some buckets will try to get relocated – and will fail with that. -This problem will consume network resources and time. It is important to -configure these parameters to not conflict with each other. - -.. _vshard-lock-pin: - -Replica set lock and bucket pin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A replica set lock makes a replica set invisible to the ``rebalancer``: a locked -replica set can neither receive new buckets nor migrate its own buckets. - -A bucket pin blocks a specific bucket from migrating: a pinned bucket stays on -the replica set to which it is pinned, until it is unpinned. - -Pinning all replica set buckets is not equivalent to locking a replica set. Even if -you pin all buckets, a non-locked replica set can still receive new buckets. - -Replica set lock is helpful, for example, to separate a replica set from production -replica sets for testing, or to preserve some application metadata that must not -be sharded for a while. A bucket pin is used for similar cases but in a smaller -scope. - -By both locking a replica set and pinning all buckets, one can -isolate an entire replica set. - -Locked replica sets and pinned buckets affect the rebalancing algorithm as the -``rebalancer`` must ignore locked replica sets and consider pinned buckets when -attempting to reach the best possible balance. - -The issue is not trivial as a user can pin too many buckets to a replica set, -so a perfect balance becomes unreachable. For example, consider the following -cluster (assume all replica set weights are equal to 1). - -The initial configuration: - -.. code-block:: none - - rs1: bucket_count = 150 - rs2: bucket_count = 150, pinned_count = 120 - -Adding a new replica set: - -.. code-block:: none - - rs1: bucket_count = 150 - rs2: bucket_count = 150, pinned_count = 120 - rs3: bucket_count = 0 - -The perfect balance would be ``100 - 100 - 100``, which is impossible since the -``rs2`` replica set has 120 pinned buckets. The best possible balance here is the -following: - -.. code-block:: none - - rs1: bucket_count = 90 - rs2: bucket_count = 120, pinned_count 120 - rs3: bucket_count = 90 - -The ``rebalancer`` moved as many buckets as possible from ``rs2`` to decrease the -disbalance. At the same time it respected equal weights of ``rs1`` and ``rs3``. - -The algorithms for implementing locks and pins are completely different, although -they look similar in terms of functionality. - -.. _vshard-lock-and-rebalancing: - -Replica set lock and rebalancing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Locked replica sets simply do not participate in rebalancing. This means that -even if the actual total number of buckets is not equal to the etalon number, -the disbalance cannot be fixed due to the lock. When the rebalancer detects that -one of the replica sets is locked, it recalculates the etalon number of buckets -of the non-locked replica sets as if the locked replica set and its buckets did -not exist at all. - -.. _vshard-pin-and-rebalancing: - -Bucket pin and rebalancing -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Rebalancing replica sets with pinned buckets requires a more complex algorithm. -Here ``pinned_count[o]`` is the number of pinned buckets, and ``etalon_count`` is -the etalon number of buckets for a replica set: - -1. The ``rebalancer`` calculates the etalon number of buckets as if all buckets - were not pinned. Then the rebalancer checks each replica set and compares the - etalon number of buckets with the number of pinned buckets in a replica set. - If ``pinned_count < etalon_count``, non-locked replica sets (at this point all - locked replica sets already are filtered out) with pinned buckets can receive - new buckets. -2. If ``pinned_count > etalon_count``, the disbalance cannot be fixed, as the - ``rebalancer`` cannot move pinned buckets out of this replica set. In such a case - the etalon number is updated and set equal to the number of pinned buckets. - The replica sets with ``pinned_count > etalon_count`` are not processed by - the ``rebalancer``, and the number of pinned buckets is subtracted from the - total number of buckets. The rebalancer tries to move out as many buckets as - possible from such replica sets. -3. This procedure is restarted from step 1 for replica sets with - ``pinned_count >= etalon_count`` until ``pinned_count <= etalon_count`` on - all replica sets. The procedure is also restarted when the total number of - buckets is changed. - -Here is the pseudocode for the algorithm: - -.. code-block:: lua - - function cluster_calculate_perfect_balance(replicasets, bucket_count) - -- rebalance the buckets using weights of the still viable replica sets -- - end; - - cluster = ; - bucket_count = ; - can_reach_balance = false - while not can_reach_balance do - can_reach_balance = true - cluster_calculate_perfect_balance(cluster, bucket_count); - foreach replicaset in cluster do - if replicaset.perfect_bucket_count < - replicaset.pinned_bucket_count then - can_reach_balance = false - bucket_count -= replicaset.pinned_bucket_count; - replicaset.perfect_bucket_count = - replicaset.pinned_bucket_count; - end; - end; - end; - cluster_calculate_perfect_balance(cluster, bucket_count); - -The complexity of the algorithm is ``O(N^2)``, where N is the number of replica sets. -On each step, the algorithm either finishes the calculation, or ignores at least -one new replica set overloaded with the pinned buckets, and updates the etalon -number of buckets on other replica sets. - -.. _vshard-ref: - -Bucket ref -~~~~~~~~~~ - -Bucket ref is an in-memory counter that is similar to the -:ref:`bucket pin `, but has the following differences: - -#. Bucket ref is not persistent. Refs are intended for forbidding bucket transfer - during request execution, but on restart all requests are dropped. - -#. There are two types of bucket refs: read-only (RO) and read-write (RW). - - If a bucket has RW refs, it cannot be moved. However, when the rebalancer - needs it to be sent, it locks the bucket for new write requests, waits - until all current requests are finished, and then sends the bucket. - - If a bucket has RO refs, it can be sent, but cannot be dropped. Such a - bucket can even enter GARBAGE or SENT state, but its data is kept until - the last reader is gone. - - A single bucket can have both RO and RW refs. - -#. Bucket ref is countable. - -The :ref:`vshard.storage.bucket_ref/unref()` methods -are called automatically when :ref:`vshard.router.call() ` -or :ref:`vshard.storage.call() ` is used. -For raw API like ``r = vshard.router.route() r:callro/callrw`` you should -explicitly call the ``bucket_ref()`` method inside the function. Also, make sure -that you call ``bucket_unref()`` after ``bucket_ref()``, otherwise the bucket -cannot be moved from the storage until the instance restart. - -To see how many refs there are for a bucket, use -:ref:`vshard.storage.buckets_info([bucket_id]) ` -(the ``bucket_id`` parameter is optional). - -For example: - -.. code-block:: tarantoolsession - - vshard.storage.buckets_info(1) - --- - - 1: - status: active - ref_rw: 1 - ref_ro: 1 - ro_lock: true - rw_lock: true - id: 1 - -.. _vshard-define-spaces: - -Defining spaces -~~~~~~~~~~~~~~~ - -Database Schema is stored on ``storages``, while ``routers`` know nothing about -spaces and tuples. - -Spaces should be defined within a storage application using ``box.once()``. -For example: - -.. code-block:: lua - - box.once("testapp:schema:1", function() - local customer = box.schema.space.create('customer') - customer:format({ - {'customer_id', 'unsigned'}, - {'bucket_id', 'unsigned'}, - {'name', 'string'}, - }) - customer:create_index('customer_id', {parts = {'customer_id'}}) - customer:create_index('bucket_id', {parts = {'bucket_id'}, unique = false}) - - local account = box.schema.space.create('account') - account:format({ - {'account_id', 'unsigned'}, - {'customer_id', 'unsigned'}, - {'bucket_id', 'unsigned'}, - {'balance', 'unsigned'}, - {'name', 'string'}, - }) - account:create_index('account_id', {parts = {'account_id'}}) - account:create_index('customer_id', {parts = {'customer_id'}, unique = false}) - account:create_index('bucket_id', {parts = {'bucket_id'}, unique = false}) - box.snapshot() - - box.schema.func.create('customer_lookup') - box.schema.role.grant('public', 'execute', 'function', 'customer_lookup') - box.schema.func.create('customer_add') - end) - -.. note:: - - Every space you plan to shard must have a field with - :ref:`bucket id ` numbers, indexed by the - :ref:`shard index `. - -.. _vshard-adding-data: - -Adding data -~~~~~~~~~~~ - -All DML operations with data should be performed via ``router``. The -only operation supported by ``router`` is `CALL` via ``bucket_id``: - -.. code-block:: lua - - result = vshard.router.call(bucket_id, mode, func, args) - -``vshard.router.call()`` routes ``result = func(unpack(args))`` call to a shard -which serves ``bucket_id``. - -``bucket_id`` is just a regular number in the range -``1..``:ref:`bucket_count`. This number can be assigned in -an arbitrary way by the client application. A sharded Tarantool cluster uses this -number as an opaque unique identifier to distribute data across replica sets. It -is guaranteed that all records with the same ``bucket_id`` will be stored on the -same replica set. - -.. _vshard-bootstrap: - -Bootstrapping and restarting a storage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If a replica set master fails, it is recommended to: - -#. Switch one of the replicas into the master mode. This allows the new master - to process all the incoming requests. -#. Update the configuration of all the cluster members. This forwards all the - requests to the new master. - -Monitoring the master and switching the instance modes can be handled by any -external utility. - -To perform a scheduled downtime of a replica set master, it is recommended to: - -#. Update the configuration of the master and wait for the replicas to get into - sync. All the requests then are forwarded to a new master. -#. Switch another instance into the master mode. -#. Update the configuration of all the nodes. -#. Shut down the old master. - -To perform a scheduled downtime of a replica set, it is recommended to: - -#. Migrate all the buckets to the other cluster storages. -#. Update the configuration of all the nodes. -#. Shut down the replica set. - -In case a whole replica set fails, some part of the dataset becomes inaccessible. -Meanwhile, the ``router`` tries to reconnect to the master of the failed replica -set. This way, once the replica set is up and running again, the cluster is -automatically restored. - -.. _vshard-fibers: - -Fibers -~~~~~~ - -Searches for buckets, buckets recovery, and buckets rebalancing are performed -automatically and do not require manual intervention. - -Technically, there are multiple fibers responsible for different types of -operations: - -* a **discovery** fiber on the ``router`` searches for buckets in the background -* a **failover** fiber on the ``router`` maintains replica connections -* a **garbage collector** fiber on each master ``storage`` removes the contents - of buckets that were moved -* a **bucket recovery** fiber on each master ``storage`` recovers buckets in the - SENDING and RECEIVING states in case of reboot -* a **rebalancer** on a single master ``storage`` among all replica sets executes - the rebalancing process. - -See the :ref:`Rebalancing process ` and -:ref:`Migration of buckets ` sections for details. - -.. _vshard-gc: - -Garbage collector -^^^^^^^^^^^^^^^^^ - -A **garbage collector** fiber runs in the background on the master storages -of each replica set. It starts deleting the contents of the bucket in the GARBAGE -state part by part. Once the bucket is empty, its record is deleted from the -``_bucket`` system space. - -.. _vshard-bucket-recovery: - -Bucket recovery -^^^^^^^^^^^^^^^ - -A **bucket recovery** fiber runs on the master storages. It helps to recover -buckets in the SENDING and RECEIVING states in case of reboot. - -Buckets in the SENDING state are recovered as follows: - -1. The system first searches for buckets in the SENDING state. -2. If such a bucket is found, the system sends a request to the destination - replica set. -3. If the bucket on the destination replica set is ACTIVE, the original bucket - is deleted from the source node. - -Buckets in the RECEIVING state are deleted without extra checks. - -.. _vshard-failover: - -Failover -^^^^^^^^ - -A **failover** fiber runs on every ``router``. If a master of a replica set -becomes unavailable, the failover fiber redirects read requests to the replicas. -Write requests are rejected with an error until the master becomes available. diff --git a/doc/book/box/index.rst b/doc/book/box/index.rst deleted file mode 100644 index ec5d6cde48..0000000000 --- a/doc/book/box/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _database-chapter: - -******************************************************************************** -Database -******************************************************************************** - -In this chapter, we introduce the basic concepts of working with Tarantool as -a database manager. - -This chapter contains the following sections: - -.. toctree:: - :maxdepth: 2 - :numbered: 0 - - ../../concepts/data_model/index - ../../concepts/atomic - ../admin/access_control - ../../concepts/triggers - limitations - ../../concepts/engines/index diff --git a/doc/book/box/limitations.rst b/doc/book/box/limitations.rst deleted file mode 100644 index 84aa99717a..0000000000 --- a/doc/book/box/limitations.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _limitations_fields_in_index: - -================================================================================ -Limitations -================================================================================ - -**Number of parts in an index** - - For TREE or HASH indexes, the maximum - is 255 (``box.schema.INDEX_PART_MAX``). For :ref:`RTREE ` indexes, the - maximum is 1 but the field is an ARRAY of up to 20 dimensions. - For BITSET indexes, the maximum is 1. - -.. _limitations_indexes_in_space: - -**Number of indexes in a space** - - 128 (``box.schema.INDEX_MAX``). - -.. _limitations_fields_in_tuple: - -**Number of fields in a tuple** - - The theoretical maximum is 2,147,483,647 (``box.schema.FIELD_MAX``). The - practical maximum is whatever is specified by the space's - :ref:`field_count ` - member, or the maximal tuple length. - -.. _limitations_bytes_in_tuple: - -**Number of bytes in a tuple** - - The maximal number of bytes in a tuple is roughly equal to - :ref:`memtx_max_tuple_size ` or - :ref:`vinyl_max_tuple_size ` - (with a metadata - overhead of about 20 bytes per tuple, which is added on top of useful bytes). - By default, the value of either ``memtx_max_tuple_size`` or - ``vinyl_max_tuple_size`` is 1,048,576. To increase it, - specify a larger value when starting the Tarantool instance. - For example, ``box.cfg{memtx_max_tuple_size=2*1048576}``. - -.. _limitations_bytes_in_index_key: - -**Number of bytes in an index key** - - If a field in a tuple can contain a million bytes, then the index key - can contain a million bytes, so the maximum is determined by factors - such as :ref:`Number of bytes in a tuple `, - not by the index support. - -.. _limitations_fields_in_tuple_multikey_index: - -**Number of elements in array fields in a space with a multikey index** - - In a Tarantool space that has :ref:`multikey indexes `, - any tuple cannot contain more than ~8,000 elements in a field indexed with that multikey index. - This is because every element has 4 bytes of metadata, and the tuple's metadata, - which includes multikey metadata, cannot exceed 2^16 bytes. - -.. _limitations_number_of_spaces: - -**Number of spaces** - - The theoretical maximum is 2147483647 (``box.schema.SPACE_MAX``) - but the practical maximum is around 65,000. - -.. _limitations_number_of_connections: - -**Number of connections** - - The practical limit is the number of file descriptors that one can set - with the operating system. - -.. _limitations_space_size: - -**Space size** - - The total maximum size for all spaces is in effect set by - :ref:`memtx_memory `, which in turn - is limited by the total available memory. - -.. _limitations_update_ops: - -**Update operations count** - - The maximum number of operations per tuple that can be in a single update - is 4000 (``BOX_UPDATE_OP_CNT_MAX``). - -.. _limitations_users_and_roles: - -**Number of users and roles** - - 32 (``BOX_USER_MAX``). - -.. _limitations_length: - -**Length of an index name or space name or user name** - - 65000 (``box.schema.NAME_MAX``). - -.. _limitations_replicas: - -**Number of replicas in a replica set** - - 32 (``vclock.VCLOCK_MAX``). diff --git a/doc/book/cartridge/cartridge_overview.rst b/doc/book/cartridge/cartridge_overview.rst deleted file mode 100644 index 1f7e75ca3c..0000000000 --- a/doc/book/cartridge/cartridge_overview.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _cartridge-overview: - -================================================================================ -About Tarantool Cartridge -================================================================================ - -Tarantool Cartridge is the recommended alternative to the -:ref:`old-school practices ` of application development -for Tarantool. - -.. _cluster-app: - -As a software development kit (SDK), Tarantool Cartridge provides you with -utilities and :ref:`templates ` to help: - -* easily set up a development environment for your applications; -* plug the necessary Lua modules. - -The resulting package can be installed and started on one or multiple servers -as one or multiple instantiated services -- independent or organized into a -**cluster**. - -.. NOTE:: - - A Tarantool cluster is a collection of Tarantool instances acting in concert. - While a single Tarantool instance can leverage the performance of a single server - and is vulnerable to failure, the cluster spans multiple servers, utilizes their - cumulative CPU power, and is fault-tolerant. - - To fully utilize the capabilities of a Tarantool cluster, you need to - develop applications keeping in mind they are to run in a cluster environment. - -Further on, Tarantool Cartridge provides your cluster-aware applications with -the following benefits: - -* horizontal scalability and load balancing via built-in automatic sharding; -* asynchronous replication; -* automatic failover; -* centralized cluster control via GUI or API; -* automatic configuration synchronization; -* instance functionality segregation. - -A Tarantool Cartridge cluster can segregate functionality between instances via -built-in and custom (user-defined) :ref:`cluster roles `. -You can toggle instances on and off on the fly during cluster operation. -This allows you to put different types of workloads -(e.g., compute- and transaction-intensive ones) on different physical servers -with dedicated hardware. diff --git a/doc/book/cartridge/images/auth_creds.png b/doc/book/cartridge/images/auth_creds.png deleted file mode 100644 index 04a5c14488..0000000000 Binary files a/doc/book/cartridge/images/auth_creds.png and /dev/null differ diff --git a/doc/book/cartridge/images/bootstrap-vshard.png b/doc/book/cartridge/images/bootstrap-vshard.png deleted file mode 100644 index 71734bc85b..0000000000 Binary files a/doc/book/cartridge/images/bootstrap-vshard.png and /dev/null differ diff --git a/doc/book/cartridge/images/change-weight.png b/doc/book/cartridge/images/change-weight.png deleted file mode 100644 index bdd0aa5dfb..0000000000 Binary files a/doc/book/cartridge/images/change-weight.png and /dev/null differ diff --git a/doc/book/cartridge/images/create-router.png b/doc/book/cartridge/images/create-router.png deleted file mode 100644 index dfb43a331b..0000000000 Binary files a/doc/book/cartridge/images/create-router.png and /dev/null differ diff --git a/doc/book/cartridge/images/create-storage.png b/doc/book/cartridge/images/create-storage.png deleted file mode 100644 index d0a6189e48..0000000000 Binary files a/doc/book/cartridge/images/create-storage.png and /dev/null differ diff --git a/doc/book/cartridge/images/edit-replica-set.png b/doc/book/cartridge/images/edit-replica-set.png deleted file mode 100644 index d4e2d105d4..0000000000 Binary files a/doc/book/cartridge/images/edit-replica-set.png and /dev/null differ diff --git a/doc/book/cartridge/images/enabled-failover.png b/doc/book/cartridge/images/enabled-failover.png deleted file mode 100644 index 48a3f3e298..0000000000 Binary files a/doc/book/cartridge/images/enabled-failover.png and /dev/null differ diff --git a/doc/book/cartridge/images/expelling-instance.png b/doc/book/cartridge/images/expelling-instance.png deleted file mode 100644 index 41d9d9a361..0000000000 Binary files a/doc/book/cartridge/images/expelling-instance.png and /dev/null differ diff --git a/doc/book/cartridge/images/failover-control.png b/doc/book/cartridge/images/failover-control.png deleted file mode 100644 index 6eac960da8..0000000000 Binary files a/doc/book/cartridge/images/failover-control.png and /dev/null differ diff --git a/doc/book/cartridge/images/failover-priority.png b/doc/book/cartridge/images/failover-priority.png deleted file mode 100644 index fa9ece3cf8..0000000000 Binary files a/doc/book/cartridge/images/failover-priority.png and /dev/null differ diff --git a/doc/book/cartridge/images/failover.png b/doc/book/cartridge/images/failover.png deleted file mode 100644 index c51839d432..0000000000 Binary files a/doc/book/cartridge/images/failover.png and /dev/null differ diff --git a/doc/book/cartridge/images/final-cluster.png b/doc/book/cartridge/images/final-cluster.png deleted file mode 100644 index 378cab79b4..0000000000 Binary files a/doc/book/cartridge/images/final-cluster.png and /dev/null differ diff --git a/doc/book/cartridge/images/join-new-set.png b/doc/book/cartridge/images/join-new-set.png deleted file mode 100644 index 58436cf0b0..0000000000 Binary files a/doc/book/cartridge/images/join-new-set.png and /dev/null differ diff --git a/doc/book/cartridge/images/join-router.png b/doc/book/cartridge/images/join-router.png deleted file mode 100644 index 651f07e791..0000000000 Binary files a/doc/book/cartridge/images/join-router.png and /dev/null differ diff --git a/doc/book/cartridge/images/join-storage.png b/doc/book/cartridge/images/join-storage.png deleted file mode 100644 index aa5fa0b18e..0000000000 Binary files a/doc/book/cartridge/images/join-storage.png and /dev/null differ diff --git a/doc/book/cartridge/images/new-unconfig.png b/doc/book/cartridge/images/new-unconfig.png deleted file mode 100644 index f148aaede9..0000000000 Binary files a/doc/book/cartridge/images/new-unconfig.png and /dev/null differ diff --git a/doc/book/cartridge/images/probe-server.png b/doc/book/cartridge/images/probe-server.png deleted file mode 100644 index 872287f95b..0000000000 Binary files a/doc/book/cartridge/images/probe-server.png and /dev/null differ diff --git a/doc/book/cartridge/images/switch-master.png b/doc/book/cartridge/images/switch-master.png deleted file mode 100644 index 59168413c1..0000000000 Binary files a/doc/book/cartridge/images/switch-master.png and /dev/null differ diff --git a/doc/book/cartridge/images/unconfigured-router.png b/doc/book/cartridge/images/unconfigured-router.png deleted file mode 100644 index fdec390d11..0000000000 Binary files a/doc/book/cartridge/images/unconfigured-router.png and /dev/null differ diff --git a/doc/book/cartridge/images/users-tab.png b/doc/book/cartridge/images/users-tab.png deleted file mode 100644 index 302601c6e0..0000000000 Binary files a/doc/book/cartridge/images/users-tab.png and /dev/null differ diff --git a/doc/book/cartridge/images/zero-weight.png b/doc/book/cartridge/images/zero-weight.png deleted file mode 100644 index 926318cab0..0000000000 Binary files a/doc/book/cartridge/images/zero-weight.png and /dev/null differ diff --git a/doc/book/cartridge/images/zero.png b/doc/book/cartridge/images/zero.png deleted file mode 100644 index 50654147e1..0000000000 Binary files a/doc/book/cartridge/images/zero.png and /dev/null differ diff --git a/doc/book/connectors.rst b/doc/book/connectors.rst deleted file mode 100644 index c17bd6fb83..0000000000 --- a/doc/book/connectors.rst +++ /dev/null @@ -1,210 +0,0 @@ -.. _index-box_connectors: - -Connectors -========== - -Connectors are APIs that allow using Tarantool with various programming languages. - -Connectors can be divided into two groups -- those maintained by the Tarantool team -and those supported by the community. -The Tarantool team maintains the :ref:`high-level C API `, the :ref:`Go ` -and :ref:`Java ` connectors, and a synchronous :ref:`Python ` connector. -All other connectors are :ref:`community-supported `, which means that support for new Tarantool features may be delayed. -Besides, the Tarantool support team cannot prioritize issues that arise while working through these connectors. - -This chapter documents APIs for various programming languages: - -.. toctree:: - :maxdepth: 1 - - connectors/c - connectors/go - connectors/java - connectors/python - connectors/community - -Protocol --------- - -Tarantool's binary protocol was designed with a focus on asynchronous I/O and -easy integration with proxies. Each client request starts with a variable-length -binary header, containing request id, request type, instance id, log sequence -number, and so on. - -The mandatory length, present in request header simplifies client or proxy I/O. -A response to a request is sent to the client as soon as it is ready. It always -carries in its header the same type and id as in the request. The id makes it -possible to match a request to a response, even if the latter arrived out of -order. - -Unless implementing a client driver, you needn't concern yourself with the -complications of the binary protocol. Language-specific drivers provide a -friendly way to store domain language data structures in Tarantool. A complete -description of the binary protocol is maintained in annotated Backus-Naur form -in the source tree. For detailed examples and diagrams of all binary-protocol -requests and responses, see -:ref:`Tarantool's binary protocol `. - - -Packet example --------------- - -The Tarantool API exists so that a client program can send a request packet to -a server instance, and receive a response. Here is an example of a what the client -would send for ``box.space[513]:insert{'A', 'BB'}``. The BNF description of -the components is on the page about -:ref:`Tarantool's binary protocol `. - -.. _Language-specific drivers: `Connectors`_ - -.. container:: table - - .. rst-class:: left-align-column-1 - .. rst-class:: right-align-column-2 - .. rst-class:: right-align-column-3 - .. rst-class:: right-align-column-4 - - +---------------------------------+---------+---------+---------+---------+ - | Component | Byte #0 | Byte #1 | Byte #2 | Byte #3 | - +=================================+=========+=========+=========+=========+ - | code for insert | 02 | | | | - +---------------------------------+---------+---------+---------+---------+ - | rest of header | ... | ... | ... | ... | - +---------------------------------+---------+---------+---------+---------+ - | 2-digit number: space id | cd | 02 | 01 | | - +---------------------------------+---------+---------+---------+---------+ - | code for tuple | 21 | | | | - +---------------------------------+---------+---------+---------+---------+ - | 1-digit number: field count = 2 | 92 | | | | - +---------------------------------+---------+---------+---------+---------+ - | 1-character string: field[1] | a1 | 41 | | | - +---------------------------------+---------+---------+---------+---------+ - | 2-character string: field[2] | a2 | 42 | 42 | | - +---------------------------------+---------+---------+---------+---------+ - -Now, you could send that packet to the Tarantool instance, and interpret the -response (the page about -:ref:`Tarantool's binary protocol ` has a -description of the packet format for responses as well as requests). But it -would be easier, and less error-prone, if you could invoke a routine that -formats the packet according to typed parameters. Something like -``response = tarantool_routine("insert", 513, "A", "B");``. And that is why APIs -exist for drivers for Perl, Python, PHP, and so on. - -.. _index-connector_setting: - -Setting up the server for connector examples --------------------------------------------- - -This chapter has examples that show how to connect to a Tarantool instance via -the Perl, PHP, Python, node.js, and C connectors. The examples contain hard code that -will work if and only if the following conditions are met: - -* the Tarantool instance (tarantool) is running on localhost (127.0.0.1) and is listening on - port 3301 (``box.cfg.listen = '3301'``), - -* space ``examples`` has id = 999 (``box.space.examples.id = 999``) and has - a primary-key index for a numeric field - (``box.space[999].index[0].parts[1].type = "unsigned"``), - -* user 'guest' has privileges for reading and writing. - -It is easy to meet all the conditions by starting the instance and executing this -script: - -.. code-block:: lua - - box.cfg{listen=3301} - box.schema.space.create('examples',{id=999}) - box.space.examples:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) - box.schema.user.grant('guest','read,write','space','examples') - box.schema.user.grant('guest','read','space','_space') - - -Interpreting function return values ------------------------------------ - -For all connectors, calling a function via Tarantool causes a return in the -MsgPack format. If the function is called using the connector's API, some -conversions may occur. All scalar values are returned as tuples (with a MsgPack -type-identifier followed by a value); all non-scalar values are returned as a -group of tuples (with a MsgPack array-identifier followed by the scalar values). -If the function is called via the binary protocol command layer -- "eval" -- -rather than via the connector's API, no conversions occur. - -In the following example, a Lua function will be created. Since it will be -accessed externally by a :ref:`'guest' user`, a -:doc:`grant ` of an execute privilege will -be necessary. The function returns an empty array, a scalar string, two booleans, -and a short integer. The values are the ones described in the table -:ref:`Common Types and MsgPack Encodings `. - -.. code-block:: tarantoolsession - - tarantool> box.cfg{listen=3301} - 2016-03-03 18:45:52.802 [27381] main/101/interactive I> ready to accept requests - --- - ... - tarantool> function f() return {},'a',false,true,127; end - --- - ... - tarantool> box.schema.func.create('f') - --- - ... - tarantool> box.schema.user.grant('guest','execute','function','f') - --- - ... - -Here is a C program which calls the function. Although C is being used for the -example, the result would be precisely the same if the calling program was -written in Perl, PHP, Python, Go, or Java. - -.. code-block:: c - - #include - #include - #include - #include - #include - void main() { - struct tnt_stream *tnt = tnt_net(NULL); /* SETUP */ - tnt_set(tnt, TNT_OPT_URI, "localhost:3301"); - if (tnt_connect(tnt) < 0) { /* CONNECT */ - printf("Connection refused\n"); - exit(-1); - } - struct tnt_stream *arg; arg = tnt_object(NULL); /* MAKE REQUEST */ - tnt_object_add_array(arg, 0); - struct tnt_request *req1 = tnt_request_call(NULL); /* CALL function f() */ - tnt_request_set_funcz(req1, "f"); - uint64_t sync1 = tnt_request_compile(tnt, req1); - tnt_flush(tnt); /* SEND REQUEST */ - struct tnt_reply reply; tnt_reply_init(&reply); /* GET REPLY */ - tnt->read_reply(tnt, &reply); - if (reply.code != 0) { - printf("Call failed %lu.\n", reply.code); - exit(-1); - } - const unsigned char *p= (unsigned char*)reply.data; /* PRINT REPLY */ - while (p < (unsigned char *) reply.data_end) - { - printf("%x ", *p); - ++p; - } - printf("\n"); - tnt_close(tnt); /* TEARDOWN */ - tnt_stream_free(arg); - tnt_stream_free(tnt); - } - -When this program is executed, it will print: - -.. code-block:: console - - dd 0 0 0 5 90 91 a1 61 91 c2 91 c3 91 7f - -The first five bytes -- ``dd 0 0 0 5`` -- are the MsgPack encoding for -"32-bit array header with value 5" (see -`MsgPack specification `__). -The rest are as described in the -table :ref:`Common Types and MsgPack Encodings `. diff --git a/doc/book/connectors/go.rst b/doc/book/connectors/go.rst deleted file mode 100644 index 3d68dd21a8..0000000000 --- a/doc/book/connectors/go.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. _index_connector_go: - -Go -== - -The following connectors are available: - -* Tarantool-supported `go-tarantool `__ - -* Community-supported `viciious/go-tarantool `_ - -* Community-supported `FZambia/tarantool `_. - -.. _go-feature-comparison: - -Feature comparison ------------------- - -Last update: January 2023 - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - - * - - - `tarantool/go-tarantool `_ - - `viciious/go-tarantool `_ - - `FZambia/tarantool `_ - - * - License - - BSD 2-Clause - - MIT - - BSD 2-Clause - - * - Last update - - 2023 - - 2022 - - 2022 - - * - Documentation - - README with examples and up-to-date GoDoc - - README with examples, code comments - - README with examples - - * - Testing / CI / CD - - GitHub Actions - - Travis CI - - GitHub Actions - - * - GitHub Stars - - 147 - - 45 - - 14 - - * - Static analysis - - golangci-lint, luacheck - - golint - - golangci-lint - - * - Packaging - - go get - - go get - - go get - - * - Code coverage - - Yes - - No - - No - - * - msgpack driver - - `vmihailenco/msgpack/v2 `_ or `vmihailenco/msgpack/v5 `_ - - `tinylib/msgp `_ - - `vmihailenco/msgpack/v5 `_ - - * - Async work - - Yes - - Yes - - Yes - - * - Schema reload - - Yes (manual pull) - - Yes (manual pull) - - Yes (manual pull) - - * - Space / index names - - Yes - - Yes - - Yes - - * - Tuples as structures - - Yes (structure and marshall functions must be predefined in Go code) - - No - - Yes (structure and marshall functions must be predefined in Go code) - - * - Access tuple fields by names - - Only if marshalled to structure - - No - - Only if marshalled to structure - - * - `SQL `_ support - - Yes - - No (`#18 `_, closed) - - No - - * - `Interactive transactions `_ - - Yes - - No - - No - - * - `Varbinary `_ support - - Yes (with in-built language tools) - - Yes (with in-built language tools) - - Yes (decodes to string by default, see `#6 `_) - - * - `UUID `_ support - - Yes - - No - - No - - * - Decimal support - - Yes - - No - - No - - * - `EXT_ERROR `_ - support - - Yes - - No - - No - - * - `Datetime `_ support - - Yes - - No - - No - - * - `box.session.push() responses `_ - - Yes - - No (`#21 `_) - - Yes - - * - `Session settings `_ - - Yes - - No - - No - - * - `Graceful shutdown `_ - - Yes - - No - - No - - * - `IPROTO_ID (feature discovering) `_ - - Yes - - No - - No - - * - `tarantool/crud `_ support - - No - - No - - No - - * - Connection pool - - Yes (round-robin failover, no balancing) - - No - - No - - * - Transparent reconnecting - - Yes (see comments in `#129 `_) - - No (handle reconnects explicitly, refer to `#11 `_) - - Yes (see comments in `#7 `_) - - * - Transparent request retrying - - No - - No - - No - - * - `Watchers `_ - - Yes - - No - - No - - * - `Pagination `_ - - Yes - - No - - No - - * - Language features - - context - - context - - context - - * - Miscellaneous - - Supports `tarantool/queue `_ API - - Can mimic a Tarantool instance (also as replica). Provides instrumentation for reading snapshot and xlog files - via `snapio module `_. - Implements unpacking of query structs if you want to implement your own iproto proxy - - API is experimental and breaking changes may happen diff --git a/doc/book/connectors/python.rst b/doc/book/connectors/python.rst deleted file mode 100644 index 3fd7e1d381..0000000000 --- a/doc/book/connectors/python.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. _index_connector_py: - -Python -====== - -`tarantool-python `__ -is the official Python connector for Tarantool. It is not supplied as part -of the Tarantool repository and must be installed separately (see below for details). - -Here is a complete Python program that inserts ``[99999,'Value','Value']`` into -space ``examples`` via the high-level Python API. - -.. code-block:: python - - #!/usr/bin/python - from tarantool import Connection - - c = Connection("127.0.0.1", 3301) - result = c.insert("examples",(99999,'Value', 'Value')) - print result - -To prepare, paste the code into a file named :file:`example.py` and install -the ``tarantool-python`` connector with either :samp:`pip install tarantool\>0.4` -to install in :file:`/usr` (requires **root** privilege) or -:samp:`pip install tarantool\>0.4 --user` to install in :file:`~` i.e. user's -default directory. - -Before trying to run, check that the server instance is :ref:`listening ` at -``localhost:3301`` and that the space ``examples`` exists, as -:ref:`described earlier `. -To run the program, say :samp:`python example.py`. The program will connect -to the Tarantool server, will send the :ref:`INSERT ` request, and will not throw any exception if -all went well. If the tuple already exists, the program will throw -``tarantool.error.DatabaseError: (3, "Duplicate key exists in unique index 'primary' in space 'examples'")``. - -The example program only shows one request and does not show all that's -necessary for good practice. For that, please see -`tarantool-python `__ project at GitHub. - -Also there are several community-driven Python connectors: - -* `asynctnt `__ with asyncio support -* `aiotarantool `__ also with asyncio support, **no active maintenance** -* `gtarantool `__ with gevent support, **no active maintenance** - -The table below contains a feature comparison for asynctnt and -tarantool-python. aiotarantool and gtarantool are absent there because they are quite outdated and -unmaintained. - -.. _python-feature-comparison: - -Feature comparison ------------------- - -Last update: September 2023 - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - - * - Parameter - - `igorcoding/asynctnt `__ - - `tarantool/tarantool-python `__ - - * - License - - Apache License 2.0 - - BSD-2 - - * - Is maintained - - Yes - - Yes - - * - Known Issues - - None - - None - - * - Documentation - - Yes (`github.io `__) - - Yes (`readthedocs - `__ - and :ref:`tarantool.io `) - - * - Testing / CI / CD - - GitHub Actions - - GitHub Actions - - * - GitHub Stars - - 73 - - 92 - - * - Static Analysis - - Yes (Flake8) - - Yes (Flake8, Pylint) - - * - Packaging - - `pip `__ - - `pip, deb, rpm `__ - - * - Code coverage - - Yes - - Yes - - * - Support asynchronous mode - - Yes, `asyncio `__ - - No - - * - Batching support - - No - - Yes (with CRUD API) - - * - Schema reload - - Yes (automatically, see `auto_refetch_schema `__) - - Yes (automatically) - - * - Space / index names - - Yes - - Yes - - * - Access tuple fields by names - - Yes - - No - - * - :ref:`SQL support ` - - Yes - - Yes - - * - :ref:`Interactive transactions ` - - Yes - - No (`issue #163 `__) - - * - :ref:`Varbinary support ` - - Yes (in ``MP_BIN`` fields) - - Yes - - * - :ref:`Decimal support ` - - Yes - - Yes - - * - :ref:`UUID support ` - - Yes - - Yes - - * - :ref:`EXT_ERROR support ` - - Yes - - Yes - - * - :ref:`Datetime support ` - - Yes - - Yes - - * - :ref:`Interval support ` - - No (`issue #30 `__) - - Yes - - * - :ref:`box.session.push() responses ` - - Yes - - Yes - - * - :ref:`Session settings ` - - No - - No - - * - `Graceful shutdown `__ - - No - - No - - * - `IPROTO_ID (feature discovery) `__ - - Yes - - Yes - - * - `CRUD support `__ - - No - - Yes - - * - Transparent request retrying - - No - - No - - * - Transparent reconnecting - - Autoreconnect - - Yes (reconnect_max_attempts, reconnect_delay), checking of connection liveness - - * - Connection pool - - No - - Yes (with master discovery) - - * - Support of `PEP 249 -- Python Database API Specification v2.0 `__ - - No - - `Yes `__ - - * - :ref:`Encrypted connection (Enterprise Edition) ` - - No (`issue #22 `__) - - Yes diff --git a/doc/book/faq.rst b/doc/book/faq.rst deleted file mode 100644 index 0b28ac2646..0000000000 --- a/doc/book/faq.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _faq: - -------------------------------------------------------------------------------- -FAQ -------------------------------------------------------------------------------- - -.. container:: faq - - :Q: Why Tarantool? - :A: Tarantool is the latest generation of a family of in-memory data servers - developed for web applications. It is the result of practical experience - and trials within Mail.Ru since development began in 2008. - - :Q: Why Lua? - :A: Lua is a lightweight, fast, extensible multi-paradigm language. Lua also - happens to be very easy to embed. Lua coroutines relate very closely to - Tarantool fibers, and Lua architecture works well with Tarantool - internals. Lua acts well as a stored program language for Tarantool, - although connecting with other languages is also easy. - - :Q: What's the key advantage of Tarantool? - :A: | Tarantool provides a rich database feature set (HASH, TREE, RTREE, - BITSET indexes, secondary indexes, composite indexes, transactions, - triggers, asynchronous replication) in a flexible environment of a - Lua interpreter. - | These two properties make it possible to be a fast, atomic and - reliable in-memory data server which handles non-trivial - application-specific logic. The advantage over traditional SQL servers - is in performance: low-overhead, lock-free architecture means - Tarantool can serve an order of magnitude more requests per second, on - comparable hardware. The advantage over NoSQL alternatives is in - flexibility: Lua allows flexible processing of data stored in a - compact, denormalized format. - - :Q: Who is developing Tarantool? - :A: There is an engineering team employed by Mail.Ru -- check out our commit - logs on `github.com/tarantool `_. The - development is fully open. Most of the connectors' authors, and the - maintainers for different distributions, come from the wider community. - - :Q: Are there problems associated with being an in-memory server? - :A: The principal storage engine (memtx) is designed for RAM plus persistent - storage. It is immune to data loss because there is a write-ahead log. - Its memory-allocation and compression techniques ensure there is no - waste. And if Tarantool runs out of memory, then it will stop accepting - updates until more memory is available, but will continue to handle read - and delete requests without difficulty. However, for databases which are - much larger than the available RAM space, Tarantool has a second storage - engine (vinyl) which is only limited by the available disk space. - - :Q: Can I store (large) BLOBs in Tarantool? - :A: Starting with Tarantool 1.7, there is no "hard" limit for the maximal - tuple size. Tarantool, however, is designed for high-velocity workload - with a lot of small chunks. - For example, when you change an existing tuple, Tarantool creates a new - version of the tuple in memory. - Thus, an optimal tuple size is within kilobytes. - - :Q: I delete data from vinyl, but disk usage stays the same. What gives? - :A: Data you write to vinyl is persisted in append-only run files. - These files are immutable, and to perform a delete, a deletion marker - (tombstone) is written to a newer run file instead. On compaction, - new and old run files are merged, and a new run file is produced. - Independently, the checkpoint manager keeps track of all run files - involved in a checkpoint, and deletes obsolete files once they are - no longer needed. diff --git a/doc/book/index.rst b/doc/book/index.rst deleted file mode 100644 index 0ad7da7169..0000000000 --- a/doc/book/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -:noindex: -:fullwidth: - -.. _user_guide: - -------------------------------------------------------------------------------- -User's Guide -------------------------------------------------------------------------------- - -.. toctree:: - :maxdepth: 2 - - intro - ../getting_started/index - ../how-to/index - ../concepts/index - box/index - cartridge/index - admin/index - monitoring/index - connectors - ../reference/reference_sql/index - faq diff --git a/doc/book/intro.rst b/doc/book/intro.rst deleted file mode 100644 index af0296e2fa..0000000000 --- a/doc/book/intro.rst +++ /dev/null @@ -1,60 +0,0 @@ -=============================================================================== -Preface -=============================================================================== - -Welcome to Tarantool! This is the User's Guide. We recommend reading it first, -and consulting :ref:`Reference ` materials for more detail afterwards, -if needed. - -------------------------------------------------------------------------------- -How to read the documentation -------------------------------------------------------------------------------- - -To get started, you can install and launch Tarantool using -:ref:`a Docker container `, -:ref:`a package manager `, -or the online Tarantool server at http://try.tarantool.org. -Either way, as the first tryout, you can follow the introductory exercises -from :ref:`Chapter 2 "Getting started" `. -If you want more hands-on experience, proceed to :ref:`How-to guides ` -after you are through with Chapter 2. - -:ref:`Chapter 3 "Database" ` is about using Tarantool -as a NoSQL DBMS, whereas :ref:`Chapter 4 "Application server" ` -is about using Tarantool as an application server. - -:ref:`Chapter 5 "Server administration" ` and -:ref:`Chapter 6 "Replication" ` are primarily for administrators. - -:ref:`Chapter 7 "Connectors" ` is strictly for users who -are connecting from a different language such as C or Perl or Python — other -users will find no immediate need for this chapter. - -:ref:`Chapter 8 "FAQ" ` gives answers to some frequently asked questions -about Tarantool. - -For experienced users, there are also :ref:`Reference ` materials, -a :ref:`Contributor's Guide ` and an extensive set of comments -in the source code. - -------------------------------------------------------------------------------- -Getting in touch with the Tarantool community -------------------------------------------------------------------------------- - -Please report bugs or make feature requests at http://github.com/tarantool/tarantool/issues. - -You can contact developers directly in `telegram `_ -or in a Tarantool discussion group -(`English `_ or -`Russian `_). - -------------------------------------------------------------------------------- -Conventions used in this manual -------------------------------------------------------------------------------- - -Square brackets [ and ] enclose optional syntax. - -Two dots in a row .. mean the preceding tokens may be repeated. - -A vertical bar | means the preceding and following tokens are mutually exclusive -alternatives. diff --git a/doc/code_snippets/README.md b/doc/code_snippets/README.md index 23f5d9108c..f04e6a918f 100644 --- a/doc/code_snippets/README.md +++ b/doc/code_snippets/README.md @@ -1,25 +1,43 @@ # Tarantool code examples -The `doc/code_snippets` folder of a Tarantool documentation repository contains runnable code examples that show how to work with various Tarantool modules. Code from these examples is [referenced](#referencing-code-snippets) in corresponding documentation sections. +The `doc/code_snippets` folder of a Tarantool documentation repository contains runnable code examples that show how to work with Tarantool: + +- The [snippets](snippets) folder contains sample applications that demonstrate how to configure a Tarantool cluster. +- The [test](test) folder contains testable Lua examples that show how to work with various Tarantool modules. + +Code from these examples is [referenced](#referencing-code-snippets) in corresponding documentation sections. ## Prerequisites -First, install the [tt CLI utility](https://www.tarantool.io/en/doc/latest/reference/tooling/tt_cli/). -Then, go to the `doc/code_snippets` folder and install the following libraries: +- Install the [tt CLI utility](https://www.tarantool.io/en/doc/latest/tooling/tt_cli/). +- To be able to run tests for samples from [test](test), go to the `doc/code_snippets` folder and install the following libraries: -- Install [luatest](https://github.com/tarantool/luatest): - ```shell - tt rocks install luatest - ``` + - [luatest](https://github.com/tarantool/luatest): + ```shell + tt rocks install luatest + ``` + + - [luarapidxml](https://github.com/tarantool/luarapidxml): + ```shell + tt rocks install luarapidxml + ``` -- Install [luarapidxml](https://github.com/tarantool/luarapidxml): - ```shell - tt rocks install luarapidxml - ``` +## Running + +### Running applications from 'snippets' + +To run applications placed in [snippets](snippets), follow these steps: + +1. Go to the directory containing samples for a specific feature, for example, [snippets/replication](snippets/replication). +2. To run applications placed in [instances.enabled](instances.enabled), execute the `tt start` command, for example: + + ```console + $ tt start auto_leader + ``` -## Running and testing examples +### Running and testing examples from 'test' To test all the examples, go to the `doc/code_snippets` folder and execute the `luatest` command: diff --git a/doc/code_snippets/snippets/centralized_config/README.md b/doc/code_snippets/snippets/centralized_config/README.md new file mode 100644 index 0000000000..aa5d22d3a9 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/README.md @@ -0,0 +1,3 @@ +# Centralized configuration storages + +Sample applications demonstrating how to store configuration data in one place using Tarantool or etcd-based storage. Learn more at [Centralized configuration storages](https://www.tarantool.io/en/doc/latest/platform/configuration/configuration_etcd/). diff --git a/doc/code_snippets/snippets/centralized_config/etcd_config_storage.sh b/doc/code_snippets/snippets/centralized_config/etcd_config_storage.sh new file mode 100644 index 0000000000..ca7128952e --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/etcd_config_storage.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash + +# 1. Remove the 'default.etcd' directory to reset etcd to initial state. +# 2. Start etcd by executing the 'etcd' command. +# 3. Execute this script to enable authentication. +etcdctl user add root:topsecret +etcdctl role add myapp_config_manager +etcdctl role grant-permission myapp_config_manager --prefix=true readwrite /myapp/ +etcdctl user add sampleuser:123456 +etcdctl user grant-role sampleuser myapp_config_manager +etcdctl auth enable diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/README.md b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/README.md new file mode 100644 index 0000000000..a422a4f5c0 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/README.md @@ -0,0 +1,13 @@ +# etcd configuration storage + +A sample application demonstrating how to obtain a cluster's configuration from the etcd-based configuration storage. + +## Running + +Before running this sample, start etcd and enable authentication by executing [etcd_config_storage.sh](../../etcd_config_storage.sh). + +To start all instances, execute the following command in the [centralized_config](../../../centralized_config) directory: + +```console +$ tt start config_etcd +``` diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/config.yaml b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/config.yaml new file mode 100644 index 0000000000..893c369bff --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/config.yaml @@ -0,0 +1,10 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /myapp + username: sampleuser + password: '123456' + http: + request: + timeout: 3 diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/instances.yml b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_etcd/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/README.md b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/README.md new file mode 100644 index 0000000000..4079cea76d --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/README.md @@ -0,0 +1,13 @@ +# Tarantool configuration storage + +A sample application demonstrating how to obtain a cluster's configuration from the Tarantool-based configuration storage. + +## Running + +Before running this sample, start a Tarantool-based configuration storage: [tarantool_config_storage](../tarantool_config_storage). + +To start all instances, execute the following command in the [centralized_config](../../../centralized_config) directory: + +```console +$ tt start config_storage +``` diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/config.yaml b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/config.yaml new file mode 100644 index 0000000000..9aaffa024b --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/config.yaml @@ -0,0 +1,19 @@ +config: + storage: + endpoints: + - uri: '127.0.0.1:4401' + login: sampleuser + password: '123456' + - uri: '127.0.0.1:4402' + login: sampleuser + password: '123456' + - uri: '127.0.0.1:4403' + login: sampleuser + password: '123456' + prefix: /myapp + timeout: 3 + reconnect_after: 5 + +# Watch key changes +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/instances.yml b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua new file mode 100644 index 0000000000..040d407963 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/config_storage/myapp.lua @@ -0,0 +1,6 @@ +net_box = require('net.box') +local conn = net_box.connect('127.0.0.1:4401') +local log = require('log') +conn:watch('config.storage:/myapp/config/all', function(key, value) + log.info("Configuration stored by the '/myapp/config/all' key is changed") +end) diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/README.md b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/README.md new file mode 100644 index 0000000000..2fecb3681c --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/README.md @@ -0,0 +1,11 @@ +# Setting up Tarantool configuration storage + +A sample application demonstrating how to set up Tarantool configuration storage. + +## Running + +To start all instances of the configuration storage, execute the following command in the [centralized_config](../../../centralized_config) directory: + +```console +$ tt start tarantool_config_storage +``` diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml new file mode 100644 index 0000000000..4ec249c420 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml @@ -0,0 +1,49 @@ +credentials: + users: + sampleuser: + password: '123456' + privileges: + - permissions: [ read, write ] + spaces: [ config_storage, config_storage_meta ] + - permissions: [ execute ] + universe: true + replicator: + password: 'topsecret' + roles: [ replication ] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: election + +database: + use_mvcc_engine: true + +groups: + group001: + replicasets: + replicaset001: + roles: [ config.storage ] + roles_cfg: + config.storage: + status_check_interval: 3 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:4401' + instance002: + iproto: + listen: + - uri: '127.0.0.1:4402' + instance003: + iproto: + listen: + - uri: '127.0.0.1:4403' + +# Interact with config storage +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/instances.yml b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua new file mode 100644 index 0000000000..7df22d09a4 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua @@ -0,0 +1,37 @@ +function put_config() + local fio = require('fio') + local cluster_config_handle = fio.open('../../source.yaml') + local cluster_config = cluster_config_handle:read() + local response = config.storage.put('/myapp/config/all', cluster_config) + cluster_config_handle:close() + return response +end + +function get_config_by_path() + local response = config.storage.get('/myapp/config/all') + return response +end + +function get_config_by_prefix() + local response = config.storage.get('/myapp/') + return response +end + +function make_txn_request() + local response = config.storage.txn({ + predicates = { { 'value', '==', 'v0', '/myapp/config/all' } }, + on_success = { { 'put', '/myapp/config/all', 'v1' } }, + on_failure = { { 'get', '/myapp/config/all' } } + }) + return response +end + +function delete_config() + local response = config.storage.delete('/myapp/config/all') + return response +end + +function delete_all_configs() + local response = config.storage.delete('/') + return response +end diff --git a/doc/code_snippets/snippets/centralized_config/source.yaml b/doc/code_snippets/snippets/centralized_config/source.yaml new file mode 100644 index 0000000000..24385b2265 --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/source.yaml @@ -0,0 +1,34 @@ +# A sample cluster config used to demonstrate a centralized configuration storage. +# Learn more: https://www.tarantool.io/en/doc/latest/concepts/configuration/configuration_etcd. +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' diff --git a/doc/code_snippets/snippets/centralized_config/tt.yaml b/doc/code_snippets/snippets/centralized_config/tt.yaml new file mode 100644 index 0000000000..e9cf7000cf --- /dev/null +++ b/doc/code_snippets/snippets/centralized_config/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/snippets/config/README.md b/doc/code_snippets/snippets/config/README.md new file mode 100644 index 0000000000..90dc3215b0 --- /dev/null +++ b/doc/code_snippets/snippets/config/README.md @@ -0,0 +1,11 @@ +# Configuration + +A sample application demonstrating various features related to Tarantool [configuration](https://www.tarantool.io/en/doc/latest/platform/configuration/). + +## Running + +To run applications placed in [instances.enabled](instances.enabled), go to the `config` directory in the terminal and execute the `tt start` command, for example: + +```console +$ tt start application +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml new file mode 100644 index 0000000000..5f44e0ec4a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml @@ -0,0 +1,14 @@ +app: + file: 'myapp.lua' + cfg: + greeting: 'Hello' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua new file mode 100644 index 0000000000..81322b1ead --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua @@ -0,0 +1,4 @@ +-- myapp.lua -- +local log = require('log').new("myapp") +local config = require('config') +log.info("%s from app, %s!", config:get('app.cfg.greeting'), box.info.name) diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role/config.yaml new file mode 100644 index 0000000000..2258022f07 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role/config.yaml @@ -0,0 +1,7 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ greeter ] diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/greeter.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role/greeter.lua new file mode 100644 index 0000000000..e49da0d052 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role/greeter.lua @@ -0,0 +1,6 @@ +-- greeter.lua -- +return { + validate = function() end, + apply = function() require('log').info("Hi from the 'greeter' role!") end, + stop = function() end, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua new file mode 100644 index 0000000000..f7cf4d2bad --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua @@ -0,0 +1,9 @@ +-- byeer.lua -- +local log = require('log').new("byeer") + +return { + dependencies = { 'greeter' }, + validate = function() end, + apply = function() log.info("Bye from the 'byeer' role!") end, + stop = function() end, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml new file mode 100644 index 0000000000..190cf800a5 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml @@ -0,0 +1,10 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ greeter ] + roles_cfg: + greeter: + greeting: 'Hi' diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua new file mode 100644 index 0000000000..0ce468c661 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua @@ -0,0 +1,28 @@ +-- greeter.lua -- +local log = require('log').new("greeter") +local schema = require('experimental.config.utils.schema') + +local greeter_schema = schema.new('greeter', schema.record({ + greeting = schema.scalar({ + type = 'string', + allowed_values = { 'Hi', 'Hello' } + }) +})) + +local function validate(cfg) + greeter_schema:validate(cfg) +end + +local function apply(cfg) + log.info("%s from the 'greeter' role!", greeter_schema:get(cfg, 'greeting')) +end + +local function stop() + log.info("The 'greeter' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/README.md b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/README.md new file mode 100644 index 0000000000..b62308fa1e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/README.md @@ -0,0 +1,28 @@ +# HTTP API + +A sample application showing how to implement a custom `http-api` role. + +## Running + +Before starting the application, install the `http` module by executing the `tt rocks install` command in the [config](../../../config) directory: + +```shell +$ tt rocks install http +``` + +Then, start the application: + +```shell +$ tt start application_role_http_api +``` + +## Making test requests + +To test the API, make the following requests: + +```console +$ curl -X GET --location "http://0.0.0.0:8080/band?limit=7" \ + -H "Accept: application/json" +$ curl -X GET --location "http://0.0.0.0:8080/band/5" \ + -H "Accept: application/json" +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml new file mode 100644 index 0000000000..76e7b9fe74 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml @@ -0,0 +1,11 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http-api ] + roles_cfg: + http-api: + host: '127.0.0.1' + port: 8080 diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/data.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/data.lua new file mode 100644 index 0000000000..775d00d668 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/data.lua @@ -0,0 +1,32 @@ +local data = {} + +data.add_sample_data = function() + box.watch('box.status', function() + if box.info.ro then + return + end + + box.schema.space.create('bands', { if_not_exists = true }) + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) + box.space.bands:create_index('band', { parts = { 'band_name' } }) + box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } }) + + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } + end) +end + +return data diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua new file mode 100644 index 0000000000..b5bb980963 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua @@ -0,0 +1,89 @@ +-- http-api.lua -- +local httpd +local json = require('json') +local schema = require('experimental.config.utils.schema') + +local function validate_host(host, w) + local host_pattern = "^(%d+)%.(%d+)%.(%d+)%.(%d+)$" + if not host:match(host_pattern) then + w.error("'host' should be a string containing a valid IP address, got %q", host) + end +end + +local function validate_port(port, w) + if port <= 1 or port >= 65535 then + w.error("'port' should be between 1 and 65535, got %d", port) + end +end + +local listen_address_schema = schema.new('listen_address', schema.record({ + host = schema.scalar({ + type = 'string', + validate = validate_host, + default = '127.0.0.1', + }), + port = schema.scalar({ + type = 'integer', + validate = validate_port, + default = 8080, + }), +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + if httpd then + httpd:stop() + end + local cfg_with_defaults = listen_address_schema:apply_default(cfg) + local host = listen_address_schema:get(cfg_with_defaults, 'host') + local port = listen_address_schema:get(cfg_with_defaults, 'port') + httpd = require('http.server').new(host, port) + local response_headers = { ['content-type'] = 'application/json' } + httpd:route({ path = '/band/:id', method = 'GET' }, function(req) + local id = req:stash('id') + local band_tuple = box.space.bands:get(tonumber(id)) + if not band_tuple then + return { status = 404, body = 'Band not found' } + else + local band = { id = band_tuple['id'], + band_name = band_tuple['band_name'], + year = band_tuple['year'] } + return { status = 200, headers = response_headers, body = json.encode(band) } + end + end) + httpd:route({ path = '/band', method = 'GET' }, function(req) + local limit = req:query_param('limit') + if not limit then + limit = 5 + end + local band_tuples = box.space.bands:select({}, { limit = tonumber(limit) }) + local bands = {} + for _, tuple in pairs(band_tuples) do + local band = { id = tuple['id'], + band_name = tuple['band_name'], + year = tuple['year'] } + table.insert(bands, band) + end + return { status = 200, headers = response_headers, body = json.encode(bands) } + end) + httpd:start() +end + +local function stop() + httpd:stop() +end + +local function init() + require('data'):add_sample_data() +end + +init() + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml new file mode 100644 index 0000000000..a1f6a2be38 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/config.yaml @@ -0,0 +1,17 @@ +audit_log: + to: file + file: 'audit_tarantool.log' + filter: [ user_create,data_operations,ddl,custom ] + format: json + spaces: [ bands ] + extract_key: true + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua new file mode 100644 index 0000000000..abd2380609 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua @@ -0,0 +1,51 @@ +-- myapp.lua -- + +-- Create space +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } }) + box.space.bands:create_index('secondary', { type = "tree", parts = { 'band_name' } }) + box.schema.user.grant('guest', 'read,write,execute', 'universe') +end +-- Insert data +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } +end + +local audit = require('audit') +-- Log message string +audit.log('Hello, Alice!') +-- Log format string and arguments +audit.log('Hello, %s!', 'Bob') +-- Log table with audit log field values +audit.log({ type = 'custom_hello', description = 'Hello, World!' }) +audit.log({ type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!' }) +-- Create a new log module +local my_audit = audit.new({ type = 'custom_hello', module = 'my_module' }) +my_audit:log('Hello, Alice!') +my_audit:log({ tag = 'admin', description = 'Hello, Bob!' }) + +-- Log 'Hello!' message with the VERBOSE severity level +audit.log({ severity = 'VERBOSE', description = 'Hello!' }) + +-- Log 'Hello!' message with a shortcut helper function +audit.verbose('Hello!') + +-- Like audit.log(), a shortcut helper function accepts a table of options +audit.verbose({ description = 'Hello!' }) + +-- Severity levels are available for custom loggers +local my_logger = audit.new({ module = 'my_module' }) +my_logger:log({ severity = 'ALARM', description = 'Alarm' }) +my_logger:alarm('Alarm') + +-- Overwrite session_type and remote fields +audit.log({ type = 'custom_hello', description = 'Hello!', + session_type = 'my_session', remote = 'my_remote' }) +-- End \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml new file mode 100644 index 0000000000..5dd84fefc6 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml @@ -0,0 +1,13 @@ +audit_log: + to: pipe + pipe: 'cronolog audit_tarantool.log' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_pipe/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml new file mode 100644 index 0000000000..5858d514bd --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml @@ -0,0 +1,18 @@ +audit_log: + to: syslog + syslog: + server: 'unix:/dev/log' + facility: 'user' + identity: 'tarantool_audit' + filter: [ audit, auth, priv, password_change, access_denied ] + extract_key: false + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/audit_log_syslog/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml new file mode 100644 index 0000000000..e12a18735c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml @@ -0,0 +1,17 @@ +conditional: + - if: tarantool_version < 3.1.0 + labels: + upgraded: 'false' + - if: tarantool_version >= 3.1.0 + labels: + upgraded: 'true' + compat: + box_error_serialize_verbose: 'new' + box_error_unpack_type_and_code: 'new' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: {} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/config.yaml new file mode 100644 index 0000000000..bd2f31e7f4 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/config.yaml @@ -0,0 +1,12 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/http_api.lua new file mode 100644 index 0000000000..5619769d6e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/http_api.lua @@ -0,0 +1,56 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local function validate_host(host, w) + local host_pattern = "^(%d+)%.(%d+)%.(%d+)%.(%d+)$" + if not host:match(host_pattern) then + w.error("'host' should be a string containing a valid IP address, got %q", host) + end +end + +local function validate_port(port, w) + if port <= 1 or port >= 65535 then + w.error("'port' should be between 1 and 65535, got %d", port) + end +end + +local listen_address_schema = schema.new('listen_address', schema.record({ + scheme = schema.scalar({ + type = 'string', + allowed_values = { 'http', 'https' }, + default = 'http', + }), + host = schema.scalar({ + type = 'string', + validate = validate_host, + default = '127.0.0.1', + }), + port = schema.scalar({ + type = 'integer', + validate = validate_port, + default = 8080, + }), +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local cfg_with_defaults = listen_address_schema:apply_default(cfg) + local scheme = listen_address_schema:get(cfg_with_defaults, 'scheme') + local host = listen_address_schema:get(cfg_with_defaults, 'host') + local port = listen_address_schema:get(cfg_with_defaults, 'port') + log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/api.lua new file mode 100644 index 0000000000..f73e2f3bcc --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/api.lua @@ -0,0 +1,51 @@ +-- api.lua -- +local log = require('log').new("api") +local schema = require('experimental.config.utils.schema') + +local listen_address = schema.record({ + scheme = schema.enum({ 'http', 'https' }), + host = schema.scalar({ type = 'string' }), + port = schema.scalar({ type = 'integer' }) +}, { + validate = function(data, w) + local protocol = w.schema.computed.annotations.protocol + if protocol == 'iproto' and data.scheme ~= nil then + w.error("iproto doesn't support 'scheme'") + end + end, +}) + +local http_listen_address_schema = schema.new('http_listen_address', schema.record({ + name = schema.scalar({ type = 'string' }), + listen_address = listen_address, +}, { + protocol = 'http', +})) + +local iproto_listen_address_schema = schema.new('iproto_listen_address', schema.record({ + name = schema.scalar({ type = 'string' }), + listen_address = listen_address, +}, { + protocol = 'iproto', +})) + +local function validate(cfg) + http_listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local scheme = http_listen_address_schema:get(cfg, 'listen_address.scheme') + local host = http_listen_address_schema:get(cfg, 'listen_address.host') + local port = http_listen_address_schema:get(cfg, 'listen_address.port') + log.info("API endpoint: %s://%s:%d", scheme, host, port) +end + +local function stop() + log.info("The 'api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/config.yaml new file mode 100644 index 0000000000..01db397f76 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/config.yaml @@ -0,0 +1,14 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ api ] + roles_cfg: + api: + name: 'HTTP listen address' + listen_address: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/config.yaml new file mode 100644 index 0000000000..bd2f31e7f4 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/config.yaml @@ -0,0 +1,12 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/http_api.lua new file mode 100644 index 0000000000..481603c893 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/http_api.lua @@ -0,0 +1,43 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new('listen_address', schema.record({ + scheme = schema.enum({ 'http', 'https' }, { env = 'HTTP_SCHEME' }), + host = schema.scalar({ type = 'string', env = 'HTTP_HOST' }), + port = schema.scalar({ type = 'integer', env = 'HTTP_PORT' }) +})) + +local function collect_env_cfg() + local res = {} + for _, w in listen_address_schema:pairs() do + local env_var = w.schema.env + if env_var ~= nil then + local value = schema.fromenv(env_var, os.getenv(env_var), w.schema) + listen_address_schema:set(res, w.path, value) + end + end + return res +end + +local function validate(cfg) + local env_cfg = collect_env_cfg() + local result_cfg = listen_address_schema:merge(cfg, env_cfg) + listen_address_schema:validate(result_cfg) +end + +local function apply(cfg) + local env_cfg = collect_env_cfg() + local result_cfg = listen_address_schema:merge(cfg, env_cfg) + log.info("HTTP API endpoint: %s://%s:%d", result_cfg.scheme, result_cfg.host, result_cfg.port) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/config.yaml new file mode 100644 index 0000000000..bd2f31e7f4 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/config.yaml @@ -0,0 +1,12 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/http_api.lua new file mode 100644 index 0000000000..0ab1ce4bfe --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/http_api.lua @@ -0,0 +1,40 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new( + "listen_address", + schema.record( + { + scheme = schema.enum({ "http", "https" }), + host = schema.scalar({ type = "string" }), + port = schema.scalar({ type = "integer" }) + } + ), + { + methods = { + format = function(_self, url) + return string.format("%s://%s:%d", url.scheme, url.host, url.port) + end + } + } +) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local url_string = listen_address_schema:format(cfg) + log.info("HTTP API endpoint: %s", url_string) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/config.yaml new file mode 100644 index 0000000000..2b49dc5420 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/config.yaml @@ -0,0 +1,15 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http-api ] + roles_cfg: + http-api: + - host: '127.0.0.1' + port: 8080 + scheme: 'http' + - host: '127.0.0.1' + port: 8443 + scheme: 'https' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/http-api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/http-api.lua new file mode 100644 index 0000000000..ae7cb6ccf7 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/http-api.lua @@ -0,0 +1,34 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new('listen_address', schema.array({ + items = schema.record({ + scheme = schema.enum({ 'http', 'https' }), + host = schema.scalar({ type = 'string' }), + port = schema.scalar({ type = 'integer' }) + }) +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + for _, uri in ipairs(cfg) do + local scheme = uri.scheme + local host = uri.host + local port = uri.port + log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port) + end +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/config.yaml new file mode 100644 index 0000000000..55edfabbb5 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/config.yaml @@ -0,0 +1,16 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + host: '127.0.0.1' + port: 8080 + scheme: 'http' + endpoints: + user: true + order: true + customer: false diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/http_api.lua new file mode 100644 index 0000000000..99c52e488b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/http_api.lua @@ -0,0 +1,37 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new('listen_address', schema.record({ + scheme = schema.enum({ 'http', 'https' }), + host = schema.scalar({ type = 'string' }), + port = schema.scalar({ type = 'integer' }), + endpoints = schema.map({ key = schema.scalar({ type = 'string' }), + value = schema.scalar({ type = 'boolean' }) }) +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local scheme = listen_address_schema:get(cfg, 'scheme') + local host = listen_address_schema:get(cfg, 'host') + local port = listen_address_schema:get(cfg, 'port') + local endpoints = listen_address_schema:get(cfg, 'endpoints') + for name, value in pairs(endpoints) do + if value then + log.info("HTTP API endpoint: %s://%s:%d/%s", scheme, host, port, name) + end + end +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_map/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/config.yaml new file mode 100644 index 0000000000..bd2f31e7f4 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/config.yaml @@ -0,0 +1,12 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/http_api.lua new file mode 100644 index 0000000000..46e3f13933 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/http_api.lua @@ -0,0 +1,30 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new('listen_address', schema.record({ + scheme = schema.enum({ 'http', 'https' }), + host = schema.scalar({ type = 'string' }), + port = schema.scalar({ type = 'integer' }) +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local scheme = listen_address_schema:get(cfg, 'scheme') + local host = listen_address_schema:get(cfg, 'host') + local port = listen_address_schema:get(cfg, 'port') + log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/config.yaml new file mode 100644 index 0000000000..d5d003f21f --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/config.yaml @@ -0,0 +1,13 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: + listen_address: + host: '127.0.0.1' + port: 8080 + scheme: 'http' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/http_api.lua new file mode 100644 index 0000000000..12102a3a6b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/http_api.lua @@ -0,0 +1,32 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local listen_address_schema = schema.new('listen_address', schema.record({ + listen_address = schema.record({ + scheme = schema.enum({ 'http', 'https' }), + host = schema.scalar({ type = 'string' }), + port = schema.scalar({ type = 'integer' }) + }) +})) + +local function validate(cfg) + listen_address_schema:validate(cfg) +end + +local function apply(cfg) + local scheme = listen_address_schema:get(cfg, 'listen_address.scheme') + local host = listen_address_schema:get(cfg, 'listen_address.host') + local port = listen_address_schema:get(cfg, 'listen_address.port') + log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_record_hierarchy/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/config.yaml new file mode 100644 index 0000000000..2d56515801 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + roles: [ http_api ] + roles_cfg: + http_api: 'http://127.0.0.1:8080' diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/http_api.lua b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/http_api.lua new file mode 100644 index 0000000000..c8aea6e018 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/http_api.lua @@ -0,0 +1,24 @@ +-- http_api.lua -- +local log = require('log').new("http_api") +local schema = require('experimental.config.utils.schema') + +local http_api_schema = schema.new('http_api', schema.scalar({ type = 'string' })) + +local function validate(cfg) + http_api_schema:validate(cfg) +end + +local function apply(cfg) + local http_api_cfg = http_api_schema:get(cfg) + log.info("HTTP API endpoint: %s", http_api_cfg) +end + +local function stop() + log.info("The 'http_api' role is stopped") +end + +return { + validate = validate, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_scalar/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md b/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md new file mode 100644 index 0000000000..31cf4036e5 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md @@ -0,0 +1,11 @@ +# Creating your first Tarantool database + +A sample application created in the [Creating your first Tarantool database](https://www.tarantool.io/en/doc/latest/getting_started/getting_started_db/) tutorial. + +## Running + +To start an instance, execute the following command in the [config](../../../config) directory: + +```console +$ tt start create_db +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml new file mode 100644 index 0000000000..7aeaa6ed21 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/create_db/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/create_db/instances.yml new file mode 100644 index 0000000000..9d7cb5e7c2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/instances.yml @@ -0,0 +1 @@ +instance001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md new file mode 100644 index 0000000000..251d6a3b60 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/README.md @@ -0,0 +1,11 @@ +# Credentials + +A sample application demonstrating how configure user credentials in a YAML configuration. + +## Running + +Start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml new file mode 100644 index 0000000000..d771d4f153 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/config.yaml @@ -0,0 +1,30 @@ +credentials: + users: + dbadmin: + password: 'T0p_Secret_P@$$w0rd' + roles: [ super ] + sampleuser: + password: '123456' + roles: [ writers_space_reader ] + privileges: + - permissions: [ read, write ] + spaces: [ books ] + roles: + writers_space_reader: + privileges: + - permissions: [ read ] + spaces: [ writers ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + +# Load sample data +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua new file mode 100644 index 0000000000..d316d69e97 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/myapp.lua @@ -0,0 +1,36 @@ +function create_spaces() + box.schema.space.create('writers') + box.space.writers:format({ + { name = 'id', type = 'unsigned' }, + { name = 'name', type = 'string' } + }) + box.space.writers:create_index('primary', { parts = { 'id' } }) + + box.schema.space.create('books') + box.space.books:format({ + { name = 'id', type = 'unsigned' }, + { name = 'title', type = 'string' }, + { name = 'author_id', foreign_key = { space = 'writers', field = 'id' } }, + }) + box.space.books:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.writers:insert { 1, 'Leo Tolstoy' } + box.space.writers:insert { 2, 'Fyodor Dostoevsky' } + box.space.writers:insert { 3, 'Alexander Pushkin' } + + box.space.books:insert { 1, 'War and Peace', 1 } + box.space.books:insert { 2, 'Anna Karenina', 1 } + box.space.books:insert { 3, 'Resurrection', 1 } + box.space.books:insert { 4, 'Crime and Punishment', 2 } + box.space.books:insert { 5, 'The Idiot', 2 } + box.space.books:insert { 6, 'The Brothers Karamazov', 2 } + box.space.books:insert { 7, 'Eugene Onegin', 3 } + box.space.books:insert { 8, 'The Captain\'s Daughter', 3 } + box.space.books:insert { 9, 'Boris Godunov', 3 } + box.space.books:insert { 10, 'Ruslan and Ludmila', 3 } +end + +create_spaces() +load_data() diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_all.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_all.yaml new file mode 100644 index 0000000000..70439cbeb9 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_all.yaml @@ -0,0 +1,7 @@ +# empty permissions array: +privileges: +- permissions: [] # !! read permission revoked !! + spaces: [books] + +# empty privileges array: + privileges: [] # !! no privileges at all !! diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_one.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_one.yaml new file mode 100644 index 0000000000..4678703d23 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials/revoke_one.yaml @@ -0,0 +1,9 @@ +# grant privileges: +privileges: +- permissions: [read, write] + spaces: [books] + +# revoke a privilege: + privileges: + - permissions: [read] # !! write permission revoked !! + spaces: [books] diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md new file mode 100644 index 0000000000..3e63c1498a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/README.md @@ -0,0 +1,18 @@ +# Credentials: environment variables + +A sample application demonstrating how set passwords in a YAML configuration using environment variables. + +## Running + +Before starting instances, set the `DBADMIN_PASSWORD` and `SAMPLEUSER_PASSWORD` environment variables, for example: + +```console +$ export DBADMIN_PASSWORD='T0p_Secret_P@$$w0rd' +$ export SAMPLEUSER_PASSWORD='123456' +``` + +Then, start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials_context_env +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml new file mode 100644 index 0000000000..017190f28c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml @@ -0,0 +1,25 @@ +config: + context: + dbadmin_password: + from: env + env: DBADMIN_PASSWORD + sampleuser_password: + from: env + env: SAMPLEUSER_PASSWORD + +credentials: + users: + dbadmin: + password: '{{ context.dbadmin_password }}' + sampleuser: + password: '{{ context.sampleuser_password }}' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_env/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md new file mode 100644 index 0000000000..7a76cd0296 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/README.md @@ -0,0 +1,11 @@ +# Credentials: files + +A sample application demonstrating how load passwords to a YAML configuration from files. + +## Running + +Start the application by executing the following command in the [config](../../../config) directory: + +```console +$ tt start credentials_context_file +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml new file mode 100644 index 0000000000..20354193c7 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml @@ -0,0 +1,27 @@ +config: + context: + dbadmin_password: + from: file + file: secrets/dbadmin_password.txt + rstrip: true + sampleuser_password: + from: file + file: secrets/sampleuser_password.txt + rstrip: true + +credentials: + users: + dbadmin: + password: '{{ context.dbadmin_password }}' + sampleuser: + password: '{{ context.sampleuser_password }}' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt new file mode 100644 index 0000000000..3c0da6017c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/dbadmin_password.txt @@ -0,0 +1 @@ +T0p_Secret_P@$$w0rd \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt new file mode 100644 index 0000000000..4632e068d5 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/credentials_context_file/secrets/sampleuser_password.txt @@ -0,0 +1 @@ +123456 \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml new file mode 100644 index 0000000000..32f2552513 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/config.yaml @@ -0,0 +1,17 @@ +flightrec: + enabled: true + logs_size: 10485800 + logs_log_level: 5 + metrics_period: 240 + metrics_interval: 0.5 + requests_size: 10485780 + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/flightrec/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/force_recovery/README.md b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/README.md new file mode 100644 index 0000000000..9eb681ec5b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/README.md @@ -0,0 +1,18 @@ +# Force recovery + +A sample application demonstrating how to start an instance with a corrupted write-ahead log file. + +## Running + +- To start the instance using the `tt` utility, execute the following command in the [config](../../../config) directory: + + ```console + $ TT_FORCE_RECOVERY=true tt start force_recovery + ``` + +- To start the instance using the `tarantool` command, you can use both the `TT_FORCE_RECOVERY` environment variable and add the `--force-recovery` option. + In the example below, the `tarantool` command is executed in the [config/instances.enabled/force_recovery](../../../config/instances.enabled/force_recovery) directory: + + ```console + $ tarantool --name instance001 --config config.yaml --force-recovery -i + ``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/force_recovery/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/config.yaml new file mode 100644 index 0000000000..69ccf58c8c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/force_recovery/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.snap b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.snap new file mode 100644 index 0000000000..43e18b2355 Binary files /dev/null and b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.snap differ diff --git a/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.xlog b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.xlog new file mode 100644 index 0000000000..d9b4e6642f Binary files /dev/null and b/doc/code_snippets/snippets/config/instances.enabled/force_recovery/var/lib/instance001/00000000000000000000.xlog differ diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml new file mode 100644 index 0000000000..43236de99d --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml @@ -0,0 +1,10 @@ +iproto: + listen: + - uri: '127.0.0.1:3301' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: { } \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml new file mode 100644 index 0000000000..b2b27c78a6 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + iproto: + listen: + - uri: '127.0.0.1:3301' + replicasets: + replicaset001: + instances: + instance001: { } \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/config.yaml new file mode 100644 index 0000000000..94082e0729 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/config.yaml @@ -0,0 +1,15 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + database: + hot_standby: true + wal: + dir: /tmp/wals + snapshot: + dir: /tmp/snapshots + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_1/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/config.yaml new file mode 100644 index 0000000000..94082e0729 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/config.yaml @@ -0,0 +1,15 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + database: + hot_standby: true + wal: + dir: /tmp/wals + snapshot: + dir: /tmp/snapshots + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/hot_standby_2/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml new file mode 100644 index 0000000000..7aeaa6ed21 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config_annotated.yaml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config_annotated.yaml new file mode 100644 index 0000000000..610e8ec76f --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config_annotated.yaml @@ -0,0 +1,11 @@ +# yaml-language-server: $schema=https://download.tarantool.org/tarantool/schema/config.schema.json + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml new file mode 100644 index 0000000000..dd03d061ba --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml new file mode 100644 index 0000000000..79b0474a16 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml @@ -0,0 +1,16 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + - uri: '127.0.0.1:3302' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml new file mode 100644 index 0000000000..6bfa766771 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml new file mode 100644 index 0000000000..e2bacce8bc --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: 'unix/:./var/run/{{ instance_name }}/tarantool.iproto' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml new file mode 100644 index 0000000000..aed96e565d --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml @@ -0,0 +1,10 @@ +groups: + g: + replicasets: + r: + instances: + i-001: {} + i-002: {} + i-003: {} + i-004: + isolated: true diff --git a/doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml new file mode 100644 index 0000000000..e64da49b39 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml @@ -0,0 +1,12 @@ +groups: + group001: + replicasets: + replicaset001: + labels: + dc: 'east' + production: 'false' + instances: + instance001: + labels: + rack: '10' + production: 'true' diff --git a/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua new file mode 100644 index 0000000000..5b8745ed3b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua @@ -0,0 +1,16 @@ +ffi = require('ffi') + +-- Prints 'info' messages -- +ffi.C._say(ffi.C.S_INFO, nil, 0, nil, 'Info message from C module') +--[[ +[6024] main/103/interactive I> Info message from C module +--- +... +--]] + +-- Swallows 'debug' messages -- +ffi.C._say(ffi.C.S_DEBUG, nil, 0, nil, 'Debug message from C module') +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml new file mode 100644 index 0000000000..746232c06e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml @@ -0,0 +1,15 @@ +log: + modules: + tarantool: 'info' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_c_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua new file mode 100644 index 0000000000..fec680ad97 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua @@ -0,0 +1,17 @@ +module1 = require('test.module1') +module2 = require('test.module2') + +-- Prints 'info' messages -- +module1.say_hello() +--[[ +[92617] main/103/interactive/test.logging.module1 I> Info message from module1 +--- +... +--]] + +-- Swallows 'info' messages -- +module2.say_hello() +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml new file mode 100644 index 0000000000..525bf902c2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml @@ -0,0 +1,16 @@ +log: + modules: + test.module1: 'verbose' + test.module2: 'error' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua new file mode 100644 index 0000000000..008a03b099 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua @@ -0,0 +1,6 @@ +return { + say_hello = function() + local log = require('log') + log.info('Info message from module1') + end +} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua new file mode 100644 index 0000000000..6f36de4e47 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module2.lua @@ -0,0 +1,6 @@ +return { + say_hello = function() + local log = require('log') + log.info('Info message from module2') + end +} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml new file mode 100644 index 0000000000..d16fb8fd1a --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_file/config.yaml @@ -0,0 +1,13 @@ +log: + to: file + file: var/log/{{ instance_name }}/instance.log + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_file/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml new file mode 100644 index 0000000000..dcc4f37926 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_level/config.yaml @@ -0,0 +1,12 @@ +log: + level: 'verbose' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_level/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua new file mode 100644 index 0000000000..d58f85c8a8 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua @@ -0,0 +1,25 @@ +-- Creates new loggers -- +module1_log = require('log').new('module1') +module2_log = require('log').new('module2') + +-- Prints 'info' messages -- +module1_log.info('Info message from module1') +--[[ +[16300] main/103/interactive/module1 I> Info message from module1 +--- +... +--]] + +-- Swallows 'debug' messages -- +module1_log.debug('Debug message from module1') +--[[ +--- +... +--]] + +-- Swallows 'info' messages -- +module2_log.info('Info message from module2') +--[[ +--- +... +--]] diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml new file mode 100644 index 0000000000..302ae2364e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml @@ -0,0 +1,16 @@ +log: + modules: + module1: 'verbose' + module2: 'error' +app: + file: 'app.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_new_modules/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml new file mode 100644 index 0000000000..4e53e27c03 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml @@ -0,0 +1,13 @@ +log: + to: pipe + pipe: 'cronolog tarantool.log' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_pipe/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml new file mode 100644 index 0000000000..904342fa52 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml @@ -0,0 +1,15 @@ +log: + to: syslog + syslog: + server: '127.0.0.1:514' +# server: 'unix:/dev/log' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/log_syslog/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/lua_call/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/lua_call/config.yaml new file mode 100644 index 0000000000..114b4005d1 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/lua_call/config.yaml @@ -0,0 +1,6 @@ +credentials: + users: + alice: + privileges: + - permissions: [execute] + lua_call: [my_func, my_func2] diff --git a/doc/code_snippets/snippets/config/instances.enabled/memtx/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/memtx/config.yaml new file mode 100644 index 0000000000..604f4b2f74 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/memtx/config.yaml @@ -0,0 +1,14 @@ +memtx: + memory: 1073741824 + min_tuple_size: 8 + max_tuple_size: 5242880 + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/memtx/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/memtx/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/memtx/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/README.md b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/README.md new file mode 100644 index 0000000000..fef01516ca --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/README.md @@ -0,0 +1,11 @@ +# Collecting custom metrics + +A sample application showing how to collect custom [metrics](https://www.tarantool.io/doc/latest/book/monitoring/). + +## Running + +Start the application by executing the following command in the [config](../../../config) directory: + +```shell +$ tt start metrics_collect_custom +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/config.yaml new file mode 100644 index 0000000000..54bf57667e --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/config.yaml @@ -0,0 +1,20 @@ +metrics: + include: [ all ] + exclude: [ vinyl ] + labels: + alias: '{{ instance_name }}' +roles: +- examples.collect_custom_replace_count +- examples.collect_custom_waste_size +app: + file: 'load_data.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_replace_count.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_replace_count.lua new file mode 100644 index 0000000000..a15d81a4bf --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_replace_count.lua @@ -0,0 +1,22 @@ +local function apply() + -- Collect a custom metric at an arbitrary moment in time -- + local metrics = require('metrics') + local bands_replace_count = metrics.counter('bands_replace_count', 'The number of data operations') + local trigger = require('trigger') + trigger.set( + 'box.space.bands.on_replace', + 'update_bands_replace_count_metric', + function(_, _, _, request_type) + bands_replace_count:inc(1, { request_type = request_type }) + end + ) + -- End -- +end + +return { + validate = function() + end, + apply = apply, + stop = function() + end, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_waste_size.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_waste_size.lua new file mode 100644 index 0000000000..520975b468 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/examples/collect_custom_waste_size.lua @@ -0,0 +1,17 @@ +local function apply() + -- Collect a custom metric when the data collected by metrics is requested -- + local metrics = require('metrics') + local bands_waste_size = metrics.gauge('bands_waste_size', 'The size of memory wasted due to internal fragmentation') + metrics.register_callback(function() + bands_waste_size:set(box.space.bands:stat()['tuple']['memtx']['waste_size']) + end) + -- End -- +end + +return { + validate = function() + end, + apply = apply, + stop = function() + end, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/load_data.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/load_data.lua new file mode 100644 index 0000000000..cc721d61a3 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_custom/load_data.lua @@ -0,0 +1,25 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end + +create_space() +load_data() diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/README.md b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/README.md new file mode 100644 index 0000000000..95fbea43a3 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/README.md @@ -0,0 +1,17 @@ +# Collecting HTTP metrics + +A sample application showing how to enable and configure [metrics](https://www.tarantool.io/doc/latest/book/monitoring/) in your application. + +## Running + +Before starting the application, install the `http` module by executing the `tt rocks install` command in the [config](../../../config) directory: + +```shell +$ tt rocks install http +``` + +Then, start the application: + +```shell +$ tt start metrics_collect_http +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/collect_http_metrics.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/collect_http_metrics.lua new file mode 100644 index 0000000000..2e57785196 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/collect_http_metrics.lua @@ -0,0 +1,34 @@ +local httpd + +local function apply() + if httpd then + httpd:stop() + end + + -- Collect HTTP metrics for the '/metrics/hello' route -- + httpd = require('http.server').new('127.0.0.1', 8080) + local metrics = require('metrics') + metrics.http_middleware.configure_default_collector('summary') + httpd:route({ + method = 'GET', + path = '/metrics/hello' + }, metrics.http_middleware.v1( + function() + return { status = 200, + headers = { ['content-type'] = 'text/plain' }, + body = 'Hello from http_middleware!' } + end)) + + httpd:start() +end + +local function stop() + httpd:stop() +end + +return { + validate = function() + end, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/config.yaml new file mode 100644 index 0000000000..2697252750 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/config.yaml @@ -0,0 +1,17 @@ +metrics: + include: [ all ] + exclude: [ vinyl ] + labels: + alias: '{{ instance_name }}' +roles: +- collect_http_metrics + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_collect_http/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/README.md b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/README.md new file mode 100644 index 0000000000..11c9d7705d --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/README.md @@ -0,0 +1,29 @@ +# Exposing metrics using plugins + +A sample application showing how to use [metrics](https://www.tarantool.io/doc/latest/book/monitoring/) plugins for exposing metrics. + +## Running + +Before starting the application, install the `http` module by executing the `tt rocks install` command in the [config](../../../config) directory: + +```shell +$ tt rocks install http +``` + +Then, start the application: + +```shell +$ tt start metrics_plugins +``` + +To get Prometheus metrics, make the following request: + +```console +$ curl -X GET --location "http://127.0.0.1:8080/metrics/prometheus" +``` + +To get metrics in the JSON format, make the following request: + +```console +$ curl -X GET --location "http://127.0.0.1:8081/metrics/json" +``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/config.yaml new file mode 100644 index 0000000000..fde2bf723f --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/config.yaml @@ -0,0 +1,18 @@ +metrics: + include: [ all ] + exclude: [ vinyl ] + labels: + alias: '{{ instance_name }}' +roles: +- examples.expose_prometheus_metrics +- examples.expose_json_metrics + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_json_metrics.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_json_metrics.lua new file mode 100644 index 0000000000..411f32014f --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_json_metrics.lua @@ -0,0 +1,32 @@ +local httpd + +local function apply() + if httpd then + httpd:stop() + end + + -- Expose JSON metrics -- + httpd = require('http.server').new('127.0.0.1', 8081) + httpd:route({ + method = 'GET', + path = '/metrics/json' + }, function() + local json_plugin = require('metrics.plugins.json') + local json_metrics = json_plugin.export() + return { status = 200, + headers = { ['content-type'] = 'application/json' }, + body = json_metrics } + end) + httpd:start() +end + +local function stop() + httpd:stop() +end + +return { + validate = function() + end, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_prometheus_metrics.lua b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_prometheus_metrics.lua new file mode 100644 index 0000000000..c812df8598 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/examples/expose_prometheus_metrics.lua @@ -0,0 +1,30 @@ +local httpd + +local function apply() + if httpd then + httpd:stop() + end + + -- Expose Prometheus metrics -- + httpd = require('http.server').new('127.0.0.1', 8080) + httpd:route({ + method = 'GET', + path = '/metrics/prometheus' + }, function() + local prometheus_plugin = require('metrics.plugins.prometheus') + local prometheus_metrics = prometheus_plugin.collect_http() + return prometheus_metrics + end) + httpd:start() +end + +local function stop() + httpd:stop() +end + +return { + validate = function() + end, + apply = apply, + stop = stop, +} diff --git a/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/metrics_plugins/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/mysql/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/mysql/config.yaml new file mode 100644 index 0000000000..74f3ca8cbc --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/mysql/config.yaml @@ -0,0 +1,12 @@ +app: + file: 'myapp.lua' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/mysql/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/mysql/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/mysql/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/mysql/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/mysql/myapp.lua new file mode 100644 index 0000000000..c328d21022 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/mysql/myapp.lua @@ -0,0 +1,17 @@ +-- myapp.lua -- + +box.schema.user.grant('guest', 'read,write,execute', 'universe') + +local function bootstrap() + if not box.space.mysqldaemon then + s = box.schema.space.create('mysqldaemon') + s:create_index('primary', + { type = 'tree', parts = { 1, 'unsigned' }, if_not_exists = true }) + end + if not box.space.mysqldata then + t = box.schema.space.create('mysqldata') + t:create_index('primary', + { type = 'tree', parts = { 1, 'unsigned' }, if_not_exists = true }) + end +end +bootstrap() diff --git a/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml new file mode 100644 index 0000000000..ac71476864 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml @@ -0,0 +1,15 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + snapshot: + dir: 'var/lib/{{ instance_name }}/snapshots' + count: 3 + by: + interval: 7200 + wal_size: 1000000000000000000 + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/instances.yml new file mode 100644 index 0000000000..9d7cb5e7c2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/persistence_snapshot/instances.yml @@ -0,0 +1 @@ +instance001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml new file mode 100644 index 0000000000..a073a3f2e2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml @@ -0,0 +1,21 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + wal: + dir: 'var/lib/{{ instance_name }}/wals' + mode: 'write' + dir_rescan_delay: 3 + cleanup_delay: 18000 + max_size: 268435456 + ext: + new: true + old: true + spaces: + bands: + old: false + iproto: + listen: + - uri: '127.0.0.1:3301' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/instances.yml new file mode 100644 index 0000000000..9d7cb5e7c2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/persistence_wal/instances.yml @@ -0,0 +1 @@ +instance001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml new file mode 100644 index 0000000000..db5a998c55 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml @@ -0,0 +1,9 @@ +groups: + group001: + replicasets: + replicaset001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instances: + instance001: { } \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/generate.sh b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/generate.sh new file mode 100644 index 0000000000..877f798985 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/generate.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -xeuo pipefail + +# 1. Generate an unencrypted server key. +openssl genrsa -out server.key 2048 + +# 2. Create a certificate signing request based on the server key. +openssl req -new -key server.key -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server/" -out server.csr + +# 3. Generate a server certificate. +openssl x509 -req -in server.csr -signkey server.key -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -out server.crt diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.crt b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.crt new file mode 100644 index 0000000000..1cef7b4fe9 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDhTCCAm2gAwIBAgIUM0cXJSowqJRoJlpwxgJBpS1V7KkwDQYJKoZIhvcNAQEL +BQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5 +MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UEAwwGc2VydmVy +MCAXDTI0MDExMjE0MTc1NFoYDzIxMDAwMTAxMTQxNzU0WjBcMQswCQYDVQQGEwJV +UzEOMAwGA1UECAwFU3RhdGUxDTALBgNVBAcMBENpdHkxHTAbBgNVBAoMFEV4YW1w +bGUtQ2VydGlmaWNhdGVzMQ8wDQYDVQQDDAZzZXJ2ZXIwggEiMA0GCSqGSIb3DQEB +AQUAA4IBDwAwggEKAoIBAQCekLkd2cXQfgRDBJK0LIEfzeH0C/AqQPr58qc3+A9i +MxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6cLcFPObd0XkDUbXQW1i2/BWI6ai3 +7FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxxEQqnr+K2+EhbqWfS88Gf5+1kWvJq +AyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBNqq9RQL+AcIdl5UFSApmnzOFDCdiK +qnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIBbvdsvGD7ONqewqdGC0xSa4Xx+XJn +8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnuRQ8FQifxAgMBAAGjPTA7MBoGA1Ud +EQQTMBGCCWxvY2FsaG9zdIcEfwAAATAdBgNVHQ4EFgQU6oCAZ+kJ88rox7OFt/tr +GIYQVFYwDQYJKoZIhvcNAQELBQADggEBABvev81NhG1DR5mS4UbpEvl6NGtcDE4H +yVKPpI3gfdJ3etZhV2FQ7nZZzQcTaqsm2IMr336s+nb4wrqDkZJ+OhYsU1OgFF3b +DM0BJ91YUeZz/redx7naxhawHn1BKXDvseNrH9C+XKa+1maK7bCYLkZZEtiOYZku +yD4pfBx+A+zipas3iQdLiXDkg+qoY2OmO+9bo+tvV8zzVx7V0+8L/NU8bU2d/Dgb +IuEPKc98hVx1W1v4RndrUmcneovbBEv82Y17RUqTi42TumsYjOjx/LvdD7RKBDZw +XVtjKL+zwuge9rQU4sZMAwN/tHanOXAfWG6/LU5RNW87b8+YcwOxMVc= +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.csr b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.csr new file mode 100644 index 0000000000..1c370f7281 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.csr @@ -0,0 +1,17 @@ +-----BEGIN CERTIFICATE REQUEST----- +MIICoTCCAYkCAQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYD +VQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UE +AwwGc2VydmVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnpC5HdnF +0H4EQwSStCyBH83h9AvwKkD6+fKnN/gPYjMWz6rs6v9u9kKgM09WF2FRzYy9EM8x +P9W7enC3BTzm3dF5A1G10FtYtvwViOmot+xS7Oqn6OzAPlEEwOWtIzayhldU3LSW +nuHccREKp6/itvhIW6ln0vPBn+ftZFryagMlDfNDc7rezIHwCjyxJ0Hou5hgZPlE +6N0gTaqvUUC/gHCHZeVBUgKZp8zhQwnYiqp8PZ7SKCVCIfpAFD8jWd9mqMPQQUQv +/YmyAW73bLxg+zjansKnRgtMUmuF8flyZ/JQU0xa8nOg+gvSq0QFf2O3IaCuEbJ9 +hi3J7kUPBUIn8QIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAF2jrSsrQyfET0Ux +SEeuyJemaLp8CYGbaICDIpM5jvq43ZGDKzQWqZGgOe2QmKR4mOqe2ixr3duwjpaK +Yd3eqQCMYkW9s5QdIs4AasQVMJXZ8uL5gIuFPtAT5BNa8GAhmpfUvHlLQeobZX4N +NpYaZZTLvQkjqnxOU9OQfnQ/89sa5zi8+G9xgWPnu3BOBznZvWsqcIVPZAekafvd +iP78wBWn9aF9CYrUvCmMmLgmwUe4BC3Lo4MvkosMFFH96oqrOPBztMv8swYGJBY8 +WFv1aJ8AtxpF9IGIDaP58TT0eEg/pDLGtPdaH4Q4TP9WkAs8Ybgn331xSmDDidLl +WQFHHXY= +-----END CERTIFICATE REQUEST----- diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.key b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.key new file mode 100644 index 0000000000..3c4abdba42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.key @@ -0,0 +1,28 @@ +-----BEGIN PRIVATE KEY----- +MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCekLkd2cXQfgRD +BJK0LIEfzeH0C/AqQPr58qc3+A9iMxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6 +cLcFPObd0XkDUbXQW1i2/BWI6ai37FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxx +EQqnr+K2+EhbqWfS88Gf5+1kWvJqAyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBN +qq9RQL+AcIdl5UFSApmnzOFDCdiKqnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIB +bvdsvGD7ONqewqdGC0xSa4Xx+XJn8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnu +RQ8FQifxAgMBAAECggEAM20OjK7faCImsbGe/s5cRntYZ/UjPCD9BOl88DsEij21 +jT6LPh//1eB/4oQ9kLGgfUDC5Nu9xk1EU46Q3SMGYTSZwcjTZbLqj9YsCc52SMhd +kLb+JB38r3lJSGJ1B7GqrsVOIZJ0My1feFAlm4MAzYSyuv+zS4iA6KKorF6OtnCx +RIvWTWrQM0yIxm8HBpNu1hFLqr7QV57u18pz6zSnBTd5VTYivQQkv7JWR5ci2Hry +4yjVfwwh8Xcm8i8S+BZZ1hsVrVsoKmjMyqbj/Lrnx4/MsfCG3WQOL/ZP38w+z+Ds +XptopV3/ZKC8Dnyf3x7HyJ0uDGD0fAzxtdCslk3TrQKBgQC1nzyDX2i/uZlhK+3T +Nkj1LFakANY8yIY3AfPVJROuA+KERAkuTJfRfSxDUkE9QJyxy0S2DUSq2pOov33Q +6NH0wNEjCFRoXGqCgkNPbwECwJtKQWwsrHHpZZCINH7TyWCUi9p4tcAzww7UyUDT +JiJP7iOvxMCB8ebNca6rQ0xI+wKBgQDfgEj+PI8kXCP4qk2xcVJ+yOkwoSWoBS0s +KBV5pGgbO12NPDHal5ZWLpCZMi3Cw0gObEj5mYbcj+fkmk9xKhuxtfo4DQaAP5y4 +VnoXsaAwryLqG/iby3zAFkspN+5hoD8hmDXHrqrqC7AOmPrrAHIQHdt11TCBheEY +UuK+xrBXAwKBgE/+R4fRQPCYzW5YC9KoKTAbDDoFyFZTN5IIwR1SzD0rptv8n1KO +F5wEFre8BdH1oE5KqgPJCkJ6LOj5FnAp6zdyqWpVo9+nPJ4ow3679GUC8iKdeAih +FzbmLedfv7CGFIy4oEvkOThTJDgiP/P/6sLrrzoeXW+eXLqF5Jm39WR7AoGAYqSf +Er6turGEGtMneUJ304dfDFyDXzXxqwSB/e8nF6XK83P22PCApMbmgQbZlZVU7zCx +wKAXGq/U/Fty5pJcKMIVjrmI/f+VbvKT7nMyLWqO8V6pCjH0fF8aizWpW6M7Wdtx +GRGpU6UW7kpsrF3E+gIDg201fGUXZQHoG6Vb3PsCgYBRgDDKXXD0dKqU9GzO/og7 +WpJOZqI+OZoG778aP2HqQ8z9m93nQ0NTzXK8rRNDSEbd+QFFf9s5Y5gjjK5bsNUJ +mDziJ7B8tP2ecLcuO5DF2ro9nCPPYNixViKqZ1oJAFEIFetZzp7ZB6PFf7tcnXJ3 +aqTpCZBW2gL5iktwXYz+DA== +-----END PRIVATE KEY----- diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml new file mode 100644 index 0000000000..688b64e2fe --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml @@ -0,0 +1,25 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +security: + auth_type: 'pap-sha256' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua new file mode 100644 index 0000000000..692796caaa --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua @@ -0,0 +1,10 @@ +function connect() + local connection = require('net.box').connect({ + uri = 'admin:topsecret@127.0.0.1:3301', + params = { auth_type = 'pap-sha256', + transport = 'ssl', + ssl_cert_file = 'certs/server.crt', + ssl_key_file = 'certs/server.key' } + }) + return connection +end diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml new file mode 100644 index 0000000000..2a3e8a432d --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml @@ -0,0 +1,20 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +security: + auth_delay: 10 + auth_retries: 2 + disable_guest: true + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml new file mode 100644 index 0000000000..eb673159af --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml @@ -0,0 +1,24 @@ +credentials: + users: + admin: + password: 'T0p_Secret_P@$$w0rd' + roles: [ super ] + +security: + password_min_length: 16 + password_enforce_lowercase: true + password_enforce_uppercase: true + password_enforce_digits: true + password_enforce_specialchars: true + password_lifetime_days: 365 + password_history_length: 3 + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/README.md b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/README.md new file mode 100644 index 0000000000..e3462b11b2 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/README.md @@ -0,0 +1,19 @@ +# Getting started with Tarantool Cluster Manager + +A sample application created in the [Getting started with Tarantool Cluster Manager](https://www.tarantool.io/en/doc/latest/getting_started/getting_started_tcm/) tutorial. + +## Running + +Before starting instances, set up a Tarantool EE cluster as described in the tutorial. +Then, start all instances by executing the following command in the [config](../../../config) directory: + +```console +$ tt start tcm_get_started +``` + +> +> To publish a cluster's configuration to etcd using tt, execute `tt cluster publish`: +> +> ```shell +> tt cluster publish "http://localhost:2379/default" instances.enabled/tcm_get_started/cluster.yaml +> ``` diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/cluster.yaml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/cluster.yaml new file mode 100644 index 0000000000..4ba95bf0a1 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/cluster.yaml @@ -0,0 +1,30 @@ +credentials: + users: + guest: + roles: [super] +groups: + group-001: + replicasets: + replicaset-001: + replication: + failover: manual + leader: instance-001 + instances: + instance-001: + iproto: + listen: + - uri: '127.0.0.1:3301' + advertise: + client: '127.0.0.1:3301' + instance-002: + iproto: + listen: + - uri: '127.0.0.1:3302' + advertise: + client: '127.0.0.1:3302' + instance-003: + iproto: + listen: + - uri: '127.0.0.1:3303' + advertise: + client: '127.0.0.1:3303' diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/config.yaml new file mode 100644 index 0000000000..3071113699 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/config.yaml @@ -0,0 +1,5 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /default diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/instances.yml new file mode 100644 index 0000000000..c9e5954a95 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/instances.yml @@ -0,0 +1,3 @@ +instance-001: +instance-002: +instance-003: diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua new file mode 100644 index 0000000000..c4cc0c25fb --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua @@ -0,0 +1,20 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } }) + box.schema.user.grant('guest', 'read,write,execute', 'universe') +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } +end + +function select_data() + box.space.bands:select { 3 } +end diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml new file mode 100644 index 0000000000..5df487e662 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml @@ -0,0 +1,10 @@ +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + snapshot: + dir: ./var/{{ instance_name }}/snapshots + wal: + dir: ./var/{{ instance_name }}/wals \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/tt.yaml b/doc/code_snippets/snippets/config/tt.yaml new file mode 100644 index 0000000000..41a3915f50 --- /dev/null +++ b/doc/code_snippets/snippets/config/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/snippets/connectors/go/README.md b/doc/code_snippets/snippets/connectors/go/README.md new file mode 100644 index 0000000000..180db90a7a --- /dev/null +++ b/doc/code_snippets/snippets/connectors/go/README.md @@ -0,0 +1,14 @@ +# Go + +A sample application containing requests from the [Go](https://www.tarantool.io/en/doc/latest/connector/go/) tutorial. + + +## Running + +Before running this sample, start an application that allows remote connections to a sample database: [sample_db](../instances.enabled/sample_db). + +Then, start this sample by executing the following command in the `go` directory: + +``` +$ go run . +``` diff --git a/doc/code_snippets/snippets/connectors/go/go.mod b/doc/code_snippets/snippets/connectors/go/go.mod new file mode 100644 index 0000000000..191575428a --- /dev/null +++ b/doc/code_snippets/snippets/connectors/go/go.mod @@ -0,0 +1,12 @@ +module example/hello + +go 1.22.3 + +require ( + github.com/google/uuid v1.3.0 // indirect + github.com/shopspring/decimal v1.3.1 // indirect + github.com/tarantool/go-iproto v1.0.0 // indirect + github.com/tarantool/go-tarantool/v2 v2.1.0 // indirect + github.com/vmihailenco/msgpack/v5 v5.3.5 // indirect + github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect +) diff --git a/doc/code_snippets/snippets/connectors/go/go.sum b/doc/code_snippets/snippets/connectors/go/go.sum new file mode 100644 index 0000000000..199d48ec59 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/go/go.sum @@ -0,0 +1,18 @@ +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I= +github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/shopspring/decimal v1.3.1 h1:2Usl1nmF/WZucqkFZhnfFYxxxu8LG21F6nPQBE5gKV8= +github.com/shopspring/decimal v1.3.1/go.mod h1:DKyhrW/HYNuLGql+MJL6WCR6knT2jwCFRcu2hWCYk4o= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/tarantool/go-iproto v1.0.0 h1:quC4hdFhCuFYaCqOFgUxH2foRkhAy+TlEy7gQLhdVjw= +github.com/tarantool/go-iproto v1.0.0/go.mod h1:LNCtdyZxojUed8SbOiYHoc3v9NvaZTB7p96hUySMlIo= +github.com/tarantool/go-tarantool/v2 v2.1.0 h1:IY33WoS8Kqb+TxNnKbzu/7yVkiCNZGhbG5Gw0/tMfSk= +github.com/tarantool/go-tarantool/v2 v2.1.0/go.mod h1:cpjGW5FHAXIMf0PKZte70pMOeadw1MA/hrDv1LblWk4= +github.com/vmihailenco/msgpack/v5 v5.3.5 h1:5gO0H1iULLWGhs2H5tbAHIZTV8/cYafcFOr9znI5mJU= +github.com/vmihailenco/msgpack/v5 v5.3.5/go.mod h1:7xyJ9e+0+9SaZT0Wt1RGleJXzli6Q/V5KbhBonMG9jc= +github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g= +github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/doc/code_snippets/snippets/connectors/go/hello.go b/doc/code_snippets/snippets/connectors/go/hello.go new file mode 100644 index 0000000000..ee93e43def --- /dev/null +++ b/doc/code_snippets/snippets/connectors/go/hello.go @@ -0,0 +1,134 @@ +package main + +import ( + "context" + "fmt" + "github.com/tarantool/go-tarantool/v2" + _ "github.com/tarantool/go-tarantool/v2/datetime" + _ "github.com/tarantool/go-tarantool/v2/decimal" + _ "github.com/tarantool/go-tarantool/v2/uuid" + "time" +) + +func main() { + // Connect to the database + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + dialer := tarantool.NetDialer{ + Address: "127.0.0.1:3301", + User: "sampleuser", + Password: "123456", + } + opts := tarantool.Opts{ + Timeout: time.Second, + } + + conn, err := tarantool.Connect(ctx, dialer, opts) + if err != nil { + fmt.Println("Connection refused:", err) + return + } + + // Interact with the database + // ... + // Insert data + tuples := [][]interface{}{ + {1, "Roxette", 1986}, + {2, "Scorpions", 1965}, + {3, "Ace of Base", 1987}, + {4, "The Beatles", 1960}, + } + var futures []*tarantool.Future + for _, tuple := range tuples { + request := tarantool.NewInsertRequest("bands").Tuple(tuple) + futures = append(futures, conn.Do(request)) + } + fmt.Println("Inserted tuples:") + for _, future := range futures { + result, err := future.Get() + if err != nil { + fmt.Println("Got an error:", err) + } else { + fmt.Println(result) + } + } + + // Select by primary key + data, err := conn.Do( + tarantool.NewSelectRequest("bands"). + Limit(10). + Iterator(tarantool.IterEq). + Key([]interface{}{uint(1)}), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Tuple selected by the primary key value:", data) + + // Select by secondary key + data, err = conn.Do( + tarantool.NewSelectRequest("bands"). + Index("band"). + Limit(10). + Iterator(tarantool.IterEq). + Key([]interface{}{"The Beatles"}), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Tuple selected by the secondary key value:", data) + + // Update + data, err = conn.Do( + tarantool.NewUpdateRequest("bands"). + Key(tarantool.IntKey{2}). + Operations(tarantool.NewOperations().Assign(1, "Pink Floyd")), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Updated tuple:", data) + + // Upsert + data, err = conn.Do( + tarantool.NewUpsertRequest("bands"). + Tuple([]interface{}{uint(5), "The Rolling Stones", 1962}). + Operations(tarantool.NewOperations().Assign(1, "The Doors")), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + + // Replace + data, err = conn.Do( + tarantool.NewReplaceRequest("bands"). + Tuple([]interface{}{1, "Queen", 1970}), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Replaced tuple:", data) + + // Delete + data, err = conn.Do( + tarantool.NewDeleteRequest("bands"). + Key([]interface{}{uint(5)}), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Deleted tuple:", data) + + // Call + data, err = conn.Do( + tarantool.NewCallRequest("get_bands_older_than").Args([]interface{}{1966}), + ).Get() + if err != nil { + fmt.Println("Got an error:", err) + } + fmt.Println("Stored procedure result:", data) + + // Close connection + conn.CloseGraceful() + fmt.Println("Connection is closed") +} diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md new file mode 100644 index 0000000000..3d071d0fda --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md @@ -0,0 +1,11 @@ +# Connectors + +A sample application used to demonstrate how to connect to a database using connectors for different languages and execute requests for manipulating the data. + +## Running + +Start the application by executing the following command in the [connectors](../../../connectors) directory: + +```console +$ tt start sample_db +``` diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml new file mode 100644 index 0000000000..a4446cbca4 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml @@ -0,0 +1,22 @@ +credentials: + users: + sampleuser: + password: '123456' + privileges: + - permissions: [ read, write ] + spaces: [ bands ] + - permissions: [ execute ] + functions: [ get_bands_older_than ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua new file mode 100644 index 0000000000..5859c4be19 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua @@ -0,0 +1,23 @@ +-- Create a space -- +box.schema.space.create('bands') + +-- Specify field names and types -- +box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } +}) + +-- Create indexes -- +box.space.bands:create_index('primary', { parts = { 'id' } }) +box.space.bands:create_index('band', { parts = { 'band_name' } }) +box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } }) + +-- Create a stored function -- +box.schema.func.create('get_bands_older_than', { + body = [[ + function(year) + return box.space.bands.index.year_band:select({ year }, { iterator = 'LT', limit = 10 }) + end + ]] +}) diff --git a/doc/code_snippets/snippets/connectors/net_box/README.md b/doc/code_snippets/snippets/connectors/net_box/README.md new file mode 100644 index 0000000000..18e714591a --- /dev/null +++ b/doc/code_snippets/snippets/connectors/net_box/README.md @@ -0,0 +1,16 @@ +# net.box + +A sample application containing `net.box` requests from the [Connecting to a database using net.box](https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#connecting-to-a-database-using-net-box) tutorial. + + +## Running + +Before running this sample, start an application that allows remote connections to a sample database: [sample_db](../instances.enabled/sample_db). + +Then, start the interactive session by executing the following command in the [connectors](..) directory: + +```console +$ tt run -i net_box/myapp.lua +``` + +In the console, you can use the `conn` object to execute requests for manipulating the data. diff --git a/doc/code_snippets/snippets/connectors/net_box/myapp.lua b/doc/code_snippets/snippets/connectors/net_box/myapp.lua new file mode 100644 index 0000000000..f454a43d57 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/net_box/myapp.lua @@ -0,0 +1,102 @@ +net_box = require('net.box') +--[[ +--- +... +]] + +conn = net_box.connect('sampleuser:123456@127.0.0.1:3301') +--[[ +--- +... +]] + +conn:ping() +--[[ +--- +- true +... +]] + +function net_box_data_operations() + -- Start net.box session + conn.space.bands:insert({ 1, 'Roxette', 1986 }) + --[[ + --- + - - [1, 'Roxette', 1986] + ... + ]] + conn.space.bands:insert({ 2, 'Scorpions', 1965 }) + --[[ + --- + - [2, 'Scorpions', 1965] + ... + ]] + conn.space.bands:insert({ 3, 'Ace of Base', 1987 }) + --[[ + --- + - [3, 'Ace of Base', 1987] + ... + ]] + conn.space.bands:insert({ 4, 'The Beatles', 1960 }) + --[[ + --- + - [4, 'The Beatles', 1960] + ... + ]] + + conn.space.bands:select({ 1 }) + --[[ + --- + - - [1, 'Roxette', 1986] + ... + ]] + + conn.space.bands.index.band:select({ 'The Beatles' }) + --[[ + --- + - - [4, 'The Beatles', 1960] + ... + ]] + + conn.space.bands:update({ 2 }, { { '=', 'band_name', 'Pink Floyd' } }) + --[[ + --- + - [2, 'Pink Floyd', 1965] + ... + ]] + + conn.space.bands:upsert({ 5, 'The Rolling Stones', 1962 }, { { '=', 'band_name', 'The Doors' } }) + --[[ + --- + ... + ]] + + conn.space.bands:replace({ 1, 'Queen', 1970 }) + --[[ + --- + - [1, 'Queen', 1970] + ... + ]] + + conn.space.bands:delete({ 5 }) + --[[ + --- + - [5, 'The Rolling Stones', 1962] + ... + ]] + + conn:call('get_bands_older_than', { 1966 }) + -- --- + -- - [[2, 'Pink Floyd', 1965], [4, 'The Beatles', 1960]] + -- ... + -- End net.box session +end + +function net_box_close_connection() + conn:close() + --[[ + --- + ... + ]] + -- Close net.box connection +end diff --git a/doc/code_snippets/snippets/connectors/python/README.md b/doc/code_snippets/snippets/connectors/python/README.md new file mode 100644 index 0000000000..9fc97a72de --- /dev/null +++ b/doc/code_snippets/snippets/connectors/python/README.md @@ -0,0 +1,14 @@ +# Python + +A sample application containing requests from the [Python](https://www.tarantool.io/en/doc/latest/connector/python/) tutorial. + + +## Running + +Before running this sample, start an application that allows remote connections to a sample database: [sample_db](../instances.enabled/sample_db). + +Then, start this sample by executing the following command in the `python` directory: + +``` +$ python hello.py +``` diff --git a/doc/code_snippets/snippets/connectors/python/hello.py b/doc/code_snippets/snippets/connectors/python/hello.py new file mode 100644 index 0000000000..0a9dec567e --- /dev/null +++ b/doc/code_snippets/snippets/connectors/python/hello.py @@ -0,0 +1,52 @@ +import tarantool + +# Connect to the database +conn = tarantool.Connection(host='127.0.0.1', + port=3301, + user='sampleuser', + password='123456') + +# Insert data +tuples = [(1, 'Roxette', 1986), + (2, 'Scorpions', 1965), + (3, 'Ace of Base', 1987), + (4, 'The Beatles', 1960)] +print("Inserted tuples:") +for tuple in tuples: + response = conn.insert(space_name='bands', values=tuple) + print(response[0]) + +# Select by primary key +response = conn.select(space_name='bands', key=1) +print('Tuple selected by the primary key value:', response[0]) + +# Select by secondary key +response = conn.select(space_name='bands', key='The Beatles', index='band') +print('Tuple selected by the secondary key value:', response[0]) + +# Update +response = conn.update(space_name='bands', + key=2, + op_list=[('=', 'band_name', 'Pink Floyd')]) +print('Updated tuple:', response[0]) + +# Upsert +conn.upsert(space_name='bands', + tuple_value=(5, 'The Rolling Stones', 1962), + op_list=[('=', 'band_name', 'The Doors')]) + +# Replace +response = conn.replace(space_name='bands', values=(1, 'Queen', 1970)) +print('Replaced tuple:', response[0]) + +# Delete +response = conn.delete(space_name='bands', key=5) +print('Deleted tuple:', response[0]) + +# Call +response = conn.call('get_bands_older_than', 1966) +print('Stored procedure result:', response[0]) + +# Close connection +conn.close() +print('Connection is closed') diff --git a/doc/code_snippets/snippets/connectors/tt.yaml b/doc/code_snippets/snippets/connectors/tt.yaml new file mode 100644 index 0000000000..e9cf7000cf --- /dev/null +++ b/doc/code_snippets/snippets/connectors/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/snippets/migrations/README.md b/doc/code_snippets/snippets/migrations/README.md new file mode 100644 index 0000000000..1f2f58b298 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/README.md @@ -0,0 +1,4 @@ +# Centralized migrations with tt + +Sample applications demonstrating how to use the centralized migration mechanism +for Tarantool EE clusters via the tt utility. Learn more at [Centralized configuration storages](https://www.tarantool.io/en/doc/latest/platform/https://www.tarantool.io/en/doc/latest/platform/ddl_dml/migrations/). diff --git a/doc/code_snippets/snippets/migrations/etcd_setup.sh b/doc/code_snippets/snippets/migrations/etcd_setup.sh new file mode 100644 index 0000000000..31855a5992 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/etcd_setup.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +# 1. Remove the 'default.etcd' directory to reset etcd to initial state. +# 2. Start etcd by executing the 'etcd' command. +# 3. Execute this script to enable authentication. + +etcdctl user add root:topsecret +etcdctl role add app_config_manager +etcdctl role grant-permission app_config_manager --prefix=true readwrite /myapp/ +etcdctl user add app_user:config_pass +etcdctl user grant-role app_user app_config_manager +etcdctl auth enable diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/config.yaml b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/config.yaml new file mode 100644 index 0000000000..2e9d6f9fd4 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/config.yaml @@ -0,0 +1,10 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /myapp/ + username: app_user + password: config_pass + http: + request: + timeout: 3 diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances-3-storages.yml b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances-3-storages.yml new file mode 100644 index 0000000000..ef5d67a472 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances-3-storages.yml @@ -0,0 +1,7 @@ +router-001-a: +storage-001-a: +storage-001-b: +storage-002-a: +storage-002-b: +storage-003-a: +storage-003-b: diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances.yml b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances.yml new file mode 100644 index 0000000000..de6c038972 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/instances.yml @@ -0,0 +1,5 @@ +router-001-a: +storage-001-a: +storage-001-b: +storage-002-a: +storage-002-b: diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/myapp-scm-1.rockspec b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/myapp-scm-1.rockspec new file mode 100644 index 0000000000..a7a4035198 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/myapp-scm-1.rockspec @@ -0,0 +1,14 @@ +package = 'myapp' +version = 'scm-1' + +source = { + url = '/dev/null', +} + +dependencies = { + 'crud == 1.5.2', +} + +build = { + type = 'none'; +} diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yaml b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yaml new file mode 100644 index 0000000000..61122da382 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yaml @@ -0,0 +1,88 @@ +credentials: + users: + client: + password: 'secret' + roles: [super] + replicator: + password: 'secret' + roles: [replication] + storage: + password: 'secret' + roles: [sharding] + +iproto: + advertise: + peer: + login: replicator + sharding: + login: storage + +sharding: + bucket_count: 3000 + +groups: + routers: + sharding: + roles: [router] + roles: [roles.crud-router] + replicasets: + router-001: + instances: + router-001-a: + iproto: + listen: + - uri: localhost:3301 + advertise: + client: localhost:3301 + storages: + sharding: + roles: [storage] + roles: [roles.crud-storage] + replication: + failover: manual + replicasets: + storage-001: + leader: storage-001-a + instances: + storage-001-a: + iproto: + listen: + - uri: localhost:3302 + advertise: + client: localhost:3302 + storage-001-b: + iproto: + listen: + - uri: localhost:3303 + advertise: + client: localhost:3303 + storage-002: + leader: storage-002-a + instances: + storage-002-a: + iproto: + listen: + - uri: localhost:3304 + advertise: + client: localhost:3304 + storage-002-b: + iproto: + listen: + - uri: localhost:3305 + advertise: + client: localhost:3305 + storage-003: + leader: storage-003-a + instances: + storage-003-a: + iproto: + listen: + - uri: localhost:3306 + advertise: + client: localhost:3306 + storage-003-b: + iproto: + listen: + - uri: localhost:3307 + advertise: + client: localhost:3307 diff --git a/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source.yaml b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source.yaml new file mode 100644 index 0000000000..7e49410ab3 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/instances.enabled/myapp/source.yaml @@ -0,0 +1,73 @@ +credentials: + users: + client: + password: 'secret' + roles: [super] + replicator: + password: 'secret' + roles: [replication] + storage: + password: 'secret' + roles: [sharding] + +iproto: + advertise: + peer: + login: replicator + sharding: + login: storage + +sharding: + bucket_count: 3000 + +groups: + routers: + sharding: + roles: [router] + roles: [roles.crud-router] + replicasets: + router-001: + instances: + router-001-a: + iproto: + listen: + - uri: localhost:3301 + advertise: + client: localhost:3301 + storages: + sharding: + roles: [storage] + roles: [roles.crud-storage] + replication: + failover: manual + replicasets: + storage-001: + leader: storage-001-a + instances: + storage-001-a: + iproto: + listen: + - uri: localhost:3302 + advertise: + client: localhost:3302 + storage-001-b: + iproto: + listen: + - uri: localhost:3303 + advertise: + client: localhost:3303 + storage-002: + leader: storage-002-a + instances: + storage-002-a: + iproto: + listen: + - uri: localhost:3304 + advertise: + client: localhost:3304 + storage-002-b: + iproto: + listen: + - uri: localhost:3305 + advertise: + client: localhost:3305 diff --git a/doc/code_snippets/snippets/migrations/migrations/scenario/000001_create_writers_space.lua b/doc/code_snippets/snippets/migrations/migrations/scenario/000001_create_writers_space.lua new file mode 100644 index 0000000000..c8e6fc45ce --- /dev/null +++ b/doc/code_snippets/snippets/migrations/migrations/scenario/000001_create_writers_space.lua @@ -0,0 +1,23 @@ +local helpers = require('tt-migrations.helpers') + +local function apply_scenario() + local space = box.schema.space.create('writers') + + space:format({ + {name = 'id', type = 'number'}, + {name = 'bucket_id', type = 'number'}, + {name = 'name', type = 'string'}, + {name = 'age', type = 'number'}, + }) + + space:create_index('primary', {parts = {'id'}}) + space:create_index('bucket_id', {parts = {'bucket_id'}}) + + helpers.register_sharding_key('writers', {'id'}) +end + +return { + apply = { + scenario = apply_scenario, + }, +} diff --git a/doc/code_snippets/snippets/migrations/migrations/scenario/000002_create_writers_index.lua b/doc/code_snippets/snippets/migrations/migrations/scenario/000002_create_writers_index.lua new file mode 100644 index 0000000000..fdee011a3e --- /dev/null +++ b/doc/code_snippets/snippets/migrations/migrations/scenario/000002_create_writers_index.lua @@ -0,0 +1,11 @@ +local function apply_scenario() + local space = box.space['writers'] + + space:create_index('age', {parts = {'age'}}) +end + +return { + apply = { + scenario = apply_scenario, + }, +} diff --git a/doc/code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua b/doc/code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua new file mode 100644 index 0000000000..3d53314782 --- /dev/null +++ b/doc/code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua @@ -0,0 +1,48 @@ +local function apply_scenario() + local space = box.space['writers'] + local new_format = { + {name = 'id', type = 'number'}, + {name = 'bucket_id', type = 'number'}, + {name = 'first_name', type = 'string'}, + {name = 'last_name', type = 'string'}, + {name = 'age', type = 'number'}, + } + box.space.writers.index.age:drop() + + box.schema.func.create('_writers_split_name', { + language = 'lua', + is_deterministic = true, + body = [[ + function(t) + local name = t[3] + + local split_data = {} + local split_regex = '([^%s]+)' + for v in string.gmatch(name, split_regex) do + table.insert(split_data, v) + end + + local first_name = split_data[1] + assert(first_name ~= nil) + + local last_name = split_data[2] + assert(last_name ~= nil) + + return {t[1], t[2], first_name, last_name, t[4]} + end + ]], + }) + + local future = space:upgrade({ + func = '_writers_split_name', + format = new_format, + }) + + future:wait() +end + +return { + apply = { + scenario = apply_scenario, + }, +} diff --git a/doc/code_snippets/snippets/migrations/tt.yaml b/doc/code_snippets/snippets/migrations/tt.yaml new file mode 100644 index 0000000000..e9cf7000cf --- /dev/null +++ b/doc/code_snippets/snippets/migrations/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml new file mode 100644 index 0000000000..69709e923b --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml @@ -0,0 +1,44 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + - uri: '127.0.0.1:4401' + advertise: + peer: + uri: '127.0.0.1:4401' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + - uri: '127.0.0.1:4402' + advertise: + peer: + uri: '127.0.0.1:4402' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + - uri: '127.0.0.1:4403' + advertise: + peer: + uri: '127.0.0.1:4403' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/README.md b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/README.md new file mode 100644 index 0000000000..ef7de1dd37 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/README.md @@ -0,0 +1,11 @@ +# Anonymous replica + +A sample application demonstrating how to add an anonymous replica to a replica set. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start anonymous_replica +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml new file mode 100644 index 0000000000..7db1730981 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml @@ -0,0 +1,34 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + replication: + anon: true + iproto: + listen: + - uri: '127.0.0.1:3303' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/README.md b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/README.md new file mode 100644 index 0000000000..d167308c7c --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/README.md @@ -0,0 +1,11 @@ +# Master-replica: automated failover + +A sample application demonstrating how to bootstrap a replica set with [automated failover](https://www.tarantool.io/en/doc/latest/platform/replication/replication_tutorials/repl_bootstrap_auto/). + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start auto_leader +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml new file mode 100644 index 0000000000..e289dc146b --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml @@ -0,0 +1,35 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: election + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + +# Load sample data +app: + file: 'myapp.lua' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/myapp.lua new file mode 100644 index 0000000000..27b0b6bbf6 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/myapp.lua @@ -0,0 +1,32 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function create_sync_space() + box.schema.space.create('bands', { is_sync = true }) + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/README.md b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/README.md new file mode 100644 index 0000000000..f7e99e1308 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/README.md @@ -0,0 +1,11 @@ +# replication.bootstrap_strategy + +A sample application demonstrating how to use the specified instance to bootstrap a replica set. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start bootstrap_strategy +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/config.yaml new file mode 100644 index 0000000000..b6c0e0c849 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/config.yaml @@ -0,0 +1,34 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: election + +groups: + group001: + replicasets: + replicaset001: + replication: + bootstrap_strategy: config + bootstrap_leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/README.md b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/README.md new file mode 100644 index 0000000000..e4c95b3929 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/README.md @@ -0,0 +1,23 @@ +# Using box.info.synchro + +A sample application demonstrating how to work with [box.info.synchro](https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_info/synchro/). + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start box_info_synchro +``` + +To check the instance status, run: + +```console +$ tt status box_info_synchro +``` + +To connect to the ``instance001`` instance, run: + +```console +$ tt connect box_info_synchro:instance001 +``` \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/config.yaml new file mode 100644 index 0000000000..06f27a7b70 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/config.yaml @@ -0,0 +1,31 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + database: + mode: rw + replication: + synchro_quorum: 2 + synchro_timeout: 1000 + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + database: + mode: ro + iproto: + listen: + - uri: '127.0.0.1:3302' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/instances.yml new file mode 100644 index 0000000000..75e286d69c --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/box_info_synchro/instances.yml @@ -0,0 +1,2 @@ +instance001: +instance002: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/README.md b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/README.md new file mode 100644 index 0000000000..3725a12d5d --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/README.md @@ -0,0 +1,11 @@ +# Master-replica: manual failover + +A sample application demonstrating how to bootstrap a replica set with [manual failover](https://www.tarantool.io/en/doc/latest/platform/replication/replication_tutorials/repl_bootstrap/). + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start manual_leader +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml new file mode 100644 index 0000000000..4b2e3d9192 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml @@ -0,0 +1,36 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + +# Load sample data +app: + file: 'myapp.lua' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua new file mode 100644 index 0000000000..321db0aab1 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua @@ -0,0 +1,22 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/README.md b/doc/code_snippets/snippets/replication/instances.enabled/master_master/README.md new file mode 100644 index 0000000000..de22161fa5 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/README.md @@ -0,0 +1,11 @@ +# Master-master + +A sample application demonstrating how to bootstrap a [master-master](https://www.tarantool.io/en/doc/latest/platform/replication/replication_tutorials/repl_bootstrap_master_master/) replica set. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start master_master +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml new file mode 100644 index 0000000000..dfc3083b35 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml @@ -0,0 +1,35 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: off + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + database: + mode: rw + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + database: + mode: rw + iproto: + listen: + - uri: '127.0.0.1:3302' + +# Load sample data +app: + file: 'myapp.lua' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml new file mode 100644 index 0000000000..75e286d69c --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml @@ -0,0 +1,2 @@ +instance001: +instance002: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua new file mode 100644 index 0000000000..321db0aab1 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua @@ -0,0 +1,22 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { parts = { 'id' } }) +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } + box.space.bands:insert { 4, 'The Beatles', 1960 } + box.space.bands:insert { 5, 'Pink Floyd', 1965 } + box.space.bands:insert { 6, 'The Rolling Stones', 1962 } + box.space.bands:insert { 7, 'The Doors', 1965 } + box.space.bands:insert { 8, 'Nirvana', 1987 } + box.space.bands:insert { 9, 'Led Zeppelin', 1968 } + box.space.bands:insert { 10, 'Queen', 1970 } +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/peers/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/peers/config.yaml new file mode 100644 index 0000000000..7037c2c188 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/peers/config.yaml @@ -0,0 +1,30 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +replication: + peers: + - replicator:topsecret@127.0.0.1:3301 + - replicator:topsecret@127.0.0.1:3302 + - replicator:topsecret@127.0.0.1:3303 + failover: election + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/peers/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/peers/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/peers/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md new file mode 100644 index 0000000000..258232361e --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md @@ -0,0 +1,11 @@ +# SSL (with CA) + +A sample application demonstrating how to enable TLS traffic encryption for connections between replica set peers. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start ssl_with_ca +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh new file mode 100644 index 0000000000..fe724af0e6 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -xeuo pipefail + +# 1. Generate a root CA key. +openssl genrsa -out root_ca.key 2048 + +# 2. Generate a root CA certificate. +openssl req -x509 -new -key root_ca.key -days 365 -out root_ca.crt -subj "/C=US/CN=Example-Root-CA" + +# 3. Generate server keys encrypted using different passphrases. +openssl genrsa -aes256 -passout pass:'qwerty' -out server001.key 2048 +openssl genrsa -aes256 -passout pass:'123456' -out server002.key 2048 +openssl genrsa -aes256 -passout pass:'topsecret' -out server003.key 2048 + +# 4. Create certificate signing requests based on server keys. +openssl req -new -key server001.key -passin pass:'qwerty' -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server001/" -out server001.csr +openssl req -new -key server002.key -passin pass:'123456' -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server002/" -out server002.csr +openssl req -new -key server003.key -passin pass:'topsecret' -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server003/" -out server003.csr + +# 5. Generate server certificates. +openssl x509 -req -in server001.csr -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -CA root_ca.crt -CAkey root_ca.key -CAcreateserial -out server001.crt +openssl x509 -req -in server002.csr -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -CA root_ca.crt -CAkey root_ca.key -CAcreateserial -out server002.crt +openssl x509 -req -in server003.csr -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -CA root_ca.crt -CAkey root_ca.key -CAcreateserial -out server003.crt + +cp server001.crt server001.key instance001 +cp server002.crt server002.key instance002 +cp server003.crt server003.key instance003 + +rm -rf server* diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.crt new file mode 100644 index 0000000000..b8b3176231 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDdDCCAlygAwIBAgIUZ3UUfbU+PVMvCBz6V60Cdhhlmi8wDQYJKoZIhvcNAQEL +BQAwJzELMAkGA1UEBhMCVVMxGDAWBgNVBAMMD0V4YW1wbGUtUm9vdC1DQTAgFw0y +NDAxMDkxMDIwMjlaGA8yMTAwMDEwMTEwMjAyOVowXzELMAkGA1UEBhMCVVMxDjAM +BgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNl +cnRpZmljYXRlczESMBAGA1UEAwwJc2VydmVyMDAxMIIBIjANBgkqhkiG9w0BAQEF +AAOCAQ8AMIIBCgKCAQEAjV8WYiwj6pKhdvhd5JHKiRWsPH8DldGkuC22WYYqW4pG +4jwIgbHK4XDw7dtIKiTp5j1hxswPYfelwT4PswvvUt2ZTuWrC2wxH7gUeX3WOoRV +GuQWvz5jwyZecGKa0D9a/0e/MedcqyNY8e15qUfFZXOg74hCp1VtXGJLtJ3ttL2Z +JXCXK+tLKbn5hK5XnyksHbd0yhHbfv3WgbyIJHkPf9Ld1McmvlJOsP/pYM31L3Pv +KS/NYtjC7ZrxGNYwmry+9ECfsqvdrR3WOSPc7x6XDluqQhsBpR5L5yMBD7/Pmdmh +85QO89FpuE2fZbzbBgOAIv74m1+9vVo0bl9GQ5ItdQIDAQABo14wXDAaBgNVHREE +EzARgglsb2NhbGhvc3SHBH8AAAEwHQYDVR0OBBYEFLRPcYdn/ZzyvTICSE4eHkpq +Yo2uMB8GA1UdIwQYMBaAFMcoPooETZGmQ44FaE298f3LsrBDMA0GCSqGSIb3DQEB +CwUAA4IBAQCu2eVNEPiCgH2oEpieb5O3+H13RGt7K0OG8xIdrScLm8g7UP964uqS +V8svDodF++o/zBtL2ebbeTL7+cqW8Oz3NZrBiUmRdXUrGncpT26wNut8pppV9C8c +O533Mu0yPLXguoykE67BMiZ0aXafvCxEWj0d5Ml1BlIucaZ7HJY+C4JMeX/T27OQ +u4jrvNLykyfWu7aIquhKcxuzdMo7rFRGOR01738M0/Sp4a952of1lFuv/macgttQ +6M5oWW/XgNwbbcTnN7oCv4aTK7QOoi3NZfAD723hq9AQLTZD/Nl+xkMBDMNiDc3R +9r39ptN92K3YkAHaULLyk+c14Wox4f7N +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.key new file mode 100644 index 0000000000..09585dc45a --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.key @@ -0,0 +1,30 @@ +-----BEGIN ENCRYPTED PRIVATE KEY----- +MIIFLTBXBgkqhkiG9w0BBQ0wSjApBgkqhkiG9w0BBQwwHAQIoIzCBu75OnUCAggA +MAwGCCqGSIb3DQIJBQAwHQYJYIZIAWUDBAEqBBAGERLT6LYhWrk4nTQ2rAfEBIIE +0Awkcsj9RAgl07YEFq0YrhjBmLw4xg++qKFBm5TKwwBBpzNLkefqzOoY9wRAQZF6 +vhgGg87rEUwWaKhyhVI2yq0osKtIz4wrC+VWdB5G4eMVRYes8f1DSXHBRksTs314 +QTF1TY+0mecGmEBQ0iOvE5Z4EcxZMUeZimMEb4nXnGVdkz+tskcru5Br9a7iArC0 +hp7ibf71J4KnQAS/rBiUBVBpDaE5tdNo0mU8Icy11vg/YkykTwZ5qeO3VLsHho5/ +nOsv7CB6UbGnVJCsQckFViJTDJvyyrmJ6urfqvPMLG5u/0sIWTDfYnPrTQOibt+N +XcvqrgZ09xLzLrgrqZ8E8nHX1xQ1w3m4TWKnXlM0enpzKp+BTMRTdly3V45asvpa +cUlbZjX+ktW0c/bsq91DU79uy5MZuOiX3BpPFeMgreES2YIjOYo1pYloHeAw3tGG +rfXYVuPo9IfrdkXmfq9LpqPcB5zsqkAAomPpLLfb2B/gisUZZ//Y+BAEaGOlwWoa +81JrM363jt8U11up+6ahShwSjHol9QhqC1yEPgBVnpNbCj4ypzJxq9upnNjowvuL +D4MhVdVf58ILkiybASTvW2IeilQf9N3scwQwiRq1duLqkrjDKD1AqxsJQobPVuV3 +YxYZ7JwwvWD86eMsvtnevT1mG9NFRfmxPD4xesvtv7OdYxQqrrkGYhOz9f3YQJiu +EJBjq3HFnMmh9FFZ0W1I8OjnLKoN2z4XMo29HtPUX1sJpWM4wWAf+ZxABnO2kJyp +xV6XvuhZU4V/seL+DGL6cT1b4Zg0gcc//RnlkeX3l9cE0Sqi3FKv4aKBG4/g41vR +fNee0eB1O71rzwaNh4KYBgInNy70XjNnARxSC/KOd/el77Xv7hPKL9Wxah+B11Uc +Csw6Ynj+Ea+HrifVBWeo7z5cqQ1ZXQD6DKWfdvujYNxwSLMpBpk5d9rX1gUvQHOU +GmJjKp80Wrr3eA9tuBBiMkp0ljBjbagDr8PGjRwO9LslzGAUdzDuqsqLVJz8vv2t +uDxjYARmtQHCeG8VowpP3QmrbmNM2m7s4M5+G8ZhzAZCHvPXyEEItGMP9qcjNUk2 +Sqpkz3ZYPAtDFp+cx6raggULd1AWv2xJU0kvJULE8tyWev7AyZKz/buiG2Fib5WX +oJAQwAymkP13eGvIXaWUybsO98TgtlcaNlNkvTdmAwZyuZlYYvH9yiV2vi4ldqdl +irAVTWqiqDo9TiGRBR0QxuJPJciuJG5D+pOdIw6tU4XHq1RiikCYE9RMqiBddqlr +5WB4j/ls0Mpqk6fvUkttEW6vovO1AQw80Ut5hifDu5hLM3CzqysTf0bbEgS7DcWg +hpQghcIWFJuNIrR4o7zN9hHHyKg6oZKF35edDoEmEr8COd12vIzLezanNkTwKB1A +7FKSpT1A/u3W0D2oPHrkd2mGEjYO8RDhScMsPQjTnHObzSQvX8wGIQDIE4rLD8me +9nxcodr+gNO/rdvEnQ1JWD52jW+S4mkJM4EswIO56sGy60sq4YoEzyWCexGxoWwF +lOrrX4vn2H6N++TPNBeWdnrT2L5BEKlbh0SHn74CPXXBNp6JqmdRUvTfHuC1C0jK +7KQPwMleAeh969wMyGqZO+DGULNC0D+Apck9ZQ3Hb28E +-----END ENCRYPTED PRIVATE KEY----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.crt new file mode 100644 index 0000000000..c29206916a --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDdDCCAlygAwIBAgIUYnbNUm7f3GQuqcJUmOcYMY7vu2QwDQYJKoZIhvcNAQEL +BQAwJzELMAkGA1UEBhMCVVMxGDAWBgNVBAMMD0V4YW1wbGUtUm9vdC1DQTAgFw0y +NDAxMDkxMDIwMjlaGA8yMTAwMDEwMTEwMjAyOVowXzELMAkGA1UEBhMCVVMxDjAM +BgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNl +cnRpZmljYXRlczESMBAGA1UEAwwJc2VydmVyMDAyMIIBIjANBgkqhkiG9w0BAQEF +AAOCAQ8AMIIBCgKCAQEAqjNtMpDuy9XXI6Ve7wFlHFvA0PZIIooobHqSNt7A4fPQ +NgOvjSXi04o2dOCQ3Tz0ku5AMkx14ZLv13NMJNPWIO+jbuqIY0sTA7qxj7T2ykEW +Dga9lWKTe4fFXNOITClImF2OKYlriCYXQ+UrUSRSYfaapc2byo94qQG6GqNC4RI9 +AsKSVlEXbOtwglTjA2gItBZ0URyCntddXek4JaUfdfDjY4RT1prNUniIaAT/8Xz5 +HPJR1jSJ8093mDdIBjDCwv7tY8N9dVtUOdV9k0q0JMgwaKv9rj93J1Esnew8uDiL +UhEojYkRCZQ267csSnXghtl2ZVulcttJLhyeqQ7PUwIDAQABo14wXDAaBgNVHREE +EzARgglsb2NhbGhvc3SHBH8AAAEwHQYDVR0OBBYEFE+RD/crlhgQjup7dCT53kMG +cfYDMB8GA1UdIwQYMBaAFMcoPooETZGmQ44FaE298f3LsrBDMA0GCSqGSIb3DQEB +CwUAA4IBAQBXLD8RlbclU/w/ynL7Clr1EZRVaXtcvBNhzZMPG+N+cl9/OAbCc+K1 +zBqU9MC3+ftjCo0b1Gn+WelB0rBR43JMDbP/Lkwcn7GqJXk/KApG54ygSDxTasMj +rmMuw8eES/7ndo+X/u/Jy71CFEJZbW15GKzv55fYE1LIOILLEepn3ikOn/1jujCZ +3oSikIlcIVkQSXOoglT1VBsWlNjA5AynofCjyW8VKVTZGCBvoBx7kVPUg4yzK2dx +gaIFosrqhV1v9ENfu+exErHDFyctsKsH34Tjjrkm+3hdseMjivBT8sOzWmTMNryk +3QquTfdJbOMFw873ynIEj/Q9vHFT76Ae +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.key new file mode 100644 index 0000000000..280627b6e7 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.key @@ -0,0 +1,30 @@ +-----BEGIN ENCRYPTED PRIVATE KEY----- +MIIFLTBXBgkqhkiG9w0BBQ0wSjApBgkqhkiG9w0BBQwwHAQIg0PYOtHuXYsCAggA +MAwGCCqGSIb3DQIJBQAwHQYJYIZIAWUDBAEqBBCSkBdX9Acur/mj1FWWXiiyBIIE +0H4nMqNCCkvVkbBKBy+5khhbCxN0kLgseHIPP3oAo6phLrhAAkv0xKr3wv/mR6Zp +3jQ2JHbOfGrduFckdCBU8tST621p6wdRLwm9MbeWNjjsuSCKH45y5w2jU3aXiLpz +4AsbweoO9a260nR4Aq5DG1t8VrJpofCfmye9FjacNGbCAa6HINigGrlp25USoead +sqqKf8Jl/g1729yzIB6WkTA9hXBxwz25BtgwSd+tUlvl6dYocKXCM6ljn/q25SgW +ozNBfOkzX3S8g6ZXjx0SkMdbUjuTrgjl7mn5cVYdjx6VM9fJjalca0h4Gr0kdHFM +z50D40Ha2O3HQ36ImKjlyzbZOjkIMpqOa6o7kH7jLlJLjYJo2+LocIr8/REw4Lgl +DeahUAl6Iya4K67sJG61FGKhzuOuxWW/Ymsa1v2Yq80PsZS1IyAD7jmH7zrT8mNq +0T82z/hQfY+vOo+1+VMmZd1azm5UHap/bsJ32e8GXszdjH2P6dMkymAykYQVtt4/ +W6+Q53tCNfmfbdzFNszzvRP5VjcDvUGtiD9gSLsqsFCh7GJlD8vXcrrOn61l3OLC +0CR3X9VBqerMiUFmsT1g7HsSHTD1h0OX2DTkhAfM0P4QXemGGke9/LBRsYaN07XD +akhs4jd++3hdMSWPSrm7JNx2BC2L+u4SyRdHnu7DtQ9DVPubwT63dhxMGkGzXOGK +3x3payRlp96ckms27tiWnsiPfVe/CECS6YXK0PLONenbvVDQO31iWDcV2AgOd0nv +OKUuC/oN37kY4P6J8MGao3zsmcfWxQSWjnImdnLsqtD6QxqyNH18Id2GOcwrkuoG +3Jyi43rR5c6r6O0ldvCB+iFHizzIBWA6GpDmzRYRd7lJlkQJ0ihCozWOsPC1lKZu +E3DiRwaTbGcOTOTJDHG6B3RE9YgZjZPkVVRYsPUp2e/flLr+2QZo3XyAFd9TJDOZ +GlCGnjmKVT83gRmgTd5mMfI2lm6vJwWC1jAIYNVuAQNWf+ZKsPfhm6mr6n6Najxr +lVPZOg+7loKxJLfcXIP3sItLCHT4Jc/rmn6/HwnFqrdFQDkIk/dPVYnIPZlCG24Z +to8pmjFyK5qX15rjZKAacYpSIoYHo26wFnFGSGtikUZXFm5aTGCxKnf+gBQ1Zrtw ++d9hKnmef0zlozU2b8byPRFNqV0cBaXxccXc5WFWJY60PZ6wbEs8wkBUmOh06pcR +IO4qX4RX1QRfSSldXNZ+3CFbUXT8u999DCCV/onw2NlbdqKiHQMoLhQQAWGReG1e +xpXXU8lRBMpW3PGHsWsGlzNTb4DkasKfL3LPxDc8DzDGrlkudYxARI23lHhKAZEv +WVqp00HiFA2n1HSqrdUjoBsnX5KzU5By4KgdS4pp8Le0vFStlq47257P3PUWEFnB +BFTmdbd44kOZK4mDgpyH3hQMJesdYMr8wWxhAUPx6SLK9OvVKRiLjjC1AHJQI6lS +umT8min1q88Pw9PfmL6speXYkPXD3PLms//bnqTI44rcptlWwmaZydW51cPc5CNA +CMVAoUHgwpJe+t+JH2B/ShmIG+Vh4aCEer70ZG38g8lLTG/wQNs0Cmfv01R2B53K +4bJY7jCy8YUnB+pEVohyWltI3rNkA27brnISIBVllPKn +-----END ENCRYPTED PRIVATE KEY----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.crt new file mode 100644 index 0000000000..76a85e35bf --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDdDCCAlygAwIBAgIUC2vN8EGo9naK0NawqRXTBdiR1BYwDQYJKoZIhvcNAQEL +BQAwJzELMAkGA1UEBhMCVVMxGDAWBgNVBAMMD0V4YW1wbGUtUm9vdC1DQTAgFw0y +NDAxMDkxMDIwMjlaGA8yMTAwMDEwMTEwMjAyOVowXzELMAkGA1UEBhMCVVMxDjAM +BgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNl +cnRpZmljYXRlczESMBAGA1UEAwwJc2VydmVyMDAzMIIBIjANBgkqhkiG9w0BAQEF +AAOCAQ8AMIIBCgKCAQEAn51RtVj89wuf8lVjCiQ0UeIvkPO87YIO8O5b0G35IKuQ +rRcanLifN8skooDs+oINzHpgp7tENy+uPynOuw02TJx+Li4JXX1XAX5v2WGWET2Y +/VykmTzCFDovzAR+aVyarDONxRDvV1v86Hfee34mBxkWF8gz5cyTOZjtQMWKmaxZ +jGSazuNcqet9XJYsUqRdCnxG+VRJTfGG7lnQ/+7sRE0BVqOaU+xOdRZCuHEUp99d +NponYJUJa6UwL06abvS6OO0Ab81mBTnaev7hAjsfpY+SYItUfcRlc57yBESGGB0r +ymQKy70KmK2vMUPGoS6YKE3sBXBJJdl/DOAe2v53FQIDAQABo14wXDAaBgNVHREE +EzARgglsb2NhbGhvc3SHBH8AAAEwHQYDVR0OBBYEFLal5fgbXAZz+Zg11+GEVbjT +ed0oMB8GA1UdIwQYMBaAFMcoPooETZGmQ44FaE298f3LsrBDMA0GCSqGSIb3DQEB +CwUAA4IBAQC2qhOwJ3ZtZ5wyvI7qKzQ0IHy3D01tjN80YnUXm1MLkc3Jt8N/6apT +SvtS7o/IAmjlctoR2Xg4XTp0zgECgIWAQ07G9rGF5+i3au9ydTkFY3mjBEFCaa/6 +oet/MYSfx5JBfQoz4GkQk7qBesz1HTP19w10HFYH5HoLGkWkd3SITYnAn0aSzMvi +ymstSd1O9/rFefIrPuSRuKAxsSdIH/L6q5LAmq/k4BM1WeV7zpjxcNc7+SdiiW22 +ZoXcPLYcKh9UsbYon//1lipvR+x/zB4t5YyaevbpaY4MRTASVHM7rF/szTQE5+VZ +a9vz/3X+K9QrpCGqOyMzU8A6zcNeV3Kc +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.key new file mode 100644 index 0000000000..880140dea7 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.key @@ -0,0 +1,30 @@ +-----BEGIN ENCRYPTED PRIVATE KEY----- +MIIFLTBXBgkqhkiG9w0BBQ0wSjApBgkqhkiG9w0BBQwwHAQI4hq3UcvHxeMCAggA +MAwGCCqGSIb3DQIJBQAwHQYJYIZIAWUDBAEqBBANIql3sdt63kUD9IS1h8uQBIIE +0AyuJU6umXXNb8aO5UwcfJoeiVT6P0xr8guiPXNHx/hZpEE21RoHEUlqRgStLFqH +AaeWOaPBNehqpcFnU34llM+XZMt7diL9nVkZFa5cePGuR6Od4ZE5S0xDmzyOpAbq +Hvn3FhZtDih9nyZHZUFO7WFZFxQLLE6YU9GOW8UsHEBt8Z2zbn4eBaVUw81Elpv6 +uhpx0H+apmj+TcXehv7FvWxn64nOQSDICuK6Zwva3DC4Bc0OpRAhWKR81w0hdufK +ej1mcANgGu/zTp3JJ9eGf1DX1TIB8nM7SXPVz+mDELZPu6U9kMBRoiQ8B24UEoRY +4VHODLDOoL7X+vbAk4oJVRqPnR/FvaAmzSTu4quOjRKE2fhBYD4oe4UTdp+5GxPK +4qcxS9eqe1/Jl4mPYCsM9oXdrRNVvk3lKPG63TVqEr6vrCfV+sogFYY/qY1sL81H +vkHF5QjqLTdWiSI82HiqoczQKfvZXdqZWB32YPiiZhv9LyyuTdHzvijFNRW6X6xf +Eng66BJ+S8TYr7ib+cUUy1OLyh5a6WAs/qsy2Fi02KOHN8BNfznwAqmJ14IbQrRQ +JjYaHhTHm+FZFpU+if32mSPr/CjmGuzhGNlh+Pm+5udDOvVcqAE9ifAZ9G9f9jgd +1vuTNOkWSwLcY2hs3vRN9VrDxbQ9PivB8Asr08F84KceJEaReN2CCiyCR++q95oH +2imrrQLH5EXM6Xc2k5OnltrWSLzvA58bJ+KcHj+MvRMx7kTjDcTrOHL0/xbqeXzU +TDaft8gGtudlFqy3/4kuV5Zp3E0Bgn/1WjUe8/VUJuYCX2ffhQVAc+Yum3o80Mu3 +RH7kEaZQeqnxC8qwiu6aOsqg3C74Hc+rguWeXnUV5Ysb3rcq1O50PGWEsey/+nxn +7I8hgZFvJrlYs05jQu93/Hzps5jVuxluRzFHuZcEM1v/12jNnY/C7yQSWctZFdD4 +h7DnzGjPgD/CRd0V63ScciRDfofQtFcshMEJjtCiP2tzmCMB4S7VB1186JdTLWys +u5OmQ76F2CcmBybksrx7dZyVB/z3gNB3/DObBVvVxn8z/WMqsoKjjXbJvHUBeo2W +KnZY7VHMjhsRGTLcxfL8jeS2clkEl4qOO0d47HIFy90BmLLpWosC+ZX5AMsrX2x7 +xV6yfXBGU5JHXRrofvC3AH33GlHkQ1r6r5SDqLDQrAAMm0eqlOjmiNM151M1uORw +m4r1csflKlIkWLwFVH1BIMmB8eGefyfS/4lXhx+UvvZKgFkJDJ3IJ0oHdj2zHiln +sp2WIm/nh9wqDh7fvGP+b1skVFlrChuTtjNHa4Ye2QagWRgZfAZAh89HuMfclC5x +0w971lLbnoC3iB7tjY8+J9Ye6Mzim6oZofROdBDxbDXraaYjcq/EezfFDPTUSpGx +JtX2Cr4nq596TucXXwKjHBHnjfhUPdeLRWBRSidkyogjrW68tVUCUZ7a0/3a2wz1 +6hRLvKzxnMGXfr1cggtX8PapgIXNOLxkjmLPmoEEQLNqOSXzx7y+iLGPzYcj2Fe+ +gV93fIq1IbwEChOFTHa/WtoN+idhESqvPvH2PKnWmAB5ioLYDCIQ6BnKWdPflrYh +mGfTg3YhOuwFmTkZPnvKux+yOLTDZfzeaMmBpdeQuHl3 +-----END ENCRYPTED PRIVATE KEY----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/root_ca.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/root_ca.crt new file mode 100644 index 0000000000..a01999b815 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/root_ca.crt @@ -0,0 +1,20 @@ +-----BEGIN CERTIFICATE----- +MIIDMTCCAhmgAwIBAgIUTbG8/x5SNhhMkhq1/spUkvTNGtUwDQYJKoZIhvcNAQEL +BQAwJzELMAkGA1UEBhMCVVMxGDAWBgNVBAMMD0V4YW1wbGUtUm9vdC1DQTAgFw0y +NDAxMDkxMDIwMjRaGA8yMTAwMDEwMTEwMjAyNFowJzELMAkGA1UEBhMCVVMxGDAW +BgNVBAMMD0V4YW1wbGUtUm9vdC1DQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC +AQoCggEBAL7K7lF5lXLunkNNI1ieuOgWyASA4fLNGxoGmZznwHCS3qVO2OmULy1Z +tKYCDZdQLRfc1GRR+PepbU5XVZUSm0k3VRVgT6FXrml6WVIISfjti18tZeybQzpt +c1HnnZk4prsq+pbckiCzFisg1xpG3CxyJUzrq010rKt1LGAeP32L0rI0yBBe08U6 +fSbX3kyGTl6bf3OIhpMVmg9VNB2LZm+FgEUG4OUpRT0yMk7Al+IxFt/R2TndfIhd +ZHu4t/lJLqHzfFyvM6XVEThP8y5eJ9dF0Oz6jUcNC45Tw6t9ubOGnwBriWkgLtw9 +4VK0XwK4tRvVQgptd2xro/sHFW14Sa0CAwEAAaNTMFEwHQYDVR0OBBYEFMcoPooE +TZGmQ44FaE298f3LsrBDMB8GA1UdIwQYMBaAFMcoPooETZGmQ44FaE298f3LsrBD +MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAGBnpnV8NoGoz8sF +IjEFwF76rfYT/NhYEE5SV9zOGE5kgbFh1N1+lAlcFpULsxXm+6ULnMZbrKGTDCKS +tD7XhPqTP5DHjxyXvD4VTZVgQ8NAUtttM+w8vdjIIHGHoQkdCo5QpGxqGZhlRCnM +HFQwmeXFKalln4qfgpkBA92K8H2eK/7ZhnnAGh/bclgOV7KOknV/hs7cBuwYIHVP +c7UCSyUMSkhujCysjRw5zjLiSM6bO8XFrVt0hOxZhV91mHXsIFZ2MopVIO4vPBHJ +q1z2XTu49XOrY4+N+7Sk37wImjfE5BD+U3GTw2QfoFO4EHd2JvvfoqS6Q5BtQ1lp +6OZswbA= +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/ssl_passwords.txt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/ssl_passwords.txt new file mode 100644 index 0000000000..bca0b5d502 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/ssl_passwords.txt @@ -0,0 +1,3 @@ +qwerty +123456 +topsecret diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml new file mode 100644 index 0000000000..c19495d871 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml @@ -0,0 +1,57 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + replicator: + password: 'topsecret' + roles: [replication] + +groups: + group001: + replicasets: + replicaset001: + replication: + failover: manual + leader: instance001 + iproto: + advertise: + peer: + login: replicator + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + params: + transport: 'ssl' + ssl_ca_file: 'certs/root_ca.crt' + ssl_cert_file: 'certs/instance001/server001.crt' + ssl_key_file: 'certs/instance001/server001.key' + ssl_password: 'qwerty' + ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + params: + transport: 'ssl' + ssl_ca_file: 'certs/root_ca.crt' + ssl_cert_file: 'certs/instance002/server002.crt' + ssl_key_file: 'certs/instance002/server002.key' + ssl_password_file: 'certs/ssl_passwords.txt' + ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + params: + transport: 'ssl' + ssl_ca_file: 'certs/root_ca.crt' + ssl_cert_file: 'certs/instance003/server003.crt' + ssl_key_file: 'certs/instance003/server003.key' + ssl_password_file: 'certs/ssl_passwords.txt' + ssl_ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256' + +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/instances.yml new file mode 100644 index 0000000000..9a634da7a0 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua new file mode 100644 index 0000000000..53182dbae3 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua @@ -0,0 +1,10 @@ +function connect() + local connection = require('net.box').connect({ + uri = 'admin:topsecret@127.0.0.1:3301', + params = { transport = 'ssl', + ssl_cert_file = 'certs/instance001/server001.crt', + ssl_key_file = 'certs/instance001/server001.key', + ssl_password = 'qwerty' } + }) + return connection +end diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md new file mode 100644 index 0000000000..14ad6e2937 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md @@ -0,0 +1,11 @@ +# SSL (without CA) + +A sample application demonstrating how to enable TLS traffic encryption for connections between replica set peers. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start ssl_without_ca +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/generate.sh b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/generate.sh new file mode 100644 index 0000000000..877f798985 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/generate.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -xeuo pipefail + +# 1. Generate an unencrypted server key. +openssl genrsa -out server.key 2048 + +# 2. Create a certificate signing request based on the server key. +openssl req -new -key server.key -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server/" -out server.csr + +# 3. Generate a server certificate. +openssl x509 -req -in server.csr -signkey server.key -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -out server.crt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.crt new file mode 100644 index 0000000000..1cef7b4fe9 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDhTCCAm2gAwIBAgIUM0cXJSowqJRoJlpwxgJBpS1V7KkwDQYJKoZIhvcNAQEL +BQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5 +MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UEAwwGc2VydmVy +MCAXDTI0MDExMjE0MTc1NFoYDzIxMDAwMTAxMTQxNzU0WjBcMQswCQYDVQQGEwJV +UzEOMAwGA1UECAwFU3RhdGUxDTALBgNVBAcMBENpdHkxHTAbBgNVBAoMFEV4YW1w +bGUtQ2VydGlmaWNhdGVzMQ8wDQYDVQQDDAZzZXJ2ZXIwggEiMA0GCSqGSIb3DQEB +AQUAA4IBDwAwggEKAoIBAQCekLkd2cXQfgRDBJK0LIEfzeH0C/AqQPr58qc3+A9i +MxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6cLcFPObd0XkDUbXQW1i2/BWI6ai3 +7FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxxEQqnr+K2+EhbqWfS88Gf5+1kWvJq +AyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBNqq9RQL+AcIdl5UFSApmnzOFDCdiK +qnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIBbvdsvGD7ONqewqdGC0xSa4Xx+XJn +8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnuRQ8FQifxAgMBAAGjPTA7MBoGA1Ud +EQQTMBGCCWxvY2FsaG9zdIcEfwAAATAdBgNVHQ4EFgQU6oCAZ+kJ88rox7OFt/tr +GIYQVFYwDQYJKoZIhvcNAQELBQADggEBABvev81NhG1DR5mS4UbpEvl6NGtcDE4H +yVKPpI3gfdJ3etZhV2FQ7nZZzQcTaqsm2IMr336s+nb4wrqDkZJ+OhYsU1OgFF3b +DM0BJ91YUeZz/redx7naxhawHn1BKXDvseNrH9C+XKa+1maK7bCYLkZZEtiOYZku +yD4pfBx+A+zipas3iQdLiXDkg+qoY2OmO+9bo+tvV8zzVx7V0+8L/NU8bU2d/Dgb +IuEPKc98hVx1W1v4RndrUmcneovbBEv82Y17RUqTi42TumsYjOjx/LvdD7RKBDZw +XVtjKL+zwuge9rQU4sZMAwN/tHanOXAfWG6/LU5RNW87b8+YcwOxMVc= +-----END CERTIFICATE----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.csr b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.csr new file mode 100644 index 0000000000..1c370f7281 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.csr @@ -0,0 +1,17 @@ +-----BEGIN CERTIFICATE REQUEST----- +MIICoTCCAYkCAQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYD +VQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UE +AwwGc2VydmVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnpC5HdnF +0H4EQwSStCyBH83h9AvwKkD6+fKnN/gPYjMWz6rs6v9u9kKgM09WF2FRzYy9EM8x +P9W7enC3BTzm3dF5A1G10FtYtvwViOmot+xS7Oqn6OzAPlEEwOWtIzayhldU3LSW +nuHccREKp6/itvhIW6ln0vPBn+ftZFryagMlDfNDc7rezIHwCjyxJ0Hou5hgZPlE +6N0gTaqvUUC/gHCHZeVBUgKZp8zhQwnYiqp8PZ7SKCVCIfpAFD8jWd9mqMPQQUQv +/YmyAW73bLxg+zjansKnRgtMUmuF8flyZ/JQU0xa8nOg+gvSq0QFf2O3IaCuEbJ9 +hi3J7kUPBUIn8QIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAF2jrSsrQyfET0Ux +SEeuyJemaLp8CYGbaICDIpM5jvq43ZGDKzQWqZGgOe2QmKR4mOqe2ixr3duwjpaK +Yd3eqQCMYkW9s5QdIs4AasQVMJXZ8uL5gIuFPtAT5BNa8GAhmpfUvHlLQeobZX4N +NpYaZZTLvQkjqnxOU9OQfnQ/89sa5zi8+G9xgWPnu3BOBznZvWsqcIVPZAekafvd +iP78wBWn9aF9CYrUvCmMmLgmwUe4BC3Lo4MvkosMFFH96oqrOPBztMv8swYGJBY8 +WFv1aJ8AtxpF9IGIDaP58TT0eEg/pDLGtPdaH4Q4TP9WkAs8Ybgn331xSmDDidLl +WQFHHXY= +-----END CERTIFICATE REQUEST----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.key new file mode 100644 index 0000000000..3c4abdba42 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.key @@ -0,0 +1,28 @@ +-----BEGIN PRIVATE KEY----- +MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCekLkd2cXQfgRD +BJK0LIEfzeH0C/AqQPr58qc3+A9iMxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6 +cLcFPObd0XkDUbXQW1i2/BWI6ai37FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxx +EQqnr+K2+EhbqWfS88Gf5+1kWvJqAyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBN +qq9RQL+AcIdl5UFSApmnzOFDCdiKqnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIB +bvdsvGD7ONqewqdGC0xSa4Xx+XJn8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnu +RQ8FQifxAgMBAAECggEAM20OjK7faCImsbGe/s5cRntYZ/UjPCD9BOl88DsEij21 +jT6LPh//1eB/4oQ9kLGgfUDC5Nu9xk1EU46Q3SMGYTSZwcjTZbLqj9YsCc52SMhd +kLb+JB38r3lJSGJ1B7GqrsVOIZJ0My1feFAlm4MAzYSyuv+zS4iA6KKorF6OtnCx +RIvWTWrQM0yIxm8HBpNu1hFLqr7QV57u18pz6zSnBTd5VTYivQQkv7JWR5ci2Hry +4yjVfwwh8Xcm8i8S+BZZ1hsVrVsoKmjMyqbj/Lrnx4/MsfCG3WQOL/ZP38w+z+Ds +XptopV3/ZKC8Dnyf3x7HyJ0uDGD0fAzxtdCslk3TrQKBgQC1nzyDX2i/uZlhK+3T +Nkj1LFakANY8yIY3AfPVJROuA+KERAkuTJfRfSxDUkE9QJyxy0S2DUSq2pOov33Q +6NH0wNEjCFRoXGqCgkNPbwECwJtKQWwsrHHpZZCINH7TyWCUi9p4tcAzww7UyUDT +JiJP7iOvxMCB8ebNca6rQ0xI+wKBgQDfgEj+PI8kXCP4qk2xcVJ+yOkwoSWoBS0s +KBV5pGgbO12NPDHal5ZWLpCZMi3Cw0gObEj5mYbcj+fkmk9xKhuxtfo4DQaAP5y4 +VnoXsaAwryLqG/iby3zAFkspN+5hoD8hmDXHrqrqC7AOmPrrAHIQHdt11TCBheEY +UuK+xrBXAwKBgE/+R4fRQPCYzW5YC9KoKTAbDDoFyFZTN5IIwR1SzD0rptv8n1KO +F5wEFre8BdH1oE5KqgPJCkJ6LOj5FnAp6zdyqWpVo9+nPJ4ow3679GUC8iKdeAih +FzbmLedfv7CGFIy4oEvkOThTJDgiP/P/6sLrrzoeXW+eXLqF5Jm39WR7AoGAYqSf +Er6turGEGtMneUJ304dfDFyDXzXxqwSB/e8nF6XK83P22PCApMbmgQbZlZVU7zCx +wKAXGq/U/Fty5pJcKMIVjrmI/f+VbvKT7nMyLWqO8V6pCjH0fF8aizWpW6M7Wdtx +GRGpU6UW7kpsrF3E+gIDg201fGUXZQHoG6Vb3PsCgYBRgDDKXXD0dKqU9GzO/og7 +WpJOZqI+OZoG778aP2HqQ8z9m93nQ0NTzXK8rRNDSEbd+QFFf9s5Y5gjjK5bsNUJ +mDziJ7B8tP2ecLcuO5DF2ro9nCPPYNixViKqZ1oJAFEIFetZzp7ZB6PFf7tcnXJ3 +aqTpCZBW2gL5iktwXYz+DA== +-----END PRIVATE KEY----- diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml new file mode 100644 index 0000000000..31343d07cf --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml @@ -0,0 +1,45 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + replicator: + password: 'topsecret' + roles: [replication] + +groups: + group001: + replicasets: + replicaset001: + replication: + failover: manual + leader: instance001 + iproto: + advertise: + peer: + login: replicator + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml new file mode 100644 index 0000000000..9a634da7a0 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: diff --git a/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/README.md b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/README.md new file mode 100644 index 0000000000..e17c4b0bec --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/README.md @@ -0,0 +1,31 @@ +# Master-replica: supervised failover + +A sample application demonstrating how to bootstrap a replica set that uses an [external failover coordinator](https://www.tarantool.io/doc/latest/concepts/replication/supervised_failover/). +The failover coordinator's state is stored in etcd along with a replica set configuration. + + +## Running + +1. Start etcd: + + ```console + $ etcd + ``` + +2. Publish a replica set configuration to etcd by executing the `tt cluster publish` command in the [replication](../../../replication) directory: + + ```console + $ tt cluster publish "http://localhost:2379/myapp" instances.enabled/supervised_failover/source.yaml + ``` + +3. To start the failover coordinator, execute the `tarantool` command with the `--failover` option: + + ```console + $ tarantool --failover --config instances.enabled/supervised_failover/config.yaml + ``` + +4. Then, start the application as follows: + + ```console + $ tt start supervised_failover + ``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/config.yaml new file mode 100644 index 0000000000..b21d92768e --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/config.yaml @@ -0,0 +1,8 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /myapp + http: + request: + timeout: 3 diff --git a/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml new file mode 100644 index 0000000000..f4c0a7d6ed --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml @@ -0,0 +1,42 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [ replication ] + privileges: + - permissions: [ execute ] + lua_call: [ 'failover.execute' ] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: supervised + +failover: + probe_interval: 5 + lease_interval: 15 + renew_interval: 5 + stateboard: + keepalive_interval: 5 + renew_interval: 1 + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' diff --git a/doc/code_snippets/snippets/replication/tt.yaml b/doc/code_snippets/snippets/replication/tt.yaml new file mode 100644 index 0000000000..41a3915f50 --- /dev/null +++ b/doc/code_snippets/snippets/replication/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/README.md b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/README.md new file mode 100644 index 0000000000..0eb14e6bfe --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/README.md @@ -0,0 +1,70 @@ +# Sharded cluster + +A sample application demonstrating how to configure a [sharded](https://www.tarantool.io/en/doc/latest/platform/sharding/) cluster. + +## Running + +To run the cluster, go to the `sharding` directory in the terminal and perform the following steps: + +1. Install dependencies defined in the `*.rockspec` file: + + ```console + $ tt build sharded_cluster + ``` + +2. Run the cluster: + + ```console + $ tt start sharded_cluster + ``` + +3. Connect to the router: + + ```console + $ tt connect sharded_cluster:router-a-001 + ``` + +4. Call `vshard.router.bootstrap()` to perform the initial cluster bootstrap: + + ```console + sharded_cluster:router-a-001> vshard.router.bootstrap() + --- + - true + ... + ``` + +5. Insert test data: + + ```console + sharded_cluster:router-a-001> insert_data() + --- + ... + ``` + +6. Connect to storages in different replica sets to see how data is distributed across nodes: + + a. `storage-a-001`: + + ```console + sharded_cluster:storage-a-001> box.space.bands:select() + --- + - - [1, 614, 'Roxette', 1986] + - [2, 986, 'Scorpions', 1965] + - [5, 755, 'Pink Floyd', 1965] + - [7, 998, 'The Doors', 1965] + - [8, 762, 'Nirvana', 1987] + ... + ``` + + b. `storage-b-001`: + + ```console + sharded_cluster:storage-b-001> box.space.bands:select() + --- + - - [3, 11, 'Ace of Base', 1987] + - [4, 42, 'The Beatles', 1960] + - [6, 55, 'The Rolling Stones', 1962] + - [9, 299, 'Led Zeppelin', 1968] + - [10, 167, 'Queen', 1970] + ... + ``` diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml new file mode 100644 index 0000000000..ca966083a6 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml @@ -0,0 +1,62 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + storage: + password: 'secret' + roles: [sharding] + +iproto: + advertise: + peer: + login: replicator + sharding: + login: storage + +sharding: + bucket_count: 1000 + +groups: + storages: + app: + module: storage + sharding: + roles: [storage] + replication: + failover: manual + replicasets: + storage-a: + leader: storage-a-001 + instances: + storage-a-001: + iproto: + listen: + - uri: '127.0.0.1:3302' + storage-a-002: + iproto: + listen: + - uri: '127.0.0.1:3303' + storage-b: + leader: storage-b-001 + instances: + storage-b-001: + iproto: + listen: + - uri: '127.0.0.1:3304' + storage-b-002: + iproto: + listen: + - uri: '127.0.0.1:3305' + routers: + app: + module: router + sharding: + roles: [router] + replicasets: + router-a: + instances: + router-a-001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/instances.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/instances.yaml new file mode 100644 index 0000000000..368bc16cb6 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/instances.yaml @@ -0,0 +1,5 @@ +storage-a-001: +storage-a-002: +storage-b-001: +storage-b-002: +router-a-001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/router.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/router.lua new file mode 100644 index 0000000000..27fbbd707f --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/router.lua @@ -0,0 +1,24 @@ +local vshard = require('vshard') + +function put(id, band_name, year) + local bucket_id = vshard.router.bucket_id_mpcrc32({ id }) + vshard.router.callrw(bucket_id, 'insert_band', { id, bucket_id, band_name, year }) +end + +function get(id) + local bucket_id = vshard.router.bucket_id_mpcrc32({ id }) + return vshard.router.callro(bucket_id, 'get_band', { id }) +end + +function insert_data() + put(1, 'Roxette', 1986) + put(2, 'Scorpions', 1965) + put(3, 'Ace of Base', 1987) + put(4, 'The Beatles', 1960) + put(5, 'Pink Floyd', 1965) + put(6, 'The Rolling Stones', 1962) + put(7, 'The Doors', 1965) + put(8, 'Nirvana', 1987) + put(9, 'Led Zeppelin', 1968) + put(10, 'Queen', 1970) +end diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec new file mode 100644 index 0000000000..5be1567c6b --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec @@ -0,0 +1,12 @@ +package = 'sharded_cluster' +version = 'scm-1' +source = { + url = '/dev/null', +} + +dependencies = { + 'vshard == 0.1.27' +} +build = { + type = 'none'; +} diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua new file mode 100644 index 0000000000..bc0b4ef3b2 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua @@ -0,0 +1,25 @@ +box.once('bands', function() + box.schema.create_space('bands', { + format = { + { name = 'id', type = 'unsigned' }, + { name = 'bucket_id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }, + if_not_exists = true + }) + box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true }) + box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true }) +end) + +function insert_band(id, bucket_id, band_name, year) + box.space.bands:insert({ id, bucket_id, band_name, year }) +end + +function get_band(id) + local tuple = box.space.bands:get(id) + if tuple == nil then + return nil + end + return { tuple.id, tuple.band_name, tuple.year } +end diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/README.md b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/README.md new file mode 100644 index 0000000000..043d08d4d0 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/README.md @@ -0,0 +1,7 @@ +# Sharded cluster with CRUD + +A sample application created in the [Creating a sharded cluster](https://www.tarantool.io/en/doc/latest/getting_started/vshard_quick/) tutorial. + +## Running + +To learn how to run the cluster, see the [Working with the cluster](https://www.tarantool.io/en/doc/latest/getting_started/vshard_quick/#working-with-the-cluster) section. diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml new file mode 100644 index 0000000000..dbccf140cb --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml @@ -0,0 +1,74 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [ replication ] + storage: + password: 'secret' + roles: [ sharding ] + +iproto: + advertise: + peer: + login: replicator + sharding: + login: storage + +sharding: + bucket_count: 1000 + +groups: + storages: + roles: [ roles.crud-storage ] + app: + module: storage + sharding: + roles: [ storage ] + replication: + failover: manual + replicasets: + storage-a: + leader: storage-a-001 + instances: + storage-a-001: + iproto: + listen: + - uri: '127.0.0.1:3302' + advertise: + client: '127.0.0.1:3302' + storage-a-002: + iproto: + listen: + - uri: '127.0.0.1:3303' + advertise: + client: '127.0.0.1:3303' + storage-b: + leader: storage-b-001 + instances: + storage-b-001: + iproto: + listen: + - uri: '127.0.0.1:3304' + advertise: + client: '127.0.0.1:3304' + storage-b-002: + iproto: + listen: + - uri: '127.0.0.1:3305' + advertise: + client: '127.0.0.1:3305' + routers: + roles: [ roles.crud-router ] + app: + module: router + sharding: + roles: [ router ] + replicasets: + router-a: + instances: + router-a-001: + iproto: + listen: + - uri: '127.0.0.1:3301' + advertise: + client: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/instances.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/instances.yaml new file mode 100644 index 0000000000..368bc16cb6 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/instances.yaml @@ -0,0 +1,5 @@ +storage-a-001: +storage-a-002: +storage-b-001: +storage-b-002: +router-a-001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua new file mode 100644 index 0000000000..61ccb2c40b --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua @@ -0,0 +1 @@ +local vshard = require('vshard') diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec new file mode 100644 index 0000000000..fb61077796 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec @@ -0,0 +1,13 @@ +package = 'sharded_cluster_crud' +version = 'scm-1' +source = { + url = '/dev/null', +} + +dependencies = { + 'vshard == 0.1.27', + 'crud == 1.5.2' +} +build = { + type = 'none'; +} diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua new file mode 100644 index 0000000000..f692015c03 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua @@ -0,0 +1,17 @@ +box.watch('box.status', function() + if box.info.ro then + return + end + + box.schema.create_space('bands', { + format = { + { name = 'id', type = 'unsigned' }, + { name = 'bucket_id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }, + if_not_exists = true + }) + box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true }) + box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true }) +end) diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/README.md b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/README.md new file mode 100644 index 0000000000..1d3419d44f --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/README.md @@ -0,0 +1,44 @@ +# Sharded cluster: Exposing metrics + +A sample application showing how to enable and expose [metrics](https://www.tarantool.io/doc/latest/book/monitoring/) through HTTP. + +## Running + +Before starting the application, install dependencies defined in the `*.rockspec` file: + +```console +$ tt build sharded_cluster_crud_metrics +``` + +Then, start the application: + +```console +$ tt start sharded_cluster_crud_metrics +``` + +To get Prometheus metrics, make the following request: + +```console +$ curl -X GET --location "http://127.0.0.1:8081/metrics/prometheus" +``` + +To get metrics in the JSON format, make the following request: + +```console +$ curl -X GET --location "http://127.0.0.1:8081/metrics/json" +``` + + +## Running the Prometheus server + +To monitor the metrics of a running sample, you need to install Prometheus either locally or using Docker. +To install and run Prometheus using Docker, follow the steps below: + +1. Open the [sharded_cluster_crud_metrics](../../../sharding/instances.enabled/sharded_cluster_crud_metrics) directory in the terminal. +2. Replace `127.0.0.1` with `host.docker.internal` in the `prometheus/prometheus.yml` file. +3. Then, run a server: + ```Bash + docker compose up + ``` +4. Open the [http://localhost:9090/graph](http://localhost:9090/graph) page to access the Prometheus expression browser. +5. Enter the desired Tarantool metric, for example, `tnt_info_uptime`or `tnt_info_memory_data` to see monitoring results. diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml new file mode 100644 index 0000000000..4e208542f2 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml @@ -0,0 +1,134 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [ replication ] + storage: + password: 'secret' + roles: [ sharding ] + +iproto: + advertise: + peer: + login: replicator + sharding: + login: storage + +sharding: + bucket_count: 1000 + +metrics: + include: [ all ] + exclude: [ vinyl ] + labels: + alias: '{{ instance_name }}' + +groups: + storages: + roles: + - roles.crud-storage + - roles.metrics-export + app: + module: storage + sharding: + roles: [ storage ] + replication: + failover: manual + replicasets: + storage-a: + leader: storage-a-001 + instances: + storage-a-001: + roles_cfg: + roles.metrics-export: + http: + - listen: '127.0.0.1:8082' + endpoints: + - path: /metrics/prometheus/ + format: prometheus + - path: /metrics/json + format: json + iproto: + listen: + - uri: '127.0.0.1:3302' + advertise: + client: '127.0.0.1:3302' + storage-a-002: + roles_cfg: + roles.metrics-export: + http: + - listen: '127.0.0.1:8083' + endpoints: + - path: /metrics/prometheus/ + format: prometheus + - path: /metrics/json + format: json + iproto: + listen: + - uri: '127.0.0.1:3303' + advertise: + client: '127.0.0.1:3303' + storage-b: + leader: storage-b-001 + instances: + storage-b-001: + roles_cfg: + roles.metrics-export: + http: + - listen: '127.0.0.1:8084' + endpoints: + - path: /metrics/prometheus/ + format: prometheus + - path: /metrics/json + format: json + iproto: + listen: + - uri: '127.0.0.1:3304' + advertise: + client: '127.0.0.1:3304' + storage-b-002: + roles_cfg: + roles.metrics-export: + http: + - listen: '127.0.0.1:8085' + endpoints: + - path: /metrics/prometheus/ + format: prometheus + - path: /metrics/json + format: json + iproto: + listen: + - uri: '127.0.0.1:3305' + advertise: + client: '127.0.0.1:3305' + routers: + roles: + - roles.crud-router + - roles.metrics-export + roles_cfg: + roles.crud-router: + stats: true + stats_driver: metrics + stats_quantiles: true + app: + module: router + sharding: + roles: [ router ] + replicasets: + router-a: + instances: + router-a-001: + roles_cfg: + roles.metrics-export: + http: + - listen: '127.0.0.1:8081' + endpoints: + - path: /metrics/prometheus/ + format: prometheus + - path: /metrics/json + format: json + iproto: + listen: + - uri: '127.0.0.1:3301' + advertise: + client: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/docker-compose.yml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/docker-compose.yml new file mode 100644 index 0000000000..fb0d5d974f --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/docker-compose.yml @@ -0,0 +1,27 @@ +services: + prometheus: + image: prom/prometheus + container_name: prometheus + command: + - '--config.file=/etc/prometheus/prometheus.yml' + ports: + - 9090:9090 + volumes: + - ./prometheus:/etc/prometheus + networks: + - monitoring_network + grafana: + image: grafana/grafana + container_name: grafana + ports: + - 3000:3000 + restart: unless-stopped + environment: + - GF_SECURITY_ADMIN_USER=admin + - GF_SECURITY_ADMIN_PASSWORD=grafana + networks: + - monitoring_network +networks: + monitoring_network: + name: monitoring_network + driver: bridge diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/instances.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/instances.yaml new file mode 100644 index 0000000000..96d4e2111f --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/instances.yaml @@ -0,0 +1,5 @@ +storage-a-001: +storage-a-002: +storage-b-001: +storage-b-002: +router-a-001: diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/prometheus/prometheus.yml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/prometheus/prometheus.yml new file mode 100644 index 0000000000..4fc09ed358 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/prometheus/prometheus.yml @@ -0,0 +1,14 @@ +global: + scrape_interval: 5s + evaluation_interval: 5s + +scrape_configs: + - job_name: prometheus + static_configs: + - targets: + - 127.0.0.1:8081 + - 127.0.0.1:8082 + - 127.0.0.1:8083 + - 127.0.0.1:8084 + - 127.0.0.1:8085 + metrics_path: "/metrics/prometheus" diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/router.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/router.lua new file mode 100644 index 0000000000..61ccb2c40b --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/router.lua @@ -0,0 +1 @@ +local vshard = require('vshard') diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/sharded_cluster_crud_metrics-scm-1.rockspec b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/sharded_cluster_crud_metrics-scm-1.rockspec new file mode 100644 index 0000000000..1245faba68 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/sharded_cluster_crud_metrics-scm-1.rockspec @@ -0,0 +1,14 @@ +package = 'sharded_cluster_crud_metrics' +version = 'scm-1' +source = { + url = '/dev/null', +} + +dependencies = { + 'vshard == 0.1.27', + 'crud == 1.5.2', + 'metrics-export-role == 0.1.0-1', +} +build = { + type = 'none'; +} diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/storage.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/storage.lua new file mode 100644 index 0000000000..f692015c03 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/storage.lua @@ -0,0 +1,17 @@ +box.watch('box.status', function() + if box.info.ro then + return + end + + box.schema.create_space('bands', { + format = { + { name = 'id', type = 'unsigned' }, + { name = 'bucket_id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }, + if_not_exists = true + }) + box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true }) + box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true }) +end) diff --git a/doc/code_snippets/snippets/sharding/templates/basic/MANIFEST.yaml b/doc/code_snippets/snippets/sharding/templates/basic/MANIFEST.yaml new file mode 100644 index 0000000000..10f9d4792f --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/MANIFEST.yaml @@ -0,0 +1,30 @@ +description: Basic template +vars: + - prompt: A name of the user for replication + name: replicator_user_name + default: replicator + + - prompt: A password for a replicator user + name: replicator_user_password + re: ^\w+$ + + - prompt: A name of the user for sharding + name: sharding_user_name + default: storage + + - prompt: A password for a sharding user + name: sharding_user_password + re: ^\w+$ + + - prompt: The number of buckets in a cluster + name: sharding_bucket_count + default: '1000' + + - prompt: A listen URI + name: listen_uri + default: '127.0.0.1' +include: + - config.yaml + - instances.yaml + - router.lua + - storage.lua diff --git a/doc/code_snippets/snippets/sharding/templates/basic/config.yaml.tt.template b/doc/code_snippets/snippets/sharding/templates/basic/config.yaml.tt.template new file mode 100644 index 0000000000..6add24cb64 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/config.yaml.tt.template @@ -0,0 +1,62 @@ +credentials: + users: + {{.replicator_user_name}}: + password: '{{.replicator_user_password}}' + roles: [replication] + {{.sharding_user_name}}: + password: '{{.sharding_user_password}}' + roles: [sharding] + +iproto: + advertise: + peer: + login: {{.replicator_user_name}} + sharding: + login: {{.sharding_user_name}} + +sharding: + bucket_count: {{.sharding_bucket_count}} + +groups: + storages: + app: + module: storage + sharding: + roles: [storage] + replication: + failover: manual + replicasets: + storage-a: + leader: storage-a-001 + instances: + storage-a-001: + iproto: + listen: + - uri: '{{.listen_uri}}:3302' + storage-a-002: + iproto: + listen: + - uri: '{{.listen_uri}}:3303' + storage-b: + leader: storage-b-001 + instances: + storage-b-001: + iproto: + listen: + - uri: '{{.listen_uri}}:3304' + storage-b-002: + iproto: + listen: + - uri: '{{.listen_uri}}:3305' + routers: + app: + module: router + sharding: + roles: [router] + replicasets: + router-a: + instances: + router-a-001: + iproto: + listen: + - uri: '{{.listen_uri}}:3301' diff --git a/doc/code_snippets/snippets/sharding/templates/basic/instances.yaml b/doc/code_snippets/snippets/sharding/templates/basic/instances.yaml new file mode 100644 index 0000000000..368bc16cb6 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/instances.yaml @@ -0,0 +1,5 @@ +storage-a-001: +storage-a-002: +storage-b-001: +storage-b-002: +router-a-001: \ No newline at end of file diff --git a/doc/code_snippets/snippets/sharding/templates/basic/router.lua b/doc/code_snippets/snippets/sharding/templates/basic/router.lua new file mode 100644 index 0000000000..4df433e3f6 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/router.lua @@ -0,0 +1,3 @@ +local vshard = require('vshard') + +-- Router code -- diff --git a/doc/code_snippets/snippets/sharding/templates/basic/storage.lua b/doc/code_snippets/snippets/sharding/templates/basic/storage.lua new file mode 100644 index 0000000000..87f063f033 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/storage.lua @@ -0,0 +1 @@ +-- Storage code -- diff --git a/doc/code_snippets/snippets/sharding/templates/basic/{{.name}}-scm-1.rockspec.tt.template b/doc/code_snippets/snippets/sharding/templates/basic/{{.name}}-scm-1.rockspec.tt.template new file mode 100644 index 0000000000..b34bf8e015 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/templates/basic/{{.name}}-scm-1.rockspec.tt.template @@ -0,0 +1,12 @@ +package = '{{ .name }}' +version = 'scm-1' +source = { + url = '/dev/null', +} + +dependencies = { + 'vshard == 0.1.27' +} +build = { + type = 'none'; +} diff --git a/doc/code_snippets/snippets/sharding/tt.yaml b/doc/code_snippets/snippets/sharding/tt.yaml new file mode 100644 index 0000000000..41a3915f50 --- /dev/null +++ b/doc/code_snippets/snippets/sharding/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/code_snippets/test/access_control/grant_roles_test.lua b/doc/code_snippets/test/access_control/grant_roles_test.lua new file mode 100644 index 0000000000..55204594fa --- /dev/null +++ b/doc/code_snippets/test/access_control/grant_roles_test.lua @@ -0,0 +1,104 @@ +local fio = require('fio') +local server = require('luatest.server') +local t = require('luatest') +local g = t.group() +g.before_all(function(cg) + cg.server = server:new { + box_cfg = {}, + workdir = fio.cwd() .. '/tmp' + } + cg.server:start() + cg.server:exec(function() + box.schema.space.create('writers') + box.space.writers:format({ + { name = 'id', type = 'unsigned' }, + { name = 'name', type = 'string' } + }) + box.space.writers:create_index('primary', { parts = { 'id' } }) + + box.schema.space.create('books') + box.space.books:format({ + { name = 'id', type = 'unsigned' }, + { name = 'title', type = 'string' }, + { name = 'author_id', foreign_key = { space = 'writers', field = 'id' } }, + }) + box.space.books:create_index('primary', { parts = { 'id' } }) + + box.space.writers:insert { 1, 'Leo Tolstoy' } + box.space.writers:insert { 2, 'Fyodor Dostoevsky' } + box.space.writers:insert { 3, 'Alexander Pushkin' } + + box.space.books:insert { 1, 'War and Peace', 1 } + box.space.books:insert { 2, 'Anna Karenina', 1 } + box.space.books:insert { 3, 'Resurrection', 1 } + box.space.books:insert { 4, 'Crime and Punishment', 2 } + box.space.books:insert { 5, 'The Idiot', 2 } + box.space.books:insert { 6, 'The Brothers Karamazov', 2 } + box.space.books:insert { 7, 'Eugene Onegin', 3 } + box.space.books:insert { 8, 'The Captain\'s Daughter', 3 } + box.space.books:insert { 9, 'Boris Godunov', 3 } + box.space.books:insert { 10, 'Ruslan and Ludmila', 3 } + end) +end) + +g.after_all(function(cg) + cg.server:drop() + fio.rmtree(cg.server.workdir) +end) + +g.test_role_granted_revoked = function(cg) + cg.server:exec(function() + box.schema.user.create('testuser', { password = 'foobar' }) + + -- Create roles -- + box.schema.role.create('books_space_manager') + box.schema.role.create('writers_space_reader') + -- End: Create roles -- + + -- Grant read/write privileges to a role -- + box.schema.role.grant('books_space_manager', 'read,write', 'space', 'books') + -- Grant write privileges to a role -- + box.schema.role.grant('writers_space_reader', 'read', 'space', 'writers') + -- End: Grant privileges to roles -- + + -- Grant a role to a role -- + box.schema.role.create('all_spaces_manager') + box.schema.role.grant('all_spaces_manager', 'books_space_manager') + box.schema.role.grant('all_spaces_manager', 'writers_space_reader') + -- End: Grant a role to a role -- + + -- Grant a role to a user -- + box.schema.user.grant('testuser', 'books_space_manager') + box.schema.user.grant('testuser', 'writers_space_reader') + -- End: Grant a role to a user -- + + -- Test removing a tuple from 'writers' -- + box.session.su('testuser') + local _, delete_writer_error = pcall(function() + box.space.writers:delete(3) + end) + t.assert_equals(delete_writer_error:unpack().message, "Write access to space 'writers' is denied for user 'testuser'") + box.session.su('admin') + + -- Revoking a role from a user -- + box.schema.user.revoke('testuser', 'execute', 'role', 'writers_space_reader') + -- End: Revoking a role from a user -- + + -- Test selecting data from 'writers' -- + box.session.su('testuser') + local _, select_writer_error = pcall(function() + box.space.writers:select(3) + end) + t.assert_equals(select_writer_error:unpack().message, "Read access to space 'writers' is denied for user 'testuser'") + box.session.su('admin') + + -- Dropping a role -- + box.schema.role.drop('writers_space_reader') + -- End: Dropping a role -- + + -- Test roles exist -- + t.assert_equals(box.schema.role.exists('books_space_manager'), true) + t.assert_equals(box.schema.role.exists('all_spaces_manager'), true) + t.assert_equals(box.schema.role.exists('writers_space_reader'), false) + end) +end diff --git a/doc/code_snippets/test/access_control/grant_user_privileges_test.lua b/doc/code_snippets/test/access_control/grant_user_privileges_test.lua new file mode 100644 index 0000000000..7e5f1b9e9a --- /dev/null +++ b/doc/code_snippets/test/access_control/grant_user_privileges_test.lua @@ -0,0 +1,138 @@ +local fio = require('fio') +local server = require('luatest.server') +local t = require('luatest') +local g = t.group() +g.before_all(function(cg) + cg.server = server:new { + box_cfg = {}, + workdir = fio.cwd() .. '/tmp' + } + cg.server:start() + cg.server:exec(function() + box.schema.space.create('writers') + box.space.writers:format({ + { name = 'id', type = 'unsigned' }, + { name = 'name', type = 'string' } + }) + box.space.writers:create_index('primary', { parts = { 'id' } }) + + box.schema.space.create('books') + box.space.books:format({ + { name = 'id', type = 'unsigned' }, + { name = 'title', type = 'string' }, + { name = 'author_id', foreign_key = { space = 'writers', field = 'id' } }, + }) + box.space.books:create_index('primary', { parts = { 'id' } }) + + box.space.writers:insert { 1, 'Leo Tolstoy' } + box.space.writers:insert { 2, 'Fyodor Dostoevsky' } + box.space.writers:insert { 3, 'Alexander Pushkin' } + + box.space.books:insert { 1, 'War and Peace', 1 } + box.space.books:insert { 2, 'Anna Karenina', 1 } + box.space.books:insert { 3, 'Resurrection', 1 } + box.space.books:insert { 4, 'Crime and Punishment', 2 } + box.space.books:insert { 5, 'The Idiot', 2 } + box.space.books:insert { 6, 'The Brothers Karamazov', 2 } + box.space.books:insert { 7, 'Eugene Onegin', 3 } + box.space.books:insert { 8, 'The Captain\'s Daughter', 3 } + box.space.books:insert { 9, 'Boris Godunov', 3 } + box.space.books:insert { 10, 'Ruslan and Ludmila', 3 } + end) +end) + +g.after_each(function(cg) + cg.server:exec(function() + if box.schema.user.exists('testuser') then + box.schema.user.drop('testuser') + end + end) +end) + +g.after_all(function(cg) + cg.server:drop() + fio.rmtree(cg.server.workdir) +end) + +g.test_user_without_password_created = function(cg) + cg.server:exec(function() + -- Create a user without a password -- + box.schema.user.create('testuser') + -- End: Create a user without a password -- + t.assert_equals(box.space._user.index.name:select { 'testuser' }[1][5]['chap-sha1'], nil) + end) +end + +g.test_user_with_password_created = function(cg) + cg.server:exec(function() + -- Create a user with a password -- + box.schema.user.create('testuser', { password = 'foobar' }) + -- End: Create a user with a password -- + t.assert_equals(box.space._user.index.name:select { 'testuser' }[1][5]['chap-sha1'], 'm1ADQ7xS4pERcutSrlz0hHYExuU=') + end) +end + +g.test_current_user_password_set = function(cg) + cg.server:exec(function() + box.session.su('admin') + -- Set a password for the current user -- + box.schema.user.passwd('foobar') + -- End: Set a password for the current user -- + t.assert_equals(box.space._user.index.name:select { 'admin' }[1][5]['chap-sha1'], 'm1ADQ7xS4pERcutSrlz0hHYExuU=') + end) +end + +g.test_specified_user_password_set = function(cg) + cg.server:exec(function() + box.schema.user.create('testuser') + -- Set a password for the specified user -- + box.schema.user.passwd('testuser', 'foobar') + -- End: Set a password for the specified user -- + t.assert_equals(box.space._user.index.name:select { 'testuser' }[1][5]['chap-sha1'], 'm1ADQ7xS4pERcutSrlz0hHYExuU=') + end) +end + +g.test_grant_revoke_privileges_user = function(cg) + cg.server:exec(function() + box.schema.user.create('testuser', { password = 'foobar' }) + box.schema.user.grant('testuser', 'execute', 'universe') + -- Grant privileges to the specified user -- + box.schema.user.grant('testuser', 'read', 'space', 'writers') + box.schema.user.grant('testuser', 'read,write', 'space', 'books') + -- End: Grant privileges to the specified user -- + box.session.su('testuser') + local _, delete_writer_error = pcall(function() + box.space.writers:delete(3) + end) + t.assert_equals(delete_writer_error:unpack().message, "Write access to space 'writers' is denied for user 'testuser'") + + box.session.su('admin') + -- Revoke space reading -- + box.schema.user.revoke('testuser', 'write', 'space', 'books') + -- End: Revoke space reading -- + box.session.su('testuser') + local _, delete_book_error = pcall(function() + box.space.books:delete(10) + end) + t.assert_equals(delete_book_error:unpack().message, "Write access to space 'books' is denied for user 'testuser'") + + box.session.su('admin') + -- Revoke session -- + box.schema.user.revoke('testuser', 'session', 'universe') + -- End: Revoke session -- + local _, change_user_error = pcall(function() + box.session.su('testuser') + end) + t.assert_equals(change_user_error:unpack().message, "Session access to universe '' is denied for user 'testuser'") + end) +end + +g.test_user_dropped = function(cg) + cg.server:exec(function() + box.schema.user.create('testuser') + -- Drop a user -- + box.schema.user.drop('testuser') + -- End: Drop a user -- + t.assert_equals(box.schema.user.exists('testuser'), false) + end) +end diff --git a/doc/code_snippets/test/checks/checkers_test.lua b/doc/code_snippets/test/checks/checkers_test.lua index ee9f3c6ae0..23826a1d4c 100644 --- a/doc/code_snippets/test/checks/checkers_test.lua +++ b/doc/code_snippets/test/checks/checkers_test.lua @@ -20,7 +20,7 @@ local is_uint64 = checkers.uint64(2048) -- is_int64/is_uint64 = true -- tuple checker -local is_tuple = checkers.tuple(box.tuple.new(1, 'The Beatles', 1960)) +local is_tuple = checkers.tuple(box.tuple.new{1, 'The Beatles', 1960}) -- is_tuple = true -- uuid checkers diff --git a/doc/code_snippets/test/constraints/constraint_sql_expr_test.lua b/doc/code_snippets/test/constraints/constraint_sql_expr_test.lua index 61af6ddeda..84bd260e40 100644 --- a/doc/code_snippets/test/constraints/constraint_sql_expr_test.lua +++ b/doc/code_snippets/test/constraints/constraint_sql_expr_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_constraints = function(cg) @@ -42,21 +42,21 @@ g.test_constraints = function(cg) local _, age_err = pcall(function() -- insert_age_error_start customers:insert { 2, "Bob", 18 } - -- error: Check constraint 'check_person' failed for tuple + -- error: Check constraint 'check_person' failed for a tuple -- insert_age_error_end end) local _, name_err = pcall(function() -- insert_name_error_start customers:insert { 3, "Admin", 25 } - -- error: Check constraint 'check_person' failed for tuple + -- error: Check constraint 'check_person' failed for a tuple -- insert_name_error_end end) -- Tests -- t.assert_equals(customers:count(), 1) t.assert_equals(customers:get(1), { 1, "Alice", 30 }) - t.assert_equals(age_err:unpack().message, 'Check constraint \'check_person\' failed for tuple') - t.assert_equals(name_err:unpack().message, 'Check constraint \'check_person\' failed for tuple') + t.assert_equals(age_err:unpack().message, 'Check constraint \'check_person\' failed for a tuple') + t.assert_equals(name_err:unpack().message, 'Check constraint \'check_person\' failed for a tuple') end) end diff --git a/doc/code_snippets/test/constraints/constraint_test.lua b/doc/code_snippets/test/constraints/constraint_test.lua index cd37ee25e7..ac5b7e8817 100644 --- a/doc/code_snippets/test/constraints/constraint_test.lua +++ b/doc/code_snippets/test/constraints/constraint_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_constraints = function(cg) @@ -50,8 +50,8 @@ g.test_constraints = function(cg) t.assert_equals(customers:count(), 1) t.assert_equals(customers:get(1), {1, "Alice", 30}) - -- Failed contstraint -- - t.assert_error_msg_contains("Check constraint 'check_person' failed for tuple", + -- Failed constraint -- + t.assert_error_msg_contains("Check constraint 'check_person' failed for a tuple", function() customers:insert{2, "Bob", 230} end) -- Create one more tuple constraint -- diff --git a/doc/code_snippets/test/default_values/default_functions_test.lua b/doc/code_snippets/test/default_values/default_functions_test.lua new file mode 100644 index 0000000000..2bf6b7d35b --- /dev/null +++ b/doc/code_snippets/test/default_values/default_functions_test.lua @@ -0,0 +1,65 @@ +local fio = require('fio') +local server = require('luatest.server') +local t = require('luatest') +local g = t.group() +g.before_each(function(cg) + cg.server = server:new { + box_cfg = {}, + workdir = fio.cwd() .. '/tmp' + } + cg.server:start() +end) + +g.after_each(function(cg) + cg.server:drop() + fio.rmtree(cg.server.workdir) +end) + +g.test_default_func = function(cg) + cg.server:exec(function() + + -- create_no_arg_function_start + box.schema.func.create('current_year', { + language = 'Lua', + body = "function() return require('datetime').now().year end" + }) + -- create_no_arg_function_end + + -- format_space_default_func_start + local books = box.schema.space.create('books') + books:format({ + { name = 'id', type = 'unsigned' }, + { name = 'isbn', type = 'string' }, + { name = 'title', type = 'string' }, + { name = 'year', type = 'unsigned', default_func = 'current_year' } + }) + books:create_index('primary', { parts = { 1 } }) + -- format_space_default_func_end + + -- insert_ok_start + books:insert { 1, '978000', 'Thinking in Java' } + -- insert_ok_end + + -- create_arg_function_start + box.schema.func.create('randomize', { + language = 'Lua', + body = "function(limit) return math.random(limit.min, limit.max) end" + }) + -- create_arg_function_end + + -- reformat_space_start + books:format({ + { name = 'id', type = 'unsigned', default_func= 'randomize', default = {min = 0, max = 1000} }, + { name = 'isbn', type = 'string' }, + { name = 'title', type = 'string' }, + { name = 'year', type = 'unsigned', default_func = 'current_year' } + }) + -- reformat_space_end + + books:insert { nil, '978001', 'How to code in Go' } + + -- Tests -- + t.assert_equals(books:count(), 2) + t.assert_equals(books:get(1), { 1, '978000','Thinking in Java', 2024 }) + end) +end \ No newline at end of file diff --git a/doc/code_snippets/test/default_values/explicit_default_test.lua b/doc/code_snippets/test/default_values/explicit_default_test.lua new file mode 100644 index 0000000000..874c70ef79 --- /dev/null +++ b/doc/code_snippets/test/default_values/explicit_default_test.lua @@ -0,0 +1,39 @@ +local fio = require('fio') +local server = require('luatest.server') +local t = require('luatest') +local g = t.group() +g.before_each(function(cg) + cg.server = server:new { + box_cfg = {}, + workdir = fio.cwd() .. '/tmp' + } + cg.server:start() +end) + +g.after_each(function(cg) + cg.server:drop() + fio.rmtree(cg.server.workdir) +end) + +g.test_default_values = function(cg) + cg.server:exec(function() + -- configure_space_start + local books = box.schema.space.create('books') + books:format({ + { name = 'id', type = 'number' }, + { name = 'name', type = 'string' }, + { name = 'year', type = 'number', default = 2024 }, + }) + books:create_index('primary', { parts = { 1 } }) + -- configure_space_end + + -- insert_ok_start + books:insert { 1, 'Thinking in Java' } + books:insert { 2, 'How to code in Go', nil } + -- insert_ok_end + + -- Tests -- + t.assert_equals(books:count(), 2) + t.assert_equals(books:get(1), { 1, 'Thinking in Java', 2024 }) + end) +end \ No newline at end of file diff --git a/doc/code_snippets/test/foreign_keys/field_foreign_key_test.lua b/doc/code_snippets/test/foreign_keys/field_foreign_key_test.lua index 196018545c..2aab77aeea 100644 --- a/doc/code_snippets/test/foreign_keys/field_foreign_key_test.lua +++ b/doc/code_snippets/test/foreign_keys/field_foreign_key_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_foreign_keys = function(cg) diff --git a/doc/code_snippets/test/foreign_keys/tuple_foreign_key_test.lua b/doc/code_snippets/test/foreign_keys/tuple_foreign_key_test.lua index 325c0705b7..4701d92362 100644 --- a/doc/code_snippets/test/foreign_keys/tuple_foreign_key_test.lua +++ b/doc/code_snippets/test/foreign_keys/tuple_foreign_key_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_foreign_keys = function(cg) diff --git a/doc/code_snippets/test/http_client/default_client_get_test.lua b/doc/code_snippets/test/http_client/default_client_get_test.lua new file mode 100644 index 0000000000..c8d7f949f9 --- /dev/null +++ b/doc/code_snippets/test/http_client/default_client_get_test.lua @@ -0,0 +1,9 @@ +local http_client = require('http.client') +local response = http_client.get('https://httpbin.org/get') +print('Status: '..response.status..' '.. response.reason) + +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_returns_status = function() + luatest.assert_equals(response.status, 200) +end diff --git a/doc/code_snippets/test/indexes/create_index_field_number_test.lua b/doc/code_snippets/test/indexes/create_index_field_number_test.lua index 6126112dc5..8857ddf2f3 100644 --- a/doc/code_snippets/test/indexes/create_index_field_number_test.lua +++ b/doc/code_snippets/test/indexes/create_index_field_number_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_indexes = function(cg) diff --git a/doc/code_snippets/test/indexes/create_index_func_multikey_test.lua b/doc/code_snippets/test/indexes/create_index_func_multikey_test.lua index 2ad5d70d27..84ef8fdbdd 100644 --- a/doc/code_snippets/test/indexes/create_index_func_multikey_test.lua +++ b/doc/code_snippets/test/indexes/create_index_func_multikey_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_func_multikey_index = function(cg) diff --git a/doc/code_snippets/test/indexes/create_index_func_test.lua b/doc/code_snippets/test/indexes/create_index_func_test.lua index 2250add97a..e62fed9700 100644 --- a/doc/code_snippets/test/indexes/create_index_func_test.lua +++ b/doc/code_snippets/test/indexes/create_index_func_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_func_index = function(cg) diff --git a/doc/code_snippets/test/indexes/create_index_json_path_test.lua b/doc/code_snippets/test/indexes/create_index_json_path_test.lua index 6e98633be5..9d50bb814c 100644 --- a/doc/code_snippets/test/indexes/create_index_json_path_test.lua +++ b/doc/code_snippets/test/indexes/create_index_json_path_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_json_path_index = function(cg) diff --git a/doc/code_snippets/test/indexes/create_index_key_parts_test.lua b/doc/code_snippets/test/indexes/create_index_key_parts_test.lua index 6fb1b401a2..87a733231a 100644 --- a/doc/code_snippets/test/indexes/create_index_key_parts_test.lua +++ b/doc/code_snippets/test/indexes/create_index_key_parts_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_indexes = function(cg) diff --git a/doc/code_snippets/test/indexes/index_aggr_functions_test.lua b/doc/code_snippets/test/indexes/index_aggr_functions_test.lua index 630e051f42..71d7c9b8a3 100644 --- a/doc/code_snippets/test/indexes/index_aggr_functions_test.lua +++ b/doc/code_snippets/test/indexes/index_aggr_functions_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_indexes = function(cg) diff --git a/doc/code_snippets/test/indexes/index_custom_function_test.lua b/doc/code_snippets/test/indexes/index_custom_function_test.lua index 462ade33ad..2da068a330 100644 --- a/doc/code_snippets/test/indexes/index_custom_function_test.lua +++ b/doc/code_snippets/test/indexes/index_custom_function_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_indexes = function(cg) diff --git a/doc/code_snippets/test/indexes/index_select_test.lua b/doc/code_snippets/test/indexes/index_select_test.lua index ee4403f8cd..14bfd54027 100644 --- a/doc/code_snippets/test/indexes/index_select_test.lua +++ b/doc/code_snippets/test/indexes/index_select_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_indexes = function(cg) diff --git a/doc/code_snippets/test/logging/log_existing_c_modules_test.lua b/doc/code_snippets/test/logging/log_existing_c_modules_test.lua index 2fba3bc083..0897e489c3 100644 --- a/doc/code_snippets/test/logging/log_existing_c_modules_test.lua +++ b/doc/code_snippets/test/logging/log_existing_c_modules_test.lua @@ -31,8 +31,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) local function find_in_log(cg, str, must_be_present) diff --git a/doc/code_snippets/test/logging/log_existing_modules_test.lua b/doc/code_snippets/test/logging/log_existing_modules_test.lua index 7ee515d2bf..08d4e672d0 100644 --- a/doc/code_snippets/test/logging/log_existing_modules_test.lua +++ b/doc/code_snippets/test/logging/log_existing_modules_test.lua @@ -39,8 +39,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) local function find_in_log(cg, str, must_be_present) diff --git a/doc/code_snippets/test/logging/log_new_modules_test.lua b/doc/code_snippets/test/logging/log_new_modules_test.lua index 82302a545a..b7dee6ba7d 100644 --- a/doc/code_snippets/test/logging/log_new_modules_test.lua +++ b/doc/code_snippets/test/logging/log_new_modules_test.lua @@ -43,8 +43,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) local function find_in_log(cg, str, must_be_present) diff --git a/doc/code_snippets/test/logging/log_test.lua b/doc/code_snippets/test/logging/log_test.lua index ed913473e3..278cd43986 100644 --- a/doc/code_snippets/test/logging/log_test.lua +++ b/doc/code_snippets/test/logging/log_test.lua @@ -6,32 +6,22 @@ local g = t.group() g.before_each(function(cg) cg.server = server:new { workdir = fio.cwd() .. '/tmp', - box_cfg = { log_level = 'warn' } + box_cfg = {} } cg.server:start() cg.server:exec(function() - log = require('log') - - -- Prints 'warn' messages -- + local log = require('log') + log.cfg { level = 'verbose' } log.warn('Warning message') - --[[ - 2023-07-20 11:03:57.029 [16300] main/103/interactive/tarantool [C]:-1 W> Warning message - --- - ... - --]] - - -- Swallows 'debug' messages -- + log.info('Tarantool version: %s', box.info.version) + log.error({ 500, 'Internal error' }) log.debug('Debug message') - --[[ - --- - ... - --]] end) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) local function find_in_log(cg, str, must_be_present) @@ -43,5 +33,7 @@ end g.test_log_contains_messages = function(cg) find_in_log(cg, 'Warning message', true) + find_in_log(cg, 'Tarantool version:', true) + find_in_log(cg, 'Internal error', true) find_in_log(cg, 'Debug message', false) end diff --git a/doc/code_snippets/test/msgpack/msgpack_object_index_test.lua b/doc/code_snippets/test/msgpack/msgpack_object_index_test.lua index ee9fa88cd5..9cbfc69804 100644 --- a/doc/code_snippets/test/msgpack/msgpack_object_index_test.lua +++ b/doc/code_snippets/test/msgpack/msgpack_object_index_test.lua @@ -2,7 +2,7 @@ local msgpack = require('msgpack') local mp_from_array = msgpack.object({ 10, 20, 30 }) local mp_from_table = msgpack.object({ band_name = 'The Beatles', year = 1960 }) -local mp_from_tuple = msgpack.object(box.tuple.new(1, 'The Beatles', 1960)) +local mp_from_tuple = msgpack.object(box.tuple.new{1, 'The Beatles', 1960}) -- Get MsgPack data by the specified index or key local mp_array_get_by_index = mp_from_array[1] -- Returns 10 diff --git a/doc/code_snippets/test/msgpack/msgpack_object_test.lua b/doc/code_snippets/test/msgpack/msgpack_object_test.lua index 1718d18b18..7d52ff0093 100644 --- a/doc/code_snippets/test/msgpack/msgpack_object_test.lua +++ b/doc/code_snippets/test/msgpack/msgpack_object_test.lua @@ -5,7 +5,7 @@ local mp_from_number = msgpack.object(123) local mp_from_string = msgpack.object('hello world') local mp_from_array = msgpack.object({ 10, 20, 30 }) local mp_from_table = msgpack.object({ band_name = 'The Beatles', year = 1960 }) -local mp_from_tuple = msgpack.object(box.tuple.new(1, 'The Beatles', 1960)) +local mp_from_tuple = msgpack.object(box.tuple.new{1, 'The Beatles', 1960}) -- Create a MsgPack object from a raw MsgPack string local raw_mp_string = msgpack.encode({ 10, 20, 30 }) diff --git a/doc/code_snippets/test/sequence/sequence_test.lua b/doc/code_snippets/test/sequence/sequence_test.lua index 5c702dda73..c0f7486fc1 100644 --- a/doc/code_snippets/test/sequence/sequence_test.lua +++ b/doc/code_snippets/test/sequence/sequence_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_sequence = function(cg) diff --git a/doc/code_snippets/test/sql/array_access_test.lua b/doc/code_snippets/test/sql/array_access_test.lua index ff05428e0e..341947e788 100644 --- a/doc/code_snippets/test/sql/array_access_test.lua +++ b/doc/code_snippets/test/sql/array_access_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/sql/check_table_constraint_test.lua b/doc/code_snippets/test/sql/check_table_constraint_test.lua index c8a6862fe9..54e4721431 100644 --- a/doc/code_snippets/test/sql/check_table_constraint_test.lua +++ b/doc/code_snippets/test/sql/check_table_constraint_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) @@ -36,12 +36,12 @@ g.test_space_is_updated = function(cg) -- insert_short_name_start INSERT INTO author VALUES (3, 'Alex'); /* - - Check constraint 'CHECK_NAME_LENGTH' failed for tuple + - Check constraint 'check_name_length' failed for a tuple */ -- insert_short_name_end ]]) -- Tests - t.assert_equals(insert_author_err:unpack().message, "Check constraint 'CHECK_NAME_LENGTH' failed for tuple") + t.assert_equals(insert_author_err:unpack().message, "Check constraint 'check_name_length' failed for a tuple") end) end diff --git a/doc/code_snippets/test/sql/foreign_key_table_constraint_test.lua b/doc/code_snippets/test/sql/foreign_key_table_constraint_test.lua index 4ed831343a..e5b3fcf680 100644 --- a/doc/code_snippets/test/sql/foreign_key_table_constraint_test.lua +++ b/doc/code_snippets/test/sql/foreign_key_table_constraint_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) @@ -53,7 +53,7 @@ g.test_space_is_updated = function(cg) -- insert_error_start INSERT INTO book VALUES (3, 'Eugene Onegin', 3); /* - - 'Foreign key constraint ''fk_unnamed_BOOK_1'' failed: foreign tuple was not found' + - 'Foreign key constraint ''fk_unnamed_book_1'' failed: foreign tuple was not found' */ -- insert_error_end ]]) @@ -61,7 +61,7 @@ g.test_space_is_updated = function(cg) -- update_error_start UPDATE book SET author_id = 10 WHERE id = 1; /* - - 'Foreign key constraint ''fk_unnamed_BOOK_1'' failed: foreign tuple was not found' + - 'Foreign key constraint ''fk_unnamed_book_1'' failed: foreign tuple was not found' */ -- update_error_end ]]) @@ -69,14 +69,14 @@ g.test_space_is_updated = function(cg) -- delete_error_start DELETE FROM author WHERE id = 2; /* - - 'Foreign key ''fk_unnamed_BOOK_1'' integrity check failed: tuple is referenced' + - 'Foreign key ''fk_unnamed_book_1'' integrity check failed: tuple is referenced' */ -- delete_error_end ]]) -- Tests - t.assert_equals(insert_err:unpack().message, "Foreign key constraint 'fk_unnamed_BOOK_1' failed: foreign tuple was not found") - t.assert_equals(update_err:unpack().message, "Foreign key constraint 'fk_unnamed_BOOK_1' failed: foreign tuple was not found") - t.assert_equals(delete_err:unpack().message, "Foreign key 'fk_unnamed_BOOK_1' integrity check failed: tuple is referenced") + t.assert_equals(insert_err:unpack().message, "Foreign key constraint 'fk_unnamed_book_1' failed: foreign tuple was not found") + t.assert_equals(update_err:unpack().message, "Foreign key constraint 'fk_unnamed_book_1' failed: foreign tuple was not found") + t.assert_equals(delete_err:unpack().message, "Foreign key 'fk_unnamed_book_1' integrity check failed: tuple is referenced") end) end diff --git a/doc/code_snippets/test/sql/map_access_test.lua b/doc/code_snippets/test/sql/map_access_test.lua index b0bf49a1e1..1e24110826 100644 --- a/doc/code_snippets/test/sql/map_access_test.lua +++ b/doc/code_snippets/test/sql/map_access_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/sql/primary_key_table_constraint_test.lua b/doc/code_snippets/test/sql/primary_key_table_constraint_test.lua index f981e271b7..cc3a022e79 100644 --- a/doc/code_snippets/test/sql/primary_key_table_constraint_test.lua +++ b/doc/code_snippets/test/sql/primary_key_table_constraint_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) @@ -35,7 +35,7 @@ g.test_space_is_updated = function(cg) -- insert_duplicate_author_start INSERT INTO author VALUES (2, 'Alexander Pushkin'); /* - - Duplicate key exists in unique index "pk_unnamed_AUTHOR_1" in space "AUTHOR" with + - Duplicate key exists in unique index "pk_unnamed_author_1" in space "author" with old tuple - [2, "Fyodor Dostoevsky"] and new tuple - [2, "Alexander Pushkin"] */ -- insert_duplicate_author_end @@ -59,14 +59,14 @@ g.test_space_is_updated = function(cg) -- insert_duplicate_book_start INSERT INTO book VALUES (2, 'Crime and Punishment'); /* - - Duplicate key exists in unique index "pk_unnamed_BOOK_1" in space "BOOK" with old + - Duplicate key exists in unique index "pk_unnamed_book_1" in space "BOOK" with old tuple - [2, "Crime and Punishment"] and new tuple - [2, "Crime and Punishment"] */ -- insert_duplicate__book_end ]]) -- Tests - t.assert_equals(insert_author_err:unpack().message, "Duplicate key exists in unique index \"pk_unnamed_AUTHOR_1\" in space \"AUTHOR\" with old tuple - [2, \"Fyodor Dostoevsky\"] and new tuple - [2, \"Alexander Pushkin\"]") - t.assert_equals(insert_book_err:unpack().message, "Duplicate key exists in unique index \"pk_unnamed_BOOK_1\" in space \"BOOK\" with old tuple - [2, \"Crime and Punishment\"] and new tuple - [2, \"Crime and Punishment\"]") + t.assert_equals(insert_author_err:unpack().message, "Duplicate key exists in unique index \"pk_unnamed_author_1\" in space \"author\" with old tuple - [2, \"Fyodor Dostoevsky\"] and new tuple - [2, \"Alexander Pushkin\"]") + t.assert_equals(insert_book_err:unpack().message, "Duplicate key exists in unique index \"pk_unnamed_book_1\" in space \"book\" with old tuple - [2, \"Crime and Punishment\"] and new tuple - [2, \"Crime and Punishment\"]") end) end diff --git a/doc/code_snippets/test/sql/unique_table_constraint_test.lua b/doc/code_snippets/test/sql/unique_table_constraint_test.lua index fdf53bb7a5..2bcfa2fb66 100644 --- a/doc/code_snippets/test/sql/unique_table_constraint_test.lua +++ b/doc/code_snippets/test/sql/unique_table_constraint_test.lua @@ -11,8 +11,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) @@ -35,7 +35,7 @@ g.test_space_is_updated = function(cg) -- insert_duplicate_author_start INSERT INTO author VALUES (3, 'Leo Tolstoy'); /* - - Duplicate key exists in unique index "unique_unnamed_AUTHOR_2" in space "AUTHOR" + - Duplicate key exists in unique index "unique_unnamed_author_2" in space "author" with old tuple - [1, "Leo Tolstoy"] and new tuple - [3, "Leo Tolstoy"] */ -- insert_duplicate_author_end @@ -60,14 +60,14 @@ g.test_space_is_updated = function(cg) -- insert_duplicate_book_start INSERT INTO book VALUES (3, 'War and Peace', 1); /* - - Duplicate key exists in unique index "unique_unnamed_BOOK_2" in space "BOOK" with + - Duplicate key exists in unique index "unique_unnamed_book_2" in space "book" with old tuple - [1, "War and Peace", 1] and new tuple - [3, "War and Peace", 1] */ -- insert_duplicate__book_end ]]) -- Tests - t.assert_equals(insert_author_err:unpack().message, "Duplicate key exists in unique index \"unique_unnamed_AUTHOR_2\" in space \"AUTHOR\" with old tuple - [1, \"Leo Tolstoy\"] and new tuple - [3, \"Leo Tolstoy\"]") - t.assert_equals(insert_book_err:unpack().message, "Duplicate key exists in unique index \"unique_unnamed_BOOK_2\" in space \"BOOK\" with old tuple - [1, \"War and Peace\", 1] and new tuple - [3, \"War and Peace\", 1]") + t.assert_equals(insert_author_err:unpack().message, "Duplicate key exists in unique index \"unique_unnamed_author_2\" in space \"author\" with old tuple - [1, \"Leo Tolstoy\"] and new tuple - [3, \"Leo Tolstoy\"]") + t.assert_equals(insert_book_err:unpack().message, "Duplicate key exists in unique index \"unique_unnamed_book_2\" in space \"book\" with old tuple - [1, \"War and Peace\", 1] and new tuple - [3, \"War and Peace\", 1]") end) end diff --git a/doc/code_snippets/test/transactions/box_atomic_test.lua b/doc/code_snippets/test/transactions/box_atomic_test.lua index 46c0c7167b..6e5f3870c2 100644 --- a/doc/code_snippets/test/transactions/box_atomic_test.lua +++ b/doc/code_snippets/test/transactions/box_atomic_test.lua @@ -19,8 +19,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/transactions/box_commit_test.lua b/doc/code_snippets/test/transactions/box_commit_test.lua index 122572a58f..5190cfe8a1 100644 --- a/doc/code_snippets/test/transactions/box_commit_test.lua +++ b/doc/code_snippets/test/transactions/box_commit_test.lua @@ -20,8 +20,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/transactions/box_on_commit_iterator_test.lua b/doc/code_snippets/test/transactions/box_on_commit_iterator_test.lua index 68deaecb16..8072c9ebff 100644 --- a/doc/code_snippets/test/transactions/box_on_commit_iterator_test.lua +++ b/doc/code_snippets/test/transactions/box_on_commit_iterator_test.lua @@ -20,8 +20,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/transactions/box_on_commit_test.lua b/doc/code_snippets/test/transactions/box_on_commit_test.lua index d1ed66a15d..aae0aedcdd 100644 --- a/doc/code_snippets/test/transactions/box_on_commit_test.lua +++ b/doc/code_snippets/test/transactions/box_on_commit_test.lua @@ -20,8 +20,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated = function(cg) diff --git a/doc/code_snippets/test/transactions/box_rollback_savepoint_test.lua b/doc/code_snippets/test/transactions/box_rollback_savepoint_test.lua index bfcf89a8d7..31e86a3881 100644 --- a/doc/code_snippets/test/transactions/box_rollback_savepoint_test.lua +++ b/doc/code_snippets/test/transactions/box_rollback_savepoint_test.lua @@ -20,8 +20,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_updated_partially = function(cg) diff --git a/doc/code_snippets/test/transactions/box_rollback_test.lua b/doc/code_snippets/test/transactions/box_rollback_test.lua index 34a02e5a9a..fd80a96457 100644 --- a/doc/code_snippets/test/transactions/box_rollback_test.lua +++ b/doc/code_snippets/test/transactions/box_rollback_test.lua @@ -20,8 +20,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) g.test_space_is_not_updated = function(cg) diff --git a/doc/code_snippets/test/triggers/on_recovery_state_test.lua b/doc/code_snippets/test/triggers/on_recovery_state_test.lua index adf7dc32bb..82108f682d 100644 --- a/doc/code_snippets/test/triggers/on_recovery_state_test.lua +++ b/doc/code_snippets/test/triggers/on_recovery_state_test.lua @@ -22,8 +22,8 @@ g.before_each(function(cg) end) g.after_each(function(cg) - cg.server:stop() cg.server:drop() + fio.rmtree(cg.server.workdir) end) local function find_in_log(cg, str, must_be_present) diff --git a/doc/code_snippets/test/varbinary/varbinary_test.lua b/doc/code_snippets/test/varbinary/varbinary_test.lua new file mode 100644 index 0000000000..d535c2cbc2 --- /dev/null +++ b/doc/code_snippets/test/varbinary/varbinary_test.lua @@ -0,0 +1,37 @@ +local varbinary = require('varbinary') + +-- Create a varbinary object +local bin = varbinary.new('data') +local bin_hex = varbinary.new('\xFF\xFE') + +-- Check whether a value is a varbinary object +varbinary.is(bin) -- true +varbinary.is(bin_hex) -- true +varbinary.is(100) -- false +varbinary.is('data') -- false + +-- Check varbinary objects equality +print(bin == varbinary.new('data')) -- true +print(bin == 'data') -- true +print(bin ~= 'data1') -- true +print(bin_hex ~= '\xFF\xFE') -- false + +-- Check varbinary objects length +print(#bin) -- 4 +print(#bin_hex) -- 2 + +-- Print string representation +print(tostring(bin)) -- data + +local bin2 = varbinary.new(ffi.cast('const char *', 'data'), 4) +varbinary.is(bin2) -- true +print(bin2) -- data + +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_varbinary = function() + luatest.assert_equals(varbinary.is(bin), true) + luatest.assert_equals(bin, 'data') + luatest.assert_equals(#bin, 4) + luatest.assert_equals(#varbinary.new('\xFF\xFE'), 2) +end diff --git a/doc/concepts/atomic/thread_model.rst b/doc/concepts/atomic/thread_model.rst deleted file mode 100644 index fb3e90d4e9..0000000000 --- a/doc/concepts/atomic/thread_model.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _thread_model: - -Thread model -============ - -.. _main_threads: - -Main threads ------------- - -The thread model assumes that a :ref:`query ` received by Tarantool via network -is processed with three operating system **threads**: - -1. The **network thread** (or :ref:`threads `) - on the server side receives the query, parses - the statement, checks if it is correct, and then transforms it into a special - structure -- a message containing an executable statement and its options. - -2. The network thread sends this message to the instance's - **transaction processor thread** (*TX thread*) via a lock-free message bus. - Lua programs are executed directly in the transaction processor thread, - and do not need to be parsed and prepared. - - The TX thread either uses a space index to find and update the tuple, - or executes a stored function that performs a data operation. - -3. The execution of the operation results in a message to the - :ref:`write-ahead logging (WAL) ` thread used to commit - the transaction and the fiber executing the transaction is suspended. - When the transaction results in a COMMIT or ROLLBACK, the following actions are taken: - - * The WAL thread responds with a message to the TX thread. - - * The fiber executing the transaction is resumed to process the result of the transaction. - - * The result of the fiber execution is passed to the network thread, - and the network thread returns the result to the client. - - -.. note:: - - There is only one TX thread in Tarantool. - Some users are used to the idea that there can be multiple threads - working on the database. For example, thread #1 reads a row #x while - thread #2 writes a row #y. With Tarantool this does not happen. - Only the TX thread can access the database, - and there is only one TX thread for each Tarantool instance. - - -The TX thread can handle many :ref:`fibers ` -- -a set of computer instructions that can contain "**yield**" signals. -The TX thread executes all computer instructions up to a -yield signal, and then switches to execute the instructions of another fiber. - - -:ref:`Yields ` must happen, otherwise the TX thread would -be permanently stuck on the same fiber. - - -.. _supplementary_threads: - -Supplementary threads ---------------------- - -There are also several supplementary threads that serve additional capabilities: - -* For :ref:`replication `, Tarantool creates a separate thread for each connected replica. - This thread reads a write-ahead log and sends it to the replica, following its position in the log. - Separate threads are required because each replica can point to a different position in the log and can run at different speeds. - -* There is a thread pool for ad hoc asynchronous tasks, - such as a DNS resolver or :ref:`fsync `. - -* There are OpenMP threads used to parallelize sorting - (hence, to parallelize building :ref:`indexes `). - For example, this is applicable when Tarantool is restoring from a - :ref:`snapshot ` with a large amount of data - and needs to sort a secondary index if it is ordered by something other than the primary order. - - .. note:: - - The maximum number of OpenMP threads can be controlled by the ``OMP_NUM_THREADS`` environment variable. diff --git a/doc/concepts/data_model/data_model.png b/doc/concepts/data_model/data_model.png deleted file mode 100644 index 5aa378e90a..0000000000 Binary files a/doc/concepts/data_model/data_model.png and /dev/null differ diff --git a/doc/concepts/data_model/data_model.svg b/doc/concepts/data_model/data_model.svg deleted file mode 100644 index 11f31a248c..0000000000 --- a/doc/concepts/data_model/data_model.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - data_model copy - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/doc/concepts/data_model/index.rst b/doc/concepts/data_model/index.rst deleted file mode 100644 index 470bdfe35d..0000000000 --- a/doc/concepts/data_model/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _box_data_model: - -Data model -========== - -If you tried to create a database as suggested in our -:ref:`basic tutorial `, -then your test database now looks like this: - -.. image:: data_model.png - -Tarantool stores data in :ref:`spaces `, which can be thought of as tables in a relational database. -Every record or row in a space is called a :ref:`tuple `. -A tuple may have any number of fields, and the fields may be of different :ref:`types `. - -String data in fields are compared based on the specified :ref:`collation ` rules. -The user can provide hard limits for data values through :ref:`constraints ` -and link related spaces with :ref:`foreign keys `. - -Tarantool supports highly customizable :ref:`indexes ` of various types. -In particular, indexes can be defined with generators like :ref:`sequences `. - -There are six basic :ref:`data operations ` in Tarantool: -SELECT, INSERT, UPDATE, UPSERT, REPLACE, and DELETE. A number of :ref:`complexity factors ` -affects the resource usage of each function. - -Tarantool allows :ref:`describing the data schema ` but does not require it. -The user can :ref:`migrate a schema ` without migrating the data. - -To ensure :ref:`data persistence ` and recover quickly in case of failure, -Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots. - -.. toctree:: - :maxdepth: 2 - - value_store - indexes - operations - schema_desc - persistence - migrations diff --git a/doc/concepts/data_model/migrations.rst b/doc/concepts/data_model/migrations.rst deleted file mode 100644 index 8237be789e..0000000000 --- a/doc/concepts/data_model/migrations.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. _migrations: - -Migrations -========== - -**Migration** refers to any change in a data schema: adding/removing a field, -creating/dropping an index, changing a field format, etc. - -In Tarantool, there are two types of schema migration -that do not require data migration: - -- adding a field to the end of a space - -- creating an index - -.. note:: - - Check the :ref:`Upgrading space schema ` section. - With the help of ``space:upgrade()``, - you can enable compression and migrate, including already created tuples. - - -Adding a field to the end of a space ------------------------------------- - -You can add a field as follows: - -.. code:: lua - - local users = box.space.users - local fmt = users:format() - - table.insert(fmt, { name = 'age', type = 'number', is_nullable = true }) - users:format(fmt) - -Note that the field must have the ``is_nullable`` parameter. Otherwise, -an error will occur. - -After creating a new field, you probably want to fill it with data. -The `tarantool/moonwalker `_ -module is useful for this task. -The README file describes how to work with this module. - -Creating an index ------------------ - -Index creation is described in the -:doc:`/reference/reference_lua/box_space/create_index` method. - -.. _other-migrations: - -Other types of migrations -------------------------- - -Other types of migrations are also allowed, but it would be more difficult to -maintain data consistency. - -Migrations are possible in two cases: - -- When Tarantool starts, and no client uses the database yet - -- During request processing, when active clients are already using the database - -For the first case, it is enough to write and test the migration code. -The most difficult task is to migrate data when there are active clients. -You should keep it in mind when you initially design the data schema. - -We identify the following problems if there are active clients: - -- Associated data can change atomically. - -- The system should be able to transfer data using both the new schema and the old one. - -- When data is being transferred to a new space, data access should consider - that the data might be in one space or another. - -- Write requests must not interfere with the migration. - A common approach is to write according to the new data schema. - -These issues may or may not be relevant depending on your application and -its availability requirements. - -What you need to know when writing complex migrations ------------------------------------------------------ - -Tarantool has a transaction mechanism. It is useful when writing a migration, -because it allows you to work with the data atomically. But before using -the transaction mechanism, you should explore its limitations. - -For details, see the section about :doc:`transactions `. - -How you can apply migration ---------------------------- - -The migration code is executed on a running Tarantool instance. -Important: no method guarantees you transactional application of migrations -on the whole cluster. - -**Method 1**: include migrations in the application code - -This is quite simple: when you reload the code, the data is migrated at the right moment, -and the database schema is updated. -However, this method may not work for everyone. -You may not be able to restart Tarantool or update the code using the hot-reload mechanism. - -**Method 2**: tarantool/migrations (only for a Tarantool Cartridge cluster) - -This method is described in the README file of the -`tarantool/migrations `_ module. - -.. note:: - - There are also two other methods that we **do not recommend**, - but you may find them useful for one reason or another. - - **Method 3**: the :ref:`tt ` utility - - Connect to the necessary instance using ``tt connect``. - - .. code:: console - - $ tt connect admin:password@localhost:3301 - - - If your migration is written in a Lua file, you can execute it - using ``dofile()``. Call this function and specify the path to the - migration file as the first argument. It looks like this: - - .. code-block:: tarantoolsession - - tarantool> dofile('0001-delete-space.lua') - --- - ... - - - (or) Copy the migration script code, - paste it into the console, and run it. - - You can also connect to the instance and execute the migration script in a single call: - - .. code:: console - - $ tt connect admin:password@localhost:3301 -f 0001-delete-space.lua - - - **Method 4**: applying migration with Ansible - - If you use the `Ansible role `_ - to deploy a Tarantool cluster, you can use ``eval``. - You can find more information about it - `in the Ansible role documentation `_. diff --git a/doc/concepts/data_model/persistence.rst b/doc/concepts/data_model/persistence.rst deleted file mode 100644 index 0545fdbfef..0000000000 --- a/doc/concepts/data_model/persistence.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _concepts-data_model-persistence: -.. _index-box_persistence: - -Persistence -=========== - -To ensure data persistence, Tarantool records updates to the database in the so-called -:ref:`write-ahead log (WAL) ` files. -When a power outage occurs or the Tarantool instance is killed incidentally, -the in-memory database is lost. -In such case, Tarantool restores the data from WAL files -by reading them and redoing the requests. -This is called the "recovery process". -You can change the timing of the WAL writer or turn it off by setting -the :ref:`wal_mode `. - -Tarantool also maintains a set of :ref:`snapshot files `. -These files contain an on-disk copy of the entire data set for a given moment. -Instead of reading every WAL file since the databases were created, the recovery -process can load the latest snapshot file and then read the WAL files, -produced after the snapshot file was made. -After creating a new snapshot, the earlier WAL files can be removed to free up space. - -To force immediate creation of a snapshot file, use the -:doc:`box.snapshot() ` function. -To enable the automatic creation of snapshot files, use Tarantool's -:ref:`checkpoint daemon `. -The checkpoint daemon sets intervals for forced checkpoints. It makes sure that the states -of both memtx and vinyl storage engines are synchronized and saved to disk, -and automatically removes earlier WAL files. - -Snapshot files can be created even if there is no WAL file. - -.. NOTE:: - - The memtx engine makes only regular checkpoints with the interval set in - :ref:`checkpoint daemon ` configuration. - - The vinyl engine runs checkpointing in the background at all times. - -See the :ref:`Internals ` section for more details -about the WAL writer and the recovery process. diff --git a/doc/concepts/engines/memtx.rst b/doc/concepts/engines/memtx.rst deleted file mode 100644 index dec2586d44..0000000000 --- a/doc/concepts/engines/memtx.rst +++ /dev/null @@ -1,162 +0,0 @@ -.. _engines-memtx: - -Storing data with memtx -======================= - -The ``memtx`` storage engine is used in Tarantool by default. It keeps all data in random-access memory (RAM), and therefore has very low read latency. - -The obvious question here is: -if all the data is stored in memory, how can you prevent the data loss in case of emergency such as outage or Tarantool instance failure? - -First of all, Tarantool persists all data changes by writing requests to the write-ahead log (WAL) that is stored on disk. -Read more about that in the :ref:`memtx-persist` section. -In case of a distributed application, there is an option of synchronous replication that ensures keeping the data consistent on a quorum of replicas. -Although replication is not directly a storage engine topic, it is a part of the answer regarding data safety. Read more in the :ref:`memtx-replication` section. - -In this chapter, the following topics are discussed in brief with the references to other chapters that explain the subject matter in details. - -.. contents:: - :local: - :depth: 1 - -.. _memtx-memory: - -Memory model ------------- - -There is a fixed number of independent :ref:`execution threads `. -The threads don't share state. Instead they exchange data using low-overhead message queues. -While this approach limits the number of cores that the instance uses, -it removes competition for the memory bus and ensures peak scalability of memory access and network throughput. - -Only one thread, namely, the **transaction processor thread** (further, **TX thread**) -can access the database, and there is only one TX thread for each Tarantool instance. -In this thread, transactions are executed in a strictly consecutive order. -Multi-statement transactions exist to provide isolation: -each transaction sees a consistent database state and commits all its changes atomically. -At commit time, a yield happens and all transaction changes are written to :ref:`WAL ` -in a single batch. -In case of errors during transaction execution, a transaction is rolled-back completely. -Read more in the following sections: :ref:`transaction_model`, :ref:`txn_mode_transaction-manager`. - -Within the TX thread, there is a memory area allocated for Tarantool to store data. It's called **Arena**. - -.. image:: memtx/arena2.svg - -Data is stored in :term:`spaces `. Spaces contain database records—:term:`tuples `. -To access and manipulate the data stored in spaces and tuples, Tarantool builds :doc:`indexes `. - -Special `allocators `__ manage memory allocations for spaces, tuples, and indexes within the Arena. -The slab allocator is the main allocator used to store tuples. -Tarantool has a built-in module called ``box.slab`` which provides the slab allocator statistics -that can be used to monitor the total memory usage and memory fragmentation. -For more details, see the ``box.slab`` module :doc:`reference `. - -.. image:: memtx/spaces_indexes.svg - -Also inside the TX thread, there is an event loop. Within the event loop, there are a number of :ref:`fibers `. -Fibers are cooperative primitives that allow interaction with spaces, that is, reading and writing the data. -Fibers can interact with the event loop and between each other directly or by using special primitives called channels. -Due to the usage of fibers and :ref:`cooperative multitasking `, the ``memtx`` engine is lock-free in typical situations. - -.. image:: memtx/fibers-channels.svg - -To interact with external users, there is a separate :ref:`network thread ` also called the **iproto thread**. -The iproto thread receives a request from the network, parses and checks the statement, -and transforms it into a special structure—a message containing an executable statement and its options. -Then the iproto thread ships this message to the TX thread and runs the user's request in a separate fiber. - -.. image:: memtx/iproto.svg - -.. _memtx-persist: - -Data persistence ----------------- - -To ensure :ref:`data persistence `, Tarantool does two things. - -* After executing data change requests in memory, Tarantool writes each such request to the :ref:`write-ahead log (WAL) ` files (``.xlog``) - that are stored on disk. Tarantool does this via a separate thread called the **WAL thread**. - -.. image:: memtx/wal.svg - -* Tarantool periodically takes the entire :doc:`database snapshot ` and saves it on disk. - It is necessary for accelerating instance's restart because when there are too many WAL files, it can be difficult for Tarantool to restart quickly. - - To save a snapshot, there is a special fiber called the **snapshot daemon**. - It reads the consistent content of the entire Arena and writes it on disk into a snapshot file (``.snap``). - Due of the cooperative multitasking, Tarantool cannot write directly on disk because it is a locking operation. - That is why Tarantool interacts with disk via a separate pool of threads from the :doc:`fio ` library. - -.. image:: memtx/snapshot03.svg - -So, even in emergency situations such as an outage or a Tarantool instance failure, -when the in-memory database is lost, the data can be restored fully during Tarantool restart. - -What happens during the restart: - -1. Tarantool finds the latest snapshot file and reads it. -2. Tarantool finds all the WAL files created after that snapshot and reads them as well. -3. When the snapshot and WAL files have been read, there is a fully recovered in-memory data set - corresponding to the state when the Tarantool instance stopped. -4. While reading the snapshot and WAL files, Tarantool is building the primary indexes. -5. When all the data is in memory again, Tarantool is building the secondary indexes. -6. Tarantool runs the application. - -.. _memtx-indexes: - -Accessing data --------------- - -To access and manipulate the data stored in memory, Tarantool builds indexes. -Indexes are also stored in memory within the Arena. - -Tarantool supports a number of :ref:`index types ` intended for different usage scenarios. -The possible types are TREE, HASH, BITSET, and RTREE. - -Select query are possible against secondary index keys as well as primary keys. -Indexes can have multi-part keys. - -For detailed information about indexes, refer to the :doc:`/concepts/data_model/indexes` page. - -.. _memtx-replication: - -Replicating data ----------------- - -Although this topic is not directly related to the ``memtx`` engine, it completes the overall picture of how Tarantool works in case of a distributed application. - -Replication allows multiple Tarantool instances to work on copies of the same database. -The copies are kept in sync because each instance can communicate its changes to all the other instances. -It is implemented via WAL replication. - -To send data to a replica, Tarantool runs another thread called **relay**. -Its purpose is to read the WAL files and send them to replicas. -On a replica, the fiber called **applier** is run. It receives the changes from a remote node and applies them to the replica's Arena. -All the changes are being written to WAL files via the replica's WAL thread as if they are done locally. - -.. image:: memtx/replica-xlogs.svg - -By default, :ref:`replication ` in Tarantool is asynchronous: if a transaction -is committed locally on a master node, it does not mean it is replicated onto any -replicas. - -:ref:`Synchronous replication ` exists to solve this problem. Synchronous transactions -are not considered committed and are not responded to a client until they are -replicated onto some number of replicas. - -For more information on replication, refer to the :ref:`corresponding chapter `. - -.. _memtx-summary: - -Summary --------- - -The main key points describing how the in-memory storage engine works can be summarized in the following way: - -* All data is in RAM. -* Access to data is from one thread. -* Tarantool writes all data change requests in WAL. -* Data snapshots are taken periodically. -* Indexes are build to access the data. -* WAL can be replicated. diff --git a/doc/concepts/index.rst b/doc/concepts/index.rst deleted file mode 100644 index 60b72ec810..0000000000 --- a/doc/concepts/index.rst +++ /dev/null @@ -1,125 +0,0 @@ -:fullwidth: - -.. _concepts: - -Concepts -======== - -Data model ----------- - -Tarantool is a NoSQL database. It stores data in :ref:`spaces `, -which can be thought of as tables in a relational database, and :ref:`tuples `, -which are analogous to rows. There are six basic :ref:`data operations ` in Tarantool. - -The platform allows :ref:`describing the data schema ` but does not require it. - -Tarantool supports highly customizable :ref:`indexes ` of various types. - -To ensure :ref:`data persistence ` and recover quickly in case of failure, -Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots. - -For details, check the :ref:`Data model ` page. - -Fibers and cooperative multitasking ------------------------------------ - -Tarantool executes code in :ref:`fibers ` that are managed via -:ref:`cooperative multitasking `. -Learn more about Tarantool's :ref:`thread model `. - -For details, check the page :ref:`Fibers, yields, and cooperative multitasking `. - -Transactions ------------- - -Tarantool's ACID-compliant :ref:`transaction model ` lets the user choose -between two modes of transactions. - -The :ref:`default mode ` allows for fast monopolistic atomic transactions. -It doesn't support interactive transactions, and in case of an error, all transaction changes are rolled back. - -The :ref:`MVCC mode ` relies on a multi-version concurrency control engine -that allows yielding within a longer transaction. -This mode only works with the default in-memory :ref:`memtx ` storage engine. - -For details, check the :ref:`Transactions ` page. - -.. _concepts-application_server: - -Application server ------------------- - -Using Tarantool as an application server, you can write -applications in Lua, C, or C++. You can also create reusable :ref:`modules `. - -A convenient way to serve a clustered application on Tarantool is using :ref:`Tarantool Cartridge ` -- -a framework for developing, deploying, and managing applications. - -To increase the speed of code execution, Tarantool has a Lua Just-In-Time compiler (LuaJIT) on board. -LuaJIT compiles hot paths in the code -- paths that are used many times -- -thus making the application work faster. -To enable developers to work with LuaJIT, Tarantool provides tools like the :ref:`memory profiler ` -and the :ref:`getmetrics ` module. - -For details on Tarantool's modular structure, check the :ref:`Modules ` page. - -To learn how to use Tarantool as an application server, refer to the :ref:`guides ` in the How-to section. - -Sharding --------- - -Tarantool implements database sharding via the ``vshard`` module. -For details, go to the :ref:`Sharding ` page. - -Triggers --------- - -Tarantool allows specifying callback functions that run upon certain database events. -They can be useful for resolving replication conflicts. -For details, go to the :ref:`Triggers ` page. - -Replication ------------ - -Replication allows keeping the data in copies of the same database for better reliability. - -Several Tarantool instances can be organized in a replica set. -They communicate and transfer data via the :ref:`iproto ` binary protocol. -Learn more about Tarantool's :ref:`replication architecture `. - -By default, replication in Tarantool is asynchronous. -A transaction committed locally on the master node -may not get replicated onto other instances before the client receives a success response. -Thus, if the master reports success and then dies, the client might not see the result of the transaction. - -With :ref:`synchronous replication `, transactions on the master node are not considered committed -or successful before they are replicated onto a number of instances. This is slower, but more reliable. -Synchronous replication in Tarantool is based on an :ref:`implementation of the RAFT algorithm `. - -For details, check the :ref:`Replication ` section. - -Storage engines ---------------- - -A storage engine is a set of low-level routines that store and -retrieve values. Tarantool offers a choice of two storage engines: - -* :ref:`memtx ` is the in-memory storage engine used by default. -* :ref:`vinyl ` is the on-disk storage engine. - -For details, check the :ref:`Storage engines ` section. - - -.. toctree:: - :hidden: - - data_model/index - coop_multitasking - atomic - modules - Tarantool Cartridge - sharding/index - replication/index - triggers - engines/index diff --git a/doc/concepts/modules.rst b/doc/concepts/modules.rst deleted file mode 100644 index ccd7cdcc2d..0000000000 --- a/doc/concepts/modules.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _concepts-modules: - -Modules -======= - -Any logic that is used in Tarantool can be packaged as an application -(like a :ref:`Cartridge application `) or a reusable **module**. -A module is an optional library that enhances Tarantool functionality. -It can be used by Tarantool applications or other modules. -Modules allow for easier code management and hot code reload without restarting the Tarantool instance. -Like applications, modules in Tarantool can be written in Lua, -C, or C++. Lua modules are also referred to as "rocks". - -For example, here is a Lua module named ``mymodule.lua`` that exports -one function named ``myfun``: - -.. code-block:: lua - - local exports = {} - exports.myfun = function(input_string) - print('Hello', input_string) - end - return exports - -To launch the function ``myfun()`` -- from another module, from a Lua application, -or from Tarantool itself, -- save this module as a file, then load -this module with the ``require()`` directive and call the exported function. - -For example, here's a Lua application that uses ``myfun()`` from -``mymodule.lua``: - -.. code-block:: lua - - -- loading the module - local mymodule = require('mymodule') - - -- calling myfun() from within test() - local test = function() - mymodule.myfun() - end - -Tarantool provides an `extensive library `_ of compatible modules. -Install them using Tarantool's CLI utility :ref:`tt `. -Some modules are also included in the Tarantool repository and can be installed -via your operating system's package manager. - -Learn how to: - -* :ref:`install a module ` -* :ref:`contribute a module ` diff --git a/doc/concepts/replication/index.rst b/doc/concepts/replication/index.rst deleted file mode 100644 index 17194039f2..0000000000 --- a/doc/concepts/replication/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -:noindex: -:fullwidth: - -.. _replication: - -Replication -=========== - -Replication allows multiple Tarantool instances to work on copies of the same -databases. The databases are kept in sync because each instance can communicate -its changes to all the other instances. - -This chapter includes the following sections: - -.. toctree:: - :maxdepth: 2 - :numbered: 0 - - repl_architecture - repl_sync - repl_leader_elect - -For practical guides to replication, see the :ref:`How-to section `. -You can learn about :ref:`bootstrapping a replica set `, -:ref:`adding instances ` to the replica set -or :ref:`removing them `, -:ref:`using synchronous replication ` -and :ref:`managing leader elections `. diff --git a/doc/concepts/replication/repl_leader_elect.rst b/doc/concepts/replication/repl_leader_elect.rst deleted file mode 100644 index 1031cd55b3..0000000000 --- a/doc/concepts/replication/repl_leader_elect.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. _repl_leader_elect: - -Automated leader election -========================= - -Starting from version :doc:`2.6.1 `, -Tarantool has the built-in functionality -managing automated *leader election* in a replica set. -This functionality increases the fault tolerance of the systems built -on the base of Tarantool and decreases -dependency on external tools for replica set management. - -To learn how to configure and monitor automated leader elections, -check the :ref:`how-to guide `. - -The following topics are described below: - -.. contents:: - :local: - :depth: 1 - -.. _repl_leader_elect_and_sync_repl: - -Leader election and synchronous replication -------------------------------------------- - -Leader election and synchronous replication are implemented in Tarantool as -a modification of the `Raft `__ -algorithm. -Raft is an algorithm of synchronous replication and automatic leader election. -Its complete description can be found in the `corresponding document `_. - -In Tarantool, :ref:`synchronous replication ` and leader election -are supported as two separate subsystems. -So it is possible to get synchronous replication -but use an alternative algorithm for leader election. -And vice versa -- elect a leader -in the cluster but don't use synchronous spaces at all. -Synchronous replication has a separate :ref:`documentation section `. -Leader election is described below. - -.. note:: - - The system behavior can be specified exactly according to the Raft algorithm. To do this: - - * Ensure that the user has only synchronous spaces. - * Set the :ref:`replication_synchro_quorum ` option to ``N / 2 + 1``. - * Set the :ref:`replication_synchro_timeout ` option to infinity. - * In the :ref:`election_fencing_mode ` option, select either the ``soft`` mode (the default) - or the ``strict`` mode, which is more restrictive. - -.. _repl_leader_elect_process: - -Leader election process ------------------------ - -Automated leader election in Tarantool helps guarantee that -there is at most one leader at any given moment of time in a replica set. -A *leader* is a writable node, and all other nodes are non-writable -- -they accept read-only requests exclusively. - -When :ref:`the election is enabled `, the life cycle of -a replica set is divided into so-called -*terms*. Each term is described by a monotonically growing number. -After the first boot, each node has its term equal to 1. When a node sees that -it is not a leader and there is no leader available for some time in the replica -set, it increases the term and starts a new leader election round. - -Leader election happens via votes. The node that started the election votes -for itself and sends vote requests to other nodes. -Upon receiving vote requests, a node votes for the first of them, and then cannot -do anything in the same term but wait for a leader to be elected. - -The node that collected a quorum of votes defined by the :ref:`replication_synchro_quorum ` parameter -becomes the leader -and notifies other nodes about that. Also, a split vote can happen -when no nodes received a quorum of votes. In this case, -after a :ref:`random timeout `, -each node increases its term and starts a new election round if no new vote -request with a greater term arrives during this time. -Eventually, a leader is elected. - -If any unfinalized synchronous transactions are left from the previous leader, -the new leader finalizes them automatically. - -All the non-leader nodes are called *followers*. The nodes that start a new -election round are called *candidates*. The elected leader sends heartbeats to -the non-leader nodes to let them know it is alive. - -In case there are no heartbeats for the period of :ref:`replication_timeout ` * 4, -a non-leader node starts a new election if the following conditions are met: - -* The node has a quorum of connections to other cluster members. -* None of these cluster members can see the leader node. - -.. note:: - - A cluster member considers the leader node to be alive if the member received heartbeats from the leader at least - once during the ``replication_timeout * 4``, - and there are no replication errors (the connection is not broken due to timeout or due to an error). - -Terms and votes are persisted by each instance to preserve certain Raft guarantees. - -During the election, the nodes prefer to vote for those ones that have the -newest data. So as if an old leader managed to send something before its death -to a quorum of replicas, that data wouldn't be lost. - -When :ref:`election is enabled `, there must be connections -between each node pair so as it would be the full mesh topology. This is needed -because election messages for voting and other internal things need a direct -connection between the nodes. - -.. _repl_leader_elect_fencing: - -In the classic Raft algorithm, a leader doesn't track its connectivity to the rest of the cluster. -Once the leader is elected, it considers itself in the leader position until receiving a new term from another cluster node. -This can lead to a split situation if the other nodes elect a new leader upon losing the connectivity to the previous one. - -The issue is resolved in Tarantool version :doc:`2.10.0 ` by introducing the leader *fencing* mode. -The mode can be switched by the :ref:`election_fencing_mode ` configuration parameter. -When the fencing is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than -:ref:`replication_synchro_quorum ` of alive connections to the cluster nodes. -The resigning leader receives the status of a follower in the current election term and becomes read-only. -Leader *fencing* can be turned off by setting the :ref:`election_fencing_mode ` configuration parameter to ``off``. - -In ``soft`` mode, a connection is considered dead if there are no responses for -:ref:`4*replication_timeout ` seconds both on the current leader and the followers. - -In ``strict`` mode, a connection is considered dead if there are no responses -for :ref:`2*replication_timeout ` seconds on the current leader and for -:ref:`4*replication_timeout ` seconds on the followers. -This improves chances that there is only one leader at any time. - -Fencing applies to the instances that have the :ref:`election_mode ` set to "candidate" or "manual". - -.. _repl_leader_elect_splitbrain: - -There can still be a situation when a replica set has two leaders working independently (so-called *split-brain*). -It can happen, for example, if a user mistakenly lowered the :ref:`replication_synchro_quorum ` below ``N / 2 + 1``. -In this situation, to preserve the data integrity, if an instance detects the split-brain anomaly in the incoming replication data, -it breaks the connection with the instance sending the data and writes the ``ER_SPLIT_BRAIN`` error in the log. - -Eventually, there will be two sets of nodes with the diverged data, -and any node from one set is disconnected from any node from the other set with the ``ER_SPLIT_BRAIN`` error. - -Once noticing the error, a user can choose any representative from each of the sets and inspect the data on them. -To correlate the data, the user should remove it from the nodes of one set, -and reconnect them to the nodes from the other set that have the correct data. - -Also, if election is enabled on the node, it doesn't replicate from any nodes except -the newest leader. This is done to avoid the issue when a new leader is elected, -but the old leader has somehow survived and tries to send more changes -to the other nodes. - -Term numbers also work as a kind of filter. -For example, if election is enabled on two nodes and ``node1`` has the term number less than ``node2``, -then ``node2`` doesn't accept any transactions from ``node1``. diff --git a/doc/concepts/replication/repl_sync.rst b/doc/concepts/replication/repl_sync.rst deleted file mode 100644 index 40b21ff4b0..0000000000 --- a/doc/concepts/replication/repl_sync.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _repl_sync: - -Synchronous replication -======================= - -Overview --------- - -By default, replication in Tarantool is **asynchronous**: if a transaction -is committed locally on a master node, it does not mean it is replicated onto any -replicas. If a master responds success to a client and then dies, after failover -to a replica, from the client's point of view the transaction will disappear. - -**Synchronous** replication exists to solve this problem. Synchronous transactions -are not considered committed and are not responded to a client until they are -replicated onto some number of replicas. - -To learn how to enable and use synchronous replication, -check the :ref:`guide `. - -Synchronous and asynchronous transactions ------------------------------------------ - -A killer feature of Tarantool's synchronous replication is its being *per-space*. -So, if you need it only rarely for some critical data changes, you won't pay for -it in performance terms. - -When there is more than one synchronous transaction, they all wait for being -replicated. Moreover, if an asynchronous transaction appears, it will -also be blocked by the existing synchronous transactions. This behavior is very -similar to a regular queue of asynchronous transactions because all the transactions -are committed in the same order as they make the :ref:`box.commit() ` call. -So, here comes **the commit rule**: -transactions are committed in the same order as they make -the ``box.commit()`` call -- regardless of being synchronous or asynchronous. - -If one of the waiting synchronous transactions times out and is rolled back, it -will first roll back all the newer pending transactions. Again, just like how -asynchronous transactions are rolled back when WAL write fails. -So, here comes **the rollback rule:** -transactions are always rolled back in the order reversed from the one they -make the ``box.commit()`` call -- regardless of being synchronous or asynchronous. - -One more important thing is that if an asynchronous transaction is blocked by -a synchronous transaction, it does not become synchronous as well. -This just means it will wait for the synchronous transaction to be committed. -But once it is done, the asynchronous transaction will be committed -immediately -- it won't wait for being replicated itself. - -.. warning:: - - Be careful when using synchronous and asynchronous transactions together. - Asynchronous transactions are considered committed even if there is no connection to other nodes. - Therefore, an old leader node (:ref:`synchronous transaction queue owner `) might have some - committed asynchronous transactions that no other replica set member has. - - When the connection to such an old (previous) leader node is restored, it starts receiving data from the new leader. - At the same time, other replica set members receive the data from the previous leader that they don't have yet. - The data from the previous leader contains some committed asynchronous transactions. - At this time, the integrity protection will throw - the :ref:`ER_SPLIT_BRAIN ` error, which will force the user to rebootstrap the previous leader. - - -Limitations and known problems ------------------------------- - -Until version :doc:`2.5.2 `, -there was no way to enable synchronous replication for -existing spaces, but since 2.5.2 it can be enabled by -:ref:`space_object:alter({is_sync = true}) `. - -Synchronous transactions work only for master-slave topology. You can have multiple -replicas, anonymous replicas, but only one node can make synchronous transactions. - -Since Tarantool :doc:`2.10.0 `, anonymous replicas do not participate in the quorum. - -Leader election ---------------- - -Starting from version :doc:`2.6.1 `, -Tarantool has the built-in functionality -managing automated leader election in a replica set. For more information, -refer to the :ref:`corresponding chapter `. diff --git a/doc/concepts/sharding/index.rst b/doc/concepts/sharding/index.rst deleted file mode 100644 index c447f70beb..0000000000 --- a/doc/concepts/sharding/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _sharding: -.. _vshard-summary: - -Sharding -======== - -Scaling databases in a growing project is often considered one of the most -challenging issues. Once a single server cannot withstand the load, scaling -methods should be applied. - -**Sharding** is a database architecture that allows for -`horizontal scaling `_, -which implies that a dataset is partitioned and distributed over multiple servers. - -With Tarantool's `vshard `_ module, -the tuples of a dataset are distributed across -multiple nodes, with a Tarantool database server instance on each node. Each instance -handles only a subset of the total data, so larger loads can be handled by simply -adding more servers. The initial dataset is partitioned into multiple parts, so each -part is stored on a separate server. - -The ``vshard`` module is based on the concept of -:ref:`virtual buckets `, where a tuple -set is partitioned into a large number of abstract virtual nodes (**virtual buckets**, -further just **buckets**) rather than into a smaller number of physical nodes. - -The dataset is partitioned using **sharding keys** (bucket id numbers). -Hashing a sharding key into a large number of buckets allows seamlessly -changing the number of servers in the cluster. The **rebalancing mechanism** distributes -buckets evenly among all shards in case some servers were added or removed. - -The buckets have **states**, so it is easy to monitor the server states. For example, -a server instance is active and available for all types of requests, or a failover -occurred and the instance accepts only read requests. - -The ``vshard`` module provides router and storage API (public and internal) for sharding-aware applications. - -Check out the :ref:`quick start guide ` or -learn more about :ref:`how sharding works ` in Tarantool: - -.. toctree:: - :maxdepth: 2 - - vshard_architecture - -You can also find out more about :ref:`sharding administration ` -or dive into the ``vshard`` configuration and API :ref:`reference `. diff --git a/doc/book/connectors/c.rst b/doc/connector/c.rst similarity index 96% rename from doc/book/connectors/c.rst rename to doc/connector/c.rst index 6f3343083d..74765d1966 100644 --- a/doc/book/connectors/c.rst +++ b/doc/connector/c.rst @@ -3,6 +3,9 @@ C = +`tarantool-c `__ is the official C connector for Tarantool. +You can find the full library documentation here: `Documentation for tarantool-c `__. + Here follow two examples of using Tarantool's high-level C API. Example 1 @@ -72,7 +75,7 @@ If Tarantool is not running on localhost with listen address = 3301, the program will print “Connection refused”. If the insert fails, the program will print "Insert failed" and an error number (see all error codes in the source file -`/src/box/errcode.h `__). +`/src/box/errcode.h `__). Here are notes corresponding to comments in the example program. @@ -246,7 +249,7 @@ To display the results, the program uses functions in the } struct tnt_stream *tuple = tnt_object(NULL); tnt_object_format(tuple, "[%d]", 99999); /* tuple = search key */ - tnt_select(tnt, 999, 0, (2^32) - 1, 0, 0, tuple); + tnt_select(tnt, 999, 0, UINT32_MAX, 0, 0, tuple); tnt_flush(tnt); struct tnt_reply reply; tnt_reply_init(&reply); tnt->read_reply(tnt, &reply); diff --git a/doc/book/connectors/community.rst b/doc/connector/community.rst similarity index 86% rename from doc/book/connectors/community.rst rename to doc/connector/community.rst index 2f909f6cfb..ca69e2b8c2 100644 --- a/doc/book/connectors/community.rst +++ b/doc/connector/community.rst @@ -9,11 +9,10 @@ Note that they may have limited support for new Tarantool features. .. toctree:: :maxdepth: 1 - csharp - C++ - nodejs - perl - php + community/csharp + community/nodejs + community/perl + community/php For Erlang, use the `Erlang tarantool driver `__. diff --git a/doc/book/connectors/csharp.rst b/doc/connector/community/csharp.rst similarity index 100% rename from doc/book/connectors/csharp.rst rename to doc/connector/community/csharp.rst diff --git a/doc/book/connectors/nodejs.rst b/doc/connector/community/nodejs.rst similarity index 100% rename from doc/book/connectors/nodejs.rst rename to doc/connector/community/nodejs.rst diff --git a/doc/book/connectors/perl.rst b/doc/connector/community/perl.rst similarity index 100% rename from doc/book/connectors/perl.rst rename to doc/connector/community/perl.rst diff --git a/doc/book/connectors/php.rst b/doc/connector/community/php.rst similarity index 100% rename from doc/book/connectors/php.rst rename to doc/connector/community/php.rst diff --git a/doc/connector/cpp.rst b/doc/connector/cpp.rst new file mode 100644 index 0000000000..bf94cbbcad --- /dev/null +++ b/doc/connector/cpp.rst @@ -0,0 +1,12 @@ +.. _index_connector_cpp: + +C++ +=== + +`tntcxx `__ is the official C++ connector for Tarantool. + +.. toctree:: + :maxdepth: 1 + + Connecting to Tarantool from C++ + C++ connector API diff --git a/doc/connector/go.rst b/doc/connector/go.rst new file mode 100644 index 0000000000..81f1a8c0d8 --- /dev/null +++ b/doc/connector/go.rst @@ -0,0 +1,475 @@ +.. _index_connector_go: +.. _getting_started-go: + +Go +== + +**Examples on GitHub**: `sample_db `_, `go `_ + +`go-tarantool `__ is the official Go connector for Tarantool. +It is not supplied as part of the Tarantool repository and should be installed separately. + +This tutorial shows how to use the `go-tarantool `__ 2.x library to create a Go application that connects to a remote Tarantool instance, performs CRUD operations, and executes a stored procedure. +You can find the full package documentation here: `Client in Go for Tarantool `__. + +.. NOTE:: + + This tutorial shows how to make CRUD requests to a single-instance Tarantool database. + To make requests to a sharded Tarantool cluster with the `CRUD `__ module, use the `crud `__ package's API. + + + +.. _getting_started_go_sample_db: + +Sample database configuration +----------------------------- + +.. include:: /reference/reference_lua/net_box.rst + :start-after: connectors_sample_db_config_start + :end-before: connectors_sample_db_config_end + +.. _getting_started_go_sample_db_start: + +Starting a sample database application +-------------------------------------- + +Before creating and starting a client Go application, you need to run the :ref:`sample_db ` application using :ref:`tt start `: + +.. code-block:: console + + $ tt start sample_db + +Now you can create a client Go application that makes requests to this database. + + +.. _getting_started_go_develop_client_app: + +Developing a client application +------------------------------- + +Before you start, make sure you have `Go installed `__ on your computer. + +.. _getting_started_go_create_client_app: + +Creating an application +~~~~~~~~~~~~~~~~~~~~~~~ + +1. Create the ``hello`` directory for your application and go to this directory: + + .. code-block:: console + + $ mkdir hello + $ cd hello + +2. Initialize a new Go module: + + .. code-block:: console + + $ go mod init example/hello + +3. Inside the ``hello`` directory, create the ``hello.go`` file for application code. + + +.. _getting_started_go_import_: + +Importing 'go-tarantool' packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the ``hello.go`` file, declare a ``main`` package and import the following packages: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: package main + :end-before: func main() + :dedent: + +The packages for external MsgPack types, such as ``datetime``, ``decimal``, or ``uuid``, are required to parse these types in a response. + + +.. _getting_started_go_creating_connection: + +Connecting to the database +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Declare the ``main()`` function: + + .. code-block:: go + + func main() { + + } + +2. Inside the ``main()`` function, add the following code: + + .. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Connect to the database + :end-before: // Insert data + :dedent: + + This code establishes a connection to a running Tarantool instance on behalf of ``sampleuser``. + The ``conn`` object can be used to make CRUD requests and execute stored procedures. + + + +.. _getting_started_go_manipulating_data: + +Manipulating data +~~~~~~~~~~~~~~~~~ + +.. _getting_started_go_inserting_data: + +Inserting data +************** + +Add the following code to insert four tuples into the ``bands`` space: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Insert data + :end-before: // Select by primary key + :dedent: + +This code makes insert requests asynchronously: + +- The ``Future`` structure is used as a handle for asynchronous requests. +- The ``NewInsertRequest()`` method creates an insert request object that is executed by the connection. + +.. NOTE:: + + Making requests asynchronously is the recommended way to perform data operations. + Further requests in this tutorial are made synchronously. + + +.. _getting_started_go_querying_data: + +Querying data +************* + +To get a tuple by the specified primary key value, use ``NewSelectRequest()`` to create an insert request object: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Select by primary key + :end-at: Tuple selected by the primary key value + :dedent: + +You can also get a tuple by the value of the specified index by using ``Index()``: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Select by secondary key + :end-at: Tuple selected by the secondary key value + :dedent: + + + +.. _getting_started_go_updating_data: + +Updating data +************* + +``NewUpdateRequest()`` can be used to update a tuple identified by the primary key as follows: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Update + :end-at: Updated tuple + :dedent: + +``NewUpsertRequest()`` can be used to update an existing tuple or insert a new one. +In the example below, a new tuple is inserted: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Upsert + :end-before: // Replace + :dedent: + + +In this example, ``NewReplaceRequest()`` is used to delete the existing tuple and insert a new one: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Replace + :end-at: Replaced tuple + :dedent: + + + + +.. _getting_started_go_deleting_data: + +Deleting data +************* + +``NewDeleteRequest()`` in the example below is used to delete a tuple whose primary key value is ``5``: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Delete + :end-at: Deleted tuple + :dedent: + + + +.. _getting_started_go_stored_procedures: + +Executing stored procedures +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To execute a stored procedure, use ``NewCallRequest()``: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Call + :end-at: Stored procedure result + :dedent: + + +.. _getting_started_go_closing_connection: + +Closing the connection +~~~~~~~~~~~~~~~~~~~~~~ + +The ``CloseGraceful()`` method can be used to close the connection when it is no longer needed: + +.. literalinclude:: /code_snippets/snippets/connectors/go/hello.go + :language: go + :start-at: // Close connection + :end-at: Connection is closed + :dedent: + +.. NOTE:: + + You can find the example with all the requests above on GitHub: `go `_. + + + +.. _getting_started_go_run_client_app: + +Starting a client application +----------------------------- + +1. Execute the following ``go get`` commands to update dependencies in the ``go.mod`` file: + + .. code-block:: console + + $ go get github.com/tarantool/go-tarantool/v2 + $ go get github.com/tarantool/go-tarantool/v2/decimal + $ go get github.com/tarantool/go-tarantool/v2/uuid + +2. To run the resulting application, execute the ``go run`` command in the application directory: + + .. code-block:: console + + $ go run . + Inserted tuples: + [[1 Roxette 1986]] + [[2 Scorpions 1965]] + [[3 Ace of Base 1987]] + [[4 The Beatles 1960]] + Tuple selected by the primary key value: [[1 Roxette 1986]] + Tuple selected by the secondary key value: [[4 The Beatles 1960]] + Updated tuple: [[2 Pink Floyd 1965]] + Replaced tuple: [[1 Queen 1970]] + Deleted tuple: [[5 The Rolling Stones 1962]] + Stored procedure result: [[[2 Pink Floyd 1965] [4 The Beatles 1960]]] + Connection is closed + + + + + +.. _getting_started-go-comparison: +.. _go-feature-comparison: + +Community Go connectors +----------------------- + +Last update: January 2023 + +There are also the following community-driven Go connectors: + +* `viciious/go-tarantool `_ + +* `FZambia/tarantool `_ + +The table below contains a feature comparison for the connectors mentioned above. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - + - `tarantool/go-tarantool `_ + - `viciious/go-tarantool `_ + - `FZambia/tarantool `_ + + * - License + - BSD 2-Clause + - MIT + - BSD 2-Clause + + * - Last update + - 2023 + - 2022 + - 2022 + + * - Documentation + - README with examples and up-to-date GoDoc + - README with examples, code comments + - README with examples + + * - Testing / CI / CD + - GitHub Actions + - Travis CI + - GitHub Actions + + * - GitHub Stars + - 147 + - 45 + - 14 + + * - Static analysis + - golangci-lint, luacheck + - golint + - golangci-lint + + * - Packaging + - go get + - go get + - go get + + * - Code coverage + - Yes + - No + - No + + * - msgpack driver + - `vmihailenco/msgpack/v2 `_ or `vmihailenco/msgpack/v5 `_ + - `tinylib/msgp `_ + - `vmihailenco/msgpack/v5 `_ + + * - Async work + - Yes + - Yes + - Yes + + * - Schema reload + - Yes (manual pull) + - Yes (manual pull) + - Yes (manual pull) + + * - Space / index names + - Yes + - Yes + - Yes + + * - Tuples as structures + - Yes (structure and marshall functions must be predefined in Go code) + - No + - Yes (structure and marshall functions must be predefined in Go code) + + * - Access tuple fields by names + - Only if marshalled to structure + - No + - Only if marshalled to structure + + * - `SQL `_ support + - Yes + - No (`#18 `_, closed) + - No + + * - `Interactive transactions `_ + - Yes + - No + - No + + * - `Varbinary `_ support + - Yes (with in-built language tools) + - Yes (with in-built language tools) + - Yes (decodes to string by default, see `#6 `_) + + * - `UUID `_ support + - Yes + - No + - No + + * - Decimal support + - Yes + - No + - No + + * - `EXT_ERROR `_ + support + - Yes + - No + - No + + * - `Datetime `_ support + - Yes + - No + - No + + * - `box.session.push() responses `_ + - Yes + - No (`#21 `_) + - Yes + + * - `Session settings `_ + - Yes + - No + - No + + * - `Graceful shutdown `_ + - Yes + - No + - No + + * - `IPROTO_ID (feature discovering) `_ + - Yes + - No + - No + + * - `tarantool/crud `_ support + - No + - No + - No + + * - Connection pool + - Yes (round-robin failover, no balancing) + - No + - No + + * - Transparent reconnecting + - Yes (see comments in `#129 `_) + - No (handle reconnects explicitly, refer to `#11 `_) + - Yes (see comments in `#7 `_) + + * - Transparent request retrying + - No + - No + - No + + * - `Watchers `_ + - Yes + - No + - No + + * - `Pagination `_ + - Yes + - No + - No + + * - Language features + - context + - context + - context + + * - Miscellaneous + - Supports `tarantool/queue `_ API + - Can mimic a Tarantool instance (also as replica). Provides instrumentation for reading snapshot and xlog files + via `snapio module `_. + Implements unpacking of query structs if you want to implement your own iproto proxy + - API is experimental and breaking changes may happen diff --git a/doc/connector/index.rst b/doc/connector/index.rst new file mode 100644 index 0000000000..d865c69068 --- /dev/null +++ b/doc/connector/index.rst @@ -0,0 +1,217 @@ +.. _index-box_connectors: +.. _getting_started_connectors: + +Connectors +========== + +Connectors are APIs that allow using Tarantool with various programming languages. + +Connectors can be divided into two groups -- those maintained by the Tarantool team +and those supported by the community. +The Tarantool team maintains the following connectors: + +- :ref:`Go ` +- :ref:`Java ` +- :ref:`high-level C API ` +- :ref:`synchronous Python connector ` +- :ref:`index_connector_cpp` + +All other connectors are community-supported, which means that support for new Tarantool features may be delayed. +Find all the available connectors on the `Connectors `_ page. + + +Protocol +-------- + +Tarantool's binary protocol was designed with a focus on asynchronous I/O and +easy integration with proxies. Each client request starts with a variable-length +binary header, containing request id, request type, instance id, log sequence +number, and so on. + +The mandatory length, present in request header simplifies client or proxy I/O. +A response to a request is sent to the client as soon as it is ready. It always +carries in its header the same type and id as in the request. The id makes it +possible to match a request to a response, even if the latter arrived out of +order. + +Unless implementing a client driver, you needn't concern yourself with the +complications of the binary protocol. Language-specific drivers provide a +friendly way to store domain language data structures in Tarantool. A complete +description of the binary protocol is maintained in annotated Backus-Naur form +in the source tree. For detailed examples and diagrams of all binary-protocol +requests and responses, see +:ref:`Tarantool's binary protocol `. + + +Packet example +-------------- + +The Tarantool API exists so that a client program can send a request packet to +a server instance, and receive a response. Here is an example of a what the client +would send for ``box.space[513]:insert{'A', 'BB'}``. The BNF description of +the components is on the page about +:ref:`Tarantool's binary protocol `. + +.. _Language-specific drivers: `Connectors`_ + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: right-align-column-2 + .. rst-class:: right-align-column-3 + .. rst-class:: right-align-column-4 + + +---------------------------------+---------+---------+---------+---------+ + | Component | Byte #0 | Byte #1 | Byte #2 | Byte #3 | + +=================================+=========+=========+=========+=========+ + | code for insert | 02 | | | | + +---------------------------------+---------+---------+---------+---------+ + | rest of header | ... | ... | ... | ... | + +---------------------------------+---------+---------+---------+---------+ + | 2-digit number: space id | cd | 02 | 01 | | + +---------------------------------+---------+---------+---------+---------+ + | code for tuple | 21 | | | | + +---------------------------------+---------+---------+---------+---------+ + | 1-digit number: field count = 2 | 92 | | | | + +---------------------------------+---------+---------+---------+---------+ + | 1-character string: field[1] | a1 | 41 | | | + +---------------------------------+---------+---------+---------+---------+ + | 2-character string: field[2] | a2 | 42 | 42 | | + +---------------------------------+---------+---------+---------+---------+ + +Now, you could send that packet to the Tarantool instance, and interpret the +response (the page about +:ref:`Tarantool's binary protocol ` has a +description of the packet format for responses as well as requests). But it +would be easier, and less error-prone, if you could invoke a routine that +formats the packet according to typed parameters. Something like +``response = tarantool_routine("insert", 513, "A", "B");``. And that is why APIs +exist for drivers for Perl, Python, PHP, and so on. + +.. _index-connector_setting: + +Setting up the server for connector examples +-------------------------------------------- + +This chapter has examples that show how to connect to a Tarantool instance via +the Perl, PHP, Python, node.js, and C connectors. The examples contain hard code that +will work if and only if the following conditions are met: + +* the Tarantool instance (tarantool) is running on localhost (127.0.0.1) and is listening on + port 3301 (``box.cfg.listen = '3301'``), + +* space ``examples`` has id = 999 (``box.space.examples.id = 999``) and has + a primary-key index for a numeric field + (``box.space[999].index[0].parts[1].type = "unsigned"``), + +* user 'guest' has privileges for reading and writing. + +It is easy to meet all the conditions by starting the instance and executing this +script: + +.. code-block:: lua + + box.cfg{listen=3301} + box.schema.space.create('examples',{id=999}) + box.space.examples:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) + box.schema.user.grant('guest','read,write','space','examples') + box.schema.user.grant('guest','read','space','_space') + + +Interpreting function return values +----------------------------------- + +For all connectors, calling a function via Tarantool causes a return in the +MsgPack format. If the function is called using the connector's API, some +conversions may occur. All scalar values are returned as tuples (with a MsgPack +type-identifier followed by a value); all non-scalar values are returned as a +group of tuples (with a MsgPack array-identifier followed by the scalar values). +If the function is called via the binary protocol command layer -- "eval" -- +rather than via the connector's API, no conversions occur. + +In the following example, a Lua function will be created. Since it will be +accessed externally by a :ref:`'guest' user`, a +:doc:`grant ` of an execute privilege will +be necessary. The function returns an empty array, a scalar string, two booleans, +and a short integer. The values are the ones described in the table +:ref:`Common Types and MsgPack Encodings `. + +.. code-block:: tarantoolsession + + tarantool> box.cfg{listen=3301} + 2016-03-03 18:45:52.802 [27381] main/101/interactive I> ready to accept requests + --- + ... + tarantool> function f() return {},'a',false,true,127; end + --- + ... + tarantool> box.schema.func.create('f') + --- + ... + tarantool> box.schema.user.grant('guest','execute','function','f') + --- + ... + +Here is a C program which calls the function. Although C is being used for the +example, the result would be precisely the same if the calling program was +written in Perl, PHP, Python, Go, or Java. + +.. code-block:: c + + #include + #include + #include + #include + #include + void main() { + struct tnt_stream *tnt = tnt_net(NULL); /* SETUP */ + tnt_set(tnt, TNT_OPT_URI, "localhost:3301"); + if (tnt_connect(tnt) < 0) { /* CONNECT */ + printf("Connection refused\n"); + exit(-1); + } + struct tnt_stream *arg; arg = tnt_object(NULL); /* MAKE REQUEST */ + tnt_object_add_array(arg, 0); + struct tnt_request *req1 = tnt_request_call(NULL); /* CALL function f() */ + tnt_request_set_funcz(req1, "f"); + uint64_t sync1 = tnt_request_compile(tnt, req1); + tnt_flush(tnt); /* SEND REQUEST */ + struct tnt_reply reply; tnt_reply_init(&reply); /* GET REPLY */ + tnt->read_reply(tnt, &reply); + if (reply.code != 0) { + printf("Call failed %lu.\n", reply.code); + exit(-1); + } + const unsigned char *p= (unsigned char*)reply.data; /* PRINT REPLY */ + while (p < (unsigned char *) reply.data_end) + { + printf("%x ", *p); + ++p; + } + printf("\n"); + tnt_close(tnt); /* TEARDOWN */ + tnt_stream_free(arg); + tnt_stream_free(tnt); + } + +When this program is executed, it will print: + +.. code-block:: console + + dd 0 0 0 5 90 91 a1 61 91 c2 91 c3 91 7f + +The first five bytes -- ``dd 0 0 0 5`` -- are the MsgPack encoding for +"32-bit array header with value 5" (see +`MsgPack specification `__). +The rest are as described in the +table :ref:`Common Types and MsgPack Encodings `. + +.. toctree:: + :hidden: + + go + java + c + python + cpp + community diff --git a/doc/book/connectors/java.rst b/doc/connector/java.rst similarity index 87% rename from doc/book/connectors/java.rst rename to doc/connector/java.rst index 6cb53ee2f4..fc6d3d81f3 100644 --- a/doc/book/connectors/java.rst +++ b/doc/connector/java.rst @@ -8,7 +8,7 @@ There are two Java connectors available: * `cartridge-java `__ supports both single Tarantool nodes and clusters, as well as applications built using the - :doc:`Cartridge framework ` and its modules. + `Cartridge framework `__ and its modules. The Tarantool team actively updates this module with the newest Tarantool features. * `tarantool-java `__ works with early Tarantool versions (1.6 and later) @@ -19,7 +19,7 @@ There are two Java connectors available: The following modules support Java libraries and frameworks: * `TestContainers Tarantool module `__ - adds support for the popular `TestСontainers framework `__ + adds support for the popular `TestContainers framework `__ used for integration testing of Java applications. * `Spring Data Tarantool module `__ adds support for the `Spring framework `__. diff --git a/doc/connector/python.rst b/doc/connector/python.rst new file mode 100644 index 0000000000..26fd167ba9 --- /dev/null +++ b/doc/connector/python.rst @@ -0,0 +1,418 @@ +.. _index_connector_py: +.. _getting_started-python: + +Python +====== + +**Examples on GitHub**: `sample_db `_, `python `_ + +`tarantool-python `__ +is the official Python connector for Tarantool. It is not supplied as part +of the Tarantool repository and must be installed separately. + +The tutorial shows how to use the `tarantool-python `__ library to create a Python script that connects to a remote Tarantool instance, performs CRUD operations, and executes a stored procedure. +You can find the full package documentation here: `Python client library for Tarantool `__. + +.. NOTE:: + + This tutorial shows how to make CRUD requests to a single-instance Tarantool database. + To make requests to a sharded Tarantool cluster with the `CRUD `__ module, use the `tarantool.crud `__ module's API. + + + + +.. _getting_started_python_sample_db: + +Sample database configuration +----------------------------- + +.. include:: /reference/reference_lua/net_box.rst + :start-after: connectors_sample_db_config_start + :end-before: connectors_sample_db_config_end + +.. _getting_started_python_sample_db_start: + +Starting a sample database application +-------------------------------------- + +Before creating and starting a client Python application, you need to run the :ref:`sample_db ` application using :ref:`tt start `: + +.. code-block:: console + + $ tt start sample_db + +Now you can create a client Python application that makes requests to this database. + + +.. _getting_started_python_develop_client_app: + +Developing a client application +------------------------------- + +Before you start, make sure you have `Python installed `__ on your computer. + +.. _getting_started_python_create_client_app: + +Creating an application +~~~~~~~~~~~~~~~~~~~~~~~ + +1. Create the ``hello`` directory for your application and go to this directory: + + .. code-block:: console + + $ mkdir hello + $ cd hello + +2. Create and activate a Python virtual environment: + + .. code-block:: console + + $ python -m venv .venv + $ source .venv/bin/activate + +3. Install the ``tarantool`` module: + + .. code-block:: console + + $ pip install tarantool + +4. Inside the ``hello`` directory, create the ``hello.py`` file for application code. + + +.. _getting_started_python_import_: + +Importing 'tarantool' +~~~~~~~~~~~~~~~~~~~~~ + +In the ``hello.py`` file, import the ``tarantool`` package: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: import + :end-at: import + :dedent: + + +.. _getting_started_python_creating_connection: + +Connecting to the database +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add the following code: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Connect to the database + :end-before: # Insert data + :dedent: + +This code establishes a connection to a running Tarantool instance on behalf of ``sampleuser``. +The ``conn`` object can be used to make CRUD requests and execute stored procedures. + + + +.. _getting_started_python_manipulating_data: + +Manipulating data +~~~~~~~~~~~~~~~~~ + +.. _getting_started_python_inserting_data: + +Inserting data +************** + +Add the following code to insert four tuples into the ``bands`` space: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Insert data + :end-before: # Select by primary key + :dedent: + +``Connection.insert()`` is used to insert a tuple to the space. + + +.. _getting_started_python_querying_data: + +Querying data +************* + +To get a tuple by the specified primary key value, use ``Connection.select()``: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Select by primary key + :end-at: Tuple selected by the primary key value + :dedent: + +You can also get a tuple by the value of the specified index using the ``index`` argument: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Select by secondary key + :end-at: Tuple selected by the secondary key value + :dedent: + + + +.. _getting_started_python_updating_data: + +Updating data +************* + +``Connection.update()`` can be used to update a tuple identified by the primary key as follows: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Update + :end-at: Updated tuple + :dedent: + +``Connection.upsert()`` updates an existing tuple or inserts a new one. +In the example below, a new tuple is inserted: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Upsert + :end-before: # Replace + :dedent: + + +In this example, ``Connection.replace()`` deletes the existing tuple and inserts a new one: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Replace + :end-at: Replaced tuple + :dedent: + + + + +.. _getting_started_python_deleting_data: + +Deleting data +************* + +``Connection.delete()`` in the example below deletes a tuple whose primary key value is ``5``: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Delete + :end-at: Deleted tuple + :dedent: + + + +.. _getting_started_python_stored_procedures: + +Executing stored procedures +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To execute a stored procedure, use ``Connection.call()``: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Call + :end-at: Stored procedure result + :dedent: + + +.. _getting_started_python_closing_connection: + +Closing the connection +~~~~~~~~~~~~~~~~~~~~~~ + +The ``Connection.close()`` method can be used to close the connection when it is no longer needed: + +.. literalinclude:: /code_snippets/snippets/connectors/python/hello.py + :language: python + :start-at: # Close connection + :end-at: Connection is closed + :dedent: + +.. NOTE:: + + You can find the example with all the requests above on GitHub: `python `_. + + + +.. _getting_started_python_run_client_app: + +Starting a client application +----------------------------- + +To run the resulting application, pass the script name to the ``python`` command: + +.. code-block:: console + + $ python hello.py + Inserted tuples: + [1, 'Roxette', 1986] + [2, 'Scorpions', 1965] + [3, 'Ace of Base', 1987] + [4, 'The Beatles', 1960] + Tuple selected by the primary key value: [1, 'Roxette', 1986] + Tuple selected by the secondary key value: [4, 'The Beatles', 1960] + Updated tuple: [2, 'Pink Floyd', 1965] + Replaced tuple: [1, 'Queen', 1970] + Deleted tuple: [5, 'The Rolling Stones', 1962] + Stored procedure result: [[2, 'Pink Floyd', 1965], [4, 'The Beatles', 1960]] + Connection is closed + + + + +.. _getting_started-python-comparison: +.. _python-feature-comparison: + +Community Python connectors +--------------------------- + +Last update: September 2023 + +There are also several community-driven Python connectors: + +* `asynctnt `__ with asyncio support +* `aiotarantool `__ also with asyncio support, **no active maintenance** +* `gtarantool `__ with gevent support, **no active maintenance** + +The table below contains a feature comparison for ``asynctnt`` and ``tarantool-python``. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Parameter + - `igorcoding/asynctnt `__ + - `tarantool/tarantool-python `__ + + * - License + - Apache License 2.0 + - BSD-2 + + * - Is maintained + - Yes + - Yes + + * - Known Issues + - None + - None + + * - Documentation + - Yes (`github.io `__) + - Yes (`readthedocs + `__ + and :ref:`tarantool.io `) + + * - Testing / CI / CD + - GitHub Actions + - GitHub Actions + + * - GitHub Stars + - 73 + - 92 + + * - Static Analysis + - Yes (Flake8) + - Yes (Flake8, Pylint) + + * - Packaging + - `pip `__ + - `pip, deb, rpm `__ + + * - Code coverage + - Yes + - Yes + + * - Support asynchronous mode + - Yes, `asyncio `__ + - No + + * - Batching support + - No + - Yes (with CRUD API) + + * - Schema reload + - Yes (automatically, see `auto_refetch_schema `__) + - Yes (automatically) + + * - Space / index names + - Yes + - Yes + + * - Access tuple fields by names + - Yes + - No + + * - :ref:`SQL support ` + - Yes + - Yes + + * - :ref:`Interactive transactions ` + - Yes + - No (`issue #163 `__) + + * - :ref:`Varbinary support ` + - Yes (in ``MP_BIN`` fields) + - Yes + + * - :ref:`Decimal support ` + - Yes + - Yes + + * - :ref:`UUID support ` + - Yes + - Yes + + * - :ref:`EXT_ERROR support ` + - Yes + - Yes + + * - :ref:`Datetime support ` + - Yes + - Yes + + * - :ref:`Interval support ` + - No (`issue #30 `__) + - Yes + + * - :ref:`box.session.push() responses ` + - Yes + - Yes + + * - :ref:`Session settings ` + - No + - No + + * - `Graceful shutdown `__ + - No + - No + + * - `IPROTO_ID (feature discovery) `__ + - Yes + - Yes + + * - `CRUD support `__ + - No + - Yes + + * - Transparent request retrying + - No + - No + + * - Transparent reconnecting + - Autoreconnect + - Yes (reconnect_max_attempts, reconnect_delay), checking of connection liveness + + * - Connection pool + - No + - Yes (with master discovery) + + * - Support of `PEP 249 -- Python Database API Specification v2.0 `__ + - No + - `Yes `__ + + * - :ref:`Encrypted connection (Enterprise Edition) ` + - No (`issue #22 `__) + - Yes diff --git a/doc/dev_guide/building_from_source.rst b/doc/contributing/building_from_source.rst similarity index 100% rename from doc/dev_guide/building_from_source.rst rename to doc/contributing/building_from_source.rst diff --git a/doc/dev_guide/c_style_guide.rst b/doc/contributing/c_style_guide.rst similarity index 100% rename from doc/dev_guide/c_style_guide.rst rename to doc/contributing/c_style_guide.rst diff --git a/doc/contributing/contributing.rst b/doc/contributing/contributing.rst index 5c9dd555d7..712f5fbe6f 100644 --- a/doc/contributing/contributing.rst +++ b/doc/contributing/contributing.rst @@ -132,8 +132,8 @@ There are several ways to improve the documentation: see how it works. This can be done automatically in Docker. To learn more, check the `README of the tarantool/doc repository `_. -Some projects, like `Tarantool Cartridge `_, -have their documentation in the code repository. +Some Tarantool projects have their documentation in the code repository. +This is typical for modules, for example, `metrics `_. This is done on purpose, so the developers themselves can update it faster. You can find instructions for building such documentation in the code repository. @@ -161,8 +161,6 @@ Here are some of our official modules: the persistent message queue. * `metrics `_: Ready-to-use solution for collecting metrics. -* `cartridge `_: Framework for writing - distributed applications. Official modules are provided in our organization on GitHub. @@ -186,7 +184,7 @@ Check the `currently open tasks `_ for the HTTP Server module. -Please see our :doc:`Lua style guide `. +Please see our :ref:`lua_style_guide`. You can find the contact of the current maintainer in the MAINTAINERS file, located in the root of the repository. If there is no such file, please @@ -216,13 +214,13 @@ may take longer to review because we want the code to be reliable. To start: -* :doc:`Learn how to build Tarantool `. +* :ref:`Learn how to build Tarantool `. * Read about Tarantool architecture and main modules on the - `developer site `__ and on + `developer site `__ and on `GitHub `__. In Tarantool development, we strive to follow the standards laid out in -our :doc:`style and contribution guides `. +our :ref:`style and contribution guides `. These documents explain how to format your code and commits as well as how to write tests without breaking anything accidentally. @@ -279,7 +277,7 @@ application server in the required format. Data access connectors have already been implemented for all major languages. If you want to write your own connector, you first need to familiarize yourself with the Tarantool binary protocol. -Read :doc:`the protocol description ` to learn more. +Read :ref:`the protocol description ` to learn more. We consider the following connectors as references: @@ -311,11 +309,8 @@ help with application deployment, or allow working with Kubernetes. Here are some of the tools created by the Tarantool team: -* `ansible-cartridge `_: - an Ansible role to deploy Cartridge applications. -* `cartridge-cli `_: - a CLI utility for creating applications, launching clusters locally on Cartridge, - and solving operation problems. +* `tt `_: + a CLI utility for creating and managing Tarantool applications. * `tarantool-operator `_: a Kubernetes operator for cluster orchestration. diff --git a/doc/dev_guide/contributing_module.rst b/doc/contributing/contributing_module.rst similarity index 100% rename from doc/dev_guide/contributing_module.rst rename to doc/contributing/contributing_module.rst diff --git a/doc/dev_guide/developer_guidelines.rst b/doc/contributing/developer_guidelines.rst similarity index 100% rename from doc/dev_guide/developer_guidelines.rst rename to doc/contributing/developer_guidelines.rst diff --git a/doc/contributing/docs/api.rst b/doc/contributing/docs/api.rst index a1fd0efcda..0cf1879ccf 100644 --- a/doc/contributing/docs/api.rst +++ b/doc/contributing/docs/api.rst @@ -93,7 +93,7 @@ Function and method parameters If the parameter is optional, make sure it is enclosed in square brackets in the function declaration (in the "heading"). -Do not mark parameters additionaly as "optional" or "required": +Do not mark parameters additionally as "optional" or "required": .. code-block:: rst diff --git a/doc/contributing/docs/infra.rst b/doc/contributing/docs/infra.rst index 7276247a1a..0271c6e2a5 100644 --- a/doc/contributing/docs/infra.rst +++ b/doc/contributing/docs/infra.rst @@ -15,9 +15,8 @@ The documentation source files are mainly stored in the `documentation repository `_. However, in some cases, they are stored in the repositories of other Tarantool-related products -or modules -- `Cartridge `_, -`Monitoring `__, -and others. +or modules, such as +`Monitoring `__. If you are working with source files from a product or module repository, add that repository as a submodule to the @@ -103,32 +102,6 @@ The ``${project_root}`` variable is defined earlier in the file as ``project_roo This is because the documentation build has to start from the documentation repository root directory. -cartridge_cli -^^^^^^^^^^^^^ - -The content source file for the ``cartridge_cli`` submodule is -``README.rst``, located in the directory of the submodule repository. -In the final documentation view, the content should appear here: -``https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_cli/``. - -To make this work: - -* Create a directory at ``./doc/book/cartridge/cartridge_cli``. -* Copy ``./modules/cartridge_cli/README.rst`` to - ``./doc/book/cartridge/cartridge_cli/index.rst``. - -Here ar the corresponding settings in ``build_submodules.sh``: - -.. code-block:: bash - - rst_dest="${project_root}/doc/book/cartridge" - cartridge_cli_root="${project_root}/modules/cartridge-cli" - cartridge_cli_dest="${rst_dest}/cartridge_cli" - cartridge_cli_index_dest="${cartridge_cli_dest}/index.rst" - - mkdir -p "${cartridge_cli_dest}" - yes | cp -rf "${cartridge_cli_root}/README.rst" "${cartridge_cli_index_dest}" - .. _guidelines_doc_submodules_gitignore: 3. Update .gitignore diff --git a/doc/contributing/docs/localization/_includes/glossary-cartridge.csv b/doc/contributing/docs/localization/_includes/glossary-cartridge.csv deleted file mode 100644 index 67502c4740..0000000000 --- a/doc/contributing/docs/localization/_includes/glossary-cartridge.csv +++ /dev/null @@ -1,10 +0,0 @@ -Term [en];Term [ru];Description [en];Description [ru] -;приложение на Tarantool Cartridge;;Если без предлога, то теряется смысл: читается так, как будто Tarantool Cartridge — это название приложения. А это не так. -Tarantool Cartridge application;Tarantool Cartridge — это фреймворк;;" на базе которого можно разработать свое приложение.""" -Cartridge;Cartridge;; -production environment;производственная среда;Production environment is a term used mostly by developers to describe the setting where software and other products are actually put into operation for their intended uses by end users.; -failover;восстановление после сбоев;In computing and related technologies such as networking, failover is switching to a redundant or standby computer server, system, hardware component or network upon the failure or abnormal termination of the previously active application, server, system, hardware component, or network.; -replicaset;набор реплик;; -directory;директория;; -bucket;сегмент;; -check;выберите, выбрать;To select a checkbox; \ No newline at end of file diff --git a/doc/contributing/docs/localization/_includes/glossary.csv b/doc/contributing/docs/localization/_includes/glossary.csv index 5dc02a7245..8cdfb97728 100644 --- a/doc/contributing/docs/localization/_includes/glossary.csv +++ b/doc/contributing/docs/localization/_includes/glossary.csv @@ -1,7 +1,6 @@ Term [en];Term [ru];Description [en];Description [ru] space;спейс;A space is a container for tuples.; -;"https://www.tarantool.io/en/doc/latest/book/box/data_model/#spaces""";;NOUN -tuple;кортеж;A tuple plays the same role as a “row” or a “record”. The number of tuples in a space is unlimited. Tuples in Tarantool are stored as MsgPack arrays. https://www.tarantool.io/en/doc/latest/book/box/data_model/#tuples; +tuple;кортеж;A tuple plays the same role as a “row” or a “record”. The number of tuples in a space is unlimited. Tuples in Tarantool are stored as MsgPack arrays.; Tarantool;Tarantool;НЕ ПЕРЕВОДИТЬ; primary index;первичный индекс;The first index defined on a space is called the primary key index, and it must be unique. All other indexes are called secondary indexes, and they may be non-unique. https://www.tarantool.io/en/doc/latest/book/box/data_model/#indexes; fiber;файбер;A fiber is a set of instructions which are executed with cooperative multitasking. Fibers managed by the fiber module are associated with a user-supplied function called the fiber function. https://www.tarantool.io/en/doc/latest/reference/reference_lua/fiber/#fibers; @@ -16,8 +15,6 @@ implicit casting;неявное приведение типов;; database;база данных;; Release policy;Релизная политика;A set of rules for releasing and naming new distributions of Tarantool: where we add new features and where we don't, how we give them numbers, what versions are suitable to use in production.; field;поле;Fields are distinct data values, contained in a tuple. They play the same role as «row columns» or «record fields» in relational databases.; -;;; -;"https://www.tarantool.io/ru/doc/latest/book/box/data_model/#term-field""";;NOUN leader election;выборы лидера;(in a replica set, by the Raft algorithm); replica set;набор реплик;; heartbeat;контрольный сигнал;; @@ -43,14 +40,18 @@ expression;выражение;; predicate;предикат;(SQL) Predicates, which specify conditions that can be evaluated to SQL three-valued logic (3VL) (true/false/unknown) or Boolean truth values and are used to limit the effects of statements and queries, or to change program flow.; query;запрос;(SQL) Queries retrieve the data based on specific criteria. A query is a statement that returns a result set (possibly empty).; result set;результат запроса;(SQL) An SQL result set is a set of rows from a database, as well as metadata about the query such as the column names, and the types and sizes of each column. A result set is effectively a table.; -resultset;результат запроса;(SQL) An SQL result set is a set of rows from a database, as well as metadata about the query such as the column names, and the types and sizes of each column. A result set is effectively a table.; statement;инструкция;(SQL) A statement is any text that the database engine recognizes as a valid command.;(SQL) Любой текст, который распознаётся движком БД как команда. Инструкция состоит из ключевых слов и выражений языка SQL, которые предписывают Tarantool выполнять какие-либо действия с базой данных. -;"Tarantool: A statement consists of SQL-language keywords and expressions that direct Tarantool to do something with a database. https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql_user_guide/#statements""";; +;;"Tarantool: A statement consists of SQL-language keywords and expressions that direct Tarantool to do something with a database. https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql_user_guide/#statements""";; batch;пакет (инструкций);(SQL) A series of SQL statements sent to the server at once is called a batch.;(SQL) Серия SQL-инструкций (statements), отправляемая на сервер вместе production configuration;конфигурация производственной среды;; -deployment;;Transforming a mechanical, electrical, or computer system from a packaged to an operational state. IT infrastructure deployment typically involves defining the sequence of operations or steps, often referred to as a deployment plan, that must be carried to deliver changes into a target system environment.; +deployment;развертывание;Transforming a mechanical, electrical, or computer system from a packaged to an operational state. IT infrastructure deployment typically involves defining the sequence of operations or steps, often referred to as a deployment plan, that must be carried to deliver changes into a target system environment.; roll back;отменить;;транзакцию deploy to production;;IT infrastructure deployment typically involves defining the sequence of operations or steps, often referred to as a deployment plan, that must be carried to deliver changes into a target system environment. Production environment is a setting where software and other products are actually put into operation for their intended uses by end users; operations;эксплуатация;(DevOps) Information technology operations, or IT operations, are the set of all processes and services that are both provisioned by an IT staff to their internal or external clients and used by themselves, to run themselves as a business. ; to deploy;;Transforming a mechanical, electrical, or computer system from a packaged to an operational state. IT infrastructure deployment typically involves defining the sequence of operations or steps, often referred to as a deployment plan, that must be carried to deliver changes into a target system environment.; -deployment plan;;A sequence of operations or steps that must be carried to deliver changes into a target system environment.; \ No newline at end of file +deployment plan;;A sequence of operations or steps that must be carried to deliver changes into a target system environment.; +production environment;производственная среда;Production environment is a term used mostly by developers to describe the setting where software and other products are actually put into operation for their intended uses by end users.; +failover;восстановление после сбоев;In computing and related technologies such as networking, failover is switching to a redundant or standby computer server, system, hardware component or network upon the failure or abnormal termination of the previously active application, server, system, hardware component, or network.; +directory;директория;; +bucket;сегмент;; +select;выберите, выбрать;To select a checkbox; \ No newline at end of file diff --git a/doc/contributing/docs/localization/glossaries.rst b/doc/contributing/docs/localization/glossaries.rst index 97fb063058..b9917c9747 100644 --- a/doc/contributing/docs/localization/glossaries.rst +++ b/doc/contributing/docs/localization/glossaries.rst @@ -1,18 +1,8 @@ Glossaries ========== -Tarantool Core --------------- - .. csv-table:: :file: _includes/glossary.csv :header-rows: 1 :delim: ; -Cartridge ---------- - -.. csv-table:: - :file: _includes/glossary-cartridge.csv - :header-rows: 1 - :delim: ; diff --git a/doc/contributing/docs/localization/locstate.rst b/doc/contributing/docs/localization/locstate.rst index 80c38d5255..8c38ac3754 100644 --- a/doc/contributing/docs/localization/locstate.rst +++ b/doc/contributing/docs/localization/locstate.rst @@ -15,18 +15,10 @@ State of localization - |doc| - 352 000 - * - Cartridge - - |cartridge| - - 14 000 - * - Tarantool Ansible Role - |tarantool-ansible-role| - 11 000 - * - Cartridge CLI - - |cartridge-cli| - - 6 500 - * - Tarantool Enterprise Edition - |tarantool-enterprise| - 6 000 @@ -58,12 +50,6 @@ State of localization .. |doc| image:: https://badges.crowdin.net/tarantool-docs/localized.svg :target: https://crowdin.com/project/tarantool-docs/ru# -.. |cartridge| image:: https://badges.crowdin.net/tarantool-cartridge-docs/localized.svg - :target: https://crowdin.com/project/tarantool-cartridge-docs/ru# - -.. |cartridge-cli| image:: https://badges.crowdin.net/tarantool-cartridge-cli/localized.svg - :target: https://crowdin.com/project/tarantool-cartridge-cli/ru# - .. |tarantool-enterprise| image:: https://badges.crowdin.net/tarantool-enterprise-docs/localized.svg :target: https://crowdin.com/project/tarantool-enterprise-docs/ru# diff --git a/doc/contributing/docs/markup/admonitions.rst b/doc/contributing/docs/markup/admonitions.rst index 0eff1aa23b..1b8bdbe4c5 100644 --- a/doc/contributing/docs/markup/admonitions.rst +++ b/doc/contributing/docs/markup/admonitions.rst @@ -44,9 +44,6 @@ In Tarantool we have 3 variants of css-style for admonitions: This block contains essential information that the user should know while doing something. - For example, the block :doc:`in Getting Started with Docker ` is used to warn the user against - closing the terminal window. - * Custom admonition: .. code-block:: rst diff --git a/doc/contributing/docs/markup/code.rst b/doc/contributing/docs/markup/code.rst index 9380f15908..b10663fb9a 100644 --- a/doc/contributing/docs/markup/code.rst +++ b/doc/contributing/docs/markup/code.rst @@ -56,9 +56,9 @@ For code snippets, we use the ``code-block:: language`` You can enable syntax highlighting if you specify the language for the snippet. The most commonly used highlighting languages are: -* ``tarantoolsession``—interactive Tarantool session, +* ``tarantoolsession`` -- interactive Tarantool session, where command lines start with ``tarantool>`` prompt. -* ``console``—interactive console session, where command lines +* ``console`` -- interactive console session, where command lines start with ``$`` or ``#``. * ``lua``, ``bash`` or ``c`` for programming languages. * ``text`` for cases when we want the code block to have no highlighting. diff --git a/doc/contributing/docs/sphinx-warnings.rst b/doc/contributing/docs/sphinx-warnings.rst index e7743614d1..51210c2c75 100644 --- a/doc/contributing/docs/sphinx-warnings.rst +++ b/doc/contributing/docs/sphinx-warnings.rst @@ -163,7 +163,7 @@ This may happen when you refer to a wrong path to a document. Check the path. -If the path points to ``cartridge`` or another submodule, check that you've +If the path points to a submodule, check that you've :doc:`built the submodules content ` before building docs. diff --git a/doc/dev_guide/guidelines_index.rst b/doc/contributing/guidelines_index.rst similarity index 92% rename from doc/dev_guide/guidelines_index.rst rename to doc/contributing/guidelines_index.rst index d63db4e3b5..b6487279fc 100644 --- a/doc/dev_guide/guidelines_index.rst +++ b/doc/contributing/guidelines_index.rst @@ -6,7 +6,7 @@ :maxdepth: 2 developer_guidelines - ../contributing/docs + docs c_style_guide python_style_guide lua_style_guide diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index 9ec8df5384..37f5df0c51 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -11,6 +11,6 @@ Contributing contributing release_notes - ../dev_guide/building_from_source - ../dev_guide/contributing_module - ../dev_guide/guidelines_index + building_from_source + contributing_module + guidelines_index diff --git a/doc/dev_guide/lua_style_guide.rst b/doc/contributing/lua_style_guide.rst similarity index 100% rename from doc/dev_guide/lua_style_guide.rst rename to doc/contributing/lua_style_guide.rst diff --git a/doc/dev_guide/python_style_guide.rst b/doc/contributing/python_style_guide.rst similarity index 100% rename from doc/dev_guide/python_style_guide.rst rename to doc/contributing/python_style_guide.rst diff --git a/doc/dev_guide/index.rst b/doc/dev_guide/index.rst deleted file mode 100644 index 8b1e4fd1bd..0000000000 --- a/doc/dev_guide/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -:noindex: -:fullwidth: - -.. _contrib_guide: - -******************************************************************************** -Contributor's Guide -******************************************************************************** - -.. toctree:: - :maxdepth: 2 - - reference_capi/index - internals/index - building_from_source - ../book/admin/modules - contributing_module - guidelines_index diff --git a/doc/dev_guide/internals/file_formats.rst b/doc/dev_guide/internals/file_formats.rst deleted file mode 100644 index 72ef740f47..0000000000 --- a/doc/dev_guide/internals/file_formats.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. _internals-data_persistence: - -File formats -============ - -.. _internals-wal: - -Data persistence and the WAL file format ----------------------------------------- - -To maintain data persistence, Tarantool writes each data change request (insert, -update, delete, replace, upsert) into a write-ahead log (WAL) file in the -:ref:`wal_dir ` directory. A new WAL file is created -when the current one reaches the :ref:`wal_max_size ` size. -Each data change request gets assigned a continuously growing 64-bit log sequence -number. The name of the WAL file is based on the log sequence number of the first -record in the file, plus an extension ``.xlog``. - -Apart from a log sequence number and the data change request (formatted as in -:ref:`Tarantool's binary protocol `), -each WAL record contains a header, some metadata, and then the data formatted -according to `msgpack `_ rules. -For example, this is what the WAL file looks like after the first INSERT request -("s:insert({1})") for the sandbox database created in our -:ref:`"Getting started" exercises `. -On the left are the hexadecimal bytes that you would see with: - -.. code-block:: console - - $ hexdump 00000000000000000000.xlog - -and on the right are comments. - -.. code-block:: none - - Hex dump of WAL file Comment - -------------------- ------- - 58 4c 4f 47 0a "XLOG\n" - 30 2e 31 33 0a "0.13\n" = version - 53 65 72 76 65 72 3a 20 "Server: " - 38 62 66 32 32 33 65 30 2d [Server UUID]\n - 36 39 31 34 2d 34 62 35 35 - 2d 39 34 64 32 2d 64 32 62 - 36 64 30 39 62 30 31 39 36 - 0a - 56 43 6c 6f 63 6b 3a 20 "Vclock: " - 7b 7d "{}" = vclock value, initially blank - ... (not shown = tuples for system spaces) - d5 ba 0b ab Magic row marker always = 0xab0bbad5 - 19 Length, not including length of header, = 25 bytes - 00 Record header: previous crc32 - ce 8c 3e d6 70 Record header: current crc32 - a7 cc 73 7f 00 00 66 39 Record header: padding - 84 msgpack code meaning "Map of 4 elements" follows - 00 02 element#1: tag=request type, value=0x02=IPROTO_INSERT - 02 01 element#2: tag=server id, value=0x01 - 03 04 element#3: tag=lsn, value=0x04 - 04 cb 41 d4 e2 2f 62 fd d5 d4 element#4: tag=timestamp, value=an 8-byte "Float64" - 82 msgpack code meaning "map of 2 elements" follows - 10 cd 02 00 element#1: tag=space id, value=512, big byte first - 21 91 01 element#2: tag=tuple, value=1-element fixed array={1} - -Tarantool processes requests atomically: a change is either accepted and recorded -in the WAL, or discarded completely. Let's clarify how this happens, using the -REPLACE request as an example: - -1. The server instance attempts to locate the original tuple by primary key. If found, a - reference to the tuple is retained for later use. - -2. The new tuple is validated. If for example it does not contain an indexed - field, or it has an indexed field whose type does not match the type - according to the index definition, the change is aborted. - -3. The new tuple replaces the old tuple in all existing indexes. - -4. A message is sent to the WAL writer running in a separate thread, requesting that - the change be recorded in the WAL. The instance switches to work on the next - request until the write is acknowledged. - -5. On success, a confirmation is sent to the client. On failure, a rollback - procedure is begun. During the rollback procedure, the transaction processor - rolls back all changes to the database which occurred after the first failed - change, from latest to oldest, up to the first failed change. All rolled back - requests are aborted with :errcode:`ER_WAL_IO ` error. No new - change is applied while rollback is in progress. When the rollback procedure - is finished, the server restarts the processing pipeline. - -One advantage of the described algorithm is that complete request pipelining is -achieved, even for requests on the same value of the primary key. As a result, -database performance doesn't degrade even if all requests refer to the same -key in the same space. - -The transaction processor thread communicates with the WAL writer thread using -asynchronous (yet reliable) messaging; the transaction processor thread, not -being blocked on WAL tasks, continues to handle requests quickly even at high -volumes of disk I/O. A response to a request is sent as soon as it is ready, -even if there were earlier incomplete requests on the same connection. In -particular, SELECT performance, even for SELECTs running on a connection packed -with UPDATEs and DELETEs, remains unaffected by disk load. - -The WAL writer employs a number of durability modes, as defined in configuration -variable :ref:`wal_mode `. It is possible to turn the write-ahead -log completely off, by setting -:ref:`wal_mode ` to *none*. Even -without the write-ahead log it's still possible to take a persistent copy of the -entire data set with the :ref:`box.snapshot() ` request. - -An .xlog file always contains changes based on the primary key. -Even if the client requested an update or delete using -a secondary key, the record in the .xlog file will contain the primary key. - -.. _internals-snapshot: - -The snapshot file format ------------------------- - -The format of a snapshot .snap file is nearly the same as the format of a WAL .xlog file. -However, the snapshot header differs: it contains the instance's global unique identifier -and the snapshot file's position in history, relative to earlier snapshot files. -Also, the content differs: an .xlog file may contain records for any data-change -requests (inserts, updates, upserts, and deletes), a .snap file may only contain records -of inserts to memtx spaces. - -Primarily, the .snap file's records are ordered by space id. Therefore the records of -system spaces -- such as ``_schema``, ``_space``, ``_index``, ``_func``, ``_priv`` -and ``_cluster`` -- will be at the start of the .snap file, before the records of -any spaces that were created by users. - -Secondarily, the .snap file's records are ordered by primary key within space id. - -.. _box_protocol-xlog: - -Example -------- - -The header of a ``.snap`` or ``.xlog`` file looks like: - -.. code-block:: none - - \n SNAP\n or XLOG\n - \n currently 0.13\n - Server: \n where UUID is a 36-byte string - VClock: \n e.g. {1: 0}\n - \n - -After the file header come the data tuples. -Tuples begin with a row marker ``0xd5ba0bab`` and -the last tuple may be followed by an EOF marker -``0xd510aded``. -Thus, between the file header and the EOF marker, there -may be data tuples that have this form: - -.. code-block:: none - - 0 3 4 17 - +-------------+========+============+===========+=========+ - | | | | | | - | 0xd5ba0bab | LENGTH | CRC32 PREV | CRC32 CUR | PADDING | - | | | | | | - +-------------+========+============+===========+=========+ - MP_FIXEXT2 MP_INT MP_INT MP_INT --- - - +============+ +===================================+ - | | | | - | HEADER | | BODY | - | | | | - +============+ +===================================+ - MP_MAP MP_MAP - diff --git a/doc/dev_guide/internals/iproto/images/auth.puml b/doc/dev_guide/internals/iproto/images/auth.puml deleted file mode 100644 index 9b0aaf19c4..0000000000 --- a/doc/dev_guide/internals/iproto/images/auth.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_AUTH**" as auth_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_AUTH", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_USER_NAME]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": { - "MP_ARRAY": "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/authentication Authentication mechanism]], [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/authentication scramble]]" - } - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/call.puml b/doc/dev_guide/internals/iproto/images/call.puml deleted file mode 100644 index 6f665e2f52..0000000000 --- a/doc/dev_guide/internals/iproto/images/call.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_CALL**" as call_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_CALL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FUNCTION_NAME]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY of arguments" - } -} - -json "**Response to IPROTO_CALL**" as call_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/call.svg b/doc/dev_guide/internals/iproto/images/call.svg deleted file mode 100644 index 83337f0a33..0000000000 --- a/doc/dev_guide/internals/iproto/images/call.svg +++ /dev/null @@ -1,44 +0,0 @@ -IPROTO_CALLSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_CALLIPROTO_SYNCMP_UINTBodyIPROTO_FUNCTION_NAMEMP_STRIPROTO_TUPLEMP_ARRAY of argumentsResponse to IPROTO_CALLSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/delete.puml b/doc/dev_guide/internals/iproto/images/delete.puml deleted file mode 100644 index c4a1f83624..0000000000 --- a/doc/dev_guide/internals/iproto/images/delete.puml +++ /dev/null @@ -1,35 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_DELETE**" as delete_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_DELETE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_KEY]]": "MP_ARRAY of key values" - } -} - -json "**Response to IPROTO_DELETE**" as delete_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/delete.svg b/doc/dev_guide/internals/iproto/images/delete.svg deleted file mode 100644 index 1658841e86..0000000000 --- a/doc/dev_guide/internals/iproto/images/delete.svg +++ /dev/null @@ -1,45 +0,0 @@ -IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_DELETEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_KEYMP_ARRAY of key valuesResponse to IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/error.puml b/doc/dev_guide/internals/iproto/images/error.puml deleted file mode 100644 index 8ab858ff07..0000000000 --- a/doc/dev_guide/internals/iproto/images/error.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Error response**" as error_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "0x8XXX", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ERROR]]": "MP_ERROR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ERROR_24]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/error.svg b/doc/dev_guide/internals/iproto/images/error.svg deleted file mode 100644 index 090ffc9e98..0000000000 --- a/doc/dev_guide/internals/iproto/images/error.svg +++ /dev/null @@ -1,33 +0,0 @@ -Error responseSizeMP_UINTHeaderIPROTO_REQUEST_TYPE0x8XXXIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_ERRORMP_ERRORIPROTO_ERROR_24MP_STR \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/error_24.puml b/doc/dev_guide/internals/iproto/images/error_24.puml deleted file mode 100644 index a5af7606e6..0000000000 --- a/doc/dev_guide/internals/iproto/images/error_24.puml +++ /dev/null @@ -1,22 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Error response before 2.4.1**" as error_response { - "Size": "32", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "0x800a", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "5", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "0x78" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ERROR]]": "Space '_space' already exists" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/eval.puml b/doc/dev_guide/internals/iproto/images/eval.puml deleted file mode 100644 index f438295123..0000000000 --- a/doc/dev_guide/internals/iproto/images/eval.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_EVAL**" as eval_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EVAL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EXPR]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY of arguments" - } -} - -json "**Response to IPROTO_EVAL**" as eval_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/eval.svg b/doc/dev_guide/internals/iproto/images/eval.svg deleted file mode 100644 index 84d15879d9..0000000000 --- a/doc/dev_guide/internals/iproto/images/eval.svg +++ /dev/null @@ -1,44 +0,0 @@ -IPROTO_EVALSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_EVALIPROTO_SYNCMP_UINTBodyIPROTO_EXPRMP_STRIPROTO_TUPLEMP_ARRAY of argumentsResponse to IPROTO_EVALSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/eval_example.puml b/doc/dev_guide/internals/iproto/images/eval_example.puml deleted file mode 100644 index 84d934d958..0000000000 --- a/doc/dev_guide/internals/iproto/images/eval_example.puml +++ /dev/null @@ -1,22 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_EVAL** example request" as eval_request { - "Size": "24", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EVAL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EXPR]]": "'return 5;'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "[]" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/event.puml b/doc/dev_guide/internals/iproto/images/event.puml deleted file mode 100644 index 0311d8b67d..0000000000 --- a/doc/dev_guide/internals/iproto/images/event.puml +++ /dev/null @@ -1,21 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_EVENT**" as event { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EVENT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EVENT_KEY]]": "MP_STR", - "(Optional) [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EVENT_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/events_unwatch.puml b/doc/dev_guide/internals/iproto/images/events_unwatch.puml deleted file mode 100644 index 81cb7a9c25..0000000000 --- a/doc/dev_guide/internals/iproto/images/events_unwatch.puml +++ /dev/null @@ -1,20 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_UNWATCH**" as unwatch { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_UNWATCH" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EVENT_KEY]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/events_watch.puml b/doc/dev_guide/internals/iproto/images/events_watch.puml deleted file mode 100644 index 43ba14ff50..0000000000 --- a/doc/dev_guide/internals/iproto/images/events_watch.puml +++ /dev/null @@ -1,20 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_WATCH**" as watch { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_WATCH" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_EVENT_KEY]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/execute.puml b/doc/dev_guide/internals/iproto/images/execute.puml deleted file mode 100644 index a07bc6ccdb..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute.puml +++ /dev/null @@ -1,36 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_EXECUTE**, prepared statement" as execute_request_prepared { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EXECUTE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STMT_ID]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SQL_BIND]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OPTIONS]]": "MP_ARRAY" - } -} - -json "**IPROTO_EXECUTE**, SQL string" as execute_request_string { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EXECUTE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SQL_TEXT]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SQL_BIND]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OPTIONS]]": "MP_ARRAY" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/execute.svg b/doc/dev_guide/internals/iproto/images/execute.svg deleted file mode 100644 index 3b5193f414..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute.svg +++ /dev/null @@ -1,46 +0,0 @@ -IPROTO_EXECUTE, prepared statementSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_EXECUTEIPROTO_SYNCMP_UINTBodyIPROTO_STMT_IDMP_INTIPROTO_SQL_BINDMP_ARRAYIPROTO_OPTIONSMP_ARRAYIPROTO_EXECUTE, SQL stringSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_EXECUTEIPROTO_SYNCMP_UINTBodyIPROTO_SQL_TEXTMP_STRIPROTO_SQL_BINDMP_ARRAYIPROTO_OPTIONSMP_ARRAY \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/execute_example_1.puml b/doc/dev_guide/internals/iproto/images/execute_example_1.puml deleted file mode 100644 index 73030679a3..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute_example_1.puml +++ /dev/null @@ -1,16 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Body**" as execute_body_1 { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STMT_ID]]": "0xd7aa741b", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SQL_BIND]]": "[1, 'a']", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OPTIONS]]": "[]" -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/execute_example_1.svg b/doc/dev_guide/internals/iproto/images/execute_example_1.svg deleted file mode 100644 index 4ce2d62dd9..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute_example_1.svg +++ /dev/null @@ -1,26 +0,0 @@ -BodyIPROTO_STMT_ID0xd7aa741bIPROTO_SQL_BIND[1, 'a']IPROTO_OPTIONS[] \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/execute_example_2.puml b/doc/dev_guide/internals/iproto/images/execute_example_2.puml deleted file mode 100644 index 4469e486c4..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute_example_2.puml +++ /dev/null @@ -1,28 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Body**" as execute_body_2 { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STMT_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_BIND_COUNT]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_BIND_METADATA]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_METADATA]]": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_NAME]]": "'DD'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'integer'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "false", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_AUTOINCREMENT]]": "true", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_SPAN]]": "nil", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_NAME]]": "'Д'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'string'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_COLL]]": "'unicode'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "true", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_SPAN]]": "'дд'" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/execute_example_2.svg b/doc/dev_guide/internals/iproto/images/execute_example_2.svg deleted file mode 100644 index 66eff1b11f..0000000000 --- a/doc/dev_guide/internals/iproto/images/execute_example_2.svg +++ /dev/null @@ -1,38 +0,0 @@ -BodyIPROTO_STMT_IDMP_UINTIPROTO_BIND_COUNTMP_INTIPROTO_BIND_METADATAMP_ARRAYIPROTO_METADATAIPROTO_FIELD_NAME'DD'IPROTO_FIELD_TYPE'integer'IPROTO_FIELD_IS_NULLABLEfalseIPROTO_FIELD_IS_AUTOINCREMENTtrueIPROTO_FIELD_SPANnilIPROTO_FIELD_NAME'Д'IPROTO_FIELD_TYPE'string'IPROTO_FIELD_COLL'unicode'IPROTO_FIELD_IS_NULLABLEtrueIPROTO_FIELD_SPAN'дд' \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/header.puml b/doc/dev_guide/internals/iproto/images/header.puml deleted file mode 100644 index e5d867a826..0000000000 --- a/doc/dev_guide/internals/iproto/images/header.puml +++ /dev/null @@ -1,17 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -map "**Header**" as Header { - [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]] => MP_UINT - [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]] => MP_UINT - [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]] => MP_UINT - [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STREAM_ID]] => MP_UINT -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/header.svg b/doc/dev_guide/internals/iproto/images/header.svg deleted file mode 100644 index 6a692023a0..0000000000 --- a/doc/dev_guide/internals/iproto/images/header.svg +++ /dev/null @@ -1,27 +0,0 @@ -HeaderIPROTO_REQUEST_TYPEMP_UINTIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTIPROTO_STREAM_IDMP_UINT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/id.puml b/doc/dev_guide/internals/iproto/images/id.puml deleted file mode 100644 index bbe7648dc3..0000000000 --- a/doc/dev_guide/internals/iproto/images/id.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_ID**" as id_request { - "Size": "MP_INT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_ID", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_VERSION]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FEATURES]]": "MP_ARRAY of MP_UINT items", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_AUTH_TYPE]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/id.svg b/doc/dev_guide/internals/iproto/images/id.svg deleted file mode 100644 index da3d6510a8..0000000000 --- a/doc/dev_guide/internals/iproto/images/id.svg +++ /dev/null @@ -1,33 +0,0 @@ -IPROTO_IDSizeMP_INTHeaderIPROTO_REQUEST_TYPEIPROTO_IDIPROTO_SYNCMP_UINTBodyIPROTO_VERSIONMP_UINTIPROTO_FEATURESMP_ARRAY of MP_UINT itemsIPROTO_AUTH_TYPEMP_STR \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/insert.puml b/doc/dev_guide/internals/iproto/images/insert.puml deleted file mode 100644 index dd498fe6e1..0000000000 --- a/doc/dev_guide/internals/iproto/images/insert.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_INSERT**" as insert_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_INSERT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY" - } -} - -json "**Response to IPROTO_INSERT**" as insert_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_ARRAY of tuples" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/insert_example.puml b/doc/dev_guide/internals/iproto/images/insert_example.puml deleted file mode 100644 index 7fd6824f3f..0000000000 --- a/doc/dev_guide/internals/iproto/images/insert_example.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_INSERT** example request" as insert_example_request { - "Size": "17", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_INSERT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "5" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "512", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "[1, 'AAA']" - } -} - -json "**IPROTO_INSERT** example response" as insert_example_response { - "Size": "36", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "5", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "100" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "[1, 'AAA']" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/ping.puml b/doc/dev_guide/internals/iproto/images/ping.puml deleted file mode 100644 index ab7e7cef04..0000000000 --- a/doc/dev_guide/internals/iproto/images/ping.puml +++ /dev/null @@ -1,31 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_PING**" as ping_request { - "Size": "5", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_PING", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": "MP_MAP, empty" -} - -json "**Response to IPROTO_PING**" as insert_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_MAP, empty" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/prepare.puml b/doc/dev_guide/internals/iproto/images/prepare.puml deleted file mode 100644 index 5490ee3154..0000000000 --- a/doc/dev_guide/internals/iproto/images/prepare.puml +++ /dev/null @@ -1,21 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_PREPARE**" as prepare_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_PREPARE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SQL_TEXT]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_ballot.puml b/doc/dev_guide/internals/iproto/images/repl_ballot.puml deleted file mode 100644 index 964a50391e..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_ballot.puml +++ /dev/null @@ -1,22 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_BALLOT body**" as ballot { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_RO_CFG]]": "MP_BOOL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_VCLOCK]]": "MP_MAP", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_GC_VCLOCK]]": "MP_MAP", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_RO]]": "MP_BOOL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_ANON]]": "MP_BOOL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_BOOTED]]": "MP_BOOL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_CAN_LEAD]]": "MP_BOOL", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_BOOTSTRAP_LEADER_UUID]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS]]": "MP_ARRAY" -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_ballot.svg b/doc/dev_guide/internals/iproto/images/repl_ballot.svg deleted file mode 100644 index 6ae1ea5aa5..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_ballot.svg +++ /dev/null @@ -1 +0,0 @@ -IPROTO_BALLOT bodyIPROTO_BALLOT_IS_RO_CFGMP_BOOLIPROTO_BALLOT_VCLOCKMP_MAPIPROTO_BALLOT_GC_VCLOCKMP_MAPIPROTO_BALLOT_IS_ROMP_BOOLIPROTO_BALLOT_IS_ANONMP_BOOLIPROTO_BALLOT_IS_BOOTEDMP_BOOLIPROTO_BALLOT_CAN_LEADMP_BOOLIPROTO_BALLOT_BOOTSTRAP_LEADER_UUIDMP_STRIPROTO_BALLOT_REGISTERED_REPLICA_UUIDSMP_ARRAY \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_heartbeat_message.puml b/doc/dev_guide/internals/iproto/images/repl_heartbeat_message.puml deleted file mode 100644 index c5adefe8ab..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_heartbeat_message.puml +++ /dev/null @@ -1,22 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Heartbeat message from master**" as heartbeat_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_REPLICA_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general IPROTO_TIMESTAMP]]": "MP_DOUBLE" - }, - "Body": { - "(Optional) [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_VCLOCK_SYNC]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_heartbeat_response.puml b/doc/dev_guide/internals/iproto/images/repl_heartbeat_response.puml deleted file mode 100644 index 39dc816edf..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_heartbeat_response.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Response from replica**" as heartbeat_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/key/#general IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_REPLICA_ID]]": "MP_UINT", - "(Optional) [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general IPROTO_TIMESTAMP]]": "MP_DOUBLE" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_VCLOCK]]": "MP_MAP", - "(Optional) [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#general-replication IPROTO_VCLOCK_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys/#synchronous-replication IPROTO_TERM]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_join_request.puml b/doc/dev_guide/internals/iproto/images/repl_join_request.puml deleted file mode 100644 index 516830f7b2..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_join_request.puml +++ /dev/null @@ -1,21 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_JOIN**" as join_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_JOIN", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_join_request.svg b/doc/dev_guide/internals/iproto/images/repl_join_request.svg deleted file mode 100644 index edcf290400..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_join_request.svg +++ /dev/null @@ -1,31 +0,0 @@ -IPROTO_JOINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOINIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instance \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_join_response.puml b/doc/dev_guide/internals/iproto/images/repl_join_response.puml deleted file mode 100644 index c1ab82d2ba..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_join_response.puml +++ /dev/null @@ -1,21 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Response to IPROTO_JOIN**" as join_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_VCLOCK]]": "MP_MAP" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_join_response.svg b/doc/dev_guide/internals/iproto/images/repl_join_response.svg deleted file mode 100644 index 0d579f4221..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_join_response.svg +++ /dev/null @@ -1,31 +0,0 @@ -Response to IPROTO_JOINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTBodyIPROTO_VCLOCKMP_MAP \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_raft.puml b/doc/dev_guide/internals/iproto/images/repl_raft.puml deleted file mode 100644 index 1d1748bfe9..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft.puml +++ /dev/null @@ -1,26 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_RAFT**" as raft { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_TERM]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_VOTE]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_STATE]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_VCLOCK]]": "MP_MAP", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_LEADER_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_RAFT_IS_LEADER_SEEN]]": "MP_BOOL" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_raft.svg b/doc/dev_guide/internals/iproto/images/repl_raft.svg deleted file mode 100644 index ee55369f78..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft.svg +++ /dev/null @@ -1,36 +0,0 @@ -IPROTO_RAFTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFTIPROTO_REPLICA_IDMP_UINTBodyIPROTO_RAFT_TERMMP_UINTIPROTO_RAFT_VOTEMP_UINTIPROTO_RAFT_STATEMP_UINTIPROTO_RAFT_VCLOCKMP_MAPIPROTO_RAFT_LEADER_IDMP_UINTIPROTO_RAFT_IS_LEADER_SEENMP_BOOL \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_confirm.puml b/doc/dev_guide/internals/iproto/images/repl_raft_confirm.puml deleted file mode 100644 index 6cc0812d7e..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_confirm.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_RAFT_CONFIRM**" as raft_confirm { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_CONFIRM", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_INT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_confirm.svg b/doc/dev_guide/internals/iproto/images/repl_raft_confirm.svg deleted file mode 100644 index fd8426950d..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_confirm.svg +++ /dev/null @@ -1,34 +0,0 @@ -IPROTO_RAFT_CONFIRMSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_CONFIRMIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INTIPROTO_SYNCMP_UINTBodyIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_demote.puml b/doc/dev_guide/internals/iproto/images/repl_raft_demote.puml deleted file mode 100644 index 0aaa82ba7e..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_demote.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_RAFT_DEMOTE**" as demote { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_DEMOTE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TERM]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_demote.svg b/doc/dev_guide/internals/iproto/images/repl_raft_demote.svg deleted file mode 100644 index 62dcbb0237..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_demote.svg +++ /dev/null @@ -1,34 +0,0 @@ -IPROTO_RAFT_DEMOTESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_DEMOTEIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTBodyIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_promote.puml b/doc/dev_guide/internals/iproto/images/repl_raft_promote.puml deleted file mode 100644 index 4e74bdbe3d..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_promote.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_RAFT_PROMOTE**" as promote { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_PROMOTE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TERM]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_promote.svg b/doc/dev_guide/internals/iproto/images/repl_raft_promote.svg deleted file mode 100644 index 63434078de..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_promote.svg +++ /dev/null @@ -1,34 +0,0 @@ -IPROTO_RAFT_PROMOTESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_PROMOTEIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTBodyIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_rollback.puml b/doc/dev_guide/internals/iproto/images/repl_raft_rollback.puml deleted file mode 100644 index a6853ab0df..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_rollback.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_RAFT_ROLLBACK**" as raft_rollback { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_ROLLBACK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LSN]]": "MP_INT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_raft_rollback.svg b/doc/dev_guide/internals/iproto/images/repl_raft_rollback.svg deleted file mode 100644 index c546f8b1f5..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_raft_rollback.svg +++ /dev/null @@ -1,34 +0,0 @@ -IPROTO_RAFT_ROLLBACKSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_ROLLBACKIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INTIPROTO_SYNCMP_UINTBodyIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_subscribe_request.puml b/doc/dev_guide/internals/iproto/images/repl_subscribe_request.puml deleted file mode 100644 index a7352d5c71..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_subscribe_request.puml +++ /dev/null @@ -1,26 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_SUBSCRIBE**" as subscribe_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_SUBSCRIBE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_CLUSTER_UUID]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_VCLOCK]]": "MP_MAP", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REPLICA_ANON]]": "MP_BOOL", - "(Optional) [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ID_FILTER]]": "MP_ARRAY" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_subscribe_request.svg b/doc/dev_guide/internals/iproto/images/repl_subscribe_request.svg deleted file mode 100644 index df4034e5ad..0000000000 --- a/doc/dev_guide/internals/iproto/images/repl_subscribe_request.svg +++ /dev/null @@ -1,36 +0,0 @@ -IPROTO_SUBSCRIBESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_SUBSCRIBEIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STRIPROTO_CLUSTER_UUIDMP_STRIPROTO_VCLOCKMP_MAPIPROTO_SERVER_VERSIONMP_UINTIPROTO_REPLICA_ANONMP_BOOL(Optional)IPROTO_ID_FILTERMP_ARRAY \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/replace.puml b/doc/dev_guide/internals/iproto/images/replace.puml deleted file mode 100644 index f486b98a98..0000000000 --- a/doc/dev_guide/internals/iproto/images/replace.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_REPLACE**" as replace_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_REPLACE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY of field values" - } -} - -json "**Response to IPROTO_REPLACE**" as replace_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/select.puml b/doc/dev_guide/internals/iproto/images/select.puml deleted file mode 100644 index ea7173a2f8..0000000000 --- a/doc/dev_guide/internals/iproto/images/select.puml +++ /dev/null @@ -1,42 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_SELECT**" as select { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_SELECT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LIMIT]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OFFSET]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ITERATOR]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_KEY]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_AFTER_POSITION]]": "MP_STR", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_AFTER_TUPLE]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FETCH_POSITION]]": "MP_BOOL" - } -} - -json "**Response to IPROTO_SELECT**" as select_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_POSITION]]": "MP_STR" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/select.svg b/doc/dev_guide/internals/iproto/images/select.svg deleted file mode 100644 index 4feea6e65f..0000000000 --- a/doc/dev_guide/internals/iproto/images/select.svg +++ /dev/null @@ -1,52 +0,0 @@ -IPROTO_SELECTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_SELECTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_LIMITMP_UINTIPROTO_OFFSETMP_UINTIPROTO_ITERATORMP_UINTIPROTO_KEYMP_ARRAYIPROTO_AFTER_POSITIONMP_STRIPROTO_AFTER_TUPLEMP_ARRAYIPROTO_FETCH_POSITIONMP_BOOLResponse to IPROTO_SELECTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECTIPROTO_POSITIONMP_STR \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/select_example.puml b/doc/dev_guide/internals/iproto/images/select_example.puml deleted file mode 100644 index 5a6fa35c9b..0000000000 --- a/doc/dev_guide/internals/iproto/images/select_example.puml +++ /dev/null @@ -1,26 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_SELECT** example request" as select_example { - "Size": "21", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_SELECT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "5" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "512", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_ID]]": "0", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_ITERATOR]]": "6", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OFFSET]]": "1", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_LIMIT]]": "2", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_KEY]]": "[1]" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/select_example.svg b/doc/dev_guide/internals/iproto/images/select_example.svg deleted file mode 100644 index ade25043b6..0000000000 --- a/doc/dev_guide/internals/iproto/images/select_example.svg +++ /dev/null @@ -1,36 +0,0 @@ -IPROTO_SELECTexample requestSize21HeaderIPROTO_REQUEST_TYPEIPROTO_SELECTIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_ITERATOR6IPROTO_OFFSET1IPROTO_LIMIT2IPROTO_KEY[1] \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/sql_response_other.puml b/doc/dev_guide/internals/iproto/images/sql_response_other.puml deleted file mode 100644 index 0bc556189c..0000000000 --- a/doc/dev_guide/internals/iproto/images/sql_response_other.puml +++ /dev/null @@ -1,25 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Response to SQL requests other than SELECT, VALUES, or PRAGMA**" as sql_response_other { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys SQL_INFO]]": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys SQL_INFO_ROW_COUNT]]": "MP_UINT", - "(Optional) [[tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys SQL_INFO_AUTO_INCREMENT_IDS]]": "MP_ARRAY" - } - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/sql_response_select.puml b/doc/dev_guide/internals/iproto/images/sql_response_select.puml deleted file mode 100644 index 77e50e5ebd..0000000000 --- a/doc/dev_guide/internals/iproto/images/sql_response_select.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Response to SELECT, VALUES, or PRAGMA**" as sql_response_select { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_METADATA]]": "MP_ARRAY of column maps", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_ARRAY of tuples" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/sql_response_select.svg b/doc/dev_guide/internals/iproto/images/sql_response_select.svg deleted file mode 100644 index 8c2b4fd13e..0000000000 --- a/doc/dev_guide/internals/iproto/images/sql_response_select.svg +++ /dev/null @@ -1,33 +0,0 @@ -Response to SELECT, VALUES, or PRAGMASizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_METADATAMP_ARRAY of column mapsIPROTO_DATAMP_ARRAY of tuples \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/sql_response_select_example.puml b/doc/dev_guide/internals/iproto/images/sql_response_select_example.puml deleted file mode 100644 index 9444bfda66..0000000000 --- a/doc/dev_guide/internals/iproto/images/sql_response_select_example.puml +++ /dev/null @@ -1,28 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**Body**" as sql_response_select_example { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_METADATA]]": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_NAME]]": "'DD'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'integer'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "false", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_AUTOINCREMENT]]": "true", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_SPAN]]": "nil", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_NAME]]": "'Д'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'string'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_COLL]]": "'unicode'", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "true", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_FIELD_SPAN]]": "'дд'" - }, - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": { - "MP_ARRAY": "[1, 'a'], [2, 'b']" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/sql_response_select_example.svg b/doc/dev_guide/internals/iproto/images/sql_response_select_example.svg deleted file mode 100644 index 1819546240..0000000000 --- a/doc/dev_guide/internals/iproto/images/sql_response_select_example.svg +++ /dev/null @@ -1,38 +0,0 @@ -BodyIPROTO_METADATAIPROTO_FIELD_NAME'DD'IPROTO_FIELD_TYPE'integer'IPROTO_FIELD_IS_NULLABLEfalseIPROTO_FIELD_IS_AUTOINCREMENTtrueIPROTO_FIELD_SPANnilIPROTO_FIELD_NAME'Д'IPROTO_FIELD_TYPE'string'IPROTO_FIELD_COLL'unicode'IPROTO_FIELD_IS_NULLABLEtrueIPROTO_FIELD_SPAN'дд'IPROTO_DATAMP_ARRAY[1, 'a'], [2, 'b'] \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/stream_begin.puml b/doc/dev_guide/internals/iproto/images/stream_begin.puml deleted file mode 100644 index b0c1d44030..0000000000 --- a/doc/dev_guide/internals/iproto/images/stream_begin.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_BEGIN**" as begin { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_BEGIN", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STREAM_ID]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TIMEOUT]]": "MP_DOUBLE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TXN_ISOLATION]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/stream_begin.svg b/doc/dev_guide/internals/iproto/images/stream_begin.svg deleted file mode 100644 index dc9dc601e6..0000000000 --- a/doc/dev_guide/internals/iproto/images/stream_begin.svg +++ /dev/null @@ -1,33 +0,0 @@ -IPROTO_BEGINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_BEGINIPROTO_SYNCMP_UINTIPROTO_STREAM_IDMP_UINTBodyIPROTO_TIMEOUTMP_DOUBLEIPROTO_TXN_ISOLATIONMP_UINT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/stream_commit.puml b/doc/dev_guide/internals/iproto/images/stream_commit.puml deleted file mode 100644 index 45e96826bc..0000000000 --- a/doc/dev_guide/internals/iproto/images/stream_commit.puml +++ /dev/null @@ -1,19 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_COMMIT**" as commit { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_COMMIT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STREAM_ID]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/stream_rollback.puml b/doc/dev_guide/internals/iproto/images/stream_rollback.puml deleted file mode 100644 index 961a2a97b7..0000000000 --- a/doc/dev_guide/internals/iproto/images/stream_rollback.puml +++ /dev/null @@ -1,19 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_ROLLBACK**" as rollback { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_ROLLBACK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_STREAM_ID]]": "MP_UINT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/update.puml b/doc/dev_guide/internals/iproto/images/update.puml deleted file mode 100644 index 84081dc86b..0000000000 --- a/doc/dev_guide/internals/iproto/images/update.puml +++ /dev/null @@ -1,36 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_UPDATE**" as update_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_UPDATE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_KEY]]": "MP_ARRAY of index keys", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY of update ops" - } -} - -json "**Response to IPROTO_UPDATE**" as update_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/update.svg b/doc/dev_guide/internals/iproto/images/update.svg deleted file mode 100644 index f20ae91ba1..0000000000 --- a/doc/dev_guide/internals/iproto/images/update.svg +++ /dev/null @@ -1,46 +0,0 @@ -IPROTO_UPDATESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_UPDATEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_KEYMP_ARRAY of index keysIPROTO_TUPLEMP_ARRAY of update opsResponse to IPROTO_UPDATESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/update_example.puml b/doc/dev_guide/internals/iproto/images/update_example.puml deleted file mode 100644 index bcc49d8599..0000000000 --- a/doc/dev_guide/internals/iproto/images/update_example.puml +++ /dev/null @@ -1,25 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_UPDATE** example request" as update_example { - "Size": "32", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_UPDATE", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "5" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "512", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_ID]]": "0", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_BASE]]": "1", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "['=',2,'B']", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_KEY]]": "[999]" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/update_example.svg b/doc/dev_guide/internals/iproto/images/update_example.svg deleted file mode 100644 index 058198e0a1..0000000000 --- a/doc/dev_guide/internals/iproto/images/update_example.svg +++ /dev/null @@ -1,35 +0,0 @@ -IPROTO_UPDATEexample requestSize32HeaderIPROTO_REQUEST_TYPEIPROTO_UPDATEIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_INDEX_BASE1IPROTO_TUPLE['=',2,'B']IPROTO_KEY[999] \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/upsert.puml b/doc/dev_guide/internals/iproto/images/upsert.puml deleted file mode 100644 index 397595a381..0000000000 --- a/doc/dev_guide/internals/iproto/images/upsert.puml +++ /dev/null @@ -1,36 +0,0 @@ -@startuml - -skinparam { - HyperlinkColor #0077FF - FontColor #313131 - BorderColor #313131 - BackgroundColor transparent -} - -json "**IPROTO_UPSERT**" as upsert_request { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_UPSERT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_INDEX_BASE]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_OPS]]": "MP_ARRAY", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY" - } -} - -json "**Response to IPROTO_UPSERT**" as upsert_response { - "Size": "MP_UINT", - "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" - } -} - -@enduml diff --git a/doc/dev_guide/internals/iproto/images/upsert.svg b/doc/dev_guide/internals/iproto/images/upsert.svg deleted file mode 100644 index 43c606880b..0000000000 --- a/doc/dev_guide/internals/iproto/images/upsert.svg +++ /dev/null @@ -1,46 +0,0 @@ -IPROTO_UPSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_UPSERTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_BASEMP_UINTIPROTO_OPSMP_ARRAYIPROTO_TUPLEMP_ARRAYResponse to IPROTO_UPSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/replication.rst b/doc/dev_guide/internals/iproto/replication.rst deleted file mode 100644 index f22355c618..0000000000 --- a/doc/dev_guide/internals/iproto/replication.rst +++ /dev/null @@ -1,344 +0,0 @@ -.. _internals-iproto-replication: -.. _box_protocol-replication: - -Replication requests and responses -================================== - -This section describes internal requests and responses that happen during replication. -Each of them is distinguished by the header, -containing a unique :ref:`IPROTO_REQUEST_TYPE ` value. -These values and the corresponding packet body structures are considered below. - -Connectors and clients do not need to send replication packets. - -.. _box_protocol-general: - -General -------- - -.. container:: table - - .. list-table:: - :widths: 40 20 40 - :header-rows: 1 - - * - Name - - Code - - Description - - * - :ref:`IPROTO_JOIN ` - - 0x41 - - Request to join a replica set - - * - :ref:`IPROTO_SUBSCRIBE ` - - 0x42 - - Request to subscribe to a specific node in a replica set - - * - :ref:`IPROTO_VOTE ` - - 0x44 - - Request for replication - - * - :ref:`IPROTO_BALLOT ` - - 0x29 - - Response to IPROTO_VOTE. Used during replica set bootstrap - - * - IPROTO_FETCH_SNAPSHOT - - 0x45 - - Fetch the master's snapshot and start anonymous replication. - See :ref:`replication_anon ` - - * - IPROTO_REGISTER - - 0x46 - - Register an anonymous replica so it is not anonymous anymore - -The master also sends :ref:`heartbeat ` messages to the replicas. -The heartbeat message's IPROTO_REQUEST_TYPE is ``0``. - -Below are details on individual replication requests. -For synchronous replication requests, see :ref:`below `. - -.. _box_protocol-heartbeat: - -Heartbeats -~~~~~~~~~~ - -Once in :ref:`replication_timeout ` seconds, -a master sends a :ref:`heartbeat ` message to a replica, -and the replica sends a response. -Both messages' IPROTO_REQUEST_TYPE is IPROTO_OK. -IPROTO_TIMESTAMP is a float-64 MP_DOUBLE 8-byte timestamp. - -Since version 2.11, both messages have an optional field in the body that contains -the :ref:`IPROTO_VCLOCK_SYNC ` key. -The master's heartbeat has no body if the IPROTO_VCLOCK_SYNC key is omitted. - -The message from master to a replica: - -.. raw:: html - :file: images/repl_heartbeat_message.svg - -The response from the replica: - -.. raw:: html - :file: images/repl_heartbeat_response.svg - -The tutorial :ref:`Understanding the binary protocol ` -shows actual byte codes of the above heartbeat examples. - -.. _box_protocol-join: - -IPROTO_JOIN -~~~~~~~~~~~ - -Code: 0x41. - -To join a replica set, an instance must send an initial IPROTO_JOIN request to any node in the replica set: - -.. raw:: html - :file: images/repl_join_request.svg - -The node that receives the request does the following in response: - -#. It sends its vclock: - - .. raw:: html - :file: images/repl_join_response.svg - -#. It sends a number of :ref:`INSERT ` requests (with additional LSN and ServerID). - In this way, the data is updated on the instance that sent the IPROTO_JOIN request. - The instance should not reply to these INSERT requests. - -#. It sends the new vclock's MP_MAP in a response similar to the one above - and closes the socket. - -.. _internals-iproto-replication-subscribe: - -IPROTO_SUBSCRIBE -~~~~~~~~~~~~~~~~ - -Code: 0x42. - -If :ref:`IPROTO_JOIN ` was successful, -the initiator instance must send an IPROTO_SUBSCRIBE request -to all the nodes listed in its :ref:`box.cfg.replication `: - -.. raw:: html - :file: images/repl_subscribe_request.svg - -After a successful IPROTO_SUBSCRIBE request, -the instance must process every request that could come from other masters. -Each master's request includes a vclock pair corresponding to that master -- -its instance ID and its LSN, independent from other masters. - -IPROTO_ID_FILTER (0x51) -is an optional key used in the SUBSCRIBE request followed by an array -of ids of instances whose rows won't be relayed to the replica. -The field is encoded only when the ID list is not empty. - -.. _internals-iproto-replication-vote: - -IPROTO_VOTE -~~~~~~~~~~~ - -Code: 0x44. - -When connecting for replication, an instance sends an IPROTO_VOTE request. It has no body: - -.. raw:: html - :file: images/repl_vote.svg - -IPROTO_VOTE is critical during replica set bootstrap. -The response to this request is :ref:`IPROTO_BALLOT `. - -.. _box_protocol-ballots: - -IPROTO_BALLOT -~~~~~~~~~~~~~ - -Code: 0x29. - -This value of IPROTO_REQUEST_TYPE indicates a message sent in response -to :ref:`IPROTO_VOTE ` (not to be confused with the key IPROTO_RAFT_VOTE). - -IPROTO_BALLOT and IPROTO_VOTE are critical during replica set bootstrap. -IPROTO_BALLOT corresponds to a map containing the following fields: - -.. raw:: html - :file: images/repl_ballot.svg - -IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS has the MP_ARRAY type. -The array contains MP_STR elements. - -.. _internals-iproto-replication-synchronous: - -Synchronous ------------ - -.. container:: table - - .. list-table:: - :widths: 40 20 40 - :header-rows: 1 - - * - Name - - Code - - Description - - * - :ref:`IPROTO_RAFT ` - - 0x1e - - Inform that the node changed its :ref:`RAFT status ` - - * - :ref:`IPROTO_RAFT_PROMOTE ` - - 0x1f - - Wait, then choose new replication leader - - * - :ref:`IPROTO_RAFT_DEMOTE ` - - 0x20 - - Revoke the leader role from the instance - - * - :ref:`IPROTO_RAFT_CONFIRM ` - - 0x28 - - Confirm that the RAFT transactions have achieved quorum and can be committed - - * - :ref:`IPROTO_RAFT_ROLLBACK ` - - 0x29 - - Roll back the RAFT transactions because they haven't achieved quorum - - - -.. _box_protocol-raft: - -IPROTO_RAFT -~~~~~~~~~~~ - -Code: 0x1e. - -A node broadcasts the IPROTO_RAFT request to all the replicas connected to it -when the RAFT state of the node changes. -It can be any actions changing the state, like starting a new election, bumping the term, -voting for another node, becoming the leader, and so on. - -If there should be a response, for example, in case of a vote request to other nodes, -the response will also be an IPROTO_RAFT message. -In this case, the node should be connected as a replica to another node from which the response is expected -because the response is sent via the replication channel. -In other words, there should be a full-mesh connection between the nodes. - -.. raw:: html - :file: images/repl_raft.svg - -IPROTO_REPLICA_ID is the ID of the replica from which the request came. - -.. _internals-iproto-replication-raft_promote: - -IPROTO_RAFT_PROMOTE -~~~~~~~~~~~~~~~~~~~ - -Code: 0x1f. - -See :ref:`box.ctl.promote() `. - -.. raw:: html - :file: images/repl_raft_promote.svg - -In the header: - -* IPROTO_REPLICA_ID is the replica ID of the node that sent the request. -* IPROTO_LSN is the actual LSN of the promote operation as recorded in the WAL. - -In the body: - -* IPROTO_REPLICA_ID is the replica ID of the previous :ref:`synchronous queue owner `. -* IPROTO_LSN is the LSN of the last operation on the previous synchronous queue owner. -* IPROTO_TERM is the term in which the node that sent the request becomes the synchronous queue owner. - This term corresponds to the value of :ref:`box.info.synchro.queue.term ` on the instance. - -.. _internals-iproto-replication-raft_demote: - -IPROTO_RAFT_DEMOTE -~~~~~~~~~~~~~~~~~~ - -Code: 0x20. - -See :ref:`box.ctl.demote() `. - -.. raw:: html - :file: images/repl_raft_demote.svg - -In the header: - -* IPROTO_REPLICA_ID is the replica ID of the node that sent the request. -* IPROTO_LSN is the actual LSN of the demote operation as recorded in the WAL. - -In the body: - -* IPROTO_REPLICA_ID is the replica ID of the node that sent the request - (same as the value in the header). -* IPROTO_LSN is the LSN of the last synchronous transaction recorded in the node's WAL. -* IPROTO_TERM is the term in which the queue becomes empty. - -.. _box_protocol-raft_confirm: - -IPROTO_RAFT_CONFIRM -~~~~~~~~~~~~~~~~~~~ - -Code: 0x28. - -This message is used in replication connections between -Tarantool nodes in :ref:`synchronous replication `. -It is not supposed to be used by any client applications in their -regular connections. - -This message confirms that the transactions that originated from the instance -with id = IPROTO_REPLICA_ID (body) have achieved quorum and can be committed, -up to and including LSN = IPROTO_LSN (body). - -The body is a 2-item map: - -.. raw:: html - :file: images/repl_raft_confirm.svg - -In the header: - -* IPROTO_REPLICA_ID is the ID of the replica that sends the confirm message. -* IPROTO_LSN is the LSN of the confirmation action. - -In the body: - -* IPROTO_REPLICA_ID is the ID of the instance from which the transactions originated. -* IPROTO_LSN is the LSN up to which the transactions should be confirmed. - -Prior to Tarantool :tarantool-release:`2.10.0`, IPROTO_RAFT_CONFIRM was called IPROTO_CONFIRM. - -.. _box_protocol-raft_rollback: - -IPROTO_RAFT_ROLLBACK -~~~~~~~~~~~~~~~~~~~~ - -Code: 0x29. - -This message is used in replication connections between -Tarantool nodes in :ref:`synchronous replication `. -It is not supposed to be used by any client applications in their -regular connections. - -This message says that the transactions that originated from the instance -with id = IPROTO_REPLICA_ID (body) couldn't achieve quorum for some reason -and should be rolled back, down to LSN = IPROTO_LSN (body) and including it. - -The body is a 2-item map: - -.. raw:: html - :file: images/repl_raft_rollback.svg - -In the header: - -* IPROTO_REPLICA_ID is the ID of the replica that sends the rollback message. -* IPROTO_LSN is the LSN of the rollback action. - -In the body: - -* IPROTO_REPLICA_ID is the ID of the instance from which the transactions originated. -* IPROTO_LSN is the LSN starting with which all pending synchronous transactions should be rolled back. - -Prior to Tarantool :tarantool-release:`2.10.0`, IPROTO_RAFT_ROLLBACK was called IPROTO_ROLLBACK. diff --git a/doc/dev_guide/reference_capi/index.rst b/doc/dev_guide/reference_capi/index.rst deleted file mode 100644 index 9a169d9c7d..0000000000 --- a/doc/dev_guide/reference_capi/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -:noindex: -:fullwidth: - -.. _index-c_api_reference: - -------------------------------------------------------------------------------- - C API reference -------------------------------------------------------------------------------- - -.. toctree:: - :maxdepth: 1 - :caption: List of C API headers - - box - clock - coio - error - fiber - box_index - latch - on_shutdown - utils - say - schema - trivia - tuple - txn diff --git a/doc/enterprise/admin.rst b/doc/enterprise/admin.rst deleted file mode 100644 index 8f9d19b1bf..0000000000 --- a/doc/enterprise/admin.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. _enterprise-admin: - -=============================================================================== -Cluster administrator's guide -=============================================================================== - -This guide focuses on Enterprise-specific administration features available -on top of Tarantool Community Edition with Tarantool Cartridge framework: - -* :ref:`space explorer ` -* :ref:`upgrade of environment-independent applications in production ` - -Otherwise, consult the following documentation for: - -* basic information on - :doc:`deploying and managing a Tarantool cluster ` -* more information on - :doc:`managing Tarantool instances ` - -.. _space_explorer: - -------------------------------------------------------------------------------- -Exploring spaces -------------------------------------------------------------------------------- - -The web interface lets you connect (in the browser) to any instance in the cluster -and see what spaces it stores (if any) and their contents. - -To explore spaces: - -#. Open the **Space Explorer** tab in the menu on the left: - - .. image:: images/space_explr_tab.png - :align: center - :scale: 80% - -#. Click **connect** next to an instance that stores data. The basic sanity-check - (``test.py``) of the example application puts sample data to one replica - set (shard), so its master and replica store the data in their spaces: - - .. image:: images/spaces_with_data.png - :align: center - :scale: 80% - - When connected to a instance, the space explorer shows a table with basic - information on its spaces. For more information, see the - :doc:`box.space reference `. - - To see hidden spaces, tick the corresponding checkbox: - - .. image:: images/hidden_spaces.png - :align: center - :scale: 80% - -#. Click the space's name to see its format and contents: - - .. image:: images/space_contents.png - :align: center - :scale: 70% - - To search the data, select an index and, optionally, its iteration type from - the drop-down lists, and enter the index value: - - .. image:: images/space_search.png - :align: center - :scale: 80% - -.. _enterprise-production-upgrade: - -------------------------------------------------------------------------------- -Upgrading in production -------------------------------------------------------------------------------- - -To upgrade either a single instance or a cluster, you need a new version of the -packaged (archived) application. - -A single instance upgrade is simple: - -#. Upload the package (archive) to the server. -#. Stop the current instance. -#. Deploy the new one as described in :ref:`deploying packaged applications ` - (or :ref:`archived ones `). - -.. _enterprise-cluster-upgrade: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Cluster upgrade -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To upgrade a cluster, choose one of the following scenarios: - -* **Cluster shutdown**. Recommended for backward-incompatible updates, requires - downtime. - -* **Instance by instance**. Recommended for backward-compatible updates, does - not require downtime. - -To upgrade the cluster, do the following: - -#. Schedule a downtime or plan for the instance-by-instance upgrade. - -#. Upload a new application package (archive) to all servers. - -Next, execute the chosen scenario: - -* **Cluster shutdown**: - - #. Stop all instances on all servers. - #. Deploy the new package (archive) on every server. - -* **Instance by instance**. Do the following in every replica set in succession: - - #. Stop a replica on any server. - #. Deploy the new package (archive) in place of the old replica. - #. Promote the new replica to a master (see - :ref:`Switching the replica set's master ` - section in the Tarantool manual). - #. Redeploy the old master and the rest of the instances in the replica set. - #. Be prepared to resolve possible logic conflicts. diff --git a/doc/enterprise/audit_log.rst b/doc/enterprise/audit_log.rst deleted file mode 100644 index 9c3a2d814b..0000000000 --- a/doc/enterprise/audit_log.rst +++ /dev/null @@ -1,668 +0,0 @@ -.. _enterprise_audit_module: - -Audit module -============ - -The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, CSV, or JSON format. - -It provides detailed reports of security-related activities and helps you find and -fix breaches to protect your business. For example, you can see who created a new user -and when: - -.. code-block:: json - - { - "time": "2022-04-07T13:39:36.046+0300", - "remote": "", - "session_type": "background", - "module": "tarantool", - "user": "admin", - "type": "user_create", - "tag": "", - "description": "Create user alice" - } - -It is up to each company to decide exactly what activities to audit and what actions to take. -System administrators, security engineers, and people in charge of the company may want to -audit different events for different reasons. Tarantool provides such an option for each of them. - -.. _audit-log-events: - -Audit log events ----------------- - -The Tarantool audit log module can record various events that you can monitor and -decide whether you need to take actions: - -* Admin activity -- events related to actions performed by the administrator. - For example, such logs record the creation of a user. - -* Access events -- events related to authorization and authentication of users. - For example, such logs record failed attempts to access secure data. - -* Data access and modification -- events of data manipulation in the storage. - -* System events -- events related to modification or configuration of resources. - For example, such logs record the replacement of a space. - -* :ref:`User-defined events `-- any events added manually using - the audit module API. - -The full list of available audit log events is provided in the table below: - -.. container:: table - - .. list-table:: - :widths: 30 35 35 - :header-rows: 1 - - * - Event - - Type of event written to the audit log - - Example of an event description - * - Audit log enabled for events - - ``audit_enable`` - - - * - :ref:`User-defined events ` - - ``custom`` - - - * - User authorized successfully - - ``auth_ok`` - - ``Authenticate user `` - * - User authorization failed - - ``auth_fail`` - - ``Failed to authenticate user `` - * - User logged out or quit the session - - ``disconnect`` - - ``Close connection`` - * - User created - - ``user_create`` - - ``Create user `` - * - User dropped - - ``user_drop`` - - ``Drop user `` - * - Role created - - ``role_create`` - - ``Create role `` - * - Role dropped - - ``role_drop`` - - ``Drop role `` - * - User disabled - - ``user_disable`` - - ``Disable user `` - * - User enabled - - ``user_enable`` - - ``Enable user `` - * - User granted rights - - ``user_grant_rights`` - - ``Grant rights for to user `` - * - User revoked rights - - ``user_revoke_rights`` - - ``Revoke rights for from user `` - * - Role granted rights - - ``role_grant_rights`` - - ``Grant rights for to role `` - * - Role revoked rights - - ``role_revoke_rights`` - - ``Revoke rights for from role `` - * - User password changed - - ``password_change`` - - ``Change password for user `` - * - Failed attempt to access secure data (personal records, details, geolocation, etc.) - - ``access_denied`` - - `` denied to `` - * - Expressions with arguments evaluated in a string - - ``eval`` - - ``Evaluate expression `` - * - Function called with arguments - - ``call`` - - ``Call function with arguments `` - * - Iterator key selected from ``space.index`` - - ``space_select`` - - ``Select from .`` - * - Space created - - ``space_create`` - - ``Create space `` - * - Space altered - - ``space_alter`` - - ``Alter space `` - * - Space dropped - - ``space_drop`` - - ``Drop space `` - * - Tuple inserted into space - - ``space_insert`` - - ``Insert tuple into space `` - * - Tuple replaced in space - - ``space_replace`` - - ``Replace tuple with in space `` - * - Tuple deleted from space - - ``space_delete`` - - ``Delete tuple from space `` - - - .. note:: - - The ``eval`` event displays data from the ``console`` module - and the ``eval`` function of the ``net.box`` module. - For more on how they work, see :ref:`Module console ` - and :ref:`Module net.box -- eval `. - To separate the data, specify ``console`` or ``binary`` in the session field. - -.. _audit-log-event-groups: - -Event groups ------------- - -You can simplify working with audit log events by using built-in event groups. -For example, you can set to record only events related to the enabling of the audit log, -or only events related to a space. - -Tarantool provides the following event groups: - -* ``all`` -- all :ref:`events `. - - .. note:: - - Events ``call`` and ``eval`` are included only into the ``all`` group. - -* ``audit`` -- ``audit_enable`` event. - -* ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. - -* ``priv`` -- events related to authentication, authorization, users, and roles: - ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, - ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``, ``role_revoke_rights``. - -* ``ddl`` -- events of space creation, altering, and dropping: - ``space_create``, ``space_alter``, ``space_drop``. - -* ``dml`` -- events of data modification in spaces: - ``space_insert``, ``space_replace``, ``space_delete``. - -* ``data_operations`` -- events of data modification or selection from spaces: - ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``. - -* ``compatibility`` -- events available in Tarantool before the version 2.10.0. - ``auth_ok``, ``auth_fail``, ``disconnect``, ``user_create``, ``user_drop``, - ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, - ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``. - ``role_revoke_rights``, ``password_change``, ``access_denied``. - This group enables the compatibility with earlier Tarantool versions. - -.. warning:: - - Be careful when recording ``all`` and ``data_operations`` event groups. - The more events you record, the slower the requests will be processed over time. - It is recommended that you select only those groups - whose events your company really needs to monitor and analyze. - -.. _audit-log-structure: - -Structure of audit log events ------------------------------ - -Each audit log event contains several fields to make it easy to filter and aggregate the resulting logs. -They are described in the following table. - -.. container:: table - - .. list-table:: - :widths: 30 35 35 - :header-rows: 1 - - * - Field - - Description - - Example of a log field display - * - ``time`` - - Time of the event - - 2022-04-07T13:20:05.327+0300 - * - ``remote`` - - Remote host that triggered the event - - 100.96.163.226:48722 - * - ``session_type`` - - Session type - - console - * - ``module`` - - Audit log module. Set to ``tarantool`` for system events; - can be overwritten for user-defined events - - tarantool - * - ``user`` - - User who triggered the event - - admin - * - ``type`` - - Audit event type - - access_denied - * - ``tag`` - - A text field that can be overwritten by the user - - - * - ``description`` - - Human-readable event description - - Authenticate user Alice - - .. warning:: - - You can set all these parameters only once. Unlike many other parameters in ``box.cfg``, - they cannot be changed. - -.. _audit-log-start: - -Enable the Tarantool audit log ------------------------------- - -By default, audit logging is disabled. To enable audit logging, -define the logs location by setting the ``box.cfg.audit_log`` option. -Tarantool can write audit logs to a file, to a pipe, or to the system logger. - -To disable audit logging, set the ``audit_log`` option to ``nil``. - -Write to a file -~~~~~~~~~~~~~~~ - -.. code-block:: lua - - box.cfg{audit_log = 'audit_tarantool.log'} - -- or - box.cfg{audit_log = 'file:audit_tarantool.log'} - -This opens the ``audit_tarantool.log`` file for output in the server’s default directory. -If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path. - -Send to a pipe -~~~~~~~~~~~~~~ - -.. code-block:: lua - - box.cfg{audit_log = '| cronolog audit_tarantool.log'} - -- or - box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}' - -This starts the `cronolog `_ program when the server starts -and sends all ``audit_log`` messages to cronolog's standard input (``stdin``). -If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, -the string is interpreted as a Unix `pipeline `_. - -Send to syslog -~~~~~~~~~~~~~~ - -.. warning:: - - Below is an example of writing audit logs to a directory shared with the system logs. - Tarantool allows this option, but it is not recommended to do this to avoid difficulties - when working with audit logs. System and audit logs should be written separately. - To do this, create separate paths and specify them. - -This example setting sends the audit log to syslog: - -.. code-block:: lua - - box.cfg{audit_log = 'syslog:identity=tarantool'} - -- or - box.cfg{audit_log = 'syslog:facility=user'} - -- or - box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'} - -- or - box.cfg{audit_log = 'syslog:server=unix:/dev/log'} - -If the ``audit_log`` string starts with "syslog:", -it is interpreted as a message for the `syslogd `_ program, -which normally runs in the background of any Unix-like platform. -The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination. - -The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages. -The default value is ``tarantool``. - -The ``syslog:facility`` setting is currently ignored, but will be used in the future. -The value must be one of the `syslog `_ keywords -that tell ``syslogd`` where to send the message. -The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``, -``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``, -``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``. -The default value is ``local7``. - -The ``syslog:server`` setting is the locator for the syslog server. -It can be a Unix socket path starting with "unix:" or an ipv4 port number. -The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS). -The default port value is 514, which is the UDP port. - -If you log to a file, Tarantool will reopen the audit log at `SIGHUP `_. -If log is a program, its pid is stored in the ``audit_log.logger_pid`` variable. -You need to send it a signal to rotate logs. - -An example of a Tarantool audit log entry in the syslog: - -.. code-block:: json - - { - "__CURSOR" : "s=81564632436a4de590e80b89b0151148;i=11519;b=def80c1464fe49d1aac8a64895d6614d;m=8c825ebfc;t=5edb27a75f282;x=7eba320f7cc9ae4d", - "__REALTIME_TIMESTAMP" : "1668725698065026", - "__MONOTONIC_TIMESTAMP" : "37717666812", - "_BOOT_ID" : "def80c1464fe49d1aac8a64895d6614d", - "_UID" : "1003", - "_GID" : "1004", - "_COMM" : "tarantool", - "_EXE" : "/app/tarantool/dist/tdg-2.6.4.0.x86_64/tarantool", - "_CMDLINE" : "tarantool init.lua : core-03", - "_CAP_EFFECTIVE" : "0", - "_AUDIT_SESSION" : "1", - "_AUDIT_LOGINUID" : "1003", - "_SYSTEMD_CGROUP" : "/user.slice/user-1003.slice/user@1003.service/app.slice/app@core-03.service", - "_SYSTEMD_OWNER_UID" : "1003", - "_SYSTEMD_UNIT" : "user@1003.service", - "_SYSTEMD_USER_UNIT" : "app@core-03.service", - "_SYSTEMD_SLICE" : "user-1003.slice", - "_SYSTEMD_USER_SLICE" : "app.slice", - "_SYSTEMD_INVOCATION_ID" : "be368b4243d842ea8c06b010e0df62c2", - "_MACHINE_ID" : "2e2339725deb4bc198c54ff4a2e8d626", - "_HOSTNAME" : "vm-0.test.env", - "_TRANSPORT" : "syslog", - "PRIORITY" : "6", - "SYSLOG_FACILITY" : "23", - "SYSLOG_IDENTIFIER" : "tarantool", - "SYSLOG_PID" : "101562", - "_PID" : "101562", - "MESSAGE" : "remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[119eae0e-a691-42cc-9b4c-f14c499e6726] subj: \"anonymous\", msg: \"Access granted to anonymous user\"", - "_SOURCE_REALTIME_TIMESTAMP" : "1668725698064202" - } - -.. _audit-log-filters: - -Select events to write to audit log ------------------------------------ - -Tarantool's extensive filtering options help you write only the events you need to the audit log. - -To select events to write to audit log, use the ``box.cfg.audit_filter`` option. -Its value can be a list of events and event groups. -The default value for the ``box.cfg.audit_filter`` option is ``compatibility``, -which enables logging of all events available before 2.10.0. - -.. code-block:: lua - - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'audit,auth,priv,password_change,access_denied' - } - -.. _audit-log-combinations: - -Customize your filters -~~~~~~~~~~~~~~~~~~~~~~ - -You can customize the filters and use different combinations of filters for your purposes. - -Filter based on a specific event -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can set only certain events that you need to record. - -For example, select ``password_change`` to monitor the users who have changed their passwords. - -.. code-block:: lua - - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'password_change' - } - -Filter based on a specific group -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can set one of the groups of events that you need to record. - -For example, select ``compatibility`` to monitor only events of user authorization, -granted privileges, disconnection, user password change, and denied access. - -.. code-block:: lua - - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'compatibility' - } - -Filter based on multiple groups -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can specify multiple groups depending on the purpose. - -For example, select ``auth`` and ``priv`` to see only events related to authorization and granted privileges. - -.. code-block:: lua - - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'auth,priv' - } - -Filter based on a group and a specific event -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can specify a group and a certain event depending on the purpose. - -For example, you can select ``priv`` and ``disconnect`` to see only events related to -granted privileges and disconnect events. - -.. code-block:: lua - - box.cfg{ - audit_log = 'audit.log', - audit_filter = 'priv,disconnect' - } - -Example -~~~~~~~ - -Run the command to filter: - -.. code-block:: lua - - local audit = require('audit') - - box.cfg{audit_log = 'audit.log', audit_filter = 'custom,user_create', audit_format = 'csv'} - -- The Tarantool audit module writes the event because a filter is set for it - box.schema.user.create('alice') - -- The Tarantool audit module will not write the event because no filter is set for it - box.schema.user.drop('alice') - -.. _audit-log-nonblock: - -Configure a blocking mode -------------------------- - -By default, the ``audit_nonblock`` option is set to ``true`` -and Tarantool will not block during logging if the system is not ready to write, dropping the message instead. -Using this value may improve logging performance at the cost of losing some log messages. -This option only has an effect if the output goes to ``syslog:`` or ``pipe:``. -Setting ``audit_nonblock`` to ``true`` is not allowed if the output is to a file. -In this case, set ``audit_nonblock`` to ``false``. - -.. _audit-log-format: - -Configure the format of audit log events ----------------------------------------- - -You can choose the format of audit log events -- plain text, CSV or JSON format. - -Plain text is used by default. This human-readable format can be efficiently compressed. -The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. -Using the CSV format allows you to view audit log events in tabular form. - -Use these commands to configure the format of audit log events in Tarantool. - -Plain text -~~~~~~~~~~ - -.. code-block:: lua - - box.cfg{audit_log = 'audit.log', audit_format = 'plain'} - -Example: - -.. code-block:: text - - remote: - session_type:background - module:common.admin.auth - user: type:custom_tdg_audit - tag:tdg_severity_INFO - description:[5e35b406-4274-4903-857b-c80115275940] - subj: "anonymous", - msg: "Access granted to anonymous user" - -JSON format -~~~~~~~~~~~ - -.. code-block:: lua - - box.cfg{audit_log = 'audit.log', audit_format = 'json'} - -Example: - -.. code-block:: json - - { - "time": "2022-11-17T21:55:49.880+0300", - "remote": "", - "session_type": "background", - "module": "common.admin.auth", - "user": "", - "type": "custom_tdg_audit", - "tag": "tdg_severity_INFO", - "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\"" - } - -CSV format -~~~~~~~~~~ - -.. code-block:: lua - - box.cfg{audit_log = 'audit.log', audit_format = 'csv'} - -Example: - -.. code-block:: text - - 2022-11-17T21:58:03.131+0300,,background,common.admin.auth,,,custom_tdg_audit,tdg_severity_INFO,"[b3dfe2a3-ec29-4e61-b747-eb2332c83b2e] subj: ""anonymous"", msg: ""Access granted to anonymous user""" - -.. _audit-log-custom: - -Create user-defined events --------------------------- - -Tarantool provides an API for writing user-defined audit log events. - -To add a new event, use the ``audit.log()`` function that takes one of the following values: - -* Message string. Printed to the audit log with type ``message``. Example: ``audit.log('Hello, World!')``. - -* Format string and arguments. Passed to string format and then output to the audit log with type message. - Example: ``audit.log('Hello, %s!', 'World')``. - -* Table with audit log field values. The table must contain at least one field -- description. - Example: ``audit.log({type = 'custom_hello', description = 'Hello, World!'})``. - -Using the field ``audit.new()``, you can create a new log module that allows you -to avoid passing all custom audit log fields each time ``audit.log()`` is called. -It takes a table of audit log field values (same as ``audit.log()``). The ``type`` -of the log module for writing user-defined events must either be ``message`` or -have the ``custom_`` prefix. - -Example -~~~~~~~ - -.. code-block:: lua - - local my_audit = audit.new({type = 'custom_hello', module = 'my_module'}) - my_audit:log('Hello, Alice!') - my_audit:log({tag = 'admin', description = 'Hello, Bob!'}) - - -- is equivalent to - audit.log({type = 'custom_hello', module = 'my_module', - description = 'Hello, Alice!' }) - audit.log({type = 'custom_hello', module = 'my_module', - tag = 'admin', description = 'Hello, Bob!'}) - - -Some user-defined audit log fields (``time``, ``remote``, ``session_type``) -are set in the same way as for a system event. -If a field is not overwritten, it is set to the same value as for a system event. - -Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``: - -* type -* user -* module -* tag -* description - - .. note:: - - To avoid confusion with system events, the value of the type field must either be ``message`` (default) - or begin with ``custom_``. Otherwise you will get the error message. - User-defined events are filtered out by default. - To enable user-defined audit log events, you must add ``custom`` to ``box.cfg.audit_filter``. - -Example -~~~~~~~ - -.. code-block:: lua - - local audit = require('audit') - - box.cfg{audit_log = 'audit.log', audit_filter = 'custom', audit_format = 'csv'} - audit.log('Hello, Alice!') - audit.log('Hello, %s!', 'Bob') - audit.log({type = 'custom_hello', description = 'Hello, Eve!'}) - audit.log({type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!'}) - - local my_audit = audit.new({module = 'my_module', tag = 'default'}) - my_audit:log({description = 'Message 1'}) - my_audit:log({description = 'Message 2', tag = 'my_tag'}) - my_audit:log({description = 'Message 3', module = 'other_module'}) - -.. _audit-log-read: - -Use read commands ------------------ - -To easily read the audit log events in the needed form, use the different commands: - -* ``cat`` -- prints one or more files - -* ``grep`` -- prints a specific text - -* ``head`` -- prints the first N lines of the file - -* ``tail`` -- prints the last N lines of the file - - .. note:: - - These are the basic commands to help you read the logs. If necessary, you can use other commands. - -.. _audit-log-tips: - -Tips ----- - -How many events can be recorded? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you write to a file, the size of the Tarantool audit module is limited by the disk space. -If you write to a system logger, the size of the Tarantool audit module is limited by the system logger. -If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer -if the ``audit_nonblock`` = ``false``; if ``audit_nonblock`` = ``true``, there is no limit. -However, it is not recommended to use the entire memory, as this may cause performance degradation -and even loss of some logs. - -How often should audit logs be reviewed? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Consider setting up a schedule in your company. It is recommended to review audit logs at least every 3 months. - -How long should audit logs be stored? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is recommended to store audit logs for at least one year. - -What is the best way to process audit logs? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is recommended to use SIEM systems for this issue. diff --git a/doc/enterprise/cartridge-auth.rst b/doc/enterprise/cartridge-auth.rst deleted file mode 100644 index 3cd3a7b796..0000000000 --- a/doc/enterprise/cartridge-auth.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. _enterprise-cartridge-auth: - -LDAP authorization -================== - -This chapter describes how to manage the access roles for LDAP users authorizing in your Cartridge application. - -Setting up this feature is twofold: - -* :ref:`enabling the feature ` for your application -* :ref:`specifying configuration parameters `. - -.. note:: - - For information on setting up the authorization of external users in your application, refer to :ref:`ldap_auth`. - -.. _enterprise-cartridge-auth-enable: - -Enabling LDAP authorization ---------------------------- - -First, you should enable LDAP authorization function in your :ref:`application development project `: - -* set up dependency to the ``cartridge-auth-extension`` module that is available in the :ref:`Enterprise Edition's package `. -* update the configuration in the application initialization file. - -.. note:: - - If you don't have a development project yet, refer to :doc:`dev` on how to create it. - -1. In your development project, find a ``.rockspec`` file and specify the following dependency: - - .. code-block:: bash - - dependencies = { - 'cartridge-auth-extension' - } - -2. In an initialization Lua file of your project, specify the ``cartridge-auth-extension`` :ref:`cluster role ` in the :ref:`Cartridge configuration `. - The role enables storing authorized users and validating the :ref:`LDAP configuration `. - - .. code-block:: lua - - cartridge.cfg({ - roles = { - 'cartridge-auth-extension', - }, - auth_backend_name = 'cartridge-auth-extension', - }) - -3. Deploy and start your application. For details, refer to :doc:`dev`. - -.. _enterprise-cartridge-auth-config: - -Configuring LDAP authorization ------------------------------- - -After starting your application, you need to configure LDAP authorization. It can be done via the GUI administrative console. - -1. In a web browser, open the GUI administrative console of your application. - -2. If you have the application instances already configured, proceed to the next step. Otherwise, refer to :ref:`cartridge-deployment` on how to configure the cluster. - -3. In the GUI administrative console, navigate to the **Code** tab. Create the following YAML configuration files and specify the necessary parameters. - Below is the example of configuration and the :ref:`description of parameters `. - -.. note:: - - If you set the authorization mode as ``local`` in the ``auth_extension.yml`` file, you don't need to define LDAP configuration parameters in the ``ldap.yml`` file. - - -* ``auth_extension.yml`` - - .. code-block:: yaml - - method: local+ldap - -* ``ldap.yml`` - - .. code-block:: yaml - - - domain: 'test.glauth.com' - organizational_units: ['all_staff'] - hosts: - - localhost:3893 - use_tls: false - use_active_directory: false - search_timeout: 2 - roles: - - role: 'admin' - domain_groups: - - 'cn=superusers,ou=groups,dc=glauth,dc=com' - - 'cn=users,ou=groups,dc=glauth,dc=com' - options: - LDAP_OPT_DEBUG_LEVEL: 10 - -* ``auth.yml`` - - .. code-block:: yaml - - enabled: true - -.. _enterprise-cartridge-auth-config-params: - -**Configuration parameters:** - -* ``method`` -- authorization mode. Possible values: - - * ``local`` -- only local users can be authorized in the application. "Local" refers to users created in the application. - * ``ldap`` -- only LDAP users can be authorized. - * ``local+ldap`` -- both local and LDAP users can be authorized. - -* ``domain`` -- domain name that is used in the domain login ID (``user_name@domain``). - -* ``organizational_units`` -- names of the organizational units or user groups. - -* ``hosts`` -- LDAP server addresses. - -* ``use_tls`` -- boolean flag that defines TLS usage. Defaults to ``false``. - -* ``use_active_directory`` -- boolean flag that defines usage of the Active Directory. Defaults to ``false``. - If set to ``true``, use the login ID in the email format (``user_name@domain``). - The ID should be equal to the ``userPrincipalName`` Active Directory attribute value because the latter is used in the Active Directory filter. - -* ``search_timeout`` -- LDAP server response timeout. Defaults to 2 seconds. - -* ``roles`` -- user roles assigned to a user depending on the LDAP groups the user belongs to: - - * ``role`` -- user role; - * ``domain_groups`` -- LDAP groups where ``cn`` -- common name; ``ou`` -- organization unit name; ``dc`` -- domain component. - -* ``options`` -- the OpenLDAP library options. Supported options: - - * LDAP_OPT_X_TLS_REQUIRE_CERT - * LDAP_OPT_PROTOCOL_VERSION - * LDAP_OPT_DEBUG_LEVEL - * LDAP_OPT_X_TLS_CACERTFILE - * LDAP_OPT_X_TLS_CACERTDIR. - - For description of the options, refer to the `OpenLDAP documentation `__. - -* ``enabled`` -- boolean flag. If set to ``true``, enables mandatory authentication mode in the application web interface. - diff --git a/doc/enterprise/changelog.rst b/doc/enterprise/changelog.rst deleted file mode 100644 index 44e51b03dd..0000000000 --- a/doc/enterprise/changelog.rst +++ /dev/null @@ -1,486 +0,0 @@ -.. _enterprise_changelog: - -Changelog -========= - -Versioning policy ------------------ - -A Tarantool Enterprise SDK version consists of two parts: - -.. code-block:: text - - -r - - -For example: ``2.11.1-0-gc42d9735b-r589``. - -- ``TARANTOOL_BASE_VERSION`` is the Community version which the Enterprise version is based on. -- ``REVISION`` is the SDK revision. Besides Tarantool itself, it includes the ``tt`` utility, a set of open and closed source modules, and examples. Learn more from :ref:`Package contents `. - -598 ---- - -- Updated cartridge-cli to `2.12.9 `__. -- Updated tt-ee to `1.3.1 `__. - -595 ---- - -- Updated tt-ee to `1.3.0 `__. -- Updated cartridge to `2.8.3 `__. -- Updated cartridge-cli-extensions to `1.1.2 `__. -- Updated crud to `1.3.0 `__. -- Updated queue to `1.3.3 `__. -- Updated sharded-queue to `0.1.1 `__. -- Updated membership to `2.4.1 `__. -- Added tests for Astra Linux 1.7. - - -589 ---- - -- Updated ``tarantool-2.10`` to 2.10.8. -- Updated ``tarantool-master`` to 3.0.0-alpha3. -- Updated migrations to `0.6.0 `__. -- Updated tt-ee to `1.2.0 `__. -- Updated space-explorer to `1.1.8 `__. -- Updated cartridge-metrics-role to `0.1.1 `__. -- Updated cartridge to `2.8.2 `__. -- Updated expirationd to `1.5.0 `__. -- Added sideservice `0.1.0 `__. - -579 ---- - -- Updated cartridge-cli to `2.12.7 `__. -- Updated ``tarantool-2.11`` to 2.11.1. - -577 ---- - -- Added crud `1.2.0 `__. -- Added ddl `1.6.3 `__. -- Added sharded-queue `0.1.0 `__. -- Added ddl `1.6.4 `__. -- Updated tt-ee to `1.1.2 `__. -- Updated cartridge-cli to `2.12.6 `__. - -563 ---- - -- Updated ``tarantool-2.10`` to 2.10.7. -- Updated ``tarantool-2.11`` to 2.11.0. -- Added kafka `1.6.6 `__. -- Added vshard `0.1.24 `__. -- Added metrics `1.0.0 `__. -- Added cartridge-metrics-role `0.1.0 `__. -- Added cartridge `2.8.0 `__. -- Added http `1.5.0 `__. - -557 ---- - -- Added checks `3.3.0 `__. -- Updated cartridge-cli to `2.12.5 `__. - -553 ---- - -- Added ``tt-ee`` and ``tt`` environment configuration. -- Added crud `1.1.1 `__. -- Added avro-schema `3.1.1 `__. -- Added expirationd `1.4.0 `__. -- Added graphql `0.3.0 `__. -- Added graphqlapi `0.0.10 `__. -- Added metrics `0.17.0 `__. -- Added migrations `0.5.0 `__. -- Added oracle `1.4.0 `__. -- Added cartridge `2.7.9 `__. -- Added vshard `0.1.23 `__. -- Added kafka `1.6.5 `__. - -549 ---- - -- Updated ``tarantool-2.10`` to 2.10.6. - -545 ---- - -- Updated ``tarantool-2.11`` to 2.11.0-rc2. - -543 ---- - -- Added the ``tarantool-2.11`` submodule. - -542 ---- - -- Updated ``tarantool-1.10`` to 1.10.15. - -541 ---- - -- Updated ``tarantool-master`` to ``3.0.0-entrypoint``. - -540 ---- - -- Updated ``tarantool-2.10`` to 2.10.5. - -539 ---- - -- Added vshard `0.1.22 `__. - -538 ---- - -- Updated ``tarantool-2.8`` to apply 2 hotfixes. - -537 ---- - -- Fix non-interactive installation of the ``brew`` package. - -- Changed the owner of the ``/usr/local/bin`` directory. - -- Installed ``awscli@1`` instead of ``awscli`` since it takes much less - time. - -536 ---- - -- Added the missing property ``2.10`` for scope ``CACHE`` in CMakeLists.txt. - -535 ---- - -- Added expirationd `1.3.1 `__. - -534 ---- - -- Added crud `1.0.0 `__. - -533 ---- - -- Use runners with label ``regular`` for builds and the tagged release - workflow. - -532 ---- - -- Added http `1.4.0 `__. -- Added space-explorer `1.1.7 `__. -- Added checks `3.2.0 `__. -- Added metrics `0.16.0 `__. -- Added cartridge `2.7.8 `__. - -531 ---- - -- Added the ``-DENABLE_LTO=ON`` flag for tarantool-ee@master branch to - CMakeLists.txt - -530 ---- - -- Upgraded devtoolset from 8 to 9. It was required for upgrading ld from - 2.30 to 2.31+ for LTO. - - -529 ---- - -- Updated tarantool’s master branch to a recent revision. - -528 ---- - -- Fixed code style in the Linux and macOS workflows. - -527 ---- - -- Reliably install packages in macOS builds. - -526 ---- - -- Refactored the way that GC64 builds are defined in the build workflow. - There are no changes to the composition of resulting bundles. - -525 ---- - -- Added alerting failures in builds on stable branches and integration testing - to VK Teams chats. - -524 ---- - -- Updated to fresh tarantool master (``2.11.0-entrypoint-107-ga18449d``) - -523 ---- - -- Added cartridge `2.7.7 `__. - -522 ---- - -- Outdated workflow runs are now canceled to save CI time. - -521 ---- - -- Added crud `0.14.1 `__. -- Added expirationd `1.3.0 `__. -- Added metrics `0.15.1 `__. -- Added queue `1.2.2 `__. - -520 ---- - -Release SDK by tags: - -- Run workflow in SDK docker container. -- Upload SDK files for 1.10, 2.8, 2.10 versions to release folder. -- Add consistency check for all versions. - -519 ---- - -* On feature branches, SDK is now rebuilt only on relevant changes. - -r518 ----- - -* Added frontend core `8.2.1 `__. -* Added vshard `0.1.21 `__. -* Added http `1.3.0 `__. -* Added cartridge `2.7.6 `__. - -r517 ----- - -* Updated Tarantool EE to `2.10.4 `__. - -r516 ----- - -* Updated bundled OpenSSL to version 1.1.1q. - -r515 ----- - -* Removed support of Tarantool 2.7. -* Started using ``tarantool/actions/prepare-checkout`` to make builds more stable. - -r514 ----- - -* Remove the local registry and setup using GitHub registry. -* Sync rocks cache to s3 and back. -* Setup using shared runners. -* Refactor and format ``ci-linux.yml`` and ``ci-macos.yml``. - -r513 ----- - -* Removed kafka 1.5.0 due to a build issue with Tarantool 2.10.3 and higher. -* Updated kafka to version `1.6.2 `__. - -r512 ----- - -* Updated tuple-keydef to version `0.0.3 `__. - -r511 ----- - -* Enabled parallel build of rocks for macOS in CI. - -r510 ----- - -* Updated Tarantool to :doc:`2.10.3 `. -* Added a readable error for the case when the flight recoder fails - to write data due to insufficient free space on the disk device. - Previously, it was sending a `SIGBUS` error (:tarantool-ee-issue:`196`). -* Fixed a crash in the flight recorder caused by non-thread-safe log - recording from multiple threads (:tarantool-ee-issue:`226`). - -r502 ----- - -* Updated Tarantool to :doc:`2.10.2 `. -* Increased resolution of stored entries in flight recorder (:tarantool-ee-issue:`193`). -* Fixed a bug in the flight recorder that resulted in skipping log entries in case - ``box.cfg.log_level`` is less than ``flightrec_log_level`` (:tarantool-ee-issue:`201`). - -r498 ----- - -* Updated Tarantool to :doc:`2.10.1 `. -* Updated Cyrus SASL to version 2.1.28. -* Updated OpenLDAP to version 2.5.13. -* Updated LZ4 to version 1.9.3. Fixed `CVE-2021-3520 `__. -* Fixed replication reconnect failure after disabling SSL encryption (:tarantool-ee-issue:`137`). -* Fixed a crash that occurred while tyring to start an instance that has - a compressed memtx space (:tarantool-ee-issue:`171`). -* Fixed `CVE-2022-29242 `__ in GOST SSL engine. -* Fixed a bug in the flight recorder reader implementation that resulted in - a hang or error while trying to open an empty section (:tarantool-ee-issue:`187`). - -r467 ----- - -Breaking changes -~~~~~~~~~~~~~~~~ - -* Default audit log format was changed to CSV. - -Functionality added or changed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enterprise -^^^^^^^^^^ - -* Implemented user-defined audit events. Now it's possible to log custom - messages to the audit log from Lua (:tarantool-ee-issue:`65`). - -* **[Breaking change]** Switched the default audit log format to CSV. The - format can be switched back to JSON using the new ``box.cfg.audit_format`` - configuration option (:tarantool-ee-issue:`66`). - -* Implemented the audit log filter. Now, it's possible to enable logging only - for a subset of all audit events using the new ``box.cfg.audit_filter`` - configuration option (:tarantool-ee-issue:`67`). - -Core -^^^^ - -* Implement constraints and foreign keys. Now a user can create function constraints and foreign key relations - (:tarantool-issue:`6436`). -* Changed log level of some information messages from critical to info - (:tarantool-issue:`4675`). -* Added predefined system events: ``box.status``, ``box.id``, ``box.election`` - and ``box.schema`` (:tarantool-issue:`6260`). -* Introduced transaction isolation levels in Lua and IPROTO (:tarantool-issue:`6930`). - -Vinyl -^^^^^ - -* Disabled the deferred DELETE optimization in Vinyl to avoid possible - performance degradation of secondary index reads. Now, to enable the - optimization, one has to set the ``defer_deletes`` flag in space options - (:tarantool-issue:`4501`). - -Lua -^^^ - -* Added support of console autocompletion for net.box objects ``stream`` - and ``future`` (:tarantool-issue:`6305`). - -Datetime -^^^^^^^^ - -* Parse method to allow converting string literals in extended iso-8601 - or rfc3339 formats (:tarantool-issue:`6731`). -* The range of supported years has been extended in all parsers to cover - fully -5879610-06-22..5879611-07-11 (:tarantool-issue:`6731`). - -Build -^^^^^ - -* Added bundling of *GNU libunwind* to support backtrace feature on - *AARCH64* architecture and distributives that don't provide *libunwind* - package. -* Re-enabled backtrace feature for all *RHEL* distributions by default, except - for *AARCH64* architecture and ancient *GCC* versions, which lack compiler - features required for backtrace (gh-4611). - -Bugs fixed -~~~~~~~~~~ - -Enterprise -^^^^^^^^^^ - -* Disabled audit log unless explicitly configured (:tarantool-ee-issue:`39`). Before this change, - audit events were written to stderr if ``box.cfg.audit_log`` wasn't set. Now, - audit log is disabled in this case. -* Disabled audit logging of replicated events (:tarantool-ee-issue:`59`). Now, replicated events - (for example, user creation) are logged only on the origin, never on a - replica. - -Core -^^^^ - -* Banned DDL operations in space on_replace triggers, since they could lead - to a crash (:tarantool-issue:`6920`). -* Fixed a bug due to which all fibers created with ``fiber_attr_setstacksize()`` - leaked until the thread exit. Their stacks also leaked except when - ``fiber_set_joinable(..., true)`` was used. -* Fixed a crash in mvcc connected with secondary index conflict (:tarantool-issue:`6452`). -* Fixed a bug which resulted in wrong space count (:tarantool-issue:`6421`). -* Select in RO transaction now reads confirmed data, like a standalone (auotcommit) select does - (:tarantool-issue:`6452`). - -Replication -^^^^^^^^^^^ - -* Fixed potential obsolete data write in synchronious replication - due to race in accessing terms while disk write operation is in - progress and not yet completed. -* Fixed replicas failing to bootstrap when master is just re-started (:tarantool-issue:`6966`). - -Lua -^^^ - -* Fixed the behavior of tarantool console on SIGINT. Now Ctrl+C discards - the current input and prints the new prompt (:tarantool-issue:`2717`). - -Triggers -^^^^^^^^ - -* Fixed assertion or segfault when MP_EXT received via net.box (:tarantool-issue:`6766`). -* Now ROUND() properly support INTEGER and DECIMAL as the first - argument (:tarantool-issue:`6988`). - -Datetime -^^^^^^^^ - -* Intervals received after datetime arithmetic operations may be improperly - normalized if result was negative - - .. code-block:: tarantoolsession - - tarantool> date.now() - date.now() - --- - - -1.000026000 seconds - ... - - I.e. 2 immediately called ``date.now()`` produce very close values, whose - difference should be close to 0, not 1 second (gh-6882). - -Net.box -^^^^^^^ - -* Changed the type of the error returned by net.box on timeout - from ClientError to TimedOut (:tarantool-issue:`6144`). - -r457 ----- - -- Fixed some binary protocol encryption bugs. - -r455 ----- - -- Added :ref:`binary protocol encryption `. -- Added :doc:`tuple field compression `. \ No newline at end of file diff --git a/doc/enterprise/deprecated.rst b/doc/enterprise/deprecated.rst deleted file mode 100644 index 248a0fd3cc..0000000000 --- a/doc/enterprise/deprecated.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _enterprise_deprecated_features: - -Deprecated features -=================== - -The ZooKeeper along with ``orchestrator`` are no longer supported. However, they -still can be used, if necessary. - -The following sections describe the corresponding functionality. - -.. _manage-sharding-api: - -Controlling the cluster via API -------------------------------- - -To control the cluster, use the ``orchestrator`` included in the delivery package. -The ``orchestrator`` uses ZooKeeper to store and distribute the configuration. -The ``orchestrator`` provides the REST API for controlling the cluster. -Configurations in the ZooKeeper are changed as a result of calling the ``orchestrator``'s -API-functions, which in turn leads to changes in configurations of the Tarantool -nodes. - -We recommend using a **curl** command line interface to call the API-functions -of the ``orchestrator``. - -The following example shows how to register a new availability zone (DC): - -.. code-block:: kconfig - - $ curl -X POST http://HOST:PORT/api/v1/zone \ - -d '{ - "name": "Caucasian Boulevard" - }' - -To check whether the DC registration was successful, try the following instruction. -It retrieves the list of all registered nodes in the JSON format: - -.. code-block:: console - - $ curl http://HOST:PORT/api/v1/zone| python -m json.tool - -To apply the new configuration directly on the Tarantool nodes, increase the -configuration version number after calling the API function. To do this, use the -POST request to ``/api/v1/version``: - -.. code-block:: console - - $ curl -X POST http://HOST:PORT/api/v1/version - -Altogether, to update the cluster configuration: - -1. Call the ``POST/PUT`` method of the ``orchestrator``. - As a result, the ZooKeeper nodes are updated, and a subsequent update of the - Tarantool nodes is initiated. -2. Update the configuration version using the ``POST`` request to ``/api/v1/version``. - As a result, the configuration is applied to the Tarantool nodes. - -See the :ref:`Orchestrator API reference ` for the detailed orchestrator API. - -.. _geo-redundancy-setup: - -Setting up geo redundancy -------------------------- - -Logically, cluster nodes can belong to some availability zone. Physically, an -availability zone is a separate DC, or a rack inside a DC. You can specify a matrix -of weights (distances) for the availability zones. - -New zones are added by calling a corresponding API method of the orchestrator. - -By default, the matrix of weights (distances) for the zones is not configured, -and geo-redundancy for such configurations works as follows: - -* Data is always written to the master. -* If the master is available, then it is used for reading. -* If the master is unavailable, then any available replica is used for reading. - -When you define a matrix of weights (distances) by calling ``/api/v1/zones/weights``, -the automatic scale-out system of the Tarantool DBMS finds a replica which is the -closest to the specified router in terms of weights, and starts using this replica -for reading. If this replica is not available, then the next nearest replica is -selected, taking into account the distances specified in the configuration. - - -.. toctree:: - :hidden: - - deprecated/orchestrator_api diff --git a/doc/enterprise/deprecated/orchestrator_api.rst b/doc/enterprise/deprecated/orchestrator_api.rst deleted file mode 100644 index 78d34c3c6d..0000000000 --- a/doc/enterprise/deprecated/orchestrator_api.rst +++ /dev/null @@ -1,954 +0,0 @@ -.. _enterprise_orchestrator_api: - -Orchestrator API reference -========================== - -.. _orchestrator-configure-zones: - -Configuring the zones ---------------------- - -* :ref:`POST /api/v1/zone ` -* :ref:`GET /api/v1/zone/ ` -* :ref:`PUT /api/v1/zone/ ` -* :ref:`DELETE /api/v1/zone/ ` - -.. _orchestrator_api-post_zone: - -.. function:: POST /api/v1/zone - - Create a new zone. - - **Request** - - .. code-block:: kconfig - - { - "name": "zone 1" - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "id": 2, - "name": "zone 2" - }, - "status": true - } - - **Potential errors** - - * ``zone_exists`` - the specified zone already exists - -.. _orchestrator_api-get_zone: - -.. function:: GET /api/v1/zone/{zone_id: optional} - - Return information on the specified zone or on all the zones. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": [ - { - "id": 1, - "name": "zone 11" - }, - { - "id": 2, - "name": "zone 2" - } - ], - "status": true - } - - **Potential errors** - - * ``zone_not_found`` - the specified zone is not found - -.. _orchestrator_api-put_zone: - -.. function:: PUT /api/v1/zone/{zone_id} - - Update information on the zone. - - **Body** - - .. code-block:: kconfig - - { - "name": "zone 22" - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``zone_not_found`` - the specified zone is not found - -.. _orchestrator_api-delete_zone: - -.. function:: DELETE /api/v1/zone/{zone_id} - - Delete a zone if it doesn’t store any nodes. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``zone_not_found`` - the specified zone is not found - * ``zone_in_use`` - the specified zone stores at least one node - -.. _orchestrator-configure-zone-weights: - -Configuring the zone weights ----------------------------- - -* :ref:`GET /api/v1/zones/weights ` -* :ref:`POST /api/v1/zones/weights ` - -.. _orchestrator_api-post_weights: - -.. function:: POST /api/v1/zones/weights - - Set the zone weights configuration. - - **Body** - - .. code-block:: kconfig - - { - "weights": { - "1": { - "2": 10, - "3": 11 - }, - "2": { - "1": 10, - "3": 12 - }, - "3": { - "1": 11, - "2": 12 - } - } - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``zones_weights_error`` - configuration error - -.. _orchestrator_api-get_weights: - -.. function:: GET /api/v1/zones/weights - - Return the zone weights configuration. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "1": { - "2": 10, - "3": 11 - }, - "2": { - "1": 10, - "3": 12 - }, - "3": { - "1": 11, - "2": 12 - } - }, - "status": true - } - - **Potential errors** - - * ``zone_not_found`` - the specified zone is not found - -.. _orchestrator-configure-registry: - -Configuring registry --------------------- - -* :ref:`GET /api/v1/registry/nodes/new ` -* :ref:`POST /api/v1/registry/node ` -* :ref:`PUT /api/v1/registry/node/ ` -* :ref:`GET /api/v1/registry/node/ ` -* :ref:`DELETE /api/v1/registry/node/ ` - -.. _orchestrator_api-get_new: - -.. function:: GET /api/v1/registry/nodes/new - - Return all the detected nodes. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": [ - { - "uuid": "uuid-2", - "hostname": "tnt2.public.i", - "name": "tnt2" - } - ], - "status": true - } - -.. _orchestrator_api-post_registry_node: - -.. function:: POST /api/v1/registry/node - - Register the detected node. - - **Body** - - .. code-block:: kconfig - - { - "zone_id": 1, - "uuid": "uuid-2", - "uri": "tnt2.public.i:3301", - "user": "user1:pass1", - "repl_user": "repl_user1:repl_pass1", - "cfg": { - "listen": "0.0.0.0:3301" - } - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``node_already_registered`` - the specified node is already registered - * ``zone_not_found`` - the specified zone is not found - * ``node_not_discovered`` - the specified node is not detected - -.. _orchestrator_api-put_node: - -.. function:: PUT /api/v1/registry/node/{node_uuid} - - Update the registered node parameters. - - **Body** - - Pass only those parameters that need to be updated. - - .. code-block:: kconfig - - { - "zone_id": 1, - "repl_user": "repl_user2:repl_pass2", - "cfg": { - "listen": "0.0.0.0:3301", - "memtx_memory": 100000 - } - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``node_not_registered`` - the specified node is not registered - -.. _orchestrator_api-get_node: - -.. function:: GET /api/v1/registry/node/{node_uuid: optional} - - Return information on the nodes in a cluster. If ``node_uuid`` is passed, - information on this node only is returned. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "uuid-1": { - "user": "user1:pass1", - "hostname": "tnt1.public.i", - "repl_user": "repl_user2:repl_pass2", - "uri": "tnt1.public.i:3301", - "zone_id": 1, - "name": "tnt1", - "cfg": { - "listen": "0.0.0.0:3301", - "memtx_memory": 100000 - }, - "zone": 1 - }, - "uuid-2": { - "user": "user1:pass1", - "hostname": "tnt2.public.i", - "name": "tnt2", - "uri": "tnt2.public.i:3301", - "repl_user": "repl_user1:repl_pass1", - "cfg": { - "listen": "0.0.0.0:3301" - }, - "zone": 1 - } - }, - "status": true - } - - **Potential errors** - - * ``node_not_registered`` - the specified node is not registered - -.. _orchestrator_api-delete_node: - -.. function:: DELETE /api/v1/registry/node/{node_uuid} - - Delete the node if it doesn’t belong to any replica set. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``node_not_registered`` - the specified node is not registered - * ``node_in_use`` - the specified node is in use by a replica set - -.. _orchestrator-router-api: - -Routers API ------------ - -* :ref:`GET /api/v1/routers ` -* :ref:`POST /api/v1/routers ` -* :ref:`DELETE /api/v1/routers/{uuid} ` - -.. _orchestrator_api-get_routers: - -.. function:: GET /api/v1/routers - - Return the list of all nodes that constitute the router. - - **Response** - - .. code-block:: kconfig - - { - "data": [ - "uuid-1" - ], - "status": true, - "error": { - "code": 0, - "message": "ok" - } - } - -.. _orchestrator_api-post_routers: - -.. function:: POST /api/v1/routers - - Assign the router role to the node. - - **Body** - - .. code-block:: kconfig - - { - "uuid": "uuid-1" - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``node_not_registered`` - the specified node is not registered - -.. _orchestrator_api-delete_routers: - -.. function:: DELETE /api/v1/routers/{uuid} - - Release the router role from the node. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - -.. _orchestrator_api-replica_set_cfg: - -Configuring replica sets ------------------------- - -* :ref:`POST /api/v1/replicaset ` -* :ref:`PUT /api/v1/replicaset/ ` -* :ref:`GET /api/v1/replicaset/ ` -* :ref:`DELETE /api/v1/replicaset/ ` -* :ref:`POST /api/v1/replicaset/{replicaset_uuid}/master ` -* :ref:`POST /api/v1/replicaset/{replicaset_uuid}/node ` -* :ref:`DELETE /api/v1/zone/ ` - -.. _orchestrator_api-post_replicaset: - -.. function:: POST /api/v1/replicaset - - Create a replica set containing all the registered nodes. - - **Body** - - .. code-block:: kconfig - - { - "uuid": "optional-uuid", - "replicaset": [ - { - "uuid": "uuid-1", - "master": true - } - ] - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "replicaset_uuid": "cc6568a2-63ca-413d-8e39-704b20adb7ae" - }, - "status": true - } - - **Potential errors** - - * ``replicaset_exists`` – the specified replica set already exists - * ``replicaset_empty`` – the specified replica set doesn’t contain any nodes - * ``node_not_registered`` – the specified node is not registered - * ``node_in_use`` – the specified node is in use by another replica set - -.. _orchestrator_api-put_replicaset: - -.. function:: PUT /api/v1/replicaset/{replicaset_uuid} - - Update the replica set parameters. - - **Body** - - .. code-block:: kconfig - - { - "replicaset": [ - { - "uuid": "uuid-1", - "master": true - }, - { - "uuid": "uuid-2", - "master": false, - "off": true - } - ] - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``replicaset_empty`` – the specified replica set doesn’t contain any nodes - * ``replicaset_not_found`` – the specified replica set is not found - * ``node_not_registered`` – the specified node is not registered - * ``node_in_use`` – the specified node is in use by another replica set - -.. _orchestrator_api-get_replicaset: - -.. function:: GET /api/v1/replicaset/{replicaset_uuid: optional} - - Return information on all the cluster components. If ``replicaset_uuid`` is - passed, information on this replica set only is returned. - - **Body** - - .. code-block:: kconfig - - { - "name": "zone 22" - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "cc6568a2-63ca-413d-8e39-704b20adb7ae": { - "uuid-1": { - "hostname": "tnt1.public.i", - "off": false, - "repl_user": "repl_user2:repl_pass2", - "uri": "tnt1.public.i:3301", - "master": true, - "name": "tnt1", - "user": "user1:pass1", - "zone_id": 1, - "zone": 1 - }, - "uuid-2": { - "hostname": "tnt2.public.i", - "off": true, - "repl_user": "repl_user1:repl_pass1", - "uri": "tnt2.public.i:3301", - "master": false, - "name": "tnt2", - "user": "user1:pass1", - "zone": 1 - } - } - }, - "status": true - } - - **Potential errors** - - * ``replicaset_not_found`` – the specified replica set is not found - -.. _orchestrator_api-delete_replicaset: - -.. function:: DELETE /api/v1/replicaset/{replicaset_uuid} - - Delete a replica set. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``replicaset_not_found`` - the specified replica set is not found - -.. _orchestrator_api-post_master: - -.. function:: POST /api/v1/replicaset/{replicaset_uuid}/master - - Switch the master in the replica set. - - **Body** - - .. code-block:: kconfig - - { - "instance_uuid": "uuid-1", - "hostname_name": "hostname:instance_name" - } - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Potential errors** - - * ``replicaset_not_found`` – the specified replica set is not found - * ``node_not_registered`` – the specified node is not registered - * ``node_not_in_replicaset`` – the specified node is not in the specified replica set - -.. _orchestrator_api-post_replicaset_node: - -.. function:: POST /api/v1/replicaset/{replicaset_uuid}/node - - Add a node to the replica set. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": {}, - "status": true - } - - **Body** - - .. code-block:: kconfig - - { - "instance_uuid": "uuid-1", - "hostname_name": "hostname:instance_name", - "master": false, - "off": false - } - - **Potential errors** - -* ``replicaset_not_found`` – the specified replica set is not found -* ``node_not_registered`` – the specified node is not registered -* ``node_in_use`` – the specified node is in use by another replica set - -.. _orchestrator_api-get_status: - -.. function:: GET /api/v1/replicaset/status - - Return statistics on the cluster. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "data": { - "cluster": { - "routers": [ - { - "zone": 1, - "name": "tnt1", - "repl_user": "repl_user1:repl_pass1", - "hostname": "tnt1.public.i", - "status": null, - "uri": "tnt1.public.i:3301", - "user": "user1:pass1", - "uuid": "uuid-1", - "total_rps": null - } - ], - "storages": [ - { - "hostname": "tnt1.public.i", - "repl_user": "repl_user2:repl_pass2", - "uri": "tnt1.public.i:3301", - "name": "tnt1", - "total_rps": null, - "status": 'online', - "replicas": [ - { - "user": "user1:pass1", - "hostname": "tnt2.public.i", - "replication_info": null, - "repl_user": "repl_user1:repl_pass1", - "uri": "tnt2.public.i:3301", - "uuid": "uuid-2", - "status": 'online', - "name": "tnt2", - "total_rps": null, - "zone": 1 - } - ], - "user": "user1:pass1", - "zone_id": 1, - "uuid": "uuid-1", - "replicaset_uuid": "cc6568a2-63ca-413d-8e39-704b20adb7ae", - "zone": 1 - } - ] - } - }, - "status": true - } - - **Potential errors** - - * ``zone_not_found`` - the specified zone is not found - * ``zone_in_use`` - the specified zone stores at least one node - -.. _orchestrator-setup-config-versions: - -Setting up configuration versions ---------------------------------- - -* :ref:`POST /api/v1/version ` -* :ref:`GET /api/v1/version ` - -.. _orchestrator_api-post_version: - -.. function:: POST /api/v1/version - - Set the configuration version. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": { - "version": 2 - } - } - - **Potential errors** - - * ``cfg_error`` - configuration error - -.. _orchestrator_api-get_version: - -.. function:: GET /api/v1/version - - Return the configuration version. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": { - "version": 2 - } - } - -.. _orchestrator-config-shards: - -Configuring sharding --------------------- - -* :ref:`POST /api/v1/sharding/cfg ` -* :ref:`GET /api/v1/sharding/cfg ` - -.. _orchestrator_api-post_cfg: - -.. function:: POST /api/v1/sharding/cfg - - Add a new sharding configuration. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": {} - } - -.. _orchestrator_api-get_cfg: - -.. function:: GET /api/v1/sharding/cfg - - Return the current sharding configuration. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": {} - } - -.. _orchestrator-reset-cluster-config: - -Resetting cluster configuration -------------------------------- - -* :ref:`POST /api/v1/clean/cfg ` -* :ref:`POST /api/v1/clean/all ` - -.. _orchestrator_api-post_clean_cfg: - -.. function:: POST /api/v1/clean/cfg - - Reset the cluster configuration. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": {} - } - -.. _orchestrator_api-post_clean_all: - -.. function:: POST /api/v1/clean/all - - Reset the cluster configuration and delete information on the cluster nodes - from the ZooKeeper catalogues. - - **Response** - - .. code-block:: kconfig - - { - "error": { - "code": 0, - "message": "ok" - }, - "status": true, - "data": {} - } diff --git a/doc/enterprise/dev.rst b/doc/enterprise/dev.rst deleted file mode 100644 index b1c5a08220..0000000000 --- a/doc/enterprise/dev.rst +++ /dev/null @@ -1,448 +0,0 @@ -.. _enterprise-app-development: - -=============================================================================== -Developer's guide -=============================================================================== - -To develop an application, use the Tarantool Cartridge framework that is -:ref:`installed ` as part of Tarantool Enterprise Edition. - -Here is a summary of the commands you need: - -#. Create a cluster-aware application from the template: - - .. code-block:: bash - - $ tt create cartridge --name -d /path/to - -#. Develop your application: - - .. code-block:: bash - - $ cd /path/to/ - $ ... - -#. Package your application: - - .. code-block:: bash - - $ tt pack [rpm|tgz] /path/to/ - -#. Deploy your application: - - * For ``rpm`` package: - - 1. Upload the package to all servers dedicated to Tarantool. - 2. Install the package: - - .. code-block:: bash - - $ yum install -.rpm - - 3. Launch the application. - - .. code-block:: bash - - $ systemctl start - - * For ``tgz`` archive: - - 1. Upload the archive to all servers dedicated to Tarantool. - 2. Unpack the archive: - - .. code-block:: bash - - $ tar -xzvf -.tar.gz -C /home//apps - - 3. Launch the application - - .. code-block:: bash - - $ tarantool init.lua - -For details and examples, consult the following documentation: - -* a `getting started guide `_ - that walks you through developing and deploying a simple clustered application using - Tarantool Cartridge, -* a :doc:`detailed manual ` - on creating and managing clustered Tarantool applications using - Tarantool Cartridge. - -Further on, this guide focuses on Enterprise-specific developer features available -on top of Tarantool Community Edition with the Tarantool Cartridge framework: - -* :ref:`LDAP authorization in the web interface `, -* :ref:`environment-independent applications `, -* :ref:`sample applications with Enterprise flavors `. - -.. _ldap_auth: - -------------------------------------------------------------------------------- -Implementing LDAP authorization in the web interface -------------------------------------------------------------------------------- - -If you run an LDAP server in your organization, you can connect Tarantool -Enterprise to it and let it handle the authorization. In this case, follow the -:ref:`general recipe ` -where in the first step add the ``ldap`` module to the ``.rockspec`` file -as a dependency and consider implementing the ``check_password`` function -the following way: - -.. code-block:: Lua - :emphasize-lines: 4, 10, 13 - - -- auth.lua - -- Require the LDAP module at the start of the file - local ldap = require('ldap') - ... - -- Add a function to check the credentials - local function check_password(username, password) - - -- Configure the necessary LDAP parameters - local user = string.format("cn=%s,ou=tarantool,dc=glauth,dc=com", username) - - -- Connect to the LDAP server - local ld, err = ldap.open("localhost:3893", user, password) - - -- Return an authentication success or failure - if not ld then - return false - end - return true - end - ... - -.. _enterprise-env-independent-apps: - --------------------------------------------------------------------------------- -Delivering environment-independent applications --------------------------------------------------------------------------------- - -Tarantool Enterprise Edition allows you to build environment-independent applications. - -An environment-independent application is an assembly (in one directory) of: - -* files with Lua code, -* ``tarantool`` executable, -* plugged external modules (if necessary). - -When started by the ``tarantool`` executable, the application provides a -service. - -The modules are Lua rocks installed into a virtual environment (under the -application directory) similar to Python's ``virtualenv`` and Ruby's bundler. - -Such an application has the same structure both in development and -production-ready phases. All the application-related code resides in one place, -ready to be packed and copied over to any server. - -.. _enterprise-app-package: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Packaging applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once custom cluster role(s) are defined and the application is developed, pack -it and all its dependencies (module binaries) together with the ``tarantool`` -executable. - -This will allow you to upload, install, and run your application on any server in -one go. - -To pack the application, say: - -.. code-block:: console - - $ tt pack [rpm|tgz] /path/to/ - -where specify a path to your development environment -- the Git repository -containing your application code, -- and one of the following build options: - -* ``rpm`` to build an RPM package (recommended), or -* ``tgz`` to build a ``tar + gz`` archive - (choose this option only if you do not have root - privileges on servers dedicated for Tarantool Enterprise). - -This will create a package (or compressed archive) named -``--`` (e.g., ``myapp-1.2.1-12.rpm``) -containing your environment-independent application. - -Next, proceed to deploying :ref:`packaged applications ` -(or :ref:`archived ones `) on your servers. - -.. _enterprise-packaged-app: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Deploying packaged applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To deploy your packaged application, do the following on every server dedicated -for Tarantool Enterprise: - -#. Upload the package created in the :ref:`previous step `. - -#. Install: - - .. code-block:: console - - $ yum install -.rpm - -#. Start one or multiple Tarantool instances with the corresponding services - as described below. - - * A single instance: - - .. code-block:: console - - $ systemctl start - - This will start an instantiated ``systemd`` service that will listen to port - ``3301``. - - * Multiple instances on one or multiple servers: - - .. code-block:: console - - $ systemctl start @instance_1 - $ systemctl start @instance_2 - ... - $ systemctl start @instance_ - - where ``@instance_`` is the instantiated service name - for ``systemd`` with an incremental ```` (unique for every - instance) to be added to the ``3300`` port the instance will listen to - (e.g., ``3301``, ``3302``, etc.). - -#. In case it is a cluster-aware application, proceed to - :ref:`deploying the cluster `. - -To stop all services on a server, use the ``systemctl stop`` command and specify -instance names one by one. For example: - -.. code-block:: console - - $ systemctl stop @instance_1 @instance_2 ... @instance_ - -.. _enterprise-archived-app: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Deploying archived applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -While the RPM package places your application to ``/usr/share/tarantool/`` -on your server by default, the ``tar + gz`` archive does not enforce any structure -apart from just the ``/`` directory, so you are responsible for placing -it appropriately. - -.. NOTE:: - - RPM packages are recommended for deployment. Deploy archives only if - you do not have root privileges. - -To place and deploy the application, do the following on every server dedicated -for Tarantool Enterprise: - -#. Upload the archive, decompress, and extract it to the ``/home//apps`` - directory: - - .. code-block:: console - - $ tar -xzvf -.tar.gz -C /home//apps - -#. Start Tarantool instances with the corresponding services. - - To manage instances and configuration, use tools like ``ansible``, - ``systemd``, and ``supervisord``. - -#. In case it is a cluster-aware application, proceed to - :ref:`deploying the cluster `. - -.. _enterprise-code-upgrade: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Upgrading code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All instances in the cluster are to run the same code. This includes all the -components: custom roles, applications, module binaries, ``tarantool``, and -``tt`` (if necessary) executables. - -Pay attention to possible backward incompatibility that any component may -introduce. This will help you choose a scenario for an -:ref:`upgrade in production `. Keep in mind that -you are responsible for code compatibility and handling conflicts should -inconsistencies occur. - -To upgrade any of the components, prepare a new version of the package (archive): - -#. Update the necessary files in your development environment (directory): - - * Your own source code: custom roles and/or applications. - * Module binaries. - * Executables. Replace them with ones from the new bundle. - -#. Increment the version as described in - :ref:`application versioning `. - -#. Repack the updated files as described in :ref:`packaging applications `. - -#. Choose an upgrade scenario as described in the :ref:`Upgrading in production ` - section. - -.. _enterprise-run-app: - -------------------------------------------------------------------------------- -Running sample applications -------------------------------------------------------------------------------- - -The Enterprise distribution package includes sample applications in the -``examples/`` directory that showcase basic Tarantool functionality. - -.. contents:: Sample applications: - :depth: 1 - :local: - -.. _enterprise-pg-write-through-cache: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Write-through cache application for PostgreSQL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The example in ``pg_writethrough_cache/`` shows how Tarantool can cache data -written *through* it to a PostgreSQL database to speed up the reads. - -The sample application requires a deployed PostgreSQL database and the following -rock modules: - -.. code-block:: console - - $ tt rocks install http - $ tt rocks install pg - $ tt rocks install argparse - -Look through the code in the files to get an understanding of what the application -does. - -To run the application for a local PostgreSQL database, say: - -.. code-block:: console - - $ tarantool cachesrv.lua --binary-port 3333 --http-port 8888 --database postgresql://localhost/postgres - -.. _enterprise-ora-write-behind-cache: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Write-behind cache application for Oracle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The example in ``ora-writebehind-cache/`` shows how Tarantool can cache writes -and queue them to an Oracle database to speed up both writes and reads. - -.. _enterprise-ora-write-behind-cache_reqs: - -******************************************************************************* -Application requirements -******************************************************************************* - -The sample application requires: - -* deployed Oracle database; -* Oracle tools: `Instant Client and SQL Plus `_, - both of version 12.2; - - .. NOTE:: - - In case the Oracle Instant Client errors out on ``.so`` files - (Oracle's dynamic libraries), put them to some directory and add it to the - ``LD_LIBRARY_PATH`` environment variable. - - For example: ``export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/`` - -* rock modules listed in the ``rockspec`` file. - -To install the modules, run the following command in the ``examples/ora_writebehind_cache`` -directory: - -.. code-block:: console - - $ tt rocks make oracle_rb_cache-0.1.0-1.rockspec - -If you do not have a deployed Oracle instance at hand, run a dummy in a Docker -container: - -#. In the browser, log in to `Oracle container registry `_, - click **Database**, and accept the Oracle's Enterprise Terms and Restrictions. - -#. In the ``ora-writebehind-cache/`` directory, log in to the repository under - the Oracle account, pull, and run an image using the prepared scripts: - - .. code-block:: console - - $ docker login container-registry.oracle.com - Login: - Password: - Login Succeeded - $ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1 - $ docker run -itd \ - -p 1521:1521 \ - -p 5500:5500 \ - --name oracle \ - -v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \ - -v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \ - -v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \ - container-registry.oracle.com/database/enterprise:12.2.0.1 - -When all is set and done, run the example application. - -.. _enterprise-ora-write-behind-cache_run: - -******************************************************************************* -Running write-behind cache -******************************************************************************* - -To launch the application, run the following in the ``examples/ora_writebehind_cache`` -directory: - -.. code-block:: console - - $ tarantool init.lua - -The application supports the following requests: - -* Get: ``GET http://:/account/id``; -* Add: ``POST http://:/account/`` with the following data: - - .. code-block:: console - - {"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"} - -* Update: ``POST http://:/account/id`` with the same data as in the add request; -* Remove: ``DELETE http://:/account/id`` where ``id`` is an account identifier. - -Look for sample CURL scripts in the ``examples/ora_writebehind_cache/testing`` -directory and check ``README.md`` for more information on implementation. - -.. _enterprise-docker-app: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Hello-world application in Docker -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The example in the ``docker/`` directory contains a hello-world application -that you can pack in a Docker container and run on CentOS 7. - -The ``hello.lua`` file is the entry point and it is very bare-bones, so you -can add your code here. - -#. To build the container, say: - - .. code-block:: console - - $ docker build -t tarantool-enterprise-docker -f Dockerfile ../.. - -#. To run it: - - .. code-block:: console - - $ docker run --rm -t -i tarantool-enterprise-docker diff --git a/doc/enterprise/flight_recorder.rst b/doc/enterprise/flight_recorder.rst deleted file mode 100644 index ce3f6cbac2..0000000000 --- a/doc/enterprise/flight_recorder.rst +++ /dev/null @@ -1,218 +0,0 @@ -.. _enterprise-flight-recorder: - -Flight recorder -=============== - -The flight recorder available in the Enterprise Edition is an event collection tool that -gathers various information about a working Tarantool instance, such as: - -* logs - -* metrics - -* requests and responses - -This information helps you investigate incidents related -to :ref:`crashing ` a Tarantool instance. - - -.. _enable: - -Enabling the flight recorder ----------------------------- - -The flight recorder is disabled by default and can be enabled and configured for -a specific Tarantool instance. -To enable the flight recorder, set the ``flightrec_enabled`` -:doc:`configuration option ` to ``true``. -This option is :ref:`dynamic ` and can be changed at runtime by calling ``box.cfg{}``: - -.. code-block:: lua - - box.cfg{ flightrec_enabled = true } - -After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. -This file is stored in the :ref:`memtx_dir ` directory. -If the instance crashes and reboots, Tarantool rotates the flight recording: -``current.ttfr`` is renamed to ``.ttfr`` (for example, ``20230411T050721.ttfr``) -and the new ``current.ttfr`` file is created for collecting data. -In the case of correct shutdown (for example, using ``os.exit()``), -Tarantool continues writing to the existing ``current.ttfr`` file after restart. - -.. NOTE:: - - Note that old flight recordings should be removed manually. - - - -.. _config: - -Configuration -------------- - -This section describes options related to the flight recorder configuration. -Note that all options are :ref:`dynamic ` and can be changed at runtime. - -.. TODO not implemented yet - .. _config-directory: - - Flight recording directory - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. _cfg_flightrec_dir: - - .. confval:: flightrec_dir - - Specifies the directory used to store flight recordings (``*.ttfr`` files). - - | Type: string - | Default: :ref:`memtx_dir ` - | Environment variable: TT_FLIGHTREC_DIR - - - -.. _config-logs: - -Logs -~~~~ - -This section describes the flight recorder settings related to :ref:`logging `. -For example, you can configure a more detailed logging level in the flight recorder for deeper analysis. - -* :ref:`flightrec_logs_size ` -* :ref:`flightrec_logs_max_msg_size ` -* :ref:`flightrec_logs_log_level ` - -.. _cfg_flightrec_logs_size: - -.. confval:: flightrec_logs_size - - Specifies the size (in bytes) of the log storage. - You can set this option to ``0`` to disable the log storage. - - | Type: integer - | Default: 10485760 - | Environment variable: TT_FLIGHTREC_LOGS_SIZE - - -.. _cfg_flightrec_logs_max_msg_size: - -.. confval:: flightrec_logs_max_msg_size - - Specifies the maximum size (in bytes) of the log message. - The log message is truncated if its size exceeds this limit. - - | Type: integer - | Default: 4096 - | Maximum: 16384 - | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE - - -.. _cfg_flightrec_logs_log_level: - -.. confval:: flightrec_logs_log_level - - Specifies the level of detail the log has. - You can learn more about log levels from the :ref:`log_level ` - option description. - Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``. - - | Type: integer - | Default: 6 - | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL - - -.. _config-metrics: - -Metrics -~~~~~~~ - -This section describes the flight recorder settings related to collecting -:ref:`metrics `. - -* :ref:`flightrec_metrics_period ` -* :ref:`flightrec_metrics_interval ` - -.. _cfg_flightrec_metrics_period: - -.. confval:: flightrec_metrics_period - - Specifies the time period (in seconds) that defines how long metrics are stored from the moment of dump. - So, this value defines how much historical metrics data is collected up to the moment of crash. - The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `. - - | Type: integer - | Default: 180 - | Environment variable: TT_FLIGHTREC_METRICS_PERIOD - - -.. _cfg_flightrec_metrics_interval: - -.. confval:: flightrec_metrics_interval - - Specifies the time interval (in seconds) that defines the frequency of dumping metrics. - This value shouldn't exceed :ref:`flightrec_metrics_period `. - - | Type: number - | Default: 1.0 - | Minimum: 0.001 - | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL - -.. NOTE:: - - Given that the average size of a metrics entry is 2 kB, - you can estimate the size of the metrics storage as follows: - - .. code-block:: console - - (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB - - - -.. _config-requests: - -Requests -~~~~~~~~ - -This section lists the flight recorder settings related to -storing the :ref:`request and response ` data. - -* :ref:`flightrec_requests_size ` -* :ref:`flightrec_requests_max_req_size ` -* :ref:`flightrec_requests_max_res_size ` - -.. _cfg_flightrec_requests_size: - -.. confval:: flightrec_requests_size - - Specifies the size (in bytes) of storage for the request and response data. - You can set this parameter to ``0`` to disable a storage of requests and responses. - - | Type: integer - | Default: 10485760 - | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE - - - -.. _cfg_flightrec_requests_max_req_size: - -.. confval:: flightrec_requests_max_req_size - - Specifies the maximum size (in bytes) of a request entry. - A request entry is truncated if this size is exceeded. - - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE - - -.. _cfg_flightrec_requests_max_res_size: - -.. confval:: flightrec_requests_max_res_size - - Specifies the maximum size (in bytes) of a response entry. - A response entry is truncated if this size is exceeded. - - | Type: integer - | Default: 16384 - | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE diff --git a/doc/enterprise/images/hidden_spaces.png b/doc/enterprise/images/hidden_spaces.png deleted file mode 100644 index 587244358a..0000000000 Binary files a/doc/enterprise/images/hidden_spaces.png and /dev/null differ diff --git a/doc/enterprise/images/space_contents.png b/doc/enterprise/images/space_contents.png deleted file mode 100644 index b086377f26..0000000000 Binary files a/doc/enterprise/images/space_contents.png and /dev/null differ diff --git a/doc/enterprise/images/space_explr_tab.png b/doc/enterprise/images/space_explr_tab.png deleted file mode 100644 index dadcf14200..0000000000 Binary files a/doc/enterprise/images/space_explr_tab.png and /dev/null differ diff --git a/doc/enterprise/images/space_search.png b/doc/enterprise/images/space_search.png deleted file mode 100644 index a6c719572b..0000000000 Binary files a/doc/enterprise/images/space_search.png and /dev/null differ diff --git a/doc/enterprise/images/spaces_with_data.png b/doc/enterprise/images/spaces_with_data.png deleted file mode 100644 index 22f836070c..0000000000 Binary files a/doc/enterprise/images/spaces_with_data.png and /dev/null differ diff --git a/doc/enterprise/index.rst b/doc/enterprise/index.rst deleted file mode 100644 index b301c6cf4e..0000000000 --- a/doc/enterprise/index.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _tarantool_enterprise: - -Tarantool Enterprise Edition -============================ - -.. ifconfig:: language == 'en' - - .. container:: documentation-main-page-description - - This section describes the Enterprise Edition of Tarantool software -- a Lua - application server integrated with a DBMS for deploying fault-tolerant - distributed data storages. - - The Enterprise Edition provides an `extended feature set `__ for developing - and managing clustered Tarantool applications, for example: - - * :ref:`Static package ` - for standalone Linux systems. - * Tarantool :ref:`bindings to OpenLDAP `. - * Security :ref:`audit log `. - * Enterprise :ref:`database connectivity `: - Oracle and any ODBC-supported DBMS - (for example, MySQL, Microsoft SQL Server). - * SSL support for :ref:`traffic encryption `. - * :doc:`Tuple compression `. - * :doc:`Non-blocking DDL `. - -.. ifconfig:: language == 'ru' - - .. container:: documentation-main-page-description - - Данное руководство посвящено Enterprise-версии продукта Tarantool, - который сочетает в себе сервер приложений Lua и отказоустойчивую - распределенную СУБД. - - Enterprise-версия предлагает `дополнительные возможности `__ по - разработке и эксплуатации кластерных приложений, например: - - * :ref:`Статическая сборка ` - для автономных Linux-систем. - * :ref:`Модуль интеграции с OpenLDAP `. - * :ref:`Журнал аудита безопасности `. - * Подключения к :ref:`корпоративным базам данных `: - Oracle и любым СУБД с интерфейсом ODBC (MySQL, Microsoft SQL Server и т.д.). - (например, MySQL, Microsoft SQL Server). - * :ref:`Шифрование трафика ` с помощью SSL. - * :doc:`Сжатие кортежей `. - * :doc:`Смена схемы данных в фоновом режиме `. - - -.. toctree:: - :hidden: - - changelog - setup - dev - admin - security - audit - cartridge-auth - tuple_compression - wal_extensions - read_views - flight_recorder - audit_log - space_upgrade - migration - system_metrics - deprecated - rocksref diff --git a/doc/enterprise/migration.rst b/doc/enterprise/migration.rst deleted file mode 100644 index 71af6ddddf..0000000000 --- a/doc/enterprise/migration.rst +++ /dev/null @@ -1,60 +0,0 @@ -Migration from Tarantool Cartridge -================================== - -If your company uses a service based on Tarantool Community Edition and -Tarantool Cartridge, follow the steps below to update these components to -Tarantool Enterprise Edition. - -As a reference, the instructions below use a template service created with -:ref:`tt`, the Tarantool CLI utility. - -Service build pipeline ----------------------- - -Get access to the source code and build pipeline of your service. Here is an -example of what the service build pipeline might look like for CentOS/RHEL 7: - -.. code-block:: bash - - curl -L https://tarantool.io/release/2/installer.sh | bash - yum -y install tarantool tarantool-devel tt git gcc gcc-с++ cmake - tt pack rpm - - -Update the pipeline -------------------- - -In the installation section of your pipeline, replace open-source ``tarantool`` -packages with Tarantool Enterprise SDK: - -.. code-block:: bash - - curl -L \ - https://${TOKEN}@download.tarantool.io/enterprise/release/${OS}/${ARCH}/${VERSION}/tarantool-enterprise-sdk-${VERSION_OS_ARCH_POSTFIX}.tar.gz \ - > sdk.tar.gz - - # for example, the URL for the Linux build of Tarantool 2.10.4 for the x86_64 platform will be: - # https://${TOKEN}@download.tarantool.io/enterprise/release/linux/x86_64/2.10/tarantool-enterprise-sdk-gc64-2.10.4-0-r523.linux.x86_64.tar.gz - - tar -xvf sdk.tar.gz - source tarantool-enterprise/env.sh - tt pack rpm - -Now the pipeline will produce a new service artifact, which includes -Tarantool Enterprise Edition. - -Update the service ------------------- - -Update your service to the new version like you usually update Tarantool in -your organization. You don't have to interrupt access to the service. -To learn how to do it with ``ansible-cartridge``, -`check this example `__. - - -That's it! ----------- - -You can now use Tarantool Enterprise Edition's features in your installation. -For example, to enable the audit log, -:ref:`set up the audit_log parameter in your node configuration `. diff --git a/doc/enterprise/read_views/c_api.rst b/doc/enterprise/read_views/c_api.rst deleted file mode 100644 index a21eb2729a..0000000000 --- a/doc/enterprise/read_views/c_api.rst +++ /dev/null @@ -1,274 +0,0 @@ -.. _read_views_c_api: - -Read views: C API -================= - -This topic describes the C API for working with :ref:`read views `. -The C API is MT-safe and provides the ability to use a read view from any thread, -not only from the :ref:`main (TX) thread `. - -The C API has the following specifics: - -* The :ref:`space.upgrade ` function is not applied to retrieved tuples even if a space upgrade is in progress. - -* Tuples stored in :ref:`compressed spaces ` are not decompressed - they are returned as :ref:`raw MessagePack ` (``MP_EXT/MP_COMPRESSION``). - -.. note:: - - You can learn how to call C code using stored procedures in the - :ref:`C tutorial`. - - -.. _data_types: - -Data types ----------- - -The opaque data types below represent raw read views and an iterator over data in a raw read view. -Note that there is no special data type for tuples retrieved from a read view. -Tuples are returned as raw MessagePack data (``const char *``). - -.. c:type:: box_raw_read_view box_raw_read_view_t - - A raw database read view. - -.. c:type:: box_raw_read_view_space box_raw_read_view_space_t - - A space in a raw read view. - -.. c:type:: box_raw_read_view_index box_raw_read_view_index_t - - An index in a raw read view. - -.. c:type:: box_raw_read_view_iterator box_raw_read_view_iterator_t - - An iterator over data in a raw read view. - - - -.. _creating_destroying_read_views: - -Creating and destroying read views ----------------------------------- - -To create or destroy a read view, use the functions below. - -.. _box_raw_read_view_new: - -.. c:function:: box_raw_read_view_t * box_raw_read_view_new(const char *name) - - Open a raw read view with the specified name and get a pointer to this read view. - In the case of error, returns ``NULL`` and sets :ref:`box_error_last()`. - This function may be called from the main (TX) thread only. - - :param const char *name: (optional) a read view name; if ``name`` is not specified, a read view name is set to ``unknown`` - - :return: a pointer to a read view - - -.. _box_raw_read_view_delete: - -.. c:function:: void box_raw_read_view_delete(box_raw_read_view_t *rv) - - Close a raw read view and release all resources associated with it. - This function may be called from the main (TX) thread only. - - :param box_raw_read_view_t *rv: a pointer to a read view - - -.. NOTE:: - - Read views created using ``box_raw_read_view_new`` are displayed in :ref:`box.read_view.list() ` along with read views :ref:`created in Lua `. - - -.. _spaces_and_indexes: - -Spaces and indexes ------------------- - -To fetch data from a read view, you need to specify an index to fetch the data from. -The following functions are available for looking up spaces and indexes in a read view object. - - -.. _box_raw_read_view_space_by_id: - -.. c:function:: box_raw_read_view_space_t * box_raw_read_view_space_by_id(const box_raw_read_view_t *rv, uint32_t space_id) - - Find a space by ID in a raw read view. - If not found, returns ``NULL`` and sets :ref:`box_error_last()`. - - :param const box_raw_read_view_t *rv: a pointer to a read view - :param uint32_t space_id: a space identifier - - :return: a pointer to a space - - -.. _box_raw_read_view_space_by_name: - -.. c:function:: box_raw_read_view_space_t * box_raw_read_view_space_by_name(const box_raw_read_view_t *rv, const char *space_name, uint32_t space_name_len) - - Find a space by name in a raw read view. - If not found, returns ``NULL`` and sets :ref:`box_error_last()`. - - :param const box_raw_read_view_t *rv: a pointer to a read view - :param const char *space_name: a space name - :param uint32_t space_name_len: a space name length - - :return: a pointer to a space - - -.. _box_raw_read_view_index_by_id: - -.. c:function:: box_raw_read_view_index_t * box_raw_read_view_index_by_id(const box_raw_read_view_space_t *space, uint32_t index_id) - - Find an index by ID in a read view's space. - If not found, returns ``NULL`` and sets :ref:`box_error_last()`. - - :param const box_raw_read_view_space_t *space: a pointer to a read view's space - :param uint32_t space_id: a space identifier - - :return: a pointer to an index - - -.. _box_raw_read_view_index_by_name: - -.. c:function:: box_raw_read_view_index_t * box_raw_read_view_index_by_name(const box_raw_read_view_space_t *space, const char *index_name, uint32_t index_name_len) - - Find an index by name in a read view's space. - If not found, returns ``NULL`` and sets :ref:`box_error_last()`. - - :param const box_raw_read_view_space_t *space: a pointer to a space - :param const char *index_name: an index name - :param uint32_t index_name_len: an index name length - - :return: a pointer to an index - - - -.. _iteration_and_lookup: - -Iteration and lookup --------------------- - -The functions below provide the ability to look up a tuple by the key or create an iterator over a read view index. - -.. NOTE:: - - Methods of the read view iterator are safe to call from any thread, but they may be used in one thread at the same time. This means that an iterator should be thread-local. - - -.. _box_raw_read_view_get: - -.. c:function:: int box_raw_read_view_get(const box_raw_read_view_index_t *index, const char *key, const char *key_end, const char **data, uint32_t *size) - - Look up a tuple in a read view's index. - If found, the ``data`` and ``size`` out arguments return a pointer to and the size of tuple data. - If not found, ``*data`` is set to ``NULL`` and ``*size`` is set to ``0``. - - :param const box_raw_read_view_index_t *index: a pointer to a read view's index - :param const char *key: a pointer to the first byte of the MsgPack data that represents the search key - :param const char *key_end: a pointer to the byte following the last byte of the MsgPack data that represents the search key - :param const char **data: a pointer to the tuple data - :param uint32_t *size: the size of tuple data - - :return: ``0`` on success; in the case of error, returns ``-1`` and sets :ref:`box_error_last()` - - - - -.. _box_raw_read_view_iterator_create: - -.. c:function:: int box_raw_read_view_iterator_create(box_raw_read_view_iterator_t *it, const box_raw_read_view_index_t *index, int type, const char *key, const char *key_end) - - Create an iterator over a raw read view index. - The initialized iterator object returned by this function remains valid and may be safely used until it's destroyed or the read view is closed. - When the iterator object is no longer needed, it should be destroyed using - :ref:`box_raw_read_view_iterator_destroy() `. - - :param box_raw_read_view_iterator_t *it: an iterator over a raw read view index - :param const box_raw_read_view_index_t *index: a pointer to a read view index - :param int type: an iteration direction represented by the :ref:`iterator_type ` - :param const char *key: a pointer to the first byte of the MsgPack data that represents the search key - :param const char *key_end: a pointer to the byte following the last byte of the MsgPack data that represents the search key - - :return: ``0`` on success; in the case of error, returns ``-1`` and sets :ref:`box_error_last()` - - - -.. _box_raw_read_view_iterator_next: - -.. c:function:: int box_raw_read_view_iterator_next(box_raw_read_view_iterator_t *it, const char **data, uint32_t *size) - - Retrieve the current tuple and advance the given iterator over a raw read view index. - The pointer to and the size of tuple data are returned in the ``data`` and the ``size`` out arguments. - The data returned by this function remains valid and may be safely used until the read view is closed. - - :param box_raw_read_view_iterator_t *it: an iterator over a read view index - :param const char **data: a pointer to the tuple data; at the end of iteration, ``*data`` is set to ``NULL`` - :param uint32_t *size: the size of tuple data; at the end of iteration, ``*size`` is set to ``0`` - - :return: ``0`` on success; in the case of error, returns ``-1`` and sets :ref:`box_error_last()` - - - -.. _box_raw_read_view_iterator_destroy: - -.. c:function:: void box_raw_read_view_iterator_destroy(box_raw_read_view_iterator_t *it) - - Destroy an iterator over a raw read view index. - The iterator object should not be used after calling this function, - but the data returned by the iterator may be safely dereferenced until the read view is closed. - - :param box_raw_read_view_iterator_t *it: an iterator over a read view index - - - - - -.. _space_format: - -Space format ------------- - -A space object's methods below provide the ability to get names and types of space fields. - - -.. _box_raw_read_view_space_field_count: - -.. c:function:: uint32_t box_raw_read_view_space_field_count(const box_raw_read_view_space_t *space) - - Get the number of fields defined in the format of a read view space. - - :param const box_raw_read_view_space_t *space: a pointer to a read view space - - :return: the number of fields - - - -.. _box_raw_read_view_space_field_name: - -.. c:function:: const char * box_raw_read_view_space_field_name(const box_raw_read_view_space_t *space, uint32_t field_no) - - Get the name of a field defined in the format of a read view space. - If the field number is greater than the total number of fields defined in the format, ``NULL`` is returned. - The string returned by this function is guaranteed to remain valid until the read view is closed. - - :param const box_raw_read_view_space_t *space: a pointer to a read view space - :param uint32_t field_no: the field number (starts with ``0``) - - :return: the name of a field - - - -.. _box_raw_read_view_space_field_type: - -.. c:function:: const char * box_raw_read_view_space_field_type(const box_raw_read_view_space_t *space, uint32_t field_no) - - Get the type of a field defined in the format of a read view space. - If the field number is greater than the total number of fields defined in the format, ``NULL`` is returned. - The string returned by this function is guaranteed to remain valid until the read view is closed. - - :param const box_raw_read_view_space_t *space: a pointer to a read view space - :param uint32_t field_no: the field number (starts with ``0``) - - :return: the type of a field diff --git a/doc/enterprise/read_views/lua_api.rst b/doc/enterprise/read_views/lua_api.rst deleted file mode 100644 index 81b3daa958..0000000000 --- a/doc/enterprise/read_views/lua_api.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _read_views_lua_api: - -Read views: Lua API -=================== - -This topic describes the Lua API for working with :ref:`read views `. - -.. _box-read_view-open: - -.. function:: box.read_view:open({opts}) - - Create a :ref:`new read view `. - - :param table opts: (optional) configurations options for a read view. - For example, the ``name`` option specifies a read view name. - If ``name`` is not specified, a read view name is set to ``unknown``. - - :return: a created read view object - :rtype: read_view_object - - **Example:** - - .. code-block:: tarantoolsession - - tarantool> read_view1 = box.read_view.open({name = 'read_view1'}) - - - -.. class:: read_view_object - - An object that represents a :ref:`read view `. - - .. _read_view_object-info: - - .. method:: read_view_object:info() - - Get information about a read view such as a name, status, or ID. - All the available fields are listed below in the object options. - - :return: information about a read view - :rtype: table - - .. _read_view_object-close: - - .. method:: read_view_object:close() - - Close a read view. - After the read view is closed, its :ref:`status ` is set to ``closed``. - On an attempt to use it, an error is raised. - - .. _read_view_object-status: - - .. data:: status - - A read view status. - The possible values are ``open`` and ``closed``. - - :rtype: string - - .. _read_view_object-id: - - .. data:: id - - A unique numeric identifier of a read view. - - :rtype: number - - .. _read_view_object-name: - - .. data:: name - - A read view name. - You can specify a read view name in the :ref:`box.read_view.open() ` arguments. - - :rtype: string - - .. _read_view_object-is_system: - - .. data:: is_system - - Determine whether a read view is system. - For example, system read views can be created to make a :ref:`checkpoint ` - or join a new :ref:`replica `. - - :rtype: boolean - - .. _read_view_object-timestamp: - - .. data:: timestamp - - The :ref:`fiber.clock() ` value at the moment of opening a read view. - - :rtype: number - - .. _read_view_object-vclock: - - .. data:: vclock - - The :ref:`box.info.vclock ` value at the moment of opening a read view. - - :rtype: table - - .. _read_view_object-signature: - - .. data:: signature - - The :ref:`box.info.signature ` value at the moment of opening a read view. - - :rtype: number - - .. _read_view_object-space: - - .. data:: space - - Get access to database spaces included in a read view. - You can use this field to :ref:`query space data `. - - :rtype: space object diff --git a/doc/enterprise/rocksref.rst b/doc/enterprise/rocksref.rst deleted file mode 100644 index e85f1f79f8..0000000000 --- a/doc/enterprise/rocksref.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. _enterprise-rocks: - -=============================================================================== -Modules -=============================================================================== - -This section covers open and closed source Lua modules for Tarantool Enterprise Edition -included in the distribution as an offline rocks repository. - -------------------------------------------------------------------------------- -Open source modules -------------------------------------------------------------------------------- - -* `avro-schema `_ - is an assembly of `Apache Avro `_ - schema tools; -* :doc:`cartridge ` - is a high-level cluster management interface that contains - several modules: - - * ``rpc`` implements remote procedure calls between cluster instances and - allows roles running on some instances to interact with other roles on - other instances. - * ``service-registry`` implements inter-role interaction and allows different - roles to interact with each other in the scope of one instance. - * ``confapplier`` implements cluster-wide configuration validation and - application via a two-phase commit. - * ``auth`` manages authentication. - * ``pool`` reuses Tarantool's ``net.box`` connections. - * ``admin`` implements administration functions. - -* :doc:`cartridge-cli ` - is the command-line interface for the ``cartridge`` module. - - .. important:: - - ``cartridge-cli`` is deprecated in favor of the :ref:`tt CLI utility `. - -* :ref:`checks ` - is a type checker of functional arguments. This library that declares - a ``checks()`` function and ``checkers`` table that allow to check the - parameters passed to a Lua function in a fast and unobtrusive way. -* `http `_ is an - on-board HTTP-server, which comes in addition to Tarantool's out-of-the-box - HTTP client, and must be installed as described in the - :ref:`installation section `. -* `icu-date `_ - is a date-and-time formatting library for Tarantool - based on International Components for Unicode; -* `kafka `_ - is a full-featured high-performance ``kafka`` library for Tarantool - based on ``librdkafka``; -* `luacheck `_ is a static analyzer and - linter for Lua, preconfigured for Tarantool. -* `luarapidxml `_ - is a fast XML parser. -* `luatest `_ is - a Tarantool test framework written in Lua. -* :ref:`membership ` - builds a mesh from multiple Tarantool instances based on gossip protocol. - The mesh monitors itself, helps members discover everyone else in the group - and get notified about their status changes with low latency. It is built - upon the ideas from Consul or, more precisely, the SWIM algorithm. -* :ref:`metrics ` is a collection - of useful monitoring metrics. -* `tracing `_ - is a module for debugging performance issues. -* :ref:`vshard ` - is an automatic sharding system that enables horizontal scaling for Tarantool - DBMS instances. - -------------------------------------------------------------------------------- -Closed source modules -------------------------------------------------------------------------------- - -* :doc:`ldap ` - allows you to authenticate in a LDAP server and perform searches. -* :doc:`odbc ` - is an ODBC connector for Tarantool based on unixODBC. -* :doc:`oracle ` - is an Oracle connector for Lua applications through which they can send and - receive data to and from Oracle databases. - The advantage of the Tarantool-Oracle integration is that anyone can handle all - the tasks with Oracle DBMSs (control, manipulation, storage, access) with the - same high-level language (Lua) and with minimal delay. -* :doc:`task ` - is a module for managing background tasks in a Tarantool cluster. -* :doc:`space-explorer ` - is a module for exploring Tarantool spaces in ``cartridge``. - -.. _enterprise-rocks-install: - -------------------------------------------------------------------------------- -Installing and using modules -------------------------------------------------------------------------------- - -To use a module, install the following: - -#. All the necessary third-party software packages (if any). See the - module's prerequisites for the list. - -#. The module itself on every Tarantool instance: - - .. code-block:: console - - $ tt rocks install MODULE_NAME [MODULE_VERSION] - -See the :ref:`tt rocks reference ` to learn more about -managing Lua modules. diff --git a/doc/enterprise/security.rst b/doc/enterprise/security.rst deleted file mode 100644 index c86f85daf1..0000000000 --- a/doc/enterprise/security.rst +++ /dev/null @@ -1,741 +0,0 @@ -.. _enterprise-security: - -Security hardening guide -======================== - -This guide explains how to enhance security in your Tarantool Enterprise Edition's -cluster using built-in features and provides general recommendations on security -hardening. -If you need to perform a security audit of a Tarantool Enterprise cluster, -refer to the :doc:`security checklist `. - -Tarantool Enterprise Edition does not provide a dedicated API for security control. All -the necessary configurations can be done via an administrative console or -initialization code. - -Tarantool Enterprise Edition has the following built-in security features: - -* :ref:`authentication ` -* :ref:`access control ` -* :ref:`audit log ` -* :ref:`traffic encryption ` - - -.. _enterprise-authentication: - -Authentication --------------- - -Tarantool Enterprise Edition supports password-based authentication and allows for two -types of connections: - -* Via an :doc:`administrative console `. -* Over a binary port for read and write operations and procedure invocation. - -For more information on authentication and connection types, see the -:doc:`Security ` section of the Tarantool manual. - -In addition, Tarantool provides the following functionality: - -* :ref:`Sessions ` - -- states which associate connections with users and make Tarantool API available - to them after authentication. -* Authentication :ref:`triggers `, - which execute actions on authentication events. -* Third-party (external) authentication protocols and services such as LDAP or - Active Directory -- supported in the web interface, but unavailable - on the binary-protocol level. - -.. _enterprise-access-control: - -Access control --------------- - -Tarantool Enterprise Edition provides the means for administrators to prevent -unauthorized access to the database and to certain functions. - -Tarantool recognizes: - -* different users (guests and administrators) -* privileges associated with users -* roles (containers for privileges) granted to users - -The following system spaces are used to store users and privileges: - -* The ``_user`` space to store usernames and hashed passwords for authentication. -* The ``_priv`` space to store privileges for access control. - -For more information, see the -:ref:`Access control ` section. - -Users who create **objects** (spaces, indexes, users, roles, sequences, and -functions) in the database become their **owners** and automatically acquire -privileges for what they create. For more information, see the -:ref:`Owners and privileges ` section. - - -.. _enterprise-auth-restrictions: - -Authentication restrictions -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tarantool Enterprise Edition provides the ability to apply additional restrictions for user authentication. -For example, you can specify the minimum time between authentication attempts -or disable access for guest users. - -The following :doc:`configuration options ` are available: - -* :ref:`auth_delay ` -* :ref:`disable_guest ` - - -.. _cfg_auth_delay: - -.. confval:: auth_delay - - Specifies a period of time (in seconds) that a specific user should wait - for the next attempt after failed authentication. - - With the configuration below, Tarantool refuses the authentication attempt if the previous - attempt was less than 5 seconds ago. - - .. code-block:: lua - - box.cfg{ auth_delay = 5 } - - - | Since version: 2.11 - | Type: number - | Default: 0 - | Environment variable: TT_AUTH_DELAY - | Dynamic: **yes** - - -.. _cfg_disable_guest: - -.. confval:: disable_guest - - If **true**, disables access over remote connections - from unauthenticated or :ref:`guest access ` users. - This option affects both - :doc:`net.box ` and - :ref:`replication ` connections. - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_DISABLE_GUEST - | Dynamic: **yes** - - - -.. _enterprise-password-policy: - -Password policy -~~~~~~~~~~~~~~~ - -A password policy allows you to improve database security by enforcing the use -of strong passwords, setting up a maximum password age, and so on. -When you create a new user with -:doc:`box.schema.user.create ` -or update the password of an existing user with -:doc:`box.schema.user.passwd `, -the password is checked against the configured password policy settings. - -The following :doc:`configuration options ` are available: - -* :ref:`password_min_length ` -* :ref:`password_enforce_uppercase ` -* :ref:`password_enforce_lowercase ` -* :ref:`password_enforce_digits ` -* :ref:`password_enforce_specialchars ` -* :ref:`password_lifetime_days ` -* :ref:`password_history_length ` - -.. _cfg_password_min_length: - -.. confval:: password_min_length - - Specifies the minimum number of characters for a password. - - The following example shows how to set the minimum password length to 10. - - .. code-block:: lua - - box.cfg{ password_min_length = 10 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_MIN_LENGTH - | Dynamic: **yes** - - -.. _cfg_password_enforce_uppercase: - -.. confval:: password_enforce_uppercase - - If **true**, a password should contain uppercase letters (A-Z). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE - | Dynamic: **yes** - - -.. _cfg_password_enforce_lowercase: - -.. confval:: password_enforce_lowercase - - If **true**, a password should contain lowercase letters (a-z). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE - | Dynamic: **yes** - - -.. _cfg_password_enforce_digits: - -.. confval:: password_enforce_digits - - If **true**, a password should contain digits (0-9). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_DIGITS - | Dynamic: **yes** - - -.. _cfg_password_enforce_specialchars: - -.. confval:: password_enforce_specialchars - - If **true**, a password should contain at least one special character (such as ``&|?!@$``). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS - | Dynamic: **yes** - - -.. _cfg_password_lifetime_days: - -.. confval:: password_lifetime_days - - Specifies the maximum period of time (in days) a user can use the same password. - When this period ends, a user gets the "Password expired" error on a login attempt. - To restore access for such users, use :doc:`box.schema.user.passwd `. - - .. note:: - - The default 0 value means that a password never expires. - - The example below shows how to set a maximum password age to 365 days. - - .. code-block:: lua - - box.cfg{ password_lifetime_days = 365 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_LIFETIME_DAYS - | Dynamic: **yes** - - -.. _cfg_password_history_length: - -.. confval:: password_history_length - - Specifies the number of unique new user passwords before an old password can be reused. - - In the example below, a new password should differ from the last three passwords. - - .. code-block:: lua - - box.cfg{ password_history_length = 3 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_HISTORY_LENGTH - | Dynamic: **yes** - - .. note:: - Tarantool uses the ``auth_history`` field in the - :doc:`box.space._user ` - system space to store user passwords. - - - - -.. _enterprise-authentication-protocol: - -Authentication protocol -~~~~~~~~~~~~~~~~~~~~~~~ - -By default, Tarantool uses the -`CHAP `_ -protocol to authenticate users and applies ``SHA-1`` hashing to -:ref:`passwords `. -Note that CHAP stores password hashes in the ``_user`` space unsalted. -If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table `_. - -In the Enterprise Edition, you can enable -`PAP `_ authentication -with the ``SHA256`` hashing algorithm. -For PAP, a password is salted with a user-unique salt before saving it in the database, -which keeps the database protected from cracking using a rainbow table. - -To enable PAP, specify the ``box.cfg.auth_type`` option as follows: - -.. code-block:: lua - - box.cfg{ auth_type = 'pap-sha256' } - -| Since version: 2.11 -| Type: string -| Default value: 'chap-sha1' -| Possible values: 'chap-sha1', 'pap-sha256' -| Environment variable: TT_AUTH_TYPE -| Dynamic: **yes** - -For new users, the :doc:`box.schema.user.create ` method -will generate authentication data using ``PAP-SHA256``. -For existing users, you need to reset a password using -:doc:`box.schema.user.passwd ` -to use the new authentication protocol. - -.. warning:: - - Given that ``PAP`` transmits a password as plain text, - Tarantool requires configuring :ref:`SSL/TLS ` - for a connection. - -The examples below show how to specify the authentication protocol on the client side: - -* For :doc:`net.box `, you can - specify the authentication protocol using the ``auth_type`` URI parameter or - the corresponding connection option: - - .. code-block:: lua - - -- URI parameters - conn = require('net.box').connect( - 'username:password@localhost:3301?auth_type=pap-sha256') - - -- URI parameters table - conn = require('net.box').connect({ - uri = 'username:password@localhost:3301', - params = {auth_type = 'pap-sha256'}, - }) - - -- Connection options - conn = require('net.box').connect('localhost:3301', { - user = 'username', - password = 'password', - auth_type = 'pap-sha256', - }) - -* For :ref:`replication configuration `, - the authentication protocol can be specified in URI parameters: - - .. code-block:: lua - - -- URI parameters - box.cfg{ - replication = { - 'replicator:password@localhost:3301?auth_type=pap-sha256', - }, - } - - -- URI parameters table - box.cfg{ - replication = { - { - uri = 'replicator:password@localhost:3301', - params = {auth_type = 'pap-sha256'}, - }, - }, - } - -If the authentication protocol isn't specified explicitly on the client side, -the client uses the protocol configured on the server via ``box.cfg.auth_type``. - - - - -.. _enterprise-logging: - -Audit log ---------- - -Tarantool Enterprise Edition has a built-in audit log that records events such as: - -* authentication successes and failures -* connection closures -* creation, removal, enabling, and disabling of users -* changes of passwords, privileges, and roles -* denials of access to database objects - -The audit log contains: - -* timestamps -* usernames of users who performed actions -* event types (e.g. ``user_create``, ``user_enable``, ``disconnect``, etc) -* descriptions - -You can configure the following audit log parameters: - -* ``audit_log = `` which is similar to the - :ref:`log ` - parameter. This parameter tells Tarantool to record audit events to a specific file. -* ``audit_nonblock`` which is similar to the - :ref:`log_nonblock ` - parameter. - -For more information on logging, see the following: - -* the :doc:`Logs ` section -* the :ref:`Logging ` section in the configuration reference -* the :ref:`Tarantool audit module ` topic - -Access permissions to audit log files can be set up as to any other Unix file -system object -- via ``chmod``. - -.. _enterprise-iproto-encryption: - -Traffic encryption ------------------- - -Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over :ref:`binary connections `, -that is, between Tarantool instances in a cluster or connecting to an instance via connectors using :doc:`net.box `. - -Tarantool uses the OpenSSL library that is included in the delivery package. -Please note that SSL connections use only TLSv1.2. - -.. _enterprise-iproto-encryption-config: - -Configuration -~~~~~~~~~~~~~ - -To configure traffic encryption, you need to set the special :ref:`URI parameters ` for a particular connection. -The parameters can be set for the following ``box.cfg`` options and ``nex.box`` method: - -* :ref:`box.cfg.listen ` -- on the server side. -* :ref:`box.cfg.replication `--on the client side. -* :ref:`net_box_object.connect() `--on the client side. - -Below is the list of the parameters. -In the :ref:`next section `, you can find details and examples on what should be configured on both the server side and the client side. - -* ``transport`` -- enables SSL encryption for a connection if set to ``ssl``. - The default value is ``plain``, which means the encryption is off. If the parameter is not set, the encryption is off too. - Other encryption-related parameters can be used only if the ``transport = 'ssl'`` is set. - - Example: - - .. code-block:: lua - - c = require('net.box').connect({ - uri = 'localhost:3301', - params = {transport = 'ssl'} - }) - -* ``ssl_key_file`` -- a path to a private SSL key file. - Mandatory for a server. - For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. - If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter. - -* ``ssl_cert_file`` -- a path to an SSL certificate file. - Mandatory for a server. - For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. - -* ``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. Optional. If not set, the peer won't be checked for authenticity. - - Both a server and a client can use the ``ssl_ca_file`` parameter: - - * If it's on the server side, the server verifies the client. - * If it's on the client side, the client verifies the server. - * If both sides have the CA files, the sever and the client verify each other. - -* ``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use. See the :ref:`enterprise-iproto-encryption-ciphers` section for details. Optional. - Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found. - -* ``ssl_password`` -- a password for an encrypted private SSL key. Optional. Alternatively, the password - can be provided in ``ssl_password_file``. - -* ``ssl_password_file`` -- a text file with one or more passwords for encrypted private SSL keys - (each on a separate line). Optional. Alternatively, the password can be provided in ``ssl_password``. - - Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order: - - 1. If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it. - 2. If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` - one by one in the order they are written. - 3. If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, - or none of them is provided, Tarantool treats the private key as unencrypted. - -Configuration example: - -.. code-block:: lua - - box.cfg{ listen = { - uri = 'localhost:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ciphers = 'HIGH:!aNULL', - ssl_password = 'topsecret' - } - }} - -.. _enterprise-iproto-encryption-ciphers: - -Supported ciphers -***************** - -Tarantool Enterprise supports the following cipher suites: - -* ECDHE-ECDSA-AES256-GCM-SHA384 -* ECDHE-RSA-AES256-GCM-SHA384 -* DHE-RSA-AES256-GCM-SHA384 -* ECDHE-ECDSA-CHACHA20-POLY1305 -* ECDHE-RSA-CHACHA20-POLY1305 -* DHE-RSA-CHACHA20-POLY1305 -* ECDHE-ECDSA-AES128-GCM-SHA256 -* ECDHE-RSA-AES128-GCM-SHA256 -* DHE-RSA-AES128-GCM-SHA256 -* ECDHE-ECDSA-AES256-SHA384 -* ECDHE-RSA-AES256-SHA384 -* DHE-RSA-AES256-SHA256 -* ECDHE-ECDSA-AES128-SHA256 -* ECDHE-RSA-AES128-SHA256 -* DHE-RSA-AES128-SHA256 -* ECDHE-ECDSA-AES256-SHA -* ECDHE-RSA-AES256-SHA -* DHE-RSA-AES256-SHA -* ECDHE-ECDSA-AES128-SHA -* ECDHE-RSA-AES128-SHA -* DHE-RSA-AES128-SHA -* AES256-GCM-SHA384 -* AES128-GCM-SHA256 -* AES256-SHA256 -* AES128-SHA256 -* AES256-SHA -* AES128-SHA -* GOST2012-GOST8912-GOST8912 -* GOST2001-GOST89-GOST89 - -Tarantool Enterprise static build has the embeded engine to support the GOST cryptographic algorithms. -If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ``ssl_ciphers`` parameter, for example: - -.. code-block:: lua - - box.cfg{ listen = { - uri = 'localhost:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ciphers = 'GOST2012-GOST8912-GOST8912' - } - }} - -For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__. - -Using environment variables -*************************** - -The URI parameters for traffic encryption can also be set via environment variables. For example: - -.. code-block:: bash - - export TT_LISTEN="localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file" - -For details, refer to the Tarantool :ref:`configuration reference `. - -.. _enterprise-iproto-encryption-config-sc: - -Server-client configuration details -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. -Below you can find the summary on the options and parameters to be used and :ref:`examples of configuration `. - -**Server side** - -* Is configured via the ``box.cfg.listen`` option. -* Mandatory URI parameters: ``transport``, ``ssl_key_file`` and ``ssl_cert_file``. -* Optional URI parameters: ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file``. - - -**Client side** - -* Is configured via the ``box.cfg.replication`` option (see :ref:`details `) or ``net_box_object.connect()``. - -Parameters: - -* If the server side has only the ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` parameters set, - on the client side, you need to specify only ``transport = ssl`` as the mandatory parameter. - All other URI parameters are optional. - -* If the server side also has the ``ssl_ca_file`` parameter set, - on the client side, you need to specify ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` as the mandatory parameters. - Other parameters -- ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file`` -- are optional. - -.. _enterprise-iproto-encryption-config-example: - -Configuration examples -********************** - -Suppose, there is a :ref:`master-replica ` set with two Tarantool instances: - -* 127.0.0.1:3301 -- master (server) -* 127.0.0.1:3302 -- replica (client). - -Examples below show the configuration related to connection encryption for two cases: -when the trusted certificate authorities (CA) file is not set on the server side and when it does. -Only mandatory URI parameters are mentioned in these examples. - -1. **Without CA** - -* 127.0.0.1:3301 -- master (server) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - } - } - -* 127.0.0.1:3302 -- replica (client) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3302', - params = {transport = 'ssl'} - }, - replication = { - uri = 'username:password@127.0.0.1:3301', - params = {transport = 'ssl'} - }, - read_only = true - } - -2. **With CA** - -* 127.0.0.1:3301 -- master (server) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ca_file = '/path_to_ca_file' - } - } - } - -* 127.0.0.1:3302 -- replica (client) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3302', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - }, - replication = { - uri = 'username:password@127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - }, - read_only = true - } - -.. _enterprise-security-hardening: - -Recommendations on security hardening -------------------------------------- - -This section lists recommendations that can help you harden the cluster's security. - -.. _enterprise-traffic-encryption: - -Encrypting traffic -~~~~~~~~~~~~~~~~~~ - -Since version 2.10.0, Tarantool Enterprise Edition has built-in support for using SSL to encrypt the client-server communications over binary connections, -that is, between Tarantool instances in a cluster. For details on enabling SSL encryption, see the :ref:`enterprise-iproto-encryption` section of this guide. - -In case the built-in encryption is not set for particular connections, consider the following security recommendations: - -* setting up connection tunneling, or -* encrypting the actual data stored in the database. - -For more information on data encryption, see the -:doc:`crypto module reference `. - -The `HTTP server module `_ provided by rocks -does not support the HTTPS protocol. To set up a secure connection for a client -(e.g., REST service), consider hiding the Tarantool instance (router if it is -a cluster of instances) behind an Nginx server and setting up an SSL certificate -for it. - -To make sure that no information can be intercepted 'from the wild', run nginx -on the same physical server as the instance and set up their communication over -a Unix socket. For more information, see the -:doc:`socket module reference `. - -.. _enterprise-firewall-config: - -Firewall configuration -~~~~~~~~~~~~~~~~~~~~~~ - -To protect the cluster from any unwanted network activity 'from the wild', -configure the firewall on each server to allow traffic on ports listed in -:ref:`Network requirements `. - -If you are using static IP addresses, whitelist them, again, on each server as -the cluster has a full mesh network topology. Consider blacklisting all the other -addresses on all servers except the router (running behind the Nginx server). - -Tarantool Enterprise does not provide defense against DoS or DDoS attacks. -Consider using third-party software instead. - -.. _enterprise-integrity: - -Data integrity -~~~~~~~~~~~~~~ - -Tarantool Enterprise Edition does not keep checksums or provide the means to control -data integrity. However, it ensures data persistence using a write-ahead log, -regularly snapshots the entire data set to disk, and checks the data format -whenever it reads the data back from the disk. For more information, see the -:ref:`Data persistence ` section. diff --git a/doc/enterprise/setup.rst b/doc/enterprise/setup.rst deleted file mode 100644 index 551e4d5c34..0000000000 --- a/doc/enterprise/setup.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. _enterprise-setup: - -=============================================================================== -Setup -=============================================================================== - -This chapter explains how to download and set up Tarantool Enterprise Edition and run -a sample application provided with it. - -.. _enterprise-prereqs: - -------------------------------------------------------------------------------- -System requirements -------------------------------------------------------------------------------- - -The recommended system requirements for running Tarantool Enterprise are as -follows. - -.. _enterprise-prereqs-hardware: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Hardware requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To fully ensure the fault tolerance of a distributed data storage system, at -least **three** physical computers or virtual servers are required. - -For testing/development purposes, the system can be deployed using a smaller number -of servers; however, it is not recommended to use such configurations for production. - -.. _enterprise-prereqs-software: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Software requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -#. As host operating systems, Tarantool Enterprise Edition supports - **Red Hat Enterprise Linux** and **CentOS** versions 7.5 and higher. - - .. NOTE:: - - Tarantool Enterprise can run on other ``systemd``-based Linux distributions - but it is not tested on them and may not work as expected. - -#. ``glibc`` 2.17-260.el7_6.6 and higher is required. Take care to check and - update, if needed: - - .. code-block:: console - - $ rpm -q glibc - glibc-2.17-196.el7_4.2 - $ yum update glibc - -.. _enterprise-prereqs-network: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Network requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Hereinafter, **"storage servers"** or **"Tarantool servers"** are the computers -used to store and process data, and **"administration server"** is the computer -used by the system operator to install and configure the product. - -The Tarantool cluster has a full mesh topology, therefore all Tarantool servers -should be able to communicate and send traffic from and to TCP/UDP ports -used by the cluster's instances (see ``advertise_uri: :`` and -``config: advertise_uri: ':'`` in ``/etc/tarantool/conf.d/*.yml`` -for each instance). For example: - -.. code-block:: kconfig - - # /etc/tarantool/conf.d/*.yml - - myapp.s2-replica: - advertise_uri: localhost:3305 # this is a TCP/UDP port - http_port: 8085 - - all: - ... - hosts: - storage-1: - config: - advertise_uri: 'vm1:3301' # this is a TCP/UDP port - http_port: 8081 - -To configure remote monitoring or to connect via the administrative console, -the administration server should be able to access the following TCP ports on -Tarantool servers: - -* 22 to use the SSH protocol, -* ports specified in - :ref:`instance configuration ` - (``http_port`` parameter) to monitor the HTTP-metrics. - -Additionally, it is recommended to apply the following settings for ``sysctl`` -on all Tarantool servers: - -.. code-block:: console - - $ # TCP KeepAlive setting - $ sysctl -w net.ipv4.tcp_keepalive_time=60 - $ sysctl -w net.ipv4.tcp_keepalive_intvl=5 - $ sysctl -w net.ipv4.tcp_keepalive_probes=5 - -This optional setup of the Linux network stack helps speed up the troubleshooting -of network connectivity when the server physically fails. To achieve maximum -performance, you may also need to configure other network stack parameters that -are not specific to the Tarantool DBMS. For more information, please refer to the -`Network Performance Tuning Guide `_ -section of the RHEL7 user documentation. - -.. _enterprise-package-contents: - -------------------------------------------------------------------------------- -Package contents -------------------------------------------------------------------------------- - -The latest release packages of Tarantool Enterprise are available in the -`customer zone `_ -at Tarantool website. Please contact ``support@tarantool.io`` for access. - -Each package is distributed as a ``tar + gzip`` archive and includes -the following components and features: - -* static Tarantool binary for simplified deployment in Linux environments, -* selection of open and closed source modules, -* sample application walking you through all included modules. - -Archive contents: - -* ``tarantool`` is the main executable of Tarantool. -* ``tt`` is the utility that provides a unified command-line interface for managing Tarantool-based applications. -* ``tarantoolctl`` is the utility script for installing supplementary modules - and connecting to the administrative console. - - .. important:: - - ``tarantoolctl`` is deprecated in favor of the :ref:`tt CLI utility `. - -* ``cartridge`` is the utility script to help you set up a development - environment for applications and pack them for easy deployment. - - .. important:: - - ``cartridge`` utility is deprecated in favor of the :ref:`tt CLI utility `. - -* ``examples/`` is the directory containing sample applications: - - * ``pg_writethrough_cache/`` is an application showcasing how Tarantool can - cache data written to, for example, a PostgreSQL database; - * ``ora_writebehind_cache/`` is an application showcasing how Tarantool can - cache writes and queue them to, for example, an Oracle database; - * ``docker/`` is an application designed to be easily packed into a Docker - container; - -* ``rocks/`` is the directory containing a selection of additional open and - closed source modules included in the distribution as an offline rocks - repository. See the :ref:`rocks reference ` for details. -* ``templates/`` is the directory containing template files for your application - development environment. -* ``deprecated/`` is a set of modules that are no longer supported: - - * ``vshard-zookeeper-orchestrator`` is a Python application - for launching ``orchestrator``, - * ``zookeeper-scm`` files are the ZooKeeper integration modules (require - ``usr/`` libraries). - -.. _archive-unpack: -.. _enterprise-install: - -------------------------------------------------------------------------------- -Installation -------------------------------------------------------------------------------- - -The delivered ``tar + gzip`` archive should be uploaded to a server and unpacked: - -.. code-block:: console - - $ tar xvf tarantool-enterprise-sdk-.tar.gz - -No further installation is required as the unpacked binaries are almost ready -to go. Go to the directory with the binaries (``tarantool-enterprise``) and -add them to the executable path by running the script provided by the distribution: - -.. code-block:: console - - $ source ./env.sh - -Make sure you have enough privileges to run the script and that the file is executable. -Otherwise, try ``chmod`` and ``chown`` commands to adjust it. - -Next, set up your development environment as described in -:ref:`the developer's guide `. diff --git a/doc/enterprise/system_metrics.rst b/doc/enterprise/system_metrics.rst deleted file mode 100644 index 0ee9cd27b3..0000000000 --- a/doc/enterprise/system_metrics.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _enterprise_system_metrics: - -Monitoring system metrics -========================= - -.. container:: table - - .. rst-class:: left-align-column-1 - .. rst-class:: left-align-column-2 - - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | Option | Description | SNMP type | Units of measure| Threshold | - +======================+======================================+==============+=================+=================+ - | Version | Tarantool version | DisplayString| | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | IsAlive | instance availability indicator | Integer | | 0 - unavailable | - | | | | | | - | | | (listing) | | 1 - available | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | MemoryLua | storage space used by Lua | Gauge32 | Mbyte | 900 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | MemoryData | storage space used for storing data | Gauge32 | Mbyte | set the value | - | | | | | manually | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | MemoryNet | storage space used for network I/O | Gauge32 | Mbyte | 1024 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | MemoryIndex | storage space used for storing | Gauge32 | Mbyte | set the value | - | | indexes | | | manually | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | MemoryCache | storage space used for storing caches| Gauge32 | Mbyte | | - | | (for vinyl engine only) | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | ReplicationLag | lag time since the last sync between | Integer32 | sec. | 5 | - | | (the maximum value in case there are | | | | - | | multiple fibers) | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | FiberCount | number of fibers | Gauge32 | pc. | 1000 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | CurrentTime | current time, in seconds, starting at| Unsigned32 | Unix timestamp, | | - | | January, 1st, 1970 | | in sec. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageStatus | status of a replica set | Integer | listing | > 1 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageAlerts | number of alerts for storage nodes | Gauge32 | pc. | >= 1 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageTotalBkts | total number of buckets in the | Gauge32 | pc. | < 0 | - | | storage | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageActiveBkts | number of buckets in the ACTIVE state| Gauge32 | pc. | < 0 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageGarbageBkts | number of buckets in the GARBAGE | Gauge32 | pc. | < 0 | - | | state | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageReceivingBkts | number of buckets in the RECEIVING | Gauge32 | pc. | < 0 | - | | state | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | StorageSendingBkts | number of buckets in the SENDING | Gauge32 | pc. | < 0 | - | | state | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | RouterStatus | status of the ``router`` | Integer | listing | > 1 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | RouterAlerts | number of alerts for the router | Gauge32 | pc. | >= 1 | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | RouterKnownBkts | number of buckets within the known | Gauge32 | pc. | < 0 | - | | destination replica sets | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | RouterUnknownBkts | number of buckets that are unknown to| Gauge32 | pc. | < 0 | - | | the ``router`` | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | RequestCount | total number of requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | InsertCount | total number of insert requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | DeleteCount | total number of delete requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | ReplaceCount | total number of replace requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | UpdateCount | total number of update requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | SelectCount | total number of select requests | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | EvalCount | number of calls made via Eval | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | CallCount | number of calls made via ``call`` | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | ErrorCount | number of errors in Tarantool | Counter64 | pc. | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ - | AuthCount | number of completed authentication | Counter64 | pc. | | - | | operations | | | | - +----------------------+--------------------------------------+--------------+-----------------+-----------------+ diff --git a/doc/enterprise/tuple_compression/api/compress.rst b/doc/enterprise/tuple_compression/api/compress.rst deleted file mode 100644 index 14a5667cd5..0000000000 --- a/doc/enterprise/tuple_compression/api/compress.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _compress-module: - -Module compress -=============== - -.. module:: compress - -**Since:** :doc:`2.11.0 ` - -The ``compress`` module provides a set of submodules for compressing and decompressing data using different algorithms: - -.. toctree:: - :maxdepth: 1 - :includehidden: - - zlib - zstd - lz4 diff --git a/doc/enterprise/wal_extensions.rst b/doc/enterprise/wal_extensions.rst deleted file mode 100644 index c07cc5d0fb..0000000000 --- a/doc/enterprise/wal_extensions.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _wal_extensions: - -WAL extensions -============== - -WAL extensions available in Tarantool Enterprise Edition allow you to add auxiliary information to each :ref:`write-ahead log ` record. -For example, you can enable storing an old and new tuple for each CRUD operation performed. -This information might be helpful for implementing a CDC (Change Data Capture) utility -that transforms a data replication stream. - - -.. _wal_extensions_configuration: - -Configuration -------------- - -To configure WAL extensions, use the ``wal_ext`` :ref:`configuration property `. -Inside the ``wal_ext`` block, you can enable storing old and new tuples as follows: - -* Set the ``old`` and ``new`` options to ``true`` to store old and new tuples in a write-ahead log for all spaces. - - .. code-block:: lua - - box.cfg { - wal_ext = { old = true, new = true } - } - -* To adjust these options for specific spaces, use the ``spaces`` option. - - .. code-block:: lua - - box.cfg { - wal_ext = { - old = true, new = true, - spaces = { - space1 = { old = false }, - space2 = { new = false } - } - } - } - - - The configuration for specific spaces has priority over the global configuration, - so only new tuples are added to the log for ``space1`` and only old tuples for ``space2``. - -Note that records with additional fields are :ref:`replicated ` as follows: - -* If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped. -* If a replica and master have different configurations for WAL records, a master's configuration is ignored. - - -.. _wal_extensions_example: - -Example -------- - -The table below demonstrates how write-ahead log records might look -for the specific :ref:`CRUD operations ` -if storing old and new tuples is enabled for the ``bands`` space. - -.. container:: table - - .. list-table:: - :widths: 10 50 40 - :header-rows: 1 - - * - Operation - - Example - - WAL information - * - insert - - ``bands:insert{4, 'The Beatles', 1960}`` - - | **new_tuple**: [4, 'The Beatles', 1960] - | tuple: [4, 'The Beatles', 1960] - * - delete - - ``bands:delete{4}`` - - | key: [4] - | **old_tuple**: [4, 'The Beatles', 1960] - * - update - - ``bands:update({2}, {{'=', 2, 'Pink Floyd'}})`` - - | **new_tuple**: [2, 'Pink Floyd', 1965] - | **old_tuple**: [2, 'Scorpions', 1965] - | key: [2] - | tuple: [['=', 2, 'Pink Floyd']] - * - upsert - - ``bands:upsert({2, 'Pink Floyd', 1965}, {{'=', 2, 'The Doors'}})`` - - | **new_tuple**: [2, 'The Doors', 1965] - | **old_tuple**: [2, 'Pink Floyd', 1965] - | operations: [['=', 2, 'The Doors']] - | tuple: [2, 'Pink Floyd', 1965] - * - replace - - ``bands:replace{1, 'The Beatles', 1960}`` - - | **old_tuple**: [1, 'Roxette', 1986] - | **new_tuple**: [1, 'The Beatles', 1960] - | tuple: [1, 'The Beatles', 1960] - -Storing both old and new tuples is especially useful for the ``update`` -operation because a write-ahead log record contains only a key value. - -.. NOTE:: - - You can use the :doc:`tt cat ` command to see the contents of a write-ahead log. diff --git a/doc/getting_started/change_schema_dynamically.rst b/doc/getting_started/change_schema_dynamically.rst deleted file mode 100644 index 3577cf0349..0000000000 --- a/doc/getting_started/change_schema_dynamically.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _getting_started-schema_changing: - -================================================================================= -Updating the data schema -================================================================================= - -When working with data, it is sometimes necessary to change the original data schema. - -In the previous sections, we described a cluster-wide data schema in the YAML format. -The ``ddl`` module is responsible for applying the schema on the cluster. This module does not allow -to modify the schema after applying it. - -The easiest way to change it is to delete the database snapshots and create -a schema from scratch. Of course, this is only acceptable during application -development and debugging. -For production scenarios, read the section on :ref:`migrations `. - -To remove snapshots: - -* If you are using Tarantool in the cloud, - click the "Reset configuration" button. -* If you've started Tarantool locally via ``cartridge start``, - run ``cartridge clean`` in the application directory. -* If you've started Tarantool in a different way, - delete the snapshots and xlogs manually. - These files have the .snap and .xlog extensions respectively, - and they are located in the Tarantool working directory. - -To understand how the Tarantool data schema works, read the :ref:`Data model ` section. diff --git a/doc/getting_started/connecting_to_cluster.rst b/doc/getting_started/connecting_to_cluster.rst deleted file mode 100644 index 06665a5340..0000000000 --- a/doc/getting_started/connecting_to_cluster.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _connecting_to_cluster: - -================================================================================= -Connecting to the cluster -================================================================================= - -In the last section, we set up a cluster, created a schema, and wrote data through the HTTP API. -Now we can connect to the cluster from code and work with data. - -.. note:: - - If you are using Tarantool without Cartridge, go to the - :ref:`Connecting from your favorite language ` section. - If you are undergoing training, read on. - -You may have noticed that we used the ``crud`` module in the HTTP handler code. -The code looked something like this: - -.. code:: lua - - local crud = require ('crud') - - function add_user(request) - local result, err = crud.insert_object ('users', {user_id = uuid.new (), fullname = fullname}) - end - - -This module allows you to work with data in a cluster. The syntax here is similar to -what the Tarantool ``box`` module offers. -You will learn more about the ``box`` module in the following sections. - -The ``crud`` module contains a set of stored procedures. -To work with them, we must activate special roles on all routers and storages. -We selected those roles in the previous section, so we don't need to do anything. -The roles are named accordingly: "crud-router" and "crud-storage". - -To write and read data in the Tarantool cluster from code, we will call stored -procedures of the ``crud`` module. - -In Python, it looks like this: - -.. code:: python - - res = conn.call('crud.insert', 'users', , 'Jim Carrey') - users = conn.call('crud.select', 'users', {limit: 100}) - -All functions of the ``crud`` module are described -in the `README of our GitHub repository `_. - -Here is an incomplete list: - -* ``insert`` -* ``select`` -* ``get`` -* ``delete`` -* ``min``\/``max`` -* ``replace``\/``upsert`` -* ``truncate`` - -To learn how to call stored procedures in your programming language, see the corresponding section: - -* :ref:`for Python ` -* :ref:`for Go ` -* :ref:`for PHP ` -* :doc:`for C++ ` - -For connectors to other languages, check the README for the connector of your choice -`on GitHub `_. diff --git a/doc/getting_started/getting_started_db.rst b/doc/getting_started/getting_started_db.rst new file mode 100644 index 0000000000..a062d3c4f0 --- /dev/null +++ b/doc/getting_started/getting_started_db.rst @@ -0,0 +1,220 @@ +.. _getting_started_db: + +Creating your first Tarantool database +====================================== + +**Example on GitHub**: `create_db `_ + +In this tutorial, you create a Tarantool database, write data to it, and select data from this database. + + +.. _getting_started_db_prerequisites: + +Prerequisites +------------- + +Before starting this tutorial: + +* Install the :ref:`tt ` utility. +* Install `Tarantool `_. + + .. NOTE:: + + The tt utility provides the ability to install Tarantool software using the :ref:`tt install ` command. + + + +.. _getting_started_db_creating-app: + +Creating an application +----------------------- + +The :ref:`tt create ` command can be used to :ref:`create an application ` from a predefined or custom template. +In this tutorial, the application layout is prepared manually: + +#. Create a tt environment in the current directory using the :ref:`tt init ` command. + +#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``create_db`` directory. + +#. Inside ``instances.enabled/create_db``, create the ``instances.yml`` and ``config.yaml`` files: + + * ``instances.yml`` specifies instances to run in the current environment. In this example, there is one instance: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/instances.yml + :language: yaml + :dedent: + + * ``config.yaml`` contains basic instance :ref:`configuration `: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/config.yaml + :language: yaml + :dedent: + + The instance in the configuration accepts incoming requests on the ``3301`` port. + + + + +.. _getting_started_db_working_with_database: + +Working with the database +------------------------- + +.. _getting_started_db-start: + +Starting an instance +~~~~~~~~~~~~~~~~~~~~ + +#. Start the Tarantool instance from the tt environment directory using :ref:`tt start `: + + .. code-block:: console + + $ tt start create_db + +#. To check the running instance, use the :ref:`tt status ` command: + + .. code-block:: console + + $ tt status create_db + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + create_db:instance001 RUNNING 8685 RW ready running -- + +#. Connect to the instance with :ref:`tt connect `: + + .. code-block:: console + + $ tt connect create_db:instance001 + • Connecting to the instance... + • Connected to create_db:instance001 + + create_db:instance001> + + This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt. + Now you can enter requests in the command line. + + +.. _creating-db-locally: + +Creating a space +~~~~~~~~~~~~~~~~ + +#. Create a :term:`space ` named ``bands``: + + .. code-block:: tarantoolsession + + create_db:instance001> box.schema.space.create('bands') + --- + - engine: memtx + before_replace: 'function: 0x010229d788' + field_count: 0 + is_sync: false + is_local: false + on_replace: 'function: 0x010229d750' + temporary: false + index: [] + type: normal + enabled: false + name: bands + id: 512 + - created + ... + +#. Format the created space by specifying :term:`field` names and :ref:`types `: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + --- + ... + + +.. _creating-db-indexes: + +Creating indexes +~~~~~~~~~~~~~~~~ + +#. Create the primary :ref:`index ` based on the ``id`` field: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands:create_index('primary', { parts = { 'id' } }) + --- + - unique: true + parts: + - fieldno: 1 + sort_order: asc + type: unsigned + exclude_null: false + is_nullable: false + hint: true + id: 0 + type: TREE + space_id: 512 + name: primary + ... + +#. Create the secondary index based on the ``band_name`` field: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands:create_index('secondary', { parts = { 'band_name' } }) + --- + - unique: true + parts: + - fieldno: 2 + sort_order: asc + type: string + exclude_null: false + is_nullable: false + hint: true + id: 1 + type: TREE + space_id: 512 + name: secondary + ... + + + +.. _getting_started_db-start_writing_selecting_data: + +Writing and selecting data +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Insert three :term:`tuples ` into the space: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands:insert { 1, 'Roxette', 1986 } + --- + - [1, 'Roxette', 1986] + ... + create_db:instance001> box.space.bands:insert { 2, 'Scorpions', 1965 } + --- + - [2, 'Scorpions', 1965] + ... + create_db:instance001> box.space.bands:insert { 3, 'Ace of Base', 1987 } + --- + - [3, 'Ace of Base', 1987] + ... + +#. Select a tuple using the ``primary`` index: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands:select { 3 } + --- + - - [3, 'Ace of Base', 1987] + ... + +#. Select tuples using the ``secondary`` index: + + .. code-block:: tarantoolsession + + create_db:instance001> box.space.bands.index.secondary:select{'Scorpions'} + --- + - - [2, 'Scorpions', 1965] + ... diff --git a/doc/getting_started/getting_started_imcp.rst b/doc/getting_started/getting_started_imcp.rst deleted file mode 100644 index 8c232eb0ac..0000000000 --- a/doc/getting_started/getting_started_imcp.rst +++ /dev/null @@ -1,532 +0,0 @@ -.. _getting_started-imcp: - -First steps -=========== - -This is the recommended guide for getting to know the product. - -.. note:: - - You also might want to check out our - :ref:`basic Tarantool tutorial `. - It shows how to launch one Tarantool instance, - create a space, build an index, and write data. - - We recommend that beginners go through the current tutorial first - and then see the basic tutorial to dive deeper into the product. - -If you just want to run the complete tutorial code quickly, go to -:ref:`Launching an application `. - -Installation -~~~~~~~~~~~~ - -**Launch in the cloud** - -This tutorial is also available in the cloud. It's free, and it's the fastest way to start. -To follow this tutorial in the cloud, go to `try.tarantool.io `__. - -However, you will still need to install Tarantool -if you want to get better acquainted with it. - -**Run locally** - -**For Linux/macOS users:** - -* Install Tarantool from the `Download page `__. -* Install `Node.js `_, which is required for the tutorial frontend. -* Install the ``cartridge-cli`` utility through your package manager: - - .. code-block:: bash - - sudo yum install cartridge-cli - - .. code-block:: bash - - brew install cartridge-cli - - To learn more, check the ``cartridge-cli`` - :doc:`installation guide `. - -* Clone the `Getting Started tutorial repository `__. - - Everything is ready and organized in this repository. - In the cloned directory, run the following: - - .. code-block:: bash - - cartridge build - cartridge start - -.. note:: - - In case of a problem with `cartridge build`, run it with the `--verbose` flag - to learn about the source of the problem. If there is a problem with Node.js (`npm`): - - 1. Check that Node.js is in the `$PATH`. - - 2. Try forcefully removing the `node_modules` directory from the dependencies' directories: - - `rm -rf analytics/node_modules front/node_modules` - - After that, try running `cartridge build` again. - If all else fails, please `file us an issue on GitHub `_. - - -You're all set! At http://localhost:8081, you will see the Tarantool Cartridge UI. - -**Running in Docker:** - -.. code-block:: bash - - docker run -p 3301:3301 -p 8081:8081 tarantool/getting-started - -That's it! At http://localhost:8081, you will see the Tarantool Cartridge UI. - -**For Windows users:** - -Use Docker to get started. - - -Getting to know Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Today, we will solve a high-performance challenge for TikTok using -Tarantool. - -You will implement a counter of likes for videos. -First, you will create base tables and search indexes. -Then you will set up an HTTP API for mobile clients. - -The challenge doesn't require you to write any additional code. -Everything will be implemented on the Tarantool platform. - -If you accidentally do something wrong while following the instructions, -there is a magic button to help you reset all changes. -It is called **"Reset Configuration"**. You can find it at the top of the "Cluster" page. - -Configuring a cluster [1 minute] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Everything you need to know to get started:** - -A Tarantool cluster has two service roles: router and storage. - -* Storage is used to store data. -* Router is an intermediary between clients and storages. - It accepts a client's request, takes data from the proper storage, - and returns it to the client. - -We see that we have 5 unconfigured instances on the "Cluster" tab. - -.. figure:: images/hosts-list.png - :alt: List of all nodes - - List of all nodes - -Let's create one router and one storage for a start. - -First, click the "Configure" button on the "router" instance and configure -it as in the screenshot below: - -.. figure:: images/router-configuration.png - :alt: Configuring a router - - Configuring a router - -Next, we configure the "s1-master" instance: - -.. figure:: images/storage-configuration.png - :alt: Configuring s1-master - - Configuring s1-master - -It will look something like this: - -.. figure:: images/first-configuration-result.png - :alt: Cluster view after first setup - - Cluster view after first setup - -Let's enable sharding in the cluster using the "Bootstrap vshard" button. It is -located in the top right corner. - -Creating a data schema [2 minutes] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Let's start with the data schema -- take a look at the **Code** tab on the left. - -There you can find a file called ``schema.yml``. In this file, you can -describe the entire cluster's data schema, edit the current schema, -validate its correctness, and apply it to the whole cluster. - -First, let's create the necessary tables. In Tarantool, they are called spaces. - -We need to store: - -* Users -* Videos with descriptions -* Likes for each video - -Copy the schema description from the code block below and paste it in the ``schema.yml`` file on the **Code** tab. -Click the "Apply" button. -After that, the data schema will be described in the cluster. - -This is what our data schema will look like: - - .. code-block:: yaml - - spaces: - users: - engine: memtx - is_local: false - temporary: false - sharding_key: - - "user_id" - format: - - {name: bucket_id, type: unsigned, is_nullable: false} - - {name: user_id, type: uuid, is_nullable: false} - - {name: fullname, type: string, is_nullable: false} - indexes: - - name: user_id - unique: true - parts: [{path: user_id, type: uuid, is_nullable: false}] - type: HASH - - name: bucket_id - unique: false - parts: [{path: bucket_id, type: unsigned, is_nullable: false}] - type: TREE - videos: - engine: memtx - is_local: false - temporary: false - sharding_key: - - "video_id" - format: - - {name: bucket_id, type: unsigned, is_nullable: false} - - {name: video_id, type: uuid, is_nullable: false} - - {name: description, type: string, is_nullable: true} - indexes: - - name: video_id - unique: true - parts: [{path: video_id, type: uuid, is_nullable: false}] - type: HASH - - name: bucket_id - unique: false - parts: [{path: bucket_id, type: unsigned, is_nullable: false}] - type: TREE - - likes: - engine: memtx - is_local: false - temporary: false - sharding_key: - - "video_id" - format: - - {name: bucket_id, type: unsigned, is_nullable: false} - - {name: like_id, type: uuid, is_nullable: false} - - {name: user_id, type: uuid, is_nullable: false} - - {name: video_id, type: uuid, is_nullable: false} - - {name: timestamp, type: string, is_nullable: true} - indexes: - - name: like_id - unique: true - parts: [{path: like_id, type: uuid, is_nullable: false}] - type: HASH - - name: bucket_id - unique: false - parts: [{path: bucket_id, type: unsigned, is_nullable: false}] - type: TREE - -It's simple. Let's take a closer look at the essential points. - -Tarantool has two built-in storage engines: memtx and vinyl. -memtx stores all data in RAM while asynchronously writing to -disk so that nothing gets lost. - -Vinyl is a classic engine for storing data on the -hard drive. It is optimized for write-intensive scenarios. - -In TikTok, there are a lot of simultaneous readings and -posts: users watch videos, like them, and comment on them. -Therefore, let's use memtx. - -The configuration above describes three memtx spaces (tables) -and the necessary indexes for each of the spaces. - -Each space has two indexes: - -* The primary key, which is required to read/write data. -* An index on the bucket_id field, which is a service field used for sharding. - -**Important:** The name ``bucket_id`` is reserved. If you choose -another name, sharding won't work for this space. -If you don't use sharding in your project, you can remove the second index. - -To understand which field to shard data by, Tarantool uses -``sharding_key``. ``sharding_key`` points to fields in the space by -which database records will be sharded. There can be more than one such field, but -in this example, we will only use one. When some data is inserted, -Tarantool forms a hash from this field, calculates the bucket number, -and selects the storage to record the data into. - -Yes, buckets can repeat, and each storage stores a specific range of buckets. - -Here are a couple more interesting facts: - -* The ``parts`` field in the index description can contain several fields, - which allows building a composite index. You won't need it in this tutorial. -* Tarantool does not support foreign keys, so you have to check manually - upon insertion - that ``video_id`` and ``user_id`` exist in the ``likes`` space. - -Writing data [5 minutes] -~~~~~~~~~~~~~~~~~~~~~~~~ - -We will write data to the Tarantool cluster using the CRUD module. -You don't have to specify the shard you want to read from or write to -- the module -does it for you. - -**Important:** All cluster operations must be performed only on the router -and using the CRUD module. - -Let's connect the CRUD module in the code and write three procedures: - -* User creation -* Adding a video -* Liking a video - -The procedures must be described in a special file. To do this, go to -the "Code" tab. Create a new directory called ``extensions``, and -in this directory, create the file ``api.lua``. - -Paste the code below into ``api.lua`` and click "Apply". - -.. code-block:: lua - - local cartridge = require('cartridge') - local crud = require('crud') - local uuid = require('uuid') - local json = require('json') - - function add_user(request) - local fullname = request:post_param("fullname") - local result, err = crud.insert_object('users', {user_id = uuid.new(), fullname = fullname}) - if err ~= nil then - return {body = json.encode({status = "Error!", error = err}), status = 500} - end - - return {body = json.encode({status = "Success!", result = result}), status = 200} - end - - function add_video(request) - local description = request:post_param("description") - local result, err = crud.insert_object('videos', {video_id = uuid.new(), description = description}) - if err ~= nil then - return {body = json.encode({status = "Error!", error = err}), status = 500} - end - - return {body = json.encode({status = "Success!", result = result}), status = 200} - end - - function like_video(request) - local video_id = request:post_param("video_id") - local user_id = request:post_param("user_id") - - local result, err = crud.insert_object('likes', {like_id = uuid.new(), - video_id = uuid.fromstr(video_id), - user_id = uuid.fromstr(user_id)}) - if err ~= nil then - return {body = json.encode({status = "Error!", error = err}), status = 500} - end - - return {body = json.encode({status = "Success!", result = result}), status = 200} - end - - return { - add_user = add_user, - add_video = add_video, - like_video = like_video, - } - -Setting up HTTP API [2 minutes] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clients will visit the Tarantool cluster using the HTTP protocol. -The cluster already has a built-in HTTP server. - -To configure HTTP paths, you need to write a configuration -file. Go to the "Code" tab. Create the file ``config.yml`` -in the ``extensions`` directory, which you created on the last step. - -Paste the configuration example below into ``config.yml`` and click "Apply". - -.. code-block:: yaml - - --- - functions: - - add_user: - module: extensions.api - handler: add_user - events: - - http: {path: "/add_user", method: POST} - - add_video: - module: extensions.api - handler: add_video - events: - - http: {path: "/add_video", method: POST} - - like_video: - module: extensions.api - handler: like_video - events: - - http: {path: "/like_video", method: POST} - ... - -Done! Let's make test requests from the console. - -.. code-block:: bash - - curl -X POST --data "fullname=Taran Tool" url/add_user - -.. note:: - - In the requests, substitute ``url`` with the address of your sandbox. - The protocol must be strictly HTTP. - - For example, if you're following this tutorial with Try Tarantool, this request will look something like this - (note that your hash is different): - - .. code-block:: bash - - curl -X POST --data "fullname=Taran Tool" http://artpjcvnmwctc4qppejgf57.try.tarantool.io/add_user - - But if you've bootstrapped Tarantool locally, the request will look as follows: - - .. code-block:: bash - - curl -X POST --data "fullname=Taran Tool" http://localhost:8081/add_user - -We've just created a user and got their UUID. Let's remember it. - -.. code-block:: bash - - curl -X POST --data "description=My first tiktok" url/add_video - -Let's say a user has added their first video with a description. -The video clip also has a UUID. Let's remember it, too. - -In order to "like" the video, you need to specify the user UUID and the video UUID from the previous steps. -Substitute the ellipses in the command below with the corresponding UUIDs: - -.. code-block:: bash - - curl -X POST --data "video_id=...&user_id=..." url/like_video - -The result will be something like this: - -.. figure:: images/console.png - :alt: Test queries in the console - - Test queries in the console - -In our example, you can "like" the video as many times as you want. -It makes no sense in the real life, but it will help us understand how -sharding works -- more precisely, the ``sharding_key`` parameter. - -Our ``sharding_key`` for the ``likes`` is ``video_id``. -We also specified a ``sharding_key`` for the ``videos`` space. It means -that likes will be stored on the same storage as videos. -This ensures data locality with regard to storage and allows -getting all the information you need in one network trip to Storage. - -More details are described on the next step. - -Looking at the data [1 minute] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The following instructions are for Tarantool Enterprise Edition and the Try Tarantool cloud service. - - The Space-Explorer tool is unavailable in the open-source version. Use the console to view data. - - Check our documentation to learn more about :doc:`data viewing `. - To learn how to connect to a Tarantool instance, :ref:`read the basic Tarantool manual `. - - -Go to the "Space-Explorer" tab to see all the nodes in the cluster. -As we have only one storage and one router started so far, the data is stored -on only one node. - -Let's go to the node ``s1-master``: click "Connect" and select the necessary space. -Check that everything is in place and move on. - -.. figure:: images/hosts.png - :alt: Space Explorer, host list - - Space Explorer, host list - -.. figure:: images/likes.png - :alt: Space Explorer, view likes - - Space Explorer, viewing likes - - -Scaling the cluster [1 minute] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Let's create a second shard. Click on the "Cluster" tab, select -``s2-master``, and click "Configure". Select the roles as shown in the picture: - -.. figure:: images/configuring-server.png - :alt: Cluster, new shard configuration screen - - Cluster, new shard configuration screen - -Click on the necessary roles and create a shard (replica set). - -Checking how sharding works [1 minute] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now we have two shards -- two logical nodes that -share data among themselves. The router decides what piece of data goes to what shard. -By default, the router uses the hash function from the field ``sharding_key`` -we've specified in the DDL. - -To enable a new shard, you need to set its weight to one. -Go back to the "Cluster" tab, open the ``s2-master`` settings, -set the Replica set weight to 1, and apply. - -Something has already happened. Let's go to Space-Explorer and check the node -``s2-master``. It turns out that some of the data from the first shard -has already migrated here! The scaling is done automatically. - -Now let's try adding more data to the cluster via the HTTP API. -We can check back later and make sure that the new data is also evenly -distributed across the two shards. - -Disconnecting a shard for a while [1 minute] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the ``s1-master`` settings, set Replica set weight to 0 and -apply. Wait for a few seconds, then go to Space-Explorer and look at the -data in ``s2-master``. You will see that all the data has been migrated to -the remaining shard automatically. - -Now we can safely disable the first shard for maintenance. - -See also -~~~~~~~~ - -* README of the `DDL `__ module to create - your own data schema. -* README of the `CRUD `__ module to - learn more about the API and create your own cluster queries. - - -To continue to the next steps of the tutorial, -click the button in the bottom right corner -or select the section in the table of contents on the left. diff --git a/doc/getting_started/getting_started_tcm.rst b/doc/getting_started/getting_started_tcm.rst new file mode 100644 index 0000000000..4d7b124851 --- /dev/null +++ b/doc/getting_started/getting_started_tcm.rst @@ -0,0 +1,402 @@ +.. _getting_started_tcm: + +Getting started with Tarantool Cluster Manager +============================================== + +.. admonition:: Enterprise Edition + :class: fact + + This tutorial uses `Tarantool Enterprise Edition `_. + +**Example on GitHub**: `tcm_get_started `_ + +In this tutorial, you get :ref:`tcm` up and running on your local system, deploy +a local Tarantool EE cluster, and learn to manage the cluster from the |tcm| web UI. + +To complete this tutorial, you need: + +* A Linux machine with glibc 2.17 or later. +* A web browser: Chromium-based (Chromium version 108 or later), Mozilla Firefox 101 or later, or another up-to-date browser. +* The Tarantool Enterprise Edition SDK 3.0 or later in the ``tar.gz`` archive. + See :ref:`tarantool_installation` for information about getting the archive. + +For more detailed information about using |tcm|, refer to :ref:`tcm`. + +.. _getting_started_tcm_setup: + +Setting up Tarantool EE +----------------------- + +#. Extract the Tarantool EE SDK archive: + + .. code-block:: console + + $ tar -xvzf tarantool-enterprise-sdk-gc64---r.linux.x86_64.tar.gz + + This creates the ``tarantool-enterprise`` directory beside the archive. + The directory contains three executables for key Tarantool EE components: + + * ``tarantool`` -- Tarantool Enterprise Edition. + * ``tt`` -- the :ref:`tt ` command-line utility. + * ``tcm`` -- :ref:`tcm`. + +#. Add the Tarantool EE components to the executable path by executing the ``env.sh`` + script included in the distribution: + + .. code-block:: console + + $ source tarantool-enterprise/env.sh + +#. To check that the Tarantool EE executables ``tarantool``, ``tt``, + and ``tcm`` are available in the system, print their versions: + + .. code-block:: console + + $ tarantool --version + Tarantool Enterprise 3.0.0-0-gf58f7d82a-r23-gc64 + Target: Linux-x86_64-RelWithDebInfo + Build options: cmake . -DCMAKE_INSTALL_PREFIX=/home/centos/release/sdk/tarantool/static-build/tarantool-prefix -DENABLE_BACKTRACE=TRUE + Compiler: GNU-9.3.1 + C_FLAGS: -fexceptions -funwind-tables -fasynchronous-unwind-tables -static-libstdc++ -fno-common -msse2 -fmacro-prefix-map=/home/centos/release/sdk/tarantool=. -std=c11 -Wall -Wextra -Wno-gnu-alignof-expression -fno-gnu89-inline -Wno-cast-function-type -O2 -g -DNDEBUG -ggdb -O2 + CXX_FLAGS: -fexceptions -funwind-tables -fasynchronous-unwind-tables -static-libstdc++ -fno-common -msse2 -fmacro-prefix-map=/home/centos/release/sdk/tarantool=. -std=c++11 -Wall -Wextra -Wno-invalid-offsetof -Wno-gnu-alignof-expression -Wno-cast-function-type -O2 -g -DNDEBUG -ggdb -O2 + $ tt version + Tarantool CLI EE 2.1.0, linux/amd64. commit: d80c2e3 + $ tcm version + 1.0.0-0-gd38b12c2 + +.. _getting_started_tcm_start: + +Starting TCM +------------ + +|tcm_full_name| is ready to run out of the box. To start |tcm| run the following command: + +.. code-block:: console + + $ tcm --storage.etcd.embed.enabled + +.. important:: + + The |tcm| bootstrap log in the terminal includes a message with the credentials + to use for the first login. Make sure to save them somewhere. + + .. code-block:: text + + Jan 24 05:51:28.443 WRN Generated super admin credentials login=admin password=qF3A5rjGurjAwmlYccJ7JrL5XqjbIHY6 + + +The :ref:`--storage.etcd.embed.enabled ` +option makes |tcm| start its own instance of `etcd `__ on bootstrap. +This ``etcd`` instance is used for storing the :ref:`TCM configuration `. + +.. note:: + + During the development, it is also convenient to use the TCM-embedded etcd + as a configuration storage for Tarantool EE clusters connected to TCM. + Learn more in :ref:`configuration_etcd`. + +.. _getting_started_tcm_login: + +Logging into TCM +---------------- + +#. Open a web browser and go to ``http://127.0.0.1:8080/``. +#. Enter the username and the password you got from the |tcm| bootstrap log in the previous step. +#. Click **Log in**. + +After a successful login, you see the |tcm| web UI: + +.. image:: images/tcm_start_empty_cluster.png + :width: 700 + :align: center + :alt: TCM stateboard with empty cluster + +.. _getting_started_tcm_cluster: + +Setting up a Tarantool EE cluster +--------------------------------- + +To prepare a Tarantool EE cluster, complete the following steps: + +#. Define the cluster connection settings in |tcm|. +#. Configure the cluster in |tcm|. +#. Start the cluster instances locally using the :ref:`tt ` utility. + +.. _getting_started_tcm_cluster_connection: + +Defining the cluster's connection settings in TCM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A freshly installed |TCM| has a predefined cluster named **Default cluster**. It +doesn't have any configuration or topology out of the box. Its initial properties +include the etcd and Tarantool connection parameters. Check these properties +to find out where TCM sends the cluster configuration that you write. + +To view the **Default cluster**'s properties: + +#. Go to **Clusters** and click **Edit** in the **Actions** menu opposite the cluster name. + + .. image:: images/tcm_start_cluster_edit.png + :width: 700 + :align: center + :alt: TCM edit cluster + +#. Click **Next** on the **General** tab. + + .. image:: images/tcm_start_cluster_general.png + :width: 700 + :align: center + :alt: General cluster settings + +#. Find the connection properties of the configuration storage that the cluster uses. + By default, it's an etcd running on port ``2379`` (default etcd port) on the same host. + The key prefix used for the cluster configuration is ``/default``. Click **Next**. + + .. image:: images/tcm_start_cluster_storage.png + :width: 700 + :align: center + :alt: Cluster configuration storage settings + +#. Check the Tarantool user that |tcm| uses to connect to the cluster instances. + It's ``guest`` by default. + + .. image:: images/tcm_start_cluster_tarantool.png + :width: 700 + :align: center + :alt: Cluster Tarantool connection settings + + +.. _getting_started_tcm_cluster_config: + +Configuring a cluster in TCM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +|tcm| provides a web-based editor for writing cluster configurations. It is connected +to the configuration storage (etcd in this case): all changes you make in the browser +are sent to etcd in one click. + +To write the cluster configuration and upload it to the etcd storage: + +#. Go to **Configuration**. +#. Click **+** and provide an arbitrary name for the configuration file, for example, ``all``. +#. Paste the following :ref:`YAML configuration ` into the editor: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/cluster.yaml + :language: yaml + :dedent: + + This configuration sets up a cluster of three nodes in one replica set: + one leader and two followers. + +#. Click **Apply** to send the configuration to etcd. + + .. image:: images/tcm_start_cluster_config.png + :width: 700 + :align: center + :alt: Cluster configuration in TCM + +When the cluster configuration is saved, you can see the cluster topology on the **Stateboard** page: + +.. image:: images/tcm_start_stateboard_offline.png + :width: 700 + :align: center + :alt: Offline cluster stateboard + +However, the cluster instances are offline because they aren't deployed yet. + +.. _getting_started_tcm_cluster_deploy: + +Deploying the cluster locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To deploy a local cluster based on the configuration from etcd: + +#. Go to the system terminal you used when setting up Tarantool. +#. Create a new ``tt`` environment in a directory of your choice: + + .. code-block:: console + + $ mkdir cluster-env + $ cd cluster-env/ + $ tt init + +#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``cluster`` directory. + + .. code-block:: console + + $ mkdir instances.enabled/cluster + $ cd instances.enabled/cluster/ + +#. Inside ``instances.enabled/cluster``, create the ``instances.yml`` and ``config.yaml`` files: + + * ``instances.yml`` specifies instances to run in the current environment. In this example, there are three instances: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/instances.yml + :language: yaml + :dedent: + + * ``config.yaml`` instructs ``tt`` to load the cluster configuration from etcd. + The specified etcd location matches the configuration storage of the **Default cluster** in TCM: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/config.yaml + :language: yaml + :dedent: + +#. Start the cluster from the ``tt`` environment root (the ``cluster-env`` directory): + + .. code-block:: console + + $ tt start cluster + + To check how the cluster started, run ``tt status``. This output should look like this: + + .. code-block:: console + + $ tt status cluster + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + cluster:instance-001 RUNNING 8747 RW ready running -- + cluster:instance-002 RUNNING 8748 RO ready running -- + cluster:instance-003 RUNNING 8749 RO ready running -- + +.. _getting_started_tcm_manage: + +Managing the cluster in TCM +--------------------------- + +To learn to interact with a cluster in |tcm|, complete typical database tasks such as: + +* Checking the cluster state. +* Creating a space. +* Writing data. +* Viewing data. + +.. _getting_started_tcm_manage_check: + +Checking cluster state +~~~~~~~~~~~~~~~~~~~~~~ + +To check the cluster state in |tcm|, go to **Stateboard**. Here you see the overview +of the cluster topology, health, memory consumption, and other information. + +.. image:: images/tcm_start_stateboard_online.png + :width: 700 + :align: center + :alt: Online cluster stateboard + +.. _getting_started_tcm_manage_connect: + +Connecting to an instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view detailed information about an instance, click its name in the instances list +on the **Stateboard** page. + +.. image:: images/tcm_start_instance_details.png + :width: 700 + :align: center + :alt: Instance details in TCM + +To connect to the instance interactively and execute code on it, go to the **Terminal** tab. + +.. image:: images/tcm_start_instance_terminal.png + :width: 700 + :align: center + :alt: Instance terminal in TCM + +.. _getting_started_tcm_manage_space: + +Creating a space +~~~~~~~~~~~~~~~~ + +Go to the terminal of ``instance-001`` (the leader instance) and run the following code to +create a formatted space with a primary index in the cluster: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua + :language: lua + :start-at: box.schema.space.create + :end-at: box.space.bands:create_index + :dedent: + +.. _getting_started_tcm_manage_write: + +Writing data +~~~~~~~~~~~~ + +Since ``instance-001`` is a read-write instance (its ``box.info.ro`` is ``false``), +the write requests must be executed on it. Run the following code in the ``instance-001`` +terminal to write tuples in the space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua + :language: lua + :start-at: 'Roxette' + :end-at: 'Ace of Base' + :dedent: + +.. _getting_started_tcm_manage_read: + +Reading data +~~~~~~~~~~~~ + +Check the space's tuples by running a read request on ``instance-001``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started/myapp.lua + :language: lua + :start-at: box.space.bands:select + :end-at: box.space.bands:select + :dedent: + +This is how it looks in |tcm|: + +.. image:: images/tcm_start_instance_write.png + :width: 700 + :align: center + :alt: Writing data through TCM + +.. _getting_started_tcm_manage_replication: + +Checking replication +~~~~~~~~~~~~~~~~~~~~ + +To check that the data is replicated across instances, run the read request on any +other instance -- ``instance-002`` or ``instance-003``. The result is the same as on ``instance-001``. + +.. image:: images/tcm_start_instance_read.png + :width: 700 + :align: center + :alt: Reading data through TCM + +.. note:: + + If you try to execute a write request on any instance but ``instance-001``, + you get an error because these instances are configured to be read-only. + +.. _getting_started_tcm_manage_view: + +Viewing data in TCM +~~~~~~~~~~~~~~~~~~~ + +|tcm| web UI includes a tool for viewing data stored in the cluster. To view +the space tuples in |tcm|: + +#. Click an instance name on the **Stateboard** page. +#. Open the **Actions** menu in the top-right corner and click **Explorer**. + + .. image:: images/tcm_start_explorer.png + :width: 700 + :align: center + :alt: Opening Explorer in TCM + + This opens the page that lists user-created spaces on the instance. + + .. image:: images/tcm_start_explorer_spaces.png + :width: 700 + :align: center + :alt: TCM Explorer: spaces + +#. Click **View** in the **Actions** menu of the space you want to see. The page + shows all the tuples added previously. + + .. image:: images/tcm_start_explorer_tuples.png + :width: 700 + :align: center + :alt: TCM Explorer: space tuples diff --git a/doc/getting_started/images/configuring-server.png b/doc/getting_started/images/configuring-server.png deleted file mode 100644 index 0ee06f3d07..0000000000 Binary files a/doc/getting_started/images/configuring-server.png and /dev/null differ diff --git a/doc/getting_started/images/console.png b/doc/getting_started/images/console.png deleted file mode 100755 index 602357530e..0000000000 Binary files a/doc/getting_started/images/console.png and /dev/null differ diff --git a/doc/getting_started/images/first-configuration-result.png b/doc/getting_started/images/first-configuration-result.png deleted file mode 100644 index f1bdee66a7..0000000000 Binary files a/doc/getting_started/images/first-configuration-result.png and /dev/null differ diff --git a/doc/getting_started/images/hosts-list.png b/doc/getting_started/images/hosts-list.png deleted file mode 100644 index 199bfe814b..0000000000 Binary files a/doc/getting_started/images/hosts-list.png and /dev/null differ diff --git a/doc/getting_started/images/hosts.png b/doc/getting_started/images/hosts.png deleted file mode 100644 index 59f41c98a3..0000000000 Binary files a/doc/getting_started/images/hosts.png and /dev/null differ diff --git a/doc/getting_started/images/likes.png b/doc/getting_started/images/likes.png deleted file mode 100644 index 164b1daf82..0000000000 Binary files a/doc/getting_started/images/likes.png and /dev/null differ diff --git a/doc/getting_started/images/router-configuration.png b/doc/getting_started/images/router-configuration.png deleted file mode 100644 index 12129afa9c..0000000000 Binary files a/doc/getting_started/images/router-configuration.png and /dev/null differ diff --git a/doc/getting_started/images/scaling.png b/doc/getting_started/images/scaling.png deleted file mode 100644 index d2e75a89eb..0000000000 Binary files a/doc/getting_started/images/scaling.png and /dev/null differ diff --git a/doc/getting_started/images/storage-configuration.png b/doc/getting_started/images/storage-configuration.png deleted file mode 100644 index d9a9d7f424..0000000000 Binary files a/doc/getting_started/images/storage-configuration.png and /dev/null differ diff --git a/doc/getting_started/images/tcm_start_cluster_config.png b/doc/getting_started/images/tcm_start_cluster_config.png new file mode 100644 index 0000000000..ba69fbe0f5 Binary files /dev/null and b/doc/getting_started/images/tcm_start_cluster_config.png differ diff --git a/doc/getting_started/images/tcm_start_cluster_edit.png b/doc/getting_started/images/tcm_start_cluster_edit.png new file mode 100644 index 0000000000..0b92eeb52f Binary files /dev/null and b/doc/getting_started/images/tcm_start_cluster_edit.png differ diff --git a/doc/getting_started/images/tcm_start_cluster_general.png b/doc/getting_started/images/tcm_start_cluster_general.png new file mode 100644 index 0000000000..cf03802876 Binary files /dev/null and b/doc/getting_started/images/tcm_start_cluster_general.png differ diff --git a/doc/getting_started/images/tcm_start_cluster_storage.png b/doc/getting_started/images/tcm_start_cluster_storage.png new file mode 100644 index 0000000000..0a5090d965 Binary files /dev/null and b/doc/getting_started/images/tcm_start_cluster_storage.png differ diff --git a/doc/getting_started/images/tcm_start_cluster_tarantool.png b/doc/getting_started/images/tcm_start_cluster_tarantool.png new file mode 100644 index 0000000000..785115fca5 Binary files /dev/null and b/doc/getting_started/images/tcm_start_cluster_tarantool.png differ diff --git a/doc/getting_started/images/tcm_start_empty_cluster.png b/doc/getting_started/images/tcm_start_empty_cluster.png new file mode 100644 index 0000000000..4b1199a28e Binary files /dev/null and b/doc/getting_started/images/tcm_start_empty_cluster.png differ diff --git a/doc/getting_started/images/tcm_start_explorer.png b/doc/getting_started/images/tcm_start_explorer.png new file mode 100644 index 0000000000..d39b8528fb Binary files /dev/null and b/doc/getting_started/images/tcm_start_explorer.png differ diff --git a/doc/getting_started/images/tcm_start_explorer_spaces.png b/doc/getting_started/images/tcm_start_explorer_spaces.png new file mode 100644 index 0000000000..8a1718e43b Binary files /dev/null and b/doc/getting_started/images/tcm_start_explorer_spaces.png differ diff --git a/doc/getting_started/images/tcm_start_explorer_tuples.png b/doc/getting_started/images/tcm_start_explorer_tuples.png new file mode 100644 index 0000000000..2472d756e9 Binary files /dev/null and b/doc/getting_started/images/tcm_start_explorer_tuples.png differ diff --git a/doc/getting_started/images/tcm_start_instance_details.png b/doc/getting_started/images/tcm_start_instance_details.png new file mode 100644 index 0000000000..aec6843617 Binary files /dev/null and b/doc/getting_started/images/tcm_start_instance_details.png differ diff --git a/doc/getting_started/images/tcm_start_instance_read.png b/doc/getting_started/images/tcm_start_instance_read.png new file mode 100644 index 0000000000..5481ac5f80 Binary files /dev/null and b/doc/getting_started/images/tcm_start_instance_read.png differ diff --git a/doc/getting_started/images/tcm_start_instance_terminal.png b/doc/getting_started/images/tcm_start_instance_terminal.png new file mode 100644 index 0000000000..acc7136b74 Binary files /dev/null and b/doc/getting_started/images/tcm_start_instance_terminal.png differ diff --git a/doc/getting_started/images/tcm_start_instance_write.png b/doc/getting_started/images/tcm_start_instance_write.png new file mode 100644 index 0000000000..1b0ba4f4e4 Binary files /dev/null and b/doc/getting_started/images/tcm_start_instance_write.png differ diff --git a/doc/getting_started/images/tcm_start_stateboard_offline.png b/doc/getting_started/images/tcm_start_stateboard_offline.png new file mode 100644 index 0000000000..2828506cdc Binary files /dev/null and b/doc/getting_started/images/tcm_start_stateboard_offline.png differ diff --git a/doc/getting_started/images/tcm_start_stateboard_online.png b/doc/getting_started/images/tcm_start_stateboard_online.png new file mode 100644 index 0000000000..c712544bec Binary files /dev/null and b/doc/getting_started/images/tcm_start_stateboard_online.png differ diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index 3fdcd016a8..61ee8b4f89 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -3,41 +3,17 @@ .. _getting_started: -******************************************************************************** Getting started -******************************************************************************** +*************** -The :ref:`First steps ` section -will get you acquainted with Tarantool in 15 minutes. -We will be creating a basic microservice for TikTok. -We will start Tarantool, create a data schema, and write our first data. -You'll get an understanding of the technology and learn about the basic terms and features. +.. TODO: New Getting Started https://github.com/tarantool/doc/issues/3636 -In the :ref:`Connecting to cluster ` section, -we'll show you how to read or write data to Tarantool -from your Python/Go/PHP application or another programming language. +This section will get you acquainted with Tarantool. -After connecting to the database for the first time, you might want to change the data schema. -In the section :ref:`Updating the data schema `, -we'll discuss the approaches to changing the data schema and the associated limitations. +.. toctree:: + :maxdepth: 1 -To make our code work with Tarantool, -we may want to transfer some of our data logic to Tarantool. -In the section :ref:`Writing cluster application code `, -we'll write a "Hello, World!" program in the Lua language, -which will work in our Tarantool cluster. -This will give you a basic understanding of how the role mechanism works. -In this way, you'll understand what part of your business logic you would like -to write in/migrate to Tarantool. - -.. toctree:: - :maxdepth: 1 - - getting_started_imcp - connecting_to_cluster - change_schema_dynamically - writing_cluster_code - -To continue exploring Tarantool and its ecosystem, you might want to check out -Tarantool :doc:`tutorials and guides <../how-to/index>`. -The :ref:`Cartridge beginner tutorial ` can also be found there. + installation + getting_started_db + vshard_quick + getting_started_tcm diff --git a/doc/getting_started/installation.rst b/doc/getting_started/installation.rst new file mode 100644 index 0000000000..79600bec4f --- /dev/null +++ b/doc/getting_started/installation.rst @@ -0,0 +1,172 @@ +.. _tarantool_installation: + +Installing Tarantool +==================== + +This section explains how to download and set up :ref:`Tarantool Enterprise Edition ` and run +a sample application provided with it. +To learn how to download and install Tarantool Community Edition, see the `Download `_ page. + +.. NOTE:: + + The :ref:`tt ` utility provides the ability to install and work with multiple Tarantool versions. + + +.. _enterprise-prereqs: + +System requirements +------------------- + +The recommended system requirements for running Tarantool Enterprise are as +follows. + +.. _enterprise-prereqs-hardware: + +Hardware requirements +~~~~~~~~~~~~~~~~~~~~~ + +To fully ensure the fault tolerance of a distributed data storage system, at +least **three** physical computers or virtual servers are required. + +For testing/development purposes, the system can be deployed using a smaller number of servers. +However, it is not recommended to use such configurations for production. + +.. _enterprise-prereqs-software: + +Software requirements +~~~~~~~~~~~~~~~~~~~~~ + +#. As host operating systems, Tarantool Enterprise Edition supports + **Red Hat Enterprise Linux** and **CentOS** versions 7.5 and higher. + + .. NOTE:: + + Tarantool Enterprise can run on other ``systemd``-based Linux distributions + but it is not tested on them and may not work as expected. + +#. ``glibc`` 2.17-260.el7_6.6 and higher is required. Take care to check and + update, if needed: + + .. code-block:: console + + $ rpm -q glibc + glibc-2.17-196.el7_4.2 + $ yum update glibc + +.. _enterprise-prereqs-network: + +Network requirements +~~~~~~~~~~~~~~~~~~~~ + +Hereinafter, **"storage servers"** or **"Tarantool servers"** are the computers +used to store and process data, and **"administration server"** is the computer +used by the system operator to install and configure the product. + +The Tarantool cluster has a full mesh topology, therefore all Tarantool servers +should be able to communicate and send traffic from and to TCP/UDP ports +used by the cluster's instances (see ``advertise_uri: :`` and +``config: advertise_uri: ':'`` in ``/etc/tarantool/conf.d/*.yml`` +for each instance). For example: + +.. code-block:: kconfig + + # /etc/tarantool/conf.d/*.yml + + myapp.s2-replica: + advertise_uri: localhost:3305 # this is a TCP/UDP port + http_port: 8085 + + all: + ... + hosts: + storage-1: + config: + advertise_uri: 'vm1:3301' # this is a TCP/UDP port + http_port: 8081 + +To configure remote monitoring or to connect via the administrative console, +the administration server should be able to access the following TCP ports on +Tarantool servers: + +* 22 to use the SSH protocol, +* ports specified in instance configuration to monitor the HTTP-metrics. + +Additionally, it is recommended to apply the following settings for ``sysctl`` +on all Tarantool servers: + +.. code-block:: console + + $ # TCP KeepAlive setting + $ sysctl -w net.ipv4.tcp_keepalive_time=60 + $ sysctl -w net.ipv4.tcp_keepalive_intvl=5 + $ sysctl -w net.ipv4.tcp_keepalive_probes=5 + +This optional setup of the Linux network stack helps speed up the troubleshooting +of network connectivity when the server physically fails. To achieve maximum +performance, you may also need to configure other network stack parameters that +are not specific to the Tarantool DBMS. For more information, please refer to the +`Network Performance Tuning Guide `_ +section of the RHEL7 user documentation. + +.. _enterprise-package-contents: + +Package contents +---------------- + +The latest release packages of Tarantool Enterprise are available in the +`customer zone `_ +at Tarantool website. Please contact ``support@tarantool.io`` for access. + +Each package is distributed as a ``tar + gzip`` archive and includes +the following components and features: + +* Static Tarantool binary for simplified deployment in Linux environments. +* ``tt`` command-line utility that provides a unified command-line interface for + managing Tarantool-based applications. See :ref:`tt-cli` for details. +* |tcm_full_name| -- a web-based interface for managing Tarantool EE clusters. + See :ref:`tcm` for details. +* Selection of open and closed source modules. +* Sample application walking you through all included modules + +Archive contents: + +* ``tarantool`` is the main executable of Tarantool. +* ``tt`` command-line utility. +* ``tcm`` is the |tcm_full_name| executable. +* ``examples/`` is the directory containing sample applications: + + * ``pg_writethrough_cache/`` is an application showcasing how Tarantool can + cache data written to, for example, a PostgreSQL database; + * ``ora_writebehind_cache/`` is an application showcasing how Tarantool can + cache writes and queue them to, for example, an Oracle database; + * ``docker/`` is an application designed to be easily packed into a Docker + container; + +* ``rocks/`` is the directory containing a selection of additional open and + closed source modules included in the distribution as an offline rocks + repository. See the :ref:`rocks reference ` for details. +* ``templates/`` is the directory containing template files for your application + development environment. + +.. _archive-unpack: +.. _enterprise-install: + +Installation +------------ + +The delivered ``tar + gzip`` archive should be uploaded to a server and unpacked: + +.. code-block:: console + + $ tar xvf tarantool-enterprise-sdk-.tar.gz + +No further installation is required as the unpacked binaries are almost ready +to go. Go to the directory with the binaries (``tarantool-enterprise``) and +add them to the executable path by running the script provided by the distribution: + +.. code-block:: console + + $ source ./env.sh + +Make sure you have enough privileges to run the script and that the file is executable. +Otherwise, try ``chmod`` and ``chown`` commands to adjust it. diff --git a/doc/getting_started/vshard_quick.rst b/doc/getting_started/vshard_quick.rst new file mode 100644 index 0000000000..0ba45aa5ae --- /dev/null +++ b/doc/getting_started/vshard_quick.rst @@ -0,0 +1,498 @@ +.. _vshard-quick-start: + +Creating a sharded cluster +========================== + +**Example on GitHub**: `sharded_cluster_crud `_ + +In this tutorial, you get a sharded cluster up and running on your local machine and learn how to manage the cluster using the tt utility. +This cluster uses the following external modules: + +- :ref:`vshard ` enables sharding in the cluster. +- `crud `__ allows you to manipulate data in the sharded cluster. + +The cluster created in this tutorial includes 5 instances: one router and 4 storages, which constitute two replica sets. + +.. image:: /admin/admin_instances_dev.png + :align: left + :width: 700 + :alt: Cluster topology + + +.. _vshard-quick-start-prerequisites: + +Prerequisites +------------- + +Before starting this tutorial: + +* :ref:`Install the tt ` utility. +* `Install tarantool `_. + + .. NOTE:: + + The tt utility provides the ability to install Tarantool software using the :ref:`tt install ` command. + + +.. _vshard-quick-start-creating-app: + +Creating a cluster application +------------------------------ + +The :ref:`tt create ` command can be used to create an application from a predefined or custom template. +For example, the built-in ``vshard_cluster`` template enables you to create a ready-to-run sharded cluster application. + +In this tutorial, the application layout is prepared manually: + +1. Create a tt environment in the current directory by executing the :ref:`tt init ` command. + +2. Inside the empty ``instances.enabled`` directory of the created tt environment, create the ``sharded_cluster_crud`` directory. + +3. Inside ``instances.enabled/sharded_cluster_crud``, create the following files: + + - ``instances.yml`` specifies instances to run in the current environment. + - ``config.yaml`` specifies the cluster :ref:`configuration `. + - ``storage.lua`` contains code specific for :ref:`storages `. + - ``router.lua`` contains code specific for a :ref:`router `. + - ``sharded_cluster_crud-scm-1.rockspec`` specifies external dependencies required by the application. + + The next :ref:`vshard-quick-start-developing-app` section shows how to configure the cluster and write code for routing read and write requests to different storages. + + +.. _vshard-quick-start-developing-app: + +Developing the application +-------------------------- + +.. _vshard-quick-start-configuring-instances: + +Configuring instances to run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open the ``instances.yml`` file and add the following content: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/instances.yaml + :language: yaml + :dedent: + +This file specifies instances to run in the current environment. + + +.. _vshard-quick-start-configuring-cluster: + +Configuring the cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to configure the cluster in the ``config.yaml`` file. + +.. _vshard-quick-start-configuring-cluster-credentials: + +Step 1: Configuring credentials +******************************* + +Add the :ref:`credentials ` configuration section: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-at: credentials: + :end-at: roles: [ sharding ] + :dedent: + +In this section, two users with the specified passwords are created: + +* The ``replicator`` user with the ``replication`` role. +* The ``storage`` user with the ``sharding`` role. + +These users are intended to maintain replication and sharding in the cluster. + +.. IMPORTANT:: + + It is not recommended to store passwords as plain text in a YAML configuration. + Learn how to load passwords from safe storage such as external files or environment variables from :ref:`configuration_credentials_loading_secrets`. + + + +.. _vshard-quick-start-configuring-cluster-advertise: + +Step 2: Specifying advertise URIs +********************************* + +Add the :ref:`iproto.advertise ` section: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-after: roles: [ sharding ] + :end-at: login: storage + :dedent: + +In this section, the following options are configured: + +* ``iproto.advertise.peer`` specifies how to advertise the current instance to other cluster members. + In particular, this option informs other replica set members that the ``replicator`` user should be used to connect to the current instance. +* ``iproto.advertise.sharding`` specifies how to advertise the current instance to a router and rebalancer. + +The cluster topology defined in the :ref:`following section ` also specifies the ``iproto.advertise.client`` option for each instance. +This option accepts a URI used to advertise the instance to clients. +For example, :ref:`Tarantool Cluster Manager ` uses these URIs to :ref:`connect ` to cluster instances. + + +.. _vshard-quick-start-configuring-cluster-bucket-count: + +Step 3: Configuring bucket count +******************************** + +Specify the total number of :ref:`buckets ` in a sharded cluster using the :ref:`sharding.bucket_count ` option: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-after: login: storage + :end-at: bucket_count + :dedent: + + +.. _vshard-quick-start-configuring-cluster-topology: + +Step 4: Defining the cluster topology +************************************* + +Define the cluster topology inside the :ref:`groups ` section. +The cluster includes two groups: + +* ``storages`` includes two replica sets. Each replica set contains two instances. +* ``routers`` includes one router instance. + +Here is a schematic view of the cluster topology: + +.. code-block:: yaml + + groups: + storages: + replicasets: + storage-a: + # ... + storage-b: + # ... + routers: + replicasets: + router-a: + # ... + +1. To configure storages, add the following code inside the ``groups`` section: + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-at: storages: + :end-at: client: '127.0.0.1:3305' + :dedent: + + The main group-level options here are: + + * ``roles``: This option enables the ``roles.crud-storage`` :ref:`role ` provided by the CRUD module for all storage instances. + * ``app``: The ``app.module`` option specifies that code specific to storages should be loaded from the ``storage`` module. This is explained below in the :ref:`vshard-quick-start-storage-code` section. + * ``sharding``: The :ref:`sharding.roles ` option specifies that all instances inside this group act as storages. + A rebalancer is selected automatically from two master instances. + * ``replication``: The :ref:`replication.failover ` option specifies that a leader in each replica set should be specified manually. + * ``replicasets``: This section configures two replica sets that constitute cluster storages. + + +2. To configure a router, add the following code inside the ``groups`` section: + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-at: routers: + :end-at: client: '127.0.0.1:3301' + :dedent: + + The main group-level options here are: + + * ``roles``: This option enables the ``roles.crud-router`` :ref:`role ` provided by the CRUD module for a router instance. + * ``app``: The ``app.module`` option specifies that code specific to a router should be loaded from the ``router`` module. This is explained below in the :ref:`vshard-quick-start-router-code` section. + * ``sharding``: The :ref:`sharding.roles ` option specifies that an instance inside this group acts as a router. + * ``replicasets``: This section configures a replica set with one router instance. + + +Resulting configuration +*********************** + +The resulting ``config.yaml`` file should look as follows: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :dedent: + + +.. _vshard-quick-start-storage-code: + +Adding storage code +~~~~~~~~~~~~~~~~~~~ + +Open the ``storage.lua`` file and define a space and indexes inside :ref:`box.watch() ` as follows: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua + :language: lua + :dedent: + +* The :ref:`box.schema.create_space() ` function creates a space. + Note that the created ``bands`` space includes the ``bucket_id`` field. + This field represents a sharding key used to partition a dataset across different storage instances. +* :ref:`space_object:create_index() ` creates two indexes based on the ``id`` and ``bucket_id`` fields. + + + +.. _vshard-quick-start-router-code: + +Adding router code +~~~~~~~~~~~~~~~~~~ + +Open the ``router.lua`` file and load the ``vshard`` module as follows: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua + :language: lua + :start-at: local vshard + :end-at: local vshard + :dedent: + + + +.. _vshard-quick-start-build-settings: + +Configuring build settings +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open the ``sharded_cluster_crud-scm-1.rockspec`` file and add the following content: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec + :language: none + :dedent: + +The ``dependencies`` section includes the specified versions of the ``vshard`` and ``crud`` modules. +To install dependencies, you need to :ref:`build the application `. + + +.. _vshard-quick-start-building-app: + +Building the application +------------------------ + +In the terminal, open the :ref:`tt environment directory `. +Then, execute the ``tt build`` command: + +.. code-block:: console + + $ tt build sharded_cluster_crud + • Running rocks make + No existing manifest. Attempting to rebuild... + • Application was successfully built + +This installs the ``vshard`` and ``crud`` modules defined in the :ref:`*.rockspec ` file to the ``.rocks`` directory. + + + +.. _vshard-quick-start-working-cluster: + +Working with the cluster +------------------------ + +.. _vshard-quick-start-working-starting-instances: + +Starting instances +~~~~~~~~~~~~~~~~~~ + +To start all instances in the cluster, execute the ``tt start`` command: + +.. code-block:: console + + $ tt start sharded_cluster_crud + • Starting an instance [sharded_cluster_crud:storage-a-001]... + • Starting an instance [sharded_cluster_crud:storage-a-002]... + • Starting an instance [sharded_cluster_crud:storage-b-001]... + • Starting an instance [sharded_cluster_crud:storage-b-002]... + • Starting an instance [sharded_cluster_crud:router-a-001]... + + +.. _vshard-quick-start-working-bootstrap: + +Bootstrapping a cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +After starting instances, you need to bootstrap the cluster as follows: + +1. Connect to the router instance using ``tt connect``: + + .. code-block:: console + + $ tt connect sharded_cluster_crud:router-a-001 + • Connecting to the instance... + • Connected to sharded_cluster_crud:router-a-001 + +2. Call :ref:`vshard.router.bootstrap() ` to perform the initial cluster bootstrap and distribute all buckets across the replica sets: + + .. code-block:: tarantoolsession + + sharded_cluster_crud:router-a-001> vshard.router.bootstrap() + --- + - true + ... + + +.. _vshard-quick-start-working-status: + +Checking the cluster status +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To check the cluster status, execute :ref:`vshard.router.info() ` on the router: + +.. code-block:: tarantoolsession + + sharded_cluster_crud::router-a-001> vshard.router.info() + --- + - replicasets: + storage-b: + replica: + network_timeout: 0.5 + status: available + uri: storage@127.0.0.1:3305 + name: storage-b-002 + bucket: + available_rw: 500 + master: + network_timeout: 0.5 + status: available + uri: storage@127.0.0.1:3304 + name: storage-b-001 + name: storage-b + storage-a: + replica: + network_timeout: 0.5 + status: available + uri: storage@127.0.0.1:3303 + name: storage-a-002 + bucket: + available_rw: 500 + master: + network_timeout: 0.5 + status: available + uri: storage@127.0.0.1:3302 + name: storage-a-001 + name: storage-a + bucket: + unreachable: 0 + available_ro: 0 + unknown: 0 + available_rw: 1000 + status: 0 + alerts: [] + ... + +The output includes the following sections: + +* ``replicasets``: contains information about storages and their availability. +* ``bucket``: displays the total number of read-write and read-only buckets that are currently available for this router. +* ``status``: the number from 0 to 3 that indicates whether there are any issues with the cluster. + 0 means that there are no issues. +* ``alerts``: might describe the exact issues related to bootstrapping a cluster, for example, connection issues, failover events, or unidentified buckets. + + +.. _vshard-quick-start-working-writing-selecting-data: + +Writing and selecting data +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. To insert sample data, call ``crud.insert_many()`` on the router: + + .. code-block:: lua + + crud.insert_many('bands', { + { 1, box.NULL, 'Roxette', 1986 }, + { 2, box.NULL, 'Scorpions', 1965 }, + { 3, box.NULL, 'Ace of Base', 1987 }, + { 4, box.NULL, 'The Beatles', 1960 }, + { 5, box.NULL, 'Pink Floyd', 1965 }, + { 6, box.NULL, 'The Rolling Stones', 1962 }, + { 7, box.NULL, 'The Doors', 1965 }, + { 8, box.NULL, 'Nirvana', 1987 }, + { 9, box.NULL, 'Led Zeppelin', 1968 }, + { 10, box.NULL, 'Queen', 1970 } + }) + + Calling this function :ref:`distributes data ` evenly across the cluster nodes. + +2. To get a tuple by the specified ID, call the ``crud.get()`` function: + + .. code-block:: tarantoolsession + + sharded_cluster_crud:router-a-001> crud.get('bands', 4) + --- + - rows: + - [4, 161, 'The Beatles', 1960] + metadata: [{'name': 'id', 'type': 'unsigned'}, {'name': 'bucket_id', 'type': 'unsigned'}, + {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'unsigned'}] + - null + ... + +3. To insert a new tuple, call ``crud.insert()``: + + .. code-block:: tarantoolsession + + sharded_cluster_crud:router-a-001> crud.insert('bands', {11, box.NULL, 'The Who', 1962}) + --- + - rows: + - [11, 652, 'The Who', 1962] + metadata: [{'name': 'id', 'type': 'unsigned'}, {'name': 'bucket_id', 'type': 'unsigned'}, + {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'unsigned'}] + - null + ... + + + + +.. _vshard-quick-start-working-adding-data: + +Checking data distribution +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To check how data is distributed across the replica sets, follow the steps below: + +1. Connect to any storage in the ``storage-a`` replica set: + + .. code-block:: console + + $ tt connect sharded_cluster_crud:storage-a-001 + • Connecting to the instance... + • Connected to sharded_cluster_crud:storage-a-001 + + Then, select all tuples in the ``bands`` space: + + .. code-block:: tarantoolsession + + sharded_cluster_crud:storage-a-001> box.space.bands:select() + --- + - - [1, 477, 'Roxette', 1986] + - [2, 401, 'Scorpions', 1965] + - [4, 161, 'The Beatles', 1960] + - [5, 172, 'Pink Floyd', 1965] + - [6, 64, 'The Rolling Stones', 1962] + - [8, 185, 'Nirvana', 1987] + ... + + +2. Connect to any storage in the ``storage-b`` replica set: + + .. code-block:: console + + $ tt connect sharded_cluster_crud:storage-b-001 + • Connecting to the instance... + • Connected to sharded_cluster_crud:storage-b-001 + + Select all tuples in the ``bands`` space to make sure it contains another subset of data: + + .. code-block:: tarantoolsession + + sharded_cluster_crud:storage-b-001> box.space.bands:select() + --- + - - [3, 804, 'Ace of Base', 1987] + - [7, 693, 'The Doors', 1965] + - [9, 644, 'Led Zeppelin', 1968] + - [10, 569, 'Queen', 1970] + - [11, 652, 'The Who', 1962] + ... diff --git a/doc/getting_started/writing_cluster_code.rst b/doc/getting_started/writing_cluster_code.rst deleted file mode 100644 index 7a8f8ec10a..0000000000 --- a/doc/getting_started/writing_cluster_code.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _getting_started-wrirting_cluster-code: - -================================================================================= -Writing code in a cluster application -================================================================================= - -In the "Getting Started" tutorial, -we wrote the application code directly in the browser. -We used the file ``config.yml`` to describe HTTP endpoint handlers. -This is a convenient and fast way to write code -that allows you to use Tarantool as a repository without any additional HTTP service. -This functionality is implemented through the ``cartridge-extensions`` module. -It is also included in the tutorial default application. - -However, in Tarantool, you can implement absolutely any business logic on top of a cluster. -This :doc:`Cartridge getting started section ` -covers the cluster roles mechanism and writing a cluster application from scratch. diff --git a/doc/how-to/app/index.rst b/doc/how-to/app/index.rst deleted file mode 100644 index 9600843978..0000000000 --- a/doc/how-to/app/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _how-to-app-server: - -Developing applications with Tarantool -====================================== - -Using Tarantool as an application server, you can write your own applications. -Tarantool’s native language for writing applications is -`Lua `_, so a typical application would be -a file that contains your Lua script. But you can also write applications -in C or C++. - -.. toctree:: - :maxdepth: 1 - - launching_app - creating_app - using_ide - cookbook - lua_tutorials - c_tutorial diff --git a/doc/how-to/db/index.rst b/doc/how-to/db/index.rst deleted file mode 100644 index 184a2cf2a1..0000000000 --- a/doc/how-to/db/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Defining and manipulating data -============================== - -This section contains guides on performing data operations in Tarantool. - -.. toctree:: - :maxdepth: 1 - - crud - indexes - sequences diff --git a/doc/how-to/getting_started_cartridge.rst b/doc/how-to/getting_started_cartridge.rst deleted file mode 100644 index dc21e2edc2..0000000000 --- a/doc/how-to/getting_started_cartridge.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. _getting_started_cartridge: - -Creating your first Tarantool Cartridge application -=================================================== - -Here we'll walk you through developing a simple cluster application. - -First, -:doc:`set up the development environment `. - -Next, create an application named ``myapp``. Run: - -.. code-block:: console - - $ cartridge create --name myapp - -This will create a Tarantool Cartridge application in the ``./myapp`` directory, -with a handful of -:doc:`template files and directories ` -inside. - -Go inside and make a dry run: - -.. code-block:: console - - $ cd ./myapp - $ cartridge build - $ cartridge start - -This will build the application locally, start 5 instances of Tarantool -and a :ref:`stateboard ` (state provider), and -run the application as it is, with no business logic yet. - -Why 5 instances and a stateboard? See the ``instances.yml`` file in your application directory. -It contains the :ref:`configuration ` of all instances -that you can use in the cluster. By default, it defines configuration for 5 -Tarantool instances and a stateboard. - -.. code-block:: yaml - - --- - myapp.router: - advertise_uri: localhost:3301 - http_port: 8081 - - myapp.s1-master: - advertise_uri: localhost:3302 - http_port: 8082 - - myapp.s1-replica: - advertise_uri: localhost:3303 - http_port: 8083 - - myapp.s2-master: - advertise_uri: localhost:3304 - http_port: 8084 - - myapp.s2-replica: - advertise_uri: localhost:3305 - http_port: 8085 - - myapp-stateboard: - listen: localhost:4401 - password: passwd - -You can already see these instances in the cluster management web interface at -http://localhost:8081 (here 8081 is the HTTP port of the first instance -specified in ``instances.yml``). - -.. image:: images/cluster_dry_run-border-5px.png - :align: center - :scale: 40% - -Okay, press ``Ctrl + C`` to stop the cluster for a while. - -Now it’s time to add some business logic to your application. -This will be an evergreen "Hello world!"" -- just to keep things simple. - -Rename the template file ``app/roles/custom.lua`` to ``hello-world.lua``. - -.. code-block:: console - - $ mv app/roles/custom.lua app/roles/hello-world.lua - -This will be your *role*. In Tarantool Cartridge, a role is a Lua module that -implements some instance-specific functions and/or logic. -Further on we'll show how to add code to a role, build it, enable and test. - -There is already some code in the role's ``init()`` function. - -.. code-block:: lua - :emphasize-lines: 5-7 - - local function init(opts) -- luacheck: no unused args - -- if opts.is_master then - -- end - - local httpd = assert(cartridge.service_get('httpd'), "Failed to get httpd service") - httpd:route({method = 'GET', path = '/hello'}, function() - return {body = 'Hello world!'} - end) - - return true - end - -This exports an HTTP endpoint ``/hello``. For example, http://localhost:8081/hello -if you address the first instance from the ``instances.yml`` file. -If you open it in a browser after enabling the role (we'll do it here a bit later), -you'll see "Hello world!" on the page. - -Let's add some more code there. - -.. code-block:: lua - :emphasize-lines: 9-11 - - local function init(opts) -- luacheck: no unused args - -- if opts.is_master then - -- end - - local httpd = cartridge.service_get('httpd') - httpd:route({method = 'GET', path = '/hello'}, function() - return {body = 'Hello world!'} - end) - - local log = require('log') - log.info('Hello world!') - - return true - end - -This writes "Hello, world!" to the console when the role gets enabled, -so you'll have a chance to spot this. No rocket science. - -Next, amend ``role_name`` in the "return" section of the ``hello-world.lua`` file. -You'll see this section at the bottom of the file. -This text will be displayed as a label for your role in the cluster management -web interface. - -.. code-block:: lua - :emphasize-lines: 2 - - return { - role_name = 'Hello world!', - init = init, - stop = stop, - validate_config = validate_config, - apply_config = apply_config, - -- dependencies = {'cartridge.roles.vshard-router'}, - } - -The final thing to do before you can run the application is to add your role to -the list of available cluster roles in the ``init.lua`` file in the project root directory. - -.. code-block:: lua - :emphasize-lines: 8 - - local cartridge = require('cartridge') - - local ok, err = cartridge.cfg({ - roles = { - 'cartridge.roles.vshard-storage', - 'cartridge.roles.vshard-router', - 'cartridge.roles.metrics', - 'app.roles.hello-world', - }, - }) - -Now the cluster will be aware of your role. - -Why ``app.roles.hello-world``? By default, the role name here should match the -path from the application root (``./myapp``) to the role file -(``app/roles/hello-world.lua``). - -Great! Your role is ready. Re-build the application and re-start the cluster now: - -.. code-block:: console - - $ cartridge build - $ cartridge start - -Now all instances are up, but idle, waiting for you to enable roles for them. - -Instances (replicas) in a Tarantool Cartridge cluster are organized into -*replica sets*. Roles are enabled per replica set, so all instances in a -replica set have the same roles enabled. - -Let's create a replica set containing just one instance and enable your role: - -#. Open the cluster management web interface at http://localhost:8081. -#. Next to the **router** instance, click :guilabel:`Configure`. -#. Check the role ``Hello world!`` to enable it. Notice that the role name here - matches the label text that you specified in the ``role_name`` parameter in - the ``hello-world.lua`` file. -#. (Optionally) Specify the replica set name, for example - "hello-world-replica-set". - - .. image:: images/cluster_create_replica_set-border-5px.png - :align: center - :scale: 40% - -#. Click :guilabel:`Create replica set` and see the newly-created replica set - in the web interface. - - .. image:: images/cluster_new_replica_set-border-5px.png - :align: center - :scale: 40% - -Your custom role got enabled. Find the "Hello world!" message in console, -like this: - -.. image:: images/cluster_hello_world_console-border-5px.png - :align: center - :scale: 40% - -Finally, open the HTTP endpoint of this instance at -http://localhost:8081/hello and see the reply to your GET request. - -.. image:: images/cluster_hello_http-border-5px.png - :align: center - :scale: 40% - -Everything is up and running! What's next? - -* Follow the :ref:`administrator's guide ` to set up the rest of the - cluster and try some cool cluster management features -- for example, enable failover. -* Check out the Cartridge :doc:`developer's guide ` - and implement more sophisticated business logic for your role. -* :doc:`Pack ` your application for easy distribution. - Choose what you like: a DEB or RPM package, a TGZ archive, or a Docker image. - Archives and packages can be deployed with `ansible-cartridge `__. -* Read the :doc:`Cartridge documentation `. diff --git a/doc/how-to/getting_started_connectors.rst b/doc/how-to/getting_started_connectors.rst deleted file mode 100644 index 5609575267..0000000000 --- a/doc/how-to/getting_started_connectors.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _getting_started_connectors: - -================================================================================ -Connecting from your favorite language -================================================================================ - -In the :ref:`previous sections `, -you have learned how to create a Tarantool database. -Now let's see how to connect to the database from different programming -languages, such as Python, PHP, Go, and C++, and -execute typical requests for manipulating the data (select, insert, delete, -and so on). - -.. toctree:: - :maxdepth: 2 - :numbered: 0 - - getting_started_python - getting_started_php - getting_started_go - getting_started_cxx diff --git a/doc/how-to/getting_started_db.rst b/doc/how-to/getting_started_db.rst deleted file mode 100644 index 5df67e117f..0000000000 --- a/doc/how-to/getting_started_db.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _getting_started_db: - -================================================================================ -Creating your first Tarantool database -================================================================================ - -First, let's install Tarantool, start it, and create a simple database. - -You can install Tarantool and work with it locally or in Docker. - -.. include:: using_docker.rst - -.. include:: using_package_manager.rst diff --git a/doc/how-to/getting_started_go.rst b/doc/how-to/getting_started_go.rst deleted file mode 100644 index 64fe7b907a..0000000000 --- a/doc/how-to/getting_started_go.rst +++ /dev/null @@ -1,261 +0,0 @@ -.. _getting_started-go: - --------------------------------------------------------------------------------- -Connecting from Go --------------------------------------------------------------------------------- - -.. _getting_started-go-pre-requisites: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Pre-requisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before we proceed: - -#. `Install `__ - the ``go-tarantool`` library. - -#. :ref:`Start ` Tarantool (locally or in Docker) - and make sure that you have created and populated a database as we suggested - :ref:`earlier `: - - .. code-block:: lua - - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:format({ - {name = 'id', type = 'unsigned'}, - {name = 'band_name', type = 'string'}, - {name = 'year', type = 'unsigned'} - }) - s:create_index('primary', { - type = 'hash', - parts = {'id'} - }) - s:create_index('secondary', { - type = 'hash', - parts = {'band_name'} - }) - s:insert{1, 'Roxette', 1986} - s:insert{2, 'Scorpions', 2015} - s:insert{3, 'Ace of Base', 1993} - - .. IMPORTANT:: - - Please do not close the terminal window - where Tarantool is running -- you'll need it soon. - -#. In order to connect to Tarantool as an administrator, reset the password - for the ``admin`` user: - - .. code-block:: lua - - box.schema.user.passwd('pass') - -.. _getting_started-go-connecting: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Connecting to Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To get connected to the Tarantool server, write a simple Go program: - -.. code-block:: go - - package main - - import ( - "fmt" - - "github.com/tarantool/go-tarantool" - ) - - func main() { - - conn, err := tarantool.Connect("127.0.0.1:3301", tarantool.Opts{ - User: "admin", - Pass: "pass", - }) - - if err != nil { - log.Fatalf("Connection refused") - } - - defer conn.Close() - - // Your logic for interacting with the database - } - -The default user is ``guest``. - -.. _getting_started-go-manipulate: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Manipulating the data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. _getting_started-go-insert: - -******************************************************************************** -Inserting data -******************************************************************************** - -To insert a :term:`tuple` into a :term:`space`, use ``Insert``: - -.. code-block:: go - - resp, err = conn.Insert("tester", []interface{}{4, "ABBA", 1972}) - -This inserts the tuple ``(4, "ABBA", 1972)`` into a space named ``tester``. - -The response code and data are available in the -`tarantool.Response `_ -structure: - -.. code-block:: go - - code := resp.Code - data := resp.Data - -.. _getting_started-go-query: - -******************************************************************************** -Querying data -******************************************************************************** - -To select a tuple from a space, use -`Select `_: - -.. code-block:: go - - resp, err = conn.Select("tester", "primary", 0, 1, tarantool.IterEq, []interface{}{4}) - -This selects a tuple by the primary key with ``offset = 0`` and ``limit = 1`` -from a space named ``tester`` (in our example, this is the index named ``primary``, -based on the ``id`` field of each tuple). - -Next, select tuples by a secondary key. - -.. code-block:: go - - resp, err = conn.Select("tester", "secondary", 0, 1, tarantool.IterEq, []interface{}{"ABBA"}) - -Finally, it would be nice to select all the tuples in a space. But there is no -one-liner for this in Go; you would need a script like -:ref:`this one `. - -For more examples, see https://github.com/tarantool/go-tarantool#usage - -.. _getting_started-go-update: - -******************************************************************************** -Updating data -******************************************************************************** - -Update a :term:`field` value using ``Update``: - -.. code-block:: go - - resp, err = conn.Update("tester", "primary", []interface{}{4}, []interface{}{[]interface{}{"+", 2, 3}}) - -This increases by 3 the value of field ``2`` in the tuple with ``id = 4``. -If a tuple with this ``id`` doesn't exist, Tarantool will return an error. - -Now use ``Replace`` to totally replace the tuple that matches the -primary key. If a tuple with this primary key doesn't exist, Tarantool will -do nothing. - -.. code-block:: go - - resp, err = conn.Replace("tester", []interface{}{4, "New band", 2011}) - -You can also update the data using ``Upsert`` that works similarly -to ``Update``, but creates a new tuple if the old one was not found. - -.. code-block:: go - - resp, err = conn.Upsert("tester", []interface{}{4, "Another band", 2000}, []interface{}{[]interface{}{"+", 2, 5}}) - -This increases by 5 the value of the third field in the tuple with ``id = 4``, or -inserts the tuple ``(4, "Another band", 2000)`` if a tuple with this ``id`` -doesn't exist. - -.. _getting_started-go-delete: - -******************************************************************************** -Deleting data -******************************************************************************** - -To delete a tuple, use ``сonnection.Delete``: - -.. code-block:: go - - resp, err = conn.Delete("tester", "primary", []interface{}{4}) - -To delete all tuples in a space (or to delete an entire space), use ``Call``. -We'll focus on this function in more detail in the -:ref:`next ` section. - -To delete all tuples in a space, call ``space:truncate``: - -.. code-block:: go - - resp, err = conn.Call("box.space.tester:truncate", []interface{}{}) - -To delete an entire space, call ``space:drop``. -This requires connecting to Tarantool as the ``admin`` user: - -.. code-block:: go - - resp, err = conn.Call("box.space.tester:drop", []interface{}{}) - -.. _getting_started-go-stored-procs: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Executing stored procedures -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Switch to the terminal window where Tarantool is running. - -.. NOTE:: - - If you don't have a terminal window with remote connection to Tarantool, - check out these guides: - - * :ref:`connecting to a local Tarantool instance ` - * :ref:`attaching to a Tarantool instance that runs in a Docker container ` - -Define a simple Lua function: - -.. code-block:: lua - - function sum(a, b) - return a + b - end - -Now we have a Lua function defined in Tarantool. To invoke this function from -``go``, use ``Call``: - -.. code-block:: go - - resp, err = conn.Call("sum", []interface{}{2, 3}) - -To send bare Lua code for execution, use ``Eval``: - -.. code-block:: go - - resp, err = connection.Eval("return 4 + 5", []interface{}{}) - -.. _getting_started-go-comparison: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Feature comparison -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are two more connectors from the open-source community: - -* `viciious/go-tarantool `_ - -* `FZambia/tarantool `_. - -See the :ref:`feature comparison table ` of all Go connectors available. diff --git a/doc/how-to/getting_started_net_box.rst b/doc/how-to/getting_started_net_box.rst deleted file mode 100644 index 154892bce4..0000000000 --- a/doc/how-to/getting_started_net_box.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. _getting_started_net_box: - -Getting started with net.box -============================ - -The tutorial shows how to work with some common ``net.box`` methods. - -For more information about the ``net.box`` module, -check the :ref:`corresponding module reference `. - -Sandbox configuration ---------------------- - -The sandbox configuration for the tutorial assumes that: - -* The Tarantool instance is running on ``localhost 127.0.0.1:3301``. -* There is a space named ``tester`` with a numeric primary key. -* The space contains a tuple with the key value = ``800``. -* The current user has read, write, and execute privileges. - -Use the commands below for a quick sandbox setup: - -.. code-block:: lua - - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) - t = s:insert({800, 'TEST'}) - box.schema.user.grant('guest', 'read,write,execute', 'universe') - -Creating a net.box connection ------------------------------ - -First, load the ``net.box`` module with the ``require('net.box')`` method: - -.. code-block:: tarantoolsession - - tarantool> net_box = require('net.box') - -The next step is to create a new connection. -In ``net.box``, self-connection is pre-established. -That is, ``conn = net_box.connect('localhost:3301')`` command can be replaced with the ``conn = net_box.self`` object call: - -.. code-block:: tarantoolsession - - tarantool> conn = net_box.self - -Then, make a ping: - -.. code-block:: tarantoolsession - - tarantool> conn:ping() - --- - - true - ... - -Using data operations ---------------------- - -Select all tuples in the ``tester`` space where the key value is ``800``: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:select{800} - --- - - - [800, 'TEST'] - ... - -Insert two tuples into the space: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:insert({700, 'TEST700'}) - --- - - [700, 'TEST700'] - ... - tarantool> conn.space.tester:insert({600, 'TEST600'}) - --- - - [600, 'TEST600'] - ... - -After the insert, there is one tuple where the key value is ``600``. -To select this tuple, you can use the ``get()`` method. -Unlike the ``select()`` command, ``get()`` returns only one tuple that satisfies the stated condition. - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:get({600}) - --- - - [600, 'TEST600'] - ... - -To update the existing tuple, you can use either ``update()`` or ``upsert()``. -The ``update()`` method can be used for assignment, arithmetic (if the field is numeric), -cutting and pasting fragments of a field, and deleting or inserting a field. - -In this tutorial, the ``update()`` command is used to update the tuple identified by primary key value = ``800``. -The operation assigns a new value to the second field in the tuple: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:update(800, {{'=', 2, 'TEST800'}}) - --- - - [800, 'TEST800'] - ... - -As for the ``upsert`` function, if there is an existing tuple that matches the key field of tuple, then the command -has the same effect as ``update()``. -Otherwise, the effect is equal to the ``insert()`` method. - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:upsert({500, 'TEST500'}, {{'=', 2, 'TEST'}}) - -To delete a tuple where the key value is ``600``, run the ``delete()`` method below: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:delete{600} - --- - - [600, 'TEST600'] - ... - -Then, replace the existing tuple with a new one: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:replace{500, 'New data', 'Extra data'} - --- - - [500, 'New data', 'Extra data'] - ... - -Finally, select all tuples from the space: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:select{} - --- - - - [800, 'TEST800'] - - [500, 'New data', 'Extra data'] - - [700, 'TEST700'] - ... - -Closing the connection ----------------------- - -In the end, close the connection when it is no longer needed: - -.. code-block:: tarantoolsession - - tarantool> conn:close() - --- - ... \ No newline at end of file diff --git a/doc/how-to/getting_started_php.rst b/doc/how-to/getting_started_php.rst deleted file mode 100644 index fd221cefe9..0000000000 --- a/doc/how-to/getting_started_php.rst +++ /dev/null @@ -1,267 +0,0 @@ -.. _getting_started-php: - --------------------------------------------------------------------------------- -Connecting from PHP --------------------------------------------------------------------------------- - -.. _getting_started-php-pre-requisites: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Pre-requisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before we proceed: - -#. `Install `__ - the ``tarantool/client`` library. - -#. :ref:`Start ` Tarantool (locally or in Docker) - and make sure that you have created and populated a database as we suggested - :ref:`earlier `: - - .. code-block:: lua - - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:format({ - {name = 'id', type = 'unsigned'}, - {name = 'band_name', type = 'string'}, - {name = 'year', type = 'unsigned'} - }) - s:create_index('primary', { - type = 'hash', - parts = {'id'} - }) - s:create_index('secondary', { - type = 'hash', - parts = {'band_name'} - }) - s:insert{1, 'Roxette', 1986} - s:insert{2, 'Scorpions', 2015} - s:insert{3, 'Ace of Base', 1993} - - .. IMPORTANT:: - - Please do not close the terminal window - where Tarantool is running -- you'll need it soon. - -#. In order to connect to Tarantool as an administrator, reset the password - for the ``admin`` user: - - .. code-block:: lua - - box.schema.user.passwd('pass') - -.. _getting_started-php-connecting: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Connecting to Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To configure a connection to the Tarantool server, say this: - -.. code-block:: php - - use Tarantool\Client\Client; - - require __DIR__.'/vendor/autoload.php'; - $client = Client::fromDefaults(); - -The connection itself will be established at the first request. -You can also specify the user name and password, if needed: - -.. code-block:: php - - $client = Client::fromOptions([ - 'uri' => 'tcp://127.0.0.1:3301', - 'username' => '', - 'password' => '' - ]); - -The default user is ``guest``. - -.. _getting_started-php-manipulate: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Manipulating the data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A :term:`space` is a container for :term:`tuples `. To access a space as a named object, -use ``getSpace``: - -.. code-block:: php - - $tester = $client->getSpace('tester'); - -.. _getting_started-php-insert: - -******************************************************************************** -Inserting data -******************************************************************************** - -To insert a tuple into a space, use ``insert``: - -.. code-block:: php - - $result = $tester->insert([4, 'ABBA', 1972]); - -.. _getting_started-php-query: - -******************************************************************************** -Querying data -******************************************************************************** - -Let's start with selecting a tuple by the primary key -(in our example, this is the index named ``primary``, based on the ``id`` field -of each tuple). Use ``select``: - -.. code-block:: php - - use Tarantool\Client\Schema\Criteria; - - $result = $tester->select(Criteria::key([4])); - printf(json_encode($result)); - -.. code-block:: none - - [[4, 'ABBA', 1972]] - -Next, select tuples by a secondary key. -For this purpose, you need to specify the number *or* name of the index. - -First off, select tuples using the index number: - -.. code-block:: php - - $result = $tester->select(Criteria::index(1)->andKey(['Scorpions'])); - printf(json_encode($result)); - -.. code-block:: none - - [2, 'Scorpions', 2015] - -(We say ``index(1)`` because index numbers in Tarantool start with 0, -and we're using our second index here.) - -Now make a similar query by the index name and make sure that the result -is the same: - -.. code-block:: php - - $result = $tester->select(Criteria::index('secondary')->andKey(['Scorpions'])); - printf(json_encode($result)); - -.. code-block:: none - - [2, 'Scorpions', 2015] - -Finally, select all the tuples in a space via a ``select``: - -.. code-block:: php - - $result = $tester->select(Criteria::allIterator()); - -.. _getting_started-php-update: - -******************************************************************************** -Updating data -******************************************************************************** - -Update a :term:`field` value using ``update``: - -.. code-block:: php - - use Tarantool\Client\Schema\Operations; - - $result = $tester->update([4], Operations::set(1, 'New group')->andAdd(2, 2)); - -This updates the value of field ``1`` and increases the value of field ``2`` -in the tuple with ``id = 4``. If a tuple with this ``id`` doesn't exist, -Tarantool will return an error. - -Now use ``replace`` to totally replace the tuple that matches the -primary key. If a tuple with this primary key doesn't exist, Tarantool will -do nothing. - -.. code-block:: php - - $result = $tester->replace([4, 'New band', 2015]); - -You can also update the data using ``upsert`` that works similarly -to ``update``, but creates a new tuple if the old one was not found. - -.. code-block:: php - - use Tarantool\Client\Schema\Operations; - - $tester->upsert([4, 'Another band', 2000], Operations::add(2, 5)); - -This increases by 5 the value of field ``2`` in the tuple with ``id = 4``, or -inserts the tuple ``(4, "Another band", 2000)`` if a tuple with this ``id`` -doesn't exist. - -.. _getting_started-php-delete: - -******************************************************************************** -Deleting data -******************************************************************************** - -To delete a tuple, use ``delete(primary_key)``: - -.. code-block:: php - - $result = $tester->delete([4]); - -To delete all tuples in a space (or to delete an entire space), use ``call``. -We'll focus on this function in more detail in the -:ref:`next ` section. - -To delete all tuples in a space, call ``space:truncate``: - -.. code-block:: php - - $result = $client->call('box.space.tester:truncate'); - -To delete an entire space, call ``space:drop``. -This requires connecting to Tarantool as the ``admin`` user: - -.. code-block:: php - - $result = $client->call('box.space.tester:drop'); - -.. _getting_started-php-stored-procs: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Executing stored procedures -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Switch to the terminal window where Tarantool is running. - -.. NOTE:: - - If you don't have a terminal window with remote connection to Tarantool, - check out these guides: - - * :ref:`connecting to a local Tarantool instance ` - * :ref:`attaching to a Tarantool instance that runs in a Docker container ` - -Define a simple Lua function: - -.. code-block:: lua - - function sum(a, b) - return a + b - end - -Now we have a Lua function defined in Tarantool. To invoke this function from -``php``, use ``call``: - -.. code-block:: php - - $result = $client->call('sum', 3, 2); - -To send bare Lua code for execution, use ``eval``: - -.. code-block:: php - - $result = $client->evaluate('return 4 + 5'); diff --git a/doc/how-to/getting_started_python.rst b/doc/how-to/getting_started_python.rst deleted file mode 100644 index b94ea459d2..0000000000 --- a/doc/how-to/getting_started_python.rst +++ /dev/null @@ -1,255 +0,0 @@ -.. _getting_started-python: - --------------------------------------------------------------------------------- -Connecting from Python --------------------------------------------------------------------------------- - -.. _getting_started-python-pre-requisites: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Pre-requisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before we proceed: - -#. `Install `__ - the ``tarantool`` module. We recommend using ``python3`` and ``pip3``. - -#. :ref:`Start ` Tarantool (locally or in Docker) - and make sure that you have created and populated a database as we suggested - :ref:`earlier `: - - .. code-block:: lua - - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:format({ - {name = 'id', type = 'unsigned'}, - {name = 'band_name', type = 'string'}, - {name = 'year', type = 'unsigned'} - }) - s:create_index('primary', { - type = 'hash', - parts = {'id'} - }) - s:create_index('secondary', { - type = 'hash', - parts = {'band_name'} - }) - s:insert{1, 'Roxette', 1986} - s:insert{2, 'Scorpions', 2015} - s:insert{3, 'Ace of Base', 1993} - - .. IMPORTANT:: - - Please do not close the terminal window - where Tarantool is running -- you'll need it soon. - -#. In order to connect to Tarantool as an administrator, reset the password - for the ``admin`` user: - - .. code-block:: lua - - box.schema.user.passwd('pass') - -.. _getting_started-python-connecting: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Connecting to Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To get connected to the Tarantool server, say this: - -.. code-block:: python - - >>> import tarantool - >>> connection = tarantool.connect("localhost", 3301) - -You can also specify the user name and password, if needed: - -.. code-block:: python - - >>> tarantool.connect("localhost", 3301, user=username, password=password) - -The default user is ``guest``. - -.. _getting_started-python-manipulate: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Manipulating the data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A :term:`space` is a container for :term:`tuples `. -To access a space as a named object, use ``connection.space``: - -.. code-block:: python - - >>> tester = connection.space('tester') - -.. _getting_started-python-insert: - -******************************************************************************** -Inserting data -******************************************************************************** - -To insert a tuple into a space, use ``insert``: - -.. code-block:: python - - >>> tester.insert((4, 'ABBA', 1972)) - [4, 'ABBA', 1972] - -.. _getting_started-python-query: - -******************************************************************************** -Querying data -******************************************************************************** - -Let's start with selecting a tuple by the primary key -(in our example, this is the index named ``primary``, based on the ``id`` field -of each tuple). Use ``select``: - -.. code-block:: python - - >>> tester.select(4) - [4, 'ABBA', 1972] - -Next, select tuples by a secondary key. -For this purpose, you need to specify the number *or* name of the index. - -First off, select tuples using the index number: - -.. code-block:: python - - >>> tester.select('Scorpions', index=1) - [2, 'Scorpions', 2015] - -(We say ``index=1`` because index numbers in Tarantool start with 0, -and we're using our second index here.) - -Now make a similar query by the index name and make sure that the result -is the same: - -.. code-block:: python - - >>> tester.select('Scorpions', index='secondary') - [2, 'Scorpions', 2015] - -Finally, select all the tuples in a space via a ``select`` with no -arguments: - -.. code-block:: python - - >>> tester.select() - -.. _getting_started-python-update: - -******************************************************************************** -Updating data -******************************************************************************** - -Update a :term:`field` value using ``update``: - -.. code-block:: python - - >>> tester.update(4, [('=', 1, 'New group'), ('+', 2, 2)]) - -This updates the value of field ``1`` and increases the value of field ``2`` -in the tuple with ``id = 4``. If a tuple with this ``id`` doesn't exist, -Tarantool will return an error. - -Now use ``replace`` to totally replace the tuple that matches the -primary key. If a tuple with this primary key doesn't exist, Tarantool will -do nothing. - -.. code-block:: python - - >>> tester.replace((4, 'New band', 2015)) - -You can also update the data using ``upsert`` that works similarly -to ``update``, but creates a new tuple if the old one was not found. - -.. code-block:: python - - >>> tester.upsert((4, 'Another band', 2000), [('+', 2, 5)]) - -This increases by 5 the value of field ``2`` in the tuple with ``id = 4``, or -inserts the tuple ``(4, "Another band", 2000)`` if a tuple with this ``id`` -doesn't exist. - -.. _getting_started-python-delete: - -******************************************************************************** -Deleting data -******************************************************************************** - -To delete a tuple, use ``delete(primary_key)``: - -.. code-block:: python - - >>> tester.delete(4) - [4, 'New group', 2012] - -To delete all tuples in a space (or to delete an entire space), use ``call``. -We'll focus on this function in more detail in the -:ref:`next ` section. - -To delete all tuples in a space, call ``space:truncate``: - -.. code-block:: python - - >>> connection.call('box.space.tester:truncate', ()) - -To delete an entire space, call ``space:drop``. -This requires connecting to Tarantool as the ``admin`` user: - -.. code-block:: python - - >>> connection.call('box.space.tester:drop', ()) - -.. _getting_started-python-stored-procs: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Executing stored procedures -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Switch to the terminal window where Tarantool is running. - -.. NOTE:: - - If you don't have a terminal window with remote connection to Tarantool, - check out these guides: - - * :ref:`connecting to a local Tarantool instance ` - * :ref:`attaching to a Tarantool instance that runs in a Docker container ` - -Define a simple Lua function: - -.. code-block:: lua - - function sum(a, b) - return a + b - end - -Now we have a Lua function defined in Tarantool. To invoke this function from -``python``, use ``call``: - -.. code-block:: python - - >>> connection.call('sum', (3, 2)) - 5 - -To send bare Lua code for execution, use ``eval``: - -.. code-block:: python - - >>> connection.eval('return 4 + 5') - 9 - -.. _getting_started-python-comparison: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Feature comparison -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See the :ref:`feature comparison table ` of all Python connectors available. diff --git a/doc/how-to/images/cluster_create_replica_set-border-5px.png b/doc/how-to/images/cluster_create_replica_set-border-5px.png deleted file mode 100644 index 649c1dfd48..0000000000 Binary files a/doc/how-to/images/cluster_create_replica_set-border-5px.png and /dev/null differ diff --git a/doc/how-to/images/cluster_dry_run-border-5px.png b/doc/how-to/images/cluster_dry_run-border-5px.png deleted file mode 100644 index da9db48f4d..0000000000 Binary files a/doc/how-to/images/cluster_dry_run-border-5px.png and /dev/null differ diff --git a/doc/how-to/images/cluster_hello_http-border-5px.png b/doc/how-to/images/cluster_hello_http-border-5px.png deleted file mode 100644 index ea9b96fbd5..0000000000 Binary files a/doc/how-to/images/cluster_hello_http-border-5px.png and /dev/null differ diff --git a/doc/how-to/images/cluster_hello_world_console-border-5px.png b/doc/how-to/images/cluster_hello_world_console-border-5px.png deleted file mode 100644 index c0f54aec62..0000000000 Binary files a/doc/how-to/images/cluster_hello_world_console-border-5px.png and /dev/null differ diff --git a/doc/how-to/images/cluster_new_replica_set-border-5px.png b/doc/how-to/images/cluster_new_replica_set-border-5px.png deleted file mode 100644 index f13594b629..0000000000 Binary files a/doc/how-to/images/cluster_new_replica_set-border-5px.png and /dev/null differ diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst deleted file mode 100644 index bf313d80c3..0000000000 --- a/doc/how-to/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -:noindex: -:fullwidth: - -.. _tutorials: -.. _how-to: - -How-to guides -============= - -This chapter contains practical examples as well as -tutorials for those who would like to dig deeper into Tarantool usage. - -If you are new to Tarantool, please see our -:ref:`Getting Started guides ` first. - -.. toctree:: - :maxdepth: 2 - - Creating Tarantool database - getting_started_connectors - getting_started_cartridge - db/index - getting_started_net_box - vshard_quick - app/index - replication/index - sql/index - other/index diff --git a/doc/how-to/other/index.rst b/doc/how-to/other/index.rst deleted file mode 100644 index 6e597e4256..0000000000 --- a/doc/how-to/other/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -More guides -=========== - -.. toctree:: - :maxdepth: 1 - - iproto - libslave \ No newline at end of file diff --git a/doc/how-to/other/libslave.rst b/doc/how-to/other/libslave.rst deleted file mode 100644 index f468e5756a..0000000000 --- a/doc/how-to/other/libslave.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. _libslave: - -================================================================================ -libslave tutorial -================================================================================ - -``libslave`` is a C++ library for reading data changes done by MysQL and, -optionally, writing them to a Tarantool database. -It works by acting as a replication slave. -The MySQL server writes data-change information to -a "binary log", and transfers the information to -any client that says "I want to see the information -starting with this file and this record, continuously". -So, ``libslave`` is primarily good for making a Tarantool database replica -(much faster than using a conventional MySQL slave server), -and for keeping track of data changes so they can be searched. - -We will not go into the many details here -- the -`API documentation `_ has them. -We will only show an exercise: a minimal program that uses the library. - -.. NOTE:: - - Use a test machine. Do not use a production machine. - -STEP 1: Make sure you have: - -* a recent version of Linux (versions such as Ubuntu 14.04 will not do), -* a recent version of MySQL 5.6 or MySQL 5.7 server (MariaDB will not do), -* MySQL client development package. For example, on Ubuntu you can download - it with this command: - - .. code-block:: console - - $ sudo apt-get install mysql-client-core-5.7 - -STEP 2: Download ``libslave``. - -The recommended source is https://github.com/tarantool/libslave/. -Downloads include the source code only. - -.. code-block:: console - - $ sudo apt-get install libboost-all-dev - $ cd ~ - $ git clone https://github.com/tarantool/libslave.git tarantool-libslave - $ cd tarantool-libslave - $ git submodule init - $ git submodule update - $ cmake . - $ make - -If you see an error message mentioning the word "vector", -edit ``field.h`` and add this line: - -.. code-block:: c - - #include - -STEP 3: Start the MySQL server. On the command line, add -appropriate switches for doing replication. For example: - -.. code-block:: console - - $ mysqld --log-bin=mysql-bin --server-id=1 - -STEP 4: For purposes of this exercise, we are assuming you have: - -* a "root" user with password "root" with privileges, -* a "test" database with a table named "test", -* a binary log named "mysql-bin", -* a server with server id = 1. - -The values are hard-coded in the program, though of course -you can change the program -- it's easy to see their settings. - -STEP 5: Look at the program: - -.. code-block:: c - - #include - #include - #include - #include "Slave.h" - #include "DefaultExtState.h" - - slave::Slave* sl = NULL; - - void callback(const slave::RecordSet& event) { - slave::Position sBinlogPos = sl->getLastBinlogPos(); - switch (event.type_event) { - case slave::RecordSet::Update: std::cout << "UPDATE" << "\n"; break; - case slave::RecordSet::Delete: std::cout << "DELETE" << "\n"; break; - case slave::RecordSet::Write: std::cout << "INSERT" << "\n"; break; - default: break; - } - } - - bool isStopping() - { - return 0; - } - - int main(int argc, char** argv) - { - slave::MasterInfo masterinfo; - slave::Position position("mysql-bin", 0); - masterinfo.conn_options.mysql_host = "127.0.0.1"; - masterinfo.conn_options.mysql_port = 3306; - masterinfo.conn_options.mysql_user = "root"; - masterinfo.conn_options.mysql_pass = "root"; - bool error = false; - try { - slave::DefaultExtState sDefExtState; - slave::Slave slave(masterinfo, sDefExtState); - sl = &slave; - sDefExtState.setMasterPosition(position); - slave.setCallback("test", "test", callback); - slave.init(); - slave.createDatabaseStructure(); - try { - slave.get_remote_binlog(isStopping); - } catch (std::exception& ex) { - std::cout << "Error reading: " << ex.what() << std::endl; - error = true; - } - } catch (std::exception& ex) { - std::cout << "Error initializing: " << ex.what() << std::endl; - error = true; - } - return 0; - } - -Everything unnecessary has been stripped so that you can -see quickly how it works. At the start of ``main()``, there are -some settings used for connecting -- host, port, user, password. -Then there is an initialization call with the binary log file -name = "mysql-bin". Pay particular attention to the ``setCallback`` -statement, which passes database name = "test", table name = "test", -and callback function address = callback. The program will be -looping and invoking this callback function. See how, earlier -in the program, the callback function prints "UPDATE" or "DELETE" -or "INSERT" depending on what is passed to it. - -STEP 5: Put the program in the ``tarantool-libslave`` directory and -name it ``example.cpp``. - -Step 6: Compile and build: - -.. code-block:: console - - $ g++ -I/tarantool-libslave/include example.cpp -o example libslave_a.a -ldl -lpthread - -.. NOTE:: - - Replace ``tarantool-libslave/include`` with the full directory name. - - Notice that the name of the static library is ``libslave_a.a``, - not ``libslave.a``. - -Step 7: Run: - -.. code-block:: console - - $ ./example - -The result will be nothing -- the program is looping, waiting for -the MySQL server to write to the replication binary log. - -Step 8: Start a MySQL client program -- any client program will do. -Enter these statements: - -.. code-block:: sql - - USE test - INSERT INTO test VALUES ('A'); - INSERT INTO test VALUES ('B'); - DELETE FROM test; - -Watch what happens in ``example.cpp`` output -- it displays: - -.. code-block:: text - - INSERT - INSERT - DELETE - DELETE - -This is row-based replication, so you see two DELETEs, because there are two -rows. - -What the exercise has shown is: - -* the library can be built, and -* programs that use the library can access everything that - the MySQL server dumps. - -For the many details and examples of usage in the field, see: - -* | Our downloadable ``libslave`` version: - | https://github.com/tarantool/libslave - -* | The version it was forked from (with a different README): - | https://github.com/vozbu/libslave/wiki/API - -* `How to speed up your MySQL with replication to in-memory database `_ - article -* `Replicating data from MySQL to Tarantool `_ - article (in Russian) -* `Asynchronous replication uncensored `_ - article (in Russian) diff --git a/doc/how-to/replication/index.rst b/doc/how-to/replication/index.rst deleted file mode 100644 index 463aa246eb..0000000000 --- a/doc/how-to/replication/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _how-to-replication: - -Replication tutorials -===================== - -.. toctree:: - :maxdepth: 2 - - repl_bootstrap - repl_add_instances - repl_remove_instances - repl_sync - repl_leader_elect - \ No newline at end of file diff --git a/doc/how-to/replication/repl_add_instances.rst b/doc/how-to/replication/repl_add_instances.rst deleted file mode 100644 index 8eb87e5ce8..0000000000 --- a/doc/how-to/replication/repl_add_instances.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _replication-add_instances: - -Adding instances -================ - -.. _replication-add_replica: - -This tutorial is intended as a follow-up to the -:ref:`replication bootstrapping ` guide. -It continues building on the examples from that page. -It is recommended that you complete the bootstrapping guide before you proceed. - - -Adding a replica ----------------- - -.. image:: mr-1m-2r-mesh-add.png - :align: center - -To add a second **replica** instance to the **master-replica** set from our -:ref:`bootstrapping example `, we need an -analog of the instance file that we created for the first replica in that set: - -.. code-block:: lua - - -- instance file for replica #2 - box.cfg{ - listen = 3301, - replication = {'replicator:password@192.168.0.101:3301', -- master URI - 'replicator:password@192.168.0.102:3301', -- replica #1 URI - 'replicator:password@192.168.0.103:3301'}, -- replica #2 URI - read_only = true - } - box.once("schema", function() - box.schema.user.create('replicator', {password = 'password'}) - box.schema.user.grant('replicator', 'replication') -- grant replication role - box.schema.space.create("test") - box.space.test:create_index("primary") - print('box.once executed on replica #2') - end) - -Here we add the URI of replica #2 to the :ref:`replication ` -parameter, so now it contains three URIs. - -After we launch the new replica instance, it gets connected to the master -instance and retrieves the master's write-ahead-log and snapshot files: - -.. code-block:: console - - $ # launching replica #2 - $ tarantool replica2.lua - 2017-06-14 14:54:33.927 [46945] main/101/replica2.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 14:54:33.927 [46945] main/101/replica2.lua C> log level 5 - 2017-06-14 14:54:33.928 [46945] main/101/replica2.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 14:54:33.930 [46945] main/104/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 14:54:33.930 [46945] main/104/applier/replicator@192.168.0.10 I> authenticated - 2017-06-14 14:54:33.930 [46945] main/101/replica2.lua I> bootstrapping replica from 192.168.0.101:3301 - 2017-06-14 14:54:33.933 [46945] main/104/applier/replicator@192.168.0.10 I> initial data received - 2017-06-14 14:54:33.933 [46945] main/104/applier/replicator@192.168.0.10 I> final data received - 2017-06-14 14:54:33.934 [46945] snapshot/101/main I> saving snapshot `/var/lib/tarantool/replica2/00000000000000000010.snap.inprogress' - 2017-06-14 14:54:33.934 [46945] snapshot/101/main I> done - 2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> vinyl checkpoint done - 2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> ready to accept requests - 2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> set 'read_only' configuration option to true - 2017-06-14 14:54:33.936 [46945] main C> entering the event loop - -Since we are adding a read-only instance, there is no need to dynamically -update the ``replication`` parameter on the other running instances. This update -would be required if we :ref:`added a master instance `. - -However, we recommend specifying the URI of replica #3 in all instance files of the -replica set. This will keep all the files consistent with each other and with -the current replication topology, and so will help to avoid configuration errors -in case of further configuration updates and replica set restart. - -.. _replication-add_master: - -Adding a master ---------------- - -.. image:: mm-3m-mesh-add.png - :align: center - -To add a third master instance to the **master-master** set from our -:ref:`bootstrapping example `, we need an -analog of the instance files that we created to bootstrap the other master -instances in that set: - -.. code-block:: lua - - -- instance file for master #3 - box.cfg{ - listen = 3301, - replication = {'replicator:password@192.168.0.101:3301', -- master#1 URI - 'replicator:password@192.168.0.102:3301', -- master#2 URI - 'replicator:password@192.168.0.103:3301'}, -- master#3 URI - read_only = true, -- temporarily read-only - } - box.once("schema", function() - box.schema.user.create('replicator', {password = 'password'}) - box.schema.user.grant('replicator', 'replication') -- grant replication role - box.schema.space.create("test") - box.space.test:create_index("primary") - end) - -Here we make the following changes: - -* Add the URI of master #3 to the :ref:`replication ` - parameter. -* Temporarily specify :ref:`read_only=true ` to disable - data-change operations on the instance. After launch, master #3 will act as a - replica until it retrieves all data from the other masters in the replica set. - -After we launch master #3, it gets connected to the other master -instances and retrieves their write-ahead-log and snapshot files: - -.. code-block:: console - - $ # launching master #3 - $ tarantool master3.lua - 2017-06-14 17:10:00.556 [47121] main/101/master3.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 17:10:00.557 [47121] main/101/master3.lua C> log level 5 - 2017-06-14 17:10:00.557 [47121] main/101/master3.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 17:10:00.559 [47121] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 17:10:00.559 [47121] main/104/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 17:10:00.559 [47121] main/105/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.102:3301 - 2017-06-14 17:10:00.559 [47121] main/106/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.103:3301 - 2017-06-14 17:10:00.559 [47121] main/105/applier/replicator@192.168.0.10 I> authenticated - 2017-06-14 17:10:00.559 [47121] main/101/master3.lua I> bootstrapping replica from 192.168.0.102:3301 - 2017-06-14 17:10:00.562 [47121] main/105/applier/replicator@192.168.0.10 I> initial data received - 2017-06-14 17:10:00.562 [47121] main/105/applier/replicator@192.168.0.10 I> final data received - 2017-06-14 17:10:00.562 [47121] snapshot/101/main I> saving snapshot `/Users/e.shebunyaeva/work/tarantool-test-repl/master3_dir/00000000000000000009.snap.inprogress' - 2017-06-14 17:10:00.562 [47121] snapshot/101/main I> done - 2017-06-14 17:10:00.564 [47121] main/101/master3.lua I> vinyl checkpoint done - 2017-06-14 17:10:00.564 [47121] main/101/master3.lua I> ready to accept requests - 2017-06-14 17:10:00.565 [47121] main/101/master3.lua I> set 'read_only' configuration option to true - 2017-06-14 17:10:00.565 [47121] main C> entering the event loop - 2017-06-14 17:10:00.565 [47121] main/104/applier/replicator@192.168.0.10 I> authenticated - -Next, we add the URI of master #3 to the ``replication`` parameter on the existing two -masters. Replication-related parameters are dynamic, so we only need to make a -``box.cfg{}`` request on each of the running instances: - -.. code-block:: tarantoolsession - - # adding master #3 URI to replication sources - tarantool> box.cfg{replication = - > {'replicator:password@192.168.0.101:3301', - > 'replicator:password@192.168.0.102:3301', - > 'replicator:password@192.168.0.103:3301'}} - --- - ... - -When master #3 catches up with the other masters' state, we can disable -read-only mode for this instance: - -.. code-block:: tarantoolsession - - # making master #3 a real master - tarantool> box.cfg{read_only=false} - --- - ... - -We also recommend to specify master #3 URI in all instance files in order to -keep all the files consistent with each other and with the current replication -topology. diff --git a/doc/how-to/replication/repl_bootstrap.rst b/doc/how-to/replication/repl_bootstrap.rst deleted file mode 100644 index a6f1a81bff..0000000000 --- a/doc/how-to/replication/repl_bootstrap.rst +++ /dev/null @@ -1,386 +0,0 @@ -.. _replication-bootstrap: - -Bootstrapping a replica set -=========================== - -.. _replication-setup: - -Replication setup ------------------ - -To enable replication, you need to specify two parameters in a ``box.cfg{}`` -request: - -* :ref:`replication ` which defines the - replication source(s), and -* :ref:`read_only ` which is ``true`` for a - replica and ``false`` for a master. - -Both these parameters are "dynamic". This allows a replica to become a master -and vice versa on the fly with the help of a ``box.cfg{}`` request. - -.. _replication-master_replica_bootstrap: - -Master-replica bootstrap ------------------------- - -Let us first bootstrap a simple **master-replica** set containing two instances, -each located on its own machine. For easier administration, we make the -:ref:`instance files ` almost identical. - -.. image:: mr-1m-1r-twoway.png - :align: center - -Here is an example of the master's instance file: - -.. code-block:: lua - - -- instance file for the master - box.cfg{ - listen = 3301, - replication = {'replicator:password@192.168.0.101:3301', -- master URI - 'replicator:password@192.168.0.102:3301'}, -- replica URI - read_only = false - } - box.once("schema", function() - box.schema.user.create('replicator', {password = 'password'}) - box.schema.user.grant('replicator', 'replication') -- grant replication role - box.schema.space.create("test") - box.space.test:create_index("primary") - print('box.once executed on master') - end) - -where: - -* the ``box.cfg()`` :ref:`listen ` parameter defines a URI - (port 3301 in our example), on which the master can accept connections from - replicas. -* the ``box.cfg()`` :ref:`replication ` parameter - defines the URIs at which all instances in the replica set can accept connections. - It includes the replica's URI as well, although the replica is not a replication - source right now. This parameter is mandatory only for master-master or full-mesh - cluster setups. - - .. note:: - - For security reasons, we recommend that administrators prevent unauthorized - replication sources by associating a password with every user that has a - replication :ref:`role `. That way, the :ref:`URI - ` for ``replication`` parameter must have the long form - ``username:password@host:port``. - -* the :ref:`read_only = false ` parameter setting enables - data-change operations on the instance and makes the instance act as a master, - not as a replica. *That is the only parameter setting in our instance files - that will differ.* -* the :doc:`box.once() ` function contains database initialization logic - that should be executed only once during the replica set lifetime. - -In this example, we create a space with a primary index, and a user for -replication purposes. We also say ``print('box.once executed on master')`` -so that it will later be visible on a console whether ``box.once()`` was executed. - -.. note:: - - Replication requires privileges. We can grant privileges for accessing spaces - directly to the user who will start the instance. However, it is more usual - to grant privileges for accessing spaces to a - :ref:`role `, and then grant the role to the user who - will start the replica. - -Here we use Tarantool's predefined role named "replication" which by default -grants "read" privileges for all database objects ("universe"), and we can -change privileges for this role as required. - -In the replica's instance file, we set the ``read_only`` parameter to "true", and -say ``print('box.once executed on replica')`` so that later it will be visible -that ``box.once()`` was not executed more than once. -Otherwise the replica's instance file is identical to the master's instance file. - -.. code-block:: lua - - -- instance file for the replica - box.cfg{ - listen = 3301, - replication = {'replicator:password@192.168.0.101:3301', -- master URI - 'replicator:password@192.168.0.102:3301'}, -- replica URI - read_only = true - } - box.once("schema", function() - box.schema.user.create('replicator', {password = 'password'}) - box.schema.user.grant('replicator', 'replication') -- grant replication role - box.schema.space.create("test") - box.space.test:create_index("primary") - print('box.once executed on replica') - end) - -.. note:: - - The replica does not inherit the master’s configuration parameters, such as - those making the :ref:`checkpoint daemon ` run on - the master. To get the same behavior, set the relevant parameters - explicitly so that they are the same on both master and replica. - -Now we can launch the two instances. The master... - -.. code-block:: console - - $ # launching the master - $ tarantool master.lua - 2017-06-14 14:12:03.847 [18933] main/101/master.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 14:12:03.848 [18933] main/101/master.lua C> log level 5 - 2017-06-14 14:12:03.849 [18933] main/101/master.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 14:12:03.859 [18933] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 14:12:03.861 [18933] main/105/applier/replicator@192.168.0. I> can't connect to master - 2017-06-14 14:12:03.861 [18933] main/105/applier/replicator@192.168.0. coio.cc:105 !> SystemError connect, called on fd 14, aka 192.168.0.102:56736: Connection refused - 2017-06-14 14:12:03.861 [18933] main/105/applier/replicator@192.168.0. I> will retry every 1 second - 2017-06-14 14:12:03.861 [18933] main/104/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 14:12:19.878 [18933] main/105/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.102:3301 - 2017-06-14 14:12:19.879 [18933] main/101/master.lua I> initializing an empty data directory - 2017-06-14 14:12:19.908 [18933] snapshot/101/main I> saving snapshot `/var/lib/tarantool/master/00000000000000000000.snap.inprogress' - 2017-06-14 14:12:19.914 [18933] snapshot/101/main I> done - 2017-06-14 14:12:19.914 [18933] main/101/master.lua I> vinyl checkpoint done - 2017-06-14 14:12:19.917 [18933] main/101/master.lua I> ready to accept requests - 2017-06-14 14:12:19.918 [18933] main/105/applier/replicator@192.168.0. I> failed to authenticate - 2017-06-14 14:12:19.918 [18933] main/105/applier/replicator@192.168.0. xrow.cc:431 E> ER_LOADING: Instance bootstrap hasn't finished yet - box.once executed on master - 2017-06-14 14:12:19.920 [18933] main C> entering the event loop - -... (the display confirms that ``box.once()`` was executed on the master) -- and the replica: - -.. code-block:: console - - $ # launching the replica - $ tarantool replica.lua - 2017-06-14 14:12:19.486 [18934] main/101/replica.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 14:12:19.486 [18934] main/101/replica.lua C> log level 5 - 2017-06-14 14:12:19.487 [18934] main/101/replica.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 14:12:19.494 [18934] iproto/101/main I> binary: bound to [::]:3311 - 2017-06-14 14:12:19.495 [18934] main/104/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 14:12:19.495 [18934] main/105/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.102:3302 - 2017-06-14 14:12:19.496 [18934] main/104/applier/replicator@192.168.0. I> failed to authenticate - 2017-06-14 14:12:19.496 [18934] main/104/applier/replicator@192.168.0. xrow.cc:431 E> ER_LOADING: Instance bootstrap hasn't finished yet - -In both logs, there are messages saying that the replica was bootstrapped from the master: - -.. code-block:: console - - $ # bootstrapping the replica (from the master's log) - <...> - 2017-06-14 14:12:20.503 [18933] main/106/main I> initial data sent. - 2017-06-14 14:12:20.505 [18933] relay/[::ffff:192.168.0.101]:/101/main I> recover from `/var/lib/tarantool/master/00000000000000000000.xlog' - 2017-06-14 14:12:20.505 [18933] main/106/main I> final data sent. - 2017-06-14 14:12:20.522 [18933] relay/[::ffff:192.168.0.101]:/101/main I> recover from `/Users/e.shebunyaeva/work/tarantool-test-repl/master_dir/00000000000000000000.xlog' - 2017-06-14 14:12:20.922 [18933] main/105/applier/replicator@192.168.0. I> authenticated - -.. code-block:: console - - $ # bootstrapping the replica (from the replica's log) - <...> - 2017-06-14 14:12:20.498 [18934] main/104/applier/replicator@192.168.0. I> authenticated - 2017-06-14 14:12:20.498 [18934] main/101/replica.lua I> bootstrapping replica from 192.168.0.101:3301 - 2017-06-14 14:12:20.512 [18934] main/104/applier/replicator@192.168.0. I> initial data received - 2017-06-14 14:12:20.512 [18934] main/104/applier/replicator@192.168.0. I> final data received - 2017-06-14 14:12:20.517 [18934] snapshot/101/main I> saving snapshot `/var/lib/tarantool/replica/00000000000000000005.snap.inprogress' - 2017-06-14 14:12:20.518 [18934] snapshot/101/main I> done - 2017-06-14 14:12:20.519 [18934] main/101/replica.lua I> vinyl checkpoint done - 2017-06-14 14:12:20.520 [18934] main/101/replica.lua I> ready to accept requests - 2017-06-14 14:12:20.520 [18934] main/101/replica.lua I> set 'read_only' configuration option to true - 2017-06-14 14:12:20.520 [18934] main C> entering the event loop - -Notice that ``box.once()`` was executed only at the master, although we added -``box.once()`` to both instance files. - -We could as well launch the replica first: - -.. code-block:: console - - $ # launching the replica - $ tarantool replica.lua - 2017-06-14 14:35:36.763 [18952] main/101/replica.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 14:35:36.765 [18952] main/101/replica.lua C> log level 5 - 2017-06-14 14:35:36.765 [18952] main/101/replica.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 14:35:36.772 [18952] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 14:35:36.772 [18952] main/104/applier/replicator@192.168.0. I> can't connect to master - 2017-06-14 14:35:36.772 [18952] main/104/applier/replicator@192.168.0. coio.cc:105 !> SystemError connect, called on fd 13, aka 192.168.0.101:56820: Connection refused - 2017-06-14 14:35:36.772 [18952] main/104/applier/replicator@192.168.0. I> will retry every 1 second - 2017-06-14 14:35:36.772 [18952] main/105/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.102:3301 - -... and the master later: - -.. code-block:: console - - $ # launching the master - $ tarantool master.lua - 2017-06-14 14:35:43.701 [18953] main/101/master.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 14:35:43.702 [18953] main/101/master.lua C> log level 5 - 2017-06-14 14:35:43.702 [18953] main/101/master.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 14:35:43.709 [18953] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 14:35:43.709 [18953] main/105/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.102:3301 - 2017-06-14 14:35:43.709 [18953] main/104/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 14:35:43.709 [18953] main/101/master.lua I> initializing an empty data directory - 2017-06-14 14:35:43.721 [18953] snapshot/101/main I> saving snapshot `/var/lib/tarantool/master/00000000000000000000.snap.inprogress' - 2017-06-14 14:35:43.722 [18953] snapshot/101/main I> done - 2017-06-14 14:35:43.723 [18953] main/101/master.lua I> vinyl checkpoint done - 2017-06-14 14:35:43.723 [18953] main/101/master.lua I> ready to accept requests - 2017-06-14 14:35:43.724 [18953] main/105/applier/replicator@192.168.0. I> failed to authenticate - 2017-06-14 14:35:43.724 [18953] main/105/applier/replicator@192.168.0. xrow.cc:431 E> ER_LOADING: Instance bootstrap hasn't finished yet - box.once executed on master - 2017-06-14 14:35:43.726 [18953] main C> entering the event loop - 2017-06-14 14:35:43.779 [18953] main/103/main I> initial data sent. - 2017-06-14 14:35:43.780 [18953] relay/[::ffff:192.168.0.101]:/101/main I> recover from `/var/lib/tarantool/master/00000000000000000000.xlog' - 2017-06-14 14:35:43.780 [18953] main/103/main I> final data sent. - 2017-06-14 14:35:43.796 [18953] relay/[::ffff:192.168.0.102]:/101/main I> recover from `/var/lib/tarantool/master/00000000000000000000.xlog' - 2017-06-14 14:35:44.726 [18953] main/105/applier/replicator@192.168.0. I> authenticated - -In this case, the replica would wait for the master to become available, so the -launch order doesn't matter. Our ``box.once()`` logic would also be executed -only once, at the master. - -.. code-block:: console - - $ # the replica has eventually connected to the master - $ # and got bootstrapped (from the replica's log) - 2017-06-14 14:35:43.777 [18952] main/104/applier/replicator@192.168.0. I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 14:35:43.777 [18952] main/104/applier/replicator@192.168.0. I> authenticated - 2017-06-14 14:35:43.777 [18952] main/101/replica.lua I> bootstrapping replica from 192.168.0.199:3310 - 2017-06-14 14:35:43.788 [18952] main/104/applier/replicator@192.168.0. I> initial data received - 2017-06-14 14:35:43.789 [18952] main/104/applier/replicator@192.168.0. I> final data received - 2017-06-14 14:35:43.793 [18952] snapshot/101/main I> saving snapshot `/var/lib/tarantool/replica/00000000000000000005.snap.inprogress' - 2017-06-14 14:35:43.793 [18952] snapshot/101/main I> done - 2017-06-14 14:35:43.795 [18952] main/101/replica.lua I> vinyl checkpoint done - 2017-06-14 14:35:43.795 [18952] main/101/replica.lua I> ready to accept requests - 2017-06-14 14:35:43.795 [18952] main/101/replica.lua I> set 'read_only' configuration option to true - 2017-06-14 14:35:43.795 [18952] main C> entering the event loop - -.. _replication-controlled_failover: - -Controlled failover -------------------- - -To perform a **controlled failover**, that is, swap the roles of the master and -replica, all we need to do is to set ``read_only=true`` at the master, and -``read_only=false`` at the replica. The order of actions is important here. -If a system is running in production, we do not want concurrent writes happening -both at the replica and the master. Nor do we want the new replica to accept -any writes until it has finished fetching all replication data from the old -master. To compare replica and master state, we can use -:ref:`box.info.signature `. - -1. Set ``read_only=true`` at the master. - - .. code-block:: tarantoolsession - - # at the master - tarantool> box.cfg{read_only=true} - -2. Record the master’s current position with ``box.info.signature``, containing - the sum of all LSNs in the master’s vector clock. - - .. code-block:: tarantoolsession - - # at the master - tarantool> box.info.signature - -3. Wait until the replica’s signature is the same as the master’s. - - .. code-block:: tarantoolsession - - # at the replica - tarantool> box.info.signature - -4. Set ``read_only=false`` at the replica to enable write operations. - - .. code-block:: tarantoolsession - - # at the replica - tarantool> box.cfg{read_only=false} - -These four steps ensure that the replica doesn’t accept new writes until it’s done -fetching writes from the master. - -.. _replication-master_master_bootstrap: - -Master-master bootstrap ------------------------ - -Now let us bootstrap a two-instance **master-master** set. For easier -administration, we make master#1 and master#2 instance files fully identical. - -.. image:: mm-2m-mesh.png - :align: center - -We re-use the master's instance file from the -:ref:`master-replica example ` above. - -.. code-block:: lua - - -- instance file for any of the two masters - box.cfg{ - listen = 3301, - replication = {'replicator:password@192.168.0.101:3301', -- master1 URI - 'replicator:password@192.168.0.102:3301'}, -- master2 URI - read_only = false - } - box.once("schema", function() - box.schema.user.create('replicator', {password = 'password'}) - box.schema.user.grant('replicator', 'replication') -- grant replication role - box.schema.space.create("test") - box.space.test:create_index("primary") - print('box.once executed on master #1') - end) - -In the :ref:`replication ` parameter, we define the -URIs of both masters in the replica set and say -``print('box.once executed on master #1')`` so it will be clear when and where the -``box.once()`` logic is executed. - -Now we can launch the two masters. Again, the launch order doesn't matter. -The ``box.once()`` logic will also be executed only once, at the master which -is elected as the replica set :ref:`leader ` at bootstrap. - -.. code-block:: console - - $ # launching master #1 - $ tarantool master1.lua - 2017-06-14 15:39:03.062 [47021] main/101/master1.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 15:39:03.062 [47021] main/101/master1.lua C> log level 5 - 2017-06-14 15:39:03.063 [47021] main/101/master1.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 15:39:03.065 [47021] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 15:39:03.065 [47021] main/105/applier/replicator@192.168.0.10 I> can't connect to master - 2017-06-14 15:39:03.065 [47021] main/105/applier/replicator@192.168.0.10 coio.cc:107 !> SystemError connect, called on fd 14, aka 192.168.0.102:57110: Connection refused - 2017-06-14 15:39:03.065 [47021] main/105/applier/replicator@192.168.0.10 I> will retry every 1 second - 2017-06-14 15:39:03.065 [47021] main/104/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 15:39:08.070 [47021] main/105/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.102:3301 - 2017-06-14 15:39:08.071 [47021] main/105/applier/replicator@192.168.0.10 I> authenticated - 2017-06-14 15:39:08.071 [47021] main/101/master1.lua I> bootstrapping replica from 192.168.0.102:3301 - 2017-06-14 15:39:08.073 [47021] main/105/applier/replicator@192.168.0.10 I> initial data received - 2017-06-14 15:39:08.074 [47021] main/105/applier/replicator@192.168.0.10 I> final data received - 2017-06-14 15:39:08.074 [47021] snapshot/101/main I> saving snapshot `/Users/e.shebunyaeva/work/tarantool-test-repl/master1_dir/00000000000000000008.snap.inprogress' - 2017-06-14 15:39:08.074 [47021] snapshot/101/main I> done - 2017-06-14 15:39:08.076 [47021] main/101/master1.lua I> vinyl checkpoint done - 2017-06-14 15:39:08.076 [47021] main/101/master1.lua I> ready to accept requests - box.once executed on master #1 - 2017-06-14 15:39:08.077 [47021] main C> entering the event loop - -.. code-block:: console - - $ # launching master #2 - $ tarantool master2.lua - 2017-06-14 15:39:07.452 [47022] main/101/master2.lua C> version 1.7.4-52-g980d30092 - 2017-06-14 15:39:07.453 [47022] main/101/master2.lua C> log level 5 - 2017-06-14 15:39:07.453 [47022] main/101/master2.lua I> mapping 268435456 bytes for tuple arena... - 2017-06-14 15:39:07.455 [47022] iproto/101/main I> binary: bound to [::]:3301 - 2017-06-14 15:39:07.455 [47022] main/104/applier/replicator@192.168.0.19 I> remote master is 1.7.4 at 192.168.0.101:3301 - 2017-06-14 15:39:07.455 [47022] main/105/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.102:3301 - 2017-06-14 15:39:07.455 [47022] main/101/master2.lua I> initializing an empty data directory - 2017-06-14 15:39:07.457 [47022] snapshot/101/main I> saving snapshot `/Users/e.shebunyaeva/work/tarantool-test-repl/master2_dir/00000000000000000000.snap.inprogress' - 2017-06-14 15:39:07.457 [47022] snapshot/101/main I> done - 2017-06-14 15:39:07.458 [47022] main/101/master2.lua I> vinyl checkpoint done - 2017-06-14 15:39:07.459 [47022] main/101/master2.lua I> ready to accept requests - 2017-06-14 15:39:07.460 [47022] main C> entering the event loop - 2017-06-14 15:39:08.072 [47022] main/103/main I> initial data sent. - 2017-06-14 15:39:08.073 [47022] relay/[::ffff:192.168.0.102]:/101/main I> recover from `/Users/e.shebunyaeva/work/tarantool-test-repl/master2_dir/00000000000000000000.xlog' - 2017-06-14 15:39:08.073 [47022] main/103/main I> final data sent. - 2017-06-14 15:39:08.077 [47022] relay/[::ffff:192.168.0.102]:/101/main I> recover from `/Users/e.shebunyaeva/work/tarantool-test-repl/master2_dir/00000000000000000000.xlog' - 2017-06-14 15:39:08.461 [47022] main/104/applier/replicator@192.168.0.10 I> authenticated diff --git a/doc/how-to/replication/repl_leader_elect.rst b/doc/how-to/replication/repl_leader_elect.rst deleted file mode 100644 index 2daca37163..0000000000 --- a/doc/how-to/replication/repl_leader_elect.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _how-to-repl_leader_elect: - -Managing leader elections -========================= - -Starting from version :doc:`2.6.1 `, -Tarantool has the built-in functionality -managing automated leader election in a replica set. -Learn more about the :ref:`concept of leader election `. - -.. _repl_leader_elect_config: - -Configuration -------------- - -.. code-block:: console - - box.cfg({ - election_mode = , - election_fencing_mode = , - election_timeout = , - replication_timeout = , - replication_synchro_quorum = - }) - -* ``election_mode`` -- specifies the role of a node in the leader election - process. For the details, refer to the :ref:`option description ` - in the configuration reference. -* ``election_fencing_mode`` -- specifies the :ref:`leader fencing mode `. - For the details, refer to the :ref:`option description ` in the configuration reference. -* ``election_timeout`` -- specifies the timeout between election rounds if the - previous round ended up with a split vote. For the details, refer to the - :ref:`option description ` in the configuration - reference. -* ``replication_timeout`` -- reuse of the :ref:`replication_timeout ` - configuration option for the purpose of the leader election process. - Heartbeats sent by an active leader have a timeout after which a new election - starts. Heartbeats are sent once per seconds. - The default value is ``1``. The leader is considered dead if it hasn't sent any - heartbeats for the period of ``replication_timeout * 4``. -* ``replication_synchro_quorum`` -- reuse of the :ref:`replication_synchro_quorum ` - option for the purpose of configuring the election quorum. The default value is ``1``, - meaning that each node becomes a leader immediately after voting for itself. - It is best to set up this option value to the ``( / 2) + 1``. - Otherwise, there is no guarantee that there is only one leader at a time. - -It is important to know that being a leader is not the only requirement for a node to be writable. -The leader should also satisfy the following requirements: - -* The :ref:`read_only ` option is set to ``false``. - -* The leader shouldn't be in the orphan state. - -Nothing prevents you from setting the ``read_only`` option to ``true``, -but the leader just won't be writable then. The option doesn't affect the -election process itself, so a read-only instance can still vote and become -a leader. - -.. _repl_leader_elect_monitoring: - -Monitoring ----------- - -To monitor the current state of a node regarding the leader election, you can -use the ``box.info.election`` function. -For details, -refer to the :doc:`function description `. - -**Example:** - -.. code-block:: console - - tarantool> box.info.election - --- - - state: follower - vote: 0 - leader: 0 - term: 1 - ... - -The Raft-based election implementation logs all its actions -with the ``RAFT:`` prefix. The actions are new Raft message handling, -node state changing, voting, and term bumping. - -.. _repl_leader_elect_important: - -Important notes ---------------- - -Leader election doesn't work correctly if the election quorum is set to less or equal -than `` / 2`` because in that case, a split vote can lead to -a state when two leaders are elected at once. - -For example, suppose there are five nodes. When the quorum is set to ``2``, ``node1`` -and ``node2`` can both vote for ``node1``. ``node3`` and ``node4`` can both vote -for ``node5``. In this case, ``node1`` and ``node5`` both win the election. -When the quorum is set to the cluster majority, that is -``( / 2) + 1`` or greater, the split vote is impossible. - -That should be considered when adding new nodes. -If the majority value is changing, it's better to update the quorum on all the existing nodes -before adding a new one. - -Also, the automated leader election doesn't bring many benefits in terms of data -safety when used *without* :ref:`synchronous replication `. -If the replication is asynchronous and a new leader gets elected, -the old leader is still active and considers itself the leader. -In such case, nothing stops -it from accepting requests from clients and making transactions. -Non-synchronous transactions are successfully committed because -they are not checked against the quorum of replicas. -Synchronous transactions fail because they are not able -to collect the quorum -- most of the replicas reject -these old leader's transactions since it is not a leader anymore. diff --git a/doc/how-to/replication/repl_remove_instances.rst b/doc/how-to/replication/repl_remove_instances.rst deleted file mode 100644 index 4ebd93cc25..0000000000 --- a/doc/how-to/replication/repl_remove_instances.rst +++ /dev/null @@ -1,225 +0,0 @@ -.. _replication-remove_instances: - -Removing instances -================== - -Let's assume that we have the following configured replica set with 3 instances -(*instance1*, *instance2* and *intance3*) and we want to remove *instance2*. - -.. image:: /concepts/replication/images/replication.svg - :align: left - -To remove it politely, follow these steps: - -1. Disconnect *instance2* from the cluster. -2. Disconnect the cluster from *instance2*. -3. Remove *instance2* from the ``_cluster`` space. - -.. image:: replicationX.svg - :align: left - -**Step 1: disconnecting an instance from the cluster** - -On the disconnecting instance *instance2*, run ``box.cfg{}`` -with a blank replication source: - -.. code-block:: tarantoolsession - - tarantool> box.cfg{replication=''} - -Then check that it was disconnected. Take a look at ``box.info.replication`` -on *instance2* (notice that ``replication.{1,3}.upstream`` is absent): - -.. code-block:: tarantoolsession - - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: db89978f-7115-4537-8417-9982bb5a256f - lsn: 9 - -- upstream is absent - downstream: - status: follow - idle: 0.93983899999876 - vclock: {1: 9} - 2: - id: 2 - uuid: 0a756d14-e437-4296-85b0-d27a0621613e - lsn: 0 - 3: - id: 3 - uuid: bb362584-c265-4e53-aeb6-450ae818bf59 - lsn: 0 - -- upstream is absent - downstream: - status: follow - idle: 0.26624799999991 - vclock: {1: 9} - ... - -Check *instance1* and *instance3* as well -(notice that the status of ``replication.2.downstream`` is ``stopped``): - -.. code-block:: tarantoolsession - - -- instance1 - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: db89978f-7115-4537-8417-9982bb5a256f - lsn: 9 - 2: - id: 2 - uuid: 0a756d14-e437-4296-85b0-d27a0621613e - lsn: 0 - upstream: - status: follow - idle: 0.3533439999992 - peer: replicator@localhost:3302 - lag: 0.0001220703125 - downstream: - status: stopped -- status has changed: - message: unexpected EOF when reading from socket, called on fd 13, aka [::1]:3301, - peer of [::1]:53776 - system_message: Broken pipe - 3: - id: 3 - uuid: bb362584-c265-4e53-aeb6-450ae818bf59 - lsn: 0 - upstream: - status: follow - idle: 0.35327999999936 - peer: replicator@localhost:3303 - lag: 0.00018095970153809 - downstream: - status: follow - idle: 0.68685100000221 - vclock: {1: 9} - ... - -**Step 2: disconnecting the cluster from the decommissioned instance** - -On every other instance in the cluster remove *instance2* from -the ``box.cfg{ replication }`` list and call an appropriate -``box.cfg{ replication = {instance1, instance3} }``: - -.. code-block:: tarantoolsession - - tarantool> box.cfg{ replication = { 'instance1-uri', 'instance3-uri' } } - -Take a look at ``box.info.replication`` on *instance2* to check that *instance1* and *instance3* were -disconnected -(notice that the status of ``replication.{1,3}.downstream`` is ``stopped``): - -.. code-block:: tarantoolsession - - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: db89978f-7115-4537-8417-9982bb5a256f - lsn: 9 - downstream: - status: stopped -- status has changed - message: unexpected EOF when reading from socket, called on fd 16, aka [::1]:3302, - peer of [::1]:53832 - system_message: Broken pipe - 2: - id: 2 - uuid: 0a756d14-e437-4296-85b0-d27a0621613e - lsn: 0 - 3: - id: 3 - uuid: bb362584-c265-4e53-aeb6-450ae818bf59 - lsn: 0 - downstream: - status: stopped -- status has changed - message: unexpected EOF when reading from socket, called on fd 18, aka [::1]:3302, - peer of [::1]:53825 - system_message: Broken pipe - ... - -Check *instance1* and *instance3* as well -(notice that the status of ``replication.2.upstream`` is ``stopped``): - -.. code-block:: tarantoolsession - - -- instance1 - tarantool> box.info.replication - --- - - 1: - id: 1 - uuid: db89978f-7115-4537-8417-9982bb5a256f - lsn: 9 - 2: - id: 2 - uuid: 0a756d14-e437-4296-85b0-d27a0621613e - lsn: 0 - downstream: - status: stopped -- status has changed - message: unexpected EOF when reading from socket, called on fd 13, aka [::1]:3301, - peer of [::1]:53776 - system_message: Broken pipe - 3: - id: 3 - uuid: bb362584-c265-4e53-aeb6-450ae818bf59 - lsn: 0 - upstream: - status: follow - idle: 0.50240100000156 - peer: replicator@localhost:3303 - lag: 0.00015711784362793 - downstream: - status: follow - idle: 0.14237199999843 - vclock: {1: 9} - ... - -**Step 3: persistent removal** - -If a removed instance rejoins later, it will receive all the updates made -by the other instances while it was disconnected. - -If an instance is decommissioned forever, we should clean up the ``_cluster`` space. -First, discover the ``id`` and ``uuid`` of the instance. -On *instance2*, call ``return box.info.id, box.info.uuid``: - -.. code-block:: tarantoolsession - - tarantool> return box.info.id, box.info.uuid - --- - - 2 - - '0a756d14-e437-4296-85b0-d27a0621613e' - ... - -Take a note of ``id`` and ``uuid``. - -Now choose any master from the remaining cluster and perform the following actions on it -(let's assume that we chose *instance1*): - -1. Select all records from the ``_cluster`` space: - -.. code-block:: tarantoolsession - - tarantool> box.space._cluster:select{} - --- - - - [1, 'db89978f-7115-4537-8417-9982bb5a256f'] - - [2, '0a756d14-e437-4296-85b0-d27a0621613e'] - - [3, 'bb362584-c265-4e53-aeb6-450ae818bf59'] - ... - -2. Check if the ``id`` and ``uuid`` of *instance2* are correct and remove them - from the cluster: - -.. code-block:: tarantoolsession - - tarantool> box.space._cluster:delete(2) - --- - - [2, '0a756d14-e437-4296-85b0-d27a0621613e'] - ... - -**Final checks** - -After all modifications, say ``box.info.replication`` to check the health status. diff --git a/doc/how-to/replication/repl_sync.rst b/doc/how-to/replication/repl_sync.rst deleted file mode 100644 index 9c89429eff..0000000000 --- a/doc/how-to/replication/repl_sync.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. _how-to-repl_sync: - -Configuring synchronous replication -=================================== - -Since version :doc:`2.5.1 `, -:ref:`synchronous replication ` -can be enabled per-space by using the ``is_sync`` option: - -.. code-block:: lua - - box.schema.create_space('test1', {is_sync = true}) - -Any transaction doing a DML request on this space becomes synchronous. -Notice that DDL on this space (including truncation) is **not** synchronous. - -To control the behavior of synchronous transactions, there exist global -``box.cfg`` :ref:`options `: - -.. code-block:: lua - - box.cfg{replication_synchro_quorum = } - -.. code-block:: lua - - box.cfg{replication_synchro_quorum = "N / 2 + 1"} - -This option tells how many replicas should confirm the receipt of a synchronous transaction before it is committed. -Since version :doc:`2.5.3 `, the parameter supports dynamic evaluation of the quorum number -(see :ref:`reference for the replication_synchro_quorum parameter ` for details). -Since version :doc:`2.10.0 `, -this option does not account for anonymous replicas. -As a usage example, consider this: - -.. code-block:: lua - - -- Instance 1 - box.cfg{ - listen = 3313, - replication_synchro_quorum = 2, - } - box.schema.user.grant('guest', 'super') - _ = box.schema.space.create('sync', {is_sync=true}) - _ = _:create_index('pk') - -.. code-block:: lua - - -- Instance 2 - box.cfg{ - listen = 3314, - replication = 'localhost:3313' - } - -.. code-block:: lua - - -- Instance 1 - box.space.sync:replace{1} - -When the first instance makes ``replace()``, it won't finish until the second -instance confirms its receipt and successful appliance. Note that the quorum is -set to 2, but the transaction was still committed even though there is only one -replica. This is because the master instance itself also participates in the quorum. - -Now, if the second instance is down, the first one won't be able to commit any -synchronous change. - -.. code-block:: lua - - -- Instance 2 - Ctrl+D - -.. code-block:: tarantoolsession - - -- Instance 1 - tarantool> box.space.sync:replace{2} - --- - - error: Quorum collection for a synchronous transaction is timed out - ... - -The transaction wasn't committed because it failed to achieve the quorum in the -given time. The time is a second configuration option: - -.. code-block:: lua - - box.cfg{replication_synchro_timeout = } - -It tells how many seconds to wait for a synchronous transaction quorum -replication until it is declared failed and is rolled back. - -A successful synchronous transaction commit is persisted in the WAL as a special -CONFIRM record. The rollbacks are similarly persisted with a ROLLBACK record. - -The ``timeout`` and ``quorum`` options are not used on replicas. It means if -the master dies, the pending synchronous transactions will be kept waiting on -the replicas until a new master is elected. - - -Tips and tricks ---------------- - -If a transaction is rolled back, it does not mean the ROLLBACK message reached -the replicas. It still can happen that the master node suddenly dies, so the -transaction will be committed by the new master. Your application logic should be -ready for that. - -Synchronous transactions are better to use with full mesh. Then the replicas can -talk to each other in case of the master node's death and still confirm some -pending transactions. diff --git a/doc/how-to/sql/improving_mysql.rst b/doc/how-to/sql/improving_mysql.rst deleted file mode 100644 index 393ea6dc7f..0000000000 --- a/doc/how-to/sql/improving_mysql.rst +++ /dev/null @@ -1,337 +0,0 @@ -.. _improving_mysql: - -================================================================================ -Improving MySQL with Tarantool -================================================================================ - -Replicating MySQL is one of the Tarantool’s killer functions. -It allows you to keep your existing MySQL database while at the same time -accelerating it and scaling it out horizontally. Even if you aren’t interested -in extensive expansion, simply replacing existing replicas with Tarantool can -save you money, because Tarantool is more efficient per core than MySQL. To read -a testimonial of a company that implemented Tarantool replication on a large scale, -please see -`here `_. - -Notes: - -* if you run into any trouble with regards to the basics of Tarantool, you may - wish to consult the :ref:`Getting started guide ` or - the :ref:`Data model description `. - -* these instructions are for **CentOS 7.5** and **MySQL 5.7**. They also assume - that you have systemd installed and are working with an existing MySQL installation. - -* a helpful log for troubleshooting during this tutorial is ``replicatord.log`` - in ``/var/log``. You can also have a look at the instance’s log ``example.log`` - in ``/var/log/tarantool``. - -So let’s proceed. - -#. First we’ll install the necessary packages in CentOS: - - .. code-block:: bash - - yum -y install git ncurses-devel cmake gcc-c++ boost boost-devel wget unzip nano bzip2 mysql-devel mysql-lib - -#. Next we’ll clone the Tarantool-MySQL replication package from GitHub: - - .. code-block:: bash - - git clone https://github.com/tarantool/mysql-tarantool-replication.git - -#. Now we can build the replicator with cmake: - - .. code-block:: bash - - cd mysql-tarantool-replication - git submodule update --init --recursive - cmake . - make - -#. Our replicator will run as a systemd daemon called replicatord, so let’s edit - its systemd service file, ``replicatord.service``, in the - mysql-tarantool-replication repo. - - .. code-block:: bash - - nano replicatord.service - - Change the following line: - - .. code-block:: bash - - ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.cfg - - Replace the ``.cfg`` extension with ``.yml``: - - .. code-block:: bash - - ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.yml - -#. Next let’s copy some files from our replicatord repo to other necessary locations: - - .. code-block:: bash - - cp replicatord /usr/local/sbin/replicatord - cp replicatord.service /etc/systemd/system - -#. Now let’s enter the MySQL console and create a sample database (depending on - your existing installation, you may of course be a user other than root): - - .. code-block:: sql - - mysql -u root -p - CREATE DATABASE menagerie; - QUIT - -#. Next we’ll get some sample data from MySQL, which we’ll pull into our root - directory, then install from the terminal: - - .. code-block:: sql - - cd - wget http://downloads.mysql.com/docs/menagerie-db.zip - unzip menagerie-db.zip - cd menagerie-db - mysql -u root -p menagerie < cr_pet_tbl.sql - mysql -u root -p menagerie < load_pet_tbl.sql - mysql menagerie -u root -p < ins_puff_rec.sql - mysql menagerie -u root -p < cr_event_tbl.sql - -#. Let’s enter the MySQL console now and massage the data for use with the - Tarantool replicator (we are adding an ID, changing a field name to avoid - conflict, and cutting down the number of fields; note that with real data, - this is the step that will involve the most tweaking): - - .. code-block:: sql - - mysql -u root -p - USE menagerie; - ALTER TABLE pet ADD id INT PRIMARY KEY AUTO_INCREMENT FIRST; - ALTER TABLE pet CHANGE COLUMN 'name' 'name2' VARCHAR(255); - ALTER TABLE pet DROP sex, DROP birth, DROP death; - QUIT - -#. Now that we have the sample data set up, we’ll need to edit MySQL’s - configuration file for use with the replicator. - - .. code-block:: bash - - cd - nano /etc/my.cnf - - Note that your ``my.cnf`` for MySQL could be in a slightly different location. - Set: - - .. code-block:: bash - - [mysqld] - binlog_format = ROW - server_id = 1 - log-bin = mysql-bin - interactive_timeout = 3600 - wait_timeout = 3600 - max_allowed_packet = 32M - socket = /var/lib/mysql/mysql.sock - bind-address = 127.0.0.1 - - [client] - socket = /var/lib/mysql/mysql.sock - -#. After exiting nano, we’ll restart mysqld: - - .. code-block:: bash - - systemctl restart mysqld - -#. Next, let’s install Tarantool and set up spaces for replication. - Go to the `Download page - `_ and - follow the instructions there to install Tarantool. - -#. Now we will write a standard Tarantool program by editing the Lua example, - which comes with Tarantool: - - .. code-block:: bash - - cd - nano /etc/tarantool/instances.available/example.lua - -#. Replace the entire contents of the file with the following: - - .. code-block:: lua - - box.cfg { - listen = 3301; - memtx_memory = 128 * 1024 * 1024; -- 128Mb - memtx_min_tuple_size = 16; - memtx_max_tuple_size = 128 * 1024 * 1024; -- 128Mb - vinyl_memory = 128 * 1024 * 1024; -- 128Mb - vinyl_cache = 128 * 1024 * 1024; -- 128Mb - vinyl_max_tuple_size = 128 * 1024 * 1024; -- 128Mb - vinyl_write_threads = 2; - wal_mode = "none"; - wal_max_size = 256 * 1024 * 1024; - checkpoint_interval = 60 * 60; -- one hour - checkpoint_count = 6; - force_recovery = true; - - -- 1 – SYSERROR - -- 2 – ERROR - -- 3 – CRITICAL - -- 4 – WARNING - -- 5 – INFO - -- 6 – VERBOSE - -- 7 – DEBUG - log_level = 7; - too_long_threshold = 0.5; - } - - box.schema.user.grant('guest','read,write,execute','universe') - - local function bootstrap() - - if not box.space.mysqldaemon then - s = box.schema.space.create('mysqldaemon') - s:create_index('primary', - {type = 'tree', parts = {1, 'unsigned'}, if_not_exists = true}) - end - - if not box.space.mysqldata then - t = box.schema.space.create('mysqldata') - t:create_index('primary', - {type = 'tree', parts = {1, 'unsigned'}, if_not_exists = true}) - end - - end - - bootstrap() - - To understand more of what’s happening here, it would be best to have a look - back at the earlier - `articles `_ - in the Tarantool 101 series or use the :ref:`getting-started ` guide. - -#. Now we need to create a symlink from ``instances.available`` to a directory named - ``instances.enabled`` (similar to NGINX). So in ``/etc/tarantool`` run the - following: - - .. code-block:: bash - - mkdir instances.enabled - ln -s /instances.available/example.lua instances.enabled - -#. Next we can start up our Lua program with ``tt``, the Tarantool command-line - utility: - - .. code-block:: bash - - tt start example - -#. Now let’s enter our Tarantool instance, where we can check that our target - spaces were successfully created: - - .. code-block:: bash - - tt connect example - - .. code-block:: tarantoolsession - - tarantool> box.space._space:select() - - At the bottom you will see "mysqldaemon" and "mysqldata" spaces. Then exit with "CTRL+C". - -#. Now that we have MySQL and Tarantool set up, we can proceed to configure - our replicator. First let’s work with ``replicatord.yml`` in the main - ``tarantool-mysql-replication`` directory. - - .. code-block:: bash - - nano replicatord.yml - - Change the entire file as follows, making sure to add your MySQL password and - to set the appropriate user: - - .. code-block:: bash - - mysql: - host: 127.0.0.1 - port: 3306 - user: root - password: - connect_retry: 15 # seconds - - tarantool: - host: 127.0.0.1:3301 - binlog_pos_space: 512 - binlog_pos_key: 0 - connect_retry: 15 # seconds - sync_retry: 1000 # milliseconds - - mappings: - - database: menagerie - table: pet - columns: [ id, name2, owner, species ] - space: 513 - key_fields: [ 0 ] - # insert_call: function_name - # update_call: function_name - # delete_call: function_name - -#. Now we need to copy replicatord.yml to the location where systemd looks for it: - - .. code-block:: bash - - cp replicatord.yml /usr/local/etc/replicatord.yml - -#. Next we can start up the replicator: - - .. code-block:: bash - - systemctl start replicatord - - Now we can enter our Tarantool instance and do a select on the “mysqldata” - space. We will see the replicated content from MySQL: - - .. code-block:: bash - - tt connect example - - .. code-block:: tarantoolsession - - tarantool> box.space.mysqldata:select() - --- - - - [1, 'Fluffy', 'Harold', 'cat'] - - [2, 'Claws', 'Gwen', 'cat'] - - [3, 'Buffy', 'Harold', 'dog'] - - [4, 'Fang', 'Benny', 'dog'] - - [5, 'Bowser', 'Diane', 'dog'] - - [6, 'Chirpy', 'Gwen', 'bird'] - - [7, 'Whistler', 'Gwen', 'bird'] - - [8, 'Slim', 'Benny', 'snake'] - - [9, 'Puffball', 'Diane', 'hamster'] - - -#. Finally let’s enter a record into MySQL and then go back to Tarantool to make - sure it’s replicated. So first we’ll exit our Tarantool instance with - ``CTRL-C``, and then say: - - .. code-block:: sql - - mysql -u root -p - USE menagerie; - INSERT INTO pet(name2, owner, species) VALUES ('Spot', 'Brad', 'dog'); - QUIT - - Once back in the terminal enter: - - .. code-block:: bash - - tt connect example - - .. code-block:: tarantoolsession - - tarantool> box.space.mysqldata:select() - - You should see the replicated data in Tarantool! diff --git a/doc/how-to/using_docker.rst b/doc/how-to/using_docker.rst deleted file mode 100644 index f4e5a497c2..0000000000 --- a/doc/how-to/using_docker.rst +++ /dev/null @@ -1,236 +0,0 @@ -.. _getting_started-using_docker: - --------------------------------------------------------------------------------- -Using a Docker image --------------------------------------------------------------------------------- - -For trial and test purposes, we recommend using -`the official Tarantool images for Docker `_. -An official image contains a particular Tarantool version and all popular -external modules for Tarantool. -Everything is already installed and configured in Linux. -These images are the easiest way to install and use Tarantool. - -.. NOTE:: - - If you're new to Docker, we recommend going over - `this tutorial `_ - before proceeding with this chapter. - -.. _getting_started-launching_a-container: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Launching a container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you don't have Docker installed, please follow the official -`installation guide `_ -for your OS. - -To start a fully functional Tarantool instance, run a container with some minimal -options: - -.. code-block:: console - - $ docker run \ - --name mytarantool \ - -d -p 3301:3301 \ - -v /data/dir/on/host:/var/lib/tarantool \ - tarantool/tarantool:latest - -This command runs a new container named ``mytarantool``. -Docker starts it from an official image named ``tarantool/tarantool:latest``, -with the latest Tarantool version and all external modules already installed. - -Tarantool will accept incoming connections on ``localhost:3301``. -You can start using it as a key-value storage right away. - -Tarantool :ref:`persists data ` inside the container. -To make your test data available after you stop the container, -this command also mounts the host's directory ``/data/dir/on/host`` -(you need to specify here an absolute path to an existing local directory) -in the container's directory ``/var/lib/tarantool`` -(by convention, Tarantool in a container uses this directory to persist data). -Through this, all changes made in the mounted directory on the container's side -are applied to the host's disk. - -Tarantool's database module in the container is already -:doc:`configured ` and started. -You don't need to do it manually, unless you use Tarantool as an -:ref:`application server ` and run it with an application. - -.. NOTE:: - - If your container terminates immediately after starting, follow - `this page `_ - for a possible solution. - -.. _getting_started-docker-attaching: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Attaching to Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To attach to Tarantool that runs inside the container, run: - -.. code-block:: console - - $ docker exec -i -t mytarantool console - -This command: - -* Instructs Tarantool to open an interactive console port for incoming connections. -* Attaches to the Tarantool server inside the container under the ``admin`` user via - a standard Unix socket. - -Tarantool displays a prompt: - -.. code-block:: tarantoolsession - - tarantool.sock> - -Now you can enter requests on the command line. - -.. NOTE:: - - On production machines, Tarantool's interactive mode is designed for system - administration only. We use it for most examples in this manual, - because it is convenient for learning. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Creating a database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -While we're attached to the console, let's create a simple test database. - -First, create the first :term:`space` (named ``tester``): - -.. code-block:: tarantoolsession - - tarantool.sock> s = box.schema.space.create('tester') - -Format the created space by specifying :term:`field` names and :ref:`types `: - -.. code-block:: tarantoolsession - - tarantool.sock> s:format({ - > {name = 'id', type = 'unsigned'}, - > {name = 'band_name', type = 'string'}, - > {name = 'year', type = 'unsigned'} - > }) - -Create the first :ref:`index ` (named ``primary``): - -.. code-block:: tarantoolsession - - tarantool.sock> s:create_index('primary', { - > type = 'tree', - > parts = {'id'} - > }) - -This is a primary index based on the ``id`` field of each tuple. -``TREE`` is the most universal index type. To learn more, check the documentation on Tarantool :ref:`index types `. - -Insert three :term:`tuples ` (our name for records) -into the space: - -.. code-block:: tarantoolsession - - tarantool.sock> s:insert{1, 'Roxette', 1986} - tarantool.sock> s:insert{2, 'Scorpions', 2015} - tarantool.sock> s:insert{3, 'Ace of Base', 1993} - -To select a tuple using the ``primary`` index, run: - -.. code-block:: tarantoolsession - - tarantool.sock> s:select{3} - -The terminal screen now looks like this: - -.. code-block:: tarantoolsession - - tarantool.sock> s = box.schema.space.create('tester') - --- - ... - tarantool.sock> s:format({ - > {name = 'id', type = 'unsigned'}, - > {name = 'band_name', type = 'string'}, - > {name = 'year', type = 'unsigned'} - > }) - --- - ... - tarantool.sock> s:create_index('primary', { - > type = 'tree', - > parts = {'id'} - > }) - --- - - unique: true - parts: - - type: unsigned - is_nullable: false - fieldno: 1 - id: 0 - space_id: 512 - name: primary - type: TREE - ... - tarantool.sock> s:insert{1, 'Roxette', 1986} - --- - - [1, 'Roxette', 1986] - ... - tarantool.sock> s:insert{2, 'Scorpions', 2015} - --- - - [2, 'Scorpions', 2015] - ... - tarantool.sock> s:insert{3, 'Ace of Base', 1993} - --- - - [3, 'Ace of Base', 1993] - ... - tarantool.sock> s:select{3} - --- - - - [3, 'Ace of Base', 1993] - ... - -To add a secondary index based on the ``band_name`` field, run: - -.. code-block:: tarantoolsession - - tarantool.sock> s:create_index('secondary', { - > type = 'tree', - > parts = {'band_name'} - > }) - -To select tuples using the ``secondary`` index, run: - -.. code-block:: tarantoolsession - - tarantool.sock> s.index.secondary:select{'Scorpions'} - --- - - - [2, 'Scorpions', 2015] - ... - -To drop an index, run: - -.. code-block:: tarantoolsession - - tarantool> s.index.secondary:drop() - --- - ... - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Stopping a container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When the testing is over, stop the container politely: - -.. code-block:: console - - $ docker stop mytarantool - -This was a temporary container, and its disk/memory data were flushed when you -stopped it. But since you mounted a data directory from the host in the container, -Tarantool's data files were persisted to the host's disk. Now if you start a new -container and mount that data directory, Tarantool will recover all of the data -from disk and continue working with the persisted data. - diff --git a/doc/how-to/using_package_manager.rst b/doc/how-to/using_package_manager.rst deleted file mode 100644 index d13d6b82ed..0000000000 --- a/doc/how-to/using_package_manager.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. _getting_started-using_package_manager: - --------------------------------------------------------------------------------- -Using a package manager --------------------------------------------------------------------------------- - -For production purposes, we recommend that you install Tarantool via the -`official package manager `_. -You can choose one of three versions: LTS, stable, or beta. -An automatic build system creates, tests and publishes packages for every -push into a corresponding branch at -`Tarantool's GitHub repository `_. - -To download and install the package that's appropriate for your OS, -start a shell (terminal) and enter the command-line instructions provided -for your OS at Tarantool's `download page `_. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Starting Tarantool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To start working with Tarantool, start a terminal and run this: - -.. code-block:: console - - $ tarantool - $ # by doing this, you create a new Tarantool instance - -Tarantool starts in interactive mode and displays a prompt: - -.. code-block:: tarantoolsession - - tarantool> - -Now you can enter requests on the command line. - -.. NOTE:: - - On production machines, Tarantool's interactive mode is designed for system - administration only. We use it for most examples in this manual - because it is convenient for learning. - -.. _creating-db-locally: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Creating a database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here is how to create a simple test database after installation. - -#. To let Tarantool store data in a separate place, create a new directory - dedicated for tests: - - .. code-block:: console - - $ mkdir ~/tarantool_sandbox - $ cd ~/tarantool_sandbox - - You can delete the directory when the tests are completed. - -#. Check if the default port that the database instance will listen to is vacant. - - In versions before :doc:`2.4.2 `, during installation - the Tarantool packages for Debian and Ubuntu automatically enable and start - the demonstrative global ``example.lua`` instance that - listens to the ``3301`` port by default. The ``example.lua`` file showcases - the basic configuration and can be found in the ``/etc/tarantool/instances.enabled`` - or ``/etc/tarantool/instances.available`` directories. - - However, we encourage you to perform the instance startup manually, so you - can learn. - - Make sure the default port is vacant: - - #. To check if the demonstrative instance is running, run: - - .. code-block:: console - - $ lsof -i :3301 - COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME - tarantool 6851 root 12u IPv4 40827 0t0 TCP *:3301 (LISTEN) - - #. If it is running, kill the corresponding process. In this example: - - .. code-block:: console - - $ kill 6851 - -#. To start Tarantool's database module and make the instance accept TCP requests - on port ``3301``, run: - - .. code-block:: tarantoolsession - - tarantool> box.cfg{listen = 3301} - -#. Create the first :term:`space ` (named ``tester``): - - .. code-block:: tarantoolsession - - tarantool> s = box.schema.space.create('tester') - -#. Format the created space by specifying :term:`field` names and :ref:`types `: - - .. code-block:: tarantoolsession - - tarantool> s:format({ - > {name = 'id', type = 'unsigned'}, - > {name = 'band_name', type = 'string'}, - > {name = 'year', type = 'unsigned'} - > }) - -#. Create the first :ref:`index ` (named ``primary``): - - .. code-block:: tarantoolsession - - tarantool> s:create_index('primary', { - > type = 'tree', - > parts = {'id'} - > }) - - This is a primary index based on the ``id`` field of each tuple. - ``TREE`` is the most universal index type. To learn more, check the documentation on Tarantool :ref:`index types `. - -#. Insert three :term:`tuples ` (our name for records) - into the space: - - .. code-block:: tarantoolsession - - tarantool> s:insert{1, 'Roxette', 1986} - tarantool> s:insert{2, 'Scorpions', 2015} - tarantool> s:insert{3, 'Ace of Base', 1993} - -#. To select a tuple using the ``primary`` index, run: - - .. code-block:: tarantoolsession - - tarantool> s:select{3} - - The terminal screen now looks like this: - - .. code-block:: tarantoolsession - - tarantool> s = box.schema.space.create('tester') - --- - ... - tarantool> s:format({ - > {name = 'id', type = 'unsigned'}, - > {name = 'band_name', type = 'string'}, - > {name = 'year', type = 'unsigned'} - > }) - --- - ... - tarantool> s:create_index('primary', { - > type = 'tree', - > parts = {'id'} - > }) - --- - - unique: true - parts: - - type: unsigned - is_nullable: false - fieldno: 1 - id: 0 - space_id: 512 - name: primary - type: TREE - ... - tarantool> s:insert{1, 'Roxette', 1986} - --- - - [1, 'Roxette', 1986] - ... - tarantool> s:insert{2, 'Scorpions', 2015} - --- - - [2, 'Scorpions', 2015] - ... - tarantool> s:insert{3, 'Ace of Base', 1993} - --- - - [3, 'Ace of Base', 1993] - ... - tarantool> s:select{3} - --- - - - [3, 'Ace of Base', 1993] - ... - -#. To add a secondary index based on the ``band_name`` field, run: - - .. code-block:: tarantoolsession - - tarantool> s:create_index('secondary', { - > type = 'tree', - > parts = {'band_name'} - > }) - -#. To select tuples using the ``secondary`` index, run: - - .. code-block:: tarantoolsession - - tarantool> s.index.secondary:select{'Scorpions'} - --- - - - [2, 'Scorpions', 2015] - ... - -#. Now, to prepare for the example in the next section, try this: - - .. code-block:: tarantoolsession - - tarantool> box.schema.user.grant('guest', 'read,write,execute', 'universe') - -.. _connecting-remotely: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Connecting remotely -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the request ``box.cfg{listen = 3301}`` that we made earlier, the ``listen`` -value can be any form of a :ref:`URI ` (uniform resource identifier). -In this case, it’s just a local port: port ``3301``. You can send requests to the -listen URI via: - -(1) ``telnet``, -(2) a :ref:`connector `, -(3) another instance of Tarantool (using the :ref:`console ` module), or -(4) :ref:`tt ` administrative utility. - -Let’s try (3). - -Switch to another terminal. On Linux, for example, this means starting another -instance of a Bash shell. You can switch to any working directory in the new -terminal, not necessarily to ``~/tarantool_sandbox``. - -Start another instance of ``tarantool``: - -.. code-block:: console - - $ tarantool - -Use ``net.box`` to connect to the Tarantool instance -that’s listening on ``localhost:3301``": - -.. code-block:: tarantoolsession - - tarantool> net_box = require('net.box') - --- - ... - tarantool> conn = net_box.connect(3301) - --- - ... - -Try this request: - -.. code-block:: tarantoolsession - - tarantool> conn.space.tester:select{2} - -This means "send a request to that Tarantool instance, and display the result". -It is equivalent to the local request ``box.space.tester:select{2}``. -The result in this case is one of the tuples that was inserted earlier. -Your terminal screen should now look like this: - -.. code-block:: tarantoolsession - - $ tarantool - - Tarantool 2.6.1-32-g53dbba7c2 - type 'help' for interactive help - tarantool> net_box = require('net.box') - --- - ... - tarantool> conn = net_box.connect(3301) - --- - ... - tarantool> conn.space.tester:select{2} - --- - - - [2, 'Scorpions', 2015] - ... - -You can repeat ``box.space...:insert{}`` and ``box.space...:select{}`` -(or ``conn.space...:insert{}`` and ``conn.space...:select{}``) -indefinitely, on either Tarantool instance. - -When the testing is over: - -* To drop the space: ``s:drop()`` -* To stop ``tarantool``: Ctrl+C or Ctrl+D -* To stop Tarantool (an alternative): the standard Lua function - `os.exit() `_ -* To stop Tarantool (from another terminal): ``sudo pkill -f tarantool`` -* To destroy the test: ``rm -r ~/tarantool_sandbox`` diff --git a/doc/how-to/vshard_quick.rst b/doc/how-to/vshard_quick.rst deleted file mode 100644 index 61f8df9d09..0000000000 --- a/doc/how-to/vshard_quick.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _vshard-quick-start: - -Quick start with sharding -========================= - -For installation instructions, check out the :ref:`vshard installation manual `. - -For a pre-configured development cluster, check out the ``example/`` directory in -the `vshard repository `__. -This example includes 5 Tarantool instances and 2 replica sets: - -* ``router_1`` – a ``router`` instance -* ``storage_1_a`` – a ``storage`` instance, the **master** of the **first** replica set -* ``storage_1_b`` – a ``storage`` instance, the **replica** of the **first** replica set -* ``storage_2_a`` – a ``storage`` instance, the **master** of the **second** replica set -* ``storage_2_b`` – a ``storage`` instance, the **replica** of the **second** replica set - -All instances are managed using the :ref:`tt ` administrative utility. - -Change the directory to ``example/`` and use ``make`` to run the development cluster: - -.. code-block:: console - - $ cd example/ - $ make - -Essential ``make`` commands you need to know: - -* ``make start`` – start all Tarantool instances -* ``make stop`` – stop all Tarantool instances -* ``make logcat`` – show logs from all instances -* ``make enter`` – enter the admin console on ``router_1`` -* ``make clean`` – clean up all persistent data -* ``make test`` – run the test suite (you can also run ``test-run.py`` in the ``test`` directory) -* ``make`` – execute ``make stop``, ``make clean``, ``make start`` and ``make enter`` - -For example, to start all instances, use ``make start``: - -.. code-block:: console - - $ make start - $ ps x|grep tarantool - 46564 ?? Ss 0:00.34 tarantool storage_1_a.lua - 46566 ?? Ss 0:00.19 tarantool storage_1_b.lua - 46568 ?? Ss 0:00.35 tarantool storage_2_a.lua - 46570 ?? Ss 0:00.20 tarantool storage_2_b.lua - 46572 ?? Ss 0:00.25 tarantool router_1.lua - -To perform commands in the admin console, use the router's -:ref:`public API `: - -.. code-block:: tarantoolsession - - unix/:./data/router_1.control> vshard.router.info() - --- - - replicasets: - ac522f65-aa94-4134-9f64-51ee384f1a54: - replica: &0 - network_timeout: 0.5 - status: available - uri: storage@127.0.0.1:3303 - uuid: 1e02ae8a-afc0-4e91-ba34-843a356b8ed7 - uuid: ac522f65-aa94-4134-9f64-51ee384f1a54 - master: *0 - cbf06940-0790-498b-948d-042b62cf3d29: - replica: &1 - network_timeout: 0.5 - status: available - uri: storage@127.0.0.1:3301 - uuid: 8a274925-a26d-47fc-9e1b-af88ce939412 - uuid: cbf06940-0790-498b-948d-042b62cf3d29 - master: *1 - bucket: - unreachable: 0 - available_ro: 0 - unknown: 0 - available_rw: 3000 - status: 0 - alerts: [] - ... - -.. _vshard-config-cluster-example: - -Sample configuration --------------------- - -The configuration of a simple sharded cluster can look like this: - -.. code-block:: kconfig - - local cfg = { - memtx_memory = 100 * 1024 * 1024, - bucket_count = 10000, - rebalancer_disbalance_threshold = 10, - rebalancer_max_receiving = 100, - sharding = { - ['cbf06940-0790-498b-948d-042b62cf3d29'] = { - replicas = { - ['8a274925-a26d-47fc-9e1b-af88ce939412'] = { - uri = 'storage:storage@127.0.0.1:3301', - name = 'storage_1_a', - master = true - }, - ['3de2e3e1-9ebe-4d0d-abb1-26d301b84633'] = { - uri = 'storage:storage@127.0.0.1:3302', - name = 'storage_1_b' - } - }, - }, - ['ac522f65-aa94-4134-9f64-51ee384f1a54'] = { - replicas = { - ['1e02ae8a-afc0-4e91-ba34-843a356b8ed7'] = { - uri = 'storage:storage@127.0.0.1:3303', - name = 'storage_2_a', - master = true - }, - ['001688c3-66f8-4a31-8e19-036c17d489c2'] = { - uri = 'storage:storage@127.0.0.1:3304', - name = 'storage_2_b' - } - }, - }, - }, - } - -This cluster includes one ``router`` instance and two ``storage`` instances. -Each ``storage`` instance includes one master and one replica. -The ``sharding`` field defines the logical topology of a sharded Tarantool cluster. -All the other fields are passed to ``box.cfg()`` as they are, without modifications. -See the :ref:`Configuration reference ` section for details. - -On routers, call ``vshard.router.cfg(cfg)``: - -.. code-block:: lua - - cfg.listen = 3300 - - -- Start the database with sharding - vshard = require('vshard') - vshard.router.cfg(cfg) - -On storages, call ``vshard.storage.cfg(cfg, instance_uuid)``: - -.. code-block:: lua - - -- Get instance name - local MY_UUID = "de0ea826-e71d-4a82-bbf3-b04a6413e417" - - -- Call a configuration provider - local cfg = require('localcfg') - - -- Start the database with sharding - vshard = require('vshard') - vshard.storage.cfg(cfg, MY_UUID) - -``vshard.storage.cfg()`` automatically calls ``box.cfg()`` and configures the listen -port and replication parameters. - -For a sample configuration, see ``router.lua`` and ``storage.lua`` in the -``example/`` directory of the `vshard repository `__. diff --git a/doc/index.rst b/doc/index.rst index 3c0d334c1b..4f66a68fe4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -52,13 +52,10 @@ overview getting_started/index - how-to/index - concepts/index - CRUD operations - Cluster on Cartridge - book/admin/index - book/connectors - enterprise/index + platform/index + tooling/index + admin/index + connector/index reference/index - contributing/index release/index + contributing/index diff --git a/doc/overview.rst b/doc/overview.rst index 199939714b..8e779916a7 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -18,7 +18,7 @@ Here are some of Tarantool's key characteristics: and :ref:`data snapshots ` * **Cooperative multitasking**: transactions are performed in - :ref:`lightweight coroutines ` with no interthread locking + :ref:`lightweight coroutines ` with no inter-thread locking * **Advanced indexing**: :ref:`composite indexes `, :ref:`locale support `, @@ -38,7 +38,7 @@ and a single Tarantool instance can also receive :ref:`SQL requests `__ (Lua rocks). You can pick the ones that you need and install them manually. -Tarantool runs on Linux (x86_64, aarch64), Mac OS X (x86_64, M1), and FreeBSD (x86_64). +Tarantool runs on Linux (x86_64, aarch64), macOS (x86_64, aarch64), and FreeBSD (x86_64). You can use Tarantool with a programming language you're familiar with. For this purpose, a number of :ref:`connectors ` are provided. @@ -51,18 +51,91 @@ Editions Tarantool comes in two editions: the open-source **Community Edition (CE)** and the commercial **Enterprise Edition (EE)**. +.. _tarantool_community_edition: + +Tarantool Community Edition +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + **Tarantool Community Edition** lets you develop applications and speed up a system in operation. It features :ref:`synchronous replication `, affords easy :ref:`scalability `, and includes tools to develop efficient :ref:`applications `. The `Tarantool community `__ helps with any practical questions regarding the Community Edition. + +.. _tarantool_enterprise: +.. _tarantool_enterprise_edition: + +Tarantool Enterprise Edition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + **Tarantool Enterprise Edition** `provides advanced tools `__ for administration, deployment, and security management, along with premium support services. This edition includes all the Community Edition features and is more predictable in terms of solution cost and maintenance. The Enterprise Edition is shipped as an SDK and includes a number of closed-source modules. -See the :ref:`Tarantool Enterprise Edition ` documentation. + +.. NOTE:: + + In this documentation, topics related to Enterprise Edition features are marked with an ``Enterprise Edition`` admonition. + +.. ifconfig:: language == 'en' + + .. container:: documentation-main-page-description + + The Enterprise Edition provides an extended feature set for developing + and managing clustered Tarantool applications, such as: + + * Security :ref:`audit log `. + * SSL support for :ref:`traffic encryption `. + * :ref:`Centralized configuration storage `. + * :ref:`Supervised failover `. + * :ref:`Tuple compression `. + * :ref:`Non-blocking DDL `. + * :ref:`Security enforcement features `. + * :ref:`Read views `. + * :ref:`Write-ahead log extensions `. + * :ref:`Flight recorder `. + * Tarantool bindings to OpenLDAP. + * Enterprise database connectivity: + Oracle and any ODBC-supported DBMS + (for example, MySQL, Microsoft SQL Server). + * :ref:`Static package ` for standalone Linux systems. + + The Enterprise Edition is distributed in the form of an SDK, which includes + the following key components: + + * The extended Enterprise version of the :ref:`tt ` utility. + * :ref:`Tarantool Cluster Manager ` -- a web-based visual tool for managing Tarantool clusters. + + + +.. ifconfig:: language == 'ru' + + .. container:: documentation-main-page-description + + Enterprise-версия предлагает `дополнительные возможности `__ по + разработке и эксплуатации кластерных приложений, например: + + * :ref:`Статическая сборка ` для автономных Linux-систем. + * Модуль интеграции с OpenLDAP. + * :ref:`Журнал аудита безопасности `. + * Подключения к корпоративным базам данных: + Oracle и любым СУБД с интерфейсом ODBC (например, MySQL, Microsoft SQL Server). + * :ref:`Шифрование трафика ` с помощью SSL. + * :ref:`Централизованная конфигурация `. + * :ref:`Сжатие кортежей `. + * :ref:`Смена схемы данных в фоновом режиме `. + * :ref:`Функции обеспечения безопасности `. + * :ref:`Представления для чтения (read views) `. + * :ref:`Расширения для Write-ahead log `. + * :ref:`Flight recorder `. + + Enterprise-версия распространяется в форме SDK, который включает следующие + ключевые компоненты: + + * Расширенная Enterprise-версия утилиты :ref:`tt `. + * :ref:`Tarantool Cluster Manager ` -- визуальный веб-инструмент для управления кластерами Tarantool. .. _overview-use_cases: diff --git a/doc/platform/app/app_roles.rst b/doc/platform/app/app_roles.rst new file mode 100644 index 0000000000..52bf795c7b --- /dev/null +++ b/doc/platform/app/app_roles.rst @@ -0,0 +1,546 @@ +.. _application_roles: + +Application roles +================= + +An application role is a Lua module that implements specific functions or logic. +You can turn on or off a particular role for certain instances in a :ref:`configuration ` without restarting these instances. +A role is run when a configuration is loaded or reloaded. + +Roles can be divided into the following groups: + +- Tarantool's built-in roles. + For example, the ``config.storage`` role can be used to make a Tarantool replica set act as a :ref:`configuration storage `. +- Roles provided by third-party Lua modules. + For example, the `CRUD `__ module provides the ``roles.crud-storage`` and ``roles.crud-router`` roles that enable CRUD operations in a sharded cluster. +- Custom roles that are developed as a part of a cluster application. + For example, you can create a custom role to define a stored procedure or implement a supplementary service, such as an email notifier or a replicator. + +This section describes how to develop custom roles. +To learn how to enable and configure roles, see :ref:`configuration_application_roles`. + +.. NOTE:: + + Don't confuse application roles with other role types: + + - A role is a container for privileges that can be granted to users. Learn more in :ref:`access_control_concepts_roles`. + - A role of a replica set in regard to sharding. Learn more in :ref:`vshard_config_sharding_roles`. + + +.. _roles_create_custom_role_config: + +Providing a role configuration +------------------------------ + +A custom role can be configured in the same way as roles provided by Tarantool or third-party Lua modules. +You can learn more from :ref:`configuration_application_roles`. + +This example shows how to enable and configure the ``greeter`` role, which is implemented in the next section: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml + :language: yaml + :start-at: instance001 + :dedent: + +The role configuration provided in ``roles_cfg`` can be accessed when :ref:`validating ` and :ref:`applying ` this configuration. + +Tarantool includes the :ref:`experimental.config.utils.schema ` +built-in module that provides tools for managing user-defined configurations +of applications (``app.cfg``) and roles (``roles_cfg``). The examples below show its +basic usage. + +Given that a role is a :ref:`Lua module `, a role name is passed to ``require()`` to obtain the module. +When :ref:`developing an application `, you can place a file with the role code next to the cluster configuration file. + + + +.. _roles_create_custom_role: + +Creating a custom role +---------------------- + +.. _roles_create_custom_role_overview: + +Overview +~~~~~~~~ + +A custom application role is an object which implements custom functions or logic adding to Tarantool's built-in roles and roles provided by third-party Lua modules. +For example, a logging role can be created to add logging functionality on top of the built-in one. + +Since version :doc:`3.4.0 `, you can define an ``on_event`` callback for custom roles. The ``on_event`` callback is called +every time a ``box.status`` system event is broadcasted. +If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order +defined by roles dependencies. + +The ``on_event`` callback returns 3 arguments, when it is called: + +- ``config``, which contains the configuration of the role; + +- ``key``, which reflects the trigger event and is set to: + + - ``config.apply`` if the callback was triggered by a configuration update; + + - ``box.status`` if it was triggered by the ``box.status`` system event. +- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event. + If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event. + +.. NOTE:: + + - All ``on_event`` callbacks with the ``config.apply`` key are executed as a part of the configuration process. + Process statuses ``ready`` or ``check_warnings`` are reached only after all such ``on_event`` callbacks are done. + + - All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged + with the ``error`` level and the series execution continues. + +Creating a custom role includes the following steps: + +#. (Optional) Define the role configuration schema. +#. Define a function that validates a role configuration. +#. Define a function that applies a validated configuration. +#. Define a function that stops a role. +#. (Optional) Define roles from which this custom role depends on. +#. (Optional) Define the ``on_event`` callback function. + +As a result, a role module should return an object that has corresponding functions and fields specified: + +.. code-block:: lua + + return { + validate = function() -- ... -- end, + apply = function() -- ... -- end, + stop = function() -- ... -- end, + dependencies = { -- ... -- }, + on_event = function(config, key, value) + local log = require('log') + log.info('roles_cfg.my_role.foo: ' .. config.foo) + log.info('on_event is triggered by ' .. key) + log.info('is_ro: ' .. value.is_ro) + end, + } + +The examples in this article show how to do this. + +You can omit the optional steps and get a simple role as in the example below. + +.. code-block:: lua + + return { + validate = function() -- ... -- end, + apply = function() -- ... -- end, + stop = function() -- ... -- end, + } + +You can modify a role, for example, by adding dependencies or specifying the on_event callback. +If you modify a role, you need to restart the Tarantool instance with the role in order to apply the changes. + +.. NOTE:: + + - Code snippets shown in this section are included from the following application: `application_role_cfg `_. + +.. _roles_create_custom_role_schema: + +Defining the role configuration schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`experimental.config.utils.schema ` built-in module +provides the :ref:`config-utils-schema_object` class. An object of this class defines +a custom configuration scheme of a role or an application. + +This example shows how to define a schema that reflects the role configuration shown above: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :start-at: local greeter_schema + :end-before: local function validate + :dedent: + +If you don't use the module, skip this step. In this case, use the ``cfg`` argument +of the role's ``validate()`` and ``apply()`` functions to refer to its configuration +values, for example, ``cfg.greeting``. + +.. _roles_create_custom_role_validate: + +Validating a role configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To validate a role configuration, you need to define the :ref:`validate([cfg]) ` function. + +In the example below, the ``validate()`` function of the role configuration schema +is used to validate the ``greeting`` value: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :start-at: local function validate + :end-before: local function apply + :dedent: + +If the configuration is not valid, ``validate()`` reports an unrecoverable error by throwing an error object. + +.. _roles_create_custom_role_apply: + +Applying a role configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To apply the validated configuration, define the :ref:`apply([cfg]) ` function. +As the ``validate()`` function, ``apply()`` provides access to a role's configuration using the ``cfg`` argument. + +In the example below, the ``apply()`` function uses the :ref:`log ` module to write a value from the role configuration to the log: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :start-at: local function apply + :end-before: local function stop + :dedent: + +.. _roles_create_custom_role_stop: + +Stopping a role +~~~~~~~~~~~~~~~ + +To stop a role, use the :ref:`stop() ` function. + +In the example below, the ``stop()`` function uses the :ref:`log ` module to indicate that a role is stopped: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :start-at: local function stop + :end-before: return + :dedent: + +When you've defined all the role functions, you need to return an object that has corresponding functions specified: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :start-at: return + :dedent: + + + +.. _roles_create_custom_role_dependencies: + +Role dependencies +~~~~~~~~~~~~~~~~~ + +To define a role's dependencies, use the :ref:`dependencies ` field. +In this example, the ``byeer`` role has the ``greeter`` role as the dependency: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua + :language: lua + :dedent: + +A role cannot be started without its dependencies. +This means that all the dependencies of a role should be defined in the ``roles`` configuration parameter: + +.. code-block:: yaml + + instance001: + roles: [ greeter, byeer ] + +You can find the full example here: `application_role_cfg `_. + + + +.. _roles_create_custom_role_init: + +Adding initialization code +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can add initialization code to a role by defining and calling a function with an arbitrary name at the top level of a module, for example: + +.. code-block:: lua + + local function init() + -- ... -- + end + + init() + +For example, you can :ref:`create spaces `, define :ref:`indexes `, or :ref:`grant privileges ` to specific users or roles. + +See also: :ref:`roles_create_space`. + + + +.. _roles_create_space: + +Specifics of creating spaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a space in a role, you need to make sure that the target instance is in read-write mode (its :ref:`box.info.ro ` is ``false``). +You can check an instance state by subscribing to the ``box.status`` event using :ref:`box.watch() `: + +.. code-block:: lua + + box.watch('box.status', function() + -- creating a space + -- ... + end) + + +.. NOTE:: + + Given that a role may be enabled when an instance is already in read-write mode, + you also need to execute schema initialization code from :ref:`apply() `. + To make sure a space is created only once, use the :ref:`if_not_exists ` option. + + + +.. _roles_life_cycle: + +Roles life cycle +---------------- + +A role’s life cycle includes the stages described below. + +.. _roles_life_cycle_loading_roles: + +1) *Loading roles* + + On each run, all roles are loaded in the order they are specified in the :ref:`configuration `. + This stage takes effect when a role is enabled or an instance with this role is restarted. + At this stage, a role executes the :ref:`initialization code `. + + A role cannot be started if it has :ref:`dependencies ` that are not specified in a configuration. + + .. NOTE:: + + Dependencies do not affect the order in which roles are loaded. + However, the ``validate()``, ``apply()``, and ``stop()`` functions are executed taking dependencies into account. + Learn more in :ref:`roles_life_cycle_dependencies_specifics`. + + +.. _roles_life_cycle_stopping_roles: + +2) *Stopping roles* + + This stage takes effect during a configuration reload when a role is removed from the configuration for a given instance. + Note that all ``stop()`` calls are performed before any ``validate()`` or ``apply()`` calls. + This means that old roles are stopped first, and only then new roles are started. + +.. _roles_life_cycle_validating_role_config: + +3) *Validating a role's configurations* + + At this stage, a configuration for each role is validated using the corresponding :ref:`validate() ` function in the same order in which they are specified in the configuration. + +.. _roles_life_cycle_applying_role_config: + +4) *Applying a role's configurations* + + At this stage, a configuration for each role is applied using the corresponding :ref:`apply() ` function in the same order in which they are specified in the configuration. + + +All role's functions report an unrecoverable error by throwing an error object. +If an error is thrown in any phase, applying a configuration is stopped. +If starting or stopping a role throws an error, no roles are stopped or started afterward. +An error is caught and shown in :ref:`config:info() ` in the ``alerts`` section. + + +.. _roles_life_cycle_dependencies_specifics: + +Executing functions for dependent roles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For roles that :ref:`depend ` on each other, their ``validate()``, ``apply()``, and ``stop()`` functions are executed taking into account the dependencies. +Suppose, there are three independent and two dependent roles: + +.. code-block:: none + + role1 + role2 + role3 + └─── role4 + └─── role5 + +- ``role1``, ``role2``, and ``role5`` are independent roles. +- ``role3`` depends on ``role4``, ``role4`` depends on ``role5``. + +The roles are enabled in a configuration as follows: + +.. code-block:: yaml + + roles: [ role1, role2, role3, role4, role5 ] + +In this case, ``validate()`` and ``apply()`` for these roles are executed in the following order: + +.. code-block:: none + + role1 -> role2 -> role5 -> role4 -> role3 + +Roles removed from a configuration are stopped in the order reversed to the order they are specified in a configuration, taking into account the dependencies. +Suppose, all roles except ``role1`` are removed from the configuration above: + +.. code-block:: yaml + + roles: [ role1 ] + +After reloading a configuration, ``stop()`` functions for the removed roles are executed in the following order: + +.. code-block:: none + + role3 -> role4 -> role5 -> role2 + + + + +.. _roles_example_custom_role: + +Example: Role without a configuration +------------------------------------- + +The example below shows how to enable the custom ``greeter`` role for ``instance001``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/config.yaml + :language: yaml + :start-at: instance001 + :end-at: greeter + :dedent: + +The implementation of this role looks as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/greeter.lua + :language: lua + :dedent: + +Example on GitHub: `application_role `_ + + + +.. _roles_example_custom_role_with_config: + +Example: Role with a configuration +---------------------------------- + +The example below shows how to enable the custom ``greeter`` role for ``instance001`` and specify the configuration for this role: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml + :language: yaml + :start-at: instance001 + :end-at: greeting + :dedent: + +The implementation of this role looks as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua + :language: lua + :dedent: + +Example on GitHub: `application_role_cfg `_ + + + + +.. _roles_example_custom_role_http_api: + +Example: HTTP API +----------------- + +The example below shows how to enable and configure the ``http-api`` custom role: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml + :language: yaml + :start-at: instance001 + :end-at: 8080 + :dedent: + +The implementation of this role looks as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua + :language: lua + :dedent: + +Example on GitHub: `application_role_http_api `_ + + + + + +.. _roles_api_reference: + +API Reference +------------- + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 35 65 + + * - **Members** + - + + * - :ref:`validate([cfg]) ` + - Validate a role's configuration. + + * - :ref:`apply([cfg]) ` + - Apply a role's configuration. + + * - :ref:`stop() ` + - Stop a role. + + * - :ref:`dependencies ` + - Define a role's dependencies. + + + + +.. _roles_api_reference_validate: + +.. function:: validate([cfg]) + + Validate a role's configuration. + This function is called on instance startup or when the :ref:`configuration is reloaded ` for the instance with this role. + Note that the ``validate()`` function is called regardless of whether the role's configuration or any field in a cluster's configuration is changed. + + ``validate()`` should throw an error if the validation fails. + + :param cfg: a role's role configuration to be validated. + This parameter provides access to configuration options defined in :ref:`roles_cfg.\ `. + To get values of configuration options placed outside ``roles_cfg.``, use :ref:`config:get() `. + + See also: :ref:`roles_create_custom_role_validate` + + +.. _roles_api_reference_apply: + +.. function:: apply([cfg]) + + Apply a role's configuration. + ``apply()`` is called after ``validate()`` is executed for all the enabled roles. + As the ``validate()`` function, ``apply()`` is called on instance startup or when the configuration is reloaded for the instance with this role. + + ``apply()`` should throw an error if the specified configuration can't be applied. + + .. NOTE:: + + Note that ``apply()`` is not invoked if an instance switches to read-write mode when :ref:`replication.failover ` is set to ``election`` or ``supervised``. + You can check an instance state by subscribing to the ``box.status`` event using :ref:`box.watch() `. + + :param cfg: a role's role configuration to be applied. + This parameter provides access to configuration options defined in :ref:`roles_cfg.\ `. + To get values of configuration options placed outside ``roles_cfg.``, use :ref:`config:get() `. + + See also: :ref:`roles_create_custom_role_apply` + + +.. _roles_api_reference_stop: + +.. function:: stop() + + Stop a role. + This function is called on configuration reload if the role is removed from ``roles`` for the given instance. + + See also: :ref:`roles_create_custom_role_stop` + +.. _roles_api_reference_dependencies: + +.. data:: dependencies + + (Optional) Define a role's dependencies. + + :rtype: table + + See also: :ref:`roles_create_custom_role_dependencies` + diff --git a/doc/how-to/app/aster.svg b/doc/platform/app/aster.svg similarity index 100% rename from doc/how-to/app/aster.svg rename to doc/platform/app/aster.svg diff --git a/doc/how-to/app/c_tutorial.rst b/doc/platform/app/c_tutorial.rst similarity index 99% rename from doc/how-to/app/c_tutorial.rst rename to doc/platform/app/c_tutorial.rst index af34f58bd8..68172c0329 100644 --- a/doc/how-to/app/c_tutorial.rst +++ b/doc/platform/app/c_tutorial.rst @@ -99,7 +99,7 @@ easy.c Start another shell. Change directory (``cd``) so that it is the same as the directory that the client is running on. -Create a file. Name it ``easy.c``. Put these six lines in it. +Create a file. Name it ``easy.c``. Put the following code in it: .. code-block:: c diff --git a/doc/how-to/app/cookbook.rst b/doc/platform/app/cookbook.rst similarity index 93% rename from doc/how-to/app/cookbook.rst rename to doc/platform/app/cookbook.rst index 1902fc5450..65a84b3ad3 100644 --- a/doc/how-to/app/cookbook.rst +++ b/doc/platform/app/cookbook.rst @@ -249,56 +249,6 @@ a metatable). local b = a + point(0.5, 8) print(#b) --> 12.5 -.. _cookbook-ffi_varbinary_insert: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -ffi_varbinary_insert.lua -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the `LuaJIT ffi library `_ to -insert a tuple which has a VARBINARY field. - -Note that it is allowed only inside a memtx transaction: when ``box_insert()`` -does not yield. - -Lua does not have direct support for VARBINARY, so using C -is one way to put in data which in MessagePack is stored as bin -(MP_BIN). If the tuple is retrieved later, field "b" will have type = 'cdata'. - -.. code-block:: lua - - #!/usr/bin/env tarantool - - -- box.cfg{} should be here - - s = box.schema.space.create('withdata') - s:format({{"b", "varbinary"}}) - s:create_index('pk', {parts = {1, "varbinary"}}) - - buffer = require('buffer') - ffi = require('ffi') - - function varbinary_insert(space, bytes) - local tmpbuf = buffer.ibuf() - local p = tmpbuf:alloc(3 + #bytes) - p[0] = 0x91 -- MsgPack code for "array-1" - p[1] = 0xC4 -- MsgPack code for "bin-8" so up to 256 bytes - p[2] = #bytes - for i, c in pairs(bytes) do p[i + 3 - 1] = c end - ffi.cdef[[int box_insert(uint32_t space_id, - const char *tuple, - const char *tuple_end, - box_tuple_t **result);]] - ffi.C.box_insert(space.id, tmpbuf.rpos, tmpbuf.wpos, nil) - tmpbuf:recycle() - end - - varbinary_insert(s, {0xDE, 0xAD, 0xBE, 0xAF}) - varbinary_insert(s, {0xFE, 0xED, 0xFA, 0xCE}) - - -- if successful, Tarantool enters the event loop now - - .. _cookbook-print_arrays: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/how-to/app/cookbook/main.go b/doc/platform/app/cookbook/main.go similarity index 100% rename from doc/how-to/app/cookbook/main.go rename to doc/platform/app/cookbook/main.go diff --git a/doc/concepts/coop_multitasking.rst b/doc/platform/app/coop_multitasking.rst similarity index 100% rename from doc/concepts/coop_multitasking.rst rename to doc/platform/app/coop_multitasking.rst diff --git a/doc/how-to/app/creating_app.rst b/doc/platform/app/creating_app.rst similarity index 100% rename from doc/how-to/app/creating_app.rst rename to doc/platform/app/creating_app.rst diff --git a/doc/how-to/app/creating_app/GIS.rst b/doc/platform/app/creating_app/GIS.rst similarity index 100% rename from doc/how-to/app/creating_app/GIS.rst rename to doc/platform/app/creating_app/GIS.rst diff --git a/doc/how-to/app/creating_app/aster.svg b/doc/platform/app/creating_app/aster.svg similarity index 100% rename from doc/how-to/app/creating_app/aster.svg rename to doc/platform/app/creating_app/aster.svg diff --git a/doc/how-to/app/creating_app/avro_schemas.rst b/doc/platform/app/creating_app/avro_schemas.rst similarity index 100% rename from doc/how-to/app/creating_app/avro_schemas.rst rename to doc/platform/app/creating_app/avro_schemas.rst diff --git a/doc/how-to/app/creating_app/bootstrapping_a_database.rst b/doc/platform/app/creating_app/bootstrapping_a_database.rst similarity index 100% rename from doc/how-to/app/creating_app/bootstrapping_a_database.rst rename to doc/platform/app/creating_app/bootstrapping_a_database.rst diff --git a/doc/how-to/app/creating_app/fibers.rst b/doc/platform/app/creating_app/fibers.rst similarity index 100% rename from doc/how-to/app/creating_app/fibers.rst rename to doc/platform/app/creating_app/fibers.rst diff --git a/doc/how-to/app/creating_app/index_iterators.rst b/doc/platform/app/creating_app/index_iterators.rst similarity index 100% rename from doc/how-to/app/creating_app/index_iterators.rst rename to doc/platform/app/creating_app/index_iterators.rst diff --git a/doc/how-to/app/creating_app/logging.rst b/doc/platform/app/creating_app/logging.rst similarity index 100% rename from doc/how-to/app/creating_app/logging.rst rename to doc/platform/app/creating_app/logging.rst diff --git a/doc/how-to/app/creating_app/modules_rocks_and_applications.rst b/doc/platform/app/creating_app/modules_rocks_and_applications.rst similarity index 100% rename from doc/how-to/app/creating_app/modules_rocks_and_applications.rst rename to doc/platform/app/creating_app/modules_rocks_and_applications.rst diff --git a/doc/how-to/app/creating_app/nginx.rst b/doc/platform/app/creating_app/nginx.rst similarity index 100% rename from doc/how-to/app/creating_app/nginx.rst rename to doc/platform/app/creating_app/nginx.rst diff --git a/doc/how-to/app/creating_app/non-blockng_io.rst b/doc/platform/app/creating_app/non-blockng_io.rst similarity index 100% rename from doc/how-to/app/creating_app/non-blockng_io.rst rename to doc/platform/app/creating_app/non-blockng_io.rst diff --git a/doc/how-to/app/ide_1.png b/doc/platform/app/ide_1.png similarity index 100% rename from doc/how-to/app/ide_1.png rename to doc/platform/app/ide_1.png diff --git a/doc/how-to/app/ide_2.png b/doc/platform/app/ide_2.png similarity index 100% rename from doc/how-to/app/ide_2.png rename to doc/platform/app/ide_2.png diff --git a/doc/how-to/app/ide_3.png b/doc/platform/app/ide_3.png similarity index 100% rename from doc/how-to/app/ide_3.png rename to doc/platform/app/ide_3.png diff --git a/doc/how-to/app/ide_4.png b/doc/platform/app/ide_4.png similarity index 100% rename from doc/how-to/app/ide_4.png rename to doc/platform/app/ide_4.png diff --git a/doc/how-to/app/ide_5.png b/doc/platform/app/ide_5.png similarity index 100% rename from doc/how-to/app/ide_5.png rename to doc/platform/app/ide_5.png diff --git a/doc/how-to/app/ide_6.png b/doc/platform/app/ide_6.png similarity index 100% rename from doc/how-to/app/ide_6.png rename to doc/platform/app/ide_6.png diff --git a/doc/how-to/app/ide_7.png b/doc/platform/app/ide_7.png similarity index 100% rename from doc/how-to/app/ide_7.png rename to doc/platform/app/ide_7.png diff --git a/doc/how-to/app/ide_8.png b/doc/platform/app/ide_8.png similarity index 100% rename from doc/how-to/app/ide_8.png rename to doc/platform/app/ide_8.png diff --git a/doc/how-to/app/ide_9.png b/doc/platform/app/ide_9.png similarity index 100% rename from doc/how-to/app/ide_9.png rename to doc/platform/app/ide_9.png diff --git a/doc/platform/app/index.rst b/doc/platform/app/index.rst new file mode 100644 index 0000000000..7f89536610 --- /dev/null +++ b/doc/platform/app/index.rst @@ -0,0 +1,24 @@ +.. _how-to-app-server: + +Applications +============ + +Using Tarantool as an application server, you can write your own applications. +Tarantool’s native language for writing applications is +`Lua `_, so a typical application would be +a file that contains your Lua script. But you can also write applications +in C or C++. + +.. toctree:: + :maxdepth: 1 + + launching_app + app_roles + coop_multitasking + cookbook + lua_tutorials + lua_tips + rocksref + creating_app + c_tutorial + using_ide diff --git a/doc/how-to/app/launching_app.rst b/doc/platform/app/launching_app.rst similarity index 97% rename from doc/how-to/app/launching_app.rst rename to doc/platform/app/launching_app.rst index 205b7397c7..dc6c3015aa 100644 --- a/doc/how-to/app/launching_app.rst +++ b/doc/platform/app/launching_app.rst @@ -49,7 +49,7 @@ Now let's discuss how we can launch our application with Tarantool. Launching in Docker -------------------------------------------------------------------------------- -If we run Tarantool in a :ref:`Docker container `, +If we run Tarantool in a Docker container, the following command will start Tarantool without any application: .. code-block:: console @@ -82,8 +82,7 @@ is ``/opt/tarantool``, and the directory for data is ``/var/lib/tarantool``. Launching a binary program -------------------------------------------------------------------------------- -If we run Tarantool from a :ref:`package -` or from a :ref:`source build +If we run Tarantool from a :ref:`package ` or from a :ref:`source build `, we can launch our application: * in the script mode, diff --git a/doc/reference/lua_tips.rst b/doc/platform/app/lua_tips.rst similarity index 100% rename from doc/reference/lua_tips.rst rename to doc/platform/app/lua_tips.rst diff --git a/doc/how-to/app/lua_tutorials.rst b/doc/platform/app/lua_tutorials.rst similarity index 100% rename from doc/how-to/app/lua_tutorials.rst rename to doc/platform/app/lua_tutorials.rst diff --git a/doc/platform/app/rocksref.rst b/doc/platform/app/rocksref.rst new file mode 100644 index 0000000000..aa348fce22 --- /dev/null +++ b/doc/platform/app/rocksref.rst @@ -0,0 +1,84 @@ +.. _enterprise-rocks: + +=============================================================================== +Enterprise modules +=============================================================================== + +This section covers open and closed source Lua modules for Tarantool Enterprise Edition +included in the distribution as an offline rocks repository. + +------------------------------------------------------------------------------- +Open source modules +------------------------------------------------------------------------------- + +* `avro-schema `_ + is an assembly of `Apache Avro `_ + schema tools; + +* :ref:`checks ` + is a type checker of functional arguments. This library that declares + a ``checks()`` function and ``checkers`` table that allow to check the + parameters passed to a Lua function in a fast and unobtrusive way. +* `http `_ is an + on-board HTTP-server, which comes in addition to Tarantool's out-of-the-box + HTTP client, and must be installed as described in the + :ref:`installation section `. +* `icu-date `_ + is a date-and-time formatting library for Tarantool + based on International Components for Unicode; +* `kafka `_ + is a full-featured high-performance ``kafka`` library for Tarantool + based on ``librdkafka``; +* `luacheck `_ is a static analyzer and + linter for Lua, preconfigured for Tarantool. +* `luarapidxml `_ + is a fast XML parser. +* `luatest `_ is + a Tarantool test framework written in Lua. +* :ref:`membership ` + builds a mesh from multiple Tarantool instances based on gossip protocol. + The mesh monitors itself, helps members discover everyone else in the group + and get notified about their status changes with low latency. It is built + upon the ideas from Consul or, more precisely, the SWIM algorithm. +* :ref:`metrics ` is a collection + of useful monitoring metrics. +* `tracing `_ + is a module for debugging performance issues. +* :ref:`vshard ` + is an automatic sharding system that enables horizontal scaling for Tarantool + DBMS instances. + +------------------------------------------------------------------------------- +Closed source modules +------------------------------------------------------------------------------- + +* ``ldap`` allows you to authenticate in a LDAP server and perform searches. +* ``odbc`` is an ODBC connector for Tarantool based on unixODBC. +* ``oracle`` + is an Oracle connector for Lua applications through which they can send and + receive data to and from Oracle databases. + The advantage of the Tarantool-Oracle integration is that anyone can handle all + the tasks with Oracle DBMSs (control, manipulation, storage, access) with the + same high-level language (Lua) and with minimal delay. +* ``task`` + is a module for managing background tasks in a Tarantool cluster. + +.. _enterprise-rocks-install: + +------------------------------------------------------------------------------- +Installing and using modules +------------------------------------------------------------------------------- + +To use a module, install the following: + +#. All the necessary third-party software packages (if any). See the + module's prerequisites for the list. + +#. The module itself on every Tarantool instance: + + .. code-block:: console + + $ tt rocks install MODULE_NAME [MODULE_VERSION] + +See the :ref:`tt rocks reference ` to learn more about +managing Lua modules. diff --git a/doc/how-to/app/using_ide.rst b/doc/platform/app/using_ide.rst similarity index 100% rename from doc/how-to/app/using_ide.rst rename to doc/platform/app/using_ide.rst diff --git a/doc/concepts/yields.svg b/doc/platform/app/yields.svg similarity index 100% rename from doc/concepts/yields.svg rename to doc/platform/app/yields.svg diff --git a/doc/concepts/atomic.rst b/doc/platform/atomic.rst similarity index 90% rename from doc/concepts/atomic.rst rename to doc/platform/atomic.rst index e3ee0e9bf3..a8d7d0a9ce 100644 --- a/doc/concepts/atomic.rst +++ b/doc/platform/atomic.rst @@ -1,20 +1,20 @@ -:noindex: -:fullwidth: - -.. _atomic-atomic_execution: - -Transactions -============ - -Transactions allow users to perform multiple operations atomically. - -For more information on how transactions work in Tarantool, see the following sections: - -.. toctree:: - :maxdepth: 2 - - atomic/transaction_model - atomic/thread_model - atomic/txn_mode_default - atomic/txn_mode_mvcc - +:noindex: +:fullwidth: + +.. _atomic-atomic_execution: + +Transactions +============ + +Transactions allow users to perform multiple operations atomically. + +For more information on how transactions work in Tarantool, see the following sections: + +.. toctree:: + :maxdepth: 1 + + atomic/transaction_model + atomic/thread_model + atomic/txn_mode_default + atomic/txn_mode_mvcc + diff --git a/doc/platform/atomic/thread_model.rst b/doc/platform/atomic/thread_model.rst new file mode 100644 index 0000000000..8dee877b46 --- /dev/null +++ b/doc/platform/atomic/thread_model.rst @@ -0,0 +1,85 @@ +.. _thread_model: + +Thread model +============ + +.. _main_threads: + +Main threads +------------ + +The thread model assumes that a :ref:`query ` received by Tarantool via network +is processed with three operating system **threads**: + +1. The **network thread** (or :ref:`threads `) + on the server side receives the query, parses + the statement, checks if it is correct, and then transforms it into a special + structure -- a message containing an executable statement and its options. + +2. The network thread sends this message to the instance's + **transaction processor thread** (*TX thread*) via a lock-free message bus. + Lua programs are executed directly in the transaction processor thread, + and do not need to be parsed and prepared. + + The TX thread either uses a space index to find and update the tuple, + or executes a stored function that performs a data operation. + +3. The execution of the operation results in a message to the + :ref:`write-ahead logging (WAL) ` thread used to commit + the transaction and the fiber executing the transaction is suspended. + When the transaction results in a COMMIT or ROLLBACK, the following actions are taken: + + * The WAL thread responds with a message to the TX thread. + + * The fiber executing the transaction is resumed to process the result of the transaction. + + * The result of the fiber execution is passed to the network thread, + and the network thread returns the result to the client. + + +.. note:: + + There is only one TX thread in Tarantool. + Some users are used to the idea that there can be multiple threads + working on the database. For example, thread #1 reads a row #x while + thread #2 writes a row #y. With Tarantool this does not happen. + Only the TX thread can access the database, + and there is only one TX thread for each Tarantool instance. + + +The TX thread can handle many :ref:`fibers ` -- +a set of computer instructions that can contain "**yield**" signals. +The TX thread executes all computer instructions up to a +yield signal, and then switches to execute the instructions of another fiber. + + +:ref:`Yields ` must happen, otherwise the TX thread would +be permanently stuck on the same fiber. + + +.. _supplementary_threads: + +Supplementary threads +--------------------- + +There are also several supplementary threads that serve additional capabilities: + +* For :ref:`replication `, Tarantool creates a separate thread for each connected replica. + This thread reads a write-ahead log and sends it to the replica, following its position in the log. + Separate threads are required because each replica can point to a different position in the log and can run at different speeds. + +* There is a thread pool for ad hoc asynchronous tasks, such as a DNS resolver or :ref:`fsync `. + +* There is a thread pool that can be used for parallel sorting (hence, to parallelize building :ref:`indexes `). + To configure it, use the :ref:`memtx.sort_threads ` configuration option. + The option sets the number of threads used to sort keys of secondary indexes on loading a ``memtx`` database. + + .. note_drop_openmp_start + + .. NOTE:: + + Since :doc:`3.0.0 `, this option replaces the approach when OpenMP threads are used to parallelize sorting. + For backward compatibility, the ``OMP_NUM_THREADS`` environment variable is taken into account to + set the number of sorting threads. + + .. note_drop_openmp_end diff --git a/doc/concepts/atomic/transaction_model.rst b/doc/platform/atomic/transaction_model.rst similarity index 100% rename from doc/concepts/atomic/transaction_model.rst rename to doc/platform/atomic/transaction_model.rst diff --git a/doc/concepts/atomic/txn_mode_default.rst b/doc/platform/atomic/txn_mode_default.rst similarity index 88% rename from doc/concepts/atomic/txn_mode_default.rst rename to doc/platform/atomic/txn_mode_default.rst index 26034b291d..d4eacaf45f 100644 --- a/doc/concepts/atomic/txn_mode_default.rst +++ b/doc/platform/atomic/txn_mode_default.rst @@ -4,7 +4,7 @@ Transaction mode: default =========================== By default, Tarantool does not allow :ref:`"yielding" ` inside a :ref:`memtx ` -transaction and the :ref:`transaction manager ` is disabled. This allows fast +transaction and the :ref:`transaction manager ` is disabled. This allows fast atomic transactions without conflicts, but brings some limitations: * You cannot use :ref:`interactive transactions `. diff --git a/doc/concepts/atomic/txn_mode_mvcc.rst b/doc/platform/atomic/txn_mode_mvcc.rst similarity index 99% rename from doc/concepts/atomic/txn_mode_mvcc.rst rename to doc/platform/atomic/txn_mode_mvcc.rst index f9452b2a1c..9af69ce817 100644 --- a/doc/concepts/atomic/txn_mode_mvcc.rst +++ b/doc/platform/atomic/txn_mode_mvcc.rst @@ -18,7 +18,7 @@ but has a different implementation. Currently, you cannot use several different storage engines within one transaction. -.. _txn_mode_mvcc-tnx-manager: +.. _txn_mode_mvcc-txn-manager: Transaction manager ------------------- @@ -97,7 +97,7 @@ You can set an isolation level for a specific transaction in its ``box.begin()`` .. code-block:: lua - box.begin({ tnx_isolation = 'best-effort' }) + box.begin({ txn_isolation = 'best-effort' }) In this case, you can also use the ``default`` option. It sets the transaction's isolation level to the one set in ``box.cfg``. diff --git a/doc/platform/concepts.rst b/doc/platform/concepts.rst new file mode 100644 index 0000000000..9bfc03c06c --- /dev/null +++ b/doc/platform/concepts.rst @@ -0,0 +1,112 @@ +.. _concepts: +.. _platform_concepts: + +Concepts +======== + +Storage engines +--------------- + +A storage engine is a set of low-level routines that store and +retrieve values. Tarantool offers a choice of two storage engines: + +* :ref:`memtx ` is the in-memory storage engine used by default. +* :ref:`vinyl ` is the on-disk storage engine. + +For details, check the :ref:`Storage engines ` section. + + +Data model +---------- + +Tarantool is a NoSQL database. It stores data in :ref:`spaces `, +which can be thought of as tables in a relational database, and :ref:`tuples `, +which are analogous to rows. There are six basic :ref:`data operations ` in Tarantool. + +The platform allows :ref:`describing the data schema ` but does not require it. + +Tarantool supports highly customizable :ref:`indexes ` of various types. + +To ensure :ref:`data persistence ` and recover quickly in case of failure, +Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots. + +For details, check the :ref:`Data model ` page. + +Fibers and cooperative multitasking +----------------------------------- + +Tarantool executes code in :ref:`fibers ` that are managed via +:ref:`cooperative multitasking `. +Learn more about Tarantool's :ref:`thread model `. + +For details, check the page :ref:`Fibers, yields, and cooperative multitasking `. + +Transactions +------------ + +Tarantool's ACID-compliant :ref:`transaction model ` lets the user choose +between two modes of transactions. + +The :ref:`default mode ` allows for fast monopolistic atomic transactions. +It doesn't support interactive transactions, and in case of an error, all transaction changes are rolled back. + +The :ref:`MVCC mode ` relies on a multi-version concurrency control engine +that allows yielding within a longer transaction. +This mode only works with the default in-memory :ref:`memtx ` storage engine. + +For details, check the :ref:`Transactions ` page. + + +Replication +----------- + +Replication allows keeping the data in copies of the same database for better reliability. + +Several Tarantool instances can be organized in a replica set. +They communicate and transfer data via the :ref:`iproto ` binary protocol. +Learn more about Tarantool's :ref:`replication architecture `. + +By default, replication in Tarantool is asynchronous. +A transaction committed locally on the master node +may not get replicated onto other instances before the client receives a success response. +Thus, if the master reports success and then dies, the client might not see the result of the transaction. + +With :ref:`synchronous replication `, transactions on the master node are not considered committed +or successful before they are replicated onto a number of instances. This is slower, but more reliable. +Synchronous replication in Tarantool is based on an :ref:`implementation of the RAFT algorithm `. + +For details, check the :ref:`Replication ` section. + + + +Sharding +-------- + +Tarantool implements database sharding via the ``vshard`` module. +For details, go to the :ref:`Sharding ` page. + +Triggers +-------- + +Tarantool allows specifying callback functions that run upon certain database events. +They can be useful for resolving replication conflicts. +For details, go to the :ref:`Triggers ` page. + + + + +.. _concepts-application_server: + +Application server +------------------ + +Using Tarantool as an application server, you can write +applications in Lua, C, or C++. You can also create reusable :ref:`modules `. + +To increase the speed of code execution, Tarantool has a Lua Just-In-Time compiler (LuaJIT) on board. +LuaJIT compiles hot paths in the code -- paths that are used many times -- +thus making the application work faster. +To enable developers to work with LuaJIT, Tarantool provides tools like the :ref:`memory profiler ` +and the :ref:`getmetrics ` module. + +To learn how to use Tarantool as an application server, refer to the :ref:`guides ` in the How-to section. diff --git a/doc/platform/configuration.rst b/doc/platform/configuration.rst new file mode 100644 index 0000000000..c2e242066a --- /dev/null +++ b/doc/platform/configuration.rst @@ -0,0 +1,587 @@ +.. _configuration: + +Configuration +============= + +Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, such as connection settings, memory used to store data, logging, and snapshot settings. +Each instance uses this configuration during :ref:`startup ` to organize the cluster. + +There are two approaches to configuring Tarantool: + +* *Since version 3.0*: In the YAML format. + + YAML configuration allows you to provide the full cluster topology and specify all configuration options. + You can use local configuration in a YAML file for each instance or store configuration data in a reliable :ref:`centralized storage `. + +* *In version 2.11 and earlier*: :ref:`In code ` using the ``box.cfg`` API. + + In this case, configuration is provided in a Lua initialization script. + + .. NOTE:: + + Starting with the 3.0 version, configuring Tarantool in code is considered a legacy approach. + + +.. _configuration_overview: + +Configuration overview +---------------------- + +YAML configuration describes the full topology of a Tarantool cluster. +A cluster's topology includes the following elements, starting from the lower level: + +.. code-block:: yaml + :emphasize-lines: 1,3,5 + + groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + # ... + instance002: + # ... + +- ``instances`` + + An *instance* represents a single running Tarantool instance. + It stores data or might act as a router for handling CRUD requests in a :ref:`sharded ` cluster. +- ``replicasets`` + + A *replica set* is a pack of instances that operate on same data sets. + :ref:`Replication ` provides redundancy and increases data availability. +- ``groups`` + + A *group* provides the ability to organize replica sets. + For example, in a sharded cluster, one group can contain :ref:`storage ` instances and another group can contain :ref:`routers ` used to handle CRUD requests. + +You can flexibly configure a cluster's settings on different levels: from global settings applied to all groups to parameters specific for concrete instances. + +.. NOTE:: + + All the available options are documented in the :ref:`Configuration reference `. + + +.. _configuration_file: + +Configuration in a file +----------------------- + +This section provides an overview on how to configure Tarantool in a YAML file. + +.. _configuration_instance_basic: + +Basic instance configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The example below shows a sample configuration of a single Tarantool instance: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/instance_scope/config_annotated.yaml + :language: yaml + :dedent: + +- The ``instances`` section includes only one instance named *instance001*. + The ``iproto.listen.uri`` option sets an address used to listen for incoming requests. +- The ``replicasets`` section contains one replica set named *replicaset001*. +- The ``groups`` section contains one group named *group001*. + +.. NOTE:: + + The initial line in this sample contains a link to an annotated Tarantool configuration + schema for a YAML language server (e.g. for `LSP-Yaml`). + With this link you can set up your code editor (VScode, Neovim, Sublime, etc.) to get + full-text annotations and completion prompts upon ``Alt+ESC`` (Linux) / ``Option+ESC`` (MacOS) + when you work with Tarantool configuration. + +.. image:: images/yaml-annotated.png + :align: center + +.. _configuration_scopes: + +Configuration scopes +~~~~~~~~~~~~~~~~~~~~ + +This section shows how to control a scope the specified configuration option is applied to. +Most of the configuration options can be applied to a specific instance, replica set, group, or to all instances globally. + +- *Instance* + + To apply certain configuration options to a specific instance, + specify such options for this instance only. + In the example below, ``iproto.listen`` is applied to *instance001* only. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml + :language: yaml + :emphasize-lines: 7-9 + :dedent: + +- *Replica set* + + In this example, ``iproto.listen`` is in effect for all instances in *replicaset001*. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml + :language: yaml + :emphasize-lines: 5-7 + :dedent: + +- *Group* + + In this example, ``iproto.listen`` is in effect for all instances in *group001*. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/group_scope/config.yaml + :language: yaml + :emphasize-lines: 3-5 + :dedent: + +- *Global* + + In this example, ``iproto.listen`` is applied to all instances of the cluster. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/global_scope/config.yaml + :language: yaml + :emphasize-lines: 1-3 + :dedent: + +Configuration scopes above are listed in the order of their precedence -- from highest to lowest. +For example, if the same option is defined at the instance and global level, the instance's value takes precedence over the global one. + + +.. NOTE:: + + The :ref:`Configuration reference ` contains information about scopes to which each configuration option can be applied. + + +.. _configuration_replica_set_scopes: + +Configuration scopes: Replica set example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The example below shows how specific configuration options work in different configuration scopes for a replica set with a manual failover. +You can learn more about configuring replication from :ref:`Replication tutorials `. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :end-before: Load sample data + :dedent: + +- ``credentials`` (*global*) + + This section is used to create the *replicator* user and assign it the specified role. + These options are applied globally to all instances. + +- ``iproto`` (*global*, *instance*) + + The ``iproto`` section is specified on both global and instance levels. + The ``iproto.advertise.peer`` option specifies the parameters used by an instance to connect to another instance as a replica, for example, a URI, a login and password, or SSL parameters . + In the example above, the option includes ``login`` only. + An URI is taken from ``iproto.listen`` that is set on the instance level. + +- ``replication`` (*global*) + + The ``replication.failover`` global option sets a manual failover for all replica sets. + +- ``leader`` (*replica set*) + + The ``.leader`` option sets a :ref:`master ` instance for *replicaset001*. + + + +.. _configuration_application: +.. _configuration_application_roles: + +Enabling and configuring roles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An application role is a Lua module that implements specific functions or logic. +You can turn on or off a particular role for certain instances in a configuration without restarting these instances. + +There can be built-in Tarantool roles, roles provided by third-party Lua modules, or custom roles that are developed as a part of a cluster application. +This section describes how to enable and configure roles. +To learn how to develop custom roles, see :ref:`application_roles`. + + + +.. _configuration_application_roles_enable: + +Enabling a role +*************** + +To turn on or off a role for a specific instance or a set of instances, use the :ref:`roles ` configuration option. +The example below shows how to enable the ``roles.crud-router`` role provided by the `CRUD `__ module using the :ref:`roles ` option: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-at: roles.crud-router + :end-at: roles.crud-router + :dedent: + +Similarly, you can enable the ``roles.crud-storage`` role to make instances act as CRUD storages: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml + :language: yaml + :start-at: roles.crud-storage + :end-at: roles.crud-storage + :dedent: + +Example on GitHub: `sharded_cluster_crud `_ + + +.. _configuration_application_roles_configure: + +Configuring a role +****************** + +The :ref:`roles_cfg ` option allows you to specify the configuration for each role. +In this option, the role name is the key and the role configuration is the value. + +The example below shows how to enable statistics on called operations by providing the ``roles.crud-router`` role's configuration: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml + :language: yaml + :start-after: routers: + :end-at: stats_quantiles + :dedent: + +Example on GitHub: `sharded_cluster_crud_metrics `_ + + + +.. _configuration_application_roles_scopes: + +Roles and configuration scopes +****************************** + +As the most of configuration options, roles and their configurations can be defined at :ref:`different levels `. +Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, there are some specifics of applying the configuration: + +- For ``roles``, an instance's role takes precedence over roles defined at another level. + In the example below, ``instance001`` has only ``role3``: + + .. code-block:: yaml + + # ... + replicaset001: + roles: [ role1, role2 ] + instances: + instance001: + roles: [ role3 ] + + Learn more about the order of precedence for different configuration scopes in :ref:`configuration_scopes`. + +- For ``roles_cfg``, the following rules are applied: + + - If a configuration *for the same role* is provided at different levels, an instance configuration takes precedence over the configuration defined at another level. + In the example below, ``role1.greeting`` is ``'Hi'``: + + .. code-block:: yaml + + # ... + replicaset001: + roles_cfg: + role1: + greeting: 'Hello' + instances: + instance001: + roles: [ role1 ] + roles_cfg: + role1: + greeting: 'Hi' + + - If the configurations *for different roles* are provided at different levels, both configurations are applied at the instance level. + In the example below, ``instance001`` has ``role1.greeting`` set to ``'Hi'`` and ``role2.farewell`` set to ``'Bye'``: + + .. code-block:: yaml + + # ... + replicaset001: + roles_cfg: + role1: + greeting: 'Hi' + instances: + instance001: + roles: [ role1, role2 ] + roles_cfg: + role2: + farewell: 'Bye' + + +.. _configuration_labels: + +Adding labels +~~~~~~~~~~~~~ + +*Labels* allow adding custom attributes to your cluster configuration. A label is +an arbitrary ``key: value`` pair with a string key and value. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml + :language: yaml + :start-at: labels: + :end-at: 'false' + :dedent: + +Labels can be defined in any configuration scope. An instance receives labels from +all scopes it belongs to. The ``labels`` section in a group or a replica set scope +applies to all instances of the group or a replica set. To override these labels on +the instance level or add instance-specific labels, define another ``labels`` section in the instance scope. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml + :language: yaml + :dedent: + +Example on GitHub: `labels `_ + +To access instance labels from the application code, call the :ref:`config:get() ` function: + +.. code-block:: tarantoolsession + + myapp:instance001> require('config'):get('labels') + --- + - production: 'true' + rack: '10' + dc: east + ... + +Labels can be used to direct function calls to instances that match certain criteria +using the :ref:`connpool module `. + +.. _configuration_predefined_variables: + +Predefined variables +~~~~~~~~~~~~~~~~~~~~ + +In a configuration file, you can use the following predefined variables that are replaced with actual values at runtime: + +- ``instance_name`` +- ``replicaset_name`` +- ``group_name`` + +To reference these variables in a configuration file, enclose them in double curly braces with whitespaces. +In the example below, ``{{ instance_name }}`` is replaced with *instance001*. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/templating/config.yaml + :language: yaml + :dedent: + +As a result, the paths to :ref:`snapshots and write-ahead logs ` differ for different instances. + +.. _configuration_conditional: + +Conditional configuration sections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A YAML configuration can include parts that apply only to instances that meet certain conditions. +This is useful for cluster upgrade scenarios: during an upgrade, instances can be running +different Tarantool versions and therefore require different configurations. + +Conditional parts are defined in the :ref:`conditional ` configuration section in the global scope. +It includes one or more ``if`` subsections. Each ``if`` subsection defines conditions +and configuration parts that apply to instances that meet these conditions. + +The example below shows a ``conditional`` section for cluster upgrade from Tarantool 3.0.0 +to Tarantool 3.1.0: + +- The user-defined :ref:`label ` ``upgraded`` is ``true`` + on instances that are running Tarantool 3.1.0 or later. On older versions, it is ``false``. +- Two :ref:`compat ` options that were introduced in 3.1.0 are defined for Tarantool 3.1.0 + instances. On older versions, they would cause an error. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml + :language: yaml + :start-at: conditional: + :end-before: groups: + :dedent: + +Example on GitHub: `conditional `_ + + +``if`` sections can use one variable -- ``tarantool_version``. It contains +a three-number Tarantool version and compares with values of the same format +using the comparison operators ``>``, ``<``, ``>=``, ``<=``, ``==``, and ``!=``. +You can write complex conditions using the logical operators ``||`` (OR) and ``&&`` (AND). +Parentheses ``()`` can be used to define the operators precedence. + +.. code-block:: yaml + + conditional: + - if: (tarantool_version > 3.2.0 || tarantool_version == 3.1.3) && tarantool_version <= 3.99.0 + -- < ... > + + +If the same option is set in multiple ``if`` sections that are true for an instance, +this option receives the value from the section declared last in the configuration. + +Example: + +.. code-block:: yaml + + conditional: + - if: tarantool_version >= 3.0.0 + labels: + version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0 + - if: tarantool_version >= 3.1.0 + labels: + version: '3.1+' # applies to versions >= 3.1.0 + +.. _configuration_environment_variable: + +Environment variables +--------------------- + +For each configuration parameter, Tarantool provides two sets of predefined environment variables: + +* ``TT_``. These variables are used to substitute parameters specified in a configuration file. + This means that these variables have a higher :ref:`priority ` than the options specified in a configuration file. + +* ``TT__DEFAULT``. These variables are used to specify default values for parameters missing in a configuration file. + These variables have a lower :ref:`priority ` than the options specified in a configuration file. + +For example, ``TT_IPROTO_LISTEN`` and ``TT_IPROTO_LISTEN_DEFAULT`` correspond to the ``iproto.listen`` option. +``TT_SNAPSHOT_DIR`` and ``TT_SNAPSHOT_DIR_DEFAULT`` correspond to the ``snapshot.dir`` option. +To see all the supported environment variables, execute the ``tarantool`` command with the ``--help-env-list`` :ref:`option `. + +.. code-block:: console + + $ tarantool --help-env-list + +.. NOTE:: + + There are also special ``TT_INSTANCE_NAME`` and ``TT_CONFIG`` environment variables that can be used to :ref:`start ` the specified Tarantool instance with configuration from the given file. + +Below are a few examples that show how to set environment variables of different types, like *string*, *number*, *array*, or *map*. + +.. _configuration_environment_variable_string: + +String +~~~~~~ + +In this example, ``TT_LOG_LEVEL`` is used to set a logging level to ``CRITICAL``: + +.. code-block:: console + + $ export TT_LOG_LEVEL='crit' + + +.. _configuration_environment_variable_number: + +Number +~~~~~~ + +In this example, a logging level is set to ``CRITICAL`` using a corresponding numeric value: + +.. code-block:: console + + $ export TT_LOG_LEVEL=3 + +.. _configuration_environment_variable_array: + +Array +~~~~~ + +The examples below show how to set the ``TT_SHARDING_ROLES`` variable that accepts an array value. +Arrays can be passed in two ways: using a *simple* ... + +.. code-block:: console + + $ export TT_SHARDING_ROLES=router,storage + +... or *JSON* format: + +.. code-block:: console + + $ export TT_SHARDING_ROLES='["router", "storage"]' + +The *simple* format is applicable only to arrays containing scalar values. + + +.. _configuration_environment_variable_map: + +Map +~~~ + +To assign map values to environment variables, you can also use *simple* or *JSON* formats. +In the example below, ``TT_LOG_MODULES`` sets different logging levels for different modules using a *simple* format: + +.. code-block:: console + + $ export TT_LOG_MODULES=module1=info,module2=error + +In the next example, ``TT_ROLES_CFG`` is used to specify the value of a custom configuration for a :ref:`role ` using a *JSON* format: + +.. code-block:: console + + $ export TT_ROLES_CFG='{"greeter":{"greeting":"Hello"}}' + +The *simple* format is applicable only to maps containing scalar values. + + +.. _configuration_environment_variable_array_of_maps: + +Array of maps +~~~~~~~~~~~~~ + +In the example below, ``TT_IPROTO_LISTEN`` is used to specify a :ref:`listening host and port ` values: + +.. code-block:: console + + $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}'] + +You can also pass several listening addresses: + +.. code-block:: console + + $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}','{"uri":"127.0.0.1:3312"}'] + + + + + + +.. _configuration_etcd_overview: + +Centralized configuration +------------------------- + +.. include:: /platform/configuration/configuration_etcd.rst + :start-after: ee_note_centralized_config_start + :end-before: ee_note_centralized_config_end + + +Tarantool enables you to store configuration data in one place using a Tarantool or etcd-based storage. +To achieve this, you need to: + +1. Set up a centralized configuration storage. + +2. Publish a cluster's configuration to the storage. + +3. Configure a connection to the storage by providing a local YAML configuration with an endpoint address and key prefix in the ``config`` section: + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_etcd/config.yaml + :language: yaml + :end-at: prefix: /myapp + :dedent: + +Learn more from the following guide: :ref:`configuration_etcd`. + + +.. _configuration_precedence: + +Configuration precedence +------------------------ + +Tarantool configuration options are applied from multiple sources with the following precedence, from highest to lowest: + +- `TT_*` :ref:`environment variables `. +- Configuration from a :ref:`local YAML file `. +- :ref:`Centralized configuration `. +- `TT_*_DEFAULT` :ref:`environment variables `. + +If the same option is defined in two or more locations, the option with the highest precedence is applied. + + + +.. toctree:: + :hidden: + + configuration/configuration_etcd + configuration/configuration_code diff --git a/doc/platform/configuration/configuration_code.rst b/doc/platform/configuration/configuration_code.rst new file mode 100644 index 0000000000..512ddb0f14 --- /dev/null +++ b/doc/platform/configuration/configuration_code.rst @@ -0,0 +1,616 @@ +.. _configuration_code: + +Configuration in code +===================== + +.. box_cfg_legacy_note_start + +.. NOTE:: + + Starting with the 3.0 version, the recommended way of configuring Tarantool is using a :ref:`configuration file `. + Configuring Tarantool in code is considered a legacy approach. + +.. box_cfg_legacy_note_end + +This topic covers the specifics of configuring Tarantool in code using the ``box.cfg`` API. +In this case, a configuration is stored in an :ref:`initialization file ` - a Lua script with the specified configuration options. +You can find all the available options in the :ref:`Configuration reference `. + + +.. _index-init_label: + +Initialization file +------------------- + +If the command to :ref:`start Tarantool ` includes an instance file, then +Tarantool begins by invoking the Lua program in the file, which may have the name ``init.lua``. +The Lua program may get further arguments +from the command line or may use operating-system functions, such as ``getenv()``. +The Lua program almost always begins by invoking ``box.cfg()``, if the database +server will be used or if ports need to be opened. For example, suppose +``init.lua`` contains the lines + +.. _index-init-example: + +.. code-block:: lua + + #!/usr/bin/env tarantool + box.cfg{ + listen = os.getenv("LISTEN_URI"), + memtx_memory = 33554432, + pid_file = "tarantool.pid", + wal_max_size = 2500 + } + print('Starting ', arg[1]) + +and suppose the environment variable ``LISTEN_URI`` contains 3301, +and suppose the command line is ``tarantool init.lua ARG``. +Then the screen might look like this: + +.. code-block:: console + + $ export LISTEN_URI=3301 + $ tarantool init.lua ARG + ... main/101/init.lua C> Tarantool 2.8.3-0-g01023dbc2 + ... main/101/init.lua C> log level 5 + ... main/101/init.lua I> mapping 33554432 bytes for memtx tuple arena... + ... main/101/init.lua I> recovery start + ... main/101/init.lua I> recovering from './00000000000000000000.snap' + ... main/101/init.lua I> set 'listen' configuration option to "3301" + ... main/102/leave_local_hot_standby I> ready to accept requests + Starting ARG + ... main C> entering the event loop + +If you wish to start an interactive session on the same terminal after +initialization is complete, you can pass the ``-i`` :ref:`command-line option `. + + +.. _box-cfg-params-env: + +Environment variables +--------------------- + +Starting from version :doc:`2.8.1 `, you can specify configuration parameters via special environment variables. +The name of a variable should have the following pattern: ``TT_``, +where ```` is the uppercase name of the corresponding :ref:`box.cfg parameter `. + +For example: + +* ``TT_LISTEN`` -- corresponds to the :ref:`box.cfg.listen ` option. +* ``TT_MEMTX_DIR`` -- corresponds to the :ref:`box.cfg.memtx_dir ` option. + +In case of an array value, separate the array elements by a comma without space: + +.. code-block:: console + + export TT_REPLICATION="localhost:3301,localhost:3302" + +If you need to pass :ref:`additional parameters for URI `, use the ``?`` and ``&`` delimiters: + +.. code-block:: console + + export TT_LISTEN="localhost:3301?param1=value1¶m2=value2" + +An empty variable (``TT_LISTEN=``) has the same effect as an unset one, meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. + + + +.. _index-local_hot_standby: +.. _index-replication_port: +.. _index-slab_alloc_arena: +.. _index-replication_source: +.. _index-snap_dir: +.. _index-wal_dir: +.. _index-wal_mode: +.. _index-checkpoint daemon: + +.. _box_cfg_params: + + +Configuration parameters +------------------------ + +Configuration parameters have the form: + +:extsamp:`{**{box.cfg}**}{[{*{key = value}*} [, {*{key = value ...}*}]]}` + +Configuration parameters can be set in a Lua :ref:`initialization file `, +which is specified on the Tarantool command line. + +Most configuration parameters are for allocating resources, opening ports, and +specifying database behavior. All parameters are optional. +Most of the parameters are dynamic, that is, they can be changed at runtime by calling ``box.cfg{}`` a second time. +For example, the command below sets the :ref:`listen port ` to ``3301``. + +.. code-block:: tarantoolsession + + tarantool> box.cfg{ listen = 3301 } + 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: stopped + 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: bound to [::]:3301 + 2023-05-10 13:28:54.667 [31326] main/103/interactive/box.load_cfg I> set 'listen' configuration option to 3301 + --- + ... + + +To see all the non-null parameters, execute ``box.cfg`` (no parentheses). + +.. code-block:: tarantoolsession + + tarantool> box.cfg + --- + - replication_skip_conflict: false + wal_queue_max_size: 16777216 + feedback_host: https://feedback.tarantool.io + memtx_dir: . + memtx_min_tuple_size: 16 + -- other parameters -- + ... + +To see a particular parameter value, call a corresponding ``box.cfg`` option. +For example, ``box.cfg.listen`` shows the specified :ref:`listen address `. + +.. code-block:: tarantoolsession + + tarantool> box.cfg.listen + --- + - 3301 + ... + + + +.. _index-uri: + +Listen URI +---------- + +Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). +The URI string format is similar to the +`generic syntax for a URI schema `_. +It may contain (in order): + +* user name for login +* password +* host name or host IP address +* port number +* query parameters + +Only a port number is always mandatory. A password is mandatory if a user +name is specified unless the user name is 'guest'. + +Formally, the URI +syntax is ``[host:]port`` or ``[username:password@]host:port``. +If a host is omitted, then "0.0.0.0" or "[::]" is assumed, +meaning respectively any IPv4 address or any IPv6 address +on the local machine. +If ``username:password`` is omitted, then the "guest" user is assumed. Some examples: + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + +-----------------------------+------------------------------+ + | URI fragment | Example | + +=============================+==============================+ + | port | 3301 | + +-----------------------------+------------------------------+ + | host:port | 127.0.0.1:3301 | + +-----------------------------+------------------------------+ + | username:password@host:port | notguest:sesame@mail.ru:3301 | + +-----------------------------+------------------------------+ + +In code, the URI value can be passed as a number (if only a port is specified) or a string: + +.. code-block:: lua + + box.cfg { listen = 3301 } + + box.cfg { listen = "127.0.0.1:3301" } + +In certain circumstances, a Unix domain socket may be used +where a URI is expected, for example, ``unix/:/tmp/unix_domain_socket.sock`` or +simply ``/tmp/unix_domain_socket.sock``. + +The :ref:`uri ` module provides functions that convert URI strings into their +components or turn components into URI strings. + +.. _index-uri-several: + +Specifying several URIs +~~~~~~~~~~~~~~~~~~~~~~~ + +Starting from version 2.10.0, a user can open several listening iproto sockets on a Tarantool instance +and, consequently, can specify several URIs in the configuration parameters +such as :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. + +URI values can be set in a number of ways: + +* As a string with URI values separated by commas. + + .. code-block:: lua + + box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } + +* As a table that contains URIs in the string format. + + .. code-block:: lua + + box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } + +* As an array of tables with the ``uri`` field. + + .. code-block:: lua + + box.cfg { listen = { + {uri = "127.0.0.1:3301"}, + {uri = "/unix.sock"}, + {uri = 3302} + } + } + +* In a combined way -- an array that contains URIs in both the string and the table formats. + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301", + { uri = "/unix.sock" }, + { uri = 3302 } + } + } + +.. _index-uri-several-params: + +Also, starting from version 2.10.0, it is possible to specify additional parameters for URIs. +You can do this in different ways: + +* Using the ``?`` delimiter when URIs are specified in a string format. + + .. code-block:: lua + + box.cfg { listen = "127.0.0.1:3301?p1=value1&p2=value2, /unix.sock?p3=value3" } + +* Using the ``params`` table: a URI is passed in a table with additional parameters in the "params" table. + Parameters in the "params" table overwrite the ones from a URI string ("value2" overwrites "value1" for ``p1`` in the example below). + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301?p1=value1", + params = {p1 = "value2", p2 = "value3"} + } + } + +* Using the ``default_params`` table for specifying default parameter values. + + In the example below, two URIs are passed in a table. + The default value for the ``p3`` parameter is defined in the ``default_params`` table + and used if this parameter is not specified in URIs. + Parameters in the ``default_params`` table are applicable to all the URIs passed in a table. + + .. code-block:: lua + + box.cfg { listen = { + "127.0.0.1:3301?p1=value1", + { uri = "/unix.sock", params = { p2 = "value2" } }, + default_params = { p3 = "value3" } + } + } + +The recommended way for specifying URI with additional parameters is the following: + +.. code-block:: lua + + box.cfg { listen = { + {uri = "127.0.0.1:3301", params = {p1 = "value1"}}, + {uri = "/unix.sock", params = {p2 = "value2"}}, + {uri = 3302, params = {p3 = "value3"}} + } + } + +In case of a single URI, the following syntax also works: + +.. code-block:: lua + + box.cfg { listen = { + uri = "127.0.0.1:3301", + params = { p1 = "value1", p2 = "value2" } + } + } + + +.. _configuration_code_iproto-encryption: + +Traffic encryption +------------------ + +.. admonition:: Enterprise Edition + :class: fact + + Traffic encryption is supported by the `Enterprise Edition `_ only. + +Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over :ref:`binary connections `, +that is, between Tarantool instances in a cluster or connecting to an instance via connectors using :doc:`net.box `. + +Tarantool uses the OpenSSL library that is included in the delivery package. +Note that SSL connections use only TLSv1.2. + +.. _configuration_code_iproto-encryption-config: + +Configuration +~~~~~~~~~~~~~ + +To configure traffic encryption, you need to set the special :ref:`URI parameters ` for a particular connection. +The parameters can be set for the following ``box.cfg`` options and ``net.box`` method: + +* :ref:`box.cfg.listen ` -- on the server side. +* :ref:`box.cfg.replication ` -- on the client side. +* :ref:`net_box_object.connect() ` -- on the client side. + +Below is the list of the parameters. +In the :ref:`next section `, you can find details and examples on what should be configured on both the server side and the client side. + +* ``transport`` -- enables SSL encryption for a connection if set to ``ssl``. + The default value is ``plain``, which means the encryption is off. If the parameter is not set, the encryption is off too. + Other encryption-related parameters can be used only if the ``transport = 'ssl'`` is set. + + Example: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua + :language: lua + :start-at: net.box + :end-before: return connection + :dedent: + +* ``ssl_key_file`` -- a path to a private SSL key file. + Mandatory for a server. + For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. + If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter. + +* ``ssl_cert_file`` -- a path to an SSL certificate file. + Mandatory for a server. + For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. + +* ``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. Optional. If not set, the peer won't be checked for authenticity. + + Both a server and a client can use the ``ssl_ca_file`` parameter: + + * If it's on the server side, the server verifies the client. + * If it's on the client side, the client verifies the server. + * If both sides have the CA files, the server and the client verify each other. + +* ``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use. See the :ref:`configuration_code_iproto-encryption-ciphers` section for details. Optional. + Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found. + +* ``ssl_password`` -- a password for an encrypted private SSL key. Optional. Alternatively, the password + can be provided in ``ssl_password_file``. + +* ``ssl_password_file`` -- a text file with one or more passwords for encrypted private SSL keys + (each on a separate line). Optional. Alternatively, the password can be provided in ``ssl_password``. + + Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order: + + 1. If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it. + 2. If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` + one by one in the order they are written. + 3. If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, + or none of them is provided, Tarantool treats the private key as unencrypted. + +Configuration example: + +.. code-block:: lua + + box.cfg{ listen = { + uri = 'localhost:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ciphers = 'HIGH:!aNULL', + ssl_password = 'topsecret' + } + }} + +.. _configuration_code_iproto-encryption-ciphers: + +Supported ciphers +***************** + +Tarantool Enterprise supports the following cipher suites: + +* ECDHE-ECDSA-AES256-GCM-SHA384 +* ECDHE-RSA-AES256-GCM-SHA384 +* DHE-RSA-AES256-GCM-SHA384 +* ECDHE-ECDSA-CHACHA20-POLY1305 +* ECDHE-RSA-CHACHA20-POLY1305 +* DHE-RSA-CHACHA20-POLY1305 +* ECDHE-ECDSA-AES128-GCM-SHA256 +* ECDHE-RSA-AES128-GCM-SHA256 +* DHE-RSA-AES128-GCM-SHA256 +* ECDHE-ECDSA-AES256-SHA384 +* ECDHE-RSA-AES256-SHA384 +* DHE-RSA-AES256-SHA256 +* ECDHE-ECDSA-AES128-SHA256 +* ECDHE-RSA-AES128-SHA256 +* DHE-RSA-AES128-SHA256 +* ECDHE-ECDSA-AES256-SHA +* ECDHE-RSA-AES256-SHA +* DHE-RSA-AES256-SHA +* ECDHE-ECDSA-AES128-SHA +* ECDHE-RSA-AES128-SHA +* DHE-RSA-AES128-SHA +* AES256-GCM-SHA384 +* AES128-GCM-SHA256 +* AES256-SHA256 +* AES128-SHA256 +* AES256-SHA +* AES128-SHA +* GOST2012-GOST8912-GOST8912 +* GOST2001-GOST89-GOST89 + +Tarantool Enterprise static build has the embedded engine to support the GOST cryptographic algorithms. +If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ``ssl_ciphers`` parameter, for example: + +.. code-block:: lua + + box.cfg{ listen = { + uri = 'localhost:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ciphers = 'GOST2012-GOST8912-GOST8912' + } + }} + +For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__. + +Using environment variables +*************************** + +The URI parameters for traffic encryption can also be set via :ref:`environment variables `, for example: + +.. code-block:: bash + + export TT_LISTEN="localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file" + + +.. _configuration_code_iproto-encryption-config-sc: + +Server-client configuration details +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. +Below you can find the summary on the options and parameters to be used and :ref:`examples of configuration `. + +**Server side** + +* Is configured via the ``box.cfg.listen`` option. +* Mandatory URI parameters: ``transport``, ``ssl_key_file`` and ``ssl_cert_file``. +* Optional URI parameters: ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file``. + + +**Client side** + +* Is configured via the ``box.cfg.replication`` option (see :ref:`details `) or ``net_box_object.connect()``. + +Parameters: + +* If the server side has only the ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` parameters set, + on the client side, you need to specify only ``transport = ssl`` as the mandatory parameter. + All other URI parameters are optional. + +* If the server side also has the ``ssl_ca_file`` parameter set, + on the client side, you need to specify ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` as the mandatory parameters. + Other parameters -- ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file`` -- are optional. + + +.. _configuration_code_iproto-encryption-config-example: + +Configuration examples +********************** + +Suppose, there is a :ref:`master-replica ` set with two Tarantool instances: + +* 127.0.0.1:3301 -- master (server) +* 127.0.0.1:3302 -- replica (client). + +Examples below show the configuration related to connection encryption for two cases: +when the trusted certificate authorities (CA) file is not set on the server side and when it does. +Only mandatory URI parameters are mentioned in these examples. + +1. **Without CA** + +* 127.0.0.1:3301 -- master (server) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + } + } + +* 127.0.0.1:3302 -- replica (client) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3302', + params = {transport = 'ssl'} + }, + replication = { + uri = 'username:password@127.0.0.1:3301', + params = {transport = 'ssl'} + }, + read_only = true + } + +2. **With CA** + +* 127.0.0.1:3301 -- master (server) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file', + ssl_ca_file = '/path_to_ca_file' + } + } + } + +* 127.0.0.1:3302 -- replica (client) + + .. code-block:: lua + + box.cfg{ + listen = { + uri = '127.0.0.1:3302', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + }, + replication = { + uri = 'username:password@127.0.0.1:3301', + params = { + transport = 'ssl', + ssl_key_file = '/path_to_key_file', + ssl_cert_file = '/path_to_cert_file' + } + }, + read_only = true + } + + + +.. _configuration_code_run_instance_tarantool: + +Starting a Tarantool instance +----------------------------- + +Below is the syntax for starting a Tarantool instance configured in a Lua initialization script: + +.. code-block:: console + + $ tarantool LUA_INITIALIZATION_FILE [OPTION ...] + +The ``tarantool`` command also provides a set of :ref:`options ` that might be helpful for development purposes. + +The command below starts a Tarantool instance configured in the ``init.lua`` file: + +.. code-block:: console + + $ tarantool init.lua diff --git a/doc/platform/configuration/configuration_etcd.rst b/doc/platform/configuration/configuration_etcd.rst new file mode 100644 index 0000000000..1f8f13725e --- /dev/null +++ b/doc/platform/configuration/configuration_etcd.rst @@ -0,0 +1,336 @@ +.. _configuration_etcd: + +Centralized configuration storages +================================== + +.. ee_note_centralized_config_start + +.. admonition:: Enterprise Edition + :class: fact + + Centralized configuration storages are supported by the `Enterprise Edition `_ only. + +.. ee_note_centralized_config_end + +**Examples on GitHub**: `centralized_config `_ + +Tarantool enables you to store a cluster's configuration in one reliable place using a Tarantool or etcd-based storage: + +- A Tarantool-based configuration storage is a replica set that stores a cluster's configuration in :ref:`synchronous ` spaces. +- `etcd `__ is a distributed key-value storage for any type of critical data used by distributed systems. + +With a :ref:`local YAML configuration `, you need to make sure that all cluster instances use identical configuration files: + +| + +.. image:: tarantool_config_local.png + :align: left + :width: 500 + :alt: Local configuration file + +| + +Using a centralized configuration storage, all instances get the actual configuration from one place: + +| + +.. image:: tarantool_config_centralized.png + :align: left + :width: 500 + :alt: Centralized configuration storage + +| + +This topic describes how to set up a configuration storage, publish a cluster configuration to this storage, and use this configuration for all cluster instances. + + + +.. _centralized_configuration_storage_set_up: + +Setting up a configuration storage +---------------------------------- + +.. _centralized_configuration_storage_set_up_tarantool: + +Tarantool-based storage +~~~~~~~~~~~~~~~~~~~~~~~ + +To make a replica set act as a configuration storage, use the built-in ``config.storage`` :ref:`role `. + + +.. _centralized_configuration_storage_tarantool_configure: + +Configuring a storage +********************* + +To :ref:`configure ` a Tarantool-based storage, follow the steps below: + +1. Define a replica set topology and specify the following options at the replica set level: + + * Enable the ``config.storage`` role in :ref:`roles `. + * Optionally, provide the role configuration in :ref:`roles_cfg `. In the example below, the ``status_check_interval`` option sets the interval (in seconds) of status checks. + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:4403 + :dedent: + +2. :ref:`Create a user ` and grant them the following privileges: + + * The ``read`` and ``write`` permissions to the ``config_storage`` and ``config_storage_meta`` spaces used to store configuration data. + * The ``execute`` permission to ``universe`` to allow interacting with the storage using the tt utility. + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml + :language: yaml + :start-at: credentials: + :end-before: replicator: + :dedent: + +3. Set the :ref:`replication.failover ` option to ``election`` to enable automated failover: + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml + :language: yaml + :start-at: replication: + :end-at: failover: election + :dedent: + +4. Enable the :ref:`MVCC transaction mode ` to provide linearizability of read operations: + + .. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml + :language: yaml + :start-at: database: + :end-at: use_mvcc_engine + :dedent: + +The resulting storage configuration might look as follows: + +.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/config.yaml + :language: yaml + :end-before: Interact with config storage + :dedent: + +You can find the full example here: `tarantool_config_storage `_. + + +.. _centralized_configuration_storage_tarantool_start: + +Starting a storage +****************** + +To start instances of the configured storage, use the ``tt start`` command, for example: + +.. code-block:: console + + $ tt start tarantool_config_storage + +Learn more from the :ref:`Starting and stopping instances ` section. + + + + +.. _centralized_configuration_storage_set_up_etcd: + +etcd-based storage +~~~~~~~~~~~~~~~~~~ + +To learn how to set up an etcd-based configuration storage, consult the `etcd documentation `__. + +The example script below demonstrates how to use the ``etcdctl`` utility to create a user that has read and write access to configurations stored by the ``/myapp/`` prefix: + +.. literalinclude:: /code_snippets/snippets/centralized_config/etcd_config_storage.sh + :language: console + :start-at: user add root:topsecret + :end-at: auth enable + :dedent: + +The credentials of this user should be specified when :ref:`configuring a connection ` to the etcd cluster. + + + + +.. _centralized_configuration_storage_publish_config: + +Publishing a cluster's configuration +------------------------------------ + +.. _centralized_configuration_storage_publish_config_tt: + +Publishing configuration using the tt utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tt utility provides the :ref:`tt cluster ` command for managing centralized cluster configurations. +The ``tt cluster publish`` command can be used to publish a cluster's configuration to both Tarantool and etcd-based storages. + +The example below shows how a tt environment and a :ref:`layout ` of the application called ``myapp`` might look: + +.. code-block:: none + + ├── tt.yaml + ├── source.yaml + └── instances.enabled + └── myapp + ├── config.yaml + └── instances.yml + +* ``tt.yaml``: a tt configuration file. +* ``source.yaml`` contains a cluster's configuration to be published. +* ``config.yaml`` contains a :ref:`local configuration ` used to connect to the centralized storage. +* ``instances.yml`` specifies :ref:`instances ` to run in the current environment. + The configured instances are used by tt when :ref:`starting a cluster `. + ``tt cluster publish`` ignores this configuration file. + +To publish a cluster's configuration (``source.yaml``) to a centralized storage, execute ``tt cluster publish`` as follows: + +.. code-block:: console + + $ tt cluster publish "http://sampleuser:123456@localhost:2379/myapp" source.yaml + +Executing this command publishes a cluster configuration by the ``/myapp/config/all`` path. + +.. NOTE:: + + You can see a cluster's configuration using the ``tt cluster show`` command. + + + +.. _centralized_configuration_storage_publish_config_tarantool: + +Publishing configuration using the 'config' module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`config module ` provides the API for interacting with a Tarantool-based configuration storage. +The example below shows how to read a configuration stored in the ``source.yaml`` file using the :ref:`fio module ` API and put this configuration by the ``/myapp/config/all`` path: + +.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage/myapp.lua + :language: lua + :start-after: function put_config + :end-at: cluster_config_handle:close() + :dedent: + +Learn more from the :ref:`config_storage_api_reference` section. + +.. NOTE:: + + The ``net.box module`` provides the ability to monitor configuration updates by watching path or prefix changes. Learn more in :ref:`conn:watch() `. + + +.. _centralized_configuration_storage_publish_config_etcdctl: + +Publishing configuration using etcdctl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To publish a cluster's configuration to etcd using the ``etcdctl`` utility, use the ``put`` command: + +.. code-block:: console + + $ etcdctl put /myapp/config/all < source.yaml + +.. NOTE:: + + For etcd versions earlier than 3.4, you need to set the ``ETCDCTL_API`` environment variable to ``3``. + + + + + +.. _centralized_configuration_storage_connect: + +Configuring connection to a storage +----------------------------------- + +To use a configuration from a centralized storage for your cluster, you need to provide connection settings in a local configuration file. + + +.. _centralized_configuration_storage_connect_tarantool: + +Configuring connection to a Tarantool storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Connection options for a Tarantool-based storage should be specified in the :ref:`config.storage ` section of the configuration file. +In the example below, the following options are specified: + +.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_storage/config.yaml + :language: yaml + :end-before: Watch key changes + :dedent: + +- ``endpoints`` specifies the list of configuration storage endpoints. +- ``prefix`` sets a key prefix used to search a configuration. Tarantool searches keys by the following path: ``/config/*``. Note that ```` should start with a slash (``/``). +- ``timeout`` specifies the interval (in seconds) to perform the status check of a configuration storage. +- ``reconnect_after`` specifies how much time to wait (in seconds) before reconnecting to a configuration storage. + +You can find the full example here: `config_storage `_. + + + +.. _etcd_local_configuration: + +Configuring connection to an etcd storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Connection options for etcd should be specified in the :ref:`config.etcd ` section of the configuration file. +In the example below, the following options are specified: + +.. literalinclude:: /code_snippets/snippets/centralized_config/instances.enabled/config_etcd/config.yaml + :language: yaml + :dedent: + +- ``endpoints`` specifies the list of etcd endpoints. +- ``prefix`` sets a key prefix used to search a configuration. Tarantool searches keys by the following path: ``/config/*``. Note that ```` should start with a slash (``/``). +- ``username`` and ``password`` specify credentials used for authentication. +- ``http.request.timeout`` configures a request timeout for an etcd server. + +You can find the full example here: `config_etcd `_. + + + + +.. _etcd_starting_instances: + +Starting a cluster +------------------ + +The :ref:`tt ` utility is the recommended way to start Tarantool instances. +You can learn how to do this from the :ref:`Starting and stopping instances ` section. + +You can also use the ``tarantool`` command to :ref:`start a Tarantool instance `. +In this case, you can eliminate creating a :ref:`local configuration ` and provide connection settings using the following :ref:`environment variables `: + +* Tarantool-based storage: ``TT_CONFIG_STORAGE_ENDPOINTS`` and ``TT_CONFIG_STORAGE_PREFIX``. +* etcd-based storage: ``TT_CONFIG_ETCD_ENDPOINTS`` and ``TT_CONFIG_ETCD_PREFIX``. + +The example below shows how to provide etcd connection settings and start cluster instances using the ``tarantool`` command: + +.. code-block:: console + + $ export TT_CONFIG_ETCD_ENDPOINTS=http://localhost:2379 + $ export TT_CONFIG_ETCD_PREFIX=/myapp + + $ tarantool --name instance001 + $ tarantool --name instance002 + $ tarantool --name instance003 + + + + +.. _etcd_reloading_configuration: + +Reloading configuration +----------------------- + +By default, Tarantool watches keys with the :ref:`specified prefix ` for changes in a cluster's configuration and reloads a changed configuration automatically. +If necessary, you can set the :ref:`config.reload ` option to ``manual`` to turn off configuration reloading: + +.. code-block:: yaml + + config: + reload: 'manual' + etcd: + # ... + +In this case, you can reload a configuration in an :ref:`admin console ` or :ref:`application code ` using the :ref:`reload() ` function provided by the ``config`` module: + +.. code-block:: lua + + require('config'):reload() diff --git a/doc/platform/configuration/configuration_migrating.rst b/doc/platform/configuration/configuration_migrating.rst new file mode 100644 index 0000000000..c557d741ae --- /dev/null +++ b/doc/platform/configuration/configuration_migrating.rst @@ -0,0 +1,9 @@ +.. _configuration_migrating_declarative: + +Migrating to declarative configuration +====================================== + +.. TODO + https://github.com/tarantool/doc/issues/3661 + 1) Configuration applying idempotence: how the config's 'target state' approach differs from the 'state changes' box.cfg() approach. + 2) How non-dynamic box.cfg() options are applied (no error, wait for restart). diff --git a/doc/platform/configuration/tarantool_config_centralized.png b/doc/platform/configuration/tarantool_config_centralized.png new file mode 100644 index 0000000000..c8ee9e2696 Binary files /dev/null and b/doc/platform/configuration/tarantool_config_centralized.png differ diff --git a/doc/platform/configuration/tarantool_config_centralized_tcm.png b/doc/platform/configuration/tarantool_config_centralized_tcm.png new file mode 100644 index 0000000000..63b48a6e99 Binary files /dev/null and b/doc/platform/configuration/tarantool_config_centralized_tcm.png differ diff --git a/doc/platform/configuration/tarantool_config_local.png b/doc/platform/configuration/tarantool_config_local.png new file mode 100644 index 0000000000..146b3327e2 Binary files /dev/null and b/doc/platform/configuration/tarantool_config_local.png differ diff --git a/doc/platform/connections_and_auth/authentication.rst b/doc/platform/connections_and_auth/authentication.rst new file mode 100644 index 0000000000..916b24ba14 --- /dev/null +++ b/doc/platform/connections_and_auth/authentication.rst @@ -0,0 +1,110 @@ +.. _configuration_authentication: + +Authentication +============== + +.. admonition:: Enterprise Edition + :class: fact + + Authentication features are supported by the `Enterprise Edition `_ only. + +.. _enterprise-auth-restrictions: + +Authentication restrictions +--------------------------- + +Tarantool Enterprise Edition provides the ability to apply additional restrictions for user authentication. +For example, you can specify the minimum time between authentication attempts +or turn off access for guest users. + +In the configuration below, :ref:`security.auth_retries ` is set to ``2``, +which means that Tarantool lets a client try to authenticate with the same username three times. +At the fourth attempt, the authentication delay configured with :ref:`security.auth_delay ` is enforced. +This means that a client should wait 10 seconds after the first failed attempt. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml + :language: yaml + :start-at: security: + :end-at: disable_guest + :dedent: + +The :ref:`disable_guest ` option turns off access over remote connections from unauthenticated or :ref:`guest ` users. + + +.. _enterprise-password-policy: + +Password policy +--------------- + +A password policy allows you to improve database security by enforcing the use +of strong passwords, setting up a maximum password age, and so on. +When you create a new user with +:doc:`box.schema.user.create ` +or update the password of an existing user with +:doc:`box.schema.user.passwd `, +the password is checked against the configured password policy settings. + +In the example below, the following options are specified: + +- :ref:`password_min_length ` specifies that a password should be at least 16 characters. +- :ref:`password_enforce_lowercase ` and :ref:`password_enforce_uppercase ` specify that a password should contain lowercase and uppercase letters. +- :ref:`password_enforce_digits ` and :ref:`password_enforce_specialchars ` specify that a password should contain digits and at least one special character. +- :ref:`password_lifetime_days ` sets a maximum password age to 365 days. +- :ref:`password_history_length ` specifies that a new password should differ from the last three passwords. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml + :language: yaml + :start-at: security: + :end-at: password_history_length + :dedent: + + + + +.. _enterprise-authentication-protocol: + +Authentication protocol +----------------------- + +By default, Tarantool uses the +`CHAP `_ +protocol to authenticate users and applies ``SHA-1`` hashing to +:ref:`passwords `. +Note that CHAP stores password hashes in the ``_user`` space unsalted. +If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table `_. + +In the Enterprise Edition, you can enable +`PAP `_ authentication +with the ``SHA256`` hashing algorithm. +For PAP, a password is salted with a user-unique salt before saving it in the database, +which keeps the database protected from cracking using a rainbow table. + +To enable PAP, specify the :ref:`security.auth_type ` option as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml + :language: yaml + :start-at: security: + :end-at: pap-sha256 + :dedent: + +For new users, the :doc:`box.schema.user.create ` method generates authentication data using ``PAP-SHA256``. +For existing users, you need to reset a password using +:doc:`box.schema.user.passwd ` +to use the new authentication protocol. + +.. warning:: + + Given that ``PAP`` transmits a password as plain text, + Tarantool requires configuring :ref:`SSL/TLS ` + for a connection. + +The example below shows how to specify the authentication protocol using the ``auth_type`` parameter when connecting to an instance using :doc:`net.box `: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua + :language: lua + :start-at: local connection + :end-before: return connection + :dedent: + +If the authentication protocol isn't specified explicitly on the client side, +the client uses the protocol configured on the server via ``security.auth_type``. diff --git a/doc/platform/connections_and_auth/connections.rst b/doc/platform/connections_and_auth/connections.rst new file mode 100644 index 0000000000..59b5606b7b --- /dev/null +++ b/doc/platform/connections_and_auth/connections.rst @@ -0,0 +1,299 @@ +.. _configuration_connections: + +Connections +=========== + +To set up a Tarantool cluster, you need to enable communication between its instances, regardless of whether they running on one or different hosts. +This requires :ref:`configuring ` connection settings that include: + +- One or several URIs used to listen for incoming requests. +- An URI used to advertise an instance to other cluster members. This URI lets other cluster members know how to connect to the current Tarantool instance. +- (Optional) SSL settings used to secure connections between instances. + +Configuring connection settings is also required to enable communication of a Tarantool cluster to external systems. +For example, this might be administering cluster members using :ref:`tt `, managing clusters using :ref:`Tarantool Cluster Manager `, or using :ref:`connectors ` for different languages. + +This topic describes how to define connection settings in the :ref:`iproto ` section of a YAML configuration. + +.. NOTE:: + + iproto is a :ref:`binary protocol ` used to communicate between cluster instances and with external systems. + + +.. _configuration_connections_listen_uri: + +Listen URI +---------- + +To configure URIs used to listen for incoming requests, use the :ref:`iproto.listen ` configuration option. + +.. _configuration_connections_listen_address: + +One listen address +~~~~~~~~~~~~~~~~~~ + +The example below shows how to set a listening IP address for ``instance001`` to ``127.0.0.1:3301``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml + :start-at: instance001 + :end-at: '127.0.0.1:3301' + :language: yaml + :dedent: + +.. _configuration_connections_listen_addresses: + +Multiple listen addresses +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this example, ``instance001`` listens on two IP addresses: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml + :start-at: instance001 + :end-at: '127.0.0.1:3302' + :language: yaml + :dedent: + +.. _configuration_connections_listen_port: + +Listen port +~~~~~~~~~~~ + +You can pass only a port value to ``iproto.listen``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml + :start-at: instance001 + :end-at: '3301' + :language: yaml + :dedent: + +In this case, this port is used for all IP addresses the server listens on. + + +.. _configuration_connections_listen_ssl: + +SSL parameters +~~~~~~~~~~~~~~ + +In the Enterprise Edition, you can enable SSL for a connection using the ``params`` section of the specified URI: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml + :language: yaml + :start-at: instance001: + :end-before: instance002: + :dedent: + +Learn more from :ref:`configuration_connections_ssl`. + + +.. _configuration_connections_unix_socket: + +Unix domain socket +~~~~~~~~~~~~~~~~~~ + +For local development, you can enable communication between cluster members by using Unix domain sockets: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml + :start-at: instance001 + :end-at: tarantool.iproto + :language: yaml + :dedent: + + + + +.. _configuration_connections_advertise: + +Advertise URI +------------- + +An advertise URI (:ref:`iproto.advertise.* `) lets other cluster members or clients know how to connect to the current Tarantool instance: + +- ``iproto.advertise.peer`` specifies how to advertise the instance to other cluster members. +- ``iproto.advertise.sharding`` specifies how to advertise the instance to a :ref:`router ` and :ref:`rebalancer `. +- ``iproto.advertise.client`` accepts a URI used to advertise the instance to clients. + +``iproto.advertise.`` might include the credentials required to connect to this instance, a URI used to listen for incoming requests, and SSL settings. + +If ``iproto.advertise..uri`` is not specified explicitly, a :ref:`listen URI ` of this instance is used. +In this case, you need at least to specify credentials for connecting to this instance. + + +.. _configuration_connections_advertise_credentials: + +Connection credentials +~~~~~~~~~~~~~~~~~~~~~~ + +In the example below, the ``iproto.advertise.peer`` option is used to inform other replica set members that the ``replicator`` user should be used to connect to the current instance: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml + :language: yaml + :start-after: roles: [replication] + :end-at: login: replicator + :dedent: + +In a sharded cluster, ``iproto.advertise.sharding`` specifies that a router and rebalancer should use the ``storage`` user to connect to storages: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-at: iproto + :end-at: login: storage + :dedent: + + +.. _configuration_connections_advertise_explicitly: + +URI +~~~ + +If required, you can specify an advertise URI explicitly by setting up the :ref:`iproto.advertise.\.uri ` option. +In the example below, ``iproto.listen`` includes two URIs that can be used to connect to ``instance001`` but only the second one is used to advertise this instance to other replica set peers: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml + :language: yaml + :start-at: instance001: + :end-before: instance002: + :dedent: + +The ``iproto.advertise..uri`` option can also accept an FQDN instead of an IP address: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + advertise: + peer: + uri: 'server001.example.com:3301' + +To learn about the specifics of configuring an advertise URI’s SSL settings, see :ref:`configuration_connections_ssl_advertise_uri`. + + + + +.. _configuration_connections_ssl: +.. _enterprise-iproto-encryption: +.. _enterprise-iproto-encryption-config: + +Securing connections with SSL +----------------------------- + +.. admonition:: Enterprise Edition + :class: fact + + SSL is supported by the `Enterprise Edition `_ only. + +Tarantool supports the use of SSL connections to encrypt client-server communications for increased security. +To enable SSL, use the :ref:`.params.* ` options, which can be applied to both listen and advertise URIs. + + +.. _configuration_connections_ssl_without_ca: + +Without CA +~~~~~~~~~~ + +The example below demonstrates how to enable traffic encryption by using a self-signed server certificate. +The following parameters are specified for each instance: + +- :ref:`ssl_cert_file `: a path to an SSL certificate file. +- :ref:`ssl_key_file `: a path to a private SSL key file. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml + :language: yaml + :start-at: instances: + :dedent: + +You can find the full example here: `ssl_without_ca `_. + + +.. _configuration_connections_ssl_with_ca: + +With CA +~~~~~~~ + +The example below demonstrates how to enable traffic encryption by using a server certificate signed by a trusted certificate authority. +In this case, all replica set peers verify each other for authenticity. + +The following parameters are specified for each instance: + +- :ref:`ssl_ca_file `: a path to a trusted certificate authorities (CA) file. +- :ref:`ssl_cert_file `: a path to an SSL certificate file. +- :ref:`ssl_key_file `: a path to a private SSL key file. +- :ref:`ssl_password ` (``instance001``): a password for an encrypted private SSL key. +- :ref:`ssl_password_file ` (``instance002`` and ``instance003``): a text file containing passwords for encrypted SSL keys. +- :ref:`ssl_ciphers `: a colon-separated list of SSL cipher suites the connection can use. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml + :language: yaml + :start-at: instances: + :end-before: app: + :dedent: + +You can find the full example here: `ssl_with_ca `_. + + +.. _configuration_connections_ssl_advertise_uri: + +Advertise URI specifics +~~~~~~~~~~~~~~~~~~~~~~~ + +SSL parameters for an advertise URI should be set only if this :ref:`advertise URI is specified explicitly `. +Otherwise, SSL parameters of a listen URI are used and no additional configuration is required. + +Configuring an advertise URI's SSL options depends on whether a trusted certificate authorities (CA) file is set or not. +Without the CA file, you only need to set ``iproto.advertise..params.transport`` to ``ssl`` as shown below: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + advertise: + peer: + uri: 'server.example.com:3301' + params: + transport: 'ssl' + + +If the CA file is specified for a listen URI, you also need to configure ``ssl_cert_file`` and ``ssl_key_file`` for this advertise URI: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + params: + transport: 'ssl' + ssl_ca_file: 'certs/root_ca.crt' + ssl_cert_file: 'certs/instance001/server001.crt' + ssl_key_file: 'certs/instance001/server001.key' + advertise: + peer: + uri: 'server001.example.com:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/instance001/server001.crt' + ssl_key_file: 'certs/instance001/server001.key' + + + +.. _configuration_connections_ssl_reloading_certificates: + +Reloading certificates +~~~~~~~~~~~~~~~~~~~~~~ + +To reload SSL certificate files specified in the configuration, open an :ref:`admin console ` and reload the configuration using :ref:`config.reload() `: + +.. code-block:: lua + + require('config'):reload() + +New certificates will be used for new connections. +Existing connections will continue using old SSL certificates until reconnection is required. +For example, certificate expiry or a network issue causes reconnection. diff --git a/doc/platform/connections_and_auth/credentials.rst b/doc/platform/connections_and_auth/credentials.rst new file mode 100644 index 0000000000..6fba06d739 --- /dev/null +++ b/doc/platform/connections_and_auth/credentials.rst @@ -0,0 +1,151 @@ +.. _configuration_credentials: + +Credentials +=========== + +Tarantool enables flexible management of access to various database resources by providing specific privileges to users. +You can read more about the main concepts of Tarantool access control system in the :ref:`authentication` section. + +This topic describes how to create users and grant them the specified privileges in the :ref:`credentials ` section of a YAML configuration. +For example, you can define users with the ``replication`` and ``sharding`` roles to maintain :ref:`replication ` and sharding in a Tarantool cluster. + + +.. _configuration_credentials_managing_users_roles: + +Managing users and roles +------------------------ + +.. _configuration_credentials_managing_users_roles_creating_user: + +Creating a user +~~~~~~~~~~~~~~~ + +You can create new or configure credentials of the existing users in the :ref:`credentials.users ` section. + +In the example below, a ``dbadmin`` user without a password is created: + +.. code-block:: yaml + + credentials: + users: + dbadmin: {} + +To set a password, use the :ref:`credentials.users.\.password ` option: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: T0p_Secret + :dedent: + +.. _configuration_credentials_managing_users_roles_granting_privileges: + +Granting privileges to a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To assign a role to a user, use the :ref:`credentials.users.\.roles ` option. +In this example, the ``dbadmin`` user gets privileges granted to the ``super`` built-in role: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: [ super ] + :dedent: + +To create a new role, define it in the :ref:`credentials.roles.* ` section. +In the example below, the ``writers_space_reader`` role gets privileges to select data in the ``writers`` space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-after: spaces: [ books ] + :end-at: spaces: [ writers ] + :dedent: + +Then, you can assign this role to a user using :ref:`credentials.users.\.roles ` (``sampleuser`` in the example below): + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ writers_space_reader ] + :dedent: + +You can grant specific privileges directly using :ref:`credentials.users.\.privileges `. +In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + +You can find the full example here: `credentials `_. + +.. _configuration_credentials_managing_users_roles_revoking_privileges: + +Revoking privileges from a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To revoke a previously granted privilege, remove it from the configuration. + +For example, here is how to grant privileges to a space and how to revoke one of the privileges: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/revoke_one.yaml + :language: yaml + :start-at: # grant privileges + :dedent: + +If you want to revoke the remaining privilege to from a space, you can remove it, too, thus making ``permissions`` an empty array: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/revoke_all.yaml + :language: yaml + :start-at: # empty permissions array: + :end-at: [books] + :dedent: + +You can revoke all privileges by making the ``privileges`` an empty array: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/revoke_all.yaml + :language: yaml + :start-at: # empty privileges array: + :dedent: + +.. warning:: + Do not remove a user or a role from configuration in order to revoke that user's or role's privileges. If a user or a role is entirely + removed from the configuration, it is not tracked by configuration machinery anymore. The user/role is not removed and its privileges are not revoked. + +.. _configuration_credentials_loading_secrets: + +Loading secrets from safe storage +--------------------------------- + +Tarantool enables you to load secrets from safe storage such as external files or environment variables. +To do this, you need to define corresponding options in the :ref:`config.context ` section. +In the examples below, ``context.dbadmin_password`` and ``context.sampleuser_password`` define how to load user passwords from ``*.txt`` files or environment variables: + +* This example shows how to load passwords from ``*.txt`` files: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + +* This example shows how to load passwords from environment variables: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + These environment variables should be set before :ref:`starting instances `. + +After configuring how to load passwords, you can set password values using :ref:`credentials.users.\.password ` as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: credentials: + :end-at: context.sampleuser_password + :dedent: + +You can find the full examples here: `credentials_context_file `_, `credentials_context_env `_. diff --git a/doc/platform/connections_and_auth/index.rst b/doc/platform/connections_and_auth/index.rst new file mode 100644 index 0000000000..7aa12af20a --- /dev/null +++ b/doc/platform/connections_and_auth/index.rst @@ -0,0 +1,13 @@ +.. _connections_and_authentication: + +Connections and authentication +============================== + +This section contains guides on how to configure connections and authentication features. + +.. toctree:: + :maxdepth: 1 + + connections + credentials + authentication diff --git a/doc/how-to/db/crud.rst b/doc/platform/ddl_dml/crud.rst similarity index 100% rename from doc/how-to/db/crud.rst rename to doc/platform/ddl_dml/crud.rst diff --git a/doc/concepts/data_model/foreign_key.svg b/doc/platform/ddl_dml/foreign_key.svg similarity index 100% rename from doc/concepts/data_model/foreign_key.svg rename to doc/platform/ddl_dml/foreign_key.svg diff --git a/doc/platform/ddl_dml/index.rst b/doc/platform/ddl_dml/index.rst new file mode 100644 index 0000000000..d629312295 --- /dev/null +++ b/doc/platform/ddl_dml/index.rst @@ -0,0 +1,38 @@ +.. _box_data_model: + +Defining and manipulating data +============================== + +Tarantool stores data in :ref:`spaces `, which can be thought of as tables in a relational database. +Every record or row in a space is called a :ref:`tuple `. +A tuple may have any number of fields, and the fields may be of different :ref:`types `. + +String data in fields are compared based on the specified :ref:`collation ` rules. +The user can provide hard limits for data values through :ref:`constraints ` +and link related spaces with :ref:`foreign keys `. + +Tarantool supports highly customizable :ref:`indexes ` of various types. +In particular, indexes can be defined with generators like :ref:`sequences `. + +There are six basic :ref:`data operations ` in Tarantool: +SELECT, INSERT, UPDATE, UPSERT, REPLACE, and DELETE. A number of :ref:`complexity factors ` +affects the resource usage of each function. + +Tarantool allows :ref:`describing the data schema ` but does not require it. +The user can :ref:`migrate a schema ` without migrating the data. + +To ensure :ref:`data persistence ` and recover quickly in case of failure, +Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots. + +This section contains guides on performing data operations in Tarantool. + +.. toctree:: + :maxdepth: 1 + + value_store + schema_desc + operations + migrations/index + read_views + sql/index + diff --git a/doc/concepts/data_model/indexes.rst b/doc/platform/ddl_dml/indexes.rst similarity index 97% rename from doc/concepts/data_model/indexes.rst rename to doc/platform/ddl_dml/indexes.rst index 8b65bf5781..29571854fe 100644 --- a/doc/concepts/data_model/indexes.rst +++ b/doc/platform/ddl_dml/indexes.rst @@ -30,8 +30,7 @@ The first index defined on a space is called the **primary key index**, and it must be unique. All other indexes are called **secondary indexes**, and they may be non-unique. -Indexes have certain limitations. See details on page -:doc:`Limitations `. +Indexes have certain limitations. See details on page :ref:`tarantool_limitations`. To create a generator for indexes, you can use a sequence object. Learn how to do it in the :ref:`tutorial `. @@ -68,7 +67,7 @@ To learn more about field types, check the - Index type * - ``'boolean'`` - :ref:`boolean ` - - :ref:`boolean ` + - TREE or HASH * - ``'integer'`` (may also be called ``'int'``) - :ref:`integer `, which may include unsigned values - TREE or HASH @@ -95,12 +94,15 @@ To learn more about field types, check the * - ``'uuid'`` - :ref:`uuid ` - TREE or HASH - * - ``datetime`` + * - ``'datetime'`` - :ref:`datetime ` - TREE * - ``'array'`` - :ref:`array ` - :ref:`RTREE ` + * - ``'map'`` + - :ref:`table ` + - Cannot be indexed * - ``'scalar'`` - may include :ref:`nil `, :ref:`boolean `, @@ -260,7 +262,7 @@ RTREE index can accept two types of ``distance`` functions: ``euclid`` and ``man .. warning:: Currently, the :ref:`isolation level ` of RTREE indexes - in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). + in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). If a transaction uses these indexes, it can read committed or confirmed data (depending on the isolation level). However, the indexes are subject to different anomalies that can make them unserializable. @@ -443,7 +445,7 @@ attributes. .. warning:: Currently, the :ref:`isolation level ` of BITSET indexes - in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). + in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). If a transaction uses these indexes, it can read committed or confirmed data (depending on the isolation level). However, the indexes are subject to different anomalies that can make them unserializable. diff --git a/doc/platform/ddl_dml/migrations/basic_migrations_tt.rst b/doc/platform/ddl_dml/migrations/basic_migrations_tt.rst new file mode 100644 index 0000000000..9ae58f6609 --- /dev/null +++ b/doc/platform/ddl_dml/migrations/basic_migrations_tt.rst @@ -0,0 +1,311 @@ +.. _basic_migrations_tt: + +Basic tt migrations tutorial +============================ + +**Example on GitHub:** `migrations `_ + +In this tutorial, you learn to define the cluster data schema using the centralized +migration management mechanism implemented in the Enterprise Edition of the :ref:`tt ` utility. + +.. _basic_migrations_tt_prereq: + +Prerequisites +------------- + +Before starting this tutorial: + +- Download and :ref:`install Tarantool Enterprise SDK `. +- Install `etcd `__. + +.. _basic_migrations_tt_cluster: + +Preparing a cluster +------------------- + +The centralized migration mechanism works with Tarantool EE clusters that: + +- use etcd as a centralized configuration storage +- use the `CRUD `__ module or its Enterprise + version for data distribution + +.. _basic_migrations_tt_cluster_etcd: + +Setting up etcd +~~~~~~~~~~~~~~~ + +First, start up an etcd instance to use as a configuration storage: + +.. code-block:: console + + $ etcd + +etcd runs on the default port 2379. + +Optionally, enable etcd authentication by executing the following script: + +.. code-block:: bash + + #!/usr/bin/env bash + + etcdctl user add root:topsecret + etcdctl role add app_config_manager + etcdctl role grant-permission app_config_manager --prefix=true readwrite /myapp/ + etcdctl user add app_user:config_pass + etcdctl user grant-role app_user app_config_manager + etcdctl auth enable + +It creates an etcd user ``app_user`` with read and write permissions to the ``/myapp`` +prefix, in which the cluster configuration will be stored. The user's password is ``config_pass``. + +.. note:: + + If you don't enable etcd authentication, make ``tt migrations`` calls without + the configuration storage credentials. + +.. _basic_migrations_tt_cluster_create: + +Creating a cluster +~~~~~~~~~~~~~~~~~~ + +#. Initialize a ``tt`` environment: + + .. code-block:: console + + $ tt init + +#. In the ``instances.enabled`` directory, create the ``myapp`` directory. +#. Go to the ``instances.enabled/myapp`` directory and create application files: + + - ``instances.yml``: + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/instances.yml + :language: yaml + :dedent: + + - ``config.yaml``: + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/config.yaml + :language: yaml + :dedent: + + - ``myapp-scm-1.rockspec``: + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/myapp-scm-1.rockspec + :language: none + :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 storage replica sets, each including one master and one read-only replica. + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/source.yaml + :language: yaml + :dedent: + +#. Publish the configuration to etcd: + + .. code-block:: console + + $ tt cluster publish "http://app_user:config_pass@localhost:2379/myapp/" source.yaml + +The full cluster code is available on GitHub here: `migrations `_. + +.. _basic_migrations_tt_cluster_start: + +Building and starting the cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Build the application: + + .. code-block:: console + + $ tt build myapp + +#. Start the cluster: + + .. code-block:: console + + $ tt start myapp + + To check that the cluster is up and running, use ``tt status``: + + .. code-block:: console + + $ tt status myapp + +#. Bootstrap vshard in the cluster: + + .. code-block:: console + + $ tt replicaset vshard bootstrap myapp + +.. _basic_migrations_tt_write: + +Writing migrations +------------------ + +To perform migrations in the cluster, write them in Lua and publish to the cluster's +etcd configuration storage. + +Each migration file must return a Lua table with one object named ``apply``. +This object has one field -- ``scenario`` -- that stores the migration function: + +.. code-block:: lua + + local function apply_scenario() + -- migration code + end + + return { + apply = { + scenario = apply_scenario, + }, + } + +The migration unit is a single file: its ``scenario`` is executed as a whole. An error +that happens in any step of the ``scenario`` causes the entire migration to fail. + +Migrations are executed in the lexicographical order. Thus, it's convenient to +use filenames that start with ordered numbers to define the migrations order, for example: + +.. code-block:: text + + 000001_create_space.lua + 000002_create_index.lua + 000003_alter_space.lua + +The default location where ``tt`` searches for migration files is ``/migrations/scenario``. +Create this subdirectory inside the ``tt`` environment. Then, create two migration files: + +- ``000001_create_writers_space.lua``: create a space, define its format, and + create a primary index. + + .. literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000001_create_writers_space.lua + :language: lua + :dedent: + + .. note:: + + Note the usage of the ``tt-migrations.helpers`` module. + In this example, its function ``register_sharding_key`` is used + to define a sharding key for the space. + +- ``000002_create_writers_index.lua``: add one more index. + + .. literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000002_create_writers_index.lua + :language: lua + :dedent: + +.. _basic_migrations_tt_publish: + +Publishing migrations +--------------------- + +To publish migrations to the etcd configuration storage, run ``tt migrations publish``: + +.. code-block:: console + + $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" + • 000001_create_writes_space.lua: successfully published to key "000001_create_writes_space.lua" + • 000002_create_writers_index.lua: successfully published to key "000002_create_writers_index.lua" + +.. _basic_migrations_tt_apply: + +Applying migrations +------------------- + +To apply published migrations to the cluster, run ``tt migrations apply`` providing +a cluster user's credentials: + +.. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + +.. important:: + + The cluster user must have enough access privileges to execute the migrations code. + +The output should look as follows: + +.. code-block:: console + + • router-001: + • 000001_create_writes_space.lua: successfully applied + • 000002_create_writers_index.lua: successfully applied + • storage-001: + • 000001_create_writes_space.lua: successfully applied + • 000002_create_writers_index.lua: successfully applied + • storage-002: + • 000001_create_writes_space.lua: successfully applied + • 000002_create_writers_index.lua: successfully applied + +The migrations are applied on all replica set leaders. Read-only replicas +receive the changes from the corresponding replica set leaders. + +Check the migrations status with ``tt migration status``: + +.. code-block:: console + + $ tt migrations status "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + • migrations centralized storage scenarios: + • 000001_create_writes_space.lua + • 000002_create_writers_index.lua + • migrations apply status on Tarantool cluster: + • router-001: + • 000001_create_writes_space.lua: APPLIED + • 000002_create_writers_index.lua: APPLIED + • storage-001: + • 000001_create_writes_space.lua: APPLIED + • 000002_create_writers_index.lua: APPLIED + • storage-002: + • 000001_create_writes_space.lua: APPLIED + • 000002_create_writers_index.lua: APPLIED + +To make sure that the space and indexes are created in the cluster, connect to the router +instance and retrieve the space information: + +.. code-block:: console + + $ tt connect myapp:router-001-a + +.. code-block:: tarantoolsession + + myapp:router-001-a> require('crud').schema('writers') + --- + - indexes: + 0: + unique: true + parts: + - fieldno: 1 + type: number + exclude_null: false + is_nullable: false + id: 0 + type: TREE + name: primary + 2: + unique: true + parts: + - fieldno: 4 + type: number + exclude_null: false + is_nullable: false + id: 2 + type: TREE + name: age + format: [{'name': 'id', 'type': 'number'}, {'type': 'number', 'name': 'bucket_id', + 'is_nullable': true}, {'name': 'name', 'type': 'string'}, {'name': 'age', 'type': 'number'}] + ... + +.. _basic_migrations_tt_next: + +Next steps +---------- + +Learn to write and perform data migration in :ref:`upgrade_migrations_tt`. \ No newline at end of file diff --git a/doc/platform/ddl_dml/migrations/centralized_migrations_tt.rst b/doc/platform/ddl_dml/migrations/centralized_migrations_tt.rst new file mode 100644 index 0000000000..db59261a7e --- /dev/null +++ b/doc/platform/ddl_dml/migrations/centralized_migrations_tt.rst @@ -0,0 +1,25 @@ +.. _centralized_migrations_tt: + +Centralized migrations with tt +============================== + +**Example on GitHub:** `migrations `_ + +In this section, you learn to use the centralized migration management mechanism +implemented in the Enterprise Edition of the :ref:`tt ` utility. + +The section includes the following tutorials: + +.. toctree:: + :maxdepth: 1 + + basic_migrations_tt + upgrade_migrations_tt + extend_migrations_tt + troubleshoot_migrations_tt + + +See also: + +- :ref:`tt migrations reference ` for the full list of command-line options. +- :ref:`tcm_cluster_migrations` to learn about managing migrations from |tcm_full_name|. \ No newline at end of file diff --git a/doc/platform/ddl_dml/migrations/extend_migrations_tt.rst b/doc/platform/ddl_dml/migrations/extend_migrations_tt.rst new file mode 100644 index 0000000000..d82d9e8148 --- /dev/null +++ b/doc/platform/ddl_dml/migrations/extend_migrations_tt.rst @@ -0,0 +1,103 @@ +.. _extend_migrations_tt: + +Extending the cluster +===================== + +**Example on GitHub:** `migrations `_ + +In this tutorial, you learn how to consistently define the data schema on newly +added cluster instances using the centralized migration management mechanism. + +.. _extend_migrations_tt_prereq: + +Prerequisites +------------- + +Before starting this tutorial, complete the :ref:`basic_migrations_tt` and :ref:`upgrade_migrations_tt`. +As a result, you have a sharded Tarantool EE cluster that uses an etcd-based configuration +storage. The cluster has a space with two indexes. + +.. _extend_migrations_tt_cluster: + +Extending the cluster +--------------------- + +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. + +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. + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/instances-3-storages.yml + :language: yaml + :start-at: storage-003-a: + :dedent: + +- ``source.yaml``: add the lines below to the end. + + .. literalinclude:: /code_snippets/snippets/migrations/instances.enabled/myapp/source-3-storages.yaml + :language: yaml + :start-at: storage-003: + :dedent: + +Publish the new cluster configuration to etcd: + +.. code-block:: console + + $ tt cluster publish "http://app_user:config_pass@localhost:2379/myapp/" source.yaml + +Run ``tt start`` to start up the new instances: + +.. code-block:: console + + $ tt start myapp + • The instance myapp:router-001-a (PID = 61631) is already running. + • The instance myapp:storage-001-a (PID = 61632) is already running. + • The instance myapp:storage-001-b (PID = 61634) is already running. + • The instance myapp:storage-002-a (PID = 61639) is already running. + • The instance myapp:storage-002-b (PID = 61640) is already running. + • Starting an instance [myapp:storage-003-a]... + • Starting an instance [myapp:storage-003-b]... + +Now the cluster contains three storage replica sets. + + +.. _extend_migrations_tt_apply: + +Applying migrations to the new replica set +------------------------------------------ + +The new replica set -- ``storage-003``-- is just started and has no data schema yet. +Apply all stored migrations to the cluster to load the same data schema to the new replica set: + +.. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + --replicaset=storage-003 + +.. note:: + + You can also apply migrations without specifying the replica set. All published + migrations are already applied on other replica sets, so ``tt`` skips the + operation on them. + + .. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + +To make sure that the space exists on the new instances, connect to ``storage-003-a`` +and check ``box.space.writers``: + +.. code-block:: console + + $ tt connect myapp:storage-003-a + +.. code-block:: tarantoolsession + + myapp:storage-003-a> box.space.writers ~= nil + --- + - true + ... diff --git a/doc/enterprise/images/ddl-state.png b/doc/platform/ddl_dml/migrations/images/ddl-state.png similarity index 100% rename from doc/enterprise/images/ddl-state.png rename to doc/platform/ddl_dml/migrations/images/ddl-state.png diff --git a/doc/platform/ddl_dml/migrations/index.rst b/doc/platform/ddl_dml/migrations/index.rst new file mode 100644 index 0000000000..ffdae15d40 --- /dev/null +++ b/doc/platform/ddl_dml/migrations/index.rst @@ -0,0 +1,165 @@ +.. _migrations: + +Migrations +========== + +**Migration** refers to any change in a data schema: adding or removing a field, +creating or dropping an index, changing a field format, and so on. Space creation +is also a migration. Using migrations, you can track the evolution of your +data schema since its initial state. In Tarantool, migrations are presented as Lua +code that alters the data schema using the built-in Lua API. + +There are two types of migrations: + +- *simple migrations* don't require additional actions on existing data +- *complex migrations* include both schema and data changes + +.. _migrations_simple: + +Simple migrations +----------------- + +There are two types of schema migration that do not require data migration: + +- *Creating an index*. A new index can be created at any time. To learn more about + index creation, see :ref:`concepts-data_model_indexes` and the :ref:`box_space-create_index` reference. +- *Adding a field to the end of a space*. To add a field, update the space format so + that it includes all its fields and also the new field. For example: + + .. code-block:: lua + + local users = box.space.writers + local fmt = users:format() + + table.insert(fmt, { name = 'age', type = 'number', is_nullable = true }) + users:format(fmt) + + The field must have the ``is_nullable`` parameter. Otherwise, an error occurs + if the space contains tuples of old format. + + .. note:: + + After creating a new field, you probably want to fill it with data. + The `tarantool/moonwalker `_ + module is useful for this task. + +.. _migrations_complex: + +Complex migrations +------------------ + +Other types of migrations are more complex and require additional actions to +maintain data consistency. + +Migrations are possible in two cases: + +- When Tarantool starts, and no client uses the database yet +- During request processing, when active clients are already using the database + +For the first case, it is enough to write and test the migration code. +The most difficult task is to migrate data when there are active clients. +You should keep it in mind when you initially design the data schema. + +We identify the following problems if there are active clients: + +- Associated data can change atomically. + +- The system should be able to transfer data using both the new schema and the old one. + +- When data is being transferred to a new space, data access should consider + that the data might be in one space or another. + +- Write requests must not interfere with the migration. + A common approach is to write according to the new data schema. + +These issues may or may not be relevant depending on your application and +its availability requirements. + +Tarantool offers the following features that make migrations easier and safer: + +- *Transaction mechanism*. It is useful when writing a migration, + because it allows you to work with the data atomically. But before using + the transaction mechanism, you should explore its limitations. + For details, see the section about :ref:`transactions `. + +- ``space:upgrade()`` *function* (EE only). With the help of ``space:upgrade()``, + you can enable compression and migrate, including already created tuples. + For details, check the :ref:`Upgrading space schema ` section. + +- *Centralized migration management mechanism* (EE only). Implemented + in the Enterprise version of the :ref:`tt ` utility and in :ref:`tcm`, + this mechanism enables migration execution and tracking in the replication + clusters. For details, see :ref:`migrations_centralized`. + +.. _migrations_apply: + +Applying migrations +------------------- + +The migration code is executed on a running Tarantool instance. +Important: no method guarantees you transactional application of migrations +on the whole cluster. + +**Method 1**: include migrations in the application code + +This is quite simple: when you reload the code, the data is migrated at the right moment, +and the database schema is updated. +However, this method may not work for everyone. +You may not be able to restart Tarantool or update the code using the hot-reload mechanism. + +**Method 2**: the :ref:`tt ` utility + +Connect to the necessary instance using ``tt connect``. + +.. code:: console + + $ tt connect admin:password@localhost:3301 + +- If your migration is written in a Lua file, you can execute it + using ``dofile()``. Call this function and specify the path to the + migration file as the first argument. It looks like this: + + .. code-block:: tarantoolsession + + tarantool> dofile('0001-delete-space.lua') + --- + ... + +- (or) Copy the migration script code, + paste it into the console, and run it. + +You can also connect to the instance and execute the migration script in a single call: + +.. code:: console + + $ tt connect admin:password@localhost:3301 -f 0001-delete-space.lua + +.. _migrations_centralized: + +Centralized migration management +-------------------------------- + +.. admonition:: Enterprise Edition + :class: fact + + Centralized migration management is available in the `Enterprise Edition `_ only. + +Tarantool EE offers a mechanism for centralized migration management in replication +clusters that use etcd as a :ref:`configuration storage `. +The mechanism uses the same etcd storage to store migrations and applies them +across the entire Tarantool cluster. This ensures migration consistency +in the cluster and enables migration history tracking. + +The centralized migration management mechanism is implemented in the Enterprise +version of the :ref:`tt ` utility and in :ref:`tcm`. + +To learn how to manage migrations in Tarantool EE clusters from the command line, +see :ref:`centralized_migrations_tt`. To learn how to use the mechanism from the |tcm| +web interface, see the :ref:`tcm_cluster_migrations` |tcm| documentation page. + +.. toctree:: + :maxdepth: 1 + + centralized_migrations_tt + space_upgrade + diff --git a/doc/enterprise/space_upgrade.rst b/doc/platform/ddl_dml/migrations/space_upgrade.rst similarity index 98% rename from doc/enterprise/space_upgrade.rst rename to doc/platform/ddl_dml/migrations/space_upgrade.rst index f8eb00c082..13f266a783 100644 --- a/doc/enterprise/space_upgrade.rst +++ b/doc/platform/ddl_dml/migrations/space_upgrade.rst @@ -1,8 +1,14 @@ .. _enterprise-space_upgrade: +.. _box_space-upgrade: Upgrading space schema ====================== +.. admonition:: Enterprise Edition + :class: fact + + ``space:upgrade()`` is available in the `Enterprise Edition `_ only. + In Tarantool, :ref:`migration ` refers to any change in a data schema, for example, creating an index, adding a field, or changing a field format. If you need to change a data schema, there are several possible cases: @@ -15,7 +21,7 @@ If you need to change a data schema, there are several possible cases: To solve the task of migrating the data, you can: -* :ref:`Migrate data ` to a new space manually. +* :ref:`Migrate data ` to a new space manually. * Use the ``space:upgrade()`` feature. diff --git a/doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst b/doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst new file mode 100644 index 0000000000..a56c9c8179 --- /dev/null +++ b/doc/platform/ddl_dml/migrations/troubleshoot_migrations_tt.rst @@ -0,0 +1,103 @@ +.. _centralized_migrations_tt_troubleshoot: + +Troubleshooting migrations +========================== + +The centralized migrations mechanism allows troubleshooting migration issues using +dedicated ``tt migration`` options. When troubleshooting migrations, remember that +any unfinished or failed migration can bring the data schema into to inconsistency. +Additional steps may be needed to fix this. + +.. warning:: + + The options used for migration troubleshooting can cause migration inconsistency + in the cluster. Use them only for local development and testing purposes. + +.. _centralized_migrations_tt_troubleshoot_publish: + +Incorrect migration published +----------------------------- + +If an incorrect migration was published to etcd but wasn't applied yet, +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" \ + 000001_create_space.lua --overwrite + +If the migration that needs a fix isn't the last in the lexicographical order, +add also ``--ignore-order-violation``: + +.. code-block:: console + + $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" \ + 000001_create_space.lua --overwrite --ignore-order-violation + +If a migration was published by mistake and wasn't applied yet, you can delete it +from etcd using ``tt migrations remove``: + +.. code-block:: console + + $ tt migrations remove "http://app_user:config_pass@localhost:2379/myapp" \ + --migration 000003_not_needed.lua + +.. _centralized_migrations_tt_troubleshoot_apply: + +Incorrect migration applied +--------------------------- + +.. warning:: + + Any schema change that was made by an incorrect migration before its fail or + cancellation must be resolved manually on each replica set before reapply. + ``--force-reapply`` and other ``tt migrations`` options affect only internal + status of the migration and don't revert changes that it has made in the cluster. + +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 + +If execution of the incorrect migration version has failed, you may also need to add +the ``--ignore-preceding-status`` option: + +When you reapply a migration, ``tt`` checks the statuses of preceding migrations +to ensure consistency. To skip this check, add the ``--ignore-preceding-status`` option: + +.. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret \ + --migration=00003_alter_space.lua + --force-reapply --ignore-preceding-status + +.. _centralized_migrations_tt_troubleshoot_stop: + +Migration execution takes too long +---------------------------------- + +To interrupt migration execution on the cluster, use ``tt migrations stop``: + +.. code-block:: console + + $ tt migrations stop "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + +You can adjust the maximum migration execution time using the ``--execution-timeout`` +option of ``tt migrations apply``: + +.. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret \ + --execution-timeout=60 + +.. note:: + + If a migration timeout is reached, you may need to call ``tt migrations stop`` + to cancel requests that were sent when applying migrations. \ No newline at end of file diff --git a/doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst b/doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst new file mode 100644 index 0000000000..234e58e915 --- /dev/null +++ b/doc/platform/ddl_dml/migrations/upgrade_migrations_tt.rst @@ -0,0 +1,152 @@ +.. _upgrade_migrations_tt: + +Data migrations with space.upgrade() +==================================== + +**Example on GitHub:** `migrations `_ + +In this tutorial, you learn to write migrations that include data migration using +the ``space.upgrade()`` function. + +.. _upgrade_migrations_tt_prereq: + +Prerequisites +------------- + +Before starting this tutorial, complete the :ref:`basic_migrations_tt`. +As a result, you have a sharded Tarantool EE cluster that uses an etcd-based configuration +storage. The cluster has a space with two indexes. + +.. _upgrade_migrations_tt_write: + +Writing a complex migration +--------------------------- + +Complex migrations require data migration along with schema migration. Connect to +the router instance and insert some tuples into the space before proceeding to the next steps. + +.. code-block:: console + + $ tt connect myapp:router-001-a + +.. code-block:: tarantoolsession + + myapp:router-001-a> require('crud').insert_object_many('writers', { + {id = 1, name = 'Haruki Murakami', age = 75}, + {id = 2, name = 'Douglas Adams', age = 49}, + {id = 3, name = 'Eiji Mikage', age = 41}, + }, {noreturn = true}) + +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 ` 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: + +.. code-block:: lua + + local function apply_scenario() + -- migration code + end + return { + apply = { + scenario = apply_scenario, + }, + } + +Start the migration function with the new format description: + +.. literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua + :language: lua + :start-at: local function apply_scenario() + :end-at: box.space.writers.index.age:drop() + :dedent: + +.. note:: + + ``box.space.writers.index.age:drop()`` drops an existing index. This is done + because indexes rely on field numbers and may break during this format change. + If you need the ``age`` field indexed, recreate the index after applying the + new format. + +Next, create a stored function that transforms tuples to fit the new format. +In this case, the function extracts the first and the last name from the ``name`` field +and returns a tuple of the new format: + +.. literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua + :language: lua + :start-at: box.schema.func.create + :end-before: local future = space:upgrade + :dedent: + +Finally, call ``space:upgrade()`` with the new format and the transformation function +as its arguments. Here is the complete migration code: + +.. literalinclude:: /code_snippets/snippets/migrations/migrations/scenario/000003_alter_writers_space.lua + :language: lua + :dedent: + +Learn more about ``space.upgrade()`` in :ref:`enterprise-space_upgrade`. + +.. _upgrade_migrations_tt_publish: + +Publishing the migration +------------------------ + +Publish the new migration to etcd. + +.. code-block:: console + + $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" \ + migrations/scenario/000003_alter_writers_space.lua + +.. note:: + + You can also publish all migrations from the default location ``/migrations/scenario``. + All other migrations stored in this directory are already published, so ``tt`` + skips them. + + .. code-block:: console + + $ tt migrations publish "http://app_user:config_pass@localhost:2379/myapp" + + +.. _upgrade_migrations_tt_apply: + +Applying the migration +---------------------- + +Apply the published migrations: + +.. code-block:: console + + $ tt migrations apply "http://app_user:config_pass@localhost:2379/myapp" \ + --tarantool-username=client --tarantool-password=secret + +Connect to the router instance and check that the space and its tuples have the new format: + +.. code-block:: console + + $ tt connect myapp:router-001-a + +.. code-block:: tarantoolsession + + myapp:router-001-a> require('crud').get('writers', 2) + --- + - rows: [2, 401, 'Douglas', 'Adams', 49] + metadata: [{'name': 'id', 'type': 'number'}, {'name': 'bucket_id', 'type': 'number'}, + {'name': 'first_name', 'type': 'string'}, {'name': 'last_name', 'type': 'string'}, + {'name': 'age', 'type': 'number'}] + - null + ... + + +.. _upgrade_migrations_tt_next: + +Next steps +---------- + +Learn to use migrations for data schema definition on new instances added to the cluster +in :ref:`extend_migrations_tt`. \ No newline at end of file diff --git a/doc/concepts/data_model/operations.rst b/doc/platform/ddl_dml/operations.rst similarity index 97% rename from doc/concepts/data_model/operations.rst rename to doc/platform/ddl_dml/operations.rst index 602c202539..0fd4a620b4 100644 --- a/doc/concepts/data_model/operations.rst +++ b/doc/platform/ddl_dml/operations.rst @@ -150,9 +150,15 @@ resource usage of each function. important than the others. * - WAL settings - The important setting for the write-ahead log is - :ref:`wal_mode `. + :ref:`wal.mode `. If the setting causes no writing or delayed writing, this factor is unimportant. If the setting causes every data-change request to wait for writing to finish on a slow device, this factor is more important than all the others. + +.. toctree:: + :hidden: + + crud + sequences diff --git a/doc/enterprise/read_views.rst b/doc/platform/ddl_dml/read_views.rst similarity index 80% rename from doc/enterprise/read_views.rst rename to doc/platform/ddl_dml/read_views.rst index 8316473dbf..a3f304a4b5 100644 --- a/doc/enterprise/read_views.rst +++ b/doc/platform/ddl_dml/read_views.rst @@ -3,6 +3,11 @@ Read views ========== +.. admonition:: Enterprise Edition + :class: fact + + Read views are available in the `Enterprise Edition `_ only. + A read view is an in-memory snapshot of the entire database that isn't affected by future :ref:`data modifications `. Read views provide access to database spaces and their indexes and enable you to @@ -21,10 +26,6 @@ Tarantool duplicates only blocks modified after a read view is created. Tarantool Enterprise Edition supports read views starting from v2.11.0 and enables the ability to work with them using both :ref:`Lua ` and :ref:`C API `. - - - - .. _read_views_limitations: Limitations @@ -32,11 +33,10 @@ Limitations Read views have the following limitations: -- Only the :ref:`memtx ` engine is supported. -- Only TREE and HASH :ref:`indexes ` are supported. -- Pagination is not supported (the :ref:`after ` option). - +- Only the :ref:`memtx ` engine is supported. +- Only :ref:`TREE `, :ref:`HASH ` and :ref:`functional ` + indexes are supported. .. _working_with_read_views: @@ -73,8 +73,6 @@ After creating a read view, you can see the information about it by calling To list all the created read views, call the :ref:`box.read_view.list() ` function. - - .. _querying_data: Querying data @@ -111,7 +109,39 @@ Similarly, you can retrieve data by the specific index. - [3, 'Ace of Base', 1987] ... +Pagination is supported in read views in the same ways as in ``select`` requests +to spaces: using the ``fetch_pos`` and ``after`` arguments. To get the cursor position +after executing a request on a read view, set ``fetch_pos`` to ``true``: +.. code-block:: tarantoolsession + + tarantool> result, position = read_view1.space.bands:select({}, { limit = 3, fetch_pos = true }) + --- + ... + + tarantool> result + --- + - - [1, 'Roxette', 1986] + - [2, 'Scorpions', 1965] + - [3, 'Ace of Base', 1987] + ... + + tarantool> position + --- + - kQM + ... + +Then, pass this position in the ``after`` parameter of a request to get the +next data chunk: + +.. code-block:: tarantoolsession + + tarantool> read_view1.space.bands:select({}, { limit = 3, after = position }) + --- + - - [4, 'The Beatles', 1960] + - [5, 'Pink Floyd', 1965] + - [6, 'The Rolling Stones', 1962] + ... .. _closing_read_view: @@ -134,13 +164,11 @@ After the read view is closed, its :ref:`status ` is set to ``closed``. On an attempt to use it, an error is raised. - .. _read_views_example: Example ------- - A Tarantool session below demonstrates how to open a read view, get data from this view, and close it. To repeat these steps, you need to bootstrap a Tarantool instance @@ -200,12 +228,3 @@ as described in :ref:`Using data operations read_view1:close() --- ... - - - -.. toctree:: - :maxdepth: 2 - :hidden: - - read_views/lua_api - read_views/c_api \ No newline at end of file diff --git a/doc/concepts/data_model/schema_desc.rst b/doc/platform/ddl_dml/schema_desc.rst similarity index 89% rename from doc/concepts/data_model/schema_desc.rst rename to doc/platform/ddl_dml/schema_desc.rst index cecf2566f6..21e9aefa03 100644 --- a/doc/concepts/data_model/schema_desc.rst +++ b/doc/platform/ddl_dml/schema_desc.rst @@ -86,14 +86,7 @@ The schema would look something like this: This alternative is simpler to use, and you do not have to dive deep into Lua. -``DDL`` is a built-in -:doc:`Cartridge ` module. -Cartridge is a cluster solution for Tarantool. In its WebUI, there is a separate tab -called "Code". On this tab, in the ``schema.yml`` file, you can define the schema, check its correctness, -and apply it to the whole cluster. - -If you do not use Cartridge, you can still use the DDL module: -put the following Lua code into the file that you use to run Tarantool. +To use the DDL module, put the following Lua code into the file that you use to run Tarantool. This file is usually called ``init.lua``. .. code:: lua diff --git a/doc/how-to/db/sequences.rst b/doc/platform/ddl_dml/sequences.rst similarity index 100% rename from doc/how-to/db/sequences.rst rename to doc/platform/ddl_dml/sequences.rst diff --git a/doc/platform/ddl_dml/sql/improving_mysql.rst b/doc/platform/ddl_dml/sql/improving_mysql.rst new file mode 100644 index 0000000000..52fd89ef68 --- /dev/null +++ b/doc/platform/ddl_dml/sql/improving_mysql.rst @@ -0,0 +1,320 @@ +.. _improving_mysql: + +Improving MySQL with Tarantool +============================== + +Replicating MySQL is one of the Tarantool’s killer functions. +It allows you to keep your existing MySQL database while at the same time +accelerating it and scaling it out horizontally. Even if you aren’t interested +in extensive expansion, replacing existing replicas with Tarantool can +save you money, because Tarantool is more efficient per core than MySQL. To read +a testimonial of a company that implemented Tarantool replication on a large scale, see +`the following article `_. + +If you run into any trouble with regards to the basics of Tarantool, see the +:ref:`Getting started guide ` or the :ref:`Data model description `. +A helpful log for troubleshooting during this tutorial is ``replicatord.log`` in ``/var/log``. +You can also have a look at the instance’s log ``example.log`` in ``/var/log/tarantool``. + +The tutorial is intended for **CentOS 7.5** and **MySQL 5.7**. +The tutorial requires that ``systemd`` and MySQL are installed. + +.. _improving_mysql-setup-mysql: + +Setting up MySQL +---------------- + +In this section, you configure MySQL and create a database. + +#. First, install the necessary packages in CentOS: + + .. code-block:: console + + $ yum -y install git ncurses-devel cmake gcc-c++ boost boost-devel wget unzip nano bzip2 mysql-devel mysql-lib + +#. Clone the Tarantool-MySQL replication package from GitHub: + + .. code-block:: console + + $ git clone https://github.com/tarantool/mysql-tarantool-replication.git + +#. Build the replicator with ``cmake``: + + .. code-block:: console + + $ cd mysql-tarantool-replication + $ git submodule update --init --recursive + $ cmake . + $ make + +#. The replicator will run as a ``systemd`` daemon called ``replicatord``, so, edit + its ``systemd`` service file (``replicatord.service``) in the + ``mysql-tarantool-replication`` repository: + + .. code-block:: console + + $ nano replicatord.service + + The following line should be changed: + + .. code-block:: bash + + ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.cfg + + To change it, replace the ``.cfg`` extension with ``.yml``: + + .. code-block:: bash + + ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.yml + +#. Next, copy the files from the ``replicatord`` repository to other necessary locations: + + .. code-block:: console + + $ cp replicatord /usr/local/sbin/replicatord + $ cp replicatord.service /etc/systemd/system + +#. Enter MySQL console and create a sample database (depending on + your existing installation, you may be a user other than root): + + .. code-block:: sql + + mysql -u root -p + CREATE DATABASE menagerie; + QUIT + +#. Get some sample data from MySQL. The data will be pulled into the root + directory. After that, install it from the terminal. + + .. code-block:: sql + + cd + wget http://downloads.mysql.com/docs/menagerie-db.zip + unzip menagerie-db.zip + cd menagerie-db + mysql -u root -p menagerie < cr_pet_tbl.sql + mysql -u root -p menagerie < load_pet_tbl.sql + mysql menagerie -u root -p < ins_puff_rec.sql + mysql menagerie -u root -p < cr_event_tbl.sql + +#. Enter MySQL console and massage the data for use with the + Tarantool replicator. In this step, you: + + * add an ID + * change a field name to avoid conflict + * cut down the number of fields + + With real data, this is the step that involves the most tweaking. + + .. code-block:: sql + + mysql -u root -p + USE menagerie; + ALTER TABLE pet ADD id INT PRIMARY KEY AUTO_INCREMENT FIRST; + ALTER TABLE pet CHANGE COLUMN 'name' 'name2' VARCHAR(255); + ALTER TABLE pet DROP sex, DROP birth, DROP death; + QUIT + +#. The sample data is set up. Edit MySQL + configuration file to use it with the replicator: + + .. code-block:: console + + $ cd + $ nano /etc/my.cnf + + Note that your ``my.cnf`` for MySQL could be in a slightly different location. + Set: + + .. code-block:: bash + + [mysqld] + binlog_format = ROW + server_id = 1 + log-bin = mysql-bin + interactive_timeout = 3600 + wait_timeout = 3600 + max_allowed_packet = 32M + socket = /var/lib/mysql/mysql.sock + bind-address = 127.0.0.1 + + [client] + socket = /var/lib/mysql/mysql.sock + +#. After exiting ``nano``, restart ``mysqld``: + + .. code-block:: console + + $ systemctl restart mysqld + +.. _improving_mysql-setup-tarantool: + +Installing and configuring Tarantool +------------------------------------ + +In this section, you install Tarantool and set up spaces for replication. + +#. Go to the `Download page `_ and + follow the installation instructions. + +#. Install the :ref:`tt CLI ` utility. + +#. Create a new tt environment in the current directory using the :ref:`tt init ` command. + +#. In the ``/etc/tarantool/instances.available/mysql`` directory, create the ``tt`` instance configuration files: + + * ``config.yaml`` -- specifies the following configuration + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/mysql/config.yaml + :language: yaml + :dedent: + + * ``instances.yml`` -- specifies instances to run in the current environment + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/mysql/instances.yml + :language: yaml + :dedent: + + * ``myapp.lua`` -- contains a Lua script with an application to load + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/mysql/myapp.lua + :language: lua + :lines: 3-17 + :dedent: + + For details, see the :ref:`Configuration ` section. + +#. Inside the ``instances.enabled`` directory of the created tt environment, create a symlink (``mysql``) + to the directory from the previous step: + + .. code-block:: console + + $ ln -s /etc/tarantool/instances.available/mysql mysql + +#. Next, start up the Lua program with ``tt``, the Tarantool command-line + utility: + + .. code-block:: console + + $ tt start mysql + +#. Enter the Tarantool instance: + + .. code-block:: console + + $ tt connect mysql:instance001 + +#. Check that the target spaces were successfully created: + + .. code-block:: tarantoolsession + + mysql:instance001> box.space._space:select() + + At the bottom, you will see ``mysqldaemon`` and ``mysqldata`` spaces. Then exit with "CTRL+C". + +.. _improving_mysql-replicator: + +Setting up the replicator +------------------------- + +MySQL and Tarantool are now set up. You can proceed to configure the replicator. + +#. Edit the ``replicatord.yml`` file in the main ``tarantool-mysql-replication`` directory: + + .. code-block:: bash + + nano replicatord.yml + +#. Change the entire file as follows. Don't forget to add your MySQL password and + set the appropriate user: + + .. code-block:: bash + + mysql: + host: 127.0.0.1 + port: 3306 + user: root + password: + connect_retry: 15 # seconds + + tarantool: + host: 127.0.0.1:3301 + binlog_pos_space: 512 + binlog_pos_key: 0 + connect_retry: 15 # seconds + sync_retry: 1000 # milliseconds + + mappings: + - database: menagerie + table: pet + columns: [ id, name2, owner, species ] + space: 513 + key_fields: [ 0 ] + # insert_call: function_name + # update_call: function_name + # delete_call: function_name + +#. Copy ``replicatord.yml`` to the location where ``systemd`` looks for it: + + .. code-block:: console + + $ cp replicatord.yml /usr/local/etc/replicatord.yml + +#. Next, start up the replicator: + + .. code-block:: console + + $ systemctl start replicatord + +#. Enter the Tarantool instance: + + .. code-block:: console + + $ tt connect mysql:instance001 + +#. Do a select on the ``mysqldata`` space. The replicated content from MySQL looks the following way: + + .. code-block:: tarantoolsession + + mysql:instance001> box.space.mysqldata:select() + --- + - - [1, 'Fluffy', 'Harold', 'cat'] + - [2, 'Claws', 'Gwen', 'cat'] + - [3, 'Buffy', 'Harold', 'dog'] + - [4, 'Fang', 'Benny', 'dog'] + - [5, 'Bowser', 'Diane', 'dog'] + - [6, 'Chirpy', 'Gwen', 'bird'] + - [7, 'Whistler', 'Gwen', 'bird'] + - [8, 'Slim', 'Benny', 'snake'] + - [9, 'Puffball', 'Diane', 'hamster'] + +.. _improving_mysql-test-replication: + +Testing the replication +----------------------- + +In this section, you enter a record into MySQL and check that the record is replicated to Tarantool. +To do this: + +#. Exit the Tarantool instance with ``CTRL-D``. + +#. Insert a record into MySQL: + + .. code-block:: sql + + mysql -u root -p + USE menagerie; + INSERT INTO pet(name2, owner, species) VALUES ('Spot', 'Brad', 'dog'); + QUIT + +#. In the terminal, enter the Tarantool instance: + + .. code-block:: bash + + $ tt connect mysql:instance001 + +#. To see the replicated data in Tarantool, run the following command: + + .. code-block:: tarantoolsession + + mysql:instance001> box.space.mysqldata:select() diff --git a/doc/how-to/sql/index.rst b/doc/platform/ddl_dml/sql/index.rst similarity index 100% rename from doc/how-to/sql/index.rst rename to doc/platform/ddl_dml/sql/index.rst diff --git a/doc/how-to/sql/sql_beginners_guide.rst b/doc/platform/ddl_dml/sql/sql_beginners_guide.rst similarity index 99% rename from doc/how-to/sql/sql_beginners_guide.rst rename to doc/platform/ddl_dml/sql/sql_beginners_guide.rst index 19eff0f171..84f9995ac2 100644 --- a/doc/how-to/sql/sql_beginners_guide.rst +++ b/doc/platform/ddl_dml/sql/sql_beginners_guide.rst @@ -9,6 +9,10 @@ The SQL Beginners' Guide is about databases in general, and about the relationsh Tarantool's NoSQL and SQL products. Most of the matters in the Beginners' Guide will already be familiar to people who have used relational databases before. +.. include:: sql_tutorial.rst + :start-after: sql_prereq_start + :end-before: sql_prereq_end + .. _sql_beginners_sample_table: Sample table diff --git a/doc/how-to/sql/sql_tutorial.rst b/doc/platform/ddl_dml/sql/sql_tutorial.rst similarity index 78% rename from doc/how-to/sql/sql_tutorial.rst rename to doc/platform/ddl_dml/sql/sql_tutorial.rst index 49b40659d6..c1d37b2292 100644 --- a/doc/how-to/sql/sql_tutorial.rst +++ b/doc/platform/ddl_dml/sql/sql_tutorial.rst @@ -1,4 +1,4 @@ -.. _sql_tutorial: +.. _sql_tutorial: SQL tutorial ============ @@ -6,45 +6,50 @@ SQL tutorial This tutorial is a demonstration of the support for SQL in Tarantool. It includes the functionality that you'd encounter in an "SQL-101" course. -.. _sql_tutorial-starting_up_with_a_first_table_and_selects: +.. sql_prereq_start -Starting up with a first table and SELECTs ------------------------------------------- +.. _sql_tutorial-prerequisites: -Initialize -~~~~~~~~~~ +Prerequisites +------------- -In this tutorial, the requests are done in the Tarantool interactive console. -Start Tarantool and initialize it with :ref:`default settings ` -by calling ``box.cfg{}``: +Before starting this tutorial: -.. code-block:: tarantoolsession +#. Install the :ref:`tt CLI ` utility. - tarantool> box.cfg{} +#. Start a Tarantool instance in the interactive mode by running :ref:`tt run -i `: -Now you can start working with the database. + .. code-block:: console -Switch to the SQL language -~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ tt run -i + Tarantool 3.0.0-0-g6ba34da7f8 + type 'help' for interactive help + tarantool> -A feature of the client console program is that you can switch languages and -specify the end-of-statement delimiter. +#. Initialize the instance and switch the input language to SQL: -Run the following commands to set the console input language to SQL and use -semicolon as a delimiter: + .. code-block:: tarantoolsession -.. code-block:: tarantoolsession + tarantool> box.cfg{} + tarantool> \set language sql + tarantool> \set delimiter ; + +Now you have a running Tarantool instance that accepts SQL input. - tarantool> \set language sql - tarantool> \set delimiter ; +.. sql_prereq_end + +.. _sql_tutorial-starting_up_with_a_first_table_and_selects: + +Create a table and execute SQL statements +----------------------------------------- CREATE, INSERT, UPDATE, SELECT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To get started, enter simple SQL statements: +To get started, enter these SQL statements: -.. code-block:: sql +.. code-block:: sql CREATE TABLE table1 (column1 INTEGER PRIMARY KEY, column2 VARCHAR(100)); INSERT INTO table1 VALUES (1, 'A'); @@ -53,9 +58,9 @@ To get started, enter simple SQL statements: The result of the ``SELECT`` statement looks like this: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - tarantool> SELECT * FROM table1 WHERE column1 = 1; + sql_tutorial:instance001> SELECT * FROM table1 WHERE column1 = 1; --- - metadata: - name: COLUMN1 @@ -68,8 +73,8 @@ The result of the ``SELECT`` statement looks like this: The result includes: -- Metadata: the names and data types of each column -- Result rows +* metadata: the names and data types of each column +* result rows For conciseness, metadata is skipped in query results in this tutorial. Only the result rows are shown. @@ -82,7 +87,9 @@ Here is ``CREATE TABLE`` with more details: * There are multiple columns, with different data types. * There is a ``PRIMARY KEY`` (unique and not-null) for two of the columns. -.. code-block:: sql +Create another table: + +.. code-block:: sql CREATE TABLE table2 (column1 INTEGER, column2 VARCHAR(100), @@ -95,13 +102,13 @@ The result is: ``row_count: 1``. INSERT ~~~~~~ -Put four rows in the table: +Put four rows in the table (``table2``): * The INTEGER and DOUBLE columns get numbers * The VARCHAR and SCALAR columns get strings (the SCALAR strings are expressed as hexadecimals) -.. code-block:: sql +.. code-block:: sql INSERT INTO table2 VALUES (1, 'AB', X'4142', 5.5); INSERT INTO table2 VALUES (1, 'CD', X'2020', 1E4); @@ -110,7 +117,7 @@ Put four rows in the table: Then try to put another row: -.. code-block:: sql +.. code-block:: sql INSERT INTO table2 VALUES (1, 'AB', X'A5', -5.5); @@ -120,17 +127,17 @@ key ``1, 'AB'`` already exists. The SEQSCAN keyword ~~~~~~~~~~~~~~~~~~~ -In Tarantool, ``SELECT`` SQL queries that perform sequential scans (that is, go -through all the table rows instead of using indexes) are prohibited by default. +Sequential scan is the scan through all the table rows instead of using indexes. +In Tarantool, ``SELECT`` SQL queries that perform sequential scans are prohibited by default. For example, this query leads to the error ``Scanning is not allowed for 'table2'``: -.. code-block:: sql +.. code-block:: sql SELECT * FROM table2; To execute a scan query, put the ``SEQSCAN`` keyword before the table name: -.. code-block:: sql +.. code-block:: sql SELECT * FROM SEQSCAN table2; @@ -145,7 +152,7 @@ The result is: * The first query returns rows: - .. code-block:: tarantoolsession + .. code-block:: tarantoolsession - [1, 'AB', 'AB', 10.5] - [1, 'CD', ' ', 10005] @@ -154,12 +161,12 @@ The result is: Although ``column1`` is indexed, the expression ``column1 + 1`` is not calculated from the index, which makes this ``SELECT`` a scan query. -.. note:: +.. note:: - You can allow SQL scan queries without ``SEQSCAN`` for the current session - by running the command: + To enable SQL scan queries without ``SEQSCAN`` for the current session, + run this command: - .. code-block:: sql + .. code-block:: sql SET SESSION "sql_seq_scan" = true; @@ -174,17 +181,14 @@ Retrieve the 4 rows in the table, in descending order by ``column2``, then ``*`` is short for "all columns". -.. code-block:: sql +.. code-block:: sql SELECT * FROM SEQSCAN table2 ORDER BY column2 DESC, column4 ASC; -.. important:: - - Tarantool has its own The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [1, 'CD', ' ', 10000] - [1, 'AB', 'AB', 5.5] @@ -196,14 +200,13 @@ SELECT with WHERE clauses Retrieve some of what you inserted: -* The first statement uses - the ``LIKE`` comparison operator which is asking +* The first statement uses the ``LIKE`` comparison operator which is asking for "first character must be 'A', the next characters can be anything." -* The second statement uses logical operators and parentheses, - so the ANDed expressions must be true, or the ORed expression - must be true. Notice the columns don't have to be indexed. -.. code-block:: sql +* The second statement uses logical operators and parentheses, so the ``AND`` expressions must be true, or the ``OR`` + expression must be true. Notice the columns don't have to be indexed. + +.. code-block:: sql SELECT column1, column2, column1 * column4 FROM SEQSCAN table2 WHERE column2 LIKE 'A%'; @@ -211,16 +214,16 @@ Retrieve some of what you inserted: WHERE (column1 < 2 AND column4 < 10) OR column3 = X'2020'; -The results are: +The first result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [1, 'AB', 5.5] - [2, 'AB', 24.69134] -and +The second result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [-1000, '', '', 0] - [1, 'AB', 'AB', 5.5] @@ -232,10 +235,10 @@ SELECT with GROUP BY and aggregate functions Retrieve with grouping. -The rows which have the same values for ``column2`` are grouped and are aggregated +The rows that have the same values for ``column2`` are grouped and are aggregated -- summed, counted, averaged -- for ``column4``. -.. code-block:: sql +.. code-block:: sql SELECT column2, SUM(column4), COUNT(column4), AVG(column4) FROM SEQSCAN table2 @@ -243,7 +246,7 @@ The rows which have the same values for ``column2`` are grouped and are aggregat The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - ['', 0, 1, 0] - ['AB', 17.84567, 2, 8.922835] @@ -262,7 +265,7 @@ Insert rows that contain ``NULL`` values. ``NULL`` is not the same as Lua ``nil``; it commonly is used in SQL for unknown or not-applicable. -.. code-block:: sql +.. code-block:: sql INSERT INTO table2 VALUES (1, NULL, X'4142', 5.5); INSERT INTO table2 VALUES (0, '!!@', NULL, NULL); @@ -270,10 +273,11 @@ or not-applicable. The results are: -* The first ``INSERT`` fails because ``NULL`` is not - permitted for a column that was defined with a - ``PRIMARY KEY`` clause. -* The other ``INSERT`` statements succeed. +* The first ``INSERT`` fails because ``NULL`` is not + permitted for a column that was defined with a + ``PRIMARY KEY`` clause. + +* The other ``INSERT`` statements succeed. Indexes ~~~~~~~ @@ -285,7 +289,7 @@ faster. In this case, the index also acts as a constraint, because it prevents two rows from having the same values in ``column4``. However, it is not an error that ``column4`` has multiple occurrences of NULLs. -.. code-block:: sql +.. code-block:: sql CREATE UNIQUE INDEX i ON table2 (column4); @@ -300,7 +304,7 @@ and a subset of the ``table2`` rows. You can do this by combining ``INSERT`` with ``SELECT``. Then select everything from the result table. -.. code-block:: sql +.. code-block:: sql CREATE TABLE table3 (column1 INTEGER, column2 VARCHAR(100), PRIMARY KEY (column2)); @@ -309,7 +313,7 @@ from the result table. The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [-1000, ''] - [0, '!!!'] @@ -325,7 +329,7 @@ A subquery is a query within a query. Find all the rows in ``table2`` whose ``(column1, column2)`` values are not present in ``table3``. -.. code-block:: sql +.. code-block:: sql SELECT * FROM SEQSCAN table2 WHERE (column1, column2) NOT IN (SELECT column1, column2 FROM SEQSCAN table3); @@ -333,7 +337,7 @@ present in ``table3``. The result is the single row that was excluded when inserting the rows with the ``INSERT ... SELECT`` statement: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [2, 'AB', ' ', 12.34567] @@ -341,12 +345,12 @@ SELECT with a join ~~~~~~~~~~~~~~~~~~ A join is a combination of two tables. There is more than one way to do them in -Tarantool: "Cartesian joins", "left outer joins", and so on. +Tarantool, for example, "Cartesian joins" or "left outer joins". This example shows the most typical case, where column values from one table match column values from another table. -.. code-block:: sql +.. code-block:: sql SELECT * FROM SEQSCAN table2, table3 WHERE table2.column1 = table3.column1 AND table2.column2 = table3.column2 @@ -354,7 +358,7 @@ column values from another table. The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [0, '!!!', "\0", null, 0, '!!!'] - [0, '!!@', null, null, 0, '!!@'] @@ -362,7 +366,7 @@ The result is: - [1, 'AB', 'AB', 5.5, 1, 'AB'] - [1, 'CD', ' ', 10000, 1, 'CD'] -.. _sql_tutorial-constraints_and_foreign_keys: +.. _sql_tutorial-constraints_and_foreign_keys: Constraints and foreign keys ----------------------------- @@ -370,10 +374,10 @@ Constraints and foreign keys CREATE TABLE with a CHECK clause ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create a table which includes a constraint that there must not be any rows -containing ``13`` in ``column2``. Then try to insert such a row. +Create a table that includes a constraint -- there must not be any rows +containing ``13`` in ``column2``. After that, try to insert the following row: -.. code-block:: sql +.. code-block:: sql CREATE TABLE table4 (column1 INTEGER PRIMARY KEY, column2 INTEGER, CHECK (column2 <> 13)); @@ -385,10 +389,10 @@ Result: the insert fails, as it should, with the message CREATE TABLE with a FOREIGN KEY clause ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create a table which includes a constraint that there must not be any rows containing +Create a table that includes a constraint: there must not be any rows containing values that do not appear in ``table2``. -.. code-block:: sql +.. code-block:: sql CREATE TABLE table5 (column1 INTEGER, column2 VARCHAR(100), PRIMARY KEY (column1), @@ -400,6 +404,7 @@ Result: * The first ``INSERT`` statement succeeds because ``table3`` contains a row with ``[2, 'AB', ' ', 12.34567]``. + * The second ``INSERT`` statement, correctly, fails with the message ``Foreign key constraint ''fk_unnamed_TABLE5_1'' failed: foreign tuple was not found``. @@ -411,7 +416,7 @@ Due to earlier ``INSERT`` statements, these values are in ``column4`` of ``table Adding ``5`` to ``NULL`` results in NULL, as SQL arithmetic requires. Use ``SELECT`` to see what happened to ``column4``. -.. code-block:: sql +.. code-block:: sql UPDATE table2 SET column4 = column4 + 5 WHERE column4 <> 0; SELECT column4 FROM SEQSCAN table2 ORDER BY column4; @@ -423,7 +428,7 @@ DELETE Due to earlier ``INSERT`` statements, there are 6 rows in ``table2``: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [-1000, '', '', 0] - [0, '!!!', "\0", null] @@ -434,7 +439,7 @@ Due to earlier ``INSERT`` statements, there are 6 rows in ``table2``: Try to delete the last and first of these rows: -.. code-block:: sql +.. code-block:: sql DELETE FROM table2 WHERE column1 = 2; DELETE FROM table2 WHERE column1 = -1000; @@ -444,7 +449,9 @@ The result is: * The first ``DELETE`` statement causes an error because there's a foreign-key constraint. + * The second ``DELETE`` statement succeeds. + * The ``SELECT`` statement shows that there are 5 rows remaining. ALTER TABLE with a FOREIGN KEY clause @@ -455,7 +462,7 @@ containing values that do not appear in ``table5``. This was impossible during the ``table1`` creation because at that time ``table5`` did not exist. You can add constraints to existing tables with the ``ALTER TABLE`` statement. -.. code-block:: sql +.. code-block:: sql ALTER TABLE table1 ADD CONSTRAINT c FOREIGN KEY (column1) REFERENCES table5 (column1); @@ -512,13 +519,13 @@ in many ways. For example: * concatenate strings with the ``||`` operator * extract substrings with the ``SUBSTR`` function -.. code-block:: sql +.. code-block:: sql SELECT column2, column2 || column2, SUBSTR(column2, 2, 1) FROM SEQSCAN table2; The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - ['!!!', '!!!!!!', '!'] - ['!!@', '!!@!!@', '!'] @@ -532,16 +539,16 @@ Number operations You can also manipulate number data (usually defined with ``INTEGER`` or ``DOUBLE`` data types) in many ways. For example: -* shift left with the ``<<`` operator -* get modulo with the ``%`` operator +* shift left with the ``<<`` operator +* get modulo with the ``%`` operator -.. code-block:: sql +.. code-block:: sql SELECT column1, column1 << 1, column1 << 2, column1 % 2 FROM SEQSCAN table2; The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [0, 0, 0, 0] - [0, 0, 0, 0] @@ -588,7 +595,7 @@ in the database, their values are calculated from other tables. Create a view ``v3`` based on ``table3`` and select from it: -.. code-block:: sql +.. code-block:: sql CREATE VIEW v3 AS SELECT SUBSTR(column2,1,2), column4 FROM SEQSCAN t6 WHERE column4 >= 0; @@ -596,7 +603,7 @@ Create a view ``v3`` based on ``table3`` and select from it: The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - ['АБ', 123456.123456] - ['FA', 1e-06] @@ -610,7 +617,7 @@ temporary view that lasts for the duration of the statement. Create such a view and select from it: -.. code-block:: sql +.. code-block:: sql WITH cte AS ( SELECT SUBSTR(column2,1,2), column4 FROM SEQSCAN t6 @@ -619,7 +626,7 @@ Create such a view and select from it: The result is the same as the ``CREATE VIEW`` result: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - ['АБ', 123456.123456] - ['FA', 1e-06] @@ -632,14 +639,14 @@ Tarantool can handle statements like ``SELECT 55;`` (select without ``FROM``) like some other popular DBMSs. But it also handles the more standard statement ``VALUES (expression [, expression ...]);``. -.. code-block:: sql +.. code-block:: sql SELECT 55 * 55, 'The rain in Spain'; VALUES (55 * 55, 'The rain in Spain'); The result of both these statements is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [3025, 'The rain in Spain'] @@ -659,13 +666,13 @@ Actually, these statements select from NoSQL "system spaces". Select from ``_space`` by a table name: -.. code-block:: sql +.. code-block:: sql SELECT "id", "name", "owner", "engine" FROM "_space" WHERE "name"='TABLE3'; The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [517, 'TABLE3', 1, 'memtx'] @@ -680,21 +687,21 @@ the SQL input. Change the settings so that the console accepts statements written in Lua instead of statements written in SQL: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - tarantool> \set language lua + sql_tutorial:instance001> \set language lua box.execute() ~~~~~~~~~~~~~ You can invoke SQL statements using the Lua function ``box.execute(string)``. -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - tarantool> box.execute([[SELECT * FROM SEQSCAN table3;]]); + sql_tutorial:instance001> box.execute([[SELECT * FROM SEQSCAN table3;]]); The result is: -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - - [-1000, ''] - [0, '!!!'] @@ -712,28 +719,28 @@ The following Lua code generates one million rows with random data and inserts them into a table. Copy this code into the Tarantool console and wait a bit: -.. code-block:: lua +.. code-block:: lua box.execute("CREATE TABLE tester (s1 INT PRIMARY KEY, s2 VARCHAR(10))"); function string_function() - local random_number - local random_string - random_string = "" - for x = 1,10,1 do - random_number = math.random(65, 90) - random_string = random_string .. string.char(random_number) - end - return random_string + local random_number + local random_string + random_string = "" + for x = 1, 10, 1 do + random_number = math.random(65, 90) + random_string = random_string .. string.char(random_number) + end + return random_string end; function main_function() - local string_value, t, sql_statement - for i = 1,1000000,1 do - string_value = string_function() - sql_statement = "INSERT INTO tester VALUES (" .. i .. ",'" .. string_value .. "')" - box.execute(sql_statement) - end + local string_value, t, sql_statement + for i = 1, 1000000, 1 do + string_value = string_function() + sql_statement = "INSERT INTO tester VALUES (" .. i .. ",'" .. string_value .. "')" + box.execute(sql_statement) + end end; start_time = os.clock(); main_function(); @@ -741,7 +748,7 @@ a bit: print('insert done in ' .. end_time - start_time .. ' seconds'); The result is: you now have a table with a million rows, with a message saying -"``insert done in 88.570578 seconds``". +``insert done in 88.570578 seconds``. Select from a million-row table @@ -752,7 +759,7 @@ Check how ``SELECT`` works on the million-row table: * the first query goes by an index because ``s1`` is the primary key * the second query does not go by an index -.. code-block:: lua +.. code-block:: lua box.execute([[SELECT * FROM tester WHERE s1 = 73446;]]); box.execute([[SELECT * FROM SEQSCAN tester WHERE s2 LIKE 'QFML%';]]); @@ -771,17 +778,17 @@ and triggers. These statements must be entered separately. -.. code-block:: tarantoolsession +.. code-block:: tarantoolsession - tarantool> \set language sql - tarantool> DROP TABLE tester; - tarantool> DROP TABLE table1; - tarantool> DROP VIEW v3; - tarantool> DROP TRIGGER tr; - tarantool> DROP TABLE table5; - tarantool> DROP TABLE table4; - tarantool> DROP TABLE table3; - tarantool> DROP TABLE table2; - tarantool> DROP TABLE t6; - tarantool> \set language lua - tarantool> os.exit(); + sql_tutorial:instance001> \set language sql + sql_tutorial:instance001> DROP TABLE tester; + sql_tutorial:instance001> DROP TABLE table1; + sql_tutorial:instance001> DROP VIEW v3; + sql_tutorial:instance001> DROP TRIGGER tr; + sql_tutorial:instance001> DROP TABLE table5; + sql_tutorial:instance001> DROP TABLE table4; + sql_tutorial:instance001> DROP TABLE table3; + sql_tutorial:instance001> DROP TABLE table2; + sql_tutorial:instance001> DROP TABLE t6; + sql_tutorial:instance001> \set language lua + sql_tutorial:instance001> os.exit(); diff --git a/doc/enterprise/tuple_compression.rst b/doc/platform/ddl_dml/tuple_compression.rst similarity index 97% rename from doc/enterprise/tuple_compression.rst rename to doc/platform/ddl_dml/tuple_compression.rst index ec53e8114e..c8fdcae149 100644 --- a/doc/enterprise/tuple_compression.rst +++ b/doc/platform/ddl_dml/tuple_compression.rst @@ -3,6 +3,11 @@ Tuple compression ================= +.. admonition:: Enterprise Edition + :class: fact + + Tuple compression is available in the `Enterprise Edition `_ only. + Tuple compression, introduced in Tarantool Enterprise Edition 2.10.0, aims to save memory space. Typically, it decreases the volume of stored data by 15%. However, the exact volume saved depends on the type of data. @@ -173,11 +178,3 @@ Performance is measured in requests per second. - 325k - 107k - 20,768,548 - - - -.. toctree:: - :maxdepth: 2 - :hidden: - - tuple_compression/api/compress diff --git a/doc/how-to/db/indexes.rst b/doc/platform/ddl_dml/using_indexes.rst similarity index 100% rename from doc/how-to/db/indexes.rst rename to doc/platform/ddl_dml/using_indexes.rst diff --git a/doc/concepts/data_model/value_store.rst b/doc/platform/ddl_dml/value_store.rst similarity index 85% rename from doc/concepts/data_model/value_store.rst rename to doc/platform/ddl_dml/value_store.rst index 1419f36c58..3060f3dec9 100644 --- a/doc/concepts/data_model/value_store.rst +++ b/doc/platform/ddl_dml/value_store.rst @@ -345,9 +345,8 @@ bin *** A bin (binary) value is not directly supported by Lua but there is -a Tarantool type ``varbinary`` which is encoded as MsgPack binary. -For an (advanced) example showing how to insert varbinary into a database, -see the Cookbook Recipe for :ref:`ffi_varbinary_insert `. +a Tarantool type ``varbinary``. See the :ref:`varbinary module reference ` +for details. **Example:** ``"\65 \66 \67"``. @@ -562,6 +561,120 @@ Charts explaining the precise differences from DUCET order are in the `Common Language Data Repository `_. + +.. _index-defaults: + +Default values +-------------- + +*Default values* are assigned to tuple fields automatically if these fields are +skipped during the tuple :ref:`insert or update `. + +You can specify a default value for a field in the :ref:`space_object:format() ` +call that defines the space format. Default values apply regardless of the field nullability: +any tuple in which the field is skipped or set to `nil` receives +the default value. + +Default values can be set in two ways: explicitly or using a function. + +.. _index-defaults-explicit: + +Explicit default values +~~~~~~~~~~~~~~~~~~~~~~~ + +Explicit default values are defined in the ``default`` parameter of the field declaration +in a :ref:`space_object:format() ` call. + +.. literalinclude:: /code_snippets/test/default_values/explicit_default_test.lua + :language: lua + :start-after: configure_space_start + :end-before: configure_space_end + :dedent: + +To use a default value for a field, skip it or assign `nil`: + +.. literalinclude:: /code_snippets/test/default_values/explicit_default_test.lua + :language: lua + :start-after: insert_ok_start + :end-before: insert_ok_end + :dedent: + +Any Lua object that can be evaluated during the ``space_object.format()`` call +may be used as a default value, for example: + +- a constant: ``default = 100`` +- an initialized variable: ``default = default_size`` +- an expression: ``default = 10 + default_size`` +- a function return value: ``default = count_default()`` + +.. important:: + + Explicit default values are evaluated **only** when setting the space format. + If you use a variable as a default value, its further assignments do not affect the default value. + + To change the default values, call ``space_object:format()`` again. + + +See also the :ref:`space_object:format() ` reference. + +.. _index-defaults-functions: + +Default functions +~~~~~~~~~~~~~~~~~ + +A default value can be defined as a return value of a stored Lua function. To be +the default, a function must be created with :ref:`box.schema.func.create() ` +with the function body and return one value of the field's type. It also must not :ref:`yield `. + +.. literalinclude:: /code_snippets/test/default_values/default_functions_test.lua + :language: lua + :start-after: create_no_arg_function_start + :end-before: create_no_arg_function_end + :dedent: + +Default functions are set in the ``default_func`` parameter of the field declaration +in a ``space_object:format()`` call. To make a function with no arguments the default +for a field, specify its name: + +.. literalinclude:: /code_snippets/test/default_values/default_functions_test.lua + :language: lua + :start-after: format_space_default_func_start + :end-before: format_space_default_func_end + :dedent: + +A default function can also have one argument. + +.. literalinclude:: /code_snippets/test/default_values/default_functions_test.lua + :language: lua + :start-after: create_arg_function_start + :end-before: create_arg_function_end + :dedent: + +To pass the function argument when setting the default, specify it in the ``default`` parameter +of the ``space_object:format()`` call: + +.. literalinclude:: /code_snippets/test/default_values/default_functions_test.lua + :language: lua + :start-after: reformat_space_start + :end-before: reformat_space_end + :dedent: + + +.. note:: + + A key difference between a default function (``default_func = 'count_default'``) + and a function return value used as a field default value (``default = count_default()``) + is the following: + + - A *default function* is called **every time a default value must be produced**, + that is, a tuple is inserted or updated without specifying the field. + - A return value used a field *default value*: the function is called **once** + when setting the space format. Then, all tuples receive the result of + this exact call if the field is not specified. + +See also the :ref:`space_object.format() ` reference. + + .. _index-constraints: Constraints @@ -762,3 +875,10 @@ you will get an error. Renaming parent spaces or referenced fields may break the corresponding foreign keys and prevent further insertions or modifications in the child spaces. + +.. toctree:: + :hidden: + + indexes + using_indexes + tuple_compression diff --git a/doc/concepts/engines/index.rst b/doc/platform/engines/index.rst similarity index 100% rename from doc/concepts/engines/index.rst rename to doc/platform/engines/index.rst diff --git a/doc/platform/engines/memtx.rst b/doc/platform/engines/memtx.rst new file mode 100644 index 0000000000..d0e2b63e1d --- /dev/null +++ b/doc/platform/engines/memtx.rst @@ -0,0 +1,167 @@ +.. _engines-memtx: + +Storing data with memtx +======================= + +The ``memtx`` storage engine is used in Tarantool by default. +The engine keeps all data in random-access memory (RAM), and therefore has a low read latency. + +Tarantool prevents the data loss in case of emergency, such as outage or Tarantool instance failure, in the following ways: + +* Tarantool persists all data changes by writing requests to the :ref:`write-ahead log ` (WAL) + that is stored on disk. Also, Tarantool periodically takes the entire + :doc:`database snapshot ` and saves it on disk. + Learn more: :ref:`Data persistence `. + +* In case of a distributed application, a synchronous replication is used to ensure keeping the data consistent on a quorum of replicas. + Although replication is not directly a storage engine topic, it is a part of the answer regarding data safety. + Learn more: :ref:`Replicating data `. + +In this section, the following topics are discussed in brief with the references to other sections that explain the +subject matter in details. + +.. contents:: + :local: + :depth: 1 + +.. _memtx-memory: + +Memory model +------------ + +There is a fixed number of independent :ref:`execution threads `. +The threads don't share state. Instead they exchange data using low-overhead message queues. +While this approach limits the number of cores that the instance uses, +it removes competition for the memory bus and ensures peak scalability of memory access and network throughput. + +Only one thread, namely, the **transaction processor thread** (further, **TX thread**) +can access the database, and there is only one TX thread for each Tarantool instance. +In this thread, transactions are executed in a strictly consecutive order. +Multi-statement transactions exist to provide isolation: +each transaction sees a consistent database state and commits all its changes atomically. +At commit time, a yield happens and all transaction changes are written to :ref:`WAL ` +in a single batch. +In case of errors during transaction execution, a transaction is rolled-back completely. +Read more in the following sections: :ref:`transaction_model`, :ref:`txn_mode_transaction-manager`. + +Within the TX thread, there is a memory area allocated for Tarantool to store data. It's called **Arena**. + +.. image:: memtx/arena2.svg + +Data is stored in :term:`spaces `. Spaces contain database records -- :term:`tuples `. +To access and manipulate the data stored in spaces and tuples, Tarantool builds :ref:`indexes `. + +Special `allocators `__ manage memory allocations for spaces, tuples, and indexes within the Arena. +The slab allocator is the main allocator used to store tuples. +Tarantool has a built-in module called ``box.slab`` which provides the slab allocator statistics +that can be used to monitor the total memory usage and memory fragmentation. +For more details, see the ``box.slab`` module :doc:`reference `. + +.. image:: memtx/spaces_indexes.svg + +Also inside the TX thread, there is an event loop. Within the event loop, there are a number of :ref:`fibers `. +Fibers are cooperative primitives that allow interaction with spaces, that is, reading and writing the data. +Fibers can interact with the event loop and between each other directly or by using special primitives called channels. +Due to the usage of fibers and :ref:`cooperative multitasking `, the ``memtx`` engine is lock-free in typical situations. + +.. image:: memtx/fibers-channels.svg + +To interact with external users, there is a separate :ref:`network thread ` also called the **iproto thread**. +The iproto thread receives a request from the network, parses and checks the statement, +and transforms it into a special structure—a message containing an executable statement and its options. +Then the iproto thread ships this message to the TX thread and runs the user's request in a separate fiber. + +.. image:: memtx/iproto.svg + +.. _memtx-persist: + +Data persistence +---------------- + +Tarantool ensures :ref:`data persistence ` as follows: + +* After executing data change requests in memory, Tarantool writes each such request to the :ref:`write-ahead log (WAL) ` files (``.xlog``) + that are stored on disk. Tarantool does this via a separate thread called the **WAL thread**. + +.. image:: memtx/wal.svg + +* Tarantool periodically takes the entire :doc:`database snapshot ` and saves it on disk. + It is necessary for accelerating instance's restart because when there are too many WAL files, it can be difficult for Tarantool to restart quickly. + + To save a snapshot, there is a special fiber called the :ref:`snapshot daemon `. + It reads the consistent content of the entire Arena and writes it on disk into a snapshot file (``.snap``). + Due of the cooperative multitasking, Tarantool cannot write directly on disk because it is a locking operation. + That is why Tarantool interacts with disk via a separate pool of threads from the :doc:`fio ` library. + +.. image:: memtx/snapshot03.svg + +So, even in emergency situations such as an outage or a Tarantool instance failure, +when the in-memory database is lost, the data can be restored fully during Tarantool restart. + +What happens during the restart: + +1. Tarantool finds the latest snapshot file and reads it. +2. Tarantool finds all the WAL files created after that snapshot and reads them as well. +3. When the snapshot and WAL files have been read, there is a fully recovered in-memory data set + corresponding to the state when the Tarantool instance stopped. +4. While reading the snapshot and WAL files, Tarantool is building the primary indexes. +5. When all the data is in memory again, Tarantool is building the secondary indexes. +6. Tarantool runs the application. + +.. _memtx-indexes: + +Accessing data +-------------- + +To access and manipulate the data stored in memory, Tarantool builds indexes. +Indexes are also stored in memory within the Arena. + +Tarantool supports a number of :ref:`index types ` intended for different usage scenarios. +The possible types are TREE, HASH, BITSET, and RTREE. + +Select query are possible against secondary index keys as well as primary keys. +Indexes can have multi-part keys. + +For detailed information about indexes, refer to the :ref:`concepts-data_model_indexes` page. + +.. _memtx-replication: + +Replicating data +---------------- + +Although this topic is not directly related to the ``memtx`` engine, it completes the overall picture of how Tarantool works in case of a distributed application. + +Replication allows multiple Tarantool instances to work on copies of the same database. +The copies are kept in sync because each instance can communicate its changes to all the other instances. +It is implemented via WAL replication. + +To send data to a replica, Tarantool runs another thread called **relay**. +Its purpose is to read the WAL files and send them to replicas. +On a replica, the fiber called **applier** is run. It receives the changes from a remote node and applies them to the replica's Arena. +All the changes are being written to WAL files via the replica's WAL thread as if they are done locally. + +.. image:: memtx/replica-xlogs.svg + +By default, :ref:`replication ` in Tarantool is asynchronous: if a transaction +is committed locally on a master node, it does not mean it is replicated onto any +replicas. + +:ref:`Synchronous replication ` exists to solve this problem. Synchronous transactions +are not considered committed and are not responded to a client until they are +replicated onto some number of replicas. + +For more information on replication, refer to the :ref:`corresponding chapter `. + +.. _memtx-summary: + +Summary +------- + +The main key points describing how the in-memory storage engine works can be summarized in the following way: + +* All data is in RAM. +* Access to data is from one thread. +* Tarantool writes all data change requests in WAL. +* Data snapshots are taken periodically. +* Indexes are build to access the data. +* WAL can be replicated. diff --git a/doc/concepts/engines/memtx/arena2.svg b/doc/platform/engines/memtx/arena2.svg similarity index 100% rename from doc/concepts/engines/memtx/arena2.svg rename to doc/platform/engines/memtx/arena2.svg diff --git a/doc/concepts/engines/memtx/fibers-channels.svg b/doc/platform/engines/memtx/fibers-channels.svg similarity index 100% rename from doc/concepts/engines/memtx/fibers-channels.svg rename to doc/platform/engines/memtx/fibers-channels.svg diff --git a/doc/concepts/engines/memtx/iproto.svg b/doc/platform/engines/memtx/iproto.svg similarity index 100% rename from doc/concepts/engines/memtx/iproto.svg rename to doc/platform/engines/memtx/iproto.svg diff --git a/doc/concepts/engines/memtx/replica-xlogs.svg b/doc/platform/engines/memtx/replica-xlogs.svg similarity index 100% rename from doc/concepts/engines/memtx/replica-xlogs.svg rename to doc/platform/engines/memtx/replica-xlogs.svg diff --git a/doc/concepts/engines/memtx/snapshot03.svg b/doc/platform/engines/memtx/snapshot03.svg similarity index 100% rename from doc/concepts/engines/memtx/snapshot03.svg rename to doc/platform/engines/memtx/snapshot03.svg diff --git a/doc/concepts/engines/memtx/spaces_indexes.svg b/doc/platform/engines/memtx/spaces_indexes.svg similarity index 100% rename from doc/concepts/engines/memtx/spaces_indexes.svg rename to doc/platform/engines/memtx/spaces_indexes.svg diff --git a/doc/concepts/engines/memtx/wal.svg b/doc/platform/engines/memtx/wal.svg similarity index 100% rename from doc/concepts/engines/memtx/wal.svg rename to doc/platform/engines/memtx/wal.svg diff --git a/doc/concepts/engines/memtx_vinyl_diff.rst b/doc/platform/engines/memtx_vinyl_diff.rst similarity index 100% rename from doc/concepts/engines/memtx_vinyl_diff.rst rename to doc/platform/engines/memtx_vinyl_diff.rst diff --git a/doc/concepts/engines/vinyl.rst b/doc/platform/engines/vinyl.rst similarity index 100% rename from doc/concepts/engines/vinyl.rst rename to doc/platform/engines/vinyl.rst diff --git a/doc/concepts/engines/vinyl/1.svg b/doc/platform/engines/vinyl/1.svg similarity index 100% rename from doc/concepts/engines/vinyl/1.svg rename to doc/platform/engines/vinyl/1.svg diff --git a/doc/concepts/engines/vinyl/10.svg b/doc/platform/engines/vinyl/10.svg similarity index 100% rename from doc/concepts/engines/vinyl/10.svg rename to doc/platform/engines/vinyl/10.svg diff --git a/doc/concepts/engines/vinyl/11.svg b/doc/platform/engines/vinyl/11.svg similarity index 100% rename from doc/concepts/engines/vinyl/11.svg rename to doc/platform/engines/vinyl/11.svg diff --git a/doc/concepts/engines/vinyl/12.svg b/doc/platform/engines/vinyl/12.svg similarity index 100% rename from doc/concepts/engines/vinyl/12.svg rename to doc/platform/engines/vinyl/12.svg diff --git a/doc/concepts/engines/vinyl/13.svg b/doc/platform/engines/vinyl/13.svg similarity index 100% rename from doc/concepts/engines/vinyl/13.svg rename to doc/platform/engines/vinyl/13.svg diff --git a/doc/concepts/engines/vinyl/14.svg b/doc/platform/engines/vinyl/14.svg similarity index 100% rename from doc/concepts/engines/vinyl/14.svg rename to doc/platform/engines/vinyl/14.svg diff --git a/doc/concepts/engines/vinyl/15.svg b/doc/platform/engines/vinyl/15.svg similarity index 100% rename from doc/concepts/engines/vinyl/15.svg rename to doc/platform/engines/vinyl/15.svg diff --git a/doc/concepts/engines/vinyl/16.svg b/doc/platform/engines/vinyl/16.svg similarity index 100% rename from doc/concepts/engines/vinyl/16.svg rename to doc/platform/engines/vinyl/16.svg diff --git a/doc/concepts/engines/vinyl/17.svg b/doc/platform/engines/vinyl/17.svg similarity index 100% rename from doc/concepts/engines/vinyl/17.svg rename to doc/platform/engines/vinyl/17.svg diff --git a/doc/concepts/engines/vinyl/2.svg b/doc/platform/engines/vinyl/2.svg similarity index 100% rename from doc/concepts/engines/vinyl/2.svg rename to doc/platform/engines/vinyl/2.svg diff --git a/doc/concepts/engines/vinyl/3.svg b/doc/platform/engines/vinyl/3.svg similarity index 100% rename from doc/concepts/engines/vinyl/3.svg rename to doc/platform/engines/vinyl/3.svg diff --git a/doc/concepts/engines/vinyl/4.svg b/doc/platform/engines/vinyl/4.svg similarity index 100% rename from doc/concepts/engines/vinyl/4.svg rename to doc/platform/engines/vinyl/4.svg diff --git a/doc/concepts/engines/vinyl/5.svg b/doc/platform/engines/vinyl/5.svg similarity index 100% rename from doc/concepts/engines/vinyl/5.svg rename to doc/platform/engines/vinyl/5.svg diff --git a/doc/concepts/engines/vinyl/6.svg b/doc/platform/engines/vinyl/6.svg similarity index 100% rename from doc/concepts/engines/vinyl/6.svg rename to doc/platform/engines/vinyl/6.svg diff --git a/doc/concepts/engines/vinyl/7.svg b/doc/platform/engines/vinyl/7.svg similarity index 100% rename from doc/concepts/engines/vinyl/7.svg rename to doc/platform/engines/vinyl/7.svg diff --git a/doc/concepts/engines/vinyl/8.svg b/doc/platform/engines/vinyl/8.svg similarity index 100% rename from doc/concepts/engines/vinyl/8.svg rename to doc/platform/engines/vinyl/8.svg diff --git a/doc/concepts/engines/vinyl/9.svg b/doc/platform/engines/vinyl/9.svg similarity index 100% rename from doc/concepts/engines/vinyl/9.svg rename to doc/platform/engines/vinyl/9.svg diff --git a/doc/concepts/engines/vinyl/actor_threads.png b/doc/platform/engines/vinyl/actor_threads.png similarity index 100% rename from doc/concepts/engines/vinyl/actor_threads.png rename to doc/platform/engines/vinyl/actor_threads.png diff --git a/doc/concepts/engines/vinyl/classical_b_tree.png b/doc/platform/engines/vinyl/classical_b_tree.png similarity index 100% rename from doc/concepts/engines/vinyl/classical_b_tree.png rename to doc/platform/engines/vinyl/classical_b_tree.png diff --git a/doc/concepts/engines/vinyl/compaction.png b/doc/platform/engines/vinyl/compaction.png similarity index 100% rename from doc/concepts/engines/vinyl/compaction.png rename to doc/platform/engines/vinyl/compaction.png diff --git a/doc/concepts/engines/vinyl/curve.png b/doc/platform/engines/vinyl/curve.png similarity index 100% rename from doc/concepts/engines/vinyl/curve.png rename to doc/platform/engines/vinyl/curve.png diff --git a/doc/concepts/engines/vinyl/deletion_1.png b/doc/platform/engines/vinyl/deletion_1.png similarity index 100% rename from doc/concepts/engines/vinyl/deletion_1.png rename to doc/platform/engines/vinyl/deletion_1.png diff --git a/doc/concepts/engines/vinyl/deletion_2.png b/doc/platform/engines/vinyl/deletion_2.png similarity index 100% rename from doc/concepts/engines/vinyl/deletion_2.png rename to doc/platform/engines/vinyl/deletion_2.png diff --git a/doc/concepts/engines/vinyl/deletion_3.png b/doc/platform/engines/vinyl/deletion_3.png similarity index 100% rename from doc/concepts/engines/vinyl/deletion_3.png rename to doc/platform/engines/vinyl/deletion_3.png diff --git a/doc/concepts/engines/vinyl/dump_from_shadow.png b/doc/platform/engines/vinyl/dump_from_shadow.png similarity index 100% rename from doc/concepts/engines/vinyl/dump_from_shadow.png rename to doc/platform/engines/vinyl/dump_from_shadow.png diff --git a/doc/concepts/engines/vinyl/dumps.png b/doc/platform/engines/vinyl/dumps.png similarity index 100% rename from doc/concepts/engines/vinyl/dumps.png rename to doc/platform/engines/vinyl/dumps.png diff --git a/doc/concepts/engines/vinyl/factor_lsm.png b/doc/platform/engines/vinyl/factor_lsm.png similarity index 100% rename from doc/concepts/engines/vinyl/factor_lsm.png rename to doc/platform/engines/vinyl/factor_lsm.png diff --git a/doc/concepts/engines/vinyl/lsm.png b/doc/platform/engines/vinyl/lsm.png similarity index 100% rename from doc/concepts/engines/vinyl/lsm.png rename to doc/platform/engines/vinyl/lsm.png diff --git a/doc/concepts/engines/vinyl/lsm_single.png b/doc/platform/engines/vinyl/lsm_single.png similarity index 100% rename from doc/concepts/engines/vinyl/lsm_single.png rename to doc/platform/engines/vinyl/lsm_single.png diff --git a/doc/concepts/engines/vinyl/purge.png b/doc/platform/engines/vinyl/purge.png similarity index 100% rename from doc/concepts/engines/vinyl/purge.png rename to doc/platform/engines/vinyl/purge.png diff --git a/doc/concepts/engines/vinyl/range_search.png b/doc/platform/engines/vinyl/range_search.png similarity index 100% rename from doc/concepts/engines/vinyl/range_search.png rename to doc/platform/engines/vinyl/range_search.png diff --git a/doc/concepts/engines/vinyl/read_speed.png b/doc/platform/engines/vinyl/read_speed.png similarity index 100% rename from doc/concepts/engines/vinyl/read_speed.png rename to doc/platform/engines/vinyl/read_speed.png diff --git a/doc/concepts/engines/vinyl/search.png b/doc/platform/engines/vinyl/search.png similarity index 100% rename from doc/concepts/engines/vinyl/search.png rename to doc/platform/engines/vinyl/search.png diff --git a/doc/concepts/engines/vinyl/secondary.png b/doc/platform/engines/vinyl/secondary.png similarity index 100% rename from doc/concepts/engines/vinyl/secondary.png rename to doc/platform/engines/vinyl/secondary.png diff --git a/doc/platform/images/yaml-annotated.png b/doc/platform/images/yaml-annotated.png new file mode 100644 index 0000000000..d4eff1e2ea Binary files /dev/null and b/doc/platform/images/yaml-annotated.png differ diff --git a/doc/platform/index.rst b/doc/platform/index.rst new file mode 100644 index 0000000000..70d6797c86 --- /dev/null +++ b/doc/platform/index.rst @@ -0,0 +1,24 @@ +.. _platform: +.. _tutorials: +.. _how-to: + +Platform +======== + +This section contains documentation for the Tarantool platform consisting of a database and an application server. + +.. toctree:: + :maxdepth: 1 + + concepts + engines/index + configuration + storage/index + ddl_dml/index + atomic + replication/index + sharding/index + connections_and_auth/index + security/index + triggers + app/index diff --git a/doc/concepts/replication/images/cascade-problem-1.svg b/doc/platform/replication/images/cascade-problem-1.svg similarity index 100% rename from doc/concepts/replication/images/cascade-problem-1.svg rename to doc/platform/replication/images/cascade-problem-1.svg diff --git a/doc/concepts/replication/images/cascade-problem-2.svg b/doc/platform/replication/images/cascade-problem-2.svg similarity index 100% rename from doc/concepts/replication/images/cascade-problem-2.svg rename to doc/platform/replication/images/cascade-problem-2.svg diff --git a/doc/concepts/replication/images/cascade-to-ring.svg b/doc/platform/replication/images/cascade-to-ring.svg similarity index 100% rename from doc/concepts/replication/images/cascade-to-ring.svg rename to doc/platform/replication/images/cascade-to-ring.svg diff --git a/doc/concepts/replication/images/mm-3m-mesh-add.svg b/doc/platform/replication/images/mm-3m-mesh-add.svg similarity index 100% rename from doc/concepts/replication/images/mm-3m-mesh-add.svg rename to doc/platform/replication/images/mm-3m-mesh-add.svg diff --git a/doc/concepts/replication/images/mm-3m-mesh.svg b/doc/platform/replication/images/mm-3m-mesh.svg similarity index 100% rename from doc/concepts/replication/images/mm-3m-mesh.svg rename to doc/platform/replication/images/mm-3m-mesh.svg diff --git a/doc/concepts/replication/images/mr-1m-2r-mesh-add.svg b/doc/platform/replication/images/mr-1m-2r-mesh-add.svg similarity index 100% rename from doc/concepts/replication/images/mr-1m-2r-mesh-add.svg rename to doc/platform/replication/images/mr-1m-2r-mesh-add.svg diff --git a/doc/concepts/replication/images/mr-1m-2r-mesh.svg b/doc/platform/replication/images/mr-1m-2r-mesh.svg similarity index 100% rename from doc/concepts/replication/images/mr-1m-2r-mesh.svg rename to doc/platform/replication/images/mr-1m-2r-mesh.svg diff --git a/doc/concepts/replication/images/mr-1m-2r-oneway.svg b/doc/platform/replication/images/mr-1m-2r-oneway.svg similarity index 100% rename from doc/concepts/replication/images/mr-1m-2r-oneway.svg rename to doc/platform/replication/images/mr-1m-2r-oneway.svg diff --git a/doc/concepts/replication/images/no-cascade.svg b/doc/platform/replication/images/no-cascade.svg similarity index 100% rename from doc/concepts/replication/images/no-cascade.svg rename to doc/platform/replication/images/no-cascade.svg diff --git a/doc/concepts/replication/images/replication.svg b/doc/platform/replication/images/replication.svg similarity index 100% rename from doc/concepts/replication/images/replication.svg rename to doc/platform/replication/images/replication.svg diff --git a/doc/platform/replication/images/tarantool_supervised_failover.png b/doc/platform/replication/images/tarantool_supervised_failover.png new file mode 100644 index 0000000000..8b8d964dc9 Binary files /dev/null and b/doc/platform/replication/images/tarantool_supervised_failover.png differ diff --git a/doc/platform/replication/index.rst b/doc/platform/replication/index.rst new file mode 100644 index 0000000000..952517444c --- /dev/null +++ b/doc/platform/replication/index.rst @@ -0,0 +1,25 @@ +:noindex: +:fullwidth: + +.. _replication: + +Replication +=========== + +Replication allows multiple Tarantool instances to work on copies of the same +databases. The databases are kept in sync because each instance can communicate +its changes to all the other instances. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 1 + + repl_architecture + repl_sync + repl_leader_elect + supervised_failover + replication_tutorials/index + +For practical guides to replication, see :ref:`Replication tutorials `. +You can learn about bootstrapping a replica set, adding instances to the replica set, or removing them. diff --git a/doc/concepts/replication/repl_architecture.rst b/doc/platform/replication/repl_architecture.rst similarity index 99% rename from doc/concepts/replication/repl_architecture.rst rename to doc/platform/replication/repl_architecture.rst index ed8850816e..a5c1453167 100644 --- a/doc/concepts/replication/repl_architecture.rst +++ b/doc/platform/replication/repl_architecture.rst @@ -47,7 +47,7 @@ The following are specifics of adding different types of information to the WAL: * Data change operations on **replication-local** spaces (:doc:`created ` with ``is_local = true``) are written to the WAL but are not replicated. -To learn how to enable replication, check the :ref:`Bootstrapping a replica set ` guide. +To learn how to enable replication, check the :ref:`Bootstrapping a replica set ` guide. .. _replication_stages: diff --git a/doc/platform/replication/repl_leader_elect.rst b/doc/platform/replication/repl_leader_elect.rst new file mode 100644 index 0000000000..b6bc31d08c --- /dev/null +++ b/doc/platform/replication/repl_leader_elect.rst @@ -0,0 +1,253 @@ +.. _repl_leader_elect: + +Automated leader election +========================= + +Starting from version :doc:`2.6.1 `, +Tarantool has the built-in functionality +managing automated *leader election* in a replica set. +This functionality increases the fault tolerance of the systems built +on the base of Tarantool and decreases +dependency on external tools for replica set management. + +To learn how to configure and monitor automated leader elections, +check :ref:`Managing leader elections `. + +The following topics are described below: + +.. contents:: + :local: + :depth: 1 + +.. _repl_leader_elect_and_sync_repl: + +Leader election and synchronous replication +------------------------------------------- + +Leader election and synchronous replication are implemented in Tarantool as +a modification of the `Raft `__ +algorithm. +Raft is an algorithm of synchronous replication and automatic leader election. +Its complete description can be found in the `corresponding document `_. + +In Tarantool, :ref:`synchronous replication ` and leader election +are supported as two separate subsystems. +So it is possible to get synchronous replication +but use an alternative algorithm for leader election. +And vice versa -- elect a leader +in the cluster but don't use synchronous spaces at all. +Synchronous replication has a separate :ref:`documentation section `. +Leader election is described below. + +.. note:: + + The system behavior can be specified exactly according to the Raft algorithm. To do this: + + * Ensure that the user has only synchronous spaces. + * Set the :ref:`replication.synchro_quorum ` option to ``N / 2 + 1``. + * Set the :ref:`replication.synchro_timeout ` option to infinity. + * In the :ref:`replication.election_fencing_mode ` option, select either the ``soft`` mode (the default) + or the ``strict`` mode, which is more restrictive. + +.. _repl_leader_elect_process: + +Leader election process +----------------------- + +Automated leader election in Tarantool helps guarantee that +there is at most one leader at any given moment of time in a replica set. +A *leader* is a writable node, and all other nodes are non-writable -- +they accept read-only requests exclusively. + +When :ref:`the election is enabled `, the life cycle of +a replica set is divided into so-called +*terms*. Each term is described by a monotonically growing number. +After the first boot, each node has its term equal to 1. When a node sees that +it is not a leader and there is no leader available for some time in the replica +set, it increases the term and starts a new leader election round. + +Leader election happens via votes. The node that started the election votes +for itself and sends vote requests to other nodes. +Upon receiving vote requests, a node votes for the first of them, and then cannot +do anything in the same term but wait for a leader to be elected. + +The node that collected a quorum of votes defined by the :ref:`replication.synchro_quorum ` parameter +becomes the leader +and notifies other nodes about that. Also, a split vote can happen +when no nodes received a quorum of votes. In this case, +after a random timeout, +each node increases its term and starts a new election round if no new vote +request with a greater term arrives during this time. +Eventually, a leader is elected. + +If any unfinalized synchronous transactions are left from the previous leader, +the new leader finalizes them automatically. + +All the non-leader nodes are called *followers*. The nodes that start a new +election round are called *candidates*. The elected leader sends heartbeats to +the non-leader nodes to let them know it is alive. + +In case there are no heartbeats for the period of :ref:`replication.timeout ` * 4, +a non-leader node starts a new election if the following conditions are met: + +* The node has a quorum of connections to other cluster members. +* None of these cluster members can see the leader node. + +.. note:: + + A cluster member considers the leader node to be alive if the member received heartbeats from the leader at least + once during the ``replication.timeout * 4``, + and there are no replication errors (the connection is not broken due to timeout or due to an error). + +Terms and votes are persisted by each instance to preserve certain Raft guarantees. + +During the election, the nodes prefer to vote for those ones that have the +newest data. So as if an old leader managed to send something before its death +to a quorum of replicas, that data wouldn't be lost. + +When election is enabled, there must be connections +between each node pair so as it would be the full mesh topology. This is needed +because election messages for voting and other internal things need a direct +connection between the nodes. + +.. _repl_leader_elect_fencing: + +In the classic Raft algorithm, a leader doesn't track its connectivity to the rest of the cluster. +Once the leader is elected, it considers itself in the leader position until receiving a new term from another cluster node. +This can lead to a split situation if the other nodes elect a new leader upon losing the connectivity to the previous one. + +The issue is resolved in Tarantool version :doc:`2.10.0 ` by introducing the leader *fencing* mode. +The mode can be switched by the :ref:`replication.election_fencing_mode ` configuration parameter. +When the fencing is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than +:ref:`replication.synchro_quorum ` of alive connections to the cluster nodes. +The resigning leader receives the status of a follower in the current election term and becomes read-only. +Leader *fencing* can be turned off by setting the :ref:`replication.election_fencing_mode ` configuration parameter to ``off``. + +In ``soft`` mode, a connection is considered dead if there are no responses for +:ref:`4 * replication.timeout ` seconds both on the current leader and the followers. + +In ``strict`` mode, a connection is considered dead if there are no responses +for :ref:`2 * replication.timeout ` seconds on the current leader and for +:ref:`4 * replication.timeout ` seconds on the followers. +This improves chances that there is only one leader at any time. + +Fencing applies to the instances that have the :ref:`replication.election_mode ` set to "candidate" or "manual". + +.. _repl_leader_elect_splitbrain: + +There can still be a situation when a replica set has two leaders working independently (so-called *split-brain*). +It can happen, for example, if a user mistakenly lowered the :ref:`replication.synchro_quorum ` below ``N / 2 + 1``. +In this situation, to preserve the data integrity, if an instance detects the split-brain anomaly in the incoming replication data, +it breaks the connection with the instance sending the data and writes the ``ER_SPLIT_BRAIN`` error in the log. + +Eventually, there will be two sets of nodes with the diverged data, +and any node from one set is disconnected from any node from the other set with the ``ER_SPLIT_BRAIN`` error. + +Once noticing the error, a user can choose any representative from each of the sets and inspect the data on them. +To correlate the data, the user should remove it from the nodes of one set, +and reconnect them to the nodes from the other set that have the correct data. + +Also, if election is enabled on the node, it doesn't replicate from any nodes except +the newest leader. This is done to avoid the issue when a new leader is elected, +but the old leader has somehow survived and tries to send more changes +to the other nodes. + +Term numbers also work as a kind of filter. +For example, if election is enabled on two nodes and ``node1`` has the term number less than ``node2``, +then ``node2`` doesn't accept any transactions from ``node1``. + + +.. _how-to-repl_leader_elect: + +Managing leader elections +------------------------- + +.. _repl_leader_elect_config: + +Configuration +~~~~~~~~~~~~~ + +.. code-block:: yaml + + replication: + election_mode: + election_fencing_mode: + election_timeout: + timeout: + synchro_quorum: + + +* :ref:`replication.election_mode ` -- specifies the role of a node in the leader election + process. +* :ref:`replication.election_fencing_mode ` -- specifies the :ref:`leader fencing mode `. +* :ref:`replication.election_timeout ` -- specifies the timeout between election rounds if the + previous round ended up with a split vote. +* :ref:`replication.timeout ` -- a time interval (in seconds) used by a master to send heartbeat requests to a replica when there are no updates to send to this replica. +* :ref:`replication.synchro_quorum ` -- a number of replicas that should confirm the receipt of a :ref:`synchronous ` transaction before it can finish its commit. + +It is important to know that being a leader is not the only requirement for a node to be writable. +The leader should also satisfy the following requirements: + +* The :ref:`database.mode ` option is set to ``rw``. + +* The leader shouldn't be in the orphan state. + +Nothing prevents you from setting the ``database.mode`` option to ``ro``, +but the leader won't be writable then. The option doesn't affect the +election process itself, so a read-only instance can still vote and become +a leader. + +.. _repl_leader_elect_monitoring: + +Monitoring +~~~~~~~~~~ + +To monitor the current state of a node regarding the leader election, use the :doc:`box.info.election ` function. + +**Example:** + +.. code-block:: console + + tarantool> box.info.election + --- + - state: follower + vote: 0 + leader: 0 + term: 1 + ... + +The Raft-based election implementation logs all its actions +with the ``RAFT:`` prefix. The actions are new Raft message handling, +node state changing, voting, and term bumping. + +.. _repl_leader_elect_important: + +Important notes +~~~~~~~~~~~~~~~ + +Leader election doesn't work correctly if the election quorum is set to less or equal +than `` / 2``. In that case, a split vote can lead to +a state when two leaders are elected at once. + +For example, suppose there are five nodes. When the quorum is set to ``2``, ``node1`` +and ``node2`` can both vote for ``node1``. ``node3`` and ``node4`` can both vote +for ``node5``. In this case, ``node1`` and ``node5`` both win the election. +When the quorum is set to the cluster majority, that is +``( / 2) + 1`` or greater, the split vote is impossible. + +That should be considered when adding new nodes. +If the majority value is changing, it's better to update the quorum on all the existing nodes +before adding a new one. + +Also, the automated leader election doesn't bring many benefits in terms of data +safety when used *without* :ref:`synchronous replication `. +If the replication is asynchronous and a new leader gets elected, +the old leader is still active and considers itself the leader. +In such case, nothing stops +it from accepting requests from clients and making transactions. +Non-synchronous transactions are successfully committed because +they are not checked against the quorum of replicas. +Synchronous transactions fail because they are not able +to collect the quorum -- most of the replicas reject +these old leader's transactions since it is not a leader anymore. + diff --git a/doc/platform/replication/repl_sync.rst b/doc/platform/replication/repl_sync.rst new file mode 100644 index 0000000000..21a70d414e --- /dev/null +++ b/doc/platform/replication/repl_sync.rst @@ -0,0 +1,82 @@ +.. _repl_sync: + +Synchronous replication +======================= + +Overview +-------- + +By default, replication in Tarantool is **asynchronous**: if a transaction +is committed locally on a master node, it does not mean it is replicated onto any +replicas. If a master responds success to a client and then dies, after failover +to a replica, from the client's point of view the transaction will disappear. + +**Synchronous** replication exists to solve this problem. Synchronous transactions +are not considered committed and are not responded to a client until they are +replicated onto some number of replicas. + +To enable synchronous replication, use the :ref:`space_opts.is_sync ` option when creating or altering a space. + +Synchronous and asynchronous transactions +----------------------------------------- + +A killer feature of Tarantool's synchronous replication is its being *per-space*. +So, if you need it only rarely for some critical data changes, you won't pay for +it in performance terms. + +When there is more than one synchronous transaction, they all wait for being +replicated. Moreover, if an asynchronous transaction appears, it will +also be blocked by the existing synchronous transactions. This behavior is very +similar to a regular queue of asynchronous transactions because all the transactions +are committed in the same order as they make the :ref:`box.commit() ` call. +So, here comes **the commit rule**: +transactions are committed in the same order as they make +the ``box.commit()`` call -- regardless of being synchronous or asynchronous. + +If one of the waiting synchronous transactions times out and is rolled back, it +will first roll back all the newer pending transactions. Again, just like how +asynchronous transactions are rolled back when WAL write fails. +So, here comes **the rollback rule:** +transactions are always rolled back in the order reversed from the one they +make the ``box.commit()`` call -- regardless of being synchronous or asynchronous. + +One more important thing is that if an asynchronous transaction is blocked by +a synchronous transaction, it does not become synchronous as well. +This just means it will wait for the synchronous transaction to be committed. +But once it is done, the asynchronous transaction will be committed +immediately -- it won't wait for being replicated itself. + +.. warning:: + + Be careful when using synchronous and asynchronous transactions together. + Asynchronous transactions are considered committed even if there is no connection to other nodes. + Therefore, an old leader node (:ref:`synchronous transaction queue owner `) might have some + committed asynchronous transactions that no other replica set member has. + + When the connection to such an old (previous) leader node is restored, it starts receiving data from the new leader. + At the same time, other replica set members receive the data from the previous leader that they don't have yet. + The data from the previous leader contains some committed asynchronous transactions. + At this time, the integrity protection will throw + the :ref:`ER_SPLIT_BRAIN ` error, which will force the user to rebootstrap the previous leader. + + +Limitations and known problems +------------------------------ + +Until version :doc:`2.5.2 `, +there was no way to enable synchronous replication for +existing spaces, but since 2.5.2 it can be enabled by +:ref:`space_object:alter({is_sync = true}) `. + +Synchronous transactions work only for master-slave topology. You can have multiple +replicas, anonymous replicas, but only one node can make synchronous transactions. + +Since Tarantool :doc:`2.10.0 `, anonymous replicas do not participate in the quorum. + +Leader election +--------------- + +Starting from version :doc:`2.6.1 `, +Tarantool has the built-in functionality +managing automated leader election in a replica set. For more information, +refer to the :ref:`corresponding chapter `. diff --git a/doc/platform/replication/replication_tutorials/box_info_replication_instance002_disconnected.png b/doc/platform/replication/replication_tutorials/box_info_replication_instance002_disconnected.png new file mode 100644 index 0000000000..06100f20b6 Binary files /dev/null and b/doc/platform/replication/replication_tutorials/box_info_replication_instance002_disconnected.png differ diff --git a/doc/platform/replication/replication_tutorials/box_info_replication_master_master_follow_stopped.png b/doc/platform/replication/replication_tutorials/box_info_replication_master_master_follow_stopped.png new file mode 100644 index 0000000000..bd0117b654 Binary files /dev/null and b/doc/platform/replication/replication_tutorials/box_info_replication_master_master_follow_stopped.png differ diff --git a/doc/platform/replication/replication_tutorials/box_info_replication_master_master_stopped.png b/doc/platform/replication/replication_tutorials/box_info_replication_master_master_stopped.png new file mode 100644 index 0000000000..035f86e914 Binary files /dev/null and b/doc/platform/replication/replication_tutorials/box_info_replication_master_master_stopped.png differ diff --git a/doc/platform/replication/replication_tutorials/index.rst b/doc/platform/replication/replication_tutorials/index.rst new file mode 100644 index 0000000000..26f9531ad5 --- /dev/null +++ b/doc/platform/replication/replication_tutorials/index.rst @@ -0,0 +1,13 @@ +.. _how-to-replication: +.. _replication-setup: + +Replication tutorials +===================== + +.. toctree:: + :maxdepth: 1 + + repl_bootstrap + repl_bootstrap_auto + repl_bootstrap_master_master + \ No newline at end of file diff --git a/doc/how-to/replication/mm-2m-mesh.png b/doc/platform/replication/replication_tutorials/mm-2m-mesh.png similarity index 100% rename from doc/how-to/replication/mm-2m-mesh.png rename to doc/platform/replication/replication_tutorials/mm-2m-mesh.png diff --git a/doc/how-to/replication/mm-2m-mesh.svg b/doc/platform/replication/replication_tutorials/mm-2m-mesh.svg similarity index 100% rename from doc/how-to/replication/mm-2m-mesh.svg rename to doc/platform/replication/replication_tutorials/mm-2m-mesh.svg diff --git a/doc/how-to/replication/mm-3m-mesh-add.png b/doc/platform/replication/replication_tutorials/mm-3m-mesh-add.png similarity index 100% rename from doc/how-to/replication/mm-3m-mesh-add.png rename to doc/platform/replication/replication_tutorials/mm-3m-mesh-add.png diff --git a/doc/how-to/replication/mr-1m-1r-twoway.png b/doc/platform/replication/replication_tutorials/mr-1m-1r-twoway.png similarity index 100% rename from doc/how-to/replication/mr-1m-1r-twoway.png rename to doc/platform/replication/replication_tutorials/mr-1m-1r-twoway.png diff --git a/doc/how-to/replication/mr-1m-1r-twoway.svg b/doc/platform/replication/replication_tutorials/mr-1m-1r-twoway.svg similarity index 100% rename from doc/how-to/replication/mr-1m-1r-twoway.svg rename to doc/platform/replication/replication_tutorials/mr-1m-1r-twoway.svg diff --git a/doc/how-to/replication/mr-1m-2r-mesh-add.png b/doc/platform/replication/replication_tutorials/mr-1m-2r-mesh-add.png similarity index 100% rename from doc/how-to/replication/mr-1m-2r-mesh-add.png rename to doc/platform/replication/replication_tutorials/mr-1m-2r-mesh-add.png diff --git a/doc/platform/replication/replication_tutorials/repl_bootstrap.rst b/doc/platform/replication/replication_tutorials/repl_bootstrap.rst new file mode 100644 index 0000000000..d3dde02549 --- /dev/null +++ b/doc/platform/replication/replication_tutorials/repl_bootstrap.rst @@ -0,0 +1,669 @@ +.. _replication-bootstrap: +.. _replication-master_replica_bootstrap: + +Master-replica: manual failover +=============================== + +**Example on GitHub**: `manual_leader `_ + +This tutorial shows how to configure and work with a replica set with manual failover. + + +.. _replication-tt-env: + +Prerequisites +------------- + +Before starting this tutorial: + +1. Install the :ref:`tt ` utility. + +2. Create a tt environment in the current directory by executing the :ref:`tt init ` command. + +3. Inside the ``instances.enabled`` directory of the created tt environment, create the ``manual_leader`` directory. + +4. Inside ``instances.enabled/manual_leader``, create the ``instances.yml`` and ``config.yaml`` files: + + - ``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml + :language: yaml + :end-at: instance002: + :dedent: + + - The ``config.yaml`` file is intended to store a :ref:`replica set configuration `. + + + +.. _replication-master_replica_configuring: + +Configuring a replica set +------------------------- + +This section describes how to configure a replica set in ``config.yaml``. + +.. _replication-master_replica_configuring_failover_mode: + +Step 1: Configuring a failover mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, set the :ref:`replication.failover ` option to ``manual``: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: replication: + :end-at: failover: manual + :dedent: + +.. _replication-master_replica_configuring_topology: + +Step 2: Defining a replica set topology +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Define a replica set topology inside the :ref:`groups ` section: + +- The :ref:`leader ` option sets ``instance001`` as a replica set leader. +- The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:3302 + :dedent: + + +.. _replication-master_replica_configuring_credentials: + +Step 3: Creating a user for replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: credentials: + :end-at: roles: [replication] + :dedent: + + +.. _replication-master_replica_configuring_advertise: + +Step 4: Specifying advertise URIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: iproto: + :end-at: login: replicator + :dedent: + +.. _replication-master_replica_configuring_result: + +Resulting configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +The resulting replica set configuration should look as follows: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :end-at: 127.0.0.1:3302 + :dedent: + + + + +.. _replication-master_replica_work: + +Working with a replica set +-------------------------- + +.. _replication-master_replica_starting: + +Starting instances +~~~~~~~~~~~~~~~~~~ + +1. After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: + + .. code-block:: console + + $ tt start manual_leader + • Starting an instance [manual_leader:instance001]... + • Starting an instance [manual_leader:instance002]... + +2. Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command: + + .. code-block:: console + + $ tt status manual_leader + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + manual_leader:instance001 RUNNING 8841 RW ready running -- + manual_leader:instance002 RUNNING 8842 RO ready running -- + + +.. _replication-master_replica_status: + +Checking a replica set status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Connect to ``instance001`` using :ref:`tt connect `: + + .. code-block:: console + + $ tt connect manual_leader:instance001 + • Connecting to the instance... + • Connected to manual_leader:instance001 + +2. Make sure that the instance is in the ``running`` state by executing :ref:`box.info.status `: + + .. code-block:: console + + manual_leader:instance001> box.info.status + --- + - running + ... + +3. Check that the instance is writable using ``box.info.ro``: + + .. code-block:: console + + manual_leader:instance001> box.info.ro + --- + - false + ... + +4. Execute ``box.info.replication`` to check a replica set status. + For ``instance002``, ``upstream.status`` and ``downstream.status`` should be ``follow``. + + .. code-block:: console + + manual_leader:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + lsn: 7 + name: instance001 + 2: + id: 2 + uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23 + lsn: 0 + upstream: + status: follow + idle: 0.3893879999996 + peer: replicator@127.0.0.1:3302 + lag: 0.00028800964355469 + name: instance002 + downstream: + status: follow + idle: 0.37777199999982 + vclock: {1: 7} + lag: 0 + ... + + To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, + refer to :ref:`Monitoring a replica set `. + + +.. _replication-master_replica_add_data: + +Adding data +~~~~~~~~~~~ + +To check that a replica (``instance002``) gets all updates from the master, follow the steps below: + +1. On ``instance001``, create a space and add data as described in :ref:`CRUD operation examples `. + +2. Open the second terminal, connect to ``instance002`` using ``tt connect``, and use the ``select`` operation to make sure data is replicated. + +3. Check that :ref:`box.info.vclock ` values are the same on both instances: + + - ``instance001``: + + .. code-block:: console + + manual_leader:instance001> box.info.vclock + --- + - {1: 21} + ... + + - ``instance002``: + + .. code-block:: console + + manual_leader:instance002> box.info.vclock + --- + - {1: 21} + ... + + .. vclock_0th_component_note_start + + .. NOTE:: + + Note that a ``vclock`` value might include the ``0`` component that is related to local space operations and might differ for different instances in a replica set. + + .. vclock_0th_component_note_end + + + +.. _replication-add_instances: + +Adding instances +---------------- + +This section describes how to add a new replica to a replica set. + +.. _replication-add_instances-update-config: + +Adding an instance to the configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Add ``instance003`` to the ``instances.yml`` file: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml + :language: yaml + :dedent: + +2. Add ``instance003`` with the specified ``iproto.listen`` option to the ``config.yaml`` file: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:3303 + :dedent: + + +.. _replication-add_instances-start-instance: + +Starting an instance +~~~~~~~~~~~~~~~~~~~~ + +1. Open the third terminal to work with a new instance. + Start ``instance003`` using ``tt start``: + + .. code-block:: console + + $ tt start manual_leader:instance003 + • Starting an instance [manual_leader:instance003]... + +2. Check a replica set status using ``tt status``: + + .. code-block:: console + + $ tt status manual_leader + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + manual_leader:instance001 RUNNING 8841 RW ready running -- + manual_leader:instance002 RUNNING 8842 RO ready running -- + manual_leader:instance003 RUNNING 8856 RO ready running -- + + +.. _replication-add_instances-reload-config: + +Reloading configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +After you added ``instance003`` to the configuration and started it, you need to reload configurations on all instances. +This is required to allow ``instance001`` and ``instance002`` to get data from the new instance in case it becomes a master. + +1. Connect to ``instance003`` using ``tt connect``: + + .. code-block:: console + + $ tt connect manual_leader:instance003 + • Connecting to the instance... + • Connected to manual_leader:instance001 + +2. Reload configurations on all three instances using the ``reload()`` function provided by the :ref:`config ` module: + + - ``instance001``: + + .. code-block:: console + + manual_leader:instance001> require('config'):reload() + --- + ... + + - ``instance002``: + + .. code-block:: console + + manual_leader:instance002> require('config'):reload() + --- + ... + + - ``instance003``: + + .. code-block:: console + + manual_leader:instance003> require('config'):reload() + --- + ... + + +3. Execute ``box.info.replication`` to check a replica set status. + Make sure that ``upstream.status`` and ``downstream.status`` are ``follow`` for ``instance003``. + + .. box_info_replication_manual_leader_start + + .. code-block:: console + + manual_leader:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + lsn: 21 + name: instance001 + 2: + id: 2 + uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23 + lsn: 0 + upstream: + status: follow + idle: 0.052655000000414 + peer: replicator@127.0.0.1:3302 + lag: 0.00010204315185547 + name: instance002 + downstream: + status: follow + idle: 0.09503500000028 + vclock: {1: 21} + lag: 0.00026917457580566 + 3: + id: 3 + uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6 + lsn: 0 + upstream: + status: follow + idle: 0.77522099999987 + peer: replicator@127.0.0.1:3303 + lag: 0.0001838207244873 + name: instance003 + downstream: + status: follow + idle: 0.33186100000012 + vclock: {1: 21} + lag: 0 + ... + + .. box_info_replication_manual_leader_end + + + +.. _replication-controlled_failover: + +Performing manual failover +-------------------------- + +This section shows how to perform manual failover and change a replica set leader. + +.. _replication-controlled_failover_read_only: + +Switching instances to read-only mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. In the ``config.yaml`` file, change the replica set leader from ``instance001`` to ``null``: + + .. code-block:: yaml + + replicaset001: + leader: null + +2. Reload configurations on all three instances using :ref:`config:reload() ` and check that instances are in read-only mode. + The example below shows how to do this for ``instance001``: + + .. code-block:: console + + manual_leader:instance001> require('config'):reload() + --- + ... + manual_leader:instance001> box.info.ro + --- + - true + ... + manual_leader:instance001> box.info.ro_reason + --- + - config + ... + + +3. Make sure that :ref:`box.info.vclock ` values are the same on all instances: + + - ``instance001``: + + .. code-block:: console + + manual_leader:instance001> box.info.vclock + --- + - {1: 21} + ... + + - ``instance002``: + + .. code-block:: console + + manual_leader:instance002> box.info.vclock + --- + - {1: 21} + ... + + + - ``instance003``: + + .. code-block:: console + + manual_leader:instance003> box.info.vclock + --- + - {1: 21} + ... + + +.. _replication-controlled_failover_new_leader: + +Configuring a new leader +~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Change a replica set leader in ``config.yaml`` to ``instance002``: + + .. code-block:: yaml + + replicaset001: + leader: instance002 + +2. Reload configuration on all instances using :ref:`config:reload() `. + +3. Make sure that ``instance002`` is a new master: + + .. code-block:: console + + manual_leader:instance002> box.info.ro + --- + - false + ... + +4. Check replication status using ``box.info.replication``. + + +.. _replication-remove_instances: + +Removing instances +------------------ + +This section describes the process of removing an instance from a replica set. + +Before removing an instance, make sure it is in read-only mode. +If the instance is a master, perform :ref:`manual failover `. + +.. _replication-remove_instances-disconnect: + +Disconnecting an instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Clear the ``iproto`` option for ``instance003`` by setting its value to ``{}``: + + .. code-block:: yaml + + instance003: + iproto: {} + +2. Reload configurations on ``instance001`` and ``instance002``: + + - ``instance001``: + + .. code-block:: console + + manual_leader:instance001> require('config'):reload() + --- + ... + + - ``instance002``: + + .. code-block:: console + + manual_leader:instance002> require('config'):reload() + --- + ... + +3. Check that the ``upstream`` section is missing for ``instance003`` by executing ``box.info.replication[3]``: + + .. code-block:: console + + manual_leader:instance001> box.info.replication[3] + --- + - id: 3 + uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6 + lsn: 0 + downstream: + status: follow + idle: 0.4588760000006 + vclock: {1: 21} + lag: 0 + name: instance003 + ... + + +.. _replication-remove_instances-stop: + +Stopping an instance +~~~~~~~~~~~~~~~~~~~~ + +1. Stop ``instance003`` using the :ref:`tt stop ` command: + + .. code-block:: console + + $ tt stop manual_leader:instance003 + • The Instance manual_leader:instance003 (PID = 15551) has been terminated. + + +2. Check that ``downstream.status`` is ``stopped`` for ``instance003``: + + .. code-block:: console + + manual_leader:instance001> box.info.replication[3] + --- + - id: 3 + uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6 + lsn: 0 + downstream: + status: stopped + message: 'unexpected EOF when reading from socket, called on fd 27, aka 127.0.0.1:3301, + peer of 127.0.0.1:54185: Broken pipe' + system_message: Broken pipe + name: instance003 + ... + + +.. _replication-remove_instances-update-config: + +Removing an instance from the configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Remove ``instance003`` from the ``instances.yml`` file: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml + :language: yaml + :end-at: instance002 + :dedent: + +2. Remove ``instance003`` from ``config.yaml``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: instances + :end-at: 127.0.0.1:3302 + :dedent: + +3. Reload configurations on ``instance001`` and ``instance002``: + + - ``instance001``: + + .. code-block:: console + + manual_leader:instance001> require('config'):reload() + --- + ... + + - ``instance002``: + + .. code-block:: console + + manual_leader:instance002> require('config'):reload() + --- + ... + + +.. _replication-remove_instances-remove_cluster: + +Removing an instance from the '_cluster' space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To remove an instance from the replica set permanently, it should be removed from the :ref:`box.space._cluster ` system space: + +1. Select all the tuples in the ``box.space._cluster`` system space: + + .. code-block:: console + + manual_leader:instance002> box.space._cluster:select{} + --- + - - [1, '9bb111c2-3ff5-36a7-00f4-2b9a573ea660', 'instance001'] + - [2, '4cfa6e3c-625e-b027-00a7-29b2f2182f23', 'instance002'] + - [3, '9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6', 'instance003'] + ... + +2. Delete a tuple corresponding to ``instance003``: + + .. code-block:: console + + manual_leader:instance002> box.space._cluster:delete(3) + --- + - [3, '9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6', 'instance003'] + ... + +3. Execute ``box.info.replication`` to check the health status: + + .. code-block:: console + + manual_leader:instance002> box.info.replication + --- + - 1: + id: 1 + uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + lsn: 21 + upstream: + status: follow + idle: 0.73316000000159 + peer: replicator@127.0.0.1:3301 + lag: 0.00016212463378906 + name: instance001 + downstream: + status: follow + idle: 0.7269320000014 + vclock: {2: 1, 1: 21} + lag: 0.00083398818969727 + 2: + id: 2 + uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23 + lsn: 1 + name: instance002 + ... diff --git a/doc/platform/replication/replication_tutorials/repl_bootstrap_auto.rst b/doc/platform/replication/replication_tutorials/repl_bootstrap_auto.rst new file mode 100644 index 0000000000..11dcba54fa --- /dev/null +++ b/doc/platform/replication/replication_tutorials/repl_bootstrap_auto.rst @@ -0,0 +1,452 @@ +.. _replication-bootstrap-auto: + +Master-replica: automated failover +================================== + +**Example on GitHub**: `auto_leader `_ + +This tutorial shows how to configure and work with a replica set with automated failover. + + +.. _replication-automated-failover-tt-env: + +Prerequisites +------------- + +Before starting this tutorial: + +1. Install the :ref:`tt ` utility. + +2. Create a tt environment in the current directory by executing the :ref:`tt init ` command. + +3. Inside the ``instances.enabled`` directory of the created tt environment, create the ``auto_leader`` directory. + +4. Inside ``instances.enabled/auto_leader``, create the ``instances.yml`` and ``config.yaml`` files: + + - ``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml + :language: yaml + :dedent: + + - The ``config.yaml`` file is intended to store a :ref:`replica set configuration `. + + + + +.. _replication-automated-failover-configure-cluster: + +Configuring a replica set +------------------------- + +This section describes how to configure a replica set in ``config.yaml``. + +.. _replication-automated-failover_configuring_failover_mode: + +Step 1: Configuring a failover mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, set the :ref:`replication.failover ` option to ``election``: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: replication: + :end-at: failover: election + :dedent: + +.. _replication-automated-failover_configuring_topology: + +Step 2: Defining a replica set topology +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Define a replica set topology inside the :ref:`groups ` section. +The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:3303 + :dedent: + + +.. _replication-automated-failover_configuring_credentials: + +Step 3: Creating a user for replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: credentials: + :end-at: roles: [replication] + :dedent: + + +.. _replication-automated-failover_configuring_advertise: + +Step 4: Specifying advertise URIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: iproto: + :end-at: login: replicator + :dedent: + +.. _replication-automated-failover_configuring_result: + +Resulting configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +The resulting replica set configuration should look as follows: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :end-at: 127.0.0.1:3303 + :dedent: + + + + +.. _replication-automated-failover-work: + +Working with a replica set +-------------------------- + +.. _replication-automated-failover-start-instances: + +Starting instances +~~~~~~~~~~~~~~~~~~ + +1. After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: + + .. code-block:: console + + $ tt start auto_leader + • Starting an instance [auto_leader:instance001]... + • Starting an instance [auto_leader:instance002]... + • Starting an instance [auto_leader:instance003]... + +2. Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command: + + .. code-block:: console + + $ tt status auto_leader + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + auto_leader:instance001 RUNNING 9170 RO ready running -- + auto_leader:instance002 RUNNING 9171 RO ready running -- + auto_leader:instance003 RUNNING 9172 RW ready running -- + + + +.. _replication-automated-failover-work-status: + +Checking a replica set status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Connect to ``instance001`` using :ref:`tt connect `: + + .. code-block:: console + + $ tt connect auto_leader:instance001 + • Connecting to the instance... + • Connected to auto_leader:instance001 + +2. Check the instance state in regard to :ref:`leader election ` using :ref:`box.info.election `. + The output below shows that ``instance001`` is a follower while ``instance002`` is a replica set leader. + + .. code-block:: console + + auto_leader:instance001> box.info.election + --- + - leader_idle: 0.77491499999815 + leader_name: instance002 + state: follower + vote: 0 + term: 2 + leader: 1 + ... + +3. Check that ``instance001`` is in read-only mode using ``box.info.ro``: + + .. code-block:: console + + auto_leader:instance001> box.info.ro + --- + - true + ... + +4. Execute ``box.info.replication`` to check a replica set status. + Make sure that ``upstream.status`` and ``downstream.status`` are ``follow`` for ``instance002`` and ``instance003``. + + .. code-block:: console + + auto_leader:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23 + lsn: 9 + upstream: + status: follow + idle: 0.8257709999998 + peer: replicator@127.0.0.1:3302 + lag: 0.00012326240539551 + name: instance002 + downstream: + status: follow + idle: 0.81174199999805 + vclock: {1: 9} + lag: 0 + 2: + id: 2 + uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + lsn: 0 + name: instance001 + 3: + id: 3 + uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6 + lsn: 0 + upstream: + status: follow + idle: 0.83125499999733 + peer: replicator@127.0.0.1:3303 + lag: 0.00010204315185547 + name: instance003 + downstream: + status: follow + idle: 0.83213399999659 + vclock: {1: 9} + lag: 0 + ... + + To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, + refer to :ref:`Monitoring a replica set `. + +.. _replication-automated-failover-add-data: + +Adding data +~~~~~~~~~~~ + +To check that replicas (``instance001`` and ``instance003``) get all updates from the master (``instance002``), follow the steps below: + +1. Connect to ``instance002`` using ``tt connect``: + + .. code-block:: console + + $ tt connect auto_leader:instance002 + • Connecting to the instance... + • Connected to auto_leader:instance002 + +2. Create a space and add data as described in :ref:`CRUD operation examples `. + +3. Use the ``select`` operation on ``instance001`` and ``instance003`` to make sure data is replicated. + +4. Check that the ``1`` component of :ref:`box.info.vclock ` values are the same on all instances: + + - ``instance001``: + + .. code-block:: console + + auto_leader:instance001> box.info.vclock + --- + - {0: 1, 1: 32} + ... + + - ``instance002``: + + .. code-block:: console + + auto_leader:instance002> box.info.vclock + --- + - {0: 1, 1: 32} + ... + + - ``instance003``: + + .. code-block:: console + + auto_leader:instance003> box.info.vclock + --- + - {0: 1, 1: 32} + ... + +.. include:: /platform/replication/replication_tutorials/repl_bootstrap.rst + :start-after: vclock_0th_component_note_start + :end-before: vclock_0th_component_note_end + + + +.. _replication-automated-failover-testing: + +Testing automated failover +-------------------------- + +To test how automated failover works if the current master is stopped, follow the steps below: + +1. Stop the current master instance (``instance002``) using the ``tt stop`` command: + + .. code-block:: console + + $ tt stop auto_leader:instance002 + • The Instance auto_leader:instance002 (PID = 24769) has been terminated. + + +2. On ``instance001``, check ``box.info.election``. + In this example, a new replica set leader is ``instance001``. + + .. code-block:: console + + auto_leader:instance001> box.info.election + --- + - leader_idle: 0 + leader_name: instance001 + state: leader + vote: 2 + term: 3 + leader: 2 + ... + +3. Check replication status using ``box.info.replication`` for ``instance002``: + + - ``upstream.status`` is ``disconnected``. + - ``downstream.status`` is ``stopped``. + + .. box_info_replication_auto_leader_disconnected_start + + .. code-block:: console + + auto_leader:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23 + lsn: 32 + upstream: + peer: replicator@127.0.0.1:3302 + lag: 0.00032305717468262 + status: disconnected + idle: 48.352504000002 + message: 'connect, called on fd 20, aka 127.0.0.1:62575: Connection refused' + system_message: Connection refused + name: instance002 + downstream: + status: stopped + message: 'unexpected EOF when reading from socket, called on fd 32, aka 127.0.0.1:3301, + peer of 127.0.0.1:62204: Broken pipe' + system_message: Broken pipe + 2: + id: 2 + uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660 + lsn: 1 + name: instance001 + 3: + id: 3 + uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6 + lsn: 0 + upstream: + status: follow + idle: 0.18620999999985 + peer: replicator@127.0.0.1:3303 + lag: 0.00012516975402832 + name: instance003 + downstream: + status: follow + idle: 0.19718099999955 + vclock: {2: 1, 1: 32} + lag: 0.00051403045654297 + ... + + .. box_info_replication_auto_leader_disconnected_end + + The diagram below illustrates how the ``upstream`` and ``downstream`` connections look like: + + .. image:: box_info_replication_instance002_disconnected.png + :width: 600 + :align: center + :alt: replication status on a new master + + +4. Start ``instance002`` back using ``tt start``: + + .. code-block:: console + + $ tt start auto_leader:instance002 + • Starting an instance [auto_leader:instance002]... + + +.. _replication-automated-failover-new-leader: + +Choosing a leader manually +-------------------------- + +1. Make sure that :ref:`box.info.vclock ` values (except the ``0`` components) are the same on all instances: + + - ``instance001``: + + .. code-block:: console + + auto_leader:instance001> box.info.vclock + --- + - {0: 2, 1: 32, 2: 1} + ... + + - ``instance002``: + + .. code-block:: console + + auto_leader:instance002> box.info.vclock + --- + - {0: 2, 1: 32, 2: 1} + ... + + + - ``instance003``: + + .. code-block:: console + + auto_leader:instance003> box.info.vclock + --- + - {0: 3, 1: 32, 2: 1} + ... + +2. On ``instance002``, run :ref:`box.ctl.promote() ` to choose it as a new replica set leader: + + .. code-block:: console + + auto_leader:instance002> box.ctl.promote() + --- + ... + +3. Check ``box.info.election`` to make sure ``instance002`` is a leader now: + + .. code-block:: console + + auto_leader:instance002> box.info.election + --- + - leader_idle: 0 + leader_name: instance002 + state: leader + vote: 1 + term: 4 + leader: 1 + ... + + + +.. _replication-automated-failover-add-remove-instances: + +Adding and removing instances +----------------------------- + +The process of adding instances to a replica set and removing them is similar for all failover modes. +Learn how to do this from the :ref:`Master-replica: manual failover ` tutorial: + +- :ref:`Adding instances ` +- :ref:`Removing instances ` + +Before removing an instance from a replica set with :ref:`replication.failover ` set to ``election``, make sure this instance is in read-only mode. +If the instance is a master, choose a :ref:`new leader manually `. diff --git a/doc/platform/replication/replication_tutorials/repl_bootstrap_master_master.rst b/doc/platform/replication/replication_tutorials/repl_bootstrap_master_master.rst new file mode 100644 index 0000000000..f369cc3687 --- /dev/null +++ b/doc/platform/replication/replication_tutorials/repl_bootstrap_master_master.rst @@ -0,0 +1,602 @@ +.. _replication-bootstrap-master-master: + +Master-master +============= + +**Example on GitHub**: `master_master `_ + +This tutorial shows how to configure and work with a master-master replica set. + + +.. _replication-master-master-tt-env: + +Prerequisites +------------- + +Before starting this tutorial: + +1. Install the :ref:`tt ` utility. + +2. Create a tt environment in the current directory by executing the :ref:`tt init ` command. + +3. Inside the ``instances.enabled`` directory of the created tt environment, create the ``master_master`` directory. + +4. Inside ``instances.enabled/master_master``, create the ``instances.yml`` and ``config.yaml`` files: + + - ``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/instances.yml + :language: yaml + :end-at: instance002: + :dedent: + + - The ``config.yaml`` file is intended to store a :ref:`replica set configuration `. + + + + +.. _replication-master-master-configure-cluster: + +Configuring a replica set +------------------------- + +This section describes how to configure a replica set in ``config.yaml``. + + +.. _replication-master-master-configure-failover_mode: + +Step 1: Configuring a failover mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, set the :ref:`replication.failover ` option to ``off``: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :start-at: replication: + :end-at: failover: off + :dedent: + + + +.. _replication-master-master-configure-topology: + +Step 2: Defining a replica set topology +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Define a replica set topology inside the :ref:`groups ` section: + +- The ``database.mode`` option should be set to ``rw`` to make instances work in read-write mode. +- The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:3302 + :dedent: + + +.. _replication-master-master-configure_credentials: + +Step 3: Creating a user for replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :start-at: credentials: + :end-at: roles: [replication] + :dedent: + + +.. _replication-master-master-configure_advertise: + +Step 4: Specifying advertise URIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :start-at: iproto: + :end-at: login: replicator + :dedent: + + +.. _replication-master-master-configure_result: + +Resulting configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +The resulting replica set configuration should look as follows: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :end-at: 127.0.0.1:3302 + :dedent: + + + + +.. _replication-master-master-work: + +Working with a replica set +-------------------------- + +.. _replication-master-master-start-instances: + +Starting instances +~~~~~~~~~~~~~~~~~~ + +1. After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `: + + .. code-block:: console + + $ tt start master_master + • Starting an instance [master_master:instance001]... + • Starting an instance [master_master:instance002]... + +2. Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command: + + .. code-block:: console + + $ tt status master_master + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + master_master:instance001 RUNNING 9263 RW ready running -- + master_master:instance002 RUNNING 9264 RW ready running -- + + +.. _replication-master-master-check-status: + +Checking a replica set status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Connect to both instances using :ref:`tt connect `. + Below is the example for ``instance001``: + + .. code-block:: console + + $ tt connect master_master:instance001 + • Connecting to the instance... + • Connected to master_master:instance001 + + master_master:instance001> + +2. Check that both instances are writable using ``box.info.ro``: + + - ``instance001``: + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.ro + --- + - false + ... + + - ``instance002``: + + .. code-block:: tarantoolsession + + master_master:instance002> box.info.ro + --- + - false + ... + +3. Execute ``box.info.replication`` to check a replica set status. + For ``instance002``, ``upstream.status`` and ``downstream.status`` should be ``follow``. + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: c3bfd89f-5a1c-4556-aa9f-461377713a2a + lsn: 7 + name: instance001 + 2: + id: 2 + uuid: dccf7485-8bff-47f6-bfc4-b311701e36ef + lsn: 0 + upstream: + status: follow + idle: 0.93246499999987 + peer: replicator@127.0.0.1:3302 + lag: 0.00016188621520996 + name: instance002 + downstream: + status: follow + idle: 0.8988360000003 + vclock: {1: 7} + lag: 0 + ... + + To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, + refer to :ref:`Monitoring a replica set `. + +.. include:: /platform/replication/replication_tutorials/repl_bootstrap.rst + :start-after: vclock_0th_component_note_start + :end-before: vclock_0th_component_note_end + + + + +.. _replication-master-master-add-data: + +Adding data +~~~~~~~~~~~ + +To check that both instances get updates from each other, follow the steps below: + +1. On ``instance001``, create a space, format it, and create a primary index: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua + :start-at: box.schema.space.create + :end-at: box.space.bands:create_index + :language: lua + :dedent: + + Then, add sample data to this space: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua + :start-at: Roxette + :end-at: Scorpions + :language: lua + :dedent: + +2. On ``instance002``, use the ``select`` operation to make sure data is replicated: + + .. code-block:: tarantoolsession + + master_master:instance002> box.space.bands:select() + --- + - - [1, 'Roxette', 1986] + - [2, 'Scorpions', 1965] + ... + +3. Add more data to the created space on ``instance002``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua + :start-at: Ace of Base + :end-at: The Beatles + :language: lua + :dedent: + +4. Get back to ``instance001`` and use ``select`` to make sure new records are replicated: + + .. code-block:: tarantoolsession + + master_master:instance001> box.space.bands:select() + --- + - - [1, 'Roxette', 1986] + - [2, 'Scorpions', 1965] + - [3, 'Ace of Base', 1987] + - [4, 'The Beatles', 1960] + ... + +5. Check that :ref:`box.info.vclock ` values are the same on both instances: + + - ``instance001``: + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.vclock + --- + - {2: 2, 1: 12} + ... + + - ``instance002``: + + .. code-block:: tarantoolsession + + master_master:instance002> box.info.vclock + --- + - {2: 2, 1: 12} + ... + + + +.. _replication-master-master-resolve-conflicts: + +Resolving replication conflicts +------------------------------- + +.. NOTE:: + + To learn how to fix and prevent replication conflicts using trigger functions, see :ref:`Resolving replication conflicts `. + +.. _replication-master-master_conflicting_records: + +Inserting conflicting records +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To insert conflicting records to ``instance001`` and ``instance002``, follow the steps below: + +1. Stop ``instance001`` using the ``tt stop`` command: + + .. code-block:: console + + $ tt stop master_master:instance001 + +2. On ``instance002``, insert a new record: + + .. code-block:: lua + + box.space.bands:insert { 5, 'incorrect data', 0 } + +3. Stop ``instance002`` using ``tt stop``: + + .. code-block:: console + + $ tt stop master_master:instance002 + +4. Start ``instance001`` back: + + .. code-block:: console + + $ tt start master_master:instance001 + +5. Connect to ``instance001`` and insert a record that should conflict with a record already inserted on ``instance002``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/myapp.lua + :start-at: Pink Floyd + :end-at: Pink Floyd + :language: lua + :dedent: + +6. Start ``instance002`` back: + + .. code-block:: console + + $ tt start master_master:instance002 + + Then, check ``box.info.replication`` on ``instance001``. + ``upstream.status`` should be ``stopped`` because of the ``Duplicate key exists`` error: + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: c3bfd89f-5a1c-4556-aa9f-461377713a2a + lsn: 13 + name: instance001 + 2: + id: 2 + uuid: dccf7485-8bff-47f6-bfc4-b311701e36ef + lsn: 2 + upstream: + peer: replicator@127.0.0.1:3302 + lag: 115.99977827072 + status: stopped + idle: 2.0342070000006 + message: Duplicate key exists in unique index "primary" in space "bands" with + old tuple - [5, "Pink Floyd", 1965] and new tuple - [5, "incorrect data", + 0] + name: instance002 + downstream: + status: stopped + message: 'unexpected EOF when reading from socket, called on fd 24, aka 127.0.0.1:3301, + peer of 127.0.0.1:58478: Broken pipe' + system_message: Broken pipe + ... + + The diagram below illustrates how the ``upstream`` and ``downstream`` connections look like: + + .. image:: box_info_replication_master_master_stopped.png + :width: 600 + :align: center + :alt: replication status on a new master + + +.. _replication-master-master-reseed-replica: + +Reseeding a replica +~~~~~~~~~~~~~~~~~~~ + +To resolve a replication conflict, ``instance002`` should get the correct data from ``instance001`` first. +To achieve this, ``instance002`` should be rebootstrapped: + +1. Select all the tuples in the :ref:`box.space._cluster ` system space to get a UUID of ``instance002``: + + .. code-block:: tarantoolsession + + master_master:instance001> box.space._cluster:select() + --- + - - [1, 'c3bfd89f-5a1c-4556-aa9f-461377713a2a', 'instance001'] + - [2, 'dccf7485-8bff-47f6-bfc4-b311701e36ef', 'instance002'] + ... + +2. In the ``config.yaml`` file, change the following ``instance002`` settings: + + * Set ``database.mode`` to ``ro``. + * Set ``database.instance_uuid`` to a UUID value obtained in the previous step. + + .. code-block:: yaml + + instance002: + database: + mode: ro + instance_uuid: 'dccf7485-8bff-47f6-bfc4-b311701e36ef' + +3. Reload configurations on both instances using the :ref:`config:reload() ` function: + + - ``instance001``: + + .. code-block:: tarantoolsession + + master_master:instance001> require('config'):reload() + --- + ... + + - ``instance002``: + + .. code-block:: tarantoolsession + + master_master:instance002> require('config'):reload() + --- + ... + +4. Delete write-ahead logs and snapshots stored in the ``var/lib/instance002`` directory. + + .. NOTE:: + + ``var/lib`` is the default directory used by tt to store write-ahead logs and snapshots. + Learn more from :ref:`Configuration `. + +5. Restart ``instance002`` using the :ref:`tt restart ` command: + + .. code-block:: console + + $ tt restart master_master:instance002 + +6. Connect to ``instance002`` and make sure it received the correct data from ``instance001``: + + .. code-block:: tarantoolsession + + master_master:instance002> box.space.bands:select() + --- + - - [1, 'Roxette', 1986] + - [2, 'Scorpions', 1965] + - [3, 'Ace of Base', 1987] + - [4, 'The Beatles', 1960] + - [5, 'Pink Floyd', 1965] + ... + + +.. _replication-master-master-resolve-conflict: + +Restarting replication +~~~~~~~~~~~~~~~~~~~~~~ + +After :ref:`reseeding a replica `, you need to resolve a replication conflict that keeps replication stopped: + +1. Execute ``box.info.replication`` on ``instance001``. + ``upstream.status`` is still stopped: + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: c3bfd89f-5a1c-4556-aa9f-461377713a2a + lsn: 13 + name: instance001 + 2: + id: 2 + uuid: dccf7485-8bff-47f6-bfc4-b311701e36ef + lsn: 2 + upstream: + peer: replicator@127.0.0.1:3302 + lag: 115.99977827072 + status: stopped + idle: 1013.688243 + message: Duplicate key exists in unique index "primary" in space "bands" with + old tuple - [5, "Pink Floyd", 1965] and new tuple - [5, "incorrect data", + 0] + name: instance002 + downstream: + status: follow + idle: 0.69694700000036 + vclock: {2: 2, 1: 13} + lag: 0 + ... + + The diagram below illustrates how the ``upstream`` and ``downstream`` connections look like: + + .. image:: box_info_replication_master_master_follow_stopped.png + :width: 600 + :align: center + :alt: replication status after reseeding a replica + + +2. In the ``config.yaml`` file, clear the ``iproto`` option for ``instance001`` by setting its value to ``{}`` to disconnect this instance from ``instance002``. + Set ``database.mode`` to ``ro``: + + .. code-block:: yaml + + instance001: + database: + mode: ro + iproto: {} + +3. Reload configuration on ``instance001`` only: + + .. code-block:: tarantoolsession + + master_master:instance001> require('config'):reload() + --- + ... + +4. Change ``database.mode`` values back to ``rw`` for both instances and restore ``iproto.listen`` for ``instance001``. + The ``database.instance_uuid`` option can be removed for ``instance002``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :start-at: instance001 + :end-at: 127.0.0.1:3302 + :dedent: + +5. Reload configurations on both instances one more time: + + - ``instance001``: + + .. code-block:: tarantoolsession + + master_master:instance001> require('config'):reload() + --- + ... + + - ``instance002``: + + .. code-block:: tarantoolsession + + master_master:instance002> require('config'):reload() + --- + ... + +6. Check ``box.info.replication``. + ``upstream.status`` should be ``follow`` now. + + .. code-block:: tarantoolsession + + master_master:instance001> box.info.replication + --- + - 1: + id: 1 + uuid: c3bfd89f-5a1c-4556-aa9f-461377713a2a + lsn: 13 + name: instance001 + 2: + id: 2 + uuid: dccf7485-8bff-47f6-bfc4-b311701e36ef + lsn: 2 + upstream: + status: follow + idle: 0.86873800000012 + peer: replicator@127.0.0.1:3302 + lag: 0.0001060962677002 + name: instance002 + downstream: + status: follow + idle: 0.058662999999797 + vclock: {2: 2, 1: 13} + lag: 0 + ... + + + +.. _replication-master-master-add-remove-instances: + +Adding and removing instances +----------------------------- + +The process of adding instances to a replica set and removing them is similar for all failover modes. +Learn how to do this from the :ref:`Master-replica: manual failover ` tutorial: + +- :ref:`Adding instances ` +- :ref:`Removing instances ` + +Before removing an instance from a replica set with :ref:`replication.failover ` set to ``off``, make sure this instance is in read-only mode. diff --git a/doc/how-to/replication/replicationX.svg b/doc/platform/replication/replication_tutorials/replicationX.svg similarity index 100% rename from doc/how-to/replication/replicationX.svg rename to doc/platform/replication/replication_tutorials/replicationX.svg diff --git a/doc/platform/replication/supervised_failover.rst b/doc/platform/replication/supervised_failover.rst new file mode 100644 index 0000000000..681827fa79 --- /dev/null +++ b/doc/platform/replication/supervised_failover.rst @@ -0,0 +1,226 @@ +.. _repl_supervised_failover: + +Supervised failover +=================== + +.. admonition:: Enterprise Edition + :class: fact + + Supervised failover is supported by the `Enterprise Edition `_ only. + +**Example on GitHub**: `supervised_failover `_ + +Tarantool provides the ability to control leadership in a replica set using an external failover coordinator. +A failover coordinator reads a cluster configuration from a file or an :ref:`etcd-based configuration storage `, polls instances for their statuses, and appoints a leader for each replica set depending on the availability and health of instances. + +To increase fault tolerance, you can run two or more failover coordinators. +In this case, an etcd cluster provides synchronization between coordinators. + +| + +.. image:: images/tarantool_supervised_failover.png + :align: left + :width: 500 + :alt: Supervised failover + +| + + +.. _supervised_failover_overview: + +Overview +-------- + +The main steps of using an external failover coordinator for a newly configured cluster might look as follows: + +1. :ref:`Configure a cluster ` to work with an external coordinator. + The main step is setting the ``replication.failover`` option to ``supervised`` for all replica sets that should be managed by the external coordinator. + +2. Start a configured cluster. + When an external coordinator is still not running, instances in a replica set start in the following modes: + + - If a replica set is already :ref:`bootstrapped `, all instances are started in read-only mode. + - If a replica set is not bootstrapped, one instance is started in read-write mode. + +3. :ref:`Start a failover coordinator `. + You can start two or more failover coordinators to increase fault tolerance. + In this case, one coordinator is active and others are passive. + +Once a cluster and failover coordinators are up and running, a failover coordinator appoints one instance to be a master if there is no master instance in a replica set. +Then, the following events may occur: + +- If a master instance fails, a failover coordinator performs an automated failover. +- If an active failover coordinator fails, another coordinator becomes active and performs an automated failover. + +.. NOTE:: + + Note that a failover coordinator doesn't work with replica sets with two or more read-write instances. + In this case, a coordinator logs a warning to stdout and doesn't perform any appointments. + + + +.. _supervised_failover_overview_appoint_master: + +Appointing a new master instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After a master instance has been appointed, a failover coordinator monitors the statuses of all instances in a replica set by sending requests each :ref:`probe_interval ` seconds. +For the master instance, the coordinator maintains a read-write mode deadline, which is renewed periodically each :ref:`renew_interval ` seconds. +If all attempts to renew the deadline fail during the specified time interval (:ref:`lease_interval `), the master switches to read-only mode. +Then, the coordinator appoints a new instance as the master. + +.. NOTE:: + + :ref:`Anonymous replicas ` are not considered as candidates to be a master. + +If a remote etcd-based storage is used to maintain the state of failover coordinators, you can also perform a :ref:`manual failover `. + + + + +.. _supervised_failover_overview_fault_tolerance: + +Active and passive coordinators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To increase fault tolerance, you can :ref:`run ` two or more failover coordinators. +In this case, only one coordinator is active and used to control leadership in a replica set. +Other coordinators are passive and don't perform any read-write appointments. + +To maintain the state of coordinators, Tarantool uses a stateboard -- a remote etcd-based storage. +This storage uses the same connection settings as a :ref:`centralized etcd-based configuration storage `. +If a cluster configuration is stored in the ``/config/*`` keys in etcd, the failover coordinator looks into ``/failover/*`` for its state. +Here are a few examples of keys used for different purposes: + +- ``/failover/info/by-uuid/``: contains a state of a failover coordinator identified by the specified ``uuid``. +- ``/failover/active/lock``: a unique identifier (UUID) of an active failover coordinator. +- ``/failover/active/term``: a kind of fencing token allowing to have an order in which coordinators become active (took the lock) over time. +- ``/failover/command/``: a key used to perform a :ref:`manual failover `. + + + +.. _supervised_failover_configuration: + +Configuring a cluster +--------------------- + +To configure a cluster to work with an external failover coordinator, follow the steps below: + +#. (Optional) If you need to run :ref:`several failover coordinators ` to increase fault tolerance, set up an etcd-based configuration storage, as described in :ref:`configuration_etcd`. + +#. Set the :ref:`replication.failover ` option to ``supervised``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml + :language: yaml + :start-at: replication: + :end-at: failover: supervised + :dedent: + +#. Grant a user used for replication :ref:`permissions ` to execute the ``failover.execute`` function: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml + :language: yaml + :start-at: credentials: + :end-at: failover.execute + :dedent: + + .. note:: + + In Tarantool 3.0 and 3.1, the configuration is different and the function + must be created in the application code. See :ref:`supervised_failover_configuration_with_role` for details. + +#. (Optional) Configure options that control how a failover coordinator operates in the :ref:`failover ` section: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml + :language: yaml + :start-after: failover: supervised + :end-before: groups + :dedent: + +You can find the full example on GitHub: `supervised_failover `_. + +.. _supervised_failover_configuration_with_role: + +Tarantool 3.0 and 3.1 configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before version 3.2, Tarantool used another mechanism to grant execute access to Lua +functions. In Tarantool 3.0 and 3.1, the ``credentials`` configuration section +should look as follows: + +.. code-block:: yaml + + # Tarantool 3.0 and 3.1 + credentials: + users: + replicator: + password: 'topsecret' + roles: [ replication ] + privileges: + - permissions: [ execute ] + functions: [ 'failover.execute' ] + +Additionally, you should create the ``failover.execute`` function in the application code. +For example, you can create a :ref:`custom role ` for this purpose: + +.. code-block:: lua + + -- Tarantool 3.0 and 3.1 -- + -- supervised_instance.lua -- + return { + validate = function() + end, + apply = function() + if box.info.ro then + return + end + local func_name = 'failover.execute' + local opts = { if_not_exists = true } + box.schema.func.create(func_name, opts) + end, + stop = function() + if box.info.ro then + return + end + local func_name = 'failover.execute' + if not box.schema.func.exists(func_name) then + return + end + box.schema.func.drop(func_name) + end, + } + +Then, enable this role for all storage instances: + +.. code-block:: yaml + + # Tarantool 3.0 and 3.1 + roles: [ 'supervised_instance' ] + +.. _supervised_failover_start_coordinator: + +Starting a failover coordinator +------------------------------- + +To start a failover coordinator, you need to execute the ``tarantool`` command with the :ref:`failover ` option. +This command accepts the path to a cluster configuration file: + +.. code-block:: console + + tarantool --failover --config instances.enabled/supervised_failover/config.yaml + +If a cluster's configuration is stored in etcd, the ``config.yaml`` file contains :ref:`connection options for the etcd storage `. + +You can run two or more failover coordinators to increase fault tolerance. +In this case, only one coordinator is active and used to control leadership in a replica set. +Learn more from :ref:`supervised_failover_overview_fault_tolerance`. + + +.. _supervised_failover_manual: + +Performing manual failover +-------------------------- + +If an etcd-based storage is used to maintain the state of failover coordinators, you can perform a manual failover. +External tools can use the ``/failover/command/`` key to choose a new master. +For example, the tt utility provides the :ref:`tt cluster failover ` command for managing a supervised failover. diff --git a/doc/enterprise/audit.rst b/doc/platform/security/audit.rst similarity index 86% rename from doc/enterprise/audit.rst rename to doc/platform/security/audit.rst index 15d26a16da..de8bed6685 100644 --- a/doc/enterprise/audit.rst +++ b/doc/platform/security/audit.rst @@ -10,7 +10,7 @@ Encryption of external iproto traffic ------------------------------------- Tarantool uses the -:doc:`iproto binary protocol ` +:ref:`iproto binary protocol ` for replicating data between instances and also in the connector libraries. Since version 2.10.0, the Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over binary connections. @@ -43,9 +43,9 @@ is not sufficiently secure. Closed HTTP ports ----------------- -Tarantool accepts HTTP connections on a specific port, configured with -``http_port: `` value -(see :ref:`configuring Cartridge instances `). +.. TODO: update for new EE config + +Tarantool accepts HTTP connections on a specific port. It must be only available on the same host for nginx to connect to it. Check that the configured HTTP port is closed @@ -103,8 +103,6 @@ Authorization in the web UI --------------------------- Using the web interface must require logging in with a username and password. -See more details in the documentation on -:ref:`configuring web interface authorization `. Running under the tarantool user -------------------------------- @@ -128,8 +126,7 @@ This should be checked on each Tarantool instance. The :ref:`snapshot_count ` value determines the number of kept snapshots. Configuration values are primarily set in the configuration files -but :doc:`can be overridden ` -with environment variables and command-line arguments. +but can be overridden with environment variables and command-line arguments. So, it's best to check both the values in the configuration files and the actual values using the console: @@ -147,21 +144,17 @@ Tarantool records all incoming data in the write-ahead log (WAL). The WAL must be enabled to ensure that data will be recovered in case of a possible instance restart. -Secure values of ``wal_mode`` are ``write`` and ``fsync``: +Secure values of the :ref:`wal.mode ` configuration option are ``write`` and ``fsync``: -.. code-block:: tarantoolsession - - tarantool> box.cfg.wal_mode - --- - - write +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: wal: + :end-at: 'write' + :dedent: An exclusion from this requirement is when the instance is processing data, -which can be freely rejected. -For example, when Tarantool is used for caching. -Then WAL can be disabled to reduce i/o load. - -For more details, see the -:ref:`wal_mode reference `. +which can be freely rejected - for example, when Tarantool is used for caching. +In this case, WAL can be disabled to reduce i/o load. The logging level is INFO or higher ----------------------------------- diff --git a/doc/platform/security/audit_log.rst b/doc/platform/security/audit_log.rst new file mode 100644 index 0000000000..44a02b2622 --- /dev/null +++ b/doc/platform/security/audit_log.rst @@ -0,0 +1,643 @@ +.. _enterprise_audit_module: + +Audit module +============ + +.. admonition:: Enterprise Edition + :class: fact + + The audit module is available in the `Enterprise Edition `_ only. + +**Example on GitHub**: `audit_log `_ + +The audit module allows you to record various events occurred in Tarantool. +Each :ref:`event ` is an action related to authorization and authentication, data manipulation, +administrator activity, or system events. + +The module provides detailed reports of these activities and helps you find and +fix breaches to protect your business. For example, you can see who created a new user +and when. + +It is up to each company to decide exactly what activities to audit and what actions to take. +System administrators, security engineers, and people in charge of the company may want to +audit different events for different reasons. Tarantool provides such an option for each of them. + +.. _audit-log-configure: + +Configure audit log +------------------- + +The section describes how to enable and configure audit logging and write logs to a selected destination -- a file, a pipe, +or a system logger. + +Read more: :ref:`Audit log configuration reference `. + +.. _audit-log-enable: + +Enable audit logging +~~~~~~~~~~~~~~~~~~~~ + +To enable audit logging, define the log location using the +:ref:`audit_log.to ` option in the configuration file. +Possible log locations: + +* a :ref:`file ` +* a :ref:`pipe ` +* a :ref:`system logger ` + +In the configuration below, the :ref:`audit_log.to ` option is set to ``file``. +It means that the logs are written to a file. +By default, audit logs are saved in the ``var/log/{{ instance_name }}/audit.log`` file. +To specify the path to an audit log file explicitly, use the :ref:`audit_log.file ` option. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'audit_tarantool.log' + :dedent: + +If you log to a file, Tarantool reopens the audit log at `SIGHUP `_. + +To disable audit logging, set the ``audit_log.to`` option to ``devnull``. + +.. _audit-log-filters: + +Filter the events +~~~~~~~~~~~~~~~~~ + +Tarantool's extensive filtering options help you write only the events you need to the audit log. +To select the recorded events, use the :ref:`audit_log.filter ` option. +Its value can be a list of events and event groups. +You can customize the filters and use different combinations of them for your purposes. +Possible filtering options: + +- Filter by event. You can set a list of :ref:`events ` to be recorded. For example, select + ``password_change`` to monitor the users who have changed their passwords: + + .. code-block:: yaml + + audit_log: + filter: [ password_change ] + +- Filter by group. You can specify a list of :ref:`event groups ` to be recorded. For example, + select ``auth`` and ``priv`` to see the events related to authorization and granted privileges: + + .. code-block:: yaml + + audit_log: + filter: [ auth,priv ] + +- Filter by group and event. You can specify a group and a certain event depending on the purpose. + In the configuration below, ``user_create``, ``data_operations``, ``ddl``, and ``custom`` are selected to see the events related to: + + * user creation + * space creation, altering, and dropping + * data modification or selection from spaces + * :ref:`custom events ` (any events added manually using the audit module API) + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: filter: + :end-at: custom ] + :dedent: + +.. _audit-log-format: + +Set the format of audit log events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :ref:`audit_log.format ` option to choose the format of audit log events +-- plain text, CSV, or JSON. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: format: + :end-at: json + :dedent: + +JSON is used by default. It is more convenient to receive log events, analyze them, and integrate them with other systems if needed. +The plain format can be efficiently compressed. +The CSV format allows you to view audit log events in tabular form. + +.. _audit-log-spaces: + +Specify the spaces to be logged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`audit_log.spaces ` option is used to specify +a list of space names for which data operation events should be logged. + +In the configuration below, only the events from the ``bands`` space are logged: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: spaces: + :end-at: bands ] + :dedent: + +.. _audit-log-extract: + +Specify the logging mode in DML events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If set to ``true``, the :ref:`audit_log.extract_key ` option +forces the audit subsystem to log the primary key instead of a full tuple in DML operations. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: extract_key: + :end-at: true + :dedent: + +.. _audit-log-run-example: + +Examples of audit log entries +----------------------------- + +In this example, the following audit log configuration is used: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log + :end-at: extract_key: true + :dedent: + +Create a space ``bands`` and check the logs in the file after the creation: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: function create_space() + :end-before: box.space.bands:format({ + :dedent: + +The audit log entry for the ``space_create`` event might look as follows: + +.. code-block:: json + + { + "time": "2024-01-24T11:43:21.566+0300", + "uuid": "26af0a7d-1052-490a-9946-e19eacc822c9", + "severity": "INFO", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_create", + "tag": "", + "description": "Create space Bands" + } + +Then insert one tuple to space: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: load_data() + :end-before: box.space.bands:insert { 2 + :dedent: + +If the ``extract_key`` option is set to ``true``, the audit system prints the primary key instead of the full tuple: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert key [2] into space bands" + } + +If the ``extract_key`` option is set to ``false``, the audit system prints the full tuple like this: + +.. code-block:: json + + { + "time": "2024-01-24T11:45:42.358+0300", + "uuid": "b437934d-62a7-419a-8d59-e3b33c688d7a", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "space_insert", + "tag": "", + "description": "Insert tuple [1, \"Roxette\", 1986] into space bands" + } + +.. _audit-log-events: + +Audit log events +---------------- + +.. _audit-log-events-types: + +Events types +~~~~~~~~~~~~ + +The Tarantool audit log module can record various events that you can monitor and +decide whether you need to take actions: + +* Administrator activity -- events related to actions performed by the administrator. + For example, such logs record the creation of a user. + +* Access events -- events related to authorization and authentication of users. + For example, such logs record failed attempts to access secure data. + +* Data access and modification -- events of data manipulation in the storage. + +* System events -- events related to modification or configuration of resources. + For example, such logs record the replacement of a space. + +* :ref:`Custom events ` -- any events added manually using + the audit module API. + +The full list of available audit log events is provided in the table below: + +.. container:: table + + .. list-table:: + :widths: 20 25 20 35 + :header-rows: 1 + + * - Event + - Event type + - Severity level + - Example + * - Audit log enabled for events + - ``audit_enable`` + - ``VERBOSE`` + - + * - :ref:`Custom events ` + - ``custom`` + - ``INFO`` (default) + - + * - User authorized successfully + - ``auth_ok`` + - ``VERBOSE`` + - ``Authenticate user `` + * - User authorization failed + - ``auth_fail`` + - ``ALARM`` + - ``Failed to authenticate user `` + * - User logged out or quit the session + - ``disconnect`` + - ``VERBOSE`` + - ``Close connection`` + * - User created + - ``user_create`` + - ``INFO`` + - ``Create user `` + * - User dropped + - ``user_drop`` + - ``INFO`` + - ``Drop user `` + * - Role created + - ``role_create`` + - ``INFO`` + - ``Create role `` + * - Role dropped + - ``role_drop`` + - ``INFO`` + - ``Drop role `` + * - User disabled + - ``user_disable`` + - ``INFO`` + - ``Disable user `` + * - User enabled + - ``user_enable`` + - ``INFO`` + - ``Enable user `` + * - User granted rights + - ``user_grant_rights`` + - ``INFO`` + - ``Grant rights for to user `` + * - User revoked rights + - ``user_revoke_rights`` + - ``INFO`` + - ``Revoke rights for from user `` + * - Role granted rights + - ``role_grant_rights`` + - ``INFO`` + - ``Grant rights for to role `` + * - Role revoked rights + - ``role_revoke_rights`` + - ``INFO`` + - ``Revoke rights for from role `` + * - User password changed + - ``password_change`` + - ``INFO`` + - ``Change password for user `` + * - Failed attempt to access secure data (for example, personal records, details, geolocation) + - ``access_denied`` + - ``ALARM`` + - `` denied to `` + * - Expressions with arguments evaluated in a string + - ``eval`` + - ``INFO`` + - ``Evaluate expression `` + * - Function called with arguments + - ``call`` + - ``VERBOSE`` + - ``Call function with arguments `` + * - Iterator key selected from ``space.index`` + - ``space_select`` + - ``VERBOSE`` + - ``Select from .`` + * - Space created + - ``space_create`` + - ``INFO`` + - ``Create space `` + * - Space altered + - ``space_alter`` + - ``INFO`` + - ``Alter space `` + * - Space dropped + - ``space_drop`` + - ``INFO`` + - ``Drop space `` + * - Tuple inserted into space + - ``space_insert`` + - ``VERBOSE`` + - ``Insert tuple into space `` + * - Tuple replaced in space + - ``space_replace`` + - ``VERBOSE`` + - ``Replace tuple with in space `` + * - Tuple deleted from space + - ``space_delete`` + - ``VERBOSE`` + - ``Delete tuple from space `` + + + .. note:: + + The ``eval`` event displays data from the ``console`` module + and the ``eval`` function of the ``net.box`` module. + For more on how they work, see :ref:`Module console ` + and :ref:`Module net.box -- eval `. + To separate the data, specify ``console`` or ``binary`` in the session field. + +.. _audit-log-structure: + +Structure of audit log event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each audit log event contains a number of fields that can be used to filter and aggregate the resulting logs. +An example of a Tarantool audit log entry in JSON: + +.. code-block:: json + + { + "time": "2024-01-15T13:39:36.046+0300", + "uuid": "cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0", + "severity": "VERBOSE", + "remote": "unix/:(socket)", + "session_type": "console", + "module": "tarantool", + "user": "admin", + "type": "auth_ok", + "tag": "", + "description": "Authenticate user Admin" + } + +Each event consists of the following fields: + +.. container:: table + + .. list-table:: + :widths: 30 35 35 + :header-rows: 1 + + * - Field + - Description + - Example + * - ``time`` + - Time of the event + - ``2024-01-15T16:33:12.368+0300`` + * - ``uuid`` + - Since :doc:`3.0.0 `. A unique identifier of audit log event + - ``cb44fb2b-5c1f-4c4b-8f93-1dd02a76cec0`` + * - ``severity`` + - Since :doc:`3.0.0 `. A severity level. Each system audit event has a severity level determined by its importance. + :ref:`Custom events ` have the ``INFO`` severity level by default. + + - ``VERBOSE`` + * - ``remote`` + - Remote host that triggered the event + - ``unix/:(socket)`` + * - ``session_type`` + - Session type + - ``console`` + * - ``module`` + - Audit log module. Set to ``tarantool`` for system events; + can be overwritten for custom events + - ``tarantool`` + * - ``user`` + - User who triggered the event + - ``admin`` + * - ``type`` + - Audit event type + - ``auth_ok`` + * - ``tag`` + - A text field that can be overwritten by the user + - + * - ``description`` + - Human-readable event description + - ``Authenticate user Admin`` + + +.. _audit-log-event-groups: + +Event groups +~~~~~~~~~~~~ + +Built-in event groups are used to filter the event types that you want to audit. +For example, you can set to record only authorization events or only events related to a space. + +Tarantool provides the following event groups: + +* ``all`` -- all :ref:`events `. + + .. note:: + + Events ``call`` and ``eval`` are included only in the ``all`` group. + +* ``audit`` -- ``audit_enable`` event. + +* ``auth`` -- authorization events: ``auth_ok``, ``auth_fail``. + +* ``priv`` -- events related to authentication, authorization, users, and roles: + ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, + ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``, ``role_revoke_rights``. + +* ``ddl`` -- events of space creation, altering, and dropping: + ``space_create``, ``space_alter``, ``space_drop``. + +* ``dml`` -- events of data modification in spaces: + ``space_insert``, ``space_replace``, ``space_delete``. + +* ``data_operations`` -- events of data modification or selection from spaces: + ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``. + +* ``compatibility`` -- events available in Tarantool before the version 2.10.0. + ``auth_ok``, ``auth_fail``, ``disconnect``, ``user_create``, ``user_drop``, + ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, + ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``. + ``role_revoke_rights``, ``password_change``, ``access_denied``. + This group enables the compatibility with earlier Tarantool versions. + +.. warning:: + + Be careful when recording ``all`` and ``data_operations`` event groups. + The more events you record, the slower the requests are processed over time. + It is recommended that you select only those groups + whose events your company needs to monitor and analyze. + +.. _audit-log-custom: + +Custom events +------------- + +Tarantool provides an API for writing custom audit log events. +To enable these events, specify the ``custom`` value in the :ref:`audit_log.filter ` option: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: filter: + :end-at: custom ] + :dedent: + +.. _audit-log-custom-log: + +Log a custom event +~~~~~~~~~~~~~~~~~~ + +To log an event, use the ``audit.log()`` function that takes one of the following values: + +* Message string. Printed to the audit log with type ``message``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log message string + :end-before: Log format string and arguments + :dedent: + +* Format string and arguments. Passed to string format and then output to the audit log with type ``message``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log format string and arguments + :end-before: Log table with audit log field values + :dedent: + +* Table with audit log field values. The table must contain at least one field -- ``description``. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Log table with audit log field values + :end-at: description = 'Farewell, Eve!' }) + :dedent: + +Alternatively, you can use ``audit.new()`` to create a new log module. +This allows you to avoid passing all custom audit log fields each time ``audit.log()`` is called. +The ``audit.new()`` function takes a table of audit log field values (same as ``audit.log()``). +The ``type`` of the log module for writing custom events must either be ``message`` or have the ``custom_`` prefix. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Create a new log module + :end-before: Log 'Hello!' message with the VERBOSE severity level + :dedent: + +.. _audit-log-custom-field-overwrite: + +Overwrite custom event fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to overwrite most of the custom audit log :ref:`fields ` using ``audit.new()`` or ``audit.log()``. +The only audit log field that cannot be overwritten is ``time``. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-after: Overwrite session_type and remote fields + :end-at: remote = 'my_remote' }) + :dedent: + +If omitted, the ``session_type`` is set to the current session type, ``remote`` is set to the remote peer address. + +.. note:: + + To avoid confusion with system events, the value of the type field must either be ``message`` (default) + or begin with the ``custom_`` prefix. Otherwise, you receive the error message. + Custom events are filtered out by default. + +.. _audit-log-custom-severity: + +Severity level +~~~~~~~~~~~~~~ + +By default, custom events have the ``INFO`` :ref:`severity level `. +To override the level, you can: + +* specify the ``severity`` field +* use a shortcut function + +The following shortcuts are available: + +.. container:: table + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Shortcut + - Equivalent + * - ``audit.verbose(...)`` + - ``audit.log({severity = 'VERBOSE', ...})`` + * - ``audit.info(...)`` + - ``audit.log({severity = 'INFO', ...})`` + * - ``audit.warning(...)`` + - ``audit.log({severity = 'WARNING', ...})`` + * - ``audit.alarm(...)`` + - ``audit.log({severity = 'ALARM', ...})`` + +**Example** + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/myapp.lua + :language: lua + :start-at: audit.log({ severity + :end-at: description = 'Hello!' }) + :dedent: + +.. _audit-log-tips: + +Tips +---- + +How many events can be recorded? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you write to a file, the size of the Tarantool audit log is limited by the disk space. +If you write to a system logger, the size of the Tarantool audit log is limited by the system logger. +If you write to a pipe, the size of the Tarantool audit message is limited by the system buffer. +If the ``audit_log.nonblock = false``, if ``audit_log.nonblock`` = ``true``, there is no limit. + +How often should audit logs be reviewed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider setting up a schedule in your company. It is recommended to review audit logs at least every 3 months. + +How long should audit logs be stored? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is recommended to store audit logs for at least one year. + +What is the best way to process audit logs? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is recommended to use SIEM systems for this issue. diff --git a/doc/platform/security/index.rst b/doc/platform/security/index.rst new file mode 100644 index 0000000000..6900af1e31 --- /dev/null +++ b/doc/platform/security/index.rst @@ -0,0 +1,13 @@ +.. _security: + +Security +======== + +This section contains guides related to security features. + +.. toctree:: + :maxdepth: 1 + + audit_log + audit + security diff --git a/doc/platform/security/security.rst b/doc/platform/security/security.rst new file mode 100644 index 0000000000..666a07b569 --- /dev/null +++ b/doc/platform/security/security.rst @@ -0,0 +1,176 @@ +.. _enterprise-security: + +Security hardening guide +======================== + +This guide explains how to enhance security in your Tarantool Enterprise Edition's +cluster using built-in features and provides general recommendations on security +hardening. +If you need to perform a security audit of a Tarantool Enterprise cluster, +refer to the :doc:`security checklist `. + +Tarantool Enterprise Edition does not provide a dedicated API for security control. All +the necessary configurations can be done via an administrative console or +initialization code. + +Tarantool Enterprise Edition has the following built-in security features: + +* :ref:`authentication ` +* :ref:`access control ` +* :ref:`audit log ` +* :ref:`traffic encryption ` + + +.. _enterprise-authentication: + +Authentication +-------------- + +Tarantool Enterprise Edition supports password-based authentication and allows for two +types of connections: + +* Via an :doc:`administrative console `. +* Over a binary port for read and write operations and procedure invocation. + +For more information on authentication and connection types, see the +:ref:`admin-security` section in :ref:`Administration `. + +In addition, Tarantool provides the following functionality: + +* :ref:`Sessions ` + -- states which associate connections with users and make Tarantool API available + to them after authentication. +* Authentication :ref:`triggers `, + which execute actions on authentication events. +* Third-party (external) authentication protocols and services such as LDAP or + Active Directory -- supported in the web interface, but unavailable + on the binary-protocol level. + +.. _enterprise-access-control: + +Access control +-------------- + +Tarantool Enterprise Edition provides the means for administrators to prevent +unauthorized access to the database and to certain functions. + +Tarantool recognizes: + +* different users (guests and administrators) +* privileges associated with users +* roles (containers for privileges) granted to users + +The following system spaces are used to store users and privileges: + +* The ``_user`` space to store usernames and hashed passwords for authentication. +* The ``_priv`` space to store privileges for access control. + +For more information, see the +:ref:`Access control ` section. + +Users who create **objects** (spaces, indexes, users, roles, sequences, and +functions) in the database become their **owners** and automatically acquire +privileges for what they create. For more information, see the +:ref:`Owners and privileges ` section. + + + +.. _enterprise-logging: + +Audit log +--------- + +Tarantool Enterprise Edition has a built-in audit log that records events such as: + +* authentication successes and failures +* connection closures +* creation, removal, enabling, and disabling of users +* changes of passwords, privileges, and roles +* denials of access to database objects + +The audit log contains: + +* timestamps +* usernames of users who performed actions +* event types (for example, ``user_create``, ``user_enable``, ``disconnect``) +* descriptions + +You can configure the following audit log options: + +* :ref:`audit_log.to ` -- enable audit logging and define the log location (file, pipe, or syslog). + The option is similar to the :ref:`log `. + +* :ref:`audit_log.nonblock ` -- specify the logging behavior if the system is not ready to write. + The option is similar to the :ref:`log_nonblock `. + +For more information on logging, see the following: + +* the :ref:`admin-logs` section +* the :ref:`log ` section in the configuration reference +* the :ref:`Tarantool audit module ` topic + +Access permissions to audit log files can be set up as to any other Unix file +system object -- via ``chmod``. + + + +.. _enterprise-security-hardening: + +Recommendations on security hardening +------------------------------------- + +This section lists recommendations that can help you harden the cluster's security. + +.. _enterprise-traffic-encryption: + +Encrypting traffic +~~~~~~~~~~~~~~~~~~ + +Since version 2.10.0, Tarantool Enterprise Edition has built-in support for using SSL to encrypt the client-server communications over binary connections, +that is, between Tarantool instances in a cluster. For details on enabling SSL encryption, see the :ref:`enterprise-iproto-encryption` section of this guide. + +In case the built-in encryption is not set for particular connections, consider the following security recommendations: + +* setting up connection tunneling, or +* encrypting the actual data stored in the database. + +For more information on data encryption, see the +:doc:`crypto module reference `. + +The `HTTP server module `_ provided by rocks +does not support the HTTPS protocol. To set up a secure connection for a client +(e.g., REST service), consider hiding the Tarantool instance (router if it is +a cluster of instances) behind an Nginx server and setting up an SSL certificate +for it. + +To make sure that no information can be intercepted 'from the wild', run nginx +on the same physical server as the instance and set up their communication over +a Unix socket. For more information, see the +:doc:`socket module reference `. + +.. _enterprise-firewall-config: + +Firewall configuration +~~~~~~~~~~~~~~~~~~~~~~ + +To protect the cluster from any unwanted network activity 'from the wild', +configure the firewall on each server to allow traffic on ports listed in +:ref:`Network requirements `. + +If you are using static IP addresses, whitelist them, again, on each server as +the cluster has a full mesh network topology. Consider blacklisting all the other +addresses on all servers except the router (running behind the Nginx server). + +Tarantool Enterprise does not provide defense against DoS or DDoS attacks. +Consider using third-party software instead. + +.. _enterprise-integrity: + +Data integrity +~~~~~~~~~~~~~~ + +Tarantool Enterprise Edition does not keep checksums or provide the means to control +data integrity. However, it ensures data persistence using a write-ahead log, +regularly snapshots the entire data set to disk, and checks the data format +whenever it reads the data back from the disk. For more information, see the +:ref:`Data persistence ` section. diff --git a/doc/concepts/sharding/bucket.svg b/doc/platform/sharding/bucket.svg similarity index 100% rename from doc/concepts/sharding/bucket.svg rename to doc/platform/sharding/bucket.svg diff --git a/doc/concepts/sharding/buckets.svg b/doc/platform/sharding/buckets.svg similarity index 100% rename from doc/concepts/sharding/buckets.svg rename to doc/platform/sharding/buckets.svg diff --git a/doc/concepts/sharding/hierarchy.png b/doc/platform/sharding/hierarchy.png similarity index 100% rename from doc/concepts/sharding/hierarchy.png rename to doc/platform/sharding/hierarchy.png diff --git a/doc/platform/sharding/index.rst b/doc/platform/sharding/index.rst new file mode 100644 index 0000000000..029f9f7de0 --- /dev/null +++ b/doc/platform/sharding/index.rst @@ -0,0 +1,48 @@ +.. _sharding: +.. _vshard-summary: + +Sharding +======== + +Scaling databases in a growing project is often considered one of the most +challenging issues. Once a single server cannot withstand the load, scaling +methods should be applied. + +**Sharding** is a database architecture that allows for +`horizontal scaling `_, +which implies that a dataset is partitioned and distributed over multiple servers. + +With Tarantool's `vshard `_ module, +the tuples of a dataset are distributed across +multiple nodes, with a Tarantool database server instance on each node. Each instance +handles only a subset of the total data, so larger loads can be handled by simply +adding more servers. The initial dataset is partitioned into multiple parts, so each +part is stored on a separate server. + +The ``vshard`` module is based on the concept of +:ref:`virtual buckets `, where a tuple +set is partitioned into a large number of abstract virtual nodes (**virtual buckets**, +further just **buckets**) rather than into a smaller number of physical nodes. + +The dataset is partitioned using **sharding keys** (bucket id numbers). +Hashing a sharding key into a large number of buckets allows seamlessly +changing the number of servers in the cluster. The **rebalancing mechanism** distributes +buckets evenly among all shards in case some servers were added or removed. + +The buckets have **states**, so it is easy to monitor the server states. For example, +a server instance is active and available for all types of requests, or a failover +occurred and the instance accepts only read requests. + +The ``vshard`` module provides router and storage API (public and internal) for sharding-aware applications. + +Check out the :ref:`quick start guide ` or +learn more about :ref:`how sharding works ` in Tarantool: + +.. toctree:: + :maxdepth: 2 + + vshard_architecture + vshard_admin + +You can also find out more about :ref:`sharding administration ` +or dive into the ``vshard`` configuration and API :ref:`reference `. diff --git a/doc/concepts/sharding/master_replica.svg b/doc/platform/sharding/master_replica.svg similarity index 100% rename from doc/concepts/sharding/master_replica.svg rename to doc/platform/sharding/master_replica.svg diff --git a/doc/concepts/sharding/schema.svg b/doc/platform/sharding/schema.svg similarity index 100% rename from doc/concepts/sharding/schema.svg rename to doc/platform/sharding/schema.svg diff --git a/doc/concepts/sharding/states.svg b/doc/platform/sharding/states.svg similarity index 100% rename from doc/concepts/sharding/states.svg rename to doc/platform/sharding/states.svg diff --git a/doc/concepts/sharding/vbuckets.svg b/doc/platform/sharding/vbuckets.svg similarity index 100% rename from doc/concepts/sharding/vbuckets.svg rename to doc/platform/sharding/vbuckets.svg diff --git a/doc/platform/sharding/vshard_admin.rst b/doc/platform/sharding/vshard_admin.rst new file mode 100644 index 0000000000..ae338eca34 --- /dev/null +++ b/doc/platform/sharding/vshard_admin.rst @@ -0,0 +1,663 @@ +.. _vshard-admin: + +Sharding with vshard +==================== + +Sharding in Tarantool is implemented in the ``vshard`` module. +For a quick start with ``vshard``, refer to :ref:`vshard-quick-start`. + +.. NOTE:: + + Starting with the 3.0 version, the recommended way of configuring Tarantool is using a :ref:`configuration file `. + The :ref:`sharding ` section defines configuration parameters related to sharding. + To learn how to configure ``vshard`` in code, see :ref:`vshard-config-reference`. + + +.. _vshard-install: + +Installation +------------ + +The ``vshard`` module is distributed separately from the main Tarantool package. +To install the module, execute the following command: + +.. code-block:: console + + $ tt rocks install vshard + +If you are developing a sharded cluster application, add the ``vshard`` module dependency to a ``*.rockspec`` file: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec + :language: none + :start-at: dependencies + :end-before: build + :dedent: + +.. note:: + + The minimum required version of ``vshard`` is 0.1.25. + + +.. _vshard-config-cluster: + +Configuration overview +---------------------- + +Configuring settings related to sharding might include the following steps: + +1. Configure :ref:`connection settings ` to allow instances within a sharded cluster to communicate with each other. + +2. Specify which :ref:`role ` each replica set plays in a sharded cluster. + +3. Configure how data is :ref:`partitioned ` across shards. + +4. Specify settings related to :ref:`data rebalancing `. + + +.. _vshard_config_connectivity: + +Connectivity +------------ + +This section describes connection options that enable communication between instances within a sharded cluster. +For general information about connections, see the :ref:`configuration_connections` topic. + +.. _vshard_config_advertise_uri: + +Advertise URI +~~~~~~~~~~~~~ + +In a sharded cluster configuration, you need to specify how a router and rebalancer connect to storages using the :ref:`iproto.advertise.sharding ` option. +In the example below, the ``storage`` user is used for this purpose: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-at: iproto + :end-at: login: storage + :dedent: + +The ``storage`` user should have the ``sharding`` role described in the next section. + + +.. _vshard_config_credentials: + +Credentials +~~~~~~~~~~~ + +To allow a router and rebalancer to connect to storages, a user with the ``sharding`` :ref:`role ` should be used. +The example below shows how to grant the ``sharding`` role to the ``storage`` user: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-at: credentials: + :end-at: roles: [sharding] + :dedent: + +The ``sharding`` role has different privileges depending on a replica set's :ref:`sharding role `. +For replica sets with the ``storage`` sharding role, the ``sharding`` credential role has the following privileges: + +- All privileges provided by the ``replication`` role. +- Executing :ref:`vshard.storage.* ` functions. + +If a replica set does not have the ``storage`` sharding role, the ``sharding`` credential role does not have any privileges. + + +.. _vshard_config_sharding_roles: + +Sharding roles +-------------- + +Each replica set in a sharded cluster can have one of three roles: + +* ``router``: a replica set acts as a :ref:`router `. +* ``storage``: a replica set acts as a :ref:`storage `. +* ``rebalancer``: a replica set acts as a :ref:`rebalancer `. + +You can use the :ref:`sharding.roles ` option to assign a specific role to a replica set or group of replica sets. +In the example below, all replica sets in the ``storages`` group have the ``storage`` role while replica sets in the ``routers`` group have the ``router`` role. + +.. code-block:: yaml + + groups: + storages: + sharding: + roles: [storage] + # ... + routers: + sharding: + roles: [router] + # ... + +Note that the ``rebalancer`` role is optional. +If it is not specified, a rebalancer is selected automatically from the master instances of replica sets. +To specify the rebalancer manually or turn it off, use the :ref:`sharding.rebalancer_mode ` option. + + +.. _vshard_config_data_partitioning: + +Data partitioning +----------------- + +This section describes configuration settings related to data partitioning. +Learn how to define spaces to be sharded in :ref:`vshard-define-spaces`. + + +.. _vshard_config_bucket_count: + +Bucket count +~~~~~~~~~~~~ + +To define the total number of buckets in a cluster, configure the :ref:`sharding.bucket_count ` option at the :ref:`global level `. +In the example below, ``sharding.bucket_count`` is set to 1000: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-after: login: storage + :end-at: bucket_count + :dedent: + +``sharding.bucket_count`` should be several orders of magnitude larger than the potential number of cluster nodes considering potential scaling out in the future. + +If the estimated number of nodes in a cluster is N, then the data set should be divided into 100N or even 1000N buckets depending on the planned scaling out. +This number is greater than the potential number of cluster nodes in the system being designed. + +Keep in mind that too many buckets can cause a need to allocate more memory to store routing information. +On the other hand, an insufficient number of buckets can lead to decreased granularity when :ref:`rebalancing `. + + + +.. _vshard-replica-set-weights: + +Replica set weights +~~~~~~~~~~~~~~~~~~~ + +A replica set weight defines the storage capacity of the replica set: the larger the weight, the more buckets the replica set can store. +You can configure a replica set weight using the :ref:`sharding.weight ` option. +This option can be used to store the prevailing amount of data on a replica set with more memory space. +You can also assign a zero weight to a replica set to initiate :ref:`migration of its buckets ` to the remaining cluster nodes. + +In the example below, the ``storage-a`` replica set can store twice as much data as ``storage-b``: + +.. code-block:: yaml + + # ... + replicasets: + storage-a: + sharding: + weight: 2 + # ... + storage-b: + sharding: + weight: 1 + # ... + + +.. _vshard_config_rebalancing: + +Data rebalancing +---------------- + + +.. _vshard-rebalancing: + +Rebalancing process +~~~~~~~~~~~~~~~~~~~ + +There is an **etalon number** of buckets for a replica set. +(Etalon in this context means "ideal".) +If there is no deviation +from this number in the whole replica set, then the buckets are distributed evenly. + +The etalon number is calculated automatically considering the number of buckets +in the cluster and the weights of the replica sets. + +Rebalancing starts if the **disbalance threshold of a replica set** +exceeds the disbalance threshold specified in the configuration +(the :ref:`sharding.rebalancer_disbalance_threshold ` option). + +The disbalance threshold of a replica set is calculated as follows: + +.. code-block:: none + + |etalon_bucket_number - real_bucket_number| / etalon_bucket_number * 100 + +For example, a cluster is configured as follows: + +* The number of buckets (:ref:`sharding.bucket_count `) is set to 3000. +* :ref:`Weights ` of 3 replica sets are 1, 0.5, and 1.5. + +In this case, the etalon numbers of buckets for the replica sets are: + +* 1st replica set -- 1000. +* 2nd replica set -- 500. +* 3rd replica set -- 1500. + +You can set a :ref:`replica set weight ` to zero to initiate migration of its buckets to the remaining cluster nodes. +You can also add a new replica set with a non-zero weight to initiate migration of the buckets from the existing replica sets. + +When a new shard is added, a configuration should be reloaded on each instance to migrate buckets to a new shard: + +* If a :ref:`centralized configuration storage ` is used, Tarantool reloads a changed configuration automatically. +* If a local configuration file is used, you need to reload a configuration on all the routers first and then on all the storages. + + +.. _vshard-parallel-rebalancing: + +Parallel rebalancing +~~~~~~~~~~~~~~~~~~~~ + +Originally, ``vshard`` had quite a simple ``rebalancer`` – +one process on one node that calculated *routes* that should send buckets, how +many, and to whom. The nodes applied these routes one by +one sequentially. + +Unfortunately, such a simple schema worked not fast enough, +especially for Vinyl, where costs of reading disk were comparable +with network costs. In fact, with Vinyl the ``rebalancer`` routes +applier was sleeping most of the time. + +Now each node can send multiple buckets in parallel in a +round-robin manner to multiple destinations, or to just one. + +To set the degree of parallelism, use the :ref:`sharding.rebalancer_max_sending ` option: + +.. code-block:: yaml + + sharding: + rebalancer_max_sending: 5 + +.. note:: + + Specifying ``sharding.rebalancer_max_sending = N`` probably won't give N times + speed up. It depends on network, disk, number of other fibers in the system. + +.. _vshard-parallel-rebalancing-example1: + +Example 1 +********* + +You have 10 replica sets and a new one is added. +Now all the 10 replica sets will try to send buckets to the new one. + +Assume that each replica set can send up to 5 buckets at once. In that case, +the new replica set will experience a rather big load of 50 buckets +being downloaded at once. If the node needs to do some other +work, perhaps such a big load is undesirable. Also too, many +parallel buckets can cause timeouts in the rebalancing process +itself. + +To fix the problem, you can set a lower value for ``rebalancer_max_sending`` +for old replica sets, or decrease ``rebalancer_max_receiving`` for the new one. +In the latter case, some workers on old nodes will be throttled, +and you will see that in the logs. + +``rebalancer_max_sending`` is important, if you have restrictions for +the maximum number of buckets that can be read only at once in the cluster. As you +remember, when a bucket is being sent, it does not accept new +write requests. + +.. _vshard-parallel-rebalancing-example2: + +Example 2 +********* + +You have 100000 buckets and each +bucket stores ~0.001% of your data. The cluster has 10 +replica sets. And you never can afford > 0.1% of data locked on +write. Then you should not set ``rebalancer_max_sending`` > 10 on +these nodes. It guarantees that the rebalancer won't send more +than 100 buckets at once in the whole cluster. + +If ``rebalancer_max_sending`` is too high and ``rebalancer_max_receiving`` is too low, +then some buckets will try to get relocated – and will fail with that. +This problem will consume network resources and time. It is important to +configure these parameters to not conflict with each other. + +.. _vshard-lock-pin: + +Replica set lock and bucket pin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A replica set lock (:ref:`sharding.lock `) makes a replica set invisible to the ``rebalancer``: a locked +replica set can neither receive new buckets nor migrate its own buckets. + +A bucket pin (:ref:`vshard.storage.bucket_pin(bucket_id) `) blocks a specific bucket from migrating: a pinned bucket stays on +the replica set to which it is pinned until it is unpinned. + +Pinning all replica set buckets is not equivalent to locking a replica set. Even if +you pin all buckets, a non-locked replica set can still receive new buckets. + +A replica set lock is helpful, for example, to separate a replica set from production +replica sets for testing, or to preserve some application metadata that must not +be sharded for a while. A bucket pin is used for similar cases but in a smaller +scope. + +By both locking a replica set and pinning all buckets, you can +isolate an entire replica set. + +Locked replica sets and pinned buckets affect the rebalancing algorithm as the +``rebalancer`` must ignore locked replica sets and consider pinned buckets when +attempting to reach the best possible balance. + +The issue is not trivial as a user can pin too many buckets to a replica set, +so a perfect balance becomes unreachable. For example, consider the following +cluster (assume all replica set weights are equal to 1). + +The initial configuration: + +.. code-block:: none + + rs1: bucket_count = 150 + rs2: bucket_count = 150, pinned_count = 120 + +Adding a new replica set: + +.. code-block:: none + + rs1: bucket_count = 150 + rs2: bucket_count = 150, pinned_count = 120 + rs3: bucket_count = 0 + +The perfect balance would be ``100 - 100 - 100``, which is impossible since the +``rs2`` replica set has 120 pinned buckets. The best possible balance here is the +following: + +.. code-block:: none + + rs1: bucket_count = 90 + rs2: bucket_count = 120, pinned_count 120 + rs3: bucket_count = 90 + +The ``rebalancer`` moved as many buckets as possible from ``rs2`` to decrease the +disbalance. At the same time, it respected equal weights of ``rs1`` and ``rs3``. + +The algorithms for implementing locks and pins are completely different, although +they look similar in terms of functionality. + +.. _vshard-lock-and-rebalancing: + +Replica set lock and rebalancing +******************************** + +Locked replica sets do not participate in rebalancing. This means that +even if the actual total number of buckets is not equal to the etalon number, +the disbalance cannot be fixed due to the lock. When the rebalancer detects that +one of the replica sets is locked, it recalculates the etalon number of buckets +of the non-locked replica sets as if the locked replica set and its buckets did +not exist at all. + +.. _vshard-pin-and-rebalancing: + +Bucket pin and rebalancing +************************** + +Rebalancing replica sets with pinned buckets requires a more complex algorithm. +Here ``pinned_count[o]`` is the number of pinned buckets, and ``etalon_count`` is +the etalon number of buckets for a replica set: + +1. The ``rebalancer`` calculates the etalon number of buckets as if all buckets + were not pinned. Then the rebalancer checks each replica set and compares the + etalon number of buckets with the number of pinned buckets in a replica set. + If ``pinned_count < etalon_count``, non-locked replica sets (at this point all + locked replica sets already are filtered out) with pinned buckets can receive + new buckets. +2. If ``pinned_count > etalon_count``, the disbalance cannot be fixed, as the + ``rebalancer`` cannot move pinned buckets out of this replica set. In such a case + the etalon number is updated and set equal to the number of pinned buckets. + The replica sets with ``pinned_count > etalon_count`` are not processed by + the ``rebalancer``, and the number of pinned buckets is subtracted from the + total number of buckets. The rebalancer tries to move out as many buckets as + possible from such replica sets. +3. This procedure is restarted from step 1 for replica sets with + ``pinned_count >= etalon_count`` until ``pinned_count <= etalon_count`` on + all replica sets. The procedure is also restarted when the total number of + buckets is changed. + +Here is the pseudocode for the algorithm: + +.. code-block:: lua + + function cluster_calculate_perfect_balance(replicasets, bucket_count) + -- rebalance the buckets using weights of the still viable replica sets -- + end; + + cluster = ; + bucket_count = ; + can_reach_balance = false + while not can_reach_balance do + can_reach_balance = true + cluster_calculate_perfect_balance(cluster, bucket_count); + foreach replicaset in cluster do + if replicaset.perfect_bucket_count < + replicaset.pinned_bucket_count then + can_reach_balance = false + bucket_count -= replicaset.pinned_bucket_count; + replicaset.perfect_bucket_count = + replicaset.pinned_bucket_count; + end; + end; + end; + cluster_calculate_perfect_balance(cluster, bucket_count); + +The complexity of the algorithm is ``O(N^2)``, where N is the number of replica sets. +On each step, the algorithm either finishes the calculation, or ignores at least +one new replica set overloaded with the pinned buckets, and updates the etalon +number of buckets on other replica sets. + +.. _vshard-ref: + +Bucket ref +~~~~~~~~~~ + +Bucket ref is an in-memory counter that is similar to the +:ref:`bucket pin `, but has the following differences: + +#. Bucket ref is not persistent. Refs are intended for forbidding bucket transfer + during request execution, but on restart all requests are dropped. + +#. There are two types of bucket refs: read-only (RO) and read-write (RW). + + If a bucket has RW refs, it cannot be moved. However, when the rebalancer + needs it to be sent, it locks the bucket for new write requests, waits + until all current requests are finished, and then sends the bucket. + + If a bucket has RO refs, it can be sent, but cannot be dropped. Such a + bucket can even enter GARBAGE or SENT state, but its data is kept until + the last reader is gone. + + A single bucket can have both RO and RW refs. + +#. Bucket ref is countable. + +The :ref:`vshard.storage.bucket_ref/unref()` methods +are called automatically when :ref:`vshard.router.call() ` +or :ref:`vshard.storage.call() ` is used. +For raw API like ``r = vshard.router.route() r:callro/callrw``, you should +explicitly call the ``bucket_ref()`` method inside the function. Also, make sure +that you call ``bucket_unref()`` after ``bucket_ref()``, otherwise the bucket +cannot be moved from the storage until the instance is restarted. + +To see how many refs there are for a bucket, use +:ref:`vshard.storage.buckets_info([bucket_id]) ` +(the ``bucket_id`` parameter is optional). + +For example: + +.. code-block:: tarantoolsession + + vshard.storage.buckets_info(1) + --- + - 1: + status: active + ref_rw: 1 + ref_ro: 1 + ro_lock: true + rw_lock: true + id: 1 + + + +.. _vshard_defining_manipulating_data: + +Defining and manipulating data +------------------------------ + +.. _vshard-define-spaces: + +Data definition +~~~~~~~~~~~~~~~ + +Sharded spaces should be defined in a storage application inside :ref:`box.once() ` and should have a field with :ref:`bucket id ` values. +This field should meet the following requirements: + +- The field's :ref:`data type ` can be ``unsigned``, ``number``, or ``integer``. +- The field must be non-nullable. +- The field must be indexed by the :ref:`shard_index `. The default name for this index is ``bucket_id``. + +In the example below, the ``bands`` space has the ``bucket_id`` field, which is used to partition a dataset across different storage instances: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua + :language: lua + :start-at: box.once + :end-before: function insert_band + :dedent: + +Example on GitHub: `sharded_cluster `_ + + + + +.. _vshard-adding-data: + +Data manipulation +~~~~~~~~~~~~~~~~~ + +All DML operations with data should be performed via a router using the ``vshard.router.call`` functions, such as :ref:`vshard.router.callrw() ` or :ref:`vshard.router.callro() `. +For example, a storage application has the ``insert_band`` function used to insert new tuples: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua + :language: lua + :start-at: function insert_band + :end-before: function get_band + :dedent: + +In a router application, you can define the ``put`` function that specifies how a router selects the storage to write data: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/router.lua + :language: lua + :start-at: function put + :end-before: function get + :dedent: + +Learn more at :ref:`vshard-process-requests`. + +.. _vshard-maintenance: + +Sharded cluster maintenance +--------------------------- + +.. _vshard-maintenance-master_crash: + +Master crash +~~~~~~~~~~~~ + +If a replica set master fails, it is recommended to: + +#. Switch one of the replicas into the master mode. This allows the new master + to process all the incoming requests. +#. Update the configuration of all the cluster members. This forwards all the + requests to the new master. + +.. _vshard-maintenance-replicaset_crash: + +Replica set crash +~~~~~~~~~~~~~~~~~ + +In case a whole replica set fails, some part of the dataset becomes inaccessible. +Meanwhile, the router tries to reconnect to the master of the failed replica set. +This way, once the replica set is up and running again, the cluster is automatically restored. + + +.. _vshard-maintenance-master_scheduled_downtime: + +Master scheduled downtime +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform a scheduled downtime of a replica set master, it is recommended to: + +#. Update the configuration to use another instance as a master. +#. Reload the configuration on all the instances. All the requests then are forwarded to a new master. +#. Shut down the old master. + +.. _vshard-maintenance-replicaset_scheduled_downtime: + +Replica set scheduled downtime +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform a scheduled downtime of a replica set, it is recommended to: + +#. Migrate all the buckets to the other cluster storages. + You can do this by assigning a zero :ref:`weight ` to a replica set to initiate migration of its buckets to the remaining cluster nodes. +#. Update the configuration of all the nodes. +#. Shut down the replica set. + + +.. _vshard-fibers: + +Fibers +------ + +Searches for buckets, buckets recovery, and buckets rebalancing are performed +automatically and do not require manual intervention. + +Technically, there are multiple fibers responsible for different types of +operations: + +* a **discovery** fiber on the router searches for buckets in the background +* a **failover** fiber on the router maintains replica connections +* a **garbage collector** fiber on each master storage removes the contents + of buckets that were moved +* a **bucket recovery** fiber on each master storage recovers buckets in the + SENDING and RECEIVING states in case of reboot +* a **rebalancer** on a single master storage among all replica sets executes the rebalancing process. + +See the :ref:`Rebalancing process ` and +:ref:`Migration of buckets ` sections for details. + +.. _vshard-gc: + +Garbage collector +~~~~~~~~~~~~~~~~~ + + +A **garbage collector** fiber runs in the background on the master storages +of each replica set. It starts deleting the contents of the bucket in the GARBAGE +state part by part. Once the bucket is empty, its record is deleted from the +``_bucket`` system space. + +.. _vshard-bucket-recovery: + +Bucket recovery +~~~~~~~~~~~~~~~ + +A **bucket recovery** fiber runs on the master storages. It helps to recover +buckets in the SENDING and RECEIVING states in case of reboot. + +Buckets in the SENDING state are recovered as follows: + +1. The system first searches for buckets in the SENDING state. +2. If such a bucket is found, the system sends a request to the destination + replica set. +3. If the bucket on the destination replica set is ACTIVE, the original bucket + is deleted from the source node. + +Buckets in the RECEIVING state are deleted without extra checks. + +.. _vshard-failover: + +Failover +~~~~~~~~ + +A **failover** fiber runs on every router. If a master of a replica set +becomes unavailable, the failover fiber redirects read requests to the replicas. +Write requests are rejected with an error until the master becomes available. diff --git a/doc/concepts/sharding/vshard_architecture.rst b/doc/platform/sharding/vshard_architecture.rst similarity index 96% rename from doc/concepts/sharding/vshard_architecture.rst rename to doc/platform/sharding/vshard_architecture.rst index cf1663339c..5ba9803ca3 100644 --- a/doc/concepts/sharding/vshard_architecture.rst +++ b/doc/platform/sharding/vshard_architecture.rst @@ -70,18 +70,10 @@ buckets. Each replica set stores a unique subset of buckets. One bucket cannot belong to multiple replica sets at a time. -The total number of buckets is determined by the administrator who sets up the -initial cluster configuration. +The total :ref:`number of buckets ` is determined by the administrator who sets up the initial cluster configuration. Every space you plan to shard must have a numeric field containing bucket id-s. -This field must comply with the following requirements: - -* The field's data type can be: unsigned, number or integer. -* The field must be not nullable. -* The field must be indexed by the :ref:`shard_index `. - The default name for this index is ``bucket_id``. - -See the :ref:`configuration example `. +You can learn more from :ref:`vshard-define-spaces`. .. _vshard-structure: @@ -90,9 +82,16 @@ Structure A sharded cluster in Tarantool consists of: -* storages, -* routers, -* and a rebalancer. +* One or more replica sets. + + Each replica set should contain at least two storage instances. + For redundancy, it is recommended to have 3 or more storage instances in a replica set. + +* One or more router instances. + + The number of router instances is not limited and should be increased if the existing router instances become CPU or I/O bound. + +* Rebalancer. .. image:: schema.svg :align: center @@ -231,8 +230,7 @@ While a bucket is being migrated, it can have different states: * RECEIVING – the bucket is currently being filled; all requests to it are rejected. * SENT – the bucket was migrated to the destination replica set. The `router` uses the SENT state to calculate the new location of the bucket. A bucket in - the SENT state goes to the GARBAGE state automatically after BUCKET_SENT_GARBAGE_DELAY - seconds, which by default is :ref:`0.5 seconds `. + the SENT state goes to the GARBAGE state automatically after 0.5 seconds. * GARBAGE – the bucket was already migrated to the destination replica set during rebalancing; or the bucket was initially in the RECEIVING state, but some error occurred during the migration. diff --git a/doc/platform/storage/index.rst b/doc/platform/storage/index.rst new file mode 100644 index 0000000000..c215b40dc2 --- /dev/null +++ b/doc/platform/storage/index.rst @@ -0,0 +1,13 @@ +.. _config_storage: + +Storage +======= + +This section contains guides on configuring a storage. + +.. toctree:: + :maxdepth: 1 + + memtx + persistence + wal_extensions diff --git a/doc/platform/storage/memtx.rst b/doc/platform/storage/memtx.rst new file mode 100644 index 0000000000..520076d24d --- /dev/null +++ b/doc/platform/storage/memtx.rst @@ -0,0 +1,65 @@ +.. _configuration_memtx: + +In-memory storage +================= + +**Example on GitHub**: `memtx `_ + +In Tarantool, all data is stored in random-access memory (RAM) by default. +For this purpose, the :ref:`memtx ` storage engine is used. + +This topic describes how to define basic settings related to in-memory storage in the +:ref:`memtx ` section of a :ref:`YAML configuration ` +-- for example, :ref:`memory size ` and :ref:`maximum tuple size `. +For the specific settings related to allocator or sorting threads, +check the corresponding ``memtx`` options in the :ref:`Configuration reference `. + +.. NOTE:: + + To estimate the required amount of memory, you can use the + `sizing calculator `_. + +.. _configuration_memtx-memory: + +Memory size +----------- + +In Tarantool, data is stored in spaces. +Each space consists of tuples -- the database records. +To specify the amount of memory that Tarantool allocates to store tuples, use the +:ref:`memtx.memory ` configuration option. + +In the example below, the memory size is set to 1 GB (1073741824 bytes): + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/memtx/config.yaml + :language: yaml + :start-at: memtx: + :end-at: 1073741824 + :dedent: + +The server does not exceed this limit to allocate tuples. +For indexes and connection information, additional memory is used. + +When the ``memtx.memory`` limit is reached, ``INSERT`` or ``UPDATE`` requests fail with +:ref:`ER_MEMORY_ISSUE `. + +.. _configuration_memtx-tuple-size: + +Tuple size +---------- + +You can configure the minimum and the maximum tuple sizes in bytes. + +* If the tuples are small, you can decrease the minimum size. +* If the tuples are large, you can increase the maximum size. + +To define the tuple size, use the :ref:`memtx.min_tuple_size ` and +:ref:`memtx.max_tuple_size ` configuration options. + +In the example, the minimum size is set to 8 bytes and the maximum size is set to 5 MB: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/memtx/config.yaml + :language: yaml + :start-at: memtx: + :end-at: 5242880 + :dedent: diff --git a/doc/platform/storage/persistence.rst b/doc/platform/storage/persistence.rst new file mode 100644 index 0000000000..974df61115 --- /dev/null +++ b/doc/platform/storage/persistence.rst @@ -0,0 +1,305 @@ +.. _configuration_persistence: +.. _concepts-data_model-persistence: +.. _index-box_persistence: + +Persistence +=========== + +To ensure data persistence, Tarantool provides the abilities to: + +* Record each data change request into a write-ahead log (WAL) file (``.xlog`` files). + + When a power outage occurs or the Tarantool instance is killed incidentally, the in-memory database is lost. + In such case, Tarantool restores the data from WAL files by reading them and redoing the requests. + This is called the "recovery process". + +* Take internals-snapshot that contain an on-disk copy of the entire data set for a given moment + (``.snap`` files). + + During the recovery process, Tarantool can load the latest snapshot file and then read the requests from the WAL files, produced after this snapshot was made. + After creating a new snapshot, the earlier WAL files can be removed to free up space. + +This topic describes how to configure: + +* the snapshot creation in the :ref:`snapshot ` section of a :ref:`YAML configuration `. +* the recording to the write-ahead log in the :ref:`wal ` section of a YAML configuration. + +To learn more about the persistence mechanism in Tarantool, see the :ref:`Persistence ` section. +The formats of WAL and snapshot files are described in detail in the :ref:`File formats ` section. + +.. _configuration_persistence_snapshot: + +Configure the snapshots +----------------------- + +**Example on GitHub**: `snapshot `_ + +This section describes how to define snapshot settings in the :ref:`snapshot ` section of a YAML configuration. + +.. NOTE:: + + To force immediate creation of a snapshot file, use the + :doc:`box.snapshot() ` function. + +.. _configuration_persistence_snapshot_creation: + +Set up automatic snapshot creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Tarantool, it is possible to automate the snapshot creation. +Automatic creation is enabled by default and can be configured in two ways: + +* A new snapshot is taken once in a given period (see :ref:`snapshot.by.interval `). +* A new snapshot is taken once the size of all WAL files created since the last snapshot exceeds a given limit + (see :ref:`snapshot.by.wal_size `). + +The ``snapshot.by.interval`` option sets up the :ref:`checkpoint daemon ` +that takes a new snapshot every ``snapshot.by.interval`` seconds. +If the ``snapshot.by.interval`` option is set to zero, the checkpoint daemon is disabled. + +The ``snapshot.by.wal_size`` option defines the maximum size in bytes for all WAL files created since the last snapshot taken. +Once this size is exceeded, the checkpoint daemon takes a snapshot. Then, :ref:`Tarantool garbage collector ` +deletes the old WAL files. + +The example shows how to specify the ``snapshot.by.interval`` and the ``snapshot.by.wal_size`` options: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml + :language: yaml + :start-at: by: + :end-at: 1000000000000000000 + :dedent: + +In the example, a new snapshot is created in two cases: + +* every 2 hours (every 7200 seconds) +* when the size for all WAL files created since the last snapshot reaches the size of 1e18 (1000000000000000000) bytes. + +.. _configuration_persistence_snapshot_dir: + +Specify a directory for snapshot files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure a directory where the snapshot files are stored, use the :ref:`snapshot.dir ` +configuration option. +The example below shows how to specify a snapshot directory for ``instance001`` explicitly: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml + :language: yaml + :start-at: instance001: + :end-at: 'var/lib/{{ instance_name }}/snapshots' + :dedent: + +By default, WAL files and snapshot files are stored in the same directory ``var/lib/{{ instance_name }}``. +However, you can specify different directories for them. +For example, you can place snapshots and write-ahead logs on different hard drives for better reliability: + +.. code-block:: yaml + + instance001: + snapshot: + dir: '/media/drive1/snapshots' + wal: + dir: '/media/drive2/wals' + +.. _configuration_persistence_snapshot_count: + +Configure a maximum number of stored snapshots +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can set a limit on the number of snapshots stored in the :ref:`snapshot.dir ` +directory using the :ref:`snapshot.count ` option. +Once the number of snapshots reaches the given limit, :ref:`Tarantool garbage collector ` +deletes the oldest snapshot file and any associated WAL files after the new snapshot is taken. + +In the example below, the snapshot is created every two hours (every 7200 seconds) until there are three snapshots in the +``snapshot.dir`` directory. +After creating a new snapshot (the fourth one), the oldest snapshot and the corresponding WALs are deleted. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml + :language: yaml + :start-at: count: + :end-at: 7200 + :dedent: + +.. _configuration_persistence_wal: + +Configure the write-ahead log +----------------------------- + +**Example on GitHub**: `wal `_ + +This section describes how to define WAL settings in the :ref:`wal ` section of a YAML configuration. + +.. _configuration_persistence_wal_mode: + +Set the WAL mode +~~~~~~~~~~~~~~~~ + +The recording to the write-ahead log is enabled by default. +It means that if an instance restart occurs, the data will be recovered. +The recording to the WAL can be configured using the :ref:`wal.mode ` configuration option. + +There are two modes that enable writing to the WAL: + +* ``write`` (default) -- enable WAL and write the data without waiting for the data to be flushed to the storage device. +* ``fsync`` -- enable WAL and ensure that the record is written to the storage device. + +The example below shows how to specify the ``write`` WAL mode: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: mode: + :end-at: 'write' + :dedent: + +To turn the WAL writer off, set the ``wal.mode`` option to ``none``. + +.. _configuration_persistence_wal_dir: + +Specify a directory for WAL files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure a directory where the WAL files are stored, use the :ref:`wal.dir ` configuration option. +The example below shows how to specify a directory for ``instance001`` explicitly: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: instance001: + :end-at: 'var/lib/{{ instance_name }}/wals' + :dedent: + + +.. _configuration_persistence_wal_rescan: + +Set an interval between scans +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case of :ref:`replication ` or :ref:`hot standby ` mode, +Tarantool scans for changes in the WAL files every :ref:`wal.dir_rescan_delay ` +seconds. The example below shows how to specify the interval between scans: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: dir_rescan_delay + :end-before: cleanup_delay + :dedent: + +.. _configuration_persistence_wal_maxsize: + +Set a maximum size for the WAL file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A new WAL file is created when the current one reaches the :ref:`wal.max_size ` +size. The configuration for this option might look as follows: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: max_size + :end-at: 268435456 + :dedent: + +.. _configuration_persistence_cleanup_delay: + +Set a delay for the garbage collector +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Tarantool, the :ref:`checkpoint daemon ` +takes new snapshots at the given interval (see :ref:`snapshot.by.interval `). +After an instance restart, the Tarantool garbage collector deletes the old WAL files. + +To delay the immediate deletion of WAL files, use the :ref:`wal.cleanup_delay ` +configuration option. The delay eliminates possible erroneous situations when the master deletes WALs +needed by :ref:`replicas ` after restart. +As a consequence, replicas sync with the master faster after its restart and +don't need to download all the data again. + +In the example, the delay is set to 5 hours (18000 seconds): + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: cleanup_delay + :end-at: 18000 + :dedent: + +.. _configuration_persistence_wal_ext: + +Specify the WAL extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Tarantool Enterprise, you can store an old and new tuple for each CRUD operation performed. +A detailed description and examples of the WAL extensions are provided in the :ref:`WAL extensions ` section. + +See also: :ref:`wal.ext.* ` configuration options. + +.. _configuration_persistence_checkpoint_daemon: + +Checkpoint daemon +----------------- + +The checkpoint daemon (snapshot daemon) is a constantly running :ref:`fiber `. +The checkpoint daemon creates a schedule for the periodic snapshot creation based on +the :ref:`configuration options ` and the speed of file size growth. +If enabled, the daemon makes new :ref:`snapshot ` (``.snap``) files according to this schedule. + +The work of the checkpoint daemon is based on the following configuration options: + +* :ref:`snapshot.by.interval ` -- a new snapshot is taken once in a given period. +* :ref:`snapshot.by.wal_size ` -- a new snapshot is taken once the size + of all WAL files created since the last snapshot exceeds a given limit. + +If necessary, the checkpoint daemon also activates the :ref:`Tarantool garbage collector ` +that deletes old snapshots and WAL files. + +.. NOTE:: + + The memtx engine takes only regular snapshots with the interval set in + the checkpoint daemon configuration. + + The vinyl engine runs checkpointing in the background at all times. + + +.. _configuration_persistence_garbage_collector: + +Tarantool garbage collector +--------------------------- + +Tarantool garbage collector can be activated by the :ref:`checkpoint daemon `. +The garbage collector tracks the snapshots that are to be :ref:`relayed to a replica ` or needed +by other consumers. When the files are no longer needed, Tarantool garbage collector deletes them. + +.. NOTE:: + + The garbage collector called by the checkpoint daemon is distinct from the `Lua garbage collector `_ + which is for Lua objects, and distinct from the Tarantool garbage collector that specializes in :ref:`handling shard buckets `. + +This garbage collector is called as follows: + +* When the number of snapshots reaches the limit of :ref:`snapshot.count ` size. + After a new snapshot is taken, Tarantool garbage collector deletes the oldest snapshot file and any associated WAL files. + +* When the size of all WAL files created since the last snapshot reaches the limit of :ref:`snapshot.by.wal_size `. + Once this size is exceeded, the checkpoint daemon takes a snapshot, then the garbage collector deletes the old WAL files. + +If an old snapshot file is deleted, the Tarantool garbage collector also deletes +any :ref:`write-ahead log (.xlog) ` files that meet the following conditions: + +* The WAL files are older than the snapshot file. +* The WAL files contain information present in the snapshot file. + +Tarantool garbage collector also deletes obsolete vinyl ``.run`` files. + +Tarantool garbage collector doesn't delete a file in the following cases: + +* A backup is running, and the file has not been backed up + (see :ref:`Hot backup `). + +* Replication is running, and the file has not been relayed to a replica + (see :ref:`Replication architecture `), + +* A replica is connecting. + +* A replica has fallen behind. + The progress of each replica is tracked; if a replica's position is far + from being up to date, then the server stops to give it a chance to catch up. + If an administrator concludes that a replica is permanently down, then the + correct procedure is to restart the server, or (preferably) :ref:`remove the replica from the cluster `. diff --git a/doc/platform/storage/wal_extensions.rst b/doc/platform/storage/wal_extensions.rst new file mode 100644 index 0000000000..61c50eda59 --- /dev/null +++ b/doc/platform/storage/wal_extensions.rst @@ -0,0 +1,109 @@ +.. _wal_extensions: + +WAL extensions +============== + +.. admonition:: Enterprise Edition + :class: fact + + WAL extensions are available in the `Enterprise Edition `_ only. + +WAL extensions allow you to add auxiliary information to each :ref:`write-ahead log ` record. +For example, you can enable storing an old and new tuple for each CRUD operation performed. +This information might be helpful for implementing a CDC (Change Data Capture) utility +that transforms a data replication stream. + +See also: :ref:`Configure the write-ahead log `. + +.. _wal_extensions_configuration: + +Configuration +------------- + +WAL extensions are disabled by default. +To configure them, use the :ref:`wal.ext.* ` configuration options. +Inside the ``wal.ext`` block, you can enable storing old and new tuples as follows: + +* To store old and new tuples in a write-ahead log for all spaces, set the + :ref:`wal.ext.old ` and :ref:`wal.ext.new ` + options to ``true``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: ext: + :end-at: old: true + :dedent: + +* To adjust these options for specific spaces, specify the :ref:`wal.ext.spaces ` option: + + .. code-block:: yaml + + wal: + ext: + old: true + new: true + spaces: + space1: + old: false + space2: + new: false + + The configuration for specific spaces has priority over the configuration in the ``wal.ext.new`` and ``wal.ext.old`` + options. + It means that only new tuples are added to the log for ``space1`` and only old tuples for ``space2``. + +Note that records with additional fields are :ref:`replicated ` as follows: + +* If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped. +* If a replica and master have different configurations for WAL records, the master's configuration is ignored. + +.. _wal_extensions_example: + +Example +------- + +The table below demonstrates how write-ahead log records might look +for the specific :ref:`CRUD operations ` +if storing old and new tuples is enabled for the ``bands`` space. + +.. container:: table + + .. list-table:: + :widths: 10 50 40 + :header-rows: 1 + + * - Operation + - Example + - WAL information + * - insert + - ``bands:insert{4, 'The Beatles', 1960}`` + - | **new_tuple**: [4, 'The Beatles', 1960] + | tuple: [4, 'The Beatles', 1960] + * - delete + - ``bands:delete{4}`` + - | key: [4] + | **old_tuple**: [4, 'The Beatles', 1960] + * - update + - ``bands:update({2}, {{'=', 2, 'Pink Floyd'}})`` + - | **new_tuple**: [2, 'Pink Floyd', 1965] + | **old_tuple**: [2, 'Scorpions', 1965] + | key: [2] + | tuple: [['=', 2, 'Pink Floyd']] + * - upsert + - ``bands:upsert({2, 'Pink Floyd', 1965}, {{'=', 2, 'The Doors'}})`` + - | **new_tuple**: [2, 'The Doors', 1965] + | **old_tuple**: [2, 'Pink Floyd', 1965] + | operations: [['=', 2, 'The Doors']] + | tuple: [2, 'Pink Floyd', 1965] + * - replace + - ``bands:replace{1, 'The Beatles', 1960}`` + - | **old_tuple**: [1, 'Roxette', 1986] + | **new_tuple**: [1, 'The Beatles', 1960] + | tuple: [1, 'The Beatles', 1960] + +Storing both old and new tuples is especially useful for the ``update`` +operation because a write-ahead log record contains only a key value. + +.. NOTE:: + + You can use the :ref:`tt-cat` command to see the contents of a write-ahead log. diff --git a/doc/concepts/triggers.rst b/doc/platform/triggers.rst similarity index 100% rename from doc/concepts/triggers.rst rename to doc/platform/triggers.rst diff --git a/doc/reference/configuration/cfg_audit.rst b/doc/reference/configuration/cfg_audit.rst new file mode 100644 index 0000000000..364cbedd7a --- /dev/null +++ b/doc/reference/configuration/cfg_audit.rst @@ -0,0 +1,259 @@ +.. _cfg_audit: + +.. admonition:: Enterprise Edition + :class: fact + + Audit log features are available in the `Enterprise Edition `_ only. + +The ``audit_*`` parameters define configuration related to :ref:`audit logging `. + +* :ref:`audit_extract_key ` +* :ref:`audit_filter ` +* :ref:`audit_format ` +* :ref:`audit_log ` +* :ref:`audit_nonblock ` +* :ref:`audit_spaces ` + +.. _cfg_audit_extract_key: + +.. confval:: audit_extract_key + + **Since:** :doc:`3.0.0 `. + + If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full + tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``). + Otherwise, full tuples are logged. + The option may be useful in case tuples are big. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_EXTRACT_KEY + +.. _cfg_audit_filter: + +.. confval:: audit_filter + + Enable logging for a specified subset of audit events. + This option accepts the following values: + + * Event names (for example, ``password_change``). For details, see :ref:`Audit log events `. + * Event groups (for example, ``audit``). For details, see :ref:`Event groups `. + + The option contains either one value from ``Possible values`` section (see below) or a combination of them. + + To enable :ref:`custom audit log events `, specify the ``custom`` value in this option. + + The default value is ``compatibility``, which enables logging of all events available before 2.10.0. + + **Example** + + .. code-block:: lua + + box.cfg{ + audit_log = 'audit.log', + audit_filter = 'audit,auth,priv,password_change,access_denied' + } + + | + | Type: array + | Possible values: 'all', 'audit', 'auth', 'priv', 'ddl', 'dml', 'data_operations', 'compatibility', + 'audit_enable', 'auth_ok', 'auth_fail', 'disconnect', 'user_create', 'user_drop', 'role_create', 'role_drop', + 'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change', + 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', + 'space_replace', 'space_delete', 'custom' + | Default: 'compatibility' + | Environment variable: TT_AUDIT_FILTER + +.. _cfg_audit_format: + +.. confval:: audit_format + + Specify the format that is used for the audit log events -- plain text, CSV or JSON format. + + Plain text is used by default. This human-readable format can be efficiently compressed. + + .. code-block:: lua + + box.cfg{audit_log = 'audit.log', audit_format = 'plain'} + + **Example** + + .. code-block:: text + + remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[5e35b406-4274-4903-857b-c80115275940] subj: "anonymous", msg: "Access granted to anonymous user" + + The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. + + .. code-block:: lua + + box.cfg{audit_log = 'audit.log', audit_format = 'json'} + + **Example** + + .. code-block:: json + + {"time": "2022-11-17T21:55:49.880+0300", "remote": "", "session_type": "background", "module": "common.admin.auth", "user": "", "type": "custom_tdg_audit", "tag": "tdg_severity_INFO", "description": "[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \"anonymous\", msg: \"Access granted to anonymous user\""} + + Using the CSV format allows you to view audit log events in tabular form. + + .. code-block:: lua + + box.cfg{audit_log = 'audit.log', audit_format = 'csv'} + + **Example** + + .. code-block:: text + + 2022-11-17T21:58:03.131+0300,,background,common.admin.auth,,,custom_tdg_audit,tdg_severity_INFO,"[b3dfe2a3-ec29-4e61-b747-eb2332c83b2e] subj: ""anonymous"", msg: ""Access granted to anonymous user""" + + | + | Type: string + | Possible values: 'json', 'csv', 'plain' + | Default: 'json' + | Environment variable: TT_AUDIT_FORMAT + +.. _cfg_audit_log: + +.. confval:: audit_log + + Enable audit logging and define the log location. + + This option accepts a string value that allows you to define the log location. + The following locations are supported: + + - File: to write audit logs to a file, specify a path to a file (with an optional `file` prefix) + - Pipeline: to start a program and write audit logs to it, specify a program name (with `|` or `pipe` prefix) + - System log: to write audit logs to a system log, specify a message for `syslogd` (with `syslog` prefix) + + See the examples below. + + By default, audit logging is disabled. + + **Example: Writing to a file** + + .. code-block:: lua + + box.cfg{audit_log = 'audit_tarantool.log'} + -- or + box.cfg{audit_log = 'file:audit_tarantool.log'} + + This opens the ``audit_tarantool.log`` file for output in the server’s default directory. + If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path. + + If you log to a file, Tarantool will reopen the audit log at `SIGHUP `_. + + **Example: Sending to a pipeline** + + .. code-block:: lua + + box.cfg{audit_log = '| cronolog audit_tarantool.log'} + -- or + box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}' + + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog's standard input (``stdin``). + If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, + the string is interpreted as a Unix `pipeline `_. + + If log is a program, check out its pid and send it a signal to rotate logs. + + **Example: Writing to a system log** + + .. warning:: + + Below is an example of writing audit logs to a directory shared with the system logs. + Tarantool allows this option, but it is **not recommended** to do this to avoid difficulties + when working with audit logs. System and audit logs should be written separately. + To do this, create separate paths and specify them. + + This sample configuration sends the audit log to syslog: + + .. code-block:: lua + + box.cfg{audit_log = 'syslog:identity=tarantool'} + -- or + box.cfg{audit_log = 'syslog:facility=user'} + -- or + box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'} + -- or + box.cfg{audit_log = 'syslog:server=unix:/dev/log'} + + If the ``audit_log`` string starts with "syslog:", + it is interpreted as a message for the `syslogd `_ program, + which normally runs in the background of any Unix-like platform. + The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination. + + The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages. + The default value is ``tarantool``. + + The ``syslog:facility`` setting is currently ignored, but will be used in the future. + The value must be one of the `syslog `_ keywords + that tell ``syslogd`` where to send the message. + The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``, + ``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``, + ``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``. + The default value is ``local7``. + + The ``syslog:server`` setting is the locator for the syslog server. + It can be a Unix socket path starting with "unix:" or an ipv4 port number. + The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS). + The default port value is 514, which is the UDP port. + + An example of a Tarantool audit log entry in the syslog: + + .. code-block:: json + + 09:32:52 tarantool_audit: {"time": "2024-02-08T09:32:52.190+0300", "uuid": "94454e46-9a0e-493a-bb9f-d59e44a43581", "severity": "INFO", "remote": "unix/:(socket)", "session_type": "console", "module": "tarantool", "user": "admin", "type": "space_create", "tag": "", "description": "Create space bands"} + + | + | Type: string + | Possible values: see the string format above + | Default: 'nill' + | Environment variable: TT_AUDIT_LOG + +.. _cfg_audit_nonblock: + +.. confval:: audit_nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`audit_log ` is set to ``syslog`` + or ``pipe``. + + Setting ``audit_nonblock`` to ``true`` is not allowed if the output is to a file. + In this case, set ``audit_nonblock`` to ``false``. + + | + | Type: boolean + | Default: true + | Environment variable: TT_AUDIT_NONBLOCK + +.. _cfg_audit_spaces: + +.. confval:: audit_spaces + + **Since:** :doc:`3.0.0 `. + + The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, + ``space_delete``) should be logged. The array accepts string values. + If set to :ref:`box.NULL `, the data operation events are logged for all spaces. + + **Example** + + In the example, only the events of ``bands`` and ``singers`` spaces are logged: + + .. code-block:: lua + + box.cfg{ + audit_spaces = 'bands,singers' + } + + | + | Type: array + | Default: box.NULL + | Environment variable: TT_AUDIT_SPACES diff --git a/doc/reference/configuration/cfg_authentication.rst b/doc/reference/configuration/cfg_authentication.rst new file mode 100644 index 0000000000..b445f36e9b --- /dev/null +++ b/doc/reference/configuration/cfg_authentication.rst @@ -0,0 +1,238 @@ +.. _cfg_authentication: + +.. admonition:: Enterprise Edition + :class: fact + + Authentication features are supported by the `Enterprise Edition `_ only. + +* :ref:`auth_delay ` +* :ref:`auth_retries ` +* :ref:`auth_type ` +* :ref:`disable_guest ` +* :ref:`password_min_length ` +* :ref:`password_enforce_uppercase ` +* :ref:`password_enforce_lowercase ` +* :ref:`password_enforce_digits ` +* :ref:`password_enforce_specialchars ` +* :ref:`password_lifetime_days ` +* :ref:`password_history_length ` + + +.. _cfg_auth_delay: + +.. confval:: auth_delay + + Since :doc:`2.11.0 `. + + Specify a period of time (in seconds) that a specific user should wait + for the next attempt after failed authentication. + + With the configuration below, Tarantool refuses the authentication attempt if the previous + attempt was less than 5 seconds ago. + + .. code-block:: lua + + box.cfg{ auth_delay = 5 } + + + | + | Type: number + | Default: 0 + | Environment variable: TT_AUTH_DELAY + | Dynamic: yes + +.. _cfg_auth_retries: + +.. confval:: auth_retries + + Since :doc:`3.0.0 `. + + Specify the maximum number of authentication retries allowed before ``auth_delay`` is enforced. + The default value is 0, which means ``auth_delay`` is enforced after the first failed authentication attempt. + + The retry counter is reset after ``auth_delay`` seconds since the first failed attempt. + For example, if a client tries to authenticate fewer than ``auth_retries`` times within ``auth_delay`` seconds, no authentication delay is enforced. + The retry counter is also reset after any successful authentication attempt. + + | + | Type: number + | Default: 0 + | Environment variable: TT_AUTH_RETRIES + | Dynamic: yes + + +.. _cfg_auth_type: + +.. confval:: auth_type + + Since :doc:`2.11.0 `. + + Specify an authentication protocol: + + - 'chap-sha1': use the `CHAP `_ protocol to authenticate users with ``SHA-1`` hashing applied to :ref:`passwords `. + - 'pap-sha256': use `PAP `_ authentication with the ``SHA256`` hashing algorithm. + + For new users, the :doc:`box.schema.user.create ` method + will generate authentication data using ``PAP-SHA256``. + For existing users, you need to reset a password using + :doc:`box.schema.user.passwd ` + to use the new authentication protocol. + + | + | Type: string + | Default value: 'chap-sha1' + | Environment variable: TT_AUTH_TYPE + | Dynamic: yes + + +.. _cfg_disable_guest: + +.. confval:: disable_guest + + Since :doc:`2.11.0 `. + + If **true**, disables access over remote connections + from unauthenticated or :ref:`guest access ` users. + This option affects both + :doc:`net.box ` and + :ref:`replication ` connections. + + | + | Type: boolean + | Default: false + | Environment variable: TT_DISABLE_GUEST + | Dynamic: yes + +.. _cfg_password_min_length: + +.. confval:: password_min_length + + Since :doc:`2.11.0 `. + + Specify the minimum number of characters for a password. + + The following example shows how to set the minimum password length to 10. + + .. code-block:: lua + + box.cfg{ password_min_length = 10 } + + | + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_MIN_LENGTH + | Dynamic: yes + + +.. _cfg_password_enforce_uppercase: + +.. confval:: password_enforce_uppercase + + Since :doc:`2.11.0 `. + + If **true**, a password should contain uppercase letters (A-Z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE + | Dynamic: yes + + +.. _cfg_password_enforce_lowercase: + +.. confval:: password_enforce_lowercase + + Since :doc:`2.11.0 `. + + If **true**, a password should contain lowercase letters (a-z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE + | Dynamic: yes + + +.. _cfg_password_enforce_digits: + +.. confval:: password_enforce_digits + + Since :doc:`2.11.0 `. + + If **true**, a password should contain digits (0-9). + + | + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_DIGITS + | Dynamic: yes + + +.. _cfg_password_enforce_specialchars: + +.. confval:: password_enforce_specialchars + + Since :doc:`2.11.0 `. + + If **true**, a password should contain at least one special character (such as ``&|?!@$``). + + | + | Type: boolean + | Default: false + | Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS + | Dynamic: yes + + +.. _cfg_password_lifetime_days: + +.. confval:: password_lifetime_days + + Since :doc:`2.11.0 `. + + Specify the maximum period of time (in days) a user can use the same password. + When this period ends, a user gets the "Password expired" error on a login attempt. + To restore access for such users, use :doc:`box.schema.user.passwd `. + + .. note:: + + The default 0 value means that a password never expires. + + The example below shows how to set a maximum password age to 365 days. + + .. code-block:: lua + + box.cfg{ password_lifetime_days = 365 } + + | + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_LIFETIME_DAYS + | Dynamic: yes + + +.. _cfg_password_history_length: + +.. confval:: password_history_length + + Since :doc:`2.11.0 `. + + Specify the number of unique new user passwords before an old password can be reused. + + In the example below, a new password should differ from the last three passwords. + + .. code-block:: lua + + box.cfg{ password_history_length = 3 } + + | + | Type: integer + | Default: 0 + | Environment variable: TT_PASSWORD_HISTORY_LENGTH + | Dynamic: yes + + .. note:: + Tarantool uses the ``auth_history`` field in the + :doc:`box.space._user ` + system space to store user passwords. + diff --git a/doc/reference/configuration/cfg_basic.rst b/doc/reference/configuration/cfg_basic.rst index acb08806e5..cf240acf71 100644 --- a/doc/reference/configuration/cfg_basic.rst +++ b/doc/reference/configuration/cfg_basic.rst @@ -1,4 +1,5 @@ * :ref:`background ` +* :ref:`coredump ` * :ref:`custom_proc_title ` * :ref:`listen ` * :ref:`memtx_dir ` @@ -19,20 +20,53 @@ .. confval:: background Since version 1.6.2. + Run the server as a background task. The :ref:`log ` and :ref:`pid_file ` parameters must be non-null for this to work. + .. important:: + + Do not enable the background mode for applications intended to run by the + ``tt`` utility. For more information, see the :ref:`tt start ` reference. + + | | Type: boolean | Default: false | Environment variable: TT_BACKGROUND | Dynamic: no +.. _cfg_basic-coredump: + +.. confval:: coredump + + Create coredump files. + + Usually, an administrator needs to call ``ulimit -c unlimited`` + (or set corresponding options in systemd's unit file) + before running a Tarantool process to get core dumps. + If ``coredump`` is enabled, Tarantool sets the corresponding + resource limit by itself + and the administrator doesn't need to call ``ulimit -c unlimited`` + (see `man 3 setrlimit `_). + + This option also sets the state of the ``dumpable`` attribute, + which is enabled by default, + but may be dropped in some circumstances (according to + `man 2 prctl `_, see PR_SET_DUMPABLE). + + | + | Type: boolean + | Environment variable: TT_COREDUMP + | Default: false + | Dynamic: no + .. _cfg_basic-custom_proc_title: .. confval:: custom_proc_title Since version 1.6.7. + Add the given string to the server's process title (what’s shown in the COMMAND column for ``ps -ef`` and ``top -c`` commands). @@ -53,6 +87,7 @@ $ ps -ef | grep tarantool 1000 14939 14188 1 10:53 pts/2 00:00:16 tarantool : sessions + | | Type: string | Default: null | Environment variable: TT_CUSTOM_PROC_TITLE @@ -87,6 +122,7 @@ Starting from version 2.10.0, you can specify :ref:`several URIs `, and the port number is always stored as an integer value. + | | Type: integer or string | Default: null | Environment variable: TT_LISTEN @@ -97,10 +133,15 @@ .. confval:: memtx_dir Since version 1.7.4. - A directory where memtx stores snapshot (.snap) files. Can be relative to - :ref:`work_dir `. If not specified, defaults to - ``work_dir``. See also :ref:`wal_dir `. + A directory where memtx stores snapshot (``.snap``) files. + A relative path in this option is interpreted as relative to :ref:`work_dir `. + + By default, snapshots and WAL files are stored in the same directory. + However, you can set different values for the ``memtx_dir`` and :ref:`wal_dir ` options + to store them on different physical disks for performance matters. + + | | Type: string | Default: "." | Environment variable: TT_MEMTX_DIR @@ -111,9 +152,11 @@ .. confval:: pid_file Since version 1.4.9. + Store the process id in this file. Can be relative to :ref:`work_dir `. A typical value is “:file:`tarantool.pid`”. + | | Type: string | Default: null | Environment variable: TT_PID_FILE @@ -124,6 +167,7 @@ .. confval:: read_only Since version 1.7.1. + Say ``box.cfg{read_only=true...}`` to put the server instance in read-only mode. After this, any requests that try to change persistent data will fail with error :errcode:`ER_READONLY`. Read-only mode should be used for master-replica @@ -133,6 +177,7 @@ Although read-only mode prevents the server from writing to the :ref:`WAL `, it does not prevent writing diagnostics with the :ref:`log module `. + | | Type: boolean | Default: false | Environment variable: TT_READ_ONLY @@ -160,11 +205,13 @@ .. confval:: sql_cache_size Since version 2.3.1. + The maximum number of bytes in the cache for :ref:`SQL prepared statements `. (The number of bytes that are actually used can be seen with :ref:`box.info.sql().cache.size `.) + | | Type: number | Default: 5242880 | Environment variable: TT_SQL_CACHE_SIZE @@ -175,10 +222,12 @@ .. confval:: vinyl_dir Since version 1.7.1. + A directory where vinyl files or subdirectories will be stored. Can be relative to :ref:`work_dir `. If not specified, defaults to ``work_dir``. + | | Type: string | Default: "." | Environment variable: TT_VINYL_DIR @@ -189,6 +238,7 @@ .. confval:: vinyl_timeout Since version 1.7.5. + The vinyl storage engine has a scheduler which does compaction. When vinyl is low on available memory, the compaction scheduler may be unable to keep up with incoming update requests. @@ -198,6 +248,7 @@ Compaction can also be ordered manually with :doc:`/reference/reference_lua/box_index/compact`. + | | Type: float | Default: 60 | Environment variable: TT_VINYL_TIMEOUT @@ -207,8 +258,11 @@ .. confval:: username - Since version 1.4.9. UNIX user name to switch to after start. + Since version 1.4.9. + + UNIX user name to switch to after start. + | | Type: string | Default: null | Environment variable: TT_USERNAME @@ -219,12 +273,15 @@ .. confval:: wal_dir Since version 1.6.2. - A directory where write-ahead log (.xlog) files are stored. Can be relative - to :ref:`work_dir `. Sometimes ``wal_dir`` and - :ref:`memtx_dir ` are specified with different values, so - that write-ahead log files and snapshot files can be stored on different - disks. If not specified, defaults to ``work_dir``. + A directory where write-ahead log (``.xlog``) files are stored. + A relative path in this option is interpreted as relative to :ref:`work_dir `. + + By default, WAL files and snapshots are stored in the same directory. + However, you can set different values for the ``wal_dir`` and :ref:`memtx_dir ` options + to store them on different physical disks for performance matters. + + | | Type: string | Default: "." | Environment variable: TT_WAL_DIR @@ -235,6 +292,7 @@ .. confval:: work_dir Since version 1.4.9. + A directory where database working files will be stored. The server instance switches to ``work_dir`` with :manpage:`chdir(2)` after start. Can be relative to the current directory. If not specified, defaults to @@ -252,6 +310,7 @@ will put xlog files in ``/home/user/A/B``, snapshot files in ``/home/user/A/C``, and all other files or subdirectories in ``/home/user/A``. + | | Type: string | Default: null | Environment variable: TT_WORK_DIR @@ -263,11 +322,13 @@ .. confval:: worker_pool_threads Since version 1.7.5. + The maximum number of threads to use during execution of certain internal processes (currently :ref:`socket.getaddrinfo() ` and :ref:`coio_call() `). + | | Type: integer | Default: 4 | Environment variable: TT_WORKER_POOL_THREADS @@ -277,11 +338,14 @@ .. confval:: strip_core - Since version 2.2.2. Whether coredump files should include memory allocated for tuples. + Since version 2.2.2. + + Whether coredump files should include memory allocated for tuples. (This can be large if Tarantool runs under heavy load.) Setting to ``true`` means "do not include". In an older version of Tarantool the default value of this parameter was ``false``. + | | Type: boolean | Default: true | Environment variable: TT_STRIP_CORE @@ -292,8 +356,10 @@ .. confval:: memtx_use_mvcc_engine Since version :doc:`2.6.1 `. - Enables :ref:`transactional manager ` if set to ``true``. + Enable :ref:`transactional manager ` if set to ``true``. + + | | Type: boolean | Default: false | Environment variable: TT_MEMTX_USE_MVCC_ENGINE diff --git a/doc/reference/configuration/cfg_binary_logging_snapshots.rst b/doc/reference/configuration/cfg_binary_logging_snapshots.rst index 3d0bcdb1b1..942e28db7e 100644 --- a/doc/reference/configuration/cfg_binary_logging_snapshots.rst +++ b/doc/reference/configuration/cfg_binary_logging_snapshots.rst @@ -5,12 +5,15 @@ * :ref:`wal_dir_rescan_delay ` * :ref:`wal_queue_max_size ` * :ref:`wal_cleanup_delay ` +* :ref:`wal_ext ` +* :ref:`secure_erasing ` .. _cfg_binary_logging_snapshots-force_recovery: .. confval:: force_recovery Since version 1.7.4. + If ``force_recovery`` equals true, Tarantool tries to continue if there is an error while reading a :ref:`snapshot file` (at server instance start) or a :ref:`write-ahead log file` @@ -21,6 +24,7 @@ Otherwise, Tarantool aborts recovery if there is an error while reading. + | | Type: boolean | Default: false | Environment variable: TT_FORCE_RECOVERY @@ -31,10 +35,12 @@ .. confval:: wal_max_size Since version 1.7.4. + The maximum number of bytes in a single write-ahead log file. - When a request would cause an .xlog file to become larger than - ``wal_max_size``, Tarantool creates another WAL file. + When a request would cause an ``.xlog`` file to become larger than + ``wal_max_size``, Tarantool creates a new WAL file. + | | Type: integer | Default: 268435456 (256 * 1024 * 1024) bytes | Environment variable: TT_WAL_MAX_SIZE @@ -45,6 +51,7 @@ .. confval:: snap_io_rate_limit Since version 1.4.9. + Reduce the throttling effect of :doc:`box.snapshot() ` on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be @@ -53,26 +60,32 @@ locations and moving snapshots to a separate disk. The limit also affects what :ref:`box.stat.vinyl().regulator ` - may show for the write rate of dumps to .run and .index files. + may show for the write rate of dumps to ``.run`` and ``.index`` files. + | | Type: float | Default: null | Environment variable: TT_SNAP_IO_RATE_LIMIT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_snapshots-wal_mode: .. confval:: wal_mode - Since version 1.6.2. Specify fiber-WAL-disk synchronization mode as: + Since version 1.6.2. + + Specify fiber-WAL-disk synchronization mode as: - * ``none``: write-ahead log is not maintained. - A node with ``wal_mode = none`` can't be replication master; - * ``write``: :ref:`fibers ` wait for their data to be written to - the write-ahead log (no :manpage:`fsync(2)`); - * ``fsync``: fibers wait for their data, :manpage:`fsync(2)` - follows each :manpage:`write(2)`; + * ``none``: write-ahead log is not maintained. + A node with ``wal_mode`` set to ``none`` can't be a replication master. + * ``write``: :ref:`fibers ` wait for their data to be written to + the write-ahead log (no :manpage:`fsync(2)`). + + * ``fsync``: fibers wait for their data, :manpage:`fsync(2)` + follows each :manpage:`write(2)`. + + | | Type: string | Default: "write" | Environment variable: TT_WAL_MODE @@ -83,10 +96,12 @@ .. confval:: wal_dir_rescan_delay Since version 1.6.2. - Number of seconds between periodic scans of the write-ahead-log + + The time interval in seconds between periodic scans of the write-ahead-log file directory, when checking for changes to write-ahead-log files for the sake of :ref:`replication ` or :ref:`hot standby `. + | | Type: float | Default: 2 | Environment variable: TT_WAL_DIR_RESCAN_DELAY @@ -97,6 +112,7 @@ .. confval:: wal_queue_max_size Since version :doc:`2.8.1 `. + The size of the queue (in bytes) used by a :ref:`replica ` to submit new transactions to a :ref:`write-ahead log` (WAL). This option helps limit the rate at which a replica submits transactions to the WAL. @@ -108,32 +124,100 @@ You might consider increasing the ``wal_queue_max_size`` value in case of large tuples (approximately one megabyte or larger). + | | Type: number | Default: 16777216 bytes | Environment variable: TT_WAL_QUEUE_MAX_SIZE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_binary_logging_snapshots-wal_cleanup_delay: .. confval:: wal_cleanup_delay Since version :doc:`2.6.3 `. - The delay (in seconds) used to prevent the :ref:`Tarantool garbage collector ` - from immediately removing :ref:`write-ahead log` files after a node restart. + + The delay in seconds used to prevent the :ref:`Tarantool garbage collector ` + from immediately removing :ref:`write-ahead log ` files after a node restart. This delay eliminates possible erroneous situations when the master deletes WALs needed by :ref:`replicas ` after restart. As a consequence, replicas sync with the master faster after its restart and don't need to download all the data again. - - Once all the nodes in the replica set are up and running, - automatic cleanup is started again even if ``wal_cleanup_delay`` has not expired. + Once all the nodes in the replica set are up and running, a scheduled garbage collection is started again + even if ``wal_cleanup_delay`` has not expired. .. NOTE:: The ``wal_cleanup_delay`` option has no effect on nodes running as - :ref:`anonymous replicas`. + :ref:`anonymous replicas `. + | | Type: number | Default: 14400 seconds | Environment variable: TT_WAL_CLEANUP_DELAY - | Dynamic: **yes** \ No newline at end of file + | Dynamic: yes + + +.. _cfg_binary_logging_snapshots-wal_ext: + +.. confval:: wal_ext + + Since version :doc:`2.11.0 `. + + (**Enterprise Edition only**) Allows you to add auxiliary information to each :ref:`write-ahead log ` record. + For example, you can enable storing an old and new tuple for each CRUD operation performed. + This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream. + + You can enable storing old and new tuples as follows: + + * Set the ``old`` and ``new`` options to ``true`` to store old and new tuples in a write-ahead log for all spaces. + + .. code-block:: lua + + box.cfg { + wal_ext = { old = true, new = true } + } + + * To adjust these options for specific spaces, use the ``spaces`` option. + + .. code-block:: lua + + box.cfg { + wal_ext = { + old = true, new = true, + spaces = { + space1 = { old = false }, + space2 = { new = false } + } + } + } + + + The configuration for specific spaces has priority over the global configuration, + so only new tuples are added to the log for ``space1`` and only old tuples for ``space2``. + + Note that records with additional fields are :ref:`replicated ` as follows: + + * If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped. + * If a replica and master have different configurations for WAL records, the master's configuration is ignored. + + | + | Type: map + | Default: nil + | Environment variable: TT_WAL_EXT + | Dynamic: yes + + +.. _cfg_binary_logging_secure_erasing: + +.. confval:: secure_erasing + + Since version :doc:`3.0.0 `. + + (**Enterprise Edition only**) If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. + The option applies to both ``.xlog`` and ``.snap`` files as well as Vinyl data files. + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURE_ERASING + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_deprecated.rst b/doc/reference/configuration/cfg_deprecated.rst index 7d291d1716..95f3e8d061 100644 --- a/doc/reference/configuration/cfg_deprecated.rst +++ b/doc/reference/configuration/cfg_deprecated.rst @@ -2,7 +2,6 @@ These parameters are deprecated since Tarantool version 1.7.4: -* :ref:`coredump ` * :ref:`logger ` * :ref:`logger_nonblock ` * :ref:`panic_on_snap_error `, @@ -17,16 +16,6 @@ These parameters are deprecated since Tarantool version 1.7.4: * :ref:`rows_per_wal ` * :ref:`election_fencing_enabled ` -.. _cfg_basic-coredump_deprecated: - -.. confval:: coredump - - **Deprecated**, do not use. - - | Type: boolean - | Default: false - | Dynamic: no - .. _cfg_logging-logger_deprecated: .. confval:: logger @@ -53,6 +42,7 @@ These parameters are deprecated since Tarantool version 1.7.4: If there is an error while reading a snapshot file (at server instance start), abort. + | | Type: boolean | Default: true | Dynamic: no @@ -64,6 +54,7 @@ These parameters are deprecated since Tarantool version 1.7.4: **Deprecated** in favor of :ref:`force_recovery `. + | | Type: boolean | Default: true | Dynamic: yes @@ -91,6 +82,7 @@ These parameters are deprecated since Tarantool version 1.7.4: indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than the limit set here. + | | Type: float | Default: 1.0 | Dynamic: no @@ -160,6 +152,7 @@ These parameters are deprecated since Tarantool version 1.7.4: Setting to ``false`` is equivalent to setting the ``off`` :ref:`election_fencing_mode `. + | | Type: boolean | Default: true | Environment variable: TT_ELECTION_FENCING_ENABLED diff --git a/doc/reference/configuration/cfg_feedback.rst b/doc/reference/configuration/cfg_feedback.rst index e91b5de398..f716495010 100644 --- a/doc/reference/configuration/cfg_feedback.rst +++ b/doc/reference/configuration/cfg_feedback.rst @@ -15,35 +15,44 @@ adjust or turn off this feature. .. confval:: feedback_enabled - Since version 1.10.1. Whether to send feedback. + Since version 1.10.1. + + Whether to send feedback. If this is set to ``true``, feedback will be sent as described above. If this is set to ``false``, no feedback will be sent. + | | Type: boolean | Default: true | Environment variable: TT_FEEDBACK_ENABLED - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-feedback_host: .. confval:: feedback_host - Since version 1.10.1. The address to which the packet is sent. + Since version 1.10.1. + + The address to which the packet is sent. Usually the recipient is Tarantool, but it can be any URL. + | | Type: string | Default: ``https://feedback.tarantool.io`` | Environment variable: TT_FEEDBACK_HOST - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-feedback_interval: .. confval:: feedback_interval - Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour). + Since version 1.10.1. + + The number of seconds between sendings, usually 3600 (1 hour). + | | Type: float | Default: 3600 | Environment variable: TT_FEEDBACK_INTERVAL - | Dynamic: **yes** + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_flight_recorder.rst b/doc/reference/configuration/cfg_flight_recorder.rst new file mode 100644 index 0000000000..1319264740 --- /dev/null +++ b/doc/reference/configuration/cfg_flight_recorder.rst @@ -0,0 +1,174 @@ +.. _cfg_flight_recorder: + +.. admonition:: Enterprise Edition + :class: fact + + The flight recorder is available in the `Enterprise Edition `_ only. + +* :ref:`flightrec_enabled ` +* :ref:`flightrec_logs_size ` +* :ref:`flightrec_logs_max_msg_size ` +* :ref:`flightrec_logs_log_level ` +* :ref:`flightrec_metrics_period ` +* :ref:`flightrec_metrics_interval ` +* :ref:`flightrec_requests_size ` +* :ref:`flightrec_requests_max_req_size ` +* :ref:`flightrec_requests_max_res_size ` + + +.. _cfg_flightrec_enabled: + +.. confval:: flightrec_enabled + + Since :doc:`2.11.0 `. + + Enable the :ref:`flight recorder `. + + | + | Type: boolean + | Default: false + | Environment variable: TT_FLIGHTREC_ENABLED + | Dynamic: yes + + +.. _cfg_flightrec_logs_size: + +.. confval:: flightrec_logs_size + + Since :doc:`2.11.0 `. + + Specify the size (in bytes) of the log storage. + You can set this option to ``0`` to disable the log storage. + + | + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_LOGS_SIZE + | Dynamic: yes + + +.. _cfg_flightrec_logs_max_msg_size: + +.. confval:: flightrec_logs_max_msg_size + + Since :doc:`2.11.0 `. + + Specify the maximum size (in bytes) of the log message. + The log message is truncated if its size exceeds this limit. + + | + | Type: integer + | Default: 4096 + | Maximum: 16384 + | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE + | Dynamic: yes + + +.. _cfg_flightrec_logs_log_level: + +.. confval:: flightrec_logs_log_level + + Since :doc:`2.11.0 `. + + Specify the level of detail the log has. + You can learn more about log levels from the :ref:`log_level ` + option description. + Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``. + + | + | Type: integer + | Default: 6 + | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + | Dynamic: yes + + +.. _cfg_flightrec_metrics_period: + +.. confval:: flightrec_metrics_period + + Since :doc:`2.11.0 `. + + Specify the time period (in seconds) that defines how long metrics are stored from the moment of dump. + So, this value defines how much historical metrics data is collected up to the moment of crash. + The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `. + + | + | Type: integer + | Default: 180 + | Environment variable: TT_FLIGHTREC_METRICS_PERIOD + | Dynamic: yes + + +.. _cfg_flightrec_metrics_interval: + +.. confval:: flightrec_metrics_interval + + Since :doc:`2.11.0 `. + + Specify the time interval (in seconds) that defines the frequency of dumping metrics. + This value shouldn't exceed :ref:`flightrec_metrics_period `. + + .. NOTE:: + + Given that the average size of a metrics entry is 2 kB, + you can estimate the size of the metrics storage as follows: + + .. code-block:: console + + (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB + + | + | Type: number + | Default: 1.0 + | Minimum: 0.001 + | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL + | Dynamic: yes + + +.. _cfg_flightrec_requests_size: + +.. confval:: flightrec_requests_size + + Since :doc:`2.11.0 `. + + Specify the size (in bytes) of storage for the request and response data. + You can set this parameter to ``0`` to disable a storage of requests and responses. + + | + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE + | Dynamic: yes + + + +.. _cfg_flightrec_requests_max_req_size: + +.. confval:: flightrec_requests_max_req_size + + Since :doc:`2.11.0 `. + + Specify the maximum size (in bytes) of a request entry. + A request entry is truncated if this size is exceeded. + + | + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE + | Dynamic: yes + + +.. _cfg_flightrec_requests_max_res_size: + +.. confval:: flightrec_requests_max_res_size + + Since :doc:`2.11.0 `. + + Specify the maximum size (in bytes) of a response entry. + A response entry is truncated if this size is exceeded. + + | + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE + | Dynamic: yes diff --git a/doc/reference/configuration/cfg_hot_standby.rst b/doc/reference/configuration/cfg_hot_standby.rst index 3d4481f861..2b674ebad8 100644 --- a/doc/reference/configuration/cfg_hot_standby.rst +++ b/doc/reference/configuration/cfg_hot_standby.rst @@ -1,6 +1,8 @@ .. confval:: hot_standby - Since version 1.7.4. Whether to start the server in **hot standby** mode. + Since version 1.7.4. + + Whether to start the server in **hot standby** mode. Hot standby is a feature which provides a simple form of failover without :ref:`replication `. @@ -45,6 +47,7 @@ * for spaces created with :doc:`engine = 'vinyl' `; it is designed to work for spaces created with ``engine = 'memtx'``. + | | Type: boolean | Default: false | Environment variable: TT_HOT_STANDBY diff --git a/doc/reference/configuration/cfg_logging.rst b/doc/reference/configuration/cfg_logging.rst index c256e1ff2c..85d396ae83 100644 --- a/doc/reference/configuration/cfg_logging.rst +++ b/doc/reference/configuration/cfg_logging.rst @@ -11,30 +11,33 @@ application. * :ref:`log_format ` * :ref:`log_modules ` -.. _cfg_logging-log_level: +.. _cfg_logging-log_level: -.. confval:: log_level +.. confval:: log_level Since version 1.6.2. - Specifies the level of detail the :ref:`log ` has. There are seven levels: - * 1 – ``SYSERROR`` - * 2 – ``ERROR`` - * 3 – ``CRITICAL`` - * 4 – ``WARNING`` - * 5 – ``INFO`` - * 6 – ``VERBOSE`` - * 7 – ``DEBUG`` + Specify the level of detail the :ref:`log ` has. There are the following levels: + + * 0 -- ``fatal`` + * 1 -- ``syserror`` + * 2 -- ``error`` + * 3 -- ``crit`` + * 4 -- ``warn`` + * 5 -- ``info`` + * 6 -- ``verbose`` + * 7 -- ``debug`` By setting ``log_level``, you can enable logging of all events with severities above or equal to the given level. Tarantool prints logs to the standard error stream by default. This can be changed with the :ref:`log ` configuration parameter. - | Type: integer + | + | Type: integer, string | Default: 5 | Environment variable: TT_LOG_LEVEL - | Dynamic: **yes** + | Dynamic: yes .. note:: Prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was @@ -47,6 +50,7 @@ application. .. confval:: log Since version 1.7.4. + By default, Tarantool sends the log to the standard error stream (``stderr``). If ``log`` is specified, Tarantool can send the log to a: @@ -120,6 +124,7 @@ application. When log is a program, its PID is saved in the :ref:`log.pid ` variable. You need to send it a signal to rotate logs. + | | Type: string | Default: null | Environment variable: TT_LOG @@ -130,6 +135,7 @@ application. .. confval:: log_nonblock Since version 1.7.4. + If ``log_nonblock`` equals **true**, Tarantool does not block during logging when the system is not ready for writing, and drops the message instead. If :ref:`log_level ` is high, and many @@ -148,6 +154,7 @@ application. This is a behavior change: in earlier versions of the Tarantool server, the default value was **true**. + | | Type: boolean | Default: nil | Environment variable: TT_LOG_NONBLOCK @@ -158,20 +165,24 @@ application. .. confval:: too_long_threshold Since version 1.6.2. + If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if :ref:`log_level ` is greater than or equal to 4 (WARNING). + | | Type: float | Default: 0.5 | Environment variable: TT_TOO_LONG_THRESHOLD - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-log_format: .. confval:: log_format - Since version 1.7.6. Log entries have two possible formats: + Since version 1.7.6. + + Log entries have two possible formats: * 'plain' (the default), or * 'json' (with more detail and with JSON labels). @@ -204,10 +215,11 @@ application. The ``log_format='json'`` entry has the same fields along with their labels, and in addition has the file name and line number of the Tarantool source. + | | Type: string | Default: 'plain' | Environment variable: TT_LOG_FORMAT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_logging-log_modules: @@ -215,6 +227,7 @@ application. .. confval:: log_modules Since version :doc:`2.11.0 `. + Configure the specified log levels (:ref:`log_level `) for different modules. You can specify a logging level for the following module types: @@ -228,11 +241,11 @@ application. * The ``tarantool`` module that enables you to configure the logging level for Tarantool core messages. Specifically, it configures the logging level for messages logged from non-Lua code, including C modules. Example: :ref:`Set a log level for C modules `. + | | Type: table | Default: blank | Environment variable: TT_LOG_MODULES - | Dynamic: **yes** - | + | Dynamic: yes .. _cfg_logging-logging_example_existing_modules: diff --git a/doc/reference/configuration/cfg_networking.rst b/doc/reference/configuration/cfg_networking.rst index 5993d6755a..b53926e11c 100644 --- a/doc/reference/configuration/cfg_networking.rst +++ b/doc/reference/configuration/cfg_networking.rst @@ -8,21 +8,26 @@ .. confval:: io_collect_interval Since version 1.4.9. + The instance will sleep for io_collect_interval seconds between iterations of the event loop. Can be used to reduce CPU load in deployments in which the number of client connections is large, but requests are not so frequent (for example, each connection issues just a handful of requests per second). + + | | Type: float | Default: null | Environment variable: TT_IO_COLLECT_INTERVAL - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-net_msg_max: .. confval:: net_msg_max - Since version 1.10.1. To handle messages, Tarantool allocates fibers. + Since version 1.10.1. + + To handle messages, Tarantool allocates fibers. To prevent fiber overhead from affecting the whole system, Tarantool restricts how many messages the fibers handle, so that some pending requests are blocked. @@ -50,16 +55,18 @@ On typical systems, the default value (768) is correct. + | | Type: integer | Default: 768 | Environment variable: TT_NET_MSG_MAX - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-readahead: .. confval:: readahead Since version 1.6.2. + The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes and the more requests can be read from the operating system buffer in a single @@ -69,16 +76,19 @@ should be increased. If batched request processing is not used, it’s prudent to leave this setting at its default. + + | | Type: integer | Default: 16320 | Environment variable: TT_READAHEAD - | Dynamic: **yes** + | Dynamic: yes .. _cfg_networking-iproto_threads: .. confval:: iproto_threads Since version :doc:`2.8.1 `. + The number of :ref:`network threads `. There can be unusual workloads where the network thread is 100% loaded and the transaction processor thread is not, so the network @@ -87,7 +97,8 @@ which thread. On typical systems, the default value (1) is correct. - + + | | Type: integer | Default: 1 | Environment variable: TT_IPROTO_THREADS diff --git a/doc/reference/configuration/cfg_replication.rst b/doc/reference/configuration/cfg_replication.rst index 6ac7e48e3c..2bb192f5ad 100644 --- a/doc/reference/configuration/cfg_replication.rst +++ b/doc/reference/configuration/cfg_replication.rst @@ -1,5 +1,6 @@ * :ref:`replication ` * :ref:`replication_anon ` +* :ref:`bootstrap_leader ` * :ref:`bootstrap_strategy ` * :ref:`replication_connect_timeout ` * :ref:`replication_connect_quorum ` @@ -15,12 +16,17 @@ * :ref:`election_mode ` * :ref:`election_timeout ` * :ref:`election_fencing_mode ` +* :ref:`instance_name ` +* :ref:`replicaset_name ` +* :ref:`cluster_name ` + .. _cfg_replication-replication: .. confval:: replication Since version 1.7.4. + If ``replication`` is not an empty string, the instance is considered to be a Tarantool :ref:`replica `. The replica will try to connect to the master specified in ``replication`` with a @@ -54,19 +60,21 @@ :extsamp:`box.cfg{ replication = {*{new-value}*} }` + | | Type: string | Default: null | Environment variable: TT_REPLICATION - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_anon: .. confval:: replication_anon Since version 2.3.1. + A Tarantool replica can be anonymous. This type of replica is read-only (but you still can write to temporary and - replica-local spaces), and it isn't present in the ``_cluster`` table. + replica-local spaces), and it isn't present in the :ref:`_cluster ` space. Since an anonymous replica isn't registered in the ``_cluster`` table, there is no limitation for anonymous replicas count in a replica set: @@ -200,10 +208,37 @@ instance must replicate from some read-write instance, otherwise it cannot be added to the ``_cluster`` table. + | | Type: boolean | Default: false | Environment variable: TT_REPLICATION_ANON - | Dynamic: **yes** + | Dynamic: yes + + +.. _cfg_replication-bootstrap_leader: + +.. confval:: bootstrap_leader + + Since :doc:`3.0.0 `. + + A bootstrap leader for a replica set. + You can pass a bootstrap leader's URI, UUID, or name. + + To specify a bootstrap leader manually, you need to set :ref:`bootstrap_strategy ` to ``config``, for example: + + .. code-block:: lua + + box.cfg{ + bootstrap_strategy = 'config', + bootstrap_leader = '127.0.0.1:3301', + replication = {'127.0.0.1:3301'}, + } + + | + | Type: string + | Default: null + | Environment variable: TT_BOOTSTRAP_LEADER + | Dynamic: yes .. _cfg_replication-bootstrap_strategy: @@ -212,7 +247,7 @@ Since :doc:`2.11.0 `. - Specifies a strategy used to bootstrap a :ref:`replica set `. + Specify a strategy used to bootstrap a :ref:`replica set `. The following strategies are available: * ``auto``: a node doesn't boot if a half or more of other nodes in a replica set are not connected. @@ -221,13 +256,19 @@ In the case of 4 or 5 nodes, at least 3 connected instances are required. Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader. + * ``config``: use the specified node to bootstrap a replica set. + To specify the bootstrap leader, use the :ref:`bootstrap_leader ` option. + + * ``supervised``: a bootstrap leader isn't chosen automatically but should be appointed using :ref:`box.ctl.make_bootstrap_leader() ` on the desired node. + * ``legacy`` (deprecated since :doc:`2.11.0 `): a node requires the :ref:`replication_connect_quorum ` number of other nodes to be connected. This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future. + | | Type: string | Default: auto | Environment variable: TT_BOOTSTRAP_STRATEGY - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_connect_timeout: @@ -235,6 +276,7 @@ .. confval:: replication_connect_timeout Since version 1.9.0. + The number of seconds that a replica will wait when trying to connect to a master in a cluster. See :ref:`orphan status ` for details. @@ -244,19 +286,21 @@ which a master uses to disconnect a replica when the master receives no acknowledgments of heartbeat messages. + | | Type: float | Default: 30 | Environment variable: TT_REPLICATION_CONNECT_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_connect_quorum: .. confval:: replication_connect_quorum Deprecated since :doc:`2.11.0 `. + This option is in effect if :ref:`bootstrap_strategy ` is set to ``legacy``. - Specifies the number of nodes to be up and running to start a replica set. + Specify the number of nodes to be up and running to start a replica set. This parameter has effect during :ref:`bootstrap ` or :ref:`configuration update `. Setting ``replication_connect_quorum`` to ``0`` makes Tarantool @@ -269,16 +313,18 @@ box.cfg { replication_connect_quorum = 2 } + | | Type: integer | Default: null | Environment variable: TT_REPLICATION_CONNECT_QUORUM - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_skip_conflict: .. confval:: replication_skip_conflict Since version 1.10.1. + By default, if a replica adds a unique key that another replica has added, replication :ref:`stops ` with error = ER_TUPLE_FOUND. @@ -293,10 +339,11 @@ box.cfg{replication_skip_conflict=true} + | | Type: boolean | Default: false | Environment variable: TT_REPLICATION_SKIP_CONFLICT - | Dynamic: **yes** + | Dynamic: yes .. NOTE:: @@ -309,6 +356,7 @@ .. confval:: replication_sync_lag Since version 1.9.0. + The maximum :ref:`lag ` allowed for a replica. When a replica :ref:`syncs ` (gets updates from a master), it may not catch up completely. @@ -324,16 +372,18 @@ This parameter is ignored during bootstrap. See :ref:`orphan status ` for details. + | | Type: float | Default: 10 | Environment variable: TT_REPLICATION_SYNC_LAG - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_sync_timeout: .. confval:: replication_sync_timeout Since version 1.10.2. + The number of seconds that a node waits when trying to sync with other nodes in a replica set (see :ref:`bootstrap_strategy `), after connecting or during :ref:`configuration update `. @@ -342,21 +392,24 @@ updates. If ``replication_sync_timeout`` expires, the replica enters :ref:`orphan status `. + | | Type: float - | Default: 300 + | Default: 0 | Environment variable: TT_REPLICATION_SYNC_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. NOTE:: - The default ``replication_sync_timeout`` value is going to be changed in future versions from ``300`` to ``0``. - You can learn the reasoning behind this decision from the :ref:`Default value for replication_sync_timeout ` topic, which also describes how to try the new behavior in the current version. + The default ``replication_sync_timeout`` value can be changed to the old default value (300) by using the ``compat`` module. + For more information on changing the default value via the ``compat`` module, + see :ref:`Default value for replication_sync_timeout `. .. _cfg_replication-replication_timeout: .. confval:: replication_timeout Since version 1.7.5. + If the master has no updates to send to the replicas, it sends heartbeat messages every ``replication_timeout`` seconds, and each replica sends an ACK packet back. @@ -366,16 +419,19 @@ See more in :ref:`Monitoring a replica set `. + | | Type: integer | Default: 1 | Environment variable: TT_REPLICATION_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replicaset_uuid: .. confval:: replicaset_uuid - Since version 1.9.0. As described in section + Since version 1.9.0. + + As described in section :ref:`"Replication architecture" `, each replica set is identified by a `universally unique identifier `_ @@ -416,6 +472,7 @@ box.cfg{replicaset_uuid='7b853d13-508b-4b8e-82e6-806f088ea6e9'} + | | Type: string | Default: null | Environment variable: TT_REPLICASET_UUID @@ -426,6 +483,7 @@ .. confval:: instance_uuid Since version 1.9.0. + For replication administration purposes, it is possible to set the `universally unique identifiers `_ of the instance (``instance_uuid``) and the replica set @@ -440,6 +498,7 @@ box.cfg{instance_uuid='037fec43-18a9-4e12-a684-a42b716fcd02'} + | | Type: string | Default: null | Environment variable: TT_INSTANCE_UUID @@ -450,6 +509,7 @@ .. confval:: replication_synchro_quorum Since version :doc:`2.5.1 `. + For :ref:`synchronous replication ` only. This option tells how many replicas should confirm the receipt of a synchronous transaction before it can finish its commit. @@ -485,16 +545,18 @@ If the value for this option is set to ``1``, the synchronous transactions work like asynchronous when not configured. `1` means that successful WAL write to the master is enough to commit. + | | Type: number | Default: N / 2 + 1 (before version :doc:`2.10.0 `, the default value was 1) | Environment variable: TT_REPLICATION_SYNCHRO_QUORUM - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_synchro_timeout: .. confval:: replication_synchro_timeout Since version :doc:`2.5.1 `. + For :ref:`synchronous replication ` only. Tells how many seconds to wait for a synchronous transaction quorum replication until it is declared failed and is rolled back. @@ -503,16 +565,18 @@ transactions will be kept waiting on the replicas until a new master is elected. + | | Type: number | Default: 5 | Environment variable: TT_REPLICATION_SYNCHRO_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-replication_replication_threads: .. confval:: replication_threads Since version :doc:`2.10.0 `. + The number of threads spawned to decode the incoming replication data. The default value is `1`. @@ -523,6 +587,7 @@ Possible values range from 1 to 1000. If there are multiple replication threads, connections to serve are distributed evenly between the threads. + | | Type: number | Default: 1 | Possible values: from 1 to 1000 @@ -534,7 +599,8 @@ .. confval:: election_mode Since version :doc:`2.6.1 `. - Specifies the role of a replica set node in the + + Specify the role of a replica set node in the :ref:`leader election process `. Possible values: @@ -573,17 +639,19 @@ * Once :ref:`box.ctl.promote() ` is called, the instance becomes a candidate and starts a new election round. If the instance wins the elections, it becomes a leader, but won't participate in any new elections. + | | Type: string | Default: 'off' | Environment variable: TT_ELECTION_MODE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-election_timeout: .. confval:: election_timeout Since version :doc:`2.6.1 `. - Specifies the timeout between election rounds in the + + Specify the timeout between election rounds in the :ref:`leader election process ` if the previous round ended up with a split-vote. @@ -604,19 +672,21 @@ or to 305, 302, and 324, and so on. In that way, the votes will never be split because the election on different nodes won't be restarted simultaneously. + | | Type: number | Default: 5 | Environment variable: TT_ELECTION_TIMEOUT - | Dynamic: **yes** + | Dynamic: yes .. _cfg_replication-election_fencing_mode: .. confval:: election_fencing_mode Since version :doc:`2.11.0 `. + In earlier Tarantool versions, use :ref:`election_fencing_enabled ` instead. - Specifies the :ref:`leader fencing mode ` that + Specify the :ref:`leader fencing mode ` that affects the leader election process. When the parameter is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than :ref:`replication_synchro_quorum ` @@ -638,7 +708,92 @@ :ref:`election_mode ` set to ``candidate`` or ``manual``. To turn off :ref:`leader fencing `, set ``election_fencing_mode`` to ``off``. + | | Type: string | Default: 'soft' | Environment variable: TT_ELECTION_FENCING_MODE - | Dynamic: **yes** + | Dynamic: yes + +.. _cfg_replication-instance_name: + +.. confval:: instance_name + + Since version :doc:`3.0.0 `. + + Specify the instance name. + This value must be unique in a replica set. + + The following rules are applied to instance names: + + - The maximum number of symbols is 63. + - Should start with a letter. + - Can contain lowercase letters (a-z). If uppercase letters are used, they are converted to lowercase. + - Can contain digits (0-9). + - Can contain the following characters: ``-``, ``_``. + + To change or remove the specified name, you should temporarily set the :ref:`box.cfg.force_recovery ` configuration option to ``true``. + When all the names are updated and all the instances synced, ``box.cfg.force_recovery`` can be set back to ``false``. + + .. NOTE:: + + The instance name is persisted in the :ref:`box.space._cluster ` system space. + + See also: :ref:`box_info_name` + + | + | Type: string + | Default: null + | Environment variable: TT_INSTANCE_NAME + | Dynamic: no + +.. _cfg_replication-replicaset_name: + +.. confval:: replicaset_name + + Since version :doc:`3.0.0 `. + + Specify the name of a replica set to which this instance belongs. + This value must be the same for all instances of the replica set. + + See the :ref:`instance_name ` description to learn: + + - which rules are applied to names + - how to change or remove an already specified name + + .. NOTE:: + + The replica set name is persisted in the :ref:`box.space._schema ` system space. + + See also: :ref:`box_info_replicaset` + + | + | Type: string + | Default: null + | Environment variable: TT_REPLICASET_NAME + | Dynamic: no + +.. _cfg_replication-cluster_name: + +.. confval:: cluster_name + + Since version :doc:`3.0.0 `. + + Specify the name of a cluster to which this instance belongs. + This value must be the same for all instances of the cluster. + + See the :ref:`instance_name ` description to learn: + + - which rules are applied to names + - how to change or remove an already specified name + + .. NOTE:: + + The cluster name is persisted in the :ref:`box.space._schema ` system space. + + See also: :ref:`box_info_cluster` + + | + | Type: string + | Default: null + | Environment variable: TT_CLUSTER_NAME + | Dynamic: no diff --git a/doc/reference/configuration/cfg_snapshot_daemon.rst b/doc/reference/configuration/cfg_snapshot_daemon.rst index 3f12de315c..17d4529151 100644 --- a/doc/reference/configuration/cfg_snapshot_daemon.rst +++ b/doc/reference/configuration/cfg_snapshot_daemon.rst @@ -2,134 +2,149 @@ * :ref:`checkpoint_interval ` * :ref:`checkpoint_wal_threshold ` -The checkpoint daemon is a fiber which is constantly running. At intervals, -it may make new :ref:`snapshot (.snap) files ` and then -may delete old snapshot files. +.. _cfg_checkpoint_daemon: -The :ref:`checkpoint_interval ` and -:ref:`checkpoint_count ` configuration -settings determine how long the intervals are, and how many snapshots should -exist before deletions occur. +**Checkpoint daemon** -.. _cfg_checkpoint_daemon-garbage-collector: +The checkpoint daemon (snapshot daemon) is a constantly running :ref:`fiber `. +The checkpoint daemon creates a schedule for the periodic snapshot creation based on +the configuration options and the speed of file size growth. +If enabled, the daemon makes new :ref:`snapshot ` (``.snap``) files according to this schedule. + +The work of the checkpoint daemon is based on the following configuration options: + +* :ref:`checkpoint_interval ` -- a new snapshot is taken once in a given period. +* :ref:`checkpoint_wal_threshold ` -- a new snapshot is taken once the size + of all WAL files created since the last snapshot exceeds a given limit. + +If necessary, the checkpoint daemon also activates the :ref:`Tarantool garbage collector ` +that deletes old snapshots and WAL files. + +.. _cfg_checkpoint_daemon-garbage-collector: **Tarantool garbage collector** -The checkpoint daemon may activate the Tarantool garbage collector -which deletes old files. This garbage collector is distinct from the -`Lua garbage collector `_ -which is for Lua objects, and distinct from a -Tarantool garbage collector which specializes in -:ref:`handling shard buckets `. +Tarantool garbage collector can be activated by the :ref:`checkpoint daemon `. +The garbage collector tracks the snapshots that are to be :ref:`relayed to a replica ` or needed +by other consumers. When the files are no longer needed, Tarantool garbage collector deletes them. + +.. NOTE:: + + The garbage collector called by the checkpoint daemon is distinct from the `Lua garbage collector `_ + which is for Lua objects, and distinct from the Tarantool garbage collector that specializes in :ref:`handling shard buckets `. + +This garbage collector is called as follows: + +* When the number of snapshots reaches the limit of :ref:`checkpoint_count ` size. + After a new snapshot is taken, Tarantool garbage collector deletes the oldest snapshot file and any associated WAL files. + +* When the size of all WAL files created since the last snapshot reaches the limit of :ref:`checkpoint_wal_threshold `. + Once this size is exceeded, the checkpoint daemon takes a snapshot, then the garbage collector deletes the old WAL files. + +If an old snapshot file is deleted, the Tarantool garbage collector also deletes +any :ref:`write-ahead log (.xlog) ` files that meet the following conditions: -If the checkpoint daemon deletes an old snapshot file, then the -Tarantool garbage collector will also delete -any :ref:`write-ahead log (.xlog) ` files which are older than -the snapshot file and which contain information that is present in the snapshot -file. It will also delete obsolete vinyl ``.run`` files. +* The WAL files are older than the snapshot file. +* The WAL files contain information present in the snapshot file. -The checkpoint daemon and the Tarantool garbage collector will not delete a file if: +Tarantool garbage collector also deletes obsolete vinyl ``.run`` files. -* a **backup** is ongoing and the file has not been backed up - (see :ref:`"Hot backup" `), or +Tarantool garbage collector doesn't delete a file in the following cases: -* **replication** is ongoing and the file has not been relayed to a replica - (see :ref:`"Replication architecture" `), +* A backup is running, and the file has not been backed up + (see :ref:`Hot backup `). -* a replica is connecting, or +* Replication is running, and the file has not been relayed to a replica + (see :ref:`Replication architecture `), -* a replica has fallen behind. - The progress of each replica is tracked; if a replica's position is far - from being up to date, then the server stops to give it a chance to - catch up. - If an administrator concludes that a replica is permanently down, then the - correct procedure is to restart the server, or (preferably) - :ref:`remove the replica from the cluster `. +* A replica is connecting. -.. _cfg_checkpoint_daemon-checkpoint_interval: +* A replica has fallen behind. + The progress of each replica is tracked; if a replica's position is far + from being up to date, then the server stops to give it a chance to catch up. + If an administrator concludes that a replica is permanently down, then the + correct procedure is to restart the server, or (preferably) :ref:`remove the replica from the cluster `. -.. confval:: checkpoint_interval +.. _cfg_checkpoint_daemon-checkpoint_interval: + +.. confval:: checkpoint_interval Since version 1.7.4. - The interval between actions by the checkpoint daemon, in seconds. If - ``checkpoint_interval`` is set to a value greater than zero, and there is - activity which causes change to a database, then the checkpoint daemon will - call :doc:`box.snapshot() ` every ``checkpoint_interval`` - seconds, creating a new snapshot file each time. If ``checkpoint_interval`` - is set to zero, then the checkpoint daemon is disabled. - For example: + The interval in seconds between actions by the :ref:`checkpoint daemon `. + If the option is set to a value greater than zero, and there is + activity that causes change to a database, then the checkpoint daemon + calls :doc:`box.snapshot() ` every ``checkpoint_interval`` + seconds, creating a new snapshot file each time. If the option + is set to zero, the checkpoint daemon is disabled. + + **Example** - .. code-block:: lua + .. code-block:: lua - box.cfg{checkpoint_interval=60} + box.cfg{ checkpoint_interval = 7200 } - will cause the checkpoint daemon to create a new database snapshot once - per minute, if there is activity. + In the example, the checkpoint daemon creates a new database snapshot every two hours, if there is activity. + | | Type: integer | Default: 3600 (one hour) | Environment variable: TT_CHECKPOINT_INTERVAL | Dynamic: yes -.. _cfg_checkpoint_daemon-checkpoint_count: +.. _cfg_checkpoint_daemon-checkpoint_count: + +.. confval:: checkpoint_count + + Since version 1.7.4. -.. confval:: checkpoint_count + The maximum number of snapshots that are stored in the + :ref:`memtx_dir ` directory. + If the number of snapshots after creating a new one exceeds this value, + the :ref:`Tarantool garbage collector ` deletes old snapshots. + If the option is set to zero, the garbage collector + does not delete old snapshots. - Since version 1.7.4. The maximum number of snapshots that may exist on the - :ref:`memtx_dir ` directory - before the checkpoint daemon will delete old snapshots. - If ``checkpoint_count`` equals zero, then the checkpoint daemon - does not delete old snapshots. For example: + **Example** - .. code-block:: lua + .. code-block:: lua box.cfg{ - checkpoint_interval = 3600, - checkpoint_count = 10 + checkpoint_interval = 7200, + checkpoint_count = 3 } - will cause the checkpoint daemon to create a new snapshot each hour until - it has created ten snapshots. After that, it will delete the oldest snapshot - (and any associated write-ahead-log files) after creating a new one. + In the example, the checkpoint daemon creates a new snapshot every two hours until + it has created three snapshots. After creating a new snapshot (the fourth one), the oldest snapshot + and any associated write-ahead-log files are deleted. - Remember that, as noted earlier, snapshots will not be deleted if - replication is ongoing and the file has not been relayed to a replica. - Therefore ``checkpoint_count`` has no effect unless all replicas are alive. + .. NOTE:: + Snapshots will not be deleted if replication is ongoing and the file has not been relayed to a replica. + Therefore, ``checkpoint_count`` has no effect unless all replicas are alive. + + + | | Type: integer | Default: 2 | Environment variable: TT_CHECKPOINT_COUNT | Dynamic: yes -.. _cfg_checkpoint_daemon-checkpoint_wal_threshold: +.. _cfg_checkpoint_daemon-checkpoint_wal_threshold: -.. confval:: checkpoint_wal_threshold +.. confval:: checkpoint_wal_threshold Since version 2.1.2. - The threshold for the total size in bytes of all WAL files created since the last checkpoint. + + The threshold for the total size in bytes for all WAL files created since the last checkpoint. Once the configured threshold is exceeded, the WAL thread notifies the - checkpoint daemon that it must make a new checkpoint and delete old WAL files. + :ref:`checkpoint daemon ` that it must make a new checkpoint and delete old WAL files. This parameter enables administrators to handle a problem that could occur with calculating how much disk space to allocate for a partition containing WAL files. - For example, suppose - :ref:`checkpoint_interval ` - = 2 and - :ref:`checkpoint_count ` - = 5 - and the average amount that Tarantool writes between each checkpoint interval - = 1 GB. - Then one could calculate that the necessary amount is (2*5*1) 10GB. - But this calculation would be wrong if, instead of writing 1 GB - during one checkpoint interval, - Tarantool encounters an unusual spike and tries to write 11 GB, - causing an operating-system ENOSPC ("no space") error. - By setting ``checkpoint_wal_threshold`` to a lower value, say 9 GB, - an administrator could prevent the error. - + | | Type: integer | Default: 10^18 (a large number so in effect there is no limit by default) | Environment variable: TT_CHECKPOINT_WAL_THRESHOLD diff --git a/doc/reference/configuration/cfg_storage.rst b/doc/reference/configuration/cfg_storage.rst index 5d88d3db28..f16c6134a8 100644 --- a/doc/reference/configuration/cfg_storage.rst +++ b/doc/reference/configuration/cfg_storage.rst @@ -2,6 +2,7 @@ * :ref:`memtx_max_tuple_size ` * :ref:`memtx_min_tuple_size ` * :ref:`memtx_allocator ` +* :ref:`memtx_sort_threads ` * :ref:`slab_alloc_factor ` * :ref:`slab_alloc_granularity ` * :ref:`vinyl_bloom_fpr ` @@ -20,46 +21,49 @@ .. confval:: memtx_memory Since version 1.7.4. - How much memory Tarantool allocates to actually store tuples. + + How much memory Tarantool allocates to store tuples. When the limit is reached, :ref:`INSERT ` or :ref:`UPDATE ` requests begin failing with error :errcode:`ER_MEMORY_ISSUE`. The server does not go beyond the ``memtx_memory`` limit to allocate tuples, but there is additional memory - used to store indexes and connection information. Depending on actual - configuration and workload, Tarantool can consume up to 20% more than the - ``memtx_memory`` limit. + used to store indexes and connection information. + | | Type: float | Default: 256 * 1024 * 1024 = 268435456 bytes | Minimum: 33554432 bytes (32 MB) | Environment variable: TT_MEMTX_MEMORY - | Dynamic: **yes** but it cannot be decreased + | Dynamic: yes but it cannot be decreased .. _cfg_storage-memtx_max_tuple_size: .. confval:: memtx_max_tuple_size Since version 1.7.4. + Size of the largest allocation unit, for the memtx storage engine. It can be increased if it is necessary to store large tuples. - See also: :ref:`vinyl_max_tuple_size `. + | | Type: integer | Default: 1024 * 1024 = 1048576 bytes | Environment variable: TT_MEMTX_MAX_TUPLE_SIZE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_storage-memtx_min_tuple_size: .. confval:: memtx_min_tuple_size Since version 1.7.4. + Size of the smallest allocation unit. It can be decreased if most - of the tuples are very small. The value must be between 8 and 1048280 - inclusive. + of the tuples are very small. + | | Type: integer | Default: 16 bytes + | Possible values: between 8 and 1048280 inclusive | Environment variable: TT_MEMTX_MIN_TUPLE_SIZE | Dynamic: no @@ -68,20 +72,43 @@ .. confval:: memtx_allocator Since version :doc:`2.10.0 `. - Specifies the allocator used for memtx tuples. - The possible values are ``system`` and ``small``: - * ``system`` is based on the ``malloc`` function. - This allocator allocates memory as needed, checking that the quota is not exceeded. + Specify the allocator that manages memory for ``memtx`` tuples. + Possible values: + + * ``system`` -- the memory is allocated as needed, checking that the quota is not exceeded. + THe allocator is based on the ``malloc`` function. - * ``small`` is a special `slab allocator `_. - Note that this allocator is prone to unresolvable fragmentation on specific workloads, - so you can switch to ``system`` in such cases. + * ``small`` -- a `slab allocator `_. + The allocator repeatedly uses a memory block to allocate objects of the same type. + Note that this allocator is prone to unresolvable fragmentation on specific workloads, + so you can switch to ``system`` in such cases. + | | Type: string | Default: 'small' | Environment variable: TT_MEMTX_ALLOCATOR - | Dynamic: No + | Dynamic: no + +.. _cfg_storage-memtx_sort_threads: + +.. confval:: memtx_sort_threads + + Since: :doc:`3.0.0 `. + + The number of threads from the :ref:`thread pool ` used to sort keys of secondary indexes on loading a ``memtx`` database. + The minimum value is 1, the maximum value is 256. + The default is to use all available cores. + + .. include:: /platform/atomic/thread_model.rst + :start-after: note_drop_openmp_start + :end-before: note_drop_openmp_end + + | + | Type: integer + | Default: box.NULL + | Environment variable: TT_MEMTX_SORT_THREADS + | Dynamic: no .. _cfg_storage-slab_alloc_factor: @@ -90,12 +117,14 @@ The multiplier for computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available and the - distribution of item sizes. Allowed values range from 1 to 2. + distribution of item sizes. See also: :ref:`slab_alloc_granularity ` + | | Type: float | Default: 1.05 + | Possible values: between 1 and 2 inclusive | Environment variable: TT_SLAB_ALLOC_FACTOR | Dynamic: no @@ -104,17 +133,21 @@ .. confval:: slab_alloc_granularity Since version :doc:`2.8.1 `. - Specifies the granularity (in bytes) of memory allocation in the :ref:`small allocator `. - The value of ``slab_alloc_granularity`` should be a power of two and should be greater than or equal to 4. - Below are few recommendations on how to adjust the ``slab_alloc_granularity`` value: - * To store small tuples of approximately the same size, set ``slab_alloc_granularity`` to 4 bytes to save memory. + Specify the granularity (in bytes) of memory allocation in the :ref:`small allocator `. + The ``memtx.slab_alloc_granularity`` value should meet the following conditions: - * To store tuples of different sizes, you can increase the ``slab_alloc_granularity`` value. - This results in allocating tuples from the same ``mempool``. + * The value is a power of two. + * The value is greater than or equal to 4. + + Below are few recommendations on how to adjust the ``memtx.slab_alloc_granularity`` option: + + * If the tuples in space are small and have about the same size, set the option to 4 bytes to save memory. + * If the tuples are different-sized, increase the option value to allocate tuples from the same ``mempool`` (memory pool). See also: :ref:`slab_alloc_factor ` + | | Type: number | Default: 8 bytes | Environment variable: TT_SLAB_ALLOC_GRANULARITY @@ -125,12 +158,14 @@ .. confval:: vinyl_bloom_fpr Since version 1.7.4. + Bloom filter false positive rate -- the suitable probability of the `bloom filter `_ to give a wrong result. The ``vinyl_bloom_fpr`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. + | | Type: float | Default: 0.05 | Environment variable: TT_VINYL_BLOOM_FPR @@ -144,20 +179,24 @@ The cache size for the vinyl storage engine. The cache can be resized dynamically. + | | Type: integer | Default: 128 * 1024 * 1024 = 134217728 bytes | Environment variable: TT_VINYL_CACHE - | Dynamic: **yes** + | Dynamic: yes .. _cfg_storage-vinyl_max_tuple_size: .. confval:: vinyl_max_tuple_size - Since version 1.7.5. Size of the largest allocation unit, + Since version 1.7.5. + + Size of the largest allocation unit, for the vinyl storage engine. It can be increased if it is necessary to store large tuples. See also: :ref:`memtx_max_tuple_size `. + | | Type: integer | Default: 1024 * 1024 = 1048576 bytes | Environment variable: TT_VINYL_MAX_TUPLE_SIZE @@ -167,22 +206,27 @@ .. confval:: vinyl_memory - Since version 1.7.4. The maximum number of in-memory bytes that vinyl uses. + Since version 1.7.4. + + The maximum number of in-memory bytes that vinyl uses. + | | Type: integer | Default: 128 * 1024 * 1024 = 134217728 bytes | Environment variable: TT_VINYL_MEMORY - | Dynamic: **yes** but it cannot be decreased + | Dynamic: yes but it cannot be decreased .. _cfg_storage-vinyl_page_size: .. confval:: vinyl_page_size Since version 1.7.4. + Page size. Page is a read/write unit for vinyl disk operations. The ``vinyl_page_size`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. + | | Type: integer | Default: 8 * 1024 = 8192 bytes | Environment variable: TT_VINYL_PAGE_SIZE @@ -193,6 +237,7 @@ .. confval:: vinyl_range_size Since version 1.7.4. + The default maximum range size for a vinyl index, in bytes. The maximum range size affects the decision whether to :ref:`split ` a range. @@ -209,6 +254,7 @@ In Tarantool versions prior to 1.10.2, ``vinyl_range_size`` default value was 1073741824. + | | Type: integer | Default: nil | Environment variable: TT_VINYL_RANGE_SIZE @@ -219,11 +265,13 @@ .. confval:: vinyl_run_count_per_level Since version 1.7.4. + The maximal number of runs per level in vinyl LSM tree. If this number is exceeded, a new level is created. The ``vinyl_run_count_per_level`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. + | | Type: integer | Default: 2 | Environment variable: TT_VINYL_RUN_COUNT_PER_LEVEL @@ -234,10 +282,12 @@ .. confval:: vinyl_run_size_ratio Since version 1.7.4. + Ratio between the sizes of different levels in the LSM tree. The ``vinyl_run_size_ratio`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart. + | | Type: float | Default: 3.5 | Environment variable: TT_VINYL_RUN_SIZE_RATIO @@ -248,9 +298,11 @@ .. confval:: vinyl_read_threads Since version 1.7.5. + The maximum number of read threads that vinyl can use for some concurrent operations, such as I/O and compression. + | | Type: integer | Default: 1 | Environment variable: TT_VINYL_READ_THREADS @@ -261,9 +313,11 @@ .. confval:: vinyl_write_threads Since version 1.7.5. + The maximum number of write threads that vinyl can use for some concurrent operations, such as I/O and compression. + | | Type: integer | Default: 4 | Environment variable: TT_VINYL_WRITE_THREADS diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst new file mode 100644 index 0000000000..462ab5da6d --- /dev/null +++ b/doc/reference/configuration/configuration_reference.rst @@ -0,0 +1,5568 @@ +.. _configuration_reference: + +Configuration reference +======================= + +This topic describes all :ref:`configuration parameters ` provided by Tarantool. + +Most of the configuration options described in this reference can be applied to a specific instance, replica set, group, or to all instances globally. +To do so, you need to define the required option at the :ref:`specified level `. + +.. _configuration_reference_app: + +app +--- + +Using Tarantool as an application server, you can run your own Lua applications. +In the ``app`` section, you can load the application and provide an application configuration in the ``app.cfg`` section. + +.. NOTE:: + + ``app`` can be defined in any :ref:`scope `. + +.. NOTE:: + + Note that an application specified using ``app`` is loaded after application roles specified using the :ref:`roles ` option. + +- :ref:`app.cfg ` +- :ref:`app.file ` +- :ref:`app.module ` + + +.. _configuration_reference_app_cfg: + +.. confval:: app.cfg + + A configuration of the application loaded using ``app.file`` or ``app.module``. + + **Example** + + In the example below, the application is loaded from the ``myapp.lua`` file placed next to the YAML configuration file: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/application/config.yaml + :language: yaml + :end-at: greeting + :dedent: + + Example on GitHub: `application `_ + + .. tip:: + + The :ref:`experimental.config.utils.schema ` + built-in module provides an API for managing user-defined configurations + of applications (``app.cfg``) and roles (``roles_cfg``). + + | + | Type: map + | Default: nil + | Environment variable: TT_APP_CFG + + +.. _configuration_reference_app_file: + +.. confval:: app.file + + A path to a Lua file to load an application from. + + | + | Type: string + | Default: nil + | Environment variable: TT_APP_FILE + + +.. _configuration_reference_app_module: + +.. confval:: app.module + + A Lua module to load an application from. + + **Example** + + The ``app`` section can be placed in any :ref:`configuration scope `. + As an example use case, you can provide different applications for storages and routers in a sharded cluster: + + .. code-block:: yaml + + groups: + storages: + app: + module: storage + # ... + routers: + app: + module: router + # ... + + | + | Type: string + | Default: nil + | Environment variable: TT_APP_MODULE + +.. _configuration_reference_audit: + +audit_log +--------- + +.. admonition:: Enterprise Edition + :class: fact + + Configuring ``audit_log`` parameters is available in the `Enterprise Edition `_ only. + +The ``audit_log`` section defines configuration parameters related to :ref:`audit logging `. + +.. NOTE:: + + ``audit_log`` can be defined in any :ref:`scope `. + +* :ref:`audit_log.extract_key ` +* :ref:`audit_log.file ` +* :ref:`audit_log.filter ` +* :ref:`audit_log.format ` +* :ref:`audit_log.nonblock ` +* :ref:`audit_log.pipe ` +* :ref:`audit_log.spaces ` +* :ref:`audit_log.to ` +* :ref:`audit_log.syslog.* ` + +.. _configuration_reference_audit_extract_key: + +.. confval:: audit_log.extract_key + + If set to ``true``, the audit subsystem extracts and prints only the primary key instead of full + tuples in DML events (``space_insert``, ``space_replace``, ``space_delete``). + Otherwise, full tuples are logged. + The option may be useful in case tuples are big. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_EXTRACT_KEY + +.. _configuration_reference_audit_file: + +.. confval:: audit_log.file + + Specify a file for the audit log destination. + You can set the ``file`` type using the :ref:`audit_log.to ` option. + If you write logs to a file, Tarantool reopens the audit log at `SIGHUP `_. + + | + | Type: string + | Default: 'var/log/{{ instance_name }}/audit.log' + | Environment variable: TT_AUDIT_LOG_FILE + +.. _configuration_reference_audit_filter: + +.. confval:: audit_log.filter + + Enable logging for a specified subset of audit events. + This option accepts the following values: + + * Event names (for example, ``password_change``). For details, see :ref:`Audit log events `. + * Event groups (for example, ``audit``). For details, see :ref:`Event groups `. + + The option contains either one value from ``Possible values`` section (see below) or a combination of them. + + To enable :ref:`custom audit log events `, specify the ``custom`` value in this option. + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: filter: + :end-at: custom ] + :dedent: + + | + | Type: array + | Possible values: 'all', 'audit', 'auth', 'priv', 'ddl', 'dml', 'data_operations', 'compatibility', + 'audit_enable', 'auth_ok', 'auth_fail', 'disconnect', 'user_create', 'user_drop', 'role_create', 'role_drop', + 'user_disable', 'user_enable', 'user_grant_rights', 'role_grant_rights', 'role_revoke_rights', 'password_change', + 'access_denied', 'eval', 'call', 'space_select', 'space_create', 'space_alter', 'space_drop', 'space_insert', + 'space_replace', 'space_delete', 'custom' + | Default: 'nil' + | Environment variable: TT_AUDIT_LOG_FILTER + +.. _configuration_reference_audit_format: + +.. confval:: audit_log.format + + Specify a format that is used for the audit log. + + **Example** + + If you set the option to ``plain``, + + .. code-block:: yaml + + audit_log: + to: file + format: plain + + the output in the file might look as follows: + + .. code-block:: text + + 2024-01-17T00:12:27.155+0300 + 4b5a2624-28e5-4b08-83c7-035a0c5a1db9 + INFO remote:unix/:(socket) + session_type:console + module:tarantool + user:admin + type:space_create + tag: + description:Create space Bands + + | + | Type: string + | Possible values: 'json', 'csv', 'plain' + | Default: 'json' + | Environment variable: TT_AUDIT_LOG_FORMAT + +.. _configuration_reference_audit_nonblock: + +.. confval:: audit_log.nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`audit_log.to ` is set to ``syslog`` + or ``pipe``. + + | + | Type: boolean + | Default: false + | Environment variable: TT_AUDIT_LOG_NONBLOCK + +.. _configuration_reference_audit_pipe: + +.. confval:: audit_log.pipe + + Specify a pipe for the audit log destination. + You can set the ``pipe`` type using the :ref:`audit_log.to ` option. + If log is a program, its pid is stored in the ``audit.pid`` field. + You need to send it a signal to rotate logs. + + **Example** + + This starts the `cronolog `_ program when the server starts + and sends all ``audit_log`` messages to cronolog standard input (``stdin``). + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_pipe/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'cronolog audit_tarantool.log' + :dedent: + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_PIPE + +.. _configuration_reference_audit_spaces: + +.. confval:: audit_log.spaces + + The array of space names for which data operation events (``space_select``, ``space_insert``, ``space_replace``, + ``space_delete``) should be logged. The array accepts string values. + If set to :ref:`box.NULL `, the data operation events are logged for all spaces. + + **Example** + + In the example, only the events of ``bands`` and ``singers`` spaces are logged: + + .. code-block:: yaml + + audit_log: + spaces: [bands, singers] + + | + | Type: array + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_SPACES + +.. _configuration_reference_audit_to: + +.. confval:: audit_log.to + + Enable audit logging and define the log location. + This option accepts the following values: + + - ``devnull``: disable audit logging. + - ``file``: write audit logs to a file (see :ref:`audit_log.file `). + - ``pipe``: start a program and write audit logs to it (see :ref:`audit_log.pipe `). + - ``syslog``: write audit logs to a system logger (see :ref:`audit_log.syslog.* `). + + By default, audit logging is disabled. + + **Example** + + The basic audit log configuration might look as follows: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log/config.yaml + :language: yaml + :start-at: audit_log + :end-at: extract_key: true + :dedent: + + | + | Type: string + | Possible values: 'devnull', 'file', 'pipe', 'syslog' + | Default: 'devnull' + | Environment variable: TT_AUDIT_LOG_TO + +.. _configuration_reference_audit_syslog: + +audit_log.syslog.* +~~~~~~~~~~~~~~~~~~ + +* :ref:`audit_log.syslog.facility ` +* :ref:`audit_log.syslog.identity ` +* :ref:`audit_log.syslog.server ` + +.. _configuration_reference_audit_syslog-facility: + +.. confval:: audit_log.syslog.facility + + Specify a system logger keyword that tells `syslogd `__ where to send the message. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + + See also: :ref:`syslog configuration example ` + + | + | Type: string + | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' + | Default: 'local7' + | Environment variable: TT_AUDIT_LOG_SYSLOG_FACILITY + +.. _configuration_reference_audit_syslog-identity: + +.. confval:: audit_log.syslog.identity + + Specify an application name to show in logs. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + + See also: :ref:`syslog configuration example ` + + | + | Type: string + | Default: 'tarantool' + | Environment variable: TT_AUDIT_LOG_SYSLOG_IDENTITY + +.. _configuration_reference_audit_syslog-server: + +.. confval:: audit_log.syslog.server + + Set a location for the syslog server. + It can be a Unix socket path starting with 'unix:' or an ipv4 port number. + You can enable logging to a system logger using the :ref:`audit_log.to ` option. + +.. _configuration_reference_audit_syslog-example: + + **Example** + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/audit_log_syslog/config.yaml + :language: yaml + :start-at: audit_log: + :end-at: 'tarantool_audit' + :dedent: + + - :ref:`audit_log.syslog.server ` -- a syslog server location. + + - :ref:`audit_log.syslog.facility ` -- a system logger keyword that tells syslogd where to send the message. + The default value is ``local7``. + + - :ref:`audit_log.syslog.identity ` -- an application name to show in logs. + The default value is ``tarantool``. + + These options are interpreted as a message for the `syslogd `_ program, + which runs in the background of any Unix-like platform. + + An example of a Tarantool audit log entry in the syslog: + + .. code-block:: text + + 09:32:52 tarantool_audit: {"time": "2024-02-08T09:32:52.190+0300", "uuid": "94454e46-9a0e-493a-bb9f-d59e44a43581", "severity": "INFO", "remote": "unix/:(socket)", "session_type": "console", "module": "tarantool", "user": "admin", "type": "space_create", "tag": "", "description": "Create space bands"} + + .. warning:: + + Above is an example of writing audit logs to a directory shared with the system logs. + Tarantool allows this option, but it is not recommended to do this to avoid difficulties + when working with audit logs. System and audit logs should be written separately. + To do this, create separate paths and specify them. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_AUDIT_LOG_SYSLOG_SERVER + +.. _configuration_reference_compat: + +compat +------ + +The ``compat`` section defines values of the :ref:`compat ` module options. + +.. NOTE:: + + ``compat`` can be defined in any :ref:`scope `. + +* :ref:`compat.binary_data_decoding ` +* :ref:`compat.box_cfg_replication_sync_timeout ` +* :ref:`compat.box_error_serialize_verbose ` +* :ref:`compat.box_error_unpack_type_and_code ` +* :ref:`compat.box_info_cluster_meaning ` +* :ref:`compat.box_session_push_deprecation ` +* :ref:`compat.box_space_execute_priv ` +* :ref:`compat.box_space_max ` +* :ref:`compat.box_tuple_extension ` +* :ref:`compat.box_tuple_new_vararg ` +* :ref:`compat.c_func_iproto_multireturn ` +* :ref:`compat.fiber_channel_close_mode ` +* :ref:`compat.fiber_slice_default ` +* :ref:`compat.json_escape_forward_slash ` +* :ref:`compat.sql_priv ` +* :ref:`compat.sql_seq_scan_default ` +* :ref:`compat.yaml_pretty_multiline ` + + +.. _configuration_reference_compat_binary_decoding: + +.. confval:: compat.binary_data_decoding + + Define how to store binary data fields in Lua after decoding: + + - ``new``: as varbinary objects + - ``old``: as plain strings + + See also: :ref:`compat-option-binary-decoding` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BINARY_DATA_DECODING + +.. _configuration_reference_compat_replication_timeout: + +.. confval:: compat.box_cfg_replication_sync_timeout + + Set a default replication sync timeout: + + - ``new``: 0 + - ``old``: 300 seconds + + .. important:: + + This value is set during the initial ``box.cfg{}`` call and cannot be changed later. + + See also: :ref:`compat-option-replication-timeout` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_CFG_REPLICATION_SYNC_TIMEOUT + +.. _configuration_reference_compat_error_serialize: + +.. confval:: compat.box_error_serialize_verbose + + **Since:** :doc:`3.1.0 ` + + Set the verbosity of :ref:`error objects ` serialization: + + - ``new``: serialize the error message together with other potentially useful fields + - ``old``: serialize only the error message + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'old' + | Environment variable: TT_COMPAT_BOX_ERROR_SERIALIZE_VERBOSE + +.. _configuration_reference_compat_error_unpack: + +.. confval:: compat.box_error_unpack_type_and_code + + **Since:** :doc:`3.1.0 ` + + Whether to show error fields in ``box.error.unpack()``: + + - ``new``: do not show ``base_type`` and ``custom_type`` fields; do not show + the ``code`` field if it is 0. Note that ``base_type`` is still accessible for an error object. + - ``old``: show all fields + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'old' + | Environment variable: TT_COMPAT_BOX_ERROR_UNPACK_TYPE_AND_CODE + +.. _configuration_reference_compat_cluster_meaning: + +.. confval:: compat.box_info_cluster_meaning + + Define the behavior of ``box.info.cluster``: + + - ``new``: show the entire cluster + - ``old:``: show the current replica set + + See also: :ref:`compat-option-box-info-cluster` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_INFO_CLUSTER_MEANING + + +.. _configuration_reference_compat_session_push: + +.. confval:: compat.box_session_push_deprecation + + Whether to raise errors on attempts to call the deprecated function ``box.session.push``: + + - ``new``: raise an error + - ``old``: do not raise an error + + See also: :ref:`compat-option-session-push-deprecation` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'old' + | Environment variable: TT_COMPAT_BOX_SESSION_PUSH_DEPRECATION + +.. _configuration_reference_compat_space_execute: + +.. confval:: compat.box_space_execute_priv + + Whether the ``execute`` privilege can be granted on spaces: + + - ``new``: an error is raised + - ``old``: the privilege can be granted with no actual effect + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_SPACE_EXECUTE_PRIV + +.. _configuration_reference_compat_space_max: + +.. confval:: compat.box_space_max + + Set the maximum space identifier (``box.schema.SPACE_MAX``): + + - ``new``: 2147483646 + - ``old``: 2147483647 + + The limit was decremented because the old max value is used as an error indicator in the ``box`` C API. + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_SPACE_MAX + +.. _configuration_reference_compat_tuple_extension: + +.. confval:: compat.box_tuple_extension + + Controls ``IPROTO_FEATURE_CALL_RET_TUPLE_EXTENSION`` and + ``IPROTO_FEATURE_CALL_ARG_TUPLE_EXTENSION`` feature bits that + define tuple encoding in iproto ``call`` and ``eval`` requests. + + - ``new``: tuples with formats are encoded as ``MP_TUPLE`` + - ``old``: tuples with formats are encoded as ``MP_ARRAY`` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_TUPLE_EXTENSION + +.. _configuration_reference_compat_tuple_new: + +.. confval:: compat.box_tuple_new_vararg + + Controls how ``box.tuple.new`` interprets an argument list: + + - ``new``: as a value with a tuple format + - ``old``: as an array of tuple fields + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_BOX_TUPLE_NEW_VARARG + + +.. _configuration_reference_compat_iproto_multireturn: + +.. confval:: compat.c_func_iproto_multireturn + + Controls wrapping of multiple results of a stored C function when returning them via iproto: + + - ``new``: return without wrapping (consistently with a local call via ``box.func``) + - ``old``: wrap results into a MessagePack array + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_C_FUNC_IPROTO_MULTIRETURN + +.. _configuration_reference_compat_fiber_channel: + +.. confval:: compat.fiber_channel_close_mode + + Define the behavior of fiber channels after closing: + + - ``new``: mark the channel read-only + - ``old``: destroy the channel object + + See also: :ref:`compat-option-fiber-channel` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_FIBER_CHANNEL_CLOSE_MODE + +.. _configuration_reference_compat_fiber_slice: + +.. confval:: compat.fiber_slice_default + + Define the maximum fiber execution time without a yield: + + - ``new``: ``{warn = 0.5, err = 1.0}`` + - ``old``: infinity (no warnings or errors raised). + + See also: :ref:`compat-option-fiber-slice` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_FIBER_SLICE_DEFAULT + +.. _configuration_reference_compat_json_escape: + +.. confval:: compat.json_escape_forward_slash + + Whether to escape the forward slash symbol '/' using a backslash in a ``json.encode()`` result: + + - ``new``: do not escape the forward slash + - ``old``: escape the forward slash + + See also: :ref:`compat-option-json-slash` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_JSON_ESCAPE_FORWARD_SLASH + +.. _configuration_reference_compat_sql_priv: + +.. confval:: compat.sql_priv + + Whether to enable access checks for SQL requests over iproto: + + - ``new``: check the user's access permissions + - ``old``: allow any user to execute SQL over iproto + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_SQL_PRIV + +.. _configuration_reference_compat_sql_scan: + +.. confval:: compat.sql_seq_scan_default + + Controls the default value of the ``sql_seq_scan`` session setting: + + - ``new``: false + - ``old``: true + + See also: :ref:`compat-option-sql-scan` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_SQL_SEQ_SCAN_DEFAULT + +.. _configuration_reference_compat_yaml_pretty: + +.. confval:: compat.yaml_pretty_multiline + + Whether to encode in block scalar style all multiline strings or ones containing the ``\n\n`` substring: + + - ``new``: all multiline strings + - ``old``: only strings containing the ``\n\n`` substring + + See also: :ref:`compat-option-lyaml` + + | + | Type: string + | Possible values: 'new', 'old' + | Default: 'new' + | Environment variable: TT_COMPAT_YAML_PRETTY_MULTILINE + + +.. _configuration_reference_conditional: + +conditional +----------- + +The ``conditional`` section defines the configuration parts that apply to instances +that meet certain conditions. + +.. NOTE:: + + ``conditional`` can be defined in the global :ref:`scope ` only. + +* :ref:`conditional.if ` + +.. _configuration_reference_conditional_if: + +.. confval:: conditional.if + + Specify a conditional section of the configuration. The configuration options + defined inside a ``conditional.if`` section apply only to instances on which + the specified condition is true. + + Conditions can include one variable -- ``tarantool_version``: a three-number + Tarantool version running on the instance, for example, 3.1.0. It compares to + *version literal* values that include three numbers separated by periods (``x.y.z``). + + The following operators are available in conditions: + + - comparison: ``>``, ``<``, ``>=``, ``<=``, ``==``, ``!=`` + - logical operators ``||`` (OR) and ``&&`` (AND) + - parentheses ``()`` + + **Example**: + + In this example, different configuration parts apply to instances running + Tarantool versions above and below 3.1.0: + + - On versions less than 3.1.0, the ``upgraded`` label is set to ``false``. + - On versions 3.1.0 or newer, the ``upgraded`` label is set to ``true``. + Additionally, new ``compat`` options are defined. These options were introduced + in version 3.1.0, so on older versions they would cause an error. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml + :language: yaml + :start-at: conditional: + :end-before: groups: + :dedent: + + See also: :ref:`configuration_conditional` + +.. _configuration_reference_config: + +config +------ + +The ``config`` section defines various parameters related to centralized configuration. + +.. NOTE:: + + ``config`` can be defined in the global :ref:`scope ` only. + +* :ref:`config.reload ` +* :ref:`config.context.* ` +* :ref:`config.etcd.* ` +* :ref:`config.storage.* ` + +.. _configuration_reference_config_reload: + +.. confval:: config.reload + + Specify how the configuration is reloaded. + This option accepts the following values: + + - ``auto``: configuration is reloaded automatically when it is changed. + - ``manual``: configuration should be reloaded manually. In this case, you can reload the configuration in the application code using :ref:`config:reload() `. + + See also: :ref:`Reloading configuration ` + + | + | Type: string + | Possible values: 'auto', 'manual' + | Default: 'auto' + | Environment variable: TT_CONFIG_RELOAD + + +.. _configuration_reference_config_context_options: + +config.context.* +~~~~~~~~~~~~~~~~ + +This section describes options related to loading configuration settings from external storage such as external files or environment variables. + +* :ref:`config.context ` + + * :ref:`config.context.\ ` + + * :ref:`config.context.\.env ` + * :ref:`config.context.\.from ` + * :ref:`config.context.\.file ` + * :ref:`config.context.\.env ` + +.. _configuration_reference_config_context: + +.. confval:: config.context + + Specify how to load settings from external storage. + For example, this option can be used to load passwords from safe storage. + You can find examples in the :ref:`configuration_credentials_loading_secrets` section. + + | + | Type: map + | Default: nil + | Environment variable: TT_CONFIG_CONTEXT + + +.. _configuration_reference_config_context_name: + +.. confval:: config.context. + + The name of an entity that identifies a configuration value to load. + +.. _configuration_reference_config_context_name_env: + +.. confval:: config.context..env + + The name of an environment variable to load a configuration value from. + To load a configuration value from an environment variable, set :ref:`config.context.\.from ` to ``env``. + + **Example** + + In this example, passwords are loaded from the ``DBADMIN_PASSWORD`` and ``SAMPLEUSER_PASSWORD`` environment variables: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_env/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets` + + +.. _configuration_reference_config_context_name_from: + +.. confval:: config.context..from + + The type of storage to load a configuration value from. + There are the following storage types: + + * ``file``: load a configuration value from a file. + In this case, you need to specify the path to the file using :ref:`config.context.\.file `. + * ``env``: load a configuration value from an environment variable. + In this case, specify the environment variable name using :ref:`config.context.\.env `. + + +.. _configuration_reference_config_context_name_file: + +.. confval:: config.context..file + + The path to a file to load a configuration value from. + To load a configuration value from a file, set :ref:`config.context.\.from ` to ``file``. + + **Example** + + In this example, passwords are loaded from the ``dbadmin_password.txt`` and ``sampleuser_password.txt`` files: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials_context_file/config.yaml + :language: yaml + :start-at: config: + :end-before: credentials: + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets` + + +.. _configuration_reference_config_context_name_rstrip: + +.. confval:: config.context..rstrip + + (Optional) Whether to strip whitespace characters and newlines from the end of data. + +.. _configuration_reference_config_etcd: + +config.etcd.* +~~~~~~~~~~~~~ + +.. include:: /platform/configuration/configuration_etcd.rst + :start-after: ee_note_centralized_config_start + :end-before: ee_note_centralized_config_end + +This section describes options related to providing connection settings to a :ref:`centralized etcd-based storage `. +If :ref:`replication.failover ` is set to ``supervised``, Tarantool also uses etcd to maintain the state of failover coordinators. + +.. NOTE:: + + Note that a :ref:`centralized cluster configuration ` cannot contain the ``config.etcd`` section. + +* :ref:`config.etcd.endpoints ` +* :ref:`config.etcd.prefix ` +* :ref:`config.etcd.username ` +* :ref:`config.etcd.password ` +* :ref:`config.etcd.ssl.ca_file ` +* :ref:`config.etcd.ssl.ca_path ` +* :ref:`config.etcd.ssl.ssl_cert ` +* :ref:`config.etcd.ssl.ssl_key ` +* :ref:`config.etcd.ssl.verify_host ` +* :ref:`config.etcd.ssl.verify_peer ` +* :ref:`config.etcd.http.request.timeout ` +* :ref:`config.etcd.http.request.unix_socket ` +* :ref:`config.etcd.watchers.reconnect_max_attempts ` +* :ref:`config.etcd.watchers.reconnect_timeout ` + +.. _config_etcd_endpoints: + +.. confval:: config.etcd.endpoints + + The list of endpoints used to access an etcd server. + + See also: :ref:`etcd_local_configuration` + + | + | Type: array + | Default: nil + | Environment variable: TT_CONFIG_ETCD_ENDPOINTS + +.. _config_etcd_prefix: + +.. confval:: config.etcd.prefix + + A key prefix used to search a configuration on an etcd server. + Tarantool searches keys by the following path: ``/config/*``. + Note that ```` should start with a slash (``/``). + + See also: :ref:`etcd_local_configuration` + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PREFIX + +.. _config_etcd_username: + +.. confval:: config.etcd.username + + A username used for authentication. + + See also: :ref:`etcd_local_configuration` + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_USERNAME + +.. _config_etcd_password: + +.. confval:: config.etcd.password + + A password used for authentication. + + See also: :ref:`etcd_local_configuration` + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PASSWORD + +.. _config_etcd_ssl_ca_file: + +.. confval:: config.etcd.ssl.ca_file + + A path to a trusted certificate authorities (CA) file. + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_FILE + +.. _config_etcd_ssl_ca_path: + +.. confval:: config.etcd.ssl.ca_path + + A path to a directory holding certificates to verify the peer with. + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_PATH + +.. _config_etcd_ssl_ssl_cert: + +.. confval:: config.etcd.ssl.ssl_cert + + **Since:** :doc:`3.2.0 ` + + A path to an SSL certificate file. + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_SSL_CERT + +.. _config_etcd_ssl_ssl_key: + +.. confval:: config.etcd.ssl.ssl_key + + A path to a private SSL key file. + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_SSL_KEY + +.. _config_etcd_ssl_verify_host: + +.. confval:: config.etcd.ssl.verify_host + + Enable verification of the certificate's name (CN) against the specified host. + + | + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_HOST + + +.. _config_etcd_ssl_verify_peer: + +.. confval:: config.etcd.ssl.verify_peer + + Enable verification of the peer's SSL certificate. + + | + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_PEER + + +.. _config_etcd_http_request_timeout: + +.. confval:: config.etcd.http.request.timeout + + A time period required to process an HTTP request to an etcd server: from sending a request to receiving a response. + + See also: :ref:`etcd_local_configuration` + + | + | Type: number + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_TIMEOUT + +.. _config_etcd_http_request_unix_socket: + +.. confval:: config.etcd.http.request.unix_socket + + A Unix domain socket used to connect to an etcd server. + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_UNIX_SOCKET + +.. _config_etcd_watchers_reconnect_max_attempts: + +.. confval:: config.etcd.watchers.reconnect_max_attempts + + **Since:** :doc:`3.1.0 ` + + The maximum number of attempts to reconnect to an etcd server in case of connection failure. + + | + | Type: integer + | Default: nil + | Environment variable: TT_CONFIG_ETCD_WATCHERS_RECONNECT_MAX_ATTEMPTS + +.. _config_etcd_watchers_reconnect_timeout: + +.. confval:: config.etcd.watchers.reconnect_timeout + + **Since:** :doc:`3.1.0 ` + + The timeout (in seconds) between attempts to reconnect to an etcd server in case of connection failure. + + | + | Type: number + | Default: nil + | Environment variable: TT_CONFIG_ETCD_WATCHERS_RECONNECT_TIMEOUT + + +.. _configuration_reference_config_storage: + +config.storage.* +~~~~~~~~~~~~~~~~ + +.. include:: /platform/configuration/configuration_etcd.rst + :start-after: ee_note_centralized_config_start + :end-before: ee_note_centralized_config_end + +This section describes options related to providing connection settings to a :ref:`centralized Tarantool-based storage `. + +.. NOTE:: + + Note that a :ref:`centralized cluster configuration ` cannot contain the ``config.storage`` section. + +* :ref:`config.storage.endpoints ` +* :ref:`config.storage.prefix ` +* :ref:`config.storage.reconnect_after ` +* :ref:`config.storage.timeout ` + +.. _config_storage_endpoints: + +.. confval:: config.storage.endpoints + + An array of endpoints used to access a configuration storage. + Each endpoint can include the following fields: + + * ``uri``: a URI of the configuration storage's instance. + * ``login``: a username used to connect to the instance. + * ``password``: a password used for authentication. + * ``params``: SSL parameters required for :ref:`encrypted connections ` (:ref:`.params.* `). + + See also: :ref:`centralized_configuration_storage_connect_tarantool` + + | + | Type: array + | Default: nil + | Environment variable: TT_CONFIG_STORAGE_ENDPOINTS + + +.. _config_storage_prefix: + +.. confval:: config.storage.prefix + + A key prefix used to search a configuration in a centralized configuration storage. + Tarantool searches keys by the following path: ``/config/*``. + Note that ```` should start with a slash (``/``). + + See also: :ref:`centralized_configuration_storage_connect_tarantool` + + | + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_STORAGE_PREFIX + + +.. _config_storage_reconnect_after: + +.. confval:: config.storage.reconnect_after + + A number of seconds to wait before reconnecting to a configuration storage. + + | + | Type: number + | Default: 3 + | Environment variable: TT_CONFIG_STORAGE_RECONNECT_AFTER + + +.. _config_storage_timeout: + +.. confval:: config.storage.timeout + + The interval (in seconds) to perform the status check of a configuration storage. + + See also: :ref:`centralized_configuration_storage_connect_tarantool` + + | + | Type: number + | Default: 3 + | Environment variable: TT_CONFIG_STORAGE_TIMEOUT + +.. _configuration_reference_console: + +console +------- + +Configure the administrative console. A client to the console is ``tt connect``. + +.. NOTE:: + + ``console`` can be defined in any :ref:`scope `. + +* :ref:`console.enabled ` +* :ref:`console.socket ` + +.. _configuration_reference_console_enabled: + +.. confval:: console.enabled + + Whether to listen on the Unix socket provided in the + :ref:`console.socket ` option. + + If the option is set to ``false``, the administrative console is disabled. + + | + | Type: boolean + | Default: true + | Environment variable: TT_CONSOLE_ENABLED + +.. _configuration_reference_console_socket: + +.. confval:: console.socket + + The Unix socket for the administrative console. + + Mind the following nuances: + + * Only a Unix domain socket is allowed. A TCP socket can't be configured this way. + * ``console.socket`` is a file path, without any ``unix:`` or ``unix/:`` prefixes. + * If the file path is a relative path, it is interpreted relative to + :ref:`process.work_dir `. + + | + | Type: string + | Default: 'var/run/{{ instance_name }}/tarantool.control' + | Environment variable: TT_CONSOLE_SOCKET + +.. _configuration_reference_credentials: + +credentials +----------- + +The ``credentials`` section allows you to create users and grant them the specified privileges. +Learn more in :ref:`configuration_credentials`. + +.. NOTE:: + + ``credentials`` can be defined in any :ref:`scope `. + +* :ref:`credentials.roles.* ` +* :ref:`credentials.users.* ` +* :ref:`.privileges.* ` + +.. _configuration_reference_credentials_roles_options: + +credentials.roles.* +~~~~~~~~~~~~~~~~~~~ + +* :ref:`credentials.roles ` + + * :ref:`credentials.roles.\.roles ` + * :ref:`credentials.roles.\.privileges ` + +.. _configuration_reference_credentials_roles: + +.. confval:: credentials.roles + + An array of :ref:`roles ` that can be granted to users or other roles. + + **Example** + + In the example below, the ``writers_space_reader`` role gets privileges to select data in the ``writers`` space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-after: spaces: [ books ] + :end-at: spaces: [ writers ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles` + + | + | Type: map + | Default: nil + | Environment variable: TT_CREDENTIALS_ROLES + +.. _configuration_reference_credentials_roles_name_roles: + +.. confval:: credentials.roles..roles + + An array of :ref:`roles ` granted to this role. + +.. _configuration_reference_credentials_roles_name_privileges: + +.. confval:: credentials.roles..privileges + + An array of :ref:`privileges ` granted to this role. + + See :ref:`\.privileges.* `. + +.. _configuration_reference_credentials_users_options: + +credentials.users.* +~~~~~~~~~~~~~~~~~~~ + +* :ref:`credentials.users ` + + * :ref:`credentials.users.\.password ` + * :ref:`credentials.users.\.roles ` + * :ref:`credentials.users.\.privileges ` + +.. _configuration_reference_credentials_users: + +.. confval:: credentials.users + + An array of :ref:`users `. + + **Example** + + In this example, ``sampleuser`` gets the following privileges: + + * Privileges granted to the ``writers_space_reader`` role. + * Privileges to select and modify data in the ``books`` space. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles` + + | + | Type: map + | Default: nil + | Environment variable: TT_CREDENTIALS_USERS + + +.. _configuration_reference_credentials_users_name_password: + +.. confval:: credentials.users..password + + A user's password. + + **Example** + + In the example below, a password for the ``dbadmin`` user is set: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: credentials: + :end-at: T0p_Secret + :dedent: + + See also: :ref:`configuration_credentials_loading_secrets` + +.. _configuration_reference_credentials_users_name_roles: + +.. confval:: credentials.users..roles + + An array of :ref:`roles ` granted to this user. + +.. _configuration_reference_credentials_users_name_privileges: + +.. confval:: credentials.users..privileges + + An array of :ref:`privileges ` granted to this user. + + See :ref:`\.privileges.* `. + +.. _configuration_reference_credentials_privileges_options: + +.privileges.* +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`\.privileges ` + + * :ref:`\.privileges.permissions ` + * :ref:`\.privileges.spaces ` + * :ref:`\.privileges.functions ` + * :ref:`\.privileges.sequences ` + * :ref:`\.privileges.lua_eval ` + * :ref:`\.privileges.lua_call ` + * :ref:`\.privileges.sql ` + +.. _configuration_reference_credentials_privileges: + +.. confval:: .privileges + + Privileges that can be granted to a user or role using the following options: + + * :ref:`credentials.users.\.privileges ` + * :ref:`credentials.roles.\.privileges ` + +.. _configuration_reference_credentials_privileges_permissions: + +.. confval:: .privileges.permissions + + :ref:`Permissions ` assigned to this user or a user with this role. + + **Example** + + In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles` + +.. _configuration_reference_credentials_privileges_spaces: + +.. confval:: .privileges.spaces + + Spaces to which this user or a user with this role gets the specified permissions. + + **Example** + + In this example, ``sampleuser`` gets privileges to select and modify data in the ``books`` space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/credentials/config.yaml + :language: yaml + :start-at: sampleuser: + :end-at: [ books ] + :dedent: + + See also: :ref:`configuration_credentials_managing_users_roles` + +.. _configuration_reference_credentials_privileges_functions: + +.. confval:: .privileges.functions + + Functions to which this user or a user with this role gets the specified permissions. + +.. _configuration_reference_credentials_privileges_sequences: + +.. confval:: .privileges.sequences + + Sequences to which this user or a user with this role gets the specified permissions. + +.. _configuration_reference_credentials_privileges_lua_eval: + +.. confval:: .privileges.lua_eval + + Whether this user or a user with this role can execute arbitrary Lua code. + +.. _configuration_reference_credentials_privileges_lua_call: + +.. confval:: .privileges.lua_call + + A list of global user-defined Lua functions that this user or a user with this role can call. + To allow calling a specific function, specify its name as the value. + To allow calling all global Lua functions except built-in ones functions, specify the ``all`` value. + + This option should be configured together with the ``execute`` + :ref:`permission `. + + Since version :doc:`3.3.0 `, the ``lua_call`` option allows granting users privileges to call specified lua function on + the instance in runtime (thus it doesn't require an ability to write to the database). + + Example to grant custom functions to the 'alice' user: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/lua_call/config.yaml + :language: yaml + :dedent: + +.. _configuration_reference_credentials_privileges_sql: + +.. confval:: .privileges.sql + + Whether this user or a user with this role can execute an arbitrary SQL expression. + +.. _configuration_reference_database: + +database +-------- + +The ``database`` section defines database-specific configuration parameters, such as an instance's read-write mode or transaction isolation level. + +.. NOTE:: + + ``database`` can be defined in any :ref:`scope `. + +- :ref:`database.hot_standby ` +- :ref:`database.instance_uuid ` +- :ref:`database.mode ` +- :ref:`database.replicaset_uuid ` +- :ref:`database.txn_isolation ` +- :ref:`database.txn_timeout ` +- :ref:`database.use_mvcc_engine ` + +.. _configuration_reference_database_hot_standby: + +.. confval:: database.hot_standby + + Whether to start the server in the hot standby mode. + This mode can be used to provide failover without :ref:`replication `. + + Suppose there are two cluster applications. + Each cluster has one instance with the same configuration: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/hot_standby_1/config.yaml + :language: yaml + :dedent: + + In particular, both instances use the same directory for storing write-ahead logs and snapshots. + + When you start both cluster applications on the same machine, the instance from the first one will be the primary instance and the second will be the standby instance. + In the :ref:`logs ` of the second cluster instance, you should see a notification: + + .. code-block:: text + + main/104/interactive I> Entering hot standby mode + + This means that the standby instance is ready to take over if the primary instance goes down. + The standby instance initializes and tries to take a lock on a directory for storing write-ahead logs + but fails because the primary instance has made a lock on this directory. + + If the primary instance goes down for any reason, the lock is released. + In this case, the standby instance succeeds in taking the lock and becomes the primary instance. + + ``database.hot_standby`` has no effect: + + * If :ref:`wal.mode ` is set to ``none``. + * If :ref:`wal.dir_rescan_delay ` is set to a large value on macOS or FreeBSD. On these platforms, the hot standby mode is designed so that the loop repeats every ``wal.dir_rescan_delay`` seconds. + * For spaces created with :ref:`engine ` set to ``vinyl``. + + Examples on GitHub: `hot_standby_1 `_, `hot_standby_2 `_ + + | + | Type: boolean + | Default: false + | Environment variable: TT_DATABASE_HOT_STANDBY + +.. _configuration_reference_database_instance_uuid: + +.. confval:: database.instance_uuid + + An :ref:`instance UUID `. + + By default, instance UUIDs are generated automatically. + ``database.instance_uuid`` can be used to specify an instance identifier manually. + + UUIDs should follow these rules: + + * The values must be true unique identifiers, not shared by other instances + or replica sets within the common infrastructure. + + * The values must be used consistently, not changed after the initial setup. + The initial values are stored in :ref:`snapshot files ` + and are checked whenever the system is restarted. + + .. TODO: https://github.com/tarantool/doc/issues/3661 mention that UUIDs can be dropped during migration. + + * The values must comply with `RFC 4122 `_. + The `nil UUID `_ is not allowed. + + See also: :ref:`database.replicaset_uuid ` + + | + | Type: string + | Default: :ref:`box.NULL ` + | Environment variable: TT_DATABASE_INSTANCE_UUID + + +.. _configuration_reference_database_mode: + +.. confval:: database.mode + + An instance's operating mode. + This option is in effect if :ref:`replication.failover ` is set to ``off``. + + The following modes are available: + + - ``rw``: an instance is in read-write mode. + - ``ro``: an instance is in read-only mode. + + If not specified explicitly, the default value depends on the number of instances in a replica set. For a single instance, the ``rw`` mode is used, while for multiple instances, the ``ro`` mode is used. + + **Example** + + You can set the ``database.mode`` option to ``rw`` on all instances in a replica set to make a :ref:`master-master ` configuration. + In this case, ``replication.failover`` should be set to ``off``. + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/master_master/config.yaml + :language: yaml + :dedent: + + | + | Type: string + | Default: :ref:`box.NULL ` (the actual default value depends on the number of instances in a replica set) + | Environment variable: TT_DATABASE_MODE + + +.. _configuration_reference_database_replicaset_uuid: + +.. confval:: database.replicaset_uuid + + A :ref:`replica set UUID `. + + By default, replica set UUIDs are generated automatically. + ``database.replicaset_uuid`` can be used to specify a replica set identifier manually. + + See also: :ref:`database.instance_uuid ` + + | + | Type: string + | Default: :ref:`box.NULL ` + | Environment variable: TT_DATABASE_REPLICASET_UUID + + +.. _configuration_reference_database_txn_isolation: + +.. confval:: database.txn_isolation + + A transaction :ref:`isolation level `. + + | + | Type: string + | Default: ``best-effort`` + | Possible values: ``best-effort``, ``read-committed``, ``read-confirmed`` + | Environment variable: TT_DATABASE_TXN_ISOLATION + + +.. _configuration_reference_database_txn_timeout: + +.. confval:: database.txn_timeout + + A timeout (in seconds) after which the transaction is rolled back. + + See also: :ref:`box.begin() ` + + | + | Type: number + | Default: 3153600000 (~100 years) + | Environment variable: TT_DATABASE_TXN_TIMEOUT + + +.. _configuration_reference_database_use_mvcc_engine: + +.. confval:: database.use_mvcc_engine + + Whether the :ref:`transactional manager ` is enabled. + + | + | Type: boolean + | Default: false + | Environment variable: TT_DATABASE_USE_MVCC_ENGINE + +.. _configuration_reference_failover: + +failover +-------- + +The ``failover`` section defines parameters related to a :ref:`supervised failover `. + +.. NOTE:: + + ``failover`` can be defined in the global :ref:`scope ` only. + +- :ref:`failover.log.to ` +- :ref:`failover.log.file ` +- :ref:`failover.call_timeout ` +- :ref:`failover.connect_timeout ` +- :ref:`failover.lease_interval ` +- :ref:`failover.probe_interval ` +- :ref:`failover.renew_interval ` +- :ref:`failover.stateboard.* ` + +.. _configuration_reference_failover_log_to: + +.. confval:: failover.log.to + + **Since:** :doc:`3.3.0 ` + + .. admonition:: Enterprise Edition + :class: fact + + Configuring ``failover.log.to`` and ``failover.log.file`` parameters is available in the `Enterprise Edition `_ only. + + + Define a location Tarantool sends failover logs to. + This option accepts the following values: + + * ``stderr``: write logs to the standard error stream. + * ``file``: write logs to a file (see :ref:`failover.log.file `). + + | + | Type: string + | Default: 'stderr' + | Environment variable: TT_FAILOVER_LOG_TO + + +.. _configuration_reference_failover_log_file: + +.. confval:: failover.log.file + + **Since:** :doc:`3.3.0 ` + + Specify a file for failover logs destination. + To write logs to a file, set :ref:`failover.log.to ` to ``file``. + Otherwise, ``failover.log.file`` is ignored. + + **Example** + + The example below shows how to write failover logs to a file placed in the specified directory: + + .. code-block:: yaml + + failover: + log: + to: file + file: var/log/failover.log + + | + | Type: string + | Default: nil + | Environment variable: TT_FAILOVER_LOG_FILE + +.. _configuration_reference_failover_call_timeout: + +.. confval:: failover.call_timeout + + **Since:** :doc:`3.1.0 ` + + A call timeout (in seconds) for monitoring and failover requests to an instance. + + | Type: number + | Default: 1 + | Environment variable: TT_FAILOVER_CALL_TIMEOUT + +.. _configuration_reference_failover_connect_timeout: + +.. confval:: failover.connect_timeout + + **Since:** :doc:`3.1.0 ` + + A connection timeout (in seconds) for monitoring and failover requests to an instance. + + | Type: number + | Default: 1 + | Environment variable: TT_FAILOVER_CONNECT_TIMEOUT + +.. _configuration_reference_failover_lease_interval: + +.. confval:: failover.lease_interval + + **Since:** :doc:`3.1.0 ` + + A time interval (in seconds) that specifies how long an instance should be a leader without renew requests from a coordinator. + When this interval expires, the leader switches to read-only mode. + This action is performed by the instance itself and works even if there is no connectivity between the instance and the coordinator. + + | Type: number + | Default: 30 + | Environment variable: TT_FAILOVER_LEASE_INTERVAL + +.. _configuration_reference_failover_probe_interval: + +.. confval:: failover.probe_interval + + **Since:** :doc:`3.1.0 ` + + A time interval (in seconds) that specifies how often a monitoring service of the failover coordinator polls an instance for its status. + + | Type: number + | Default: 10 + | Environment variable: TT_FAILOVER_PROBE_INTERVAL + +.. _configuration_reference_failover_renew_interval: + +.. confval:: failover.renew_interval + + **Since:** :doc:`3.1.0 ` + + A time interval (in seconds) that specifies how often a failover coordinator sends read-write deadline renewals. + + | Type: number + | Default: 10 + | Environment variable: TT_FAILOVER_RENEW_INTERVAL + + +.. _configuration_reference_failover_stateboard: + +failover.stateboard.* +~~~~~~~~~~~~~~~~~~~~~ + +``failover.stateboard.*`` options define configuration parameters related to maintaining the state of failover coordinators in a remote etcd-based storage. + +* :ref:`failover.stateboard.keepalive_interval ` +* :ref:`failover.stateboard.renew_interval ` + +See also: :ref:`supervised_failover_overview_fault_tolerance` + +.. _configuration_reference_failover_stateboard_keepalive_interval: + +.. confval:: failover.stateboard.keepalive_interval + + **Since:** :doc:`3.1.0 ` + + A time interval (in seconds) that specifies how long a transient state information is stored and how quickly a lock expires. + + .. NOTE:: + + ``failover.stateboard.keepalive_interval`` should be smaller than :ref:`failover.lease_interval `. + Otherwise, switching of a coordinator causes a replica set leader to go to read-only mode for some time. + + | Type: number + | Default: 10 + | Environment variable: TT_FAILOVER_STATEBOARD_KEEPALIVE_INTERVAL + +.. _configuration_reference_failover_stateboard_renew_interval: + +.. confval:: failover.stateboard.renew_interval + + **Since:** :doc:`3.1.0 ` + + A time interval (in seconds) that specifies how often a failover coordinator writes its state information to etcd. + This option also determines the frequency at which an active coordinator reads new commands from etcd. + + | Type: number + | Default: 2 + | Environment variable: TT_FAILOVER_STATEBOARD_RENEW_INTERVAL + +.. _configuration_reference_feedback: + +feedback +-------- + +The ``feedback`` section describes configuration parameters for sending information about a running Tarantool instance to the specified feedback server. + +.. NOTE:: + + ``feedback`` can be defined in any :ref:`scope `. + +* :ref:`feedback.crashinfo ` +* :ref:`feedback.enabled ` +* :ref:`feedback.host ` +* :ref:`feedback.interval ` +* :ref:`feedback.metrics_collect_interval ` +* :ref:`feedback.metrics_limit ` +* :ref:`feedback.send_metrics ` + +.. _configuration_reference_feedback_crashinfo: + +.. confval:: feedback.crashinfo + + Whether to send crash information in the case of an instance failure. + This information includes: + + - General information from the ``uname`` output. + - Build information. + - The crash reason. + - The stack trace. + + To turn off sending crash information, set this option to ``false``. + + | + | Type: boolean + | Default: true + | Environment variable: TT_FEEDBACK_CRASHINFO + +.. _configuration_reference_feedback_enabled: + +.. confval:: feedback.enabled + + Whether to send information about a running instance to the feedback server. + To turn off sending feedback, set this option to ``false``. + + | + | Type: boolean + | Default: true + | Environment variable: TT_FEEDBACK_ENABLED + +.. _configuration_reference_feedback_host: + +.. confval:: feedback.host + + The address to which information is sent. + + | + | Type: string + | Default: https://feedback.tarantool.io + | Environment variable: TT_FEEDBACK_HOST + +.. _configuration_reference_feedback_interval: + +.. confval:: feedback.interval + + The interval (in seconds) of sending information. + + | + | Type: number + | Default: 3600 + | Environment variable: TT_FEEDBACK_INTERVAL + +.. _configuration_reference_feedback_metrics_collect_interval: + +.. confval:: feedback.metrics_collect_interval + + The interval (in seconds) for collecting metrics. + + | + | Type: number + | Default: 60 + | Environment variable: TT_FEEDBACK_METRICS_COLLECT_INTERVAL + +.. _configuration_reference_feedback_metrics_limit: + +.. confval:: feedback.metrics_limit + + The maximum size of memory (in bytes) used to store metrics before sending them to the feedback server. + If the size of collected metrics exceeds this value, earlier metrics are dropped. + + | + | Type: integer + | Default: 1024 * 1024 (1048576) + | Environment variable: TT_FEEDBACK_METRICS_LIMIT + +.. _configuration_reference_feedback_send_metrics: + +.. confval:: feedback.send_metrics + + Whether to send :ref:`metrics ` to the feedback server. + Note that all collected metrics are dropped after sending them to the feedback server. + + | + | Type: boolean + | Default: true + | Environment variable: TT_FEEDBACK_SEND_METRICS + + +.. _configuration_reference_fiber: + +fiber +----- + +The ``fiber`` section describes options related to configuring :ref:`fibers, yields, and cooperative multitasking `. + +.. NOTE:: + + ``fiber`` can be defined in any :ref:`scope `. + +* :ref:`fiber.io_collect_interval ` +* :ref:`fiber.too_long_threshold ` +* :ref:`fiber.worker_pool_threads ` +* :ref:`fiber.slice.* ` +* :ref:`fiber.top.* ` + +.. _configuration_reference_fiber_io_collect_interval: + +.. confval:: fiber.io_collect_interval + + The time period (in seconds) a :ref:`fiber ` sleeps between + iterations of the event loop. + + ``fiber.io_collect_interval`` can be used to reduce CPU load in deployments + where the number of client connections is large, but requests are not so frequent + (for example, each connection issues just a handful of requests per second). + + | + | Type: number + | Default: box.NULL + | Environment variable: TT_FIBER_IO_COLLECT_INTERVAL + +.. _configuration_reference_fiber_too_long_threshold: + +.. confval:: fiber.too_long_threshold + + If processing a request takes longer than the given period (in seconds), + the fiber warns about it in the log. + + ``fiber.too_long_threshold`` has effect only if + :ref:`log.level ` is greater than + or equal to 4 (``warn``). + + | + | Type: number + | Default: 0.5 + | Environment variable: TT_FIBER_TOO_LONG_THRESHOLD + +.. _configuration_reference_fiber_worker_pool_threads: + +.. confval:: fiber.worker_pool_threads + + The maximum number of threads to use during execution + of certain internal processes (for example, + :ref:`socket.getaddrinfo() ` and + :ref:`coio_call() `). + + | + | Type: number + | Default: 4 + | Environment variable: TT_FIBER_WORKER_POOL_THREADS + +.. _configuration_reference_fiber_slice_options: + +fiber.slice.* +~~~~~~~~~~~~~ + +This section describes options related to configuring time periods for +:ref:`fiber slices `. +See :ref:`fiber.set_max_slice ` for details and examples. + +* :ref:`fiber.slice.warn ` +* :ref:`fiber.slice.err ` + +.. _configuration_reference_fiber_slice_warn: + +.. confval:: fiber.slice.warn + + Set a time period (in seconds) that specifies the warning slice. + + | + | Type: number + | Default: 0.5 + | Environment variable: TT_FIBER_SLICE_WARN + +.. _configuration_reference_fiber_slice_err: + +.. confval:: fiber.slice.err + + Set a time period (in seconds) that specifies the error slice. + + | + | Type: number + | Default: 1 + | Environment variable: TT_FIBER_SLICE_ERR + +.. _configuration_reference_fiber_top_options: + +fiber.top.* +~~~~~~~~~~~ + +This section describes options related to configuring the +:ref:`fiber.top() ` function, normally used for debug purposes. +``fiber.top()`` shows all alive fibers and their CPU consumption. + +* :ref:`fiber.top.enabled ` + +.. _configuration_reference_fiber_top_enabled: + +.. confval:: fiber.top.enabled + + Enable or disable the ``fiber.top()`` function. + + Enabling ``fiber.top()`` slows down fiber switching by about 15%, + so it is disabled by default. + + | + | Type: boolean + | Default: false + | Environment variable: TT_FIBER_TOP_ENABLED + +.. _configuration_reference_flightrec: + +flightrec +--------- + +.. admonition:: Enterprise Edition + :class: fact + + Configuring ``flightrec`` parameters is available in the `Enterprise Edition `_ only. + +The ``flightrec`` section describes options related to the :ref:`flight recorder ` configuration. + +.. NOTE:: + + ``flightrec`` can be defined in any :ref:`scope `. + +* :ref:`flightrec.enabled ` +* :ref:`flightrec.logs_size ` +* :ref:`flightrec.logs_max_msg_size ` +* :ref:`flightrec.logs_log_level ` +* :ref:`flightrec.metrics_period ` +* :ref:`flightrec.metrics_interval ` +* :ref:`flightrec.requests_size ` +* :ref:`flightrec.requests_max_req_size ` +* :ref:`flightrec.requests_max_res_size ` + +.. _configuration_reference_flightrec_enabled: + +.. confval:: flightrec.enabled + + Enable the :ref:`flight recorder `. + + | + | Type: boolean + | Default: false + | Environment variable: TT_FLIGHTREC_ENABLED + +.. TODO not implemented yet + .. _config-directory: + + .. _configuration_reference_flightrec_dir: + + .. confval:: flightrec.dir + + Specify the directory used to store flight recordings (``*.ttfr`` files). + + | Type: string + | Default: snapshot.dir + | Environment variable: TT_FLIGHTREC_DIR + +.. _configuration_reference_flightrec_logs_size: + +.. confval:: flightrec.logs_size + + Specify the size (in bytes) of the log storage. + You can set this option to ``0`` to disable the log storage. + + | + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_LOGS_SIZE + +.. _configuration_reference_flightrec_logs_max_msg_size: + +.. confval:: flightrec.logs_max_msg_size + + Specify the maximum size (in bytes) of the log message. + The log message is truncated if its size exceeds this limit. + + | + | Type: integer + | Default: 4096 + | Maximum: 16384 + | Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE + +.. _configuration_reference_flightrec_logs_log_level: + +.. confval:: flightrec.logs_log_level + + Specify the level of detail the log has. + The default value is 6 (``VERBOSE``). + You can learn more about log levels from the :ref:`log_level ` + option description. + Note that the ``flightrec.logs_log_level`` value might differ from ``log_level``. + + | + | Type: integer + | Default: 6 + | Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL + +.. _configuration_reference_flightrec_metrics_period: + +.. confval:: flightrec.metrics_period + + Specify the time period (in seconds) that defines how long metrics are stored from the moment of dump. + So, this value defines how much historical metrics data is collected up to the moment of crash. + The frequency of metric dumps is defined by :ref:`flightrec.metrics_interval `. + + | + | Type: integer + | Default: 180 + | Environment variable: TT_FLIGHTREC_METRICS_PERIOD + + +.. _configuration_reference_flightrec_metrics_interval: + +.. confval:: flightrec.metrics_interval + + Specify the time interval (in seconds) that defines the frequency of dumping metrics. + This value shouldn't exceed :ref:`flightrec.metrics_period `. + + | + | Type: number + | Default: 1.0 + | Minimum: 0.001 + | Environment variable: TT_FLIGHTREC_METRICS_INTERVAL + + .. NOTE:: + + Given that the average size of a metrics entry is 2 kB, + you can estimate the size of the metrics storage as follows: + + .. code-block:: console + + (flightrec_metrics_period / flightrec_metrics_interval) * 2 kB + + +.. _configuration_reference_flightrec_requests_size: + +.. confval:: flightrec.requests_size + + Specify the size (in bytes) of storage for the request and response data. + You can set this parameter to ``0`` to disable a storage of requests and responses. + + | + | Type: integer + | Default: 10485760 + | Environment variable: TT_FLIGHTREC_REQUESTS_SIZE + +.. _configuration_reference_flightrec_requests_max_req_size: + +.. confval:: flightrec.requests_max_req_size + + Specify the maximum size (in bytes) of a request entry. + A request entry is truncated if this size is exceeded. + + | + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE + +.. _configuration_reference_flightrec_requests_max_res_size: + +.. confval:: flightrec.requests_max_res_size + + Specify the maximum size (in bytes) of a response entry. + A response entry is truncated if this size is exceeded. + + | + | Type: integer + | Default: 16384 + | Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE + +.. _configuration_reference_iproto: + +iproto +------ + +The ``iproto`` section is used to configure parameters related to :ref:`communicating to and between cluster instances `. + +.. NOTE:: + + ``iproto`` can be defined in any :ref:`scope `. + +* :ref:`iproto.listen ` +* :ref:`iproto.net_msg_max ` +* :ref:`iproto.readahead ` +* :ref:`iproto.threads ` +* :ref:`iproto.advertise.* ` +* :ref:`.params.* ` + + +.. _configuration_reference_iproto_listen: + +.. confval:: iproto.listen + + An array of URIs used to listen for incoming requests. + If required, you can enable SSL for specific URIs by providing additional parameters (:ref:`.params.* `). + + Note that a URI value can't contain parameters, a login, or a password. + + **Example** + + In the example below, ``iproto.listen`` is set explicitly for each instance in a cluster: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: groups: + :end-before: Load sample data + :dedent: + + See also: :ref:`Connections ` + + | + | Type: array + | Default: nil + | Environment variable: TT_IPROTO_LISTEN + +.. _configuration_reference_iproto_net_msg_max: + +.. confval:: iproto.net_msg_max + + To handle messages, Tarantool allocates :ref:`fibers `. + To prevent fiber overhead from affecting the whole system, + Tarantool restricts how many messages the fibers handle, + so that some pending requests are blocked. + + - On powerful systems, increase ``net_msg_max``, and the scheduler + starts processing pending requests immediately. + + - On weaker systems, decrease ``net_msg_max``, and the overhead + may decrease. However, this may take some time because the + scheduler must wait until already-running requests finish. + + When ``net_msg_max`` is reached, + Tarantool suspends processing of incoming packages until it + has processed earlier messages. This is not a direct restriction of + the number of fibers that handle network messages, rather it + is a system-wide restriction of channel bandwidth. + This in turn restricts the number of incoming + network messages that the + :ref:`transaction processor thread ` + handles, and therefore indirectly affects the fibers that handle + network messages. + + .. NOTE:: + + The number of fibers is smaller than the number of messages because + messages can be released as soon as they are delivered, while + incoming requests might not be processed until some time after delivery. + + | + | Type: integer + | Default: 768 + | Environment variable: TT_IPROTO_NET_MSG_MAX + +.. _configuration_reference_iproto_readahead: + +.. confval:: iproto.readahead + + The size of the read-ahead buffer associated with a client connection. + The larger the buffer, the more memory an active connection consumes, and the + more requests can be read from the operating system buffer in a single + system call. + + The recommendation is to make sure that the buffer can contain at least a few dozen requests. + Therefore, if a typical tuple in a request is large, e.g. a few kilobytes or even megabytes, the read-ahead buffer size should be increased. + If batched request processing is not used, it’s prudent to leave this setting at its default. + + | + | Type: integer + | Default: 16320 + | Environment variable: TT_IPROTO_READAHEAD + +.. _configuration_reference_iproto_threads: + +.. confval:: iproto.threads + + The number of :ref:`network threads `. + There can be unusual workloads where the network thread + is 100% loaded and the transaction processor thread is not, so the network + thread is a bottleneck. + In that case, set ``iproto_threads`` to 2 or more. + The operating system kernel determines which connection goes to + which thread. + + | + | Type: integer + | Default: 1 + | Environment variable: TT_IPROTO_THREADS + + +.. _configuration_reference_iproto_advertise: + +iproto.advertise.* +~~~~~~~~~~~~~~~~~~ + +* :ref:`iproto.advertise.client ` +* :ref:`iproto.advertise.peer ` +* :ref:`iproto.advertise.sharding ` +* :ref:`iproto.advertise.\.* ` + +.. _configuration_reference_iproto_advertise_client: + +.. confval:: iproto.advertise.client + + A URI used to advertise the current instance to clients. + + The ``iproto.advertise.client`` option accepts a URI in the following formats: + + - An address: ``host:port``. + + - A Unix domain socket: ``unix/:``. + + Note that this option doesn't allow to set a username and password. + If a remote client needs this information, it should be delivered outside of the cluster configuration. + + .. host_port_limitations_start + + .. NOTE:: + + The host value cannot be ``0.0.0.0``/``[::]`` and the port value cannot be ``0``. + + .. host_port_limitations_end + + | + | Type: string + | Default: :ref:`box.NULL ` + | Environment variable: TT_IPROTO_ADVERTISE_CLIENT + +.. _configuration_reference_iproto_advertise_peer: + +.. confval:: iproto.advertise.peer + + Settings used to advertise the current instance to other cluster members. + The format of these settings is described in :ref:`iproto.advertise.\.* `. + + **Example** + + In the example below, the following configuration options are specified: + + - In the :ref:`credentials ` section, the ``replicator`` user with the ``replication`` role is created. + - ``iproto.advertise.peer`` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` using the ``replicator`` user. + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml + :language: yaml + :start-at: credentials: + :end-at: 127.0.0.1:3303 + :dedent: + + | + | Type: map + | Environment variable: see :ref:`iproto.advertise.\.* ` + +.. _configuration_reference_iproto_advertise_sharding: + +.. confval:: iproto.advertise.sharding + + Settings used to advertise the current instance to a router and rebalancer. + The format of these settings is described in :ref:`iproto.advertise.\.* `. + + .. NOTE:: + + If ``iproto.advertise.sharding`` is not specified, advertise settings from :ref:`iproto.advertise.peer ` are used. + + **Example** + + In the example below, the following configuration options are specified: + + - In the :ref:`credentials ` section, the ``replicator`` and ``storage`` users are created. + - ``iproto.advertise.peer`` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` with the ``replicator`` user. + - ``iproto.advertise.sharding`` specifies that a router should connect to storages using an address defined in :ref:`iproto.listen ` with the ``storage`` user. + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-at: credentials: + :end-at: login: storage + :dedent: + + | + | Type: map + | Environment variable: see :ref:`iproto.advertise.\.* ` + +.. _configuration_reference_iproto_advertise.peer_sharding: + +iproto.advertise..* +************************************* + +* :ref:`iproto.advertise.\.uri ` +* :ref:`iproto.advertise.\.login ` +* :ref:`iproto.advertise.\.password ` +* :ref:`iproto.advertise.\.params ` + +.. _configuration_reference_iproto_advertise.peer_sharding.uri: + +.. confval:: iproto.advertise..uri + + (Optional) A URI used to advertise the current instance. + By default, the URI defined in :ref:`iproto.listen ` is used to advertise the current instance. + + .. include:: /reference/configuration/configuration_reference.rst + :start-after: host_port_limitations_start + :end-before: host_port_limitations_end + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_URI, TT_IPROTO_ADVERTISE_SHARDING_URI + +.. _configuration_reference_iproto_advertise.peer_sharding.login: + +.. confval:: iproto.advertise..login + + (Optional) A username used to connect to the current instance. + If a username is not set, the ``guest`` user is used. + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_LOGIN, TT_IPROTO_ADVERTISE_SHARDING_LOGIN + +.. _configuration_reference_iproto_advertise.peer_sharding.password: + +.. confval:: iproto.advertise..password + + (Optional) A password for the specified user. + If a ``login`` is specified but a password is missing, it is taken from the user's :ref:`credentials `. + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PASSWORD + +.. _configuration_reference_iproto_advertise.peer_sharding.params: + +.. confval:: iproto.advertise..params + + (Optional) URI parameters (:ref:`.params.* `) required for connecting to the current instance. + + + + +.. _configuration_reference_iproto_uri_params: + +.params.* +~~~~~~~~~~~~~~ + +.. admonition:: Enterprise Edition + :class: fact + + TLS traffic encryption is supported by the `Enterprise Edition `_ only. + +URI parameters that can be used in the :ref:`iproto.listen.\.params ` and :ref:`iproto.advertise.\.params ` options. + +* :ref:`\.params.transport ` +* :ref:`\.params.ssl_ca_file ` +* :ref:`\.params.ssl_cert_file ` +* :ref:`\.params.ssl_ciphers ` +* :ref:`\.params.ssl_key_file ` +* :ref:`\.params.ssl_password ` +* :ref:`\.params.ssl_password_file ` + +.. NOTE:: + + Note that ``.params.*`` options don't have corresponding :ref:`environment variables ` for URIs specified in ``iproto.listen``. + +.. _configuration_reference_iproto_uri_params_transport: + +.. confval:: .params.transport + + Allows you to enable :ref:`traffic encryption ` for client-server communications over binary connections. + In a Tarantool cluster, one instance might act as the server that accepts connections from other instances and the client that connects to other instances. + + ``.params.transport`` accepts one of the following values: + + - ``plain`` (default): turn off traffic encryption. + - ``ssl``: encrypt traffic by using the TLS 1.2 protocol (`Enterprise Edition `_ only). + + **Example** + + The example below demonstrates how to enable traffic encryption by using a self-signed server certificate. + The following parameters are specified for each instance: + + - ``ssl_cert_file``: a path to an SSL certificate file. + - ``ssl_key_file``: a path to a private SSL key file. + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml + :language: yaml + :start-at: replicaset001: + :dedent: + + Example on Github: `ssl_without_ca `_ + + | + | Type: string + | Default: 'plain' + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_TRANSPORT, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_TRANSPORT + +.. _configuration_reference_iproto_uri_params_ssl_ca_file: + +.. confval:: .params.ssl_ca_file + + (Optional) A path to a trusted certificate authorities (CA) file. + If not set, the peer won't be checked for authenticity. + + Both a server and a client can use the ``ssl_ca_file`` parameter: + + - If it's on the server side, the server verifies the client. + - If it's on the client side, the client verifies the server. + - If both sides have the CA files, the server and the client verify each other. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CA_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CA_FILE + +.. _configuration_reference_iproto_uri_params_ssl_cert_file: + +.. confval:: .params.ssl_cert_file + + A path to an SSL certificate file: + + - For a server, it's mandatory. + - For a client, it's mandatory if the :ref:`ssl_ca_file ` parameter is set for a server; otherwise, optional. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CERT_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CERT_FILE + +.. _configuration_reference_iproto_uri_params_ssl_ciphers: + +.. confval:: .params.ssl_ciphers + + (Optional) A colon-separated (``:``) list of SSL cipher suites the connection can use. + Note that the list is not validated: if a cipher suite is unknown, Tarantool ignores it, doesn't establish the connection, and writes to the log that no shared cipher was found. + + The supported cipher suites are: + + * ECDHE-ECDSA-AES256-GCM-SHA384 + * ECDHE-RSA-AES256-GCM-SHA384 + * DHE-RSA-AES256-GCM-SHA384 + * ECDHE-ECDSA-CHACHA20-POLY1305 + * ECDHE-RSA-CHACHA20-POLY1305 + * DHE-RSA-CHACHA20-POLY1305 + * ECDHE-ECDSA-AES128-GCM-SHA256 + * ECDHE-RSA-AES128-GCM-SHA256 + * DHE-RSA-AES128-GCM-SHA256 + * ECDHE-ECDSA-AES256-SHA384 + * ECDHE-RSA-AES256-SHA384 + * DHE-RSA-AES256-SHA256 + * ECDHE-ECDSA-AES128-SHA256 + * ECDHE-RSA-AES128-SHA256 + * DHE-RSA-AES128-SHA256 + * ECDHE-ECDSA-AES256-SHA + * ECDHE-RSA-AES256-SHA + * DHE-RSA-AES256-SHA + * ECDHE-ECDSA-AES128-SHA + * ECDHE-RSA-AES128-SHA + * DHE-RSA-AES128-SHA + * AES256-GCM-SHA384 + * AES128-GCM-SHA256 + * AES256-SHA256 + * AES128-SHA256 + * AES256-SHA + * AES128-SHA + * GOST2012-GOST8912-GOST8912 + * GOST2001-GOST89-GOST89 + + For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CIPHERS, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CIPHERS + +.. _configuration_reference_iproto_uri_params_ssl_key_file: + +.. confval:: .params.ssl_key_file + + A path to a private SSL key file: + + - For a server, it's mandatory. + - For a client, it's mandatory if the :ref:`ssl_ca_file ` parameter is set for a server; otherwise, optional. + + If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_KEY_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_KEY_FILE + +.. _configuration_reference_iproto_uri_params_ssl_password: + +.. confval:: .params.ssl_password + + (Optional) A password for an encrypted private SSL key provided using ``ssl_key_file``. + Alternatively, the password can be provided in ``ssl_password_file``. + + Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order: + + 1. If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it. + 2. If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` + one by one in the order they are written. + 3. If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, + or none of them is provided, Tarantool treats the private key as unencrypted. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD + +.. _configuration_reference_iproto_uri_params_ssl_password_file: + +.. confval:: .params.ssl_password_file + + (Optional) A text file with one or more passwords for encrypted private SSL keys provided using ``ssl_key_file`` (each on a separate line). + Alternatively, the password can be provided in ``ssl_password``. + + See also: :ref:`.params.transport ` + + | + | Type: string + | Default: nil + | Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD_FILE + +.. _configuration_reference_groups: + +groups +------ + +The ``groups`` section provides the ability to define the :ref:`full topology of a Tarantool cluster `. + +.. NOTE:: + + ``groups`` can be defined in the global :ref:`scope ` only. + +- :ref:`groups.\ ` +- :ref:`groups.\.replicasets ` +- :ref:`groups.\.\ ` + +.. _configuration_reference_groups_name: + +.. confval:: groups. + + A group name. + + The following rules are applied to group names: + + - The maximum number of symbols is 63. + - Should start with a letter. + - Can contain lowercase letters (a-z). + - Can contain digits (0-9). + - Can contain the following characters: ``-``, ``_``. + +.. _configuration_reference_groups_name_replicasets: + +.. confval:: groups..replicasets + + Replica sets that belong to this group. See :ref:`replicasets `. + +.. _configuration_reference_groups_name_config_parameter: + +.. confval:: groups.. + + Any configuration parameter that can be defined in the group :ref:`scope `. + For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the group level are applied to all instances in this group. + +.. _configuration_reference_replicasets: + +replicasets +~~~~~~~~~~~ + +.. NOTE:: + + ``replicasets`` can be defined in the group :ref:`scope ` only. + +- :ref:`replicasets.\ ` +- :ref:`replicasets.\.leader ` +- :ref:`replicasets.\.bootstrap_leader ` +- :ref:`replicasets.\.instances ` +- :ref:`replicasets.\.\ ` + +.. _configuration_reference_replicasets_name: + +.. confval:: replicasets. + + A replica set name. + + Note that the rules applied to a replica set name are the same as for groups. + Learn more in :ref:`groups.\ `. + +.. _configuration_reference_replicasets_name_leader: + +.. confval:: replicasets..leader + + A replica set leader. + This option can be used to set a replica set leader when ``manual`` :ref:`replication.failover ` is used. + + To perform :ref:`controlled failover `, ``.leader`` can be temporarily removed or set to ``null``. + + **Example** + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :start-at: replication: + :end-at: 127.0.0.1:3303 + :dedent: + +.. _configuration_reference_replicasets_name_bootstrap_leader: + +.. confval:: replicasets..bootstrap_leader + + A bootstrap leader for a replica set. + To specify a bootstrap leader manually, you need to set :ref:`replication.bootstrap_strategy ` to ``config``. + + **Example** + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/bootstrap_strategy/config.yaml + :language: yaml + :start-at: groups: + :end-at: 127.0.0.1:3303 + :dedent: + +.. _configuration_reference_replicasets_name_instances: + +.. confval:: replicasets..instances + + Instances that belong to this replica set. See :ref:`instances `. + +.. _configuration_reference_replicasets_name_config_parameter: + +.. confval:: replicasets.. + + Any configuration parameter that can be defined in the replica set :ref:`scope `. + For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the replica set level are applied to all instances in this replica set. + +.. _configuration_reference_instances: + +instances +********* + +.. NOTE:: + + ``instances`` can be defined in the replica set :ref:`scope ` only. + +- :ref:`instances.\ ` +- :ref:`instances.\.\ ` + +.. _configuration_reference_instances_name: + +.. confval:: instances. + + An instance name. + + Note that the rules applied to an instance name are the same as for groups. + Learn more in :ref:`groups.\ `. + +.. _configuration_reference_instances_name_config_parameter: + +.. confval:: instances.. + + Any configuration parameter that can be defined in the instance :ref:`scope `. + For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the instance level are applied to this instance only. + +.. _configuration_reference_isolated_mode: + +isolated mode +------ + +Since version :doc:`3.3.0 `, a new ``isolated`` option is added to instance configuration. + +The option takes boolean values, by default it is set to ``false``. +``isolated: true`` moves the instance it has been applied at to the **isolated** mode. + +The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it. + +In the isolated mode: + +* The instance is moved to the read-only state +* iproto stops listening for new connections +* iproto drops all the current connections +* The instance is disconnected from all the replication upstreams +* Other replicaset members exclude the isolated instance from the replication upstreams + +.. NOTE:: + + Isolated instance can't be bootstrapped (a local snapshot is required to start). + +**Example** + + The example below shows how to isolate an instance: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml + :language: yaml + :dedent: + +.. _configuration_reference_labels: + +labels +------ + +The ``labels`` section allows adding custom attributes to the configuration. +Attributes must be ``key: value`` pairs with string keys and values. + + +.. NOTE:: + + ``labels`` can be defined in any :ref:`scope `. + +- :ref:`labels.\ ` + +.. _configuration_reference_labels_name: + +.. confval:: labels. + + A value of the label with the specified name. + + **Example** + + The example below shows how to define labels on the replica set and instance levels: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml + :language: yaml + :dedent: + + See also: :ref:`configuration_labels` + +.. _configuration_reference_log: + +log +--- + +The ``log`` section defines configuration parameters related to logging. +To handle logging in your application, use the :ref:`log module `. + +.. NOTE:: + + ``log`` can be defined in any :ref:`scope `. + +* :ref:`log.to ` +* :ref:`log.file ` +* :ref:`log.format ` +* :ref:`log.level ` +* :ref:`log.modules ` +* :ref:`log.nonblock ` +* :ref:`log.pipe ` +* :ref:`log.syslog.* ` + +.. _configuration_reference_log_to: + +.. confval:: log.to + + Define a location Tarantool sends logs to. + This option accepts the following values: + + * ``stderr``: write logs to the standard error stream. + * ``file``: write logs to a file (see :ref:`log.file `). + * ``pipe``: start a program and write logs to its standard input (see :ref:`log.pipe `). + * ``syslog``: write logs to a system logger (see :ref:`log.syslog.* `). + + | + | Type: string + | Default: 'stderr' + | Environment variable: TT_LOG_TO + +.. _configuration_reference_log_file: + +.. confval:: log.file + + Specify a file for logs destination. + To write logs to a file, you need to set :ref:`log.to ` to ``file``. + Otherwise, ``log.file`` is ignored. + + **Example** + + The example below shows how to write logs to a file placed in the specified directory: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_file/config.yaml + :language: yaml + :start-at: log: + :end-at: instance.log + :dedent: + + Example on GitHub: `log_file `_ + + | + | Type: string + | Default: 'var/log/{{ instance_name }}/tarantool.log' + | Environment variable: TT_LOG_FILE + +.. _configuration_reference_log_format: + +.. confval:: log.format + + Specify a format that is used for a log entry. + The following formats are supported: + + * ``plain``: a log entry is formatted as plain text. Example: + + .. code-block:: text + + 2024-04-09 11:00:10.369 [12089] main/104/interactive I> log level 5 (INFO) + + * ``json``: a log entry is formatted as JSON and includes additional fields. Example: + + .. code-block:: text + + { + "time": "2024-04-09T11:00:57.174+0300", + "level": "INFO", + "message": "log level 5 (INFO)", + "pid": 12160, + "cord_name": "main", + "fiber_id": 104, + "fiber_name": "interactive", + "file": "src/main.cc", + "line": 498 + } + + | + | Type: string + | Default: 'plain' + | Environment variable: TT_LOG_FORMAT + + +.. _configuration_reference_log_level: + +.. confval:: log.level + + Specify the level of detail logs have. + There are the following levels: + + * 0 -- ``fatal`` + * 1 -- ``syserror`` + * 2 -- ``error`` + * 3 -- ``crit`` + * 4 -- ``warn`` + * 5 -- ``info`` + * 6 -- ``verbose`` + * 7 -- ``debug`` + + By setting ``log.level``, you can enable logging of all events with severities above or equal to the given level. + + **Example** + + The example below shows how to log all events with severities above or equal to the ``VERBOSE`` level. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_level/config.yaml + :language: yaml + :start-at: log: + :end-at: verbose + :dedent: + + Example on GitHub: `log_level `_ + + | + | Type: number, string + | Default: 5 + | Environment variable: TT_LOG_LEVEL + +.. _configuration_reference_log_modules: + +.. confval:: log.modules + + Configure the specified log levels (:ref:`log.level `) for different modules. + + You can specify a logging level for the following module types: + + * Modules (files) that use the default logger. + Example: :ref:`Set log levels for files that use the default logger `. + + * Modules that use custom loggers created using the :ref:`log.new() ` function. + Example: :ref:`Set log levels for modules that use custom loggers `. + + * The ``tarantool`` module that enables you to configure the logging level for Tarantool core messages. + Specifically, it configures the logging level for messages logged from non-Lua code, including C modules. + Example: :ref:`Set a log level for C modules `. + + .. _configuration_reference_log_modules_example_existing_modules: + + **Example 1: Set log levels for files that use the default logger** + + Suppose you have two identical modules placed by the following paths: ``test/module1.lua`` and ``test/module2.lua``. + These modules use the default logger and look as follows: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/test/module1.lua + :language: lua + :dedent: + + To configure logging levels, you need to provide module names corresponding to paths to these modules: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + To load these modules in your application (``app.lua``), you need to add the corresponding ``require`` directives: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua + :language: lua + :start-at: module1 = require + :end-at: module2 = require + :dedent: + + Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1.say_hello()`` shows a message but ``module2.say_hello()`` is swallowed: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_modules/app.lua + :language: lua + :start-after: module2 = require + :dedent: + + Example on GitHub: `log_existing_modules `_ + + .. _configuration_reference_log_modules_example_new_modules: + + **Example 2: Set log levels for modules that use custom loggers** + + This example shows how to set the ``verbose`` level for ``module1`` and the ``error`` level for ``module2``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + To create custom loggers in your application (``app.lua``), call the :ref:`log.new() ` function: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua + :language: lua + :start-at: Creates new loggers + :end-at: module2_log = require + :dedent: + + Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1_log.info()`` shows a message but ``module2_log.info()`` is swallowed: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_new_modules/app.lua + :language: lua + :start-after: module2_log = require + :dedent: + + Example on GitHub: `log_new_modules `_ + + .. _configuration_reference_log_modules_example_tarantool_module: + + **Example 3: Set a log level for C modules** + + This example shows how to set the ``info`` level for the ``tarantool`` module: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_c_modules/config.yaml + :language: yaml + :start-at: log: + :end-at: app.lua + :dedent: + + The specified level affects messages logged from C modules: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_existing_c_modules/app.lua + :language: lua + :dedent: + + The example above uses the `LuaJIT ffi library `_ to call C functions provided by the ``say`` module. + + Example on GitHub: `log_existing_c_modules `_ + + | + | Type: map + | Default: :ref:`box.NULL ` + | Environment variable: TT_LOG_MODULES + +.. _configuration_reference_log_nonblock: + +.. confval:: log.nonblock + + Specify the logging behavior if the system is not ready to write. + If set to ``true``, Tarantool does not block during logging if the system is non-writable and writes a message instead. + Using this value may improve logging performance at the cost of losing some log messages. + + .. note:: + + The option only has an effect if the :ref:`log.to ` is set to ``syslog`` + or ``pipe``. + + | + | Type: boolean + | Default: false + | Environment variable: TT_LOG_NONBLOCK + +.. _configuration_reference_log_pipe: + +.. confval:: log.pipe + + Start a program and write logs to its standard input (``stdin``). + To send logs to a program's standard input, you need to set :ref:`log.to ` to ``pipe``. + + **Example** + + In the example below, Tarantool writes logs to the standard input of ``cronolog``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_pipe/config.yaml + :language: yaml + :start-at: log: + :end-at: tarantool.log + :dedent: + + Example on GitHub: `log_pipe `_ + + | + | Type: string + | Default: :ref:`box.NULL ` + | Environment variable: TT_LOG_PIPE + + +.. _configuration_reference_log_syslog: + +log.syslog.* +~~~~~~~~~~~~ + +* :ref:`log.syslog.facility ` +* :ref:`log.syslog.identity ` +* :ref:`log.syslog.server ` + +.. _configuration_reference_log_syslog-facility: + +.. confval:: log.syslog.facility + + Specify the syslog facility to be used when syslog is enabled. + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + | + | Type: string + | Possible values: 'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr', 'mail', 'news', 'security', 'syslog', 'user', 'uucp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' + | Default: 'local7' + | Environment variable: TT_LOG_SYSLOG_FACILITY + +.. _configuration_reference_log_syslog-identity: + +.. confval:: log.syslog.identity + + Specify an application name used to identify Tarantool messages in syslog logs. + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + | + | Type: string + | Default: 'tarantool' + | Environment variable: TT_LOG_SYSLOG_IDENTITY + +.. _configuration_reference_log_syslog-server: + +.. confval:: log.syslog.server + + Set a location of a syslog server. + This option accepts one of the following values: + + * An IPv4 address. Example: ``127.0.0.1:514``. + * A Unix socket path starting with ``unix:``. Examples: ``unix:/dev/log`` on Linux or ``unix:/var/run/syslog`` on macOS. + + To write logs to syslog, you need to set :ref:`log.to ` to ``syslog``. + + **Example** + + In the example below, Tarantool writes logs to a syslog server that listens for logging messages on the ``127.0.0.1:514`` address: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/log_syslog/config.yaml + :language: yaml + :start-at: log: + :end-at: 127.0.0.1:514 + :dedent: + + Example on GitHub: `log_syslog `_ + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_LOG_SYSLOG_SERVER + +.. _configuration_reference_lua: + +lua +--- + +The ``lua`` section outlines the configuration parameters related to the Lua environment within Tarantool. + +.. NOTE:: + + ``lua`` can be defined in any :ref:`scope `. + +- :ref:`lua.memory ` + + +.. _configuration_reference_lua_memory: + +.. confval:: lua.memory + + Specifies the maximum memory amount available to Lua scripts, measured in bytes. + + When the specified value exceeds the current memory usage, the new limit takes effect immediately without a restart. + However, **when the specified value is lower than the current memory usage, a restart of the instance is required** for the change to take effect. + + Example to set the Lua memory limit to 4 GB: + + .. code-block:: yaml + + lua: + memory: 4294967296 + + | + | Type: integer + | Default: 2147483648 (2GB) + | Environment variable: TT_LUA_MEMORY + +.. _configuration_reference_memtx: + +memtx +----- + +The ``memtx`` section is used to configure parameters related to the :ref:`memtx engine `. + +.. NOTE:: + + ``memtx`` can be defined in any :ref:`scope `. + +- :ref:`memtx.allocator ` +- :ref:`memtx.max_tuple_size ` +- :ref:`memtx.memory ` +- :ref:`memtx.min_tuple_size ` +- :ref:`memtx.slab_alloc_factor ` +- :ref:`memtx.slab_alloc_granularity ` +- :ref:`memtx.sort_threads ` + +.. _configuration_reference_memtx_allocator: + +.. confval:: memtx.allocator + + Specify the allocator that manages memory for ``memtx`` tuples. + Possible values: + + * ``system`` -- the memory is allocated as needed, checking that the quota is not exceeded. + THe allocator is based on the ``malloc`` function. + + * ``small`` -- a `slab allocator `_. + The allocator repeatedly uses a memory block to allocate objects of the same type. + Note that this allocator is prone to unresolvable fragmentation on specific workloads, + so you can switch to ``system`` in such cases. + + | + | Type: string + | Default: 'small' + | Environment variable: TT_MEMTX_ALLOCATOR + +.. _configuration_reference_memtx_max_size: + +.. confval:: memtx.max_tuple_size + + Size of the largest allocation unit for the memtx storage engine in bytes. + It can be increased if it is necessary to store large tuples. + + | + | Type: integer + | Default: 1048576 + | Environment variable: TT_MEMTX_MAX_TUPLE_SIZE + +.. _configuration_reference_memtx_memory: + +.. confval:: memtx.memory + + The amount of memory in bytes that Tarantool allocates to store tuples. + When the limit is reached, :ref:`INSERT ` and + :ref:`UPDATE ` requests fail with the :errcode:`ER_MEMORY_ISSUE` error. + The server does not go beyond the ``memtx.memory`` limit to allocate tuples, but there is additional memory + used to store indexes and connection information. + + **Example** + + In the example below, the memory size is set to 1 GB (1073741824 bytes). + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/memtx/config.yaml + :language: yaml + :start-at: memtx: + :end-at: 1073741824 + :dedent: + + | + | Type: integer + | Default: 268435456 + | Environment variable: TT_MEMTX_MEMORY + +.. _configuration_reference_memtx_min_size: + +.. confval:: memtx.min_tuple_size + + Size of the smallest allocation unit in bytes. + It can be decreased if most of the tuples are very small. + + | + | Type: integer + | Default: 16 + | Possible values: between 8 and 1048280 inclusive + | Environment variable: TT_MEMTX_MIN_TUPLE_SIZE + +.. _configuration_reference_memtx_slab_alloc_factor: + +.. confval:: memtx.slab_alloc_factor + + The multiplier for computing the sizes of memory + chunks that tuples are stored in. + A lower value may result in less wasted + memory depending on the total amount of memory available and the + distribution of item sizes. + + See also: :ref:`memtx.slab_alloc_granularity ` + + | + | Type: number + | Default: 1.05 + | Possible values: between 1 and 2 inclusive + | Environment variable: TT_MEMTX_SLAB_ALLOC_FACTOR + +.. _configuration_reference_memtx_slab_alloc_granularity: + +.. confval:: memtx.slab_alloc_granularity + + Specify the granularity in bytes of memory allocation in the :ref:`small allocator `. + The ``memtx.slab_alloc_granularity`` value should meet the following conditions: + + * The value is a power of two. + * The value is greater than or equal to 4. + + Below are few recommendations on how to adjust the ``memtx.slab_alloc_granularity`` option: + + * If the tuples in space are small and have about the same size, set the option to 4 bytes to save memory. + * If the tuples are different-sized, increase the option value to allocate tuples from the same ``mempool`` (memory pool). + + See also: :ref:`memtx.slab_alloc_factor ` + + | + | Type: integer + | Default: 8 + | Environment variable: TT_MEMTX_SLAB_ALLOC_GRANULARITY + +.. _configuration_reference_memtx_sort_threads: + +.. confval:: memtx.sort_threads + + The number of threads from the :ref:`thread pool ` used to sort keys of secondary indexes on loading a ``memtx`` database. + The minimum value is 1, the maximum value is 256. + The default is to use all available cores. + + .. include:: /platform/atomic/thread_model.rst + :start-after: note_drop_openmp_start + :end-before: note_drop_openmp_end + + | + | Type: integer + | Default: box.NULL + | Environment variable: TT_MEMTX_SORT_THREADS + + + + +.. _configuration_reference_metrics: + +metrics +------- + +The ``metrics`` section defines configuration parameters for :ref:`metrics `. + +.. NOTE:: + + ``metrics`` can be defined in any :ref:`scope `. + +- :ref:`metrics.exclude ` +- :ref:`metrics.include ` +- :ref:`metrics.labels ` + + +.. _configuration_reference_metrics_exclude: + +.. confval:: metrics.exclude + + An array containing the metrics to turn off. + The array can contain the same values as the ``exclude`` configuration parameter passed to :ref:`metrics.cfg() `. + + **Example** + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud_metrics/config.yaml + :start-at: metrics: + :end-at: instance_name + :language: yaml + :dedent: + + | + | Type: array + | Default: ``[]`` + | Environment variable: TT_METRICS_EXCLUDE + + +.. _configuration_reference_metrics_include: + +.. confval:: metrics.include + + An array containing the metrics to turn on. + The array can contain the same values as the ``include`` configuration parameter passed to :ref:`metrics.cfg() `. + + | + | Type: array + | Default: ``[ all ]`` + | Environment variable: TT_METRICS_INCLUDE + + +.. _configuration_reference_metrics_labels: + +.. confval:: metrics.labels + + Global :ref:`labels ` to be added to every observation. + + | + | Type: map + | Default: ``{ alias = names.instance_name }`` + | Environment variable: TT_METRICS_LABELS + + + + +.. _configuration_reference_process: + +process +------- + +The ``process`` section defines configuration parameters of the Tarantool process in the system. + +.. NOTE:: + + ``process`` can be defined in any :ref:`scope `. + +- :ref:`process.background ` +- :ref:`process.coredump ` +- :ref:`process.title ` +- :ref:`process.pid_file ` +- :ref:`process.strip_core ` +- :ref:`process.username ` +- :ref:`process.work_dir ` + +.. _configuration_reference_process_background: + +.. confval:: process.background + + Run the server as a daemon process. + + If this option is set to ``true``, Tarantool log location defined by the + :ref:`log.to ` option should be set to + ``file``, ``pipe``, or ``syslog`` -- anything other than ``stderr``, + the default, because a daemon process is detached from a terminal + and it can't write to the terminal's stderr. + + .. important:: + + Do not enable the background mode for applications intended to run by the + ``tt`` utility. For more information, see the :ref:`tt start ` reference. + + | + | Type: boolean + | Default: false + | Environment variable: TT_PROCESS_BACKGROUND + +.. _configuration_reference_process_coredump: + +.. confval:: process.coredump + + Create coredump files. + + Usually, an administrator needs to call ``ulimit -c unlimited`` + (or set corresponding options in systemd's unit file) + before running a Tarantool process to get core dumps. + If ``process.coredump`` is enabled, Tarantool sets the corresponding + resource limit by itself + and the administrator doesn't need to call ``ulimit -c unlimited`` + (see `man 3 setrlimit `_). + + This option also sets the state of the ``dumpable`` attribute, + which is enabled by default, + but may be dropped in some circumstances (according to + `man 2 prctl `_, see PR_SET_DUMPABLE). + + | + | Type: boolean + | Default: false + | Environment variable: TT_PROCESS_COREDUMP + +.. _configuration_reference_process_title: + +.. confval:: process.title + + Add the given string to the server's process title + (it is shown in the COMMAND column for the Linux commands + ``ps -ef`` and ``top -c``). + + For example, if you set the option to ``myservice - {{ instance_name }}``: + + .. code-block:: yaml + + process: + title: myservice - {{ instance_name }} + + :samp:`ps -ef` might show the Tarantool server process like this: + + .. code-block:: console + + $ ps -ef | grep tarantool + 503 68100 68098 0 10:33 pts/2 00:00.10 tarantool : myservice instance1 + + | + | Type: string + | Default: 'tarantool - {{ instance_name }}' + | Environment variable: TT_PROCESS_TITLE + +.. _configuration_reference_process_pid_file: + +.. confval:: process.pid_file + + Store the process id in this file. + + This option may contain a relative file path. + In this case, it is interpreted as relative to + :ref:`process.work_dir `. + + | + | Type: string + | Default: 'var/run/{{ instance_name }}/tarantool.pid' + | Environment variable: TT_PROCESS_PID_FILE + +.. _configuration_reference_process_strip_core: + +.. confval:: process.strip_core + + Whether coredump files should not include memory allocated for tuples -- + this memory can be large if Tarantool runs under heavy load. + Setting to ``true`` means "do not include". + + | + | Type: boolean + | Default: true + | Environment variable: TT_PROCESS_STRIP_CORE + +.. _configuration_reference_process_username: + +.. confval:: process.username + + The name of the system user to switch to after start. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_PROCESS_USERNAME + +.. _configuration_reference_process_work_dir: + +.. confval:: process.work_dir + + A directory where Tarantool working files will be stored + (database files, logs, a PID file, a console Unix socket, and other files + if an application generates them in the current directory). + The server instance switches to ``process.work_dir`` with + :manpage:`chdir(2)` after start. + + If set as a relative file path, it is relative to the current + working directory, from where Tarantool is started. + If not specified, defaults to the current working directory. + + Other directory and file parameters, if set as relative paths, + are interpreted as relative to ``process.work_dir``, for example, directories for storing + :ref:`snapshots and write-ahead logs `. + + | + | Type: string + | Default: box.NULL + | Environment variable: TT_PROCESS_WORK_DIR + +.. _configuration_reference_replication: + +replication +----------- + +The ``replication`` section defines configuration parameters related to :ref:`replication `. + +- :ref:`replication.anon ` +- :ref:`replication.autoexpel ` +- :ref:`replication.anon ` +- :ref:`replication.bootstrap_strategy ` +- :ref:`replication.connect_timeout ` +- :ref:`replication.election_mode ` +- :ref:`replication.election_timeout ` +- :ref:`replication.election_fencing_mode ` +- :ref:`replication.failover ` +- :ref:`replication.peers ` +- :ref:`replication.skip_conflict ` +- :ref:`replication.sync_lag ` +- :ref:`replication.sync_timeout ` +- :ref:`replication.synchro_queue_max_size ` +- :ref:`replication.synchro_quorum ` +- :ref:`replication.synchro_timeout ` +- :ref:`replication.threads ` +- :ref:`replication.timeout ` + +.. _configuration_reference_replication_anon: + +.. confval:: replication.anon + + Whether to make the current instance act as an anonymous replica. + Anonymous replicas are read-only and can be used, for example, for backups. + + To make the specified instance act as an anonymous replica, set ``replication.anon`` to ``true``: + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml + :language: yaml + :start-at: instance003 + :end-at: anon: true + :dedent: + + You can find the full example on GitHub: `anonymous_replica `_. + + Anonymous replicas are not displayed in the :ref:`box.info.replication ` section. + You can check their status using :ref:`box.info.replication_anon() `. + + While anonymous replicas are read-only, you can write data to replication-local and temporary spaces (:ref:`created ` with ``is_local = true`` and ``temporary = true``, respectively). + Given that changes to replication-local spaces are allowed, an anonymous replica might increase the ``0`` component of the :ref:`vclock ` value. + + Here are the limitations of having anonymous replicas in a replica set: + + * A replica set must contain at least one non-anonymous instance. + * An anonymous replica can't be configured as a writable instance by setting :ref:`database.mode ` to ``rw`` or making it a leader using :ref:`.leader `. + * If :ref:`replication.failover ` is set to ``election``, an anonymous replica can have :ref:`replication.election_mode ` set to ``off`` only. + * If :ref:`replication.failover ` is set to ``supervised``, an external failover coordinator doesn't consider anonymous replicas when selecting a bootstrap or replica set leader. + + .. NOTE:: + + Anonymous replicas are not registered in the :ref:`_cluster ` space. + This means that there is no :ref:`limitation ` on the number of anonymous replicas in a replica set. + + | + | Type: boolean + | Default: ``false`` + | Environment variable: TT_REPLICATION_ANON + +.. _configuration_reference_replication_autoexpel: + +.. confval:: replication.autoexpel + + **Since:** :doc:`3.3.0 ` + + The ``replication.autoexpel`` option designed for managing dynamic clusters using YAML-based configurations. + It enables the automatic expulsion of instances that are removed from the YAML configuration. + + Only instances with names that match the specified prefix are considered for expulsion; all others are excluded. + Additionally, instances without a persistent name are ignored. + + If an instance is in read-write mode and has the latest database schema, it initiates the expulsion of instances that: + + - Match the specified prefix + - Absent from the updated YAML configuration + + The expulsion process follows the standard procedure, involving the removal of the instance from the ``_cluster`` system space. + + The ``autoexpel`` logic is activated during specific events: + + - **Startup**. When the cluster starts, ``autoexpel`` checks and removes instances not matching the updated configuration. + - **Reconfiguration**. When the YAML configuration is reloaded, ``autoexpel`` compares the current state to the updated configuration and performs necessary expulsions. + - ``box.status`` **watcher event**. Changes detected by the ``box.status`` watcher also trigger the ``autoexpel`` mechanism. + + + ``autoexpel`` does not take any actions on newly joined instances unless one of the triggering events occurs. + This means that an instance meeting the ``autoexpel`` criterion can still join the cluster, but it may be removed + later during reconfiguration or on subsequent triggering events. + + .. NOTE:: + The ``replication.autoexpel`` option governs the expelling process and is configurable at the replicaset, group, and + global levels. It is not applicable at the instance level. + + + Configuration fields + + - ``by`` (string, default: ``nil``): specifies the ``autoexpel`` criterion. Currently, only ``prefix`` is supported and must be explicitly set. + + - ``enabled`` (boolean, default: ``false``): enables or disables the ``autoexpel`` logic. + + - ``prefix`` (string, default: ``nil``): defines the pattern for instance names that are considered part of the cluster. + + + +replication.autoexpel_by.* +~~~~~~~~~~~~~ + + ``replication.autoexpel_by`` purpose is to define the criterion used for determining which instances in a cluster are + subject to the ``autoexpel`` process. + + The ``by`` field helps differentiate between: + + - Instances that are part of the cluster and should adhere to the YAML configuration. + + - Instances or tools (e.g., CDC tools) that use the replication channel but are not part of the cluster configuration. + + + The default value of by is ``nil``, meaning no ``autoexpel`` criterion is applied unless explicitly set. + + Currently, the only supported value for by is ``prefix``. The ``prefix`` value instructs the system to identify instances + based on their names, matching them against a prefix pattern defined in the configuration. + + If the ``autoexpel`` feature is enabled (``enabled: true``), the ``by`` field must be explicitly set to ``prefix``. + + The absence of this field or an unsupported value will result in configuration errors. + + .. code-block:: yaml + + replication: + autoexpel: + enabled: true + by: prefix + prefix: '{{ replicaset_name }}' + + | + | Type: string + | Default: ``nil`` + | Environment variable: TT_REPLICATION_AUTOEXPEL_BY + + + +replication.autoexpel_enabled.* +~~~~~~~~~~~~~ + + The ``replication.autoexpel_enabled`` field is a boolean configuration option that determines whether the autoexpel logic is active for the cluster. + This feature is designed to automatically manage dynamic cluster configurations by removing instances that are no longer present in the YAML configuration. + + .. NOTE:: + + By default, the ``enabled`` field is set to ``false``, meaning the ``autoexpel`` logic is turned off. This ensures that no instances are automatically removed unless explicitly configured. + + Enabling ``autoexpel`` logic + + To enable ``autoexpel``, you should set enabled to true in the ``replication.autoexpel`` section of your YAML configuration: + + .. code-block:: yaml + + replication: + autoexpel: + enabled: true + by: prefix + prefix: '{{ replicaset_name }}' + + + To disable ``autoexpel``, set enabled to ``false``. + + + Dependencies + + If ``enabled`` is set to ``true``, the following fields are required: + + 1. ``by``: specifies the criterion for ``autoexpel`` (e.g., ``prefix``). + 2. ``prefix``: defines the pattern used to match instance names for expulsion. + + Failure to configure these fields when enabled is true will result in a configuration error. + + | + | Type: boolean + | Default: ``false`` + | Environment variable: TT_REPLICATION_AUTOEXPEL_ENABLED + + +replication.autoexpel_prefix.* +~~~~~~~~~~~~~ + + The ``prefix`` field filters instances for expulsion by differentiating cluster instances (from the YAML configuration) from external services (e.g., CDC tools). Only instances matching the prefix are considered. + + A consistent naming pattern ensures the ``_cluster`` system space automatically aligns with the YAML configuration. + + + If the ``prefix`` field is not set (``nil``), the ``autoexpel`` logic cannot identify instances for expulsion, and the feature will not function. + This field is **mandatory** when ``replication.autoexpel_enabled`` is set to ``true``. + + + How it works: + + 1. The prefix filters instance names (e.g., ``{{ replicaset_name }}`` for replicaset-specific names or ``i-`` for names starting with ``i-``). + 2. Instances matching the prefix and removed from the YAML configuration are expelled. + 3. Unnamed instances or those not matching the prefix are ignored. + + Dynamic prefix based on replicaset name: + + .. code-block:: yaml + + replication: + autoexpel: + enabled: true + by: prefix + prefix: '{{ replicaset_name }}' + + + In this setup: + + - Instances are grouped by replicaset names (e.g., ``r-001-i-001`` for ``replicaset r-001``). + - The prefix ensures that only instances with names matching the replicaset name are auto expelled when removed from the configuration. + + + Static prefix for matching patterns: + + .. code-block:: yaml + + replication: + autoexpel: + enabled: true + by: prefix + prefix: 'i-' + + In this setup: + + - All instances with names starting with ``i-`` (e.g., ``i-001``, ``i-002``) are considered for expulsion. + - This is useful when instances follow a uniform naming convention. + + | + | Type: string + | Default: ``nil`` + | Environment variable: TT_REPLICATION_AUTOEXPEL_PREFIX + + + +autoexpel full example +~~~~~~~~~~~~~ + + 1. Create a ``config.yaml`` file with the following content: + + .. code-block:: yaml + + credentials: + users: + guest: + roles: [super] + + replication: + failover: manual + autoexpel: + enabled: true + by: prefix + prefix: '{{ replicaset_name }}' + + iproto: + listen: + - uri: 'unix/:./var/run/{{ instance_name }}.iproto' + + groups: + g-001: + replicasets: + r-001: + leader: r-001-i-001 + instances: + r-001-i-001: {} + r-001-i-002: {} + r-001-i-003: {} + + + This configuration: + - Sets up authentication with a guest user assigned the super role. + - Enables the ``autoexpel`` option to automatically expel instances not present in the YAML file. + - Defines instance names based on a prefix pattern: ``{{ replicaset_name }}``. + - Lists three instances: ``r-001-i-001``, ``r-001-i-002``, and ``r-001-i-003``. + + + 2. Open terminal window and start three instances using the following commands: + + .. code-block:: lua + + tarantool --name r-001-i-001 --config config.yaml -i + + + .. code-block:: lua + + tarantool --name r-001-i-002 --config config.yaml -i + + + .. code-block:: lua + + tarantool --name r-001-i-003 --config config.yaml -i + + 3. Edit ``config.yaml`` and remove the following entry for ``r-001-i-003``: + + .. code-block:: lua + r-001-i-003: {} + + + The updated ``config.yaml`` should look like this: + + .. code-block:: yaml + + groups: + g-001: + replicasets: + r-001: + leader: r-001-i-001 + instances: + r-001-i-001: {} + r-001-i-002: {} + + Save the file. + + 4. For the leader instance (``r-001-i-001``), check the ``_cluster`` space: + + .. hint:: + + The ``_cluster`` system space in Tarantool stores metadata about all instances currently recognized as part of the cluster. + It shows which instances are registered and active. + + You should see ``r-001-i-003`` still listed in the ``_cluster`` system space. + + 5. Reload the configuration: + + .. code-block:: lua + + config = require('config') + config:reload() + + 6. Verify the changes: + + .. code-block:: lua + + box.space._cluster:fselect() + + After the reload, ``r-001-i-003`` should no longer appear in the ``_cluster`` system space. + + + +.. _configuration_reference_replication_bootstrap_strategy: + +.. confval:: replication.bootstrap_strategy + + Specifies a strategy used to bootstrap a :ref:`replica set `. + The following strategies are available: + + * ``auto``: a node doesn't boot if half or more of the other nodes in a replica set are not connected. + For example, if a replica set contains 2 or 3 nodes, a node requires 2 connected instances. + In the case of 4 or 5 nodes, at least 3 connected instances are required. + Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader. + + * ``config``: use the specified node to bootstrap a replica set. + To specify the bootstrap leader, use the :ref:`.bootstrap_leader ` option. + + * ``supervised``: a bootstrap leader isn't chosen automatically but should be appointed using :ref:`box.ctl.make_bootstrap_leader() ` on the desired node. + + * ``legacy`` (deprecated since :doc:`2.11.0 `): a node requires the :ref:`replication_connect_quorum ` number of other nodes to be connected. + This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future. + + | + | Type: string + | Default: ``auto`` + | Environment variable: TT_REPLICATION_BOOTSTRAP_STRATEGY + +.. _configuration_reference_replication_connect_timeout: + +.. confval:: replication.connect_timeout + + A timeout (in seconds) a replica waits when trying to connect to a master in a cluster. + See :ref:`orphan status ` for details. + + This parameter is different from + :ref:`replication.timeout `, + which a master uses to disconnect a replica when the master + receives no acknowledgments of heartbeat messages. + + | + | Type: number + | Default: 30 + | Environment variable: TT_REPLICATION_CONNECT_TIMEOUT + +.. _configuration_reference_replication_election_mode: + +.. confval:: replication.election_mode + + A role of a replica set node in the :ref:`leader election process `. + + The possible values are: + + * ``off``: a node doesn't participate in the election activities. + + * ``voter``: a node can participate in the election process but can't be a leader. + + * ``candidate``: a node should be able to become a leader. + + * ``manual``: allow to control which instance is the leader explicitly instead of relying on automated leader election. + By default, the instance acts like a voter -- it is read-only and may vote for other candidate instances. + Once :ref:`box.ctl.promote() ` is called, the instance becomes a candidate and starts a new election round. + If the instance wins the elections, it becomes a leader but won't participate in any new elections. + + .. NOTE:: + + You can set ``replication.election_mode`` to a value other than ``off`` if the :ref:`replication.failover ` mode is ``election``. + + | + | Type: string + | Default: :ref:`box.NULL ` (the actual default value depends on :ref:`replication.failover `) + | Environment variable: TT_REPLICATION_ELECTION_MODE + +.. _configuration_reference_replication_election_timeout: + +.. confval:: replication.election_timeout + + Specifies the timeout (in seconds) between election rounds in the + :ref:`leader election process ` if the previous round + ended up with a split vote. + + It is quite big, and for most of the cases, it can be lowered to + 300-400 ms. + + To avoid the split vote repeat, the timeout is randomized on each node + during every new election, from 100% to 110% of the original timeout value. + For example, if the timeout is 300 ms and there are 3 nodes started + the election simultaneously in the same term, + they can set their election timeouts to 300, 310, and 320 respectively, + or to 305, 302, and 324, and so on. In that way, the votes will never be split + because the election on different nodes won't be restarted simultaneously. + + | + | Type: number + | Default: 5 + | Environment variable: TT_REPLICATION_ELECTION_TIMEOUT + +.. _configuration_reference_replication_election_fencing_mode: + +.. confval:: replication.election_fencing_mode + + Specifies the :ref:`leader fencing mode ` that + affects the leader election process. When the parameter is set to ``soft`` + or ``strict``, the leader resigns its leadership if it has less than + :ref:`replication.synchro_quorum ` + of alive connections to the cluster nodes. + The resigning leader receives the status of a follower in the current election term and becomes + read-only. + + * In ``soft`` mode, a connection is considered dead if there are no responses for + :ref:`4 * replication.timeout ` seconds both on the current leader and the followers. + + * In ``strict`` mode, a connection is considered dead if there are no responses + for :ref:`2 * replication.timeout ` seconds on the + current leader and + :ref:`4 * replication.timeout ` seconds on the + followers. This improves the chances that there is only one leader at any time. + + Fencing applies to the instances that have the + :ref:`replication.election_mode ` set to ``candidate`` or ``manual``. + To turn off leader fencing, set ``election_fencing_mode`` to ``off``. + + | + | Type: string + | Default: ``soft`` + | Possible values: ``off``, ``soft``, ``strict`` + | Environment variable: TT_REPLICATION_ELECTION_FENCING_MODE + +.. _configuration_reference_replication_failover: + +.. confval:: replication.failover + + A failover mode used to take over a master role when the current master instance fails. + The following modes are available: + + - ``off`` + + Leadership in a replica set is controlled using the :ref:`database.mode ` option. + In this case, you can set the ``database.mode`` option to ``rw`` on all instances in a replica set to make a :ref:`master-master ` configuration. + + The default ``database.mode`` is determined as follows: ``rw`` if there is one instance in a replica set; ``ro`` if there are several instances. + + - ``manual`` + + Leadership in a replica set is controlled using the :ref:`.leader ` option. + In this case, a :ref:`master-master ` configuration is forbidden. + + In the ``manual`` mode, the :ref:`database.mode ` option cannot be set explicitly. + The leader is configured in the read-write mode, all the other instances are read-only. + + - ``election`` + + :ref:`Automated leader election ` is used to control leadership in a replica set. + + In the ``election`` mode, :ref:`database.mode ` and :ref:`.leader ` shouldn't be set explicitly. + + - ``supervised`` (`Enterprise Edition `_ only) + + Leadership in a replica set is controlled using an :ref:`external failover coordinator `. + + In the ``supervised`` mode, :ref:`database.mode ` and :ref:`.leader ` shouldn't be set explicitly. + + See also: :ref:`Replication tutorials ` + + .. NOTE:: + + ``replication.failover`` can be defined in the global, group, and replica set :ref:`scope `. + + **Example** + + In the example below, the following configuration options are specified: + + - In the :ref:`credentials ` section, the ``replicator`` user with the ``replication`` role is created. + - :ref:`iproto.advertise.peer ` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` using the ``replicator`` user. + - ``replication.failover`` specifies that a master instance should be set manually. + - :ref:`.leader ` sets ``instance001`` as a replica set leader. + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml + :language: yaml + :end-before: Load sample data + :dedent: + + | + | Type: string + | Default: ``off`` + | Environment variable: TT_REPLICATION_FAILOVER + +.. _configuration_reference_replication_peers: + +.. confval:: replication.peers + + URIs of instances that constitute a replica set. + These URIs are used by an instance to connect to another instance as a replica. + + Alternatively, you can use :ref:`iproto.advertise.peer ` to specify a URI used to advertise the current instance to other cluster members. + + **Example** + + In the example below, the following configuration options are specified: + + - In the :ref:`credentials ` section, the ``replicator`` user with the ``replication`` role is created. + - ``replication.peers`` specifies URIs of replica set instances. + + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/peers/config.yaml + :language: yaml + :start-at: credentials: + :end-at: - replicator:topsecret@127.0.0.1:3303 + :dedent: + + | + | Type: array + | Default: :ref:`box.NULL ` + | Environment variable: TT_REPLICATION_PEERS + +.. _configuration_reference_replication_skip_conflict: + +.. confval:: replication.skip_conflict + + By default, if a replica adds a unique key that another replica has + added, replication :ref:`stops ` + with the ``ER_TUPLE_FOUND`` :ref:`error `. + If ``replication.skip_conflict`` is set to ``true``, such errors are ignored. + + .. NOTE:: + + Instead of saving the broken transaction to the write-ahead log, it is written as ``NOP`` (No operation). + + | + | Type: boolean + | Default: false + | Environment variable: TT_REPLICATION_SKIP_CONFLICT + +.. _configuration_reference_replication_sync_lag: + +.. confval:: replication.sync_lag + + The maximum delay (in seconds) between the time when data is written to the master and the time when it is written to a replica. + If ``replication.sync_lag`` is set to ``nil`` or 365 * 100 * 86400 (``TIMEOUT_INFINITY``), + a replica is always considered to be "synced". + + .. NOTE:: + + This parameter is ignored during bootstrap. + See :ref:`orphan status ` for details. + + | + | Type: number + | Default: 10 + | Environment variable: TT_REPLICATION_SYNC_LAG + +.. _configuration_reference_replication_sync_timeout: + +.. confval:: replication.sync_timeout + + The timeout (in seconds) that a node waits when trying to sync with + other nodes in a replica set after connecting or during a :ref:`configuration update `. + This could fail indefinitely if :ref:`replication.sync_lag ` is smaller than network latency, or if the replica cannot keep pace with master updates. + If ``replication.sync_timeout`` expires, the replica enters :ref:`orphan status `. + + | + | Type: number + | Default: 0 + | Environment variable: TT_REPLICATION_SYNC_TIMEOUT + + +.. _configuration_reference_replication_synchro_queue_max_size: + +.. confval:: replication.synchro_queue_max_size + + **Since:** :doc:`3.3.0 ` + + The maximum size of the synchronous transaction queue on a master node, in bytes. The size limit isn't strict, i.e. if there's at least one free byte, the whole write request fits and no blocking is involved. + This parameter ensures that the queue does not grow indefinitely, potentially impacting performance and resource usage, and applies only to the master node. + + The ``0`` value disables the limit. + + + If the synchronous queue reaches the configured size limit, new transactions attempting to enter the queue are discarded. + In such cases, the system returns an error to the user: + ``The synchronous transaction queue is full.`` + + This size limitation does not apply during the recovery process. Transactions processed during recovery are unaffected by the queue size limit. + + Use the following command to view the current size of the synchronous queue: + + .. code-block:: lua + + box.info.synchro.queue.size + + + .. code-block:: command line + + tarantool> box.info.synchro + --- + - queue: + owner: 1 + size: 60 + busy: false + len: 1 + term: 2 + quorum: 2 + ... + + Set the synchronous queue size limit in the configuration file: + + .. code-block:: yaml + + replication: + synchro_queue_max_size: 33554432 # Limit set to 32 MB + + | + | Type: integer + | Default: 16777216 (16 MB) + | Environment variable: TT_REPLICATION_SYNCHRO_QUEUE_MAX_SIZE + + + +.. _configuration_reference_replication_synchro_quorum: + +.. confval:: replication.synchro_quorum + + A number of replicas that should confirm the receipt of a :ref:`synchronous ` transaction before it can finish its commit. + + This option supports dynamic evaluation of the quorum number. + For example, the default value is ``N / 2 + 1`` where ``N`` is the current number of replicas registered in a cluster. + Once any replicas are added or removed, the expression is re-evaluated automatically. + + Note that the default value (``at least 50% of the cluster size + 1``) guarantees data reliability. + Using a value less than the canonical one might lead to unexpected results, + including a :ref:`split-brain `. + + ``replication.synchro_quorum`` is not used on replicas. If the master fails, the pending synchronous + transactions will be kept waiting on the replicas until a new master is elected. + + .. NOTE:: + + ``replication.synchro_quorum`` does not account for anonymous replicas. + + | + | Type: string, number + | Default: ``N / 2 + 1`` + | Environment variable: TT_REPLICATION_SYNCHRO_QUORUM + +.. _configuration_reference_replication_synchro_timeout: + +.. confval:: replication.synchro_timeout + + For :ref:`synchronous replication ` only. + Specify how many seconds to wait for a synchronous transaction quorum + replication until it is declared failed and is rolled back. + + It is not used on replicas, so if the master fails, the pending synchronous + transactions will be kept waiting on the replicas until a new master is + elected. + + | + | Type: number + | Default: 5 + | Environment variable: TT_REPLICATION_SYNCHRO_TIMEOUT + +.. _configuration_reference_replication_threads: + +.. confval:: replication.threads + + The number of threads spawned to decode the incoming replication data. + + In most cases, one thread is enough for all incoming data. + Possible values range from 1 to 1000. + If there are multiple replication threads, connections to serve are distributed evenly between the threads. + + | + | Type: integer + | Default: 1 + | Environment variable: TT_REPLICATION_THREADS + +.. _configuration_reference_replication_timeout: + +.. confval:: replication.timeout + + A time interval (in seconds) used by a master to send heartbeat requests to a replica when there are no updates to send to this replica. + For each request, a replica should return a heartbeat acknowledgment. + + If a master or replica gets no heartbeat message for ``4 * replication.timeout`` seconds, a connection is dropped and a replica tries to reconnect to the master. + + See also: :ref:`Monitoring a replica set ` + + | + | Type: number + | Default: 1 + | Environment variable: TT_REPLICATION_TIMEOUT + +.. _configuration_reference_roles_options: + +roles +----- + +This section describes configuration parameters related to :ref:`application roles `. + +.. NOTE:: + + Configuration parameters related to roles can be defined in any :ref:`scope `. + +- :ref:`roles ` +- :ref:`roles_cfg ` + +.. _configuration_reference_roles: + +.. confval:: roles + + Specify the roles of an instance. + To specify a role's configuration, use the :ref:`roles_cfg ` option. + + See also: :ref:`configuration_application_roles` + + | + | Type: array + | Default: nil + | Environment variable: TT_ROLES + +.. _configuration_reference_roles_cfg: + +.. confval:: roles_cfg + + Specify a role's configuration. + This option accepts a role name as the key and a role's configuration as the value. + To specify the roles of an instance, use the :ref:`roles ` option. + + See also: :ref:`configuration_application_roles` + + .. tip:: + + The :ref:`experimental.config.utils.schema ` + built-in module provides an API for managing user-defined configurations + of applications (``app.cfg``) and roles (``roles_cfg``). + + | + | Type: map + | Default: nil + | Environment variable: TT_ROLES_CFG + +.. _configuration_reference_security: + +security +-------- + +.. admonition:: Enterprise Edition + :class: fact + + Configuring security parameters is available in the `Enterprise Edition `_ only. + +The ``security`` section defines configuration parameters related to various security settings. + +.. NOTE:: + + ``security`` can be defined in any :ref:`scope `. + +- :ref:`security.auth_delay ` +- :ref:`security.auth_retries ` +- :ref:`security.auth_type ` +- :ref:`security.disable_guest ` +- :ref:`security.password_enforce_digits ` +- :ref:`security.password_enforce_lowercase ` +- :ref:`security.password_enforce_specialchars ` +- :ref:`security.password_enforce_uppercase ` +- :ref:`security.password_history_length ` +- :ref:`security.password_lifetime_days ` +- :ref:`security.password_min_length ` +- :ref:`security.secure_erasing ` + +.. _configuration_reference_security_auth_delay: + +.. confval:: security.auth_delay + + Specify a period of time (in seconds) that a specific user should wait for the next attempt after failed authentication. + + The :ref:`security.auth_retries ` option lets a client try to authenticate the specified number of times before ``security.auth_delay`` is enforced. + + In the configuration below, Tarantool lets a client try to authenticate with the same username three times. + At the fourth attempt, the authentication delay configured with ``security.auth_delay`` is enforced. + This means that a client should wait 10 seconds after the first failed attempt. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml + :language: yaml + :start-at: security: + :end-at: auth_retries: 2 + :dedent: + + | + | Type: number + | Default: 0 + | Environment variable: TT_SECURITY_AUTH_DELAY + +.. _configuration_reference_security_auth_retries: + +.. confval:: security.auth_retries + + Specify the maximum number of authentication retries allowed before :ref:`security.auth_delay ` is enforced. + The default value is 0, which means ``security.auth_delay`` is enforced after the first failed authentication attempt. + + The retry counter is reset after ``security.auth_delay`` seconds since the first failed attempt. + For example, if a client tries to authenticate fewer than ``security.auth_retries`` times within ``security.auth_delay`` seconds, no authentication delay is enforced. + The retry counter is also reset after any successful authentication attempt. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_AUTH_RETRIES + +.. _configuration_reference_security_auth_type: + +.. confval:: security.auth_type + + Specify a protocol used to authenticate users. + The possible values are: + + - ``chap-sha1``: use the `CHAP `_ protocol with ``SHA-1`` hashing applied to :ref:`passwords `. + - ``pap-sha256``: use `PAP `_ authentication with the ``SHA256`` hashing algorithm. + + Note that CHAP stores password hashes in the ``_user`` space unsalted. + If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table `_. + For PAP, a password is salted with a user-unique salt before saving it in the database, + which keeps the database protected from cracking using a rainbow table. + + To enable PAP, specify the ``security.auth_type`` option as follows: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml + :language: yaml + :start-at: security: + :end-at: 'pap-sha256' + :dedent: + + | + | Type: string + | Default: 'chap-sha1' + | Environment variable: TT_SECURITY_AUTH_TYPE + +.. _configuration_reference_security_disable_guest: + +.. confval:: security.disable_guest + + If **true**, turn off access over remote connections from unauthenticated or :ref:`guest ` users. + This option affects connections between cluster members and :doc:`net.box ` connections. + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_DISABLE_GUEST + +.. _configuration_reference_security_password_enforce_digits: + +.. confval:: security.password_enforce_digits + + If **true**, a password should contain digits (0-9). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_DIGITS + +.. _configuration_reference_security_password_enforce_lowercase: + +.. confval:: security.password_enforce_lowercase + + If **true**, a password should contain lowercase letters (a-z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_LOWERCASE + +.. _configuration_reference_security_password_enforce_specialchars: + +.. confval:: security.password_enforce_specialchars + + If **true**, a password should contain at least one special character (such as ``&|?!@$``). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_SPECIALCHARS + +.. _configuration_reference_security_password_enforce_uppercase: + +.. confval:: security.password_enforce_uppercase + + If **true**, a password should contain uppercase letters (A-Z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_UPPERCASE + +.. _configuration_reference_security_password_history_length: + +.. confval:: security.password_history_length + + Specify the number of unique new user passwords before an old password can be reused. + + .. NOTE:: + + Tarantool uses the ``auth_history`` field in the + :doc:`box.space._user ` + system space to store user passwords. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_HISTORY_LENGTH + +.. _configuration_reference_security_password_lifetime_days: + +.. confval:: security.password_lifetime_days + + Specify the maximum period of time (in days) a user can use the same password. + When this period ends, a user gets the "Password expired" error on a login attempt. + To restore access for such users, use :doc:`box.schema.user.passwd `. + + .. note:: + + The default 0 value means that a password never expires. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_LIFETIME_DAYS + +.. _configuration_reference_security_password_min_length: + +.. confval:: security.password_min_length + + Specify the minimum number of characters for a password. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_MIN_LENGTH + +.. _configuration_reference_security_secure_erasing: + +.. confval:: security.secure_erasing + + If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. + The option applies to both ``.xlog`` and ``.snap`` files as well as Vinyl data files. + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_SECURE_ERASING + +.. _configuration_reference_sharding: + +sharding +-------- + +The ``sharding`` section defines configuration parameters related to :ref:`sharding `. + +.. NOTE:: + + Sharding support requires installing the :ref:`vshard ` module. + The minimum required version of ``vshard`` is 0.1.25. + +- :ref:`sharding.bucket_count ` +- :ref:`sharding.discovery_mode ` +- :ref:`sharding.failover_ping_timeout ` +- :ref:`sharding.lock ` +- :ref:`sharding.rebalancer_disbalance_threshold ` +- :ref:`sharding.rebalancer_max_receiving ` +- :ref:`sharding.rebalancer_max_sending ` +- :ref:`sharding.rebalancer_mode ` +- :ref:`sharding.roles ` +- :ref:`sharding.sched_move_quota ` +- :ref:`sharding.sched_ref_quota ` +- :ref:`sharding.shard_index ` +- :ref:`sharding.sync_timeout ` +- :ref:`sharding.weight ` +- :ref:`sharding.zone ` + +.. _configuration_reference_sharding_bucket_count: + +.. confval:: sharding.bucket_count + + The total number of buckets in a cluster. + Learn more in :ref:`vshard_config_bucket_count`. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + **Example** + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-after: login: storage + :end-at: bucket_count + :dedent: + + | + | Type: integer + | Default: 3000 + | Environment variable: TT_SHARDING_BUCKET_COUNT + +.. _configuration_reference_sharding_discovery_mode: + +.. confval:: sharding.discovery_mode + + A mode of the background discovery fiber used by the router to find buckets. + Learn more in :ref:`vshard.router.discovery_set() `. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: string + | Default: 'on' + | Possible values: 'on', 'off', 'once' + | Environment variable: TT_SHARDING_DISCOVERY_MODE + +.. _configuration_reference_sharding_failover_ping_timeout: + +.. confval:: sharding.failover_ping_timeout + + The timeout (in seconds) after which a node is considered unavailable if there are no responses during this period. + The :ref:`failover fiber ` is used to detect if a node is down. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: number + | Default: 5 + | Environment variable: TT_SHARDING_FAILOVER_PING_TIMEOUT + +.. _configuration_reference_sharding_lock: + +.. confval:: sharding.lock + + Whether a replica set is :ref:`locked `. + A locked replica set cannot receive new buckets nor migrate its own buckets. + + .. NOTE:: + + ``sharding.lock`` can be specified at the :ref:`replica set level ` or higher. + + | + | Type: boolean + | Default: nil + | Environment variable: TT_SHARDING_LOCK + +.. _configuration_reference_sharding_rebalancer_disbalance_threshold: + +.. confval:: sharding.rebalancer_disbalance_threshold + + The maximum bucket :ref:`disbalance ` threshold (in percent). + The disbalance is calculated for each replica set using the following formula: + + .. code-block:: none + + |etalon_bucket_count - real_bucket_count| / etalon_bucket_count * 100 + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: number + | Default: 1 + | Environment variable: TT_SHARDING_REBALANCER_DISBALANCE_THRESHOLD + +.. _configuration_reference_sharding_rebalancer_max_receiving: + +.. confval:: sharding.rebalancer_max_receiving + + The maximum number of buckets that can be :ref:`received in parallel ` by a single replica set. + This number must be limited because the rebalancer sends a large number of buckets from the existing replica sets to the newly added one. + This produces a heavy load on the new replica set. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + **Example** + + Suppose, ``rebalancer_max_receiving`` is equal to 100 and ``bucket_count`` is equal to 1000. + There are 3 replica sets with 333, 333, and 334 buckets on each respectively. + When a new replica set is added, each replica set’s ``etalon_bucket_count`` becomes + equal to 250. Rather than receiving all 250 buckets at once, the new replica set + receives 100, 100, and 50 buckets sequentially. + + | + | Type: integer + | Default: 100 + | Environment variable: TT_SHARDING_REBALANCER_MAX_RECEIVING + +.. _configuration_reference_sharding_rebalancer_max_sending: + +.. confval:: sharding.rebalancer_max_sending + + The degree of parallelism for :ref:`parallel rebalancing `. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: integer + | Default: 1 + | Maximum: 15 + | Environment variable: TT_SHARDING_REBALANCER_MAX_SENDING + +.. _configuration_reference_sharding_rebalancer_mode: + +.. confval:: sharding.rebalancer_mode + + **Since:** :doc:`3.1.0 ` + + Configure how a rebalancer is selected: + + * ``auto`` (default): if there are no replica sets with the ``rebalancer`` sharding role (:ref:`sharding.roles `), a replica set with the rebalancer is selected automatically among all replica sets. + * ``manual``: one of the replica sets should have the ``rebalancer`` sharding role. The rebalancer is in this replica set. + * ``off``: rebalancing is turned off regardless of whether a replica set with the ``rebalancer`` sharding role exists or not. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: string + | Default: 'auto' + | Environment variable: TT_SHARDING_REBALANCER_MODE + +.. _configuration_reference_sharding_roles: + +.. confval:: sharding.roles + + Roles of a replica set in regard to sharding. + A replica set can have the following roles: + + * ``router``: a replica set acts as a :ref:`router `. + * ``storage``: a replica set acts as a :ref:`storage `. + * ``rebalancer``: a replica set acts as a :ref:`rebalancer `. + + The ``rebalancer`` role is optional. + If it is not specified, a rebalancer is selected automatically from the master instances of replica sets. + + There can be at most one replica set with the ``rebalancer`` role. + Additionally, this replica set should have a ``storage`` role. + + **Example** + + .. code-block:: yaml + + replicasets: + storage-a: + sharding: + roles: [storage, rebalancer] + + See also: :ref:`vshard_config_sharding_roles` + + .. NOTE:: + + ``sharding.roles`` can be specified at the :ref:`replica set level ` or higher. + + | + | Type: array + | Default: nil + | Environment variable: TT_SHARDING_ROLES + +.. _configuration_reference_sharding_sched_move_quota: + +.. confval:: sharding.sched_move_quota + + A scheduler's bucket move quota used by the :ref:`rebalancer `. + + ``sched_move_quota`` defines how many bucket moves can be done in a row if there are pending storage refs. + Then, bucket moves are blocked and a router continues making map-reduce requests. + + See also: :ref:`sharding.sched_ref_quota ` + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: number + | Default: 1 + | Environment variable: TT_SHARDING_SCHED_MOVE_QUOTA + +.. _configuration_reference_sharding_sched_ref_quota: + +.. confval:: sharding.sched_ref_quota + + A scheduler's storage ref quota used by a :ref:`router `'s map-reduce API. + For example, the :ref:`vshard.router.map_callrw() ` function implements consistent map-reduce over the entire cluster. + + ``sched_ref_quota`` defines how many storage refs, therefore map-reduce requests, can be executed on the storage in a row if there are pending bucket moves. + Then, storage refs are blocked and the rebalancer continues bucket moves. + + See also: :ref:`sharding.sched_move_quota ` + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: number + | Default: 300 + | Environment variable: TT_SHARDING_SCHED_REF_QUOTA + +.. _configuration_reference_sharding_shard_index: + +.. confval:: sharding.shard_index + + The name or ID of a TREE index over the :ref:`bucket id `. + Spaces without this index do not participate in a sharded Tarantool + cluster and can be used as regular spaces if needed. It is necessary to + specify the first part of the index, other parts are optional. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + See also: :ref:`vshard-define-spaces` + + | + | Type: string + | Default: 'bucket_id' + | Environment variable: TT_SHARDING_SHARD_INDEX + +.. _configuration_reference_sharding_sync_timeout: + +.. confval:: sharding.sync_timeout + + The timeout to wait for synchronization of the old master with replicas before demotion. + Used when switching a master or when manually calling the :ref:`sync() ` function. + + .. NOTE:: + + This option should be defined at the :ref:`global level `. + + | + | Type: number + | Default: 1 + | Environment variable: TT_SHARDING_SYNC_TIMEOUT + +.. _configuration_reference_sharding_weight: + +.. confval:: sharding.weight + + **Since:** :doc:`3.1.0 ` + + The relative amount of data that a replica set can store. + Learn more at :ref:`vshard-replica-set-weights`. + + .. NOTE:: + + ``sharding.weight`` can be specified at the :ref:`replica set level `. + + | + | Type: number + | Default: 1 + | Environment variable: TT_SHARDING_WEIGHT + +.. _configuration_reference_sharding_zone: + +.. confval:: sharding.zone + + A zone that can be set for routers and replicas. + This allows sending read-only requests not only to a master instance but to any available replica that is the nearest to the router. + + .. NOTE:: + + ``sharding.zone`` can be specified at any :ref:`level `. + + | + | Type: integer + | Default: nil + | Environment variable: TT_SHARDING_ZONE + +.. _configuration_reference_snapshot: + +snapshot +-------- + +The ``snapshot`` section defines configuration parameters related to the :ref:`snapshot files `. +To learn more about the snapshots' configuration, check the :ref:`Persistence ` page. + +.. NOTE:: + + ``snapshot`` can be defined in any :ref:`scope `. + +- :ref:`snapshot.dir ` +- :ref:`snapshot.snap_io_rate_limit ` +- :ref:`snapshot.count ` +- :ref:`snapshot.by.* ` + +.. _configuration_reference_snapshot_dir: + +.. confval:: snapshot.dir + + A directory where memtx stores snapshot (.snap) files. + A relative path in this option is interpreted as relative to ``process.work_dir``. + + By default, snapshots and WAL files are stored in the same directory. + However, you can set different values for the ``snapshot.dir`` and :ref:`wal.dir ` options + to store them on different physical disks for performance matters. + + | + | Type: string + | Default: 'var/lib/{{ instance_name }}' + | Environment variable: TT_SNAPSHOT_DIR + +.. _configuration_reference_snapshot_snap_io_rate_limit: + +.. confval:: snapshot.snap_io_rate_limit + + Reduce the throttling effect of :doc:`box.snapshot() ` on + INSERT/UPDATE/DELETE performance by setting a limit on how many + megabytes per second it can write to disk. The same can be + achieved by splitting :ref:`wal.dir ` and + :ref:`snapshot.dir ` + locations and moving snapshots to a separate disk. + The limit also affects what + :ref:`box.stat.vinyl().regulator ` + may show for the write rate of dumps to ``.run`` and ``.index`` files. + + | + | Type: number + | Default: box.NULL + | Environment variable: TT_SNAPSHOT_SNAP_IO_RATE_LIMIT + +.. _configuration_reference_snapshot_count: + +.. confval:: snapshot.count + + The maximum number of snapshots that are stored in the + :ref:`snapshot.dir ` directory. + If the number of snapshots after creating a new one exceeds this value, + the :ref:`Tarantool garbage collector ` deletes old snapshots. + If ``snapshot.count`` is set to zero, the garbage collector + does not delete old snapshots. + + **Example** + + In the example, the checkpoint daemon creates a snapshot every two hours until + it has created three snapshots. After creating a new snapshot (the fourth one), the oldest snapshot + and any associated write-ahead-log files are deleted. + + .. code-block:: yaml + + snapshot: + by: + interval: 7200 + count: 3 + + .. NOTE:: + + Snapshots will not be deleted if replication is ongoing and the file has not been relayed to a replica. + Therefore, ``snapshot.count`` has no effect unless all replicas are alive. + + | + | Type: integer + | Default: 2 + | Environment variable: TT_SNAPSHOT_COUNT + +.. _configuration_reference_snapshot_by: + +snapshot.by.* +~~~~~~~~~~~~~ + +* :ref:`snapshot.by.interval ` +* :ref:`snapshot.by.wal_size ` + +.. _configuration_reference_snapshot_by_interval: + +.. confval:: snapshot.by.interval + + The interval in seconds between actions by the :ref:`checkpoint daemon `. + If the option is set to a value greater than zero, and there is + activity that causes change to a database, then the checkpoint daemon calls + :doc:`box.snapshot() ` every ``snapshot.by.interval`` + seconds, creating a new snapshot file each time. + If the option is set to zero, the checkpoint daemon is disabled. + + **Example** + + In the example, the checkpoint daemon creates a new database snapshot every two hours, if there is activity. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_snapshot/config.yaml + :language: yaml + :start-at: by: + :end-at: interval: 7200 + :dedent: + + | + | Type: number + | Default: 3600 + | Environment variable: TT_SNAPSHOT_BY_INTERVAL + +.. _configuration_reference_snapshot_by_wal_size: + +.. confval:: snapshot.by.wal_size + + The threshold for the total size in bytes for all WAL files created since the last snapshot taken. + Once the configured threshold is exceeded, the WAL thread notifies the + :ref:`checkpoint daemon ` that it must make a new snapshot and delete old WAL files. + + | + | Type: integer + | Default: 10^18 + | Environment variable: TT_SNAPSHOT_BY_WAL_SIZE + + + +.. _configuration_reference_sql: + +sql +--- + +The ``sql`` section defines configuration parameters related to :ref:`SQL `. + +.. NOTE:: + + ``sql`` can be defined in any :ref:`scope `. + +- :ref:`sql.cache_size ` + +.. _configuration_reference_sql_cache_size: + +.. confval:: sql.cache_size + + The maximum cache size (in bytes) for all :ref:`SQL prepared statements `. + To see the actual cache size, use :ref:`box.info.sql().cache.size `. + + | + | Type: integer + | Default: 5242880 + | Environment variable: TT_SQL_CACHE_SIZE + + + +.. _configuration_reference_vinyl: + +vinyl +----- + +The ``vinyl`` section defines configuration parameters related to the +:ref:`vinyl storage engine `. + +.. NOTE:: + + ``vinyl`` can be defined in any :ref:`scope `. + +- :ref:`vinyl.bloom_fpr ` +- :ref:`vinyl.cache ` +- :ref:`vinyl.defer_deletes ` +- :ref:`vinyl.dir ` +- :ref:`vinyl.max_tuple_size ` +- :ref:`vinyl.memory ` +- :ref:`vinyl.page_size ` +- :ref:`vinyl.range_size ` +- :ref:`vinyl.read_threads ` +- :ref:`vinyl.run_count_per_level ` +- :ref:`vinyl.run_size_ratio ` +- :ref:`vinyl.timeout ` +- :ref:`vinyl.write_threads ` + +.. _configuration_reference_vinyl_bloom_fpr: + +.. confval:: vinyl.bloom_fpr + + A bloom filter's false positive rate -- the suitable probability of the + `bloom filter `_ + to give a wrong result. + The ``vinyl.bloom_fpr`` setting is a default value for the + :ref:`bloom_fpr ` + option passed to ``space_object:create_index()``. + + | + | Type: number + | Default: 0.05 + | Environment variable: TT_VINYL_BLOOM_FPR + +.. _configuration_reference_vinyl_cache: + +.. confval:: vinyl.cache + + The cache size for the vinyl storage engine. The cache can + be resized dynamically. + + | + | Type: integer + | Default: 128 * 1024 * 1024 + | Environment variable: TT_VINYL_CACHE + +.. _configuration_reference_vinyl_defer_deletes: + +.. confval:: vinyl.defer_deletes + + Enable the deferred DELETE optimization in vinyl. It was disabled by default + since Tarantool version 2.10 to avoid possible performance degradation + of secondary index reads. + + | + | Type: boolean + | Default: false + | Environment variable: TT_VINYL_DEFER_DELETES + +.. _configuration_reference_vinyl_dir: + +.. confval:: vinyl.dir + + A directory where vinyl files or subdirectories will be stored. + + This option may contain a relative file path. + In this case, it is interpreted as relative to + :ref:`process.work_dir `. + + | + | Type: string + | Default: 'var/lib/{{ instance_name }}' + | Environment variable: TT_VINYL_DIR + +.. _configuration_reference_vinyl_max_tuple_size: + +.. confval:: vinyl.max_tuple_size + + The size of the largest allocation unit, for the vinyl storage engine. + It can be increased if it is necessary to store large tuples. + + | + | Type: integer + | Default: 1024 * 1024 + | Environment variable: TT_VINYL_MAX_TUPLE_SIZE + +.. _configuration_reference_vinyl_memory: + +.. confval:: vinyl.memory + + The maximum number of in-memory bytes that vinyl uses. + + | + | Type: integer + | Default: 128 * 1024 * 1024 + | Environment variable: TT_VINYL_MEMORY + +.. _configuration_reference_vinyl_page_size: + +.. confval:: vinyl.page_size + + The page size. A page is a read/write unit for vinyl disk operations. + The ``vinyl.page_size`` setting is a default value + for the :ref:`page_size ` + option passed to ``space_object:create_index()``. + + | + | Type: integer + | Default: 8 * 1024 + | Environment variable: TT_VINYL_PAGE_SIZE + +.. _configuration_reference_vinyl_range_size: + +.. confval:: vinyl.range_size + + The default maximum range size for a vinyl index, in bytes. + The maximum range size affects the decision of whether to + :ref:`split ` a range. + + If ``vinyl.range_size`` is specified (but the value is not ``null`` or 0), then + it is used as the default value for the + :ref:`range_size ` + option passed to ``space_object:create_index()``. + + If ``vinyl.range_size`` is not specified (or is explicitly set to ``null`` or 0), + and ``range_size`` is not specified when the index is created, + then Tarantool sets a value later depending on performance considerations. + To see the actual value, use + :doc:`index_object:stat().range_size `. + + | + | Type: integer + | Default: box.NULL (means that an effective default is determined in runtime) + | Environment variable: TT_VINYL_RANGE_SIZE + +.. _configuration_reference_vinyl_read_threads: + +.. confval:: vinyl.read_threads + + The maximum number of read threads that vinyl can use for + concurrent operations, such as I/O and compression. + + | + | Type: integer + | Default: 1 + | Environment variable: TT_VINYL_READ_THREADS + +.. _configuration_reference_vinyl_run_count_per_level: + +.. confval:: vinyl.run_count_per_level + + The maximum number of runs per level in the vinyl LSM tree. + If this number is exceeded, a new level is created. + The ``vinyl.run_count_per_level`` setting is a default value for the + :ref:`run_count_per_level ` + option passed to ``space_object:create_index()``. + + | + | Type: integer + | Default: 2 + | Environment variable: TT_VINYL_RUN_COUNT_PER_LEVEL + +.. _configuration_reference_vinyl_run_size_ratio: + +.. confval:: vinyl.run_size_ratio + + The ratio between the sizes of different levels in the LSM tree. + The ``vinyl.run_size_ratio`` setting is a default value for the + :ref:`run_size_ratio ` + option passed to ``space_object:create_index()``. + + | + | Type: number + | Default: 3.5 + | Environment variable: TT_VINYL_RUN_SIZE_RATIO + +.. _configuration_reference_vinyl_timeout: + +.. confval:: vinyl.timeout + + The vinyl storage engine has a scheduler that performs compaction. + When vinyl is low on available memory, the compaction scheduler + may be unable to keep up with incoming update requests. + In that situation, queries may time out after ``vinyl.timeout`` seconds. + This should rarely occur, since normally vinyl + throttles inserts when it is running low on compaction bandwidth. + Compaction can also be initiated manually with + :doc:`/reference/reference_lua/box_index/compact`. + + | + | Type: integer + | Default: 60 + | Environment variable: TT_VINYL_TIMEOUT + +.. _configuration_reference_vinyl_write_threads: + +.. confval:: vinyl.write_threads + + The maximum number of write threads that vinyl can use for some + concurrent operations, such as I/O and compression. + + | + | Type: integer + | Default: 4 + | Environment variable: TT_VINYL_WRITE_THREADS + +.. _configuration_reference_wal: + +wal +--- + +The ``wal`` section defines configuration parameters related to :ref:`write-ahead log `. +To learn more about the WAL configuration, check the :ref:`Persistence ` page. + +.. NOTE:: + + ``wal`` can be defined in any :ref:`scope `. + +- :ref:`wal.cleanup_delay ` +- :ref:`wal.dir ` +- :ref:`wal.dir_rescan_delay ` +- :ref:`wal.max_size ` +- :ref:`wal.mode ` +- :ref:`wal.queue_max_size ` +- :ref:`wal.retention_period ` +- :ref:`wal.ext.* ` + +.. _configuration_reference_wal_cleanup_delay: + +.. confval:: wal.cleanup_delay + + The delay in seconds used to prevent the :ref:`Tarantool garbage collector ` + from immediately removing :ref:`write-ahead log ` files after a node restart. + This delay eliminates possible erroneous situations when the master deletes WALs + needed by :ref:`replicas ` after restart. + As a consequence, replicas sync with the master faster after its restart and + don't need to download all the data again. + Once all the nodes in the replica set are up and running, a scheduled garbage collection is started again + even if ``wal.cleanup_delay`` has not expired. + + .. NOTE:: + + The option has no effect on nodes running as + :ref:`anonymous replicas `. + + See also: :ref:`wal.retention_period ` + + | + | Type: number + | Default: 14400 + | Environment variable: TT_WAL_CLEANUP_DELAY + +.. _configuration_reference_wal_dir: + +.. confval:: wal.dir + + A directory where write-ahead log (``.xlog``) files are stored. + A relative path in this option is interpreted as relative to ``process.work_dir``. + + By default, WAL files and snapshots are stored in the same directory. + However, you can set different values for the ``wal.dir`` and :ref:`snapshot.dir ` options + to store them on different physical disks for performance matters. + + | + | Type: string + | Default: 'var/lib/{{ instance_name }}' + | Environment variable: TT_WAL_DIR + +.. _configuration_reference_wal_dir_rescan_delay: + +.. confval:: wal.dir_rescan_delay + + The time interval in seconds between periodic scans of the write-ahead-log + file directory, when checking for changes to write-ahead-log + files for the sake of :ref:`replication ` or :ref:`hot standby `. + + | + | Type: number + | Default: 2 + | Environment variable: TT_WAL_DIR_RESCAN_DELAY + +.. _configuration_reference_wal_max_size: + +.. confval:: wal.max_size + + The maximum number of bytes in a single write-ahead log file. + When a request would cause an ``.xlog`` file to become larger than + ``wal.max_size``, Tarantool creates a new WAL file. + + | + | Type: integer + | Default: 268435456 + | Environment variable: TT_WAL_MAX_SIZE + +.. _configuration_reference_wal_mode: + +.. confval:: wal.mode + + Specify fiber-WAL-disk synchronization mode as: + + * ``none``: write-ahead log is not maintained. + A node with ``wal.mode`` set to ``none`` can't be a replication master. + + * ``write``: :ref:`fibers ` wait for their data to be written to + the write-ahead log (no ``fsync(2)``). + + * ``fsync``: fibers wait for their data, :manpage:`fsync(2)` + follows each :manpage:`write(2)`. + + | + | Type: string + | Default: 'write' + | Environment variable: TT_WAL_MODE + +.. _configuration_reference_wal_queue_max_size: + +.. confval:: wal.queue_max_size + + The size of the queue in bytes used by a :ref:`replica ` to submit + new transactions to a :ref:`write-ahead log ` (WAL). + This option helps limit the rate at which a replica submits transactions to the WAL. + + Limiting the queue size might be useful when a replica is trying to sync with a master and + reads new transactions faster than writing them to the WAL. + + .. NOTE:: + + You might consider increasing the ``wal.queue_max_size`` value in case of + large tuples (approximately one megabyte or larger). + + | + | Type: integer + | Default: 16777216 + | Environment variable: TT_WAL_QUEUE_MAX_SIZE + +.. _configuration_reference_wal_retention_period: + +.. confval:: wal.retention_period + + **Since:** :doc:`3.1.0 ` (`Enterprise Edition `_ only) + + The delay in seconds used to prevent the :ref:`Tarantool garbage collector ` from removing a :ref:`write-ahead log ` file after it has been closed. + If a node is restarted, ``wal.retention_period`` counts down from the last modification time of the write-ahead log file. + + The garbage collector doesn't track write-ahead logs that are to be :ref:`relayed ` to anonymous replicas, such as: + + * Anonymous replicas added as a part of a cluster configuration (see :ref:`replication.anon `). + * CDC (Change Data Capture) that retrieves data using anonymous replication. + + In case of a replica or CDC downtime, the required write-ahead logs can be removed. + As a result, such a replica needs to be rebootstrapped. + You can use ``wal.retention_period`` to prevent such issues. + + Note that :ref:`wal.cleanup_delay ` option also sets the delay used to prevent the Tarantool garbage collector from removing write-ahead logs. + The difference is that the garbage collector doesn't take into account ``wal.cleanup_delay`` if all the nodes in the replica set are up and running, which may lead to the removal of the required write-ahead logs. + + .. NOTE:: + + :ref:`box.info.gc().wal_retention_vclock ` can be used to get a vclock value of the oldest write-ahead log protected by ``wal.retention_period``. + + | + | Type: number + | Default: 0 + | Environment variable: TT_WAL_RETENTION_PERIOD + +.. _configuration_reference_wal_ext: + +wal.ext.* +~~~~~~~~~ + +.. admonition:: Enterprise Edition + :class: fact + + Configuring ``wal.ext.*`` parameters is available in the `Enterprise Edition `_ only. + +This section describes options related to :ref:`WAL extensions `. + +* :ref:`wal.ext.new ` +* :ref:`wal.ext.old ` +* :ref:`wal.ext.spaces ` + +.. _configuration_reference_wal_ext_new: + +.. confval:: wal.ext.new + + Enable storing a new tuple for each :ref:`CRUD ` operation performed. + The option is in effect for all spaces. + To adjust the option for specific spaces, use the :ref:`wal.ext.spaces ` + option. + + | + | Type: boolean + | Default: false + | Environment variable: TT_WAL_EXT_NEW + +.. _configuration_reference_wal_ext_old: + +.. confval:: wal.ext.old + + Enable storing an old tuple for each :ref:`CRUD ` operation performed. + The option is in effect for all spaces. + To adjust the option for specific spaces, use the :ref:`wal.ext.spaces ` + option. + + | + | Type: boolean + | Default: false + | Environment variable: TT_WAL_EXT_OLD + +.. _configuration_reference_wal_ext_spaces: + +.. confval:: wal.ext.spaces + + Enable or disable storing an old and new tuple in the :ref:`WAL ` record + for a given space explicitly. + The configuration for specific spaces has priority over the configuration in the + :ref:`wal.ext.new ` and :ref:`wal.ext.old ` + options. + + The option is a key-value pair: + + * The key is a space name (string). + + * The value is a table that includes two optional boolean options: ``old`` and ``new``. + The format and the default value of these options are described in ``wal.ext.old`` and ``wal.ext.new``. + + **Example** + + In the example, only new tuples are added to the log for the ``bands`` space. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/persistence_wal/config.yaml + :language: yaml + :start-at: ext: + :end-at: old: false + :dedent: + + | + | Type: map + | Default: nil + | Environment variable: TT_WAL_EXT_SPACES diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst index be2a510d02..f27ab31ff3 100644 --- a/doc/reference/configuration/index.rst +++ b/doc/reference/configuration/index.rst @@ -1,503 +1,86 @@ -.. _index-book_cfg: - -================================================================================ -Configuration reference -================================================================================ - -This reference covers all options and parameters which can be set for Tarantool -on the command line or in an :ref:`initialization file `. - -Tarantool is started by entering either of the following command: - -.. cssclass:: highlight -.. parsed-literal:: - - $ **tarantool** - - $ **tarantool** *options* - - $ **tarantool** *lua-initialization-file* **[** *arguments* **]** - --------------------------------------------------------------------------------- -Command options --------------------------------------------------------------------------------- - -.. option:: -h, --help - - Print an annotated list of all available options and exit. - -.. _index-tarantool_version: - -.. option:: -v, -V, --version - - Print the product name and version. - - **Example** - - .. code-block:: console - - % tarantool --version - Tarantool 2.11.1-0-g96877bd - Target: Darwin-arm64-Release - ... - - In this example: - - * ``2.11.1`` is a Tarantool version. - Tarantool follows semantic versioning, which is described in the :ref:`Tarantool release policy ` section. - - * ``Target`` is the platform Tarantool is built on. - Platform-specific details may follow this line. - - -.. option:: -e EXPR - - Execute the 'EXPR' string. See also: `lua man page `_. - - **Example** - - .. code-block:: console - - % tarantool -e "print('Hello, world!')" - Hello, world! - -.. option:: -l NAME - - Require the 'NAME' library. See also: `lua man page `_. - - **Example** - - .. code-block:: console - - % tarantool -l luatest.coverage script.lua - -.. option:: -j cmd - - Perform a LuaJIT control command. See also: `Command Line Options `_. - - **Example** - - .. code-block:: console - - % tarantool -j off app.lua - -.. option:: -b ... - - Save or list bytecode. See also: `Command Line Options `_. - - **Example** - - .. code-block:: console - - % tarantool -b test.lua test.out - -.. option:: -d SCRIPT - - Activate a debugging session for 'SCRIPT'. See also: `luadebug.lua `_. - - **Example** - - .. code-block:: console - - % tarantool -d app.lua - - -.. option:: -i [SCRIPT] - - Enter an :ref:`interactive mode ` after executing 'SCRIPT'. - - **Example** - - .. code-block:: console - - % tarantool -i - - -.. option:: -- - - Stop handling options. See also: `lua man page `_. - - -.. option:: - - - Stop handling options and execute the standard input as a file. See also: `lua man page `_. - - -.. _index-uri: - --------------------------------------------------------------------------------- -URI --------------------------------------------------------------------------------- - -Some configuration parameters and some functions depend on a URI (Universal Resource Identifier). -The URI string format is similar to the -`generic syntax for a URI schema `_. -It may contain (in order): - -* user name for login -* password -* host name or host IP address -* port number. - -Only a port number is always mandatory. A password is mandatory if a user -name is specified, unless the user name is 'guest'. - -Formally, the URI -syntax is ``[host:]port`` or ``[username:password@]host:port``. -If host is omitted, then "0.0.0.0" or "[::]" is assumed -meaning respectively any IPv4 address or any IPv6 address -on the local machine. -If ``username:password`` is omitted, then the "guest" user is assumed. Some examples: - -.. container:: table - - .. rst-class:: left-align-column-1 - .. rst-class:: left-align-column-2 - - +-----------------------------+------------------------------+ - | URI fragment | Example | - +=============================+==============================+ - | port | 3301 | - +-----------------------------+------------------------------+ - | host:port | 127.0.0.1:3301 | - +-----------------------------+------------------------------+ - | username:password@host:port | notguest:sesame@mail.ru:3301 | - +-----------------------------+------------------------------+ - -In code, the URI value can be passed as a number (if only a port is specified) or a string: - -.. code-block:: lua - - box.cfg { listen = 3301 } - - box.cfg { listen = "127.0.0.1:3301" } - -In certain circumstances, a Unix domain socket may be used -where a URI is expected, for example, "unix/:/tmp/unix_domain_socket.sock" or -simply "/tmp/unix_domain_socket.sock". - -The :ref:`uri ` module provides functions that convert URI strings into their -components, or turn components into URI strings. - -.. _index-uri-several: - -Specifying several URIs -~~~~~~~~~~~~~~~~~~~~~~~ - -Starting from version 2.10.0, a user can open several listening iproto sockets on a Tarantool instance -and, consequently, can specify several URIs in the configuration parameters -such as :ref:`box.cfg.listen ` and :ref:`box.cfg.replication `. - -URI values can be set in a number of ways: - -* As a string with URI values separated by commas. - - .. code-block:: lua - - box.cfg { listen = "127.0.0.1:3301, /unix.sock, 3302" } - -* As a table that contains URIs in the string format. - - .. code-block:: lua - - box.cfg { listen = {"127.0.0.1:3301", "/unix.sock", "3302"} } - -* As an array of tables with the ``uri`` field. - - .. code-block:: lua - - box.cfg { listen = { - {uri = "127.0.0.1:3301"}, - {uri = "/unix.sock"}, - {uri = 3302} - } - } - -* In a combined way -- an array that contains URIs in both the string and the table formats. - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301", - { uri = "/unix.sock" }, - { uri = 3302 } - } - } - -.. _index-uri-several-params: - -Also, starting from version 2.10.0, it is possible to specify additional parameters for URIs. -You can do this in different ways: - -* Using the ``?`` delimiter when URIs are specified in a string format. - - .. code-block:: lua - - box.cfg { listen = "127.0.0.1:3301?p1=value1&p2=value2, /unix.sock?p3=value3" } - -* Using the ``params`` table: a URI is passed in a table with additional parameters in the "params" table. - Parameters in the "params" table overwrite the ones from a URI string ("value2" overwrites "value1" for ``p1`` in the example below). - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301?p1=value1", - params = {p1 = "value2", p2 = "value3"} - } - } - -* Using the ``default_params`` table for specifying default parameter values. - - In the example below, two URIs are passed in a table. - The default value for the ``p3`` parameter is defined in the ``default_params`` table - and used if this parameter is not specified in URIs. - Parameters in the ``default_params`` table are applicable to all the URIs passed in a table. - - .. code-block:: lua - - box.cfg { listen = { - "127.0.0.1:3301?p1=value1", - { uri = "/unix.sock", params = { p2 = "value2" } }, - default_params = { p3 = "value3" } - } - } - -The recommended way for specifying URI with additional parameters is the following: - -.. code-block:: lua - - box.cfg { listen = { - {uri = "127.0.0.1:3301", params = {p1 = "value1"}}, - {uri = "/unix.sock", params = {p2 = "value2"}}, - {uri = 3302, params = {p3 = "value3"}} - } - } - -In case of a single URI, the following syntax also works: - -.. code-block:: lua - - box.cfg { listen = { - uri = "127.0.0.1:3301", - params = { p1 = "value1", p2 = "value2" } - } - } - -.. _index-init_label: - --------------------------------------------------------------------------------- -Initialization file --------------------------------------------------------------------------------- - -If the command to start Tarantool includes :codeitalic:`lua-initialization-file`, then -Tarantool begins by invoking the Lua program in the file, which by convention -may have the name "``script.lua``". The Lua program may get further arguments -from the command line or may use operating-system functions, such as ``getenv()``. -The Lua program almost always begins by invoking ``box.cfg()``, if the database -server will be used or if ports need to be opened. For example, suppose -``script.lua`` contains the lines - -.. _index-init-example: - -.. code-block:: lua - - #!/usr/bin/env tarantool - box.cfg{ - listen = os.getenv("LISTEN_URI"), - memtx_memory = 33554432, - pid_file = "tarantool.pid", - wal_max_size = 2500 - } - print('Starting ', arg[1]) - -and suppose the environment variable LISTEN_URI contains 3301, -and suppose the command line is ``~/tarantool/src/tarantool script.lua ARG``. -Then the screen might look like this: - -.. code-block:: console - - $ export LISTEN_URI=3301 - $ ~/tarantool/src/tarantool script.lua ARG - ... main/101/script.lua C> Tarantool 2.8.3-0-g01023dbc2 - ... main/101/script.lua C> log level 5 - ... main/101/script.lua I> mapping 33554432 bytes for memtx tuple arena... - ... main/101/script.lua I> recovery start - ... main/101/script.lua I> recovering from './00000000000000000000.snap' - ... main/101/script.lua I> set 'listen' configuration option to "3301" - ... main/102/leave_local_hot_standby I> ready to accept requests - Starting ARG - ... main C> entering the event loop - -If you wish to start an interactive session on the same terminal after -initialization is complete, you can use :ref:`console.start() `. - -.. _index-local_hot_standby: -.. _index-replication_port: -.. _index-slab_alloc_arena: -.. _index-replication_source: -.. _index-snap_dir: -.. _index-wal_dir: -.. _index-wal_mode: -.. _index-checkpoint daemon: - -.. _box_cfg_params: - --------------------------------------------------------------------------------- -Configuration parameters --------------------------------------------------------------------------------- - -Configuration parameters have the form: - -:extsamp:`{**{box.cfg}**}{[{*{key = value}*} [, {*{key = value ...}*}]]}` - -Since ``box.cfg`` may contain many configuration parameters and since some of the -parameters (such as directory addresses) are semi-permanent, it's best to keep -``box.cfg`` in a Lua file. Typically this Lua file is the initialization file -which is specified on the Tarantool command line. - -Most configuration parameters are for allocating resources, opening ports, and -specifying database behavior. All parameters are optional. -A few parameters are dynamic, that is, they can be changed at runtime by calling ``box.cfg{}`` a second time. -For example, the command below sets the :ref:`listen port ` to ``3301``. - -.. code-block:: tarantoolsession - - tarantool> box.cfg{ listen = 3301 } - 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: stopped - 2023-05-10 13:28:54.667 [31326] main/103/interactive I> tx_binary: bound to [::]:3301 - 2023-05-10 13:28:54.667 [31326] main/103/interactive/box.load_cfg I> set 'listen' configuration option to 3301 - --- - ... - - -To see all the non-null parameters, execute ``box.cfg`` (no parentheses). - -.. code-block:: tarantoolsession - - tarantool> box.cfg - --- - - replication_skip_conflict: false - wal_queue_max_size: 16777216 - feedback_host: https://feedback.tarantool.io - memtx_dir: . - memtx_min_tuple_size: 16 - -- other parameters -- - ... - -To see a particular parameter value, call a corresponding ``box.cfg`` option. -For example, ``box.cfg.listen`` shows the specified :ref:`listen address `. - -.. code-block:: tarantoolsession - - tarantool> box.cfg.listen - --- - - 3301 - ... - - -.. _box-cfg-params-prior: - -Methods of setting and priorities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tarantool configuration parameters can be specified in different ways. -The priority of parameter sources is the following, from higher to lower: - -* ``box.cfg`` options -* :ref:`environment variables ` -* :ref:`tt configuration ` -* default values. - -.. _box-cfg-params-env: - -Setting via environment variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting from version :doc:`2.8.1 `, you can specify configuration parameters via special environment variables. -The name of a variable should have the following pattern: ``TT_``, -where ```` is the uppercase name of the corresponding :ref:`box.cfg parameter `. - -For example: - -* ``TT_LISTEN`` -- corresponds to the ``box.cfg.listen`` option. -* ``TT_MEMTX_DIR`` -- corresponds to the ``box.cfg.memtx_dir`` option. - -In case of an array value, separate the array elements by comma without space: - -.. code-block:: console - - export TT_REPLICATION="localhost:3301,localhost:3302" - -If you need to pass :ref:`additional parameters for URI `, use the ``?`` and ``&`` delimiters: - -.. code-block:: console - - export TT_LISTEN="localhost:3301?param1=value1¶m2=value2" +.. _index-book_cfg: +.. _box-cfg-params-ref: -An empty variable (``TT_LISTEN=``) has the same effect as an unset one meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. +Configuration reference (box.cfg) +================================= -.. _box-cfg-params-ref: +.. include:: /platform/configuration/configuration_code.rst + :start-after: box_cfg_legacy_note_start + :end-before: box_cfg_legacy_note_end -Reference -~~~~~~~~~ -The sections that follow describe all configuration parameters for basic operations, storage, -binary logging and snapshots, replication, networking, logging, and feedback. +This topic describes all configuration parameters +that can be specified :ref:`in code ` using the ``box.cfg`` API. .. contents:: :local: :depth: 1 Basic parameters -^^^^^^^^^^^^^^^^ +---------------- .. include:: cfg_basic.rst Configuring the storage -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- .. include:: cfg_storage.rst .. _book_cfg_checkpoint_daemon: Checkpoint daemon -^^^^^^^^^^^^^^^^^ +----------------- .. include:: cfg_snapshot_daemon.rst Binary logging and snapshots -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- .. include:: cfg_binary_logging_snapshots.rst .. _index-hot_standby: Hot standby -^^^^^^^^^^^ +----------- .. include:: cfg_hot_standby.rst Replication -^^^^^^^^^^^ +----------- .. include:: cfg_replication.rst Networking -^^^^^^^^^^ +---------- .. include:: cfg_networking.rst Logging -^^^^^^^ +------- .. include:: cfg_logging.rst +Audit log +--------- + +.. include:: cfg_audit.rst + +Authentication +-------------- + +.. include:: cfg_authentication.rst + +Flight recorder +--------------- + +.. include:: cfg_flight_recorder.rst + Feedback -^^^^^^^^ +-------- .. include:: cfg_feedback.rst Deprecated parameters -^^^^^^^^^^^^^^^^^^^^^ +--------------------- .. include:: cfg_deprecated.rst diff --git a/doc/reference/index.rst b/doc/reference/index.rst index eb61be86a6..2470fd4657 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -10,12 +10,12 @@ Reference .. toctree:: :maxdepth: 2 + configuration/configuration_reference configuration/index - tooling/index + tarantool_cli_options reference_sql/index reference_lua/index reference_rock/index - ../dev_guide/reference_capi/index - ../dev_guide/internals/index - ../book/box/limitations - lua_tips + reference_capi/index + internals/index + limitations diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/reference/internals/box_protocol.rst similarity index 97% rename from doc/dev_guide/internals/box_protocol.rst rename to doc/reference/internals/box_protocol.rst index 6df35f1208..cca7e59ac9 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/reference/internals/box_protocol.rst @@ -31,6 +31,7 @@ The binary protocol provides complete access to Tarantool functionality, includi .. toctree:: :maxdepth: 1 + iproto/iproto iproto/mp_types iproto/format iproto/keys @@ -41,4 +42,3 @@ The binary protocol provides complete access to Tarantool functionality, includi iproto/graceful_shutdown iproto/sql iproto/replication - Examples <../../how-to/other/iproto> diff --git a/doc/reference/internals/file_formats.rst b/doc/reference/internals/file_formats.rst new file mode 100644 index 0000000000..edf7b55c42 --- /dev/null +++ b/doc/reference/internals/file_formats.rst @@ -0,0 +1,172 @@ +.. _internals-data_persistence: + +File formats +============ + +.. _internals-wal: + +The WAL file format +------------------- + +To maintain :ref:`data persistence `, Tarantool writes each data change request (insert, +update, delete, replace, upsert) to a write-ahead log (WAL) file in the +:ref:`wal.dir ` directory. +Each data change request is assigned a continuously growing 64-bit log sequence +number. The name of the WAL file is based on the log sequence number of the first +record in the file, plus an extension ``.xlog``. +A new WAL file is created +when the current one reaches the :ref:`wal_max_size ` size. + +Each WAL record contains: + +* a log sequence number +* a data change request (formatted as in :ref:`Tarantool's binary protocol `) + +* a header +* some metadata +* the data formatted according to `msgpack `_ rules. + +To see the hexadecimal bytes of the given WAL file, use the ``hexdump`` command: + +.. code-block:: console + + $ hexdump 00000000000000000000.xlog + +For example, the WAL file after the first INSERT request might look the following way: + +.. code-block:: none + + Hex dump of WAL file Comment + -------------------- ------- + 58 4c 4f 47 0a "XLOG\n" + 30 2e 31 33 0a "0.13\n" = version + 53 65 72 76 65 72 3a 20 "Server: " + 38 62 66 32 32 33 65 30 2d [Server UUID]\n + 36 39 31 34 2d 34 62 35 35 + 2d 39 34 64 32 2d 64 32 62 + 36 64 30 39 62 30 31 39 36 + 0a + 56 43 6c 6f 63 6b 3a 20 "Vclock: " + 7b 7d "{}" = vclock value, initially blank + ... (not shown = tuples for system spaces) + d5 ba 0b ab Magic row marker always = 0xab0bbad5 + 19 Length, not including length of header, = 25 bytes + 00 Record header: previous crc32 + ce 8c 3e d6 70 Record header: current crc32 + a7 cc 73 7f 00 00 66 39 Record header: padding + 84 msgpack code meaning "Map of 4 elements" follows + 00 02 element#1: tag=request type, value=0x02=IPROTO_INSERT + 02 01 element#2: tag=server id, value=0x01 + 03 04 element#3: tag=lsn, value=0x04 + 04 cb 41 d4 e2 2f 62 fd d5 d4 element#4: tag=timestamp, value=an 8-byte "Float64" + 82 msgpack code meaning "map of 2 elements" follows + 10 cd 02 00 element#1: tag=space id, value=512, big byte first + 21 91 01 element#2: tag=tuple, value=1-element fixed array={1} + +Tarantool processes requests atomically: a change is either accepted and recorded +in the WAL, or discarded completely. To clarify how this happens, see the example with the REPLACE request below: + +#. The server instance attempts to locate the original tuple by primary key. If found, a + reference to the tuple is retained for later use. + +#. The new tuple is validated. If for example it does not contain an indexed + field, or it has an indexed field whose type does not match the type + according to the index definition, the change is aborted. + +#. The new tuple replaces the old tuple in all existing indexes. + +#. A message is sent to the WAL writer running in a separate thread, requesting that + the change be recorded in the WAL. The instance switches to work on the next + request until the write is acknowledged. + +#. On success, a confirmation is sent to the client. On failure, a rollback + procedure begins. During the rollback procedure, the transaction processor + rolls back all changes to the database which occurred after the first failed + change, from latest to oldest, up to the first failed change. All rolled back + requests are aborted with :errcode:`ER_WAL_IO ` error. No new + change is applied while rollback is in progress. When the rollback procedure + is finished, the server restarts the processing pipeline. + +One advantage of the described algorithm is that complete request pipelining is +achieved, even for requests on the same value of the primary key. As a result, +database performance doesn't degrade even if all requests refer to the same +key in the same space. + +The transaction processor thread communicates with the WAL writer thread using +asynchronous (yet reliable) messaging. +The transaction processor thread, not being blocked on WAL tasks, continues to handle requests quickly even at high +volumes of disk I/O. A response to a request is sent as soon as it is ready, +even if there were earlier incomplete requests on the same connection. In +particular, SELECT performance, even for SELECTs running on a connection packed +with UPDATEs and DELETEs, remains unaffected by disk load. + +The WAL writer employs a number of durability modes, as defined in configuration +variable :ref:`wal.mode `. +It is possible to turn the write-ahead log completely off, by setting the ``wal_mode`` option to *none*. +Even without the write-ahead log it's still possible to take a persistent copy of the +entire data set with the :ref:`box.snapshot() ` request. + +An ``.xlog`` file always contains changes based on the primary key. +Even if the client requested an update or delete using +a secondary key, the record in the .xlog file contains the primary key. + +.. _internals-snapshot: + +The snapshot file format +------------------------ + +The format of a snapshot (``.snap``) file is the following: + +* The snapshot header contains the instance's global unique identifier + and the snapshot file's position in history, relative to earlier snapshot files. + +* The snapshot content contains the records of inserts to memtx spaces. + That differs from the content of an ``.xlog`` file that may contain records for any data-change requests + (inserts, updates, upserts, and deletes). + +Primarily, the records in the snapshot file have the following order: + +* System spaces (id >= 256 && id <= 511), ordered by ID. +* Non-system spaces, ordered by ID. + +Secondarily, the .snap file's records are ordered by primary key within space ID. + +.. _box_protocol-xlog: + +Example +------- + +The header of a ``.snap`` or ``.xlog`` file might look in the following way: + +.. code-block:: none + + \n SNAP\n or XLOG\n + \n currently 0.13\n + Server: \n where UUID is a 36-byte string + VClock: \n e.g. {1: 0}\n + \n + +After the file header come the data tuples. +Tuples begin with a row marker ``0xd5ba0bab`` and +the last tuple may be followed by an EOF marker +``0xd510aded``. +Thus, between the file header and the EOF marker, there +may be data tuples that have this form: + +.. code-block:: none + + 0 3 4 17 + +-------------+========+============+===========+=========+ + | | | | | | + | 0xd5ba0bab | LENGTH | CRC32 PREV | CRC32 CUR | PADDING | + | | | | | | + +-------------+========+============+===========+=========+ + MP_FIXEXT2 MP_INT MP_INT MP_INT --- + + +============+ +===================================+ + | | | | + | HEADER | | BODY | + | | | | + +============+ +===================================+ + MP_MAP MP_MAP + diff --git a/doc/dev_guide/internals/index.rst b/doc/reference/internals/index.rst similarity index 100% rename from doc/dev_guide/internals/index.rst rename to doc/reference/internals/index.rst diff --git a/doc/dev_guide/internals/iproto/authentication.rst b/doc/reference/internals/iproto/authentication.rst similarity index 100% rename from doc/dev_guide/internals/iproto/authentication.rst rename to doc/reference/internals/iproto/authentication.rst diff --git a/doc/dev_guide/internals/iproto/events.rst b/doc/reference/internals/iproto/events.rst similarity index 100% rename from doc/dev_guide/internals/iproto/events.rst rename to doc/reference/internals/iproto/events.rst diff --git a/doc/dev_guide/internals/iproto/format.rst b/doc/reference/internals/iproto/format.rst similarity index 100% rename from doc/dev_guide/internals/iproto/format.rst rename to doc/reference/internals/iproto/format.rst diff --git a/doc/dev_guide/internals/iproto/graceful_shutdown.rst b/doc/reference/internals/iproto/graceful_shutdown.rst similarity index 100% rename from doc/dev_guide/internals/iproto/graceful_shutdown.rst rename to doc/reference/internals/iproto/graceful_shutdown.rst diff --git a/doc/reference/internals/iproto/images/auth.puml b/doc/reference/internals/iproto/images/auth.puml new file mode 100644 index 0000000000..8992fd03ae --- /dev/null +++ b/doc/reference/internals/iproto/images/auth.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_AUTH**" as auth_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_AUTH", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_USER_NAME]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TUPLE]]": { + "MP_ARRAY": "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/authentication Authentication mechanism]], [[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/authentication scramble]]" + } + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/auth.svg b/doc/reference/internals/iproto/images/auth.svg similarity index 80% rename from doc/dev_guide/internals/iproto/images/auth.svg rename to doc/reference/internals/iproto/images/auth.svg index d97db550e9..ed7e3fa1a1 100644 --- a/doc/dev_guide/internals/iproto/images/auth.svg +++ b/doc/reference/internals/iproto/images/auth.svg @@ -1,28 +1,28 @@ -IPROTO_AUTHSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_AUTHIPROTO_SYNCMP_UINTBodyIPROTO_USER_NAMEMP_STRIPROTO_TUPLEMP_ARRAYAuthentication mechanism,scramble \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/delete.puml b/doc/reference/internals/iproto/images/delete.puml new file mode 100644 index 0000000000..f76303cca6 --- /dev/null +++ b/doc/reference/internals/iproto/images/delete.puml @@ -0,0 +1,35 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_DELETE**" as delete_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_DELETE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INDEX_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_KEY]]": "MP_ARRAY of key values" + } +} + +json "**Response to IPROTO_DELETE**" as delete_response { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_DATA]]": "MP_OBJECT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/delete.svg b/doc/reference/internals/iproto/images/delete.svg new file mode 100644 index 0000000000..7d6699778a --- /dev/null +++ b/doc/reference/internals/iproto/images/delete.svg @@ -0,0 +1,45 @@ +IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_DELETEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_KEYMP_ARRAY of key valuesResponse to IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/error.puml b/doc/reference/internals/iproto/images/error.puml new file mode 100644 index 0000000000..7404cc6694 --- /dev/null +++ b/doc/reference/internals/iproto/images/error.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Error response**" as error_response { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "0x8XXX", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_ERROR]]": "MP_ERROR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_ERROR_24]]": "MP_STR" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/error.svg b/doc/reference/internals/iproto/images/error.svg new file mode 100644 index 0000000000..30db22d72d --- /dev/null +++ b/doc/reference/internals/iproto/images/error.svg @@ -0,0 +1,33 @@ +Error responseSizeMP_UINTHeaderIPROTO_REQUEST_TYPE0x8XXXIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_ERRORMP_ERRORIPROTO_ERROR_24MP_STR \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/error_24.puml b/doc/reference/internals/iproto/images/error_24.puml new file mode 100644 index 0000000000..827da80882 --- /dev/null +++ b/doc/reference/internals/iproto/images/error_24.puml @@ -0,0 +1,22 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Error response before 2.4.1**" as error_response { + "Size": "32", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "0x800a", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "5", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "0x78" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_ERROR]]": "Space '_space' already exists" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/error_24.svg b/doc/reference/internals/iproto/images/error_24.svg similarity index 77% rename from doc/dev_guide/internals/iproto/images/error_24.svg rename to doc/reference/internals/iproto/images/error_24.svg index dd6ac1e2e1..22be01b568 100644 --- a/doc/dev_guide/internals/iproto/images/error_24.svg +++ b/doc/reference/internals/iproto/images/error_24.svg @@ -1,26 +1,26 @@ -Error response before 2.4.1Size32HeaderIPROTO_REQUEST_TYPE0x800aIPROTO_SYNC5IPROTO_SCHEMA_VERSION0x78BodyIPROTO_ERRORSpace '_space' already exists \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/eval_example.puml b/doc/reference/internals/iproto/images/eval_example.puml new file mode 100644 index 0000000000..c2da654bd3 --- /dev/null +++ b/doc/reference/internals/iproto/images/eval_example.puml @@ -0,0 +1,22 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_EVAL** example request" as eval_request { + "Size": "24", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_EVAL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_EXPR]]": "'return 5;'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TUPLE]]": "[]" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/eval_example.svg b/doc/reference/internals/iproto/images/eval_example.svg similarity index 78% rename from doc/dev_guide/internals/iproto/images/eval_example.svg rename to doc/reference/internals/iproto/images/eval_example.svg index 6d3c6d0d71..07eb994988 100644 --- a/doc/dev_guide/internals/iproto/images/eval_example.svg +++ b/doc/reference/internals/iproto/images/eval_example.svg @@ -1,26 +1,26 @@ -IPROTO_EVALexample requestSize24HeaderIPROTO_REQUEST_TYPEIPROTO_EVALIPROTO_SYNCMP_UINTBodyIPROTO_EXPR'return 5;'IPROTO_TUPLE[] \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/execute_example_1.puml b/doc/reference/internals/iproto/images/execute_example_1.puml new file mode 100644 index 0000000000..fc2284ca63 --- /dev/null +++ b/doc/reference/internals/iproto/images/execute_example_1.puml @@ -0,0 +1,16 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Body**" as execute_body_1 { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_STMT_ID]]": "0xd7aa741b", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SQL_BIND]]": "[1, 'a']", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_OPTIONS]]": "[]" +} + +@enduml diff --git a/doc/reference/internals/iproto/images/execute_example_1.svg b/doc/reference/internals/iproto/images/execute_example_1.svg new file mode 100644 index 0000000000..1becd51669 --- /dev/null +++ b/doc/reference/internals/iproto/images/execute_example_1.svg @@ -0,0 +1,26 @@ +BodyIPROTO_STMT_ID0xd7aa741bIPROTO_SQL_BIND[1, 'a']IPROTO_OPTIONS[] \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/execute_example_2.puml b/doc/reference/internals/iproto/images/execute_example_2.puml new file mode 100644 index 0000000000..e128d7a2db --- /dev/null +++ b/doc/reference/internals/iproto/images/execute_example_2.puml @@ -0,0 +1,28 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Body**" as execute_body_2 { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_STMT_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_BIND_COUNT]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_BIND_METADATA]]": "MP_ARRAY", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_METADATA]]": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_NAME]]": "'DD'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'integer'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "false", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_AUTOINCREMENT]]": "true", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_SPAN]]": "nil", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_NAME]]": "'Д'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'string'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_COLL]]": "'unicode'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "true", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_SPAN]]": "'дд'" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/execute_example_2.svg b/doc/reference/internals/iproto/images/execute_example_2.svg new file mode 100644 index 0000000000..55121877e0 --- /dev/null +++ b/doc/reference/internals/iproto/images/execute_example_2.svg @@ -0,0 +1,38 @@ +BodyIPROTO_STMT_IDMP_UINTIPROTO_BIND_COUNTMP_INTIPROTO_BIND_METADATAMP_ARRAYIPROTO_METADATAIPROTO_FIELD_NAME'DD'IPROTO_FIELD_TYPE'integer'IPROTO_FIELD_IS_NULLABLEfalseIPROTO_FIELD_IS_AUTOINCREMENTtrueIPROTO_FIELD_SPANnilIPROTO_FIELD_NAME'Д'IPROTO_FIELD_TYPE'string'IPROTO_FIELD_COLL'unicode'IPROTO_FIELD_IS_NULLABLEtrueIPROTO_FIELD_SPAN'дд' \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/flags_example.puml b/doc/reference/internals/iproto/images/flags_example.puml similarity index 100% rename from doc/dev_guide/internals/iproto/images/flags_example.puml rename to doc/reference/internals/iproto/images/flags_example.puml diff --git a/doc/dev_guide/internals/iproto/images/flags_example.svg b/doc/reference/internals/iproto/images/flags_example.svg similarity index 99% rename from doc/dev_guide/internals/iproto/images/flags_example.svg rename to doc/reference/internals/iproto/images/flags_example.svg index 736268818e..dc1559993f 100644 --- a/doc/dev_guide/internals/iproto/images/flags_example.svg +++ b/doc/reference/internals/iproto/images/flags_example.svg @@ -1,24 +1,24 @@ Example of IPROTO_FLAGS usageSizeMP_UINTHeader............IPROTO_FLAGSMP_UINTBody... \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/id.puml b/doc/reference/internals/iproto/images/id.puml new file mode 100644 index 0000000000..4d491f084e --- /dev/null +++ b/doc/reference/internals/iproto/images/id.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_ID**" as id_request { + "Size": "MP_INT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_ID", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_VERSION]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FEATURES]]": "MP_ARRAY of MP_UINT items", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_AUTH_TYPE]]": "MP_STR" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/id.svg b/doc/reference/internals/iproto/images/id.svg new file mode 100644 index 0000000000..125417374f --- /dev/null +++ b/doc/reference/internals/iproto/images/id.svg @@ -0,0 +1,33 @@ +IPROTO_IDSizeMP_INTHeaderIPROTO_REQUEST_TYPEIPROTO_IDIPROTO_SYNCMP_UINTBodyIPROTO_VERSIONMP_UINTIPROTO_FEATURESMP_ARRAY of MP_UINT itemsIPROTO_AUTH_TYPEMP_STR \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/insert.puml b/doc/reference/internals/iproto/images/insert.puml new file mode 100644 index 0000000000..b224e5d7ed --- /dev/null +++ b/doc/reference/internals/iproto/images/insert.puml @@ -0,0 +1,34 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_INSERT**" as insert_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_INSERT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SPACE_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TUPLE]]": "MP_ARRAY" + } +} + +json "**Response to IPROTO_INSERT**" as insert_response { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_DATA]]": "MP_ARRAY of tuples" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/insert.svg b/doc/reference/internals/iproto/images/insert.svg similarity index 76% rename from doc/dev_guide/internals/iproto/images/insert.svg rename to doc/reference/internals/iproto/images/insert.svg index db2d5e958a..69cd8637d8 100644 --- a/doc/dev_guide/internals/iproto/images/insert.svg +++ b/doc/reference/internals/iproto/images/insert.svg @@ -1,38 +1,38 @@ -IPROTO_INSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_INSERTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_TUPLEMP_ARRAYResponse to IPROTO_INSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_ARRAY of tuples \ No newline at end of file +IPROTO_PREPARESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_PREPAREIPROTO_SYNCMP_UINTBodyIPROTO_SQL_TEXTMP_STR \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_ballot.puml b/doc/reference/internals/iproto/images/repl_ballot.puml new file mode 100644 index 0000000000..da48ab742e --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_ballot.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_BALLOT body**" as ballot { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_RO_CFG]]": "MP_BOOL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_VCLOCK]]": "MP_MAP", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_GC_VCLOCK]]": "MP_MAP", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_RO]]": "MP_BOOL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_ANON]]": "MP_BOOL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_IS_BOOTED]]": "MP_BOOL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_CAN_LEAD]]": "MP_BOOL", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_BOOTSTRAP_LEADER_UUID]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS]]": "MP_ARRAY", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_BALLOT_INSTANCE_NAME]]": "MP_STR" +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_ballot.svg b/doc/reference/internals/iproto/images/repl_ballot.svg new file mode 100644 index 0000000000..682a259a23 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_ballot.svg @@ -0,0 +1,33 @@ +IPROTO_BALLOT bodyIPROTO_BALLOT_IS_RO_CFGMP_BOOLIPROTO_BALLOT_VCLOCKMP_MAPIPROTO_BALLOT_GC_VCLOCKMP_MAPIPROTO_BALLOT_IS_ROMP_BOOLIPROTO_BALLOT_IS_ANONMP_BOOLIPROTO_BALLOT_IS_BOOTEDMP_BOOLIPROTO_BALLOT_CAN_LEADMP_BOOLIPROTO_BALLOT_BOOTSTRAP_LEADER_UUIDMP_STRIPROTO_BALLOT_REGISTERED_REPLICA_UUIDSMP_ARRAYIPROTO_BALLOT_INSTANCE_NAMEMP_STR \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml new file mode 100644 index 0000000000..3410a664a8 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml @@ -0,0 +1,21 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_FETCH_SNAPSHOT**" as fetch_snapshot_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_FETCH_SNAPSHOT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT – replica's version" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg new file mode 100644 index 0000000000..599abb674f --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg @@ -0,0 +1,31 @@ +IPROTO_FETCH_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_FETCH_SNAPSHOTIPROTO_SYNCMP_UINTBodyIPROTO_SERVER_VERSIONMP_UINT - replica's version \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_heartbeat_message.puml b/doc/reference/internals/iproto/images/repl_heartbeat_message.puml new file mode 100644 index 0000000000..1f3e412402 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_heartbeat_message.puml @@ -0,0 +1,22 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Heartbeat message from master**" as heartbeat_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_REPLICA_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general IPROTO_TIMESTAMP]]": "MP_DOUBLE" + }, + "Body": { + "(Optional) [[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_VCLOCK_SYNC]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_heartbeat_message.svg b/doc/reference/internals/iproto/images/repl_heartbeat_message.svg similarity index 77% rename from doc/dev_guide/internals/iproto/images/repl_heartbeat_message.svg rename to doc/reference/internals/iproto/images/repl_heartbeat_message.svg index 3d6a9cbbde..354fcddc46 100644 --- a/doc/dev_guide/internals/iproto/images/repl_heartbeat_message.svg +++ b/doc/reference/internals/iproto/images/repl_heartbeat_message.svg @@ -1 +1 @@ -Heartbeat message from masterSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_REPLICA_IDMP_UINTIPROTO_TIMESTAMPMP_DOUBLEBody(Optional)IPROTO_VCLOCK_SYNCMP_UINT \ No newline at end of file +Heartbeat message from masterSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_REPLICA_IDMP_UINTIPROTO_TIMESTAMPMP_DOUBLEBody(Optional)IPROTO_VCLOCK_SYNCMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_heartbeat_response.puml b/doc/reference/internals/iproto/images/repl_heartbeat_response.puml new file mode 100644 index 0000000000..3d74b2d8ba --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_heartbeat_response.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Response from replica**" as heartbeat_response { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/key/#general IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_REPLICA_ID]]": "MP_UINT", + "(Optional) [[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general IPROTO_TIMESTAMP]]": "MP_DOUBLE" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_VCLOCK]]": "MP_MAP", + "(Optional) [[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#general-replication IPROTO_VCLOCK_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys/#synchronous-replication IPROTO_TERM]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/repl_heartbeat_response.svg b/doc/reference/internals/iproto/images/repl_heartbeat_response.svg similarity index 79% rename from doc/dev_guide/internals/iproto/images/repl_heartbeat_response.svg rename to doc/reference/internals/iproto/images/repl_heartbeat_response.svg index e4f15d9673..c91809c181 100644 --- a/doc/dev_guide/internals/iproto/images/repl_heartbeat_response.svg +++ b/doc/reference/internals/iproto/images/repl_heartbeat_response.svg @@ -1 +1 @@ -Response from replicaSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_REPLICA_IDMP_UINT(Optional)IPROTO_TIMESTAMPMP_DOUBLEBodyIPROTO_VCLOCKMP_MAP(Optional)IPROTO_VCLOCK_SYNCMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file +Response from replicaSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_REPLICA_IDMP_UINT(Optional)IPROTO_TIMESTAMPMP_DOUBLEBodyIPROTO_VCLOCKMP_MAP(Optional)IPROTO_VCLOCK_SYNCMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_meta.puml b/doc/reference/internals/iproto/images/repl_join_meta.puml new file mode 100644 index 0000000000..23ce974da3 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_meta.puml @@ -0,0 +1,18 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_JOIN_META**" as join_meta_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_JOIN_META", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_join_meta.svg b/doc/reference/internals/iproto/images/repl_join_meta.svg new file mode 100644 index 0000000000..146a09f097 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_meta.svg @@ -0,0 +1,28 @@ +IPROTO_JOIN_METASizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOIN_METAIPROTO_SYNCMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_request.puml b/doc/reference/internals/iproto/images/repl_join_request.puml new file mode 100644 index 0000000000..559535100b --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_request.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_JOIN**" as join_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_JOIN", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_NAME]]": "MP_STR - name of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT – instance's version" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_join_request.svg b/doc/reference/internals/iproto/images/repl_join_request.svg new file mode 100644 index 0000000000..4d0a85dc97 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_request.svg @@ -0,0 +1,33 @@ +IPROTO_JOINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOINIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instanceIPROTO_INSTANCE_NAMEMP_STR - name of this instanceIPROTO_SERVER_VERSIONMP_UINT - instance's version \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_response.puml b/doc/reference/internals/iproto/images/repl_join_response.puml new file mode 100644 index 0000000000..9dee3ac724 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_response.puml @@ -0,0 +1,21 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Response to IPROTO_JOIN/IPROTO_FETCH_SNAPSHOT**" as join_response { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_VCLOCK]]": "MP_MAP" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_join_response.svg b/doc/reference/internals/iproto/images/repl_join_response.svg new file mode 100644 index 0000000000..d0a3b1d109 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_response.svg @@ -0,0 +1,31 @@ +Response to IPROTO_JOIN/IPROTO_FETCH_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTBodyIPROTO_VCLOCKMP_MAP \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_snapshot.puml b/doc/reference/internals/iproto/images/repl_join_snapshot.puml new file mode 100644 index 0000000000..8c983c53bc --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_snapshot.puml @@ -0,0 +1,18 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_JOIN_SNAPSHOT**" as join_snapshot_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_JOIN_SNAPSHOT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_join_snapshot.svg b/doc/reference/internals/iproto/images/repl_join_snapshot.svg new file mode 100644 index 0000000000..359b793d03 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_snapshot.svg @@ -0,0 +1,28 @@ +IPROTO_JOIN_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOIN_SNAPSHOTIPROTO_SYNCMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_raft.puml b/doc/reference/internals/iproto/images/repl_raft.puml new file mode 100644 index 0000000000..e2e8c6def7 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft.puml @@ -0,0 +1,26 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_RAFT**" as raft { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_TERM]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_VOTE]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_STATE]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_VCLOCK]]": "MP_MAP", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_LEADER_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_RAFT_IS_LEADER_SEEN]]": "MP_BOOL" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_raft.svg b/doc/reference/internals/iproto/images/repl_raft.svg new file mode 100644 index 0000000000..0cbccd3c85 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft.svg @@ -0,0 +1,36 @@ +IPROTO_RAFTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFTIPROTO_REPLICA_IDMP_UINTBodyIPROTO_RAFT_TERMMP_UINTIPROTO_RAFT_VOTEMP_UINTIPROTO_RAFT_STATEMP_UINTIPROTO_RAFT_VCLOCKMP_MAPIPROTO_RAFT_LEADER_IDMP_UINTIPROTO_RAFT_IS_LEADER_SEENMP_BOOL \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_raft_confirm.puml b/doc/reference/internals/iproto/images/repl_raft_confirm.puml new file mode 100644 index 0000000000..ba8edd2719 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_confirm.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_RAFT_CONFIRM**" as raft_confirm { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_CONFIRM", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_INT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_raft_confirm.svg b/doc/reference/internals/iproto/images/repl_raft_confirm.svg new file mode 100644 index 0000000000..2ac1d6ee12 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_confirm.svg @@ -0,0 +1,34 @@ +IPROTO_RAFT_CONFIRMSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_CONFIRMIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INTIPROTO_SYNCMP_UINTBodyIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_raft_demote.puml b/doc/reference/internals/iproto/images/repl_raft_demote.puml new file mode 100644 index 0000000000..1464d4cdc7 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_demote.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_RAFT_DEMOTE**" as demote { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_DEMOTE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TERM]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_raft_demote.svg b/doc/reference/internals/iproto/images/repl_raft_demote.svg new file mode 100644 index 0000000000..839ab7c2c6 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_demote.svg @@ -0,0 +1,34 @@ +IPROTO_RAFT_DEMOTESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_DEMOTEIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTBodyIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_raft_promote.puml b/doc/reference/internals/iproto/images/repl_raft_promote.puml new file mode 100644 index 0000000000..13f2ace07a --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_promote.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_RAFT_PROMOTE**" as promote { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_PROMOTE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TERM]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_raft_promote.svg b/doc/reference/internals/iproto/images/repl_raft_promote.svg new file mode 100644 index 0000000000..8ac4587c8a --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_promote.svg @@ -0,0 +1,34 @@ +IPROTO_RAFT_PROMOTESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_PROMOTEIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTBodyIPROTO_REPLICA_IDMP_UINTIPROTO_LSNMP_UINTIPROTO_TERMMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_raft_rollback.puml b/doc/reference/internals/iproto/images/repl_raft_rollback.puml new file mode 100644 index 0000000000..53d4e1a100 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_rollback.puml @@ -0,0 +1,24 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_RAFT_ROLLBACK**" as raft_rollback { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_RAFT_ROLLBACK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ID]]": "MP_INT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LSN]]": "MP_INT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_raft_rollback.svg b/doc/reference/internals/iproto/images/repl_raft_rollback.svg new file mode 100644 index 0000000000..981a8c949d --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_raft_rollback.svg @@ -0,0 +1,34 @@ +IPROTO_RAFT_ROLLBACKSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_RAFT_ROLLBACKIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INTIPROTO_SYNCMP_UINTBodyIPROTO_REPLICA_IDMP_INTIPROTO_LSNMP_INT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_register.puml b/doc/reference/internals/iproto/images/repl_register.puml new file mode 100644 index 0000000000..e09e596be2 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_register.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_REGISTER**" as register_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_REGISTER", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_NAME]]": "MP_STR - name of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_VCLOCK]]": "MP_MAP" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_register.svg b/doc/reference/internals/iproto/images/repl_register.svg new file mode 100644 index 0000000000..a63e7a8b2a --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_register.svg @@ -0,0 +1,33 @@ +IPROTO_REGISTERSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_REGISTERIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instanceIPROTO_INSTANCE_NAMEMP_STR - name of this instanceIPROTO_VCLOCKMP_MAP \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_subscribe_request.puml b/doc/reference/internals/iproto/images/repl_subscribe_request.puml new file mode 100644 index 0000000000..45d14caaf1 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_subscribe_request.puml @@ -0,0 +1,28 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_SUBSCRIBE**" as subscribe_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_SUBSCRIBE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_CLUSTER_UUID]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_NAME]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICASET_NAME]]": "MP_STR", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_VCLOCK]]": "MP_MAP", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REPLICA_ANON]]": "MP_BOOL", + "(Optional) [[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_ID_FILTER]]": "MP_ARRAY" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_subscribe_request.svg b/doc/reference/internals/iproto/images/repl_subscribe_request.svg new file mode 100644 index 0000000000..f9e30ad886 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_subscribe_request.svg @@ -0,0 +1,38 @@ +IPROTO_SUBSCRIBESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_SUBSCRIBEIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STRIPROTO_CLUSTER_UUIDMP_STRIPROTO_INSTANCE_NAMEMP_STRIPROTO_REPLICASET_NAMEMP_STRIPROTO_VCLOCKMP_MAPIPROTO_SERVER_VERSIONMP_UINTIPROTO_REPLICA_ANONMP_BOOL(Optional)IPROTO_ID_FILTERMP_ARRAY \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/repl_vote.puml b/doc/reference/internals/iproto/images/repl_vote.puml similarity index 80% rename from doc/dev_guide/internals/iproto/images/repl_vote.puml rename to doc/reference/internals/iproto/images/repl_vote.puml index 48d388ceaa..f85fd01df5 100644 --- a/doc/dev_guide/internals/iproto/images/repl_vote.puml +++ b/doc/reference/internals/iproto/images/repl_vote.puml @@ -10,7 +10,7 @@ skinparam { json "**IPROTO_VOTE**" as vote { "Size": "MP_UINT", "Header": { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_VOTE" + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_VOTE" } } diff --git a/doc/dev_guide/internals/iproto/images/repl_vote.svg b/doc/reference/internals/iproto/images/repl_vote.svg similarity index 87% rename from doc/dev_guide/internals/iproto/images/repl_vote.svg rename to doc/reference/internals/iproto/images/repl_vote.svg index 63b490c9b4..98f7e1cb87 100644 --- a/doc/dev_guide/internals/iproto/images/repl_vote.svg +++ b/doc/reference/internals/iproto/images/repl_vote.svg @@ -1,21 +1,21 @@ -IPROTO_VOTESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_VOTE \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/select_example.puml b/doc/reference/internals/iproto/images/select_example.puml new file mode 100644 index 0000000000..af96139ab6 --- /dev/null +++ b/doc/reference/internals/iproto/images/select_example.puml @@ -0,0 +1,26 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_SELECT** example request" as select_example { + "Size": "21", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_SELECT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "5" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SPACE_ID]]": "512", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INDEX_ID]]": "0", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_ITERATOR]]": "6", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_OFFSET]]": "1", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_LIMIT]]": "2", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_KEY]]": "[1]" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/select_example.svg b/doc/reference/internals/iproto/images/select_example.svg new file mode 100644 index 0000000000..7d3c39c064 --- /dev/null +++ b/doc/reference/internals/iproto/images/select_example.svg @@ -0,0 +1,36 @@ +IPROTO_SELECTexample requestSize21HeaderIPROTO_REQUEST_TYPEIPROTO_SELECTIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_ITERATOR6IPROTO_OFFSET1IPROTO_LIMIT2IPROTO_KEY[1] \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/sql_response_other.puml b/doc/reference/internals/iproto/images/sql_response_other.puml new file mode 100644 index 0000000000..65c7a84cdb --- /dev/null +++ b/doc/reference/internals/iproto/images/sql_response_other.puml @@ -0,0 +1,25 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Response to SQL requests other than SELECT, VALUES, or PRAGMA**" as sql_response_other { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SCHEMA_VERSION]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys SQL_INFO]]": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys SQL_INFO_ROW_COUNT]]": "MP_UINT", + "(Optional) [[tarantool.io/en/doc/latest/reference/internals/iproto/keys SQL_INFO_AUTO_INCREMENT_IDS]]": "MP_ARRAY" + } + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/sql_response_other.svg b/doc/reference/internals/iproto/images/sql_response_other.svg similarity index 77% rename from doc/dev_guide/internals/iproto/images/sql_response_other.svg rename to doc/reference/internals/iproto/images/sql_response_other.svg index c503403b62..30a4e1127c 100644 --- a/doc/dev_guide/internals/iproto/images/sql_response_other.svg +++ b/doc/reference/internals/iproto/images/sql_response_other.svg @@ -1,29 +1,29 @@ -Response to SQL requests other than SELECT, VALUES, or PRAGMASizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodySQL_INFOSQL_INFO_ROW_COUNTMP_UINT(Optional)SQL_INFO_AUTO_INCREMENT_IDSMP_ARRAY \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/sql_response_select_example.puml b/doc/reference/internals/iproto/images/sql_response_select_example.puml new file mode 100644 index 0000000000..06fd9e3cbb --- /dev/null +++ b/doc/reference/internals/iproto/images/sql_response_select_example.puml @@ -0,0 +1,28 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**Body**" as sql_response_select_example { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_METADATA]]": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_NAME]]": "'DD'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'integer'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "false", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_AUTOINCREMENT]]": "true", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_SPAN]]": "nil", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_NAME]]": "'Д'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_TYPE]]": "'string'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_COLL]]": "'unicode'", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_IS_NULLABLE]]": "true", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_FIELD_SPAN]]": "'дд'" + }, + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_DATA]]": { + "MP_ARRAY": "[1, 'a'], [2, 'b']" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/sql_response_select_example.svg b/doc/reference/internals/iproto/images/sql_response_select_example.svg new file mode 100644 index 0000000000..5a89e4b277 --- /dev/null +++ b/doc/reference/internals/iproto/images/sql_response_select_example.svg @@ -0,0 +1,38 @@ +BodyIPROTO_METADATAIPROTO_FIELD_NAME'DD'IPROTO_FIELD_TYPE'integer'IPROTO_FIELD_IS_NULLABLEfalseIPROTO_FIELD_IS_AUTOINCREMENTtrueIPROTO_FIELD_SPANnilIPROTO_FIELD_NAME'Д'IPROTO_FIELD_TYPE'string'IPROTO_FIELD_COLL'unicode'IPROTO_FIELD_IS_NULLABLEtrueIPROTO_FIELD_SPAN'дд'IPROTO_DATAMP_ARRAY[1, 'a'], [2, 'b'] \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/stream_begin.puml b/doc/reference/internals/iproto/images/stream_begin.puml new file mode 100644 index 0000000000..adf142994d --- /dev/null +++ b/doc/reference/internals/iproto/images/stream_begin.puml @@ -0,0 +1,23 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_BEGIN**" as begin { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_BEGIN", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_STREAM_ID]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TIMEOUT]]": "MP_DOUBLE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TXN_ISOLATION]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/stream_begin.svg b/doc/reference/internals/iproto/images/stream_begin.svg new file mode 100644 index 0000000000..6efa07e992 --- /dev/null +++ b/doc/reference/internals/iproto/images/stream_begin.svg @@ -0,0 +1,33 @@ +IPROTO_BEGINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_BEGINIPROTO_SYNCMP_UINTIPROTO_STREAM_IDMP_UINTBodyIPROTO_TIMEOUTMP_DOUBLEIPROTO_TXN_ISOLATIONMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/stream_commit.puml b/doc/reference/internals/iproto/images/stream_commit.puml new file mode 100644 index 0000000000..df8e55ddec --- /dev/null +++ b/doc/reference/internals/iproto/images/stream_commit.puml @@ -0,0 +1,19 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_COMMIT**" as commit { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_COMMIT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_STREAM_ID]]": "MP_UINT" + } +} + +@enduml diff --git a/doc/dev_guide/internals/iproto/images/stream_commit.svg b/doc/reference/internals/iproto/images/stream_commit.svg similarity index 78% rename from doc/dev_guide/internals/iproto/images/stream_commit.svg rename to doc/reference/internals/iproto/images/stream_commit.svg index d49df53f97..e08e359fa0 100644 --- a/doc/dev_guide/internals/iproto/images/stream_commit.svg +++ b/doc/reference/internals/iproto/images/stream_commit.svg @@ -1,23 +1,23 @@ -IPROTO_COMMITSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_COMMITIPROTO_SYNCMP_UINTIPROTO_STREAM_IDMP_UINT \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/update_example.puml b/doc/reference/internals/iproto/images/update_example.puml new file mode 100644 index 0000000000..0be426c72f --- /dev/null +++ b/doc/reference/internals/iproto/images/update_example.puml @@ -0,0 +1,25 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_UPDATE** example request" as update_example { + "Size": "32", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_UPDATE", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "5" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SPACE_ID]]": "512", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INDEX_ID]]": "0", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INDEX_BASE]]": "1", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TUPLE]]": "['=',2,'B']", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_KEY]]": "[999]" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/update_example.svg b/doc/reference/internals/iproto/images/update_example.svg new file mode 100644 index 0000000000..0a07709bee --- /dev/null +++ b/doc/reference/internals/iproto/images/update_example.svg @@ -0,0 +1,35 @@ +IPROTO_UPDATEexample requestSize32HeaderIPROTO_REQUEST_TYPEIPROTO_UPDATEIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_INDEX_BASE1IPROTO_TUPLE['=',2,'B']IPROTO_KEY[999] \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/update_example_0.puml b/doc/reference/internals/iproto/images/update_example_0.puml similarity index 87% rename from doc/dev_guide/internals/iproto/images/update_example_0.puml rename to doc/reference/internals/iproto/images/update_example_0.puml index b7ee374e4b..c58a74a916 100644 --- a/doc/dev_guide/internals/iproto/images/update_example_0.puml +++ b/doc/reference/internals/iproto/images/update_example_0.puml @@ -8,7 +8,7 @@ skinparam { } json "**Body**" as update_body_0 { - "[[https://tarantool.io/en/doc/latest/dev_guide/internals/iproto/keys IPROTO_TUPLE]]": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_TUPLE]]": { "[[https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/update/ Operator]]": "MP_STR: '#'", "[[https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/update/ Field number]]": "MP_INT" } diff --git a/doc/dev_guide/internals/iproto/images/update_example_0.svg b/doc/reference/internals/iproto/images/update_example_0.svg similarity index 89% rename from doc/dev_guide/internals/iproto/images/update_example_0.svg rename to doc/reference/internals/iproto/images/update_example_0.svg index 6cc5c7e4fd..db38123f70 100644 --- a/doc/dev_guide/internals/iproto/images/update_example_0.svg +++ b/doc/reference/internals/iproto/images/update_example_0.svg @@ -1,20 +1,20 @@ -BodyIPROTO_TUPLEOperatorMP_STR: '#'Field numberMP_INT \ No newline at end of file diff --git a/doc/dev_guide/internals/iproto/images/vclock.puml b/doc/reference/internals/iproto/images/vclock.puml similarity index 100% rename from doc/dev_guide/internals/iproto/images/vclock.puml rename to doc/reference/internals/iproto/images/vclock.puml diff --git a/doc/dev_guide/internals/iproto/images/vclock.svg b/doc/reference/internals/iproto/images/vclock.svg similarity index 99% rename from doc/dev_guide/internals/iproto/images/vclock.svg rename to doc/reference/internals/iproto/images/vclock.svg index ce2af34726..5d7779ba8e 100644 --- a/doc/dev_guide/internals/iproto/images/vclock.svg +++ b/doc/reference/internals/iproto/images/vclock.svg @@ -1,20 +1,20 @@ vclockreplica_id1LSN1replica_id2LSN2...... + -
2.8
2.8
2.7
2.7
2.6
2.6
2.5
2.5
2.4
2.4
2.3
2.3
2.2
2.2
Series
Series
Q3
Q3
Q4
Q4
Q2
Q2
Q1
Q1
Jul
Jul
Aug
Aug
Sep
Sep
Oct
Oct
Nov
Nov
Dec
Dec
Apr
Apr
May
May
Jun
Jun
Jan
Jan
Feb
Feb
Mar
Mar
2021
2021
Q3
Q3
Q4
Q4
Q2
Q2
Q1
Q1
Jul
Jul
Aug
Aug
Sep
Sep
Oct
Oct
Nov
Nov
Dec
Dec
Apr
Apr
May
May
Jun
Jun
Jan
Jan
Feb
Feb
Mar
Mar
2022
2022
1.10.11
1.1...
1.10.10
1.1...
1.10.12
1.1...
2.6.3
2.6...
2.7.2
2.7...
2.7.3
2.7...
2.8.2
2.8...
2.8.3
2.8...
Release
Release
Support
Support
End of life (no more patches)
End of life (no more patches)
1.10.13
1.1...
2.7
2.7
1.10.14
1.1...
1.10.9
1.1...
2.6.2
2.6...
Q3
Q3
Q4
Q4
Q2
Q2
Q1
Q1
Jul
Jul
Aug
Aug
Sep
Sep
Oct
Oct
Nov
Nov
Dec
Dec
Apr
Apr
May
May
Jun
Jun
Jan
Jan
Feb
Feb
Mar
Mar
2023
2023
1.10.15
1.1...
2.10.1
2.1...
2.10.2
2.1...
2.10.3
2.1...
2.10.4
2.1...
2.10.0
2.1...
2.10.5
2.1...
2.10.6
2.1...
1.10 LTS
1.10 LTS
Series 2
Series 2
2.11 LTS
2.11 LTS
2.10
2.10
2.11.0
2.1...
2.8.4
2.8...
2.10.7
2.1...
2.11.1
2.1...
2.10.8
2.1...Text is not SVG - cannot display \ No newline at end of file +
2024
2024
2025
2025
2026
2026
2027
2027
Apr
Apr
Jul
Jul
Oct
Oct
Jan
Jan
Apr
Apr
Jul
Jul
Oct
Oct
Jan
Jan
Apr
Apr
Jul
Jul
Oct
Oct
Jan
Jan
3.0
3.0
3.0.0
3.0.0
3.0.1
3.0.1
2.11 LTS
2.11 LTS
2.11.2
2.11.2
2.10
2.10
2.10.8
2.10.8
Release
Release
Updates and fixes
Updates and fixes
Support
Support
x.y
x.y
EOL series
EOL series
x.y
x.y
Current series
Current series
3.1
3.1
3.1.0
3.1.0
3.0.2
3.0.2
2.11.3
2.11.3
3.1.1
3.1.1
3.2
3.2
3.2.0
3.2.0
2.11.4
2.11.4
Jan
Jan
3.1.2
3.1.2
3.2.1
3.2.1
2.11.5
2.11.5
3.3
3.3
3.3.0
3.3.0
3.3.1
3.3.1
2.11.6
2.11.6
3.4
3.4
3.4.0
3.4.0
Apr
Apr
Jul
Jul
2.11.7
2.11.7Text is not SVG - cannot display \ No newline at end of file diff --git a/doc/release/_images/sample_cluster_diagram.png b/doc/release/_images/sample_cluster_diagram.png new file mode 100644 index 0000000000..d15f9f176a Binary files /dev/null and b/doc/release/_images/sample_cluster_diagram.png differ diff --git a/doc/release/calendar.rst b/doc/release/calendar.rst deleted file mode 100644 index c4851bf94e..0000000000 --- a/doc/release/calendar.rst +++ /dev/null @@ -1,235 +0,0 @@ -Release calendar -================ - -Every Tarantool release series has :ref:`the same lifecycle `. -Below you can find the lifecycle of all Tarantool versions starting from 1.10.x, -as well as currently supported versions visualised as a calendar: - -.. ifconfig:: builder not in ('latex', ) - - .. image:: _images/releases_calendar.svg - :target: ../../_images/releases_calendar.svg - :align: left - :alt: releases_calendar.svg - -.. _release-table: - -Release lifetime table ----------------------- - -The release lifetime table lists all Tarantool versions -starting from 1.10.x up to the current latest versions. -Each link leads to the release notes page of the corresponding version. -*End of life* means the release series will no longer receive any patches, updates, -or feature improvements after the specified date. -*End of support* means that we won't provide technical support to product versions -after the specified date. - -.. container:: table - - .. list-table:: - - * - Version - - Release date - - End of life - - End of support - - * - `2.11.1 LTS `_ - - August 17, 2023 - - May 24, 2025 - - Not planned yet - - * - :doc:`2.11.0 LTS ` - - May 24, 2023 - - May 24, 2025 - - Not planned yet - - * - :doc:`2.10.8 ` - - September 14, 2023 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.7 ` - - May 24, 2023 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.6 ` - - March 22, 2023 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.5 ` - - February 20, 2023 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.4 ` - - November 11, 2022 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.3 ` - - September 30, 2022 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.2 ` - - September 1, 2022 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.1 ` - - August 8, 2022 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.10.0 ` - - May 22, 2022 - - September 14, 2023 - - Not planned yet - - * - :doc:`2.8.4 ` - - April 25, 2022 - - April 25, 2022 - - Not planned yet - - * - :doc:`2.8.3 ` - - December 22, 2021 - - April 25, 2022 - - Not planned yet - - * - :doc:`2.8.2 ` - - August 19, 2021 - - April 25, 2022 - - Not planned yet - - * - :doc:`2.7.3 ` - - August 19, 2021 - - August 19, 2021 - - August 19, 2021 - - * - :doc:`2.7.2 ` - - April 21, 2021 - - August 19, 2021 - - August 19, 2021 - - * - :doc:`2.6.3 ` - - April 21, 2021 - - April 21, 2021 - - April 21, 2021 - - * - :doc:`2.6.2 ` - - December 30, 2020 - - April 21, 2021 - - April 21, 2021 - - * - :doc:`2.5.3 ` - - December 30, 2020 - - December 30, 2020 - - December 30, 2020 - - * - :doc:`2.5.2 ` - - October 22, 2020 - - December 30, 2020 - - December 30, 2020 - - * - :doc:`2.4.3 ` - - October 22, 2020 - - October 22, 2020 - - October 22, 2020 - - * - :doc:`2.4.2 ` - - July 17, 2020 - - October 22, 2020 - - October 22, 2020 - - * - :doc:`2.3.3 ` - - July 17, 2020 - - July 17, 2020 - - July 17, 2020 - - * - :doc:`2.3.2 ` - - April 20, 2020 - - July 17, 2020 - - July 17, 2020 - - * - :doc:`2.2.3 ` - - April 20, 2020 - - April 20, 2020 - - April 20, 2020 - - * - :doc:`2.2.2 ` - - December 31, 2019 - - April 20, 2020 - - April 20, 2020 - - * - :doc:`1.10.15 LTS ` - - February 20, 2023 - - February 20, 2023 - - February, 2024 - - * - :doc:`1.10.14 LTS ` - - August 8, 2022 - - February 20, 2023 - - February, 2024 - - * - :doc:`1.10.13 LTS ` - - April 25, 2022 - - February 20, 2023 - - February, 2024 - - * - :doc:`1.10.12 LTS ` - - December 22, 2021 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.11 LTS ` - - August 19, 2021 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.10 LTS ` - - April 24, 2021 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.9 LTS ` - - December 30, 2020 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.8 LTS ` - - October 22, 2020 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.7 LTS ` - - July 17, 2020 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.6 LTS ` - - April 20, 2020 - - February 20, 2022 - - February 20, 2023 - - * - :doc:`1.10.5 LTS ` - - January 14, 2020 - - February 20, 2022 - - February 20, 2023 - - * - :ref:`1.10.4 LTS ` - - September 26, 2019 - - February 20, 2022 - - February 20, 2023 - - * - :ref:`1.10.3 LTS ` - - April 1, 2019 - - February 20, 2022 - - February 20, 2023 - - * - :ref:`1.10.2 LTS ` - - October 13, 2018 - - February 20, 2022 - - February 20, 2023 diff --git a/doc/release/enterprise-changelog.rst b/doc/release/enterprise-changelog.rst new file mode 100644 index 0000000000..03563636d3 --- /dev/null +++ b/doc/release/enterprise-changelog.rst @@ -0,0 +1,526 @@ +.. _release-enterprise-changelog: + +Enterprise SDK changelog +======================== + +Versioning policy +----------------- + +A :ref:`Tarantool Enterprise SDK ` version consists of two parts: + +.. code-block:: text + + -r + + +For example: ``2.11.1-0-gc42d9735b-r589``. + +- ``TARANTOOL_BASE_VERSION`` is the Community version which the Enterprise version is based on. +- ``REVISION`` is the SDK revision. Besides Tarantool itself, it includes the ``tt`` utility, a set of open and closed source modules, and examples. Learn more from :ref:`Package contents `. + +616 +--- + +- Updated crud to `1.4.3 `__. +- Updated luatest to `1.0.1 `__. +- Updated migrations to `0.7.0 `__. +- Updated tt-ee to `2.1.2 `__. + +613 +--- + +- Updated cartridge to `2.8.5 `__. +- Updated crud to `1.4.2 `__. +- Added frontend-core `8.2.2 `__. +- Updated membership to `2.4.2 `__. +- Updated sideservice to `0.2.0 `__. +- Updated tt-ee to `2.1.1 `__. +- Updated vshard to `0.1.26 `__. + +609 +--- + +- Updated httpgo to `0.2.1 `__. +- Added httpgo-crud `0.1.0 `__. +- Updated ``tarantool-2.11`` to 2.11.2. + +606 +--- + +- Updated ``tarantool-master`` to 3.0.0-beta1. + +605 +--- + +- Updated cartridge to `2.8.4 `__. +- Updated crud to `1.4.1 `__. +- Updated ddl to `1.6.5 `__. +- Added httpgo `0.2.0 `__. +- Updated tt-ee to `2.0.0 `__. + +598 +--- + +- Updated cartridge-cli to `2.12.9 `__. +- Updated tt-ee to `1.3.1 `__. + +595 +--- + +- Updated tt-ee to `1.3.0 `__. +- Updated cartridge to `2.8.3 `__. +- Updated cartridge-cli-extensions to `1.1.2 `__. +- Updated crud to `1.3.0 `__. +- Updated queue to `1.3.3 `__. +- Updated sharded-queue to `0.1.1 `__. +- Updated membership to `2.4.1 `__. +- Added tests for Astra Linux 1.7. + + +589 +--- + +- Updated ``tarantool-2.10`` to 2.10.8. +- Updated ``tarantool-master`` to 3.0.0-alpha3. +- Updated migrations to `0.6.0 `__. +- Updated tt-ee to `1.2.0 `__. +- Updated space-explorer to `1.1.8 `__. +- Updated cartridge-metrics-role to `0.1.1 `__. +- Updated cartridge to `2.8.2 `__. +- Updated expirationd to `1.5.0 `__. +- Added sideservice `0.1.0 `__. + +579 +--- + +- Updated cartridge-cli to `2.12.7 `__. +- Updated ``tarantool-2.11`` to 2.11.1. + +577 +--- + +- Added crud `1.2.0 `__. +- Added ddl `1.6.3 `__. +- Added sharded-queue `0.1.0 `__. +- Added ddl `1.6.4 `__. +- Updated tt-ee to `1.1.2 `__. +- Updated cartridge-cli to `2.12.6 `__. + +563 +--- + +- Updated ``tarantool-2.10`` to 2.10.7. +- Updated ``tarantool-2.11`` to 2.11.0. +- Added kafka `1.6.6 `__. +- Added vshard `0.1.24 `__. +- Added metrics `1.0.0 `__. +- Added cartridge-metrics-role `0.1.0 `__. +- Added cartridge `2.8.0 `__. +- Added http `1.5.0 `__. + +557 +--- + +- Added checks `3.3.0 `__. +- Updated cartridge-cli to `2.12.5 `__. + +553 +--- + +- Added ``tt-ee`` and ``tt`` environment configuration. +- Added crud `1.1.1 `__. +- Added avro-schema `3.1.1 `__. +- Added expirationd `1.4.0 `__. +- Added graphql `0.3.0 `__. +- Added graphqlapi `0.0.10 `__. +- Added metrics `0.17.0 `__. +- Added migrations `0.5.0 `__. +- Added oracle `1.4.0 `__. +- Added cartridge `2.7.9 `__. +- Added vshard `0.1.23 `__. +- Added kafka `1.6.5 `__. + +549 +--- + +- Updated ``tarantool-2.10`` to 2.10.6. + +545 +--- + +- Updated ``tarantool-2.11`` to 2.11.0-rc2. + +543 +--- + +- Added the ``tarantool-2.11`` submodule. + +542 +--- + +- Updated ``tarantool-1.10`` to 1.10.15. + +541 +--- + +- Updated ``tarantool-master`` to ``3.0.0-entrypoint``. + +540 +--- + +- Updated ``tarantool-2.10`` to 2.10.5. + +539 +--- + +- Added vshard `0.1.22 `__. + +538 +--- + +- Updated ``tarantool-2.8`` to apply 2 hotfixes. + +537 +--- + +- Fix non-interactive installation of the ``brew`` package. + +- Changed the owner of the ``/usr/local/bin`` directory. + +- Installed ``awscli@1`` instead of ``awscli`` since it takes much less + time. + +536 +--- + +- Added the missing property ``2.10`` for scope ``CACHE`` in CMakeLists.txt. + +535 +--- + +- Added expirationd `1.3.1 `__. + +534 +--- + +- Added crud `1.0.0 `__. + +533 +--- + +- Use runners with label ``regular`` for builds and the tagged release + workflow. + +532 +--- + +- Added http `1.4.0 `__. +- Added space-explorer `1.1.7 `__. +- Added checks `3.2.0 `__. +- Added metrics `0.16.0 `__. +- Added cartridge `2.7.8 `__. + +531 +--- + +- Added the ``-DENABLE_LTO=ON`` flag for tarantool-ee@master branch to + CMakeLists.txt + +530 +--- + +- Upgraded devtoolset from 8 to 9. It was required for upgrading ld from + 2.30 to 2.31+ for LTO. + + +529 +--- + +- Updated tarantool’s master branch to a recent revision. + +528 +--- + +- Fixed code style in the Linux and macOS workflows. + +527 +--- + +- Reliably install packages in macOS builds. + +526 +--- + +- Refactored the way that GC64 builds are defined in the build workflow. + There are no changes to the composition of resulting bundles. + +525 +--- + +- Added alerting failures in builds on stable branches and integration testing + to VK Teams chats. + +524 +--- + +- Updated to fresh tarantool master (``2.11.0-entrypoint-107-ga18449d``) + +523 +--- + +- Added cartridge `2.7.7 `__. + +522 +--- + +- Outdated workflow runs are now canceled to save CI time. + +521 +--- + +- Added crud `0.14.1 `__. +- Added expirationd `1.3.0 `__. +- Added metrics `0.15.1 `__. +- Added queue `1.2.2 `__. + +520 +--- + +Release SDK by tags: + +- Run workflow in SDK docker container. +- Upload SDK files for 1.10, 2.8, 2.10 versions to release folder. +- Add consistency check for all versions. + +519 +--- + +* On feature branches, SDK is now rebuilt only on relevant changes. + +r518 +---- + +* Added frontend core `8.2.1 `__. +* Added vshard `0.1.21 `__. +* Added http `1.3.0 `__. +* Added cartridge `2.7.6 `__. + +r517 +---- + +* Updated Tarantool EE to `2.10.4 `__. + +r516 +---- + +* Updated bundled OpenSSL to version 1.1.1q. + +r515 +---- + +* Removed support of Tarantool 2.7. +* Started using ``tarantool/actions/prepare-checkout`` to make builds more stable. + +r514 +---- + +* Remove the local registry and setup using GitHub registry. +* Sync rocks cache to s3 and back. +* Setup using shared runners. +* Refactor and format ``ci-linux.yml`` and ``ci-macos.yml``. + +r513 +---- + +* Removed kafka 1.5.0 due to a build issue with Tarantool 2.10.3 and higher. +* Updated kafka to version `1.6.2 `__. + +r512 +---- + +* Updated tuple-keydef to version `0.0.3 `__. + +r511 +---- + +* Enabled parallel build of rocks for macOS in CI. + +r510 +---- + +* Updated Tarantool to :doc:`2.10.3 `. +* Added a readable error for the case when the flight recoder fails + to write data due to insufficient free space on the disk device. + Previously, it was sending a `SIGBUS` error (:tarantool-ee-issue:`196`). +* Fixed a crash in the flight recorder caused by non-thread-safe log + recording from multiple threads (:tarantool-ee-issue:`226`). + +r502 +---- + +* Updated Tarantool to :doc:`2.10.2 `. +* Increased resolution of stored entries in flight recorder (:tarantool-ee-issue:`193`). +* Fixed a bug in the flight recorder that resulted in skipping log entries in case + ``box.cfg.log_level`` is less than ``flightrec_log_level`` (:tarantool-ee-issue:`201`). + +r498 +---- + +* Updated Tarantool to :doc:`2.10.1 `. +* Updated Cyrus SASL to version 2.1.28. +* Updated OpenLDAP to version 2.5.13. +* Updated LZ4 to version 1.9.3. Fixed `CVE-2021-3520 `__. +* Fixed replication reconnect failure after disabling SSL encryption (:tarantool-ee-issue:`137`). +* Fixed a crash that occurred while tyring to start an instance that has + a compressed memtx space (:tarantool-ee-issue:`171`). +* Fixed `CVE-2022-29242 `__ in GOST SSL engine. +* Fixed a bug in the flight recorder reader implementation that resulted in + a hang or error while trying to open an empty section (:tarantool-ee-issue:`187`). + +r467 +---- + +Breaking changes +~~~~~~~~~~~~~~~~ + +* Default audit log format was changed to CSV. + +Functionality added or changed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enterprise +^^^^^^^^^^ + +* Implemented user-defined audit events. Now it's possible to log custom + messages to the audit log from Lua (:tarantool-ee-issue:`65`). + +* **[Breaking change]** Switched the default audit log format to CSV. The + format can be switched back to JSON using the new ``box.cfg.audit_format`` + configuration option (:tarantool-ee-issue:`66`). + +* Implemented the audit log filter. Now, it's possible to enable logging only + for a subset of all audit events using the new ``box.cfg.audit_filter`` + configuration option (:tarantool-ee-issue:`67`). + +Core +^^^^ + +* Implement constraints and foreign keys. Now a user can create function constraints and foreign key relations + (:tarantool-issue:`6436`). +* Changed log level of some information messages from critical to info + (:tarantool-issue:`4675`). +* Added predefined system events: ``box.status``, ``box.id``, ``box.election`` + and ``box.schema`` (:tarantool-issue:`6260`). +* Introduced transaction isolation levels in Lua and IPROTO (:tarantool-issue:`6930`). + +Vinyl +^^^^^ + +* Disabled the deferred DELETE optimization in Vinyl to avoid possible + performance degradation of secondary index reads. Now, to enable the + optimization, one has to set the ``defer_deletes`` flag in space options + (:tarantool-issue:`4501`). + +Lua +^^^ + +* Added support of console autocompletion for net.box objects ``stream`` + and ``future`` (:tarantool-issue:`6305`). + +Datetime +^^^^^^^^ + +* Parse method to allow converting string literals in extended iso-8601 + or rfc3339 formats (:tarantool-issue:`6731`). +* The range of supported years has been extended in all parsers to cover + fully -5879610-06-22..5879611-07-11 (:tarantool-issue:`6731`). + +Build +^^^^^ + +* Added bundling of *GNU libunwind* to support backtrace feature on + *AARCH64* architecture and distributives that don't provide *libunwind* + package. +* Re-enabled backtrace feature for all *RHEL* distributions by default, except + for *AARCH64* architecture and ancient *GCC* versions, which lack compiler + features required for backtrace (gh-4611). + +Bugs fixed +~~~~~~~~~~ + +Enterprise +^^^^^^^^^^ + +* Disabled audit log unless explicitly configured (:tarantool-ee-issue:`39`). Before this change, + audit events were written to stderr if ``box.cfg.audit_log`` wasn't set. Now, + audit log is disabled in this case. +* Disabled audit logging of replicated events (:tarantool-ee-issue:`59`). Now, replicated events + (for example, user creation) are logged only on the origin, never on a + replica. + +Core +^^^^ + +* Banned DDL operations in space on_replace triggers, since they could lead + to a crash (:tarantool-issue:`6920`). +* Fixed a bug due to which all fibers created with ``fiber_attr_setstacksize()`` + leaked until the thread exit. Their stacks also leaked except when + ``fiber_set_joinable(..., true)`` was used. +* Fixed a crash in mvcc connected with secondary index conflict (:tarantool-issue:`6452`). +* Fixed a bug which resulted in wrong space count (:tarantool-issue:`6421`). +* Select in RO transaction now reads confirmed data, like a standalone (auotcommit) select does + (:tarantool-issue:`6452`). + +Replication +^^^^^^^^^^^ + +* Fixed potential obsolete data write in synchronious replication + due to race in accessing terms while disk write operation is in + progress and not yet completed. +* Fixed replicas failing to bootstrap when master is just re-started (:tarantool-issue:`6966`). + +Lua +^^^ + +* Fixed the behavior of tarantool console on SIGINT. Now Ctrl+C discards + the current input and prints the new prompt (:tarantool-issue:`2717`). + +Triggers +^^^^^^^^ + +* Fixed assertion or segfault when MP_EXT received via net.box (:tarantool-issue:`6766`). +* Now ROUND() properly support INTEGER and DECIMAL as the first + argument (:tarantool-issue:`6988`). + +Datetime +^^^^^^^^ + +* Intervals received after datetime arithmetic operations may be improperly + normalized if result was negative + + .. code-block:: tarantoolsession + + tarantool> date.now() - date.now() + --- + - -1.000026000 seconds + ... + + I.e. 2 immediately called ``date.now()`` produce very close values, whose + difference should be close to 0, not 1 second (gh-6882). + +Net.box +^^^^^^^ + +* Changed the type of the error returned by net.box on timeout + from ClientError to TimedOut (:tarantool-issue:`6144`). + +r457 +---- + +- Fixed some binary protocol encryption bugs. + +r455 +---- + +- Added :ref:`binary protocol encryption `. +- Added :ref:`tuple field compression `. \ No newline at end of file diff --git a/doc/release/eol_versions.rst b/doc/release/eol_versions.rst index 63b3c1bb43..c882477e80 100644 --- a/doc/release/eol_versions.rst +++ b/doc/release/eol_versions.rst @@ -1,14 +1,308 @@ +.. _release-eol-versions: EOL versions ============ -This page lists release notes for Tarantool versions that have reached -their end of life in accordance with the :doc:`release policy `. -See the :doc:`release calendar ` for more information. +This section contains information about Tarantool versions that have reached +their *end of life* in accordance with the :ref:`release-policy`. This +means that these versions don't receive updates and fixes anymore. However, we still +provide technical support for certain time after a version's EOL. The current support +status is reflected by the **End of support** column of the table below. + +For information about major changes between EOL versions, see :ref:`release-eol-major-features`. + +.. note:: + + Before 2.10.0, version numbers were subject to the :doc:`legacy versioning policy `. + +.. container:: table + + .. list-table:: + :header-rows: 1 + + * - Version + - Release date + - End of life + - End of support + + * - `3.1.2 `_ + - August 26, 2024 + - August 26, 2024 + - August 26, 2024 + + * - `3.1.1 `_ + - July 31, 2024 + - August 26, 2024 + - August 26, 2024 + + * - `3.1.0 `_ + - April 16, 2024 + - August 26, 2024 + - August 26, 2024 + + * - `3.0.2 `_ + - April 16, 2024 + - April 17, 2024 + - April 17, 2024 + + * - `3.0.1 `_ + - January 25, 2024 + - April 17, 2024 + - April 17, 2024 + + * - `3.0.0 `_ + - December 26, 2023 + - April 17, 2024 + - April 17, 2024 + + * - `2.11.7 LTS `_ + - May 29, 2025 + - May 24, 2025 + - Not planned yet + + * - `2.11.6 LTS `_ + - February 24, 2025 + - May 24, 2025 + - Not planned yet + + * - `2.11.5 LTS `_ + - November 22, 2024 + - May 24, 2025 + - Not planned yet + + * - `2.11.4 LTS `_ + - August 16, 2024 + - May 24, 2025 + - Not planned yet + + * - `2.11.3 LTS `_ + - April 18, 2024 + - May 24, 2025 + - Not planned yet + + * - `2.11.2 LTS `_ + - December 7, 2023 + - May 24, 2025 + - Not planned yet + + * - `2.11.1 LTS `_ + - August 17, 2023 + - May 24, 2025 + - Not planned yet + + * - `2.11.0 LTS `_ + - May 24, 2023 + - May 24, 2025 + - Not planned yet + + * - :doc:`2.10.8 ` + - September 14, 2023 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.7 ` + - May 24, 2023 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.6 ` + - March 22, 2023 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.5 ` + - February 20, 2023 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.4 ` + - November 11, 2022 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.3 ` + - September 30, 2022 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.2 ` + - September 1, 2022 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.1 ` + - August 8, 2022 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.10.0 ` + - May 22, 2022 + - September 14, 2023 + - December 31, 2025 + + * - :doc:`2.8.4 ` + - April 25, 2022 + - April 25, 2022 + - December 31, 2024 + + * - :doc:`2.8.3 ` + - December 22, 2021 + - April 25, 2022 + - December 31, 2024 + + * - :doc:`2.8.2 ` + - August 19, 2021 + - April 25, 2022 + - December 31, 2024 + + * - :doc:`2.7.3 ` + - August 19, 2021 + - August 19, 2021 + - August 19, 2021 + + * - :doc:`2.7.2 ` + - April 21, 2021 + - August 19, 2021 + - August 19, 2021 + + * - :doc:`2.6.3 ` + - April 21, 2021 + - April 21, 2021 + - April 21, 2021 + + * - :doc:`2.6.2 ` + - December 30, 2020 + - April 21, 2021 + - April 21, 2021 + + * - :doc:`2.5.3 ` + - December 30, 2020 + - December 30, 2020 + - December 30, 2020 + + * - :doc:`2.5.2 ` + - October 22, 2020 + - December 30, 2020 + - December 30, 2020 + + * - :doc:`2.4.3 ` + - October 22, 2020 + - October 22, 2020 + - October 22, 2020 + + * - :doc:`2.4.2 ` + - July 17, 2020 + - October 22, 2020 + - October 22, 2020 + + * - :doc:`2.3.3 ` + - July 17, 2020 + - July 17, 2020 + - July 17, 2020 + + * - :doc:`2.3.2 ` + - April 20, 2020 + - July 17, 2020 + - July 17, 2020 + + * - :doc:`2.2.3 ` + - April 20, 2020 + - April 20, 2020 + - April 20, 2020 + + * - :doc:`2.2.2 ` + - December 31, 2019 + - April 20, 2020 + - April 20, 2020 + + * - :doc:`1.10.15 LTS ` + - February 20, 2023 + - February 20, 2023 + - February, 2024 + + * - :doc:`1.10.14 LTS ` + - August 8, 2022 + - February 20, 2023 + - February, 2024 + + * - :doc:`1.10.13 LTS ` + - April 25, 2022 + - February 20, 2023 + - February, 2024 + + * - :doc:`1.10.12 LTS ` + - December 22, 2021 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.11 LTS ` + - August 19, 2021 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.10 LTS ` + - April 24, 2021 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.9 LTS ` + - December 30, 2020 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.8 LTS ` + - October 22, 2020 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.7 LTS ` + - July 17, 2020 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.6 LTS ` + - April 20, 2020 + - February 20, 2022 + - February 20, 2023 + + * - :doc:`1.10.5 LTS ` + - January 14, 2020 + - February 20, 2022 + - February 20, 2023 + + * - :ref:`1.10.4 LTS ` + - September 26, 2019 + - February 20, 2022 + - February 20, 2023 + + * - :ref:`1.10.3 LTS ` + - April 1, 2019 + - February 20, 2022 + - February 20, 2023 + + * - :ref:`1.10.2 LTS ` + - October 13, 2018 + - February 20, 2022 + - February 20, 2023 .. toctree:: - :maxdepth: 1 + :hidden: + major-features + legacy-policy + 3.1.2 + 3.1.1 + 3.1.0 + 3.0.2 + 3.0.1 + 3.0.0 + 2.11.7 + 2.11.6 + 2.11.5 + 2.11.4 + 2.11.3 + 2.11.2 + 2.11.1 2.10.8 2.10.7 2.10.6 diff --git a/doc/release/index.rst b/doc/release/index.rst index 39fb421ace..8e4fcd5740 100644 --- a/doc/release/index.rst +++ b/doc/release/index.rst @@ -6,29 +6,134 @@ Releases ======== -This section contains release notes for all Tarantool versions, starting from 1.6 up to the latest. +This section contains information about Tarantool releases: release notes, lifecycle +information, release policy, and other documents. To download Tarantool releases, check the `Download `_ page. -Since version 2.10, a :doc:`new release policy for Tarantool ` has been introduced. +All currently supported versions are listed on this page :ref:`below `. +The information about earlier versions is provided in :ref:`release-eol-versions`. -Backwards compatibility is guaranteed between all versions in the same :term:`release series`. +The Enterprise Edition of Tarantool is distributed in the form of an SDK that has +its own versioning. See the :ref:`release-enterprise-changelog` to learn about +SDK version numbering and changes. + +The detailed information about Tarantool version numbering and release lifecycle +is available in :ref:`release-policy`. + +Backward compatibility is guaranteed between all versions in the same :term:`release series`. It is also appreciated but not guaranteed between different release series (major number changes). To learn more, read the :doc:`Compatibility guarantees ` article. -.. toctree:: - :maxdepth: 2 +.. _release-supported-versions: + +Supported versions +------------------ + +Every Tarantool release series has :ref:`the same lifecycle ` +defined by the release policy. The following diagram visualizes the lifecycle of currently +supported Tarantool versions: + +.. image:: _images/releases_calendar.svg + :align: center + :alt: Release calendar + +The table below provides information about supported versions with links to their +*What's new* pages in the documentation and detailed changelogs on GitHub. +For information about earlier versions, see :doc:`eol_versions`. + +.. note:: + + *End of life* (*EOL*) means the release series will no longer receive any patches, + updates, or feature improvements after the specified date. Versions that haven't + reached their end of life yet are shown in **bold**. + + *End of support* (*EOS*) means that we won't provide technical support to product + versions after the specified date. + +.. container:: table - calendar - major-features + .. list-table:: + :header-rows: 1 + + * - Series + - First release date + - End of life + - End of support + - Versions + + * - :doc:`3.4 ` + - **April 14, 2025** + - **April 14, 2027** + - **Not planned yet** + - | :tarantool-release:`3.4.0` + + * - :doc:`3.3 ` + - **November 29, 2024** + - **November 29, 2026** + - **Not planned yet** + - | :tarantool-release:`3.3.1` + | :tarantool-release:`3.3.0` + + * - :doc:`3.2 ` + - **August 26, 2024** + - **August 26, 2026** + - **Not planned yet** + - | :tarantool-release:`3.2.1` + | :tarantool-release:`3.2.0` + + * - :doc:`3.1 ` + - April 16, 2024 + - August 26, 2024 + - August 26, 2024 + - | :tarantool-release:`3.1.2` + | :tarantool-release:`3.1.1` + | :tarantool-release:`3.1.0` + + * - :doc:`3.0 ` + - December 26, 2023 + - April 17, 2024 + - April 17, 2024 + - | :tarantool-release:`3.0.2` + | :tarantool-release:`3.0.1` + | :tarantool-release:`3.0.0` + + * - :doc:`2.11 LTS ` + - May 24, 2023 + - May 24, 2025 + - Not planned yet + - | :tarantool-release:`2.11.7` + | :tarantool-release:`2.11.6` + | :tarantool-release:`2.11.5` + | :tarantool-release:`2.11.4` + | :tarantool-release:`2.11.3` + | :tarantool-release:`2.11.2` + | :tarantool-release:`2.11.1` + | :tarantool-release:`2.11.0` + + * - 2.10 + - May 22, 2022 + - September 14, 2023 + - December 31, 2025 + - | :doc:`2.10.8 ` + | :doc:`2.10.7 ` + | :doc:`2.10.6 ` + | :doc:`2.10.5 ` + | :doc:`2.10.4 ` + | :doc:`2.10.3 ` + | :doc:`2.10.2 ` + | :doc:`2.10.1 ` + | :doc:`2.10.0 ` .. toctree:: :maxdepth: 1 + 3.4.0 + 3.3.0 + 3.2.0 + 3.1.0 + 3.0.0 2.11.0 eol_versions - -.. toctree:: - :maxdepth: 2 - - policy_index + enterprise-changelog + policy compatibility diff --git a/doc/release/legacy-policy.rst b/doc/release/legacy-policy.rst index dbb7078bb3..44e64cd6fd 100644 --- a/doc/release/legacy-policy.rst +++ b/doc/release/legacy-policy.rst @@ -1,6 +1,11 @@ Tarantool legacy release policy =============================== +.. important:: + + This page describes the release policy that was used for Tarantool versions **before 2.10.0**. + + For information about the current release policy, see :ref:`release-policy`. A Tarantool release is identified by three digits, for example, 2.6.2 or 1.10.9: diff --git a/doc/release/major-features.rst b/doc/release/major-features.rst index 3b51c0ac92..2762171abf 100644 --- a/doc/release/major-features.rst +++ b/doc/release/major-features.rst @@ -1,10 +1,19 @@ +.. _release-eol-major-features: + Major features ============== +.. important:: + + This page is no longer maintained. + + The table below lists major changes in Tarantool versions **up to 2.11.0**. + For overviews of changes in newer versions, see their *What's new* pages inside :ref:`release`. + Every released version of Tarantool brings some notable features and fixes, which are all listed in the :doc:`release notes `. -To keep track of the major features in each version of the Tarantool easier, you can use the table below. +To keep track of the major features in Tarantool versions, you can use the table below. Later versions inherit features from earlier ones in the same release series. Note that versions before 2.10.* are numbered according to the :doc:`legacy release policy `, diff --git a/doc/release/policy.rst b/doc/release/policy.rst index 86c97b088c..7da2942338 100644 --- a/doc/release/policy.rst +++ b/doc/release/policy.rst @@ -1,24 +1,24 @@ +.. _release-policy: + Tarantool release policy ======================== -.. _release-policy: - Summary ------- -The Tarantool release policy is changing to become more clear and intuitive. -The new policy uses a `SemVer-like `__ versioning format, -and introduces a new version lifecycle with more long-time support series. -This document explains the new release policy, versioning rules, and :term:`release series` lifecycle. +The Tarantool release policy is constantly changing to become more clear and intuitive. +The stated policy uses a `SemVer-like `__ versioning format, +and upholds version lifecycle with more long-time support series. +This document explains the Tarantool release policy, versioning rules, and :term:`release series` lifecycle. -The new release policy replaces :doc:`the legacy policy ` +The stated release policy replaces :doc:`the legacy policy ` for: * The ``2.x.y`` series since the ``2.10.0`` release. - Development for this new release starts with version ``2.10.0-beta1``. -* The future ``3.0.0`` series. + Development for this release starts with version ``2.10.0-beta1``. +* The ``3.0.0`` series. -Here are the most significant changes from the legacy release policy: +Here are the most significant changes from the previously supported legacy release policy: * The third number in the version label doesn't distinguish between pre-release (alpha and beta) and release versions. @@ -29,7 +29,7 @@ Here are the most significant changes from the legacy release policy: while ``2.x.y`` had stable releases, but wasn't an LTS series. Now both series are long-term supported. -The topics below describe the new versioning policy in more detail. +The topics below describe the versioning policy in more detail. Versioning policy ----------------- @@ -37,7 +37,7 @@ Versioning policy Release series and versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The new Tarantool release policy is based on having several release series, +The Tarantool release policy is based on having several release series, each with its own lifecycle, pre-release and release versions. .. glossary:: @@ -49,8 +49,6 @@ each with its own lifecycle, pre-release and release versions. A series has a distinct lifecycle and certain compatibility guarantees within itself and with other series. The intended support time for each series is at least two years since the first release. - At the moment when this document is published, there are two release series: series ``1.10`` and series ``2``. - Release version Release version is a Tarantool distribution which is thoroughly tested and ready for production usage. @@ -267,6 +265,15 @@ that reaches EOL. A release series cannot reach EOL until the vast majority of production environments, for which we have commitments and SLAs, is updated to a newer series. +End of support +~~~~~~~~~~~~~~~~~ + +The end of support (EOS) date is later in time than the EOL date. When the series +reaches EOS, the Tarantool team ceases its technical support and does not comply with support- +related inquiries. + +It is recommended that the customers follow the :ref:`calendar ` +and plan for updates of their Tarantool version before the EOS date. Versions per lifecycle stage ---------------------------- @@ -353,5 +360,4 @@ No new versions are released since then. .. note:: - See all currently supported Tarantool versions visualised as :doc:`a calendar ` - or as :ref:`a release lifetime table `. + See all currently supported Tarantool versions in :doc:`Releases `. diff --git a/doc/release/policy_index.rst b/doc/release/policy_index.rst deleted file mode 100644 index f504ecbff2..0000000000 --- a/doc/release/policy_index.rst +++ /dev/null @@ -1,28 +0,0 @@ -Release policies -================ - -Since version 2.10, there's a :doc:`new release policy for Tarantool `. -In short, Tarantool version numbers consist of three parts: - -.. code-block:: text - - MAJOR.MINOR.PATCH - -Any version without extra prefixes is a release version. -If you need a version for production use, pick the latest release. -For evaluation and development, you can use beta versions. -They are marked with ``-betaN`` suffixes. - -Before 2.10.0, version numbers were subject to the -:doc:`legacy versioning policy `: - -.. code-block:: text - - MAJOR_VERSION.RELEASE_SERIES.RELEASE - -.. toctree:: - :hidden: - :maxdepth: 2 - - policy - legacy-policy diff --git a/doc/toctree.rst b/doc/toctree.rst index 353ccd2047..6a05a11cff 100644 --- a/doc/toctree.rst +++ b/doc/toctree.rst @@ -7,13 +7,10 @@ overview getting_started/index - how-to/index - concepts/index - CRUD operations - Cluster on Cartridge - book/admin/index - book/connectors - enterprise/index + platform/index + tooling/index + admin/index + connector/index reference/index release/index contributing/index diff --git a/doc/tooling/index.rst b/doc/tooling/index.rst new file mode 100644 index 0000000000..218586f315 --- /dev/null +++ b/doc/tooling/index.rst @@ -0,0 +1,15 @@ +Tooling +======= + +This section describes the tools that enable developers and administrators +to work with Tarantool. + +.. toctree:: + :maxdepth: 1 + + tt_cli/index + tcm/index + interactive_console + luajit_memprof + luajit_sysprof + luajit_getmetrics diff --git a/doc/reference/tooling/interactive_console.rst b/doc/tooling/interactive_console.rst similarity index 100% rename from doc/reference/tooling/interactive_console.rst rename to doc/tooling/interactive_console.rst diff --git a/doc/reference/tooling/luajit_getmetrics.rst b/doc/tooling/luajit_getmetrics.rst similarity index 100% rename from doc/reference/tooling/luajit_getmetrics.rst rename to doc/tooling/luajit_getmetrics.rst diff --git a/doc/reference/tooling/luajit_memprof.rst b/doc/tooling/luajit_memprof.rst similarity index 79% rename from doc/reference/tooling/luajit_memprof.rst rename to doc/tooling/luajit_memprof.rst index 87a793e9f5..cb8e76601b 100644 --- a/doc/reference/tooling/luajit_memprof.rst +++ b/doc/tooling/luajit_memprof.rst @@ -3,11 +3,13 @@ LuaJIT memory profiler ====================== -Starting from version :doc:`2.7.1 `, Tarantool +Since version :doc:`2.7.1 `, Tarantool has a built‑in module called ``misc.memprof`` that implements a LuaJIT memory -profiler (which we will just call *the profiler* in this section). The profiler provides -a memory allocation report that helps analyze Lua code and find the places -that put the most pressure on the Lua garbage collector (GC). +profiler (further in this section we call it *the profiler* for short). +The profiler provides a memory allocation report that helps analyze Lua code +and find the places that put the most pressure on the Lua garbage collector (GC). + +Inside this section: .. contents:: :local: @@ -18,7 +20,7 @@ that put the most pressure on the Lua garbage collector (GC). Working with the profiler ------------------------- -Usage of the profiler involves two steps: +The profiler usage involves two steps: 1. :ref:`Collecting ` a binary profile of allocations, reallocations, and deallocations in memory related to Lua @@ -28,13 +30,13 @@ Usage of the profiler involves two steps: .. _profiler_usage_get: -Collecting binary profile -~~~~~~~~~~~~~~~~~~~~~~~~~ +Collecting a binary profile +~~~~~~~~~~~~~~~~~~~~~~~~~~~ To collect a binary profile for a particular part of the Lua code, you need to place this part between two ``misc.memprof`` functions, namely, ``misc.memprof.start()`` and ``misc.memprof.stop()``, and then execute -the code under Tarantool. +the code in Tarantool. Below is a chunk of Lua code named ``test.lua`` to illustrate this. @@ -43,26 +45,26 @@ Below is a chunk of Lua code named ``test.lua`` to illustrate this. .. code-block:: lua :linenos: - -- Prevent allocations on traces. - jit.off() - local str, err = misc.memprof.start("memprof_new.bin") - -- Lua doesn't create a new frame to call string.rep, and all allocations - -- are attributed not to the append() function but to the parent scope. - local function append(str, rep) - return string.rep(str, rep) - end + -- Prevent allocations on traces. + jit.off() + local str, err = misc.memprof.start("memprof_new.bin") + -- Lua doesn't create a new frame to call string.rep, and all allocations + -- are attributed not to the append() function but to the parent scope. + local function append(str, rep) + return string.rep(str, rep) + end - local t = {} - for i = 1, 1e4 do - -- table.insert is the built-in function and all corresponding - -- allocations are reported in the scope of the main chunk. - table.insert(t, - append('q', i) - ) - end - local stp, err = misc.memprof.stop() + local t = {} + for i = 1, 1e4 do + -- table.insert is the built-in function and all corresponding + -- allocations are reported in the scope of the main chunk. + table.insert(t, + append('q', i) + ) + end + local str, err = misc.memprof.stop() -The Lua code for starting the profiler -- as in line 3 in the test.lua example above -- is: +The Lua code for starting the profiler -- as in line 3 in the ``test.lua`` example above -- is: .. code-block:: lua @@ -75,27 +77,29 @@ for example if it is not possible to open a file for writing or if the profiler ``misc.memprof.start()`` returns ``nil`` as the first result, an error-message string as the second result, and a system-dependent error code number as the third result. + If the operation succeeds, ``misc.memprof.start()`` returns ``true``. -The Lua code for stopping the profiler -- as in line 18 in the test.lua example above -- is: +The Lua code for stopping the profiler -- as in line 18 in the ``test.lua`` example above -- is: .. code-block:: lua - local stp, err = misc.memprof.stop() + local str, err = misc.memprof.stop() If the operation fails, -for example if there is an error when the file descriptor is being closed +for example if there is an error when the file descriptor is being closed or if there is a failure during reporting, ``misc.memprof.stop()`` returns ``nil`` as the first result, an error-message string as the second result, and a system-dependent error code number as the third result. + If the operation succeeds, ``misc.memprof.stop()`` returns ``true``. .. _profiler_usage_generate: To generate the file with memory profile in binary format (in the :ref:`test.lua code example above ` -the file name is ``memprof_new.bin``), execute the code under Tarantool: +the file name is ``memprof_new.bin``), execute the code in Tarantool: .. code-block:: console @@ -115,7 +119,7 @@ a profiling report: :ref:`note about jitoff ` for more details. * Lines 6-8: Tail call optimization doesn't create a new call frame, so all - allocations inside the function called via the ``CALLT/CALLMT`` `bytecodes `_ + allocations inside the function called via the ``CALLT/CALLMT`` `bytecodes `_ are attributed to the function's caller. See also the comments preceding these lines. * Lines 14-16: Usually the information about allocations inside Lua built‑ins @@ -127,8 +131,8 @@ a profiling report: .. _profiler_usage_parse: -Parsing binary profile and generating profiling report -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Parsing a binary profile and generating a profiling report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _profiler_usage_parse_command: @@ -143,8 +147,11 @@ via Tarantool by using the following command where ``memprof_new.bin`` is the binary profile :ref:`generated earlier ` by ``tarantool test.lua``. -(Warning: there is a slight behavior change here, the ``tarantool -e ...`` -command was slightly different in Tarantool versions prior to Tarantool 2.8.1.) + +.. note:: + + There is a slight behavior change here: the ``tarantool -e ...`` command + was slightly different in Tarantool versions prior to Tarantool 2.8.1. Tarantool generates a profiling report and displays it on the console before closing the session: @@ -187,7 +194,6 @@ the session: On macOS, a report will be different for the same chunk of code because Tarantool and LuaJIT are built with the GC64 mode enabled for macOS. - Let's examine the report structure. A report has four sections: * ALLOCATIONS @@ -203,21 +209,20 @@ An event record has the following format: .. code-block:: text @:: events + bytes - bytes - +where: -* —a name of the file containing Lua code. -* —the line number where the event is detected. -* —a number of events for this code line. -* + bytes—amount of memory allocated during all the events on this line. -* - bytes—amount of memory freed during all the events on this line. +* ```` -— a name of the file containing Lua code. +* ```` -— the line number where the event is detected. +* ```` —- a number of events for this code line. +* ``+ bytes`` —- amount of memory allocated during all the events on this line. +* ``- bytes`` —- amount of memory freed during all the events on this line. The ``Overrides`` label shows what allocation has been overridden. See the :ref:`test.lua chunk above ` with the explanation in the comments for some examples. - .. _profiler_usage_internal_jitoff: The ``INTERNAL`` label indicates that this event is caused by internal LuaJIT @@ -256,10 +261,10 @@ structures. As for investigating the Lua code with the help of profiling reports, it is always code-dependent and there can't be hundred per cent definite recommendations in this regard. Nevertheless, you can see some of the things -in the :ref:`Profiling report analysis example ` later. +in the :ref:`Profiling a report analysis example ` later. Also, below is the :ref:`FAQ ` section with the questions that -most probably can arise while using profiler. +most probably can arise while using the profiler. .. _profiler_faq: @@ -317,44 +322,44 @@ console for a running instance. .. code-block:: lua :linenos: - local fiber = require "fiber" - local log = require "log" + local fiber = require "fiber" + local log = require "log" - fiber.create(function() - fiber.name("memprof") + fiber.create(function() + fiber.name("memprof") - collectgarbage() -- Collect all objects already dead - log.warn("start of profile") + collectgarbage() -- Collect all objects already dead + log.warn("start of profile") - local st, err = misc.memprof.start(FILENAME) - if not st then - log.error("failed to start profiler: %s", err) - end + local st, err = misc.memprof.start(FILENAME) + if not st then + log.error("failed to start profiler: %s", err) + end - fiber.sleep(TIME) + fiber.sleep(TIME) - collectgarbage() - st, err = misc.memprof.stop() + collectgarbage() + st, err = misc.memprof.stop() - if not st then - log.error("profiler on stop error: %s", err) - end + if not st then + log.error("profiler on stop error: %s", err) + end - log.warn("end of profile") - end) + log.warn("end of profile") + end) -where +where: -* ``FILENAME``—the name of the binary file where profiling events are written -* ``TIME``—duration of profiling, in seconds. +* ``FILENAME``—the name of the binary file where profiling events are written +* ``TIME``—duration of profiling, in seconds. Also, you can directly call ``misc.memprof.start()`` and ``misc.memprof.stop()`` from a console. .. _profiler_analysis: -Profiling report analysis example ---------------------------------- +Profiling a report analysis example +----------------------------------- In the example below, the following Lua code named ``format_concat.lua`` is investigated with the help of the memory profiler reports. @@ -364,39 +369,39 @@ investigated with the help of the memory profiler reports. .. code-block:: lua :linenos: - -- Prevent allocations on new traces. - jit.off() + -- Prevent allocations on new traces. + jit.off() - local function concat(a) - local nstr = a.."a" - return nstr - end + local function concat(a) + local nstr = a.."a" + return nstr + end - local function format(a) - local nstr = string.format("%sa", a) - return nstr - end + local function format(a) + local nstr = string.format("%sa", a) + return nstr + end - collectgarbage() + collectgarbage() - local binfile = "/tmp/memprof_"..(arg[0]):match("([^/]*).lua")..".bin" + local binfile = "/tmp/memprof_"..(arg[0]):match("([^/]*).lua")..".bin" - local st, err = misc.memprof.start(binfile) - assert(st, err) + local st, err = misc.memprof.start(binfile) + assert(st, err) - -- Payload. - for i = 1, 10000 do - local f = format(i) - local c = concat(i) - end - collectgarbage() + -- Payload. + for i = 1, 10000 do + local f = format(i) + local c = concat(i) + end + collectgarbage() - local st, err = misc.memprof.stop() - assert(st, err) + local st, err = misc.memprof.stop() + assert(st, err) - os.exit() + os.exit() -When you run this code :ref:`under Tarantool ` and +When you run this code :ref:`in Tarantool ` and then :ref:`parse ` the binary memory profile in /tmp/memprof_format_concat.bin, you will get the following profiling report: @@ -423,9 +428,9 @@ you will get the following profiling report: Reasonable questions regarding the report can be: -* Why are there no allocations related to the ``concat()`` function? -* Why is the number of allocations not a round number? -* Why are there about 20K allocations instead of 10K? +* Why are there no allocations related to the ``concat()`` function? +* Why is the number of allocations not a round number? +* Why are there about 20K allocations instead of 10K? First of all, LuaJIT doesn't create a new string if the string with the same payload exists (see details on `lua-users.org/wiki `_). @@ -469,8 +474,8 @@ To profile only the ``concat()`` function, comment out line 23 (which is **Q**: But what will change if JIT compilation is enabled? **A**: In the :ref:`code `, comment out line 2 (which is -``jit.off()``) and run -the profiler . Now there are only 56 allocations in the report, and all other +``jit.off()``) and run the profiler. +Now there are only 56 allocations in the report, and all the other allocations are JIT-related (see also the related `dev issue `_): @@ -494,8 +499,6 @@ allocations are JIT-related (see also the related @format_concat.lua:0 holds 640 bytes: 4 allocs, 0 frees INTERNAL holds 360 bytes: 2 allocs, 1 frees - - This happens because a trace has been compiled after 56 iterations (the default value of the ``hotloop`` compiler parameter). Then, the JIT-compiler removed the unused variable ``c`` from the trace, and, therefore, @@ -538,7 +541,7 @@ identifier is not yet compiled via LuaJIT. So, a trace can't be recorded and the compiler doesn't perform the corresponding optimizations. If we change the ``format()`` function in lines 9-12 of the -:ref:`Profiling report analysis example ` +:ref:`Profiling a report analysis example ` in the following way .. code-block:: lua @@ -594,4 +597,4 @@ for example $ tarantool -e 'require("memprof")(arg)' - --leak-only memprof_new.bin -When `--leak-only`` is used, only the HEAP SUMMARY section is displayed. +When ``--leak-only`` is used, only the HEAP SUMMARY section is displayed. diff --git a/doc/tooling/luajit_sysprof.rst b/doc/tooling/luajit_sysprof.rst new file mode 100644 index 0000000000..495581f9e3 --- /dev/null +++ b/doc/tooling/luajit_sysprof.rst @@ -0,0 +1,370 @@ +.. _luajit_sysprof: + +LuaJIT platform profiler +======================== + +The default profiling options for LuaJIT are not fine enough to +get an understanding of performance. For example, ``perf`` is only +able to show the host stack, so all the Lua calls are displayed as a single +``pcall()``. Oppositely, the ``jit.p`` module provided with LuaJIT +is not able to give any information about the host stack. + +Since version :doc:`2.10.0 `, Tarantool +has a built‑in module called ``misc.sysprof`` that implements a +LuaJIT sampling profiler (further in this section we call it *the profiler* +for short). The profiler can capture both guest and +host stacks simultaneously, along with virtual machine states, so +it can show the whole picture. + +Three profiling modes are available: + +* **Default**: shows only virtual machine state counters. +* **Leaf**: shows the last frame on the stack. +* **Callchain**: performs a complete stack dump. + +The profiler comes with a default parser, which produces output in +a ``flamegraph.pl``-suitable format. + +Inside this section: + +.. contents:: + :local: + :depth: 2 + +.. _profiler_usage: + +Working with the profiler +------------------------- + +The profiler usage involves two steps: + +1. :ref:`Collecting ` a binary profile of + stacks (further referred as *binary sampling profile* or *binary profile* + for short). +2. :ref:`Parsing ` the collected binary + profile to get a human-readable profiling report. + +.. _profiler_usage_get: + +Collecting a binary profile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To collect a binary profile for a particular part of the Lua and C code, +you need to place this part between two ``misc.sysprof`` functions -- +namely, ``misc.sysprof.start()`` and ``misc.sysprof.stop()`` -- and +then execute the code in Tarantool. + +Below is a chunk of Lua code named ``test.lua`` to illustrate this. + +.. _profiler_usage_example01: + +.. code-block:: lua + :linenos: + + local function payload() + local function fib(n) + if n <= 1 then + return n + end + return fib(n - 1) + fib(n - 2) + end + return fib(32) + end + + payload() + + local res, err = misc.sysprof.start({mode = 'C', interval = 1, path = 'sysprof.bin'}) + assert(res, err) + + payload() + + res, err = misc.sysprof.stop() + assert(res, err) + +The Lua code for starting the profiler -- as in line 1 in the +``test.lua`` example above -- is: + +.. code-block:: lua + + local str, err = misc.sysprof.start({mode = 'C', interval = 1, path = 'sysprof.bin'}) + +where: + +* ``mode`` is a profiling mode; +* ``interval`` is a sampling interval; +* ``sysprof.bin`` is the name of the binary file where profiling events are written. + +If the operation fails, for example if it is not possible to open +a file for writing or if the profiler is already running, +``misc.sysprof.start()`` returns ``nil`` as the first result, +an error-message string as the second result, +and a system-dependent error code number as the third result. + +If the operation succeeds, ``misc.sysprof.start()`` returns ``true``. + +The Lua code for stopping the profiler -- as in line 15 in the +``test.lua`` example above -- is: + +.. code-block:: lua + + local res, err = misc.sysprof.stop() + +If the operation fails, for example if there is an error when the +file descriptor is being closed or if there is a failure during +reporting, ``misc.sysprof.stop()`` returns ``nil`` as the first +result, an error-message string as the second result, +and a system-dependent error code number as the third result. + +If the operation succeeds, ``misc.sysprof.stop()`` returns ``true``. + +.. _profiler_usage_generate: + +To generate a file with the memory profile in the binary format +(in the :ref:`test.lua code example above ` +the file name is ``sysprof.bin``), execute the code in Tarantool: + +.. code-block:: console + + $ tarantool test.lua + +Tarantool collects allocation events in ``sysprof.bin``, puts +the file in its :ref:`working directory `, +and closes the session. + +.. _profiler_usage_parse: + +Parsing a binary profile and generating a profiling report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _profiler_usage_parse_command: + +After getting the platform profile in the binary format, the next step is +to parse it to get a human-readable profiling report. You can do this +via Tarantool with the following command +(mind the hyphen ``-`` before the filename): + +.. code-block:: console + + $ tarantool -e 'require("sysprof")(arg)' - sysprof.bin > tmp + $ curl -O https://raw.githubusercontent.com/brendangregg/FlameGraph/refs/heads/master/flamegraph.pl + $ perl flamegraph.pl tmp > sysprof.svg + +where ``sysprof.bin`` is the binary profile +:ref:`generated earlier ` by ``tarantool test.lua``. + +.. note:: + + There is a slight behavior change here: the ``tarantool -e ...`` command + was slightly different in Tarantool versions prior to Tarantool 2.8.1. + The resulting SVG image contains a flamegraph with collected stacks + and can be opened by a modern web-browser for analysis. + +As for investigating the Lua code with the help of profiling reports, +it is always code-dependent and there are no definite recommendations +in this regard. Nevertheless, you can see some of the things +in the :ref:`Profiling report analysis example ` below. + +.. _profiler_lua_api: + +Profiler Lua API +---------------- + +The platform profiler provides a Lua interface: + +* ``misc.sysprof.start(opts)`` +* ``misc.sysprof.stop()`` +* ``misc.sysprof.report()`` + +The first two functions return boolean ``res`` and ``err``, which is +``nil`` on success and contains an error message on failure. + +``misc.sysprof.report`` returns a Lua table containing the +following counters: + +.. code-block:: console + + { + "samples" = int, + "INTERP" = int, + "LFUNC" = int, + "FFUNC" = int, + "CFUNC" = int, + "GC" = int, + "EXIT" = int, + "RECORD" = int, + "OPT" = int, + "ASM" = int, + "TRACE" = int + } + +The ``opts`` argument of ``misc.sysprof.start`` can contain the +following parameters: + +* ``mode`` (required) -- one of the supported profiling modes: + + * ``'D'`` = DEFAULT + * ``'L'`` = LEAF + * ``'C'`` = CALLGRAPH + +* ``interval`` (optional) -- sampling interval in msec (default is 10 msec). +* ``path`` (optional) -- path to a file to store profile data + (default is ``sysprof.bin``). + +.. _profiler_c_api: + +Profiler C API +-------------- + +The platform profiler provides a low-level C interface: + +* ``int luaM_sysprof_set_writer(sp_writer writer)`` -- sets a writer function + for sysprof. + +* ``int luaM_sysprof_set_on_stop(sp_on_stop on_stop)`` -- sets + an on-stop callback for ``sysprof`` to clear resources. + +* ``int luaM_sysprof_set_backtracer(sp_backtracer backtracer)`` -- sets + a backtracing function. If the ``backtracer`` argument is NULL, + the default backtracer is set. + +.. note:: + + There is no need to call the configuration functions multiple times + if you are starting and stopping the profiler several times + in a single program. + + Also, it is not necessary to configure ``sysprof`` for the ``Default`` mode. + However, you MUST configure it for other modes. + +* ``int luaM_sysprof_start(lua_State *L, const struct luam_Sysprof_Options *opt)`` -- + see :ref:`Profiler options `. + +* ``int luaM_sysprof_stop(lua_State *L)`` + +* ``int luaM_sysprof_report(struct luam_Sysprof_Counters *counters)`` -- writes + :ref:`profiling counters ` for each vmstate. + +All of the functions return 0 on success and an error code on failure. + +.. _profiler_c_config_types: + +Configuration C types +~~~~~~~~~~~~~~~~~~~~~ + +Profiler configuration settings include: + +* ``typedef size_t (*sp_writer)(const void **data, size_t len, void *ctx)`` -- + a writer function for profile events. + + Must be async-safe, see also ``man 7 signal-safety``. + + Should return the amount of written bytes on success, or zero in case of error. + + Setting ``*data`` to NULL means end of profiling. + For details see ``lj_wbuf.h``. + +* ``typedef int (*sp_on_stop)(void *ctx, uint8_t *buf)`` -- a callback + on profiler stopping. Required for a correct cleanup at VM finalization + when the profiler is still running. + + Returns zero on success. + +* ``typedef void (*sp_backtracer)(void *(*frame_writer)(int frame_no, void *addr))`` -- + a backtracing function for the host stack. + Should call ``frame_writer`` on each frame in the stack, in the order + from the stack top to the stack bottom. + + The ``frame_writer`` function is implemented inside ``sysprof`` + and will be passed to the ``backtracer`` function. + + If ``frame_writer`` returns NULL, backtracing should be stopped. + If ``frame_writer`` returns not NULL, the backtracing should be continued + if there are frames left. + +.. _profiler_c_options: + +Profiler options +~~~~~~~~~~~~~~~~ + +The options structure for ``luaM_sysprof_start`` is as follows: + +.. code-block:: console + + struct luam_Sysprof_Options { + /* Profiling mode. */ + uint8_t mode; + + /* Sampling interval in msec. */ + uint64_t interval; + + /* Custom buffer to write data. */ + uint8_t *buf; + + /* The buffer's size. */ + size_t len; + + /* Context for the profile writer and final callback. */ + void *ctx; + }; + +.. _profiler_c_modes: + +Profiling modes +~~~~~~~~~~~~~~~ + +The platform profiler supports three profiling modes: + +* ``DEFAULT`` mode collects only data for ``luam_sysprof_counters``, + which is stored in memory and can be collected with ``luaM_sysprof_report`` + after the profiler stops. + +* ``LEAF`` mode = ``DEFAULT`` + streams samples with only top frames of the host + and guests stacks in the format described in ``lj_sysprof.h``. + +* ``CALLGRAPH`` mode = DEFAULT + streams samples with full callchains of the host + and guest stacks in the format described in ``lj_sysprof.h``. + +.. code-block:: console + + #define LUAM_SYSPROF_DEFAULT 0 + #define LUAM_SYSPROF_LEAF 1 + #define LUAM_SYSPROF_CALLGRAPH 2 + +.. _profiler_c_counters: + +Profiling counters +~~~~~~~~~~~~~~~~~~ + +The counters structure for ``luaM_sysprof_report`` is as follows: + +.. code-block:: console + + struct luam_Sysprof_Counters { + uint64_t vmst_interp; + uint64_t vmst_lfunc; + uint64_t vmst_ffunc; + uint64_t vmst_cfunc; + uint64_t vmst_gc; + uint64_t vmst_exit; + uint64_t vmst_record; + uint64_t vmst_opt; + uint64_t vmst_asm; + uint64_t vmst_trace; + + uint64_t samples; + }; + +.. note:: + + The order of ``vmst_*`` counters is important: it should be the same as + the order of the vmstates. + +.. _profiler_caveats: + +Caveats +~~~~~~~ + +* Providing writers, backtracers and other settings in the ``Default`` mode + is pointless, since it only collects counters. +* There is NO default configuration for ``sysprof``, so ``luaM_Sysprof_Configure`` + must be called before the first run of ``sysprof``. Mind the async safety. diff --git a/doc/tooling/tcm/_images/tcm_ui_acl.png b/doc/tooling/tcm/_images/tcm_ui_acl.png new file mode 100644 index 0000000000..0f64965437 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_acl.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_audit_log.png b/doc/tooling/tcm/_images/tcm_ui_audit_log.png new file mode 100644 index 0000000000..e2f3094781 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_audit_log.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_audit_settings.png b/doc/tooling/tcm/_images/tcm_ui_audit_settings.png new file mode 100644 index 0000000000..d31ced7e7f Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_audit_settings.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_cluster_metrics.png b/doc/tooling/tcm/_images/tcm_ui_cluster_metrics.png new file mode 100644 index 0000000000..5ce828d3dc Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_cluster_metrics.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_cluster_migrations.png b/doc/tooling/tcm/_images/tcm_ui_cluster_migrations.png new file mode 100644 index 0000000000..4457877266 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_cluster_migrations.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_cluster_security.png b/doc/tooling/tcm/_images/tcm_ui_cluster_security.png new file mode 100644 index 0000000000..26a5b907ea Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_cluster_security.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_clusters.png b/doc/tooling/tcm/_images/tcm_ui_clusters.png new file mode 100644 index 0000000000..2e67aab4cf Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_clusters.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_config.png b/doc/tooling/tcm/_images/tcm_ui_config.png new file mode 100644 index 0000000000..739badf0f9 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_config.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_instance.png b/doc/tooling/tcm/_images/tcm_ui_instance.png new file mode 100644 index 0000000000..2158e1e9c2 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_instance.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_instance_explorer.png b/doc/tooling/tcm/_images/tcm_ui_instance_explorer.png new file mode 100644 index 0000000000..e1c66a850e Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_instance_explorer.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_ldap.png b/doc/tooling/tcm/_images/tcm_ui_ldap.png new file mode 100644 index 0000000000..ea0d4407be Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_ldap.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_login.png b/doc/tooling/tcm/_images/tcm_ui_login.png new file mode 100644 index 0000000000..a3f737b7fe Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_login.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_policy.png b/doc/tooling/tcm/_images/tcm_ui_policy.png new file mode 100644 index 0000000000..754af02309 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_policy.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_roles.png b/doc/tooling/tcm/_images/tcm_ui_roles.png new file mode 100644 index 0000000000..15694055d8 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_roles.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_sections.png b/doc/tooling/tcm/_images/tcm_ui_sections.png new file mode 100644 index 0000000000..a1ba6fe5a7 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_sections.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_sessions.png b/doc/tooling/tcm/_images/tcm_ui_sessions.png new file mode 100644 index 0000000000..1568b8e9d8 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_sessions.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_stateboard.png b/doc/tooling/tcm/_images/tcm_ui_stateboard.png new file mode 100644 index 0000000000..f0a3f73ad8 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_stateboard.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_tcf.png b/doc/tooling/tcm/_images/tcm_ui_tcf.png new file mode 100644 index 0000000000..935fe64714 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_tcf.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_tcm_metrics.png b/doc/tooling/tcm/_images/tcm_ui_tcm_metrics.png new file mode 100644 index 0000000000..8d69e8a6a7 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_tcm_metrics.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_tuples.png b/doc/tooling/tcm/_images/tcm_ui_tuples.png new file mode 100644 index 0000000000..c3a8d39c19 Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_tuples.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_user_settings.png b/doc/tooling/tcm/_images/tcm_ui_user_settings.png new file mode 100644 index 0000000000..6d70d9c93f Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_user_settings.png differ diff --git a/doc/tooling/tcm/_images/tcm_ui_users.png b/doc/tooling/tcm/_images/tcm_ui_users.png new file mode 100644 index 0000000000..446116823c Binary files /dev/null and b/doc/tooling/tcm/_images/tcm_ui_users.png differ diff --git a/doc/tooling/tcm/index.rst b/doc/tooling/tcm/index.rst new file mode 100644 index 0000000000..1251bf6bf1 --- /dev/null +++ b/doc/tooling/tcm/index.rst @@ -0,0 +1,49 @@ +.. _tcm: + +Tarantool Cluster Manager +========================= + +.. ee_note_tcm_start + +.. admonition:: Enterprise Edition + :class: fact + + |tcm_full_name| is a part of the `Enterprise Edition `_. + +.. ee_note_tcm_end + +|tcm_full_name| (|tcm|) is a web-based visual tool for configuring, managing, and +monitoring Tarantool EE clusters. It provides a GUI for working with clusters +and individual instances, from monitoring their state to executing commands interactively +in an instance's console. + +|tcm| is a standalone application included in the Tarantool Enterprise Edition +:ref:`distribution package `. It is shipped as ready-to-run +executable for Linux platforms. + +|tcm| works only with Tarantool EE clusters that use centralized configuration in +:ref:`etcd ` or a Tarantool-based configuration storage. +When you create or edit a cluster's configuration in |tcm|, it publishes the saved +configuration to the storage. This ensures consistent and reliable configuration storage. +A single |tcm| installation can connect to multiple Tarantool EE clusters and +switch between them in one click. + +To provide enterprise-grade security, |tcm| features its own role-based access control. +You can create users and assign them roles that include required permissions. +For example, a user can be an administrator of a specific cluster or only have the right +to read data. LDAP authorization is supported as well. + +.. toctree:: + :maxdepth: 1 + + tcm_ui_overview + tcm_connect_clusters + tcm_cluster_management/index + tcm_cluster_data_access + tcm_access_control/index + tcm_audit_log + tcm_configuration + tcm_backend_store + tcm_dev_mode + tcm_configuration_reference + Releases diff --git a/doc/tooling/tcm/tcm_access_control/index.rst b/doc/tooling/tcm/tcm_access_control/index.rst new file mode 100644 index 0000000000..69a2cd33df --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/index.rst @@ -0,0 +1,31 @@ +.. _tcm_access_control: + +Access control +============== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides means for managing user and client applications access +to its own functions and connected clusters: + +- :ref:`Local role-based access model ` allow flexible + access management with user accounts created inside |tcm|. +- :ref:`LDAP authentication ` enable authentication with an external + directory server. +- :ref:`Access control list ` enables fine-grained access + to entities stored on connected clusters. +- :ref:`API tokens ` enable integration with third-party applications. +- :ref:`Sessions management ` allow administrators to view and + revoke user sessions. + + +.. toctree:: + :maxdepth: 1 + + tcm_access_control_rbac + tcm_ldap_auth + tcm_access_control_list + tcm_api_tokens + tcm_sessions \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst b/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst new file mode 100644 index 0000000000..81d45ac7d4 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_access_control_list.rst @@ -0,0 +1,77 @@ +.. _tcm_access_control_list: + +Access control list +=================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| *access control list* (*ACL*) determines user access to particular data +and functions stored in clusters. You can use it to allow or deny access to specific +stored objects one by one. + +Each ACL entry specifies privileges that a |tcm| user has on a particular +space or a function. There are three access privileges that can be granted in the ACL: +read, write, and execute (for stored functions only). The privileges work as follows: + +- Spaces: + + - ``Read``: the user sees the space and its tuples on the **Tuples** and **Explorer** pages + - ``Write``: the user can add new and edit existing tuples of the space + +- Functions: + + - ``Read``: the user sees the function on the **Functions** tab of the instance details page. + - ``Write``: the user can edit or delete the function + - ``Execute``: the user can call the function + +.. important:: + + User access to space data and stored functions is primarily defined by the + :ref:`cluster permissions ` ``cluster.space.data.*`` and ``cluster.func.*``. + ACL only increases the access control granularity to particular objects. + Make sure that users have these permissions before enabling ACL for them. + +.. _tcm_access_control_list_enable: + +Enabling ACL for a user +~~~~~~~~~~~~~~~~~~~~~~~ + +To granularly manage a user's access to particular objects in a cluster, enable +the use of ACL in the user profile: + +#. Go to **Users** and click **Edit** in the **Actions** menu of the corresponding table row. + +#. In the user's **Clusters** list, add a cluster on which you want to use ACL + or click the pencil icon if the cluster is already on the list. + +#. Select the **Use Access Control List (ACL)** checkbox and save changes. + +#. Repeat two previous steps for each cluster on which you want to use ACL for this user. + +#. Click **Update** to save the user account. + +If the user doesn't exist yet, you can do the same when creating it. + +.. important:: + + When ACL use is enabled for a user, this user loses access to all spaces and + functions of the selected cluster except the ones explicitly specified in the ACL. + +.. _tcm_access_control_list_manage: + +Managing ACL +------------ + +The tools for managing ACL are located on the **ACL** page. + +To add an ACL entry: + +#. Click **Add**. +#. Select a user to which you want to grant access. +#. Select a cluster that stores the target object: a space or a function. +#. Select the target object type and enter its name. +#. Select the privileges you want to grant. + +To delete an ACL entry, click **Delete** in the **Actions** menu of the corresponding table row. diff --git a/doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst b/doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst new file mode 100644 index 0000000000..ca45072581 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_access_control_rbac.rst @@ -0,0 +1,414 @@ +.. _tcm_access_control_rbac: + +Role-based access control +========================= + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| features a role-based access control system. It enables flexible +management of access to |tcm| functions, connected clusters, and stored data. +The |tcm| access system uses three main entities: permissions, roles, +and users (or user accounts). They work as follows: + +- Permissions correspond to specific functions or objects in + |tcm| (*administrative permissions*) or operations on clusters (*cluster permissions*). +- Roles are predefined sets of *administrative* permissions to + assign to users. +- Users have roles that define their access rights to |tcm| functions and objects, and + *cluster* permissions that are assigned for each cluster individually. + +.. note:: + + |tcm| users, roles, and permissions are not to be confused with similar subjects + of the :ref:`Tarantool access control system `. To access Tarantool + instances directly, Tarantool users with corresponding roles are required. + +.. _tcm_access_control_permissions: + +Permissions +----------- + +Permissions define access to specific actions that users can do in |tcm|. For example, +there are permissions to view connected clusters or to manage users. + +There are two types of permissions in |tcm|: *administrative* and *cluster* permissions. + +* *Administrative permissions* provide access to |tcm| functions. They define which + pages and controls are available to users in the web UI. Typically, *read* permissions + define pages shown in the left menu. *Write* permissions define the availability + of controls for managing objects on the pages. + For example, users with read permission to clusters can view the **Clusters** page + but they don't see **Add**, **Edit**, or **Remove** buttons unless they have the + write permission. + + Administrative permissions are assigned to users through :ref:`roles `. + +* *Cluster permissions* enable actions with connected Tarantool clusters. + These permissions are granted to users on a per-cluster level: each user has a separate + set of permissions for each cluster. + + Cluster permissions define which pages of the **Cluster** menu section users + see and what actions they can take on these pages. + For example, users with the read configuration permission to a cluster configuration + see the **Configuration** page when this cluster is selected. + + Cluster permissions are assigned to users individually when creating or editing them. + + For a fine-grained control over user access to particular spaces and functions stored + in clusters, there is the :ref:`access control list `. + +Permissions are predefined in |tcm|, there is no way to change, add, or delete them. +The complete lists of administrative and cluster permissions in |tcm| are provided +in the :ref:`Permissions reference `. + +.. _tcm_access_control_roles: + +Roles +----- + +Roles are groups of :ref:`administrative permissions ` +that are assigned to users together. + +The assigned roles define pages that users see in |tcm| and actions available +on these pages. + +.. note:: + + Roles don't include cluster permissions. Access to connected clusters + is configured for each user individually. + +.. _tcm_access_control_roles_default: + +Default roles +~~~~~~~~~~~~~ + +|tcm| comes with default roles that cover three common usage scenarios: + +- **Super Admin Role** is a default role with all available + :ref:`administrative permissions `. + Additionally, the users with this role automatically gain all + :ref:`cluster permissions ` + to all clusters. +- **Cluster Admin Role** is a default role for cluster administration. It includes + administrative permissions for cluster management. +- **Default User Role** is a default role for working with clusters. It includes + basic administrative *read* permissions that are required to log in to |tcm| + and navigate to a cluster. + +.. _tcm_access_control_roles_manage: + +Managing roles +~~~~~~~~~~~~~~ + +Administrators can create new roles, edit, and delete existing ones. + +Roles are listed on the **Roles** page. + +To create a new role, click **Add**, enter the role name, and select the permissions +to include in the role. + +To edit an existing role, click **Edit** in the **Actions** menu of the corresponding +table row. + +To delete a role, click **Delete** in the **Actions** menu of the corresponding +table row. + +.. note:: + + You can delete a role only if there are no users with this role. + +.. _tcm_access_control_users: + +Users +----- + +|tcm| users gain access to objects and actions through assigned :ref:`roles ` +and :ref:`cluster permissions `. + +A user can have any number of roles or none of them. Users without roles +have access only to clusters that are assigned to them. + +|tcm| uses password authentication for users. For information on password management, +see the :ref:`Passwords ` section below. + +Default admin +~~~~~~~~~~~~~ + +There is one default user **Default Admin**. It has all the available permissions, +both administrative and cluster ones. When new clusters are added in |tcm|, +**Default Admin** automatically receives all cluster permissions for them as well. + +.. _tcm_access_control_users_manage: + +Managing users +~~~~~~~~~~~~~~ + +Administrators can create new users, edit, and delete existing ones. + +The tools for managing users are located on the **Users** page. + +To create a user: + +1. Click **Add**. +2. Fill in the user information: username, full name, and description. +3. Generate or type in a password. +4. Select roles to assign to the user. +5. Add clusters to give the user access to, and select cluster permissions for + each of them. + +To edit a user, click **Edit** in the **Actions** menu of the corresponding table row. + +To delete a user, click **Delete** in the **Actions** menu of the corresponding table row. + +.. _tcm_access_control_passwords: + +Passwords +--------- + +|tcm| uses the general term *secret* for user authentication keys. A secret is any +pair of a public and a private key that can be used for authentication. A *password* +combined with a *username* is a secret type used for |tcm| user authentication. +In this case, the public key is a username, and the private key is a password. + +Users receive their first passwords during their :ref:`account creation `. + +All passwords are governed by the :ref:`password policy `. +It can be flexibly configured to follow the security requirements of your organization. + +.. _tcm_access_control_password_change: + +Changing your password +~~~~~~~~~~~~~~~~~~~~~~ + +To change your own password, click your name in the top-right corner and go to +**Settings** > **Change password**. + +.. _tcm_access_control_password_users_change: + +Changing users' passwords +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Administrators can manage a user's password on this user's **Secrets** page. +To open it, click **Secrets** in the **Actions** menu of the corresponding **Users** table row. + +To change a user's password, click **Edit** in the **Actions** menu of the corresponding +**Secrets** table row and enter the new password in the **New secret key** field. + +.. _tcm_access_control_password_expiry: + +Password expiry +~~~~~~~~~~~~~~~ + +Passwords expire automatically after the expiration period defined in the :ref:`password policy `. +When a user logs in to |tcm| with an expired password, the only action available to +them is a password change. All other |tcm| functions and objects are unavailable until +the new password is set. + +Administrators can also set users' passwords to expired manually. +To set a user's password to expired, click **Expire** in the **Actions** +menu of the corresponding **Secrets** table row. + +.. important:: + + Password expiration can't be reverted. + +.. _tcm_access_control_password_block: + +Blocking passwords +~~~~~~~~~~~~~~~~~~ + +To forbid users' access to |tcm|, administrators can temporarily block their +passwords. A blocked password can't be used to log into |tcm| until it's +unblocked manually or the blocking period expires. + +To block a user's password, click **Block** in the **Actions** menu of the corresponding +**Secrets** table row. Then provide a blocking reason and enter the blocking period. + +To unblock a blocked password, click **Unblock** in the **Actions** menu of the corresponding +**Secrets** table row. + +.. _tcm_access_control_password_policy: + +Password policy +~~~~~~~~~~~~~~~ + +Password policy helps improve security and comply with security requirements that +can apply to your organization. + +You can edit the |tcm| password policy on the **Password policy** page. +There are the following password policy settings: + +- **Minimal password length**. +- **Do not use last N passwords**. +- **Password expiration in days**. Users' passwords :ref:`expire ` + after this number of days since they were set. Users with expired passwords + lose access to any objects and functions except password change until they set + a new password. +- **Password expiration warning in days**. After this number of days, the user + sees a warning that their password expires soon. +- **Block after N login attempts**. Temporarily block users if they enter their + username or password incorrectly this number of times consecutively. +- **User lockout time in seconds**. The time interval for which users can't log + in after spending all failed login attempts. +- **Password must include**. Characters and symbols that must be present in passwords: + + - **Lowercase characters (a-z)** + - **Uppercase characters (A-Z)** + - **Digits (0-9)** + - **Symbols (such as !@#$%^&\*()_+№"':,.;=][{}`?>/.)** + + +.. _tcm_access_control_permissions_ref: + +Permissions reference +--------------------- + +.. _tcm_access_control_permissions_admin: + +Administrative permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following administrative permissions are available in |tcm|: + +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Permission + - Description + + * - ``admin.clusters.read`` + - View connected clusters' details + + * - ``admin.clusters.write`` + - Edit cluster details and add new clusters + + * - ``admin.users.read`` + - View users' details + + * - ``admin.users.write`` + - Edit user details and add new users + + * - ``admin.roles.read`` + - View roles' details + + * - ``admin.roles.write`` + - Edit roles and add new roles + + * - ``admin.addons.read`` + - View add-ons + + * - ``admin.addons.write`` + - Edit add-on flags + + * - ``admin.addons.upload`` + - Upload new add-ons + + * - ``admin.auditlog.read`` + - View audit log configuration and read audit log in |tcm| + + * - ``admin.auditlog.write`` + - Edit audit log configuration + + * - ``admin.sessions.read`` + - View users' sessions + + * - ``admin.sessions.write`` + - Revoke users' sessions + + * - ``admin.ldap.read`` + - View LDAP configurations + + * - ``admin.ldap.write`` + - Manage LDAP configurations + + * - ``admin.passwordpolicy.read`` + - View password policy + + * - ``admin.passwordpolicy.write`` + - Manage password policy + + * - ``admin.secrets.read`` + - View information about users' secrets + + * - ``admin.secrets.write`` + - Manage users' secrets: add, edit, expire, block, delete + + * - ``user.password.change`` + - User's permission to change their own password + + * - ``user.api-token.read`` + - User's permission to read their own API tokens information + + * - ``user.api-token.write`` + - User's permission to modify their own API tokens + + * - ``admin.metrics`` + - Read |tcm| metrics + + * - ``admin.acl.read`` + - View the access control list (ACL) + + * - ``admin.acl.write`` + - Add and delete ACL entries + +.. _tcm_access_control_permissions_cluster: + +Cluster permissions +~~~~~~~~~~~~~~~~~~~ + +The following cluster permissions are available in |tcm|: + +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Permission + - Description + + * - ``cluster.config.read`` + - View cluster configuration + + * - ``cluster.config.write`` + - Manage cluster configuration + + * - ``cluster.stateboard.read`` + - View cluster stateboard + + * - ``cluster.func.read`` + - View cluster's stored functions + + * - ``cluster.func.write`` + - Edit cluster's stored functions + + * - ``cluster.func.call`` + - Execute stored functions on cluster instances + + * - ``cluster.space.read`` + - Read cluster data schema + + * - ``cluster.space.write`` + - Modify cluster data schema + + * - ``cluster.space.data.read`` + - Read stored data from cluster + + * - ``cluster.space.data.write`` + - Edit stored data on cluster + + * - ``cluster.failover.read`` + - Read cluster failover information + + * - ``cluster.failover.write`` + - Write cluster failover commands + + * - ``cluster.terminal`` + - Connect to cluster instances with ``tt`` terminal from |TCM| + + * - ``cluster.sql`` + - Execute SQL queries + + * - ``cluster.metrics`` + - View cluster metrics diff --git a/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst b/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst new file mode 100644 index 0000000000..813dc9cb53 --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_api_tokens.rst @@ -0,0 +1,57 @@ +.. _tcm_access_control_api_tokens: + +API tokens +========== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| uses the Bearer HTTP authentication scheme with *API tokens* to authenticate +external applications' requests to |tcm|. For example, these can be Prometheus +jobs that retrieve metrics of connected Tarantool clusters. + +The API tokens functionality is disabled by default. To enable it, set the +:ref:`feature.api-token ` configuration option to ``true``. + +.. code-block:: yaml + + feature: + api-token: true + +Each |tcm| API token belongs to the user that created it and has the same :ref:`access permissions `. +Thus, if a user has a permission to view a cluster's metrics in |tcm|, this user's +API tokens can be used to read this cluster's metrics with Prometheus. + +API tokens have expiration dates that are set during the token creation and cannot +be changed. + +.. _tcm_access_control_api_tokens_manage: + +Managing API tokens +------------------- + +.. note:: + + Each user, including **Default Admin** and other administrators, can create only + their own tokens. There is no way to create a token for another user. + +To create a |tcm| API token: + +#. Open the user settings by clicking the user's name in the top-right corner. +#. Go to the **API tokens** tab and click **Add**. +#. Specify the token expiration date and an optional description and click **Add**. + +The created token is shown in a dialog. + +.. important:: + + An API token is shown only once after its creation. There is no way to view + it again after you close the dialog. Make sure to copy the token in a safe place. + +To delete an API token, click **Delete** in the actions menu of the corresponding +**API tokens** table row. + +Administrators can also view information about users' API tokens and delete them +on the **Secrets** page. To open a user's secrets, click **Secrets** in the **Actions** +menu of the corresponding **Users** table row. \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst b/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst new file mode 100644 index 0000000000..e444f9488c --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_ldap_auth.rst @@ -0,0 +1,175 @@ +.. _tcm_ldap_auth: + +LDAP authentication +=================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +In addition to its internal :ref:`role-based access control model `, +|tcm_full_name| can use an external LDAP (Lightweight Directory Access Protocol) +directory server for user authentication and authorization. + +When LDAP authentication is enabled, |tcm| uses a connected LDAP directory server +to authenticates users who submit the login form. |tcm| constructs requests to +the servers according to configuration parameters described on this page. Permissions +of LDAP users in |tcm| are defined by LDAP group mapping. + +Both LDAP and secure LDAPS (LDAP over TLS) protocols are supported. + +.. _tcm_ldap_auth_enable: + +Enabling LDAP authentication +---------------------------- + +To allow LDAP user authentication in |tcm|, enable the ``ldap`` authentication method +in the :ref:`security.auth ` configuration option before startup: + +- In the YAML |tcm| configuration: + + .. code-block:: yaml + + security: + auth: + - ldap + +- In the command line: + + .. code-block:: console + + $ tcm --security.auth="ldap" + +.. note:: + + If both authentication methods -- LDAP and local -- are enabled, |tcm| tries them + for each login attempt in the order they are specified in the configuration. + +.. _tcm_ldap_auth_config: + +LDAP configuration +------------------ + +To enable LDAP user access to |tcm|, create an *LDAP configuration* that connects +|tcm| to the LDAP server that stores the users. An LDAP configuration +defines how |tcm| connects to the server and queries user data. To create an LDAP +configuration, go to the **LDAP** page in the **Settings** group and click **Add**. + +To edit an LDAP configuration, click **Edit** in the **Actions** menu of the corresponding row. + +To delete an LDAP configuration, click **Delete** in the **Actions** menu of the corresponding row. + +.. _tcm_ldap_auth_config_general: + +General settings +~~~~~~~~~~~~~~~~ + +Define the general configuration settings: + +* **Enabled**. Defines if the configuration is used. Turn the toggle off to + stop using the configuration. + + .. note:: + + If there are several enabled LDAP configurations, |tcm| attempts to use them + for user authentication in the order they are created. + +* **Automatically add non-existent users**. By default, |tcm| automatically saves + LDAP user information to its :ref:`backend store ` + upon their first login. Turn the toggle off if you don't want to save users from this LDAP server. + +.. _tcm_ldap_auth_config_connect: + +LDAP server connection +~~~~~~~~~~~~~~~~~~~~~~ + +Enter the LDAP server connection parameters: + +* **Endpoints**. URLs of the LDAP server. Example: ``127.0.0.1:5056``. +* **Request timeout**. The timeout for |tcm| requests to the LDAP server, in seconds. +* **Enabled TLS**. If the server uses LDAPS, turn this toggle on and specify + TLS connection parameters, such as a certificate and a key file. + +.. _tcm_ldap_auth_config_query: + +LDAP queries +~~~~~~~~~~~~ + +To define how |tcm| queries the LDAP server for user authentication and authorization, +fill in the fields of the **Queries** step: + +- **Query user** and **Query password**. Credentials of the LDAP user on behalf + of which all LDAP queries are executed: a distinguished name (DN) and a password. + Example DN: + + .. code-block:: text + + cn=admin,cn=users,dc=tarantool,dc=io + +- **Base DN**. The DN of a directory that serves as a root for making all LDAP requests. + Example: ``dc=tarantool,dc=io``. +- **Username regex**. A regular expression that defines a username template for + this LDAP configuration. When a user enters their username on the login page, + |tcm| matches it against username regular expressions of all enabled LDAP + configurations and selects the one to use for this user authentication. + + Example: a regex to match employee email addresses within the specified domain. + + .. code-block:: text + + ^([\w\-\.]+)@tarantool.io$ + +- (Optional) **Template DN**. A template for building a DN to send in an authentication bind request. + Use the numbers in curly braces as placeholders to replace with username regex parts: + ``{0}``, ``{1}``, and so on. + + Example: + + .. code-block:: text + + cn={0},cn=users,dc=tarantool,dc=io + + When used with the **Username regex** shown above, it substitutes ``{0}`` with + the username part of the email address (before ``@``) entered into the login form. + For example, the username ``user1@tarantool.io`` forms the following DN for bind request: + + .. code-block:: text + + cn=user1,cn=users,dc=tarantool,dc=io + +- (Optional) **Template query**. A template for querying the LDAP server for the DN. This + way is used if **Template DN** is not provided. +- **Group query template**. A template for querying groups to which a user belongs + for authorization purposes. Learn more in :ref:`tcm_ldap_auth_config_permissions`. + Example: + + .. code-block:: text + + (&(objectCategory=person)(objectClass=user)(cn={0})) + + +.. _tcm_ldap_auth_config_permissions: + +LDAP user permissions +~~~~~~~~~~~~~~~~~~~~~ + +Permissions of LDAP users in |tcm| are defined by the groups to which they belong. +You can map |tcm| administrative and cluster :ref:`permissions ` +to LDAP groups on the **Groups** step of the configuration creation. + +To assign permissions to an LDAP group, click **Add group**. In the dialog that opens, +enter the group name, for example, ``CN=Admins,CN=Builtin,DC=tarantool,DC=io``. +Then, select administrative permission to grant to this group in the **Permissions** list. + +To grant cluster permissions, click **Add cluster**. Select a cluster and the cluster +permissions to grant to the group. Save the group. + +Each user has permissions of all LDAP groups to which they belong. + + +.. _tcm_ldap_auth_config_disable: + +Disabling LDAP configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To stop using an LDAP configuration, open its **Edit** page and turn off the **Enabled** toggle. diff --git a/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst b/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst new file mode 100644 index 0000000000..d8a585c36d --- /dev/null +++ b/doc/tooling/tcm/tcm_access_control/tcm_sessions.rst @@ -0,0 +1,15 @@ +.. _tcm_access_control_sessions: + +Sessions +======== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| administrators can view and revoke user sessions in the web interface. +All active sessions are listed on the **Sessions** page. To revoke a session, click +**Revoke** in the **Actions** menu of the corresponding table row. + +To revoke all sessions of a |tcm| user, go to **Users** and click **Revoke all sessions** +in the **Actions** menu of the corresponding table row. diff --git a/doc/tooling/tcm/tcm_audit_log.rst b/doc/tooling/tcm/tcm_audit_log.rst new file mode 100644 index 0000000000..d702462027 --- /dev/null +++ b/doc/tooling/tcm/tcm_audit_log.rst @@ -0,0 +1,332 @@ +.. _tcm_audit_log: + +Audit log +========= + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides the audit logging functionality for tracking user activity +and security-related events, such as: + +* Successful and failed login attempts. +* Access to clusters, their configurations, data models, and stored data. +* Changes in the access control system: users, roles, passwords, LDAP configurations. + +The complete list of |tcm| audit events is provided in :ref:`Event types `. + +.. note:: + + |tcm| audit log records only events that happen in |tcm| itself. + For information about Tarantool audit logging, see :ref:`Audit module `. + +Audit logging is disabled in |tcm| by default. To start recording events, you need +to :ref:`enable ` and :ref:`configure ` it. + +The audit log stores event details in the JSON format. Each log entry contains the +event type, description, time, impacted objects, and other information that +may be used for incident investigation. The complete list of fields is provided in +:ref:`Structure of audit log events `. + +|tcm| also provides a built-in interface for reading and searching the audit log. +For details, see :ref:`Viewing audit log `. + +.. _tcm_audit_log_enable: + +Enabling audit logging +---------------------- + +To enable audit logging in |tcm|, go to **Audit settings** and click **Enable**. + +To additionally send audit log events to the standard output, click **Send to stdout**. + +.. _tcm_audit_log_config: + +Audit log configuration +----------------------- + +|tcm| audit events can be logged to a local file or sent to a +`syslog `__ server. +To configure audit logging, go to **Audit settings**. + +Writing to a file +~~~~~~~~~~~~~~~~~ + +To write |tcm| audit logs to a file: + +1. Go to **Audit settings** and select the **file** protocol. +2. Specify the name of the audit log file. The file appears in the |tcm| working directory. +3. Configure the log files rotation: the maximum file size and age, and the number + of files to store simultaneously. +4. (Optional) Enable compression of audit log files. + +.. TODO: move to UI reference + +Configuration parameters: + +- **Output file name**. The name of the audit log file. Default: ``audit.log`` +- **Max size (in MB)**. The maximum size of the log file before it gets rotated, in megabytes. Default: 100. +- **Max backups**. The maximum number of stored audit log files. Default: 10. +- **Max age (in days)**. The maximum age of audit log files in days. Default: 30. +- **Compress**. Compress audit log files into ``gzip`` archives when rotating. + +Sending to syslog +~~~~~~~~~~~~~~~~~ + +If you use a centralized log management system based on `syslog `__, +you can configure |tcm| to send its audit log to your syslog server: + +1. Go to **Audit settings** and select the **syslog** protocol. +2. Enter the syslog server URI and select the network protocol. Typically, + ``syslogd`` listens on port 514 and uses the UDP protocol. +3. Specify the syslog logging parameters: timeout, priority, and facility. + +.. TODO: move to UI reference + +Configuration parameters: + +- **Protocol**. The network protocol used for connecting to the syslog server. Default: ``udp``. +- **Output**. The syslog server URI. Default: 127.0.0.1:514 (localhost). +- **Timeout**. The syslog write timeout in the `ISO 8601 duration format `__. + Default: ``PT2S`` (two seconds). +- **Priority**. The syslog severity level. Default: ``info``. +- **Facility**. The syslog facility. Default: ``local0``. + +Selecting audit events to record +-------------------------------- + +When the audit log is enabled, |tcm| records all audit events listed in :ref:`Event types `. +To decrease load and make the audit log comply with specific security +requirements, you can record only selected events. For example, these can be events +of user account management or events of cluster data access. + +To select events to record into the audit log, go to **Audit settings** and +enter their :ref:`types ` into the **Filters** field +one-by-one, pressing the **Enter** key after each type. + +To remove an event type from a filters list, click the cross icon beside it. + +.. _tcm_audit_log_view: + +Viewing audit log +----------------- + +If the audit log is written to a file, you can view it in |tcm| on the **Audit log** page. +On this page, you can view or search for events. + +To view the details of a logged audit event, click the corresponding line in the +table. + +To search for an event, use the search bar at the top of the page. Note that the +search is case-sensitive. For example, to find events with the ``ALARM`` severity, +enter ``ALARM``, not ``alarm``. + +.. _tcm_audit_log_structure: + +Structure of audit log events +----------------------------- + +All entries of the |tcm| audit log include the mandatory fields listed in the table below. + +.. container:: table + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Field + - Description + - Example + * - ``time`` + - Time of the event + - 2023-11-23T12:05:27.099+07:00 + * - ``severity`` + - Event severity: ``VERBOSE``, ``INFO``, ``WARNING``, or ``ALARM`` + - INFO + * - ``type`` + - Audit :ref:`event type ` + - user.update + * - ``description`` + - Human-readable event description + - Update user + * - ``uuid`` + - Event UUID + - f8744f51-5760-40c3-ae2d-0b4d6b44836f + * - ``user`` + - UUID of the user who triggered the event + - 942a4f54-cf7f-4f46-80ce-3511dbbb57b7 + * - ``remote`` + - Remote host that triggered the event + - 100.96.163.226:48722 + * - ``host`` + - The |tcm| host on which the event happened + - 100.96.163.226:8080 + * - ``userAgent`` + - Information about the client application and platform that was used to trigger the event + - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 + * - ``permission`` + - The permission that was used to trigger the event + - ["admin.users.write"] + * - ``result`` + - Event result: ``ok`` or ``nok`` + - ok + * - ``err`` + - Human-readable error description for events with ``nok`` result + - failed to login + * - ``fields`` + - Additional fields for specific event types in the key-value format + - Key examples: + + - ``clusterId`` in cluster-related events + - ``payload`` in events that include sending data to the server + - ``username`` in ``current.*`` or ``auth.*`` events + + +This is an example of an audit log entry on a successful login attempt: + +.. code-block:: json + + { + "time": "2023-11-23T12:01:27.247+07:00", + "severity": "INFO", + "description": "Login user", + "type": "current.login", + "uuid": "4b9c2dd1-d9a1-4b40-a448-6bef4a0e5c79", + "user": "", + "remote": "127.0.0.1:63370", + "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36", + "host": "127.0.0.1:8080", + "permissions": [], + "result": "ok", + "fields": [ + { + "Key": "username", + "Value": "admin" + }, + { + "Key": "method", + "Value": "null" + }, + { + "Key": "output", + "Value": "true" + } + ] + } + +.. _tcm_audit_log_event_types: + +Event types +----------- + +The following table lists all possible values of the ``type`` field of |tcm| +audit log events. + +.. container:: table + + .. list-table:: + :widths: auto + :header-rows: 1 + + * - Event type + - Description + + * - ``auth.fail`` + - Authentication failed + * - ``auth.ok`` + - Authentication successful + * - ``access.denied`` + - An attempt to access an object without the required permission + * - ``user.add`` + - User added + * - ``user.update`` + - User updated + * - ``user.delete`` + - User deleted + * - ``secret.add`` + - User secret added + * - ``secret.update`` + - User secret updated + * - ``secret.block`` + - User secret blocked + * - ``secret.unblock`` + - User secret unblocked + * - ``secret.delete`` + - User secret deleted + * - ``secret.expire`` + - User secret expired + * - ``session.revoke`` + - Session revoked + * - ``session.revokeuser`` + - All user's sessions revoked + * - ``explorer.insert`` + - Data inserted in a cluster + * - ``explorer.delete`` + - Data deleted from a cluster + * - ``explorer.replace`` + - Data replaced in a cluster + * - ``explorer.call`` + - Stored function called on a cluster + * - ``explorer.evaluate`` + - Code executed on a cluster + * - ``explorer.switchover`` + - Master switched manually + * - ``test.devmode`` + - Switched to development mode + * - ``auditlog.config`` + - Audit log configuration changed + * - ``passwordpolicy.save`` + - Password policy changed + * - ``passwordpolicy.resetpasswords`` + - All passwords expired by an administrator + * - ``ddl.save`` + - Cluster data model saved + * - ``ddl.apply`` + - Cluster data model applied + * - ``cluster.config.save`` + - Cluster configuration saved + * - ``cluster.config.reset`` + - Saved cluster configuration reset + * - ``cluster.config.apply`` + - Cluster configuration applied + * - ``current.logout`` + - User logged out their own session + * - ``current.revoke`` + - User revoked their own session + * - ``current.revokeall`` + - User revoked all their active sessions + * - ``current.changepassword`` + - User changed their password + * - ``role.add`` + - Role added + * - ``role.update`` + - Role updated + * - ``role.delete`` + - Role deleted + * - ``cluster.add`` + - Cluster added + * - ``cluster.update`` + - Cluster updated + * - ``cluster.delete`` + - Cluster removed + * - ``ldap.testlogin`` + - Login test executed for a LDAP configuration + * - ``ldap.testconnection`` + - Connection test executed for a LDAP configuration + * - ``ldap.add`` + - LDAP configuration added + * - ``ldap.update`` + - LDAP configuration updated + * - ``ldap.delete`` + - LDAP configuration deleted + * - ``addon.enable`` + - Add-on enabled + * - ``addon.disable`` + - Add-on disabled + * - ``addon.delete`` + - Add-on removed + * - ``tcmstate.save`` + - Low-level information saved in the TCM storage (for debug purposes) + * - ``tcmstate.delete`` + - Low-level information deleted from the TCM storage (for debug purposes) diff --git a/doc/tooling/tcm/tcm_backend_store.rst b/doc/tooling/tcm/tcm_backend_store.rst new file mode 100644 index 0000000000..5ec128bcd1 --- /dev/null +++ b/doc/tooling/tcm/tcm_backend_store.rst @@ -0,0 +1,386 @@ +.. _tcm_backend_store: + +Backend store +============= + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| uses an underlying data store (*backend store*) for its entities: +users, roles, cluster connections, settings, and other objects that you manipulate in |tcm|. +The backend store can be either an etcd or a Tarantool cluster. + +For better reliability and scalability, the backend store works independently from |tcm|. +For example, it can be the same ectd or Tarantool cluster that you use as a :ref:`centralized configuration storage `. +This makes |tcm| stateless: all objects created or modified in its web UI are saved +to the backend store, and nothing is stored inside the |tcm| instances themselves. +Any number of instances can duplicate each other when connected to the same backend store. +If you stop all instances, the store still contains their objects. You can continue +working with them right after starting a new instance. + +In addition to using an external backend store, you can run |tcm| with an embedded +etcd or Tarantool instance to use as the backend store. + +On this page, you will learn to connect |tcm| to backend stores of both types, +or start |tcm| with an embedded backend store. + +.. _tcm_backend_store_set_up: + +Setting up a backend store +-------------------------- + +The |tcm| backend store requires the same configuration as +:ref:`Tarantool centralized configuration storage `. +Follow the instructions in :ref:`centralized_configuration_storage_set_up` to +set up a backend store. + +.. note:: + + If you already have the centralized configuration store for your Tarantool clusters, + you can use it as a |tcm| backend store as well. + +.. _tcm_backend_store_connect: + +Configuring backend store connection +------------------------------------ + +The |tcm|'s connection to its backend store is configured using the :ref:`storage.* ` +configuration options. The :ref:`storage.provider ` +option selects the store type. It can be either ``etcd`` or ``tarantool``. + +.. _tcm_backend_store_connect_etcd: + +External etcd store +~~~~~~~~~~~~~~~~~~~ + +To use an etcd cluster as a |tcm| backend store, set the ``storage.provider`` option +to ``etcd`` and specify connection parameters in ``storage.etcd.*`` options. +A minimal etcd configuration includes the storage endpoints: + +.. code-block:: yaml + + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + +If authentication is enabled in etcd, specify ``storage.etcd.username`` and ``storage.etcd.password``: + +.. code-block:: yaml + + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + username: etcduser + password: secret + +The |tcm| data is stored in etcd under the prefix specified in ``storage.etcd.prefix``. +By default, the prefix is ``/tcm``. If you want to change it or store data of +different |tcm| instances separately in one etcd cluster, set the prefix explicitly: + +.. code-block:: yaml + + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + prefix: /tcm2 + + +Other ``storage.etcd.*`` options configure various aspects of the etcd store connection, +such as network timeouts and limits or TLS parameters. +For the full list of the etcd |tcm| backend store options, see the +:ref:`TCM configuration reference `. + +.. _tcm_backend_store_connect_tarantool: + +External Tarantool-based store +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use a Tarantool cluster as a |tcm| backend store, set the ``storage.provider`` option +to ``tarantool`` and specify connection parameters in ``storage.tarantool.*`` options. +A minimal configuration includes the one or more addresses of +the backend store instances: + +.. code-block:: yaml + + storage: + provider: tarantool + tarantool: + addr: http://127.0.0.1:3301 + +Or: + +.. code-block:: yaml + + storage: + provider: tarantool + tarantool: + addrs: + - http://127.0.0.1:3301 + - http://127.0.0.1:3302 + - http://127.0.0.1:3303 + +If authentication is enabled in the backend store, specify ``storage.tarantool.username`` +and ``storage.tarantool.password``: + +.. code-block:: yaml + + storage: + provider: tarantool + tarantool: + addr: http://127.0.0.1:3301 + username: tarantooluser + password: secret + +The |tcm| data is stored in the Tarantool-based backend store under the prefix +specified in ``storage.tarantool.prefix``. +By default, the prefix is ``/tcm``. If you want to change it or store data of +different |tcm| instances separately in one Tarantool cluster, set the prefix explicitly: + +.. code-block:: yaml + + storage: + provider: tarantool + tarantool: + addr: http://127.0.0.1:3301 + username: tarantooluser + password: secret + prefix: /tcm2 + + +Other ``storage.tarantool.*`` options configure various aspects of |tcm| connection +to the Tarantool-based backend store, such as network timeouts and limits or TLS parameters. +For the full list of the Tarantool-based |tcm| backend store options, see the +:ref:`TCM configuration reference `. + +.. _tcm_backend_store_embed: + +Embedded backend store +---------------------- + +For development purposes, you can start |tcm| with an embedded backend store. +This is useful for local runs when you don't have or don't need an external backend store. + +An embedded |tcm| backend store is a single instance of etcd or Tarantool that +is started automatically on the same host during the |tcm| startup. It runs +in the background until |tcm| is stopped. The embedded backend store is persistent: +if you start |tcm| again with the same backend store configuration, it restores +the |tcm| data from the previous runs. + +.. note:: + + To start a clean instance of |tcm|, remove the working directory of the + embedded backend store specified in the ``storage.etcd.embed.workdir`` or + ``storage.tarantool.embed.workdir`` option. + +The embedded backend store parameters are configured using the ``storage.etcd.embed.*`` options +for etcd or ``storage.tarantool.embed.*`` options for a Tarantool-based store. + +To start |tcm| with an embedded etcd with default settings, set ``storage.etcd.embed.enabled`` to ``true`` +and leave other ``storage.*`` options default: + +.. code-block:: yaml + + storage.etcd.embed.enabled: true + +You can use the following call to get |tcm| running with embedded etcd without +a configuration file: + +.. code-block:: console + + $ tcm --storage.etcd.embed.enabled + +To start |tcm| with an embedded Tarantool storage with default settings: + +* set ``storage.provider`` to ``tarantool`` +* set ``storage.tarantool.embed.enabled`` to ``true`` + +.. code-block:: yaml + + storage: + provider: tarantool + tarantool.embed.enabled: true + +With command-line arguments: + +.. code-block:: console + + $ tcm --storage.provider=tarantool --storage.tarantool.embed.enabled + +You can tune the embedded backend store, for example, enable and configure TLS on it +or change its working directories or startup arguments. To set specific parameters, +specify the corresponding ``storage.etcd.embed.*`` or ``storage.tarantool.embed.*`` +options. For the full list of configuration options of embedded backend stores, see the +:ref:`TCM configuration reference `. + +.. _tcm_backend_store_embed_cluster: + +Setting up a cluster of embedded backend stores +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To simulate the production environment, you can form a distributed multi-instance cluster +from embedded stores of multiple |tcm| instances. To do this, configure each |tcm| +instance's embedded store to join each other. + +For etcd, provide the embedded store clustering parameters ``storage.etcd.embed.*`` +and specify the endpoints in ``storage.etcd.endpoints``. The options that configure +embedded etcd mostly match the etcd configuration options. For more information +about these options, see the `etcd documentation `__. + +Below are example configurations of three |tcm| instances that start with embedded etcd instances +and form an etcd cluster from them: + +* First instance: + + .. code-block:: yaml + + http.port: 8080 + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + - http://127.0.0.1:22379 + - http://127.0.0.1:32379 + embed: + enabled: true + name: infra1 + endpoints: http://127.0.0.1:2379 + advertises: http://127.0.0.1:2379 + initial-cluster-state: new + initial-cluster: infra1=http://127.0.0.1:12380,infra2=http://127.0.0.1:22380,infra3=http://127.0.0.1:32380 + initial-cluster-token: etcd-cluster-1 + peer-endpoints: http://127.0.0.1:12380 + peer-advertises: http://127.0.0.1:12380 + workdir: node1.etcd + +* Second instance: + + .. code-block:: yaml + + http.port: 8081 + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + - http://127.0.0.1:22379 + - http://127.0.0.1:32379 + embed: + enabled: true + name: infra2 + endpoints: http://127.0.0.1:22379 + advertises: http://127.0.0.1:22379 + initial-cluster-state: new + initial-cluster: infra1=http://127.0.0.1:12380,infra2=http://127.0.0.1:22380,infra3=http://127.0.0.1:32380 + initial-cluster-token: etcd-cluster-1 + peer-endpoints: http://127.0.0.1:22380 + peer-advertises: http://127.0.0.1:22380 + workdir: node2.etcd + +* Third instance: + + .. code-block:: yaml + + http.port: 8082 + storage: + provider: etcd + etcd: + endpoints: + - http://127.0.0.1:2379 + - http://127.0.0.1:22379 + - http://127.0.0.1:32379 + embed: + enabled: true + name: infra3 + endpoints: http://127.0.0.1:32379 + advertises: http://127.0.0.1:32379 + initial-cluster-state: new + initial-cluster: infra1=http://127.0.0.1:12380,infra2=http://127.0.0.1:22380,infra3=http://127.0.0.1:32380 + initial-cluster-token: etcd-cluster-1 + peer-endpoints: http://127.0.0.1:32380 + peer-advertises: http://127.0.0.1:32380 + workdir: node3.etcd + + +To set up a cluster from embedded Tarantool-based backend stores: + +1. Specify the Tarantool cluster configuration in ``storage.tarantool.embed.config`` + (as a plain text) or ``storage.tarantool.embed.config-file`` (as a YAML file). +2. Assign an instance name from this configuration to each instance using ``storage.tarantool.embed.args`` + to each embedded store. + +Below are example configurations of three |tcm| instances that start with embedded +Tarantool-based backend stores and form a cluster from them: + +* First instance: + + .. code-block:: yaml + + http.port: 8080 + storage: + provider: tarantool + tarantool: + addrs: + - http://127.0.0.1:3301 + - http://127.0.0.1:3302 + - http://127.0.0.1:3303 + embed: + enabled: true + config-filename: config.yml + workdir: node1.tarantool + args: + - --name + - instance-001 + - --config + - config.yml + +* Second instance: + + .. code-block:: yaml + + http.port: 8081 + storage: + provider: tarantool + tarantool: + addrs: + - http://127.0.0.1:3301 + - http://127.0.0.1:3302 + - http://127.0.0.1:3303 + embed: + enabled: true + config-filename: config.yml + workdir: node2.tarantool + args: + - --name + - instance-002 + - --config + - config.yml + +* Third instance: + + .. code-block:: yaml + + http.port: 8082 + storage: + provider: tarantool + tarantool: + addrs: + - http://127.0.0.1:3301 + - http://127.0.0.1:3302 + - http://127.0.0.1:3303 + embed: + enabled: true + config-filename: config.yml + workdir: node3.tarantool + args: + - --name + - instance-003 + - --config + - config.yml \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_cluster_data_access.rst b/doc/tooling/tcm/tcm_cluster_data_access.rst new file mode 100644 index 0000000000..c71ee0f6df --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_data_access.rst @@ -0,0 +1,126 @@ +.. _tcm_cluster_data_access: + +Accessing cluster data +====================== + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides access to data stored in connected clusters through its +web interface. You can view, add, edit, and delete tuples from spaces. + +.. note:: + + A |TCM| user's access to specific clusters and spaces is determined by their + :ref:`cluster permissions ` and :ref:`access control list `. + +Data access is implemented in |tcm| on a per-instance basis: you can access +data stored on one cluster instance at a time. For sharded clusters that use the +`CRUD `__ module, +it's also possible to access data throughout the whole cluster. + +.. _tcm_cluster_data_access_instance: + +Instance data +------------- + +There are the following ways to access data stored on a cluster instance from |tcm|: + +- **Instance explorer** displays the instance's spaces as tables in the web interface +- **SQL terminal** allows executing SQL statements on the instance +- **Tarantool and tt consoles** allow accessing the data using the Lua API + +.. important:: + + Data modification is possible only on instances in the read-write mode (replica set leaders). + Changes are applied to read-only replicas in accordance with the cluster topology. + +.. _tcm_cluster_data_access_instance_explorer: + +Instance explorer +~~~~~~~~~~~~~~~~~ + +The instance explorer provides access to all spaces that exist on the instances +in the web interface. This includes both system and user spaces. + +To open the instance explorer: + +#. Go to **Stateboard**. +#. Click the instance row in the instances list or its graph vertex in the graph view. +#. Click **Explorer** in the **Actions menu** of the instance details page. + +To view tuples of a space, click its row in the spaces list. + +To add a new tuple, click **+** on the space page and provide tuple field values +in the Lua format, for example, ``[ 1, 1000, true, "test"]``. + +To edit a tuple, click it in the table and then click **Edit**. + +To delete a tuple, select it in the table and click **Delete** (the trash bin button). + +In the development mode, you can also create, edit, truncate, and delete spaces +in the instance explorer. To create a space, click **Add** and follow the wizard steps. +To edit, truncate, or remove a space, click the corresponding button in the **Actions** +menu of the space row in the table. + +.. _tcm_cluster_data_access_instance_sql: + +SQL terminal +~~~~~~~~~~~~ + +|tcm| features an SQL terminal that you can use to access stored data. It is located +on the **SQL** tab of the instance details page. In the SQL terminal, you can execute +any :ref:`supported SQL expressions ` on the selected instance. + +For ``select`` SQL queries, you can also download the query result set in the CSV format. + +To learn more about using SQL in Tarantool, see the :ref:`sql_tutorial`. + +.. _tcm_cluster_data_access_instance_lua: + +Lua API: Tarantool and tt consoles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +|tcm| provides interactive access to instances' consoles on the **Terminal** tab +of the instance details page. You can choose between the :ref:`tt console ` +(**TT Connect** tab) and :ref:`Tarantool interactive console ` (**Direct** tab). + +In these consoles, you can access the stored data using the Tarantool :ref:`Lua API `. + +.. _tcm_cluster_data_access_crud: + +Sharded cluster data +-------------------- + +For sharded clusters that use the `CRUD `__ module, +it's possible to access stored data throughout the cluster on the **Cluster** > **Tuples** page. +This page displays only user spaces. + +To view all tuples of a space in a sharded cluster, click the space row in the list. + +To add a new tuple, click **+** on the space page and provide tuple field values +in the Lua format, for example ``[ 1, 1000, true, "test"]``. When you add a tuple +in a sharded cluster, it is distributed to a replica set based on the sharding key +(the ``bucket_id`` field) value. + +To edit a tuple, click it in the table and then click **Edit**. + +To delete a tuple, select it in the table and click **Delete** (the trash bin button). + + +.. _tcm_cluster_data_access_crud_spaces: + +Creating spaces in sharded clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a space in a sharded cluster, create it on all read-write cluster instances +on their :ref:`Instance explorer ` pages. + +.. important:: + + Sharded spaces must include the ``bucket_id`` field of the ``unsigned`` type + and a non-unique index by this field with the same name. + +To edit, truncate, or delete spaces in a sharded cluster, perform the corresponding +action on all read-write cluster instances. diff --git a/doc/tooling/tcm/tcm_cluster_management/index.rst b/doc/tooling/tcm/tcm_cluster_management/index.rst new file mode 100644 index 0000000000..189e583562 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/index.rst @@ -0,0 +1,24 @@ +.. _tcm_cluster_management: + +Cluster management +================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +The main goal of |tcm_full_name| is to provide visual tools for managing +various aspects of Tarantool clusters from the browser. See the pages of this section +to learn how to perform various management operations on Tarantool clusters from |tcm|. + +.. toctree:: + :maxdepth: 1 + + tcm_cluster_state + tcm_cluster_config + tcm_cluster_users + tcm_cluster_security + tcm_cluster_metrics + tcm_supervised_failover + tcm_cluster_migrations + tcm_cluster_tcf \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_config.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_config.rst new file mode 100644 index 0000000000..3b866d0224 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_config.rst @@ -0,0 +1,85 @@ +.. _tcm_configuring_clusters: + +Configuring clusters +==================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| features a built-in text editor for Tarantool EE cluster configurations. + +When you :ref:`connect a cluster ` to |tcm|, it gains access +to the cluster's centralized configuration storage: an etcd or a Tarantool cluster. +|tcm| has both read and write access to the cluster configuration. This enables +the configuration editor to work in two ways: + +* If a configuration already exists, the editor shows its current state. +* When you change the configuration in the editor and apply changes, they + are sent to the configuration storage. + +To learn how to write Tarantool cluster configurations, see :ref:`configuration`. + +.. _tcm_configuring_clusters_manage: + +Managing a cluster's configuration +---------------------------------- + +The configuration editor is available on the **Cluster** > **Configuration** page. + +To start managing a cluster's configuration, select this cluster in the **Cluster** +drop-down and go to the **Configuration** page. + +A cluster configuration in |tcm| can consist of one or multiple YAML files. +When there are multiple files, they are all considered parts of a single cluster +configuration. You can use this for structuring big cluster configurations. +All files that form the configuration of a cluster are listed on the left side +of the **Cluster configuration** page. + +To add a cluster configuration file, click the plus icon (**+**) below the page title. + +To open a configuration file in the editor, click its name in the file list. + +To delete a cluster configuration file, click the **Delete** button beside the filename. + +To download a cluster configuration file, click the **Download** button beside the filename. + +.. warning:: + + All configuration changes are discarded when you leave the **Cluster configuration** page. + :ref:`Save ` the configuration if you want to continue + editing it later or :ref:`apply ` it + to start using it on the cluster. + +.. _tcm_configuring_clusters_save: + +Saving a configuration draft +---------------------------- + +|tcm| can store configurations drafts. If you want to leave an unfinished configuration +and return to it later, save it in |tcm|. Saving applies to whole cluster configurations: +it records the edits of all files, file additions, and file deletions. + +To save a cluster configuration draft after editing, click **Save** in the **Cluster configuration** page. + +All unsaved changes are discarded when you leave the **Cluster configuration** page. + +If you have a saved configuration draft, you can reset the changes for each of its +files individually. A reset returns the file into the state that is currently used +by a cluster (that is, saved in the configuration storage). If you reset a newly +added file, it is deleted. + +To reset a saved configuration file, click the **Reset** button beside the filename. + + +.. _tcm_configuring_clusters_apply: + +Applying a configuration +------------------------ + +When you finish editing a configuration and it's ready to use, apply the updated +configuration to the cluster. To apply a cluster configuration, click **Apply** +on the **Cluster configuration** page. This sends the new configuration to the cluster +configuration storage, and it comes into effect upon the cluster configuration reload. + + diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_metrics.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_metrics.rst new file mode 100644 index 0000000000..77e80c0d03 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_metrics.rst @@ -0,0 +1,59 @@ +.. _tcm_cluster_metrics: + +Viewing cluster metrics +======================= + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +In |tcm_full_name|, you can view metrics of connected clusters in real time on the +**Cluster** > **Cluster metrics** page. The list of metrics that Tarantool exposes +is provided in the :ref:`metrics-reference`. + +Metrics are displayed one by one. To view a metric, select it in the drop-down list +at the top of the page. Then, choose a way to visualize it: + +- **Chart**: a time series chart with the metric values displayed as lines. +- **Table**: a table where the metric values are displayed as numbers in table cells. + +Once you select a metric, |tcm| starts visualizing its current values, updating them +once per second. To pause the visualization, click the button on the left from +the metrics selector. To stop the visualization, clear the metric selection. + + +.. _tcm_cluster_metrics_instance: + +Viewing instance metrics +------------------------ + +To view metrics of a specific instance, find this instance on the **Stateboard**, +click its name, and go to the **Metrics** tab of the instance page. + + +.. _tcm_cluster_metrics_prometheus: + +Monitoring metrics with Prometheus +---------------------------------- + +To allow collecting cluster metrics with external systems, such as Prometheus, +|tcm| provides HTTP endpoints at ``/api/metrics/``. + +.. note:: + + Cluster IDs are shown in the cluster selection dialog that opens when you click + **Cluster** at the top of the left navigation pane. + +To access such an endpoint, a request must be authorized with an :ref:`API token ` +that has a ``cluster.metrics`` permission on the target cluster. + +Below is an example of a Prometheus scrape configuration that collects metrics of +a Tarantool cluster from |tcm|: + +.. code-block:: yaml + + - job_name: "tarantool" + static_configs: + - targets: ["127.0.0.1:8080"] + metrics_path: "/api/metrics/00000000-0000-0000-0000-000000000000" + bearer_token: QgMPZ22JZ3uw7n0QTbqYGAQDmNDs1JnTkhaC1OlQzWM3utmpV78b23GG97zp8YE3 diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_migrations.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_migrations.rst new file mode 100644 index 0000000000..25e7e311c7 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/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 diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_security.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_security.rst new file mode 100644 index 0000000000..01f85bb12d --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_security.rst @@ -0,0 +1,30 @@ +.. _tcm_cluster_security: + +Security settings +================= + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| includes a web interface for managing security settings of connected +clusters. It is available on the **Cluster** > **Security** page. On this page, +you can manage the following security features in the cluster: + +- *Authentication settings*: protocol (CHAP or PAP), number of retries, and + the delay after a failed authentication attempt (:ref:`security.auth_* ` + configuration options). To learn more about Tarantool authentication settings, see :ref:`configuration_authentication`. +- *Password policy*: minimal password length, required characters, expiration + period, and other settings (:ref:`security.password_* ` + configuration options). To learn more about Tarantool password policy, see :ref:`enterprise-password-policy`. +- *Guest access*: whether unauthenticated or :ref:`guest ` + users can connect to cluster (:ref:`security.disable_guest ` + configuration option). +- *Secure erasing*: whether to delete data files securely so that they cannot be restored + (:ref:`security.secure_erasing ` configuration option). +- *Audit log*: configure audit logging in the cluster + (:ref:`audit_log.* ` configuration options). + To learn how to manage audit logging in the cluster, see :ref:`enterprise_audit_module`. + + + diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_state.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_state.rst new file mode 100644 index 0000000000..5216a5c7b0 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_state.rst @@ -0,0 +1,127 @@ +.. _tcm_cluster_state: + +Viewing cluster state +===================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides a visual interface for checking various aspects of connected clusters, +such as: + +* topology +* instance state +* memory usage +* data distribution +* Tarantool versions + +Cluster state information is available on the **Cluster** > **Stateboard** page. + +.. _tcm_cluster_state_topology: + +Cluster topology +---------------- + +The cluster topology is displayed on the **Stateboard** page in one of two forms: +a list or a graph. + +.. _tcm_cluster_state_topology_list: + +List view +~~~~~~~~~ + +The list view of the cluster topology is used by default. In this view, each row contains +the general information about an instance: its current state, memory usage and limit, +and other parameters. + +In the list view, |tcm| additionally displays the Tarantool version information +and instance states on circle diagrams. You can click the sectors of these diagrams +to filter the instances with the selected versions and states. + +To switch to the list view, click the list button on the right of the search bar on the **Stateboard** page. + +.. _tcm_cluster_state_topology_graph: + +Graph view +~~~~~~~~~~ + +The graph view of the cluster topology is shown in a tree-like structure where +leafs are the cluster's instances. Each instance's state is shown by its color. +You can move the graph vertices to arrange them as you like, and zoom in and out, +which is helpful for larger clusters. + +To switch to the graph view, click the graph button on the right of the search bar on the **Stateboard** page. + +.. _tcm_cluster_state_topology_group: + +Instance grouping +~~~~~~~~~~~~~~~~~ + +By default, the cluster topology is shown hierarchically as it's defined in the configuration: +instances are grouped by their replica set, and replica sets are grouped by +their configuration group. + +For better navigation across the cluster, you can adjust the instance grouping. +For example, you can group instances by their roles or custom tags defined in the configuration. +A typical case for such tags is adding a geographical markers to instances. In this case, +you see if issues happen in a specific data center or server. + +To change the instance grouping, click **Group by** in the **Actions** menu on the **Stateboard** page. +Then add or remove grouping criteria. + +.. _tcm_cluster_state_topology_filters: + +Filtering +~~~~~~~~~ + +You can filter the instances shown on the **Stateboard** page using the search bar +at the top. It has predefined filters that select: + +* instances with errors or warnings +* leader or read-only instances +* instances with no issues +* stale instances + +To display all instances, delete the filter applied in the search bar. + +.. _tcm_cluster_state_instance_details: + +Instance details +---------------- + +The general information about the state of cluster instances is shown in the +list view of the cluster topology. Each row contains the information about the instance +status, used and available memory, read-only status, and virtual buckets for sharded +clusters. + +To view the detailed information about an instance or connect to it, click the corresponding +row in the instances list or a vertex of the graph. On the instance page, you can +find: + +* the instance configuration overview +* current state (with warning and error messages if any) +* the detailed Tarantool information returned by the instance introspection functions + from :ref:`box.info `, :ref:`box.stat `, + and other built-in modules +* memory usage by the :ref:`slab allocator ` +* instance users and roles +* stored functions +* instance metrics + +The page also provides Lua and SQL terminals to execute built-in functions +and requests on the instance. You can choose between two Lua terminals: the +:ref:`tt interactive console ` with code completion and highlighting or +the default :ref:`Tarantool console `. + +.. _tcm_cluster_state_urls: + +Linked external services +------------------------ + +When you :ref:`connect a cluster ` to |tcm|, you can specify +URLs of external services linked to this cluster. For example, this can be a Grafana +server that monitors the cluster metrics. + +All the URLs added for a cluster are available for quick access in the **Actions** +menu on the **Stateboard** page. \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_tcf.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_tcf.rst new file mode 100644 index 0000000000..e18c7be0ca --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_tcf.rst @@ -0,0 +1,23 @@ +.. _tcm_cluster_tcf: + +TCF integration +=============== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides a web interface for clusters that run within `Tarantool Clusters Federation `__. +It is available on the **Cluster** > **TCF** page. If a connected cluster is +configured to run in a TCF installation, this page shows information about both +clusters in this installation: their ID's, names, and statuses. To switch cluster +states in TCF, click **Toggle** on the **TCF** page. + +To learn more about Tarantool Clusters Federation, see `its documentation `__. + +.. note:: + + For individual clusters, the **TCF** page is empty. + + + diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_users.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_users.rst new file mode 100644 index 0000000000..be8d48e0b7 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_cluster_users.rst @@ -0,0 +1,88 @@ +.. _tcm_cluster_users: + +Managing cluster users and roles +================================ + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides a visual interface for managing Tarantool users and roles +on connected clusters. + +.. note:: + + This page describes management of :ref:`Tarantool users and roles ` + on instances of connected clusters. To learn to manage |tcm| users, see :ref:`tcm_access_control`. + +The :ref:`Tarantool access model ` defines user access to entities +inside a single instance. Thus, to create or alter a cluster-wide user or role, you need to +do this on all cluster instances. In replication clusters, changes in access model +are possible only on read-write instances (replica set leaders). Changes made on +a leader instance are propagated to all instances of its replica set automatically. + +Operations on the cluster access model are possible only if the :ref:`user ` +that |tcm| uses to connect to the cluster has the privileges to manage users and roles. + +You can also manage Tarantool users and roles from |tcm| using the Lua API +as described in :ref:`access_control`. To do this, connect to instance consoles +from the **Terminal** tab of the instance page. + +.. _tcm_cluster_users_users: + +Managing cluster users +---------------------- + +The tools for managing cluster users are located on the **Users** tab +of the :ref:`instance page `. + +.. important:: + + To ensure the access model consistency across the cluster, repeat all user + management operations on all read-write instances of the cluster. + +To create a user on a cluster: + +#. Go to **Stateboard**. +#. Find a replica set leader in the instances list and click it to open the instance page. +#. Go to the **Users** tab and click **Add user**. + +To edit or delete a user, click the **Edit** or **Delete** button against the username +in the **Users** table. + +To edit a user's privileges: + +#. Click the lock icon against the username in the **Users** table. +#. In the privileges dialog: + + - Click **Add** to grant privileges + - Click **Revoke** (the trash bin icon) to revoke a privilege + +.. _tcm_cluster_users_roles: + +Managing cluster roles +---------------------- + +The tools for managing cluster roles are located on the **Users** tab +of the :ref:`instance page `. + +.. important:: + + To ensure the access model consistency across the cluster, repeat all role + management operations on all read-write instances of the cluster. + +To create a role on a cluster: + +#. Go to **Stateboard**. +#. Find a replica set leader in the instances list and click it to open the instance page. +#. Go to the **Users** tab and click **Add role**. + +To delete a role, click the **Delete** button against the role name in the **Roles** table. + +To edit a role's privileges: + +#. Click the lock icon against the role name in the **Roles** table. +#. In the privileges dialog: + + - Click **Add** to grant privileges + - Click **Revoke** (the trash bin icon) to revoke a privilege diff --git a/doc/tooling/tcm/tcm_cluster_management/tcm_supervised_failover.rst b/doc/tooling/tcm/tcm_cluster_management/tcm_supervised_failover.rst new file mode 100644 index 0000000000..89e599ede8 --- /dev/null +++ b/doc/tooling/tcm/tcm_cluster_management/tcm_supervised_failover.rst @@ -0,0 +1,72 @@ +.. _tcm_supervised_failover: + +Using supervised failover +========================= + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +For Tarantool clusters that use :ref:`supervised failover `, +|tcm_full_name| offers tools for interaction with external failover coordinators from its web interface. + +The tools for using supervised failover are located on the **Failovers** page +available from the **Actions** menu on the cluster stateboard. + +.. note:: + + |tcm| can interact with failover coordinators that are already running. + There is no way to start or stop coordinators from |tcm|. + +.. _tcm_supervised_failover_view: + +Viewing failover coordinators +----------------------------- + +To view failover coordinators running on the cluster, go to the **Failovers** tab. +On this tab, you can see the information about all Tarantool instances that the cluster +uses as failover coordinators. The information includes: + +- Current coordinator status -- ``Active`` or ``Not active`` +- ``PID`` -- process ID +- ``Hostname`` -- the host on which the coordinator is running +- ``UUID`` -- the coordinator ID +- ``Term`` -- a value that defines the order in which coordinators become active + (take the lock) over time. + + +.. _tcm_supervised_failover_commands: + +Executing failover commands +--------------------------- + +To send a failover command to a coordinator, go to the **Commands** tab and click **Add**. +Then, provide the command description in the YAML format. It can include the following +fields: + +- ``command`` -- the command name. Possible value: ``switch`` -- switch master + in a replica set. +- ``new_master`` -- the name of the instance to make the new master. +- ``timeout`` -- the command execution timeout. + +Example: + +.. code-block:: yaml + + command: switch + new_master: instance-002 + timeout: 30 + +After entering the command, click **Save** to send the command for execution. + +Tarantool assigns an id to the command and waits for the active coordinator to process the command. + +All failover commands executed on the cluster are shown on the **Commands** tab with +their ids and statuses. A command can have the following statuses: + +- ``taken`` -- a failover coordinator has started the command execution. +- ``success`` -- the command has completed successfully. +- ``failed`` -- an error occurred during the command execution. + A short error description is shown in the **Reason** field. + +To see the command execution details, click this command in the list. diff --git a/doc/tooling/tcm/tcm_configuration.rst b/doc/tooling/tcm/tcm_configuration.rst new file mode 100644 index 0000000000..93ce3aaad1 --- /dev/null +++ b/doc/tooling/tcm/tcm_configuration.rst @@ -0,0 +1,333 @@ +.. _tcm_configuration: + +Configuration +============= + + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +.. TODO: write specific configuration tutorials for http, security, logging, and so on. (https://github.com/tarantool/doc/issues/3545) + +This topic describes how to configure |tcm_full_name|. For the complete +list of |tcm| configuration parameters, see the :ref:`TCM configuration reference `. + +.. note:: + + To learn about Tarantool cluster configuration, see :ref:`configuration`. + +Configuration structure +----------------------- + +|tcm_full_name| configuration is a set of parameters that define various aspects +of |tcm| functioning. Parameters are grouped by the particular aspect that they +affect. There are the following groups: + +* HTTP +* logging +* configuration storage +* security +* add-ons +* limits +* |tcm| running mode + +Parameter groups can be nested. For example, in the ``http`` group there are +``tls`` and ``websession-cookie`` groups, which define TLS encryption and +cookie settings. + +Parameter names are the full paths from the top-level group to the specific parameter. +For example: + +* ``http.host`` is the ``host`` parameter that is defined directly in the ``http`` group. +* ``http.tls.enabled`` is the ``enabled`` parameter that is defined in the ``tls`` + nested group within ``http``. + +.. _tcm_configuration_ways: + +Ways to pass configuration parameters +------------------------------------- + +There are three ways to pass |tcm| configuration parameters: + +- a YAML file +- environment variables +- command-line options of the |tcm| executable + +.. _tcm_configuration_ways_yaml: + +YAML file +~~~~~~~~~ + +|tcm| configuration can be stored in a YAML file. Its structure must reflect the +configuration parameters hierarchy. + +The example below shows a fragment of a |tcm| configuration file: + +.. code-block:: yaml + + # a fragment of a YAML configuration file + cluster: # top-level group + on-air-limit: 4096 + connection-rate-limit: 512 + tarantool-timeout: 10s + tarantool-ping-timeout: 5s + http: # top-level group + basic-auth: # nested group + enabled: false + network: tcp + host: 127.0.0.1 + port: 8080 + request-size: 1572864 + websocket: # nested group + read-buffer-size: 16384 + write-buffer-size: 16384 + keepalive-ping-interval: 20s + handshake-timeout: 10s + init-timeout: 15s + +To start |tcm| with a YAML configuration, pass the location of the configuration +file in the ``-c`` command-line option: + +.. code-block:: console + + $ tcm -c=config.yml + +.. _tcm_configuration_ways_env: + +Environment variables +~~~~~~~~~~~~~~~~~~~~~ + +|tcm| can take values of its configuration parameters from environment variables. +The variable names start with ``TCM_``. Then goes the full path to the parameter, +converted to upper case. All delimiters are replaced with underscores (``_``). +Examples: + +- ``TCM_HTTP_HOST`` is a variable for the ``http.host`` parameter. +- ``TCM_HTTP_WEBSESSION_COOKIE_NAME`` is a variable for the ``http.websession-cookie.name`` parameter. + +The example below shows how to start |tcm| with configuration parameters passed in +environment variables: + +.. code-block:: console + + $ export TCM_HTTP_HOST=0.0.0.0 + $ export TCM_HTTP_PORT=8888 + $ tcm + +.. _tcm_configuration_ways_cli: + +Command-line arguments +~~~~~~~~~~~~~~~~~~~~~~ + +The |tcm| executable has ``--`` command-line options for each configuration parameter. +Their names reflect the full path to the parameter, with configuration levels separated by +periods (``.``). Examples: + +- ``--http.host`` is an option for ``http.host``. +- ``--http.websession-cookie.name`` is an option for ``http.websession-cookie.name``. + +The example below shows how to start |tcm| with configuration parameters passed in +command-line options: + +.. code-block:: console + + $ tcm --storage.etcd.embed.enabled --addon.enabled --http.host=0.0.0.0 --http.port=8888 + + +.. _tcm_configuration_precedence: + +Configuration precedence +~~~~~~~~~~~~~~~~~~~~~~~~ + +|tcm| configuration options are applied from multiple sources with the following precedence, +from highest to lowest: + +#. ``tcm`` executable arguments. +#. `TCM_*` environment variables. +#. Configuration from a YAML file. + +If the same option is defined in two or more locations, the option with the highest +precedence is applied. For options that aren't defined in any location, the default +values are used. + +You can combine different ways of |tcm| configuration for efficient management of +multiple |tcm| installations: + +- A single YAML file for all installations can contain the common configuration parts. + For example, a single configuration storage that is used for all installations, or + TLS settings. +- Environment variables that set specific parameters for each server, such as + local directories and paths. +- Command-line options for parameters that must be unique for different |tcm| instances + running on a single server. For example, ``http.port``. + +.. _tcm_configuration_types: + +Configuration parameter types +----------------------------- + +|tcm| configuration parameters have the `Go `__ language +types. Note that this is different from the :ref:`Tarantool configuration parameters `, +which have Lua types. + +Most options have the Go's basic types: ``int`` and other numeric types, ``bool``, ``string``. + +.. code-block:: yaml + + http: + basic-auth: + enabled: false # bool + network: tcp # string + host: 127.0.0.1 # string + port: 8080 # int + request-size: 1572864 # int64 + +Parameters that can take multiple values are arrays. In YAML, they are passed as +YAML arrays: each item on a new line, starting with a dash. + +.. code-block:: yaml + + storage: + provider: etcd + etcd: + endpoints: # array + - https://192.168.0.1:2379 # item 1 + - https://192.168.0.2:2379 # item 2 + +.. note:: + + In environment variables and command line options, such arrays are passed as + semicolon-separated strings of items. + +Parameters that set timeouts, TTLs, and other duration values, have the Go's `time.Duration `__ +type. Their values can be passed in time-formatted strings such as ``4h30m25s``. + +.. code-block:: yaml + + cluster: + tarantool-timeout: 10s # duration + tarantool-ping-timeout: 5s # duration + +Finally, there are parameters whose values are constants defined in Go packages. +For example, :ref:`http.websession-cookie.same-site ` +values are constants from the Go's `http.SameSite `__ +type. To find out the exact values available for such parameters, refer to the `Go +packages documentation `__. + +.. code-block:: yaml + + http: + websession-cookie: + same-site: SameSiteStrictMode + +.. _tcm_configuration_template: + +Creating a configuration template +--------------------------------- + +You can create a YAML configuration template for |tcm| with all parameters and +their default values using the ``generate-config`` option of the ``tcm`` executable. + +To write a default |tcm| configuration to the ``tcm.example.yml`` file, run: + +.. code-block:: console + + $ tcm generate-config > tcm.example.yml. + +.. _tcm_configuration_initial: + +Initial settings +---------------- + +You can use YAML configuration files to create entities in |tcm| automatically +upon the first start. These entities are defined in the :ref:`tcm_configuration_reference_initial` +section of the configuration file. + +.. important:: + + The initial settings are applied **only once** upon the first |tcm| start. + Further changes are **not applied** upon |tcm| restarts. + +.. _tcm_configuration_initial_clusters: + +Clusters +~~~~~~~~ + +To add clusters to |tcm| upon the first start, specify their settings in the +:ref:`initial-settings.clusters ` +configuration section. + +The ``initial-settings.clusters`` section is an array whose items describe separate clusters, +for example: + +.. code-block:: yaml + + initial-settings: + clusters: + - name: Cluster 1 + description: First cluster + # cluster settings + - name: Cluster 2 + description: Second cluster + # cluster settings + +In this configuration, you can specify all cluster settings that you define +when :ref:`connecting clusters ` through the |tcm| web interface. +This includes: + +- the cluster name +- description +- additional URLs +- configuration storage connection +- Tarantool instances connection +- and other settings. + +For the full list of cluster configuration parameters, see the :ref:`initial-settings.clusters ` +reference. For example, this is how you add a cluster that uses an etcd configuration +storage: + + +.. code-block:: yaml + + initial-settings: + clusters: + - name: My cluster + description: Cluster description + urls: + - label: Test + url: http://example.com + storage-connection: + provider: etcd + etcd-connection: + endpoints: + - http://127.0.0.1:2379 + username: "" + password: "" + prefix: /cluster1 + tarantool-connection: + username: guest + password: "" + +By default, |tcm| contains a cluster named **Default cluster** with ID +``00000000-0000-0000-0000-000000000000``. You can use this ID to modify +the default cluster settings upon the first |tcm| start. For example, rename it +and add its connection settings: + +.. code-block:: yaml + + initial-settings: + clusters: + - id: 00000000-0000-0000-0000-000000000000 + name: My cluster + storage-connection: + provider: etcd + etcd-connection: + endpoints: + - http://127.0.0.1:2379 + username: etcd-user + password: secret + prefix: /cluster1 + tarantool-connection: + username: guest + password: "" \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_configuration_reference.rst b/doc/tooling/tcm/tcm_configuration_reference.rst new file mode 100644 index 0000000000..21a34d7dab --- /dev/null +++ b/doc/tooling/tcm/tcm_configuration_reference.rst @@ -0,0 +1,2951 @@ +.. _tcm_configuration_reference: + +Configuration reference +======================= + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +This topic describes :ref:`configuration parameters ` of |tcm_full_name|. + +There are the following groups of |tcm| configuration parameters: + +- :ref:`cluster ` +- :ref:`http ` +- :ref:`log ` +- :ref:`storage ` +- :ref:`addon ` +- :ref:`limits ` +- :ref:`security ` +- :ref:`mode ` +- :ref:`initial-settings ` + +.. _tcm_configuration_reference_cluster: + +cluster +------- + +The ``cluster`` group defines parameters of |tcm| interaction with connected +Tarantool clusters. + +- :ref:`connection-rate-limit ` +- :ref:`tarantool-timeout ` +- :ref:`tarantool-ping-timeout ` +- :ref:`tt-command ` +- :ref:`refresh-state-period ` +- :ref:`refresh-state-timeout ` +- :ref:`discovery-period ` +- :ref:`sharding-index ` +- :ref:`skew-time ` +- :ref:`fragmentation-threshold ` + +.. _tcm_configuration_reference_cluster_connection-rate-limit: + +.. confval:: cluster.connection-rate-limit + + A rate limit for connections to Tarantool instances. + + | + | Type: uint + | Default: 512 + | Environment variable: TCM_CLUSTER_CONNECTION_RATE_LIMIT + | Command-line option: ``--cluster.connection-rate-limit`` + +.. _tcm_configuration_reference_cluster_tarantool-timeout: + +.. confval:: cluster.tarantool-timeout + + A timeout for receiving a response from Tarantool instances. + + | + | Type: time.Duration + | Default: 10s + | Environment variable: TCM_CLUSTER_TARANTOOL_TIMEOUT + | Command-line option: ``--cluster.tarantool-timeout`` + +.. _tcm_configuration_reference_cluster_tarantool-ping-timeout: + +.. confval:: cluster.tarantool-ping-timeout + + A timeout for receiving a ping response from Tarantool instances. + + | + | Type: time.Duration + | Default: 5s + | Environment variable: TCM_CLUSTER_TARANTOOL_PING_TIMEOUT + | Command-line option: ``--cluster.tarantool-ping-timeout`` + +.. _tcm_configuration_reference_cluster_tt-command: + +.. confval:: cluster.tt-command + + The command that runs the :ref:`tt ` utility on hosts with cluster instances. + + | + | Type: string + | Default: `tt` + | Environment variable: TCM_CLUSTER_TT_COMMAND + | Command-line option: ``--cluster.tt-command`` + +.. _tcm_configuration_reference_cluster_refresh-state-period: + +.. confval:: cluster.refresh-state-period + + The time interval for refreshing the cluster instances state on the Stateboard. + + | + | Type: time.Duration + | Default: 5s + | Environment variable: TCM_CLUSTER_REFRESH_STATE_PERIOD + | Command-line option: ``--cluster.refresh-state-period`` + +.. _tcm_configuration_reference_cluster_refresh-state-timeout: + +.. confval:: cluster.refresh-state-timeout + + The time limit for refreshing an instance state. + If this limit is reached, an error is shown. + + | + | Type: time.Duration + | Default: 4s + | Environment variable: TCM_CLUSTER_REFRESH_STATE_TIMEOUT + | Command-line option: ``--cluster.refresh-state-timeout`` + +.. _tcm_configuration_reference_cluster_discovery-period: + +.. confval:: cluster.discovery-period + + The time interval for checking the leadership in replica sets. + + | + | Type: time.Duration + | Default: 4s + | Environment variable: TCM_CLUSTER_DISCOVERY_PERIOD + | Command-line option: ``--cluster.discovery-period`` + +.. _tcm_configuration_reference_cluster_sharding-index: + +.. confval:: cluster.sharding-index + + The name of the space field that is used as a sharding key. + + | + | Type: string + | Default: `bucket_id` + | Environment variable: TCM_CLUSTER_SHARDING_INDEX + | Command-line option: ``--cluster.sharding-index`` + +.. _tcm_configuration_reference_cluster_skew-time: + +.. confval:: cluster.skew-time + + The maximum time skew between any two cluster instances. + If this limit is reached, a warning is shown. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_CLUSTER_SKEW_TIME + | Command-line option: ``--cluster.skew-time`` + +.. _tcm_configuration_reference_cluster_fragmentation-threshold: + +.. confval:: cluster.fragmentation-threshold + + The count of allocated slabs that reflects high memory fragmentation. + When this number is reached, a warning is shown. + + See also: :ref:`engines-memtx` + + | + | Type: int + | Default: 40 + | Environment variable: TCM_CLUSTER_FRAGMENTATION_THRESHOLD + | Command-line option: ``--cluster.fragmentation-threshold`` + +.. _tcm_configuration_reference_http: + +http +---- + +The ``http`` group defines parameters of HTTP connections between |tcm| and clients. + +- :ref:`http.network ` +- :ref:`http.host ` +- :ref:`http.port ` +- :ref:`http.request-size ` +- :ref:`http.websocket.read-buffer-size ` +- :ref:`http.websocket.write-buffer-size ` +- :ref:`http.websocket.keepalive-ping-interval ` +- :ref:`http.websocket.handshake-timeout ` +- :ref:`http.websocket.init-timeout ` +- :ref:`http.websession-cookie.name ` +- :ref:`http.websession-cookie.path ` +- :ref:`http.websession-cookie.domain ` +- :ref:`http.websession-cookie.ttl ` +- :ref:`http.websession-cookie.secure ` +- :ref:`http.websession-cookie.http-only ` +- :ref:`http.websession-cookie.same-site ` +- :ref:`http.cors.enabled ` +- :ref:`http.cors.allowed-origins ` +- :ref:`http.cors.allowed-methods ` +- :ref:`http.cors.allowed-headers ` +- :ref:`http.cors.exposed-headers ` +- :ref:`http.cors.allow-credentials ` +- :ref:`http.cors.debug ` +- :ref:`http.tls.enabled ` +- :ref:`http.tls.cert-file ` +- :ref:`http.tls.key-file ` +- :ref:`http.tls.server ` +- :ref:`http.tls.min-version ` +- :ref:`http.tls.max-version ` +- :ref:`http.tls.curve-preferences ` +- :ref:`http.tls.cipher-suites ` +- :ref:`http.read-timeout ` +- :ref:`http.read-header-timeout ` +- :ref:`http.write-timeout ` +- :ref:`http.idle-timeout ` +- :ref:`http.disable-general-options-handler ` +- :ref:`http.max-header-bytes ` +- :ref:`http.api-timeout ` +- :ref:`http.api-update-interval ` +- :ref:`http.frontend-dir ` +- :ref:`http.show-stack-trace ` +- :ref:`http.trace ` +- :ref:`http.max-static-size ` +- :ref:`http.graphql.complexity ` + + +.. _tcm_configuration_reference_http_network: + +.. confval:: http.network + + An addressing scheme that |tcm| uses. + + Possible values: + + - ``tcp``: IPv4 address + - ``tcp6``: IPv6 address + - ``unix``: Unix domain socket + + | + | Type: string + | Default: tcp + | Environment variable: TCM_HTTP_NETWORK + | Command-line option: ``--http.network`` + +.. _tcm_configuration_reference_http_host: + +.. confval:: http.host + + A host name on which |tcm| serves. + + | + | Type: string + | Default: 127.0.0.1 + | Environment variable: TCM_HTTP_HOST + | Command-line option: ``--http.host`` + + +.. _tcm_configuration_reference_http_port: + +.. confval:: http.port + + A port on which |tcm| serves. + + | + | Type: int + | Default: 8080 + | Environment variable: TCM_HTTP_PORT + | Command-line option: ``--http.port`` + + +.. _tcm_configuration_reference_http_request-size: + +.. confval:: http.request-size + + The maximum size (in bytes) of a client HTTP request to |tcm|. + + | + | Type: int64 + | Default: 1572864 + | Environment variable: TCM_HTTP_REQUEST_SIZE + | Command-line option: ``--http.request-size`` + +.. _tcm_configuration_reference_http_websocket_read-buffer-size: + +.. confval:: http.websocket.read-buffer-size + + The size (in bytes) of the read buffer for `WebSocket `__ + connections. + + | + | Type: int + | Default: 16384 + | Environment variable: TCM_HTTP_WEBSOCKET_READ_BUFFER_SIZE + | Command-line option: ``--http.websocket.read-buffer-size`` + +.. _tcm_configuration_reference_http_websocket_write-buffer-size: + +.. confval:: http.websocket.write-buffer-size + + The size (in bytes) of the write buffer for `WebSocket `__ + connections. + + | + | Type: int + | Default: 16384 + | Environment variable: TCM_HTTP_WEBSOCKET_WRITE_BUFFER_SIZE + | Command-line option: ``--http.websocket.write-buffer-size`` + +.. _tcm_configuration_reference_http_websocket_keepalive-ping-interval: + +.. confval:: http.websocket.keepalive-ping-interval + + The time interval for sending `WebSocket `__ + keepalive pings. + + | + | Type: time.Duration + | Default: 20s + | Environment variable: TCM_HTTP_WEBSOCKET_KEEPALIVE_PING_INTERVAL + | Command-line option: ``--http.websocket.keepalive-ping-interval`` + +.. _tcm_configuration_reference_http_websocket_handshake-timeout: + +.. confval:: http.websocket.handshake-timeout + + The time limit for completing a `WebSocket `__ + opening handshake with a client. + + | + | Type: time.Duration + | Default: 10s + | Environment variable: TCM_HTTP_WEBSOCKET_HANDSHAKE_TIMEOUT + | Command-line option: ``--http.websocket.handshake-timeout`` + +.. _tcm_configuration_reference_http_websocket_init-timeout: + +.. confval:: http.websocket.init-timeout + + The time limit for establishing a `WebSocket `__ + connection with a client. + + | + | Type: time.Duration + | Default: 15s + | Environment variable: TCM_HTTP_WEBSOCKET_INIT_TIMEOUT + | Command-line option: ``--http.websocket.init-timeout`` + +.. _tcm_configuration_reference_http_websession-cookie_name: + +.. confval:: http.websession-cookie.name + + The name of the cookie that |tcm| sends to clients. + + This value is used as the cookie name in the `Set-Cookie `__ + HTTP response header. + + | + | Type: string + | Default: tcm + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_NAME + | Command-line option: ``---http.websession-cookie.name`` + +.. _tcm_configuration_reference_http_websession-cookie_path: + +.. confval:: http.websession-cookie.path + + The URL path that must be present in the requested URL in order to send the cookie. + + This value is used in the ``Path`` attribute of the `Set-Cookie `__ + HTTP response header. + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_PATH + | Command-line option: ``---http.websession-cookie.path`` + +.. _tcm_configuration_reference_http_websession-cookie_domain: + +.. confval:: http.websession-cookie.domain + + The domain to which the cookie can be sent. + + This value is used in the ``Domain`` attribute of the `Set-Cookie `__ + HTTP response header. + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_DOMAIN + | Command-line option: ``---http.websession-cookie.domain`` + +.. _tcm_configuration_reference_http_websession-cookie_ttl: + +.. confval:: http.websession-cookie.ttl + + The maximum lifetime of the |tcm| cookie. + + This value is used in the ``Max-Age`` attribute of the `Set-Cookie `__ + HTTP response header. + + | + | Type: time.Duration + | Default: 2h0m0s + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_TTL + | Command-line option: ``---http.websession-cookie.ttl`` + +.. _tcm_configuration_reference_http_websession-cookie_secure: + +.. confval:: http.websession-cookie.secure + + Indicates whether the cookie can be sent only over the HTTPS protocol. + In this case, it's never sent over the unencrypted HTTP, therefore preventing + man-in-the-middle attacks. + + When ``true``, the ``Secure`` attribute is added to the `Set-Cookie `__ + HTTP response header. + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_SECURE + | Command-line option: ``---http.websession-cookie.secure`` + +.. _tcm_configuration_reference_http_websession-cookie_http-only: + +.. confval:: http.websession-cookie.http-only + + Indicates that the cookie can't be accessed from the JavaScript + `Document.cookie `__ API. + This helps mitigate cross-site scripting attacks. + + When ``true``, the ``HttpOnly`` attribute is added to the `Set-Cookie `__ + HTTP response header. + + | + | Type: bool + | Default: true + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_HTTP_ONLY + | Command-line option: ``---http.websession-cookie.http-only`` + +.. _tcm_configuration_reference_http_websession-cookie_same-site: + +.. confval:: http.websession-cookie.same-site + + Indicates if it is possible to send the |tcm| cookie along with cross-site + requests. Possible values are the Go's `http.SameSite `__ constants: + + - ``SameSiteDefaultMode`` + - ``SameSiteLaxMode`` + - ``SameSiteStrictMode`` + - ``SameSiteNoneMode`` + + For details on ``SameSite`` modes, see the `Set-Cookie header documentation `__ + in the MDN web docs. + + This value is used in the ``SameSite`` attribute of the `Set-Cookie `__ + HTTP response header. + + | + | Type: http.SameSite + | Default: SameSiteDefaultMode + | Environment variable: TCM_HTTP_WEBSESSION_COOKIE_SAME_SITE + | Command-line option: ``---http.websession-cookie.same-site`` + +.. _tcm_configuration_reference_http_cors_enabled: + +.. confval:: http.cors.enabled + + Indicates whether to use the `Cross-Origin Resource Sharing `__ + (*CORS*). + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_CORS_ENABLED + | Command-line option: ``--http.cors.enabled`` + +.. _tcm_configuration_reference_http_cors_allowed-origins: + +.. confval:: http.cors.allowed-origins + + The `origins `__ + with which the HTTP response can be shared, separated by semicolons. + + The specified values are sent in the `Access-Control-Allow-Origin `__ + HTTP response headers. + + | + | Type: []string + | Default: [] + | Environment variable: TCM_HTTP_CORS_ALLOWED_ORIGINS + | Command-line option: ``--http.cors.allowed-origins`` + +.. _tcm_configuration_reference_http_cors_allowed-methods: + +.. confval:: http.cors.allowed-methods + + HTTP request methods that are allowed when accessing a resource, + separated by semicolons. + + The specified values are sent in the `Access-Control-Allow-Methods `__ + HTTP header of a response to a `CORS preflight request `__. + + | + | Type: []string + | Default: [] + | Environment variable: TCM_HTTP_CORS_ALLOWED_METHODS + | Command-line option: ``--http.cors.allowed-methods`` + +.. _tcm_configuration_reference_http_cors_allowed-headers: + +.. confval:: http.cors.allowed-headers + + HTTP headers that are allowed during the actual request, separated by semicolons. + + The specified values are sent in the `Access-Control-Allow-Headers `__ + HTTP header of a response to a `CORS preflight request `__. + + | + | Type: []string + | Default: [] + | Environment variable: TCM_HTTP_CORS_ALLOWED_HEADERS + | Command-line option: ``--http.cors.allowed-headers`` + +.. _tcm_configuration_reference_http_cors_exposed-headers: + +.. confval:: http.cors.exposed-headers + + Response headers that should be made available to scripts running in the browser, + in response to a cross-origin request, separated by semicolons. + + The specified values are sent in the `Access-Control-Expose-Headers `__ + HTTP response headers. + + | + | Type: []string + | Default: [] + | Environment variable: TCM_HTTP_CORS_EXPOSED_HEADERS + | Command-line option: ``--http.cors.exposed-headers`` + +.. _tcm_configuration_reference_http_cors_allow-credentials: + +.. confval:: http.cors.allow-credentials + + Whether to expose the response to the frontend JavaScript code when the `request's + credentials `__ + mode is ``include``. + + When ``true``, the `Access-Control-Allow-Credentials `__ + HTTP response header is sent. + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_CORS_ALLOW_CREDENTIALS + | Command-line option: ``--http.cors.allow-credentials`` + +.. _tcm_configuration_reference_http_cors_debug: + +.. confval:: http.cors.debug + + For debug purposes. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_http_tls_enabled: + +.. confval:: http.tls.enabled + + Indicates whether TLS is enabled for client connections to |tcm|. + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_TLS_ENABLED + | Command-line option: ``--http.tls.enabled`` + +.. _tcm_configuration_reference_http_tls_cert-file: + +.. confval:: http.tls.cert-file + + A path to a TLS certificate file. Mandatory when TLS is enabled. + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_TLS_CERT_FILE + | Command-line option: ``--http.tls.cert-file`` + +.. _tcm_configuration_reference_http_tls_key-file: + +.. confval:: http.tls.key-file + + A path to a TLS private key file. Mandatory when TLS is enabled. + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_TLS_KEY_FILE + | Command-line option: ``--http.tls.key-file`` + +.. _tcm_configuration_reference_http_tls_server: + +.. confval:: http.tls.server + + The TLS server. + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_TLS_SERVER + | Command-line option: ``--http.tls.server`` + +.. _tcm_configuration_reference_http_tls_min-version: + +.. confval:: http.tls.min-version + + The minimum version of the TLS protocol. + + | + | Type: uint16 + | Default: 0 + | Environment variable: TCM_HTTP_TLS_MIN_VERSION + | Command-line option: ``--http.tls.min-version`` + +.. _tcm_configuration_reference_http_tls_max-version: + +.. confval:: http.tls.max-version + + The maximum version of the TLS protocol. + + | + | Type: uint16 + | Default: 0 + | Environment variable: TCM_HTTP_TLS_MAX_VERSION + | Command-line option: ``--http.tls.max-version`` + +.. _tcm_configuration_reference_http_tls_curve-preferences: + +.. confval:: http.tls.curve-preferences + + Elliptic curves that are used for TLS connections. + Possible values are the Go's `tls.CurveID `__ constants: + + - ``CurveP256`` + - ``CurveP384`` + - ``CurveP521`` + - ``X25519`` + + | + | Type: []tls.CurveID + | Default: [] + | Environment variable: TCM_HTTP_TLS_CURVE_PREFERENCES + | Command-line option: ``--http.tls.curve-preferences`` + +.. _tcm_configuration_reference_http_tls_cipher-suites: + +.. confval:: http.tls.cipher-suites + + Enabled TLS cipher suites. Possible values are the Golang `tls.TLS_* `__ constants. + + | + | Type: []uint16 + | Default: [] + | Environment variable: TCM_HTTP_TLS_CIPHER_SUITES + | Command-line option: ``--http.tls.cipher-suites`` + +.. _tcm_configuration_reference_http_read-timeout: + +.. confval:: http.read-timeout + + A timeout for reading an incoming request. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_HTTP_READ_TIMEOUT + | Command-line option: ``--http.read-timeout`` + +.. _tcm_configuration_reference_http_read-header-timeout: + +.. confval:: http.read-header-timeout + + A timeout for reading headers of an incoming request. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_HTTP_READ_HEADER_TIMEOUT + | Command-line option: ``--http.read-header-timeout`` + +.. _tcm_configuration_reference_http_write-timeout: + +.. confval:: http.write-timeout + + A timeout for writing a response. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_HTTP_WRITE_TIMEOUT + | Command-line option: ``--http.write-timeout`` + +.. _tcm_configuration_reference_http_idle-timeout: + +.. confval:: http.idle-timeout + + The timeout for idle connections. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_HTTP_IDLE_TIMEOUT + | Command-line option: ``--http.idle-timeout`` + +.. _tcm_configuration_reference_http_disable-general-options-handler: + +.. confval:: http.disable-general-options-handler + + Whether the client requests with the ``OPTIONS`` HTTP method are allowed. + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_DISABLE_GENERAL_OPTIONS_HANDLER + | Command-line option: ``--http.disable-general-options-handler`` + +.. _tcm_configuration_reference_http_max-header-bytes: + +.. confval:: http.max-header-bytes + + The maximum size (in bytes) of a header in a client's request to |TCM|. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_HTTP_MAX_HEADER_BYTES + | Command-line option: ``--http.max-header-bytes`` + +.. _tcm_configuration_reference_http_api-timeout: + +.. confval:: http.api-timeout + + The stateboard update timeout. + + | + | Type: time.Duration + | Default: 8s + | Environment variable: TCM_HTTP_API_TIMEOUT + | Command-line option: ``--http.api-timeout`` + +.. _tcm_configuration_reference_http_api-update-interval: + +.. confval:: http.api-update-interval + + The stateboard update interval. + + | + | Type: time.Duration + | Default: 5s + | Environment variable: TCM_HTTP_API_UPDATE_INTERVAL + | Command-line option: ``--http.api-update-interval`` + +.. _tcm_configuration_reference_http_frontend-dir: + +.. confval:: http.frontend-dir + + The directory with custom |tcm| frontend files (for development purposes). + + | + | Type: string + | Default: "" + | Environment variable: TCM_HTTP_FRONTEND_DIR + | Command-line option: ``--http.frontend-dir`` + +.. _tcm_configuration_reference_http_show-stack-trace: + +.. confval:: http.show-stack-trace + + Whether error stack traces are shown in the web UI. + + | + | Type: bool + | Default: true + | Environment variable: TCM_HTTP_SHOW_STACK_TRACE + | Command-line option: ``--http.show-stack-trace`` + +.. _tcm_configuration_reference_http_trace: + +.. confval:: http.trace + + Whether all query tracing information is written in logs. + + | + | Type: bool + | Default: false + | Environment variable: TCM_HTTP_TRACE + | Command-line option: ``--http.trace`` + +.. _tcm_configuration_reference_http_max-static-size: + +.. confval:: http.max-static-size + + The maximum size (in bytes) of a static content sent to |TCM|. + + | + | Type: int + | Default: 104857600 + | Environment variable: TCM_HTTP_MAX_STATIC_SIZE + | Command-line option: ``--http.max-static-size`` + +.. _tcm_configuration_reference_http_graphql_complexity: + +.. confval:: http.graphql.complexity + + The maximum `complexity `__ of + GraphQL queries that |tcm| processes. If this value is exceeded, |tcm| + returns an error. + + | + | Type: int + | Default: 40 + | Environment variable: TCM_HTTP_GRAPHQL_COMPLEXITY + | Command-line option: ``--http.graphql.complexity`` + + +.. log configuration + +.. _tcm_configuration_reference_log: + +log +--- + +The ``log`` section defines the |tcm| logging parameters. + +- :ref:`log.default.add-source ` +- :ref:`log.default.show-stack-trace ` +- :ref:`log.default.level ` +- :ref:`log.default.format ` +- :ref:`log.default.output ` +- :ref:`log.default.no-colorized ` +- :ref:`log.default.file.name ` +- :ref:`log.default.file.maxsize ` +- :ref:`log.default.file.maxage ` +- :ref:`log.default.file.maxbackups ` +- :ref:`log.default.file.compress ` +- :ref:`log.default.syslog.protocol ` +- :ref:`log.default.syslog.output ` +- :ref:`log.default.syslog.priority ` +- :ref:`log.default.syslog.facility ` +- :ref:`log.default.syslog.tag ` +- :ref:`log.default.syslog.timeout ` +- :ref:`log.outputs ` + +.. _tcm_configuration_reference_log_default_add-source: + +.. confval:: log.default.add-source + + Whether sources are added to the |tcm| log. + + | + | Type: bool + | Default: false + | Environment variable: TCM_LOG_DEFAULT_ADD_SOURCE + | Command-line option: ``--log.default.add-source`` + +.. _tcm_configuration_reference_log_default_show-stack-trace: + +.. confval:: log.default.show-stack-trace + + Whether stack traces are added to the |tcm| log. + + | + | Type: bool + | Default: false + | Environment variable: TCM_LOG_DEFAULT_SHOW_STACK_TRACE + | Command-line option: ``--log.default.show-stack-trace`` + +.. _tcm_configuration_reference_log_default_level: + +.. confval:: log.default.level + + The default |tcm| logging level. + + Possible values: + + * ``VERBOSE`` + * ``INFO`` + * ``WARN`` + * ``ALARM`` + + | + | Type: string + | Default: INFO + | Environment variable: TCM_LOG_DEFAULT_LEVEL + | Command-line option: ``--log.default.level`` + +.. _tcm_configuration_reference_log_default_format: + +.. confval:: log.default.format + + |tcm| log entries format. + + Possible values: + + * ``struct`` + * ``json`` + + | + | Type: string + | Default: struct + | Environment variable: TCM_LOG_DEFAULT_FORMAT + | Command-line option: ``--log.default.format`` + +.. _tcm_configuration_reference_log_default_output: + +.. confval:: log.default.output + + The output used for |tcm| log. + + Possible values: + + * ``stdout`` + * ``stderr`` + * ``file`` + * ``syslog`` + + | + | Type: string + | Default: stdout + | Environment variable: TCM_LOG_DEFAULT_OUTPUT + | Command-line option: ``--log.default.output`` + +.. _tcm_configuration_reference_log_default_no-colorized: + +.. confval:: log.default.no-colorized + + Whether the stdout log is not colorized. + + | + | Type: bool + | Default: false + | Environment variable: TCM_LOG_DEFAULT_NO_COLORIZED + | Command-line option: ``--log.default.no-colorized`` + +.. _tcm_configuration_reference_log_default_file_name: + +.. confval:: log.default.file.name + + The name of the |tcm| log file. + + | + | Type: string + | Default: "" + | Environment variable: TCM_LOG_DEFAULT_FILE_NAME + | Command-line option: ``--log.default.file.name`` + +.. _tcm_configuration_reference_log_default_file_maxsize: + +.. confval:: log.default.file.maxsize + + The maximum size (in bytes) of the |tcm| log file. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_LOG_DEFAULT_FILE_MAXSIZE + | Command-line option: ``--log.default.file.maxsize`` + +.. _tcm_configuration_reference_log_default_file_maxage: + +.. confval:: log.default.file.maxage + + The maximum age of a |tcm| log file, in days. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_LOG_DEFAULT_FILE_MAXAGE + | Command-line option: ``--log.default.file.maxage`` + +.. _tcm_configuration_reference_log_default_file_maxbackups: + +.. confval:: log.default.file.maxbackups + + The maximum number of users in |tcm|. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_LOG_DEFAULT_FILE_MAXBACKUPS + | Command-line option: ``--log.default.file.maxbackups`` + +.. _tcm_configuration_reference_log_default_file_compress: + +.. confval:: log.default.file.compress + + Indicated that |tcm| compresses log files upon rotation. + + | + | Type: bool + | Default: false + | Environment variable: TCM_LOG_DEFAULT_FILE_COMPRESS + | Command-line option: ``--log.default.file.compress`` + +.. _tcm_configuration_reference_log_default_syslog_protocol: + +.. confval:: log.default.syslog.protocol + + The network protocol used for connecting to the syslog server. Typically, + it's ``tcp``, ``udp``, or ``unix``. All possible values are listed in the Go's + `net.Dial `__ documentation. + + | + | Type: string + | Default: tcp + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_PROTOCOL + | Command-line option: ``--log.default.syslog.protocol`` + +.. _tcm_configuration_reference_log_default_syslog_output: + +.. confval:: log.default.syslog.output + + The syslog server URI. + + | + | Type: string + | Default: 127.0.0.1:5514 + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_OUTPUT + | Command-line option: ``--log.default.syslog.output`` + +.. _tcm_configuration_reference_log_default_syslog_priority: + +.. confval:: log.default.syslog.priority + + The syslog severity level. + + | + | Type: string + | Default: "" + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_PRIORITY + | Command-line option: ``--log.default.syslog.priority`` + +.. _tcm_configuration_reference_log_default_syslog_facility: + +.. confval:: log.default.syslog.facility + + The syslog facility. + + | + | Type: string + | Default: "" + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_FACILITY + | Command-line option: ``--log.default.syslog.facility`` + +.. _tcm_configuration_reference_log_default_syslog_tag: + +.. confval:: log.default.syslog.tag + + The syslog tag. + + | + | Type: string + | Default: "" + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_TAG + | Command-line option: ``--log.default.syslog.tag`` + +.. _tcm_configuration_reference_log_default_syslog_timeout: + +.. confval:: log.default.syslog.timeout + + The timeout for connecting to the syslog server. + + | + | Type: time.Duration + | Default: 10s + | Environment variable: TCM_LOG_DEFAULT_SYSLOG_TIMEOUT + | Command-line option: ``--log.default.syslog.timeout`` + +.. _tcm_configuration_reference_log_outputs: + +.. confval:: log.outputs + + An array of log outputs that |tcm| uses **in addition** to the default one + that is defined by the ``log.default.*`` parameters. Each array item can include + the parameters of the ``log.default`` group. If a parameter is skipped, its + value is taken from ``log.default``. + + | + | Type: []LogOuputConfig + | Default: [] + | Environment variable: TCM_LOG_OUTPUTS + | Command-line option: ``--log-outputs`` + + +.. storage configuration + +.. _tcm_configuration_reference_storage: + +storage +------- + +The ``storage`` section defines the parameters of the |tcm| :ref:`backend store `. + +- :ref:`storage.provider ` + +etcd backend store parameters: + +- :ref:`storage.etcd.prefix ` +- :ref:`storage.etcd.endpoints ` +- :ref:`storage.etcd.dial-timeout ` +- :ref:`storage.etcd.auto-sync-interval ` +- :ref:`storage.etcd.dial-keep-alive-time ` +- :ref:`storage.etcd.dial-keep-alive-timeout ` +- :ref:`storage.etcd.bootstrap-timeout ` +- :ref:`storage.etcd.max-call-send-msg-size ` +- :ref:`storage.etcd.username ` +- :ref:`storage.etcd.password ` +- :ref:`storage.etcd.password-file ` +- :ref:`storage.etcd.tls.enabled ` +- :ref:`storage.etcd.tls.auto ` +- :ref:`storage.etcd.tls.cert-file ` +- :ref:`storage.etcd.tls.key-file ` +- :ref:`storage.etcd.tls.trusted-ca-file ` +- :ref:`storage.etcd.tls.client-cert-auth ` +- :ref:`storage.etcd.tls.crl-file ` +- :ref:`storage.etcd.tls.insecure-skip-verify ` +- :ref:`storage.etcd.tls.skip-client-san-verify ` +- :ref:`storage.etcd.tls.server-name ` +- :ref:`storage.etcd.tls.cipher-suites ` +- :ref:`storage.etcd.tls.allowed-cn ` +- :ref:`storage.etcd.tls.allowed-hostname ` +- :ref:`storage.etcd.tls.empty-cn ` +- :ref:`storage.etcd.permit-without-stream ` +- :ref:`storage.etcd.embed.enabled ` +- :ref:`storage.etcd.embed.endpoints ` +- :ref:`storage.etcd.embed.advertises ` +- :ref:`storage.etcd.embed.tls.enabled ` +- :ref:`storage.etcd.embed.tls.auto ` +- :ref:`storage.etcd.embed.tls.cert-file ` +- :ref:`storage.etcd.embed.tls.key-file ` +- :ref:`storage.etcd.embed.tls.trusted-ca-file ` +- :ref:`storage.etcd.embed.tls.client-cert-auth ` +- :ref:`storage.etcd.embed.tls.crl-file ` +- :ref:`storage.etcd.embed.tls.insecure-skip-verify ` +- :ref:`storage.etcd.embed.tls.skip-client-san-verify ` +- :ref:`storage.etcd.embed.tls.server-name ` +- :ref:`storage.etcd.embed.tls.cipher-suites ` +- :ref:`storage.etcd.embed.tls.allowed-cn ` +- :ref:`storage.etcd.embed.tls.allowed-hostname ` +- :ref:`storage.etcd.embed.tls.empty-cn ` +- :ref:`storage.etcd.embed.peer-endpoints ` +- :ref:`storage.etcd.embed.peer-advertises ` +- :ref:`storage.etcd.embed.peer-tls.enabled ` +- :ref:`storage.etcd.embed.peer-tls.auto ` +- :ref:`storage.etcd.embed.peer-tls.cert-file ` +- :ref:`storage.etcd.embed.peer-tls.key-file ` +- :ref:`storage.etcd.embed.peer-tls.trusted-ca-file ` +- :ref:`storage.etcd.embed.peer-tls.client-cert-auth ` +- :ref:`storage.etcd.embed.peer-tls.crl-file ` +- :ref:`storage.etcd.embed.peer-tls.insecure-skip-verify ` +- :ref:`storage.etcd.embed.peer-tls.skip-client-san-verify ` +- :ref:`storage.etcd.embed.peer-tls.server-name ` +- :ref:`storage.etcd.embed.peer-tls.cipher-suites ` +- :ref:`storage.etcd.embed.peer-tls.allowed-cn ` +- :ref:`storage.etcd.embed.peer-tls.allowed-hostname ` +- :ref:`storage.etcd.embed.peer-tls.empty-cn ` +- :ref:`storage.etcd.embed.grpc-keep-alive-timeout ` +- :ref:`storage.etcd.embed.grpc-keep-alive-interval ` +- :ref:`storage.etcd.embed.grpc-keep-alive-min-time ` +- :ref:`storage.etcd.embed.workdir ` +- :ref:`storage.etcd.embed.waldir ` +- :ref:`storage.etcd.embed.max-request-bytes ` +- :ref:`storage.etcd.embed.debug ` +- :ref:`storage.etcd.embed.start-timeout ` +- :ref:`storage.etcd.embed.log-level ` +- :ref:`storage.etcd.embed.initial-cluster ` +- :ref:`storage.etcd.embed.initial-cluster-token ` +- :ref:`storage.etcd.embed.name ` +- :ref:`storage.etcd.embed.initial-cluster-state ` +- :ref:`storage.etcd.embed.self-signed-cert-validity ` + +Tarantool backend store parameters: + +- :ref:`storage.tarantool.prefix ` +- :ref:`storage.tarantool.addr ` +- :ref:`storage.tarantool.addrs ` +- :ref:`storage.tarantool.auth ` +- :ref:`storage.tarantool.timeout ` +- :ref:`storage.tarantool.reconnect ` +- :ref:`storage.tarantool.max-reconnects ` +- :ref:`storage.tarantool.username ` +- :ref:`storage.tarantool.password ` +- :ref:`storage.tarantool.password-file ` +- :ref:`storage.tarantool.rate-limit ` +- :ref:`storage.tarantool.rate-limit-action ` +- :ref:`storage.tarantool.concurrency ` +- :ref:`storage.tarantool.skip-schema ` +- :ref:`storage.tarantool.transport ` +- :ref:`storage.tarantool.ssl.key-file ` +- :ref:`storage.tarantool.ssl.cert-file ` +- :ref:`storage.tarantool.ssl.ca-file ` +- :ref:`storage.tarantool.ssl.ciphers ` +- :ref:`storage.tarantool.ssl.password ` +- :ref:`storage.tarantool.ssl.password-file ` +- :ref:`storage.tarantool.required-protocol-info.auth ` +- :ref:`storage.tarantool.required-protocol-info.version ` +- :ref:`storage.tarantool.required-protocol-info.features ` +- :ref:`storage.tarantool.embed.enabled ` +- :ref:`storage.tarantool.embed.workdir ` +- :ref:`storage.tarantool.embed.executable ` +- :ref:`storage.tarantool.embed.config-filename ` +- :ref:`storage.tarantool.embed.config ` +- :ref:`storage.tarantool.embed.args ` +- :ref:`storage.tarantool.embed.env ` + + +.. _tcm_configuration_reference_storage_provider: + +.. confval:: storage.provider + + The type of the storage used for storing |tcm| configuration. + + Possible values: + + - ``etcd`` + - ``tarantool`` + + | + | Type: string + | Default: etcd + | Environment variable: TCM_STORAGE_PROVIDER + | Command-line option: ``--storage.provider`` + +.. _tcm_configuration_reference_storage_etcd_prefix: + +.. confval:: storage.etcd.prefix + + A prefix for the |tcm| configuration parameters in etcd. + + | + | Type: string + | Default: "/tcm" + | Environment variable: TCM_STORAGE_ETCD_PREFIX + | Command-line option: ``--storage.etcd.prefix`` + + +.. _tcm_configuration_reference_storage_etcd_endpoints: + +.. confval:: storage.etcd.endpoints + + An array of node URIs of the etcd cluster where the |tcm| configuration is stored, + separated by semicolons (``;``). + + | + | Type: []string + | Default: ["http://127.0.0.1:2379"] + | Environment variable: TCM_STORAGE_ETCD_ENDPOINTS + | Command-line option: ``--storage.etcd.endpoints`` + + +.. _tcm_configuration_reference_storage_etcd_dial-timeout: + +.. confval:: storage.etcd.dial-timeout + + An etcd dial timeout. + + | + | Type: time.Duration + | Default: 10s + | Environment variable: TCM_STORAGE_ETCD_DIAL_TIMEOUT + | Command-line option: ``--storage.etcd.dial-timeout`` + +.. _tcm_configuration_reference_storage_etcd_auto-sync-interval: + +.. confval:: storage.etcd.auto-sync-interval + + An automated sync interval. + + | + | Type: time.Duration + | Default: 0 (disabled) + | Environment variable: TCM_STORAGE_ETCD_AUTO_SYNC_INTERVAL + | Command-line option: ``--storage.etcd.auto-sync-interval`` + +.. _tcm_configuration_reference_storage_etcd_dial-keep-alive-time: + +.. confval:: storage.etcd.dial-keep-alive-time + + A dial keep-alive time. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_STORAGE_ETCD_DIAL_KEEP_ALIVE_TIME + | Command-line option: ``--storage.etcd.dial-keep-alive-time`` + +.. _tcm_configuration_reference_storage_etcd_dial-keep-alive-timeout: + +.. confval:: storage.etcd.dial-keep-alive-timeout + + A dial keep-alive timeout. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_STORAGE_ETCD_DIAL_KEEP_ALIVE_TIMEOUT + | Command-line option: ``--storage.etcd.dial-keep-alive-timeout`` + +.. _tcm_configuration_reference_storage_etcd_bootstrap-timeout: + +.. confval:: storage.etcd.bootstrap-timeout + + A bootstrap timeout. + + | + | Type: time.Duration + | Default: 30s + | Environment variable: TCM_STORAGE_ETCD_BOOTSTRAP_TIMEOUT + | Command-line option: ``--storage.etcd.bootstrap-timeout`` + +.. _tcm_configuration_reference_storage_etcd_max-call-send-msg-size: + +.. confval:: storage.etcd.max-call-send-msg-size + + The maximum size (in bytes) of a transaction between |tcm| and etcd. + + | + | Type: int + | Default: 2097152 + | Environment variable: TCM_STORAGE_ETCD_MAX_CALL_SEND_MSG_SIZE + | Command-line option: ``--storage.etcd.max-call-send-msg-size`` + +.. _tcm_configuration_reference_storage_etcd_username: + +.. confval:: storage.etcd.username + + A username for accessing the etcd storage. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_USERNAME + | Command-line option: ``--storage.etcd.username`` + +.. _tcm_configuration_reference_storage_etcd_password: + +.. confval:: storage.etcd.password + + A password for accessing the etcd storage. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_PASSWORD + | Command-line option: ``--storage.etcd.password`` + +.. _tcm_configuration_reference_storage_etcd_password-file: + +.. confval:: storage.etcd.password-file + + A path to the file with a password for accessing the etcd storage. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_PASSWORD_FILE + | Command-line option: ``--storage.etcd.password-file`` + +.. _tcm_configuration_reference_storage_etcd_tls_enabled: + +.. confval:: storage.etcd.tls.enabled + + Indicates whether TLS is enabled for etcd connections. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_ENABLED + | Command-line option: ``--storage.etcd.tls.enabled`` + +.. _tcm_configuration_reference_storage_etcd_tls_auto: + +.. confval:: storage.etcd.tls.auto + + Use generated certificates for etcd connections. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_AUTO + | Command-line option: ``--storage.etcd.tls.auto`` + +.. _tcm_configuration_reference_storage_etcd_tls_cert-file: + +.. confval:: storage.etcd.tls.cert-file + + A path to a TLS certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_CERT_FILE + | Command-line option: ``--storage.etcd.tls.cert-file`` + +.. _tcm_configuration_reference_storage_etcd_tls_key-file: + +.. confval:: storage.etcd.tls.key-file + + A path to a TLS private key file to use for etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_KEY_FILE + | Command-line option: ``--storage.etcd.tls.key-file`` + +.. _tcm_configuration_reference_storage_etcd_tls_trusted-ca-file: + +.. confval:: storage.etcd.tls.trusted-ca-file + + A path to a trusted CA certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_TRUSTED_CA_FILE + | Command-line option: ``--storage.etcd.tls.trusted-ca-file`` + +.. _tcm_configuration_reference_storage_etcd_tls_client-cert-auth: + +.. confval:: storage.etcd.tls.client-cert-auth + + Indicates whether client cert authentication is enabled. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_CLIENT_CERT_AUTH + | Command-line option: ``--storage.etcd.tls.client-cert-auth`` + +.. _tcm_configuration_reference_storage_etcd_tls_crl-file: + +.. confval:: storage.etcd.tls.crl-file + + A path to the client certificate revocation list file. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_CRL_FILE + | Command-line option: ``--storage.etcd.tls.crl-file`` + +.. _tcm_configuration_reference_storage_etcd_tls_insecure-skip-verify: + +.. confval:: storage.etcd.tls.insecure-skip-verify + + Skip checking client certificate in etcd connections. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_INSECURE_SKIP_VERIFY + | Command-line option: ``--storage.etcd.tls.insecure-skip-verify`` + +.. _tcm_configuration_reference_storage_etcd_tls_skip-client-san-verify: + +.. confval:: storage.etcd.tls.skip-client-san-verify + + Skip verification of SAN field in client certificate for etcd connections. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_SKIP_CLIENT_SAN_VERIFY + | Command-line option: ``--storage.etcd.tls.skip-client-san-verify`` + +.. _tcm_configuration_reference_storage_etcd_tls_server-name: + +.. confval:: storage.etcd.tls.server-name + + Name of the TLS server for etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_SERVER_NAME + | Command-line option: ``--storage.etcd.tls.server-name`` + +.. _tcm_configuration_reference_storage_etcd_tls_cipher-suites: + +.. confval:: storage.etcd.tls.cipher-suites + + TLS cipher suites for etcd connections. Possible values are the Golang `tls.TLS_* `__ constants. + + | + | Type: []uint16 + | Default: [] + | Environment variable: TCM_STORAGE_ETCD_TLS_CIPHER_SUITES + | Command-line option: ``--storage.etcd.tls.cipher-suites`` + +.. _tcm_configuration_reference_storage_etcd_tls_allowed-cn: + +.. confval:: storage.etcd.tls.allowed-cn + + An allowed common name for authentication in etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_ALLOWED_CN + | Command-line option: ``--storage.etcd.tls.allowed-cn`` + +.. _tcm_configuration_reference_storage_etcd_tls_allowed-hostname: + +.. confval:: storage.etcd.tls.allowed-hostname + + An allowed TLS certificate name for authentication in etcd connections. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_ETCD_TLS_ALLOWED_HOSTNAME + | Command-line option: ``--storage.etcd.tls.allowed-hostname`` + +.. _tcm_configuration_reference_storage_etcd_tls_empty-cn: + +.. confval:: storage.etcd.tls.empty-cn + + Whether the empty common name is allowed in etcd connections. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_TLS_EMPTY_CN + | Command-line option: ``--storage.etcd.tls.empty-cn`` + +.. _tcm_configuration_reference_storage_etcd_permit-without-stream: + +.. confval:: storage.etcd.permit-without-stream + + Whether keepalive pings can be send to the etcd server without active streams. + + | + | Type: bool + | Default: false + | Environment variable: TCM_STORAGE_ETCD_PERMIT_WITHOUT_STREAM + | Command-line option: ``--storage.etcd.permit-without-stream`` + +.. _tcm_configuration_reference_storage_etcd_embed: + +storage.etcd.embed.* +~~~~~~~~~~~~~~~~~~~~ + +The ``storage.etcd.embed`` group defines the configuration of the embedded etcd +cluster to use as a |tcm| backend store. +This cluster can be used for development purposes when the production or testing +etcd cluster is not available or not needed. + +See also :ref:`tcm_backend_store_embed`. + +.. _tcm_configuration_reference_storage_tarantool_prefix: + +.. confval:: storage.tarantool.prefix + + A prefix for the |tcm| configuration parameters in the Tarantool-based configuration storage. + + | + | Type: string + | Default: "/tcm" + | Environment variable: TCM_STORAGE_TARANTOOL_PREFIX + | Command-line option: ``--storage.tarantool.prefix`` + + +.. _tcm_configuration_reference_storage_tarantool_addr: + +.. confval:: storage.tarantool.addr + + The URI for connecting to the Tarantool-based configuration storage. + + | + | Type: string + | Default: "unix/:/tmp/tnt_config_instance.sock" + | Environment variable: TCM_STORAGE_TARANTOOL_ADDR + | Command-line option: ``--storage.tarantool.addr`` + +.. _tcm_configuration_reference_storage_tarantool_addrs: + +.. confval:: storage.tarantool.addrs + + An array of the Tarantool-based configuration storage URIs. + + | + | Type: []string + | Default: ["unix/:/tmp/tnt_config_instance.sock"] + | Environment variable: TCM_STORAGE_TARANTOOL_ADDRS + | Command-line option: ``--storage.tarantool.addrs`` + + +.. _tcm_configuration_reference_storage_tarantool_auth: + +.. confval:: storage.tarantool.auth + + An authentication method for the Tarantool-based configuration storage. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_AUTH + | Command-line option: ``--storage.tarantool.auth`` + + +.. _tcm_configuration_reference_storage_tarantool_timeout: + +.. confval:: storage.tarantool.timeout + + A request timeout for the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: time.Duration + | Default: 0s + | Environment variable: TCM_STORAGE_TARANTOOL_TIMEOUT + | Command-line option: ``--storage.tarantool.timeout`` + +.. _tcm_configuration_reference_storage_tarantool_reconnect: + +.. confval:: storage.tarantool.reconnect + + A timeout between reconnect attempts for the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: time.Duration + | Default: 0s + | Environment variable: TCM_STORAGE_TARANTOOL_RECONNECT + | Command-line option: ``--storage.tarantool.reconnect`` + +.. _tcm_configuration_reference_storage_tarantool_max-reconnects: + +.. confval:: storage.tarantool.max-reconnects + + The maximum number of reconnect attempts for the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_MAX_RECONNECTS + | Command-line option: ``--storage.tarantool.max-reconnects`` + +.. _tcm_configuration_reference_storage_tarantool_user: +.. _tcm_configuration_reference_storage_tarantool_username: + +.. confval:: storage.tarantool.username + + A username for connecting to the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_USERNAME + | Command-line option: ``--storage.tarantool.username`` + +.. _tcm_configuration_reference_storage_tarantool_pass: +.. _tcm_configuration_reference_storage_tarantool_password: + +.. confval:: storage.tarantool.password + + A password for connecting to the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_PASSWORD + | Command-line option: ``--storage.tarantool.password`` + +.. _tcm_configuration_reference_storage_tarantool_password-file: + +.. confval:: storage.tarantool.password-file + + A path to the file with a password for connecting to the Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_PASSWORD_FILE + | Command-line option: ``--storage.tarantool.password-file`` + +.. _tcm_configuration_reference_storage_tarantool_rate-limit: + +.. confval:: storage.tarantool.rate-limit + + A rate limit for connecting to the Tarantool-based configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_RATE_LIMIT + | Command-line option: ``--storage.tarantool.rate-limit`` + +.. _tcm_configuration_reference_storage_tarantool_rate-limit-action: + +.. confval:: storage.tarantool.rate-limit-action + + An action to perform when the :ref:`storage.tarantool.rate-limit ` is reached. + + See also `go-tarantool.Opts `__. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_RATE_LIMIT_ACTION + | Command-line option: ``--storage.tarantool.rate-limit-action`` + + +.. _tcm_configuration_reference_storage_tarantool_concurrency: + +.. confval:: storage.tarantool.concurrency + + An amount of separate mutexes for request queues and buffers inside of a connection + to the Tarantool |tcm| configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_CONCURRENCY + | Command-line option: ``--storage.tarantool.concurrency`` + +.. _tcm_configuration_reference_storage_tarantool_skip-schema: + +.. confval:: storage.tarantool.skip-schema + + Whether the schema is loaded from the Tarantool |tcm| configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: bool + | Default: true + | Environment variable: TCM_STORAGE_TARANTOOL_SKIP_SCHEMA + | Command-line option: ``--storage.tarantool.skip-schema`` + +.. _tcm_configuration_reference_storage_tarantool_transport: + +.. confval:: storage.tarantool.transport + + The connection type for the Tarantool |tcm| configuration storage. + + See also `go-tarantool.Opts `__. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_TRANSPORT + | Command-line option: ``--storage.tarantool.transport`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_key-file: + +.. confval:: storage.tarantool.ssl.key-file + + A path to a TLS private key file to use for connecting to the Tarantool |tcm| + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_KEY_FILE + | Command-line option: ``--storage.tarantool.ssl.key-file`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_cert-file: + +.. confval:: storage.tarantool.ssl.cert-file + + A path to an SSL certificate to use for connecting to the Tarantool |tcm| + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_CERT_FILE + | Command-line option: ``--storage.tarantool.ssl.cert-file`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_ca-file: + +.. confval:: storage.tarantool.ssl.ca-file + + A path to a trusted CA certificate to use for connecting to the Tarantool |tcm| + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_CA_FILE + | Command-line option: ``--storage.tarantool.ssl.ca-file`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_ciphers: + +.. confval:: storage.tarantool.ssl.ciphers + + A list of SSL cipher suites that can be used for connecting to the Tarantool |tcm| + configuration storage. Possible values are listed in :ref:`.params.ssl_ciphers `. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_CIPHERS + | Command-line option: ``--storage.tarantool.ssl.ciphers`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_password: + +.. confval:: storage.tarantool.ssl.password + + A password for an encrypted private SSL key to use for connecting to the Tarantool |tcm| + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_PASSWORD + | Command-line option: ``--storage.tarantool.ssl.password`` + +.. _tcm_configuration_reference_storage_tarantool_ssl_password-file: + +.. confval:: storage.tarantool.ssl.password-file + + A text file with passwords for encrypted private SSL keys to use + for connecting to the Tarantool |tcm| configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_PASSWORD_FILE + | Command-line option: ``--storage.tarantool.ssl.password-file`` + +.. _tcm_configuration_reference_storage_tarantool_required-protocol-info_auth: + +.. confval:: storage.tarantool.required-protocol-info.auth + + An authentication method for the Tarantool |tcm| configuration storage. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + See also `go-tarantool.ProtocolInfo `__. + + | + | Type: int + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_REQUIRED_PROTOCOL_INFO_AUTH + | Command-line option: ``--storage.tarantool.required-protocol-info.auth`` + +.. _tcm_configuration_reference_storage_tarantool_required-protocol-info_version: + +.. confval:: storage.tarantool.required-protocol-info.version + + A Tarantool protocol version. + + See also `go-tarantool.ProtocolInfo `__. + + | + | Type: uint64 + | Default: 0 + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_REQUIRED_PROTOCOL_INFO_VERSION + | Command-line option: ``--storage.tarantool.required-protocol-info.version`` + +.. _tcm_configuration_reference_storage_tarantool_required-protocol-info_features: + +.. confval:: storage.tarantool.required-protocol-info.features + + An array of Tarantool protocol features. + + See also `go-tarantool.ProtocolInfo `__. + + | + | Type: []int + | Default: [] + | Environment variable: TCM_STORAGE_TARANTOOL_SSL_REQUIRED_PROTOCOL_INFO_FEATURES + | Command-line option: ``--storage.tarantool.required-protocol-info.features`` + +.. _tcm_configuration_reference_storage_tarantool_embed: + +storage.tarantool.embed.* +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``storage.tarantool.embed`` group parameters define the configuration of the +embedded Tarantool cluster to use as a |tcm| backend store. +This cluster can be used for development purposes when the production or testing +cluster is not available or not needed. + +See also :ref:`tcm_backend_store_embed`. + +.. _tcm_configuration_reference_addon: + +addon +----- + +The ``addon`` section defines settings related to |tcm| add-ons. + +- :ref:`addon.enabled ` +- :ref:`addon.addons-dir ` +- :ref:`addon.max-upload-size ` +- :ref:`addon.dev-addons-dir ` + +.. _tcm_configuration_reference_addon_enabled: + +.. confval:: addon.enabled + + Whether to enable the add-on functionality in |tcm|. + + | + | Type: bool + | Default: false + | Environment variable: TCM_ADDON_ENABLED + | Command-line option: ``--addon.enabled`` + +.. _tcm_configuration_reference_addon_addons-dir: + +.. confval:: addon.addons-dir + + The directory from which |tcm| takes add-ons. + + | + | Type: string + | Default: addons + | Environment variable: TCM_ADDON_ADDONS_DIR + | Command-line option: ``--addon.addons-dir`` + +.. _tcm_configuration_reference_addon_max-upload-size: + +.. confval:: addon.max-upload-size + + The maximum size (in bytes) of addon to upload to |tcm|. + + | + | Type: int64 + | Default: 104857600 + | Environment variable: TCM_ADDON_MAX_UPLOAD_SIZE + | Command-line option: ``--addon.max-upload-size`` + +.. _tcm_configuration_reference_addon_dev-addons-dir: + +.. confval:: addon.dev-addons-dir + + Additional add-on directories for development purposes, separated by semicolons (``;``). + + | + | Type: []string + | Default: [] + | Environment variable: TCM_ADDON_DEV_ADDONS_DIR + | Command-line option: ``--addon.dev-addons-dir`` + +.. limits configuration + +.. _tcm_configuration_reference_limits: + +limits +------ + +The ``limits`` section defines limits on various |tcm| objects and relations +between them. + +- :ref:`limits.users-count ` +- :ref:`limits.clusters-count ` +- :ref:`limits.roles-count ` +- :ref:`limits.webhooks-count ` +- :ref:`limits.user-secrets-count ` +- :ref:`limits.user-websessions-count ` +- :ref:`limits.linked-cluster-users ` + +.. _tcm_configuration_reference_limits_users-count: + +.. confval:: limits.users-count + + The maximum number of users in |tcm|. + + | + | Type: int + | Default: 1000 + | Environment variable: TCM_LIMITS_USERS_COUNT + | Command-line option: ``--limits.users-count`` + +.. _tcm_configuration_reference_limits_clusters-count: + +.. confval:: limits.clusters-count + + The maximum number of clusters in |tcm|. + + | + | Type: int + | Default: 10 + | Environment variable: TCM_LIMITS_CLUSTERS_COUNT + | Command-line option: ``--limits.clusters-count`` + +.. _tcm_configuration_reference_limits_roles-count: + +.. confval:: limits.roles-count + + The maximum number of roles in |tcm|. + + | + | Type: int + | Default: 100 + | Environment variable: TCM_LIMITS_ROLES_COUNT + | Command-line option: ``--limits.roles-count`` + +.. _tcm_configuration_reference_limits_webhooks-count: + +.. confval:: limits.webhooks-count + + The maximum number of webhooks in |tcm|. + + | + | Type: int + | Default: 200 + | Environment variable: TCM_LIMITS_WEBHOOKS_COUNT + | Command-line option: ``--limits.webhooks-count`` + +.. _tcm_configuration_reference_limits_user-secrets-count: + +.. confval:: limits.user-secrets-count + + The maximum number secrets that a |tcm| user can have. + + | + | Type: int + | Default: 10 + | Environment variable: TCM_LIMITS_USER_SECRETS_COUNT + | Command-line option: ``--limits.user-secrets-count`` + +.. _tcm_configuration_reference_limits_user-websessions-count: + +.. confval:: limits.user-websessions-count + + The maximum number of open sessions that a |tcm| user can have. + + | + | Type: int + | Default: 10 + | Environment variable: TCM_LIMITS_USER_WEBSESSIONS_COUNT + | Command-line option: ``--limits.user-websessions-count`` + +.. _tcm_configuration_reference_limits_linked-cluster-users: + +.. confval:: limits.linked-cluster-users + + The maximum number of clusters to which a single user can have access. + + | + | Type: int + | Default: 10 + | Environment variable: TCM_LIMITS_LINKED_CLUSTER_USERS + | Command-line option: ``--limits.linked-cluster-users`` + + +.. security parameters + +.. _tcm_configuration_reference_security: + +security +-------- + +The ``security`` section defines the security parameters of |tcm|. + +- :ref:`security.auth ` +- :ref:`security.hash-cost ` +- :ref:`security.encryption-key ` +- :ref:`security.encryption-key-file ` +- :ref:`security.bootstrap-password ` +- :ref:`security.bootstrap-api-token ` +- :ref:`security.integrity-check ` +- :ref:`security.signature-private-key-file ` + +.. _tcm_configuration_reference_security_auth: + +.. confval:: security.auth + + Ways to log into |tcm|. + + Possible values: + + - ``local`` + - ``ldap`` + + | + | Type: []string + | Default: [local] + | Environment variable: TCM_SECURITY_AUTH + | Command-line option: ``--security.auth`` + +.. _tcm_configuration_reference_security_hash-cost: + +.. confval:: security.hash-cost + + A hash cost for hashing users' passwords. + + | + | Type: int + | Default: 12 + | Environment variable: TCM_SECURITY_HASH_COST + | Command-line option: ``--security.hash-cost`` + +.. _tcm_configuration_reference_security_encryption-key: + +.. confval:: security.encryption-key + + An encryption key for passwords used by |tcm| for accessing Tarantool + and etcd clusters. + + | + | Type: string + | Default: "" + | Environment variable: TCM_SECURITY_ENCRYPTION_KEY + | Command-line option: ``--security.encryption-key`` + +.. _tcm_configuration_reference_security_encryption-key-file: + +.. confval:: security.encryption-key-file + + A path to the file with the encryption key for passwords used by |tcm| for accessing Tarantool + and etcd clusters. + + | + | Type: string + | Default: "" + | Environment variable: TCM_SECURITY_ENCRYPTION_KEY_FILE + | Command-line option: ``--security.encryption-key-file`` + +.. _tcm_configuration_reference_security_bootstrap-password: + +.. confval:: security.bootstrap-password + + A password for the first login of the ``admin`` user. Only for testing purposes. + + | + | Type: string + | Default: "" + | Environment variable: TCM_SECURITY_BOOTSTRAP_PASSWORD + | Command-line option: ``--security.bootstrap-password`` + +.. _tcm_configuration_reference_security_bootstrap-api-token: + +.. confval:: security.bootstrap-api-token + + A default API token for the ``admin`` user. Only for testing purposes. + + | + | Type: string + | Default: "" + | Environment variable: TCM_SECURITY_BOOTSTRAP_API_TOKEN + | Command-line option: ``--security.bootstrap-api-token`` + +.. _tcm_configuration_reference_security_integrity-check: + +.. confval:: security.integrity-check + + Whether to check the digital signature. If ``true``, the error is raised + in case an incorrect signature is detected. + + | + | Type: bool + | Default: false + | Environment variable: TCM_SECURITY_INTEGRITY_CHECK + | Command-line option: ``--security.integrity-check`` + +.. _tcm_configuration_reference_security_signature-private-key-file: + +.. confval:: security.signature-private-key-file + + A path to a file with the private key to sign |tcm| data. + + | + | Type: string + | Default: "" + | Environment variable: TCM_SECURITY_SIGNATURE_PRIVATE_KEY_FILE + | Command-line option: ``--security.signature-private-key-file`` + +.. mode + +.. _tcm_configuration_reference_mode: + +mode +---- + +.. confval:: mode + + The |tcm| mode: ``production``, ``development``, or ``test``. + + | + | Type: string + | Default: production + | Environment variable: TCM_MODE + | Command-line option: ``--mode`` + + +.. feature + +.. _tcm_configuration_reference_feature: + +feature +------- + + +The ``feature`` section defines the security parameters of |tcm|. + +- :ref:`feature.ttgraph ` +- :ref:`feature.column-store ` +- :ref:`feature.tqe ` +- :ref:`feature.api-token ` + + +.. _tcm_configuration_reference_feature_ttgraph: + +.. confval:: feature.ttgraph + + Whether Tarantool Graph DB integration is enabled. + + | + | Type: bool + | Default: false + | Environment variable: TCM_FEATURE_TTGRAPH + | Command-line option: ``--feature.ttgraph`` + +.. _tcm_configuration_reference_feature_column-store: + +.. confval:: feature.column-store + + Whether Tarantool Column Store integration is enabled. + + | + | Type: bool + | Default: false + | Environment variable: TCM_FEATURE_COLUMN_STORE + | Command-line option: ``--feature.column-store`` + +.. _tcm_configuration_reference_feature_tqe: + +.. confval:: feature.tqe + + Whether Tarantool Queue Enterprise integration is enabled. + + | + | Type: bool + | Default: false + | Environment variable: TCM_FEATURE_TQE + | Command-line option: ``--feature.tqe`` + +.. _tcm_configuration_reference_feature_api-token: + +.. confval:: feature.api-token + + Whether the use of :ref:`API tokens ` is enabled. + + | + | Type: bool + | Default: false + | Environment variable: TCM_FEATURE_API_TOKEN + | Command-line option: ``--feature.api-token`` + +.. _tcm_configuration_reference_initial: + +initial-settings +---------------- + +The ``initial-settings`` group defines entities that are created automatically +upon the first |tcm| startup. + +See also :ref:`tcm_configuration_initial`. + + +- :ref:`initial-settings.clusters ` + +.. important:: + + The ``initial-settings.*`` configuration options can be set in the YAML + configuration file only. There are no environment variables nor + command-line options for them. + +.. _tcm_configuration_reference_initial_clusters: + +.. confval:: initial-settings.clusters + + An array of clusters to create in |tcm| automatically upon the first startup. + + See also :ref:`tcm_configuration_initial`. + + | + | Type: []Cluster + | Default: [] + + +.. _tcm_configuration_reference_initial_cluster_id: + +.. confval:: initial-settings.clusters..id + + Cluster ID. Skip this option to generate an ID automatically. + Specify the value ``00000000-0000-0000-0000-000000000000`` + to customize the default cluster upon |tcm| startup. + + | + | Type: string + | Default: "" (ID is generated automatically) + + +.. _tcm_configuration_reference_initial_cluster_name: + +.. confval:: initial-settings.clusters..name + + Cluster name. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_description: + +.. confval:: initial-settings.clusters..description + + Cluster description. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_color: + +.. confval:: initial-settings.clusters..color + + A color to highlight the cluster in |tcm|. + Possible values: + + - ``dark`` + - ``gray`` + - ``red`` + - ``pink`` + - ``grape`` + - ``violet`` + - ``indigo`` + - ``blue`` + - ``cyan`` + - ``green`` + - ``lime`` + - ``yellow`` + - ``orange`` + - ``teal`` + - empty string (no color) + + | + | Type: string + | Default: "" (no color) + + +.. _tcm_configuration_reference_initial_cluster_urls: + +.. confval:: initial-settings.clusters..urls + + URLs of additional services for the cluster. See also :ref:`tcm_connect_clusters_connect_new`. + + | + | Type: []ClusterUrl + | Default: [] + + +.. _tcm_configuration_reference_initial_cluster_url_label: + +.. confval:: initial-settings.clusters...label + + URL label to show in |tcm|. Typically, this is the linked service name. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_url_url: + +.. confval:: initial-settings.clusters...url + + The URL address of the linked service. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_provider: + +.. confval:: initial-settings.clusters..storage-connection.provider + + The type of the storage used for storing the cluster configuration. + + Possible values: + + - ``etcd`` + - ``tarantool`` + - empty string (undefined) + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_endpoints: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.endpoints + + An array of node URIs of the etcd cluster where the Tarantool cluster configuration is stored. + + | + | Type: []string + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_autosync: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.auto-sync-interval + + An automated sync interval. + + | + | Type: time.Duration + | Default: 0 (disabled) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialtimeout: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-timeout + + An etcd dial timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialkatime: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-keep-alive-time + + A dial keep-alive time. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialkatimeout: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-keep-alive-timeout + + A dial keep-alive timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_maxcallsend: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.max-call-send-msg-size + + The maximum size (in bytes) of a request from the cluster to its etcd + configuration storage. + + | + | Type: int + | Default: 2097152 + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_maxcallrecv: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.max-call-recv-msg-size + + The maximum size (in bytes) of a response to the cluster from its etcd + configuration storage. + + | + | Type: int + | Default: 0 (unlimited) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_username: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.username + + A username for accessing the cluster's etcd storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_password: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.password + + A password for accessing the cluster's etcd storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_rejectold: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.reject-old-cluster + + Whether etcd should refuse to create a client against an outdated cluster. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_permitwostream: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.permit-without-stream + + Whether keepalive pings can be send to the etcd server without active streams. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_prefix: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.prefix + + A prefix for the cluster configuration parameters in etcd. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_enabled: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.enabled + + Indicates whether TLS is enabled for connections to the cluster's etcd storage. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_cert-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.cert-file + + A path to a TLS certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_key-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.key-file + + A path to a TLS private key file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_trusted-ca-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.trusted-ca-file + + A path to a trusted CA certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_client-cert-auth: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.client-cert-auth + + Indicates whether client cert authentication is enabled. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_crl-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.crl-file + + A path to the client certificate revocation list file. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_insecure-skip-verify: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.insecure-skip-verify + + Skip checking client certificate in etcd connections. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_skip-client-san-verify: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.skip-client-san-verify + + Skip verification of SAN field in client certificate for etcd connections. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_server-name: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.server-name + + Name of the TLS server for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_cipher-suites: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.cipher-suites + + TLS cipher suites for etcd connections. Possible values are the Golang `tls.TLS_* `__ constants. + + | + | Type: []uint16 + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_allowed-cn: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.allowed-cn + + An allowed common name for authentication in etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_allowed-hostname: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.allowed-hostname + + An allowed TLS certificate name for authentication in etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_empty-cn: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.empty-cn + + Whether the empty common name is allowed in etcd connections. + + | + | Type: bool + | Default: false + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_username: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.username + + A username for connecting to the cluster's Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_password: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.password + + A password for connecting to the cluster's Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_endpoints: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.endpoints + + An array of the cluster's Tarantool-based configuration storage URIs. + + | + | Type: []string + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_method: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.method + + An authentication method for the cluster's Tarantool-based configuration storage. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_prefix: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.prefix + + A prefix for the cluster configuration parameters in the Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_key-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.key-file + + A path to a TLS private key file to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_cert-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.cert-file + + A path to an SSL certificate to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_ca-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.ca-file + + A path to a trusted CA certificate to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_ciphers: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.ciphers + + A list of SSL cipher suites that can be used for connecting to the cluster's Tarantool-based + configuration storage. Possible values are listed in :ref:`.params.ssl_ciphers `. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_enabled: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.enabled + + A password for an encrypted private SSL key to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_password-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.password-file + + A text file with passwords for encrypted private SSL keys to use + for connecting to the cluster's Tarantool-based configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_tarantool_username: + +.. confval:: initial-settings.clusters..tarantool-connection.username + + A username for connecting to the cluster instances. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_password: + +.. confval:: initial-settings.clusters..tarantool-connection.password + + A password for connecting to the cluster instances. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_method: + +.. confval:: initial-settings.clusters..tarantool-connection.method + + An authentication method for connecting to the cluster. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_timeout: + +.. confval:: initial-settings.clusters..tarantool-connection.timeout + + The cluster request timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_tarantool_rate-limit: + +.. confval:: initial-settings.clusters..tarantool-connection.rate-limit + + The cluster rate limit. + + | + | Type: uint + | Default: 0 (not set) + + +.. _tcm_configuration_reference_initial_cluster__tarantool_ssl_key-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.key-file + + A path to a TLS private key file to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_cert-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.cert-file + + A path to an SSL certificate to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_ca-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.ca-file + + A path to a trusted CA certificate to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_ciphers: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.ciphers + + A list of SSL cipher suites that can be used for connecting to the cluster instances. + Possible values are listed in :ref:`.params.ssl_ciphers `. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_enabled: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.enabled + + A password for an encrypted private SSL key to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_password-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.password-file + + A text file with passwords for encrypted private SSL keys to use + for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" diff --git a/doc/tooling/tcm/tcm_connect_clusters.rst b/doc/tooling/tcm/tcm_connect_clusters.rst new file mode 100644 index 0000000000..8e8c031cf3 --- /dev/null +++ b/doc/tooling/tcm/tcm_connect_clusters.rst @@ -0,0 +1,174 @@ +.. _tcm_connect_clusters: + +Connecting clusters +=================== + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| works with clusters that: + +* run on Tarantool EE 3.0 or later +* use :ref:`centralized configuration ` storage: etcd or Tarantool-based. + +A single |tcm| installation can have multiple connected clusters. A connection to +|tcm| doesn't affect the cluster's functioning. You can connect clusters to |tcm| +and disconnect them on the fly. + +There are two scenarios of cluster connection to |tcm|: + +- Connect an existing cluster. +- Add a new cluster and :ref:`write its configuration ` from scratch in the |tcm| + web interface. + +In both cases, you need to deploy Tarantool and start the cluster instances using +the :ref:`tt-cli` or another suitable way. + +To add a cluster to |tcm|, you can use two ways: + +- Use the |tcm| web interface as described on this page. +- Specify the ``initial-settings.clusters`` section of the |tcm| configuration. + To learn more, see :ref:`tcm_configuration_initial`. + +.. _tcm_connect_clusters_parameters: + +Connection parameters +--------------------- + +When connecting a cluster to |tcm|, you need to provide two sets of connection parameters: +for the cluster instances and for the centralized configuration storage. + +.. _tcm_connect_clusters_parameters_storage: + +Configuration storage connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The cluster configuration can be stored in either an :ref:`etcd ` +cluster or a separate Tarantool-based storage. In both cases, the following connection +parameters are required: + +* A key prefix used to identify the cluster in the configuration storage. + A prefix must be unique for each cluster in storage. +* URIs of all instances of the configuration storage. +* The credentials for accessing the configuration storage: an `etcd user `__ + or a :ref:`Tarantool user `. + +Additionally, if SSL or TLS encryption is enabled for the configuration storage, +provide the corresponding encryption configuration: keys, certificates, and other +parameters. For the complete list of parameters, consult the `etcd documentation `__ +or Tarantool :ref:`enterprise-iproto-encryption`. + +.. _tcm_connect_clusters_parameters_tarantool: + +Cluster connection +~~~~~~~~~~~~~~~~~~ + +For interaction with the cluster instances, |tcm| needs the following access parameters: + +* A :ref:`Tarantool user ` that exists in the cluster and their password. + |tcm| connects to the cluster on behalf of this user. +* An :ref:`SSL configuration ` if the traffic encryption + is enabled on the cluster. + +Managing connected clusters +--------------------------- + +Administrators can add new clusters, edit, and remove existing ones from |tcm|. + +Connected clusters are listed on the **Clusters** page. + +.. _tcm_connect_clusters_connect_preconf: + +Connecting a pre-configured cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you already have a cluster and want to connect it to |tcm|, +follow these steps: + +#. Go to **Clusters** and click **Add**. +#. Fill in the general cluster information: + + * Specify an arbitrary name. + * Optionally, provide a description and select a color to mark this cluster in |tcm|. + * Optionally, enter the URLs of additional services for the cluster. For example, + a Grafana dashboard that monitors the cluster metrics, or a syslog server + for viewing the cluster logs. |tcm| provides quick access to these URLs on + the cluster **Stateboard** page. + +3. Provide the details of the cluster configuration storage: + + * Storage type: **etcd** or **tarantool**. + * The **Prefix** specified in the cluster configuration. + * The URIs of the configuration storage instances. + * The credentials for accessing the configuration storage. + * The SSL/TLS parameters if the connection encryption is enabled on the storage. + +4. Provide the credentials for accessing the cluster: a Tarantool user's name, their password, + and SSL parameters in case :ref:`traffic encryption ` + is enabled on the cluster. + +.. _tcm_connect_clusters_connect_new: + +Adding a new cluster +~~~~~~~~~~~~~~~~~~~~ + +If you don't have a cluster yet, you can add one in |tcm| and write its configuration +from scratch using the :ref:`built-in configuration editor `. + +.. important:: + + When adding a new cluster, you need to have a storage for its configuration up + and running so that |tcm| can connect to it. Cluster instances can be deployed later. + +To add a new cluster: + +#. Go to **Clusters** and click **Add**. +#. Fill in the general cluster information: + + * Specify an arbitrary name. + * Optionally, provide a description and select a color to mark this cluster in |tcm|. + * Optionally, enter the URLs of additional services for the cluster. For example, + a Grafana dashboard that monitors the cluster metrics, or a syslog server + for viewing the cluster logs. |tcm| provides quick access to these URLs on + the cluster **Stateboard** page. + +#. Select the type of the cluster configuration storage: **etcd** or **tarantool**. +#. Define a unique **Prefix** for identifying this cluster in the configuration storage. +#. Provide the connection details for the cluster configuration storage: + + * The URIs of configuration storage instances. + * The credentials for accessing the configuration storage. + * The SSL/TLS parameters if the connection encryption is enabled on the storage. + +#. Provide the cluster credentials: a username, a password, and SSL parameters in + case :ref:`traffic encryption ` is enabled on + the cluster. + +Once you add the cluster: + +* Set up the cluster configuration using the |tcm| :ref:`configuration editor `. +* Deploy Tarantool on the cluster nodes using the :ref:`tt-cli` or other suitable tools. +* Start the cluster using the :ref:`tt-cli` or other suitable tools. + +.. _tcm_connect_clusters_edit: + +Editing a connected cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To edit a connected cluster, go to **Clusters** and click **Edit** in the **Actions** +menu of the corresponding table row. + +.. _tcm_connect_clusters_disconnect: + +Disconnecting a cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +To disconnect a cluster from |tcm|, go to **Clusters** and click **Disconnect** +in the **Actions** menu of the corresponding table row. + +.. note:: + + Disconnecting a cluster does not affect its functioning. The only + thing that changes is that it's no longer shown in |tcm|. + You can connect this cluster again at any time. \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_dev_mode.rst b/doc/tooling/tcm/tcm_dev_mode.rst new file mode 100644 index 0000000000..f870f7d99b --- /dev/null +++ b/doc/tooling/tcm/tcm_dev_mode.rst @@ -0,0 +1,69 @@ +.. _tcm_dev_mode: + +Development mode +================ + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| provides a special mode aimed to use during the development. +This mode extends the web interface with capabilities that can help in development +or testing environments, such as starting and stopping instances or instance promotion. + +.. _tcm_dev_mode_enable: + +Enabling development mode +------------------------- + +You can enable |tcm| development mode in different ways: in its web interface, +in the configuration file, using an environment variable, or using a command-line option. + +.. _tcm_dev_mode_enable_web: + +Web interface +~~~~~~~~~~~~~ + +To enable development mode on the running |tcm| instance, use its :ref:`web interface `: + +#. Open user settings: click **Settings** under the user name in the header. +#. Go to the **About** tab. +#. Click the toggle button beside **tcm/mode**. + +.. _tcm_dev_mode_enable_config: + +Configuration file +~~~~~~~~~~~~~~~~~~ + +To start |tcm| in the development mode, specify the ``mode: development`` option +in its :ref:`configuration file `: + +.. code-block:: yaml + + # tcm_config.yaml + mode: development + +.. _tcm_dev_mode_enable_cli: + +Command-line option +~~~~~~~~~~~~~~~~~~~ + +To start |tcm| in the development mode, specify the ``--mode=development`` command-line option: + +.. code-block:: console + + $ tcm --mode=development + + +.. _tcm_dev_mode_enable_env: + +Environment variable +~~~~~~~~~~~~~~~~~~~~ + +To make new |tcm| instances start in the development mode by default, set the +``TCM_MODE`` environment variable to ``development``: + +.. code-block:: console + + $ export TCM_MODE=development + $ tcm diff --git a/doc/tooling/tcm/tcm_releases/index.rst b/doc/tooling/tcm/tcm_releases/index.rst new file mode 100644 index 0000000000..34b97b8ebf --- /dev/null +++ b/doc/tooling/tcm/tcm_releases/index.rst @@ -0,0 +1,52 @@ +.. _tcm_releases: + +Tarantool Cluster Manager releases +================================== + +.. include:: ../index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +This section contains the list of |tcm_full_name| releases along with descriptions +of their key changes. + +For information about Tarantool releases, see :ref:`release`. + +.. _tcm_releases_supported: + +Supported versions +------------------ + +.. container:: table + + .. list-table:: + :header-rows: 1 + + * - Series + - First release date + - Versions + + * - :ref:`1.2 ` + - July 30, 2024 + - | 1.2.2 + | 1.2.1 + | 1.2.0 + + * - :ref:`1.1 ` + - May 16, 2024 + - 1.1.0 + + * - :ref:`1.0 ` + - December 23, 2023 + - | 1.0.4 + | 1.0.3 + | 1.0.2 + | 1.0.1 + | 1.0.0 + +.. toctree:: + :maxdepth: 1 + + tcm_1.2 + tcm_1.1 + tcm_1.0 \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_releases/tcm_1.0.rst b/doc/tooling/tcm/tcm_releases/tcm_1.0.rst new file mode 100644 index 0000000000..fbc1ec86ad --- /dev/null +++ b/doc/tooling/tcm/tcm_releases/tcm_1.0.rst @@ -0,0 +1,82 @@ +.. _tcm_releases_1_0: + +Tarantool Cluster Manager 1.0 +============================= + +Release date: December 26, 2023 + +Latest release in series: 1.0.4 + +1.0 is the first public release series of |tcm_full_name|. It was introduced as a +part of the :ref:`Tarantool EE 3.0 release <3-0-tarantool_cluster_manager>`. +Below is an overview of key features of TCM 1.0. + +.. _tcm_releases_1_0_clusters: + +Multiple connected clusters +--------------------------- + +|tcm| works as a standalone application. You can connect any number of Tarantool EE +3.0+ clusters to a single |tcm| instance and switch between them on the fly. + +To connect a cluster to |tcm|, you need to provide the endpoint URLs and connection +parameters of its centralized configuration storage (for example, etcd). +To learn more, see :ref:`tcm_connect_clusters`. + +.. _tcm_releases_1_0_stateboard: + +Cluster stateboard +------------------ + +The cluster *stateboard* is a main |tcm| page that visualizes the information about +the selected cluster: + +- Cluster topology visualized as a table or a graph +- Tarantool versions running on instances +- Memory statistics +- Errors and warnings that happen on instances + +From the stateboard, you can navigate to specific instances to view their details +or connect to their interactive consoles. + +To learn more, see :ref:`tcm_cluster_state`. + +.. _tcm_releases_1_0_config: + +Cluster configuration management +-------------------------------- + +|tcm| includes a visual editor for cluster configuration. It allows editing cluster +configurations as a YAML file in the browser. Once you're done editing the configuration, +you can send the changes to the configuration storage in one click or save them locally +to continue editing them later. + +To learn more, see :ref:`tcm_configuring_clusters`. + +.. _tcm_releases_1_0_access: + +Role-based access control +------------------------- + +|tcm| features its own role-based access control system. It defines users that can +log into |tcm| and their permissions to perform various actions or access clusters +in its web interface. + +You can use built-in roles or create new ones with permissions you need. Users' +access can be limited to specific clusters and operations on them, for example, +editing the configuration or calling stored functions. +To learn more, see :ref:`tcm_access_control`. + +|tcm| also supports LDAP authentication. + +.. _tcm_releases_1_0_audit: + +Audit logging +------------- + +|tcm| has a built-in audit logging mechanism. When enabled, it records information +about events that occur in |tcm| and users' actions to dedicated audit log files. +You can define events to write to the audit log and adjust logging parameters, such +as filename, log rotation, or compression. + +To learn more, see :ref:`tcm_audit_log`. diff --git a/doc/tooling/tcm/tcm_releases/tcm_1.1.rst b/doc/tooling/tcm/tcm_releases/tcm_1.1.rst new file mode 100644 index 0000000000..50d3cd5f2f --- /dev/null +++ b/doc/tooling/tcm/tcm_releases/tcm_1.1.rst @@ -0,0 +1,116 @@ +.. _tcm_releases_1_1: + +Tarantool Cluster Manager 1.1 +============================= + +Release date: May 16, 2024 + +Latest release in series: 1.1.0 + +|tcm_full_name| 1.1 introduces a number of new features that extend and improve its +cluster management capabilities. Below is an overview of its key updates. + +.. _tcm_releases_1_1_data_access: + +Data access +----------- + +An important update of |tcm| 1.1.0 is a set of features that enable access to clusters' +stored data. + +The instance *space explorer* shows all spaces that exist on an instance, including +system spaces. On its pages, you can view and edit the stored data. To open the instance explorer, +find the instance on the cluster stateboard and click its name to open its details page. +Then click **Explorer** in the **Actions** menu in the top right corner. + +In the development mode, the instance explorer also includes the *schema editor*. +It allows you to add new and edit existing spaces. + +For clusters that use the `CRUD `__ module, +there is also the *CRUD explorer* that enables access to data in user spaces across +the entire cluster. The CRUD explorer is located on the **Tuples** page. + +.. _tcm_releases_1_1_acl: + +Access control list +------------------- + +|tcm|'s *access control list* (*ACL*) enables control over user access to particular spaces +and stored functions in the web interface. + +For each user that has access to a cluster, you can enable the use of ACL on this cluster. +This restricts this user's access to the cluster's spaces and functions unless they +are explicitly specified in the ACL. The ACL must contain an entry for each such +space and function. + +Users with ACL off have access to all spaces and functions on clusters according +to their cluster permissions. + +The tools for managing ACL are located on the new **ACL** page. + +.. _tcm_releases_1_1_api_tokens: + +API tokens +---------- + +|tcm| 1.1 supports token authentication of external requests. Users can generate +API tokens in their user settings dialog. An API token has the same permissions +as its creator. + +.. _tcm_releases_1_1_stateboard: + +Stateboard improvements +----------------------- + +|tcm| 1.1 extends the functionality of the cluster stateboard to improve the +cluster management experience. Here are the key updates of the stateboard: + +- More flexible instance grouping. +- Stateful failover and switchover controls. +- Runtime issues on the stateboard. + +.. _tcm_releases_1_1_instance: + +Instance interaction +-------------------- + +The instance management dialog has been extended with new functions: + +- A new terminal that uses the :ref:`tt interactive console `. +- SQL query execution terminal. +- Stored functions editor. +- Slab visualization. + +.. _tcm_releases_1_1_metrics: + +Cluster metrics +--------------- + +Starting from version 1.1.0, |tcm| displays metrics of connected clusters. +You can view metrics in |tcm| one by one, visualizing them as charts or tables. +The cluster metrics are shown on the new **Cluster metrics** page. + +For more complex monitoring, you can use dedicated solutions, for example, Prometheus. +It can integrate with |tcm| using the :ref:`API tokens `. + +.. _tcm_releases_1_1_config: + +Configuration validation +------------------------ + +The cluster configuration editor now validates the configuration semantically. +Previously, |tcm| was able to highlight the syntax errors in configurations, for example, +incorrect spelling of option names or hierarchy. In |tcm| 1.1.0, the editor +checks and highlights possible semantic issues, such as: + +- Users without passwords. +- Users with the ``super`` role. +- Absence of leader instances in replica sets. + +.. _tcm_releases_1_1_tutorial: + +Onboarding tutorial +------------------- + +|tcm| 1.1.0 includes an interactive tutorial that takes new users through its +main features and pages. It opens automatically after the first start. diff --git a/doc/tooling/tcm/tcm_releases/tcm_1.2.rst b/doc/tooling/tcm/tcm_releases/tcm_1.2.rst new file mode 100644 index 0000000000..498d988dc2 --- /dev/null +++ b/doc/tooling/tcm/tcm_releases/tcm_1.2.rst @@ -0,0 +1,59 @@ +.. _tcm_releases_1_2: + +Tarantool Cluster Manager 1.2 +============================= + +Release date: July 30, 2024 + +Latest release in series: 1.2.1 + +|tcm_full_name| 1.2 introduces new features that extend its +cluster management capabilities. Below is an overview of its key updates. + +.. _tcm_releases_1_2_tarantool_users: + +Managing Tarantool users +------------------------ + +|tcm| 1.2 introduces the ability to manage Tarantool users on connected clusters. +Previously, you could manage Tarantool users only though the Lua API (:ref:`box.schema ` submodule) +or cluster :ref:`configuration `. +Now you can create, edit, and delete users and roles on each instance of a Tarantool +cluster through the |tcm| web interface. + +The tools for managing Tarantool users on a cluster instance are located on the +**Users** tab of the instance page. + +Learn more about managing Tarantool users from |tcm| in :ref:`tcm_cluster_users`. + +.. _tcm_releases_1_2_migrations: + +Migrations +---------- + +Since version 1.2.0, |tcm| includes a page for editing and executing :ref:`migrations ` +on connected clusters. The new page **Migrations** in the **Cluster** page group +provides a text editor where you can write migration scripts in Lua and apply them +to the cluster. + +Learn more about migrations in Tarantool :ref:`migrations`. + +.. _tcm_releases_1_2_cluster_security: + +Cluster security settings +------------------------- + +Since version 1.2.2, |tcm| provides a web interface for managing cluster security settings +on the **Security** page in the **Cluster** group. + +Learn more about managing cluster security from |tcm| in :ref:`tcm_cluster_security`. + +.. _tcm_releases_1_2_tcf: + +TCF integration +--------------- + +Since version 1.2.2, |tcm| includes a page for managing clusters that +run within `Tarantool Clusters Federation `__. + +Learn more about working with TCF in |tcm| in :ref:`tcm_cluster_tcf`. diff --git a/doc/tooling/tcm/tcm_ui_overview.rst b/doc/tooling/tcm/tcm_ui_overview.rst new file mode 100644 index 0000000000..1ba7884a75 --- /dev/null +++ b/doc/tooling/tcm/tcm_ui_overview.rst @@ -0,0 +1,477 @@ +.. _tcm_ui_overview: + +Web interface overview +====================== + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + + +The |tcm_full_name| web interface is available on the hostname and port defined by the +``http.host`` and ``http.port`` :ref:`configuration options `. +If TLS is enabled, it uses the ``https`` protocol, otherwise the protocol is ``http``. +When started locally with the default configuration, |tcm| is available at ``http://127.0.0.1:8080``. + +.. _tcm_ui_login: + +Logging into TCM +---------------- + +To log into |tcm| after bootstrap, use the following credentials: + +- **Username**: ``admin`` +- **Password**: the initial password is shown in the |tcm| boot log in + a message like this: + + .. code-block:: text + + Jun 11 11:24:08.900 WRN Generated super admin credentials login=admin password=jS9PsdkEJBYNhdMtSswMlxDR1vdbfc1N + +.. image:: _images/tcm_ui_login.png + :align: left + :width: 700 + :alt: TCM login page + +After logging in with the default password: + +#. Adjust the :ref:`password policy ` + in accordance to the security requirements that apply in your organization. +#. Change the ``admin`` user's password on the :ref:`User settings ` page. + +To log out of |tcm|, click the user's name in the header and click **Log out**. + +.. _tcm_ui_page_structure: + +Page structure +-------------- + +The |tcm| web interface consists of three parts: + +#. **Navigation page** on the left shows the list of pages available to the user. + The navigation pane can be collapsed by clicking the cross icon at its top. +#. **Header** at the top provides access to notifications and :ref:`user settings `. +#. **Working area** displays the contents of the selected page. + +.. image:: _images/tcm_ui_sections.png + :align: left + :width: 700 + :alt: TCM UI parts: navigation pane, header, working area + +.. _tcm_ui_onboarding: + +Onboarding +---------- + +The **Onboarding** item of the navigation pane starts the interactive onboarding +tutorial. Use it to get familiar with main |tcm| features directly in the web interface. + +.. _tcm_ui_visibility: + +Page visibility +--------------- + +This overview describes most |tcm| pages. The exact set of pages and controls available +to a particular user is determined by the user's :ref:`permissions `. + +Some features, such as data schema editing, are available only in the **development** mode. +You can switch to it in the :ref:`user settings ` of the **Default Admin** user. +To learn more about the development mode, see :ref:`tcm_dev_mode`. + +.. _tcm_ui_groups: + +Page groups +----------- + +For easier navigation, |tcm| pages are grouped in the navigation pane by their content. +There are the following page groups: + +- **Cluster**: interaction with the selected cluster. +- **Clusters**: interaction with all connected clusters in general. +- **Users**: access management. +- **Tools**: |tcm| administration. +- **Settings**: runtime management of |tcm| settings. + +Read on to learn what you can do on pages of these groups. + +.. _tcm_ui_cluster: + +Cluster +------- + +The **Cluster** group includes pages used for interaction with a particular cluster. +To switch between clusters, click the **Cluster** group name and select a connected +cluster from the drop-down list. + +.. _tcm_ui_cluster_stateboard: + +Stateboard +~~~~~~~~~~ + +The cluster **Stateboard** is a main page for monitoring the cluster state +and interacting with its instances. + +.. image:: _images/tcm_ui_stateboard.png + :align: left + :width: 700 + :alt: TCM stateboard + +On this page, you can: + +- view and edit the cluster topology +- group and filter instances based on various criteria +- view memory statistics and Tarantool versions running on instances +- navigate to :ref:`instance pages ` + by clicking instance names in the cluster topology list +- start and stop instances (in the development mode). + +Learn more about using the cluster stateboard in :ref:`tcm_cluster_state`. + +.. _tcm_ui_instance: + +Instance page +~~~~~~~~~~~~~ + +The instance page opens when you click an instance name on the **Stateboard**. + +.. image:: _images/tcm_ui_instance.png + :align: left + :width: 700 + :alt: TCM instance page + +It provides a set of tabs for performing actions on the selected Tarantool instance: + +- **Details** and **State** tabs: view instance details as a human-readable table + or as a console output of ``box.cfg``, ``box.info``, and other built-in functions +- **SQL** and **Terminal** tabs: run SQL and Lua commands on the instance +- **Logs** tab: view instance logs +- **Slabs** tab: view :ref:`slab allocator ` statistics +- **Users** tab: manage Tarantool :ref:`users and roles ` on the instance +- **Funcs**: manage and call stored functions +- **Metrics**: view instance metrics + +The instance page has an **Actions** menu at the top that allows you to: + +- navigate to the :ref:`instance explorer ` +- edit the instance configuration +- remove the instance + +.. _tcm_ui_cluster_config: + +Configuration +~~~~~~~~~~~~~ + +The cluster **Configuration** page provides an interactive editor for the cluster +:ref:`configuration `. It is connected to the centralized configuration +storage that the cluster uses. All changes you make and apply on this page are +sent to this centralized storage. + +.. image:: _images/tcm_ui_config.png + :align: left + :width: 700 + :alt: TCM cluster configuration page + +Learn more in :ref:`tcm_configuring_clusters`. + +.. _tcm_ui_cluster_security: + +Security +~~~~~~~~ + +The **Security** page provides controls for managing the cluster security settings. + +.. image:: _images/tcm_ui_cluster_security.png + :align: left + :width: 700 + :alt: TCM cluster security page + +Learn more in :ref:`tcm_cluster_security`. + +.. _tcm_ui_cluster_migrations: + +Migrations +~~~~~~~~~~ + +The **Migrations** page provides centralized migration management tools for the selected cluster. + +.. image:: _images/tcm_ui_cluster_migrations.png + :align: left + :width: 700 + :alt: TCM cluster migrations page + +Learn more in :ref:`tcm_cluster_migrations`. + +.. _tcm_ui_cluster_tuples: + +Tuples +~~~~~~ + +.. important:: + + The cluster-wide access to stored data on the **Tuples** page is supported only + for sharded clusters that use the `CRUD `__ module. + +The **Tuples** page provides access to data stored in user spaces of the selected +cluster. + +.. image:: _images/tcm_ui_tuples.png + :align: left + :width: 700 + :alt: TCM tuples page + +On this page, you can: + +- view the list of user spaces, their size and engines +- view and edit tuples stored in user spaces + +.. _tcm_ui_cluster_tcf: + +TCF +~~~ + +The **TCF** page provides an interface for clusters that run within `Tarantool Clusters Federation `__. + +.. image:: _images/tcm_ui_tcf.png + :align: left + :width: 700 + :alt: TCM TCF page + +On this page, you can: + +- view information about TCF clusters +- switch cluster states in a TCF installation + +Learn more in :ref:`tcm_cluster_tcf`. + +.. _tcm_ui_cluster_metrics: + +Cluster metrics +~~~~~~~~~~~~~~~ + +The **Cluster metrics** page provides access to the selected cluster's :ref:`metrics `. + +.. image:: _images/tcm_ui_cluster_metrics.png + :align: left + :width: 700 + :alt: TCM cluster metrics page + +Learn more in :ref:`tcm_cluster_metrics`. + + +.. _tcm_ui_instance_explorer: + +Instance explorer +~~~~~~~~~~~~~~~~~ + +The instance **Explorer** provides access to all spaces of a specific instance, +including system spaces. + +.. image:: _images/tcm_ui_instance_explorer.png + :align: left + :width: 700 + :alt: TCM instance explorer + +On this page, you can: + +- view and edit instance spaces, their size and engines +- view and edit tuples stored in all spaces of the instance + +.. _tcm_ui_clusters: + +Clusters +-------- + +The **Clusters** group includes pages used for managing |tcm|'s cluster connections. + +.. _tcm_ui_clusters_clusters: + +Clusters +~~~~~~~~ + +The **Clusters** page lists Tarantool clusters that are connected to |tcm|. + +.. image:: _images/tcm_ui_clusters.png + :align: left + :width: 700 + :alt: TCM clusters page + +On this page, you can: + +- connect Tarantool clusters to |tcm| +- edit cluster connections +- disconnect clusters + +Learn more in :ref:`tcm_connect_clusters`. + +.. _tcm_ui_clusters_acl: + +ACL +~~~ + +The **ACL** page displays the |tcm| access control list. + +.. image:: _images/tcm_ui_acl.png + :align: left + :width: 700 + :alt: TCM ACL page + +On this page, you can add and delete ACL entries. Learn more in :ref:`tcm_access_control_list`. + +.. _tcm_ui_users: + +Users +----- + +The **Users** group includes pages related to user access to |tcm|. + +.. _tcm_ui_users_users: + +Users +~~~~~ + +The **Users** page lists |tcm| users. + +.. image:: _images/tcm_ui_users.png + :align: left + :width: 700 + :alt: TCM users page + +On this page, you can: + +- add, edit, and delete users +- manage user secrets (:ref:`passwords ` and + :ref:`API tokens `) +- revoke user sessions + +Learn more in :ref:`tcm_access_control_users`. + +.. _tcm_ui_users_roles: + +Roles +~~~~~ + +The **Roles** page lists |tcm| user roles. + +.. image:: _images/tcm_ui_roles.png + :align: left + :width: 700 + :alt: TCM roles page + +On this page, you can add, edit, and delete roles. Learn more in :ref:`tcm_access_control_roles`. + +.. _tcm_ui_users_sessions: + +Sessions +~~~~~~~~ + +The **Sessions** page lists active sessions of |tcm| users. + +.. image:: _images/tcm_ui_sessions.png + :align: left + :width: 700 + :alt: TCM sessions page + +On this page, you can view and revoke sessions. Learn more in :ref:`tcm_access_control_sessions`. + +.. _tcm_ui_tools: + +Tools +----- + +The **Tools** group includes service pages used for |tcm| maintenance and monitoring. + +.. _tcm_ui_tools_audit_log: + +Audit log +~~~~~~~~~ + +The **Audit log page** displays the |tcm| :ref:`audit log `. + +.. image:: _images/tcm_ui_audit_log.png + :align: left + :width: 700 + :alt: TCM audit log + +.. _tcm_ui_tools_metrics: + +TCM metrics +~~~~~~~~~~~ + +The **TCM metrics** page provides access to the |tcm| metrics. + +.. image:: _images/tcm_ui_tcm_metrics.png + :align: left + :width: 700 + :alt: TCM metrics page + +.. _tcm_ui_settings: + +Settings +-------- + +The **Settings** group includes service pages where you can configure various |tcm| features. + +.. _tcm_ui_settings_policy: + +Password policy +~~~~~~~~~~~~~~~ + +On the **Password policy** page, you can configure the requirements to user passwords, +such as minimal length, required symbols, expiration, and other settings. +Learn more in :ref:`tcm_access_control_password_policy`. + + +.. image:: _images/tcm_ui_policy.png + :align: left + :width: 700 + :alt: TCM password policy + +.. _tcm_ui_settings_audit: + +Audit settings +~~~~~~~~~~~~~~ + +On the **Audit settings** page, you can configure how |tcm| records events to its +audit log: whether audit log is enabled, which events are recorded, and so on. +Learn more in :ref:`tcm_audit_log`. + + +.. image:: _images/tcm_ui_audit_settings.png + :align: left + :width: 700 + :alt: TCM audit settings + +.. _tcm_ui_settings_ldap: + +LDAP +~~~~ + +On the **LDAP** page, you can manage |tcm| LDAP configurations. + + +.. image:: _images/tcm_ui_ldap.png + :align: left + :width: 700 + :alt: TCM LDAP configurations + +.. _tcm_ui_user_settings: + +User settings +------------- + +The user settings dialog opens when you click **Settings** under the user's name +in the header. + + +.. image:: _images/tcm_ui_user_settings.png + :align: left + :width: 700 + :alt: TCM user settings + +This dialog includes the following tabs: + +- **General** tab: switch the color theme +- **Change password** tab: change your password +- **API tokens** tab: generate and delete :ref:`API tokens ` +- **Sessions** tab: view and revoke your user sessions +- **About** tab: view |tcm| information about switch between development and production modes diff --git a/doc/tooling/tt_cli/_includes/cartridge_deprecation_note.rst b/doc/tooling/tt_cli/_includes/cartridge_deprecation_note.rst new file mode 100644 index 0000000000..2d7242f791 --- /dev/null +++ b/doc/tooling/tt_cli/_includes/cartridge_deprecation_note.rst @@ -0,0 +1,5 @@ +.. important:: + + The Tarantool Cartridge framework is deprecated and is not compatible with + Tarantool 3.0 and later. This command is added for backward compatibility with + earlier versions. \ No newline at end of file diff --git a/doc/tooling/tt_cli/binaries.rst b/doc/tooling/tt_cli/binaries.rst new file mode 100644 index 0000000000..4492b066b1 --- /dev/null +++ b/doc/tooling/tt_cli/binaries.rst @@ -0,0 +1,88 @@ +.. _tt-binaries: + +Managing binaries in the current environment +============================================ + +.. code-block:: console + + $ tt binaries COMMAND [COMMAND_OPTION ...] + +``tt binaries`` manages Tarantool and ``tt`` binaries installed in the current environment. + +``COMMAND`` is one of the following: + +- :ref:`list ` +- :ref:`switch ` + + +.. _tt-binaries-list: + +list +---- + +.. code-block:: console + + $ tt binaries list + +``tt binaries list`` shows a list of installed binaries and their versions. + +To show a list of installed Tarantool versions: + +.. code-block:: console + + $ tt binaries list + List of installed binaries: + • tarantool: + 3.1.0 [active] + 2.11.2 + • tt: + 2.3.0 + 2.2.1 [active] + +.. _tt-binaries-switch: + +switch +------ + +.. code-block:: console + + $ tt binaries switch [PROGRAM_NAME] [VERSION] + +``tt binaries switch`` switches binaries used in the current environment. +The possible values of ``PROGRAM_NAME`` are: + +* ``tarantool``: Tarantool Community Edition. +* ``tarantool-ee``: Tarantool Enterprise Edition. +* ``tt``: the ``tt`` command-line utility. + +When called without arguments, the command lets you choose the program and +version interactively: + +.. code-block:: console + + $ tt binaries switch + Use the arrow keys to navigate: ↓ ↑ → ← + ? Select program: + ▸ tarantool + tarantool-ee + tt + +You can also specify the program name and version in the call. + +To view ``tt`` versions installed in the current environment and switch +between them: + +.. code-block:: console + + $ tt binaries switch tt + Use the arrow keys to navigate: ↓ ↑ → ← + ? Select version: + ▸ 2.2.1 + 2.3.0 [active] + +To switch to a specific Tarantool EE version installed in the current environment: + +.. code-block:: console + + $ tt binaries switch tarantool-ee 3.1.0 + diff --git a/doc/tooling/tt_cli/build.rst b/doc/tooling/tt_cli/build.rst new file mode 100644 index 0000000000..7329ac2502 --- /dev/null +++ b/doc/tooling/tt_cli/build.rst @@ -0,0 +1,97 @@ +.. _tt-build: + +Building an application +======================= + +.. code-block:: console + + $ tt build [PATH] [--spec SPEC_FILE_PATH] + + +``tt build`` builds a Tarantool application locally. + +Options +------- + +.. option:: --spec SPEC_FILE_PATH + + Path to a ``.rockspec`` file to use for the current build + +Details +------- + +The ``PATH`` argument should contain the path to the application directory +(that is, to the build source). The default path is ``.`` (current directory). + +The application directory must contain a ``.rockspec`` file to use for the build. +If there is more than one ``.rockspec`` file in the application directory, specify +the one to use in the ``--spec`` argument. + +``tt build`` builds an application with the ``tt rocks make`` command. +It downloads the application dependencies into the ``.rocks`` directory, +making the application ready to run locally. + +Pre-build and post-build scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to building the application with LuaRocks, ``tt build`` +can execute *pre-build* and *post-build* scripts. These scripts should +contain steps to execute right before and after building the application. +These files must be named ``tt.pre-build`` and ``tt.post-build`` correspondingly +and located in the application directory. + +.. note:: + + For compatibility with Cartridge applications, + the pre-build and post-build scripts can also have names ``cartridge.pre-build`` + and ``cartridge.post-build``. + +``tt.pre-build`` is helpful when your application depends on closed-source rocks, +or if the build should contain rocks from a project added as a submodule. +You can **install** these dependencies using the pre-build script **before** building. +Example: + +.. code-block:: bash + + #!/bin/sh + + # The main purpose of this script is to build non-standard rocks modules. + # The script will run before `tt rocks make` during application build. + + tt rocks make --chdir ./third_party/proj + +``tt.post-build`` is a script that runs after ``tt rocks make``. The main purpose +of this script is to remove build artifacts from the final package. Example: + +.. code-block:: bash + + #!/bin/sh + + # The main purpose of this script is to remove build artifacts from the resulting package. + # The script will run after `tt rocks make` during application build. + + rm -rf third_party + rm -rf node_modules + rm -rf doc + + +Examples +-------- + +* Build the application ``app1`` from its directory: + + .. code-block:: console + + $ tt build + +* Build the application ``app1`` from the ``simple_app`` directory inside the current directory: + + .. code-block:: console + + $ tt build simple_app + +* Build the application ``app1`` from its directory explicitly specifying the rockspec file to use: + + .. code-block:: console + + $ tt build --spec app1-scm-1.rockspec \ No newline at end of file diff --git a/doc/reference/tooling/tt_cli/cartridge.rst b/doc/tooling/tt_cli/cartridge.rst similarity index 99% rename from doc/reference/tooling/tt_cli/cartridge.rst rename to doc/tooling/tt_cli/cartridge.rst index 101bb07b7d..6366ab433f 100644 --- a/doc/reference/tooling/tt_cli/cartridge.rst +++ b/doc/tooling/tt_cli/cartridge.rst @@ -3,6 +3,8 @@ Managing a Cartridge application ================================ +.. include:: _includes/cartridge_deprecation_note.rst + .. code-block:: console $ tt cartridge COMMAND {[OPTION ...]|SUBCOMMAND} diff --git a/doc/reference/tooling/tt_cli/cat.rst b/doc/tooling/tt_cli/cat.rst similarity index 100% rename from doc/reference/tooling/tt_cli/cat.rst rename to doc/tooling/tt_cli/cat.rst diff --git a/doc/reference/tooling/tt_cli/cfg.rst b/doc/tooling/tt_cli/cfg.rst similarity index 100% rename from doc/reference/tooling/tt_cli/cfg.rst rename to doc/tooling/tt_cli/cfg.rst diff --git a/doc/tooling/tt_cli/check.rst b/doc/tooling/tt_cli/check.rst new file mode 100644 index 0000000000..af00bd516a --- /dev/null +++ b/doc/tooling/tt_cli/check.rst @@ -0,0 +1,36 @@ +.. _tt-check: + +Checking an application file +============================ + +.. code-block:: console + + $ tt check {FILEPATH | APPLICATION[:APP_INSTANCE]} + +``tt check`` checks the syntax correctness of Lua files within Tarantool applications +or separate Lua scripts. The files must be stored inside the ``instances_enabled`` +directory specified in the :ref:`tt configuration file `. + +Examples +-------- + +To check all Lua files in an application directory at once, specify the directory name: + +.. code-block:: console + + $ tt check app + +To check a single Lua file from an application directory, add the path to this file: + +.. code-block:: console + + $ tt check app/router + # or + $ tt check app/router.lua + +.. note:: + + The ``.lua`` extension can be omitted. + + + diff --git a/doc/tooling/tt_cli/clean.rst b/doc/tooling/tt_cli/clean.rst new file mode 100644 index 0000000000..cc6b4e9c34 --- /dev/null +++ b/doc/tooling/tt_cli/clean.rst @@ -0,0 +1,38 @@ +.. _tt-clean: + +Cleaning instance files +======================= + +.. code-block:: console + + $ tt clean APPLICATION[:APP_INSTANCE] [OPTION ...] + +``tt clean`` cleans stored files of Tarantool instances: logs, snapshots, and +other files. To avoid accidental deletion of files, ``tt clean`` shows +the files it is going to delete and asks for confirmation. + +When called without arguments, cleans files of all applications in the current environment. + + +Options +------- + +.. option:: -f, --force + + Clean files without confirmation. + + +Examples +-------- + +* Clean the files of all instances of the ``app`` application: + + .. code-block:: console + + $ tt clean app + +* Clean the files of the ``master`` instance of the ``app`` application: + + .. code-block:: console + + $ tt clean app:master \ No newline at end of file diff --git a/doc/tooling/tt_cli/cluster.rst b/doc/tooling/tt_cli/cluster.rst new file mode 100644 index 0000000000..eca35d1a82 --- /dev/null +++ b/doc/tooling/tt_cli/cluster.rst @@ -0,0 +1,611 @@ +.. _tt-cluster: + +Managing cluster configurations +=============================== + +.. code-block:: console + + $ tt cluster COMMAND [COMMAND_OPTION ...] + +``tt cluster`` manages :ref:`configurations ` of Tarantool applications. +This command works both with local YAML files in application directories +and with :ref:`centralized configuration storages ` (etcd or Tarantool-based). + +``COMMAND`` is one of the following: + +* :ref:`publish ` +* :ref:`show ` +* :ref:`replicaset ` +* :ref:`failover ` + +.. _tt-cluster-publish: + +publish +------- + +.. code-block:: console + + $ tt cluster publish {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [FILE] [OPTION ...] + +``tt cluster publish`` publishes a cluster configuration using an arbitrary YAML file as a source. + +.. _tt-cluster-publish-local: + +Publishing local configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt cluster publish`` can modify local cluster configurations stored in +``config.yaml`` files inside application directories. + +To write a configuration to a local ``config.yaml``, run ``tt cluster publish`` +with two arguments: + +* the application name. +* the path to a YAML file from which the configuration should be taken. + +.. code-block:: console + + $ tt cluster publish myapp source.yaml + +.. _tt-cluster-publish-centralized: + +Publishing configurations in centralized storages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt cluster publish`` can modify :ref:`centralized cluster configurations ` +in storages of both supported types: etcd or a Tarantool-based configuration storage. + +To publish a configuration from a file to a centralized configuration storage, +run ``tt cluster publish`` with a URI of this storage's +instance as the target. For example, the command below publishes a configuration from ``source.yaml`` +to a local etcd instance running on the default port ``2379``: + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/myapp" source.yaml + +A URI must include a prefix that is unique for the application. It can also include +credentials and other connection parameters. Find the detailed description of the +URI format in :ref:`tt-cluster-uri`. + +.. _tt-cluster-publish-instance: + +Publishing configurations of specific instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to whole cluster configurations, ``tt cluster publish`` can manage +configurations of specific instances within applications: rewrite configurations +of existing instances and add new instance configurations. + +In this case, it operates with YAML fragments that describe a single :ref:`instance configuration section `. +For example, the following YAML file can be a source when publishing an instance configuration: + +.. code-block:: yaml + + # instance_source.yaml + iproto: + listen: + - uri: 127.0.0.1:3311 + +To send an instance configuration to a local ``config.yaml``, run ``tt cluster publish`` +with the ``application:instance`` pair as the target argument: + +.. code-block:: console + + $ tt cluster publish myapp:instance-002 instance_source.yaml + +To send an instance configuration to a centralized configuration storage, specify +the instance name in the ``name`` argument of the storage URI: + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/myapp?name=instance-002" instance_source.yaml + +If the instance already exists, this call overwrites its configuration with the one +from the file. + +To add a new instance configuration from a YAML fragment, specify the name to assign to +the new instance and its location in the cluster topology -- replica set and group -- +in the ``--replicaset`` and ``--group`` options. + +.. note:: + + The ``--group`` option can be omitted if the configuration contains only one group. + +To add a new instance ``instance-003`` to the ``replicaset-001`` replica set: + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/myapp?name=instance-003" instance_source.yaml --replicaset replicaset-001 + + +.. _tt-cluster-publish-validation: + +Configuration validation +~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt cluster publish`` validates configurations against the Tarantool configuration schema +and aborts in case of an error. To skip the validation, add the ``--force`` option: + +.. code-block:: console + + $ tt cluster publish myapp source.yaml --force + +.. _tt-cluster-publish-integrity: + +Publishing configurations with integrity check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +When called with the ``--with-integrity-check`` option, ``tt cluster publish`` +generates a checksum of the configurations it publishes. It signs the checksum using +the private key passed as the option argument, and writes it into the configuration store. + +.. code-block:: console + + $ tt cluster publish "http://localhost:2379/myapp" source.yaml --with-integrity-check private.pem + +If an application configuration is published this way, it can be checked for integrity +using the ``--integrity-check`` :ref:`global option `. + +.. code-block:: console + + $ tt --integrity-check public.pem cluster show myapp + $ tt --integrity-check public.pem start myapp + +Learn more about integrity checks upon application startup and in runtime in the :ref:`tt start ` reference. + +To ensure the configuration integrity when updating it, call ``tt cluster publish`` +with two options: + +- ``--integrity-check PUBLIC_KEY`` global option checks that the configuration wasn't changed + since it was published +- ``--with-integrity-check PRIVATE_KEY`` generates new hash and signature + for future integrity checks of the updated configuration. + +.. code-block:: console + + $ tt --integrity-check public.pem cluster publish \ + --with-integrity-check private.pem \ + "http://localhost:2379/myapp" source.yaml + +.. _tt-cluster-show: + +show +---- + +.. code-block:: console + + $ tt cluster show {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [OPTION ...] + +``tt cluster show`` displays a cluster configuration. + +.. _tt-cluster-show-local: + +Displaying local configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt cluster show`` can read local cluster configurations stored in ``config.yaml`` +files inside application directories. + +To print a local configuration from an application's ``config.yaml``, specify the +application name as an argument: + +.. code-block:: console + + $ tt cluster show myapp + +.. _tt-cluster-show-centralized: + +Displaying configurations from centralized storages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt cluster show`` can display :ref:`centralized cluster configurations ` +from configuration storages of both supported types: etcd or a Tarantool-based configuration storage. + +To print a cluster configuration from a centralized storage, run ``tt cluster show`` +with a storage URI including the prefix identifying the application. For example, to print +``myapp``'s configuration from a local etcd storage: + +.. code-block:: console + + $ tt cluster show "http://localhost:2379/myapp" + + +.. _tt-cluster-show-instance: + +Displaying configurations of specific instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to whole cluster configurations, ``tt cluster show`` can display +configurations of specific instances within applications. In this case, it prints +YAML fragments that describe a single :ref:`instance configuration section `. + +To print an instance configuration from a local ``config.yaml``, use the ``application:instance`` +argument: + +.. code-block:: console + + $ tt cluster show myapp:instance-002 + +To print an instance configuration from a centralized configuration storage, specify +the instance name in the ``name`` argument of the URI: + +.. code-block:: console + + $ tt cluster show "http://localhost:2379/myapp?name=instance-002" + +.. _tt-cluster-show-validation: + +Configuration validation +~~~~~~~~~~~~~~~~~~~~~~~~ + +To validate configurations when printing them with ``tt cluster show``, enable the +validation by adding the ``--validate`` option: + +.. code-block:: console + + $ tt cluster show "http://localhost:2379/myapp" --validate + +.. _tt-cluster-replicaset: + +replicaset +---------- + +.. code-block:: console + + $ tt cluster replicaset SUBCOMMAND {APPLICATION[:APP_INSTANCE] | CONFIG_URI} [OPTION ...] + +``tt cluster replicaset`` manages instances in a replica set. It supports the following +subcommands: + +- :ref:`promote ` +- :ref:`demote ` +- :ref:`expel ` +- :ref:`roles ` + +.. important:: + + ``tt cluster replicaset`` works only with centralized cluster configurations. + To manage replica sets in clusters with local YAML configurations, + use :ref:`tt replicaset `. + +.. _tt-cluster-replicaset-promote: + +promote +~~~~~~~ + +.. code-block:: console + + $ tt cluster replicaset promote CONFIG_URI INSTANCE_NAME [OPTION ...] + +``tt cluster replicaset promote`` promotes the specified instance, +making it a leader of its replica set. +This command works on Tarantool clusters with centralized configuration and +with :ref:`failover modes ` +``off`` and ``manual``. It updates the centralized configuration according to +the specified arguments and reloads it: + +- ``off`` failover mode: the command sets :ref:`database.mode ` + to ``rw`` on the specified instance. + + .. important:: + + If failover is ``off``, the command doesn't consider the modes of other + replica set members, so there can be any number of read-write instances in one replica set. + +- ``manual`` failover mode: the command updates the :ref:`leader ` + option of the replica set configuration. Other instances of this replica set become read-only. + +Example: + +.. code-block:: console + + $ tt cluster replicaset promote "http://localhost:2379/myapp" storage-001-a + +.. _tt-cluster-replicaset-demote: + +demote +~~~~~~ + +.. code-block:: console + + $ tt cluster replicaset demote CONFIG_URI INSTANCE_NAME [OPTION ...] + +``tt cluster replicaset demote`` demotes an instance in a replica set. +This command works on Tarantool clusters with centralized configuration and +with :ref:`failover mode ` +``off``. + +.. note:: + + In clusters with ``manual`` failover mode, you can demote a read-write instance + by promoting a read-only instance from the same replica set with ``tt cluster replicaset promote``. + +The command sets the instance's :ref:`database.mode ` +to ``ro`` and reloads the configuration. + +.. important:: + + If failover is ``off``, the command doesn't consider the modes of other + replica set members, so there can be any number of read-write instances in one replica set. + +.. _tt-cluster-replicaset-expel: + +expel +~~~~~ + +.. code-block:: console + + $ tt cluster replicaset expel CONFIG_URI INSTANCE_NAME [OPTION ...] + +``tt cluster replicaset expel`` expels an instance from the cluster. Example: + +.. code-block:: console + + $ tt cluster replicaset expel "http://localhost:2379" storage-b-002 + +.. _tt-cluster-replicaset-roles: + +roles +~~~~~ + +.. code-block:: console + + $ tt cluster replicaset roles [add|remove] CONFIG_URI ROLE_NAME [OPTION ...] + +``tt cluster replicaset roles`` manages :ref:`application roles ` +in the configuration scope specified in the command options. It has two subcommands: + +* ``add`` adds a role +* ``remove`` removes a role + +Use the ``--global``, ``--group``, ``--replicaset``, ``--instance`` options to specify +the configuration scope to add or remove roles. For example, to add a role to +all instances in a replica set: + +.. code-block:: console + + $ tt cluster replicaset roles add "http://localhost:2379" roles.my-role --replicaset storage-a + +To remove a role defined in the global configuration scope: + +.. code-block:: console + + $ tt cluster replicaset roles remove "http://localhost:2379" roles.my-role --global + + +.. _tt-cluster-replicaset-details: + +Implementation details +~~~~~~~~~~~~~~~~~~~~~~ + +The changes that ``tt cluster replicaset`` makes to the configuration storage +occur transactionally. Each call creates a new revision. In case of a revision mismatch, +an error is raised. + +If the cluster configuration is distributed over multiple keys in the configuration +storage (for example, in two paths ``/myapp/config/k1`` and ``/myapp/config/k2``), +the affected instance configuration can be present in more that one of them. +If it is found under several different keys, the command prompts the user to choose +a key for patching. You can skip the selection by adding the ``-f``/``--force`` option: + +.. code-block:: console + + $ tt cluster replicaset promote "http://localhost:2379/myapp" storage-001-a --force + +In this case, the command selects the key for patching automatically. A key's priority +is determined by the detail level of the instance or replica set configuration stored +under this key. For example, when failover is ``off``, a key with +``instance.database`` options takes precedence over a key with the only ``instance`` field. +In case of equal priority, the first key in the lexicographical order is patched. + +.. _tt-cluster-failover: + +failover +-------- + +.. code-block:: console + + $ tt cluster failover SUBCOMMAND [OPTION ...] + +``tt cluster failover`` manages a :ref:`supervised failover ` in Tarantool clusters. + +- :ref:`switch ` +- :ref:`switch-status ` + +.. important:: + + ``tt cluster failover`` works only with centralized cluster configurations stored in etcd. + + +.. _tt-cluster-failover-switch: + +switch +~~~~~~ + +.. code-block:: console + + $ tt cluster failover switch CONFIG_URI INSTANCE_NAME [OPTION ...] + +``tt cluster failover switch`` appoints the specified instance to be a master. +This command accepts the following arguments and options: + +- ``CONFIG_URI``: A :ref:`URI ` of the cluster configuration storage. +- ``INSTANCE_NAME``: An instance name. +- ``[OPTION ...]``: :ref:`Options ` to pass to the command. + +In the example below, ``tt cluster failover switch`` appoints ``storage-a-002`` to be a master: + +.. code-block:: console + + $ tt cluster failover switch http://localhost:2379/myapp storage-a-002 + To check the switching status, run: + tt cluster failover switch-status http://localhost:2379/myapp b1e938dd-2867-46ab-acc4-3232c2ef7ffe + +Note that the command output includes an identifier of the task responsible for switching a master. +You can use this identifier to see the status of switching a master instance using ``tt cluster failover switch-status``. + + +.. _tt-cluster-failover-switch-status: + +switch-status +~~~~~~~~~~~~~ + +.. code-block:: console + + $ tt cluster failover switch-status CONFIG_URI TASK_ID + +``tt cluster failover switch-status`` shows the status of switching a master instance. +This command accepts the following arguments: + +- ``CONFIG_URI``: A :ref:`URI ` of the cluster configuration storage. +- ``TASK_ID``: An identifier of the task used to switch a master instance. You can find the task identifier in the ``tt cluster failover switch`` command output. + +Example: + +.. code-block:: console + + $ tt cluster failover switch-status http://localhost:2379/myapp b1e938dd-2867-46ab-acc4-3232c2ef7ffe + +.. _tt-cluster-authentication: + +Authentication +-------------- + +There are three ways to pass the credentials for connecting to the centralized configuration storage. +They all apply to both etcd and Tarantool-based storages. The following list +shows these ways ordered by precedence, from highest to lowest: + +#. Credentials specified in the storage URI: ``https://username:password@host:port/prefix``: + + .. code-block:: console + + $ tt cluster show "http://myuser:p4$$w0rD@localhost:2379/myapp" + + +#. ``tt cluster`` options ``-u``/``--username`` and ``-p``/``--password``: + + .. code-block:: console + + $ tt cluster show "http://localhost:2379/myapp" -u myuser -p p4$$w0rD + +#. Environment variables ``TT_CLI_ETCD_USERNAME`` and ``TT_CLI_ETCD_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_ETCD_USERNAME=myuser + $ export TT_CLI_ETCD_PASSWORD=p4$$w0rD + $ tt cluster show "http://localhost:2379/myapp" + +If connection encryption is enabled on the configuration storage, pass the required +SSL parameters in the :ref:`URI arguments `. + +.. _tt-cluster-uri: + +URI format +---------- + +A URI of the cluster configuration storage has the following format: + +.. code-block:: text + + http(s)://[username:password@]host:port[/prefix][?arguments] + +* ``username`` and ``password`` define credentials for connecting to the configuration storage. +* ``prefix`` is a base path identifying a specific application in the storage. +* ``arguments`` defines connection parameters. The following arguments are available: + + * ``name`` -- a name of an instance in the cluster configuration. + * ``key`` -- a target configuration key in the specified ``prefix``. + * ``timeout`` -- a request timeout in seconds. Default: ``3.0``. + * ``ssl_key_file`` -- a path to a private SSL key file. + * ``ssl_cert_file`` -- a path to an SSL certificate file. + * ``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. + * ``ssl_ca_path`` -- a path to a trusted certificate authorities (CA) directory. + * ``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use (for Tarantool-based storage only). + * ``verify_host`` -- verify the certificate’s name against the host. Default ``true``. + * ``verify_peer`` -- verify the peer’s SSL certificate. Default ``true``. + +.. _tt-cluster-options: + +Options +------- + +.. option:: -u, --username STRING + + A username for connecting to the configuration storage. + + See also: :ref:`tt-cluster-authentication`. + +.. option:: -p, --password STRING + + A password for connecting to the configuration storage. + + See also: :ref:`tt-cluster-authentication`. + +.. option:: --force + + **Applicable to:** ``publish``, ``replicaset`` + + - ``publish``: skip validation when publishing. Default: `false` (validation is enabled). + - ``replicaset``: skip key selection for patching. Learn more in :ref:`tt-cluster-replicaset-details:`. + +.. option:: -G, --global + + **Applicable to:** ``replicaset roles`` + + Apply the operation to the global configuration scope, that is, to all instances. + +.. option:: -g, --group + + **Applicable to:** ``publish``, ``replicaset roles`` + + A name of the configuration group to which the operation applies. + +.. option:: -i, --instance + + **Applicable to:** ``replicaset roles`` + + A name of the instance to which the operation applies. + +.. option:: -r, --replicaset + + **Applicable to:** ``publish``, ``replicaset roles`` + + A name of the replica set to which the operation applies. + +.. option:: -t, --timeout UINT + + **Applicable to:** ``failover`` + + A timeout (in seconds) for executing a command. Default: `30`. + +.. option:: --validate + + **Applicable to:** ``show`` + + Validate the printed configuration. Default: `false` (validation is disabled). + +.. option:: -w, --wait + + **Applicable to:** ``failover`` + + Wait while the command completes the execution. Default: `false` (don't wait). + +.. option:: --with-integrity-check STRING + + .. admonition:: Enterprise Edition + :class: fact + + This option is supported by the `Enterprise Edition `_ only. + + **Applicable to:** ``publish``, ``replicaset`` + + Generate hashes and signatures for integrity checks. + + See also: :ref:`tt-cluster-publish-integrity` diff --git a/doc/reference/tooling/tt_cli/commands.rst b/doc/tooling/tt_cli/commands.rst similarity index 77% rename from doc/reference/tooling/tt_cli/commands.rst rename to doc/tooling/tt_cli/commands.rst index 5c68092f1b..1bc9d09678 100644 --- a/doc/reference/tooling/tt_cli/commands.rst +++ b/doc/tooling/tt_cli/commands.rst @@ -26,6 +26,8 @@ help for the given command. - Check an application file for syntax errors * - :doc:`clean ` - Clean instance files + * - :doc:`cluster ` + - Manage a cluster's configuration * - :doc:`completion ` - Generate completion for a specified shell * - :doc:`connect ` @@ -36,6 +38,8 @@ help for the given command. - Create an application from a template * - :doc:`crud ` - Interact with the CRUD module (`Enterprise only `_) + * - :doc:`download ` + - Download the Tarantool Enterprise SDK * - :doc:`export ` - Export data to a file (`Enterprise only `_) * - :doc:`help ` @@ -48,14 +52,22 @@ help for the given command. - Install Tarantool or ``tt`` * - :doc:`instances ` - List enabled applications + * - :doc:`kill ` + - Terminate Tarantool applications or instances + * - :doc:`log ` + - Print instance logs * - :doc:`logrotate ` - Rotate instance logs + * - :doc:`migrations ` + - Manage migrations * - :doc:`pack ` - Package an application * - :doc:`play ` - Play the contents of ``.snap`` or ``.xlog`` files to another Tarantool instance + * - :doc:`replicaset ` + - Manage replica sets * - :doc:`restart ` - - Restart a Tarantool instance + - Restart Tarantool applications or instances * - :doc:`rocks ` - Use the LuaRocks package manager * - :doc:`run ` @@ -63,11 +75,13 @@ help for the given command. * - :doc:`search ` - Search available Tarantool and ``tt`` versions * - :doc:`start ` - - Start a Tarantool instance + - Start Tarantool applications or instances * - :doc:`status ` - - Get the current status of a Tarantool instance + - Get the current status of applications or instances * - :doc:`stop ` - - Stop a Tarantool instance + - Stop Tarantool applications or instances + * - :doc:`tdg2 ` + - Interact with `Tarantool Data Grid 2 `_ clusters * - :doc:`uninstall ` - Uninstall Tarantool or ``tt`` * - :doc:`version ` @@ -83,20 +97,27 @@ help for the given command. cfg check clean + cluster completion connect coredump create crud + download + enable export help import init install instances + kill + log logrotate + migrations pack play + replicaset restart rocks run @@ -104,5 +125,6 @@ help for the given command. start status stop + tdg2 uninstall version diff --git a/doc/reference/tooling/tt_cli/completion.rst b/doc/tooling/tt_cli/completion.rst similarity index 100% rename from doc/reference/tooling/tt_cli/completion.rst rename to doc/tooling/tt_cli/completion.rst diff --git a/doc/tooling/tt_cli/configuration.rst b/doc/tooling/tt_cli/configuration.rst new file mode 100644 index 0000000000..a5352422f5 --- /dev/null +++ b/doc/tooling/tt_cli/configuration.rst @@ -0,0 +1,272 @@ +.. _tt-config: + +Configuration +============= + +.. _tt-config_file: + +Configuration file +------------------ + +The key artifact that defines the ``tt`` environment and various aspects of its +execution is its configuration file. You can generate it with a :ref:`tt init ` call. +In the :ref:`default launch mode `, the file is generated +in the current directory, making it the environment root. + +.. _tt-config_file_name: + +Name and location +~~~~~~~~~~~~~~~~~ + +By default, the configuration file is called ``tt.yaml`` and located in the ``tt`` +environment root directory. It depends on the :ref:`launch mode `. + +It is also possible to pass the configuration file name and location explicitly using +the following ways: + +#. ``-c``/``--cfg`` :ref:`global option ` +#. ``TT_CLI_CFG`` environment variable. + +The ``TT_CLI_CFG`` variable has a lower priority than the ``--cfg`` option. + +.. _tt-config_file_structure: + +Structure +~~~~~~~~~ + +The ``tt`` configuration file is a YAML file with the following structure: + +.. code-block:: yaml + + env: + instances_enabled: path/to/available/applications + bin_dir: path/to/bin_dir + inc_dir: path/to/inc_dir + restart_on_failure: bool + tarantoolctl_layout: bool + modules: + directory: path/to/modules/dir + app: + run_dir: path/to/run_dir + log_dir: path/to/log_dir + wal_dir: path/to/wal_dir + vinyl_dir: path/to/vinyl_dir + memtx_dir: path/to/memtx_dir + repo: + rocks: path/to/rocks + distfiles: path/to/install + ee: + credential_path: path/to/file + templates: + - path: path/to/app/templates1 + - path: path/to/app/templates2 + +.. note:: + + The ``tt`` configuration format and application layout have been changed in version + 2.0. Learn how to upgrade from earlier versions in :ref:`tt-config_migrating-from-1`. + +.. _tt-config_file_env: + +env section +~~~~~~~~~~~ + +.. note:: + + The paths specified in ``env.*`` parameters are relative to the current ``tt`` + environment's root. + +* ``instances_enabled`` -- the directory where :ref:`instances ` + are stored. Default: ``instances.enabled``. +* ``bin_dir`` -- the directory where binary files are stored. Default: ``bin``. +* ``inc_dir`` -- the base directory for storing header files. They will + be placed in the ``include`` subdirectory inside the specified directory. + Default: ``include``. + + .. note:: + + The header files directory path can also be passed using the ``TT_CLI_TARANTOOL_PREFIX`` + environment variable. If it is set, ``tt rocks`` and ``tt build`` commands use the + ``include/tarantool`` directory inside ``TT_CLI_TARANTOOL_PREFIX`` as the + header files directory. + +* ``restart_on_failure`` -- restart the instance on failure: ``true`` or ``false``. + Default: ``false``. +* ``tarantoolctl_layout`` -- use a layout compatible with the deprecated ``tarantoolctl`` + utility for artifact files: control sockets, ``.pid`` files, log files. + Default: ``false``. + +.. _tt-config_file_modules: + +modules section +~~~~~~~~~~~~~~~ + +* ``directory`` -- the directory where :doc:`external modules ` + are stored. + +.. _tt-config_file_app: + +app section +~~~~~~~~~~~ + +.. note:: + + The paths specified in ``app.*_dir`` parameters are relative to the application + location inside the ``instances.enabled`` directory specified in the ``env`` + configuration section. For example, the default location of the ``myapp`` + application's logs is ``instances.enabled/myapp/var/log``. + Inside this location, ``tt`` creates separate directories for each application + instance that runs in the current environment. + +* ``run_dir``-- the directory for instance runtime artifacts, such as console + sockets or PID files. Default: ``var/run``. +* ``log_dir`` -- the directory where log files are stored. Default: ``var/log``. +* ``wal_dir`` -- the directory where write-ahead log (``.xlog``) files are stored. + Default: ``var/lib``. +* ``memtx_dir`` -- the directory where memtx stores snapshot (``.snap``) files. + Default: ``var/lib``. +* ``vinyl_dir`` -- the directory where vinyl files or subdirectories are stored. + Default: ``var/lib``. + +.. _tt-config_file_repo: + +repo section +~~~~~~~~~~~~ + +* ``rocks`` -- the directory where rocks files are stored. + + .. note:: + + The rocks directory path can be passed in the ``TT_CLI_REPO_ROCKS`` + environment variable instead. The variable is also used if the directory + specified in ``repo.rocks`` does not include a repository manifest. + +* ``distfiles`` -- the directory where installation files are stored. + +.. _tt-config_file_ee: + +ee section +~~~~~~~~~~ + +* ``credential_path`` -- a path to the file with credentials used for + downloading Tarantool Enterprise Edition (Tarantool customer zone credentials). + The file should contain a username and a password, each on a separate line. + Find an example in the :ref:`tt install ` command + reference. + + .. note:: + + The customer zone credentials can also be passed in the + ``TT_CLI_EE_USERNAME`` and ``TT_CLI_EE_PASSWORD`` environment variables. + +templates section +~~~~~~~~~~~~~~~~~ + +* ``path`` -- a path to application templates used for creating applications with + :ref:`tt create `. May be specified more than once. + +.. _tt-config_modes: + +Launch modes +------------ + +``tt`` launch mode defines its working directory and the way it searches for the +configuration file. There are three launch modes: + +* default +* system +* local + +.. _tt-config_modes-default: + +Default launch +~~~~~~~~~~~~~~ + +**Global option**: none + +**Configuration file**: searched from the current directory to the root. +Taken from ``/etc/tarantool`` if the file is not found. + +**Working directory**: The directory where the configuration file is found. + +.. _tt-config_modes-system: + +System launch +~~~~~~~~~~~~~ + +**Global option**: ``--system`` or ``-S`` + +**Configuration file**: Taken from ``/etc/tarantool``. + +**Working directory**: Current directory. + +.. _tt-config_modes-local: + +Local launch +~~~~~~~~~~~~ + +**Global option**: ``--local=DIRECTORY`` or ``-L=DIRECTORY`` + +**Configuration file**: Searched from the specified directory to the root. +Taken from ``/etc/tarantool`` if the file is not found. + +**Working directory**: The specified directory. If ``tarantool`` or ``tt`` +executable files are found in the working directory, they will be used. + +.. _tt-config_migrating-from-1: + +Migrating from tt 1.* to 2.0 or later +------------------------------------- + +The `tt` configuration and application layout were changed in version 2.0. +If you are using ``tt`` 1.*, complete the following steps to migrate to ``tt`` 2.0 or later: + +#. **Update the tt configuration file**. + In tt 2.0, the following changes were made to the configuration file: + + * The root section ``tt`` was removed. Its child sections -- ``app``, ``repo``, + ``modules``, and other -- have been moved to the top level. + * Environment configuration parameters were moved from the ``app`` section + to the new section ``env``. These parameters are ``instances.enabled``, + ``bin_dir``, ``inc_dir``, and ``restart_on_failure``. + * The paths in the ``app`` section are now relative to the app directory in ``instances.enabled`` + instead of the environment root. + + You can use :ref:`tt init ` to generate a configuration file with + the new structure and default parameter values. + +#. **Move application artifacts**. + With ``tt`` 1.*, application artifacts (logs, snapshots, pid, and other files) + were created in the ``var`` directory inside the *environment root*. Starting from + ``tt`` 2.0, these artifacts are created in the ``var`` directory inside the + *application directory*, which is ``instances.enabled/``. This is + how an application directory looks: + + .. code-block:: text + + instances.enabled/app/ + ├── init.lua + ├── instances.yml + └── var + ├── lib + │ ├── instance1 + │ └── instance2 + ├── log + │ ├── instance1 + │ └── instance2 + └── run + ├── instance1 + └── instance2 + + To continue using existing application artifacts after migration from ``tt`` 1.*: + + #. Create the ``var`` directory inside the application directory. + #. Create the ``lib``, ``log``, and ``run`` directories inside ``var``. + #. Move directories with instance artifacts from the old ``var`` directory + to the new ``var`` directories in applications' directories. + +#. **Move the files accessed from the application code**. + The working directory of instance processes was changed from the ``tt`` working + directory to the application directory inside ``instances.enabled``. If the + application accesses files using relative paths, move the files accordingly + or adjust the application code. \ No newline at end of file diff --git a/doc/tooling/tt_cli/connect.rst b/doc/tooling/tt_cli/connect.rst new file mode 100644 index 0000000000..443a362ad1 --- /dev/null +++ b/doc/tooling/tt_cli/connect.rst @@ -0,0 +1,155 @@ +.. _tt-connect: + +Connecting to a Tarantool instance +================================== + +.. code-block:: console + + $ tt connect {URI|INSTANCE_NAME} [OPTION ...] + + +``tt connect`` connects to a Tarantool instance by its URI or instance name specified +in the current environment. + +Options +------- + +.. option:: -u USERNAME, --username USERNAME + + A Tarantool user for connecting to the instance. + +.. option:: -p PASSWORD, --password PASSWORD + + The user's password. + +.. option:: -f FILEPATH, --file FILEPATH + + Connect and evaluate the script from a file. + + ``-`` – read the script from stdin. + +.. option:: -i, --interactive + + Enter the interactive mode after evaluating the script passed in ``-f``/``--file``. + +.. option:: -l LANGUAGE, --language LANGUAGE + + The input language of the :ref:`tt interactive console `: + ``lua`` (default) or ``sql``. + +.. option:: -x FORMAT, --outputformat FORMAT + + The output format of the :ref:`tt interactive console `: + ``yaml`` (default), ``lua``, ``table``, ``ttable``. + +.. option:: --sslcertfile FILEPATH + + The path to an SSL certificate file for encrypted connections. + +.. option:: --sslkeyfile FILEPATH + + The path to a private SSL key file for encrypted connections. + +.. option:: --sslcafile FILEPATH + + The path to a trusted certificate authorities (CA) file for encrypted connections. + +.. option:: --sslciphers STRING + + The list of SSL cipher suites used for encrypted connections, separated by colons (``:``). + +Details +------- + +To connect to an instance, ``tt`` typically needs its URI -- the host name or IP address +and the port. + +You can also connect to instances in the same ``tt`` environment +(that is, those that use the same :ref:`configuration file ` and Tarantool installation) +by their instance names. + +Authentication +~~~~~~~~~~~~~~ + +When connecting to an instance by its URI, ``tt connect`` establishes a remote connection +for which authentication is required. Use one of the following ways to pass the +username and the password: + +* The ``-u`` (``--username``) and ``-p`` (``--password``) options: + + .. code-block:: console + + $ tt connect 192.168.10.10:3301 -u myuser -p p4$$w0rD + +* The connection string: + + .. code-block:: console + + $ tt connect myuser:p4$$w0rD@192.168.10.10:3301 + +* Environment variables ``TT_CLI_USERNAME`` and ``TT_CLI_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_USERNAME=myuser + $ export TT_CLI_PASSWORD=p4$$w0rD + $ tt connect 192.168.10.10:3301 + +If no credentials are provided for a remote connection, the user is automatically ``guest``. + +.. note:: + + Local connections (by instance name instead of the URI) don't require authentication. + +Encrypted connection +~~~~~~~~~~~~~~~~~~~~ + +To connect to instances that use :ref:`SSL encryption `, +provide the SSL certificate and SSL key files in the ``--sslcertfile`` and ``--sslkeyfile`` options. +If necessary, add other SSL parameters -- ``--sslcafile`` and ``--sslciphers``. + +Script evaluation +~~~~~~~~~~~~~~~~~ + +By default, ``tt connect`` opens an :ref:`interactive tt console `. +Alternatively, you can open a connection to evaluate a Lua script from a file or stdin. +To do this, pass the file path in the ``-f`` (``--file``) option or use ``-f -`` +to take the script from stdin. + +.. code-block:: console + + $ tt connect app -f test.lua + +Examples +-------- + +* Connect to the ``app`` instance in the same environment: + + .. code-block:: console + + $ tt connect app + +* Connect to the ``master`` instance of the ``app`` application in the same environment: + + .. code-block:: console + + $ tt connect app:master + +* Connect to the ``192.168.10.10`` host on port ``3301`` with authentication: + + .. code-block:: console + + $ tt connect 192.168.10.10:3301 -u myuser -p p4$$w0rD + +* Connect to the ``app`` instance and evaluate the code from the ``test.lua`` file: + + .. code-block:: console + + $ tt connect app -f test.lua + +* Connect to the ``app`` instance and evaluate the code from stdin: + + .. code-block:: console + + $ echo "function test() return 1 end" | tt connect app -f - # Create the test() function + $ echo "test()" | tt connect app -f - # Call this function \ No newline at end of file diff --git a/doc/tooling/tt_cli/coredump.rst b/doc/tooling/tt_cli/coredump.rst new file mode 100644 index 0000000000..37b5577e41 --- /dev/null +++ b/doc/tooling/tt_cli/coredump.rst @@ -0,0 +1,98 @@ +.. _tt-coredump: + +Manipulating Tarantool core dumps +================================= + +.. code-block:: console + + $ tt coredump COMMAND [COMMAND_OPTION ...] + +``tt coredump`` provides commands for manipulating Tarantool core dumps. + +To be able to investigate Tarantool crashes, make sure that core dumps are enabled +on the host. Here is the :ref:`instruction on enabling core dumps on Unix systems `. + +``COMMAND`` is one of the following: + +* :ref:`pack ` +* :ref:`unpack ` +* :ref:`inspect ` + +.. important:: + + ``tt coredump`` is not supported on macOS. + +.. _tt-coredump-pack: + +pack +---- + +.. code-block:: console + + $ tt coredump pack COREDUMP_FILE + +Pack a Tarantool core dump and supporting data into a ``tar.gz`` archive. +It includes: + +* the Tarantool executable +* Tarantool version information +* OS information +* shared libraries +* the `GNU debugger `__ with extensions. + +Pack a ``tar.gz`` file with a Tarantool core dump and supporting data: + +.. code-block:: console + + $ tt coredump pack name.core + +.. _tt-coredump-unpack: + +unpack +------ + +.. code-block:: console + + $ tt coredump unpack ARCHIVE + +Unpack a Tarantool core dump archive created with ``tt coredump pack`` into a new directory: + +.. code-block:: console + + $ tt coredump unpack tarantool-core-dump.tar.gz + + +.. _tt-coredump-inspect: + +inspect +------- + +.. code-block:: console + + $ tt coredump inspect [ARCHIVE|DIRECTORY] [-s] + +Inspect a Tarantool core dump with the `GNU debugger `__ (``gdb``). +The command argument can be either an archive file produced with ``tt coredump pack`` +or directory where such an archive is extracted. + +Inspect the core dump archive with ``gdb``: + +.. code-block:: console + + $ tt coredump inspect tarantool-core-dump.tar.gz + +Inspect the unpacked core dump directory with ``gdb``: + +.. code-block:: console + + $ tt coredump inspect tarantool-core-dump + + +Options +------- + +.. option:: -s + + **Applicable to**: ``inspect`` + + Specify the location of Tarantool sources. \ No newline at end of file diff --git a/doc/tooling/tt_cli/create.rst b/doc/tooling/tt_cli/create.rst new file mode 100644 index 0000000000..a2df9890f1 --- /dev/null +++ b/doc/tooling/tt_cli/create.rst @@ -0,0 +1,240 @@ +.. _tt-create: + +Creating an application from a template +======================================= + +.. code-block:: console + + $ tt create TEMPLATE_NAME [OPTION ...] + + +``tt create`` creates a new Tarantool application from a template. + +*Application templates* speed up the development of Tarantool applications by +defining their initial structure and content. A template can include application +code, configuration, build scripts, and other resources. + +``tt`` comes with built-in templates for popular use cases. You can also create +custom templates for specific purposes. + +.. _tt-create-built-in: + +Built-in templates +------------------ + +There are the following built-in templates: + +- ``vshard_cluster``: a sharded cluster application for Tarantool 3.0 or later. +- ``single_instance``: a single-instance application for Tarantool 3.0 or later. +- ``cartridge``: a Cartridge cluster application for Tarantool 2.x. + + .. important:: + + The Tarantool Cartridge framework is deprecated and is not compatible with + Tarantool 3.0 and later. + +To create the ``app1`` application in the current ``tt`` environment from the built-in +``vshard_cluster`` template: + +.. code-block:: console + + $ tt create vshard_cluster --name app1 -dst /opt/tt/apps/ + +The command requests cluster topology parameters, such as the number of shards +or routers, interactively during the execution. + +To create the application in the ``/opt/tt/apps`` directory with default cluster +topology and force rewrite the application directory if it already exists: + +.. code-block:: console + + $ tt create vshard_cluster --name app1 -f --non-interactive -dst /opt/tt/apps/ + + +.. _tt-create-custom: + +Creating custom application templates +------------------------------------- + +``tt`` searches for custom templates in the directories specified in the ``templates`` +section of its :ref:`configuration file `. + +To create the application ``app1`` from the ``simple_app`` custom template in the current directory: + +.. code-block:: console + + $ tt create simple_app --name app1 + +.. _tt-create-custom-structure: + +Template structure +~~~~~~~~~~~~~~~~~~ + +Application templates are directories with files. + +The main file of a template is its *manifest*. It defines how the applications +are instantiated from this template. + +A template manifest is a YAML file named ``MANIFEST.yaml``. It can contain the following sections: + +* ``description`` -- the template description. +* ``vars`` -- :ref:`template variables `. +* ``pre-hook`` and ``post-hook`` -- paths to executables to run before and after the template + instantiation. +* ``include`` -- a list of files to keep in the application directory after + instantiation. If this section is omitted, the application will contain all template files + and directories. + +All sections are optional. + +Example: + +.. code-block:: yaml + + description: Template description + vars: + - prompt: User name + name: user_name + default: admin + re: ^\w+$ + + - prompt: Retry count + default: "3" + name: retry_count + re: ^\d+$ + pre-hook: ./hooks/pre-gen.sh + post-hook: ./hooks/post-gen.sh + include: + - init.lua + - instances.yml + +Files and directories of a template are copied to the application directory +according to the ``include`` section of the manifest (or its absence). + +.. note:: + + Don't include the ``.rocks`` directory in application templates. + To specify application dependencies, use the ``.rockspec`` files. + +There is a special file type ``*.tt.template``. The content of such files is +adjusted for each application with the help of :ref:`template variables `. +During the instantiation, the variables in these files are replaced with provided +values and the ``*.tt.template`` extension is removed. + +.. _tt-create-custom-variables: + +Variables +~~~~~~~~~ + +Templates variables are replaced with their values provided upon the instantiation. + +All templates have the ``name`` variable. Its value is taken from the ``--name`` option. + +To add other variables, define them in the ``vars`` section of the template manifest. +A variable can have the following attributes: + +* ``prompt``: a line of text inviting to enter the variable value in the interactive mode. Required. +* ``name``: the variable name. Required. +* ``default``: the default value. Optional. +* ``re``: a regular expression that the value must match. Optional. + +Example: + +.. code-block:: yaml + + vars: + - prompt: Cluster cookie + name: cluster_cookie + default: cookie + re: ^\w+$ + +Variables can be used in all file names and the content of ``*.tt template`` files. + +.. note:: + + Variables don't work in directory names. + +To use a variable, enclose its name with a period in the beginning in double curly braces: +``{{.var_name}}`` (as in the `Golang text templates `__ +syntax). + +Examples: + +* ``init.lua.tt.template`` file: + + .. code:: lua + + local app_name = {{.name}} + local login = {{.user_name}} + +* A file name ``{{.user_name}}.txt`` + +Variables receive their values during the template instantiation. By default, ``tt create`` +asks you to provide the values interactively. You can use the ``-s`` (or ``--non-interactive``) +option to disable the interactive input. In this case, the values are searched in the following order: + +* In the ``--var`` option. Pass a string of the ``var=value`` format after the ``--var`` + option. You can pass multiple variables, each after a separate ``--var`` option: + + .. code-block:: console + + $ tt create template app --var user_name=admin + +* In a file. Specify ``var=value`` pairs in a plain text file, each on a new line, and + pass it as the value of the ``--vars-file`` option: + + .. code-block:: console + + $ tt create template app --vars-file variables.txt + + ``variables.txt`` can look like this: + + .. code-block:: text + + user_name=admin + password=p4$$w0rd + version=2 + +If a variable isn't initialized in any of these ways, the default value +from the manifest is used. + +You can combine different ways of passing variables in a single call of ``tt create``. + +.. _tt-create-custom-directory: + +Application directory +--------------------- + +By default, the application appears in the directory named after the provided +application name (``--name`` value). + +To change the application location, use the ``-dst`` option. + +.. _tt-create-options: + +Options +------- + +.. option:: -d PATH, --dst PATH + + Path to the directory where the application will be created. + +.. option:: -f, --force + + Force rewrite the application directory if it already exists. + +.. option:: --name NAME + + Application name. + +.. option:: -s, --non-interactive + + Non-interactive mode. + +.. option:: --var [VAR=VALUE ...] + + Variable definition. Usage: ``--var var_name=value``. + +.. option:: --vars-file FILEPATH + + Path to the file with variable definitions. \ No newline at end of file diff --git a/doc/reference/tooling/tt_cli/crud.rst b/doc/tooling/tt_cli/crud.rst similarity index 100% rename from doc/reference/tooling/tt_cli/crud.rst rename to doc/tooling/tt_cli/crud.rst diff --git a/doc/tooling/tt_cli/developing_apps.rst b/doc/tooling/tt_cli/developing_apps.rst new file mode 100644 index 0000000000..7494acef22 --- /dev/null +++ b/doc/tooling/tt_cli/developing_apps.rst @@ -0,0 +1,12 @@ +.. _tt-developing-apps: + +Developing applications +======================= + +This section describes ``tt`` capabilities related to developing :ref:`cluster applications `. + +.. toctree:: + :maxdepth: 1 + + instance_config + start_stop_instance diff --git a/doc/tooling/tt_cli/download.rst b/doc/tooling/tt_cli/download.rst new file mode 100644 index 0000000000..8b2cac8d81 --- /dev/null +++ b/doc/tooling/tt_cli/download.rst @@ -0,0 +1,65 @@ +.. _tt-download: + +Downloading Tarantool Enterprise SDK +==================================== + +.. code-block:: console + + $ tt download VERSION [OPTION ...] + +``tt download`` downloads Tarantool Enterprise SDK from the customer zone. + +The ``VERSION`` is a part of the SDK archive name between ``tarantool-enterprise-sdk-`` +and the platform identifier. For example, to download ``tarantool-enterprise-sdk-gc64-3.0.0-0-gf58f7d82a-r23.linux.x86_64.tar.gz``, +run: + +.. code-block:: console + + $ tt download gc64-3.0.0-0-gf58f7d82a-r23 + +``tt`` automatically chooses the bundle for the current platform. + +.. _tt-download-authentication: + +Authentication +~~~~~~~~~~~~~~ + +To download the Tarantool Enterprise SDK using ``tt download``, you need to provide +access credentials for the Tarantool customer zone. Use one of the following ways to pass +the username and the password: + +* A text file specified in the ``ee.credential_path`` parameter of the + :ref:`tt environment configuration `: + + .. code-block:: yaml + + # tt.yaml + # ... + ee: + credential_path: cred.txt + + `cred.txt` should contain a username and a password on separate lines: + + .. code-block:: text + + myuser@tarantool.io + p4$$w0rD + +* Environment variables ``TT_CLI_EE_USERNAME`` and ``TT_CLI_EE_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_EE_USERNAME=myuser@tarantool.io + $ export TT_CLI_EE_PASSWORD=p4$$w0rD + $ tt download gc64-3.0.0-0-gf58f7d82a-r23 + +Options +------- + +.. option:: --dev + + Download a development build. + +.. option:: --directory-prefix STRING + + The downloaded SDK location. Default: ``.`` (current directory). diff --git a/doc/tooling/tt_cli/enable.rst b/doc/tooling/tt_cli/enable.rst new file mode 100644 index 0000000000..9dfbb1112c --- /dev/null +++ b/doc/tooling/tt_cli/enable.rst @@ -0,0 +1,21 @@ +.. _tt-enable: + +Adding external applications to environments +============================================ + +.. code-block:: console + + $ tt enable {APPLICATION|SCRIPT} + +``tt enable`` adds an external Tarantool application to the current environment +by creating a symlink to it in the ``instances.enabled`` directory. + +To add the application located in ``/home/tt-user/external_app`` to the current +``tt`` environment: + +.. code-block:: console + + $ tt enable /home/tt-user/external_app + +Once the application is added, you can work with it the same way as with applications +created in this environment. \ No newline at end of file diff --git a/doc/tooling/tt_cli/export.rst b/doc/tooling/tt_cli/export.rst new file mode 100644 index 0000000000..69197f3402 --- /dev/null +++ b/doc/tooling/tt_cli/export.rst @@ -0,0 +1,343 @@ +.. _tt-export: + +Exporting data +============== + +.. admonition:: Enterprise Edition + :class: fact + + This command is supported by the `Enterprise Edition `_ only. + + +.. code-block:: console + + $ tt [crud|tdg2] export URI SPACE:FILE ... [EXPORT_OPTION ...] + +``tt [crud|tdg2] export`` exports a space's data to a file. Three export commands +cover the following cases: + +* ``tt export`` exports data from a replica set using the :ref:`box.space ` API. +* ``tt crud export`` exports data from a sharded cluster through a router using the `CRUD `_ module. +* ``tt tdg2 export`` exports data from a `Tarantool Data Grid 2 `_ cluster + through its `connector `_ using `TDG2 Repository API `_. + +``tt [crud|tdg2] export`` takes the following arguments: + +* ``URI``: The URI of a router instance if ``crud`` is used. Otherwise, it should specify the URI of a storage. +* ``FILE``: The name of a file for storing exported data. +* ``SPACE``: The name of a space from which data is exported. + +.. NOTE:: + + :ref:`Read access ` to the space is required to export its data. + +.. _tt-export-output-format: + +Output format +------------- + +``tt export`` exports data in the following formats: + +* ``tt export`` and ``tt crud export``: CSV +* ``tt tdg2 export``: JSON lines + +.. _tt-export-limitations: + +Limitations +----------- + +Exporting isn't supported for the :ref:`interval ` field type. + + +.. _tt-export-default: + +Exporting with default settings +------------------------------- + +The command below exports data of the ``customers`` space to the ``customers.csv`` file: + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv + +If the ``customers`` space has five fields (``id``, ``bucket_id``, ``firstname``, ``lastname``, and ``age``), the file with exported data might look like this: + +.. code-block:: text + + 1,477,Andrew,Fuller,38 + 2,401,Michael,Suyama,46 + 3,2804,Robert,King,33 + # ... + +If a tuple contains a ``null`` value, for example, ``[1, 477, 'Andrew', null, 38]``, it is exported as an empty value: + +.. code-block:: text + + 1,477,Andrew,,38 + + +.. _tt-export-header: + +Exporting headers +----------------- + +To export data with a space's field names in the first row of the CSV file, use the ``--header`` option: + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv \ + --header + +In this case, field values start from the second row, for example: + +.. code-block:: text + + id,bucket_id,firstname,lastname,age + 1,477,Andrew,Fuller,38 + 2,401,Michael,Suyama,46 + 3,2804,Robert,King,33 + # ... + + +.. _tt-export-compound-data: + +Exporting compound data +----------------------- + +In the CSV format, ``tt`` exports empty values by default for fields containing compound data such as arrays or maps. +To export compound values in a specific format, use the ``--compound-value-format`` option. +For example, the command below exports compound values to CSV serialized in JSON: + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv \ + --compound-value-format json + +.. _tt-export-tdg2: + +Exporting from Tarantool Data Grid 2 +------------------------------------ + +.. note:: + + In the TDG2 data model, a **type** represents a Tarantool space, and an **object** + of a type represents a tuple in the type's underlying space. + +The command below exports data of the ``customers`` type from a TDG2 cluster to +the ``customers.jsonl`` file: + +.. code-block:: console + + $ tt tdg2 export localhost:3301 customers:customers.jsonl + +If token authentication is enabled in TDG2, pass the application token in the ``--token`` option: + +.. code-block:: console + + $ tt tdg2 export localhost:3301 customers:customers.jsonl \ + --token=2fc136cf-8cae-4655-a431-7c318967263d + +If the ``customers`` type has four fields (``id``, ``firstname``, ``lastname``, and ``age``), +the file with exported data might look like this: + +.. code-block:: json + + {"age":30,"first_name":"Samantha","id":1,"second_name":"Carter"} + {"age":41,"first_name":"Fay","id":2,"second_name":"Rivers"} + {"age":74,"first_name":"Milo","id":4,"second_name":"Walters"} + +``null`` field values are skipped: + +.. code-block:: json + + {"age":13,"first_name":"Zachariah","id":3} + +Object fields that contain maps with non-string keys are converted to maps with string keys. + +TDG2 sets a limit on the number of objects transferred from each storage during a query execution +(the `hard-limits.returned `_ +TDG2 configuration parameter). If an export batch size (``--batch-size`` parameter) +is greater than this limit, it is possible that more than ``hard-limits.returned`` objects +will be requested from one storage and export will fail. +To make sure that ``hard-limits.returned`` is never exceeded during an export operation, +set the export batch size less or equal to this limit. + +For example, if your TDG2 cluster has a 1000 objects ``hard-limits.returned`` limit: + +.. code-block:: yaml + + # tdg2 config.yaml + # ... + hard-limits.returned: 1000 + +Set the ``tt tdg2 export`` batch size less or equal to 1000: + +.. code-block:: console + + $ tt tdg2 export localhost:3301 customers:customers.jsonl --batch-size=1000 + +.. _tt-export-auth: + +Authentication +-------------- + +When connecting to the cluster with enabled authentication, specify access credentials +in the ``--username`` and ``--password`` command options: + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv \ + --username myuser --password p4$$w0rD + +.. _tt-export-ssl: + +Encrypted connection +-------------------- + +To connect to instances that use :ref:`SSL encryption `, +provide the SSL certificate and SSL key files in the ``--sslcertfile`` and ``--sslkeyfile`` options. +If necessary, add other SSL parameters in the ``--ssl*`` options. + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv \ + --username myuser --password p4$$w0rD \ + --auth pap-sha256 --sslcertfile certs/server.crt \ + --sslkeyfile certs/server.key + +For connections that use SSL but don't require additional parameters, add the ``--use-ssl`` +option: + +.. code-block:: console + + $ tt crud export localhost:3301 customers:customers.csv \ + --username myuser --password p4$$w0rD \ + --use-ssl + +.. _tt-export-options: + +Options +------- + +.. option:: --auth STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + Authentication type: ``chap-sha1``, ``pap-sha256``, or ``auto``. + +.. option:: --batch-queue-size INT + + The maximum number of tuple batches in a queue between a fetch and write threads (the default is ``32``). + + ``tt`` exports data using two threads: + + * A *fetch* thread makes requests and receives data from a Tarantool instance. + * A *write* thread encodes received data and writes it to the output. + + The fetch thread uses a queue to pass received tuple batches to the write thread. + If a queue is full, the fetch thread waits until the write thread takes a batch from the queue. + +.. option:: --batch-size INT + + The number of tuples to transfer per request. The default is: + + * ``10000`` for ``tt export`` and ``tt crud export``. + * ``100`` for ``tt tdg2 export``. + + .. important:: + + When using ``tt tdg2 export``, make sure that the batch size does not exceed + the ``hard-limits.returned`` TDG2 parameter value set on the cluster. + +.. option:: --compound-value-format STRING + + **Applicable to:** ``tt export``, ``tt crud export`` + + A format used to export compound values like arrays or maps. + By default, ``tt`` exports empty values for fields containing such values. + + Supported formats: ``json``. + + See also: :ref:`Exporting compound data `. + +.. option:: --header + + **Applicable to:** ``tt export``, ``tt crud export`` + + Add field names in the first row. + + See also: :ref:`Exporting headers `. + +.. option:: --password STRING + + A password used to connect to the instance. + +.. option:: --readview + + **Applicable to:** ``tt export``, ``tt crud export`` + + Export data using a :ref:`read view `. + +.. option:: --sslcafile STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + The path to a trusted certificate authorities (CA) file for encrypted connections. + + See also :ref:`tt-export-ssl`. + +.. option:: --sslcertfile STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + The path to an SSL certificate file for encrypted connections. + + See also :ref:`tt-export-ssl`. + +.. option:: --sslciphersfile STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + The list of SSL cipher suites used for encrypted connections, separated by colons (``:``). + + See also :ref:`tt-export-ssl`. + +.. option:: --sslkeyfile STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + The path to a private SSL key file for encrypted connections. + + See also :ref:`tt-export-ssl`. + +.. option:: --sslpassword STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + The password for the SSL key file for encrypted connections. + + See also :ref:`tt-export-ssl`. + +.. option:: --sslpasswordfile STRING + + **Applicable to:** ``tt crud export``, ``tt tdg2 export`` + + A file with list of passwords to the SSL key file for encrypted connections. + + See also :ref:`tt-export-auth`. + +.. option:: --token STRING + + **Applicable to:** ``tt tdg2 export`` + + An application token for connecting to TDG2. + +.. option:: --use-ssl STRING + + Use SSL without providing any additional SSL parameters. + + See also :ref:`tt-export-ssl`. + +.. option:: --username STRING + + A username for connecting to the instance. diff --git a/doc/reference/tooling/tt_cli/external_modules.rst b/doc/tooling/tt_cli/external_modules.rst similarity index 100% rename from doc/reference/tooling/tt_cli/external_modules.rst rename to doc/tooling/tt_cli/external_modules.rst diff --git a/doc/tooling/tt_cli/global_options.rst b/doc/tooling/tt_cli/global_options.rst new file mode 100644 index 0000000000..a8daa7398e --- /dev/null +++ b/doc/tooling/tt_cli/global_options.rst @@ -0,0 +1,59 @@ +.. _tt-global-options: + +Global options +============== + +.. important:: + + Global options of ``tt`` must be passed before its commands and other options. + For example: + + .. code-block:: console + + $ tt --cfg tt-conf.yaml start app + +``tt`` has the following global options: + +.. option:: -c=file, --cfg=file, + + Path to the :ref:`configuration file `. + + Alternatively, this path can be passed in the ``TT_CLI_CFG`` environment variable. + +.. option:: -h, --help + + Display help. + +.. option:: --integrity-check PUBLIC_KEY + + .. admonition:: Enterprise Edition + :class: fact + + This option is supported by the `Enterprise Edition `_ only. + + Perform an integrity check using the specified public key before executing the operation. + Learn more in :ref:`tt-start-integrity-check`. + +.. option:: -I, --internal + + Force the use of an internal module even if there is an + :doc:`external module ` with the same name. + +.. option:: -L=DIRECTORY, --local=DIRECTORY + + Use the ``tt`` environment from the specified directory. + Learn more about the :ref:`local launch mode `. + +.. option:: -s, --self + + Use the current ``tt`` version instead of executing the one located + in the :ref:`bin_dir ` directory. + +.. option:: -S, --system + + Use the ``tt`` environment installed in the system. + Learn more about the :ref:`system launch mode `. + +.. option:: -V, --verbose + + Display detailed processing information (verbose mode). diff --git a/doc/reference/tooling/tt_cli/help.rst b/doc/tooling/tt_cli/help.rst similarity index 100% rename from doc/reference/tooling/tt_cli/help.rst rename to doc/tooling/tt_cli/help.rst diff --git a/doc/tooling/tt_cli/import.rst b/doc/tooling/tt_cli/import.rst new file mode 100644 index 0000000000..dad406789a --- /dev/null +++ b/doc/tooling/tt_cli/import.rst @@ -0,0 +1,525 @@ +.. _tt-import: + +Importing data +============== + +.. admonition:: Enterprise Edition + :class: fact + + This command is supported by the `Enterprise Edition `_ only. + + +.. code-block:: console + + $ tt [crud|tdg2] import URI FILE:SPACE [IMPORT_OPTION ...] + # or + $ tt [crud|tdg2] import URI :SPACE < FILE [IMPORT_OPTION ...] + +``tt [crud|tdg] import`` imports data from a file to a space. Three import commands +cover the following cases: + +* ``tt import`` imports data into a replica set through its master instance using the :ref:`box.space ` API. +* ``tt crud import`` imports data into a sharded cluster through a router using the `CRUD `_ module. +* ``tt tdg2 import`` imports data into a `Tarantool Data Grid 2 `_ cluster + through its router using the ``repository.put`` function of the `TDG2 Repository API `_. + +``tt [crud|tdg2] import`` takes the following arguments: + +* ``URI``: The URI of a router instance if ``crud`` is used. Otherwise, it should specify the URI of a storage. +* ``FILE``: The name of a file containing data to be imported. +* ``SPACE``: The name of a space to which data is imported. + +.. NOTE:: + + :ref:`Write access ` to the space and `execute` access to `universe` are required to import data. + +.. _tt-import-format: + +Input file format +----------------- + +``tt import`` imports data from the following formats: + +* ``tt import`` and ``tt crud import``: CSV +* ``tt tdg2 import``: JSON lines + +.. _tt-import-limitations: + +Limitations +----------- + +Importing isn't supported for the :ref:`interval ` field type. + + +.. _tt-import-match-fields: + +Matching of input and space fields +---------------------------------- + + +.. _tt-import-match-fields-auto: + +Automatic matching +~~~~~~~~~~~~~~~~~~ + +Suppose that you have the ``customers.csv`` file with a header containing field names in the first row: + +.. code-block:: text + + id,firstname,lastname,age + 1,Andrew,Fuller,38 + 2,Michael,Suyama,46 + 3,Robert,King,33 + # ... + +If the target ``customers`` space has fields with the same names, you can import data using the ``--header`` and ``--match`` options specified as follows: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header \ + --match=header + +In this case, fields in the input file and the target space are matched automatically. +You can also match fields :ref:`manually ` if field names in the input file and the target space differ. +Note that if you're importing data into a cluster, you don't need to specify the ``bucket_id`` field. +The CRUD module generates ``bucket_id`` values automatically. + +.. _tt-import-match-fields-manual: + +Manual matching +~~~~~~~~~~~~~~~ + +The ``--match`` option enables importing data by matching field names in the input file and the target space manually. +Suppose that you have the following ``customers.csv`` file with four fields: + +.. code-block:: text + + customer_id,name,surname,customer_age + 1,Andrew,Fuller,38 + 2,Michael,Suyama,46 + 3,Robert,King,33 + # ... + +If the target ``customers`` space has the ``id``, ``firstname``, ``lastname``, and ``age`` fields, +you can configure mapping as follows: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header \ + --match "id=customer_id;firstname=name;lastname=surname;age=customer_age" + +Similarly, you can configure mapping using numeric field positions in the input file: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header \ + --match "id=1;firstname=2;lastname=3;age=4" + +Below are the rules if some fields are missing in input data or space: + +* If a space has fields that are not specified in input data, ``tt [crud] import`` tries to insert ``null`` values. +* If input data contains fields missing in a target space, these fields are ignored. + +.. _tt-import-bucket-id: + +Importing bucket_id into sharded clusters +----------------------------------------- + +When importing data into a CRUD-enabled sharded cluster, ``tt crud import`` ignores +the ``bucket_id`` field values from the input file. This allows CRUD to automatically +manage data distribution in the cluster by generating new ``bucket_id`` for tuples +during import. + +If you need to preserve the original ``bucket_id`` values, use the ``--keep-bucket-id`` option: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --keep-bucket-id \ + --header \ + --match=header + +.. _tt-import-duplicate-error: + +Handling duplicate primary key errors +------------------------------------- + +The ``--on-exist`` option enables you to control data import when a duplicate primary key error occurs. +In the example below, values already existing in the space are replaced with new ones: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --on-exist replace + +.. _tt-import-parsing-error: + +Handling parsing errors +----------------------- + +To skip rows whose data cannot be parsed correctly, use the ``--on-error`` option as follows: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --on-error skip + +.. _tt-import-tdg2: + +Importing into Tarantool Data Grid 2 +------------------------------------ + +.. note:: + + In the TDG2 data model, a **type** represents a Tarantool space, and an **object** + of a type represents a tuple in the type's underlying space. + +The command below imports objects of the ``customers`` type into a TDG2 cluster. +The objects are described in the ``customers.jsonl`` file. + +.. code-block:: console + + $ tt tdg2 import localhost:3301 customers.jsonl:customers + +If token authentication is enabled in TDG2, pass the application token in the ``--token`` option: + +.. code-block:: console + + $ tt tdg2 import localhost:3301 customers.jsonl:customers \ + --token=2fc136cf-8cae-4655-a431-7c318967263d + +The input file can look like this: + +.. code-block:: json + + {"age":30,"first_name":"Samantha","id":1,"second_name":"Carter"} + {"age":41,"first_name":"Fay","id":2,"second_name":"Rivers"} + {"age":74,"first_name":"Milo","id":4,"second_name":"Walters"} + +.. note:: + + Since JSON describes objects in maps with string keys, there is no way to + import a field value that is a map with a non-string key. + +In case of an error during TDG2 import, ``tt tdg2 import`` rolls back the changes made +*within the current batch* on the *storage where the error has happened* (per-storage rollback) +and reports an error. On other storages, objects from the same batch can be successfully +imported. So, the rollback process of ``tt tdg2 import`` +is the same as the one of ``tt crud import`` with the ``--rollback-on-error`` option. + +Since object batches can be imported partially (per-storage rollback), the absence +of error matching complicates the debugging in case of errors. To minimize this +effect, the default batch size (``--batch-size``) for ``tt tdg2 import`` is 1. +This makes the debugging straightforward: you always know which object caused the error. +On the other hand, this decreases the performance in comparison to import in larger batches. + +If you increase the batch size, ``tt`` informs you about the possible issues and +asks for an explicit confirmation to proceed. +To automatically confirm a batch import operation, add the ``--force`` option: + +.. code-block:: console + + $ tt tdg2 import localhost:3301 customers.jsonl:customers \ + --batch-size=100 \ + --force + + +.. _tt-import-auth: + +Authentication +-------------- + +When connecting to the cluster with enabled authentication, specify access credentials +in the ``--username`` and ``--password`` command options: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header --match=header \ + --username myuser --password p4$$w0rD + +.. _tt-import-ssl: + +Encrypted connection +-------------------- + +To connect to instances that use :ref:`SSL encryption `, +provide the SSL certificate and SSL key files in the ``--sslcertfile`` and ``--sslkeyfile`` options. +If necessary, add other SSL parameters in the ``--ssl*`` options. + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header --match=header \ + --username myuser --password p4$$w0rD \ + --auth pap-sha256 --sslcertfile certs/server.crt \ + --sslkeyfile certs/server.key + +For connections that use SSL but don't require additional parameters, add the ``--use-ssl`` +option: + +.. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --header --match=header \ + --username myuser --password p4$$w0rD \ + --use-ssl + +.. _tt-import-options: + +Options +------- + +.. option:: --auth STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + Authentication type: ``chap-sha1``, ``pap-sha256``, or ``auto``. + +.. option:: --batch-size INT + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The number of tuples to transfer per request. The default is: + + * ``100`` for ``tt crud import``. + * ``1`` for ``tt tdg2 import``. See :ref:`tt-import-tdg2` for details. + +.. option:: --dec-sep STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + The string of symbols that defines decimal separators for numeric data (the default is ``.,``). + + .. NOTE:: + + Symbols specified in this option cannot intersect with ``--th-sep``. + +.. option:: --delimiter STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + A symbol that defines a field value delimiter. + For CSV, the default delimiter is a comma (``,``). + To use a tab character as a delimiter, set this value as ``tab``: + + .. code-block:: console + + $ tt crud import localhost:3301 customers.csv:customers \ + --delimiter tab + + .. NOTE:: + + A delimiter cannot be ``\r``, ``\n``, or the Unicode replacement character (``U+FFFD``). + +.. option:: --error STRING + + The name of a file containing rows that are not imported (the default is ``error``). + + See also: :ref:`Handling parsing errors `. + +.. option:: --force + + **Applicable to:** ``tt tdg2 import`` + + Automatically confirm importing into TDG2 with ``--batch-size`` greater than one. + +.. option:: --format STRING + + A format of input data. + + Supported formats: ``csv``. + +.. option:: --header + + **Applicable to:** ``tt import``, ``tt crud import`` + + Process the first line as a header containing field names. + In this case, field values start from the second line. + + See also: :ref:`Matching of input and space fields `. + +.. option:: --keep-bucket-id + + **Applicable to:** ``tt crud import`` + + Preserve original values of the ``bucket_id`` field. + + See also: :ref:`tt-import-bucket-id`. + +.. option:: --log STRING + + The name of a log file containing information about import errors (the default is ``import``). + If the log file already exists, new data is written to this file. + +.. option:: --match STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + Configure matching between field names in the input file and the target space. + + See also: :ref:`Matching of input and space fields `. + +.. option:: --null STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + A value to be interpreted as ``null`` when importing data. + By default, an empty value is interpreted as ``null``. + For example, a tuple imported from the following row ... + + .. code-block:: text + + 1,477,Andrew,,38 + + ... should look as follows: ``[1, 477, 'Andrew', null, 38]``. + +.. option:: --on-error STRING + + An action performed if a row to be imported cannot be parsed correctly. + Possible values: + + * ``stop``: stop importing data. + * ``skip``: skip rows whose data cannot be parsed correctly. + + Duplicate primary key errors are handled using the ``--on-exist`` option. + + See also: :ref:`Handling parsing errors `. + +.. option:: --on-exist STRING + + An action performed if a duplicate primary key error occurs. + Possible values: + + * ``stop``: stop importing data. + * ``skip``: skip existing values when importing. + * ``replace``: replace existing values when importing. + + Other errors are handled using the ``--on-error`` option. + + See also: :ref:`Handling duplicate primary key errors `. + +.. option:: --password STRING + + A password used to connect to the instance. + +.. option:: --progress STRING + + The name of a progress file that stores the following information: + + * The positions of lines that were not imported at the last launch. + * The last position that was processed at the last launch. + + If a file with the specified name exists, it is taken into account when importing data. + ``tt import`` tries to insert lines that were not imported and then continues importing from the last position. + + At each launch, the content of a progress file with the specified name is overwritten. + If the file with the specified name does not exist, a progress file is created with the results of this run. + + .. NOTE:: + + If the option is not set, then this mechanism is not used. + +.. option:: --quote STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + A symbol that defines a quote. + For CSV, double quotes are used by default (``"``). + The double symbol of this option acts as the escaping symbol within input data. + +.. option:: --rollback-on-error + + **Applicable to:** ``tt crud import`` + + Specify whether any operation failed on a storage leads to rolling back batch + import on this storage. + + .. note:: + + ``tt tdg2 import`` always works as if ``--rollback-on-error`` is ``true``. + +.. option:: --sslcafile STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The path to a trusted certificate authorities (CA) file for encrypted connections. + + See also :ref:`tt-import-ssl`. + +.. option:: --sslcertfile STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The path to an SSL certificate file for encrypted connections. + + See also :ref:`tt-import-ssl`. + +.. option:: --sslciphersfile STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The list of SSL cipher suites used for encrypted connections, separated by colons (``:``). + + See also :ref:`tt-import-ssl`. + +.. option:: --sslkeyfile STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The path to a private SSL key file for encrypted connections. + + See also :ref:`tt-import-ssl`. + +.. option:: --sslpassword STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + The password for the SSL key file for encrypted connections. + + See also :ref:`tt-import-ssl`. + +.. option:: --sslpasswordfile STRING + + **Applicable to:** ``tt crud import``, ``tt tdg2 import`` + + A file with a list of passwords to the SSL key file for encrypted connections. + + See also :ref:`tt-import-auth`. + +.. option:: -success STRING + + The name of a file with rows that were imported (the default is ``success``). + Overwrites the file if it already exists. + +.. option:: --th-sep STRING + + **Applicable to:** ``tt import``, ``tt crud import`` + + The string of symbols that define thousand separators for numeric data. + The default value includes a space and a backtick `````. + This means that ``1 000 000`` and ``1`000`000`` are both imported as ``1000000``. + + .. NOTE:: + + Symbols specified in this option cannot intersect with ``--dec-sep``. + +.. option:: --token STRING + + **Applicable to:** ``tt tdg2 import`` + + An application token for connecting to TDG2. + +.. option:: --use-ssl STRING + + Use SSL without providing any additional SSL parameters. + + See also :ref:`tt-import-ssl`. + +.. option:: --username STRING + + A username for connecting to the instance. + diff --git a/doc/tooling/tt_cli/index.rst b/doc/tooling/tt_cli/index.rst new file mode 100644 index 0000000000..47c93a682f --- /dev/null +++ b/doc/tooling/tt_cli/index.rst @@ -0,0 +1,67 @@ +.. _tt-cli: + +tt CLI utility +============== + +``tt`` is a utility that provides a unified command-line interface for managing +Tarantool-based applications. It covers a wide range of tasks -- from installing +a specific Tarantool version to managing remote instances and developing applications. + +``tt`` is developed in its own `GitHub repository `_. +Here you can find its source code, changelog, and releases information. +For a complete list of releases, see the `Releases `_ section on GitHub. + +There is also the Enterprise version of ``tt`` available in a +Tarantool Enterprise Edition's :ref:`release package `. +The Enterprise version provides additional features, for example, :ref:`importing ` and :ref:`exporting ` data. + +This section provides instructions on ``tt`` installation and configuration, +concept explanation, and the ``tt`` command reference. + +.. toctree:: + :maxdepth: 1 + :numbered: 0 + + installation + configuration + global_options + developing_apps + commands + external_modules + tt_interactive_console + tarantoolctl_tt_migrating + +.. _tt-cli-environments: + +tt environments +--------------- + +The key aspect of the ``tt`` usage is an *environment*. A ``tt`` environment +is a directory that includes a ``tt`` configuration, Tarantool installations, +application files, and other resources. If you're familiar with `Python virtual +environments `_, +you can think of ``tt`` environments as their analog. + +``tt`` environments enable independent management of multiple Tarantool applications, +each running on its own Tarantool version and configuration, on a single host in +an isolated manner. + +To create a ``tt`` environment in a directory, run :ref:`tt init ` in it. + +Multi-instance applications +--------------------------- + +``tt`` supports Tarantool applications that run on multiple instances. For example, +you can write an application that includes different source files for storage and router +instances. With ``tt``, you can start and stop them in a single call, or manage +each instance independently. + +Learn more about working with multi-instance applications in :ref:`Multi-instance applications `. + +Replacement for tarantoolctl and Cartridge CLI +--------------------------------------------- + +A multi-purpose tool for working with Tarantool from the command line, ``tt`` has +come to replace the deprecated utilities ``tarantoolctl`` +and `Cartridge CLI `_ command-line utilities. +The instructions on migration to ``tt`` are provided in :ref:`tarantoolctl-migration-to-tt`. diff --git a/doc/reference/tooling/tt_cli/init.rst b/doc/tooling/tt_cli/init.rst similarity index 96% rename from doc/reference/tooling/tt_cli/init.rst rename to doc/tooling/tt_cli/init.rst index a4a9cee48c..ec022654dc 100644 --- a/doc/reference/tooling/tt_cli/init.rst +++ b/doc/tooling/tt_cli/init.rst @@ -15,6 +15,8 @@ Creating a tt environment Details ------- +.. include:: _includes/cartridge_deprecation_note.rst + ``tt init`` checks the existence of configuration files for Cartridge (``cartridge.yml``) or the ``tarantoolctl`` utility (``.tarantoolctl``) in the current directory. If such files are found, ``tt`` generates an environment that uses the same diff --git a/doc/tooling/tt_cli/install.rst b/doc/tooling/tt_cli/install.rst new file mode 100644 index 0000000000..6acdbfb1bb --- /dev/null +++ b/doc/tooling/tt_cli/install.rst @@ -0,0 +1,182 @@ +.. _tt-install: + +Installing Tarantool software +============================= + +.. code-block:: console + + $ tt install PROGRAM_NAME [VERSION|COMMIT_HASH|PR_ID] [OPTION ...] + +``tt install`` installs the latest or an explicitly specified version of Tarantool +or ``tt``. The possible values of ``PROGRAM_NAME`` are: + +* ``tarantool``: Install Tarantool Community Edition. +* ``tarantool-dev``: Install Tarantool from a local build directory. +* ``tarantool-ee``: Install Tarantool Enterprise Edition. +* ``tt``: Install the ``tt`` command-line utility. + +.. note:: + + For ``tarantool-ee``, account credentials are required. Specify them in a file + (see the :ref:`ee section ` of the configuration file) or + provide them interactively. + +Additionally, ``tt install`` can build open source programs ``tarantool`` and ``tt`` +from a specific commit or a pull request on their GitHub repositories. + +To uninstall a Tarantool or ``tt`` version, use :ref:`tt uninstall `. + +Options +------- + +.. option:: --dynamic + + **Applicable to:** ``tarantool``, ``tarantool-ee`` + + Use dynamic linking for building Tarantool. + +.. option:: -f, --force + + Skip dependency check before installation. + +.. option:: --local-repo + + Install a program from the local repository, which is specified in the + :ref:`repo section ` of the ``tt`` configuration file. + +.. option:: --no-clean + + Don't delete temporary files. + +.. option:: --reinstall + + Reinstall a previously installed program. + +.. option:: --use-docker + + **Applicable to:** ``tarantool``, ``tarantool-ee`` + + Build Tarantool in an Ubuntu 18.04 Docker container. + +Details +------- + +When called without an explicitly specified version, ``tt install`` installs the +latest available version. If the version is specified in the incomplete format ``.``, +the command installs the latest available patch version in the series. +To check versions available for installation, use :ref:`tt search `. + +By default, available versions of Tarantool Community Edition and ``tt`` are taken from their git repositories. +Their installation includes building from sources, which requires some tools and +dependencies, such as a C compiler. Make sure they are available in the system. + +Tarantool Enterprise Edition is installed from prebuilt packages. + +.. _tt-install-authentication: + +Authentication +~~~~~~~~~~~~~~ + +To install Tarantool EE using ``tt install``, you need to provide access credentials +for the Tarantool customer zone. Use one of the following ways to pass the username and the password: + +* A text file specified in the ``ee.credential_path`` parameter of the + :ref:`tt enviromnment configuration `: + + .. code-block:: yaml + + # tt.yaml + # ... + ee: + credential_path: cred.txt + + `cred.txt` should contain a username and a password on separate lines: + + .. code-block:: text + + myuser@tarantool.io + p4$$w0rD + +* Environment variables ``TT_CLI_EE_USERNAME`` and ``TT_CLI_EE_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_EE_USERNAME=myuser@tarantool.io + $ export TT_CLI_EE_PASSWORD=p4$$w0rD + $ tt install tarantool-ee + +Development versions +~~~~~~~~~~~~~~~~~~~~ + +``tt install`` can be used to build custom Tarantool and ``tt`` versions for +development purposes from commits and pull requests on their GitHub repositories. + +To build Tarantool or ``tt`` from a specific commit on their GitHub repository, +pass the commit hash (7 or more characters) after the program name. If you want to use +a PR as a source, provide a ``pr/`` argument: + + +.. code-block:: console + + $ tt install tarantool 03c184d + $ tt install tt pr/50 + +If you :ref:`build Tarantool from sources `, you can install +local builds to the current ``tt`` environment by running ``tt install`` with +the ``tarantool-dev`` program name and the path to the build: + +.. code-block:: console + + $ tt install tarantool-dev ~/src/tarantool/build + +Local repositories +~~~~~~~~~~~~~~~~~~ + +You can also set up a local repository with installation files you need. +To use it, specify its location in the :ref:`repo section ` +of the ``tt`` configuration file and run ``tt install`` with the ``--local-repo`` flag. + +Example +-------- + +* Install the latest available version of Tarantool CE: + + .. code-block:: console + + $ tt install tarantool + +* Install the latest available patch version of Tarantool CE 3.2 release series: + + .. code-block:: console + + $ tt install tarantool 3.2 + +* Install Tarantool 2.11.1 from the local repository: + + .. code-block:: console + + $ tt install tarantool 2.11.1 --local-repo + +* Reinstall Tarantool 2.10.8: + + .. code-block:: console + + $ tt install tarantool 2.10.8 --reinstall + +* Install Tarantool from a PR #1234 on the `tarantool/tarantool `__ GitHub repository: + + .. code-block:: console + + $ tt install tarantool pr/1234 + +* Install ``tt`` from a commit with a hash ``40e696e`` on the `tarantool/tt `__ GitHub repository: + + .. code-block:: console + + $ tt install tt 40e696e + +* Install Tarantool :ref:`built from sources `: + + .. code-block:: console + + $ tt install tarantool-dev ~/src/tarantool/build diff --git a/doc/tooling/tt_cli/installation.rst b/doc/tooling/tt_cli/installation.rst new file mode 100644 index 0000000000..63b8b7432f --- /dev/null +++ b/doc/tooling/tt_cli/installation.rst @@ -0,0 +1,91 @@ +.. _tt-installation: + +Installation +============ + +To install the ``tt`` command-line utility, use a package manager -- Yum or +APT on Linux, or Homebrew on macOS. If you need a specific build, you can build +``tt`` from sources. + +.. NOTE:: + + A Tarantool Enterprise Edition's :ref:`release package ` includes the `tt` utility extended with additional features like :ref:`importing ` and :ref:`exporting ` data. + + +Using Linux package managers +---------------------------- + +On Linux systems, you can install ``tt`` with ``yum`` or ``apt`` package managers +from the ``tarantool/modules`` repository. Learn how to `add this repository +`_. + +The installation command looks like this: + +* On Ubuntu: + + .. code-block:: console + + $ sudo apt-get install tt + +* On CentOS: + + .. code-block:: console + + $ sudo yum install tt + +Using Homebrew on macOS +----------------------- + +On macOS, use Homebrew to install ``tt``: + +.. code-block:: console + + $ brew install tt + +Building from sources +--------------------- + +To build ``tt`` from sources: + +1. Install third-party software required for building ``tt``: + + * `git `__, + the version control system. + * `Go language `__, version 1.18 or later. + * `mage `__ build tool. + +2. Clone the `tarantool/tt `_ repository: + + .. code-block:: bash + + git clone https://github.com/tarantool/tt --recursive + +3. Go to the ``tt`` directory: + + .. code-block:: bash + + cd tt + +4. (Optional) Checkout a release tag to build a specific version: + + .. code-block:: bash + + git checkout tags/v1.0.0 + +5. Build ``tt`` using mage: + + .. code-block:: bash + + mage build + +``tt`` will appear in the current directory. + +Enabling shell completion +------------------------- + +To enable the completion for ``tt`` commands, run the following command specifying +the shell (``bash`` or ``zsh``): + +.. code-block:: bash + + . <(tt completion bash) \ No newline at end of file diff --git a/doc/tooling/tt_cli/instance_config.rst b/doc/tooling/tt_cli/instance_config.rst new file mode 100644 index 0000000000..f3b7a269cd --- /dev/null +++ b/doc/tooling/tt_cli/instance_config.rst @@ -0,0 +1,227 @@ +.. _admin-instance_config: +.. _admin-instance-environment-overview: +.. _admin-tt_config_file: + +Application environment +======================= + +This section provides a high-level overview on how to prepare a Tarantool application for deployment +and how the application's environment and layout might look. +This information is helpful for understanding how to administer Tarantool instances using :ref:`tt CLI ` in both development and production environments. + +The main steps of creating and preparing the application for deployment are: + +1. :ref:`admin-instance_config-init-environment`. + +2. :ref:`admin-instance_config-develop-app`. + +3. :ref:`admin-instance_config-package-app`. + +In this section, a `sharded_cluster_crud `_ application is used as an example. +This cluster includes 5 instances: one router and 4 storages, which constitute two replica sets. + +.. image:: /admin/admin_instances_dev.png + :align: left + :width: 700 + :alt: Cluster topology + + + +.. _admin-instance_config-init-environment: +.. _admin-start_stop_instance-running_locally: + +Initializing a local environment +-------------------------------- + +Before creating an application, you need to set up a local environment for ``tt``: + +1. Create a home directory for the environment. + +2. Run ``tt init`` in this directory: + + .. code-block:: console + + ~/myapp$ tt init + • Environment config is written to 'tt.yaml' + +This command creates a default ``tt`` configuration file ``tt.yaml`` for a local +environment and the directories for applications, control sockets, logs, and other +artifacts: + +.. code-block:: console + + ~/myapp$ ls + bin distfiles include instances.enabled modules templates tt.yaml + +Find detailed information about the ``tt`` configuration parameters and launch modes +on the :ref:`tt configuration page `. + + + +.. _admin-instance_config-develop-app: +.. _admin-start_stop_instance-multi-instance: +.. _admin-start_stop_instance-multi-instance-layout: + +Creating and developing an application +-------------------------------------- + +You can create an application in two ways: + +- Manually by preparing its layout in a directory inside ``instances_enabled``. + The directory name is used as the application identifier. + +- From a template by using the :ref:`tt create ` command. + +In this example, the application's layout is prepared manually and looks as follows. + +.. code-block:: console + + ~/myapp$ tree + . + ├── bin + ├── distfiles + ├── include + ├── instances.enabled + │ └── sharded_cluster_crud + │ ├── config.yaml + │ ├── instances.yaml + │ ├── router.lua + │ ├── sharded_cluster_crud-scm-1.rockspec + │ └── storage.lua + ├── modules + ├── templates + └── tt.yaml + + +The ``sharded_cluster_crud`` directory contains the following files: + +- ``config.yaml``: contains the :ref:`configuration ` of the cluster. This file might include the entire cluster topology or provide connection settings to a centralized configuration storage. +- ``instances.yml``: specifies instances to run in the current environment. For example, on the developer’s machine, this file might include all the instances defined in the cluster configuration. In the production environment, this file includes :ref:`instances to run on the specific machine `. +- ``router.lua``: includes code specific for a :ref:`router `. +- ``sharded_cluster_crud-scm-1.rockspec``: specifies the required external dependencies (for example, ``vshard`` and ``crud``). +- ``storage.lua``: includes code specific for :ref:`storages `. + +You can find the full example here: +`sharded_cluster_crud `_. + + + +.. _admin-instance_config-package-app: +.. _admin-instance-app-layout: +.. _admin-instance_file: + +Packaging the application +------------------------- + +To package the ready application, use the :ref:`tt pack ` command. +This command can create an installable DEB/RPM package or generate ``.tgz`` archive. + +The structure below reflects the content of the packed ``.tgz`` archive for the `sharded_cluster_crud `_ application: + +.. code-block:: console + + ~/myapp$ tree -a + . + ├── bin + │ ├── tarantool + │ └── tt + ├── instances.enabled + │ └── sharded_cluster_crud -> ../sharded_cluster_crud + ├── sharded_cluster_crud + │ ├── .rocks + │ │ └── share + │ │ └── ... + │ ├── config.yaml + │ ├── instances.yaml + │ ├── router.lua + │ └── storage.lua + └── tt.yaml + + +The application's layout looks similar to the one defined when :ref:`developing the application ` with some differences: + +- ``bin``: contains the ``tarantool`` and ``tt`` binaries packed with the application bundle. + +- ``instances.enabled``: contains a symlink to the packed ``sharded_cluster`` application. + +- ``sharded_cluster_crud``: a packed application. In addition to files created during the application development, includes the ``.rocks`` directory containing application dependencies (for example, ``vshard`` and ``crud``). + +- ``tt.yaml``: a ``tt`` configuration file. + +.. note:: + + In DEB/PRM packages generated by :ref:`tt pack `, there are also ``.service`` + unit files for each packaged application. + +.. _admin-instance_config-deploy-app: + +Deploying the application +------------------------- + +.. _admin-instances_to_run: + +Instances to run +~~~~~~~~~~~~~~~~ + +When deploying a distributed cluster application from a `.tar.gz` archive, you can +define instances to run on each machine by changing the content of the ``instances.yaml`` file. + +- On the developer's machine, this file might include all the instances defined in the cluster configuration. + + .. image:: /admin/admin_instances_dev.png + :align: left + :width: 700 + :alt: Cluster topology + + ``instances.yaml``: + + .. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/instances.yaml + :language: yaml + :dedent: + +- In the production environment, this file includes instances to run on the specific machine. + + .. image:: /admin/admin_instances_prod.png + :align: left + :width: 700 + :alt: Cluster topology + + ``instances.yaml`` (Server-001): + + .. code-block:: yaml + + router-a-001: + + ``instances.yaml`` (Server-002): + + .. code-block:: yaml + + storage-a-001: + storage-b-001: + + ``instances.yaml`` (Server-003): + + .. code-block:: yaml + + storage-a-002: + storage-b-002: + +The :ref:`Starting and stopping instances ` section describes how to start and stop Tarantool instances. + +.. _admin-deploy-rpm-deb: + +DEB and RPM packages +~~~~~~~~~~~~~~~~~~~~ + +Tarantool applications installed from DEB and RPM packages built with :ref:`tt pack ` +can run as ``systemd`` services. They run on behalf of the ``tarantool`` system user. +It is created automatically during the package installation. + +By default, the application artifacts are placed in the following directories: + +- ``/var/lib/tarantool/sys_env`` -- application data +- ``/var/log/tarantool/sys_env`` -- logs +- ``/var/run/tarantool/sys_env`` -- runtime artifacts + +If you want to change these directories, make sure that the ``tarantool`` user +has enough permissions on the directories you use. \ No newline at end of file diff --git a/doc/tooling/tt_cli/instances.rst b/doc/tooling/tt_cli/instances.rst new file mode 100644 index 0000000000..8c19fa5579 --- /dev/null +++ b/doc/tooling/tt_cli/instances.rst @@ -0,0 +1,27 @@ +.. _tt-instances: + +Listing enabled applications +============================ + +.. code-block:: console + + $ tt instances + +``tt instances`` shows the list of enabled applications and their instances +in the current environment. + +.. note:: + + *Enabled* applications are applications that are stored inside the ``instances_enabled`` + directory specified in the :ref:`tt configuration file `. + They can be either running or not. To check if an application is running, + use :doc:`tt status `. + +Example +-------- + +* Show the list of enabled applications and their instances: + + .. code-block:: console + + $ tt instances \ No newline at end of file diff --git a/doc/tooling/tt_cli/kill.rst b/doc/tooling/tt_cli/kill.rst new file mode 100644 index 0000000000..4bba3b9e63 --- /dev/null +++ b/doc/tooling/tt_cli/kill.rst @@ -0,0 +1,39 @@ +.. _tt-kill: + +Terminating Tarantool instances +=============================== + +.. code-block:: console + + $ tt kill APPLICATION[:APP_INSTANCE] + +``tt kill`` terminates instances with ``SIGQUIT`` and ``SIGKILL`` signals. + +To terminate all instances of the ``app`` application: + +.. code-block:: console + + $ tt kill app + +To terminate the ``storage-001-r`` instance of the ``app`` application without confirmation: + +.. code-block:: console + + $ tt kill app:storage-001-r --force + +To terminate the ``storage-001-r`` instance of the ``app`` application and generate its core dump: + +.. code-block:: console + + $ tt kill app:storage-001-r --dump + +Options +------- + +.. option:: -d, --dump + + Generate core dumps of terminated processes. + +.. option:: -f, --force + + Kill instances without confirmation. diff --git a/doc/tooling/tt_cli/log.rst b/doc/tooling/tt_cli/log.rst new file mode 100644 index 0000000000..fa5d3e2093 --- /dev/null +++ b/doc/tooling/tt_cli/log.rst @@ -0,0 +1,39 @@ +.. _tt-log: + +Printing Tarantool logs +======================= + +.. code-block:: console + + $ tt log [APPLICATION[:APP_INSTANCE]] + +``tt log`` prints the last lines of instance logs. + +To print 10 last log lines of all the ``app`` application instances: + +.. code-block:: console + + $ tt log app + +To print 50 last log lines of the ``router`` instance of the ``app`` application: + +.. code-block:: console + + $ tt log -n 50 app:router + +To keep printing logs of the ``app`` application instances as they grow: + +.. code-block:: console + + $ tt log -f app + +Options +------- + +.. option:: -f, --follow + + Keep printing new lines added to the log file. + +.. option:: -n, --lines + + The number of last lines to output. Default: ``10``. diff --git a/doc/tooling/tt_cli/logrotate.rst b/doc/tooling/tt_cli/logrotate.rst new file mode 100644 index 0000000000..faa6416de8 --- /dev/null +++ b/doc/tooling/tt_cli/logrotate.rst @@ -0,0 +1,25 @@ +.. _tt-logrotate: + +Rotating instance logs +====================== + +.. code-block:: console + + $ tt logrotate APPLICATION[:APP_INSTANCE] + +``tt logrotate`` rotates logs of a Tarantool application or specific instances, +and the ``tt`` log. For example, you need to call this function to continue logging +after a log rotation program renames or moves instances' logs. +Learn more about :ref:`rotating logs `. + +Calling ``tt logrotate`` on an application has the same effect as executing the +built-in :ref:`log.rotate() ` function on all its instances. + +Examples +-------- + +Rotate logs of the ``app`` application's instances: + +.. code-block:: console + + $ tt logrotate app \ No newline at end of file diff --git a/doc/tooling/tt_cli/migrations.rst b/doc/tooling/tt_cli/migrations.rst new file mode 100644 index 0000000000..f7a590b3cb --- /dev/null +++ b/doc/tooling/tt_cli/migrations.rst @@ -0,0 +1,486 @@ +.. _tt-migrations: + +Managing centralized migrations +=============================== + +.. admonition:: Enterprise Edition + :class: fact + + This command is supported by the `Enterprise Edition `_ only. + +.. code-block:: console + + $ tt migrations COMMAND [COMMAND_OPTION ...] + +``tt migrations`` manages :ref:`centralized migrations ` +in a Tarantool EE cluster. See :ref:`centralized_migrations_tt` for a detailed guide +on using the centralized migrations mechanism. + +.. important:: + + Only Tarantool EE clusters with etcd centralized configuration storage are supported. + +``COMMAND`` is one of the following: + + +* :ref:`publish ` +* :ref:`apply ` +* :ref:`status ` +* :ref:`stop ` +* :ref:`remove ` + + +.. _tt-migrations-publish: + +publish +------- + +.. code-block:: console + + $ tt migrations publish ETCD_URI [MIGRATIONS_DIR | MIGRATION_FILE] [OPTION ...] + +``tt migrations publish`` sends the migration files to the cluster's centralized +configuration storage for future execution. + +By default, the command sends all files stored in ``migrations/`` inside the current +directory. + +.. code-block:: console + + $ tt migrations publish "https://user:pass@localhost:2379/myapp" + +To select another directory with migration files, provide a path to it as the command +argument: + +.. code-block:: console + + $ tt migrations publish "https://user:pass@localhost:2379/myapp" my_migrations + +To publish a single migration from a file, use its name or path as the command argument: + +.. code-block:: console + + $ 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 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 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 + the same name, add the ``--overwirte`` option. +- Migration names order. By default, ``tt migrations`` only adds new migrations + to the end of the migrations list ordered lexicographically. For example, if + migrations ``001.lua`` and ``003.lua`` are already published, an attempt to publish + ``002.lua`` will fail. To force publishing migrations disregarding the order, + add the ``--ignore-order-violation`` option. + +.. warning:: + + Using the options that ignore checks when publishing migration may cause + migration inconsistency in the cluster. + + +.. _tt-migrations-apply: + +apply +----- + +.. code-block:: console + + $ tt migrations apply ETCD_URI [OPTION ...] + +``tt migrations apply`` applies :ref:`published ` 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 + +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 + +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 + +The command also provides options for migration troubleshooting: ``--ignore-order-violation``, +``--force-reapply``, and ``--ignore-preceding-status``. Learn to use them in +:ref:`centralized_migrations_tt_troubleshoot`. + +.. warning:: + + The use of migration troubleshooting options may lead to migration inconsistency + in the cluster. Use them only for local development and testing purposes. + + +.. _tt-migrations-status: + +status +------ + +.. code-block:: console + + $ tt migrations status ETCD_URI [OPTION ...] + +``tt migrations status`` prints the list of migrations published to the centralized +storage and the result of their execution on the cluster instances. + +Possible migration statuses are: + +- ``APPLY_STARTED`` -- the migration execution has started but not completed yet + or has been interrupted with :ref:`tt migrations stop `` +- ``APPLIED`` -- the migration is successfully applied on the instance +- ``FAILED`` -- there were errors during the migration execution on the instance + +To get the list of migrations stored in the given etcd storage and information about +their execution on the cluster, run: + +.. code-block:: console + + $ tt migrations status "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass + +If the cluster uses SSL encryption, add SSL options. Learn more in :ref:`Authentication `. + +Use the ``--migration`` and ``--replicaset`` options to get information about specific +migrations or replica sets: + +.. code-block:: console + + $ tt migrations status "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass \ + --replicaset=storage-001 --migration=000001_create_writers_space.lua + +The ``--display-mode`` option allows to tailor the command output: + +- with ``--display-mode config-storage``, the command prints only the list of migrations + published to the centralized storage. +- with ``--display-mode cluster``, the command prints only the migration statuses + on the cluster instances. + +To find out the results of a migration execution on a specific replica set in the cluster, run: + +.. code-block:: console + + $ tt migrations status "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass \ + --replicaset=storage-001 --display-mode=cluster + + +.. _tt-migrations-stop: + +stop +---- + +.. code-block:: console + + $ tt migrations stop ETCD_URI [OPTION ...] + +``tt migrations stop`` stops the execution of migrations in the cluster. + +.. warning:: + + Calling ``tt migration stop`` may cause migration inconsistency in the cluster. + +To stop the execution of a migration currently running in the cluster: + +.. code-block:: console + + $ tt migrations stop "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass + +``tt migrations stop`` interrupts a single migration. If you call it to interrupt +the process that applies multiple migrations, the ones completed before the call +receive the ``APPLIED`` status. The migration is interrupted by the call remains in +``APPLY_STARTED``. + +.. _tt-migrations-remove: + +remove +------ + +.. code-block:: console + + $ tt migrations remove ETCD_URI [OPTION ...] + +``tt migrations remove`` removes published migrations from the centralized storage. +With additional options, it can also remove the information about the migration execution +on the cluster instances. + +To remove all migrations from a specified centralized storage: + +.. code-block:: console + + $ tt migrations remove "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass + +To remove a specific migration, pass its name in the ``--migration`` option: + +.. code-block:: console + + $ tt migrations remove "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass \ + --migration=000001_create_writers_space.lua + +Before removing migrations, the command checks their :ref:`status ` +on the cluster. To ignore the status and remove migrations anyway, add the +``--force-remove-on=config-storage`` option: + +.. code-block:: console + + $ tt migrations remove "https://user:pass@localhost:2379/myapp" \ + --force-remove-on=config-storage + +.. note:: + + In this case, cluster credentials are not required. + +To remove migration execution information from the cluster (clear the migration status), +use the ``--force-remove-on=cluster`` option: + +.. code-block:: console + + $ tt migrations remove "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass \ + --force-remove-on=cluster + +To clear all migration information from the centralized storage and cluster, +use the ``--force-remove-on=all`` option: + +.. code-block:: console + + $ tt migrations remove "https://user:pass@localhost:2379/myapp" \ + --tarantool-username=admin --tarantool-password=pass \ + --force-remove-on=all + +.. _tt-migrations-auth: + +Authentication +-------------- + +Since ``tt migrations`` operates migrations via a centralizes etcd storage, it +needs credentials to access this storage. There are two ways to pass etcd credentials: + +- command-line options ``--config-storage-username`` and ``--config-storage-password`` +- the etcd URI, for example, ``https://user:pass@localhost:2379/myapp`` + +Credentials specified in the URI have a higher priority. + +For commands that connect to the cluster (that is, all except ``publish``), Tarantool +credentials are also required. The are passed in the ``--tarantool-username`` and +``--tarantool-password`` options. + +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`. + +.. _tt-migrations-options: + +Options +------- + +.. option:: --acquire-lock-timeout INT + + **Applicable to:** ``apply`` + + Migrations fiber lock acquire timeout in seconds. Default: 60. + Fiber lock is used to prevent concurrent migrations run + +.. option:: --config-storage-password STRING + + A password for connecting to the centralized migrations storage (etcd). + + See also: :ref:`tt-migrations-auth`. + +.. option:: --config-storage-username STRING + + A username for connecting to the centralized migrations storage (etcd). + + See also: :ref:`tt-migrations-auth`. + +.. option:: --display-mode STRING + + **Applicable to:** ``status`` + + Display only specific information. Possible values: + + - ``config-storage`` -- information about migrations published to the centralized storage. + - ``cluster`` -- information about migration applied on the cluster. + + See also: :ref:`tt-migrations-status`. + +.. option:: --execution-timeout INT + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + A timeout for completing the operation on a single Tarantool instance, in seconds. + Default values: + + - ``3`` for ``remove``, ``status``, and ``stop`` + - ``3600`` for ``apply`` + +.. option:: --force-reapply + + **Applicable to:** ``apply`` + + Apply migrations disregarding their previous status. + + .. warning:: + + Using this option may lead to migrations inconsistency in the cluster. + +.. option:: --force-remove-on STRING + + **Applicable to:** ``remove`` + + Remove migrations disregarding their status. Possible values: + + - ``config-storage``: remove migrations on etcd centralized migrations storage disregarding the cluster apply status. + - ``cluster``: remove migrations status info only on a Tarantool cluster. + - ``all`` to execute both ``config-storage`` and ``cluster`` force removals. + + .. warning:: + + Using this option may lead to migrations inconsistency in the cluster. + +.. option:: --ignore-order-violation + + **Applicable to:** ``apply``, ``publish`` + + Skip migration scenarios order check before publish. + + .. warning:: + + Using this option may lead to migrations inconsistency in the cluster. + +.. option:: --ignore-preceding-status + + **Applicable to:** ``apply`` + + Skip preceding migrations status check on apply. + + .. warning:: + + Using this option may lead to migrations inconsistency in the cluster. + +.. option:: --key STRING + + **Applicable to:** ``publish`` + + Put scenario to ``//migrations/scenario/`` etcd key instead. + Only for single file publish. + +.. option:: --migration STRING + + **Applicable to:** ``apply``, ``remove``, ``status`` + + A migration to apply, remove, or check status. + +.. option:: --overwrite + + **Applicable to:** ``publish`` + + overwrite existing migration storage keys. + + .. warning:: + + Using this option may lead to migrations inconsistency in the cluster. + +.. option:: --replicaset STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + Execute the operation only on the specified replica set. + +.. option:: --skip-syntax-check + + **Applicable to:** ``publish`` + + Skip syntax check before publish. + + .. warning:: + + Using this option may cause further ``tt migrations`` calls to fail. + +.. option:: --tarantool-auth STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + Authentication type used to connect to the cluster instances. + +.. option:: --tarantool-connect-timeout INT + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + Tarantool cluster instances connection timeout, in seconds. Default: 3. + +.. option:: --tarantool-password STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + A password used to connect to the cluster instances. + +.. option:: --tarantool-sslcafile STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + SSL CA file used to connect to the cluster instances. + +.. option:: --tarantool-sslcertfile STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + SSL cert file used to connect to the cluster instances. + +.. option:: --tarantool-sslciphers STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + Colon-separated list of SSL ciphers used to connect to the cluster instances. + +.. option:: --tarantool-sslkeyfile STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + SSL key file used to connect to the cluster instances. + +.. option:: --tarantool-sslpassword STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + SSL key file password used to connect to the cluster instances. + +.. option:: --tarantool-sslpasswordfile STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + 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`` + + Whether SSL is used to connect to the cluster instances. + +.. option:: --tarantool-username STRING + + **Applicable to:** ``apply``, ``remove``, ``status``, ``stop`` + + A username for connecting to the Tarantool cluster instances. diff --git a/doc/tooling/tt_cli/pack.rst b/doc/tooling/tt_cli/pack.rst new file mode 100644 index 0000000000..828627ec94 --- /dev/null +++ b/doc/tooling/tt_cli/pack.rst @@ -0,0 +1,272 @@ +.. _tt-pack: + +Packaging the application +========================= + +.. code-block:: console + + $ tt pack TYPE [OPTION ...] .. + +``tt pack`` packages an application into a distributable bundle of the specified ``TYPE``: + +- ``tgz``: create a ``.tgz`` archive. +- ``deb``: create a DEB package. +- ``rpm``: create an RPM package. + +.. _tt-pack-example: + +Example: a DEB package +---------------------- + +The command below creates a DEB package with all applications from the current ``tt`` +environment: + +.. code-block:: console + + $ tt pack deb + +This command generates a ``.deb`` file whose name depends on the environment directory name and the operating system architecture, for example, ``test-env_0.1.0.0-1_x86_64.deb``. +The package contains the following files: + +- The content of the application directories: source files, resources, dependencies. +- ``tt`` environment files: ``tarantool`` and ``tt`` executables, ``tt.yaml`` configuration file, + external modules, headers. +- ``.service`` unit files that allow running applications as ``systemd`` services + (a separate file for each application). + +You can also pass various :ref:`options ` to the ``tt pack`` command to adjust generation properties, for example, customize a bundle name, choose which artifacts should be included, specify the required application dependencies. + +.. _tt-pack-systemd: + +systemd unit parameters +----------------------- + +You can customize your application's systemd unit file generated by ``tt pack``. +To add parameters to the unit file, define them in a YAML file named ``systemd-unit-params.yml`` +in the :ref:`application directory `. + +.. code-block:: console + + $ tt pack rpm # unit file with parameters from systemd-unit-params.yml if it exists + +You can also pass unit parameters from an arbitrary file by adding the ``--unit-params-file`` +option to the ``tt pack`` call: + +.. code-block:: console + + $ tt pack rpm --unit-params-file my-params.yml # unit file with parameters from my-params.yml + +.. important:: + + The ``systemd-unit-params.yml`` file has a higher priority than the ``--unit-params-file`` option. + If this file exists, it overrides parameters from the file passed in the option. + +``tt pack`` supports the following systemd unit parameters: + +- ``FdLimit`` -- the number of open file descriptors (``LimitNOFile`` in the unit file). +- ``instance-env`` -- a list of environment variables in the ``: `` format. + Each list item adds an ``Environment==`` line to the unit file. + +An example of the ``systemd-unit-params.yml`` file: + +.. code-block:: yaml + + FdLimit: 200 + instance-env: + INSTANCE: "inst:%i" + TARANTOOL_WORKDIR: "/tmp" + +.. _tt-pack-integrity-check: + +Generating files for integrity checks +------------------------------------- + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +``tt pack`` can generate checksums and signatures to use for integrity checks +when running the application. These files are: + +- ``hashes.json`` and ``hashes.json.sig`` in each application directory. + ``hashes.json`` contains SHA256 checksums of executable files that the application uses + and its configuration file. ``hashes.json.sig`` contains a digital signature + for ``hashes.json``. + +- ``env_hashes.json`` and ``env_hashes.json.sig`` in the environment root are + similar files for the ``tt`` environment. They contain checksums for + Tarantool and ``tt`` executables, and for the ``tt.yaml`` configuration file. + +To generate checksums and signatures for integrity check, use the ``--with-integrity-check`` +option. Its argument must be an RSA private key. + +.. note:: + + You can generate a key pair using `OpenSSL 3 `__ as follows: + + .. code-block:: console + + $ openssl genrsa -traditional -out private.pem 2048 + $ openssl rsa -in private.pem -pubout > public.pem + +To create a ``tar.gz`` archive with integrity check artifacts: + +.. code-block:: console + + $ tt pack tgz --with-integrity-check private.pem + +Learn how to perform integrity checks at the application startup and in runtime +in the :ref:`tt start ` reference. + + +.. _tt-pack-options: + +Options +------- + +.. option:: --all + + Include all artifacts in a bundle. + In this case, a bundle might include snapshots, WAL files, and logs. + +.. option:: --app-list APPLICATIONS + + Specify the applications included in a bundle. + + **Example** + + .. code-block:: console + + $ tt pack tgz --app-list app1,app3 + +.. option:: --cartridge-compat + + **Applicable to:** ``tgz`` + + Package a Cartridge CLI-compatible archive. + + .. include:: _includes/cartridge_deprecation_note.rst + +.. option:: --deps STRINGS + + **Applicable to:** ``deb``, ``rpm`` + + Specify dependencies included in RPM and DEB packages. + + **Example** + + .. code-block:: console + + $ tt pack deb --deps 'wget,make>0.1.0,unzip>1,unzip<=7' + +.. option:: --deps-file STRING + + **Applicable to:** ``deb``, ``rpm`` + + Specify the path to a file containing dependencies included in RPM and DEB packages. + For example, the ``package-deps.txt`` file below contains several dependencies and their versions: + + .. code-block:: text + + unzip==6.0 + neofetch>=6,<7 + gcc>8 + + If this file is placed in the current directory, a ``tt pack`` command might look like this: + + .. code-block:: console + + $ tt pack deb --deps-file package-deps.txt + +.. option:: --filename + + Specify a bundle name. + + **Example** + + .. code-block:: console + + $ tt pack tgz --filename sample-app.tar.gz + +.. option:: --name PACKAGE_NAME + + Specify a package name. + + **Example** + + .. code-block:: console + + $ tt pack tgz --name sample-app --version 1.0.1 + +.. option:: --preinst + + **Applicable to:** ``deb``, ``rpm`` + + Specify the path to a pre-install script for RPM and DEB packages. + + **Example** + + .. code-block:: console + + $ tt pack deb --preinst pre.sh + +.. option:: --postinst + + **Applicable to:** ``deb``, ``rpm`` + + Specify the path to a post-install script for RPM and DEB packages. + + **Example** + + .. code-block:: console + + $ tt pack deb --postinst post.sh + +.. option:: --tarantool-version + + Specify a Tarantool version for packaging in a Docker container. + For use with ``--use-docker`` only. + +.. option:: --unit-params-file + + The path to a file with custom :ref:`systemd unit parameters `. + +.. option:: --use-docker + + Build a package in an Ubuntu 18.04 Docker container. To specify a Tarantool + version to use in the container, add the ``--tarantool-version`` option. + + Before executing ``tt pack`` with this option, make sure Docker is running. + +.. option:: --version PACKAGE_VERSION + + Specify a package version. + + **Example** + + .. code-block:: console + + $ tt pack tgz --name sample-app --version 1.0.1 + +.. option:: --with-binaries + + Include Tarantool and ``tt`` binaries in a bundle. + +.. option:: --with-integrity-check PRIVATE_KEY + + Generate checksums and signatures for integrity checks at the application startup. + + See also: :ref:`tt-pack-integrity-check` + +.. option:: --with-tarantool-deps + + Add Tarantool and ``tt`` as package dependencies. + +.. option:: --without-binaries + + Don't include Tarantool and ``tt`` binaries in a bundle. + +.. option:: --without-modules + + Don't include external modules in a bundle. diff --git a/doc/tooling/tt_cli/play.rst b/doc/tooling/tt_cli/play.rst new file mode 100644 index 0000000000..80ba910a63 --- /dev/null +++ b/doc/tooling/tt_cli/play.rst @@ -0,0 +1,115 @@ +.. _tt-play: + +Playing the contents of .snap and .xlog files to a Tarantool instance +===================================================================== + +.. code-block:: console + + $ tt play URI FILE ... [OPTION ...] + +``tt play`` plays the contents of :ref:`snapshot ` (``.snap``) and +:ref:`WAL ` (``.xlog``) files to another Tarantool instance. +A single call of ``tt play`` can play multiple files. + +Options +------- + +.. option:: -u USERNAME, --username USERNAME + + A Tarantool user for connecting to the instance. + +.. option:: -p PASSWORD, --password PASSWORD + + The user's password. + +.. option:: --from LSN + + Play operations starting from the given LSN. + +.. option:: --to LSN + + Play operations up to the given LSN. Default: ``18446744073709551615``. + +.. option:: --replica ID + + Filter the operations by replica ID. Can be passed more than once. + + When calling ``tt cat`` with filters by LSN (``--from`` and ``--to`` flags) and + replica ID (``--replica``), remember that LSNs differ across replicas. + Thus, if you pass more than one replica ID via ``--from`` or ``--to``, + the result may not reflect the actual sequence of operations. + +.. option:: --space ID + + Filter the output by space ID. Can be passed more than once. + +.. option:: --show-system + + Show the operations on system spaces. + +Details +------- + +``tt play`` plays operations from ``.xlog`` and ``.snap`` files to the destination +instance one by one. All data changes happen the same way as if they were performed +on this instance. This means that: + +* All affected spaces must exist on the destination instance. They must have the same structure + and ``space_id`` as on the instance that created the snapshot or WAL file. + + To play a snapshot or a WAL to a clean instance, include the operations on system spaces + by adding the ``--show-system`` flag. With this flag, ``tt`` plays the operations that + create and configure user-defined spaces. + +* The operations' LSNs change unless you play all operations that took place since the instance startup. + +* Replica IDs change in accordance with the destination instance configuration. + +Authentication +~~~~~~~~~~~~~~ + +Use one of the following ways to pass the username and the password when connecting +to the instance: + +* The ``-u`` (``--username``) and ``-p`` (``--password``) options: + + .. code-block:: console + + $ tt play 192.168.10.10:3301 00000000000000000000.xlog -u myuser -p p4$$w0rD + +* The connection string: + + .. code-block:: console + + $ tt play myuser:p4$$w0rD@192.168.10.10:3301 00000000000000000000.xlog + +* Environment variables ``TT_CLI_USERNAME`` and ``TT_CLI_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_USERNAME=myuser + $ export TT_CLI_PASSWORD=p4$$w0rD + $ tt play 192.168.10.10:3301 00000000000000000000.xlog + +Examples +-------- + +* Play the contents of ``00000000000000000000.xlog`` to the instance on + ``192.168.10.10:3301``: + + .. code-block:: console + + $ tt play 192.168.10.10:3301 00000000000000000000.xlog + +* Play operations on spaces with ``space_id`` 512 and 513 from the + ``00000000000000000012.snap`` snapshot file: + + .. code-block:: console + + $ tt play 192.168.10.10:3301 00000000000000000012.snap --space 512 --space 513 + +* Play the contents of ``00000000000000000000.xlog`` including operations on system spaces: + + .. code-block:: console + + $ tt play 192.168.10.10:3301 00000000000000000000.xlog --show-system diff --git a/doc/tooling/tt_cli/replicaset.rst b/doc/tooling/tt_cli/replicaset.rst new file mode 100644 index 0000000000..f8e2d0e340 --- /dev/null +++ b/doc/tooling/tt_cli/replicaset.rst @@ -0,0 +1,649 @@ +.. _tt-replicaset: + +Managing replica sets +===================== + +.. code-block:: console + + $ tt replicaset COMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs COMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + +``tt replicaset`` (or ``tt rs``) manages a Tarantool replica set. + +``COMMAND`` is one of the following: + +* :ref:`status ` +* :ref:`promote ` +* :ref:`demote ` +* :ref:`expel ` +* :ref:`vshard ` +* :ref:`bootstrap ` +* :ref:`rebootstrap ` +* :ref:`roles ` + +.. _tt-replicaset-status: + +status +------ + +.. code-block:: console + + $ tt replicaset status {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs status {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + +``tt replicaset status`` (``tt rs status``) shows the current status of a replica set. + +.. _tt-replicaset-status-application: + +Displaying status of all replica sets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view the status of all replica sets of an application in the current ``tt`` +environment, run ``tt replicaset status`` with the application name: + +.. code-block:: console + + $ tt replicaset status myapp + +.. _tt-replicaset-status-instance: + +Displaying status of a single replica set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view the status of a single replica set of an application, run ``tt replicaset status`` +with a name or a URI of an instance from this replica set: + +.. code-block:: console + + $ tt replicaset status myapp:storage-001-a + +For a replica outside the current ``tt`` environment, specify its URI and access credentials: + +.. code-block:: console + + $ tt replicaset status 192.168.10.10:3301 -u myuser -p p4$$w0rD + +Learn about other ways to provide user credentials in :ref:`tt-replicaset-authentication`. + +.. _tt-replicaset-promote: + +promote +------- + +.. code-block:: console + + $ tt replicaset promote {APPLICATION:APP_INSTANCE | URI} [OPTIONS ...] + # or + $ tt rs promote {APPLICATION:APP_INSTANCE | URI} [OPTIONS ...] + +``tt replicaset promote`` (``tt rs promote``) promotes the specified instance, +making it a leader of its replica set. +This command works on Tarantool clusters with a local YAML +configuration and Cartridge clusters. + +.. note:: + + To promote an instance in a Tarantool cluster with a :ref:`centralized configuration `, + use :ref:`tt cluster replicaset promote `. + +.. _tt-replicaset-promote-config: + +Promoting in clusters with local YAML configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt replicaset promote`` works on Tarantool clusters with local YAML configurations +with :ref:`failover modes ` +``off``, ``manual``, and ``election``. + +In failover modes ``off`` or ``manual``, this command updates the cluster +configuration file according to the specified arguments and reloads it: + +- ``off`` failover mode: the command sets :ref:`database.mode ` + to ``rw`` on the specified instance. + + .. important:: + + If failover is ``off``, the command doesn't consider the modes of other + replica set members, so there can be any number of read-write instances in one replica set. + +- ``manual`` failover mode: the command updates the :ref:`leader ` + option of the replica set configuration. Other instances of this replica set become read-only. + +Example: + +.. code-block:: console + + $ tt replicaset promote my-app:storage-001-a + +If some members of the affected replica set are running outside the current ``tt`` +environment, ``tt replicaset promote`` can't ensure the configuration reload on +them and reports an error. You can skip this check by adding the ``-f``/``--force`` option: + +.. code-block:: console + + $ tt replicaset promote my-app:storage-001-a --force + +In the ``election`` failover mode, ``tt replicaset promote`` initiates the new leader +election by calling :ref:`box_ctl-promote` on the specified instance. The +``--timeout`` option can be used to specify the election completion timeout: + +.. code-block:: console + + $ tt replicaset promote my-app:storage-001-a --timeout=10 + + +.. _tt-replicaset-promote-cartridge: + +Promoting in Cartridge clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: _includes/cartridge_deprecation_note.rst + +``tt replicaset promote`` promotes instances in Cartridge clusters as follows: + +- ``disabled`` or ``eventual`` failover mode: the command changes the instance failover priority. + + .. important:: + + In these cases, consistency is not guaranteed and replication conflicts may occur. + +- ``eventual`` or ``raft`` failover mode: the command calls ``cartridge.failover_promote()`` + and waits until the instance transitions to the read-write mode. If the ``-f``/``--force`` + option is specified, the ``force_inconsistency`` option of `cartridge.failover_promote `_ + is set to ``true``. + +.. code-block:: console + + $ tt replicaset promote my-cartridge-app:storage-001-a --force + +Learn more about `Cartridge failover modes `_. + + +.. _tt-replicaset-demote: + +demote +------ + +.. code-block:: console + + $ tt replicaset demote APPLICATION:APP_INSTANCE [OPTIONS ...] + # or + $ tt rs demote APPLICATION:APP_INSTANCE [OPTIONS ...] + +``tt replicaset demote`` (``tt rs demote``) demotes an instance in a Tarantool +cluster with a local YAML configuration. + +.. note:: + + To demote an instance in a Tarantool cluster with a :ref:`centralized configuration `, + use :ref:`tt cluster replicaset demote `. + +.. _tt-replicaset-demote-config: + +Demoting in clusters with local YAML configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``tt replicaset demote`` can demote instances in Tarantool clusters with local +YAML configurations with :ref:`failover modes ` +``off`` and ``election``. + +.. note:: + + In clusters with ``manual`` failover mode, you can demote a read-write instance + by promoting a read-only instance from the same replica set with ``tt replicaset promote``. + +In the ``off`` failover mode, ``tt replicaset demote`` sets the instance's :ref:`database.mode ` +to ``ro`` and reloads the configuration. + +.. important:: + + If failover is ``off``, the command doesn't consider the modes of other + replica set members, so there can be any number of read-write instances in one replica set. + +If some members of the affected replica set are running outside the current ``tt`` +environment, ``tt replicaset demote`` can't ensure the configuration reload on +them and reports an error. You can skip this check by adding the ``-f``/``--force`` option: + +.. code-block:: console + + $ tt replicaset demote my-app:storage-001-a --force + +In the ``election`` failover mode, ``tt replicaset demote`` initiates a leader +election in the replica set. The specified instance's :ref:`replication.election_mode ` +is changed to ``voter`` for this election, which guarantees that another instance +is elected as a new replica set leader. + +The ``--timeout`` option can be used to specify the election completion timeout: + +.. code-block:: console + + $ tt replicaset demote my-app:storage-001-a --timeout=10 + +.. _tt-replicaset-expel: + +expel +----- + +.. code-block:: console + + $ tt replicaset expel APPLICATION:APP_INSTANCE [OPTIONS ...] + # or + $ tt rs expel APPLICATION[:APP_INSTANCE] [OPTIONS ...] + +``tt replicaset expel`` (``tt rs expel``) expels an instance from the cluster. + +.. code-block:: console + + $ tt replicaset expel myapp:storage-001-b + +The command supports the ``--config``, ``--cartridge``, and ``--custom`` :ref:`options ` +that force the use of a specific orchestrator. + +To expel an instance from a Cartridge cluster: + +.. code-block:: console + + $ tt replicaset expel my-cartridge-app:storage-001-b --cartridge + + +.. _tt-replicaset-vshard: + +vshard +------ + +.. code-block:: console + + $ tt replicaset vshard COMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs vshard COMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs vs COMMAND {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + +``tt replicaset vshard`` (``tt rs vs``) manages :ref:`vshard ` in the cluster. + +It has the following subcommands: + +- :ref:`bootstrap ` + +.. _tt-replicaset-vshard-bootstrap: + +vshard bootstrap +~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ tt replicaset vshard bootstrap {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs vshard bootstrap {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + # or + $ tt rs vs bootstrap {APPLICATION[:APP_INSTANCE] | URI} [OPTIONS ...] + +``tt replicaset vshard bootstrap`` (``tt rs vs bootstrap``) bootstraps ``vshard`` +in the cluster. + +.. code-block:: console + + $ tt replicaset vshard bootstrap myapp + +With a URI and credentials: + +.. code-block:: console + + $ tt replicaset vshard bootstrap 192.168.10.10:3301 -u myuser -p p4$$w0rD + +You can specify the application name or the name of any cluster instance. The command +automatically finds a ``vshard`` router in the cluster and calls :ref:`vshard.router.bootstrap() ` on it. + +The command supports the ``--config``, ``--cartridge``, and ``--custom`` :ref:`options ` +that force the use of a specific orchestrator. + +To bootstrap ``vshard`` in a Cartridge cluster: + +.. code-block:: console + + $ tt replicaset vshard bootstrap my-cartridge-app --cartridge + +.. _tt-replicaset-bootstrap: + +bootstrap +--------- + +.. include:: _includes/cartridge_deprecation_note.rst + +.. code-block:: console + + $ tt replicaset bootstrap APPLICATION[:APP_INSTANCE] [OPTIONS ...] + # or + $ tt rs bootstrap APPLICATION[:APP_INSTANCE] [OPTIONS ...] + +``tt replicaset bootstrap`` (``tt rs bootstrap``) bootstraps a Cartridge cluster or +an instance. The command works within the current ``tt`` environment and uses +application and instance names. + +.. note:: + + ``tt replicasets bootstrap`` effectively duplicates two other commands: + + - When called with an application name: :ref:`tt cartridge replicasets setup ` + - When called with an instance name: :ref:`tt cartridge replicasets join ` + +.. _tt-replicaset-bootstrap-cluster: + +Bootstrapping a Cartridge cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To bootstrap the ``cartridge_app`` application using its default replica sets file +``replicasets.yml``: + +.. code-block:: console + + $ tt replicaset bootstrap cartridge_app + +To use another file with replica set configuration, provide a path to it in the ``--file`` option: + +.. code-block:: console + + $ tt replicaset bootstrap cartridge_app --file replicasets1.yml + +To additionally bootstrap vshard after the cluster bootstrap, add ``--bootstrap-vshard``: + +.. code-block:: console + + $ tt replicaset bootstrap --bootstrap-vshard cartridge_app + + +.. _tt-replicaset-bootstrap-instance: + +Bootstrapping an instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When called with the instance name, ``tt replicaset bootstrap`` joins the +instance to the replica set specified in the ``--replicaset`` option: + +.. code-block:: console + + $ tt replicaset bootstrap --replicaset replicaset cartridge_app:instance1 + +.. _tt-replicaset-rebootstrap: + +rebootstrap +----------- + +.. code-block:: console + + $ tt replicaset rebootstrap APPLICATION:APP_INSTANCE [-y | --yes] + # or + $ tt rs rebootstrap APPLICATION:APP_INSTANCE [-y | --yes] + +``tt replicaset rebootstrap`` (``tt rs rebootstrap``) rebootstraps an instance: +stops it, removes instance artifacts, starts it again. + +To rebootstrap the ``storage-001`` instance of the ``myapp`` application: + +.. code-block:: console + + $ tt replicaset rebootstrap myapp:storage-001 + +To automatically confirm reboostrap, add the ``-y``/``--yes`` option: + +.. code-block:: console + + $ tt replicaset rebootstrap myapp:storage-001 -y + +.. _tt-replicaset-roles: + +roles +----- + +.. code-block:: console + + $ tt replicaset roles [add|remove] APPLICATION[:APP_INSTANCE] ROLE_NAME [OPTIONS ...] + # or + $ tt rs roles [add|remove] APPLICATION[:APP_INSTANCE] ROLE_NAME [OPTIONS ...] + +``tt replicaset roles`` (``tt rs roles``) manages :ref:`application roles ` +in the cluster. +This command works on Tarantool clusters with a local YAML +configuration and Cartridge clusters. It has two subcommands: + +* ``add`` adds a role +* ``remove`` removes a role + +.. note:: + + To manage roles in a Tarantool cluster with a :ref:`centralized configuration `, + use :ref:`tt cluster replicaset roles `. + + +.. _tt-replicaset-roles-config: + +Managing roles in clusters with local YAML configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When called on clusters with local YAML configurations, ``tt replicaset roles`` +subcommands add or remove the corresponding lines from the configuration file +and reload the configuration. + +Use the ``--global``, ``--group``, ``--replicaset``, ``--instance`` options to specify +the configuration scope to add or remove roles. For example, to add a role to +all instances in a replica set: + +.. code-block:: console + + $ tt replicaset roles add my-app roles.my-role --replicaset storage-a + +You can also manage roles of a specific instance by specifying its name after the application name: + +.. code-block:: console + + $ tt replicaset roles add my-app:router-001 roles.my-role + +To remove a role defined in the global configuration scope: + +.. code-block:: console + + $ tt replicaset roles remove my-app roles.my-role --global + +If some instances of the affected scope are running outside the current ``tt`` +environment, ``tt replicaset roles`` can't ensure the configuration reload on +them and reports an error. You can skip this check by adding the ``-f``/``--force`` option: + +.. code-block:: console + + $ tt replicaset roles add my-app roles.my-role --replicaset storage-a --force + + +.. _tt-replicaset-roles-cartridge: + +Managing roles in Cartridge clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: _includes/cartridge_deprecation_note.rst + +When called on Cartridge clusters, ``tt replicaset roles`` subcommands add or remove +Cartridge `cluster roles `__. + +Cartridge cluster roles are defined per replica set. Thus, you can use the +``--replicaset`` and ``--group`` options to define a role's scope. In this case, +a group is a `vshard group `__. + +To add a role to a Cartridge cluster replica set: + +.. code-block:: console + + $ tt replicaset roles add my-cartridge-app my-role --replicaset storage-001 + +To remove a role from a vshard group: + +.. code-block:: console + + $ tt replicaset roles remove my-cartridge-app my-role --group cold-data + +Learn more about `Cartridge cluster roles `_. + + +.. _tt-replicaset-orchestrator: + +Selecting the application orchestrator manually +----------------------------------------------- + +You can specify the orchestrator to use for the application when calling ``tt replicaset`` +commands. The following options are available: + +* ``--config`` for applications that use YAML cluster configuration (Tarantool 3.x or later). +* ``--cartridge`` for Cartridge applications (Tarantool 2.x). +* ``--custom`` for any other orchestrators used on Tarantool 2.x clusters. + +.. code-block:: console + + $ tt replicaset status myapp --config + $ tt replicaset promote my-cartridge-app:storage-001-a --cartridge + +If an actual orchestrator that the application uses does not match the specified +option, an error is raised. + +.. _tt-replicaset-authentication: + +Authentication +-------------- + +Use one of the following ways to pass the credentials of a Tarantool user when +connecting to the instance by its URI: + +* The ``-u`` (``--username``) and ``-p`` (``--password``) options: + + .. code-block:: console + + $ tt replicaset status 192.168.10.10:3301 -u myuser -p p4$$w0rD + +* The connection string: + + .. code-block:: console + + $ tt replicaset status myuser:p4$$w0rD@192.168.10.10:3301 + +* Environment variables ``TT_CLI_USERNAME`` and ``TT_CLI_PASSWORD``: + + .. code-block:: console + + $ export TT_CLI_USERNAME=myuser + $ export TT_CLI_PASSWORD=p4$$w0rD + $ tt replicaset status 192.168.10.10:3301 + +.. _tt-replicaset-options: + +Options +------- + +.. option:: --bootstrap-vshard + + **Applicable to:** ``bootstrap`` + + Additionally bootstrap vshard when bootstrapping a Cartridge application. + +.. option:: --cartridge + + Force the Cartridge orchestrator for Tarantool 2.x clusters. + +.. option:: --config + + Force the YAML configuration orchestrator for Tarantool 3.0 or later clusters. + +.. option:: --custom + + Force a custom orchestrator for Tarantool 2.x clusters. + +.. option:: --file STRING + + **Applicable to:** ``bootstrap`` + + A file with Cartridge replica sets configuration. Default: ``instances.yml`` + in the application directory. + + See also: :ref:`tt-replicaset-bootstrap-cluster` + +.. option:: -f, --force + + **Applicable to:** ``promote``, ``demote``, ``roles`` + + Skip operation on instances not running in the same environment. + +.. option:: -G, --global + + **Applicable to:** ``roles`` on Tarantool 3.x and later + + Apply the operation to the global configuration scope, that is, to all instances. + +.. option:: -g, --group STRING + + **Applicable to:** ``roles`` + + A name of the configuration group to which the operation applies. + + +.. option:: -i, --instance STRING + + **Applicable to:** ``roles`` + + A name of the instance to which the operation applies. Not applicable to Cartridge clusters. + Learn more in :ref:`tt-replicaset-roles-cartridge`. + +.. option:: -r, --replicaset STRING + + **Applicable to:** ``bootstrap``, ``roles`` + + A name of the replica set to which the operation applies. + + See also: :ref:`tt-replicaset-bootstrap-instance` + +.. option:: -u, --username STRING + + A Tarantool user for connecting to the instance using a URI. + +.. option:: -p, --password STRING + + The user's password. + +.. option:: --sslcertfile STRING + + The path to an SSL certificate file for encrypted connections for the URI case. + +.. option:: --sslkeyfile STRING + + The path to a private SSL key file for encrypted connections for the URI case. + +.. option:: --sslcafile STRING + + The path to a trusted certificate authorities (CA) file for encrypted connections for the URI case. + +.. option:: --sslciphers STRING + + The list of SSL cipher suites used for encrypted connections for the URI case, separated by colons (``:``). + +.. option:: --timeout UINT + + **Applicable to:** ``promote``, ``demote``, ``expel``, ``vshard``, ``bootstrap`` + + The timeout for completing the operation, in seconds. Default: + + - ``3`` for ``promote``, ``demote``, ``expel``, ``roles`` + - ``10`` for ``vshard`` and ``bootstrap`` + +.. option:: --with-integrity-check STRING + + .. admonition:: Enterprise Edition + :class: fact + + This option is supported by the `Enterprise Edition `_ only. + + **Applicable to:** ``promote``, ``demote``, ``expel``, ``roles`` + + Generate hashes and signatures for integrity checks. + +.. option:: -y, --yes + + **Applicable to:** ``rebootstrap`` + + Automatically confirm rebootstrap. \ No newline at end of file diff --git a/doc/tooling/tt_cli/restart.rst b/doc/tooling/tt_cli/restart.rst new file mode 100644 index 0000000000..e1fbdbf37f --- /dev/null +++ b/doc/tooling/tt_cli/restart.rst @@ -0,0 +1,47 @@ +.. _tt-restart: + +Restarting a Tarantool instance +=============================== + +.. code-block:: console + + $ tt restart APPLICATION[:APP_INSTANCE] [OPTION ...] + +``tt restart`` restarts the specified running Tarantool instance. +A ``tt restart`` call is equivalent to consecutive calls of +:doc:`tt stop ` and :doc:`tt start `. + +When called without arguments, restarts all running applications in the current environment. + +See also: :ref:`tt-start`, :ref:`tt-stop`, :ref:`tt-status`. + + +Options +------- + +.. option:: -y, --yes + + Automatic "Yes" to confirmation prompt. + +Examples +-------- + +* Restart all instances of the application stored in the ``app`` directory inside + ``instances_enabled`` in accordance with the :ref:`instances configuration `: + + .. code-block:: console + + $ tt restart app + + .. note:: + + This call starts all application instances specified in its ``instances.yml``, + even those that were not running before the call. + +* Restart only the ``master`` instance of the ``app`` application with automatic confirmation: + + .. code-block:: console + + $ tt restart app:master -y + + diff --git a/doc/reference/tooling/tt_cli/rocks.rst b/doc/tooling/tt_cli/rocks.rst similarity index 97% rename from doc/reference/tooling/tt_cli/rocks.rst rename to doc/tooling/tt_cli/rocks.rst index 7f2a80cd5e..d84ef5eb82 100644 --- a/doc/reference/tooling/tt_cli/rocks.rst +++ b/doc/tooling/tt_cli/rocks.rst @@ -72,6 +72,8 @@ Commands :widths: 20 80 :header-rows: 0 + * - ``admin`` + - Use the `luarocks-admin `__ tool * - ``build`` - Build and compile a rock * - ``config`` diff --git a/doc/reference/tooling/tt_cli/run.rst b/doc/tooling/tt_cli/run.rst similarity index 94% rename from doc/reference/tooling/tt_cli/run.rst rename to doc/tooling/tt_cli/run.rst index 26b7d204c4..da49590efe 100644 --- a/doc/reference/tooling/tt_cli/run.rst +++ b/doc/tooling/tt_cli/run.rst @@ -7,7 +7,7 @@ Running code in a Tarantool instance $ tt run [SCRIPT|-e EXPR] [OPTION ...] -``tt run`` executes Lua code in a Tarantool instance. +``tt run`` executes Lua code in a new Tarantool instance. Options ------- @@ -61,4 +61,4 @@ Examples .. code-block:: console - $ tt run app.lua -i + $ tt run -i app.lua diff --git a/doc/reference/tooling/tt_cli/search.rst b/doc/tooling/tt_cli/search.rst similarity index 93% rename from doc/reference/tooling/tt_cli/search.rst rename to doc/tooling/tt_cli/search.rst index 0437d295e0..f2994eaf82 100644 --- a/doc/reference/tooling/tt_cli/search.rst +++ b/doc/tooling/tt_cli/search.rst @@ -25,7 +25,7 @@ Options .. option:: --debug - **Applicable to:** ``taranttol-ee`` + **Applicable to:** ``tarantool-ee`` Search for debug builds of Tarantool Enterprise Edition's SDK. @@ -36,7 +36,7 @@ Options .. option:: --version VERSION - **Applicable to:** ``taranttol-ee`` + **Applicable to:** ``tarantool-ee`` Tarantool Enterprise version. diff --git a/doc/tooling/tt_cli/start.rst b/doc/tooling/tt_cli/start.rst new file mode 100644 index 0000000000..03a851a34c --- /dev/null +++ b/doc/tooling/tt_cli/start.rst @@ -0,0 +1,148 @@ +.. _tt-start: + +Starting Tarantool applications +=============================== + +.. code-block:: console + + $ tt start [APPLICATION[:APP_INSTANCE]] + +``tt start`` starts Tarantool applications. The application files must be stored +inside the ``instances_enabled`` directory specified in the :ref:`tt configuration file `. +For detailed instructions on preparing and running Tarantool applications, see +:ref:`admin-instance-environment-overview` and :ref:`admin-start_stop_instance`. + +See also: :ref:`tt-stop`, :ref:`tt-restart`, :ref:`tt-status`. + +To start all instances of the application stored in the ``app`` directory inside +``instances_enabled`` in accordance with its ``instances.yml``: + +.. code-block:: console + + $ tt start app + +To start all instances of the ``app`` application appending their logs to stdout +(in the interactive mode): + +.. code-block:: console + + $ tt start -i app + +To start the ``router`` instance of the ``app`` application: + +.. code-block:: console + + $ tt start app:router + +When called without arguments, starts all enabled applications in the current environment: + +.. code-block:: console + + $ tt start + +.. _tt-start-app-layout: + +Application layout +------------------ + +``tt start`` can start entire Tarantool clusters based on their YAML configurations. +A cluster application directory inside ``instances_enabled`` must contain the following files: + +* ``config.yaml`` -- a :ref:`YAML configuration ` that defines + the cluster topology and settings. + It can either contain an explicit configuration in the YAML format or point + to a centralized configuration storage (for Enterprise Edition). +* ``instances.yml`` -- a file that defines the list of cluster instances to run + in the current environment. +* (Optionally) ``*.lua`` files with code to load and run in the cluster. + +For more information about Tarantool application layout, see :ref:`admin-instance-environment-overview`. + +.. note:: + + ``tt`` also supports Tarantool applications with :ref:`configuration in code `, + which is considered a legacy approach since Tarantool 3.0. For information + about using ``tt`` with such applications, refer to the Tarantool 2.11 documentation. + +.. _tt-start-background: + +Running in the background +------------------------- + +``tt start`` runs Tarantool applications in the background and uses its own watchdog +process for status checks (:ref:`tt status `) and application stopping (:ref:`tt stop `). + +.. important:: + + Do not switch on the background mode using the cluster configuration + (``process.background: true`` in the YAML configuration) or code (``box.cfg.background = true``) + in applications that you run with ``tt``. + If you start such an application with ``tt start``, ``tt`` won't be able to check + the application status or stop it using the corresponding commands. + +.. _tt-start-integrity-check: + +Integrity check +--------------- + +.. admonition:: Enterprise Edition + :class: fact + + The integrity check functionality is supported by the `Enterprise Edition `_ only. + +``tt start`` can perform initial and periodical integrity checks of the environment, +application, and centralized configuration. + +To enable integrity checks of environment and application files, you need to pack +the application using ``tt pack`` with the ``--with-integrity-check`` option. +This option generates and signs checksums of executables and configuration files in the current ``tt`` +environment. Learn more in :ref:`tt-pack-integrity-check`. + +To enable integrity check of the configuration at the centralized storage, +publish the configuration to this storage using ``tt cluster publish`` with the ``--with-integrity-check`` option. +This option generates and signs configuration checksums and saves them to the storage. +Learn more in :ref:`tt-cluster-publish-integrity`. + +To perform the integrity checks when running the application, start it with the +``--integrity-check`` :ref:`global option `. +Its argument must be a public key matching the private key that was used for +generating checksums. + +.. code-block:: console + + $ tt --integrity-check public.pem start myapp + +After such a call, ``tt`` checks the environment, application, and configuration integrity +using the checksums and starts the application in case of the success. Then, integrity +checks are performed periodically while the application is running. By default, +they are performed once every 24 hours. You can adjust the integrity check period +by adding the ``--integrity-check-period`` option: + +.. code-block:: console + + $ tt --integrity-check public.pem start myapp --integrity-check-period 60 + +Additionally, Tarantool checks the integrity of the modules that the application uses +at the load time, that is, when ``require('module')`` is called. + +If an integrity check fails, ``tt`` stops the application. + +.. _tt-start-options: + +Options +------- + +.. option:: -i, --interactive + + Start the application or instance in the interactive mode. + In this mode, instance logs are printed to the standard output in real time. + + You can use the ``SIGINT`` signal (``CTRL+C``) to stop ``tt`` and its child + Tarantool processes in the interactive mode. No watchdog processes are created. + +.. option:: --integrity-check-interval NUMBER + + Integrity check interval in seconds. Default: 86400 (24 hours). + Set this option to ``0`` to disable periodic checks. + + See also: :ref:`tt-start-integrity-check` \ No newline at end of file diff --git a/doc/tooling/tt_cli/start_stop_instance.rst b/doc/tooling/tt_cli/start_stop_instance.rst new file mode 100644 index 0000000000..a9ee6b3702 --- /dev/null +++ b/doc/tooling/tt_cli/start_stop_instance.rst @@ -0,0 +1,231 @@ +.. _admin-start_stop_instance: + +Starting and stopping instances +=============================== + +This section describes how to manage instances in a Tarantool cluster using the :ref:`tt ` utility. +A cluster can include multiple instances that run different code. +A typical example is a cluster application that includes router and storage instances. +Particularly, you can perform the following actions: + +* start all instances in a cluster or only specific ones +* check the status of instances +* connect to a specific instance +* stop all instances or only specific ones + +To get more context on how the application's environment might look, refer to :ref:`Application environment `. + +.. NOTE:: + + In this section, a `sharded_cluster_crud `_ application is used to demonstrate how to start, stop, and manage instances in a cluster. + + +.. _configuration_run_instance: +.. _configuration_run_instance_tt: + +Starting Tarantool instances +---------------------------- + +To start Tarantool instances use the :ref:`tt start ` command: + +.. code-block:: console + + $ tt start sharded_cluster_crud + • Starting an instance [sharded_cluster_crud:storage-a-001]... + • Starting an instance [sharded_cluster_crud:storage-a-002]... + • Starting an instance [sharded_cluster_crud:storage-b-001]... + • Starting an instance [sharded_cluster_crud:storage-b-002]... + • Starting an instance [sharded_cluster_crud:router-a-001]... + +After the cluster has started and worked for some time, you can find its artifacts +in the directories specified in the ``tt`` configuration. These are the default +locations in the local :ref:`launch mode `: + +* ``sharded_cluster_crud/var/log//`` -- instance :ref:`logs `. +* ``sharded_cluster_crud/var/lib//`` -- :ref:`snapshots and write-ahead logs `. +* ``sharded_cluster_crud/var/run//`` -- control sockets and PID files. + +In the system launch mode, artifacts are created in these locations: + +* ``/var/log/tarantool//`` +* ``/var/lib/tarantool//`` +* ``/var/run/tarantool//`` + + + + +.. _admin-start_stop_instance_management: + +Basic instance management +------------------------- + +Most of the commands described in this section can be called with or without an instance name. +Without the instance name, they are executed for all instances defined in ``instances.yaml``. + + +.. _admin-start_stop_instance_check_status: + +Checking an instance's status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To check the status of instances, execute :ref:`tt status `: + +.. code-block:: console + + $ tt status sharded_cluster_crud + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + sharded_cluster_crud:router-a-001 RUNNING 8382 RW ready running -- + sharded_cluster_crud:storage-a-001 RUNNING 8386 RW ready running -- + sharded_cluster_crud:storage-a-002 RUNNING 8390 RO ready running -- + sharded_cluster_crud:storage-b-001 RUNNING 8379 RW ready running -- + sharded_cluster_crud:storage-b-002 RUNNING 8380 RO ready running -- + +To check the status of a specific instance, you need to specify its name: + +.. code-block:: console + + $ tt status sharded_cluster_crud:storage-a-001 + INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM + sharded_cluster_crud:storage-a-001 RUNNING 8386 RW ready running -- + +.. _admin-start_stop_instance_connect: + +Connecting to an instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To connect to the instance, use the :ref:`tt connect ` command: + +.. code-block:: console + + $ tt connect sharded_cluster_crud:storage-a-001 + • Connecting to the instance... + • Connected to sharded_cluster_crud:storage-a-001 + + sharded_cluster_crud:storage-a-001> + +In the instance's console, you can execute commands provided by the :ref:`box ` module. +For example, :ref:`box.info ` can be used to get various information about a running instance: + +.. code-block:: tarantoolsession + + sharded_cluster_crud:storage-a-001> box.info.ro + --- + - false + ... + + + +.. _admin-start_stop_instance_restart: + +Restarting instances +~~~~~~~~~~~~~~~~~~~~ + +To restart an instance, use :ref:`tt restart `: + +.. code-block:: console + + $ tt restart sharded_cluster_crud:storage-a-002 + +After executing ``tt restart``, you need to confirm this operation: + +.. code-block:: console + + Confirm restart of 'sharded_cluster_crud:storage-a-002' [y/n]: y + • The Instance sharded_cluster_crud:storage-a-002 (PID = 2026) has been terminated. + • Starting an instance [sharded_cluster_crud:storage-a-002]... + + +.. _admin-start_stop_instance_stop: + +Stopping instances +~~~~~~~~~~~~~~~~~~ + +To stop the specific instance, use :ref:`tt stop ` as follows: + +.. code-block:: console + + $ tt stop sharded_cluster_crud:storage-a-002 + +You can also stop all the instances at once as follows: + +.. code-block:: console + + $ tt stop sharded_cluster_crud + • The Instance sharded_cluster_crud:storage-b-001 (PID = 2020) has been terminated. + • The Instance sharded_cluster_crud:storage-b-002 (PID = 2021) has been terminated. + • The Instance sharded_cluster_crud:router-a-001 (PID = 2022) has been terminated. + • The Instance sharded_cluster_crud:storage-a-001 (PID = 2023) has been terminated. + • can't "stat" the PID file. Error: "stat /home/testuser/myapp/instances.enabled/sharded_cluster_crud/var/run/storage-a-002/tt.pid: no such file or directory" + +.. note:: + + The error message indicates that ``storage-a-002`` is already not running. + + +.. _admin-start_stop_instance_remove_artifacts: + +Removing instance artifacts +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`tt clean ` command removes instance artifacts (such as logs or snapshots): + +.. code-block:: console + + $ tt clean sharded_cluster_crud + • List of files to delete: + + • /home/testuser/myapp/instances.enabled/sharded_cluster_crud/var/log/storage-a-001/tt.log + • /home/testuser/myapp/instances.enabled/sharded_cluster_crud/var/lib/storage-a-001/00000000000000001062.snap + • /home/testuser/myapp/instances.enabled/sharded_cluster_crud/var/lib/storage-a-001/00000000000000001062.xlog + • ... + + Confirm [y/n]: + +Enter ``y`` and press ``Enter`` to confirm removing of artifacts for each instance. + +.. note:: + + The ``-f`` option of the ``tt clean`` command can be used to remove the files without confirmation. + + + + + +.. _admin-tt-preload: + +Preloading Lua scripts and modules +---------------------------------- + +Tarantool supports loading and running chunks of Lua code before starting instances. +To load or run Lua code immediately upon Tarantool startup, specify the ``TT_PRELOAD`` +environment variable. Its value can be either a path to a Lua script or a Lua module name: + +* To run the Lua script ``preload_script.lua`` from the ``sharded_cluster_crud`` directory, set ``TT_PRELOAD`` as follows: + + .. code-block:: console + + $ TT_PRELOAD=preload_script.lua tt start sharded_cluster_crud + + Tarantool runs the ``preload_script.lua`` code, waits for it to complete, and + then starts instances. + +* To load the ``preload_module`` from the ``sharded_cluster_crud`` directory, set ``TT_PRELOAD`` as follows: + + .. code-block:: console + + $ TT_PRELOAD=preload_module tt start sharded_cluster_crud + + .. note:: + + ``TT_PRELOAD`` values that end with ``.lua`` are considered scripts, + so avoid module names with this ending. + +To load several scripts or modules, pass them in a single quoted string, separated +by semicolons: + +.. code-block:: console + + $ TT_PRELOAD="preload_script.lua;preload_module" tt start sharded_cluster_crud + +If an error happens during the execution of the preload script or module, Tarantool +reports the problem and exits. diff --git a/doc/tooling/tt_cli/status.rst b/doc/tooling/tt_cli/status.rst new file mode 100644 index 0000000000..6d73dd24e7 --- /dev/null +++ b/doc/tooling/tt_cli/status.rst @@ -0,0 +1,53 @@ +.. _tt-status: + +Checking instance status +======================== + +.. code-block:: console + + $ tt status [APPLICATION[:APP_INSTANCE]] [OPTION ...] + +``tt status`` prints the information about Tarantool applications and instances +in the current environment. This includes: + +- ``INSTANCE`` -- application and instance names +- ``STATUS`` -- instance status: running, not running, or terminated with an error +- ``PID`` -- process IDs +- ``MODE`` -- instance modes: read-write or read-only +- ``CONFIG`` -- the instances' states in regard to configuration for Tarantool 3.0 or later (see :ref:`config.info() `) +- ``BOX`` -- the instances' :ref:`box.info() ` statuses +- ``UPSTREAM`` -- the instances' :ref:`box.info.replication[*].upstream ` statuses + +When called without arguments, prints the status of all enabled applications in the current environment. + +Examples +-------- + +* Print the status of all instances of the ``app`` application: + + .. code-block:: console + + $ tt status app + +* Print the status of the ``replica`` instance of the ``app`` application: + + .. code-block:: console + + $ tt status app:replica + +* Pretty-print the status of the ``replica`` instance of the ``app`` application: + + .. code-block:: console + + $ tt status app:replica --pretty + +Options +------- + +.. option:: -d, --details + + Print detailed alerts. + +.. option:: -p, --pretty + + Print the status as a pretty-formatted table. \ No newline at end of file diff --git a/doc/tooling/tt_cli/stop.rst b/doc/tooling/tt_cli/stop.rst new file mode 100644 index 0000000000..8edefabed3 --- /dev/null +++ b/doc/tooling/tt_cli/stop.rst @@ -0,0 +1,45 @@ +.. _tt-stop: + +Stopping a Tarantool instance +============================= + +.. code-block:: console + + $ tt stop [APPLICATION[:APP_INSTANCE]] + +``tt stop`` stops the specified running Tarantool applications or instances. +Before stopping the instances, the command prompts the user for confirmation. + +When called without arguments, ``tt stop`` stops all running applications in the current environment. + +See also: :ref:`tt-start`, :ref:`tt-restart`, :ref:`tt-status`. + +Examples +-------- + +* Stop all instances of the ``app`` application: + + .. code-block:: console + + $ tt stop app + + +* Stop all instances of the ``app`` application without confirmation: + + .. code-block:: console + + $ tt stop app -y + +* Stop the ``replica`` instance of the ``app`` application: + + .. code-block:: console + + $ tt stop app:replica + + +Options +------- + +.. option:: -y, --yes + + Stop instances without confirmation. \ No newline at end of file diff --git a/doc/tooling/tt_cli/tarantoolctl_tt_migrating.rst b/doc/tooling/tt_cli/tarantoolctl_tt_migrating.rst new file mode 100644 index 0000000000..705978fcb9 --- /dev/null +++ b/doc/tooling/tt_cli/tarantoolctl_tt_migrating.rst @@ -0,0 +1,165 @@ +.. _tarantoolctl-migration-to-tt: + +Migration from tarantoolctl to tt +================================= + +:ref:`tt ` is a command-line utility for managing Tarantool applications +that comes to replace ``tarantoolctl``. Starting from version 3.0, ``tarantoolctl`` +is no longer shipped as a part of Tarantool distribution; ``tt`` is the only +recommended tool for managing Tarantool applications from the command line. + +``tarantoolctl`` remains fully compatible with Tarantool 2.* versions. However, +it doesn't receive major updates anymore. + +We recommend that you migrate from ``tarantoolctl`` to ``tt`` to ensure the full +support and timely updates and fixes. + +System-wide configuration +------------------------- + +``tt`` supports system-wide environment configuration by default. If you have +Tarantool instances managed by ``tarantoolctl`` in such an environment, you can +switch to ``tt`` without additional migration steps or use ``tt`` along with ``tarantoolctl``. + +Example: + +.. code-block:: bash + + $ sudo tt instances + List of enabled applications: + • example + + $ tarantoolctl start example + Starting instance example... + Forwarding to 'systemctl start tarantool@example' + + $ tarantoolctl status example + Forwarding to 'systemctl status tarantool@example' + ● tarantool@example.service - Tarantool Database Server + Loaded: loaded (/lib/systemd/system/tarantool@.service; enabled; vendor preset: enabled) + Active: active (running) + Docs: man:tarantool(1) + Main PID: 6698 (tarantool) + . . . + + $ sudo tt status + • example: RUNNING. PID: 6698. + + $ sudo tt connect example + • Connecting to the instance... + • Connected to /var/run/tarantool/example.control + + /var/run/tarantool/example.control> + + $ sudo tt stop example + • The Instance example (PID = 6698) has been terminated. + + $ tarantoolctl status example + Forwarding to 'systemctl status tarantool@example' + ○ tarantool@example.service - Tarantool Database Server + Loaded: loaded (/lib/systemd/system/tarantool@.service; enabled; vendor preset: enabled) + Active: inactive (dead) + +Local configuration +------------------- + +If you have a local ``tarantoolctl`` configuration, create a ``tt`` environment +based on the existing ``.tarantoolctl`` configuration file. To do this, run +``tt init`` in the directory where the file is located. + +Example: + +.. code-block:: bash + + $ cat .tarantoolctl + default_cfg = { + pid_file = "./run/tarantool", + wal_dir = "./lib/tarantool", + memtx_dir = "./lib/tarantool", + vinyl_dir = "./lib/tarantool", + log = "./log/tarantool", + language = "Lua", + } + instance_dir = "./instances.enabled" + + $ tt init + • Found existing config '.tarantoolctl' + • Environment config is written to 'tt.yaml' + +After that, you can start managing Tarantool instances in this environment with ``tt``: + +.. code-block:: bash + + $ tt start app1 + • Starting an instance [app1]... + + $ tt status app1 + • app1: RUNNING. PID: 33837. + + $ tt stop app1 + • The Instance app1 (PID = 33837) has been terminated. + + $ tt check app1 + • Result of check: syntax of file '/home/user/instances.enabled/app1.lua' is OK + +Commands difference +------------------- + +Most ``tarantoolctl`` commands look the same in ``tt``: ``tarantoolctl start`` and +``tt start``, ``tarantoolctl play`` and ``tt play``, and so on. To migrate such +calls, it is usually enough to replace the utility name. There can be slight differences +in command flags and format. For details on ``tt`` commands, see the +:ref:`tt commands reference `. + +The following commands are different in ``tt``: + +.. container:: table + + .. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - ``tarantoolctl`` command + - ``tt`` command + * - ``tarantoolctl enter`` + - ``tt connect`` + * - ``tarantoolctl eval`` + - ``tt connect`` with ``-f`` flag + +.. note:: + + ``tt connect`` also covers ``tarantoolctl connect`` with the same syntax. + +Example: + +.. code-block:: bash + + # tarantoolctl enter > tt connect + $ tarantoolctl enter app1 + connected to unix/:./run/tarantool/app1.control + unix/:./run/tarantool/app1.control> + + $ tt connect app1 + • Connecting to the instance... + • Connected to /home/user/run/tarantool/app1/app1.control + + # tarantoolctl eval > tt connect -f + $ tarantoolctl eval app1 eval.lua + connected to unix/:./run/tarantool/app1.control + --- + - 42 + ... + + $ tt connect app1 -f eval.lua + --- + - 42 + ... + + # tarantoolctl connect > tt connect + $ tarantoolctl connect localhost:3301 + connected to localhost:3301 + localhost:3301> + + $ tt connect localhost:3301 + • Connecting to the instance... + • Connected to localhost:3301 \ No newline at end of file diff --git a/doc/tooling/tt_cli/tdg2.rst b/doc/tooling/tt_cli/tdg2.rst new file mode 100644 index 0000000000..3877961474 --- /dev/null +++ b/doc/tooling/tt_cli/tdg2.rst @@ -0,0 +1,19 @@ +.. _tt-tdg2: + +Interacting with the Tarantool Data Grid 2 +========================================== + +.. admonition:: Enterprise Edition + :class: fact + + This command is supported by the `Enterprise Edition `_ only. + +.. code-block:: console + + $ tt tdg2 COMMAND [COMMAND_OPTION ...] + +``tt tdg2`` enables the interaction with `Tarantool Data Grid 2 `_ clusters. +``COMMAND`` is one of the following: + +* ``export``: export a TDG2 cluster's data to a file. Learn more at :ref:`Exporting data `. +* ``import``: import data to a TDG2 cluster from a file. Learn more at :ref:`Importing data `. diff --git a/doc/tooling/tt_cli/tt_interactive_console.rst b/doc/tooling/tt_cli/tt_interactive_console.rst new file mode 100644 index 0000000000..3e90449278 --- /dev/null +++ b/doc/tooling/tt_cli/tt_interactive_console.rst @@ -0,0 +1,280 @@ +.. _tt-interactive-console: + +tt interactive console +====================== + +The ``tt`` utility features a command-line console that allows executing requests +and Lua code interactively on the connected Tarantool instances. +It is similar to the :ref:`Tarantool interactive console ` with +one key difference: the ``tt`` console allows connecting to any available instance, +both local and remote. Additionally, it offers more flexible output formatting capabilities. + +.. _tt-interactive-console-enter: + +Entering the console +-------------------- + +To connect to a Tarantool instance using the ``tt`` console, run :ref:`tt connect `. + +Specify the instance URI and the user credentials in the corresponding options: + +.. code-block:: console + + $ tt connect 192.168.10.10:3301 -u myuser -p p4$$w0rD + • Connecting to the instance... + • Connected to 192.168.10.10:3301 + + 192.168.10.10:3301> + +If a user is not specified, the connection is established on behalf of the ``guest`` user. + +If the instance runs in the same ``tt`` environment, you can establish a local +connection with it by specifying the ``:`` string instead of the URI: + +.. code-block:: console + + $ tt connect app:storage001 + • Connecting to the instance... + • Connected to app:storage001 + + app:storage001> + +Local connections are established on behalf of the ``admin`` user. + +To get the list of supported console commands, enter ``\help`` or ``?``. +To quit the console, enter ``\quit`` or ``\q``. + +.. _tt-interactive-console-input: + +Console input +------------- + +Similarly to the :ref:`Tarantool interactive console `, the +``tt`` console can handle Lua or SQL input. The default is Lua. For Lua input, +the tab-based autocompletion works automatically for loaded modules. + +To change the input language to SQL, run ``\set language sql``: + +.. code-block:: console + + app:storage001> \set language sql + app:storage001> select * from bands where id = 1 + --- + - metadata: + - name: id + type: unsigned + - name: band_name + type: string + - name: year + type: unsigned + rows: + - [1, 'Roxette', 1986] + ... + +To change the input language back to Lua, run ``\set language lua``: + +.. code-block:: console + + app:storage001> \set language lua + app:storage001> box.space.bands:select { 1 } + --- + - - [1, 'Roxette', 1986] + ... + +.. note:: + + You can also specify the input language in the ``tt connect`` call using the + ``-l``/``--language`` option: + + .. code-block:: console + + $ tt connect app:storage001 -l sql + + +.. _tt-interactive-console-output: + +Console output +-------------- + +By default, the ``tt`` console prints the output data in the YAML format, each +tuple on the new line: + +.. code-block:: console + + app:storage001> box.space.bands:select { } + --- + - - [1, 'Roxette', 1986] + - [2, 'Scorpions', 1965] + - [3, 'Ace of Base', 1987] + ... + +You can switch to alternative output formats -- Lua or ASCII (pseudographics) tables -- +using the ``\set output`` console command: + +.. code-block:: console + + app:storage001> \set output lua + app:storage001> box.space.bands:select { } + {{1, "Roxette", 1986}, {2, "Scorpions", 1965}, {3, "Ace of Base", 1987}}; + app:storage001> \set output table + app:storage001> box.space.bands:select { } + +------+-------------+------+ + | id | band_name | year | + +------+-------------+------+ + | 1 | Roxette | 1986 | + +------+-------------+------+ + | 2 | Scorpions | 1965 | + +------+-------------+------+ + | 3 | Ace of Base | 1987 | + +------+-------------+------+ + +.. note:: + + Field names are printed since Tarantool 3.2. On earlier versions, + actual names are replaced by numbered placeholders ``col1``, ``col2``, and so on. + +The table output can be printed in the transposed format, where an object's fields +are arranged in columns instead of rows: + +.. code-block:: console + + app:storage001> \set output ttable + app:storage001> box.space.bands:select { } + +-----------+---------+-----------+-------------+ + | id | 1 | 2 | 3 | + +-----------+---------+-----------+-------------+ + | band_name | Roxette | Scorpions | Ace of Base | + +-----------+---------+-----------+-------------+ + | year | 1986 | 1965 | 1987 | + +-----------+---------+-----------+-------------+ + +.. note:: + + You can also specify the output format in the ``tt connect`` call using the + ``-x``/``--outputformat`` option: + + .. code-block:: console + + $ tt connect app:storage001 -x table + +For ``table`` and ``ttable`` output, more customizations are possible with the +following commands: + +* ``\set table_format`` -- table format: default (pseudographics, or ASCII table), Markdown, + or Jira-compatible format: + + .. code-block:: console + + app:storage001> \set table_format jira + app:storage001> box.space.bands:select {} + | id | 1 | 2 | 3 | + | band_name | Roxette | Scorpions | Ace of Base | + | year | 1986 | 1965 | 1987 | + +* ``\set grahpics`` -- enable or disable graphics for table cells in the default format: + + .. code-block:: console + + app:storage001> \set table_format default + app:storage001> \set graphics false + app:storage001> box.space.bands:select {} + id 1 2 3 + band_name Roxette Scorpions Ace of Base + year 1986 1965 1987 + +* ``\set table_column_width`` -- maximum column width. + + .. code-block:: console + + app:storage001> \set table_column_width 6 + app:storage001> box.space.bands:select {} + id 1 2 3 + band_n Roxett Scorpi Ace of + +ame +e +ons + Base + year 1986 1965 1987 + + +.. _tt-interactive-console-commands: + +Commands +-------- + +\\help, ? +~~~~~~~~~ + +Show help on the ``tt`` console. + +\\quit, \\q +~~~~~~~~~~~ + +Quit the ``tt`` console. + +\\shortcuts +~~~~~~~~~~~ + +Show available keyboard shortcuts. + +\\set language {lua|sql} +~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the input language. +Possible values: + +* ``lua`` (default) +* ``sql`` + +An analog of the :ref:`tt connect ` option ``-l``/``--language``. + +\\set output FORMAT, \\x{l|t|T|y}, \\x +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the output format. +Possible ``FORMAT`` values: + +* ``yaml`` (default) -- each output item is a YAML object. Example: ``[1, 'Roxette', 1986]``. + Shorthand: ``\xy``. +* ``lua`` -- each output tuple is a separate Lua table. Example: ``{{1, "Roxette", 1986}};``. + Shorthand: ``\xl``. +* ``table`` -- the output is a table where tuples are rows. + Shorthand: ``\xt``. +* ``ttable`` -- the output is a transposed table where tuples are columns. + Shorthand: ``\xT``. + +.. note:: + + The ``\x`` command switches the output format cyclically in the order + ``yaml`` > ``lua`` > ``table`` > ``ttable``. + +The format of ``table`` and ``ttable`` output can be adjusted using the ``\set table_format``, +``\set graphics``, and ``\set table_colum_width`` commands. + +An analog of the :ref:`tt connect ` option ``-x``/``--outputformat``. + +\\set table_format +~~~~~~~~~~~~~~~~~~ + +Set the table format if the output format is ``table`` or ``ttable``. +Possible values: + +* ``default`` -- a pseudographics (ASCII) table. +* ``markdown`` -- a table in the Markdown format. +* ``jira`` -- a Jira-compatible table. + +\\set graphics {true|false}, \\x{g|G} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Whether to print pseudographics for table cells if the output format is ``table`` or ``ttable``. +Possible values: ``true`` (default) and ``false``. + +The shorthands are: + +* ``\xG`` for ``true`` +* ``\xg`` for ``false`` + +\\set table_colum_width WIDTH, \\xw WIDTH +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the maximum printed width of a table cell content. If the length exceeds this value, +it continues on the next line starting from the `+` (plus) sign. + +Shorthand: ``\xw`` diff --git a/doc/reference/tooling/tt_cli/uninstall.rst b/doc/tooling/tt_cli/uninstall.rst similarity index 100% rename from doc/reference/tooling/tt_cli/uninstall.rst rename to doc/tooling/tt_cli/uninstall.rst diff --git a/doc/reference/tooling/tt_cli/version.rst b/doc/tooling/tt_cli/version.rst similarity index 100% rename from doc/reference/tooling/tt_cli/version.rst rename to doc/tooling/tt_cli/version.rst diff --git a/locale/en/_panels_static/panels-bootstrap.5fd3999ee7762ccc51105388f4a9d115.css b/locale/en/_panels_static/panels-bootstrap.5fd3999ee7762ccc51105388f4a9d115.css new file mode 100644 index 0000000000..1b057df2f2 --- /dev/null +++ b/locale/en/_panels_static/panels-bootstrap.5fd3999ee7762ccc51105388f4a9d115.css @@ -0,0 +1 @@ +.badge{border-radius:.25rem;display:inline-block;font-size:75%;font-weight:700;line-height:1;padding:.25em .4em;text-align:center;vertical-align:baseline;white-space:nowrap}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.badge-pill{border-radius:10rem;padding-left:.6em;padding-right:.6em}.badge-primary{background-color:#007bff;color:#fff}.badge-primary[href]:focus,.badge-primary[href]:hover{background-color:#0062cc;color:#fff;text-decoration:none}.badge-secondary{background-color:#6c757d;color:#fff}.badge-secondary[href]:focus,.badge-secondary[href]:hover{background-color:#545b62;color:#fff;text-decoration:none}.badge-success{background-color:#28a745;color:#fff}.badge-success[href]:focus,.badge-success[href]:hover{background-color:#1e7e34;color:#fff;text-decoration:none}.badge-info{background-color:#17a2b8;color:#fff}.badge-info[href]:focus,.badge-info[href]:hover{background-color:#117a8b;color:#fff;text-decoration:none}.badge-warning{background-color:#ffc107;color:#212529}.badge-warning[href]:focus,.badge-warning[href]:hover{background-color:#d39e00;color:#212529;text-decoration:none}.badge-danger{background-color:#dc3545;color:#fff}.badge-danger[href]:focus,.badge-danger[href]:hover{background-color:#bd2130;color:#fff;text-decoration:none}.badge-light{background-color:#f8f9fa;color:#212529}.badge-light[href]:focus,.badge-light[href]:hover{background-color:#dae0e5;color:#212529;text-decoration:none}.badge-dark{background-color:#343a40;color:#fff}.badge-dark[href]:focus,.badge-dark[href]:hover{background-color:#1d2124;color:#fff;text-decoration:none}.border-0{border:0 !important}.border-top-0{border-top:0 !important}.border-right-0{border-right:0 !important}.border-bottom-0{border-bottom:0 !important}.border-left-0{border-left:0 !important}.p-0{padding:0 !important}.pt-0,.py-0{padding-top:0 !important}.pr-0,.px-0{padding-right:0 !important}.pb-0,.py-0{padding-bottom:0 !important}.pl-0,.px-0{padding-left:0 !important}.p-1{padding:.25rem !important}.pt-1,.py-1{padding-top:.25rem !important}.pr-1,.px-1{padding-right:.25rem !important}.pb-1,.py-1{padding-bottom:.25rem !important}.pl-1,.px-1{padding-left:.25rem !important}.p-2{padding:.5rem !important}.pt-2,.py-2{padding-top:.5rem !important}.pr-2,.px-2{padding-right:.5rem !important}.pb-2,.py-2{padding-bottom:.5rem !important}.pl-2,.px-2{padding-left:.5rem !important}.p-3{padding:1rem !important}.pt-3,.py-3{padding-top:1rem !important}.pr-3,.px-3{padding-right:1rem !important}.pb-3,.py-3{padding-bottom:1rem !important}.pl-3,.px-3{padding-left:1rem !important}.p-4{padding:1.5rem !important}.pt-4,.py-4{padding-top:1.5rem !important}.pr-4,.px-4{padding-right:1.5rem !important}.pb-4,.py-4{padding-bottom:1.5rem !important}.pl-4,.px-4{padding-left:1.5rem !important}.p-5{padding:3rem !important}.pt-5,.py-5{padding-top:3rem !important}.pr-5,.px-5{padding-right:3rem !important}.pb-5,.py-5{padding-bottom:3rem !important}.pl-5,.px-5{padding-left:3rem !important}.m-0{margin:0 !important}.mt-0,.my-0{margin-top:0 !important}.mr-0,.mx-0{margin-right:0 !important}.mb-0,.my-0{margin-bottom:0 !important}.ml-0,.mx-0{margin-left:0 !important}.m-1{margin:.25rem !important}.mt-1,.my-1{margin-top:.25rem !important}.mr-1,.mx-1{margin-right:.25rem !important}.mb-1,.my-1{margin-bottom:.25rem !important}.ml-1,.mx-1{margin-left:.25rem !important}.m-2{margin:.5rem !important}.mt-2,.my-2{margin-top:.5rem !important}.mr-2,.mx-2{margin-right:.5rem !important}.mb-2,.my-2{margin-bottom:.5rem !important}.ml-2,.mx-2{margin-left:.5rem !important}.m-3{margin:1rem !important}.mt-3,.my-3{margin-top:1rem !important}.mr-3,.mx-3{margin-right:1rem !important}.mb-3,.my-3{margin-bottom:1rem !important}.ml-3,.mx-3{margin-left:1rem !important}.m-4{margin:1.5rem !important}.mt-4,.my-4{margin-top:1.5rem !important}.mr-4,.mx-4{margin-right:1.5rem !important}.mb-4,.my-4{margin-bottom:1.5rem !important}.ml-4,.mx-4{margin-left:1.5rem !important}.m-5{margin:3rem !important}.mt-5,.my-5{margin-top:3rem !important}.mr-5,.mx-5{margin-right:3rem !important}.mb-5,.my-5{margin-bottom:3rem !important}.ml-5,.mx-5{margin-left:3rem !important}.btn{background-color:transparent;border:1px solid transparent;border-radius:.25rem;color:#212529;cursor:pointer;display:inline-block;font-size:1rem;font-weight:400;line-height:1.5;padding:.375rem .75rem;text-align:center;transition:color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;user-select:none;vertical-align:middle}.btn:hover{color:#212529;text-decoration:none}.btn:visited{color:#212529}.btn.focus,.btn:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,0.25);outline:0}.btn.disabled,.btn:disabled{opacity:.65}@media (prefers-reduced-motion: reduce){.btn{transition:none}}a.btn.disabled,fieldset:disabled a.btn{pointer-events:none}.btn-primary{background-color:#007bff;border-color:#007bff;color:#fff}.btn-primary:visited{color:#fff}.btn-primary:hover{background-color:#0069d9;border-color:#0062cc;color:#fff}.btn-primary.focus,.btn-primary:focus{background-color:#0069d9;border-color:#0062cc;box-shadow:0 0 0 .2rem rgba(0,123,255,0.5);color:#fff}.btn-primary.disabled,.btn-primary:disabled{background-color:#007bff;border-color:#007bff;color:#fff}.btn-primary.active:not(:disabled):not(.disabled),.btn-primary:not(:disabled):not(.disabled):active,.show>.btn-primary.dropdown-toggle{background-color:#0062cc;border-color:#005cbf;color:#fff}.btn-primary.active:not(:disabled):not(.disabled):focus,.btn-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,0.5)}.btn-secondary{background-color:#6c757d;border-color:#6c757d;color:#fff}.btn-secondary:visited{color:#fff}.btn-secondary:hover{background-color:#5a6268;border-color:#545b62;color:#fff}.btn-secondary.focus,.btn-secondary:focus{background-color:#5a6268;border-color:#545b62;box-shadow:0 0 0 .2rem rgba(108,117,125,0.5);color:#fff}.btn-secondary.disabled,.btn-secondary:disabled{background-color:#6c757d;border-color:#6c757d;color:#fff}.btn-secondary.active:not(:disabled):not(.disabled),.btn-secondary:not(:disabled):not(.disabled):active,.show>.btn-secondary.dropdown-toggle{background-color:#545b62;border-color:#4e555b;color:#fff}.btn-secondary.active:not(:disabled):not(.disabled):focus,.btn-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,0.5)}.btn-success{background-color:#28a745;border-color:#28a745;color:#fff}.btn-success:visited{color:#fff}.btn-success:hover{background-color:#218838;border-color:#1e7e34;color:#fff}.btn-success.focus,.btn-success:focus{background-color:#218838;border-color:#1e7e34;box-shadow:0 0 0 .2rem rgba(40,167,69,0.5);color:#fff}.btn-success.disabled,.btn-success:disabled{background-color:#28a745;border-color:#28a745;color:#fff}.btn-success.active:not(:disabled):not(.disabled),.btn-success:not(:disabled):not(.disabled):active,.show>.btn-success.dropdown-toggle{background-color:#1e7e34;border-color:#1c7430;color:#fff}.btn-success.active:not(:disabled):not(.disabled):focus,.btn-success:not(:disabled):not(.disabled):active:focus,.show>.btn-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,0.5)}.btn-info{background-color:#17a2b8;border-color:#17a2b8;color:#fff}.btn-info:visited{color:#fff}.btn-info:hover{background-color:#138496;border-color:#117a8b;color:#fff}.btn-info.focus,.btn-info:focus{background-color:#138496;border-color:#117a8b;box-shadow:0 0 0 .2rem rgba(23,162,184,0.5);color:#fff}.btn-info.disabled,.btn-info:disabled{background-color:#17a2b8;border-color:#17a2b8;color:#fff}.btn-info.active:not(:disabled):not(.disabled),.btn-info:not(:disabled):not(.disabled):active,.show>.btn-info.dropdown-toggle{background-color:#117a8b;border-color:#10707f;color:#fff}.btn-info.active:not(:disabled):not(.disabled):focus,.btn-info:not(:disabled):not(.disabled):active:focus,.show>.btn-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,0.5)}.btn-warning{background-color:#ffc107;border-color:#ffc107;color:#212529}.btn-warning:visited{color:#212529}.btn-warning:hover{background-color:#e0a800;border-color:#d39e00;color:#212529}.btn-warning.focus,.btn-warning:focus{background-color:#e0a800;border-color:#d39e00;box-shadow:0 0 0 .2rem rgba(255,193,7,0.5);color:#212529}.btn-warning.disabled,.btn-warning:disabled{background-color:#ffc107;border-color:#ffc107;color:#212529}.btn-warning.active:not(:disabled):not(.disabled),.btn-warning:not(:disabled):not(.disabled):active,.show>.btn-warning.dropdown-toggle{background-color:#d39e00;border-color:#c69500;color:#212529}.btn-warning.active:not(:disabled):not(.disabled):focus,.btn-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,0.5)}.btn-danger{background-color:#dc3545;border-color:#dc3545;color:#fff}.btn-danger:visited{color:#fff}.btn-danger:hover{background-color:#c82333;border-color:#bd2130;color:#fff}.btn-danger.focus,.btn-danger:focus{background-color:#c82333;border-color:#bd2130;box-shadow:0 0 0 .2rem rgba(220,53,69,0.5);color:#fff}.btn-danger.disabled,.btn-danger:disabled{background-color:#dc3545;border-color:#dc3545;color:#fff}.btn-danger.active:not(:disabled):not(.disabled),.btn-danger:not(:disabled):not(.disabled):active,.show>.btn-danger.dropdown-toggle{background-color:#bd2130;border-color:#b21f2d;color:#fff}.btn-danger.active:not(:disabled):not(.disabled):focus,.btn-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,0.5)}.btn-light{background-color:#f8f9fa;border-color:#f8f9fa;color:#212529}.btn-light:visited{color:#212529}.btn-light:hover{background-color:#e2e6ea;border-color:#dae0e5;color:#212529}.btn-light.focus,.btn-light:focus{background-color:#e2e6ea;border-color:#dae0e5;box-shadow:0 0 0 .2rem rgba(248,249,250,0.5);color:#212529}.btn-light.disabled,.btn-light:disabled{background-color:#f8f9fa;border-color:#f8f9fa;color:#212529}.btn-light.active:not(:disabled):not(.disabled),.btn-light:not(:disabled):not(.disabled):active,.show>.btn-light.dropdown-toggle{background-color:#dae0e5;border-color:#d3d9df;color:#212529}.btn-light.active:not(:disabled):not(.disabled):focus,.btn-light:not(:disabled):not(.disabled):active:focus,.show>.btn-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,0.5)}.btn-dark{background-color:#343a40;border-color:#343a40;color:#fff}.btn-dark:visited{color:#fff}.btn-dark:hover{background-color:#23272b;border-color:#1d2124;color:#fff}.btn-dark.focus,.btn-dark:focus{background-color:#23272b;border-color:#1d2124;box-shadow:0 0 0 .2rem rgba(52,58,64,0.5);color:#fff}.btn-dark.disabled,.btn-dark:disabled{background-color:#343a40;border-color:#343a40;color:#fff}.btn-dark.active:not(:disabled):not(.disabled),.btn-dark:not(:disabled):not(.disabled):active,.show>.btn-dark.dropdown-toggle{background-color:#1d2124;border-color:#171a1d;color:#fff}.btn-dark.active:not(:disabled):not(.disabled):focus,.btn-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,0.5)}.btn-outline-primary{border-color:#007bff;color:#007bff}.btn-outline-primary:visited{color:#007bff}.btn-outline-primary:hover{background-color:#007bff;border-color:#007bff;color:#fff}.btn-outline-primary.focus,.btn-outline-primary:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,0.5)}.btn-outline-primary.disabled,.btn-outline-primary:disabled{background-color:transparent;color:#007bff}.btn-outline-primary.active:not(:disabled):not(.disabled),.btn-outline-primary:not(:disabled):not(.disabled):active,.show>.btn-outline-primary.dropdown-toggle{background-color:#007bff;border-color:#007bff;color:#fff}.btn-outline-primary.active:not(:disabled):not(.disabled):focus,.btn-outline-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,0.5)}.btn-outline-secondary{border-color:#6c757d;color:#6c757d}.btn-outline-secondary:visited{color:#6c757d}.btn-outline-secondary:hover{background-color:#6c757d;border-color:#6c757d;color:#fff}.btn-outline-secondary.focus,.btn-outline-secondary:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,0.5)}.btn-outline-secondary.disabled,.btn-outline-secondary:disabled{background-color:transparent;color:#6c757d}.btn-outline-secondary.active:not(:disabled):not(.disabled),.btn-outline-secondary:not(:disabled):not(.disabled):active,.show>.btn-outline-secondary.dropdown-toggle{background-color:#6c757d;border-color:#6c757d;color:#fff}.btn-outline-secondary.active:not(:disabled):not(.disabled):focus,.btn-outline-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,0.5)}.btn-outline-success{border-color:#28a745;color:#28a745}.btn-outline-success:visited{color:#28a745}.btn-outline-success:hover{background-color:#28a745;border-color:#28a745;color:#fff}.btn-outline-success.focus,.btn-outline-success:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,0.5)}.btn-outline-success.disabled,.btn-outline-success:disabled{background-color:transparent;color:#28a745}.btn-outline-success.active:not(:disabled):not(.disabled),.btn-outline-success:not(:disabled):not(.disabled):active,.show>.btn-outline-success.dropdown-toggle{background-color:#28a745;border-color:#28a745;color:#fff}.btn-outline-success.active:not(:disabled):not(.disabled):focus,.btn-outline-success:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,0.5)}.btn-outline-info{border-color:#17a2b8;color:#17a2b8}.btn-outline-info:visited{color:#17a2b8}.btn-outline-info:hover{background-color:#17a2b8;border-color:#17a2b8;color:#fff}.btn-outline-info.focus,.btn-outline-info:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,0.5)}.btn-outline-info.disabled,.btn-outline-info:disabled{background-color:transparent;color:#17a2b8}.btn-outline-info.active:not(:disabled):not(.disabled),.btn-outline-info:not(:disabled):not(.disabled):active,.show>.btn-outline-info.dropdown-toggle{background-color:#17a2b8;border-color:#17a2b8;color:#fff}.btn-outline-info.active:not(:disabled):not(.disabled):focus,.btn-outline-info:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,0.5)}.btn-outline-warning{border-color:#ffc107;color:#ffc107}.btn-outline-warning:visited{color:#ffc107}.btn-outline-warning:hover{background-color:#ffc107;border-color:#ffc107;color:#212529}.btn-outline-warning.focus,.btn-outline-warning:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,0.5)}.btn-outline-warning.disabled,.btn-outline-warning:disabled{background-color:transparent;color:#ffc107}.btn-outline-warning.active:not(:disabled):not(.disabled),.btn-outline-warning:not(:disabled):not(.disabled):active,.show>.btn-outline-warning.dropdown-toggle{background-color:#ffc107;border-color:#ffc107;color:#212529}.btn-outline-warning.active:not(:disabled):not(.disabled):focus,.btn-outline-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,0.5)}.btn-outline-danger{border-color:#dc3545;color:#dc3545}.btn-outline-danger:visited{color:#dc3545}.btn-outline-danger:hover{background-color:#dc3545;border-color:#dc3545;color:#fff}.btn-outline-danger.focus,.btn-outline-danger:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,0.5)}.btn-outline-danger.disabled,.btn-outline-danger:disabled{background-color:transparent;color:#dc3545}.btn-outline-danger.active:not(:disabled):not(.disabled),.btn-outline-danger:not(:disabled):not(.disabled):active,.show>.btn-outline-danger.dropdown-toggle{background-color:#dc3545;border-color:#dc3545;color:#fff}.btn-outline-danger.active:not(:disabled):not(.disabled):focus,.btn-outline-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,0.5)}.btn-outline-light{border-color:#f8f9fa;color:#f8f9fa}.btn-outline-light:visited{color:#f8f9fa}.btn-outline-light:hover{background-color:#f8f9fa;border-color:#f8f9fa;color:#212529}.btn-outline-light.focus,.btn-outline-light:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,0.5)}.btn-outline-light.disabled,.btn-outline-light:disabled{background-color:transparent;color:#f8f9fa}.btn-outline-light.active:not(:disabled):not(.disabled),.btn-outline-light:not(:disabled):not(.disabled):active,.show>.btn-outline-light.dropdown-toggle{background-color:#f8f9fa;border-color:#f8f9fa;color:#212529}.btn-outline-light.active:not(:disabled):not(.disabled):focus,.btn-outline-light:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,0.5)}.btn-outline-dark{border-color:#343a40;color:#343a40}.btn-outline-dark:visited{color:#343a40}.btn-outline-dark:hover{background-color:#343a40;border-color:#343a40;color:#fff}.btn-outline-dark.focus,.btn-outline-dark:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,0.5)}.btn-outline-dark.disabled,.btn-outline-dark:disabled{background-color:transparent;color:#343a40}.btn-outline-dark.active:not(:disabled):not(.disabled),.btn-outline-dark:not(:disabled):not(.disabled):active,.show>.btn-outline-dark.dropdown-toggle{background-color:#343a40;border-color:#343a40;color:#fff}.btn-outline-dark.active:not(:disabled):not(.disabled):focus,.btn-outline-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,0.5)}.btn-link{color:#007bff;font-weight:400;text-decoration:none}.btn-link:hover{color:#0056b3;text-decoration:underline}.btn-link.focus,.btn-link:focus{box-shadow:none;text-decoration:underline}.btn-link.disabled,.btn-link:disabled{color:#6c757d;pointer-events:none}.btn-group-lg>.btn,.btn-lg{border-radius:.3rem;font-size:1.25rem;line-height:1.5;padding:.5rem 1rem}.btn-group-sm>.btn,.btn-sm{border-radius:.2rem;font-size:.875rem;line-height:1.5;padding:.25rem .5rem}.btn-block{display:block;width:100%}.btn-block+.btn-block{margin-top:.5rem}input.btn-block[type=button],input.btn-block[type=reset],input.btn-block[type=submit]{width:100%}.stretched-link::after{background-color:rgba(0,0,0,0);bottom:0;content:'';left:0;pointer-events:auto;position:absolute;right:0;top:0;z-index:1}.text-wrap{white-space:normal !important}.card{background-clip:border-box;background-color:#fff;border:1px solid rgba(0,0,0,0.125);border-radius:.25rem;display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;position:relative;word-wrap:break-word}.card>hr{margin-left:0;margin-right:0}.card>.list-group:first-child .list-group-item:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card>.list-group:last-child .list-group-item:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-body{-ms-flex:1 1 auto;flex:1 1 auto;min-height:1px;padding:1.25rem}.card-title{margin-bottom:.75rem}.card-subtitle{margin-bottom:0;margin-top:-.375rem}.card-text:last-child{margin-bottom:0}.card-link:hover{text-decoration:none}.card-link+.card-link{margin-left:1.25rem}.card-header{background-color:rgba(0,0,0,0.03);border-bottom:1px solid rgba(0,0,0,0.125);margin-bottom:0;padding:.75rem 1.25rem}.card-header:first-child{border-radius:calc(.25rem - 1px) calc(.25rem - 1px) 0 0}.card-header+.list-group .list-group-item:first-child{border-top:0}.card-footer{background-color:rgba(0,0,0,0.03);border-top:1px solid rgba(0,0,0,0.125);padding:.75rem 1.25rem}.card-footer:last-child{border-radius:0 0 calc(.25rem - 1px) calc(.25rem - 1px)}.card-header-tabs{border-bottom:0;margin-bottom:-.75rem;margin-left:-.625rem;margin-right:-.625rem}.card-header-pills{margin-left:-.625rem;margin-right:-.625rem}.card-img-overlay{bottom:0;left:0;padding:1.25rem;position:absolute;right:0;top:0}.card-img,.card-img-bottom,.card-img-top{-ms-flex-negative:0;flex-shrink:0;width:100%}.card-img,.card-img-top{border-top-left-radius:calc(.25rem - 1px);border-top-right-radius:calc(.25rem - 1px)}.card-img,.card-img-bottom{border-bottom-left-radius:calc(.25rem - 1px);border-bottom-right-radius:calc(.25rem - 1px)}.w-100{width:100% !important}.shadow{box-shadow:0 0.5rem 1rem rgba(0,0,0,0.15) !important}.bg-primary{background-color:#007bff !important}button.bg-primary:focus,button.bg-primary:hover{background-color:#0062cc !important}a.bg-primary:focus,a.bg-primary:hover{background-color:#0062cc !important}a.text-primary:focus,a.text-primary:hover{color:#121416 !important}.bg-secondary{background-color:#6c757d !important}button.bg-secondary:focus,button.bg-secondary:hover{background-color:#545b62 !important}a.bg-secondary:focus,a.bg-secondary:hover{background-color:#545b62 !important}a.text-secondary:focus,a.text-secondary:hover{color:#121416 !important}.bg-success{background-color:#28a745 !important}button.bg-success:focus,button.bg-success:hover{background-color:#1e7e34 !important}a.bg-success:focus,a.bg-success:hover{background-color:#1e7e34 !important}a.text-success:focus,a.text-success:hover{color:#121416 !important}.bg-info{background-color:#17a2b8 !important}button.bg-info:focus,button.bg-info:hover{background-color:#117a8b !important}a.bg-info:focus,a.bg-info:hover{background-color:#117a8b !important}a.text-info:focus,a.text-info:hover{color:#121416 !important}.bg-warning{background-color:#ffc107 !important}button.bg-warning:focus,button.bg-warning:hover{background-color:#d39e00 !important}a.bg-warning:focus,a.bg-warning:hover{background-color:#d39e00 !important}a.text-warning:focus,a.text-warning:hover{color:#121416 !important}.bg-danger{background-color:#dc3545 !important}button.bg-danger:focus,button.bg-danger:hover{background-color:#bd2130 !important}a.bg-danger:focus,a.bg-danger:hover{background-color:#bd2130 !important}a.text-danger:focus,a.text-danger:hover{color:#121416 !important}.bg-light{background-color:#f8f9fa !important}button.bg-light:focus,button.bg-light:hover{background-color:#dae0e5 !important}a.bg-light:focus,a.bg-light:hover{background-color:#dae0e5 !important}a.text-light:focus,a.text-light:hover{color:#121416 !important}.bg-dark{background-color:#343a40 !important}button.bg-dark:focus,button.bg-dark:hover{background-color:#1d2124 !important}a.bg-dark:focus,a.bg-dark:hover{background-color:#1d2124 !important}a.text-dark:focus,a.text-dark:hover{color:#121416 !important}.bg-white{background-color:#fff !important}button.bg-white:focus,button.bg-white:hover{background-color:#e6e6e6 !important}a.bg-white:focus,a.bg-white:hover{background-color:#e6e6e6 !important}a.text-white:focus,a.text-white:hover{color:#121416 !important}.text-primary{color:#007bff !important}.text-secondary{color:#6c757d !important}.text-success{color:#28a745 !important}.text-info{color:#17a2b8 !important}.text-warning{color:#ffc107 !important}.text-danger{color:#dc3545 !important}.text-light{color:#f8f9fa !important}.text-dark{color:#343a40 !important}.text-white{color:#fff !important}.text-body{color:#212529 !important}.text-muted{color:#6c757d !important}.text-black-50{color:rgba(0,0,0,0.5) !important}.text-white-50{color:rgba(255,255,255,0.5) !important}.bg-transparent{background-color:transparent !important}.text-justify{text-align:justify !important}.text-left{text-align:left !important}.text-right{text-align:right !important}.text-center{text-align:center !important}.font-weight-light{font-weight:300 !important}.font-weight-lighter{font-weight:lighter !important}.font-weight-normal{font-weight:400 !important}.font-weight-bold{font-weight:700 !important}.font-weight-bolder{font-weight:bolder !important}.font-italic{font-style:italic !important}.container{margin-left:auto;margin-right:auto;padding-left:15px;padding-right:15px;width:100%}@media (min-width: 576px){.container{max-width:540px}}@media (min-width: 768px){.container{max-width:720px}}@media (min-width: 992px){.container{max-width:960px}}@media (min-width: 1200px){.container{max-width:1140px}}.container-fluid,.container-lg,.container-md,.container-sm,.container-xl{margin-left:auto;margin-right:auto;padding-left:15px;padding-right:15px;width:100%}@media (min-width: 576px){.container,.container-sm{max-width:540px}}@media (min-width: 768px){.container,.container-md,.container-sm{max-width:720px}}@media (min-width: 992px){.container,.container-lg,.container-md,.container-sm{max-width:960px}}@media (min-width: 1200px){.container,.container-lg,.container-md,.container-sm,.container-xl{max-width:1140px}}.row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-left:-15px;margin-right:-15px}.col-lg,.col-lg-1,.col-lg-10,.col-lg-11,.col-lg-12,.col-lg-2,.col-lg-3,.col-lg-4,.col-lg-5,.col-lg-6,.col-lg-7,.col-lg-8,.col-lg-9,.col-lg-auto,.col-md,.col-md-1,.col-md-10,.col-md-11,.col-md-12,.col-md-2,.col-md-3,.col-md-4,.col-md-5,.col-md-6,.col-md-7,.col-md-8,.col-md-9,.col-md-auto,.col-sm,.col-sm-1,.col-sm-10,.col-sm-11,.col-sm-12,.col-sm-2,.col-sm-3,.col-sm-4,.col-sm-5,.col-sm-6,.col-sm-7,.col-sm-8,.col-sm-9,.col-sm-auto,.col-xl,.col-xl-1,.col-xl-10,.col-xl-11,.col-xl-12,.col-xl-2,.col-xl-3,.col-xl-4,.col-xl-5,.col-xl-6,.col-xl-7,.col-xl-8,.col-xl-9,.col-xl-auto{padding-left:15px;padding-right:15px;position:relative;width:100%}@media (min-width: 576px){.col-sm{flex-basis:0;flex-grow:1;-ms-flex-positive:1;-ms-flex-preferred-size:0;max-width:100%}.col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;max-width:100%;width:auto}.col-sm-1{-ms-flex:0 0 8.33333%;flex:0 0 8.33333%;max-width:8.33333%}.col-sm-2{-ms-flex:0 0 16.66667%;flex:0 0 16.66667%;max-width:16.66667%}.col-sm-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-sm-4{-ms-flex:0 0 33.33333%;flex:0 0 33.33333%;max-width:33.33333%}.col-sm-5{-ms-flex:0 0 41.66667%;flex:0 0 41.66667%;max-width:41.66667%}.col-sm-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-sm-7{-ms-flex:0 0 58.33333%;flex:0 0 58.33333%;max-width:58.33333%}.col-sm-8{-ms-flex:0 0 66.66667%;flex:0 0 66.66667%;max-width:66.66667%}.col-sm-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-sm-10{-ms-flex:0 0 83.33333%;flex:0 0 83.33333%;max-width:83.33333%}.col-sm-11{-ms-flex:0 0 91.66667%;flex:0 0 91.66667%;max-width:91.66667%}.col-sm-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}}@media (min-width: 768px){.col-md{flex-basis:0;flex-grow:1;-ms-flex-positive:1;-ms-flex-preferred-size:0;max-width:100%}.col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;max-width:100%;width:auto}.col-md-1{-ms-flex:0 0 8.33333%;flex:0 0 8.33333%;max-width:8.33333%}.col-md-2{-ms-flex:0 0 16.66667%;flex:0 0 16.66667%;max-width:16.66667%}.col-md-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-md-4{-ms-flex:0 0 33.33333%;flex:0 0 33.33333%;max-width:33.33333%}.col-md-5{-ms-flex:0 0 41.66667%;flex:0 0 41.66667%;max-width:41.66667%}.col-md-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-md-7{-ms-flex:0 0 58.33333%;flex:0 0 58.33333%;max-width:58.33333%}.col-md-8{-ms-flex:0 0 66.66667%;flex:0 0 66.66667%;max-width:66.66667%}.col-md-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-md-10{-ms-flex:0 0 83.33333%;flex:0 0 83.33333%;max-width:83.33333%}.col-md-11{-ms-flex:0 0 91.66667%;flex:0 0 91.66667%;max-width:91.66667%}.col-md-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}}@media (min-width: 992px){.col-lg{flex-basis:0;flex-grow:1;-ms-flex-positive:1;-ms-flex-preferred-size:0;max-width:100%}.col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;max-width:100%;width:auto}.col-lg-1{-ms-flex:0 0 8.33333%;flex:0 0 8.33333%;max-width:8.33333%}.col-lg-2{-ms-flex:0 0 16.66667%;flex:0 0 16.66667%;max-width:16.66667%}.col-lg-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-lg-4{-ms-flex:0 0 33.33333%;flex:0 0 33.33333%;max-width:33.33333%}.col-lg-5{-ms-flex:0 0 41.66667%;flex:0 0 41.66667%;max-width:41.66667%}.col-lg-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-lg-7{-ms-flex:0 0 58.33333%;flex:0 0 58.33333%;max-width:58.33333%}.col-lg-8{-ms-flex:0 0 66.66667%;flex:0 0 66.66667%;max-width:66.66667%}.col-lg-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-lg-10{-ms-flex:0 0 83.33333%;flex:0 0 83.33333%;max-width:83.33333%}.col-lg-11{-ms-flex:0 0 91.66667%;flex:0 0 91.66667%;max-width:91.66667%}.col-lg-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}}@media (min-width: 1200px){.col-xl{flex-basis:0;flex-grow:1;-ms-flex-positive:1;-ms-flex-preferred-size:0;max-width:100%}.col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;max-width:100%;width:auto}.col-xl-1{-ms-flex:0 0 8.33333%;flex:0 0 8.33333%;max-width:8.33333%}.col-xl-2{-ms-flex:0 0 16.66667%;flex:0 0 16.66667%;max-width:16.66667%}.col-xl-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-xl-4{-ms-flex:0 0 33.33333%;flex:0 0 33.33333%;max-width:33.33333%}.col-xl-5{-ms-flex:0 0 41.66667%;flex:0 0 41.66667%;max-width:41.66667%}.col-xl-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-xl-7{-ms-flex:0 0 58.33333%;flex:0 0 58.33333%;max-width:58.33333%}.col-xl-8{-ms-flex:0 0 66.66667%;flex:0 0 66.66667%;max-width:66.66667%}.col-xl-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-xl-10{-ms-flex:0 0 83.33333%;flex:0 0 83.33333%;max-width:83.33333%}.col-xl-11{-ms-flex:0 0 91.66667%;flex:0 0 91.66667%;max-width:91.66667%}.col-xl-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}}.d-flex{display:-ms-flexbox !important;display:flex !important}.sphinx-bs,.sphinx-bs *{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sphinx-bs p{margin-top:0} diff --git a/locale/en/_panels_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css b/locale/en/_panels_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css new file mode 100644 index 0000000000..fc14abc85d --- /dev/null +++ b/locale/en/_panels_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css @@ -0,0 +1 @@ +details.dropdown .summary-title{padding-right:3em !important;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;user-select:none}details.dropdown:hover{cursor:pointer}details.dropdown .summary-content{cursor:default}details.dropdown summary{list-style:none;padding:1em}details.dropdown summary .octicon.no-title{vertical-align:middle}details.dropdown[open] summary .octicon.no-title{visibility:hidden}details.dropdown summary::-webkit-details-marker{display:none}details.dropdown summary:focus{outline:none}details.dropdown summary:hover .summary-up svg,details.dropdown summary:hover .summary-down svg{opacity:1}details.dropdown .summary-up svg,details.dropdown .summary-down svg{display:block;opacity:.6}details.dropdown .summary-up,details.dropdown .summary-down{pointer-events:none;position:absolute;right:1em;top:.75em}details.dropdown[open] .summary-down{visibility:hidden}details.dropdown:not([open]) .summary-up{visibility:hidden}details.dropdown.fade-in[open] summary~*{-moz-animation:panels-fade-in .5s ease-in-out;-webkit-animation:panels-fade-in .5s ease-in-out;animation:panels-fade-in .5s ease-in-out}details.dropdown.fade-in-slide-down[open] summary~*{-moz-animation:panels-fade-in .5s ease-in-out, panels-slide-down .5s ease-in-out;-webkit-animation:panels-fade-in .5s ease-in-out, panels-slide-down .5s ease-in-out;animation:panels-fade-in .5s ease-in-out, panels-slide-down .5s ease-in-out}@keyframes panels-fade-in{0%{opacity:0}100%{opacity:1}}@keyframes panels-slide-down{0%{transform:translate(0, -10px)}100%{transform:translate(0, 0)}}.octicon{display:inline-block;fill:currentColor;vertical-align:text-top}.tabbed-content{box-shadow:0 -.0625rem var(--tabs-color-overline),0 .0625rem var(--tabs-color-underline);display:none;order:99;padding-bottom:.75rem;padding-top:.75rem;width:100%}.tabbed-content>:first-child{margin-top:0 !important}.tabbed-content>:last-child{margin-bottom:0 !important}.tabbed-content>.tabbed-set{margin:0}.tabbed-set{border-radius:.125rem;display:flex;flex-wrap:wrap;margin:1em 0;position:relative}.tabbed-set>input{opacity:0;position:absolute}.tabbed-set>input:checked+label{border-color:var(--tabs-color-label-active);color:var(--tabs-color-label-active)}.tabbed-set>input:checked+label+.tabbed-content{display:block}.tabbed-set>input:focus+label{outline-style:auto}.tabbed-set>input:not(.focus-visible)+label{outline:none;-webkit-tap-highlight-color:transparent}.tabbed-set>label{border-bottom:.125rem solid transparent;color:var(--tabs-color-label-inactive);cursor:pointer;font-size:var(--tabs-size-label);font-weight:700;padding:1em 1.25em .5em;transition:color 250ms;width:auto;z-index:1}html .tabbed-set>label:hover{color:var(--tabs-color-label-active)} diff --git a/locale/en/_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css b/locale/en/_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css new file mode 100644 index 0000000000..adc6166222 --- /dev/null +++ b/locale/en/_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css @@ -0,0 +1,7 @@ +:root { +--tabs-color-label-active: hsla(231, 99%, 66%, 1); +--tabs-color-label-inactive: rgba(178, 206, 245, 0.62); +--tabs-color-overline: rgb(207, 236, 238); +--tabs-color-underline: rgb(207, 236, 238); +--tabs-size-label: 1rem; +} \ No newline at end of file diff --git a/locale/en/admin/access_control.pot b/locale/en/admin/access_control.pot new file mode 100644 index 0000000000..c346ef0024 --- /dev/null +++ b/locale/en/admin/access_control.pot @@ -0,0 +1,431 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/access_control.rst:5 +msgid "Access control" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:7 +msgid "This section explains how Tarantool makes it possible for administrators to prevent unauthorized access to the database and to certain functions." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:10 +msgid "Briefly:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:12 +msgid "There is a method to guarantee with password checks that users really are who they say they are (“authentication”)." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:15 +msgid "There is a :ref:`_user ` system space, where usernames and password-hashes are stored." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:18 +msgid "There are functions for saying that certain users are allowed to do certain things (“privileges”)." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:21 +msgid "There is a :ref:`_priv ` system space, where privileges are stored. Whenever a user tries to do an operation, there is a check whether the user has the privilege to do the operation (“access control”)." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:25 +msgid "Details follow." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:31 +msgid "Users" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:33 +msgid "There is a **current user** for any program working with Tarantool, local or remote. If a remote connection is using a :ref:`binary port `, the current user, by default, is '**guest**'. If the connection is using an :ref:`admin-console port `, the current user is '**admin**'. When executing a :ref:`Lua initialization script `, the current user is also ‘**admin**’." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:42 +msgid "The current user name can be found with :doc:`/reference/reference_lua/box_session/user`." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:45 +msgid "The current user can be changed:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:47 +msgid "For a binary port connection -- with the :ref:`AUTH protocol command `, supported by most clients;" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:51 +msgid "For an admin-console connection and in a Lua initialization script -- with :doc:`/reference/reference_lua/box_session/su`;" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:54 +msgid "For a binary-port connection invoking a stored function with the CALL command -- if the :doc:`SETUID ` property is enabled for the function, Tarantool temporarily replaces the current user with the function’s creator, with all the creator's privileges, during function execution." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:64 +msgid "Passwords" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:66 +msgid "Each user (except 'guest') may have a **password**. The password is any alphanumeric string." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:69 +msgid "Tarantool passwords are stored in the :ref:`_user ` system space with a `cryptographic hash function `_ so that, if the password is ‘x’, the stored hash-password is a long string like ‘lL3OvhkIPOKh+Vn9Avlkx69M/Ck=‘. Tarantool supports two protocols for authenticating users:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:76 +msgid "`CHAP `_ with ``SHA-1`` hashing" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:78 +msgid "In this case, password hashes are stored in the ``_user`` space `unsalted `_. If an attacker gains access to the database, they may crack a password using, for example, a `rainbow table `_." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:81 +msgid "`PAP `_ with ``SHA256`` hashing (Enterprise Edition)" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:83 +msgid "For PAP, a password is salted with a user-unique salt before saving it in the ``_user`` space. This keeps the database protected from cracking using a rainbow table. Note that PAP sends a password as plain text, so you need to configure SSL/TLS for a connection." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:87 +msgid "There are two functions for managing passwords in Tarantool:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:89 +msgid ":doc:`/reference/reference_lua/box_schema/user_passwd` allows you to change a user's password." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:91 +msgid ":doc:`/reference/reference_lua/box_schema/user_password` returns a hash of a user's password." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:93 +msgid "Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`Access control ` section." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:101 +msgid "Owners and privileges" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:103 +msgid "Tarantool has one database. It may be called \"box.schema\" or \"universe\". The database contains database objects, including spaces, indexes, users, roles, sequences, and functions." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:107 +msgid "The **owner** of a database object is the user who created it. The owner of the database itself, and the owner of objects that are created initially (the system spaces and the default users) is '**admin**'." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:112 +msgid "Owners automatically have **privileges** for what they create. They can share these privileges with other users or with roles, using :doc:`/reference/reference_lua/box_schema/user_grant` requests. The following privileges can be granted:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:117 +msgid "'read', e.g. allow select from a space" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:118 +msgid "'write', e.g. allow update on a space" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:119 +msgid "'execute', e.g. allow call of a function, or (less commonly) allow use of a role" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:120 +msgid "'create', e.g. allow :doc:`box.schema.space.create ` (access to certain system spaces is also necessary)" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:123 +msgid "'alter', e.g. allow :doc:`box.space.x.index.y:alter ` (access to certain system spaces is also necessary)" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:126 +msgid "'drop', e.g. allow :doc:`box.sequence.x:drop ` (access to certain system spaces is also necessary)" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:129 +msgid "'usage', e.g. whether any action is allowable regardless of other privileges (sometimes revoking 'usage' is a convenient way to block a user temporarily without dropping the user)" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:132 +msgid "'session', e.g. whether the user can 'connect'." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:134 +msgid "To **create** objects, users need the 'create' privilege and at least 'read' and 'write' privileges on the system space with a similar name (for example, on the :ref:`_space ` if the user needs to create spaces)." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:139 +msgid "To **access** objects, users need an appropriate privilege on the object (for example, the 'execute' privilege on function F if the users need to execute function F). See below some :ref:`examples for granting specific privileges ` that a grantor -- that is, 'admin' or the object creator -- can make." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:145 +msgid "To drop an object, a user must be an 'admin' or have the 'super' role. Some objects may also be dropped by their creators. As the owner of the entire database, any 'admin' can drop any object, including other users." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:150 +msgid "To grant privileges to a user, the object owner says :doc:`/reference/reference_lua/box_schema/user_grant`. To revoke privileges from a user, the object owner says :doc:`/reference/reference_lua/box_schema/user_revoke`. In either case, there are up to five parameters:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:156 +msgid "(user-name, privilege, object-type [, object-name [, options]])" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:160 +msgid "``user-name`` is the user (or role) that will receive or lose the privilege;" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:161 +msgid "``privilege`` is any of 'read', 'write', 'execute', 'create', 'alter', 'drop', 'usage', or 'session' (or a comma-separated list);" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:163 +msgid "``object-type`` is any of 'space', 'index', 'sequence', 'function', 'user', 'role', or 'universe';" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:165 +msgid "``object-name`` is what the privilege is for (omitted if ``object-type`` is 'universe') (may be omitted or ``nil`` if the intent is to grant for all objects of the same type);" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:168 +msgid "``options`` is a list inside braces, for example ``{if_not_exists=true|false}`` (usually omitted because the default is acceptable)." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:171 +msgid "All updates of user privileges are reflected immediately in the existing sessions and objects, e.g. functions." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:174 +msgid "**Example for granting many privileges at once**" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:176 +msgid "In this example an 'admin' user grants many privileges on many objects to user 'U', using a single request." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:179 +msgid "box.schema.user.grant('U','read,write,execute,create,drop','universe')" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:185 +msgid "**Examples for granting privileges for specific operations**" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:187 +msgid "In these examples an administrator grants strictly the minimal privileges necessary for particular operations, to user 'U'." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:191 +msgid "-- So that 'U' can create spaces:\n" +" box.schema.user.grant('U','create','space')\n" +" box.schema.user.grant('U','write', 'space', '_schema')\n" +" box.schema.user.grant('U','write', 'space', '_space')\n" +"-- So that 'U' can create indexes on space T\n" +" box.schema.user.grant('U','create,read','space','T')\n" +" box.schema.user.grant('U','read,write','space','_space_sequence')\n" +" box.schema.user.grant('U','write', 'space', '_index')\n" +"-- So that 'U' can alter indexes on space T (assuming 'U' did not create the index)\n" +" box.schema.user.grant('U','alter','space','T')\n" +" box.schema.user.grant('U','read','space','_space')\n" +" box.schema.user.grant('U','read','space','_index')\n" +" box.schema.user.grant('U','read','space','_space_sequence')\n" +" box.schema.user.grant('U','write','space','_index')\n" +"-- So that 'U' can alter indexes on space T (assuming 'U' created the index)\n" +" box.schema.user.grant('U','read','space','_space_sequence')\n" +" box.schema.user.grant('U','read,write','space','_index')\n" +"-- So that 'U' can create users:\n" +" box.schema.user.grant('U','create','user')\n" +" box.schema.user.grant('U', 'read,write', 'space', '_user')\n" +" box.schema.user.grant('U', 'write', 'space', '_priv')\n" +"-- So that 'U' can create roles:\n" +" box.schema.user.grant('U','create','role')\n" +" box.schema.user.grant('U', 'read,write', 'space', '_user')\n" +" box.schema.user.grant('U', 'write', 'space', '_priv')\n" +"-- So that 'U' can create sequence generators:\n" +" box.schema.user.grant('U','create','sequence')\n" +" box.schema.user.grant('U', 'read,write', 'space', '_sequence')\n" +"-- So that 'U' can create functions:\n" +" box.schema.user.grant('U','create','function')\n" +" box.schema.user.grant('U','read,write','space','_func')\n" +"-- So that 'U' can create any object of any type\n" +" box.schema.user.grant('U','read,write,create','universe')\n" +"-- So that 'U' can grant access on objects that 'U' created\n" +" box.schema.user.grant('U','write','space','_priv')\n" +"-- So that 'U' can select or get from a space named 'T'\n" +" box.schema.user.grant('U','read','space','T')\n" +"-- So that 'U' can update or insert or delete or truncate a space named 'T'\n" +" box.schema.user.grant('U','write','space','T')\n" +"-- So that 'U' can execute a function named 'F'\n" +" box.schema.user.grant('U','execute','function','F')\n" +"-- So that 'U' can use the \"S:next()\" function with a sequence named S\n" +" box.schema.user.grant('U','read,write','sequence','S')\n" +"-- So that 'U' can use the \"S:set()\" or \"S:reset() function with a sequence named S\n" +" box.schema.user.grant('U','write','sequence','S')\n" +"-- So that 'U' can drop a sequence (assuming 'U' did not create it)\n" +" box.schema.user.grant('U','drop','sequence')\n" +" box.schema.user.grant('U','write','space','_sequence_data')\n" +" box.schema.user.grant('U','write','space','_sequence')\n" +"-- So that 'U' can drop a function (assuming 'U' did not create it)\n" +" box.schema.user.grant('U','drop','function')\n" +" box.schema.user.grant('U','write','space','_func')\n" +"-- So that 'U' can drop a space that has some associated objects\n" +" box.schema.user.grant('U','create,drop','space')\n" +" box.schema.user.grant('U','write','space','_schema')\n" +" box.schema.user.grant('U','write','space','_space')\n" +" box.schema.user.grant('U','write','space','_space_sequence')\n" +" box.schema.user.grant('U','read','space','_trigger')\n" +" box.schema.user.grant('U','read','space','_fk_constraint')\n" +" box.schema.user.grant('U','read','space','_ck_constraint')\n" +" box.schema.user.grant('U','read','space','_func_index')\n" +"-- So that 'U' can drop any space (ignore if the privilege exists already)\n" +" box.schema.user.grant('U','drop','space',nil,{if_not_exists=true})" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:257 +msgid "**Example for creating users and objects then granting privileges**" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:259 +msgid "Here a Lua function is created that will be executed under the user ID of its creator, even if called by another user." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:262 +msgid "First, the two spaces ('u' and 'i') are created, and a no-password user ('internal') is granted full access to them. Then a ('read_and_modify') is defined and the no-password user becomes this function's creator. Finally, another user ('public_user') is granted access to execute Lua functions created by the no-password user." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:267 +msgid "box.schema.space.create('u')\n" +"box.schema.space.create('i')\n" +"box.space.u:create_index('pk')\n" +"box.space.i:create_index('pk')\n" +"\n" +"box.schema.user.create('internal')\n" +"\n" +"box.schema.user.grant('internal', 'read,write', 'space', 'u')\n" +"box.schema.user.grant('internal', 'read,write', 'space', 'i')\n" +"box.schema.user.grant('internal', 'create', 'universe')\n" +"box.schema.user.grant('internal', 'read,write', 'space', '_func')\n" +"\n" +"function read_and_modify(key)\n" +" local u = box.space.u\n" +" local i = box.space.i\n" +" local fiber = require('fiber')\n" +" local t = u:get{key}\n" +" if t ~= nil then\n" +" u:put{key, box.session.uid()}\n" +" i:put{key, fiber.time()}\n" +" end\n" +"end\n" +"\n" +"box.session.su('internal')\n" +"box.schema.func.create('read_and_modify', {setuid= true})\n" +"box.session.su('admin')\n" +"box.schema.user.create('public_user', {password = 'secret'})\n" +"box.schema.user.grant('public_user', 'execute', 'function', 'read_and_modify')" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:302 +msgid "Roles" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:304 +msgid "A **role** is a container for privileges which can be granted to regular users. Instead of granting or revoking individual privileges, you can put all the privileges in a role and then grant or revoke the role." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:308 +msgid "Role information is stored in the :ref:`_user ` space, but the third field in the tuple -- the type field -- is ‘role’ rather than ‘user’." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:311 +msgid "An important feature in role management is that roles can be **nested**. For example, role R1 can be granted a privileged \"role R2\", so users with the role R1 will subsequently get all privileges from both roles R1 and R2. In other words, a user gets all the privileges granted to a user’s roles, directly or indirectly." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:317 +msgid "There are actually two ways to grant or revoke a role: :samp:`box.schema.user.grant-or-revoke({user-name-or-role-name},'execute', 'role',{role-name}...)` or :samp:`box.schema.user.grant-or-revoke({user-name-or-role-name},{role-name}...)`. The second way is preferable." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:323 +msgid "The 'usage' and 'session' privileges cannot be granted to roles." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:325 +msgid "**Example**" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:327 +msgid "-- This example will work for a user with many privileges, such as 'admin'\n" +"-- or a user with the pre-defined 'super' role\n" +"-- Create space T with a primary index\n" +"box.schema.space.create('T')\n" +"box.space.T:create_index('primary', {})\n" +"-- Create the user U1 so that later the current user can be changed to U1\n" +"box.schema.user.create('U1')\n" +"-- Create two roles, R1 and R2\n" +"box.schema.role.create('R1')\n" +"box.schema.role.create('R2')\n" +"-- Grant role R2 to role R1 and role R1 to user U1 (order doesn't matter)\n" +"-- There are two ways to grant a role; here the shorter way is used\n" +"box.schema.role.grant('R1', 'R2')\n" +"box.schema.user.grant('U1', 'R1')\n" +"-- Grant read/write privileges for space T to role R2\n" +"-- (but not to role R1, and not to user U1)\n" +"box.schema.role.grant('R2', 'read,write', 'space', 'T')\n" +"-- Change the current user to user U1\n" +"box.session.su('U1')\n" +"-- An insertion to space T will now succeed because (due to nested roles)\n" +"-- user U1 has write privilege on space T\n" +"box.space.T:insert{1}" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:352 +msgid "More details are to be found in :doc:`/reference/reference_lua/box_schema/user_grant` and :doc:`/reference/reference_lua/box_schema/role_grant` in the built-in modules reference." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:361 +msgid "Sessions and security" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:363 +msgid "A **session** is the state of a connection to Tarantool. It contains:" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:365 +msgid "An integer ID identifying the connection," +msgstr "" + +#: ../../doc/book/admin/access_control.rst:366 +msgid "the :ref:`current user ` associated with the connection," +msgstr "" + +#: ../../doc/book/admin/access_control.rst:367 +msgid "text description of the connected peer, and" +msgstr "" + +#: ../../doc/book/admin/access_control.rst:368 +msgid "session local state, such as Lua variables and functions." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:370 +msgid "In Tarantool, a single session can execute multiple concurrent transactions. Each transaction is identified by a unique integer ID, which can be queried at start of the transaction using :doc:`/reference/reference_lua/box_session/sync`." +msgstr "" + +#: ../../doc/book/admin/access_control.rst:376 +msgid "To track all connects and disconnects, you can use :ref:`connection and authentication triggers `." +msgstr "" diff --git a/locale/en/admin/backups.pot b/locale/en/admin/backups.pot new file mode 100644 index 0000000000..a68a30d5c9 --- /dev/null +++ b/locale/en/admin/backups.pot @@ -0,0 +1,117 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/backups.rst:5 +msgid "Backups" +msgstr "" + +#: ../../doc/book/admin/backups.rst:7 +msgid "Tarantool has an append-only storage architecture: it appends data to files but it never overwrites earlier data. The :ref:`Tarantool garbage collector ` removes old files after a checkpoint. You can prevent or delay the garbage collector's action by configuring the :ref:`checkpoint daemon `. Backups can be taken at any time, with minimal overhead on database performance." +msgstr "" + +#: ../../doc/book/admin/backups.rst:16 +msgid "Two functions are helpful for backups in certain situations:" +msgstr "" + +#: ../../doc/book/admin/backups.rst:18 +msgid ":doc:`/reference/reference_lua/box_backup/start` informs the server that activities related to the removal of outdated backups must be suspended and returns a table with the names of snapshot and vinyl files that should be copied." +msgstr "" + +#: ../../doc/book/admin/backups.rst:23 +msgid ":doc:`/reference/reference_lua/box_backup/stop` later informs the server that normal operations may resume." +msgstr "" + +#: ../../doc/book/admin/backups.rst:30 +msgid "Hot backup (memtx)" +msgstr "" + +#: ../../doc/book/admin/backups.rst:32 +msgid "This is a special case when there are only in-memory tables." +msgstr "" + +#: ../../doc/book/admin/backups.rst:34 +msgid "The last :ref:`snapshot file ` is a backup of the entire database; and the :ref:`WAL ` files that are made after the last snapshot are incremental backups. Therefore taking a backup is a matter of copying the snapshot and WAL files." +msgstr "" + +#: ../../doc/book/admin/backups.rst:39 +msgid "Use ``tar`` to make a (possibly compressed) copy of the latest .snap and .xlog files on the :ref:`memtx_dir ` and :ref:`wal_dir ` directories." +msgstr "" + +#: ../../doc/book/admin/backups.rst:43 +msgid "If there is a security policy, encrypt the .tar file." +msgstr "" + +#: ../../doc/book/admin/backups.rst:45 +msgid "Copy the .tar file to a safe place." +msgstr "" + +#: ../../doc/book/admin/backups.rst:47 +msgid "Later, restoring the database is a matter of taking the .tar file and putting its contents back in the ``memtx_dir`` and ``wal_dir`` directories." +msgstr "" + +#: ../../doc/book/admin/backups.rst:54 +msgid "Hot backup (vinyl/memtx)" +msgstr "" + +#: ../../doc/book/admin/backups.rst:56 +msgid "Vinyl stores its files in :ref:`vinyl_dir `, and creates a folder for each database space. Dump and compaction processes are append-only and create new files. The Tarantool garbage collector may remove old files after each checkpoint." +msgstr "" + +#: ../../doc/book/admin/backups.rst:61 +msgid "To take a mixed backup:" +msgstr "" + +#: ../../doc/book/admin/backups.rst:63 +msgid "Issue :doc:`/reference/reference_lua/box_backup/start` on the :ref:`administrative console `. This will return a list of files to back up and suspend garbage collection for them till the next ``box.backup.stop()``." +msgstr "" + +#: ../../doc/book/admin/backups.rst:68 +msgid "Copy the files from the list to a safe location. This will include memtx snapshot files, vinyl run and index files, at a state consistent with the last checkpoint." +msgstr "" + +#: ../../doc/book/admin/backups.rst:72 +msgid "Issue :doc:`/reference/reference_lua/box_backup/stop` so the garbage collector can continue as usual." +msgstr "" + +#: ../../doc/book/admin/backups.rst:79 +msgid "Continuous remote backup (memtx)" +msgstr "" + +#: ../../doc/book/admin/backups.rst:81 +msgid "The :ref:`replication ` feature is useful for backup as well as for load balancing." +msgstr "" + +#: ../../doc/book/admin/backups.rst:84 +msgid "Therefore taking a backup is a matter of ensuring that any given replica is up to date, and doing a cold backup on it. Since all the other replicas continue to operate, this is not a cold backup from the end user’s point of view. This could be done on a regular basis, with a ``cron`` job or with a Tarantool fiber." +msgstr "" + +#: ../../doc/book/admin/backups.rst:93 +msgid "Continuous backup (memtx)" +msgstr "" + +#: ../../doc/book/admin/backups.rst:95 +msgid "The logged changes done since the last cold backup must be secured, while the system is running." +msgstr "" + +#: ../../doc/book/admin/backups.rst:98 +msgid "For this purpose, you need a file copy utility that will do the copying remotely and continuously, copying only the parts of a write ahead log file that are changing. One such utility is `rsync `_." +msgstr "" + +#: ../../doc/book/admin/backups.rst:103 +msgid "Alternatively, you need an ordinary file copy utility, but there should be frequent production of new snapshot files or new WAL files as changes occur, so that only the new files need to be copied." +msgstr "" diff --git a/locale/en/admin/bug_reports.pot b/locale/en/admin/bug_reports.pot new file mode 100644 index 0000000000..8cd6346564 --- /dev/null +++ b/locale/en/admin/bug_reports.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/bug_reports.rst:5 +msgid "Bug reports" +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:7 +msgid "If you found a bug in Tarantool, you’re doing us a favor by taking the time to tell us about it." +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:10 +msgid "Please create an issue at Tarantool repository at GitHub. We encourage you to include the following information:" +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:13 +msgid "Steps needed to reproduce the bug, and an explanation why this differs from the expected behavior according to our manual. Please provide specific unique information. For example, instead of \"I can’t get certain information\", say \"box.space.x:delete() didn’t report what was deleted\"." +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:18 +msgid "Your operating system name and version, the Tarantool name and version, and any unusual details about your machine and its configuration." +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:21 +msgid "Related files like a :ref:`stack trace ` or a Tarantool :ref:`log file `." +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:24 +msgid "If this is a feature request or if it affects a special category of users, be sure to mention that." +msgstr "" + +#: ../../doc/book/admin/bug_reports.rst:27 +msgid "Usually within one or two workdays a Tarantool team member will write an acknowledgment, or some questions, or suggestions for a workaround." +msgstr "" diff --git a/locale/en/admin/daemon_supervision.pot b/locale/en/admin/daemon_supervision.pot new file mode 100644 index 0000000000..21ac0a3c56 --- /dev/null +++ b/locale/en/admin/daemon_supervision.pot @@ -0,0 +1,318 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/daemon_supervision.rst:5 +msgid "Daemon supervision" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:11 +msgid "Server signals" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:13 +msgid "Tarantool processes these signals during the event loop in the transaction processor thread:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:22 +msgid "Signal" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:22 +msgid "Effect" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:24 +msgid "SIGHUP" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:24 +msgid "May cause log file rotation. See the :ref:`example ` in reference on Tarantool logging parameters." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:28 +msgid "SIGUSR1" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:28 +msgid "May cause a database checkpoint. See :doc:`/reference/reference_lua/box_snapshot`." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:31 +msgid "SIGTERM" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:31 +msgid "May cause graceful shutdown (information will be saved first)." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:34 +msgid "SIGINT (also known as keyboard interrupt)" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:34 +msgid "May cause graceful shutdown." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:38 +msgid "SIGKILL" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:38 +msgid "Causes an immediate shutdown." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:41 +msgid "Other signals will result in behavior defined by the operating system. Signals other than SIGKILL may be ignored, especially if Tarantool is executing a long-running procedure which prevents return to the event loop in the transaction processor thread." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:50 +msgid "Automatic instance restart" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:52 +msgid "On ``systemd``-enabled platforms, ``systemd`` automatically restarts all Tarantool instances in case of failure. To demonstrate it, let’s try to destroy an instance:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:56 +msgid "$ systemctl status tarantool@my_app|grep PID\n" +"Main PID: 5885 (tarantool)\n" +"$ tt connect my_app\n" +" • Connecting to the instance...\n" +" • Connected to /var/run/tarantool/my_app.control\n" +"/var/run/tarantool/my_app.control> os.exit(-1)\n" +" ⨯ Connection was closed. Probably instance process isn't running anymore" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:66 +msgid "Now let’s make sure that ``systemd`` has restarted the instance:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:68 +msgid "$ systemctl status tarantool@my_app|grep PID\n" +"Main PID: 5914 (tarantool)" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:73 +msgid "Additionally, you can find the information about the instance restart in the boot logs:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:75 +msgid "$ journalctl -u tarantool@my_app -n 8" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:83 +msgid "Core dumps" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:85 +msgid "Tarantool makes a core dump if it receives any of the following signals: SIGSEGV, SIGFPE, SIGABRT or SIGQUIT. This is automatic if Tarantool crashes." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:88 +msgid "On ``systemd``-enabled platforms, ``coredumpctl`` automatically saves core dumps and stack traces in case of a crash. Here is a general \"how to\" for how to enable core dumps on a Unix system:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:92 +msgid "Ensure session limits are configured to enable core dumps, i.e. say ``ulimit -c unlimited``. Check \"man 5 core\" for other reasons why a core dump may not be produced." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:96 +msgid "Set a directory for writing core dumps to, and make sure that the directory is writable. On Linux, the directory path is set in a kernel parameter configurable via ``/proc/sys/kernel/core_pattern``." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:100 +msgid "Make sure that core dumps include stack trace information. If you use a binary Tarantool distribution, this is automatic. If you build Tarantool from source, you will not get detailed information if you pass ``-DCMAKE_BUILD_TYPE=Release`` to CMake." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:105 +msgid "To simulate a crash, you can execute an illegal command against a Tarantool instance:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:108 +msgid "$ # !!! please never do this on a production system !!!\n" +"$ tt connect my_app\n" +" • Connecting to the instance...\n" +" • Connected to /var/run/tarantool/my_app.control\n" +"/var/run/tarantool/my_app.control> require('ffi').cast('char *', 0)[0] = 48\n" +" ⨯ Connection was closed. Probably instance process isn't running anymore" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:117 +msgid "Alternatively, if you know the process ID of the instance (here we refer to it as $PID), you can abort a Tarantool instance by running ``gdb`` debugger:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:120 +msgid "$ gdb -batch -ex \"generate-core-file\" -p $PID" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:124 +msgid "or manually sending a SIGABRT signal:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:126 +msgid "$ kill -SIGABRT $PID" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:132 +msgid "To find out the process id of the instance ($PID), you can:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:134 +msgid "look it up in the instance's :ref:`box.info.pid `," +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:136 +msgid "find it with ``ps -A | grep tarantool``, or" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:138 +msgid "say ``systemctl status tarantool@my_app|grep PID``." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:140 +msgid "On a ``systemd-enabled`` system, to see the latest crashes of the Tarantool daemon, say:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:143 +msgid "$ coredumpctl list /usr/bin/tarantool\n" +"MTIME PID UID GID SIG PRESENT EXE\n" +"Sat 2016-01-23 15:21:24 MSK 20681 1000 1000 6 /usr/bin/tarantool\n" +"Sat 2016-01-23 15:51:56 MSK 21035 995 992 6 /usr/bin/tarantool" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:150 +msgid "To save a core dump into a file, say:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:152 +msgid "$ coredumpctl -o filename.core info " +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:160 +msgid "Stack traces" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:162 +msgid "Since Tarantool stores tuples in memory, core files may be large. For investigation, you normally don't need the whole file, but only a \"stack trace\" or \"backtrace\"." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:166 +msgid "To save a stack trace into a file, say:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:168 +msgid "$ gdb -se \"tarantool\" -ex \"bt full\" -ex \"thread apply all bt\" --batch -c core> /tmp/tarantool_trace.txt" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:172 +msgid "where:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:174 +msgid "\"tarantool\" is the path to the Tarantool executable," +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:175 +msgid "\"core\" is the path to the core file, and" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:176 +msgid "\"/tmp/tarantool_trace.txt\" is a sample path to a file for saving the stack trace." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:180 +msgid "Occasionally, you may find that the trace file contains output without debug symbols – the lines will contain ”??” instead of names. If this happens, check the instructions on these Tarantool wiki pages: `How to debug core dump of stripped tarantool `_ and `How to debug core from different OS `_." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:187 +msgid "To see the stack trace and other useful information in console, say:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:189 +msgid "$ coredumpctl info 21035\n" +" PID: 21035 (tarantool)\n" +" UID: 995 (tarantool)\n" +" GID: 992 (tarantool)\n" +" Signal: 6 (ABRT)\n" +" Timestamp: Sat 2016-01-23 15:51:42 MSK (4h 36min ago)\n" +" Command Line: tarantool my_app.lua \n" +" Executable: /usr/bin/tarantool\n" +"Control Group: /system.slice/system-tarantool.slice/tarantool@my_app.service\n" +" Unit: tarantool@my_app.service\n" +" Slice: system-tarantool.slice\n" +" Boot ID: 7c686e2ef4dc4e3ea59122757e3067e2\n" +" Machine ID: a4a878729c654c7093dc6693f6a8e5ee\n" +" Hostname: localhost.localdomain\n" +" Message: Process 21035 (tarantool) of user 995 dumped core.\n" +"\n" +" Stack trace of thread 21035:\n" +" #0 0x00007f84993aa618 raise (libc.so.6)\n" +" #1 0x00007f84993ac21a abort (libc.so.6)\n" +" #2 0x0000560d0a9e9233 _ZL12sig_fatal_cbi (tarantool)\n" +" #3 0x00007f849a211220 __restore_rt (libpthread.so.0)\n" +" #4 0x0000560d0aaa5d9d lj_cconv_ct_ct (tarantool)\n" +" #5 0x0000560d0aaa687f lj_cconv_ct_tv (tarantool)\n" +" #6 0x0000560d0aaabe33 lj_cf_ffi_meta___newindex (tarantool)\n" +" #7 0x0000560d0aaae2f7 lj_BC_FUNCC (tarantool)\n" +" #8 0x0000560d0aa9aabd lua_pcall (tarantool)\n" +" #9 0x0000560d0aa71400 lbox_call (tarantool)\n" +" #10 0x0000560d0aa6ce36 lua_fiber_run_f (tarantool)\n" +" #11 0x0000560d0a9e8d0c _ZL16fiber_cxx_invokePFiP13__va_list_tagES0_ (tarantool)\n" +" #12 0x0000560d0aa7b255 fiber_loop (tarantool)\n" +" #13 0x0000560d0ab38ed1 coro_init (tarantool)\n" +" ..." +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:228 +msgid "Debugger" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:230 +msgid "To start ``gdb`` debugger on the core dump, say:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:232 +msgid "$ coredumpctl gdb " +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:236 +msgid "It is highly recommended to install ``tarantool-debuginfo`` package to improve ``gdb`` experience, for example:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:239 +msgid "$ dnf debuginfo-install tarantool" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:243 +msgid "``gdb`` also provides information about the debuginfo packages you need to install:" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:246 +msgid "$ gdb -p \n" +"...\n" +"Missing separate debuginfos, use: dnf debuginfo-install\n" +"glibc-2.22.90-26.fc24.x86_64 krb5-libs-1.14-12.fc24.x86_64\n" +"libgcc-5.3.1-3.fc24.x86_64 libgomp-5.3.1-3.fc24.x86_64\n" +"libselinux-2.4-6.fc24.x86_64 libstdc++-5.3.1-3.fc24.x86_64\n" +"libyaml-0.1.6-7.fc23.x86_64 ncurses-libs-6.0-1.20150810.fc24.x86_64\n" +"openssl-libs-1.0.2e-3.fc24.x86_64" +msgstr "" + +#: ../../doc/book/admin/daemon_supervision.rst:257 +msgid "Symbolic names are present in stack traces even if you don’t have ``tarantool-debuginfo`` package installed." +msgstr "" diff --git a/locale/en/admin/disaster_recovery.pot b/locale/en/admin/disaster_recovery.pot new file mode 100644 index 0000000000..51a8e9d40d --- /dev/null +++ b/locale/en/admin/disaster_recovery.pot @@ -0,0 +1,223 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/disaster_recovery.rst:4 +msgid "Disaster recovery" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:6 +msgid "The minimal fault-tolerant Tarantool configuration would be a :ref:`replica set ` that includes a master and a replica, or two masters. The basic recommendation is to configure all Tarantool instances in a replica set to create :ref:`snapshot files ` on a regular basis." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:10 +msgid "Here are action plans for typical crash scenarios." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:16 +msgid "Master-replica" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:21 +msgid "Master crash: manual failover" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:23 +msgid "**Configuration:** master-replica (:ref:`manual failover `)." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:25 +#: ../../doc/book/admin/disaster_recovery.rst:52 +msgid "**Problem:** The master has crashed." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:27 +#: ../../doc/book/admin/disaster_recovery.rst:54 +#: ../../doc/book/admin/disaster_recovery.rst:74 +#: ../../doc/book/admin/disaster_recovery.rst:117 +#: ../../doc/book/admin/disaster_recovery.rst:136 +msgid "**Actions:**" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:29 +msgid "Ensure the master is stopped. For example, log in to the master machine and use ``tt stop``." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:32 +msgid "Configure a new replica set leader using the :ref:`.leader ` option." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:34 +msgid "Reload configuration on all instances using :ref:`config:reload() `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:36 +msgid "Make sure that a new replica set leader is a master using :ref:`box.info.ro `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:38 +#: ../../doc/book/admin/disaster_recovery.rst:58 +msgid "On a new master, :ref:`remove a crashed instance from the '_cluster' space `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:40 +#: ../../doc/book/admin/disaster_recovery.rst:60 +msgid "Set up a replacement for the crashed master on a spare host." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:42 +msgid "See also: :ref:`Performing manual failover `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:48 +msgid "Master crash: automated failover" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:50 +msgid "**Configuration:** master-replica (:ref:`automated failover `)." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:56 +msgid "Use ``box.info.election`` to make sure a new master is elected automatically." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:62 +msgid "See also: :ref:`Testing automated failover `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:68 +msgid "Data loss" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:70 +msgid "**Configuration:** master-replica." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:72 +msgid "**Problem:** Some transactions are missing on a replica after the master has crashed." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:76 +msgid "You lose a few transactions in the master :ref:`write-ahead log file `, which may have not transferred to the replica before the crash. If you were able to salvage the master ``.xlog`` file, you may be able to recover these." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:81 +msgid "Find out instance UUID from the crashed master :ref:`xlog `:" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:83 +msgid "$ head -5 var/lib/instance001/*.xlog | grep Instance\n" +"Instance: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:88 +msgid "On the new master, use the UUID to find the position:" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:90 +msgid "app:instance002> box.info.vclock[box.space._cluster.index.uuid:select{'9bb111c2-3ff5-36a7-00f4-2b9a573ea660'}[1][1]]\n" +"---\n" +"- 999\n" +"..." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:97 +msgid ":ref:`Play the records ` from the crashed ``.xlog`` to the new master, starting from the new master position:" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:100 +msgid "$ tt play 127.0.0.1:3302 var/lib/instance001/00000000000000000000.xlog \\\n" +" --from 1000 \\\n" +" --replica 1 \\\n" +" --username admin --password secret" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:111 +msgid "Master-master" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:113 +msgid "**Configuration:** :ref:`master-master `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:115 +msgid "**Problem:** one master has crashed." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:119 +msgid "Let the load be handled by another master alone." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:121 +msgid "Remove a crashed master from a replica set." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:123 +msgid "Set up a replacement for the crashed master on a spare host. Learn more from :ref:`Adding and removing instances `." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:130 +msgid "Master-replica/master-master: data loss" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:132 +msgid "**Configuration:** master-replica or master-master." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:134 +msgid "**Problem:** Data was deleted at one master and this data loss was propagated to the other node (master or replica)." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:138 +msgid "Put all nodes in read-only mode. Depending on the :ref:`replication.failover ` mode, this can be done as follows:" +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:141 +msgid "``manual``: change a replica set leader to ``null``." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:142 +msgid "``election``: set :ref:`replication.election_mode ` to ``voter`` or ``off`` at the replica set level." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:143 +msgid "``off``: set ``database.mode`` to ``ro``." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:145 +msgid "Reload configurations on all instances using the ``reload()`` function provided by the :ref:`config ` module." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:147 +msgid "Turn off deletion of expired checkpoints with :doc:`/reference/reference_lua/box_backup/start`. This prevents the Tarantool garbage collector from removing files made with older checkpoints until :doc:`/reference/reference_lua/box_backup/stop` is called." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:151 +msgid "Get the latest valid :ref:`.snap file ` and use ``tt cat`` command to calculate at which LSN the data loss occurred." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:154 +msgid "Start a new instance and use :ref:`tt play ` command to play to it the contents of ``.snap`` and ``.xlog`` files up to the calculated LSN." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:157 +msgid "Bootstrap a new replica from the recovered master." +msgstr "" + +#: ../../doc/book/admin/disaster_recovery.rst:161 +msgid "The steps above are applicable only to data in the memtx storage engine." +msgstr "" diff --git a/locale/en/admin/index.pot b/locale/en/admin/index.pot new file mode 100644 index 0000000000..f03492e0e8 --- /dev/null +++ b/locale/en/admin/index.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/index.rst:7 +msgid "Administration" +msgstr "" + +#: ../../doc/book/admin/index.rst:9 +msgid "Tarantool is designed to have multiple running instances on the same host." +msgstr "" + +#: ../../doc/book/admin/index.rst:11 +msgid "Here we show how to administer Tarantool instances using any of the following utilities:" +msgstr "" + +#: ../../doc/book/admin/index.rst:14 +msgid "``systemd`` native utilities, or" +msgstr "" + +#: ../../doc/book/admin/index.rst:15 +msgid ":ref:`tt `, a command-line utility for managing Tarantool-based applications." +msgstr "" + +#: ../../doc/book/admin/index.rst:19 +msgid "Unlike the rest of this manual, here we use system-wide paths." +msgstr "" + +#: ../../doc/book/admin/index.rst:20 +msgid "Console examples here are for Fedora." +msgstr "" + +#: ../../doc/book/admin/index.rst:22 +msgid "This chapter includes the following sections:" +msgstr "" diff --git a/locale/en/admin/instance_config.pot b/locale/en/admin/instance_config.pot new file mode 100644 index 0000000000..446c6e43dd --- /dev/null +++ b/locale/en/admin/instance_config.pot @@ -0,0 +1,263 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-20 07:42+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/instance_config.rst:6 +msgid "Application environment" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:8 +msgid "This section provides a high-level overview on how to prepare a Tarantool application for deployment and how the application's environment and layout might look. This information is helpful for understanding how to administer Tarantool instances using :ref:`tt CLI ` in both development and production environments." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:12 +msgid "The main steps of creating and preparing the application for deployment are:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:14 +msgid ":ref:`admin-instance_config-init-environment`." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:16 +msgid ":ref:`admin-instance_config-develop-app`." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:18 +msgid ":ref:`admin-instance_config-package-app`." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:20 +msgid "In this section, a `sharded_cluster `_ application is used as an example. This cluster includes 5 instances: one router and 4 storages, which constitute two replica sets." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:None +#: ../../doc/book/admin/instance_config.rst:0 +#: ../../doc/book/admin/instance_config.rst:0 +msgid "Cluster topology" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:34 +msgid "Initializing a local environment" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:36 +msgid "Before creating an application, you need to set up a local environment for ``tt``:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:38 +msgid "Create a home directory for the environment." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:40 +msgid "Run ``tt init`` in this directory:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:42 +msgid "~/myapp$ tt init\n" +" • Environment config is written to 'tt.yaml'" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:47 +msgid "This command creates a default ``tt`` configuration file ``tt.yaml`` for a local environment and the directories for applications, control sockets, logs, and other artifacts:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:51 +msgid "~/myapp$ ls\n" +"bin distfiles include instances.enabled modules templates tt.yaml" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:56 +msgid "Find detailed information about the ``tt`` configuration parameters and launch modes on the :ref:`tt configuration page `." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:66 +msgid "Creating and developing an application" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:68 +msgid "You can create an application in two ways:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:70 +msgid "Manually by preparing its layout in a directory inside ``instances_enabled``. The directory name is used as the application identifier." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:73 +msgid "From a template by using the :ref:`tt create ` command." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:75 +msgid "In this example, the application's layout is prepared manually and looks as follows." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:77 +msgid "~/myapp$ tree\n" +".\n" +"├── bin\n" +"├── distfiles\n" +"├── include\n" +"├── instances.enabled\n" +"│ └── sharded_cluster\n" +"│ ├── config.yaml\n" +"│ ├── instances.yaml\n" +"│ ├── router.lua\n" +"│ ├── sharded_cluster-scm-1.rockspec\n" +"│ └── storage.lua\n" +"├── modules\n" +"├── templates\n" +"└── tt.yaml" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:96 +msgid "The ``sharded_cluster`` directory contains the following files:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:98 +msgid "``config.yaml``: contains the :ref:`configuration ` of the cluster. This file might include the entire cluster topology or provide connection settings to a centralized configuration storage." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:99 +msgid "``instances.yml``: specifies instances to run in the current environment. For example, on the developer’s machine, this file might include all the instances defined in the cluster configuration. In the production environment, this file includes :ref:`instances to run on the specific machine `." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:100 +msgid "``router.lua``: includes code specific for a :ref:`router `." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:101 +msgid "``sharded_cluster-scm-1.rockspec``: specifies the required external dependencies (for example, ``vshard``)." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:102 +msgid "``storage.lua``: includes code specific for :ref:`storages `." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:104 +msgid "You can find the full example here: `sharded_cluster `_." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:114 +msgid "Packaging the application" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:116 +msgid "To package the ready application, use the :ref:`tt pack ` command. This command can create an installable DEB/RPM package or generate ``.tgz`` archive." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:119 +msgid "The structure below reflects the content of the packed ``.tgz`` archive for the `sharded_cluster `_ application:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:121 +msgid "~/myapp$ tree -a\n" +".\n" +"├── bin\n" +"│ ├── tarantool\n" +"│ └── tt\n" +"├── include\n" +"├── instances.enabled\n" +"│ └── sharded_cluster -> ../sharded_cluster\n" +"├── modules\n" +"├── sharded_cluster\n" +"│ ├── .rocks\n" +"│ │ └── share\n" +"│ │ └── ...\n" +"│ ├── config.yaml\n" +"│ ├── instances.yaml\n" +"│ ├── router.lua\n" +"│ ├── sharded_cluster-scm-1.rockspec\n" +"│ └── storage.lua\n" +"└── tt.yaml" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:144 +msgid "The application's layout looks similar to the one defined when :ref:`developing the application ` with some differences:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:146 +msgid "``bin``: contains the ``tarantool`` and ``tt`` binaries packed with the application bundle." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:148 +msgid "``instances.enabled``: contains a symlink to the packed ``sharded_cluster`` application." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:150 +msgid "``sharded_cluster``: a packed application. In addition to files created during the application development, includes the ``.rocks`` directory containing application dependencies (for example, ``vshard``)." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:152 +msgid "``tt.yaml``: a ``tt`` configuration file." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:159 +msgid "Instances to run" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:161 +msgid "One more difference for a deployed application is the content of the ``instances.yaml`` file that specifies instances to run in the current environment." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:163 +msgid "On the developer's machine, this file might include all the instances defined in the cluster configuration." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:170 +msgid "``instances.yaml``:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:172 +msgid "storage-a-001:\n" +"storage-a-002:\n" +"storage-b-001:\n" +"storage-b-002:\n" +"router-a-001:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:176 +msgid "In the production environment, this file includes instances to run on the specific machine." +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:183 +msgid "``instances.yaml`` (Server-001):" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:185 +msgid "router-a-001:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:189 +msgid "``instances.yaml`` (Server-002):" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:191 +msgid "storage-a-001:\n" +"storage-b-001:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:196 +msgid "``instances.yaml`` (Server-003):" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:198 +msgid "storage-a-002:\n" +"storage-b-002:" +msgstr "" + +#: ../../doc/book/admin/instance_config.rst:204 +msgid "The :ref:`Starting and stopping instances ` section describes how to start and stop Tarantool instances." +msgstr "" diff --git a/locale/en/admin/logs.pot b/locale/en/admin/logs.pot new file mode 100644 index 0000000000..19b11fa018 --- /dev/null +++ b/locale/en/admin/logs.pot @@ -0,0 +1,107 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/logs.rst:4 +msgid "Logs" +msgstr "" + +#: ../../doc/book/admin/logs.rst:6 +msgid "Each Tarantool instance logs important events to its own log file ``.log``. For instances started with :ref:`tt `, the log location is defined by the ``log_dir`` parameter in the :ref:`tt configuration `. By default, it's ``/var/log/tarantool`` in the ``tt`` :ref:`system mode `, and the ``var/log/`` subdirectory of the ``tt`` working directory in the :ref:`local mode `. In the specified location, ``tt`` creates separate directories for each instance's logs." +msgstr "" + +#: ../../doc/book/admin/logs.rst:13 +msgid "To check how logging works, write something to the log using the :ref:`log ` module:" +msgstr "" + +#: ../../doc/book/admin/logs.rst:15 +msgid "$ tt connect my_app\n" +" • Connecting to the instance...\n" +" • Connected to /var/run/tarantool/my_app.control\n" +"\n" +"/var/run/tarantool/my_app.control> require('log').info(\"Hello for the manual readers\")" +msgstr "" + +#: ../../doc/book/admin/logs.rst:23 +msgid "Then check the logs:" +msgstr "" + +#: ../../doc/book/admin/logs.rst:25 +msgid "$ tail /var/log/tarantool/my_app.log\n" +"2023-09-12 18:13:00.396 [67173] main/111/guard of feedback_daemon/box.feedback_daemon V> metrics_collector restarted\n" +"2023-09-12 18:13:00.396 [67173] main/103/-/box.feedback_daemon V> feedback_daemon started\n" +"2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(14) = 0x1090077b4\n" +"2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(26) = 0x1090077ec\n" +"2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007824\n" +"2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(24) = 0x10900785c\n" +"2023-09-12 18:13:00.396 [67173] main/103/- D> memtx_tuple_new_raw_impl(39) = 0x109007894\n" +"2023-09-12 18:13:00.396 [67173] main/106/checkpoint_daemon I> scheduled next checkpoint for Tue Sep 12 19:44:34 2023\n" +"2023-09-12 18:13:00.396 [67173] main I> entering the event loop\n" +"2023-09-12 18:13:11.656 [67173] main/114/console/unix/:/tarantool I> Hello for the manual readers" +msgstr "" + +#: ../../doc/book/admin/logs.rst:42 +msgid "Log rotation" +msgstr "" + +#: ../../doc/book/admin/logs.rst:44 +msgid "When :ref:`logging to a file `, the system administrator must ensure logs are rotated timely and do not take up all the available disk space. To prevent log files from growing infinitely, ``tt`` automatically rotates instance logs. The following ``tt`` configuration parameters define the log rotation: ``log_maxsize`` (in megabytes) and ``log_maxage`` (in days). When any of these limits is reached, the log is rotated. Additionally, there is the ``log_maxbackups`` parameter (the number of stored log files for an instance), which enables automatic removal of old log files." +msgstr "" + +#: ../../doc/book/admin/logs.rst:53 +msgid "# tt.yaml\n" +"tt:\n" +" app:\n" +" log_maxsize: 100\n" +" log_maxage: 3\n" +" log_maxbackups: 50\n" +" # ..." +msgstr "" + +#: ../../doc/book/admin/logs.rst:63 +msgid "There is also the :ref:`tt logrotate ` command that performs log rotation on demand." +msgstr "" + +#: ../../doc/book/admin/logs.rst:66 +msgid "tt logrotate my_app" +msgstr "" + +#: ../../doc/book/admin/logs.rst:70 +msgid "To learn about log rotation in the deprecated ``tarantoolctl`` utility, check its :ref:`documentation `." +msgstr "" + +#: ../../doc/book/admin/logs.rst:77 +msgid "Log formats" +msgstr "" + +#: ../../doc/book/admin/logs.rst:79 +msgid "Tarantool can write its logs to a log file, to ``syslog``, or to a specified program through a pipe." +msgstr "" + +#: ../../doc/book/admin/logs.rst:82 +msgid "File is the default log format for ``tt``. To send logs to a pipe or ``syslog``, specify the :ref:`box.cfg.log ` parameter, for example:" +msgstr "" + +#: ../../doc/book/admin/logs.rst:85 +msgid "box.cfg{log = '| cronolog tarantool.log'}\n" +"-- or\n" +"box.cfg{log = 'syslog:identity=tarantool,facility=user'}" +msgstr "" + +#: ../../doc/book/admin/logs.rst:91 +msgid "In such configurations, log rotation is usually handled by the external program used for logging." +msgstr "" diff --git a/locale/en/admin/modules.pot b/locale/en/admin/modules.pot new file mode 100644 index 0000000000..1768dc2fe8 --- /dev/null +++ b/locale/en/admin/modules.pot @@ -0,0 +1,254 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/modules.rst:4 +msgid "Managing modules" +msgstr "" + +#: ../../doc/book/admin/modules.rst:6 +msgid "This section covers the installation and reloading of Tarantool modules. To learn about writing your own module and contributing it, check the :ref:`Contributing a module ` section." +msgstr "" + +#: ../../doc/book/admin/modules.rst:13 +msgid "Installing a module" +msgstr "" + +#: ../../doc/book/admin/modules.rst:15 +msgid "Modules in Lua and C that come from Tarantool developers and community contributors are available in the following locations:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:18 +msgid "Tarantool modules repository (see :ref:`below `)" +msgstr "" + +#: ../../doc/book/admin/modules.rst:19 +msgid "Tarantool deb/rpm repositories (see :ref:`below `)" +msgstr "" + +#: ../../doc/book/admin/modules.rst:24 +msgid "Installing a module from a repository" +msgstr "" + +#: ../../doc/book/admin/modules.rst:26 +msgid "See `README in tarantool/rocks repository `_ for detailed instructions." +msgstr "" + +#: ../../doc/book/admin/modules.rst:33 +msgid "Installing a module from deb/rpm" +msgstr "" + +#: ../../doc/book/admin/modules.rst:35 +msgid "Follow these steps:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:37 +msgid "Install Tarantool as recommended on the `download page `_." +msgstr "" + +#: ../../doc/book/admin/modules.rst:40 +msgid "Install the module you need. Look up the module's name on `Tarantool rocks page `_ and put the prefix \"tarantool-\" before the module name to avoid ambiguity:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:44 +msgid "$ # for Ubuntu/Debian:\n" +"$ sudo apt-get install tarantool-\n" +"\n" +"$ # for RHEL/CentOS/Amazon:\n" +"$ sudo yum install tarantool-" +msgstr "" + +#: ../../doc/book/admin/modules.rst:52 +msgid "For example, to install the module `vshard `_ on Ubuntu, say:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:55 +msgid "$ sudo apt-get install tarantool-vshard" +msgstr "" + +#: ../../doc/book/admin/modules.rst:59 +msgid "Once these steps are complete, you can:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:61 +msgid "load any module with" +msgstr "" + +#: ../../doc/book/admin/modules.rst:63 +msgid "tarantool> name = require('module-name')" +msgstr "" + +#: ../../doc/book/admin/modules.rst:67 +msgid "for example:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:69 +msgid "tarantool> vshard = require('vshard')" +msgstr "" + +#: ../../doc/book/admin/modules.rst:73 +msgid "search locally for installed modules using ``package.path`` (Lua) or ``package.cpath`` (C):" +msgstr "" + +#: ../../doc/book/admin/modules.rst:76 +msgid "tarantool> package.path\n" +"---\n" +"- ./?.lua;./?/init.lua; /usr/local/share/tarantool/?.lua;/usr/local/share/\n" +"tarantool/?/init.lua;/usr/share/tarantool/?.lua;/usr/share/tarantool/?/ini\n" +"t.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/\n" +"usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;\n" +"...\n" +"\n" +"tarantool> package.cpath\n" +"---\n" +"- ./?.so;/usr/local/lib/x86_64-linux-gnu/tarantool/?.so;/usr/lib/x86_64-li\n" +"nux-gnu/tarantool/?.so;/usr/local/lib/tarantool/?.so;/usr/local/lib/x86_64\n" +"-linux-gnu/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/local/\n" +"lib/lua/5.1/?.so;\n" +"..." +msgstr "" + +#: ../../doc/book/admin/modules.rst:96 +msgid "Question-marks stand for the module name that was specified earlier when saying ``require('module-name')``." +msgstr "" + +#: ../../doc/book/admin/modules.rst:102 +msgid "Reloading a module" +msgstr "" + +#: ../../doc/book/admin/modules.rst:104 +msgid "You can reload any Tarantool application or module with zero downtime." +msgstr "" + +#: ../../doc/book/admin/modules.rst:109 +msgid "Reloading a module in Lua" +msgstr "" + +#: ../../doc/book/admin/modules.rst:111 +msgid "Here's an example that illustrates the most typical case -- \"update and reload\"." +msgstr "" + +#: ../../doc/book/admin/modules.rst:115 +msgid "In this example, we use recommended :ref:`administration practices ` based on :ref:`instance files ` and :ref:`tt ` utility." +msgstr "" + +#: ../../doc/book/admin/modules.rst:119 +msgid "Update the application file." +msgstr "" + +#: ../../doc/book/admin/modules.rst:121 +msgid "For example, a module in ``/usr/share/tarantool/app.lua``:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:123 +msgid "local function start()\n" +" -- initial version\n" +" box.once(\"myapp:v1.0\", function()\n" +" box.schema.space.create(\"somedata\")\n" +" box.space.somedata:create_index(\"primary\")\n" +" ...\n" +" end)\n" +"\n" +" -- migration code from 1.0 to 1.1\n" +" box.once(\"myapp:v1.1\", function()\n" +" box.space.somedata.index.primary:alter(...)\n" +" ...\n" +" end)\n" +"\n" +" -- migration code from 1.1 to 1.2\n" +" box.once(\"myapp:v1.2\", function()\n" +" box.space.somedata.index.primary:alter(...)\n" +" box.space.somedata:insert(...)\n" +" ...\n" +" end)\n" +"end\n" +"\n" +"-- start some background fibers if you need\n" +"\n" +"local function stop()\n" +" -- stop all background fibers and clean up resources\n" +"end\n" +"\n" +"local function api_for_call(xxx)\n" +" -- do some business\n" +"end\n" +"\n" +"return {\n" +" start = start,\n" +" stop = stop,\n" +" api_for_call = api_for_call\n" +"}" +msgstr "" + +#: ../../doc/book/admin/modules.rst:163 +msgid "Update the :ref:`instance file `." +msgstr "" + +#: ../../doc/book/admin/modules.rst:165 +msgid "For example, ``/etc/tarantool/instances.enabled/my_app.lua``:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:167 +msgid "#!/usr/bin/env tarantool\n" +"--\n" +"-- hot code reload example\n" +"--\n" +"\n" +"box.cfg({listen = 3302})\n" +"\n" +"-- ATTENTION: unload it all properly!\n" +"local app = package.loaded['app']\n" +"if app ~= nil then\n" +" -- stop the old application version\n" +" app.stop()\n" +" -- unload the application\n" +" package.loaded['app'] = nil\n" +" -- unload all dependencies\n" +" package.loaded['somedep'] = nil\n" +"end\n" +"\n" +"-- load the application\n" +"log.info('require app')\n" +"app = require('app')\n" +"\n" +"-- start the application\n" +"app.start({some app options controlled by sysadmins})" +msgstr "" + +#: ../../doc/book/admin/modules.rst:194 +msgid "The important thing here is to properly unload the application and its dependencies." +msgstr "" + +#: ../../doc/book/admin/modules.rst:197 +msgid "Manually reload the application file." +msgstr "" + +#: ../../doc/book/admin/modules.rst:199 +msgid "For example, using ``tt``:" +msgstr "" + +#: ../../doc/book/admin/modules.rst:201 +msgid "$ tt connect my_app -f /etc/tarantool/instances.enabled/my_app.lua" +msgstr "" + +#: ../../doc/book/admin/modules.rst:208 +msgid "Reloading a module in C" +msgstr "" + +#: ../../doc/book/admin/modules.rst:210 +msgid "After you compiled a new version of a C module (``*.so`` shared library), call :doc:`box.schema.func.reload('module-name') ` from your Lua script to reload the module." +msgstr "" diff --git a/locale/en/admin/os_notes.pot b/locale/en/admin/os_notes.pot new file mode 100644 index 0000000000..77a64c9d8f --- /dev/null +++ b/locale/en/admin/os_notes.pot @@ -0,0 +1,68 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/os_notes.rst:5 +msgid "Notes for operating systems" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:10 +msgid "macOS" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:12 +msgid "On macOS, no native system tools for administering Tarantool are supported. The recommended way to administer Tarantool instances is using :ref:`tt CLI `." +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:18 +msgid "Gentoo Linux" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:20 +msgid "The section below is about a dev-db/tarantool package installed from the official layman overlay (named ``tarantool``)." +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:23 +msgid "The default instance directory is ``/etc/tarantool/instances.available``, can be redefined in ``/etc/default/tarantool``." +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:26 +msgid "Tarantool instances can be managed (start/stop/reload/status/...) using OpenRC. Consider the example how to create an OpenRC-managed instance:" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:29 +msgid "$ cd /etc/init.d\n" +"$ ln -s tarantool your_service_name\n" +"$ ln -s /usr/share/tarantool/your_service_name.lua /etc/tarantool/instances.available/your_service_name.lua" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:35 +msgid "Checking that it works:" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:37 +msgid "$ /etc/init.d/your_service_name start\n" +"$ tail -f -n 100 /var/log/tarantool/your_service_name.log" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:46 +msgid "FreeBSD" +msgstr "" + +#: ../../doc/book/admin/os_notes.rst:48 +msgid "To learn about specifics of using the deprecated ``tarantoolctl`` utility on FreeBSD, check its :ref:`documentation `." +msgstr "" diff --git a/locale/en/admin/replication/index.pot b/locale/en/admin/replication/index.pot new file mode 100644 index 0000000000..078bb59566 --- /dev/null +++ b/locale/en/admin/replication/index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/replication/index.rst:2 +msgid "Replication administration" +msgstr "" diff --git a/locale/en/admin/replication/repl_monitoring.pot b/locale/en/admin/replication/repl_monitoring.pot new file mode 100644 index 0000000000..c5c2c50eba --- /dev/null +++ b/locale/en/admin/replication/repl_monitoring.pot @@ -0,0 +1,110 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:4 +msgid "Monitoring a replica set" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:6 +msgid "To learn what instances belong to the replica set and obtain statistics for all these instances, execute a :ref:`box.info.replication ` request. The output below shows the replication status for a replica set containing one :ref:`master and two replicas `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:3 +msgid "manual_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 21\n" +" name: instance001\n" +" 2:\n" +" id: 2\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.052655000000414\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00010204315185547\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.09503500000028\n" +" vclock: {1: 21}\n" +" lag: 0.00026917457580566\n" +" 3:\n" +" id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.77522099999987\n" +" peer: replicator@127.0.0.1:3303\n" +" lag: 0.0001838207244873\n" +" name: instance003\n" +" downstream:\n" +" status: follow\n" +" idle: 0.33186100000012\n" +" vclock: {1: 21}\n" +" lag: 0\n" +" ..." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:14 +msgid "The following diagram illustrates the ``upstream`` and ``downstream`` connections if ``box.info.replication`` executed at the master instance (``instance001``):" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:None +msgid "replication status on master" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:21 +msgid "If ``box.info.replication`` is executed on ``instance002``, the ``upstream`` and ``downstream`` connections look as follows:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:None +msgid "replication status on replica" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:28 +msgid "This means that statistics for replicas are given in regard to the instance on which ``box.info.replication`` is executed." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:30 +msgid "The primary indicators of replication health are:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:34 +msgid ":ref:`idle `: the time (in seconds) since the instance received the last event from a master." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:37 +msgid "If the master has no updates to send to the replicas, it sends heartbeat messages every :ref:`replication_timeout ` seconds. The master is programmed to disconnect if it does not see acknowledgments of the heartbeat messages within ``replication_timeout`` * 4 seconds." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:42 +msgid "Therefore, in a healthy replication setup, ``idle`` should never exceed ``replication_timeout``: if it does, either the replication is lagging seriously behind, because the master is running ahead of the replica, or the network link between the instances is down." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:47 +msgid ":ref:`lag `: the time difference between the local time at the instance, recorded when the event was received, and the local time at another master recorded when the event was written to the :ref:`write-ahead log ` on that master." +msgstr "" + +#: ../../doc/book/admin/replication/repl_monitoring.rst:52 +msgid "Since the ``lag`` calculation uses the operating system clocks from two different machines, do not be surprised if it’s negative: a time drift may lead to the remote master clock being consistently behind the local instance's clock." +msgstr "" diff --git a/locale/en/admin/replication/repl_problem_solving.pot b/locale/en/admin/replication/repl_problem_solving.pot new file mode 100644 index 0000000000..3a632feae4 --- /dev/null +++ b/locale/en/admin/replication/repl_problem_solving.pot @@ -0,0 +1,263 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:5 +msgid "Resolving replication conflicts" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:7 +msgid "Tarantool guarantees that every update is applied only once on every replica. However, due to the asynchronous nature of replication, the order of updates is not guaranteed. This topic describes how to solve problems in :ref:`master-master ` replication." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:15 +msgid "Replacing the same primary key" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:17 +msgid "**Case 1:** You have two instances of Tarantool. For example, you try to make a ``replace`` operation with the same primary key on both instances at the same time. This causes a conflict over which tuple to save and which one to discard." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:21 +msgid "Tarantool :ref:`trigger functions ` can help here to implement the rules of conflict resolution on some condition. For example, if you have a timestamp, you can declare saving the tuple with the bigger one." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:25 +msgid "First, you need a :ref:`before_replace() ` trigger on the space which may have conflicts. In this trigger, you can compare the old and new replica records and choose which one to use (or skip the update entirely, or merge two records together)." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:30 +msgid "Then you need to set the trigger at the right time before the space starts to receive any updates. The way you usually set the ``before_replace`` trigger is right when the space is created, so you need a trigger to set another trigger on the system space ``_space``, to capture the moment when your space is created and set the trigger there. This can be an :ref:`on_replace() ` trigger." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:37 +msgid "The difference between ``before_replace`` and ``on_replace`` is that ``on_replace`` is called after a row is inserted into the space, and ``before_replace`` is called before that." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:41 +msgid "To set a ``_space:on_replace()`` trigger correctly, you also need the right timing. The best timing to use it is when ``_space`` is just created, which is the :ref:`box.ctl.on_schema_init() ` trigger." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:45 +msgid "You also need to utilize ``box.on_commit`` to get access to the space being created. The resulting snippet would be the following:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:48 +msgid "local my_space_name = 'my_space'\n" +"local my_trigger = function(old, new) ... end -- your function resolving a conflict\n" +"box.ctl.on_schema_init(function()\n" +" box.space._space:on_replace(function(old_space, new_space)\n" +" if not old_space and new_space and new_space.name == my_space_name then\n" +" box.on_commit(function()\n" +" box.space[my_space_name]:before_replace(my_trigger)\n" +" end\n" +" end\n" +" end)\n" +"end)" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:67 +msgid "Preventing duplicate insert" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:71 +msgid "**Case 2:** In a replica set of two masters, both of them try to insert data by the same unique key:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:73 +msgid "tarantool> box.space.tester:insert{1, 'data'}" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:77 +msgid "This would cause an error saying ``Duplicate key exists in unique index 'primary' in space 'tester'`` and the replication would be stopped. (This is the behavior when the :ref:`replication_skip_conflict ` configuration parameter has its default recommended value, ``false``.)" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:83 +msgid "$ # error messages from master #1\n" +"2017-06-26 21:17:03.233 [30444] main/104/applier/rep_user@100.96.166.1 I> can't read row\n" +"2017-06-26 21:17:03.233 [30444] main/104/applier/rep_user@100.96.166.1 memtx_hash.cc:226 E> ER_TUPLE_FOUND:\n" +"Duplicate key exists in unique index 'primary' in space 'tester'\n" +"2017-06-26 21:17:03.233 [30444] relay/[::ffff:100.96.166.178]/101/main I> the replica has closed its socket, exiting\n" +"2017-06-26 21:17:03.233 [30444] relay/[::ffff:100.96.166.178]/101/main C> exiting the relay loop\n" +"\n" +"$ # error messages from master #2\n" +"2017-06-26 21:17:03.233 [30445] main/104/applier/rep_user@100.96.166.1 I> can't read row\n" +"2017-06-26 21:17:03.233 [30445] main/104/applier/rep_user@100.96.166.1 memtx_hash.cc:226 E> ER_TUPLE_FOUND:\n" +"Duplicate key exists in unique index 'primary' in space 'tester'\n" +"2017-06-26 21:17:03.234 [30445] relay/[::ffff:100.96.166.178]/101/main I> the replica has closed its socket, exiting\n" +"2017-06-26 21:17:03.234 [30445] relay/[::ffff:100.96.166.178]/101/main C> exiting the relay loop" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:99 +msgid "If we check replication statuses with ``box.info``, we will see that replication at master #1 is stopped (``1.upstream.status = stopped``). Additionally, no data is replicated from that master (section ``1.downstream`` is missing in the report), because the downstream has encountered the same error:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:104 +msgid "# replication statuses (report from master #3)\n" +"tarantool> box.info\n" +"---\n" +"- version: 1.7.4-52-g980d30092\n" +" id: 3\n" +" ro: false\n" +" vclock: {1: 9, 2: 1000000, 3: 3}\n" +" uptime: 557\n" +" lsn: 3\n" +" vinyl: []\n" +" cluster:\n" +" uuid: 34d13b1a-f851-45bb-8f57-57489d3b3c8b\n" +" pid: 30445\n" +" status: running\n" +" signature: 1000012\n" +" replication:\n" +" 1:\n" +" id: 1\n" +" uuid: 7ab6dee7-dc0f-4477-af2b-0e63452573cf\n" +" lsn: 9\n" +" upstream:\n" +" peer: replicator@192.168.0.101:3301\n" +" lag: 0.00050592422485352\n" +" status: stopped\n" +" idle: 445.8626639843\n" +" message: Duplicate key exists in unique index 'primary' in space 'tester'\n" +" 2:\n" +" id: 2\n" +" uuid: 9afbe2d9-db84-4d05-9a7b-e0cbbf861e28\n" +" lsn: 1000000\n" +" upstream:\n" +" status: follow\n" +" idle: 201.99915885925\n" +" peer: replicator@192.168.0.102:3301\n" +" lag: 0.0015020370483398\n" +" downstream:\n" +" vclock: {1: 8, 2: 1000000, 3: 3}\n" +" 3:\n" +" id: 3\n" +" uuid: e826a667-eed7-48d5-a290-64299b159571\n" +" lsn: 3\n" +" uuid: e826a667-eed7-48d5-a290-64299b159571\n" +"..." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:151 +msgid "To learn how to resolve a replication conflict by reseeding a replica, see :ref:`Resolving replication conflicts `." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:157 +msgid "Replication runs out of sync" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:159 +msgid "In a master-master cluster of two instances, suppose we make the following operation:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:162 +msgid "tarantool> box.space.tester:upsert({1}, {{'=', 2, box.info.uuid}})" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:166 +msgid "When this operation is applied on both instances in the replica set:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:168 +msgid "# at master #1\n" +"tarantool> box.space.tester:upsert({1}, {{'=', 2, box.info.uuid}})\n" +"# at master #2\n" +"tarantool> box.space.tester:upsert({1}, {{'=', 2, box.info.uuid}})" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:175 +msgid "... we can have the following results, depending on the order of execution:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:177 +msgid "each master’s row contains the UUID from master #1," +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:178 +msgid "each master’s row contains the UUID from master #2," +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:179 +msgid "master #1 has the UUID of master #2, and vice versa." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:184 +msgid "Commutative changes" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:186 +msgid "The cases described in the previous paragraphs represent examples of **non-commutative** operations, that is operations whose result depends on the execution order. On the contrary, for **commutative operations**, the execution order does not matter." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:191 +msgid "Consider for example the following command:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:193 +msgid "tarantool> box.space.tester:upsert{{1, 0}, {{'+', 2, 1)}" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:197 +msgid "This operation is commutative: we get the same result no matter in which order the update is applied on the other masters." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:203 +msgid "Trigger usage" +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:205 +msgid "The logic and the snippet setting a trigger will be the same here as in :ref:`case 1 `. But the trigger function will differ. Note that the trigger below assumes that tuple has a timestamp in the second field." +msgstr "" + +#: ../../doc/book/admin/replication/repl_problem_solving.rst:209 +msgid "local my_space_name = 'test'\n" +"local my_trigger = function(old, new, sp, op)\n" +" -- op: ‘INSERT’, ‘DELETE’, ‘UPDATE’, or ‘REPLACE’\n" +" if new == nil then\n" +" print(\"No new during \"..op, old)\n" +" return -- deletes are ok\n" +" end\n" +" if old == nil then\n" +" print(\"Insert new, no old\", new)\n" +" return new -- insert without old value: ok\n" +" end\n" +" print(op..\" duplicate\", old, new)\n" +" if op == 'INSERT' then\n" +" if new[2] > old[2] then\n" +" -- Creating new tuple will change op to ‘REPLACE’\n" +" return box.tuple.new(new)\n" +" end\n" +" return old\n" +" end\n" +" if new[2] > old[2] then\n" +" return new\n" +" else\n" +" return old\n" +" end\n" +" return\n" +"end\n" +"\n" +"box.ctl.on_schema_init(function()\n" +" box.space._space:on_replace(function(old_space, new_space)\n" +" if not old_space and new_space and new_space.name == my_space_name then\n" +" box.on_commit(function()\n" +" box.space[my_space_name]:before_replace(my_trigger)\n" +" end)\n" +" end\n" +" end)\n" +"end)" +msgstr "" diff --git a/locale/en/admin/replication/repl_recover.pot b/locale/en/admin/replication/repl_recover.pot new file mode 100644 index 0000000000..ad83b3249c --- /dev/null +++ b/locale/en/admin/replication/repl_recover.pot @@ -0,0 +1,113 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/replication/repl_recover.rst:4 +msgid "Recovering from a degraded state" +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:6 +msgid "\"Degraded state\" is a situation when the master becomes unavailable -- due to hardware or network failure, or due to a programming bug." +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:12 +msgid "In a master-replica set with :ref:`manual failover `, if a master disappears, error messages appear on the replicas stating that the connection is lost:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:15 +msgid "2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 I> can't read row\n" +"2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 19, aka 127.0.0.1:55932, peer of 127.0.0.1:3301: Broken pipe\n" +"2023-12-04 13:19:04.724 [16755] main/110/applier/replicator@127.0.0.1:3301 I> will retry every 1.00 second\n" +"2023-12-04 13:19:04.724 [16755] relay/127.0.0.1:55940/101/main coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 23, aka 127.0.0.1:3302, peer of 127.0.0.1:55940: Broken pipe\n" +"2023-12-04 13:19:04.724 [16755] relay/127.0.0.1:55940/101/main I> exiting the relay loop" +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:23 +msgid "In a master-replica set with :ref:`automated failover `, a log also includes Raft messages showing the process of a new master's election:" +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:25 +msgid "2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 I> can't read row\n" +"2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 24, aka 127.0.0.1:55687, peer of 127.0.0.1:3302: Broken pipe\n" +"2023-12-04 13:16:56.340 [16615] main/111/applier/replicator@127.0.0.1:3302 I> will retry every 1.00 second\n" +"2023-12-04 13:16:56.340 [16615] relay/127.0.0.1:55695/101/main coio.c:349 E> SocketError: unexpected EOF when reading from socket, called on fd 25, aka 127.0.0.1:3301, peer of 127.0.0.1:55695: Broken pipe\n" +"2023-12-04 13:16:56.340 [16615] relay/127.0.0.1:55695/101/main I> exiting the relay loop\n" +"2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: message {term: 3, vote: 2, state: candidate, vclock: {1: 9}} from 2\n" +"2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: received a newer term from 2\n" +"2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: bump term to 3, follow\n" +"2023-12-04 13:16:59.690 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: vote for 2, follow\n" +"2023-12-04 13:16:59.691 [16615] main/119/raft_worker I> RAFT: persisted state {term: 3}\n" +"2023-12-04 13:16:59.691 [16615] main/119/raft_worker I> RAFT: persisted state {term: 3, vote: 2}\n" +"2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: message {term: 3, vote: 2, leader: 2, state: leader} from 2\n" +"2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: vote request is skipped - this is a notification about a vote for a third node, not a request\n" +"2023-12-04 13:16:59.691 [16615] main/112/applier/replicator@127.0.0.1:3303 I> RAFT: leader is 2, follow" +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:44 +msgid "The master's upstream status is reported as ``disconnected`` when executing :ref:`box.info.replication ` on a replica:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:3 +msgid "auto_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 32\n" +" upstream:\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00032305717468262\n" +" status: disconnected\n" +" idle: 48.352504000002\n" +" message: 'connect, called on fd 20, aka 127.0.0.1:62575: Connection refused'\n" +" system_message: Connection refused\n" +" name: instance002\n" +" downstream:\n" +" status: stopped\n" +" message: 'unexpected EOF when reading from socket, called on fd 32, aka 127.0.0.1:3301,\n" +" peer of 127.0.0.1:62204: Broken pipe'\n" +" system_message: Broken pipe\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 1\n" +" name: instance001\n" +" 3:\n" +" id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.18620999999985\n" +" peer: replicator@127.0.0.1:3303\n" +" lag: 0.00012516975402832\n" +" name: instance003\n" +" downstream:\n" +" status: follow\n" +" idle: 0.19718099999955\n" +" vclock: {2: 1, 1: 32}\n" +" lag: 0.00051403045654297\n" +"..." +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:51 +msgid "To learn how to perform manual failover in a master-replica set, see the :ref:`Performing manual failover ` section." +msgstr "" + +#: ../../doc/book/admin/replication/repl_recover.rst:53 +msgid "In a master-replica configuration with automated failover, a new master should be elected :ref:`automatically `." +msgstr "" diff --git a/locale/en/admin/replication/repl_reseed.pot b/locale/en/admin/replication/repl_reseed.pot new file mode 100644 index 0000000000..608d998130 --- /dev/null +++ b/locale/en/admin/replication/repl_reseed.pot @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/replication/repl_reseed.rst:5 +msgid "Reseeding a replica" +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:7 +msgid "If any of a replica's write-ahead log or snapshot files are corrupted or deleted, you can reseed the replica. This procedure works only if the master's write-ahead logs are present." +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:10 +msgid "Stop the replica using the :ref:`tt stop ` command." +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:12 +msgid "Delete write-ahead logs and snapshots stored in the ``var/lib/`` directory." +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:16 +msgid "``var/lib`` is the default directory used by tt to store write-ahead logs and snapshots. Learn more from :ref:`Configuration `." +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:19 +msgid "Start the replica using the :ref:`tt start ` command. The replica should catch up with the master by retrieving all the master's tuples." +msgstr "" + +#: ../../doc/book/admin/replication/repl_reseed.rst:22 +msgid "(Optional) If you're reseeding a replica after a replication conflict, you also need to :ref:`restart replication `." +msgstr "" diff --git a/locale/en/admin/security.pot b/locale/en/admin/security.pot new file mode 100644 index 0000000000..df75497222 --- /dev/null +++ b/locale/en/admin/security.pot @@ -0,0 +1,114 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/security.rst:5 +msgid "Security" +msgstr "" + +#: ../../doc/book/admin/security.rst:7 +msgid "Tarantool allows for two types of connections:" +msgstr "" + +#: ../../doc/book/admin/security.rst:9 +msgid "With :ref:`console.listen() ` function from ``console`` module, you can set up a port which can be used to open an administrative console to the server. This is for administrators to connect to a running instance and make requests. ``tt`` invokes ``console.listen()`` to create a control socket for each started instance." +msgstr "" + +#: ../../doc/book/admin/security.rst:15 +msgid "With :ref:`box.cfg{listen=...} ` parameter from ``box`` module, you can set up a binary port for connections which read and write to the database or invoke stored procedures." +msgstr "" + +#: ../../doc/book/admin/security.rst:19 +msgid "When you connect to an admin console:" +msgstr "" + +#: ../../doc/book/admin/security.rst:21 +msgid "The client-server protocol is plain text." +msgstr "" + +#: ../../doc/book/admin/security.rst:22 +msgid "No password is necessary." +msgstr "" + +#: ../../doc/book/admin/security.rst:23 +msgid "The user is automatically 'admin'." +msgstr "" + +#: ../../doc/book/admin/security.rst:24 +msgid "Each command is fed directly to the built-in Lua interpreter." +msgstr "" + +#: ../../doc/book/admin/security.rst:26 +msgid "Therefore you must set up ports for the admin console very cautiously. If it is a TCP port, it should only be opened for a specific IP. Ideally, it should not be a TCP port at all, it should be a Unix domain socket, so that access to the server machine is required. Thus a typical port setup for admin console is:" +msgstr "" + +#: ../../doc/book/admin/security.rst:31 +msgid "console.listen('/var/lib/tarantool/socket_name.sock')" +msgstr "" + +#: ../../doc/book/admin/security.rst:35 +msgid "and a typical connection :ref:`URI ` is:" +msgstr "" + +#: ../../doc/book/admin/security.rst:37 +msgid "/var/lib/tarantool/socket_name.sock" +msgstr "" + +#: ../../doc/book/admin/security.rst:41 +msgid "if the listener has the privilege to write on ``/var/lib/tarantool`` and the connector has the privilege to read on ``/var/lib/tarantool``. Alternatively, to connect to an admin console of an instance started with ``tt``, use :ref:`tt connect `." +msgstr "" + +#: ../../doc/book/admin/security.rst:46 +msgid "To find out whether a TCP port is a port for admin console, use ``telnet``. For example:" +msgstr "" + +#: ../../doc/book/admin/security.rst:49 +msgid "$ telnet 0 3303\n" +"Trying 0.0.0.0...\n" +"Connected to 0.\n" +"Escape character is '^]'.\n" +"Tarantool 2.1.0 (Lua console)\n" +"type 'help' for interactive help" +msgstr "" + +#: ../../doc/book/admin/security.rst:58 +msgid "In this example, the response does not include the word \"binary\" and does include the words \"Lua console\". Therefore it is clear that this is a successful connection to a port for admin console, and you can now enter admin requests on this terminal." +msgstr "" + +#: ../../doc/book/admin/security.rst:63 +msgid "When you connect to a binary port:" +msgstr "" + +#: ../../doc/book/admin/security.rst:65 +msgid "The client-server protocol is :ref:`binary `." +msgstr "" + +#: ../../doc/book/admin/security.rst:66 +msgid "The user is automatically ':ref:`guest `'." +msgstr "" + +#: ../../doc/book/admin/security.rst:67 +msgid "To change the user, it’s necessary to authenticate." +msgstr "" + +#: ../../doc/book/admin/security.rst:69 +msgid "For ease of use, ``tt connect`` command automatically detects the type of connection during handshake and uses :ref:`EVAL ` binary protocol command when it’s necessary to execute Lua commands over a binary connection. To execute EVAL, the authenticated user must have global \"EXECUTE\" privilege." +msgstr "" + +#: ../../doc/book/admin/security.rst:75 +msgid "Therefore, when ``ssh`` access to the machine is not available, creating a Tarantool user with global \"EXECUTE\" privilege and non-empty password can be used to provide a system administrator **remote** access to an instance." +msgstr "" diff --git a/locale/en/admin/server_introspection.pot b/locale/en/admin/server_introspection.pot new file mode 100644 index 0000000000..b3ecbfa553 --- /dev/null +++ b/locale/en/admin/server_introspection.pot @@ -0,0 +1,765 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/server_introspection.rst:4 +msgid "Server introspection" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:9 +msgid "Using Tarantool as a client" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:11 +msgid "Tarantool enters the interactive mode if:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:13 +msgid "you start Tarantool without an :ref:`instance file `, or" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:16 +msgid "the instance file contains :ref:`console.start() `." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:18 +msgid "Tarantool displays a prompt (e.g. \"tarantool>\") and you can enter requests. When used this way, Tarantool can be a client for a remote server. See basic examples in :ref:`Getting started `." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:22 +msgid "The interactive mode is used in the ``tt`` utility's :ref:`connect ` command." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:27 +msgid "Executing code on an instance" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:29 +msgid "You can attach to an instance's :ref:`admin console ` and execute some Lua code using ``tt``:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:32 +msgid "$ # for local instances:\n" +"$ tt connect my_app\n" +" • Connecting to the instance...\n" +" • Connected to /var/run/tarantool/example.control\n" +"\n" +"/var/run/tarantool/my_app.control> 1 + 1\n" +"---\n" +"- 2\n" +"...\n" +"/var/run/tarantool/my_app.control>\n" +"\n" +"$ # for local and remote instances:\n" +"$ tt connect username:password@127.0.0.1:3306" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:48 +msgid "You can also use ``tt`` to execute Lua code on an instance without attaching to its admin console. For example:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:51 +msgid "$ # executing commands directly from the command line\n" +"$ | tt connect my_app -f -\n" +"<...>\n" +"\n" +"$ # - OR -\n" +"\n" +"$ # executing commands from a script file\n" +"$ tt connect my_app -f script.lua\n" +"<...>" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:65 +msgid "Alternatively, you can use the :ref:`console ` module or the :ref:`net.box ` module from a Tarantool server. Also, you can write your client programs with any of the :ref:`connectors `. However, most of the examples in this manual illustrate usage with either ``tt connect`` or :ref:`using the Tarantool server as a client `." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:75 +msgid "Health checks" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:77 +msgid "To check the instance status, run:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:79 +msgid "$ tt status my_app\n" +"INSTANCE STATUS PID\n" +"my_app RUNNING 67172\n" +"\n" +"$ # - OR -\n" +"\n" +"$ systemctl status tarantool@my_app" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:89 +msgid "To check the boot log, on systems with ``systemd``, run:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:91 +msgid "$ journalctl -u tarantool@my_app -n 5" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:95 +msgid "For more specific checks, use the reports provided by functions in the following submodules:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:97 +msgid ":doc:`/reference/reference_lua/box_cfg` (check and specify all configuration parameters for the Tarantool server)" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:100 +msgid ":doc:`/reference/reference_lua/box_slab` (monitor the total use and fragmentation of memory allocated for storing data in Tarantool)" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:103 +msgid ":doc:`/reference/reference_lua/box_info` (introspect Tarantool server variables, primarily those related to replication)" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:106 +msgid ":doc:`/reference/reference_lua/box_stat` (introspect Tarantool request and network statistics)" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:109 +msgid "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." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:114 +#: ../../doc/book/admin/server_introspection.rst:662 +msgid "**Example**" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:116 +msgid "A very popular administrator request is :doc:`/reference/reference_lua/box_slab/slab_info`, which displays detailed memory usage statistics for a Tarantool instance." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:120 +msgid "tarantool> box.slab.info()\n" +"---\n" +"- items_size: 228128\n" +" items_used_ratio: 1.8%\n" +" quota_size: 1073741824\n" +" quota_used_ratio: 0.8%\n" +" arena_used_ratio: 43.2%\n" +" items_used: 4208\n" +" quota_used: 8388608\n" +" arena_size: 2325176\n" +" arena_used: 1003632\n" +"..." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:135 +msgid "Tarantool takes memory from the operating system, for example when a user does many insertions. You can see how much it has taken by saying (on Linux):" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:139 +msgid "ps -eo args,%mem | grep \"tarantool\"" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:143 +msgid "Tarantool almost never releases this memory, even if the user deletes everything that was inserted, or reduces fragmentation by calling the Lua garbage collector via the `collectgarbage function `_." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:148 +msgid "Ordinarily this does not affect performance. But, to force Tarantool to release memory, you can call :doc:`box.snapshot() `, stop the server instance, and restart it." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:156 +msgid "Inspect traffic" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:158 +msgid "Inspecting binary traffic is a boring task. We offer a `Wireshark plugin `_ to simplify the analysis of Tarantool's traffic." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:162 +msgid "To enable the plugin, follow the steps below." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:164 +msgid "Clone the tarantool-dissector repository:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:166 +msgid "git clone https://github.com/tarantool/tarantool-dissector.git" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:170 +msgid "Copy or symlink the plugin files into the Wireshark plugin directory:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:172 +msgid "mkdir -p ~/.local/lib/wireshark/plugins\n" +"cd ~/.local/lib/wireshark/plugins\n" +"ln -s /path/to/tarantool-dissector/MessagePack.lua ./\n" +"ln -s /path/to/tarantool-dissector/tarantool.dissector.lua ./" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:179 +msgid "(For the location of the plugin directory on macOS and Windows, please refer to the `Plugin folders `_ chapter in the Wireshark documentation.)" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:183 +msgid "Run the Wireshark GUI and ensure that the plugins are loaded:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:185 +msgid "Open :guilabel:`Help` > :guilabel:`About Wireshark` > :guilabel:`Plugins`." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:186 +msgid "Find ``MessagePack.lua`` and ``tarantool.dissector.lua`` in the list." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:188 +msgid "Now you can inspect incoming and outgoing Tarantool packets with user-friendly annotations." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:191 +msgid "Visit the project page for details: `https://github.com/tarantool/tarantool-dissector `_." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:197 +msgid "Profiling performance issues" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:199 +msgid "Tarantool can at times work slower than usual. There can be multiple reasons, such as disk issues, CPU-intensive Lua scripts or misconfiguration. Tarantool’s log may lack details in such cases, so the only indications that something goes wrong are log entries like this: ``W> too long DELETE: 8.546 sec``. Here are tools and techniques that can help you collect Tarantool’s performance profile, which is helpful in troubleshooting slowdowns." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:208 +msgid "Most of these tools -- except ``fiber.info()`` -- are intended for generic GNU/Linux distributions, but not FreeBSD or Mac OS." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:212 +msgid "fiber.info()" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:214 +msgid "The simplest profiling method is to take advantage of Tarantool’s built-in functionality. :ref:`fiber.info() ` returns information about all running fibers with their corresponding C stack traces. You can use this data to see how many fibers are running and which C functions are executed more often than others." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:220 +msgid "First, enter your instance’s interactive administrator console:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:222 +#: ../../doc/book/admin/server_introspection.rst:500 +msgid "$ tt connect NAME|URI" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:226 +msgid "Once there, load the ``fiber`` module:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:228 +msgid "tarantool> fiber = require('fiber')" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:232 +msgid "After that you can get the required information with ``fiber.info()``." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:234 +msgid "At this point, your console output should look something like this:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:236 +msgid "tarantool> fiber = require('fiber')\n" +"---\n" +"...\n" +"tarantool> fiber.info()\n" +"---\n" +"- 360:\n" +" csw: 2098165\n" +" backtrace:\n" +" - '#0 0x4d1b77 in wal_write(journal*, journal_entry*)+487'\n" +" - '#1 0x4bbf68 in txn_commit(txn*)+152'\n" +" - '#2 0x4bd5d8 in process_rw(request*, space*, tuple**)+136'\n" +" - '#3 0x4bed48 in box_process1+104'\n" +" - '#4 0x4d72f8 in lbox_replace+120'\n" +" - '#5 0x50f317 in lj_BC_FUNCC+52'\n" +" fid: 360\n" +" memory:\n" +" total: 61744\n" +" used: 480\n" +" name: main\n" +" 129:\n" +" csw: 113\n" +" backtrace: []\n" +" fid: 129\n" +" memory:\n" +" total: 57648\n" +" used: 0\n" +" name: 'console/unix/:'\n" +"..." +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:267 +msgid "We highly recommend to assign meaningful names to fibers you create so that you can find them in the ``fiber.info()`` list. In the example below, we create a fiber named ``myworker``:" +msgstr "" + +#: ../../doc/book/admin/server_introspection.rst:271 +msgid "tarantool> fiber = require('fiber')\n" +"---\n" +"...\n" +"tarantool> f = fiber.create(function() while true do fiber.sleep(0.5) end end)\n" +"---\n" +"...\n" +"tarantool> f:name('myworker') \n" +"+-------+=============+\n" +"| scale | BCD |\n" +"+-------+=============+" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:53 +msgid "Here ``scale`` is either ``MP_INT`` or ``MP_UINT``. |br| ``scale`` = number of digits after the decimal point" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:56 +msgid "``BCD`` is a sequence of bytes representing decimal digits of the encoded number (each byte has two decimal digits each encoded using 4-bit ``nibbles``), so ``byte >> 4`` is the first digit and ``byte & 0x0f`` is the second digit. The leftmost digit in the array is the most significant. The rightmost digit in the array is the least significant." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:62 +msgid "The first byte of the ``BCD`` array contains the first digit of the number, represented as follows:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:65 +msgid "| 4 bits | 4 bits |\n" +" = 0x = the 1st digit" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:70 +msgid "(The first ``nibble`` contains 0 if the decimal number has an even number of digits.) The last byte of the ``BCD`` array contains the last digit of the number and the final ``nibble``, represented as follows:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:74 +msgid "| 4 bits | 4 bits |\n" +" = the last digit = nibble" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:79 +msgid "The final ``nibble`` represents the number's sign:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:81 +msgid "``0x0a``, ``0x0c``, ``0x0e``, ``0x0f`` stand for plus," +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:82 +msgid "``0x0b`` and ``0x0d`` stand for minus." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:84 +msgid "**Examples**" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:86 +msgid "The decimal ``-12.34`` will be encoded as ``0xd6,0x01,0x02,0x01,0x23,0x4d``:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:88 +msgid "|MP_EXT (fixext 4) | MP_DECIMAL | scale | 1 | 2,3 | 4 (minus) |\n" +"| 0xd6 | 0x01 | 0x02 | 0x01 | 0x23 | 0x4d |" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:93 +msgid "The decimal 0.000000000000000000000000000000000010 will be encoded as ``0xc7,0x03,0x01,0x24,0x01,0x0c``:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:96 +msgid "| MP_EXT (ext 8) | length | MP_DECIMAL | scale | 1 | 0 (plus) |\n" +"| 0xc7 | 0x03 | 0x01 | 0x24 | 0x01 | 0x0c |" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:106 +msgid "The UUID type" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:108 +msgid "The MessagePack EXT type ``MP_EXT`` together with the extension type ``MP_UUID`` for values of the UUID type. Since version :doc:`2.4.1 `." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:111 +msgid "``MP_UUID`` type is 2." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:113 +msgid "The `MessagePack specification `_ defines ``d8`` to mean ``fixext`` with size 16, and a UUID's size is always 16. So the UUID MessagePack representation looks like this:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:117 +msgid "+--------+------------+-----------------+\n" +"| MP_EXT | MP_UUID | UuidValue |\n" +"| = d8 | = 2 | = 16-byte value |\n" +"+--------+------------+-----------------+" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:124 +msgid "The 16-byte value has 2 digits per byte. Typically, it consists of 11 fields, which are encoded as big-endian unsigned integers in the following order:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:128 +msgid "``time_low`` (4 bytes)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:129 +msgid "``time_mid`` (2 bytes)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:130 +msgid "``time_hi_and_version`` (2 bytes)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:131 +msgid "``clock_seq_hi_and_reserved`` (1 byte)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:132 +msgid "``clock_seq_low`` (1 byte)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:133 +msgid "``node[0]``, ..., ``node[5]`` (1 byte each)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:135 +msgid "Some of the functions in :ref:`Module uuid ` can produce values which are compatible with the UUID data type. For example, after" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:139 +msgid "uuid = require('uuid')\n" +"box.schema.space.create('t')\n" +"box.space.t:create_index('i', {parts={1,'uuid'}})\n" +"box.space.t:insert{uuid.fromstr('f6423bdf-b49e-4913-b361-0740c9702e4b')}\n" +"box.space.t:select()" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:147 +msgid "a peek at the server response packet will show that it contains" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:149 +msgid "d8 02 f6 42 3b df b4 9e 49 13 b3 61 07 40 c9 70 2e 4b" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:157 +msgid "The ERROR type" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:159 +msgid "Since version :doc:`2.4.1 `, responses for errors have extra information following what was described in :ref:`Box protocol -- responses for errors `. This is a \"compatible\" enhancement, because clients that expect old-style server responses should ignore map components that they do not recognize. Notice, however, that there has been a renaming of a constant: formerly ``IPROTO_ERROR`` in :file:`./box/iproto_constants.h` was ``0x31``, now ``IPROTO_ERROR`` is ``0x52`` and ``IPROTO_ERROR_24`` is ``0x31``." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:168 +msgid "``MP_ERROR`` type is 3." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:170 +msgid "++=========================+============================+\n" +"|| | |\n" +"|| 0x31: IPROTO_ERROR_24 | 0x52: IPROTO_ERROR |\n" +"|| MP_INT: MP_STRING | MP_MAP: extra information |\n" +"|| | |\n" +"++=========================+============================+\n" +" MP_MAP" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:180 +msgid "The extra information, most of which is also in :doc:`error object ` fields, is:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:183 +msgid "``MP_ERROR_TYPE`` (0x00) (MP_STR) Type that implies source, as in :samp:`{error_object}.base_type`, for example \"ClientError\"." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:185 +msgid "``MP_ERROR_FILE`` (0x01) (MP_STR) Source code file where error was caught, as in :samp:`{error_object}.trace`." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:187 +msgid "``MP_ERROR_LINE`` (0x02) (MP_UINT) Line number in source code file, as in :samp:`{error_object}.trace`." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:189 +msgid "``MP_ERROR_MESSAGE`` (0x03) (MP_STR) Text of reason, as in :samp:`{error_object}.message`. The value here will be the same as in the ``IPROTO_ERROR_24`` value." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:192 +msgid "``MP_ERROR_ERRNO`` (0x04) (MP_UINT) Ordinal number of the error, as in :samp:`{error_object}.errno`. Not to be confused with ``MP_ERROR_ERRCODE``." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:195 +msgid "``MP_ERROR_ERRCODE`` (0x05) (MP_UINT) Number of the error as defined in errcode.h, as in :samp:`{error_object}.code`, which can also be retrieved with the C function :ref:`box_error_code() `. The value here will be the same as the lower part of the Response-Code-Indicator value." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:199 +msgid "``MP_ERROR_FIELDS`` (0x06) (MP_MAPs) Additional fields depending on error type. For example, if ``MP_ERROR_TYPE`` is \"AccessDeniedError\", then ``MP_ERROR_FIELDS`` will include \"object_type\", \"object_name\", \"access_type\". This field will be omitted from the response body if there are no additional fields available." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:204 +msgid "Client and connector programmers should ensure that unknown map keys are ignored, and should check for addition of new keys in the Tarantool source code file where error object creation is defined. In version 2.4.1 the name of this source code file is mp_error.cc." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:209 +msgid "For example, in version 2.4.1 or later, if we try to create a duplicate space with |br| ``conn:eval([[box.schema.space.create('_space');]])`` |br| the server response will look like this:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:213 +msgid "ce 00 00 00 88 MP_UINT = HEADER + BODY SIZE\n" +"83 MP_MAP, size 3 (i.e. 3 items in header)\n" +" 00 Response-Code-Indicator\n" +" ce 00 00 80 0a MP_UINT = hexadecimal 800a\n" +" 01 IPROTO_SYNC\n" +" cf 00 00 00 00 00 00 00 05 MP_UINT = sync value\n" +" 05 IPROTO_SCHEMA_VERSION\n" +" ce 00 00 00 4e MP_UINT = schema version value\n" +"82 MP_MAP, size 2\n" +" 31 IPROTO_ERROR_24\n" +" bd 53 70 61 63 etc. MP_STR = \"Space '_space' already exists\"\n" +" 52 IPROTO_ERROR\n" +" 81 MP_MAP, size 1\n" +" 00 MP_ERROR_STACK\n" +" 91 MP_ARRAY, size 1\n" +" 86 MP_MAP, size 6\n" +" 00 MP_ERROR_TYPE\n" +" ab 43 6c 69 65 6e 74 etc. MP_STR = \"ClientError\"\n" +" 02 MP_ERROR_LINE\n" +" cd MP_UINT = line number\n" +" 01 MP_ERROR_FILE\n" +" aa 01 b6 62 75 69 6c etc. MP_STR \"builtin/box/schema.lua\"\n" +" 03 MP_ERROR_MESSAGE\n" +" bd 53 70 61 63 65 20 etc. MP_STR = Space.'_space'.already.exists\"\n" +" 04 MP_ERROR_ERRNO\n" +" 00 MP_UINT = error number\n" +" 05 MP_ERROR_ERRCODE\n" +" 0a MP_UINT = error code ER_SPACE_EXISTS" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:249 +msgid "The DATETIME type" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:251 +msgid "Since version :doc:`2.10.0 `. The MessagePack EXT type ``MP_EXT`` together with the extension type ``MP_DATETIME`` is a header for values of the DATETIME type. It creates a container with a payload of 8 or 16 bytes." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:256 +msgid "``MP_DATETIME`` type is 4." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:258 +msgid "The `MessagePack specification `_ defines ``d7`` to mean ``fixext`` with size 8 or ``d8`` to mean ``fixext`` with size 16." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:261 +msgid "So the datetime MessagePack representation looks like this:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:263 +msgid "+---------+----------------+==========+-----------------+\n" +"| MP_EXT | MP_DATETIME | seconds | nsec; tzoffset; |\n" +"| = d7/d8 | = 4 | | tzindex; |\n" +"+---------+----------------+==========+-----------------+" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:270 +msgid "MessagePack data contains:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:272 +msgid "Seconds (8 bytes) as an unencoded 64-bit signed integer stored in the little-endian order." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:274 +msgid "The optional fields (8 bytes), if any of them have a non-zero value. The fields include ``nsec``, ``tzoffset``, and ``tzindex`` packed in the little-endian order." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:277 +msgid "For more information about the datetime type, see :ref:`datetime field type details ` and :doc:`reference for the datetime module `." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:284 +msgid "The INTERVAL type" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:286 +msgid "Since version :doc:`2.10.0 `. The MessagePack EXT type ``MP_EXT`` together with the extension type ``MP_INTERVAL`` is a header for values of the INTERVAL type." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:290 +msgid "``MP_INTERVAL`` type is 6." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:292 +msgid "The interval is saved as a variant of a map with a predefined number of known attribute names. If some attributes are undefined, they are omitted from the generated payload." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:295 +msgid "The interval MessagePack representation looks like this:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:297 +msgid "+--------+-------------------------+-------------+----------------+\n" +"| MP_EXT | Size of packed interval | MP_INTERVAL | PackedInterval |\n" +"+--------+-------------------------+-------------+----------------+" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:303 +msgid "Packed interval consists of:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:305 +msgid "Packed number of non-zero fields." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:306 +msgid "Packed non-null fields." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:308 +msgid "Each packed field has the following structure:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:310 +msgid "+----------+=====================+\n" +"| field ID | field value |\n" +"+----------+=====================+" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:316 +msgid "The number of defined (non-null) fields can be zero. In this case, the packed interval will be encoded as integer 0." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:319 +msgid "List of the field IDs:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:321 +msgid "0 -- year" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:322 +msgid "1 -- month" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:323 +msgid "2 -- week" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:324 +msgid "3 -- day" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:325 +msgid "4 -- hour" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:326 +msgid "5 -- minute" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:327 +msgid "6 -- second" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:328 +msgid "7 -- nanosecond" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:329 +msgid "8 -- adjust" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:331 +msgid "**Example**" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:333 +msgid "Interval value ``1 years, 200 months, -77 days`` is encoded in the following way:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:335 +msgid "tarantool> I = datetime.interval.new{year = 1, month = 200, day = -77}\n" +"---\n" +"...\n" +"\n" +"tarantool> I\n" +"---\n" +"- +1 years, 200 months, -77 days\n" +"...\n" +"\n" +"tarantool> M = msgpack.encode(I)\n" +"---\n" +"...\n" +"\n" +"tarantool> M\n" +"---\n" +"- !!binary xwsGBAABAczIA9CzCAE=\n" +"...\n" +"\n" +"tarantool> tohex = function(s) return (s:gsub('.', function(c) return string.format('%02X ', string.byte(c)) end)) end\n" +"---\n" +"...\n" +"\n" +"tarantool> tohex(M)\n" +"---\n" +"- 'C7 0B 06 04 00 01 01 CC C8 03 D0 B3 08 01 '\n" +"..." +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:364 +msgid "Where:" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:366 +msgid "C7 -- MP_EXT" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:367 +msgid "0B -- size of a packed interval value (11 bytes)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:368 +msgid "06 -- MP_INTERVAL type" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:369 +msgid "04 -- number of defined fields" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:370 +msgid "00 -- field ID (year)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:371 +msgid "01 -- packed value ``1``" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:372 +msgid "01 -- field ID (month)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:373 +msgid "CCC8 -- packed value ``200``" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:374 +msgid "03 -- field ID (day)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:375 +msgid "D0B3 -- packed value ``-77``" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:376 +msgid "08 -- field ID (adjust)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:377 +msgid "01 -- packed value ``1`` (DT_LIMIT)" +msgstr "" + +#: ../../doc/dev_guide/internals/msgpack_extensions.rst:379 +msgid "For more information about the interval type, see :ref:`interval field type details ` and :doc:`description of the datetime module `." +msgstr "" diff --git a/locale/en/dev_guide/internals/recovery_internals.pot b/locale/en/dev_guide/internals/recovery_internals.pot new file mode 100644 index 0000000000..1e5b9e755d --- /dev/null +++ b/locale/en/dev_guide/internals/recovery_internals.pot @@ -0,0 +1,81 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:5 +msgid "The recovery process" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:7 +msgid "The recovery process begins when ``box.cfg{}`` happens for the first time after the Tarantool server instance starts." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:10 +msgid "The recovery process must recover the databases as of the moment when the instance was last shut down. For this it may use the latest snapshot file and any WAL files that were written after the snapshot. One complicating factor is that Tarantool has two engines -- the memtx data must be reconstructed entirely from the snapshot and the WAL files, while the vinyl data will be on disk but might require updating around the time of a checkpoint. (When a snapshot happens, Tarantool tells the vinyl engine to make a checkpoint, and the snapshot operation is rolled back if anything goes wrong, so vinyl's checkpoint is at least as fresh as the snapshot file.)" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:22 +msgid "**Step 1**" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:24 +msgid "Read the configuration parameters in the ``box.cfg{}`` request. Parameters which affect recovery may include :ref:`work_dir `, :ref:`wal_dir `, :ref:`memtx_dir `, :ref:`vinyl_dir ` and :ref:`force_recovery `." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:30 +msgid "**Step 2**" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:32 +msgid "Find the latest snapshot file. Use its data to reconstruct the in-memory databases. Instruct the vinyl engine to recover to the latest checkpoint." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:35 +msgid "There are actually two variations of the reconstruction procedure for memtx databases, depending on whether the recovery process is \"default\"." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:38 +msgid "If the recovery process is default (``force_recovery`` is ``false``), memtx can read data in the snapshot with all indexes disabled. First, all tuples are read into memory. Then, primary keys are built in bulk, taking advantage of the fact that the data is already sorted by primary key within each space." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:44 +msgid "If the recovery process is non-default (``force_recovery`` is ``true``), Tarantool performs additional checking. Indexes are enabled at the start, and tuples are added one by one. This means that any unique-key constraint violations will be caught, and any duplicates will be skipped. Normally there will be no constraint violations or duplicates, so these checks are only made if an error has occurred." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:51 +msgid "**Step 3**" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:53 +msgid "Find the WAL file that was made at the time of, or after, the snapshot file. Read its log entries until the log-entry LSN is greater than the LSN of the snapshot, or greater than the LSN of the vinyl checkpoint. This is the recovery process's \"start position\"; it matches the current state of the engines." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:59 +msgid "**Step 4**" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:61 +msgid "Redo the log entries, from the start position to the end of the WAL. The engine skips a redo instruction if it is older than the engine's checkpoint." +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:64 +msgid "**Step 5**" +msgstr "" + +#: ../../doc/dev_guide/internals/recovery_internals.rst:66 +msgid "For the memtx engine, re-create all secondary indexes." +msgstr "" diff --git a/locale/en/dev_guide/internals/replication/index.pot b/locale/en/dev_guide/internals/replication/index.pot new file mode 100644 index 0000000000..a364b84f00 --- /dev/null +++ b/locale/en/dev_guide/internals/replication/index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/internals/replication/index.rst:7 +msgid "Replication internals" +msgstr "" diff --git a/locale/en/dev_guide/internals/replication/orphan.pot b/locale/en/dev_guide/internals/replication/orphan.pot new file mode 100644 index 0000000000..9cc79d5f8d --- /dev/null +++ b/locale/en/dev_guide/internals/replication/orphan.pot @@ -0,0 +1,153 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:5 +msgid "Orphan status" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:7 +msgid "Starting with Tarantool version 1.9, there is a change to the procedure when an instance joins a replica set. During ``box.cfg()`` the instance tries to join all nodes listed in :ref:`box.cfg.replication `. If the instance does not succeed with connecting to the required number of nodes (see :ref:`bootstrap_strategy `), it switches to the **orphan** status. While an instance is in orphan status, it is read-only." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:16 +msgid "To \"join\" a master, a replica instance must \"connect\" to the master node and then \"sync\"." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:19 +msgid "\"Connect\" means contact the master over the physical network and receive acknowledgment. If there is no acknowledgment after :ref:`box.replication_connect_timeout ` seconds (usually 4 seconds), and retries fail, then the connect step fails." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:24 +msgid "\"Sync\" means receive updates from the master in order to make a local database copy. Syncing is complete when the replica has received all the updates, or at least has received enough updates that the replica's lag (see :ref:`replication.upstream.lag ` in ``box.info()``) is less than or equal to the number of seconds specified in :ref:`box.cfg.replication_sync_lag `. If ``replication_sync_lag`` is unset (nil) or set to TIMEOUT_INFINITY, then the replica skips the \"sync\" state and switches to \"follow\" immediately." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:36 +msgid "In order to leave orphan mode, you need to sync with a sufficient number of instances (:ref:`bootstrap_strategy `). To do so, you may either:" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:40 +msgid "Reset ``box.cfg.replication`` to exclude instances that cannot be reached or synced with." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:42 +msgid "Set ``box.cfg.replication`` to ``\"\"`` (empty string)." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:44 +msgid "The following situations are possible." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:48 +msgid "**Situation 1: bootstrap**" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:50 +msgid "Here ``box.cfg{}`` is being called for the first time. A replica is joining but no replica set exists yet." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:53 +msgid "Set the status to 'orphan'." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:55 +msgid "Try to connect to all nodes from ``box.cfg.replication``. The replica tries to connect for the :ref:`replication_connect_timeout ` number of seconds and retries each :ref:`replication_timeout ` seconds if needed." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:61 +msgid "Abort and throw an error if a replica is not connected to the majority of nodes in ``box.cfg.replication``." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:63 +msgid "This instance might be elected as the replica set 'leader'. Criteria for electing a leader include vclock value (largest is best), and whether it is read-only or read-write (read-write is best unless there is no other choice). The leader is the master that other instances must join. The leader is the master that executes :doc:`box.once() ` functions." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:70 +msgid "If this instance is elected as the replica set leader, then perform an \"automatic bootstrap\":" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:74 +msgid "Set status to 'running'." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:75 +msgid "Return from ``box.cfg{}``." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:77 +msgid "Otherwise this instance will be a replica joining an existing replica set, so:" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:80 +msgid "Bootstrap from the leader. See examples in section :ref:`Bootstrapping a replica set `." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:82 +msgid "In background, sync with all the other nodes in the replication set." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:84 +msgid "**Situation 2: recovery**" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:86 +msgid "Here ``box.cfg{}`` is not being called for the first time. It is being called again in order to perform recovery." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:89 +msgid "Perform :ref:`recovery ` from the last local snapshot and the WAL files." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:92 +msgid "Try to establish connections to all other nodes for the :ref:`replication_connect_timeout ` number of seconds. Once ``replication_connect_timeout`` is expired or all the connections are established, proceed to the \"sync\" state with all the established connections." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:96 +msgid "If connected, sync with all connected nodes, until the difference is not more than :ref:`replication_sync_lag ` seconds." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:101 +msgid "**Situation 3: configuration update**" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:103 +msgid "Here ``box.cfg{}`` is not being called for the first time. It is being called again because some replication parameter or something in the replica set has changed." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:107 +msgid "Try to connect to all nodes from ``box.cfg.replication``, within the time period specified in :ref:`replication_connect_timeout `." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:111 +msgid "Try to sync with the connected nodes, within the time period specified in :ref:`replication_sync_timeout `." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:115 +msgid "If earlier steps fail, change status to 'orphan'. (Attempts to sync will continue in the background and when/if they succeed then 'orphan' status will end.)" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:119 +msgid "If earlier steps succeed, set status to 'running' (master) or 'follow' (replica)." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:123 +msgid "**Situation 4: rebootstrap**" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/orphan.rst:125 +msgid "Here ``box.cfg{}`` is not being called. The replica connected successfully at some point in the past, and is now ready for an update from the master. But the master cannot provide an update. This can happen by accident, or more likely can happen because the replica is slow (its :ref:`lag ` is large), and the WAL (.xlog) files containing the updates have been deleted. This is not crippling. The replica can discard what it received earlier, and then ask for the master's latest snapshot (.snap) file contents. Since it is effectively going through the bootstrap process a second time, this is called \"rebootstrapping\". However, there has to be one difference from an ordinary bootstrap -- the replica's :ref:`replica id ` will remain the same. If it changed, then the master would think that the replica is a new addition to the cluster, and would maintain a record of an instance ID of a replica that has ceased to exist. Rebootstrapping was introduced in Tarantool version 1.10.2 and is completely automatic." +msgstr "" diff --git a/locale/en/dev_guide/internals/replication/replication_server_startup.pot b/locale/en/dev_guide/internals/replication/replication_server_startup.pot new file mode 100644 index 0000000000..bdb42e4a1d --- /dev/null +++ b/locale/en/dev_guide/internals/replication/replication_server_startup.pot @@ -0,0 +1,89 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:4 +msgid "Server startup with replication" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:6 +msgid "In addition to the recovery process described in the section :ref:`Recovery process `, the server must take additional steps and precautions if :ref:`replication ` is enabled." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:10 +msgid "Once again the startup procedure is initiated by the ``box.cfg{}`` request. One of the ``box.cfg`` parameters may be :ref:`replication ` which specifies replication source(-s). We will refer to this replica, which is starting up due to ``box.cfg``, as the \"local\" replica to distinguish it from the other replicas in a replica set, which we will refer to as \"distant\" replicas." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:17 +msgid "*If there is no snapshot .snap file and the* ``replication`` *parameter is empty and* ``cfg.read_only=false``: |br| then the local replica assumes it is an unreplicated \"standalone\" instance, or is the first replica of a new replica set. It will generate new UUIDs for itself and for the replica set. The replica UUID is stored in the ``_cluster`` space; the replica set UUID is stored in the ``_schema`` space. Since a snapshot contains all the data in all the spaces, that means the local replica's snapshot will contain the replica UUID and the replica set UUID. Therefore, when the local replica restarts on later occasions, it will be able to recover these UUIDs when it reads the .snap file." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:28 +msgid "*If there is no snapshot .snap file and the* ``replication`` *parameter is empty and* ``cfg.read_only=true``: |br| it cannot be the first replica of a new replica set because the first replica must be a master. Therefore an error message will occur: ER_BOOTSTRAP_READONLY. To avoid this, change the setting for this (local) instance to ``read_only = false``, or ensure that another (distant) instance starts first and has the local instance's UUID in its ``_cluster`` space. In the latter case, if ER_BOOTSTRAP_READONLY still occurs, set the local instance's :ref:`box.replication_connect_timeout ` to a larger value." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:39 +msgid "*If there is no snapshot .snap file and the* ``replication`` *parameter is not empty and the* ``_cluster`` *space contains no other replica UUIDs*: |br| then the local replica assumes it is not a standalone instance, but is not yet part of a replica set. It must now join the replica set. It will send its replica UUID to the first distant replica which is listed in ``replication`` and which will act as a master. This is called the \"join request\". When a distant replica receives a join request, it will send back:" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:47 +msgid "the distant replica's replica set UUID," +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:49 +msgid "the contents of the distant replica's .snap file. |br| When the local replica receives this information, it puts the replica set UUID in its ``_schema`` space, puts the distant replica's UUID and connection information in its ``_cluster`` space, and makes a snapshot containing all the data sent by the distant replica. Then, if the local replica has data in its WAL .xlog files, it sends that data to the distant replica. The distant replica will receive this and update its own copy of the data, and add the local replica's UUID to its ``_cluster`` space." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:58 +msgid "*If there is no snapshot .snap file and the* ``replication`` *parameter is not empty and the* ``_cluster`` *space contains other replica UUIDs*: |br| then the local replica assumes it is not a standalone instance, and is already part of a replica set. It will send its replica UUID and replica set UUID to all the distant replicas which are listed in ``replication``. This is called the \"on-connect handshake\". When a distant replica receives an on-connect handshake: |br|" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:65 +msgid "the distant replica compares its own copy of the replica set UUID to the one in the on-connect handshake. If there is no match, then the handshake fails and the local replica will display an error." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:69 +msgid "the distant replica looks for a record of the connecting instance in its ``_cluster`` space. If there is none, then the handshake fails. |br| Otherwise the handshake is successful. The distant replica will read any new information from its own .snap and .xlog files, and send the new requests to the local replica." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:75 +msgid "In the end, the local replica knows what replica set it belongs to, the distant replica knows that the local replica is a member of the replica set, and both replicas have the same database contents." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:81 +msgid "*If there is a snapshot file and replication source is not empty*: |br| first the local replica goes through the recovery process described in the previous section, using its own .snap and .xlog files. Then it sends a \"subscribe\" request to all the other replicas of the replica set. The subscribe request contains the server vector clock. The vector clock has a collection of pairs 'server id, lsn' for every replica in the ``_cluster`` system space. Each distant replica, upon receiving a subscribe request, will read its .xlog files' requests and send them to the local replica if (lsn of .xlog file request) is greater than (lsn of the vector clock in the subscribe request). After all the other replicas of the replica set have responded to the local replica's subscribe request, the replica startup is complete." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:93 +msgid "The following temporary limitations applied for Tarantool versions earlier than 1.7.7:" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:96 +msgid "The URIs in the ``replication`` parameter should all be in the same order on all replicas. This is not mandatory but is an aid to consistency." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:98 +msgid "The replicas of a replica set should be started up at slightly different times. This is not mandatory but prevents a situation where each replica is waiting for the other replica to be ready." +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:102 +msgid "The following limitation still applies for the current Tarantool version:" +msgstr "" + +#: ../../doc/dev_guide/internals/replication/replication_server_startup.rst:104 +msgid "The maximum number of entries in the ``_cluster`` space is :ref:`32 `. Tuples for out-of-date replicas are not automatically re-used, so if this 32-replica limit is reached, users may have to reorganize the ``_cluster`` space manually." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/box.pot b/locale/en/dev_guide/reference_capi/box.pot new file mode 100644 index 0000000000..009e1eea21 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/box.pot @@ -0,0 +1,585 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/box.rst:3 +msgid "Module box" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:7 +msgid "Opaque structure passed to a C stored procedure" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:13 +msgid "Return a tuple from a C stored procedure." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:15 +msgid "The returned tuple is automatically reference-counted by Tarantool. An example program that uses ``box_return_tuple()`` is :ref:`write.c `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:19 +#: ../../doc/dev_guide/reference_capi/box.rst:46 +msgid "an opaque structure passed to the C stored procedure by Tarantool" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:21 +msgid "a tuple to return" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:23 +#: ../../doc/dev_guide/reference_capi/box.rst:51 +msgid "-1 on error (perhaps, out of memory; check :ref:`box_error_last()`)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:25 +#: ../../doc/dev_guide/reference_capi/box.rst:53 +#: ../../doc/dev_guide/reference_capi/box.rst:106 +#: ../../doc/dev_guide/reference_capi/box.rst:123 +#: ../../doc/dev_guide/reference_capi/box.rst:139 +#: ../../doc/dev_guide/reference_capi/box.rst:160 +#: ../../doc/dev_guide/reference_capi/box.rst:181 +#: ../../doc/dev_guide/reference_capi/box.rst:204 +msgid "0 otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:32 +msgid "Return a pointer to a series of bytes in MessagePack format." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:34 +msgid "This can be used instead of :ref:`box_return_tuple() ` -- it can send the same value, but as MessagePack instead of as a tuple object. It may be simpler than ``box_return_tuple()`` when the result is small, for example a number or a boolean or a short string. It will also be faster than ``box_return_tuple()``, if the result is that users save time by not creating a tuple every time they want to return something from a C function." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:42 +msgid "On the other hand, if an already-existing tuple was obtained from an iterator, then it would be faster to return the tuple via ``box_return_tuple()`` rather than extracting its parts and sending them via ``box_return_mp()``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:48 +msgid "the first MessagePack byte" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:49 +msgid "after the last MessagePack byte" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:55 +msgid "For example, if ``mp`` is a buffer, and ``mp_end`` is a return value produced by encoding a single MP_UINT scalar value with ``mp_end=mp_encode_uint(mp,1);``, then ``box_return_mp(ctx,mp,mp_end);`` should return ``0``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:64 +msgid "Find space id by name." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:66 +msgid "This function performs a SELECT request on the ``_vspace`` system space." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:68 +msgid "space name" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:69 +#: ../../doc/dev_guide/reference_capi/box.rst:85 +msgid "length of ``name``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:71 +#: ../../doc/dev_guide/reference_capi/box.rst:87 +msgid ":c:macro:`BOX_ID_NIL` on error or if not found (check :ref:`box_error_last()`)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:73 +#: ../../doc/dev_guide/reference_capi/box.rst:89 +msgid "space_id otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:75 +msgid "See also: :c:type:`box_index_id_by_name`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:79 +msgid "Find index id by name." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:81 +msgid "This function performs a SELECT request on the ``_vindex`` system space." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:83 +#: ../../doc/dev_guide/reference_capi/box.rst:99 +#: ../../doc/dev_guide/reference_capi/box.rst:116 +#: ../../doc/dev_guide/reference_capi/box.rst:131 +#: ../../doc/dev_guide/reference_capi/box.rst:147 +#: ../../doc/dev_guide/reference_capi/box.rst:168 +#: ../../doc/dev_guide/reference_capi/box.rst:189 +msgid "space identifier" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:84 +msgid "index name" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:91 +msgid "See also: :c:type:`box_space_id_by_name`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:97 +msgid "Execute an INSERT/REPLACE request." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:100 +#: ../../doc/dev_guide/reference_capi/box.rst:117 +#: ../../doc/dev_guide/reference_capi/box.rst:170 +msgid "encoded tuple in MsgPack Array format ([ field1, field2, ...])" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:101 +#: ../../doc/dev_guide/reference_capi/box.rst:118 +#: ../../doc/dev_guide/reference_capi/box.rst:171 +msgid "end of a ``tuple``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:102 +#: ../../doc/dev_guide/reference_capi/box.rst:119 +msgid "output argument. Resulting tuple. Can be set to NULL to discard result" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:105 +#: ../../doc/dev_guide/reference_capi/box.rst:122 +#: ../../doc/dev_guide/reference_capi/box.rst:138 +#: ../../doc/dev_guide/reference_capi/box.rst:159 +#: ../../doc/dev_guide/reference_capi/box.rst:180 +#: ../../doc/dev_guide/reference_capi/box.rst:203 +msgid "-1 on error (check :ref:`box_error_last()`)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:108 +msgid "See also: :ref:`space_object.insert()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:114 +msgid "Execute a REPLACE request." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:125 +msgid "See also: :ref:`space_object.replace()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:129 +msgid "Execute a DELETE request." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:132 +#: ../../doc/dev_guide/reference_capi/box.rst:148 +#: ../../doc/dev_guide/reference_capi/box.rst:169 +msgid "index identifier" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:133 +#: ../../doc/dev_guide/reference_capi/box.rst:149 +msgid "encoded key in MsgPack Array format ([ field1, field2, ...])" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:134 +#: ../../doc/dev_guide/reference_capi/box.rst:150 +msgid "end of a ``key``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:135 +#: ../../doc/dev_guide/reference_capi/box.rst:156 +#: ../../doc/dev_guide/reference_capi/box.rst:177 +msgid "output argument. An old tuple. Can be set to NULL to discard result" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:141 +msgid "See also: :ref:`space_object.delete()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:145 +msgid "Execute an UPDATE request." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:151 +#: ../../doc/dev_guide/reference_capi/box.rst:172 +msgid "encoded operations in MsgPack Array format, e.g. ``[[ '=', field_id, value ], ['!', 2, 'xxx']]``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:153 +msgid "end of an ``ops`` section" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:154 +#: ../../doc/dev_guide/reference_capi/box.rst:175 +msgid "0 if field_ids are zero-based as in C, 1 if field ids are 1-based as in Lua" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:162 +msgid "See also: :ref:`space_object.update()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:166 +msgid "Execute an UPSERT request." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:174 +msgid "end of a ``ops``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:183 +msgid "See also: :ref:`space_object.upsert()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:187 +msgid "Truncate a space." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:195 +msgid "Since version :doc:`2.4.1 `. Push MessagePack data into a session data channel -- socket, console or whatever is behind the session. Behaves just like Lua :doc:`/reference/reference_lua/box_session/push`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:200 +msgid "begin of MessagePack to push" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:201 +msgid "end of MessagePack to push" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:210 +msgid "Since version :doc:`2.4.1 `. Return the last retrieved value of the specified sequence." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:213 +msgid "sequence identifier" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:214 +msgid "pointer to a variable where the current sequence value will be stored on success." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:217 +msgid "0 on success and -1 otherwise. In case of an error user could get it via ``box_error_last()``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:224 +msgid "Since version :doc:`2.11.0 `. Return the database schema version. A schema version is a number that indicates whether the :ref:`database schema ` is changed. For example, the ``schema_version`` value grows if a :ref:`space ` or :ref:`index ` is added or deleted, or a space, index, or field name is changed." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:230 +msgid "the database schema version" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +#: ../../doc/dev_guide/reference_capi/box.rst:0 +msgid "Return type" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:231 +#: ../../doc/dev_guide/reference_capi/box.rst:243 +#: ../../doc/dev_guide/reference_capi/box.rst:265 +#: ../../doc/dev_guide/reference_capi/box.rst:337 +msgid "number" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:233 +msgid "See also: :ref:`box.info.schema_version ` and :ref:`IPROTO_SCHEMA_VERSION `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:239 +msgid "Since version :doc:`2.11.0 `. Return the unique identifier (ID) for the current session." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:242 +msgid "the session identifier; 0 or -1 if there is no session" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:245 +msgid "See also: :ref:`box.session.id() `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:251 +msgid "Since version :doc:`2.11.0 `. Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header and body. The function yields. The function works for binary sessions only. For details, see :ref:`box.session.type() `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:257 +msgid "the IPROTO session identifier (see :ref:`box_session_id() `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:258 +msgid "a MsgPack-encoded header" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:259 +msgid "end of a header encoded as MsgPack" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:260 +msgid "a MsgPack-encoded body. If the ``body`` and ``body_end`` parameters are omitted, the packet consists of the header only." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:262 +msgid "end of a body encoded as MsgPack" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:264 +#: ../../doc/dev_guide/reference_capi/box.rst:336 +msgid "0 on success; -1 on error (check :ref:`box_error_last() `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:267 +msgid "See also: :ref:`box.iproto.send() `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:269 +#: ../../doc/dev_guide/reference_capi/box.rst:341 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:271 +msgid ":errcode:`ER_SESSION_CLOSED` -- the session is closed." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:272 +msgid ":errcode:`ER_NO_SUCH_SESSION` -- the session does not exist." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:273 +msgid ":errcode:`ER_MEMORY_ISSUE` -- out-of-memory limit has been reached." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:274 +msgid ":errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:276 +#: ../../doc/dev_guide/reference_capi/box.rst:349 +msgid "For details, see `src/box/errcode.h `__." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:278 +msgid "**Example**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:280 +msgid "/* IPROTO constants are not exported to C.\n" +"* That is, the user encodes them by himself.\n" +"*/\n" +"#define IPROTO_REQUEST_TYPE 0x00\n" +"#define IPROTO_OK 0x00\n" +"#define IPROTO_SYNC 0x01\n" +"#define IPROTO_SCHEMA_VERSION 0x05\n" +"#define IPROTO_DATA 0x30\n" +"\n" +"char buf[256] = {};\n" +"char *header = buf;\n" +"char *header_end = header;\n" +"header_end = mp_encode_map(header_end, 3);\n" +"header_end = mp_encode_uint(header_end, IPROTO_REQUEST_TYPE);\n" +"header_end = mp_encode_uint(header_end, IPROTO_OK);\n" +"header_end = mp_encode_uint(header_end, IPROTO_SYNC);\n" +"header_end = mp_encode_uint(header_end, 10);\n" +"header_end = mp_encode_uint(header_end, IPROTO_SCHEMA_VERSION);\n" +"header_end = mp_encode_uint(header_end, box_schema_version());\n" +"\n" +"char *body = header_end;\n" +"char *body_end = body;\n" +"body_end = mp_encode_map(body_end, 1);\n" +"body_end = mp_encode_uint(body_end, IPROTO_DATA);\n" +"body_end = mp_encode_uint(body_end, 1);\n" +"\n" +"/* The packet contains both the header and body. */\n" +"box_iproto_send(box_session_id(), header, header_end, body, body_end);\n" +"\n" +"/* The packet contains the header only. */\n" +"box_iproto_send(box_session_id(), header, header_end, NULL, NULL);" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:318 +msgid "Since version :doc:`2.11.0 `. Set a new IPROTO request handler with the provided context for the given request type. The function yields." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:322 +msgid "IPROTO request type code (for example, ``IPROTO_SELECT``). For details, check :ref:`Client-server requests and responses `. To override the handler of unknown request types, use the :ref:`IPROTO_UNKNOWN ` type code." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:322 +msgid "IPROTO request type code (for example, ``IPROTO_SELECT``). For details, check :ref:`Client-server requests and responses `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:325 +msgid "To override the handler of unknown request types, use the :ref:`IPROTO_UNKNOWN ` type code." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:327 +msgid "IPROTO request handler. To reset the request handler, set the ``handler`` parameter to ``NULL``. See the full parameter description in the :ref:`Handler function ` section." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:330 +msgid "IPROTO request handler destructor. The destructor is called when the corresponding handler is removed. See the full parameter description in the :ref:`Handler destructor function ` section." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:334 +msgid "a context passed to the ``handler`` and ``destroy`` callbacks" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:339 +msgid "See also: :ref:`box.iproto.override() `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:343 +msgid "If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call. The following errors are returned to the client over IPROTO (see `src/lua/utils.h `__):" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:346 +msgid ":errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:347 +msgid "diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:353 +msgid "**Handler function**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:355 +msgid "The signature of a handler function (the ``handler`` parameter):" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:357 +msgid "enum iproto_handler_status {\n" +" IPROTO_HANDLER_OK,\n" +" IPROTO_HANDLER_ERROR,\n" +" IPROTO_HANDLER_FALLBACK,\n" +"}\n" +"\n" +"typedef enum iproto_handler_status\n" +"(*iproto_handler_t)(const char *header, const char *header_end,\n" +" const char *body, const char *body_end, void *ctx);" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:369 +#: ../../doc/dev_guide/reference_capi/box.rst:395 +msgid "where:" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:371 +msgid "``header`` (const char*) -- a MsgPack-encoded header" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:372 +msgid "``header_end`` (const char*) -- end of a header encoded as MsgPack" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:373 +msgid "``body`` (const char*) -- a MsgPack-encoded body" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:374 +msgid "``header_end`` (const char*) -- end of a body encoded as MsgPack" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:376 +msgid "The handler returns a status code. Possible statuses:" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:378 +msgid "``IPROTO_REQUEST_HANDLER_OK`` -- success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:379 +msgid "``IPROTO_REQUEST_HANDLER_ERROR`` -- error, diagnostic must be set by handler (see :ref:`box_error_set() ` and :ref:`box_error_raise() `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:382 +msgid "``IPROTO_REQUEST_HANDLER_FALLBACK`` -- fallback to the default handler" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:386 +msgid "**Handler destructor function**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:388 +msgid "The destructor is called when the handler is reset. The signature of a destructor function (the ``destroy`` parameter):" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:391 +msgid "typedef void (*iproto_handler_destroy_t)(void *ctx);" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:397 +msgid "``ctx`` (void*): the context provided by ``box_iproto_override()`` function." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:399 +msgid "**Examples**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box.rst:401 +msgid "box_iproto_override(1000, iproto_request_handler_с, NULL)\n" +"box_iproto_override(IPROTO_SELECT, iproto_request_handler_с, (uintptr_t)23)\n" +"box_iproto_override(IPROTO_SELECT, NULL, NULL)\n" +"box_iproto_override(IPROTO_UNKNOWN, iproto_unknown_request_handler_с, &ctx)" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/box_index.pot b/locale/en/dev_guide/reference_capi/box_index.pot new file mode 100644 index 0000000000..baa39f3cbc --- /dev/null +++ b/locale/en/dev_guide/reference_capi/box_index.pot @@ -0,0 +1,322 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:3 +msgid "Module index" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:7 +msgid "A space iterator" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:13 +msgid "Controls how to iterate over tuples in an index. Different index types support different iterator types. For example, one can start iteration from a particular value (request key) and then retrieve all tuples where keys are greater or equal (= GE) to this key." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:18 +msgid "If iterator type is not supported by the selected index type, iterator constructor must fail with ER_UNSUPPORTED. To be selectable for primary key, an index must support at least ITER_EQ and ITER_GE types." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:22 +msgid "NULL value of request key corresponds to the first or last key in the index, depending on iteration direction. (first key for GE and GT types, and last key for LE and LT). Therefore, to iterate over all tuples in an index, one can use ITER_GE or ITER_LE iteration types with start key equal to NULL. For ITER_EQ, the key must not be NULL." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:30 +msgid "key == x ASC order" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:34 +msgid "key == x DESC order" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:38 +msgid "all tuples" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:42 +msgid "key < x" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:46 +msgid "key <= x" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:50 +msgid "key >= x" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:54 +msgid "key > x" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:58 +msgid "all bits from x are set in key" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:62 +msgid "at least one x's bit is set" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:66 +msgid "all bits are not set" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:70 +msgid "key overlaps x" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:74 +msgid "tuples in distance ascending order from specified point" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:80 +msgid "Allocate and initialize iterator for space_id, index_id." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:82 +msgid "The returned iterator must be destroyed by :ref:`box_iterator_free`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:85 +#: ../../doc/dev_guide/reference_capi/box_index.rst:129 +#: ../../doc/dev_guide/reference_capi/box_index.rst:139 +#: ../../doc/dev_guide/reference_capi/box_index.rst:149 +#: ../../doc/dev_guide/reference_capi/box_index.rst:168 +#: ../../doc/dev_guide/reference_capi/box_index.rst:184 +#: ../../doc/dev_guide/reference_capi/box_index.rst:200 +#: ../../doc/dev_guide/reference_capi/box_index.rst:216 +#: ../../doc/dev_guide/reference_capi/box_index.rst:234 +msgid "space identifier" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:86 +#: ../../doc/dev_guide/reference_capi/box_index.rst:130 +#: ../../doc/dev_guide/reference_capi/box_index.rst:140 +#: ../../doc/dev_guide/reference_capi/box_index.rst:150 +#: ../../doc/dev_guide/reference_capi/box_index.rst:169 +#: ../../doc/dev_guide/reference_capi/box_index.rst:185 +#: ../../doc/dev_guide/reference_capi/box_index.rst:201 +#: ../../doc/dev_guide/reference_capi/box_index.rst:217 +#: ../../doc/dev_guide/reference_capi/box_index.rst:235 +msgid "index identifier" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:87 +#: ../../doc/dev_guide/reference_capi/box_index.rst:218 +msgid ":ref:`iterator_type`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:88 +#: ../../doc/dev_guide/reference_capi/box_index.rst:170 +#: ../../doc/dev_guide/reference_capi/box_index.rst:186 +#: ../../doc/dev_guide/reference_capi/box_index.rst:202 +#: ../../doc/dev_guide/reference_capi/box_index.rst:219 +msgid "encode key in MsgPack Array format ([part1, part2, ...])" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:89 +#: ../../doc/dev_guide/reference_capi/box_index.rst:171 +#: ../../doc/dev_guide/reference_capi/box_index.rst:187 +#: ../../doc/dev_guide/reference_capi/box_index.rst:203 +#: ../../doc/dev_guide/reference_capi/box_index.rst:220 +msgid "the end of encoded ``key``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +#: ../../doc/dev_guide/reference_capi/box_index.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:91 +msgid "NULL on error (check :ref:`box_error_last `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:92 +msgid "iterator otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:94 +msgid "See also :ref:`box_iterator_next`, :ref:`box_iterator_free`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:101 +msgid "Retrieve the next item from the ``iterator``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:103 +#: ../../doc/dev_guide/reference_capi/box_index.rst:117 +msgid "an iterator returned by :ref:`box_index_iterator `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:105 +msgid "output argument. result a tuple or NULL if there is no more data." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:108 +#: ../../doc/dev_guide/reference_capi/box_index.rst:132 +#: ../../doc/dev_guide/reference_capi/box_index.rst:142 +#: ../../doc/dev_guide/reference_capi/box_index.rst:175 +msgid "-1 on error (check :ref:`box_error_last `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:109 +msgid "0 on success. The end of data is not an error." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:115 +msgid "Destroy and deallocate iterator." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:122 +msgid "Determine a direction of the given iterator type: -1 for REQ, LT, LE, and +1 for all others." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:127 +msgid "Return the number of element in the index." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:133 +#: ../../doc/dev_guide/reference_capi/box_index.rst:143 +msgid ">= 0 otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:137 +msgid "Return the number of bytes used in memory by the index." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:147 +msgid "Return a random tuple from the index (useful for statistical analysis)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:151 +msgid "random seed" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:152 +#: ../../doc/dev_guide/reference_capi/box_index.rst:172 +#: ../../doc/dev_guide/reference_capi/box_index.rst:188 +#: ../../doc/dev_guide/reference_capi/box_index.rst:204 +msgid "output argument. result a tuple or NULL if there is no tuples in space" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:155 +msgid "See also: :doc:`/reference/reference_lua/box_index/random`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:161 +msgid "Get a tuple from index by the key." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:163 +msgid "Please note that this function works much more faster than :doc:`/reference/reference_lua/box_index/select` or :ref:`box_index_iterator` + :ref:`box_iterator_next`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:176 +#: ../../doc/dev_guide/reference_capi/box_index.rst:192 +#: ../../doc/dev_guide/reference_capi/box_index.rst:208 +#: ../../doc/dev_guide/reference_capi/box_index.rst:223 +msgid "0 on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:178 +msgid "See also: ``index_object.get()``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:182 +msgid "Return a first (minimal) tuple matched the provided key." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:191 +#: ../../doc/dev_guide/reference_capi/box_index.rst:207 +#: ../../doc/dev_guide/reference_capi/box_index.rst:222 +msgid "-1 on error (check :ref:`box_error_last() `)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:194 +msgid "See also: :doc:`/reference/reference_lua/box_index/min`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:198 +msgid "Return a last (maximal) tuple matched the provided key." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:210 +msgid "See also: :doc:`/reference/reference_lua/box_index/max`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:214 +msgid "Count the number of tuple matched the provided key." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:225 +msgid "See also: :ref:`index_object.count()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:230 +msgid "Return :ref:`key definition ` for an index" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:232 +msgid "Returned object is valid until the next yield." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:237 +msgid "key definition on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:238 +msgid "NULL on error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:240 +msgid "See also: :ref:`box_tuple_compare() `," +msgstr "" + +#: ../../doc/dev_guide/reference_capi/box_index.rst:241 +msgid ":ref:`box_tuple_format_new() `" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/clock.pot b/locale/en/dev_guide/reference_capi/clock.pot new file mode 100644 index 0000000000..b8f8c2af48 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/clock.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/clock.rst:3 +msgid "Module clock" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/coio.pot b/locale/en/dev_guide/reference_capi/coio.pot new file mode 100644 index 0000000000..9420649d66 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/coio.pot @@ -0,0 +1,112 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/coio.rst:5 +msgid "Module coio" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:11 +msgid "READ event" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:15 +msgid "WRITE event" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:21 +msgid "Wait until READ or WRITE event on socket (``fd``). Yields." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:23 +#: ../../doc/dev_guide/reference_capi/coio.rst:72 +msgid "non-blocking socket file description" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:24 +msgid "requested events to wait. Combination of ``COIO_READ | COIO_WRITE`` bit flags." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:26 +msgid "timeout in seconds." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +#: ../../doc/dev_guide/reference_capi/coio.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:28 +msgid "0 - timeout" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:29 +msgid ">0 - returned events. Combination of ``TNT_IO_READ | TNT_IO_WRITE`` bit flags." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:35 +msgid "Create new eio task with specified function and arguments. Yield and wait until the task is complete. This function may use the :ref:`worker_pool_threads ` configuration parameter." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:40 +msgid "To avoid double error checking, this function does not throw exceptions. In most cases it is also necessary to check the return value of the called function and perform necessary actions. If func sets errno, the errno is preserved across the call." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:45 +msgid "-1 and ``errno`` = ENOMEM if failed to create a task" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:46 +msgid "the function's return (``errno`` is preserved)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:48 +msgid "**Example:**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:50 +msgid "static ssize_t openfile_cb(va_list ap)\n" +"{\n" +" const char* filename = va_arg(ap);\n" +" int flags = va_arg(ap);\n" +" return open(filename, flags);\n" +"}\n" +"\n" +"if (coio_call(openfile_cb, \"/tmp/file\", 0) == -1)\n" +" // handle errors.\n" +"..." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:65 +msgid "Fiber-friendly version of :manpage:`getaddrinfo(3)`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:69 +msgid "Close the ``fd`` and wake any fiber blocked in :ref:`coio_wait() ` call on this ``fd``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/coio.rst:74 +msgid "the result of ``close(fd)``, see :manpage:`close(2)`" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/error.pot b/locale/en/dev_guide/reference_capi/error.pot new file mode 100644 index 0000000000..cb39ff79c8 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/error.pot @@ -0,0 +1,114 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/error.rst:3 +msgid "Module error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:11 +msgid "For a complete list of errors, refer to the Tarantool `error code header file `__." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:16 +msgid "Error -- contains information about error." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:20 +msgid "Return the error type, e.g. \"ClientError\", \"SocketError\", etc." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:22 +#: ../../doc/dev_guide/reference_capi/error.rst:31 +#: ../../doc/dev_guide/reference_capi/error.rst:38 +msgid "error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +#: ../../doc/dev_guide/reference_capi/error.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:23 +#: ../../doc/dev_guide/reference_capi/error.rst:39 +msgid "not-null string" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:29 +msgid "Return IPROTO error code" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:32 +msgid ":ref:`box_error_code `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:36 +msgid "Return the error message" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:45 +msgid "Get the information about the last API call error." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:47 +msgid "The Tarantool error handling works most like libc's errno. All API calls return -1 or NULL in the event of error. An internal pointer to box_error_t type is set by API functions to indicate what went wrong. This value is only significant if API call failed (returned -1 or NULL)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:52 +msgid "Successful function can also touch the last error in some cases. You don't have to clear the last error before calling API functions. The returned object is valid only until next call to **any** API function." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:56 +msgid "You must set the last error using box_error_set() in your stored C procedures if you want to return a custom error message. You can re-throw the last API error to IPROTO client by keeping the current value and returning -1 to Tarantool from your stored procedure." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:61 +msgid "last error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:65 +msgid "Clear the last error." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:71 +msgid "Set the last error." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:75 +msgid "IPROTO :ref:`error code`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:77 +msgid "format arguments" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:79 +msgid "See also: IPROTO :ref:`error code`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/error.rst:85 +msgid "A backward-compatible API define." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/fiber.pot b/locale/en/dev_guide/reference_capi/fiber.pot new file mode 100644 index 0000000000..2c0ca7ad8b --- /dev/null +++ b/locale/en/dev_guide/reference_capi/fiber.pot @@ -0,0 +1,343 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:3 +msgid "Module fiber" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:7 +msgid "Fiber - contains information about a :ref:`fiber `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:11 +msgid "Function to run inside a fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:15 +msgid "Create a new fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:17 +msgid "Takes a fiber from the fiber cache, if it's not empty. Can fail only if there is not enough memory for the fiber structure or fiber stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:20 +msgid "The created fiber automatically returns itself to the fiber cache when its \"main\" function completes." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:23 +#: ../../doc/dev_guide/reference_capi/fiber.rst:39 +msgid "string with fiber name" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:24 +msgid "func for run inside fiber" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:26 +#: ../../doc/dev_guide/reference_capi/fiber.rst:43 +msgid "See also: :ref:`fiber_start()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:30 +msgid "Create a new fiber with defined attributes." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:32 +msgid "Can fail only if there is not enough memory for the fiber structure or fiber stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:35 +msgid "The created fiber automatically returns itself to the fiber cache if has a default stack size when its \"main\" function completes." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:40 +#: ../../doc/dev_guide/reference_capi/fiber.rst:175 +#: ../../doc/dev_guide/reference_capi/fiber.rst:181 +msgid "fiber attributes container" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:41 +msgid "function to run inside the fiber" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:49 +msgid "Start execution of created fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:51 +msgid "fiber to start" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:52 +msgid "arguments to start the fiber with" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:56 +msgid "Return control to another fiber and wait until it'll be woken." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:58 +msgid "See also: :ref:`fiber_wakeup()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:64 +msgid "Interrupt a synchronous wait of a fiber" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:66 +#: ../../doc/dev_guide/reference_capi/fiber.rst:108 +msgid "fiber to be woken up" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:72 +msgid "Cancel the subject fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:74 +msgid "Cancellation is asynchronous. Use :ref:`fiber_join()` to wait for the cancellation to complete." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:77 +msgid "After ``fiber_cancel()`` is called, the fiber may or may not check whether it was cancelled. If the fiber does not check it, it cannot ever be cancelled." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:80 +msgid "fiber to be cancelled" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:84 +msgid "Deprecated since :doc:`2.11.0 `. Make it possible or not possible to wakeup the current fiber immediately when it's cancelled." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:87 +#: ../../doc/dev_guide/reference_capi/fiber.rst:98 +msgid "fiber" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:88 +#: ../../doc/dev_guide/reference_capi/fiber.rst:99 +msgid "status to set" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +#: ../../doc/dev_guide/reference_capi/fiber.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:90 +msgid "previous state" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:96 +msgid "Set fiber to be joinable (``false`` by default)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:105 +msgid "Wait until the fiber is dead and then move its execution status to the caller. The fiber must not be detached." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:110 +msgid "Before: ``FIBER_IS_JOINABLE`` flag is set." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:112 +msgid "See also: :ref:`fiber_set_joinable()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:116 +msgid "Put the current fiber to sleep for at least 's' seconds." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:118 +msgid "time to sleep" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:120 +msgid "Note: this is a cancellation point." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:122 +msgid "See also: :ref:`fiber_is_cancelled()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:128 +msgid "Check current fiber for cancellation (it must be checked manually)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:132 +msgid "Report loop begin time as double (cheap)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:136 +msgid "Report loop begin time as 64-bit int. Uses real time clock." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:140 +msgid "Report loop begin time as double (cheap). Uses monotonic clock." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:144 +msgid "Report loop begin time as 64-bit int. Uses monotonic clock." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:148 +msgid "Reschedule fiber to end of event loop cycle." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:154 +msgid "Return ``slab_cache`` suitable to use with ``tarantool/small`` library" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:158 +msgid "Return the current fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:164 +msgid "Create a new fiber attributes container and initialize it with default parameters." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:167 +msgid "Can be used for creating many fibers: corresponding fibers will not take ownership." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:172 +msgid "Delete the ``fiber_attr`` and free all allocated resources. This is safe when fibers created with this attribute still exist." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:179 +msgid "Set the fiber's stack size in the fiber attributes container." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:182 +msgid "stack size for new fibers (in bytes)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:184 +msgid "0 on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:185 +msgid "-1 on failure (if ``stack_size`` is smaller than the minimum allowable fiber stack size)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:190 +msgid "Get the fiber's stack size from the fiber attributes container." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:192 +msgid "fiber attributes container, or NULL for default" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:195 +msgid "stack size (in bytes)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:201 +msgid "A conditional variable: a synchronization primitive that allow fibers in Tarantool's :ref:`cooperative multitasking ` environment to yield until some predicate is satisfied." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:205 +msgid "Fiber conditions have two basic operations -- \"wait\" and \"signal\", -- where \"wait\" suspends the execution of a fiber (i.e. yields) until \"signal\" is called." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:209 +msgid "Unlike ``pthread_cond``, ``fiber_cond`` doesn't require mutex/latch wrapping." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:213 +msgid "Create a new conditional variable." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:217 +msgid "Delete the conditional variable." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:219 +msgid "Note: behavior is undefined if there are fibers waiting for the conditional variable." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:222 +msgid "conditional variable to delete" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:228 +msgid "Wake up **one** (any) of the fibers waiting for the conditional variable." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:230 +#: ../../doc/dev_guide/reference_capi/fiber.rst:238 +msgid "Does nothing if no one is waiting." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:232 +#: ../../doc/dev_guide/reference_capi/fiber.rst:240 +#: ../../doc/dev_guide/reference_capi/fiber.rst:256 +msgid "conditional variable" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:236 +msgid "Wake up **all** fibers waiting for the conditional variable." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:246 +msgid "Suspend the execution of the current fiber (i.e. yield) until :ref:`fiber_cond_signal() ` is called." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:249 +msgid "Like ``pthread_cond``, ``fiber_cond`` can issue spurious wake ups caused by explicit :ref:`fiber_wakeup()` or :ref:`fiber_cancel()` calls. It is highly recommended to wrap calls to this function into a loop and check the actual predicate and :ref:`fiber_is_cancelled()` on every iteration." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:257 +msgid "timeout in seconds" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:259 +msgid "0 on :ref:`fiber_cond_signal() ` call or a spurious wake up" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:261 +msgid "-1 on timeout, and the error code is set to 'TimedOut'" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/fiber.rst:265 +msgid "Shortcut for :ref:`fiber_cond_wait_timeout() `." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/index.pot b/locale/en/dev_guide/reference_capi/index.pot new file mode 100644 index 0000000000..3b2b490f7b --- /dev/null +++ b/locale/en/dev_guide/reference_capi/index.pot @@ -0,0 +1,26 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/index.rst:10 +#: ../../doc/dev_guide/reference_capi/index.rst:10 +msgid "List of C API headers" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/index.rst:8 +msgid "C API reference" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/latch.pot b/locale/en/dev_guide/reference_capi/latch.pot new file mode 100644 index 0000000000..10c9425ee3 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/latch.pot @@ -0,0 +1,91 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/latch.rst:3 +msgid "Module latch" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:7 +msgid "A lock for cooperative multitasking environment" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:11 +msgid "Allocate and initialize the new latch." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:13 +msgid "allocated latch object" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +msgid "Return type" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:14 +msgid "box_latch_t *" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:18 +msgid "Destroy and free the latch." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +#: ../../doc/dev_guide/reference_capi/latch.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:20 +msgid "latch to destroy" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:24 +msgid "Lock a latch. Waits indefinitely until the current fiber can gain access to the latch. Since version :doc:`2.11.0 `, locks are acquired exactly in the order in which they were requested." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:28 +#: ../../doc/dev_guide/reference_capi/latch.rst:34 +msgid "latch to lock" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:32 +msgid "Try to lock a latch. Return immediately if the latch is locked." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:35 +msgid "status of operation. 0 - success, 1 - latch is locked" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:36 +msgid "int" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:40 +msgid "Unlock a latch. The fiber calling this function must own the latch." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/latch.rst:42 +msgid "latch to unlock" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/on_shutdown.pot b/locale/en/dev_guide/reference_capi/on_shutdown.pot new file mode 100644 index 0000000000..ab3cb2befe --- /dev/null +++ b/locale/en/dev_guide/reference_capi/on_shutdown.pot @@ -0,0 +1,81 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:3 +msgid "Function on_shutdown" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:9 +msgid "Register and/or deregister an on_shutdown function." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:11 +msgid "Pointer to an area that the new handler can use" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:12 +msgid "Pointer to a function which will be registered, or NULL" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:13 +msgid "Pointer to a function which will be deregistered, or NULL" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:15 +msgid "status of operation. 0 - success, -1 - failure" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:0 +msgid "Return type" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:16 +msgid "int" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:18 +msgid "A function which is registered will be called when the Tarantool instance shuts down. This is functionally similar to what :ref:`box.ctl.on_shutdown ` does." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:21 +msgid "If there are several on_shutdown functions, the Tarantool instance will call them in reverse order of registration, that is, it will call the last-registered function first." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:24 +msgid "Typically a module developer will register an on_shutdown function that does whatever cleanup work the module requires, and then returns control to the Tarantool instance. Such an on_shutdown function should be fast, or should use an asynchronous waiting mechanism (for example :ref:`coio_wait `)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:29 +msgid "Possible errors: old_handler does not exist (errno = EINVAL), new_handler and old_handler are both NULL (errno = EINVAL), memory allocation fails (errno = ENOMEM)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:34 +msgid "Example: if the C API .c program contains a function ``int on_shutdown_function(void *arg) {printf(\"Bye!\\n\");return 0; }`` and later, in the function which the instance calls, contains a line ``box_on_shutdown(NULL, on_shutdown_function, NULL);`` then, if all goes well, when the instance shuts down, it will display \"Bye!\"." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/on_shutdown.rst:40 +msgid "Added in version :doc:`2.8.1 `." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/say.pot b/locale/en/dev_guide/reference_capi/say.pot new file mode 100644 index 0000000000..c478c9da7c --- /dev/null +++ b/locale/en/dev_guide/reference_capi/say.pot @@ -0,0 +1,62 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/say.rst:3 +msgid "Module say (logging)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:11 +msgid "do not use this value directly" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:29 +#: ../../doc/dev_guide/reference_capi/say.rst:45 +msgid "Format and print a message to Tarantool log file." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:0 +#: ../../doc/dev_guide/reference_capi/say.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:31 +msgid ":ref:`log level `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:32 +#: ../../doc/dev_guide/reference_capi/say.rst:47 +msgid "``printf()``-like format string" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:33 +#: ../../doc/dev_guide/reference_capi/say.rst:48 +msgid "format arguments" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:35 +#: ../../doc/dev_guide/reference_capi/say.rst:50 +msgid "See also :manpage:`printf(3)`, :ref:`say_level`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:52 +msgid "**Example:**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/say.rst:54 +msgid "say_info(\"Some useful information: %s\", status);" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/schema.pot b/locale/en/dev_guide/reference_capi/schema.pot new file mode 100644 index 0000000000..8e91c54f12 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/schema.pot @@ -0,0 +1,89 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/schema.rst:3 +msgid "Module schema" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:11 +msgid "Start of the reserved range of system spaces." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:15 +msgid "Space id of _schema." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:19 +msgid "Space id of _space." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:23 +msgid "Space id of _vspace view." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:27 +msgid "Space id of _index." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:31 +msgid "Space id of _vindex view." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:35 +msgid "Space id of _func." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:39 +msgid "Space id of _vfunc view." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:43 +msgid "Space id of _user." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:47 +msgid "Space id of _vuser view." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:51 +msgid "Space id of _priv." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:55 +msgid "Space id of _vpriv view." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:59 +msgid "Space id of _cluster." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:63 +msgid "Space id of _trigger." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:67 +msgid "Space id of _truncate." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:71 +msgid "End of reserved range of system spaces." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/schema.rst:75 +msgid "NULL value, returned on error." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/trivia.pot b/locale/en/dev_guide/reference_capi/trivia.pot new file mode 100644 index 0000000000..e1d2f87f4f --- /dev/null +++ b/locale/en/dev_guide/reference_capi/trivia.pot @@ -0,0 +1,93 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:3 +msgid "Module trivia/config" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:7 +msgid "Extern modifier for all public functions." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:11 +msgid "Package major version - 2 for 2.0.5." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:15 +msgid "Package minor version - 0 for 2.0.5." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:19 +msgid "Package patch version - 5 for 2.0.5." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:23 +msgid "A string with major-minor-patch-commit-id identifier of the release, e.g. 2.0.5-75-gdd8e14ffb." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:28 +msgid "System configuration dir (e.g ``/etc``)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:32 +msgid "Install prefix (e.g. ``/usr``)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:36 +msgid "Build type, e.g. Debug or Release" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:40 +msgid "CMake build type signature, e.g. ``Linux-x86_64-Debug``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:44 +msgid "Command line used to run CMake." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:48 +msgid "Paths to C and CXX compilers." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:52 +msgid "C compile flags used to build Tarantool." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:56 +msgid "CXX compile flags used to build Tarantool." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:60 +msgid "A path to install ``*.lua`` module files." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:64 +msgid "A path to install ``*.so``/``*.dylib`` module files." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:68 +msgid "A path to Lua includes (the same directory where this file is contained)" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:72 +msgid "A constant added to ``package.path`` in Lua to find ``*.lua`` module files." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/trivia.rst:76 +msgid "A constant added to ``package.cpath`` in Lua to find ``*.so`` module files." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/tuple.pot b/locale/en/dev_guide/reference_capi/tuple.pot new file mode 100644 index 0000000000..44062d2efa --- /dev/null +++ b/locale/en/dev_guide/reference_capi/tuple.pot @@ -0,0 +1,452 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:3 +msgid "Module tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:11 +msgid "Tuple format." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:13 +msgid "Each Tuple has an associated format (class). Default format is used to create tuples which are not attached to any particular space." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:18 +msgid "Tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:24 +msgid "Allocate and initialize a new tuple from raw MsgPack Array data." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:26 +msgid "tuple format. Use :ref:`box_tuple_format_default()` to create space-independent tuple." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:29 +msgid "tuple data in MsgPack Array format ([field1, field2, ...])" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:30 +msgid "the end of ``data``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +#: ../../doc/dev_guide/reference_capi/tuple.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:32 +msgid "NULL on out of memory" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:33 +msgid "tuple otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:35 +msgid "See also: :doc:`/reference/reference_lua/box_tuple/new`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:39 +msgid "When working with tuples, it is the developer's responsibility to ensure that enough space is allocated, taking especial caution when writing to them with msgpuck functions such as ``mp_encode_array()``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:48 +msgid "Increase the reference counter of tuple." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:50 +msgid "Tuples are reference counted. All functions that return tuples guarantee that the last returned tuple is reference counted internally until the next call to API function that yields or returns another tuple." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:54 +msgid "You should increase the reference counter before taking tuples for long processing in your code. The Lua garbage collector will not destroy a tuple that has references, even if another fiber removes them from a space. After processing, decrement the reference counter using :ref:`box_tuple_unref()`, otherwise the tuple will leak." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:62 +#: ../../doc/dev_guide/reference_capi/tuple.rst:75 +#: ../../doc/dev_guide/reference_capi/tuple.rst:85 +#: ../../doc/dev_guide/reference_capi/tuple.rst:91 +#: ../../doc/dev_guide/reference_capi/tuple.rst:110 +#: ../../doc/dev_guide/reference_capi/tuple.rst:125 +msgid "a tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:64 +#: ../../doc/dev_guide/reference_capi/tuple.rst:103 +msgid "-1 on error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:65 +msgid "0 otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:67 +msgid "See also: :ref:`box_tuple_unref()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:73 +msgid "Decrease the reference counter of tuple." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:77 +msgid "See also: :ref:`box_tuple_ref()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:83 +msgid "Return the number of fields in a tuple (the size of MsgPack Array)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:89 +msgid "Return the number of bytes used to store internal tuple data (MsgPack Array)." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:95 +msgid "Dump raw MsgPack data to the memory buffer ``buf`` of size ``size``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:97 +msgid "Store tuple fields in the memory buffer." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:99 +msgid "Upon successful return, the function returns the number of bytes written. If buffer size is not enough then the return value is the number of bytes which would have been written if enough space had been available." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:104 +msgid "number of bytes written on success." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:108 +msgid "Return the associated format." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:112 +msgid "tuple format" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:118 +msgid "Return the raw tuple field in MsgPack format. The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program :ref:`read.c `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:123 +msgid "The buffer is valid until the next call to a ``box_tuple_*`` function." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:126 +msgid "zero-based index in MsgPack array." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:128 +msgid "NULL if i >= :ref:`box_tuple_field_count()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:129 +msgid "msgpack otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:149 +msgid "Possible data types for tuple fields." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:151 +msgid "One cannot use STRS/ENUM macros for types because there is a mismatch between enum name (STRING) and type name literal (\"STR\"). STR is already used as a type in Objective C." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:159 +msgid "Key definition" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:163 +msgid "Create a key definition with the key fields with passed types on passed positions." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:165 +msgid "May be used for tuple format creation and/or tuple comparison." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:167 +msgid "array with key field identifiers" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:168 +msgid "array with key :ref:`field types `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:169 +msgid "the number of key fields" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:171 +msgid "key definition on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:172 +#: ../../doc/dev_guide/reference_capi/tuple.rst:190 +msgid "NULL on error" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:176 +msgid "Delete a key definition" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:178 +msgid "key definition to delete" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:184 +msgid "Return new in-memory tuple format based on passed key definitions" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:186 +msgid "array of keys defined for the format" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:187 +msgid "count of keys" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:189 +msgid "new tuple format on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:194 +msgid "Increment tuple format reference count" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:196 +msgid "tuple format to ref" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:200 +msgid "Decrement tuple format reference count" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:202 +msgid "tuple format to unref" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:208 +msgid "Compare tuples using key definition" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:210 +msgid "the first tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:211 +msgid "the second tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:212 +#: ../../doc/dev_guide/reference_capi/tuple.rst:226 +msgid "key definition" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:214 +msgid "0 if ``key_fields(tuple_a)`` == ``key_fields(tuple_b)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:215 +msgid "<0 if ``key_fields(tuple_a)`` < ``key_fields(tuple_b)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:216 +msgid ">0 if ``key_fields(tuple_a)`` > ``key_fields(tuple_b)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:218 +#: ../../doc/dev_guide/reference_capi/tuple.rst:232 +msgid "See also: enum :ref:`field_type `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:222 +msgid "Compare a tuple with a key using key definition" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:224 +msgid "tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:225 +msgid "key with MessagePack array header" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:228 +msgid "0 if ``key_fields(tuple)`` == ``parts(key)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:229 +msgid "<0 if ``key_fields(tuple)`` < ``parts(key)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:230 +msgid ">0 if ``key_fields(tuple)`` > ``parts(key)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:236 +msgid "Tuple iterator" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:240 +msgid "Allocate and initialize a new tuple iterator. The tuple iterator allows iterating over fields at the root level of a MsgPack array." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:243 +msgid "**Example:**" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:245 +msgid "box_tuple_iterator_t* it = box_tuple_iterator(tuple);\n" +"if (it == NULL) {\n" +" // error handling using box_error_last()\n" +"}\n" +"const char* field;\n" +"while (field = box_tuple_next(it)) {\n" +" // process raw MsgPack data\n" +"}\n" +"\n" +"// rewind the iterator to the first position\n" +"box_tuple_rewind(it)\n" +"assert(box_tuple_position(it) == 0);\n" +"\n" +"// rewind three fields\n" +"field = box_tuple_seek(it, 3);\n" +"assert(box_tuple_position(it) == 4);\n" +"\n" +"box_iterator_free(it);" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:268 +msgid "Destroy and free tuple iterator" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:274 +msgid "Return zero-based next position in iterator. That is, this function returnы the field id of the field that will be returned by the next call to :ref:`box_tuple_next()`. Returned value is zero after initialization or rewind and :ref:`box_tuple_field_count()` after the end of iteration." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:281 +#: ../../doc/dev_guide/reference_capi/tuple.rst:288 +#: ../../doc/dev_guide/reference_capi/tuple.rst:303 +#: ../../doc/dev_guide/reference_capi/tuple.rst:324 +msgid "a tuple iterator" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:282 +msgid "position" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:286 +msgid "Rewind iterator to the initial position." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:290 +msgid "After: ``box_tuple_position(it) == 0``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:294 +msgid "Seek the tuple iterator." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:296 +msgid "The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program :ref:`read.c `. The returned buffer is valid until the next call to ``box_tuple_*`` API. The requested ``field_no`` is returned by the next call to ``box_tuple_next(it)``." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:304 +msgid "field number - zero-based position in MsgPack array" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:307 +msgid "After:" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:309 +msgid "``box_tuple_position(it) == field_not`` if returned value is not NULL." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:310 +msgid "``box_tuple_position(it) == box_tuple_field_count(tuple)`` if returned value is NULL." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:317 +msgid "Return the next tuple field from tuple iterator." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:319 +msgid "The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program :ref:`read.c `. The returned buffer is valid until next call to ``box_tuple_*`` API." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:325 +msgid "NULL if there are no more fields" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:326 +msgid "MsgPack otherwise" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:328 +msgid "Before: :ref:`box_tuple_position()` is zero-based ID of returned field." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/tuple.rst:331 +msgid "After: ``box_tuple_position(it) == box_tuple_field_count(tuple)`` if returned value is NULL." +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/txn.pot b/locale/en/dev_guide/reference_capi/txn.pot new file mode 100644 index 0000000000..69892565fe --- /dev/null +++ b/locale/en/dev_guide/reference_capi/txn.pot @@ -0,0 +1,82 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/txn.rst:3 +msgid "Module txn" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:7 +msgid "Return true if there is an active transaction." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:13 +msgid "Begin a transaction in the current fiber." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:15 +msgid "A transaction is attached to caller fiber, therefore one fiber can have only one active transaction. See also :doc:`/reference/reference_lua/box_txn_management/begin`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:0 +#: ../../doc/dev_guide/reference_capi/txn.rst:0 +#: ../../doc/dev_guide/reference_capi/txn.rst:0 +#: ../../doc/dev_guide/reference_capi/txn.rst:0 +#: ../../doc/dev_guide/reference_capi/txn.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:18 +#: ../../doc/dev_guide/reference_capi/txn.rst:27 +msgid "0 on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:19 +msgid "-1 on error. Perhaps a transaction has already been started." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:25 +msgid "Commit the current transaction. See also :doc:`/reference/reference_lua/box_txn_management/commit`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:28 +msgid "-1 on error. Perhaps a disk write failure" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:32 +msgid "Roll back the current transaction. See also :doc:`/reference/reference_lua/box_txn_management/rollback`." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:36 +msgid "Return a descriptor of a savepoint." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:40 +msgid "Roll back the current transaction as far as the specified savepoint." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:44 +msgid "Allocate memory on txn memory pool." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:46 +msgid "The memory is automatically deallocated when the transaction is committed or rolled back." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/txn.rst:49 +msgid "NULL on out of memory" +msgstr "" diff --git a/locale/en/dev_guide/reference_capi/utils.pot b/locale/en/dev_guide/reference_capi/utils.pot new file mode 100644 index 0000000000..bdfe069905 --- /dev/null +++ b/locale/en/dev_guide/reference_capi/utils.pot @@ -0,0 +1,226 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/dev_guide/reference_capi/utils.rst:3 +msgid "Module lua/utils" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:9 +msgid "Push cdata of given ``ctypeid`` onto the stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:11 +msgid "CTypeID must be used from FFI at least once. Allocated memory returned uninitialized. Only numbers and pointers are supported." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:14 +#: ../../doc/dev_guide/reference_capi/utils.rst:27 +#: ../../doc/dev_guide/reference_capi/utils.rst:42 +#: ../../doc/dev_guide/reference_capi/utils.rst:49 +#: ../../doc/dev_guide/reference_capi/utils.rst:62 +#: ../../doc/dev_guide/reference_capi/utils.rst:74 +#: ../../doc/dev_guide/reference_capi/utils.rst:81 +#: ../../doc/dev_guide/reference_capi/utils.rst:116 +#: ../../doc/dev_guide/reference_capi/utils.rst:128 +msgid "Lua State" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:15 +msgid "FFI's CTypeID of this cdata" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:17 +#: ../../doc/dev_guide/reference_capi/utils.rst:31 +msgid "memory associated with this cdata" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:19 +msgid "See also: :ref:`luaL_checkcdata()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:25 +msgid "Check whether the function argument ``idx`` is a cdata." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:28 +#: ../../doc/dev_guide/reference_capi/utils.rst:43 +msgid "stack index" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:29 +msgid "output argument. FFI's CTypeID of returned cdata" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:33 +msgid "See also: :ref:`luaL_pushcdata()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:37 +msgid "Set finalizer function on a cdata object." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:39 +msgid "Equivalent to call `ffi.gc(obj, function)`. Finalizer function must be on the top of the stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:47 +msgid "Return CTypeID (FFI) of given СDATA type." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:50 +msgid "C type name as string (e.g. \"struct request\" or \"uint32_t\")" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:53 +msgid "CTypeID" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:55 +msgid "See also: :ref:`luaL_pushcdata()`, :ref:`luaL_checkcdata()`" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:60 +msgid "Declare symbols for FFI." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:63 +msgid "C definitions (e.g. \"struct stat\")" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:65 +msgid "0 on success" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:66 +msgid "``LUA_ERRRUN``, ``LUA_ERRMEM`` or ``LUA_ERRERR`` otherwise." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:68 +msgid "See also: ``ffi.cdef(def)``" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:72 +msgid "Push uint64_t onto the stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:75 +#: ../../doc/dev_guide/reference_capi/utils.rst:82 +msgid "value to push" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:79 +msgid "Push int64_t onto the stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:86 +#: ../../doc/dev_guide/reference_capi/utils.rst:100 +msgid "Check whether the argument idx is a uint64 or a convertible string and returns this number." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +#: ../../doc/dev_guide/reference_capi/utils.rst:0 +msgid "throws" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:89 +#: ../../doc/dev_guide/reference_capi/utils.rst:96 +msgid "error if the argument can't be converted" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:93 +#: ../../doc/dev_guide/reference_capi/utils.rst:107 +msgid "Check whether the argument idx is a int64 or a convertible string and returns this number." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:103 +#: ../../doc/dev_guide/reference_capi/utils.rst:110 +msgid "the converted number or 0 of argument can't be converted" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:114 +msgid "Push a tuple onto the stack." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:118 +msgid "error on OOM" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:120 +msgid "See also: :ref:`luaT_istuple `" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:126 +msgid "Check whether ``idx`` is a tuple." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:129 +msgid "the stack index" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:131 +msgid "non-NULL if ``idx`` is a tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:132 +msgid "NULL if ``idx`` is not a tuple" +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:136 +msgid "Re-throw the last Tarantool error as a Lua object." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:138 +msgid "See also: `lua_error() `_," +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:139 +msgid ":ref:`box_error_last() `." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:143 +msgid "Similar to `lua_cpcall() `_, but with the proper support of Tarantool errors." +msgstr "" + +#: ../../doc/dev_guide/reference_capi/utils.rst:148 +msgid "Get the global Lua state used by Tarantool." +msgstr "" diff --git a/locale/en/enterprise/admin.pot b/locale/en/enterprise/admin.pot new file mode 100644 index 0000000000..971c21873c --- /dev/null +++ b/locale/en/enterprise/admin.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/admin.rst:4 +msgid "Cluster administrator's guide" +msgstr "" diff --git a/locale/en/enterprise/cartridge-auth.pot b/locale/en/enterprise/cartridge-auth.pot new file mode 100644 index 0000000000..93eb92152a --- /dev/null +++ b/locale/en/enterprise/cartridge-auth.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/cartridge-auth.rst:4 +msgid "LDAP authorization" +msgstr "" diff --git a/locale/en/enterprise/changelog.pot b/locale/en/enterprise/changelog.pot new file mode 100644 index 0000000000..9260ea67c6 --- /dev/null +++ b/locale/en/enterprise/changelog.pot @@ -0,0 +1,908 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/changelog.rst:4 +msgid "Changelog" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:7 +msgid "Versioning policy" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:9 +msgid "A Tarantool Enterprise SDK version consists of two parts:" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:11 +msgid "-r" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:16 +msgid "For example: ``2.11.1-0-gc42d9735b-r589``." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:18 +msgid "``TARANTOOL_BASE_VERSION`` is the Community version which the Enterprise version is based on." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:19 +msgid "``REVISION`` is the SDK revision. Besides Tarantool itself, it includes the ``tt`` utility, a set of open and closed source modules, and examples. Learn more from :ref:`Package contents `." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:22 +msgid "598" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:24 +msgid "Updated cartridge-cli to `2.12.9 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:25 +msgid "Updated tt-ee to `1.3.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:28 +msgid "595" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:30 +msgid "Updated tt-ee to `1.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:31 +msgid "Updated cartridge to `2.8.3 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:32 +msgid "Updated cartridge-cli-extensions to `1.1.2 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:33 +msgid "Updated crud to `1.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:34 +msgid "Updated queue to `1.3.3 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:35 +msgid "Updated sharded-queue to `0.1.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:36 +msgid "Updated membership to `2.4.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:37 +msgid "Added tests for Astra Linux 1.7." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:41 +msgid "589" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:43 +msgid "Updated ``tarantool-2.10`` to 2.10.8." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:44 +msgid "Updated ``tarantool-master`` to 3.0.0-alpha3." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:45 +msgid "Updated migrations to `0.6.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:46 +msgid "Updated tt-ee to `1.2.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:47 +msgid "Updated space-explorer to `1.1.8 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:48 +msgid "Updated cartridge-metrics-role to `0.1.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:49 +msgid "Updated cartridge to `2.8.2 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:50 +msgid "Updated expirationd to `1.5.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:51 +msgid "Added sideservice `0.1.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:54 +msgid "579" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:56 +msgid "Updated cartridge-cli to `2.12.7 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:57 +msgid "Updated ``tarantool-2.11`` to 2.11.1." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:60 +msgid "577" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:62 +msgid "Added crud `1.2.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:63 +msgid "Added ddl `1.6.3 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:64 +msgid "Added sharded-queue `0.1.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:65 +msgid "Added ddl `1.6.4 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:66 +msgid "Updated tt-ee to `1.1.2 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:67 +msgid "Updated cartridge-cli to `2.12.6 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:70 +msgid "563" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:72 +msgid "Updated ``tarantool-2.10`` to 2.10.7." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:73 +msgid "Updated ``tarantool-2.11`` to 2.11.0." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:74 +msgid "Added kafka `1.6.6 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:75 +msgid "Added vshard `0.1.24 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:76 +msgid "Added metrics `1.0.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:77 +msgid "Added cartridge-metrics-role `0.1.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:78 +msgid "Added cartridge `2.8.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:79 +msgid "Added http `1.5.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:82 +msgid "557" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:84 +msgid "Added checks `3.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:85 +msgid "Updated cartridge-cli to `2.12.5 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:88 +msgid "553" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:90 +msgid "Added ``tt-ee`` and ``tt`` environment configuration." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:91 +msgid "Added crud `1.1.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:92 +msgid "Added avro-schema `3.1.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:93 +msgid "Added expirationd `1.4.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:94 +msgid "Added graphql `0.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:95 +msgid "Added graphqlapi `0.0.10 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:96 +msgid "Added metrics `0.17.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:97 +msgid "Added migrations `0.5.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:98 +msgid "Added oracle `1.4.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:99 +msgid "Added cartridge `2.7.9 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:100 +msgid "Added vshard `0.1.23 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:101 +msgid "Added kafka `1.6.5 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:104 +msgid "549" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:106 +msgid "Updated ``tarantool-2.10`` to 2.10.6." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:109 +msgid "545" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:111 +msgid "Updated ``tarantool-2.11`` to 2.11.0-rc2." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:114 +msgid "543" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:116 +msgid "Added the ``tarantool-2.11`` submodule." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:119 +msgid "542" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:121 +msgid "Updated ``tarantool-1.10`` to 1.10.15." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:124 +msgid "541" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:126 +msgid "Updated ``tarantool-master`` to ``3.0.0-entrypoint``." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:129 +msgid "540" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:131 +msgid "Updated ``tarantool-2.10`` to 2.10.5." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:134 +msgid "539" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:136 +msgid "Added vshard `0.1.22 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:139 +msgid "538" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:141 +msgid "Updated ``tarantool-2.8`` to apply 2 hotfixes." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:144 +msgid "537" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:146 +msgid "Fix non-interactive installation of the ``brew`` package." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:148 +msgid "Changed the owner of the ``/usr/local/bin`` directory." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:150 +msgid "Installed ``awscli@1`` instead of ``awscli`` since it takes much less time." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:154 +msgid "536" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:156 +msgid "Added the missing property ``2.10`` for scope ``CACHE`` in CMakeLists.txt." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:159 +msgid "535" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:161 +msgid "Added expirationd `1.3.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:164 +msgid "534" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:166 +msgid "Added crud `1.0.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:169 +msgid "533" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:171 +msgid "Use runners with label ``regular`` for builds and the tagged release workflow." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:175 +msgid "532" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:177 +msgid "Added http `1.4.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:178 +msgid "Added space-explorer `1.1.7 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:179 +msgid "Added checks `3.2.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:180 +msgid "Added metrics `0.16.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:181 +msgid "Added cartridge `2.7.8 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:184 +msgid "531" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:186 +msgid "Added the ``-DENABLE_LTO=ON`` flag for tarantool-ee@master branch to CMakeLists.txt" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:190 +msgid "530" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:192 +msgid "Upgraded devtoolset from 8 to 9. It was required for upgrading ld from 2.30 to 2.31+ for LTO." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:197 +msgid "529" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:199 +msgid "Updated tarantool’s master branch to a recent revision." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:202 +msgid "528" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:204 +msgid "Fixed code style in the Linux and macOS workflows." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:207 +msgid "527" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:209 +msgid "Reliably install packages in macOS builds." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:212 +msgid "526" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:214 +msgid "Refactored the way that GC64 builds are defined in the build workflow. There are no changes to the composition of resulting bundles." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:218 +msgid "525" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:220 +msgid "Added alerting failures in builds on stable branches and integration testing to VK Teams chats." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:224 +msgid "524" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:226 +msgid "Updated to fresh tarantool master (``2.11.0-entrypoint-107-ga18449d``)" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:229 +msgid "523" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:231 +msgid "Added cartridge `2.7.7 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:234 +msgid "522" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:236 +msgid "Outdated workflow runs are now canceled to save CI time." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:239 +msgid "521" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:241 +msgid "Added crud `0.14.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:242 +msgid "Added expirationd `1.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:243 +msgid "Added metrics `0.15.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:244 +msgid "Added queue `1.2.2 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:247 +msgid "520" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:249 +msgid "Release SDK by tags:" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:251 +msgid "Run workflow in SDK docker container." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:252 +msgid "Upload SDK files for 1.10, 2.8, 2.10 versions to release folder." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:253 +msgid "Add consistency check for all versions." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:256 +msgid "519" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:258 +msgid "On feature branches, SDK is now rebuilt only on relevant changes." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:261 +msgid "r518" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:263 +msgid "Added frontend core `8.2.1 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:264 +msgid "Added vshard `0.1.21 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:265 +msgid "Added http `1.3.0 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:266 +msgid "Added cartridge `2.7.6 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:269 +msgid "r517" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:271 +msgid "Updated Tarantool EE to `2.10.4 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:274 +msgid "r516" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:276 +msgid "Updated bundled OpenSSL to version 1.1.1q." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:279 +msgid "r515" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:281 +msgid "Removed support of Tarantool 2.7." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:282 +msgid "Started using ``tarantool/actions/prepare-checkout`` to make builds more stable." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:285 +msgid "r514" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:287 +msgid "Remove the local registry and setup using GitHub registry." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:288 +msgid "Sync rocks cache to s3 and back." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:289 +msgid "Setup using shared runners." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:290 +msgid "Refactor and format ``ci-linux.yml`` and ``ci-macos.yml``." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:293 +msgid "r513" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:295 +msgid "Removed kafka 1.5.0 due to a build issue with Tarantool 2.10.3 and higher." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:296 +msgid "Updated kafka to version `1.6.2 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:299 +msgid "r512" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:301 +msgid "Updated tuple-keydef to version `0.0.3 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:304 +msgid "r511" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:306 +msgid "Enabled parallel build of rocks for macOS in CI." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:309 +msgid "r510" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:311 +msgid "Updated Tarantool to :doc:`2.10.3 `." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:312 +msgid "Added a readable error for the case when the flight recoder fails to write data due to insufficient free space on the disk device. Previously, it was sending a `SIGBUS` error (:tarantool-ee-issue:`196`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:315 +msgid "Fixed a crash in the flight recorder caused by non-thread-safe log recording from multiple threads (:tarantool-ee-issue:`226`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:319 +msgid "r502" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:321 +msgid "Updated Tarantool to :doc:`2.10.2 `." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:322 +msgid "Increased resolution of stored entries in flight recorder (:tarantool-ee-issue:`193`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:323 +msgid "Fixed a bug in the flight recorder that resulted in skipping log entries in case ``box.cfg.log_level`` is less than ``flightrec_log_level`` (:tarantool-ee-issue:`201`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:327 +msgid "r498" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:329 +msgid "Updated Tarantool to :doc:`2.10.1 `." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:330 +msgid "Updated Cyrus SASL to version 2.1.28." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:331 +msgid "Updated OpenLDAP to version 2.5.13." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:332 +msgid "Updated LZ4 to version 1.9.3. Fixed `CVE-2021-3520 `__." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:333 +msgid "Fixed replication reconnect failure after disabling SSL encryption (:tarantool-ee-issue:`137`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:334 +msgid "Fixed a crash that occurred while tyring to start an instance that has a compressed memtx space (:tarantool-ee-issue:`171`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:336 +msgid "Fixed `CVE-2022-29242 `__ in GOST SSL engine." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:337 +msgid "Fixed a bug in the flight recorder reader implementation that resulted in a hang or error while trying to open an empty section (:tarantool-ee-issue:`187`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:341 +msgid "r467" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:344 +msgid "Breaking changes" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:346 +msgid "Default audit log format was changed to CSV." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:349 +msgid "Functionality added or changed" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:352 +#: ../../doc/enterprise/changelog.rst:412 +msgid "Enterprise" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:354 +msgid "Implemented user-defined audit events. Now it's possible to log custom messages to the audit log from Lua (:tarantool-ee-issue:`65`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:357 +msgid "**[Breaking change]** Switched the default audit log format to CSV. The format can be switched back to JSON using the new ``box.cfg.audit_format`` configuration option (:tarantool-ee-issue:`66`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:361 +msgid "Implemented the audit log filter. Now, it's possible to enable logging only for a subset of all audit events using the new ``box.cfg.audit_filter`` configuration option (:tarantool-ee-issue:`67`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:366 +#: ../../doc/enterprise/changelog.rst:422 +msgid "Core" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:368 +msgid "Implement constraints and foreign keys. Now a user can create function constraints and foreign key relations (:tarantool-issue:`6436`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:370 +msgid "Changed log level of some information messages from critical to info (:tarantool-issue:`4675`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:372 +msgid "Added predefined system events: ``box.status``, ``box.id``, ``box.election`` and ``box.schema`` (:tarantool-issue:`6260`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:374 +msgid "Introduced transaction isolation levels in Lua and IPROTO (:tarantool-issue:`6930`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:377 +msgid "Vinyl" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:379 +msgid "Disabled the deferred DELETE optimization in Vinyl to avoid possible performance degradation of secondary index reads. Now, to enable the optimization, one has to set the ``defer_deletes`` flag in space options (:tarantool-issue:`4501`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:385 +#: ../../doc/enterprise/changelog.rst:443 +msgid "Lua" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:387 +msgid "Added support of console autocompletion for net.box objects ``stream`` and ``future`` (:tarantool-issue:`6305`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:391 +#: ../../doc/enterprise/changelog.rst:456 +msgid "Datetime" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:393 +msgid "Parse method to allow converting string literals in extended iso-8601" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:394 +msgid "or rfc3339 formats (:tarantool-issue:`6731`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:396 +msgid "The range of supported years has been extended in all parsers to cover" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:396 +msgid "fully -5879610-06-22..5879611-07-11 (:tarantool-issue:`6731`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:399 +msgid "Build" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:401 +msgid "Added bundling of *GNU libunwind* to support backtrace feature on *AARCH64* architecture and distributives that don't provide *libunwind* package." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:404 +msgid "Re-enabled backtrace feature for all *RHEL* distributions by default, except for *AARCH64* architecture and ancient *GCC* versions, which lack compiler features required for backtrace (gh-4611)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:409 +msgid "Bugs fixed" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:414 +msgid "Disabled audit log unless explicitly configured (:tarantool-ee-issue:`39`). Before this change, audit events were written to stderr if ``box.cfg.audit_log`` wasn't set. Now, audit log is disabled in this case." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:417 +msgid "Disabled audit logging of replicated events (:tarantool-ee-issue:`59`). Now, replicated events (for example, user creation) are logged only on the origin, never on a replica." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:424 +msgid "Banned DDL operations in space on_replace triggers, since they could lead to a crash (:tarantool-issue:`6920`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:426 +msgid "Fixed a bug due to which all fibers created with ``fiber_attr_setstacksize()`` leaked until the thread exit. Their stacks also leaked except when ``fiber_set_joinable(..., true)`` was used." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:429 +msgid "Fixed a crash in mvcc connected with secondary index conflict (:tarantool-issue:`6452`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:430 +msgid "Fixed a bug which resulted in wrong space count (:tarantool-issue:`6421`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:431 +msgid "Select in RO transaction now reads confirmed data, like a standalone (auotcommit) select does (:tarantool-issue:`6452`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:435 +msgid "Replication" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:437 +msgid "Fixed potential obsolete data write in synchronious replication due to race in accessing terms while disk write operation is in progress and not yet completed." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:440 +msgid "Fixed replicas failing to bootstrap when master is just re-started (:tarantool-issue:`6966`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:445 +msgid "Fixed the behavior of tarantool console on SIGINT. Now Ctrl+C discards the current input and prints the new prompt (:tarantool-issue:`2717`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:449 +msgid "Triggers" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:451 +msgid "Fixed assertion or segfault when MP_EXT received via net.box (:tarantool-issue:`6766`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:452 +msgid "Now ROUND() properly support INTEGER and DECIMAL as the first argument (:tarantool-issue:`6988`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:458 +msgid "Intervals received after datetime arithmetic operations may be improperly normalized if result was negative" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:461 +msgid "tarantool> date.now() - date.now()\n" +"---\n" +"- -1.000026000 seconds\n" +"..." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:468 +msgid "I.e. 2 immediately called ``date.now()`` produce very close values, whose difference should be close to 0, not 1 second (gh-6882)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:472 +msgid "Net.box" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:474 +msgid "Changed the type of the error returned by net.box on timeout from ClientError to TimedOut (:tarantool-issue:`6144`)." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:478 +msgid "r457" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:480 +msgid "Fixed some binary protocol encryption bugs." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:483 +msgid "r455" +msgstr "" + +#: ../../doc/enterprise/changelog.rst:485 +msgid "Added :ref:`binary protocol encryption `." +msgstr "" + +#: ../../doc/enterprise/changelog.rst:486 +msgid "Added :doc:`tuple field compression `." +msgstr "" diff --git a/locale/en/enterprise/deprecated.pot b/locale/en/enterprise/deprecated.pot new file mode 100644 index 0000000000..315e7ed969 --- /dev/null +++ b/locale/en/enterprise/deprecated.pot @@ -0,0 +1,116 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/deprecated.rst:4 +msgid "Deprecated features" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:6 +msgid "The ZooKeeper along with ``orchestrator`` are no longer supported. However, they still can be used, if necessary." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:9 +msgid "The following sections describe the corresponding functionality." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:14 +msgid "Controlling the cluster via API" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:16 +msgid "To control the cluster, use the ``orchestrator`` included in the delivery package. The ``orchestrator`` uses ZooKeeper to store and distribute the configuration. The ``orchestrator`` provides the REST API for controlling the cluster. Configurations in the ZooKeeper are changed as a result of calling the ``orchestrator``'s API-functions, which in turn leads to changes in configurations of the Tarantool nodes." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:23 +msgid "We recommend using a **curl** command line interface to call the API-functions of the ``orchestrator``." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:26 +msgid "The following example shows how to register a new availability zone (DC):" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:28 +msgid "$ curl -X POST http://HOST:PORT/api/v1/zone \\\n" +" -d '{\n" +" \"name\": \"Caucasian Boulevard\"\n" +" }'" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:35 +msgid "To check whether the DC registration was successful, try the following instruction. It retrieves the list of all registered nodes in the JSON format:" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:38 +msgid "$ curl http://HOST:PORT/api/v1/zone| python -m json.tool" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:42 +msgid "To apply the new configuration directly on the Tarantool nodes, increase the configuration version number after calling the API function. To do this, use the POST request to ``/api/v1/version``:" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:46 +msgid "$ curl -X POST http://HOST:PORT/api/v1/version" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:50 +msgid "Altogether, to update the cluster configuration:" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:52 +msgid "Call the ``POST/PUT`` method of the ``orchestrator``. As a result, the ZooKeeper nodes are updated, and a subsequent update of the Tarantool nodes is initiated." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:55 +msgid "Update the configuration version using the ``POST`` request to ``/api/v1/version``. As a result, the configuration is applied to the Tarantool nodes." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:58 +msgid "See the :ref:`Orchestrator API reference ` for the detailed orchestrator API." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:63 +msgid "Setting up geo redundancy" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:65 +msgid "Logically, cluster nodes can belong to some availability zone. Physically, an availability zone is a separate DC, or a rack inside a DC. You can specify a matrix of weights (distances) for the availability zones." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:69 +msgid "New zones are added by calling a corresponding API method of the orchestrator." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:71 +msgid "By default, the matrix of weights (distances) for the zones is not configured, and geo-redundancy for such configurations works as follows:" +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:74 +msgid "Data is always written to the master." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:75 +msgid "If the master is available, then it is used for reading." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:76 +msgid "If the master is unavailable, then any available replica is used for reading." +msgstr "" + +#: ../../doc/enterprise/deprecated.rst:78 +msgid "When you define a matrix of weights (distances) by calling ``/api/v1/zones/weights``, the automatic scale-out system of the Tarantool DBMS finds a replica which is the closest to the specified router in terms of weights, and starts using this replica for reading. If this replica is not available, then the next nearest replica is selected, taking into account the distances specified in the configuration." +msgstr "" diff --git a/locale/en/enterprise/deprecated/orchestrator_api.pot b/locale/en/enterprise/deprecated/orchestrator_api.pot new file mode 100644 index 0000000000..7f37408e1e --- /dev/null +++ b/locale/en/enterprise/deprecated/orchestrator_api.pot @@ -0,0 +1,805 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:4 +msgid "Orchestrator API reference" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:9 +msgid "Configuring the zones" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:11 +msgid ":ref:`POST /api/v1/zone `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:12 +msgid ":ref:`GET /api/v1/zone/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:13 +msgid ":ref:`PUT /api/v1/zone/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:14 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:503 +msgid ":ref:`DELETE /api/v1/zone/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:20 +msgid "Create a new zone." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:22 +msgid "**Request**" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:24 +msgid "{\n" +"\"name\": \"zone 1\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:30 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:56 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:96 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:119 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:172 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:195 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:242 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:282 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:322 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:346 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:394 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:427 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:456 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:479 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:525 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:571 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:606 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:653 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:685 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:710 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:746 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:823 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:848 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:877 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:896 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:923 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:943 +msgid "**Response**" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:32 +msgid "{\n" +"\"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +"},\n" +"\"data\": {\n" +" \"id\": 2,\n" +" \"name\": \"zone 2\"\n" +"},\n" +"\"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:46 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:78 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:109 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:132 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:185 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:221 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:295 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:335 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:384 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:407 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:469 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:540 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:584 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:643 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:666 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:698 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:734 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:804 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:838 +msgid "**Potential errors**" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:48 +msgid "``zone_exists`` - the specified zone already exists" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:54 +msgid "Return information on the specified zone or on all the zones." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:58 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": [\n" +" {\n" +" \"id\": 1,\n" +" \"name\": \"zone 11\"\n" +" },\n" +" {\n" +" \"id\": 2,\n" +" \"name\": \"zone 2\"\n" +" }\n" +" ],\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:80 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:111 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:134 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:223 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:298 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:806 +msgid "``zone_not_found`` - the specified zone is not found" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:86 +msgid "Update information on the zone." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:88 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:151 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:267 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:307 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:448 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:511 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:553 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:598 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:676 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:723 +msgid "**Body**" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:90 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:600 +msgid "{\n" +" \"name\": \"zone 22\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:98 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:121 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:174 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:284 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:324 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:396 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:458 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:481 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:573 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:655 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:687 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:712 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {},\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:117 +msgid "Delete a zone if it doesn’t store any nodes." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:135 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:807 +msgid "``zone_in_use`` - the specified zone stores at least one node" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:140 +msgid "Configuring the zone weights" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:142 +msgid ":ref:`GET /api/v1/zones/weights `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:143 +msgid ":ref:`POST /api/v1/zones/weights `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:149 +msgid "Set the zone weights configuration." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:153 +msgid "{\n" +" \"weights\": {\n" +" \"1\": {\n" +" \"2\": 10,\n" +" \"3\": 11\n" +" },\n" +" \"2\": {\n" +" \"1\": 10,\n" +" \"3\": 12\n" +" },\n" +" \"3\": {\n" +" \"1\": 11,\n" +" \"2\": 12\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:187 +msgid "``zones_weights_error`` - configuration error" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:193 +msgid "Return the zone weights configuration." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:197 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {\n" +" \"1\": {\n" +" \"2\": 10,\n" +" \"3\": 11\n" +" },\n" +" \"2\": {\n" +" \"1\": 10,\n" +" \"3\": 12\n" +" },\n" +" \"3\": {\n" +" \"1\": 11,\n" +" \"2\": 12\n" +" }\n" +" },\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:228 +msgid "Configuring registry" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:230 +msgid ":ref:`GET /api/v1/registry/nodes/new `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:231 +msgid ":ref:`POST /api/v1/registry/node `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:232 +msgid ":ref:`PUT /api/v1/registry/node/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:233 +msgid ":ref:`GET /api/v1/registry/node/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:234 +msgid ":ref:`DELETE /api/v1/registry/node/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:240 +msgid "Return all the detected nodes." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:244 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": [\n" +" {\n" +" \"uuid\": \"uuid-2\",\n" +" \"hostname\": \"tnt2.public.i\",\n" +" \"name\": \"tnt2\"\n" +" }\n" +" ],\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:265 +msgid "Register the detected node." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:269 +msgid "{\n" +" \"zone_id\": 1,\n" +" \"uuid\": \"uuid-2\",\n" +" \"uri\": \"tnt2.public.i:3301\",\n" +" \"user\": \"user1:pass1\",\n" +" \"repl_user\": \"repl_user1:repl_pass1\",\n" +" \"cfg\": {\n" +" \"listen\": \"0.0.0.0:3301\"\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:297 +msgid "``node_already_registered`` - the specified node is already registered" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:299 +msgid "``node_not_discovered`` - the specified node is not detected" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:305 +msgid "Update the registered node parameters." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:309 +msgid "Pass only those parameters that need to be updated." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:311 +msgid "{\n" +" \"zone_id\": 1,\n" +" \"repl_user\": \"repl_user2:repl_pass2\",\n" +" \"cfg\": {\n" +" \"listen\": \"0.0.0.0:3301\",\n" +" \"memtx_memory\": 100000\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:337 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:386 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:409 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:471 +msgid "``node_not_registered`` - the specified node is not registered" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:343 +msgid "Return information on the nodes in a cluster. If ``node_uuid`` is passed, information on this node only is returned." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:348 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {\n" +" \"uuid-1\": {\n" +" \"user\": \"user1:pass1\",\n" +" \"hostname\": \"tnt1.public.i\",\n" +" \"repl_user\": \"repl_user2:repl_pass2\",\n" +" \"uri\": \"tnt1.public.i:3301\",\n" +" \"zone_id\": 1,\n" +" \"name\": \"tnt1\",\n" +" \"cfg\": {\n" +" \"listen\": \"0.0.0.0:3301\",\n" +" \"memtx_memory\": 100000\n" +" },\n" +" \"zone\": 1\n" +" },\n" +" \"uuid-2\": {\n" +" \"user\": \"user1:pass1\",\n" +" \"hostname\": \"tnt2.public.i\",\n" +" \"name\": \"tnt2\",\n" +" \"uri\": \"tnt2.public.i:3301\",\n" +" \"repl_user\": \"repl_user1:repl_pass1\",\n" +" \"cfg\": {\n" +" \"listen\": \"0.0.0.0:3301\"\n" +" },\n" +" \"zone\": 1\n" +" }\n" +" },\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:392 +msgid "Delete the node if it doesn’t belong to any replica set." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:410 +msgid "``node_in_use`` - the specified node is in use by a replica set" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:415 +msgid "Routers API" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:417 +msgid ":ref:`GET /api/v1/routers `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:418 +msgid ":ref:`POST /api/v1/routers `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:419 +msgid ":ref:`DELETE /api/v1/routers/{uuid} `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:425 +msgid "Return the list of all nodes that constitute the router." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:429 +msgid "{\n" +" \"data\": [\n" +" \"uuid-1\"\n" +" ],\n" +" \"status\": true,\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:446 +msgid "Assign the router role to the node." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:450 +msgid "{\n" +" \"uuid\": \"uuid-1\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:477 +msgid "Release the router role from the node." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:495 +msgid "Configuring replica sets" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:497 +msgid ":ref:`POST /api/v1/replicaset `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:498 +msgid ":ref:`PUT /api/v1/replicaset/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:499 +msgid ":ref:`GET /api/v1/replicaset/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:500 +msgid ":ref:`DELETE /api/v1/replicaset/ `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:501 +msgid ":ref:`POST /api/v1/replicaset/{replicaset_uuid}/master `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:502 +msgid ":ref:`POST /api/v1/replicaset/{replicaset_uuid}/node `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:509 +msgid "Create a replica set containing all the registered nodes." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:513 +msgid "{\n" +" \"uuid\": \"optional-uuid\",\n" +" \"replicaset\": [\n" +" {\n" +" \"uuid\": \"uuid-1\",\n" +" \"master\": true\n" +" }\n" +" ]\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:527 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {\n" +" \"replicaset_uuid\": \"cc6568a2-63ca-413d-8e39-704b20adb7ae\"\n" +" },\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:542 +msgid "``replicaset_exists`` – the specified replica set already exists" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:543 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:586 +msgid "``replicaset_empty`` – the specified replica set doesn’t contain any nodes" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:544 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:588 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:701 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:737 +msgid "``node_not_registered`` – the specified node is not registered" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:545 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:589 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:738 +msgid "``node_in_use`` – the specified node is in use by another replica set" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:551 +msgid "Update the replica set parameters." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:555 +msgid "{\n" +" \"replicaset\": [\n" +" {\n" +" \"uuid\": \"uuid-1\",\n" +" \"master\": true\n" +" },\n" +" {\n" +" \"uuid\": \"uuid-2\",\n" +" \"master\": false,\n" +" \"off\": true\n" +" }\n" +" ]\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:587 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:645 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:700 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:736 +msgid "``replicaset_not_found`` – the specified replica set is not found" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:595 +msgid "Return information on all the cluster components. If ``replicaset_uuid`` is passed, information on this replica set only is returned." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:608 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {\n" +" \"cc6568a2-63ca-413d-8e39-704b20adb7ae\": {\n" +" \"uuid-1\": {\n" +" \"hostname\": \"tnt1.public.i\",\n" +" \"off\": false,\n" +" \"repl_user\": \"repl_user2:repl_pass2\",\n" +" \"uri\": \"tnt1.public.i:3301\",\n" +" \"master\": true,\n" +" \"name\": \"tnt1\",\n" +" \"user\": \"user1:pass1\",\n" +" \"zone_id\": 1,\n" +" \"zone\": 1\n" +" },\n" +" \"uuid-2\": {\n" +" \"hostname\": \"tnt2.public.i\",\n" +" \"off\": true,\n" +" \"repl_user\": \"repl_user1:repl_pass1\",\n" +" \"uri\": \"tnt2.public.i:3301\",\n" +" \"master\": false,\n" +" \"name\": \"tnt2\",\n" +" \"user\": \"user1:pass1\",\n" +" \"zone\": 1\n" +" }\n" +" }\n" +" },\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:651 +msgid "Delete a replica set." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:668 +msgid "``replicaset_not_found`` - the specified replica set is not found" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:674 +msgid "Switch the master in the replica set." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:678 +msgid "{\n" +" \"instance_uuid\": \"uuid-1\",\n" +" \"hostname_name\": \"hostname:instance_name\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:702 +msgid "``node_not_in_replicaset`` – the specified node is not in the specified replica set" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:708 +msgid "Add a node to the replica set." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:725 +msgid "{\n" +" \"instance_uuid\": \"uuid-1\",\n" +" \"hostname_name\": \"hostname:instance_name\",\n" +" \"master\": false,\n" +" \"off\": false\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:744 +msgid "Return statistics on the cluster." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:748 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"data\": {\n" +" \"cluster\": {\n" +" \"routers\": [\n" +" {\n" +" \"zone\": 1,\n" +" \"name\": \"tnt1\",\n" +" \"repl_user\": \"repl_user1:repl_pass1\",\n" +" \"hostname\": \"tnt1.public.i\",\n" +" \"status\": null,\n" +" \"uri\": \"tnt1.public.i:3301\",\n" +" \"user\": \"user1:pass1\",\n" +" \"uuid\": \"uuid-1\",\n" +" \"total_rps\": null\n" +" }\n" +" ],\n" +" \"storages\": [\n" +" {\n" +" \"hostname\": \"tnt1.public.i\",\n" +" \"repl_user\": \"repl_user2:repl_pass2\",\n" +" \"uri\": \"tnt1.public.i:3301\",\n" +" \"name\": \"tnt1\",\n" +" \"total_rps\": null,\n" +" \"status\": 'online',\n" +" \"replicas\": [\n" +" {\n" +" \"user\": \"user1:pass1\",\n" +" \"hostname\": \"tnt2.public.i\",\n" +" \"replication_info\": null,\n" +" \"repl_user\": \"repl_user1:repl_pass1\",\n" +" \"uri\": \"tnt2.public.i:3301\",\n" +" \"uuid\": \"uuid-2\",\n" +" \"status\": 'online',\n" +" \"name\": \"tnt2\",\n" +" \"total_rps\": null,\n" +" \"zone\": 1\n" +" }\n" +" ],\n" +" \"user\": \"user1:pass1\",\n" +" \"zone_id\": 1,\n" +" \"uuid\": \"uuid-1\",\n" +" \"replicaset_uuid\": \"cc6568a2-63ca-413d-8e39-704b20adb7ae\",\n" +" \"zone\": 1\n" +" }\n" +" ]\n" +" }\n" +" },\n" +" \"status\": true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:812 +msgid "Setting up configuration versions" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:814 +msgid ":ref:`POST /api/v1/version `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:815 +msgid ":ref:`GET /api/v1/version `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:821 +msgid "Set the configuration version." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:825 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:850 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"status\": true,\n" +" \"data\": {\n" +" \"version\": 2\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:840 +msgid "``cfg_error`` - configuration error" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:846 +msgid "Return the configuration version." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:866 +msgid "Configuring sharding" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:868 +msgid ":ref:`POST /api/v1/sharding/cfg `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:869 +msgid ":ref:`GET /api/v1/sharding/cfg `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:875 +msgid "Add a new sharding configuration." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:879 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:898 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:925 +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:945 +msgid "{\n" +" \"error\": {\n" +" \"code\": 0,\n" +" \"message\": \"ok\"\n" +" },\n" +" \"status\": true,\n" +" \"data\": {}\n" +"}" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:894 +msgid "Return the current sharding configuration." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:912 +msgid "Resetting cluster configuration" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:914 +msgid ":ref:`POST /api/v1/clean/cfg `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:915 +msgid ":ref:`POST /api/v1/clean/all `" +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:921 +msgid "Reset the cluster configuration." +msgstr "" + +#: ../../doc/enterprise/deprecated/orchestrator_api.rst:940 +msgid "Reset the cluster configuration and delete information on the cluster nodes from the ZooKeeper catalogues." +msgstr "" diff --git a/locale/en/enterprise/dev.pot b/locale/en/enterprise/dev.pot new file mode 100644 index 0000000000..1a6064e236 --- /dev/null +++ b/locale/en/enterprise/dev.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/dev.rst:4 +msgid "Developer's guide" +msgstr "" diff --git a/locale/en/enterprise/flight_recorder.pot b/locale/en/enterprise/flight_recorder.pot new file mode 100644 index 0000000000..bffaf0fa87 --- /dev/null +++ b/locale/en/enterprise/flight_recorder.pot @@ -0,0 +1,245 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/flight_recorder.rst:4 +msgid "Flight recorder" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:6 +msgid "The flight recorder available in the Enterprise Edition is an event collection tool that gathers various information about a working Tarantool instance, such as:" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:9 +msgid "logs" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:11 +msgid "metrics" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:13 +msgid "requests and responses" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:15 +msgid "This information helps you investigate incidents related to :ref:`crashing ` a Tarantool instance." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:22 +msgid "Enabling the flight recorder" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:24 +msgid "The flight recorder is disabled by default and can be enabled and configured for a specific Tarantool instance. To enable the flight recorder, set the ``flightrec_enabled`` :doc:`configuration option ` to ``true``. This option is :ref:`dynamic ` and can be changed at runtime by calling ``box.cfg{}``:" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:30 +msgid "box.cfg{ flightrec_enabled = true }" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:34 +msgid "After ``flightrec_enabled`` is set to ``true``, the flight recorder starts collecting data in the flight recording file ``current.ttfr``. This file is stored in the :ref:`memtx_dir ` directory. If the instance crashes and reboots, Tarantool rotates the flight recording: ``current.ttfr`` is renamed to ``.ttfr`` (for example, ``20230411T050721.ttfr``) and the new ``current.ttfr`` file is created for collecting data. In the case of correct shutdown (for example, using ``os.exit()``), Tarantool continues writing to the existing ``current.ttfr`` file after restart." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:44 +msgid "Note that old flight recordings should be removed manually." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:51 +msgid "Configuration" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:53 +msgid "This section describes options related to the flight recorder configuration. Note that all options are :ref:`dynamic ` and can be changed at runtime." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:77 +msgid "Logs" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:79 +msgid "This section describes the flight recorder settings related to :ref:`logging `. For example, you can configure a more detailed logging level in the flight recorder for deeper analysis." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:82 +msgid ":ref:`flightrec_logs_size `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:83 +msgid ":ref:`flightrec_logs_max_msg_size `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:84 +msgid ":ref:`flightrec_logs_log_level `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:90 +msgid "Specifies the size (in bytes) of the log storage. You can set this option to ``0`` to disable the log storage." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:93 +#: ../../doc/enterprise/flight_recorder.rst:105 +#: ../../doc/enterprise/flight_recorder.rst:120 +#: ../../doc/enterprise/flight_recorder.rst:144 +#: ../../doc/enterprise/flight_recorder.rst:191 +#: ../../doc/enterprise/flight_recorder.rst:204 +#: ../../doc/enterprise/flight_recorder.rst:216 +msgid "Type: integer" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:94 +#: ../../doc/enterprise/flight_recorder.rst:192 +msgid "Default: 10485760" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:95 +msgid "Environment variable: TT_FLIGHTREC_LOGS_SIZE" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:102 +msgid "Specifies the maximum size (in bytes) of the log message. The log message is truncated if its size exceeds this limit." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:106 +msgid "Default: 4096" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:107 +msgid "Maximum: 16384" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:108 +msgid "Environment variable: TT_FLIGHTREC_LOGS_MAX_MSG_SIZE" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:115 +msgid "Specifies the level of detail the log has. You can learn more about log levels from the :ref:`log_level ` option description. Note that the ``flightrec_logs_log_level`` value might differ from ``log_level``." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:121 +msgid "Default: 6" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:122 +msgid "Environment variable: TT_FLIGHTREC_LOGS_LOG_LEVEL" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:128 +msgid "Metrics" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:130 +msgid "This section describes the flight recorder settings related to collecting :ref:`metrics `." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:133 +msgid ":ref:`flightrec_metrics_period `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:134 +msgid ":ref:`flightrec_metrics_interval `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:140 +msgid "Specifies the time period (in seconds) that defines how long metrics are stored from the moment of dump. So, this value defines how much historical metrics data is collected up to the moment of crash. The frequency of metric dumps is defined by :ref:`flightrec_metrics_interval `." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:145 +msgid "Default: 180" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:146 +msgid "Environment variable: TT_FLIGHTREC_METRICS_PERIOD" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:153 +msgid "Specifies the time interval (in seconds) that defines the frequency of dumping metrics. This value shouldn't exceed :ref:`flightrec_metrics_period `." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:156 +msgid "Type: number" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:157 +msgid "Default: 1.0" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:158 +msgid "Minimum: 0.001" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:159 +msgid "Environment variable: TT_FLIGHTREC_METRICS_INTERVAL" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:163 +msgid "Given that the average size of a metrics entry is 2 kB, you can estimate the size of the metrics storage as follows:" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:166 +msgid "(flightrec_metrics_period / flightrec_metrics_interval) * 2 kB" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:175 +msgid "Requests" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:177 +msgid "This section lists the flight recorder settings related to storing the :ref:`request and response ` data." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:180 +msgid ":ref:`flightrec_requests_size `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:181 +msgid ":ref:`flightrec_requests_max_req_size `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:182 +msgid ":ref:`flightrec_requests_max_res_size `" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:188 +msgid "Specifies the size (in bytes) of storage for the request and response data. You can set this parameter to ``0`` to disable a storage of requests and responses." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:193 +msgid "Environment variable: TT_FLIGHTREC_REQUESTS_SIZE" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:201 +msgid "Specifies the maximum size (in bytes) of a request entry. A request entry is truncated if this size is exceeded." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:205 +#: ../../doc/enterprise/flight_recorder.rst:217 +msgid "Default: 16384" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:206 +msgid "Environment variable: TT_FLIGHTREC_REQUESTS_MAX_REQ_SIZE" +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:213 +msgid "Specifies the maximum size (in bytes) of a response entry. A response entry is truncated if this size is exceeded." +msgstr "" + +#: ../../doc/enterprise/flight_recorder.rst:218 +msgid "Environment variable: TT_FLIGHTREC_REQUESTS_MAX_RES_SIZE" +msgstr "" diff --git a/locale/en/enterprise/index.pot b/locale/en/enterprise/index.pot new file mode 100644 index 0000000000..f8979ef8d1 --- /dev/null +++ b/locale/en/enterprise/index.pot @@ -0,0 +1,73 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-22 09:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/index.rst:4 +msgid "Tarantool Enterprise Edition" +msgstr "" + +#: ../../doc/enterprise/index.rst:10 +msgid "This section describes the Enterprise Edition of Tarantool software -- a Lua application server integrated with a DBMS for deploying fault-tolerant distributed data storages." +msgstr "" + +#: ../../doc/enterprise/index.rst:14 +msgid "The Enterprise Edition provides an `extended feature set `__ for developing and managing clustered Tarantool applications, for example:" +msgstr "" + +#: ../../doc/enterprise/index.rst:17 +msgid "Static package for standalone Linux systems." +msgstr "" + +#: ../../doc/enterprise/index.rst:18 +msgid "Tarantool bindings to OpenLDAP." +msgstr "" + +#: ../../doc/enterprise/index.rst:19 +msgid "Security :ref:`audit log `." +msgstr "" + +#: ../../doc/enterprise/index.rst:20 +msgid "Enterprise database connectivity: Oracle and any ODBC-supported DBMS (for example, MySQL, Microsoft SQL Server)." +msgstr "" + +#: ../../doc/enterprise/index.rst:23 +msgid "SSL support for :ref:`traffic encryption `." +msgstr "" + +#: ../../doc/enterprise/index.rst:24 +msgid ":doc:`Tuple compression `." +msgstr "" + +#: ../../doc/enterprise/index.rst:25 +msgid ":doc:`Non-blocking DDL `." +msgstr "" + +#: ../../doc/enterprise/index.rst:27 +msgid "The Enterprise Edition is distributed in the form of an SDK, which includes the following key components:" +msgstr "" + +#: ../../doc/enterprise/index.rst:30 +msgid "The Tarantool EE binary, which can use :ref:`centralized configuration `." +msgstr "" + +#: ../../doc/enterprise/index.rst:31 +msgid "The extended Enterprise version of the :ref:`tt ` utility." +msgstr "" + +#: ../../doc/enterprise/index.rst:32 +msgid ":ref:`Tarantool Cluster Manager ` -- a web-based visual tool for managing Tarantool clusters." +msgstr "" diff --git a/locale/en/enterprise/read_views.pot b/locale/en/enterprise/read_views.pot new file mode 100644 index 0000000000..f3f94d834f --- /dev/null +++ b/locale/en/enterprise/read_views.pot @@ -0,0 +1,218 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/read_views.rst:4 +msgid "Read views" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:6 +msgid "A read view is an in-memory snapshot of the entire database that isn't affected by future :ref:`data modifications `. Read views provide access to database spaces and their indexes and enable you to retrieve data using the same ``select`` and ``pairs`` operations." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:11 +msgid "Read views can be used to make complex analytical queries. This reduces the load on the main database and improves RPS for a single Tarantool instance." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:14 +msgid "To improve memory consumption and performance, Tarantool creates read views using the copy-on-write technique. In this case, duplication of the entire data set is not required: Tarantool duplicates only blocks modified after a read view is created." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:21 +msgid "Tarantool Enterprise Edition supports read views starting from v2.11.0 and enables the ability to work with them using both :ref:`Lua ` and :ref:`C API `." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:31 +msgid "Limitations" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:33 +msgid "Read views have the following limitations:" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:35 +msgid "Only the :ref:`memtx ` engine is supported." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:36 +msgid "Only TREE and HASH :ref:`indexes ` are supported." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:37 +msgid "Pagination is not supported (the :ref:`after ` option)." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:44 +msgid "Working with read views" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:49 +msgid "Creating a read view" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:51 +msgid "To create a read view, call the :ref:`box.read_view.open() ` function. The snippet below shows how to create a read view with the ``read_view1`` name." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:54 +msgid "tarantool> read_view1 = box.read_view.open({name = 'read_view1'})" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:58 +msgid "After creating a read view, you can see the information about it by calling :ref:`read_view_object:info() `." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:61 +msgid "tarantool> read_view1:info()\n" +"---\n" +"- timestamp: 66.606817935\n" +" signature: 24\n" +" is_system: false\n" +" status: open\n" +" vclock: {1: 24}\n" +" name: read_view1\n" +" id: 1\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:74 +msgid "To list all the created read views, call the :ref:`box.read_view.list() ` function." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:81 +msgid "Querying data" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:83 +msgid "After creating a read view, you can access database spaces using the :ref:`read_view_object.space ` field. This field provides access to a space object that exposes the :ref:`select `, :ref:`get `, and :ref:`pairs ` methods with the same behavior as corresponding ``box.space`` methods." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:90 +msgid "The example below shows how to select 4 records from the ``bands`` space:" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:92 +msgid "tarantool> read_view1.space.bands:select({}, {limit = 4})\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:102 +msgid "Similarly, you can retrieve data by the specific index." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:104 +msgid "tarantool> read_view1.space.bands.index.year:select({}, {limit = 4})\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +" - [2, 'Scorpions', 1965]\n" +" - [1, 'Roxette', 1986]\n" +" - [3, 'Ace of Base', 1987]\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:119 +msgid "Closing a read view" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:121 +msgid "When a read view is no longer needed, close it using the :ref:`read_view_object:close() ` method because a read view may consume a substantial amount of memory." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:125 +#: ../../doc/enterprise/read_views.rst:198 +msgid "tarantool> read_view1:close()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:131 +msgid "Otherwise, a read view is closed implicitly when the read view object is collected by the Lua garbage collector." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:133 +msgid "After the read view is closed, its :ref:`status ` is set to ``closed``. On an attempt to use it, an error is raised." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:141 +msgid "Example" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:144 +msgid "A Tarantool session below demonstrates how to open a read view, get data from this view, and close it. To repeat these steps, you need to bootstrap a Tarantool instance as described in :ref:`Using data operations ` (you can skip creating secondary indexes)." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:150 +msgid "Insert test data." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:152 +msgid "tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}" +msgstr "" + +#: ../../doc/enterprise/read_views.rst:159 +msgid "Create a read view by calling the ``open`` function. Then, make sure that the read view status is ``open``." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:162 +msgid "tarantool> read_view1 = box.read_view.open({name = 'read_view1'})\n" +"\n" +"tarantool> read_view1.status\n" +"---\n" +"- open\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:171 +msgid "Change data in a database using the ``delete`` and ``update`` operations." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:173 +msgid "tarantool> bands:delete(4)\n" +"---\n" +"- [4, 'The Beatles', 1960]\n" +"...\n" +"tarantool> bands:update({2}, {{'=', 2, 'Pink Floyd'}})\n" +"---\n" +"- [2, 'Pink Floyd', 1965]\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:184 +msgid "Query a read view to make sure it contains a snapshot of data before a database is updated." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:186 +msgid "tarantool> read_view1.space.bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"..." +msgstr "" + +#: ../../doc/enterprise/read_views.rst:196 +msgid "Close a read view." +msgstr "" diff --git a/locale/en/enterprise/read_views/c_api.pot b/locale/en/enterprise/read_views/c_api.pot new file mode 100644 index 0000000000..ff2436ce2d --- /dev/null +++ b/locale/en/enterprise/read_views/c_api.pot @@ -0,0 +1,334 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/read_views/c_api.rst:4 +msgid "Read views: C API" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:6 +msgid "This topic describes the C API for working with :ref:`read views `. The C API is MT-safe and provides the ability to use a read view from any thread, not only from the :ref:`main (TX) thread `." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:10 +msgid "The C API has the following specifics:" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:12 +msgid "The :ref:`space.upgrade ` function is not applied to retrieved tuples even if a space upgrade is in progress." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:14 +msgid "Tuples stored in :ref:`compressed spaces ` are not decompressed - they are returned as :ref:`raw MessagePack ` (``MP_EXT/MP_COMPRESSION``)." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:18 +msgid "You can learn how to call C code using stored procedures in the :ref:`C tutorial`." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:25 +msgid "Data types" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:27 +msgid "The opaque data types below represent raw read views and an iterator over data in a raw read view. Note that there is no special data type for tuples retrieved from a read view. Tuples are returned as raw MessagePack data (``const char *``)." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:33 +msgid "A raw database read view." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:37 +msgid "A space in a raw read view." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:41 +msgid "An index in a raw read view." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:45 +msgid "An iterator over data in a raw read view." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:52 +msgid "Creating and destroying read views" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:54 +msgid "To create or destroy a read view, use the functions below." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:60 +msgid "Open a raw read view with the specified name and get a pointer to this read view. In the case of error, returns ``NULL`` and sets :ref:`box_error_last()`. This function may be called from the main (TX) thread only." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:64 +#: ../../doc/enterprise/read_views/c_api.rst:64 +msgid "(optional) a read view name; if ``name`` is not specified, a read view name is set to ``unknown``" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +#: ../../doc/enterprise/read_views/c_api.rst:0 +msgid "Returns" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:66 +#: ../../doc/enterprise/read_views/c_api.rst:76 +#: ../../doc/enterprise/read_views/c_api.rst:76 +#: ../../doc/enterprise/read_views/c_api.rst:100 +#: ../../doc/enterprise/read_views/c_api.rst:100 +#: ../../doc/enterprise/read_views/c_api.rst:113 +#: ../../doc/enterprise/read_views/c_api.rst:113 +msgid "a pointer to a read view" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:73 +msgid "Close a raw read view and release all resources associated with it. This function may be called from the main (TX) thread only." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:81 +msgid "Read views created using ``box_raw_read_view_new`` are displayed in :ref:`box.read_view.list() ` along with read views :ref:`created in Lua `." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:87 +msgid "Spaces and indexes" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:89 +msgid "To fetch data from a read view, you need to specify an index to fetch the data from. The following functions are available for looking up spaces and indexes in a read view object." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:97 +msgid "Find a space by ID in a raw read view. If not found, returns ``NULL`` and sets :ref:`box_error_last()`." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:101 +#: ../../doc/enterprise/read_views/c_api.rst:128 +msgid "a space identifier" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:103 +#: ../../doc/enterprise/read_views/c_api.rst:117 +#: ../../doc/enterprise/read_views/c_api.rst:140 +#: ../../doc/enterprise/read_views/c_api.rst:140 +msgid "a pointer to a space" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:110 +msgid "Find a space by name in a raw read view. If not found, returns ``NULL`` and sets :ref:`box_error_last()`." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:114 +#: ../../doc/enterprise/read_views/c_api.rst:114 +msgid "a space name" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:115 +msgid "a space name length" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:124 +msgid "Find an index by ID in a read view's space. If not found, returns ``NULL`` and sets :ref:`box_error_last()`." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:127 +#: ../../doc/enterprise/read_views/c_api.rst:127 +msgid "a pointer to a read view's space" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:130 +#: ../../doc/enterprise/read_views/c_api.rst:144 +msgid "a pointer to an index" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:137 +msgid "Find an index by name in a read view's space. If not found, returns ``NULL`` and sets :ref:`box_error_last()`." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:141 +#: ../../doc/enterprise/read_views/c_api.rst:141 +msgid "an index name" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:142 +msgid "an index name length" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:151 +msgid "Iteration and lookup" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:153 +msgid "The functions below provide the ability to look up a tuple by the key or create an iterator over a read view index." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:157 +msgid "Methods of the read view iterator are safe to call from any thread, but they may be used in one thread at the same time. This means that an iterator should be thread-local." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:164 +msgid "Look up a tuple in a read view's index. If found, the ``data`` and ``size`` out arguments return a pointer to and the size of tuple data. If not found, ``*data`` is set to ``NULL`` and ``*size`` is set to ``0``." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:168 +#: ../../doc/enterprise/read_views/c_api.rst:168 +msgid "a pointer to a read view's index" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:169 +#: ../../doc/enterprise/read_views/c_api.rst:169 +#: ../../doc/enterprise/read_views/c_api.rst:191 +#: ../../doc/enterprise/read_views/c_api.rst:191 +msgid "a pointer to the first byte of the MsgPack data that represents the search key" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:170 +#: ../../doc/enterprise/read_views/c_api.rst:170 +#: ../../doc/enterprise/read_views/c_api.rst:192 +#: ../../doc/enterprise/read_views/c_api.rst:192 +msgid "a pointer to the byte following the last byte of the MsgPack data that represents the search key" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:171 +#: ../../doc/enterprise/read_views/c_api.rst:171 +msgid "a pointer to the tuple data" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:172 +#: ../../doc/enterprise/read_views/c_api.rst:172 +msgid "the size of tuple data" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:174 +#: ../../doc/enterprise/read_views/c_api.rst:194 +#: ../../doc/enterprise/read_views/c_api.rst:210 +msgid "``0`` on success; in the case of error, returns ``-1`` and sets :ref:`box_error_last()`" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:183 +msgid "Create an iterator over a raw read view index. The initialized iterator object returned by this function remains valid and may be safely used until it's destroyed or the read view is closed. When the iterator object is no longer needed, it should be destroyed using :ref:`box_raw_read_view_iterator_destroy() `." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:188 +#: ../../doc/enterprise/read_views/c_api.rst:188 +msgid "an iterator over a raw read view index" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:189 +#: ../../doc/enterprise/read_views/c_api.rst:189 +msgid "a pointer to a read view index" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:190 +msgid "an iteration direction represented by the :ref:`iterator_type `" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:202 +msgid "Retrieve the current tuple and advance the given iterator over a raw read view index. The pointer to and the size of tuple data are returned in the ``data`` and the ``size`` out arguments. The data returned by this function remains valid and may be safely used until the read view is closed." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:206 +#: ../../doc/enterprise/read_views/c_api.rst:206 +#: ../../doc/enterprise/read_views/c_api.rst:222 +#: ../../doc/enterprise/read_views/c_api.rst:222 +msgid "an iterator over a read view index" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:207 +#: ../../doc/enterprise/read_views/c_api.rst:207 +msgid "a pointer to the tuple data; at the end of iteration, ``*data`` is set to ``NULL``" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:208 +#: ../../doc/enterprise/read_views/c_api.rst:208 +msgid "the size of tuple data; at the end of iteration, ``*size`` is set to ``0``" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:218 +msgid "Destroy an iterator over a raw read view index. The iterator object should not be used after calling this function, but the data returned by the iterator may be safely dereferenced until the read view is closed." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:231 +msgid "Space format" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:233 +msgid "A space object's methods below provide the ability to get names and types of space fields." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:240 +msgid "Get the number of fields defined in the format of a read view space." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:242 +#: ../../doc/enterprise/read_views/c_api.rst:242 +#: ../../doc/enterprise/read_views/c_api.rst:256 +#: ../../doc/enterprise/read_views/c_api.rst:256 +#: ../../doc/enterprise/read_views/c_api.rst:271 +#: ../../doc/enterprise/read_views/c_api.rst:271 +msgid "a pointer to a read view space" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:244 +msgid "the number of fields" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:252 +msgid "Get the name of a field defined in the format of a read view space. If the field number is greater than the total number of fields defined in the format, ``NULL`` is returned. The string returned by this function is guaranteed to remain valid until the read view is closed." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:257 +#: ../../doc/enterprise/read_views/c_api.rst:272 +msgid "the field number (starts with ``0``)" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:259 +msgid "the name of a field" +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:267 +msgid "Get the type of a field defined in the format of a read view space. If the field number is greater than the total number of fields defined in the format, ``NULL`` is returned. The string returned by this function is guaranteed to remain valid until the read view is closed." +msgstr "" + +#: ../../doc/enterprise/read_views/c_api.rst:274 +msgid "the type of a field" +msgstr "" diff --git a/locale/en/enterprise/read_views/lua_api.pot b/locale/en/enterprise/read_views/lua_api.pot new file mode 100644 index 0000000000..1d7ec261e5 --- /dev/null +++ b/locale/en/enterprise/read_views/lua_api.pot @@ -0,0 +1,143 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/read_views/lua_api.rst:4 +msgid "Read views: Lua API" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:6 +msgid "This topic describes the Lua API for working with :ref:`read views `." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:12 +msgid "Create a :ref:`new read view `." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:14 +msgid "(optional) configurations options for a read view. For example, the ``name`` option specifies a read view name. If ``name`` is not specified, a read view name is set to ``unknown``." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:18 +msgid "a created read view object" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +#: ../../doc/enterprise/read_views/lua_api.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:19 +msgid "read_view_object" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:23 +msgid "tarantool> read_view1 = box.read_view.open({name = 'read_view1'})" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:31 +msgid "An object that represents a :ref:`read view `." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:37 +msgid "Get information about a read view such as a name, status, or ID. All the available fields are listed below in the object options." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:40 +msgid "information about a read view" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:41 +#: ../../doc/enterprise/read_views/lua_api.rst:101 +msgid "table" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:47 +msgid "Close a read view. After the read view is closed, its :ref:`status ` is set to ``closed``. On an attempt to use it, an error is raised." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:55 +msgid "A read view status. The possible values are ``open`` and ``closed``." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:58 +#: ../../doc/enterprise/read_views/lua_api.rst:75 +msgid "string" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:64 +msgid "A unique numeric identifier of a read view." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:66 +#: ../../doc/enterprise/read_views/lua_api.rst:93 +#: ../../doc/enterprise/read_views/lua_api.rst:109 +msgid "number" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:72 +msgid "A read view name. You can specify a read view name in the :ref:`box.read_view.open() ` arguments." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:81 +msgid "Determine whether a read view is system. For example, system read views can be created to make a :ref:`checkpoint ` or join a new :ref:`replica `." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:85 +msgid "boolean" +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:91 +msgid "The :ref:`fiber.clock() ` value at the moment of opening a read view." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:99 +msgid "The :ref:`box.info.vclock ` value at the moment of opening a read view." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:107 +msgid "The :ref:`box.info.signature ` value at the moment of opening a read view." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:115 +msgid "Get access to database spaces included in a read view. You can use this field to :ref:`query space data `." +msgstr "" + +#: ../../doc/enterprise/read_views/lua_api.rst:118 +msgid "space object" +msgstr "" diff --git a/locale/en/enterprise/rocksref.pot b/locale/en/enterprise/rocksref.pot new file mode 100644 index 0000000000..a947f73a78 --- /dev/null +++ b/locale/en/enterprise/rocksref.pot @@ -0,0 +1,121 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/rocksref.rst:5 +msgid "Modules" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:7 +msgid "This section covers open and closed source Lua modules for Tarantool Enterprise Edition included in the distribution as an offline rocks repository." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:12 +msgid "Open source modules" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:14 +msgid "`avro-schema `_ is an assembly of `Apache Avro `_ schema tools;" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:18 +msgid ":ref:`checks ` is a type checker of functional arguments. This library that declares a ``checks()`` function and ``checkers`` table that allow to check the parameters passed to a Lua function in a fast and unobtrusive way." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:22 +msgid "`http `_ is an on-board HTTP-server, which comes in addition to Tarantool's out-of-the-box HTTP client, and must be installed as described in the :ref:`installation section `." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:26 +msgid "`icu-date `_ is a date-and-time formatting library for Tarantool based on International Components for Unicode;" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:29 +msgid "`kafka `_ is a full-featured high-performance ``kafka`` library for Tarantool based on ``librdkafka``;" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:32 +msgid "`luacheck `_ is a static analyzer and linter for Lua, preconfigured for Tarantool." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:34 +msgid "`luarapidxml `_ is a fast XML parser." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:36 +msgid "`luatest `_ is a Tarantool test framework written in Lua." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:38 +msgid ":ref:`membership ` builds a mesh from multiple Tarantool instances based on gossip protocol. The mesh monitors itself, helps members discover everyone else in the group and get notified about their status changes with low latency. It is built upon the ideas from Consul or, more precisely, the SWIM algorithm." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:43 +msgid ":ref:`metrics ` is a collection of useful monitoring metrics." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:45 +msgid "`tracing `_ is a module for debugging performance issues." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:47 +msgid ":ref:`vshard ` is an automatic sharding system that enables horizontal scaling for Tarantool DBMS instances." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:53 +msgid "Closed source modules" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:55 +msgid ":doc:`ldap ` allows you to authenticate in a LDAP server and perform searches." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:57 +msgid ":doc:`odbc ` is an ODBC connector for Tarantool based on unixODBC." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:59 +msgid ":doc:`oracle ` is an Oracle connector for Lua applications through which they can send and receive data to and from Oracle databases. The advantage of the Tarantool-Oracle integration is that anyone can handle all the tasks with Oracle DBMSs (control, manipulation, storage, access) with the same high-level language (Lua) and with minimal delay." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:65 +msgid ":doc:`task ` is a module for managing background tasks in a Tarantool cluster." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:72 +msgid "Installing and using modules" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:74 +msgid "To use a module, install the following:" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:76 +msgid "All the necessary third-party software packages (if any). See the module's prerequisites for the list." +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:79 +msgid "The module itself on every Tarantool instance:" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:81 +msgid "$ tt rocks install MODULE_NAME [MODULE_VERSION]" +msgstr "" + +#: ../../doc/enterprise/rocksref.rst:85 +msgid "See the :ref:`tt rocks reference ` to learn more about managing Lua modules." +msgstr "" diff --git a/locale/en/enterprise/space_upgrade.pot b/locale/en/enterprise/space_upgrade.pot new file mode 100644 index 0000000000..09a4745a5f --- /dev/null +++ b/locale/en/enterprise/space_upgrade.pot @@ -0,0 +1,557 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/space_upgrade.rst:4 +msgid "Upgrading space schema" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:6 +msgid "In Tarantool, :ref:`migration ` refers to any change in a data schema, for example, creating an index, adding a field, or changing a field format. If you need to change a data schema, there are several possible cases:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:10 +msgid "Schema migration does not require data migration: adding a field with the ``is_nullable`` parameter to the end of the space, creating an index." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:13 +msgid "Schema migration requires data migration. For example, it is necessary when you have to iterate over the entire space to convert columns to a new format or remove the column completely." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:16 +msgid "To solve the task of migrating the data, you can:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:18 +msgid ":ref:`Migrate data ` to a new space manually." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:20 +msgid "Use the ``space:upgrade()`` feature." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:23 +msgid "Space upgrade overview" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:25 +msgid "The ``space:upgrade()`` feature allows users to upgrade the format of a space and the tuples stored in it without blocking the database." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:31 +msgid "How to apply space upgrade" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:33 +msgid "First, specify an upgrade function -- a function that will convert the tuples in the space to a new format. The requirements for this function are listed below." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:36 +msgid "The upgrade function takes two arguments. The first argument is a tuple to be upgraded. The second one is optional. It contains some additional information stored in plain Lua object. If omitted, the second argument is ``nil``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:40 +msgid "The function returns a new tuple or a Lua table. For example, it can add a new field to the tuple. The new tuple must conform to the new space format set by the upgrade operation." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:43 +msgid "The function should be registered with :doc:`box.schema.func.create `. It should also be stored, deterministic, and written in Lua." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:47 +msgid "The function should not change the primary key of the tuple." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:49 +msgid "The function should be idempotent: ``f(f(t)) = f(t)``. This is necessary because the function is applied to all tuples returned to the user, and some of them may have already been upgraded in the background." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:52 +msgid "Then define a new space format. This step is optional. However, it could be useful if, for example, you want to add a new column with data. For details, check the :ref:`Usage Example ` section." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:56 +msgid "The next optional step is to choose an upgrade mode. There are three modes: ``upgrade``, ``dryrun``, and ``dryrun+upgrade``. The default value is ``upgrade``. To check an upgrade function without applying any changes, choose the ``dryrun`` mode. To run a space upgrade without testing the function, pick the ``upgrade`` mode. If you want to apply both the test and the actual upgrade, use the ``dryrun+upgrade`` option. For details, see the :ref:`Upgrade Modes ` section." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:65 +msgid "How the upgrade works" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:67 +msgid "The user defines an upgrade function. Each tuple of the chosen space is passed through the function. The function converts the tuple from the old format to a new one. The function is applied to all tuples stored in the space in the background. Besides, the function is applied to all tuples returned to the user via the box API (for example, ``select``, ``get``). Therefore, it appears that the space upgrades instantly." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:74 +msgid "Keep in mind that ``space:upgrade`` differs from the :doc:`space_object:format() ` in the following ways:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:83 +msgid "Difference" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:84 +msgid "``space:upgrade()``" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:85 +msgid "``space:format()``" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:87 +msgid "Non-blocking" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:88 +msgid "Yes. It returns tuples in the new format, whether or not they have already been converted." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:89 +msgid "Yes." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:91 +msgid "Set a format incompatible with the current one" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:92 +msgid "Yes. Works for non-indexed field types only." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:93 +msgid "No, only expand the format in a compatible way." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:95 +msgid "Visibility of changes" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:96 +msgid "Immediately. All changes are visible and replicated immediately. New data should conform to the new format immediately after the call." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:98 +msgid "After data validation. Data validation starts in the background, it does not block the database. Inserting data incompatible with the new format is allowed before validation is completed -- in this case ``space.format`` fails." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:103 +msgid "Cancel (error/restart)" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:104 +msgid "Writes the state to the system table. Restart: the operation continues. Error: the operation should be restarted manually, any other attempt to change the table fails." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:107 +msgid "Leaves no traces." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:109 +msgid "Set the upgrade function" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:110 +msgid "Yes. The upgrade may take a while to traverse the space and transform tuples." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:111 +msgid "No." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:116 +msgid "At the moment, the feature is not supported for :ref:`vinyl ` spaces." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:120 +msgid "User API" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:122 +msgid "The ``space:upgrade()`` method is added to the :doc:`space object `:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:126 +msgid "upgrade function name (string) or ID (integer). For details, see the :ref:`upgrade function requirements ` section." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:129 +msgid "additional information passed to the upgrade function in the second argument. The option accepts any Lua value that can be encoded in MsgPack, which means that the :doc:`msgpack.encode(arg) ` should succeed. For example, one can pass a scalar or a Lua table. The default value is ``nil``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:135 +msgid "new space format. The requirements for this are the same as for any other :doc:`space:format() `. If the field is omitted, the space format will remain the same as before the upgrade." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:139 +msgid ":ref:`upgrade mode `. Possible values: ``upgrade``, ``dryrun``, ``dryrun+upgrade``. The default value is ``upgrade``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:142 +msgid "the flag indicates whether to wait until the upgrade operation is complete before exiting the function. The default value is ``false`` -- the function is blocked until the upgrade operation is finished." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:0 +msgid "Return" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:147 +msgid "object describing the status of the operation (also known as ``future``). The methods of the object are described below." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:154 +msgid "Shows information about the state of the upgrade operation." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:156 +msgid "dry run mode flag. Possible values: ``true`` for a dry run, ``nil`` for an actual upgrade." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:159 +msgid ":ref:`upgrade status `. Possible values: ``inprogress``, ``waitrw``, ``error``, ``replica``, ``done``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:162 +msgid "name of the upgrade function. It is the same as passed to the ``space:upgrade`` method. The field is ``nil`` if the ``status`` is ``done``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:166 +msgid "additional information passed to the upgrade function. It is the same as for the ``space:upgrade`` method. The field is ``nil`` if it is omitted in the ``space:upgrade``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:170 +msgid "UUID of the instance running the upgrade (see :doc:`box.info.uuid `). The field is ``nil`` if the ``status`` is ``done``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:174 +msgid "error message if the ``status`` is ``error``, otherwise ``nil``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:176 +msgid "completion percentage if the ``status`` is ``inprogress``/``waitrw``, otherwise ``nil``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:179 +msgid "a table with information about the state of the upgrade operation" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +#: ../../doc/enterprise/space_upgrade.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:180 +msgid "table" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:182 +msgid "The fields can also be accessed directly, without calling the ``info()`` method. For example, ``future.status`` is the same as ``future:info().status``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:187 +msgid "Waits until the upgrade operation is completed or a timeout occurs. An operation is considered completed if its status is ``done`` or ``error``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:190 +msgid "if the ``timeout`` argument is omitted, the method waits as long as it takes." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:192 +msgid "returns ``true`` if the operation has been completed, ``false`` on timeout" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:193 +msgid "boolean" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:197 +msgid "Cancels the upgrade operation if it is currently running. Otherwise, an exception is thrown. A canceled upgrade operation completes with an error." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:200 +msgid "none" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:201 +msgid "void" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:203 +msgid "Running ``space:upgrade()`` with ``is_async = false`` or the ``is_async`` field not set is equal to:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:205 +msgid "local future = space:upgrade({func = 'my_func', is_async = true})\n" +"future:wait()\n" +"return future" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:211 +msgid "If called without arguments, ``space:upgrade()`` returns a future object for the active upgrade operation. If there is none, it returns ``nil``." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:217 +msgid "Upgrade modes" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:219 +msgid "There are three upgrade modes: ``dryrun``, ``dryrun+upgrade``, and ``upgrade``. Regardless of the mode selected, the upgrade does not block execution. Once in a while, the background fiber commits the upgraded tuples and yields." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:223 +msgid "Calling ``space:upgrade`` without arguments always returns the current state of the space upgrade, never the state of a dry run. If there is a dry run working in the background, ``space:upgrade`` will still return ``nil``. Unlike an actual space upgrade, the future object returned by a dry run upgrade can't be recovered if it is lost. So a dry run is aborted if it is garbage collected." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:230 +msgid "In ``dryrun+upgrade`` mode: if the future object is garbage collected by Lua before the end of the dry run and the start of the upgrade, then the dry run will be canceled, and no upgrade will be started." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:234 +msgid "Upgrade modes:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:236 +msgid "``upgrade`` mode: the background fiber iterates over the space, applies the upgrade function, checks that obtained tuples fit the new space format, and updates the tuples. This mode prevents the space from being altered. The mode can only be performed on the master instance." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:241 +msgid "``dryrun`` mode: the dry-run mode is used to check the upgrade function. The mode does not apply any changes to the target space. It starts a background fiber. The fiber:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:244 +msgid "Iterates over the target space." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:245 +msgid "Attempts to apply the upgrade function to each tuple stored in the space." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:246 +msgid "Checks if the returned tuple matches the new format." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:247 +msgid "Checks if the function is idempotent." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:248 +msgid "Checks that the function does not modify the primary key." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:250 +msgid "For details, see the :ref:`upgrade function requirements ` section." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:252 +msgid "To start a dry run, pass ``mode='dryrun'`` to the ``space:upgrade`` method. In this case, the future object has the ``dryrun`` field set to ``true``. The possible statuses are ``inprogress`` and ``dryrun``. ``replica`` and ``waitrw`` states are never set for a dry run future object." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:257 +msgid "The ``dryrun`` mode is not persisted. Restarting the instance does not restart a dry run. A dry run only works on the original instance, never on replicas. Unlike a real upgrade, a dry run does not prevent the space from being altered. The space can even be dropped. In this case, the dry run will complete with an error." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:262 +msgid "``dryrun+upgrade`` mode: it starts a dry run, which, if completed successfully, triggers an actual upgrade. The future object returned by ``space:upgrade`` remains valid throughout the process. It starts as the future object of the dry run. Then, under the hood, it is converted into an upgrade future object. Waiting on it would wait for both the dry run and the upgrade to complete. During the dry run, the future object has the ``dryrun`` field set to ``true``. When the actual upgrade starts, the ``dryrun`` field is set to ``nil``. The mode can only be performed on the master instance." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:273 +msgid "States" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:275 +msgid "An upgrade operation has one of the following upgrade states:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:277 +msgid "``inprogress`` -- the upgrade operation is running in the background. The function is applied to all tuples returned to the user." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:280 +msgid "``waitrw`` -- the instance was switched to the read-only mode (for example, by using ``box.cfg.read_only``), so the upgrade couldn't proceed. The upgrade process will resume as soon as the instance switches back to read-write mode. Nevertheless, the upgrade function is applied to all tuples returned to the user." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:285 +msgid "``error`` -- the upgrade operation failed with an error. See the ``error`` field for the error message. See the log for the tuple that caused the error. No alter operation is allowed, except for another upgrade, supposed to fix the problem. Nevertheless, the upgrade function is applied to all tuples returned to the user. The space is writable." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:290 +msgid "``done`` -- the upgrade operation is successfully completed. The upgrade function is not applied to tuples returned to the user anymore. The function can be deleted." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:293 +msgid "``replica`` -- the upgrade operation is either running or completed with an error on another instance. See the ``owner`` field for the UUID of the instance running the upgrade. Nevertheless, the upgrade function is applied to all tuples returned to the user." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:303 +msgid "Interaction with alter" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:305 +msgid "While a space upgrade is in progress, the space can't be altered or dropped. The attempt to do that will throw an exception. Restarting an upgrade is allowed in case the currently running upgrade is canceled or completed with an error. It means the manual restart is possible if the upgrade operation is in the :ref:`error state `." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:310 +msgid "If a space upgrade was canceled or failed with an error, the space can't be altered or dropped. The only option is to restart the upgrade using a different upgrade function or format." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:314 +msgid "Interaction with recovery" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:316 +msgid "The space upgrade state is persisted. It is stored in the ``_space`` system table. If an instance with a space upgrade in progress (``inprogress`` state) is shut down, it restarts the space upgrade after recovery. If a space upgrade fails (switches to the ``error`` state), it remains in the error state after recovery." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:321 +msgid "Interaction with replication" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:323 +msgid "The changes made to a space by a space upgrade are replicated. Just as on the instance where the upgrade is performed, the upgrade function is applied to all tuples returned to the user on the replicas. However, the upgrade operation is not performed on the replicas in the background. The replicas wait for the upgrade operation to complete on the master. They can't alter or drop the space. Normally, they can't cancel or restart the upgrade operation either." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:329 +msgid "There is an emergency exception when the master is permanently dead. It is possible to restart a space upgrade that started on another instance. The restart is possible if the upgrade owner UUID (see the ``owner`` field) has been deleted from the ``_cluster`` system table." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:336 +msgid "Except the ``dryrun`` mode, the upgrade can only be performed on the master. If the instance is no longer the master, the upgrade is suspended until the instance is master again. Restarting the upgrade on a new master works only if the old one has been removed from the replica set (``_cluster`` system space)." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:344 +msgid "Usage example" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:346 +msgid "Suppose there are two columns in the space `test` -- ``id`` (unsigned) and ``data`` (string). The example shows how to upgrade the schema and add another column to the space using ``space:upgrade()``. The new column contains the ``id`` values converted to string. Each step takes a while." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:350 +msgid "The test space is generated with the following script:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:352 +msgid "local log = require('log')\n" +"box.cfg{\n" +" checkpoint_count = 1,\n" +" memtx_memory = 5 * 1024 * 1024 * 1024,\n" +"}\n" +"box.schema.space.create('test')\n" +"box.space.test:format{\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'data', type = 'string'},\n" +"}\n" +"box.space.test:create_index('pk')\n" +"local count = 20 * 1000 * 1000\n" +"local progress = 0\n" +"box.begin()\n" +"for i = 1, count do\n" +" box.space.test:insert{i, 'data' .. i}\n" +"\n" +" if i % 1000 == 0 then\n" +" box.commit()\n" +" local p = math.floor(i / count * 100)\n" +" if progress ~= p then\n" +" progress = p\n" +" log.info('Generating test data set... %d%% done', p)\n" +" end\n" +" box.begin()\n" +" end\n" +"end\n" +"box.commit()\n" +"box.snapshot()\n" +"os.exit(0)" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:385 +msgid "To upgrade the space, connect to the server and then run the commands below:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:387 +msgid "localhost:3301> box.schema.func.create('convert', {\n" +" > language = 'lua',\n" +" > is_deterministic = true,\n" +" > body = [[function(t)\n" +" > if #t == 2 then\n" +" > return t:update({{'!', 2, tostring(t.id)}})\n" +" > else\n" +" > return t\n" +" > end\n" +" > end]],\n" +" > })\n" +"localhost:3301> box.space.test:upgrade({\n" +" > func = 'convert',\n" +" > format = {\n" +" > {name = 'id', type = 'unsigned'},\n" +" > {name = 'id_string', type = 'string'},\n" +" > {name = 'data', type = 'string'},\n" +" > },\n" +" > })" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:410 +msgid "While the upgrade is in progress, you can track the state of the upgrade. To check the status, connect to Tarantool from another console and run the following commands:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:413 +msgid "localhost:3311> box.space.test:upgrade()\n" +"---\n" +"- status: inprogress\n" +" progress: 8%\n" +" owner: 579a9e99-427e-4e99-9e2e-216bbd3098a7\n" +" func: convert\n" +"..." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:424 +msgid "Even though the upgrade is only 8% complete, selecting the data from the space returns the converted tuples:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:426 +msgid "localhost:3311> box.space.test:select({}, {iterator = 'req', limit = 5})\n" +"---\n" +"- - [20000000, '20000000', 'data20000000']\n" +" - [19999999, '19999999', 'data19999999']\n" +" - [19999998, '19999998', 'data19999998']\n" +" - [19999997, '19999997', 'data19999997']\n" +" - [19999996, '19999996', 'data19999996']\n" +"..." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:439 +msgid "The tuples contain the new field even though the space upgrade is still running." +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:442 +msgid "Wait for the space upgrade to complete using the command below:" +msgstr "" + +#: ../../doc/enterprise/space_upgrade.rst:444 +msgid "localhost:3311> box.space.test:upgrade():wait()" +msgstr "" diff --git a/locale/en/enterprise/system_metrics.pot b/locale/en/enterprise/system_metrics.pot new file mode 100644 index 0000000000..07d7c786b8 --- /dev/null +++ b/locale/en/enterprise/system_metrics.pot @@ -0,0 +1,435 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/system_metrics.rst:4 +msgid "Monitoring system metrics" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:12 +msgid "Option" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:12 +msgid "Description" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:12 +msgid "SNMP type" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:12 +msgid "Units of measure" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:12 +msgid "Threshold" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:14 +msgid "Version" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:14 +msgid "Tarantool version" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:14 +msgid "DisplayString" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:16 +msgid "IsAlive" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:16 +msgid "instance availability indicator" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:16 +#: ../../doc/enterprise/system_metrics.rst:42 +#: ../../doc/enterprise/system_metrics.rst:60 +msgid "Integer" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:18 +msgid "(listing)" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:16 +msgid "0 - unavailable" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:18 +msgid "1 - available" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:20 +msgid "MemoryLua" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:20 +msgid "storage space used by Lua" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:20 +#: ../../doc/enterprise/system_metrics.rst:22 +#: ../../doc/enterprise/system_metrics.rst:25 +#: ../../doc/enterprise/system_metrics.rst:27 +#: ../../doc/enterprise/system_metrics.rst:30 +#: ../../doc/enterprise/system_metrics.rst:37 +#: ../../doc/enterprise/system_metrics.rst:44 +#: ../../doc/enterprise/system_metrics.rst:46 +#: ../../doc/enterprise/system_metrics.rst:49 +#: ../../doc/enterprise/system_metrics.rst:51 +#: ../../doc/enterprise/system_metrics.rst:54 +#: ../../doc/enterprise/system_metrics.rst:57 +#: ../../doc/enterprise/system_metrics.rst:62 +#: ../../doc/enterprise/system_metrics.rst:64 +#: ../../doc/enterprise/system_metrics.rst:67 +msgid "Gauge32" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:20 +#: ../../doc/enterprise/system_metrics.rst:22 +#: ../../doc/enterprise/system_metrics.rst:25 +#: ../../doc/enterprise/system_metrics.rst:27 +#: ../../doc/enterprise/system_metrics.rst:30 +msgid "Mbyte" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:20 +msgid "900" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:22 +msgid "MemoryData" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:22 +msgid "storage space used for storing data" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:22 +#: ../../doc/enterprise/system_metrics.rst:27 +msgid "set the value manually" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:25 +msgid "MemoryNet" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:25 +msgid "storage space used for network I/O" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:25 +msgid "1024" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:27 +msgid "MemoryIndex" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:27 +msgid "storage space used for storing indexes" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:30 +msgid "MemoryCache" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:30 +msgid "storage space used for storing caches (for vinyl engine only)" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:33 +msgid "ReplicationLag" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:33 +msgid "lag time since the last sync between (the maximum value in case there are multiple fibers)" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:33 +msgid "Integer32" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:33 +msgid "sec." +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:33 +msgid "5" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:37 +msgid "FiberCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:37 +msgid "number of fibers" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:37 +#: ../../doc/enterprise/system_metrics.rst:44 +#: ../../doc/enterprise/system_metrics.rst:46 +#: ../../doc/enterprise/system_metrics.rst:49 +#: ../../doc/enterprise/system_metrics.rst:51 +#: ../../doc/enterprise/system_metrics.rst:54 +#: ../../doc/enterprise/system_metrics.rst:57 +#: ../../doc/enterprise/system_metrics.rst:62 +#: ../../doc/enterprise/system_metrics.rst:64 +#: ../../doc/enterprise/system_metrics.rst:67 +#: ../../doc/enterprise/system_metrics.rst:70 +#: ../../doc/enterprise/system_metrics.rst:72 +#: ../../doc/enterprise/system_metrics.rst:74 +#: ../../doc/enterprise/system_metrics.rst:76 +#: ../../doc/enterprise/system_metrics.rst:78 +#: ../../doc/enterprise/system_metrics.rst:80 +#: ../../doc/enterprise/system_metrics.rst:82 +#: ../../doc/enterprise/system_metrics.rst:84 +#: ../../doc/enterprise/system_metrics.rst:86 +#: ../../doc/enterprise/system_metrics.rst:88 +msgid "pc." +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:37 +msgid "1000" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:39 +msgid "CurrentTime" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:39 +msgid "current time, in seconds, starting at January, 1st, 1970" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:39 +msgid "Unsigned32" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:39 +msgid "Unix timestamp, in sec." +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:42 +msgid "StorageStatus" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:42 +msgid "status of a replica set" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:42 +#: ../../doc/enterprise/system_metrics.rst:60 +msgid "listing" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:42 +#: ../../doc/enterprise/system_metrics.rst:60 +msgid "> 1" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:44 +msgid "StorageAlerts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:44 +msgid "number of alerts for storage nodes" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:44 +#: ../../doc/enterprise/system_metrics.rst:62 +msgid ">= 1" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:46 +msgid "StorageTotalBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:46 +msgid "total number of buckets in the storage" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:46 +#: ../../doc/enterprise/system_metrics.rst:49 +#: ../../doc/enterprise/system_metrics.rst:51 +#: ../../doc/enterprise/system_metrics.rst:54 +#: ../../doc/enterprise/system_metrics.rst:57 +#: ../../doc/enterprise/system_metrics.rst:64 +#: ../../doc/enterprise/system_metrics.rst:67 +msgid "< 0" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:49 +msgid "StorageActiveBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:49 +msgid "number of buckets in the ACTIVE state" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:51 +msgid "StorageGarbageBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:51 +msgid "number of buckets in the GARBAGE state" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:54 +msgid "StorageReceivingBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:54 +msgid "number of buckets in the RECEIVING state" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:57 +msgid "StorageSendingBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:57 +msgid "number of buckets in the SENDING state" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:60 +msgid "RouterStatus" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:60 +msgid "status of the ``router``" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:62 +msgid "RouterAlerts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:62 +msgid "number of alerts for the router" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:64 +msgid "RouterKnownBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:64 +msgid "number of buckets within the known destination replica sets" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:67 +msgid "RouterUnknownBkts" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:67 +msgid "number of buckets that are unknown to the ``router``" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:70 +msgid "RequestCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:70 +msgid "total number of requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:70 +#: ../../doc/enterprise/system_metrics.rst:72 +#: ../../doc/enterprise/system_metrics.rst:74 +#: ../../doc/enterprise/system_metrics.rst:76 +#: ../../doc/enterprise/system_metrics.rst:78 +#: ../../doc/enterprise/system_metrics.rst:80 +#: ../../doc/enterprise/system_metrics.rst:82 +#: ../../doc/enterprise/system_metrics.rst:84 +#: ../../doc/enterprise/system_metrics.rst:86 +#: ../../doc/enterprise/system_metrics.rst:88 +msgid "Counter64" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:72 +msgid "InsertCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:72 +msgid "total number of insert requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:74 +msgid "DeleteCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:74 +msgid "total number of delete requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:76 +msgid "ReplaceCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:76 +msgid "total number of replace requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:78 +msgid "UpdateCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:78 +msgid "total number of update requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:80 +msgid "SelectCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:80 +msgid "total number of select requests" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:82 +msgid "EvalCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:82 +msgid "number of calls made via Eval" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:84 +msgid "CallCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:84 +msgid "number of calls made via ``call``" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:86 +msgid "ErrorCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:86 +msgid "number of errors in Tarantool" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:88 +msgid "AuthCount" +msgstr "" + +#: ../../doc/enterprise/system_metrics.rst:88 +msgid "number of completed authentication operations" +msgstr "" diff --git a/locale/en/enterprise/tuple_compression.pot b/locale/en/enterprise/tuple_compression.pot new file mode 100644 index 0000000000..5cd3ab5614 --- /dev/null +++ b/locale/en/enterprise/tuple_compression.pot @@ -0,0 +1,252 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/tuple_compression.rst:4 +msgid "Tuple compression" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:6 +msgid "Tuple compression, introduced in Tarantool Enterprise Edition 2.10.0, aims to save memory space. Typically, it decreases the volume of stored data by 15%. However, the exact volume saved depends on the type of data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:10 +msgid "The following compression algorithms are supported:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:12 +msgid "`lz4 `_" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:13 +msgid "`zstd `_" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:14 +msgid "`zlib `_ (since :doc:`2.11.0 `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:16 +msgid "To learn about the performance costs of each algorithm, check :ref:`Tuple compression performance `." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:19 +msgid "Tarantool doesn't compress tuples themselves, just the fields inside these tuples. You can only compress non-indexed fields. Compression works best when JSON is stored in the field." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:25 +msgid "The :ref:`compress ` module provides the API for compressing and decompressing data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:31 +msgid "Enabling compression for a new space" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:33 +msgid "First, create a space:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:35 +msgid "box.schema.space.create('bands')" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:39 +msgid "Then, create an index for this space, for example:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:41 +msgid "box.space.bands:create_index('primary', {parts = {{1, 'unsigned'}}})" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:45 +msgid "Create a format to declare field names and types. In the example below, the ``band_name`` and ``year`` fields have the ``zstd`` and ``lz4`` compression formats, respectively. The first field (``id``) has the index, so it cannot be compressed." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:49 +msgid "box.space.bands:format({\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'band_name', type = 'string', compression = 'zstd'},\n" +" {name = 'year', type = 'unsigned', compression = 'lz4'}\n" +" })" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:57 +msgid "Now, the new tuples that you add to the space ``bands`` will be compressed. When you read a compressed tuple, you do not need to decompress it back yourself." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:65 +msgid "Checking which fields are compressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:67 +msgid "To check which fields in a space are compressed, run :ref:`space_object:format() ` on the space. If a field is compressed, the format includes the compression algorithm, for example:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:71 +msgid "tarantool> box.space.bands:format()\n" +" ---\n" +" - [{'name': 'id', 'type': 'unsigned'},\n" +" {'type': 'string', 'compression': 'zstd', 'name': 'band_name'},\n" +" {'type': 'unsigned', 'compression': 'lz4', 'name': 'year'}]\n" +" ..." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:85 +msgid "Enabling compression for existing spaces" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:87 +msgid "You can enable compression for existing fields. All the tuples added after that will have this field compressed. However, this doesn't affect the tuples already stored in the space. You need to make the snapshot and restart Tarantool to compress the existing tuples." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:92 +msgid "Here's an example of how to compress existing fields:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:94 +msgid "Create a space without compression and add several tuples:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:96 +msgid "box.schema.space.create('bands')\n" +"\n" +"box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"\n" +"box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:113 +msgid "Suppose that you want fields 2 and 3 to be compressed from now on. To enable compression, change the format as follows:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:116 +msgid "local new_format = box.space.bands:format()\n" +"\n" +"new_format[2].compression = 'zstd'\n" +"new_format[3].compression = 'lz4'\n" +"\n" +"box.space.bands:format(new_format)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:125 +msgid "From now on, all the tuples that you add to the space have fields 2 and 3 compressed." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:127 +msgid "To finalize the change, create a snapshot by running :ref:`box.snapshot() ` and restart Tarantool. As a result, all old tuples will also be compressed in memory during recovery." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:133 +msgid ":doc:`space:upgrade() ` provides the ability to enable compression and update the existing tuples in the background. To achieve this, you need to pass a new space format in the ``format`` argument of ``space:upgrade()``." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:141 +msgid "Tuple compression performance" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:143 +msgid "Below are the results of a `synthetic test `_ that illustrate how tuple compression affects performance. The test was carried out on a simple Tarantool space containing 100,000 tuples, each having a field with a sample JSON roughly 600 bytes large. The test compared the speed of running ``select`` and ``replace`` operations on uncompressed and compressed data as well as the overall data size of the space. Performance is measured in requests per second." +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:156 +msgid "Compression type" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:157 +msgid "``select``, RPS" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:158 +msgid "``replace``, RPS" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:159 +msgid "Space size, bytes" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:160 +msgid "None" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:161 +msgid "4,486k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:162 +msgid "1,109k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:163 +msgid "41,168,548" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:164 +msgid "``zstd``" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:165 +msgid "308k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:166 +msgid "26k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:167 +msgid "21,368,548" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:168 +msgid "``lz4``" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:169 +msgid "1,765k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:170 +msgid "672k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:171 +msgid "25,268,548" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:172 +msgid "``zlib``" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:173 +msgid "325k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:174 +msgid "107k" +msgstr "" + +#: ../../doc/enterprise/tuple_compression.rst:175 +msgid "20,768,548" +msgstr "" diff --git a/locale/en/enterprise/tuple_compression/api/compress.pot b/locale/en/enterprise/tuple_compression/api/compress.pot new file mode 100644 index 0000000000..a9e770dbc1 --- /dev/null +++ b/locale/en/enterprise/tuple_compression/api/compress.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/tuple_compression/api/compress.rst:4 +msgid "Module compress" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/compress.rst:8 +msgid "**Since:** :doc:`2.11.0 `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/compress.rst:10 +msgid "The ``compress`` module provides a set of submodules for compressing and decompressing data using different algorithms:" +msgstr "" diff --git a/locale/en/enterprise/tuple_compression/api/lz4.pot b/locale/en/enterprise/tuple_compression/api/lz4.pot new file mode 100644 index 0000000000..3bf70a9f1c --- /dev/null +++ b/locale/en/enterprise/tuple_compression/api/lz4.pot @@ -0,0 +1,228 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:4 +msgid "Submodule compress.lz4" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:11 +msgid "The ``compress.lz4`` submodule provides the ability to compress and decompress data using the `lz4 `_ algorithm. You can use the ``lz4`` compressor as follows:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:14 +msgid "Create a compressor instance using the :ref:`compress.lz4.new() ` function:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:16 +msgid "local lz4_compressor = require('compress.lz4').new()\n" +"-- or --\n" +"local lz4_compressor = require('compress').lz4.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:22 +msgid "Optionally, you can pass compression options (:ref:`lz4_opts `) specific for ``lz4``:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:24 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:90 +msgid "local lz4_compressor = require('compress.lz4').new({\n" +" acceleration = 1000,\n" +" decompress_buffer_size = 2097152\n" +"})\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:28 +msgid "To compress the specified data, use the :ref:`compress() ` method:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:30 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:118 +msgid "compressed_data = lz4_compressor:compress('Hello world!')\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:34 +msgid "To decompress data, call :ref:`decompress() `:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:36 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:135 +msgid "decompressed_data = lz4_compressor:decompress(compressed_data)\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:45 +msgid "API Reference" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:55 +msgid "**Functions**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:58 +msgid ":ref:`compress.lz4.new() `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:59 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:81 +msgid "Create a ``lz4`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:61 +msgid "**Objects**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:64 +msgid ":ref:`lz4_compressor `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:65 +msgid "A ``lz4`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:67 +msgid ":ref:`lz4_opts `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:68 +msgid "Configuration options of the ``lz4`` compressor." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:75 +msgid "compress.lz4.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:83 +msgid "``lz4`` compression options (see :ref:`lz4_opts `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:85 +msgid "a new ``lz4`` compressor instance (see :ref:`lz4_compressor `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:86 +msgid "userdata" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:88 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:116 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:133 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:150 +msgid "**Example**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:98 +msgid "lz4_compressor" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:102 +msgid "A compressor instance that exposes the API for compressing and decompressing data using the ``lz4`` algorithm. To create the ``lz4`` compressor, call :ref:`compress.lz4.new() `." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:109 +msgid "Compress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:111 +msgid "data to be compressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:113 +msgid "compressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:114 +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:131 +msgid "string" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:126 +msgid "Decompress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:128 +msgid "data to be decompressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:130 +msgid "decompressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:143 +msgid "lz4_opts" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:147 +msgid "Configuration options of the :ref:`lz4_compressor `. These options can be passed to the :ref:`compress.lz4.new() ` function." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:152 +msgid "local lz4_compressor = require('compress.lz4').new({\n" +" acceleration = 1000,\n" +" decompress_buffer_size = 2097152\n" +"})\n" +"\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:160 +msgid "Specifies the acceleration factor that enables you to adjust the compression ratio and speed. The higher acceleration factor increases the compression speed but decreases the compression ratio." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:163 +msgid "Default: 1" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:164 +msgid "Maximum: 65537" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:165 +msgid "Minimum: 1" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:172 +msgid "Specifies the decompress buffer size (in bytes). If the size of decompressed data is larger than this value, the compressor returns an error on decompression." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/lz4.rst:175 +msgid "Default: 1048576" +msgstr "" diff --git a/locale/en/enterprise/tuple_compression/api/zlib.pot b/locale/en/enterprise/tuple_compression/api/zlib.pot new file mode 100644 index 0000000000..5a826dbb88 --- /dev/null +++ b/locale/en/enterprise/tuple_compression/api/zlib.pot @@ -0,0 +1,250 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:4 +msgid "Submodule compress.zlib" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:11 +msgid "The ``compress.zlib`` submodule provides the ability to compress and decompress data using the `zlib `_ algorithm. You can use the ``zlib`` compressor as follows:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:14 +msgid "Create a compressor instance using the :ref:`compress.zlib.new() ` function:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:16 +msgid "local zlib_compressor = require('compress.zlib').new()\n" +"-- or --\n" +"local zlib_compressor = require('compress').zlib.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:22 +msgid "Optionally, you can pass compression options (:ref:`zlib_opts `) specific for ``zlib``:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:24 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:90 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:152 +msgid "local zlib_compressor = require('compress.zlib').new({\n" +" level = 5,\n" +" mem_level = 5,\n" +" strategy = 'filtered'\n" +"})\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:28 +msgid "To compress the specified data, use the :ref:`compress() ` method:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:30 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:118 +msgid "compressed_data = zlib_compressor:compress('Hello world!')\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:34 +msgid "To decompress data, call :ref:`decompress() `:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:36 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:135 +msgid "decompressed_data = zlib_compressor:decompress(compressed_data)\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:45 +msgid "API Reference" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:55 +msgid "**Functions**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:58 +msgid ":ref:`compress.zlib.new() `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:59 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:81 +msgid "Create a ``zlib`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:61 +msgid "**Objects**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:64 +msgid ":ref:`zlib_compressor `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:65 +msgid "A ``zlib`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:67 +msgid ":ref:`zlib_opts `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:68 +msgid "Configuration options of the ``zlib`` compressor." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:75 +msgid "compress.zlib.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:83 +msgid "``zlib`` compression options (see :ref:`zlib_opts `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:85 +msgid "a new ``zlib`` compressor instance (see :ref:`zlib_compressor `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:86 +msgid "userdata" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:88 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:116 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:133 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:150 +msgid "**Example**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:98 +msgid "zlib_compressor" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:102 +msgid "A compressor instance that exposes the API for compressing and decompressing data using the ``zlib`` algorithm. To create the ``zlib`` compressor, call :ref:`compress.zlib.new() `." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:109 +msgid "Compress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:111 +msgid "data to be compressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:113 +msgid "compressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:114 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:131 +msgid "string" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:126 +msgid "Decompress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:128 +msgid "data to be decompressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:130 +msgid "decompressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:143 +msgid "zlib_opts" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:147 +msgid "Configuration options of the :ref:`zlib_compressor `. These options can be passed to the :ref:`compress.zlib.new() ` function." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:160 +msgid "Specifies the ``zlib`` compression level that enables you to adjust the compression ratio and speed. The lower level improves the compression speed at the cost of compression ratio." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:163 +msgid "Default: 6" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:164 +msgid "Minimum: 0 (no compression)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:165 +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:177 +msgid "Maximum: 9" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:172 +msgid "Specifies how much memory is allocated for the ``zlib`` compressor. The larger value improves the compression speed and ratio." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:175 +msgid "Default: 8" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:176 +msgid "Minimum: 1" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:184 +msgid "Specifies the compression strategy. The possible values:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:186 +msgid "``default`` - for normal data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:187 +msgid "``huffman_only`` - forces Huffman encoding only (no string match). The fastest compression algorithm but not very effective in compression for most of the data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:188 +msgid "``filtered`` - for data produced by a filter or predictor. Filtered data consists mostly of small values with a somewhat random distribution. This compression algorithm is tuned to compress them better." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:189 +msgid "``rle`` - limits match distances to one (run-length encoding). ``rle`` is designed to be almost as fast as ``huffman_only`` but gives better compression for PNG image data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zlib.rst:190 +msgid "``fixed`` - prevents the use of dynamic Huffman codes and provides a simpler decoder for special applications." +msgstr "" diff --git a/locale/en/enterprise/tuple_compression/api/zstd.pot b/locale/en/enterprise/tuple_compression/api/zstd.pot new file mode 100644 index 0000000000..f95731b69e --- /dev/null +++ b/locale/en/enterprise/tuple_compression/api/zstd.pot @@ -0,0 +1,215 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:4 +msgid "Submodule compress.zstd" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:11 +msgid "The ``compress.zstd`` submodule provides the ability to compress and decompress data using the `zstd `_ algorithm. You can use the ``zstd`` compressor as follows:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:14 +msgid "Create a compressor instance using the :ref:`compress.zstd.new() ` function:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:16 +msgid "local zstd_compressor = require('compress.zstd').new()\n" +"-- or --\n" +"local zstd_compressor = require('compress').zstd.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:22 +msgid "Optionally, you can pass compression options (:ref:`zstd_opts `) specific for ``zstd``:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:24 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:90 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:152 +msgid "local zstd_compressor = require('compress.zstd').new({\n" +" level = 5\n" +"})\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:28 +msgid "To compress the specified data, use the :ref:`compress() ` method:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:30 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:118 +msgid "compressed_data = zstd_compressor:compress('Hello world!')\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:34 +msgid "To decompress data, call :ref:`decompress() `:" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:36 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:135 +msgid "decompressed_data = zstd_compressor:decompress(compressed_data)\n" +"" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:45 +msgid "API Reference" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:55 +msgid "**Functions**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:58 +msgid ":ref:`compress.zstd.new() `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:59 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:81 +msgid "Create a ``zstd`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:61 +msgid "**Objects**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:64 +msgid ":ref:`zstd_compressor `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:65 +msgid "A ``zstd`` compressor instance." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:67 +msgid ":ref:`zstd_opts `" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:68 +msgid "Configuration options of the ``zstd`` compressor." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:75 +msgid "compress.zstd.new()" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:83 +msgid "``zstd`` compression options (see :ref:`zstd_opts `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:85 +msgid "a new ``zstd`` compressor instance (see :ref:`zstd_compressor `)" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:86 +msgid "userdata" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:88 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:116 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:133 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:150 +msgid "**Example**" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:98 +msgid "zstd_compressor" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:102 +msgid "A compressor instance that exposes the API for compressing and decompressing data using the ``zstd`` algorithm. To create the ``zstd`` compressor, call :ref:`compress.zstd.new() `." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:109 +msgid "Compress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:111 +msgid "data to be compressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:113 +msgid "compressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:114 +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:131 +msgid "string" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:126 +msgid "Decompress the specified data." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:128 +msgid "data to be decompressed" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:130 +msgid "decompressed data" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:143 +msgid "zstd_opts" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:147 +msgid "Configuration options of the :ref:`zstd_compressor `. These options can be passed to the :ref:`compress.zstd.new() ` function." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:160 +msgid "Specifies the ``zstd`` compression level that enables you to adjust the compression ratio and speed. The lower level improves the compression speed at the cost of compression ratio. For example, you can use level 1 if speed is most important and level 22 if size is most important." +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:164 +msgid "Default: 3" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:165 +msgid "Minimum: -131072" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:166 +msgid "Maximum: 22" +msgstr "" + +#: ../../doc/enterprise/tuple_compression/api/zstd.rst:170 +msgid "Assigning 0 to ``level`` resets its value to the default (3)." +msgstr "" diff --git a/locale/en/enterprise/wal_extensions.pot b/locale/en/enterprise/wal_extensions.pot new file mode 100644 index 0000000000..e374088840 --- /dev/null +++ b/locale/en/enterprise/wal_extensions.pot @@ -0,0 +1,200 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/wal_extensions.rst:4 +msgid "WAL extensions" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:6 +msgid "WAL extensions available in Tarantool Enterprise Edition allow you to add auxiliary information to each :ref:`write-ahead log ` record. For example, you can enable storing an old and new tuple for each CRUD operation performed. This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:15 +msgid "Configuration" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:17 +msgid "To configure WAL extensions, use the ``wal_ext`` :ref:`configuration property `. Inside the ``wal_ext`` block, you can enable storing old and new tuples as follows:" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:20 +msgid "Set the ``old`` and ``new`` options to ``true`` to store old and new tuples in a write-ahead log for all spaces." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:22 +msgid "box.cfg {\n" +" wal_ext = { old = true, new = true }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:28 +msgid "To adjust these options for specific spaces, use the ``spaces`` option." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:30 +msgid "box.cfg {\n" +" wal_ext = {\n" +" old = true, new = true,\n" +" spaces = {\n" +" space1 = { old = false },\n" +" space2 = { new = false }\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:43 +msgid "The configuration for specific spaces has priority over the global configuration, so only new tuples are added to the log for ``space1`` and only old tuples for ``space2``." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:46 +msgid "Note that records with additional fields are :ref:`replicated ` as follows:" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:48 +msgid "If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:49 +msgid "If a replica and master have different configurations for WAL records, a master's configuration is ignored." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:55 +#: ../../doc/enterprise/wal_extensions.rst:68 +msgid "Example" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:57 +msgid "The table below demonstrates how write-ahead log records might look for the specific :ref:`CRUD operations ` if storing old and new tuples is enabled for the ``bands`` space." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:67 +msgid "Operation" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:69 +msgid "WAL information" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:70 +msgid "insert" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:71 +msgid "``bands:insert{4, 'The Beatles', 1960}``" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**new_tuple**: [4, 'The Beatles', 1960]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "tuple: [4, 'The Beatles', 1960]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:74 +msgid "delete" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:75 +msgid "``bands:delete{4}``" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "key: [4]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**old_tuple**: [4, 'The Beatles', 1960]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:78 +msgid "update" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:79 +msgid "``bands:update({2}, {{'=', 2, 'Pink Floyd'}})``" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**new_tuple**: [2, 'Pink Floyd', 1965]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**old_tuple**: [2, 'Scorpions', 1965]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "key: [2]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "tuple: [['=', 2, 'Pink Floyd']]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:84 +msgid "upsert" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:85 +msgid "``bands:upsert({2, 'Pink Floyd', 1965}, {{'=', 2, 'The Doors'}})``" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**new_tuple**: [2, 'The Doors', 1965]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**old_tuple**: [2, 'Pink Floyd', 1965]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "operations: [['=', 2, 'The Doors']]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "tuple: [2, 'Pink Floyd', 1965]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:90 +msgid "replace" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:91 +msgid "``bands:replace{1, 'The Beatles', 1960}``" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**old_tuple**: [1, 'Roxette', 1986]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "**new_tuple**: [1, 'The Beatles', 1960]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:0 +msgid "tuple: [1, 'The Beatles', 1960]" +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:96 +msgid "Storing both old and new tuples is especially useful for the ``update`` operation because a write-ahead log record contains only a key value." +msgstr "" + +#: ../../doc/enterprise/wal_extensions.rst:101 +msgid "You can use the :doc:`tt cat ` command to see the contents of a write-ahead log." +msgstr "" diff --git a/locale/en/getting_started/getting_started_db.pot b/locale/en/getting_started/getting_started_db.pot new file mode 100644 index 0000000000..d37271de59 --- /dev/null +++ b/locale/en/getting_started/getting_started_db.pot @@ -0,0 +1,391 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-25 11:48+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_db.rst:4 +msgid "Creating your first Tarantool database" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:6 +msgid "In this tutorial, you connect to Tarantool instances using the :ref:`tt CLI ` utility, create a database, and establish a remote connection using the :ref:`net.box ` module." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:10 +msgid "Installing Tarantool" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:12 +msgid "For production purposes, we recommend that you install Tarantool via the `official package manager `_. To download and install the package that's appropriate for your OS, start a shell (terminal) and enter the command-line instructions provided for your OS at Tarantool `download page `_." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:21 +msgid "Installing tt CLI" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:23 +msgid "Before starting this tutorial:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:25 +msgid "Install the :ref:`tt CLI ` utility." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:27 +msgid "Create a tt environment in the current directory using the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:29 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create the ``create_db`` directory." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:31 +msgid "Inside ``instances.enabled/create_db``, create the ``instances.yml`` and ``config.yaml`` files:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:33 +msgid "``instances.yml`` specifies instances to run in the current environment. In this example, there is one instance:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:35 +msgid "instance001:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:39 +msgid "``config.yaml`` contains basic :ref:`configuration `, for example:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:41 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:45 +msgid "The instance in the configuration accepts TCP requests on port ``3301``." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:47 +msgid "Read more: :ref:`admin-instance_config-develop-app`." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:52 +msgid "Starting Tarantool" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:54 +msgid "First, start the Tarantool instance from the tt environment directory using :ref:`tt start `:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:57 +msgid "$ tt start create_db" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:61 +msgid "To check the running instances, use the :ref:`tt status ` command:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:63 +msgid "$ tt status create_db\n" +"INSTANCE STATUS PID\n" +"create_db:instance001 RUNNING 54560" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:69 +msgid "After that, connect to the instance with :ref:`tt connect `:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:71 +msgid "$ tt connect create_db:instance001" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:75 +msgid "This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt. Now you can enter requests on the command line." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:80 +msgid "On production machines, Tarantool's interactive mode is designed for system administration only. We use it for most examples in this manual because it is convenient for learning." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:87 +msgid "Creating a database" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:89 +msgid "To create a test database after installation:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:91 +msgid "Create a :term:`space ` named ``bands``:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:93 +msgid "box.schema.space.create('bands')\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:98 +msgid "Format the created space by specifying :term:`field` names and :ref:`types `:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:100 +msgid "box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:105 +msgid "Create the first :ref:`index ` named ``primary``:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:107 +msgid "box.space.bands:create_index('primary', { type = \"tree\", parts = { 'id' } })\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:112 +msgid "This is a primary index based on the ``id`` field of each tuple. ``TREE`` is the most universal index type. To learn more, check the documentation on Tarantool :ref:`index types `." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:115 +msgid "Insert three :term:`tuples ` into the space:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:117 +msgid "box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:122 +msgid "Then select a tuple using the ``primary`` index:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:124 +msgid "box.space.bands:select { 3 }\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:129 +msgid "Add a secondary index based on the ``band_name`` field:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:131 +msgid "box.space.bands:create_index('secondary', { type = \"tree\", parts = { 'band_name' } })\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:136 +msgid "Select tuples using the ``secondary`` index:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:138 +msgid "box.space.bands.index.secondary:select{'Scorpions'}\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:143 +msgid "To prepare for the example in the next section, grant read, write, and execute privileges to the current user:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:146 +msgid "box.schema.user.grant('guest', 'read,write,execute', 'universe')\n" +"" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:151 +msgid "The full example in the terminal looks like this:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:153 +msgid "create_db:instance001> box.schema.space.create('bands')\n" +"---\n" +"...\n" +"create_db:instance001> box.space.bands:format({\n" +" > {name = 'id', type = 'unsigned'},\n" +" > {name = 'band_name', type = 'string'},\n" +" > {name = 'year', type = 'unsigned'}\n" +" > })\n" +"---\n" +"...\n" +"create_db:instance001> box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"---\n" +"- unique: true\n" +" parts:\n" +" - type: unsigned\n" +" is_nullable: false\n" +" fieldno: 1\n" +" id: 0\n" +" space_id: 512\n" +" name: primary\n" +" type: TREE\n" +"...\n" +"create_db:instance001> box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"---\n" +"- [1, 'Roxette', 1986]\n" +"...\n" +"create_db:instance001> box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"---\n" +"- [2, 'Scorpions', 1965]\n" +"...\n" +"create_db:instance001> box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"---\n" +"- [3, 'Ace of Base', 1987]\n" +"...\n" +"create_db:instance001> box.space.bands:select { 3 }\n" +"---\n" +"- - [3, 'Ace of Base', 1987]\n" +"...\n" +"create_db:instance001> box.space.bands:create_index('secondary', { parts = { 'band_name' } })\n" +"---\n" +"- unique: true\n" +" parts:\n" +" - fieldno: 2\n" +" sort_order: asc\n" +" type: string\n" +" exclude_null: false\n" +" is_nullable: false\n" +" hint: true\n" +" id: 1\n" +" type: TREE\n" +" space_id: 512\n" +" name: secondary\n" +"...\n" +"create_db:instance001> s.index.secondary:select{'Scorpions'}\n" +"---\n" +"- - [2, 'Scorpions', 1965]\n" +"...\n" +"create_db:instance001> box.schema.user.grant('guest', 'read,write,execute', 'universe')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:219 +msgid "Connecting remotely" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:221 +msgid "In the configuration file (``config.yaml``), the instance listens on ``127.0.0.1:3301``:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:223 +msgid "instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:229 +msgid "The :ref:`iproto.listen ` option is an array of URIs used to listen for incoming requests. Each record of the array contains a required :ref:`URI ` (uniform resource identifier) field and an optional :ref:`params ` field. The ``iproto.listen.uri`` field may contain:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:234 +msgid "a listening address (for example, ``127.0.0.1:3301``)" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:235 +msgid "a listening port (for example, `3301`)" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:237 +msgid "The field can't contain parameters, login, or password." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:239 +msgid "Learn more about the :ref:`connection parameters `." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:241 +msgid "You can send requests to a Tarantool instance using:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:243 +msgid "``telnet``" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:244 +msgid "a :ref:`connector `" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:245 +msgid "another instance of Tarantool (using the :ref:`console ` module)" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:246 +msgid ":ref:`tt ` administrative utility" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:248 +msgid "In previous steps, the requests were sent using the tt utility. To connect from another Tarantool instance, start the ``tarantool`` executable with the ``-i`` option, which enables the interactive mode." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:252 +msgid "To start working, switch to another terminal and start another Tarantool instance:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:254 +msgid "$ tarantool -i" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:258 +msgid "Use the :ref:`net.box ` module to connect to the remote Tarantool instance that is listening on ``localhost:3301``:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:261 +msgid "tarantool> net_box = require('net.box')\n" +"---\n" +"...\n" +"tarantool> conn = net_box.connect(3301)\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:270 +msgid "Then send a select request to ``instance001``:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:272 +msgid "tarantool> conn.space.bands:select{2}\n" +"---\n" +"- - [2, 'Scorpions', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:279 +msgid "This request is equivalent to the local request ``box.space.bands:select{2}``. The result in this case is one of the tuples that was inserted earlier." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:282 +msgid "You can repeat ``box.space...:insert{}`` and ``box.space...:select{}`` (or ``conn.space...:insert{}`` and ``conn.space...:select{}``) indefinitely, on either Tarantool instance." +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:286 +msgid "When the tutorial is over, you can use :ref:`box.space.s:drop() ` to drop the space. To exit interactive console, enter ``Ctrl+D``. After that, to stop Tarantool instances, use the :ref:`tt stop ` command:" +msgstr "" + +#: ../../doc/how-to/getting_started_db.rst:290 +msgid "$ tt stop create_db" +msgstr "" diff --git a/locale/en/getting_started/index.pot b/locale/en/getting_started/index.pot new file mode 100644 index 0000000000..b7dba1c09e --- /dev/null +++ b/locale/en/getting_started/index.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/getting_started/index.rst:7 +msgid "Getting started" +msgstr "" + +#: ../../doc/getting_started/index.rst:11 +msgid "The :ref:`Creating your first Tarantool database ` section will get you acquainted with Tarantool. We will start Tarantool, create a data schema, and write our first data. You'll get an understanding of the technology and learn about the basic terms and features." +msgstr "" + +#: ../../doc/getting_started/index.rst:16 +msgid "To continue exploring Tarantool and its ecosystem, you might want to check out Tarantool :doc:`tutorials and guides <../how-to/index>`." +msgstr "" diff --git a/locale/en/getting_started/installation.pot b/locale/en/getting_started/installation.pot new file mode 100644 index 0000000000..47901dbdef --- /dev/null +++ b/locale/en/getting_started/installation.pot @@ -0,0 +1,242 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-08 07:55+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/setup.rst:5 +msgid "Setup" +msgstr "" + +#: ../../doc/enterprise/setup.rst:7 +msgid "This chapter explains how to download and set up Tarantool Enterprise Edition and run a sample application provided with it." +msgstr "" + +#: ../../doc/enterprise/setup.rst:14 +msgid "System requirements" +msgstr "" + +#: ../../doc/enterprise/setup.rst:16 +msgid "The recommended system requirements for running Tarantool Enterprise are as follows." +msgstr "" + +#: ../../doc/enterprise/setup.rst:23 +msgid "Hardware requirements" +msgstr "" + +#: ../../doc/enterprise/setup.rst:25 +msgid "To fully ensure the fault tolerance of a distributed data storage system, at least **three** physical computers or virtual servers are required." +msgstr "" + +#: ../../doc/enterprise/setup.rst:28 +msgid "For testing/development purposes, the system can be deployed using a smaller number of servers; however, it is not recommended to use such configurations for production." +msgstr "" + +#: ../../doc/enterprise/setup.rst:35 +msgid "Software requirements" +msgstr "" + +#: ../../doc/enterprise/setup.rst:37 +msgid "As host operating systems, Tarantool Enterprise Edition supports **Red Hat Enterprise Linux** and **CentOS** versions 7.5 and higher." +msgstr "" + +#: ../../doc/enterprise/setup.rst:42 +msgid "Tarantool Enterprise can run on other ``systemd``-based Linux distributions but it is not tested on them and may not work as expected." +msgstr "" + +#: ../../doc/enterprise/setup.rst:45 +msgid "``glibc`` 2.17-260.el7_6.6 and higher is required. Take care to check and update, if needed:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:48 +msgid "$ rpm -q glibc\n" +"glibc-2.17-196.el7_4.2\n" +"$ yum update glibc" +msgstr "" + +#: ../../doc/enterprise/setup.rst:58 +msgid "Network requirements" +msgstr "" + +#: ../../doc/enterprise/setup.rst:60 +msgid "Hereinafter, **\"storage servers\"** or **\"Tarantool servers\"** are the computers used to store and process data, and **\"administration server\"** is the computer used by the system operator to install and configure the product." +msgstr "" + +#: ../../doc/enterprise/setup.rst:64 +msgid "The Tarantool cluster has a full mesh topology, therefore all Tarantool servers should be able to communicate and send traffic from and to TCP/UDP ports used by the cluster's instances (see ``advertise_uri: :`` and ``config: advertise_uri: ':'`` in ``/etc/tarantool/conf.d/*.yml`` for each instance). For example:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:70 +msgid "# /etc/tarantool/conf.d/*.yml\n" +"\n" +"myapp.s2-replica:\n" +" advertise_uri: localhost:3305 # this is a TCP/UDP port\n" +" http_port: 8085\n" +"\n" +"all:\n" +" ...\n" +" hosts:\n" +" storage-1:\n" +" config:\n" +" advertise_uri: 'vm1:3301' # this is a TCP/UDP port\n" +" http_port: 8081" +msgstr "" + +#: ../../doc/enterprise/setup.rst:86 +msgid "To configure remote monitoring or to connect via the administrative console, the administration server should be able to access the following TCP ports on Tarantool servers:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:90 +msgid "22 to use the SSH protocol," +msgstr "" + +#: ../../doc/enterprise/setup.rst:91 +msgid "ports specified in instance configuration to monitor the HTTP-metrics." +msgstr "" + +#: ../../doc/enterprise/setup.rst:93 +msgid "Additionally, it is recommended to apply the following settings for ``sysctl`` on all Tarantool servers:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:96 +msgid "$ # TCP KeepAlive setting\n" +"$ sysctl -w net.ipv4.tcp_keepalive_time=60\n" +"$ sysctl -w net.ipv4.tcp_keepalive_intvl=5\n" +"$ sysctl -w net.ipv4.tcp_keepalive_probes=5" +msgstr "" + +#: ../../doc/enterprise/setup.rst:103 +msgid "This optional setup of the Linux network stack helps speed up the troubleshooting of network connectivity when the server physically fails. To achieve maximum performance, you may also need to configure other network stack parameters that are not specific to the Tarantool DBMS. For more information, please refer to the `Network Performance Tuning Guide `_ section of the RHEL7 user documentation." +msgstr "" + +#: ../../doc/enterprise/setup.rst:114 +msgid "Package contents" +msgstr "" + +#: ../../doc/enterprise/setup.rst:116 +msgid "The latest release packages of Tarantool Enterprise are available in the `customer zone `_ at Tarantool website. Please contact ``support@tarantool.io`` for access." +msgstr "" + +#: ../../doc/enterprise/setup.rst:120 +msgid "Each package is distributed as a ``tar + gzip`` archive and includes the following components and features:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:123 +msgid "Static Tarantool binary for simplified deployment in Linux environments." +msgstr "" + +#: ../../doc/enterprise/setup.rst:124 +msgid "``tt`` command-line utility that provides a unified command-line interface for managing Tarantool-based applications. See :ref:`tt-cli` for details." +msgstr "" + +#: ../../doc/enterprise/setup.rst:126 +msgid "|tcm_full_name| -- a web-based interface for managing Tarantool EE clusters. See :ref:`tcm` for details." +msgstr "" + +#: ../../doc/enterprise/setup.rst:128 +msgid "Selection of open and closed source modules." +msgstr "" + +#: ../../doc/enterprise/setup.rst:129 +msgid "Sample application walking you through all included modules" +msgstr "" + +#: ../../doc/enterprise/setup.rst:131 +msgid "Archive contents:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:133 +msgid "``tarantool`` is the main executable of Tarantool." +msgstr "" + +#: ../../doc/enterprise/setup.rst:134 +msgid "``tt`` command-line utility." +msgstr "" + +#: ../../doc/enterprise/setup.rst:135 +msgid "``tcm`` is the |tcm_full_name| executable." +msgstr "" + +#: ../../doc/enterprise/setup.rst:136 +msgid "``tarantoolctl`` is the utility script for installing supplementary modules and connecting to the administrative console." +msgstr "" + +#: ../../doc/enterprise/setup.rst:141 +msgid "``tarantoolctl`` is deprecated in favor of the :ref:`tt CLI utility `." +msgstr "" + +#: ../../doc/enterprise/setup.rst:143 +msgid "``examples/`` is the directory containing sample applications:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:145 +msgid "``pg_writethrough_cache/`` is an application showcasing how Tarantool can cache data written to, for example, a PostgreSQL database;" +msgstr "" + +#: ../../doc/enterprise/setup.rst:147 +msgid "``ora_writebehind_cache/`` is an application showcasing how Tarantool can cache writes and queue them to, for example, an Oracle database;" +msgstr "" + +#: ../../doc/enterprise/setup.rst:149 +msgid "``docker/`` is an application designed to be easily packed into a Docker container;" +msgstr "" + +#: ../../doc/enterprise/setup.rst:152 +msgid "``rocks/`` is the directory containing a selection of additional open and closed source modules included in the distribution as an offline rocks repository. See the :ref:`rocks reference ` for details." +msgstr "" + +#: ../../doc/enterprise/setup.rst:155 +msgid "``templates/`` is the directory containing template files for your application development environment." +msgstr "" + +#: ../../doc/enterprise/setup.rst:157 +msgid "``deprecated/`` is a set of modules that are no longer supported:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:159 +msgid "``vshard-zookeeper-orchestrator`` is a Python application for launching ``orchestrator``," +msgstr "" + +#: ../../doc/enterprise/setup.rst:161 +msgid "``zookeeper-scm`` files are the ZooKeeper integration modules (require ``usr/`` libraries)." +msgstr "" + +#: ../../doc/enterprise/setup.rst:169 +msgid "Installation" +msgstr "" + +#: ../../doc/enterprise/setup.rst:171 +msgid "The delivered ``tar + gzip`` archive should be uploaded to a server and unpacked:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:173 +msgid "$ tar xvf tarantool-enterprise-sdk-.tar.gz" +msgstr "" + +#: ../../doc/enterprise/setup.rst:177 +msgid "No further installation is required as the unpacked binaries are almost ready to go. Go to the directory with the binaries (``tarantool-enterprise``) and add them to the executable path by running the script provided by the distribution:" +msgstr "" + +#: ../../doc/enterprise/setup.rst:181 +msgid "$ source ./env.sh" +msgstr "" + +#: ../../doc/enterprise/setup.rst:185 +msgid "Make sure you have enough privileges to run the script and that the file is executable. Otherwise, try ``chmod`` and ``chown`` commands to adjust it." +msgstr "" + +#: ../../doc/enterprise/setup.rst:188 +msgid "Next, set up your development environment as described in :ref:`the developer's guide `." +msgstr "" diff --git a/locale/en/getting_started/vshard_quick.pot b/locale/en/getting_started/vshard_quick.pot new file mode 100644 index 0000000000..4cbb0bb4d4 --- /dev/null +++ b/locale/en/getting_started/vshard_quick.pot @@ -0,0 +1,227 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/vshard_quick.rst:4 +msgid "Quick start with sharding" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:6 +msgid "For installation instructions, check out the :ref:`vshard installation manual `." +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:8 +msgid "For a pre-configured development cluster, check out the ``example/`` directory in the `vshard repository `__. This example includes 5 Tarantool instances and 2 replica sets:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:12 +msgid "``router_1`` – a ``router`` instance" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:13 +msgid "``storage_1_a`` – a ``storage`` instance, the **master** of the **first** replica set" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:14 +msgid "``storage_1_b`` – a ``storage`` instance, the **replica** of the **first** replica set" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:15 +msgid "``storage_2_a`` – a ``storage`` instance, the **master** of the **second** replica set" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:16 +msgid "``storage_2_b`` – a ``storage`` instance, the **replica** of the **second** replica set" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:18 +msgid "All instances are managed using the :ref:`tt ` administrative utility." +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:20 +msgid "Change the directory to ``example/`` and use ``make`` to run the development cluster:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:22 +msgid "$ cd example/\n" +"$ make" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:27 +msgid "Essential ``make`` commands you need to know:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:29 +msgid "``make start`` – start all Tarantool instances" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:30 +msgid "``make stop`` – stop all Tarantool instances" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:31 +msgid "``make logcat`` – show logs from all instances" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:32 +msgid "``make enter`` – enter the admin console on ``router_1``" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:33 +msgid "``make clean`` – clean up all persistent data" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:34 +msgid "``make test`` – run the test suite (you can also run ``test-run.py`` in the ``test`` directory)" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:35 +msgid "``make`` – execute ``make stop``, ``make clean``, ``make start`` and ``make enter``" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:37 +msgid "For example, to start all instances, use ``make start``:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:39 +msgid "$ make start\n" +"$ ps x|grep tarantool\n" +"46564 ?? Ss 0:00.34 tarantool storage_1_a.lua \n" +"46566 ?? Ss 0:00.19 tarantool storage_1_b.lua \n" +"46568 ?? Ss 0:00.35 tarantool storage_2_a.lua \n" +"46570 ?? Ss 0:00.20 tarantool storage_2_b.lua \n" +"46572 ?? Ss 0:00.25 tarantool router_1.lua " +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:49 +msgid "To perform commands in the admin console, use the router's :ref:`public API `:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:52 +msgid "unix/:./data/router_1.control> vshard.router.info()\n" +"---\n" +"- replicasets:\n" +" ac522f65-aa94-4134-9f64-51ee384f1a54:\n" +" replica: &0\n" +" network_timeout: 0.5\n" +" status: available\n" +" uri: storage@127.0.0.1:3303\n" +" uuid: 1e02ae8a-afc0-4e91-ba34-843a356b8ed7\n" +" uuid: ac522f65-aa94-4134-9f64-51ee384f1a54\n" +" master: *0\n" +" cbf06940-0790-498b-948d-042b62cf3d29:\n" +" replica: &1\n" +" network_timeout: 0.5\n" +" status: available\n" +" uri: storage@127.0.0.1:3301\n" +" uuid: 8a274925-a26d-47fc-9e1b-af88ce939412\n" +" uuid: cbf06940-0790-498b-948d-042b62cf3d29\n" +" master: *1\n" +" bucket:\n" +" unreachable: 0\n" +" available_ro: 0\n" +" unknown: 0\n" +" available_rw: 3000\n" +" status: 0\n" +" alerts: []\n" +"..." +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:85 +msgid "Sample configuration" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:87 +msgid "The configuration of a simple sharded cluster can look like this:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:89 +msgid "local cfg = {\n" +" memtx_memory = 100 * 1024 * 1024,\n" +" bucket_count = 10000,\n" +" rebalancer_disbalance_threshold = 10,\n" +" rebalancer_max_receiving = 100,\n" +" sharding = {\n" +" ['cbf06940-0790-498b-948d-042b62cf3d29'] = {\n" +" replicas = {\n" +" ['8a274925-a26d-47fc-9e1b-af88ce939412'] = {\n" +" uri = 'storage:storage@127.0.0.1:3301',\n" +" name = 'storage_1_a',\n" +" master = true\n" +" },\n" +" ['3de2e3e1-9ebe-4d0d-abb1-26d301b84633'] = {\n" +" uri = 'storage:storage@127.0.0.1:3302',\n" +" name = 'storage_1_b'\n" +" }\n" +" },\n" +" },\n" +" ['ac522f65-aa94-4134-9f64-51ee384f1a54'] = {\n" +" replicas = {\n" +" ['1e02ae8a-afc0-4e91-ba34-843a356b8ed7'] = {\n" +" uri = 'storage:storage@127.0.0.1:3303',\n" +" name = 'storage_2_a',\n" +" master = true\n" +" },\n" +" ['001688c3-66f8-4a31-8e19-036c17d489c2'] = {\n" +" uri = 'storage:storage@127.0.0.1:3304',\n" +" name = 'storage_2_b'\n" +" }\n" +" },\n" +" },\n" +" },\n" +"}" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:126 +msgid "This cluster includes one ``router`` instance and two ``storage`` instances. Each ``storage`` instance includes one master and one replica. The ``sharding`` field defines the logical topology of a sharded Tarantool cluster. All the other fields are passed to ``box.cfg()`` as they are, without modifications. See the :ref:`Configuration reference ` section for details." +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:132 +msgid "On routers, call ``vshard.router.cfg(cfg)``:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:134 +msgid "cfg.listen = 3300\n" +"\n" +"-- Start the database with sharding\n" +"vshard = require('vshard')\n" +"vshard.router.cfg(cfg)" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:142 +msgid "On storages, call ``vshard.storage.cfg(cfg, instance_uuid)``:" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:144 +msgid "-- Get instance name\n" +"local MY_UUID = \"de0ea826-e71d-4a82-bbf3-b04a6413e417\"\n" +"\n" +"-- Call a configuration provider\n" +"local cfg = require('localcfg')\n" +"\n" +"-- Start the database with sharding\n" +"vshard = require('vshard')\n" +"vshard.storage.cfg(cfg, MY_UUID)" +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:156 +msgid "``vshard.storage.cfg()`` automatically calls ``box.cfg()`` and configures the listen port and replication parameters." +msgstr "" + +#: ../../doc/how-to/vshard_quick.rst:159 +msgid "For a sample configuration, see ``router.lua`` and ``storage.lua`` in the ``example/`` directory of the `vshard repository `__." +msgstr "" diff --git a/locale/en/how-to/getting_started_connectors.pot b/locale/en/how-to/getting_started_connectors.pot new file mode 100644 index 0000000000..d4e27ed0ec --- /dev/null +++ b/locale/en/how-to/getting_started_connectors.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_connectors.rst:5 +msgid "Connecting from your favorite language" +msgstr "" + +#: ../../doc/how-to/getting_started_connectors.rst:7 +msgid "In the :ref:`previous sections `, you have learned how to create a Tarantool database. Now let's see how to connect to the database from different programming languages, such as Python, PHP, Go, and C++, and execute typical requests for manipulating the data (select, insert, delete, and so on)." +msgstr "" diff --git a/locale/en/how-to/getting_started_go.pot b/locale/en/how-to/getting_started_go.pot new file mode 100644 index 0000000000..099ab71ad8 --- /dev/null +++ b/locale/en/how-to/getting_started_go.pot @@ -0,0 +1,303 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_go.rst:5 +msgid "Connecting from Go" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:11 +msgid "Pre-requisites" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:13 +msgid "Before we proceed:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:15 +msgid "`Install `__ the ``go-tarantool`` library." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:18 +msgid ":ref:`Start ` Tarantool (locally or in Docker) and make sure that you have created and populated a database as we suggested :ref:`earlier `:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:22 +msgid "box.cfg{listen = 3301}\n" +"s = box.schema.space.create('tester')\n" +"s:format({\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'band_name', type = 'string'},\n" +" {name = 'year', type = 'unsigned'}\n" +" })\n" +"s:create_index('primary', {\n" +" type = 'hash',\n" +" parts = {'id'}\n" +" })\n" +"s:create_index('secondary', {\n" +" type = 'hash',\n" +" parts = {'band_name'}\n" +" })\n" +"s:insert{1, 'Roxette', 1986}\n" +"s:insert{2, 'Scorpions', 2015}\n" +"s:insert{3, 'Ace of Base', 1993}" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:45 +msgid "Please do not close the terminal window where Tarantool is running -- you'll need it soon." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:48 +msgid "In order to connect to Tarantool as an administrator, reset the password for the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:51 +msgid "box.schema.user.passwd('pass')" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:59 +msgid "Connecting to Tarantool" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:61 +msgid "To get connected to the Tarantool server, write a simple Go program:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:63 +msgid "package main\n" +"\n" +"import (\n" +" \"fmt\"\n" +"\n" +" \"github.com/tarantool/go-tarantool\"\n" +")\n" +"\n" +"func main() {\n" +"\n" +" conn, err := tarantool.Connect(\"127.0.0.1:3301\", tarantool.Opts{\n" +" User: \"admin\",\n" +" Pass: \"pass\",\n" +" })\n" +"\n" +" if err != nil {\n" +" log.Fatalf(\"Connection refused\")\n" +" }\n" +"\n" +" defer conn.Close()\n" +"\n" +" // Your logic for interacting with the database\n" +"}" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:89 +msgid "The default user is ``guest``." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:95 +msgid "Manipulating the data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:101 +msgid "Inserting data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:103 +msgid "To insert a :term:`tuple` into a :term:`space`, use ``Insert``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:105 +msgid "resp, err = conn.Insert(\"tester\", []interface{}{4, \"ABBA\", 1972})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:109 +msgid "This inserts the tuple ``(4, \"ABBA\", 1972)`` into a space named ``tester``." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:111 +msgid "The response code and data are available in the `tarantool.Response `_ structure:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:115 +msgid "code := resp.Code\n" +"data := resp.Data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:124 +msgid "Querying data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:126 +msgid "To select a tuple from a space, use `Select `_:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:129 +msgid "resp, err = conn.Select(\"tester\", \"primary\", 0, 1, tarantool.IterEq, []interface{}{4})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:133 +msgid "This selects a tuple by the primary key with ``offset = 0`` and ``limit = 1`` from a space named ``tester`` (in our example, this is the index named ``primary``, based on the ``id`` field of each tuple)." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:137 +msgid "Next, select tuples by a secondary key." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:139 +msgid "resp, err = conn.Select(\"tester\", \"secondary\", 0, 1, tarantool.IterEq, []interface{}{\"ABBA\"})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:143 +msgid "Finally, it would be nice to select all the tuples in a space. But there is no one-liner for this in Go; you would need a script like :ref:`this one `." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:147 +msgid "For more examples, see https://github.com/tarantool/go-tarantool#usage" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:153 +msgid "Updating data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:155 +msgid "Update a :term:`field` value using ``Update``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:157 +msgid "resp, err = conn.Update(\"tester\", \"primary\", []interface{}{4}, []interface{}{[]interface{}{\"+\", 2, 3}})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:161 +msgid "This increases by 3 the value of field ``2`` in the tuple with ``id = 4``. If a tuple with this ``id`` doesn't exist, Tarantool will return an error." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:164 +msgid "Now use ``Replace`` to totally replace the tuple that matches the primary key. If a tuple with this primary key doesn't exist, Tarantool will do nothing." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:168 +msgid "resp, err = conn.Replace(\"tester\", []interface{}{4, \"New band\", 2011})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:172 +msgid "You can also update the data using ``Upsert`` that works similarly to ``Update``, but creates a new tuple if the old one was not found." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:175 +msgid "resp, err = conn.Upsert(\"tester\", []interface{}{4, \"Another band\", 2000}, []interface{}{[]interface{}{\"+\", 2, 5}})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:179 +msgid "This increases by 5 the value of the third field in the tuple with ``id = 4``, or inserts the tuple ``(4, \"Another band\", 2000)`` if a tuple with this ``id`` doesn't exist." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:187 +msgid "Deleting data" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:189 +msgid "To delete a tuple, use ``сonnection.Delete``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:191 +msgid "resp, err = conn.Delete(\"tester\", \"primary\", []interface{}{4})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:195 +msgid "To delete all tuples in a space (or to delete an entire space), use ``Call``. We'll focus on this function in more detail in the :ref:`next ` section." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:199 +msgid "To delete all tuples in a space, call ``space:truncate``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:201 +msgid "resp, err = conn.Call(\"box.space.tester:truncate\", []interface{}{})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:205 +msgid "To delete an entire space, call ``space:drop``. This requires connecting to Tarantool as the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:208 +msgid "resp, err = conn.Call(\"box.space.tester:drop\", []interface{}{})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:216 +msgid "Executing stored procedures" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:218 +msgid "Switch to the terminal window where Tarantool is running." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:222 +msgid "If you don't have a terminal window with remote connection to Tarantool, check out these guides:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:225 +msgid ":ref:`connecting to a local Tarantool instance `" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:226 +msgid ":ref:`attaching to a Tarantool instance that runs in a Docker container `" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:228 +msgid "Define a simple Lua function:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:230 +msgid "function sum(a, b)\n" +" return a + b\n" +"end" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:236 +msgid "Now we have a Lua function defined in Tarantool. To invoke this function from ``go``, use ``Call``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:239 +msgid "resp, err = conn.Call(\"sum\", []interface{}{2, 3})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:243 +msgid "To send bare Lua code for execution, use ``Eval``:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:245 +msgid "resp, err = connection.Eval(\"return 4 + 5\", []interface{}{})" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:253 +msgid "Feature comparison" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:255 +msgid "There are two more connectors from the open-source community:" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:257 +msgid "`viciious/go-tarantool `_" +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:259 +msgid "`FZambia/tarantool `_." +msgstr "" + +#: ../../doc/how-to/getting_started_go.rst:261 +msgid "See the :ref:`feature comparison table ` of all Go connectors available." +msgstr "" diff --git a/locale/en/how-to/getting_started_net_box.pot b/locale/en/how-to/getting_started_net_box.pot new file mode 100644 index 0000000000..6072d57046 --- /dev/null +++ b/locale/en/how-to/getting_started_net_box.pot @@ -0,0 +1,209 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_net_box.rst:4 +msgid "Getting started with net.box" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:6 +msgid "The tutorial shows how to work with some common ``net.box`` methods." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:8 +msgid "For more information about the ``net.box`` module, check the :ref:`corresponding module reference `." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:12 +msgid "Sandbox configuration" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:14 +msgid "The sandbox configuration for the tutorial assumes that:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:16 +msgid "The Tarantool instance is running on ``localhost 127.0.0.1:3301``." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:17 +msgid "There is a space named ``tester`` with a numeric primary key." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:18 +msgid "The space contains a tuple with the key value = ``800``." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:19 +msgid "The current user has read, write, and execute privileges." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:21 +msgid "Use the commands below for a quick sandbox setup:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:23 +msgid "box.cfg{listen = 3301}\n" +"s = box.schema.space.create('tester')\n" +"s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}})\n" +"t = s:insert({800, 'TEST'})\n" +"box.schema.user.grant('guest', 'read,write,execute', 'universe')" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:32 +msgid "Creating a net.box connection" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:34 +msgid "First, load the ``net.box`` module with the ``require('net.box')`` method:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:36 +msgid "tarantool> net_box = require('net.box')" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:40 +msgid "The next step is to create a new connection. In ``net.box``, self-connection is pre-established. That is, ``conn = net_box.connect('localhost:3301')`` command can be replaced with the ``conn = net_box.self`` object call:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:44 +msgid "tarantool> conn = net_box.self" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:48 +msgid "Then, make a ping:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:50 +msgid "tarantool> conn:ping()\n" +"---\n" +"- true\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:58 +msgid "Using data operations" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:60 +msgid "Select all tuples in the ``tester`` space where the key value is ``800``:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:62 +msgid "tarantool> conn.space.tester:select{800}\n" +"---\n" +"- - [800, 'TEST']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:69 +msgid "Insert two tuples into the space:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:71 +msgid "tarantool> conn.space.tester:insert({700, 'TEST700'})\n" +"---\n" +"- [700, 'TEST700']\n" +"...\n" +"tarantool> conn.space.tester:insert({600, 'TEST600'})\n" +"---\n" +"- [600, 'TEST600']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:82 +msgid "After the insert, there is one tuple where the key value is ``600``. To select this tuple, you can use the ``get()`` method. Unlike the ``select()`` command, ``get()`` returns only one tuple that satisfies the stated condition." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:86 +msgid "tarantool> conn.space.tester:get({600})\n" +"---\n" +"- [600, 'TEST600']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:93 +msgid "To update the existing tuple, you can use either ``update()`` or ``upsert()``. The ``update()`` method can be used for assignment, arithmetic (if the field is numeric), cutting and pasting fragments of a field, and deleting or inserting a field." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:97 +msgid "In this tutorial, the ``update()`` command is used to update the tuple identified by primary key value = ``800``. The operation assigns a new value to the second field in the tuple:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:100 +msgid "tarantool> conn.space.tester:update(800, {{'=', 2, 'TEST800'}})\n" +"---\n" +"- [800, 'TEST800']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:107 +msgid "As for the ``upsert`` function, if there is an existing tuple that matches the key field of tuple, then the command has the same effect as ``update()``. Otherwise, the effect is equal to the ``insert()`` method." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:111 +msgid "tarantool> conn.space.tester:upsert({500, 'TEST500'}, {{'=', 2, 'TEST'}})" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:115 +msgid "To delete a tuple where the key value is ``600``, run the ``delete()`` method below:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:117 +msgid "tarantool> conn.space.tester:delete{600}\n" +"---\n" +"- [600, 'TEST600']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:124 +msgid "Then, replace the existing tuple with a new one:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:126 +msgid "tarantool> conn.space.tester:replace{500, 'New data', 'Extra data'}\n" +"---\n" +"- [500, 'New data', 'Extra data']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:133 +msgid "Finally, select all tuples from the space:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:135 +msgid "tarantool> conn.space.tester:select{}\n" +"---\n" +"- - [800, 'TEST800']\n" +" - [500, 'New data', 'Extra data']\n" +" - [700, 'TEST700']\n" +"..." +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:145 +msgid "Closing the connection" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:147 +msgid "In the end, close the connection when it is no longer needed:" +msgstr "" + +#: ../../doc/how-to/getting_started_net_box.rst:149 +msgid "tarantool> conn:close()\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/how-to/getting_started_php.pot b/locale/en/how-to/getting_started_php.pot new file mode 100644 index 0000000000..ffd1cd7ee9 --- /dev/null +++ b/locale/en/how-to/getting_started_php.pot @@ -0,0 +1,301 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_php.rst:5 +msgid "Connecting from PHP" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:11 +msgid "Pre-requisites" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:13 +msgid "Before we proceed:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:15 +msgid "`Install `__ the ``tarantool/client`` library." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:18 +msgid ":ref:`Start ` Tarantool (locally or in Docker) and make sure that you have created and populated a database as we suggested :ref:`earlier `:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:22 +msgid "box.cfg{listen = 3301}\n" +"s = box.schema.space.create('tester')\n" +"s:format({\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'band_name', type = 'string'},\n" +" {name = 'year', type = 'unsigned'}\n" +" })\n" +"s:create_index('primary', {\n" +" type = 'hash',\n" +" parts = {'id'}\n" +" })\n" +"s:create_index('secondary', {\n" +" type = 'hash',\n" +" parts = {'band_name'}\n" +" })\n" +"s:insert{1, 'Roxette', 1986}\n" +"s:insert{2, 'Scorpions', 2015}\n" +"s:insert{3, 'Ace of Base', 1993}" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:45 +msgid "Please do not close the terminal window where Tarantool is running -- you'll need it soon." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:48 +msgid "In order to connect to Tarantool as an administrator, reset the password for the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:51 +msgid "box.schema.user.passwd('pass')" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:59 +msgid "Connecting to Tarantool" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:61 +msgid "To configure a connection to the Tarantool server, say this:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:63 +msgid "use Tarantool\\Client\\Client;\n" +"\n" +"require __DIR__.'/vendor/autoload.php';\n" +"$client = Client::fromDefaults();" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:70 +msgid "The connection itself will be established at the first request. You can also specify the user name and password, if needed:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:73 +msgid "$client = Client::fromOptions([\n" +" 'uri' => 'tcp://127.0.0.1:3301',\n" +" 'username' => '',\n" +" 'password' => ''\n" +"]);" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:81 +msgid "The default user is ``guest``." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:87 +msgid "Manipulating the data" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:89 +msgid "A :term:`space` is a container for :term:`tuples `. To access a space as a named object, use ``getSpace``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:92 +msgid "$tester = $client->getSpace('tester');" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:100 +msgid "Inserting data" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:102 +msgid "To insert a tuple into a space, use ``insert``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:104 +msgid "$result = $tester->insert([4, 'ABBA', 1972]);" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:112 +msgid "Querying data" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:114 +msgid "Let's start with selecting a tuple by the primary key (in our example, this is the index named ``primary``, based on the ``id`` field of each tuple). Use ``select``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:118 +msgid "use Tarantool\\Client\\Schema\\Criteria;\n" +"\n" +"$result = $tester->select(Criteria::key([4]));\n" +"printf(json_encode($result));" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:125 +msgid "[[4, 'ABBA', 1972]]" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:129 +msgid "Next, select tuples by a secondary key. For this purpose, you need to specify the number *or* name of the index." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:132 +msgid "First off, select tuples using the index number:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:134 +msgid "$result = $tester->select(Criteria::index(1)->andKey(['Scorpions']));\n" +"printf(json_encode($result));" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:139 +#: ../../doc/how-to/getting_started_php.rst:154 +msgid "[2, 'Scorpions', 2015]" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:143 +msgid "(We say ``index(1)`` because index numbers in Tarantool start with 0, and we're using our second index here.)" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:146 +msgid "Now make a similar query by the index name and make sure that the result is the same:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:149 +msgid "$result = $tester->select(Criteria::index('secondary')->andKey(['Scorpions']));\n" +"printf(json_encode($result));" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:158 +msgid "Finally, select all the tuples in a space via a ``select``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:160 +msgid "$result = $tester->select(Criteria::allIterator());" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:168 +msgid "Updating data" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:170 +msgid "Update a :term:`field` value using ``update``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:172 +msgid "use Tarantool\\Client\\Schema\\Operations;\n" +"\n" +"$result = $tester->update([4], Operations::set(1, 'New group')->andAdd(2, 2));" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:178 +msgid "This updates the value of field ``1`` and increases the value of field ``2`` in the tuple with ``id = 4``. If a tuple with this ``id`` doesn't exist, Tarantool will return an error." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:182 +msgid "Now use ``replace`` to totally replace the tuple that matches the primary key. If a tuple with this primary key doesn't exist, Tarantool will do nothing." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:186 +msgid "$result = $tester->replace([4, 'New band', 2015]);" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:190 +msgid "You can also update the data using ``upsert`` that works similarly to ``update``, but creates a new tuple if the old one was not found." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:193 +msgid "use Tarantool\\Client\\Schema\\Operations;\n" +"\n" +"$tester->upsert([4, 'Another band', 2000], Operations::add(2, 5));" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:199 +msgid "This increases by 5 the value of field ``2`` in the tuple with ``id = 4``, or inserts the tuple ``(4, \"Another band\", 2000)`` if a tuple with this ``id`` doesn't exist." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:207 +msgid "Deleting data" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:209 +msgid "To delete a tuple, use ``delete(primary_key)``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:211 +msgid "$result = $tester->delete([4]);" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:215 +msgid "To delete all tuples in a space (or to delete an entire space), use ``call``. We'll focus on this function in more detail in the :ref:`next ` section." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:219 +msgid "To delete all tuples in a space, call ``space:truncate``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:221 +msgid "$result = $client->call('box.space.tester:truncate');" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:225 +msgid "To delete an entire space, call ``space:drop``. This requires connecting to Tarantool as the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:228 +msgid "$result = $client->call('box.space.tester:drop');" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:236 +msgid "Executing stored procedures" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:238 +msgid "Switch to the terminal window where Tarantool is running." +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:242 +msgid "If you don't have a terminal window with remote connection to Tarantool, check out these guides:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:245 +msgid ":ref:`connecting to a local Tarantool instance `" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:246 +msgid ":ref:`attaching to a Tarantool instance that runs in a Docker container `" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:248 +msgid "Define a simple Lua function:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:250 +msgid "function sum(a, b)\n" +" return a + b\n" +"end" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:256 +msgid "Now we have a Lua function defined in Tarantool. To invoke this function from ``php``, use ``call``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:259 +msgid "$result = $client->call('sum', 3, 2);" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:263 +msgid "To send bare Lua code for execution, use ``eval``:" +msgstr "" + +#: ../../doc/how-to/getting_started_php.rst:265 +msgid "$result = $client->evaluate('return 4 + 5');" +msgstr "" diff --git a/locale/en/how-to/getting_started_python.pot b/locale/en/how-to/getting_started_python.pot new file mode 100644 index 0000000000..e2b232a6d9 --- /dev/null +++ b/locale/en/how-to/getting_started_python.pot @@ -0,0 +1,292 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/getting_started_python.rst:5 +msgid "Connecting from Python" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:11 +msgid "Pre-requisites" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:13 +msgid "Before we proceed:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:15 +msgid "`Install `__ the ``tarantool`` module. We recommend using ``python3`` and ``pip3``." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:18 +msgid ":ref:`Start ` Tarantool (locally or in Docker) and make sure that you have created and populated a database as we suggested :ref:`earlier `:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:22 +msgid "box.cfg{listen = 3301}\n" +"s = box.schema.space.create('tester')\n" +"s:format({\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'band_name', type = 'string'},\n" +" {name = 'year', type = 'unsigned'}\n" +" })\n" +"s:create_index('primary', {\n" +" type = 'hash',\n" +" parts = {'id'}\n" +" })\n" +"s:create_index('secondary', {\n" +" type = 'hash',\n" +" parts = {'band_name'}\n" +" })\n" +"s:insert{1, 'Roxette', 1986}\n" +"s:insert{2, 'Scorpions', 2015}\n" +"s:insert{3, 'Ace of Base', 1993}" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:45 +msgid "Please do not close the terminal window where Tarantool is running -- you'll need it soon." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:48 +msgid "In order to connect to Tarantool as an administrator, reset the password for the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:51 +msgid "box.schema.user.passwd('pass')" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:59 +msgid "Connecting to Tarantool" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:61 +msgid "To get connected to the Tarantool server, say this:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:63 +msgid ">>> import tarantool\n" +">>> connection = tarantool.connect(\"localhost\", 3301)" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:68 +msgid "You can also specify the user name and password, if needed:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:70 +msgid ">>> tarantool.connect(\"localhost\", 3301, user=username, password=password)" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:74 +msgid "The default user is ``guest``." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:80 +msgid "Manipulating the data" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:82 +msgid "A :term:`space` is a container for :term:`tuples `. To access a space as a named object, use ``connection.space``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:85 +msgid ">>> tester = connection.space('tester')" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:93 +msgid "Inserting data" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:95 +msgid "To insert a tuple into a space, use ``insert``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:97 +msgid ">>> tester.insert((4, 'ABBA', 1972))\n" +"[4, 'ABBA', 1972]" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:106 +msgid "Querying data" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:108 +msgid "Let's start with selecting a tuple by the primary key (in our example, this is the index named ``primary``, based on the ``id`` field of each tuple). Use ``select``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:112 +msgid ">>> tester.select(4)\n" +"[4, 'ABBA', 1972]" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:117 +msgid "Next, select tuples by a secondary key. For this purpose, you need to specify the number *or* name of the index." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:120 +msgid "First off, select tuples using the index number:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:122 +msgid ">>> tester.select('Scorpions', index=1)\n" +"[2, 'Scorpions', 2015]" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:127 +msgid "(We say ``index=1`` because index numbers in Tarantool start with 0, and we're using our second index here.)" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:130 +msgid "Now make a similar query by the index name and make sure that the result is the same:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:133 +msgid ">>> tester.select('Scorpions', index='secondary')\n" +"[2, 'Scorpions', 2015]" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:138 +msgid "Finally, select all the tuples in a space via a ``select`` with no arguments:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:141 +msgid ">>> tester.select()" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:149 +msgid "Updating data" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:151 +msgid "Update a :term:`field` value using ``update``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:153 +msgid ">>> tester.update(4, [('=', 1, 'New group'), ('+', 2, 2)])" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:157 +msgid "This updates the value of field ``1`` and increases the value of field ``2`` in the tuple with ``id = 4``. If a tuple with this ``id`` doesn't exist, Tarantool will return an error." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:161 +msgid "Now use ``replace`` to totally replace the tuple that matches the primary key. If a tuple with this primary key doesn't exist, Tarantool will do nothing." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:165 +msgid ">>> tester.replace((4, 'New band', 2015))" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:169 +msgid "You can also update the data using ``upsert`` that works similarly to ``update``, but creates a new tuple if the old one was not found." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:172 +msgid ">>> tester.upsert((4, 'Another band', 2000), [('+', 2, 5)])" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:176 +msgid "This increases by 5 the value of field ``2`` in the tuple with ``id = 4``, or inserts the tuple ``(4, \"Another band\", 2000)`` if a tuple with this ``id`` doesn't exist." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:184 +msgid "Deleting data" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:186 +msgid "To delete a tuple, use ``delete(primary_key)``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:188 +msgid ">>> tester.delete(4)\n" +"[4, 'New group', 2012]" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:193 +msgid "To delete all tuples in a space (or to delete an entire space), use ``call``. We'll focus on this function in more detail in the :ref:`next ` section." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:197 +msgid "To delete all tuples in a space, call ``space:truncate``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:199 +msgid ">>> connection.call('box.space.tester:truncate', ())" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:203 +msgid "To delete an entire space, call ``space:drop``. This requires connecting to Tarantool as the ``admin`` user:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:206 +msgid ">>> connection.call('box.space.tester:drop', ())" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:214 +msgid "Executing stored procedures" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:216 +msgid "Switch to the terminal window where Tarantool is running." +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:220 +msgid "If you don't have a terminal window with remote connection to Tarantool, check out these guides:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:223 +msgid ":ref:`connecting to a local Tarantool instance `" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:224 +msgid ":ref:`attaching to a Tarantool instance that runs in a Docker container `" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:226 +msgid "Define a simple Lua function:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:228 +msgid "function sum(a, b)\n" +" return a + b\n" +"end" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:234 +msgid "Now we have a Lua function defined in Tarantool. To invoke this function from ``python``, use ``call``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:237 +msgid ">>> connection.call('sum', (3, 2))\n" +"5" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:242 +msgid "To send bare Lua code for execution, use ``eval``:" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:244 +msgid ">>> connection.eval('return 4 + 5')\n" +"9" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:253 +msgid "Feature comparison" +msgstr "" + +#: ../../doc/how-to/getting_started_python.rst:255 +msgid "See the :ref:`feature comparison table ` of all Python connectors available." +msgstr "" diff --git a/locale/en/how-to/index.pot b/locale/en/how-to/index.pot new file mode 100644 index 0000000000..990bc54c41 --- /dev/null +++ b/locale/en/how-to/index.pot @@ -0,0 +1,33 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/index.rst:16 +msgid "Creating Tarantool database" +msgstr "" + +#: ../../doc/how-to/index.rst:8 +msgid "How-to guides" +msgstr "" + +#: ../../doc/how-to/index.rst:10 +msgid "This chapter contains practical examples as well as tutorials for those who would like to dig deeper into Tarantool usage." +msgstr "" + +#: ../../doc/how-to/index.rst:13 +msgid "If you are new to Tarantool, please see our :ref:`Getting Started guides ` first." +msgstr "" diff --git a/locale/en/how-to/other/index.pot b/locale/en/how-to/other/index.pot new file mode 100644 index 0000000000..8bdc43cec9 --- /dev/null +++ b/locale/en/how-to/other/index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/other/index.rst:2 +msgid "More guides" +msgstr "" diff --git a/locale/en/how-to/other/iproto.pot b/locale/en/how-to/other/iproto.pot new file mode 100644 index 0000000000..d23de488be --- /dev/null +++ b/locale/en/how-to/other/iproto.pot @@ -0,0 +1,357 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/other/iproto.rst:5 +msgid "Understanding the binary protocol" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:8 +msgid "Overview" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:10 +msgid "To communicate with each other, Tarantool instances use a binary protocol called iproto. To learn more, see the :ref:`Binary protocol ` section." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:13 +msgid "In this set of examples, the user will be looking at binary code transferred via iproto. The code is intercepted with ``tcpdump``, a monitoring utility." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:17 +msgid "Examples" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:19 +msgid "To follow the examples in this section, get a single Linux computer and start three command-line shells (\"terminals\")." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:22 +msgid "-- On terminal #1, Start monitoring port 3302 with `tcpdump `_: |br|" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:24 +msgid "sudo tcpdump -i lo 'port 3302' -X" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:28 +msgid "On terminal #2, start a server with:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:30 +msgid "box.cfg{listen=3302}\n" +"box.schema.space.create('tspace')\n" +"box.space.tspace:create_index('I')\n" +"box.space.tspace:insert{280}\n" +"box.schema.user.grant('guest','read,write,execute,create,drop','universe')" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:38 +msgid "On terminal #3, start another server, which will act as a client, with:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:40 +msgid "box.cfg{}\n" +"net_box = require('net.box')\n" +"conn = net_box.connect('localhost:3302')" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:47 +msgid "IPROTO_SELECT" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:49 +msgid "On terminal #3, run the following:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:51 +msgid "conn.space.tspace:select(280)" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:55 +msgid "Now look at what tcpdump shows for the job connecting to 3302 -- the \"request\". After the words \"length 32\" is a packet that ends with these 32 bytes (we have added indented comments):" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:59 +msgid "ce 00 00 00 1b MP_UINT = decimal 27 = number of bytes after this\n" +"82 MP_MAP, size 2 (we'll call this \"Main-Map\")\n" +"01 IPROTO_SYNC (Main-Map Item#1)\n" +"04 MP_INT = 4 = number that gets incremented with each request\n" +"00 IPROTO_REQUEST_TYPE (Main-Map Item#2)\n" +"01 IPROTO_SELECT\n" +"86 MP_MAP, size 6 (we'll call this \"Select-Map\")\n" +"10 IPROTO_SPACE_ID (Select-Map Item#1)\n" +"cd 02 00 MP_UINT = decimal 512 = id of tspace (could be larger)\n" +"11 IPROTO_INDEX_ID (Select-Map Item#2)\n" +"00 MP_INT = 0 = id of index within tspace\n" +"14 IPROTO_ITERATOR (Select-Map Item#3)\n" +"00 MP_INT = 0 = Tarantool iterator_type.h constant ITER_EQ\n" +"13 IPROTO_OFFSET (Select-Map Item#4)\n" +"00 MP_INT = 0 = amount to offset\n" +"12 IPROTO_LIMIT (Select-Map Item#5)\n" +"ce ff ff ff ff MP_UINT = 4294967295 = biggest possible limit\n" +"20 IPROTO_KEY (Select-Map Item#6)\n" +"91 MP_ARRAY, size 1 (we'll call this \"Key-Array\")\n" +"cd 01 18 MP_UINT = 280 (Select-Map Item#6, Key-Array Item#1)\n" +" -- 280 is the key value that we are searching for" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:83 +msgid "Now read the source code file `net_box.c `_ and skip to the line ``netbox_encode_select(lua_State *L)``. From the comments and from simple function calls like ``mpstream_encode_uint(&stream, IPROTO_SPACE_ID);`` you will be able to see how net_box put together the packet contents that you have just observed with tcpdump." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:91 +msgid "There are libraries for reading and writing MessagePack objects. C programmers sometimes include `msgpuck.h `_." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:94 +msgid "Now you know how Tarantool itself makes requests with the binary protocol. When in doubt about a detail, consult ``net_box.c`` -- it has routines for each request. Some :ref:`connectors ` have similar code." +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:99 +msgid "IPROTO_UPDATE" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:101 +msgid "For an IPROTO_UPDATE example, suppose a user changes field #2 in tuple #2 in space #256 to ``'BBBB'``. The body will look like this: (notice that in this case there is an extra map item IPROTO_INDEX_BASE, to emphasize that field numbers start with 1, which is optional and can be omitted):" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:107 +msgid "04 IPROTO_UPDATE\n" +"85 IPROTO_MAP, size 5\n" +"10 IPROTO_SPACE_ID, Map Item#1\n" +"cd 02 00 MP_UINT 256\n" +"11 IPROTO_INDEX_ID, Map Item#2\n" +"00 MP_INT 0 = primary-key index number\n" +"15 IPROTO_INDEX_BASE, Map Item#3\n" +"01 MP_INT = 1 i.e. field numbers start at 1\n" +"21 IPROTO_TUPLE, Map Item#4\n" +"91 MP_ARRAY, size 1, for array of operations\n" +"93 MP_ARRAY, size 3\n" +"a1 3d MP_STR = OPERATOR = '='\n" +"02 MP_INT = FIELD_NO = 2\n" +"a5 42 42 42 42 42 MP_STR = VALUE = 'BBBB'\n" +"20 IPROTO_KEY, Map Item#5\n" +"91 MP_ARRAY, size 1, for array of key values\n" +"02 MP_UINT = primary-key value = 2" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:128 +msgid "IPROTO_EXECUTE" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:130 +msgid "Byte codes for the :ref:`IPROTO_EXECUTE ` example:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:132 +msgid "0b IPROTO_EXECUTE\n" +"83 MP_MAP, size 3\n" +"43 IPROTO_STMT_ID Map Item#1\n" +"ce d7 aa 74 1b MP_UINT value of n.stmt_id\n" +"41 IPROTO_SQL_BIND Map Item#2\n" +"92 MP_ARRAY, size 2\n" +"01 MP_INT = 1 = value for first parameter\n" +"a1 61 MP_STR = 'a' = value for second parameter\n" +"2b IPROTO_OPTIONS Map Item#3\n" +"90 MP_ARRAY, size 0 (there are no options)" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:146 +msgid "IPROTO_INSERT" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:148 +msgid "Byte codes for the response to the :codenormal:`box.space.`:codeitalic:`space-name`:codenormal:`:insert{6}` example:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:151 +msgid "ce 00 00 00 20 MP_UINT = HEADER AND BODY SIZE\n" +"83 MP_MAP, size 3\n" +"00 IPROTO_REQUEST_TYPE\n" +"ce 00 00 00 00 MP_UINT = IPROTO_OK\n" +"01 IPROTO_SYNC\n" +"cf 00 00 00 00 00 00 00 53 MP_UINT = sync value\n" +"05 IPROTO_SCHEMA_VERSION\n" +"ce 00 00 00 68 MP_UINT = schema version\n" +"81 MP_MAP, size 1\n" +"30 IPROTO_DATA\n" +"dd 00 00 00 01 MP_ARRAY, size 1 (row count)\n" +"91 MP_ARRAY, size 1 (field count)\n" +"06 MP_INT = 6 = the value that was inserted" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:168 +msgid "IPROTO_EVAL" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:170 +msgid "Byte codes for the response to the ``conn:eval([[box.schema.space.create('_space');]])`` example:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:173 +msgid "ce 00 00 00 3b MP_UINT = HEADER AND BODY SIZE\n" +"83 MP_MAP, size 3 (i.e. 3 items in header)\n" +" 00 IPROTO_REQUEST_TYPE\n" +" ce 00 00 80 0a MP_UINT = hexadecimal 800a\n" +" 01 IPROTO_SYNC\n" +" cf 00 00 00 00 00 00 00 26 MP_UINT = sync value\n" +" 05 IPROTO_SCHEMA_VERSION\n" +" ce 00 00 00 78 MP_UINT = schema version value\n" +" 81 MP_MAP, size 1\n" +" 31 IPROTO_ERROR_24\n" +" db 00 00 00 1d 53 70 61 63 etc. MP_STR = \"Space '_space' already exists\"" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:188 +msgid "Creating a table with IPROTO_EXECUTE" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:190 +msgid "Byte codes, if we use the same net.box connection that we used in the beginning and we say |br| ``conn:execute([[CREATE TABLE t1 (dd INT PRIMARY KEY AUTOINCREMENT, дд STRING COLLATE \"unicode\");]])`` |br| ``conn:execute([[INSERT INTO t1 VALUES (NULL, 'a'), (NULL, 'b');]])`` |br| and we watch what tcpdump displays, we will see two noticeable things: (1) the CREATE statement caused a schema change so the response has a new IPROTO_SCHEMA_VERSION value and the body includes the new contents of some system tables (caused by requests from net.box which users will not see); (2) the final bytes of the response to the INSERT will be:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:201 +msgid "81 MP_MAP, size 1\n" +"42 IPROTO_SQL_INFO\n" +"82 MP_MAP, size 2\n" +"00 Tarantool constant (not in iproto_constants.h) = SQL_INFO_ROW_COUNT\n" +"02 1 = row count\n" +"01 Tarantool constant (not in iproto_constants.h) = SQL_INFO_AUTOINCREMENT_ID\n" +"92 MP_ARRAY, size 2\n" +"01 first autoincrement number\n" +"02 second autoincrement number" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:214 +msgid "SELECT with SQL" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:216 +msgid "Byte codes for the SQL SELECT example, if we ask for full metadata by saying |br| :code:`conn.space._session_settings:update('sql_full_metadata', {{'=', 'value', true}})` |br| and we select the two rows from the table that we just created |br| :code:`conn:execute([[SELECT dd, дд AS д FROM t1;]])` |br| then tcpdump will show this response, after the header:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:223 +msgid "82 MP_MAP, size 2 (i.e. metadata and rows)\n" +"32 IPROTO_METADATA\n" +"92 MP_ARRAY, size 2 (i.e. 2 columns)\n" +"85 MP_MAP, size 5 (i.e. 5 items for column#1)\n" +"00 a2 44 44 IPROTO_FIELD_NAME and 'DD'\n" +"01 a7 69 6e 74 65 67 65 72 IPROTO_FIELD_TYPE and 'integer'\n" +"03 c2 IPROTO_FIELD_IS_NULLABLE and false\n" +"04 c3 IPROTO_FIELD_IS_AUTOINCREMENT and true\n" +"05 c0 PROTO_FIELD_SPAN and nil\n" +"85 MP_MAP, size 5 (i.e. 5 items for column#2)\n" +"00 a2 d0 94 IPROTO_FIELD_NAME and 'Д' upper case\n" +"01 a6 73 74 72 69 6e 67 IPROTO_FIELD_TYPE and 'string'\n" +"02 a7 75 6e 69 63 6f 64 65 IPROTO_FIELD_COLL and 'unicode'\n" +"03 c3 IPROTO_FIELD_IS_NULLABLE and true\n" +"05 a4 d0 b4 d0 b4 IPROTO_FIELD_SPAN and 'дд' lower case\n" +"30 IPROTO_DATA\n" +"92 MP_ARRAY, size 2\n" +"92 MP_ARRAY, size 2\n" +"01 MP_INT = 1 i.e. contents of row#1 column#1\n" +"a1 61 MP_STR = 'a' i.e. contents of row#1 column#2\n" +"92 MP_ARRAY, size 2\n" +"02 MP_INT = 2 i.e. contents of row#2 column#1\n" +"a1 62 MP_STR = 'b' i.e. contents of row#2 column#2" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:250 +msgid "IPROTO_PREPARE" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:252 +msgid "Byte code for the SQL PREPARE example. If we said |br| :code:`conn:prepare([[SELECT dd, дд AS д FROM t1;]])` |br| then tcpdump would show almost the same response, but there would be no IPROTO_DATA. Instead, additional items will appear:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:257 +msgid "34 IPROTO_BIND_COUNT\n" +"00 MP_UINT = 0\n" +"\n" +"33 IPROTO_BIND_METADATA\n" +"90 MP_ARRAY, size 0" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:265 +msgid "``MP_UINT = 0`` and ``MP_ARRAY`` has size 0 because there are no parameters to bind. Full output:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:268 +msgid "84 MP_MAP, size 4\n" +"43 IPROTO_STMT_ID\n" +"ce c2 3c 2c 1e MP_UINT = statement id\n" +"34 IPROTO_BIND_COUNT\n" +"00 MP_INT = 0 = number of parameters to bind\n" +"33 IPROTO_BIND_METADATA\n" +"90 MP_ARRAY, size 0 = there are no parameters to bind\n" +"32 IPROTO_METADATA\n" +"92 MP_ARRAY, size 2 (i.e. 2 columns)\n" +"85 MP_MAP, size 5 (i.e. 5 items for column#1)\n" +"00 a2 44 44 IPROTO_FIELD_NAME and 'DD'\n" +"01 a7 69 6e 74 65 67 65 72 IPROTO_FIELD_TYPE and 'integer'\n" +"03 c2 IPROTO_FIELD_IS_NULLABLE and false\n" +"04 c3 IPROTO_FIELD_IS_AUTOINCREMENT and true\n" +"05 c0 PROTO_FIELD_SPAN and nil\n" +"85 MP_MAP, size 5 (i.e. 5 items for column#2)\n" +"00 a2 d0 94 IPROTO_FIELD_NAME and 'Д' upper case\n" +"01 a6 73 74 72 69 6e 67 IPROTO_FIELD_TYPE and 'string'\n" +"02 a7 75 6e 69 63 6f 64 65 IPROTO_FIELD_COLL and 'unicode'\n" +"03 c3 IPROTO_FIELD_IS_NULLABLE and true\n" +"05 a4 d0 b4 d0 b4 IPROTO_FIELD_SPAN and 'дд' lower case" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:293 +msgid "Heartbeat" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:295 +msgid "Byte code for the :ref:`heartbeat ` example. The master might send this body:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:297 +msgid "83 MP_MAP, size 3\n" +"00 Main-Map Item #1 IPROTO_REQUEST_TYPE\n" +"00 MP_UINT = 0\n" +"02 Main-Map Item #2 IPROTO_REPLICA_ID\n" +"02 MP_UINT = 2 = id\n" +"04 Main-Map Item #3 IPROTO_TIMESTAMP\n" +"cb MP_DOUBLE (MessagePack \"Float 64\")\n" +"41 d7 ba 06 7b 3a 03 21 8-byte timestamp\n" +"81 MP_MAP (body), size 1\n" +"5a Body Map Item #1 IPROTO_VCLOCK_SYNC\n" +"14 MP_UINT = 20 (vclock sync value)" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:311 +msgid "Byte code for the :ref:`heartbeat ` example. The replica might send back this body:" +msgstr "" + +#: ../../doc/how-to/other/iproto.rst:313 +msgid "81 MP_MAP, size 1\n" +"00 Main-Map Item #1 IPROTO_REQUEST_TYPE\n" +"00 MP_UINT = 0 = IPROTO_OK\n" +"83 MP_MAP (body), size 3\n" +"26 Body Map Item #1 IPROTO_VCLOCK\n" +"81 MP_MAP, size 1 (vclock of 1 component)\n" +"01 MP_UINT = 1 = id (part 1 of vclock)\n" +"06 MP_UINT = 6 = lsn (part 2 of vclock)\n" +"5a Body Map Item #2 IPROTO_VCLOCK_SYNC\n" +"14 MP_UINT = 20 (vclock sync value)\n" +"53 Body Map Item #3 IPROTO_TERM\n" +"31 MP_UINT = 49 (term value)" +msgstr "" diff --git a/locale/en/how-to/other/libslave.pot b/locale/en/how-to/other/libslave.pot new file mode 100644 index 0000000000..73b7ac32b8 --- /dev/null +++ b/locale/en/how-to/other/libslave.pot @@ -0,0 +1,277 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/other/libslave.rst:5 +msgid "libslave tutorial" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:7 +msgid "``libslave`` is a C++ library for reading data changes done by MysQL and, optionally, writing them to a Tarantool database. It works by acting as a replication slave. The MySQL server writes data-change information to a \"binary log\", and transfers the information to any client that says \"I want to see the information starting with this file and this record, continuously\". So, ``libslave`` is primarily good for making a Tarantool database replica (much faster than using a conventional MySQL slave server), and for keeping track of data changes so they can be searched." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:18 +msgid "We will not go into the many details here -- the `API documentation `_ has them. We will only show an exercise: a minimal program that uses the library." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:24 +msgid "Use a test machine. Do not use a production machine." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:26 +msgid "STEP 1: Make sure you have:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:28 +msgid "a recent version of Linux (versions such as Ubuntu 14.04 will not do)," +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:29 +msgid "a recent version of MySQL 5.6 or MySQL 5.7 server (MariaDB will not do)," +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:30 +msgid "MySQL client development package. For example, on Ubuntu you can download it with this command:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:33 +msgid "$ sudo apt-get install mysql-client-core-5.7" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:37 +msgid "STEP 2: Download ``libslave``." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:39 +msgid "The recommended source is https://github.com/tarantool/libslave/. Downloads include the source code only." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:42 +msgid "$ sudo apt-get install libboost-all-dev\n" +"$ cd ~\n" +"$ git clone https://github.com/tarantool/libslave.git tarantool-libslave\n" +"$ cd tarantool-libslave\n" +"$ git submodule init\n" +"$ git submodule update\n" +"$ cmake .\n" +"$ make" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:53 +msgid "If you see an error message mentioning the word \"vector\", edit ``field.h`` and add this line:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:56 +msgid "#include " +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:60 +msgid "STEP 3: Start the MySQL server. On the command line, add appropriate switches for doing replication. For example:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:63 +msgid "$ mysqld --log-bin=mysql-bin --server-id=1" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:67 +msgid "STEP 4: For purposes of this exercise, we are assuming you have:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:69 +msgid "a \"root\" user with password \"root\" with privileges," +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:70 +msgid "a \"test\" database with a table named \"test\"," +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:71 +msgid "a binary log named \"mysql-bin\"," +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:72 +msgid "a server with server id = 1." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:74 +msgid "The values are hard-coded in the program, though of course you can change the program -- it's easy to see their settings." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:77 +msgid "STEP 5: Look at the program:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:79 +msgid "#include \n" +"#include \n" +"#include \n" +"#include \"Slave.h\"\n" +"#include \"DefaultExtState.h\"\n" +"\n" +"slave::Slave* sl = NULL;\n" +"\n" +"void callback(const slave::RecordSet& event) {\n" +" slave::Position sBinlogPos = sl->getLastBinlogPos();\n" +" switch (event.type_event) {\n" +" case slave::RecordSet::Update: std::cout << \"UPDATE\" << \"\\n\"; break;\n" +" case slave::RecordSet::Delete: std::cout << \"DELETE\" << \"\\n\"; break;\n" +" case slave::RecordSet::Write: std::cout << \"INSERT\" << \"\\n\"; break;\n" +" default: break;\n" +" }\n" +"}\n" +"\n" +"bool isStopping()\n" +"{\n" +" return 0;\n" +"}\n" +"\n" +"int main(int argc, char** argv)\n" +"{\n" +" slave::MasterInfo masterinfo;\n" +" slave::Position position(\"mysql-bin\", 0);\n" +" masterinfo.conn_options.mysql_host = \"127.0.0.1\";\n" +" masterinfo.conn_options.mysql_port = 3306;\n" +" masterinfo.conn_options.mysql_user = \"root\";\n" +" masterinfo.conn_options.mysql_pass = \"root\";\n" +" bool error = false;\n" +" try {\n" +" slave::DefaultExtState sDefExtState;\n" +" slave::Slave slave(masterinfo, sDefExtState);\n" +" sl = &slave;\n" +" sDefExtState.setMasterPosition(position);\n" +" slave.setCallback(\"test\", \"test\", callback);\n" +" slave.init();\n" +" slave.createDatabaseStructure();\n" +" try {\n" +" slave.get_remote_binlog(isStopping);\n" +" } catch (std::exception& ex) {\n" +" std::cout << \"Error reading: \" << ex.what() << std::endl;\n" +" error = true;\n" +" }\n" +" } catch (std::exception& ex) {\n" +" std::cout << \"Error initializing: \" << ex.what() << std::endl;\n" +" error = true;\n" +" }\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:134 +msgid "Everything unnecessary has been stripped so that you can see quickly how it works. At the start of ``main()``, there are some settings used for connecting -- host, port, user, password. Then there is an initialization call with the binary log file name = \"mysql-bin\". Pay particular attention to the ``setCallback`` statement, which passes database name = \"test\", table name = \"test\", and callback function address = callback. The program will be looping and invoking this callback function. See how, earlier in the program, the callback function prints \"UPDATE\" or \"DELETE\" or \"INSERT\" depending on what is passed to it." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:145 +msgid "STEP 5: Put the program in the ``tarantool-libslave`` directory and name it ``example.cpp``." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:148 +msgid "Step 6: Compile and build:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:150 +msgid "$ g++ -I/tarantool-libslave/include example.cpp -o example libslave_a.a -ldl -lpthread" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:156 +msgid "Replace ``tarantool-libslave/include`` with the full directory name." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:158 +msgid "Notice that the name of the static library is ``libslave_a.a``, not ``libslave.a``." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:161 +msgid "Step 7: Run:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:163 +msgid "$ ./example" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:167 +msgid "The result will be nothing -- the program is looping, waiting for the MySQL server to write to the replication binary log." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:170 +msgid "Step 8: Start a MySQL client program -- any client program will do. Enter these statements:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:173 +msgid "USE test\n" +"INSERT INTO test VALUES ('A');\n" +"INSERT INTO test VALUES ('B');\n" +"DELETE FROM test;" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:180 +msgid "Watch what happens in ``example.cpp`` output -- it displays:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:182 +msgid "INSERT\n" +"INSERT\n" +"DELETE\n" +"DELETE" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:189 +msgid "This is row-based replication, so you see two DELETEs, because there are two rows." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:192 +msgid "What the exercise has shown is:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:194 +msgid "the library can be built, and" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:195 +msgid "programs that use the library can access everything that the MySQL server dumps." +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:198 +msgid "For the many details and examples of usage in the field, see:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:0 +msgid "Our downloadable ``libslave`` version:" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:0 +msgid "https://github.com/tarantool/libslave" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:0 +msgid "The version it was forked from (with a different README):" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:0 +msgid "https://github.com/vozbu/libslave/wiki/API" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:206 +msgid "`How to speed up your MySQL with replication to in-memory database `_ article" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:208 +msgid "`Replicating data from MySQL to Tarantool `_ article (in Russian)" +msgstr "" + +#: ../../doc/how-to/other/libslave.rst:210 +msgid "`Asynchronous replication uncensored `_ article (in Russian)" +msgstr "" diff --git a/locale/en/how-to/replication/index.pot b/locale/en/how-to/replication/index.pot new file mode 100644 index 0000000000..781ad2fb72 --- /dev/null +++ b/locale/en/how-to/replication/index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/index.rst:5 +msgid "Replication tutorials" +msgstr "" diff --git a/locale/en/how-to/replication/repl_add_instances.pot b/locale/en/how-to/replication/repl_add_instances.pot new file mode 100644 index 0000000000..45eeb537d7 --- /dev/null +++ b/locale/en/how-to/replication/repl_add_instances.pot @@ -0,0 +1,179 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_add_instances.rst:4 +msgid "Adding instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:8 +msgid "This tutorial is intended as a follow-up to the :ref:`replication bootstrapping ` guide. It continues building on the examples from that page. It is recommended that you complete the bootstrapping guide before you proceed." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:15 +msgid "Adding a replica" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:20 +msgid "To add a second **replica** instance to the **master-replica** set from our :ref:`bootstrapping example `, we need an analog of the instance file that we created for the first replica in that set:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:24 +msgid "-- instance file for replica #2\n" +"box.cfg{\n" +" listen = 3301,\n" +" replication = {'replicator:password@192.168.0.101:3301', -- master URI\n" +" 'replicator:password@192.168.0.102:3301', -- replica #1 URI\n" +" 'replicator:password@192.168.0.103:3301'}, -- replica #2 URI\n" +" read_only = true\n" +"}\n" +"box.once(\"schema\", function()\n" +" box.schema.user.create('replicator', {password = 'password'})\n" +" box.schema.user.grant('replicator', 'replication') -- grant replication role\n" +" box.schema.space.create(\"test\")\n" +" box.space.test:create_index(\"primary\")\n" +" print('box.once executed on replica #2')\n" +"end)" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:42 +msgid "Here we add the URI of replica #2 to the :ref:`replication ` parameter, so now it contains three URIs." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:45 +msgid "After we launch the new replica instance, it gets connected to the master instance and retrieves the master's write-ahead-log and snapshot files:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:48 +msgid "$ # launching replica #2\n" +"$ tarantool replica2.lua\n" +"2017-06-14 14:54:33.927 [46945] main/101/replica2.lua C> version 1.7.4-52-g980d30092\n" +"2017-06-14 14:54:33.927 [46945] main/101/replica2.lua C> log level 5\n" +"2017-06-14 14:54:33.928 [46945] main/101/replica2.lua I> mapping 268435456 bytes for tuple arena...\n" +"2017-06-14 14:54:33.930 [46945] main/104/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.101:3301\n" +"2017-06-14 14:54:33.930 [46945] main/104/applier/replicator@192.168.0.10 I> authenticated\n" +"2017-06-14 14:54:33.930 [46945] main/101/replica2.lua I> bootstrapping replica from 192.168.0.101:3301\n" +"2017-06-14 14:54:33.933 [46945] main/104/applier/replicator@192.168.0.10 I> initial data received\n" +"2017-06-14 14:54:33.933 [46945] main/104/applier/replicator@192.168.0.10 I> final data received\n" +"2017-06-14 14:54:33.934 [46945] snapshot/101/main I> saving snapshot `/var/lib/tarantool/replica2/00000000000000000010.snap.inprogress'\n" +"2017-06-14 14:54:33.934 [46945] snapshot/101/main I> done\n" +"2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> vinyl checkpoint done\n" +"2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> ready to accept requests\n" +"2017-06-14 14:54:33.935 [46945] main/101/replica2.lua I> set 'read_only' configuration option to true\n" +"2017-06-14 14:54:33.936 [46945] main C> entering the event loop" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:67 +msgid "Since we are adding a read-only instance, there is no need to dynamically update the ``replication`` parameter on the other running instances. This update would be required if we :ref:`added a master instance `." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:71 +msgid "However, we recommend specifying the URI of replica #3 in all instance files of the replica set. This will keep all the files consistent with each other and with the current replication topology, and so will help to avoid configuration errors in case of further configuration updates and replica set restart." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:79 +msgid "Adding a master" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:84 +msgid "To add a third master instance to the **master-master** set from our :ref:`bootstrapping example `, we need an analog of the instance files that we created to bootstrap the other master instances in that set:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:89 +msgid "-- instance file for master #3\n" +"box.cfg{\n" +" listen = 3301,\n" +" replication = {'replicator:password@192.168.0.101:3301', -- master#1 URI\n" +" 'replicator:password@192.168.0.102:3301', -- master#2 URI\n" +" 'replicator:password@192.168.0.103:3301'}, -- master#3 URI\n" +" read_only = true, -- temporarily read-only\n" +"}\n" +"box.once(\"schema\", function()\n" +" box.schema.user.create('replicator', {password = 'password'})\n" +" box.schema.user.grant('replicator', 'replication') -- grant replication role\n" +" box.schema.space.create(\"test\")\n" +" box.space.test:create_index(\"primary\")\n" +"end)" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:106 +msgid "Here we make the following changes:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:108 +msgid "Add the URI of master #3 to the :ref:`replication ` parameter." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:110 +msgid "Temporarily specify :ref:`read_only=true ` to disable data-change operations on the instance. After launch, master #3 will act as a replica until it retrieves all data from the other masters in the replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:114 +msgid "After we launch master #3, it gets connected to the other master instances and retrieves their write-ahead-log and snapshot files:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:117 +msgid "$ # launching master #3\n" +"$ tarantool master3.lua\n" +"2017-06-14 17:10:00.556 [47121] main/101/master3.lua C> version 1.7.4-52-g980d30092\n" +"2017-06-14 17:10:00.557 [47121] main/101/master3.lua C> log level 5\n" +"2017-06-14 17:10:00.557 [47121] main/101/master3.lua I> mapping 268435456 bytes for tuple arena...\n" +"2017-06-14 17:10:00.559 [47121] iproto/101/main I> binary: bound to [::]:3301\n" +"2017-06-14 17:10:00.559 [47121] main/104/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.101:3301\n" +"2017-06-14 17:10:00.559 [47121] main/105/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.102:3301\n" +"2017-06-14 17:10:00.559 [47121] main/106/applier/replicator@192.168.0.10 I> remote master is 1.7.4 at 192.168.0.103:3301\n" +"2017-06-14 17:10:00.559 [47121] main/105/applier/replicator@192.168.0.10 I> authenticated\n" +"2017-06-14 17:10:00.559 [47121] main/101/master3.lua I> bootstrapping replica from 192.168.0.102:3301\n" +"2017-06-14 17:10:00.562 [47121] main/105/applier/replicator@192.168.0.10 I> initial data received\n" +"2017-06-14 17:10:00.562 [47121] main/105/applier/replicator@192.168.0.10 I> final data received\n" +"2017-06-14 17:10:00.562 [47121] snapshot/101/main I> saving snapshot `/Users/e.shebunyaeva/work/tarantool-test-repl/master3_dir/00000000000000000009.snap.inprogress'\n" +"2017-06-14 17:10:00.562 [47121] snapshot/101/main I> done\n" +"2017-06-14 17:10:00.564 [47121] main/101/master3.lua I> vinyl checkpoint done\n" +"2017-06-14 17:10:00.564 [47121] main/101/master3.lua I> ready to accept requests\n" +"2017-06-14 17:10:00.565 [47121] main/101/master3.lua I> set 'read_only' configuration option to true\n" +"2017-06-14 17:10:00.565 [47121] main C> entering the event loop\n" +"2017-06-14 17:10:00.565 [47121] main/104/applier/replicator@192.168.0.10 I> authenticated" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:140 +msgid "Next, we add the URI of master #3 to the ``replication`` parameter on the existing two masters. Replication-related parameters are dynamic, so we only need to make a ``box.cfg{}`` request on each of the running instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:144 +msgid "# adding master #3 URI to replication sources\n" +"tarantool> box.cfg{replication =\n" +" > {'replicator:password@192.168.0.101:3301',\n" +" > 'replicator:password@192.168.0.102:3301',\n" +" > 'replicator:password@192.168.0.103:3301'}}\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:154 +msgid "When master #3 catches up with the other masters' state, we can disable read-only mode for this instance:" +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:157 +msgid "# making master #3 a real master\n" +"tarantool> box.cfg{read_only=false}\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_add_instances.rst:164 +msgid "We also recommend to specify master #3 URI in all instance files in order to keep all the files consistent with each other and with the current replication topology." +msgstr "" diff --git a/locale/en/how-to/replication/repl_bootstrap.pot b/locale/en/how-to/replication/repl_bootstrap.pot new file mode 100644 index 0000000000..bb30348573 --- /dev/null +++ b/locale/en/how-to/replication/repl_bootstrap.pot @@ -0,0 +1,769 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:5 +msgid "Master-replica: manual failover" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:7 +msgid "**Example on GitHub**: `manual_leader `_" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:9 +msgid "This tutorial shows how to configure and work with a replica set with manual failover." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:15 +msgid "Prerequisites" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:17 +msgid "Before starting this tutorial:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:19 +msgid "Install the :ref:`tt ` utility." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:21 +msgid "Create a tt environment in the current directory by executing the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:23 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create the ``manual_leader`` directory." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:25 +msgid "Inside ``instances.enabled/manual_leader``, create the ``instances.yml`` and ``config.yaml`` files:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:27 +msgid "``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:29 +#: ../../doc/how-to/replication/repl_bootstrap.rst:584 +msgid "instance001:\n" +"instance002:\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:34 +msgid "The ``config.yaml`` file is intended to store a :ref:`replica set configuration `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:41 +msgid "Configuring a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:43 +msgid "This section describes how to configure a replica set in ``config.yaml``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:48 +msgid "Step 1: Configuring a failover mode" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:50 +msgid "First, set the :ref:`replication.failover ` option to ``manual``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:52 +msgid "replication:\n" +" failover: manual\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:61 +msgid "Step 2: Defining a replica set topology" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:63 +msgid "Define a replica set topology inside the :ref:`groups ` section:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:65 +msgid "The :ref:`leader ` option sets ``instance001`` as a replica set leader." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:66 +msgid "The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:68 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:78 +msgid "Step 3: Creating a user for replication" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:80 +msgid "In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:82 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:92 +msgid "Step 4: Specifying advertise URIs" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:94 +msgid "Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:96 +msgid "iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:105 +msgid "Resulting configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:107 +msgid "The resulting replica set configuration should look as follows:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:109 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: manual\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:120 +msgid "Working with a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:125 +msgid "Starting instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:127 +msgid "After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:129 +msgid "$ tt start manual_leader\n" +" • Starting an instance [manual_leader:instance001]...\n" +" • Starting an instance [manual_leader:instance002]..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:135 +msgid "Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:137 +msgid "$ tt status manual_leader\n" +"INSTANCE STATUS PID\n" +"manual_leader:instance001 RUNNING 15272\n" +"manual_leader:instance002 RUNNING 15273" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:148 +msgid "Checking a replica set status" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:150 +msgid "Connect to ``instance001`` using :ref:`tt connect `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:152 +msgid "$ tt connect manual_leader:instance001\n" +" • Connecting to the instance...\n" +" • Connected to manual_leader:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:158 +msgid "Make sure that the instance is in the ``running`` state by executing :ref:`box.info.status `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:160 +msgid "manual_leader:instance001> box.info.status\n" +"---\n" +"- running\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:167 +msgid "Check that the instance is writable using ``box.info.ro``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:169 +msgid "manual_leader:instance001> box.info.ro\n" +"---\n" +"- false\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:176 +msgid "Execute ``box.info.replication`` to check a replica set status. For ``instance002``, ``upstream.status`` and ``downstream.status`` should be ``follow``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:179 +msgid "manual_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 7\n" +" name: instance001\n" +" 2:\n" +" id: 2\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.3893879999996\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00028800964355469\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.37777199999982\n" +" vclock: {1: 7}\n" +" lag: 0\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:205 +msgid "To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, refer to :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:212 +msgid "Adding data" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:214 +msgid "To check that a replica (``instance002``) gets all updates from the master, follow the steps below:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:216 +msgid "On ``instance001``, create a space and add data as described in :ref:`CRUD operation examples `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:218 +msgid "Open the second terminal, connect to ``instance002`` using ``tt connect``, and use the ``select`` operation to make sure data is replicated." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:220 +msgid "Check that :ref:`box.info.vclock ` values are the same on both instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:222 +#: ../../doc/how-to/replication/repl_bootstrap.rst:319 +#: ../../doc/how-to/replication/repl_bootstrap.rst:433 +#: ../../doc/how-to/replication/repl_bootstrap.rst:512 +#: ../../doc/how-to/replication/repl_bootstrap.rst:599 +msgid "``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:224 +#: ../../doc/how-to/replication/repl_bootstrap.rst:435 +msgid "manual_leader:instance001> box.info.vclock\n" +"---\n" +"- {1: 21}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:231 +#: ../../doc/how-to/replication/repl_bootstrap.rst:327 +#: ../../doc/how-to/replication/repl_bootstrap.rst:442 +#: ../../doc/how-to/replication/repl_bootstrap.rst:520 +#: ../../doc/how-to/replication/repl_bootstrap.rst:607 +msgid "``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:233 +#: ../../doc/how-to/replication/repl_bootstrap.rst:444 +msgid "manual_leader:instance002> box.info.vclock\n" +"---\n" +"- {1: 21}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:244 +msgid "Note that a ``vclock`` value might include the ``0`` component that is related to local space operations and might differ for different instances in a replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:253 +msgid "Adding instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:255 +msgid "This section describes how to add a new replica to a replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:260 +msgid "Adding an instance to the configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:262 +msgid "Add ``instance003`` to the ``instances.yml`` file:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:264 +msgid "instance001:\n" +"instance002:\n" +"instance003:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:268 +msgid "Add ``instance003`` with the specified ``iproto.listen`` option to the ``config.yaml`` file:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:270 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:280 +msgid "Starting an instance" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:282 +msgid "Open the third terminal to work with a new instance. Start ``instance003`` using ``tt start``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:285 +msgid "$ tt start manual_leader:instance003\n" +" • Starting an instance [manual_leader:instance003]..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:290 +msgid "Check a replica set status using ``tt status``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:292 +msgid "$ tt status manual_leader\n" +"INSTANCE STATUS PID\n" +"manual_leader:instance001 RUNNING 15272\n" +"manual_leader:instance002 RUNNING 15273\n" +"manual_leader:instance003 RUNNING 15551" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:304 +msgid "Reloading configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:306 +msgid "After you added ``instance003`` to the configuration and started it, you need to reload configurations on all instances. This is required to allow ``instance001`` and ``instance002`` to get data from the new instance in case it becomes a master." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:309 +msgid "Connect to ``instance003`` using ``tt connect``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:311 +msgid "$ tt connect manual_leader:instance003\n" +" • Connecting to the instance...\n" +" • Connected to manual_leader:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:317 +msgid "Reload configurations on all three instances using the ``reload()`` function provided by the :ref:`config ` module:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:321 +#: ../../doc/how-to/replication/repl_bootstrap.rst:514 +#: ../../doc/how-to/replication/repl_bootstrap.rst:601 +msgid "manual_leader:instance001> require('config'):reload()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:329 +#: ../../doc/how-to/replication/repl_bootstrap.rst:522 +#: ../../doc/how-to/replication/repl_bootstrap.rst:609 +msgid "manual_leader:instance002> require('config'):reload()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:335 +#: ../../doc/how-to/replication/repl_bootstrap.rst:452 +msgid "``instance003``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:337 +msgid "manual_leader:instance003> require('config'):reload()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:344 +msgid "Execute ``box.info.replication`` to check a replica set status. Make sure that ``upstream.status`` and ``downstream.status`` are ``follow`` for ``instance003``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:349 +msgid "manual_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 21\n" +" name: instance001\n" +" 2:\n" +" id: 2\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.052655000000414\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00010204315185547\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.09503500000028\n" +" vclock: {1: 21}\n" +" lag: 0.00026917457580566\n" +" 3:\n" +" id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.77522099999987\n" +" peer: replicator@127.0.0.1:3303\n" +" lag: 0.0001838207244873\n" +" name: instance003\n" +" downstream:\n" +" status: follow\n" +" idle: 0.33186100000012\n" +" vclock: {1: 21}\n" +" lag: 0\n" +" ..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:397 +msgid "Performing manual failover" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:399 +msgid "This section shows how to perform manual failover and change a replica set leader." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:404 +msgid "Switching instances to read-only mode" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:406 +msgid "In the ``config.yaml`` file, change the replica set leader from ``instance001`` to ``null``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:408 +msgid "replicaset001:\n" +" leader: null" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:413 +msgid "Reload configurations on all three instances using :ref:`config:reload() ` and check that instances are in read-only mode. The example below shows how to do this for ``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:416 +msgid "manual_leader:instance001> require('config'):reload()\n" +"---\n" +"...\n" +"manual_leader:instance001> box.info.ro\n" +"---\n" +"- true\n" +"...\n" +"manual_leader:instance001> box.info.ro_reason\n" +"---\n" +"- config\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:431 +msgid "Make sure that :ref:`box.info.vclock ` values are the same on all instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:454 +msgid "manual_leader:instance003> box.info.vclock\n" +"---\n" +"- {1: 21}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:465 +msgid "Configuring a new leader" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:467 +msgid "Change a replica set leader in ``config.yaml`` to ``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:469 +msgid "replicaset001:\n" +" leader: instance002" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:474 +msgid "Reload configuration on all instances using :ref:`config:reload() `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:476 +msgid "Make sure that ``instance002`` is a new master:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:478 +msgid "manual_leader:instance002> box.info.ro\n" +"---\n" +"- false\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:485 +msgid "Check replication status using ``box.info.replication``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:491 +msgid "Removing instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:493 +msgid "This section describes the process of removing an instance from a replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:495 +msgid "Before removing an instance, make sure it is in read-only mode. If the instance is a master, perform :ref:`manual failover `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:501 +msgid "Disconnecting an instance" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:503 +msgid "Clear the ``iproto`` option for ``instance003`` by setting its value to ``{}``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:505 +msgid "instance003:\n" +" iproto: {}" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:510 +#: ../../doc/how-to/replication/repl_bootstrap.rst:597 +msgid "Reload configurations on ``instance001`` and ``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:528 +msgid "Check that the ``upstream`` section is missing for ``instance003`` by executing ``box.info.replication[3]``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:530 +msgid "manual_leader:instance001> box.info.replication[3]\n" +"---\n" +"- id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" downstream:\n" +" status: follow\n" +" idle: 0.4588760000006\n" +" vclock: {1: 21}\n" +" lag: 0\n" +" name: instance003\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:549 +msgid "Stopping an instance" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:551 +msgid "Stop ``instance003`` using the :ref:`tt stop ` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:553 +msgid "$ tt stop manual_leader:instance003\n" +" • The Instance manual_leader:instance003 (PID = 15551) has been terminated." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:559 +msgid "Check that ``downstream.status`` is ``stopped`` for ``instance003``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:561 +msgid "manual_leader:instance001> box.info.replication[3]\n" +"---\n" +"- id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" downstream:\n" +" status: stopped\n" +" message: 'unexpected EOF when reading from socket, called on fd 27, aka 127.0.0.1:3301,\n" +" peer of 127.0.0.1:54185: Broken pipe'\n" +" system_message: Broken pipe\n" +" name: instance003\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:580 +msgid "Removing an instance from the configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:582 +msgid "Remove ``instance003`` from the ``instances.yml`` file:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:589 +msgid "Remove ``instance003`` from ``config.yaml``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:591 +msgid "instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:619 +msgid "Removing an instance from the '_cluster' space" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:621 +msgid "To remove an instance from the replica set permanently, it should be removed from the :ref:`box.space._cluster ` system space:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:623 +msgid "Select all the tuples in the ``box.space._cluster`` system space:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:625 +msgid "manual_leader:instance002> box.space._cluster:select{}\n" +"---\n" +"- - [1, '9bb111c2-3ff5-36a7-00f4-2b9a573ea660', 'instance001']\n" +" - [2, '4cfa6e3c-625e-b027-00a7-29b2f2182f23', 'instance002']\n" +" - [3, '9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6', 'instance003']\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:634 +msgid "Delete a tuple corresponding to ``instance003``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:636 +msgid "manual_leader:instance002> box.space._cluster:delete(3)\n" +"---\n" +"- [3, '9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6', 'instance003']\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:643 +msgid "Execute ``box.info.replication`` to check the health status:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:645 +msgid "manual_leader:instance002> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 21\n" +" upstream:\n" +" status: follow\n" +" idle: 0.73316000000159\n" +" peer: replicator@127.0.0.1:3301\n" +" lag: 0.00016212463378906\n" +" name: instance001\n" +" downstream:\n" +" status: follow\n" +" idle: 0.7269320000014\n" +" vclock: {2: 1, 1: 21}\n" +" lag: 0.00083398818969727\n" +" 2:\n" +" id: 2\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 1\n" +" name: instance002\n" +"..." +msgstr "" diff --git a/locale/en/how-to/replication/repl_bootstrap_auto.pot b/locale/en/how-to/replication/repl_bootstrap_auto.pot new file mode 100644 index 0000000000..85689123d8 --- /dev/null +++ b/locale/en/how-to/replication/repl_bootstrap_auto.pot @@ -0,0 +1,565 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:4 +msgid "Master-replica: automated failover" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:6 +msgid "**Example on GitHub**: `auto_leader `_" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:8 +msgid "This tutorial shows how to configure and work with a replica set with automated failover." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:14 +msgid "Prerequisites" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:16 +msgid "Before starting this tutorial:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:18 +msgid "Install the :ref:`tt ` utility." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:20 +msgid "Create a tt environment in the current directory by executing the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:22 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create the ``auto_leader`` directory." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:24 +msgid "Inside ``instances.enabled/auto_leader``, create the ``instances.yml`` and ``config.yaml`` files:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:26 +msgid "``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:28 +msgid "instance001:\n" +"instance002:\n" +"instance003:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:32 +msgid "The ``config.yaml`` file is intended to store a :ref:`replica set configuration `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:40 +msgid "Configuring a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:42 +msgid "This section describes how to configure a replica set in ``config.yaml``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:47 +msgid "Step 1: Configuring a failover mode" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:49 +msgid "First, set the :ref:`replication.failover ` option to ``election``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:51 +msgid "replication:\n" +" failover: election\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:60 +msgid "Step 2: Defining a replica set topology" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:62 +msgid "Define a replica set topology inside the :ref:`groups ` section. The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:65 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:75 +msgid "Step 3: Creating a user for replication" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:77 +msgid "In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:79 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:89 +msgid "Step 4: Specifying advertise URIs" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:91 +msgid "Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:93 +msgid "iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:102 +msgid "Resulting configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:104 +msgid "The resulting replica set configuration should look as follows:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:106 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: election\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:117 +msgid "Working with a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:122 +msgid "Starting instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:124 +msgid "After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:126 +msgid "$ tt start auto_leader\n" +" • Starting an instance [auto_leader:instance001]...\n" +" • Starting an instance [auto_leader:instance002]...\n" +" • Starting an instance [auto_leader:instance003]..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:133 +msgid "Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:135 +msgid "$ tt status auto_leader\n" +"INSTANCE STATUS PID\n" +"auto_leader:instance001 RUNNING 24768\n" +"auto_leader:instance002 RUNNING 24769\n" +"auto_leader:instance003 RUNNING 24767" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:148 +msgid "Checking a replica set status" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:150 +msgid "Connect to ``instance001`` using :ref:`tt connect `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:152 +msgid "$ tt connect auto_leader:instance001\n" +" • Connecting to the instance...\n" +" • Connected to auto_leader:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:158 +msgid "Check the instance state in regard to :ref:`leader election ` using :ref:`box.info.election `. The output below shows that ``instance001`` is a follower while ``instance002`` is a replica set leader." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:161 +msgid "auto_leader:instance001> box.info.election\n" +"---\n" +"- leader_idle: 0.77491499999815\n" +" leader_name: instance002\n" +" state: follower\n" +" vote: 0\n" +" term: 2\n" +" leader: 1\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:173 +msgid "Check that ``instance001`` is in read-only mode using ``box.info.ro``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:175 +msgid "auto_leader:instance001> box.info.ro\n" +"---\n" +"- true\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:182 +msgid "Execute ``box.info.replication`` to check a replica set status. Make sure that ``upstream.status`` and ``downstream.status`` are ``follow`` for ``instance002`` and ``instance003``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:185 +msgid "auto_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 9\n" +" upstream:\n" +" status: follow\n" +" idle: 0.8257709999998\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00012326240539551\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.81174199999805\n" +" vclock: {1: 9}\n" +" lag: 0\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 0\n" +" name: instance001\n" +" 3:\n" +" id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.83125499999733\n" +" peer: replicator@127.0.0.1:3303\n" +" lag: 0.00010204315185547\n" +" name: instance003\n" +" downstream:\n" +" status: follow\n" +" idle: 0.83213399999659\n" +" vclock: {1: 9}\n" +" lag: 0\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:226 +msgid "To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, refer to :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:232 +msgid "Adding data" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:234 +msgid "To check that replicas (``instance001`` and ``instance003``) get all updates from the master (``instance002``), follow the steps below:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:236 +msgid "Connect to ``instance002`` using ``tt connect``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:238 +msgid "$ tt connect auto_leader:instance002\n" +" • Connecting to the instance...\n" +" • Connected to auto_leader:instance002" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:244 +msgid "Create a space and add data as described in :ref:`CRUD operation examples `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:246 +msgid "Use the ``select`` operation on ``instance001`` and ``instance003`` to make sure data is replicated." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:248 +msgid "Check that the ``1`` component of :ref:`box.info.vclock ` values are the same on all instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:250 +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:388 +msgid "``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:252 +msgid "auto_leader:instance001> box.info.vclock\n" +"---\n" +"- {0: 1, 1: 32}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:259 +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:397 +msgid "``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:261 +msgid "auto_leader:instance002> box.info.vclock\n" +"---\n" +"- {0: 1, 1: 32}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:268 +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:407 +msgid "``instance003``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:270 +msgid "auto_leader:instance003> box.info.vclock\n" +"---\n" +"- {0: 1, 1: 32}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:5 +msgid "Note that a ``vclock`` value might include the ``0`` component that is related to local space operations and might differ for different instances in a replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:286 +msgid "Testing automated failover" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:288 +msgid "To test how automated failover works if the current master is stopped, follow the steps below:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:290 +msgid "Stop the current master instance (``instance002``) using the ``tt stop`` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:292 +msgid "$ tt stop auto_leader:instance002\n" +" • The Instance auto_leader:instance002 (PID = 24769) has been terminated." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:298 +msgid "On ``instance001``, check ``box.info.election``. In this example, a new replica set leader is ``instance001``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:301 +msgid "auto_leader:instance001> box.info.election\n" +"---\n" +"- leader_idle: 0\n" +" leader_name: instance001\n" +" state: leader\n" +" vote: 2\n" +" term: 3\n" +" leader: 2\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:313 +msgid "Check replication status using ``box.info.replication`` for ``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:315 +msgid "``upstream.status`` is ``disconnected``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:316 +msgid "``downstream.status`` is ``stopped``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:320 +msgid "auto_leader:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 32\n" +" upstream:\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00032305717468262\n" +" status: disconnected\n" +" idle: 48.352504000002\n" +" message: 'connect, called on fd 20, aka 127.0.0.1:62575: Connection refused'\n" +" system_message: Connection refused\n" +" name: instance002\n" +" downstream:\n" +" status: stopped\n" +" message: 'unexpected EOF when reading from socket, called on fd 32, aka 127.0.0.1:3301,\n" +" peer of 127.0.0.1:62204: Broken pipe'\n" +" system_message: Broken pipe\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 1\n" +" name: instance001\n" +" 3:\n" +" id: 3\n" +" uuid: 9a3a1b9b-8a18-baf6-00b3-a6e5e11fd8b6\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.18620999999985\n" +" peer: replicator@127.0.0.1:3303\n" +" lag: 0.00012516975402832\n" +" name: instance003\n" +" downstream:\n" +" status: follow\n" +" idle: 0.19718099999955\n" +" vclock: {2: 1, 1: 32}\n" +" lag: 0.00051403045654297\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:365 +msgid "The diagram below illustrates how the ``upstream`` and ``downstream`` connections look like:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:0 +msgid "replication status on a new master" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:373 +msgid "Start ``instance002`` back using ``tt start``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:375 +msgid "$ tt start auto_leader:instance002\n" +" • Starting an instance [auto_leader:instance002]..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:384 +msgid "Choosing a leader manually" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:386 +msgid "Make sure that :ref:`box.info.vclock ` values (except the ``0`` components) are the same on all instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:390 +msgid "auto_leader:instance001> box.info.vclock\n" +"---\n" +"- {0: 2, 1: 32, 2: 1}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:399 +msgid "auto_leader:instance002> box.info.vclock\n" +"---\n" +"- {0: 2, 1: 32, 2: 1}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:409 +msgid "auto_leader:instance003> box.info.vclock\n" +"---\n" +"- {0: 3, 1: 32, 2: 1}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:416 +msgid "On ``instance002``, run :ref:`box.ctl.promote() ` to choose it as a new replica set leader:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:418 +msgid "auto_leader:instance002> box.ctl.promote()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:424 +msgid "Check ``box.info.election`` to make sure ``instance002`` is a leader now:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:426 +msgid "auto_leader:instance002> box.info.election\n" +"---\n" +"- leader_idle: 0\n" +" leader_name: instance002\n" +" state: leader\n" +" vote: 1\n" +" term: 4\n" +" leader: 1\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:443 +msgid "Adding and removing instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:445 +msgid "The process of adding instances to a replica set and removing them is similar for all failover modes. Learn how to do this from the :ref:`Master-replica: manual failover ` tutorial:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:448 +msgid ":ref:`Adding instances `" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:449 +msgid ":ref:`Removing instances `" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_auto.rst:451 +msgid "Before removing an instance from a replica set with :ref:`replication.failover ` set to ``election``, make sure this instance is in read-only mode. If the instance is a master, choose a :ref:`new leader manually `." +msgstr "" diff --git a/locale/en/how-to/replication/repl_bootstrap_master_master.pot b/locale/en/how-to/replication/repl_bootstrap_master_master.pot new file mode 100644 index 0000000000..1e0b28a332 --- /dev/null +++ b/locale/en/how-to/replication/repl_bootstrap_master_master.pot @@ -0,0 +1,699 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:4 +msgid "Master-master" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:6 +msgid "**Example on GitHub**: `master_master `_" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:8 +msgid "This tutorial shows how to configure and work with a master-master replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:14 +msgid "Prerequisites" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:16 +msgid "Before starting this tutorial:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:18 +msgid "Install the :ref:`tt ` utility." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:20 +msgid "Create a tt environment in the current directory by executing the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:22 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create the ``master_master`` directory." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:24 +msgid "Inside ``instances.enabled/master_master``, create the ``instances.yml`` and ``config.yaml`` files:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:26 +msgid "``instances.yml`` specifies instances to :ref:`run ` in the current environment and should look like this:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:28 +msgid "instance001:\n" +"instance002:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:33 +msgid "The ``config.yaml`` file is intended to store a :ref:`replica set configuration `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:41 +msgid "Configuring a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:43 +msgid "This section describes how to configure a replica set in ``config.yaml``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:49 +msgid "Step 1: Configuring a failover mode" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:51 +msgid "First, set the :ref:`replication.failover ` option to ``off``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:53 +msgid "replication:\n" +" failover: off\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:64 +msgid "Step 2: Defining a replica set topology" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:66 +msgid "Define a replica set topology inside the :ref:`groups ` section:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:68 +msgid "The ``database.mode`` option should be set to ``rw`` to make instances work in read-write mode." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:69 +msgid "The :ref:`iproto.listen ` option specifies an address used to listen for incoming requests and allows replicas to communicate with each other." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:71 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:81 +msgid "Step 3: Creating a user for replication" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:83 +msgid "In the :ref:`credentials ` section, create the ``replicator`` user with the ``replication`` role:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:85 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:95 +msgid "Step 4: Specifying advertise URIs" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:97 +msgid "Set :ref:`iproto.advertise.peer ` to advertise the current instance to other replica set members:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:99 +msgid "iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:109 +msgid "Resulting configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:111 +msgid "The resulting replica set configuration should look as follows:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:113 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: off\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:124 +msgid "Working with a replica set" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:129 +msgid "Starting instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:131 +msgid "After configuring a replica set, execute the :ref:`tt start ` command from the :ref:`tt environment directory `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:133 +msgid "$ tt start master_master\n" +" • Starting an instance [master_master:instance001]...\n" +" • Starting an instance [master_master:instance002]..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:139 +msgid "Check that instances are in the ``RUNNING`` status using the :ref:`tt status ` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:141 +msgid "$ tt status master_master\n" +"INSTANCE STATUS PID\n" +"master_master:instance001 RUNNING 30818\n" +"master_master:instance002 RUNNING 30819" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:152 +msgid "Checking a replica set status" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:154 +msgid "Connect to both instances using :ref:`tt connect `. Below is the example for ``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:157 +msgid "$ tt connect master_master:instance001\n" +" • Connecting to the instance...\n" +" • Connected to master_master:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:163 +msgid "Check that both instances are writable using ``box.info.ro``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:165 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:267 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:398 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:516 +msgid "``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:167 +msgid "master_master:instance001> box.info.ro\n" +"---\n" +"- false\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:174 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:276 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:406 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:524 +msgid "``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:176 +msgid "master_master:instance002> box.info.ro\n" +"---\n" +"- false\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:183 +msgid "Execute ``box.info.replication`` to check a replica set status. For ``instance002``, ``upstream.status`` and ``downstream.status`` should be ``follow``." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:186 +msgid "master_master:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 7\n" +" upstream:\n" +" status: follow\n" +" idle: 0.21281599999929\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00031614303588867\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.21800899999653\n" +" vclock: {1: 7}\n" +" lag: 0\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 0\n" +" name: instance001\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:212 +msgid "To see the diagrams that illustrate how the ``upstream`` and ``downstream`` connections look, refer to :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap.rst:5 +msgid "Note that a ``vclock`` value might include the ``0`` component that is related to local space operations and might differ for different instances in a replica set." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:225 +msgid "Adding data" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:227 +msgid "To check that both instances get updates from each other, follow the steps below:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:229 +msgid "On ``instance001``, create a space, format it, and create a primary index:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:231 +msgid "box.schema.space.create('bands')\n" +"box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:237 +msgid "Then, add sample data to this space:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:239 +msgid "box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:245 +msgid "On ``instance002``, use the ``select`` operation to make sure data is replicated:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:247 +msgid "master_master:instance002> box.space.bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:255 +msgid "Add more data to the created space on ``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:257 +msgid "box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:263 +msgid "Get back to ``instance001`` and use ``select`` to make sure new records are replicated." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:265 +msgid "Check that :ref:`box.info.vclock ` values are the same on both instances:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:269 +msgid "master_master:instance001> box.info.vclock\n" +"---\n" +"- {2: 5, 1: 9}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:278 +msgid "master_master:instance002> box.info.vclock\n" +"---\n" +"- {2: 5, 1: 9}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:290 +msgid "Resolving replication conflicts" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:294 +msgid "To learn how to fix and prevent replication conflicts using trigger functions, see :ref:`Resolving replication conflicts `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:299 +msgid "Inserting conflicting records" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:301 +msgid "To insert conflicting records to ``instance001`` and ``instance002``, follow the steps below:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:303 +msgid "Stop ``instance001`` using the ``tt stop`` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:305 +msgid "$ tt stop master_master:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:309 +msgid "On ``instance002``, insert a new record:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:311 +msgid "box.space.bands:insert { 5, 'incorrect data', 0 }" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:315 +msgid "Stop ``instance002`` using ``tt stop``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:317 +msgid "$ tt stop master_master:instance002" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:321 +msgid "Start ``instance001`` back:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:323 +msgid "$ tt start master_master:instance001" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:327 +msgid "Connect to ``instance001`` and insert a record that should conflict with a record already inserted on ``instance002``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:329 +msgid "box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:335 +msgid "Start ``instance002`` back:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:337 +msgid "$ tt start master_master:instance002" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:341 +msgid "Then, check ``box.info.replication`` on ``instance001``. ``upstream.status`` should be ``stopped`` because of the ``Duplicate key exists`` error:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:344 +msgid "master_master:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 9\n" +" upstream:\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 143.52251672745\n" +" status: stopped\n" +" idle: 3.9462469999999\n" +" message: Duplicate key exists in unique index \"primary\" in space \"bands\" with\n" +" old tuple - [5, \"Pink Floyd\", 1965] and new tuple - [5, \"incorrect data\", 0]\n" +" name: instance002\n" +" downstream:\n" +" status: stopped\n" +" message: 'unexpected EOF when reading from socket, called on fd 12, aka 127.0.0.1:3301,\n" +" peer of 127.0.0.1:59258: Broken pipe'\n" +" system_message: Broken pipe\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 6\n" +" name: instance001\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:372 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:480 +msgid "The diagram below illustrates how the ``upstream`` and ``downstream`` connections look like:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:0 +msgid "replication status on a new master" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:383 +msgid "Reseeding a replica" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:385 +msgid "To resolve a replication conflict, ``instance002`` should get the correct data from ``instance001`` first. To achieve this, ``instance002`` should be rebootstrapped:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:388 +msgid "In the ``config.yaml`` file, change ``database.mode`` of ``instance002`` to ``ro``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:390 +msgid "instance002:\n" +" database:\n" +" mode: ro" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:396 +msgid "Reload configurations on both instances using the ``reload()`` function provided by the :ref:`config ` module:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:400 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:500 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:518 +msgid "master_master:instance001> require('config'):reload()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:408 +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:526 +msgid "master_master:instance002> require('config'):reload()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:414 +msgid "Delete write-ahead logs and snapshots stored in the ``var/lib/instance002`` directory." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:418 +msgid "``var/lib`` is the default directory used by tt to store write-ahead logs and snapshots. Learn more from :ref:`Configuration `." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:421 +msgid "Restart ``instance002`` using the :ref:`tt restart ` command:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:423 +msgid "$ tt restart master_master:instance002" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:427 +msgid "Connect to ``instance002`` and make sure it received the correct data from ``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:429 +msgid "master_master:instance002> box.space.bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +" - [5, 'Pink Floyd', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:444 +msgid "Restarting replication" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:446 +msgid "After :ref:`reseeding a replica `, you need to resolve a replication conflict that keeps replication stopped:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:448 +msgid "Execute ``box.info.replication`` on ``instance001``. ``upstream.status`` is still stopped:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:451 +msgid "master_master:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 9\n" +" upstream:\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 143.52251672745\n" +" status: stopped\n" +" idle: 1309.943383\n" +" message: Duplicate key exists in unique index \"primary\" in space \"bands\" with\n" +" old tuple - [5, \"Pink Floyd\", 1965] and new tuple - [5, \"incorrect data\",\n" +" 0]\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.47881799999959\n" +" vclock: {2: 6, 1: 9}\n" +" lag: 0\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 6\n" +" name: instance001\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:0 +msgid "replication status after reseeding a replica" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:488 +msgid "In the ``config.yaml`` file, clear the ``iproto`` option for ``instance001`` by setting its value to ``{}`` to disconnect this instance from ``instance002``. Set ``database.mode`` to ``ro``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:491 +msgid "instance001:\n" +" database:\n" +" mode: ro\n" +" iproto: {}" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:498 +msgid "Reload configuration on ``instance001`` only:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:506 +msgid "Change ``database.mode`` values back to ``rw`` for both instances and restore ``iproto.listen`` for ``instance001``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:508 +msgid "instance001:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +"instance002:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:514 +msgid "Reload configurations on both instances one more time:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:532 +msgid "Check ``box.info.replication``. ``upstream.status`` should be ``follow`` now." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:535 +msgid "master_master:instance001> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 4cfa6e3c-625e-b027-00a7-29b2f2182f23\n" +" lsn: 9\n" +" upstream:\n" +" status: follow\n" +" idle: 0.21281300000192\n" +" peer: replicator@127.0.0.1:3302\n" +" lag: 0.00031113624572754\n" +" name: instance002\n" +" downstream:\n" +" status: follow\n" +" idle: 0.035179000002245\n" +" vclock: {2: 6, 1: 9}\n" +" lag: 0\n" +" 2:\n" +" id: 2\n" +" uuid: 9bb111c2-3ff5-36a7-00f4-2b9a573ea660\n" +" lsn: 6\n" +" name: instance001\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:566 +msgid "Adding and removing instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:568 +msgid "The process of adding instances to a replica set and removing them is similar for all failover modes. Learn how to do this from the :ref:`Master-replica: manual failover ` tutorial:" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:571 +msgid ":ref:`Adding instances `" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:572 +msgid ":ref:`Removing instances `" +msgstr "" + +#: ../../doc/how-to/replication/repl_bootstrap_master_master.rst:574 +msgid "Before removing an instance from a replica set with :ref:`replication.failover ` set to ``off``, make sure this instance is in read-only mode." +msgstr "" diff --git a/locale/en/how-to/replication/repl_leader_elect.pot b/locale/en/how-to/replication/repl_leader_elect.pot new file mode 100644 index 0000000000..cadb9fedb1 --- /dev/null +++ b/locale/en/how-to/replication/repl_leader_elect.pot @@ -0,0 +1,121 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:4 +msgid "Managing leader elections" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:6 +msgid "Starting from version :doc:`2.6.1 `, Tarantool has the built-in functionality managing automated leader election in a replica set. Learn more about the :ref:`concept of leader election `." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:14 +msgid "Configuration" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:16 +msgid "box.cfg({\n" +" election_mode = ,\n" +" election_fencing_mode = ,\n" +" election_timeout = ,\n" +" replication_timeout = ,\n" +" replication_synchro_quorum = \n" +"})" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:26 +msgid "``election_mode`` -- specifies the role of a node in the leader election process. For the details, refer to the :ref:`option description ` in the configuration reference." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:29 +msgid "``election_fencing_mode`` -- specifies the :ref:`leader fencing mode `. For the details, refer to the :ref:`option description ` in the configuration reference." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:31 +msgid "``election_timeout`` -- specifies the timeout between election rounds if the previous round ended up with a split vote. For the details, refer to the :ref:`option description ` in the configuration reference." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:35 +msgid "``replication_timeout`` -- reuse of the :ref:`replication_timeout ` configuration option for the purpose of the leader election process. Heartbeats sent by an active leader have a timeout after which a new election starts. Heartbeats are sent once per seconds. The default value is ``1``. The leader is considered dead if it hasn't sent any heartbeats for the period of ``replication_timeout * 4``." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:41 +msgid "``replication_synchro_quorum`` -- reuse of the :ref:`replication_synchro_quorum ` option for the purpose of configuring the election quorum. The default value is ``1``, meaning that each node becomes a leader immediately after voting for itself. It is best to set up this option value to the ``( / 2) + 1``. Otherwise, there is no guarantee that there is only one leader at a time." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:47 +msgid "It is important to know that being a leader is not the only requirement for a node to be writable. The leader should also satisfy the following requirements:" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:50 +msgid "The :ref:`read_only ` option is set to ``false``." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:52 +msgid "The leader shouldn't be in the orphan state." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:54 +msgid "Nothing prevents you from setting the ``read_only`` option to ``true``, but the leader just won't be writable then. The option doesn't affect the election process itself, so a read-only instance can still vote and become a leader." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:62 +msgid "Monitoring" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:64 +msgid "To monitor the current state of a node regarding the leader election, you can use the ``box.info.election`` function. For details, refer to the :doc:`function description `." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:69 +msgid "**Example:**" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:71 +msgid "tarantool> box.info.election\n" +"---\n" +"- state: follower\n" +" vote: 0\n" +" leader: 0\n" +" term: 1\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:81 +msgid "The Raft-based election implementation logs all its actions with the ``RAFT:`` prefix. The actions are new Raft message handling, node state changing, voting, and term bumping." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:88 +msgid "Important notes" +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:90 +msgid "Leader election doesn't work correctly if the election quorum is set to less or equal than `` / 2`` because in that case, a split vote can lead to a state when two leaders are elected at once." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:94 +msgid "For example, suppose there are five nodes. When the quorum is set to ``2``, ``node1`` and ``node2`` can both vote for ``node1``. ``node3`` and ``node4`` can both vote for ``node5``. In this case, ``node1`` and ``node5`` both win the election. When the quorum is set to the cluster majority, that is ``( / 2) + 1`` or greater, the split vote is impossible." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:100 +msgid "That should be considered when adding new nodes. If the majority value is changing, it's better to update the quorum on all the existing nodes before adding a new one." +msgstr "" + +#: ../../doc/how-to/replication/repl_leader_elect.rst:104 +msgid "Also, the automated leader election doesn't bring many benefits in terms of data safety when used *without* :ref:`synchronous replication `. If the replication is asynchronous and a new leader gets elected, the old leader is still active and considers itself the leader. In such case, nothing stops it from accepting requests from clients and making transactions. Non-synchronous transactions are successfully committed because they are not checked against the quorum of replicas. Synchronous transactions fail because they are not able to collect the quorum -- most of the replicas reject these old leader's transactions since it is not a leader anymore." +msgstr "" diff --git a/locale/en/how-to/replication/repl_remove_instances.pot b/locale/en/how-to/replication/repl_remove_instances.pot new file mode 100644 index 0000000000..74dc280ee4 --- /dev/null +++ b/locale/en/how-to/replication/repl_remove_instances.pot @@ -0,0 +1,268 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:4 +msgid "Removing instances" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:6 +msgid "Let's assume that we have the following configured replica set with 3 instances (*instance1*, *instance2* and *intance3*) and we want to remove *instance2*." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:12 +msgid "To remove it politely, follow these steps:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:14 +msgid "Disconnect *instance2* from the cluster." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:15 +msgid "Disconnect the cluster from *instance2*." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:16 +msgid "Remove *instance2* from the ``_cluster`` space." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:21 +msgid "**Step 1: disconnecting an instance from the cluster**" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:23 +msgid "On the disconnecting instance *instance2*, run ``box.cfg{}`` with a blank replication source:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:26 +msgid "tarantool> box.cfg{replication=''}" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:30 +msgid "Then check that it was disconnected. Take a look at ``box.info.replication`` on *instance2* (notice that ``replication.{1,3}.upstream`` is absent):" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:33 +msgid "tarantool> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: db89978f-7115-4537-8417-9982bb5a256f\n" +" lsn: 9\n" +"-- upstream is absent\n" +" downstream:\n" +" status: follow\n" +" idle: 0.93983899999876\n" +" vclock: {1: 9}\n" +"2:\n" +" id: 2\n" +" uuid: 0a756d14-e437-4296-85b0-d27a0621613e\n" +" lsn: 0\n" +"3:\n" +" id: 3\n" +" uuid: bb362584-c265-4e53-aeb6-450ae818bf59\n" +" lsn: 0\n" +"-- upstream is absent\n" +" downstream:\n" +" status: follow\n" +" idle: 0.26624799999991\n" +" vclock: {1: 9}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:61 +msgid "Check *instance1* and *instance3* as well (notice that the status of ``replication.2.downstream`` is ``stopped``):" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:64 +msgid "-- instance1\n" +"tarantool> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: db89978f-7115-4537-8417-9982bb5a256f\n" +" lsn: 9\n" +"2:\n" +" id: 2\n" +" uuid: 0a756d14-e437-4296-85b0-d27a0621613e\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.3533439999992\n" +" peer: replicator@localhost:3302\n" +" lag: 0.0001220703125\n" +" downstream:\n" +" status: stopped -- status has changed:\n" +" message: unexpected EOF when reading from socket, called on fd 13, aka [::1]:3301,\n" +" peer of [::1]:53776\n" +" system_message: Broken pipe\n" +"3:\n" +" id: 3\n" +" uuid: bb362584-c265-4e53-aeb6-450ae818bf59\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.35327999999936\n" +" peer: replicator@localhost:3303\n" +" lag: 0.00018095970153809\n" +" downstream:\n" +" status: follow\n" +" idle: 0.68685100000221\n" +" vclock: {1: 9}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:102 +msgid "**Step 2: disconnecting the cluster from the decommissioned instance**" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:104 +msgid "On every other instance in the cluster remove *instance2* from the ``box.cfg{ replication }`` list and call an appropriate ``box.cfg{ replication = {instance1, instance3} }``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:108 +msgid "tarantool> box.cfg{ replication = { 'instance1-uri', 'instance3-uri' } }" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:112 +msgid "Take a look at ``box.info.replication`` on *instance2* to check that *instance1* and *instance3* were disconnected (notice that the status of ``replication.{1,3}.downstream`` is ``stopped``):" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:116 +msgid "tarantool> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: db89978f-7115-4537-8417-9982bb5a256f\n" +" lsn: 9\n" +" downstream:\n" +" status: stopped -- status has changed\n" +" message: unexpected EOF when reading from socket, called on fd 16, aka [::1]:3302,\n" +" peer of [::1]:53832\n" +" system_message: Broken pipe\n" +"2:\n" +" id: 2\n" +" uuid: 0a756d14-e437-4296-85b0-d27a0621613e\n" +" lsn: 0\n" +"3:\n" +" id: 3\n" +" uuid: bb362584-c265-4e53-aeb6-450ae818bf59\n" +" lsn: 0\n" +" downstream:\n" +" status: stopped -- status has changed\n" +" message: unexpected EOF when reading from socket, called on fd 18, aka [::1]:3302,\n" +" peer of [::1]:53825\n" +" system_message: Broken pipe\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:144 +msgid "Check *instance1* and *instance3* as well (notice that the status of ``replication.2.upstream`` is ``stopped``):" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:147 +msgid "-- instance1\n" +"tarantool> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: db89978f-7115-4537-8417-9982bb5a256f\n" +" lsn: 9\n" +"2:\n" +" id: 2\n" +" uuid: 0a756d14-e437-4296-85b0-d27a0621613e\n" +" lsn: 0\n" +" downstream:\n" +" status: stopped -- status has changed\n" +" message: unexpected EOF when reading from socket, called on fd 13, aka [::1]:3301,\n" +" peer of [::1]:53776\n" +" system_message: Broken pipe\n" +"3:\n" +" id: 3\n" +" uuid: bb362584-c265-4e53-aeb6-450ae818bf59\n" +" lsn: 0\n" +" upstream:\n" +" status: follow\n" +" idle: 0.50240100000156\n" +" peer: replicator@localhost:3303\n" +" lag: 0.00015711784362793\n" +" downstream:\n" +" status: follow\n" +" idle: 0.14237199999843\n" +" vclock: {1: 9}\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:180 +msgid "**Step 3: persistent removal**" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:182 +msgid "If a removed instance rejoins later, it will receive all the updates made by the other instances while it was disconnected." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:185 +msgid "If an instance is decommissioned forever, we should clean up the ``_cluster`` space. First, discover the ``id`` and ``uuid`` of the instance. On *instance2*, call ``return box.info.id, box.info.uuid``:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:189 +msgid "tarantool> return box.info.id, box.info.uuid\n" +"---\n" +"- 2\n" +"- '0a756d14-e437-4296-85b0-d27a0621613e'\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:197 +msgid "Take a note of ``id`` and ``uuid``." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:199 +msgid "Now choose any master from the remaining cluster and perform the following actions on it (let's assume that we chose *instance1*):" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:202 +msgid "Select all records from the ``_cluster`` space:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:204 +msgid "tarantool> box.space._cluster:select{}\n" +"---\n" +"- - [1, 'db89978f-7115-4537-8417-9982bb5a256f']\n" +"- [2, '0a756d14-e437-4296-85b0-d27a0621613e']\n" +"- [3, 'bb362584-c265-4e53-aeb6-450ae818bf59']\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:213 +msgid "Check if the ``id`` and ``uuid`` of *instance2* are correct and remove them from the cluster:" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:216 +msgid "tarantool> box.space._cluster:delete(2)\n" +"---\n" +"- [2, '0a756d14-e437-4296-85b0-d27a0621613e']\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:223 +msgid "**Final checks**" +msgstr "" + +#: ../../doc/how-to/replication/repl_remove_instances.rst:225 +msgid "After all modifications, say ``box.info.replication`` to check the health status." +msgstr "" diff --git a/locale/en/how-to/replication/repl_sync.pot b/locale/en/how-to/replication/repl_sync.pot new file mode 100644 index 0000000000..222cf60b8b --- /dev/null +++ b/locale/en/how-to/replication/repl_sync.pot @@ -0,0 +1,126 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/replication/repl_sync.rst:4 +msgid "Configuring synchronous replication" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:6 +msgid "Since version :doc:`2.5.1 `, :ref:`synchronous replication ` can be enabled per-space by using the ``is_sync`` option:" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:10 +msgid "box.schema.create_space('test1', {is_sync = true})" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:14 +msgid "Any transaction doing a DML request on this space becomes synchronous. Notice that DDL on this space (including truncation) is **not** synchronous." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:17 +msgid "To control the behavior of synchronous transactions, there exist global ``box.cfg`` :ref:`options `:" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:20 +msgid "box.cfg{replication_synchro_quorum = }" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:24 +msgid "box.cfg{replication_synchro_quorum = \"N / 2 + 1\"}" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:28 +msgid "This option tells how many replicas should confirm the receipt of a synchronous transaction before it is committed. Since version :doc:`2.5.3 `, the parameter supports dynamic evaluation of the quorum number (see :ref:`reference for the replication_synchro_quorum parameter ` for details). Since version :doc:`2.10.0 `, this option does not account for anonymous replicas. As a usage example, consider this:" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:35 +msgid "-- Instance 1\n" +"box.cfg{\n" +" listen = 3313,\n" +" replication_synchro_quorum = 2,\n" +"}\n" +"box.schema.user.grant('guest', 'super')\n" +"_ = box.schema.space.create('sync', {is_sync=true})\n" +"_ = _:create_index('pk')" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:46 +msgid "-- Instance 2\n" +"box.cfg{\n" +" listen = 3314,\n" +" replication = 'localhost:3313'\n" +"}" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:54 +msgid "-- Instance 1\n" +"box.space.sync:replace{1}" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:59 +msgid "When the first instance makes ``replace()``, it won't finish until the second instance confirms its receipt and successful appliance. Note that the quorum is set to 2, but the transaction was still committed even though there is only one replica. This is because the master instance itself also participates in the quorum." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:64 +msgid "Now, if the second instance is down, the first one won't be able to commit any synchronous change." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:67 +msgid "-- Instance 2\n" +"Ctrl+D" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:72 +msgid "-- Instance 1\n" +"tarantool> box.space.sync:replace{2}\n" +"---\n" +"- error: Quorum collection for a synchronous transaction is timed out\n" +"..." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:80 +msgid "The transaction wasn't committed because it failed to achieve the quorum in the given time. The time is a second configuration option:" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:83 +msgid "box.cfg{replication_synchro_timeout = }" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:87 +msgid "It tells how many seconds to wait for a synchronous transaction quorum replication until it is declared failed and is rolled back." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:90 +msgid "A successful synchronous transaction commit is persisted in the WAL as a special CONFIRM record. The rollbacks are similarly persisted with a ROLLBACK record." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:93 +msgid "The ``timeout`` and ``quorum`` options are not used on replicas. It means if the master dies, the pending synchronous transactions will be kept waiting on the replicas until a new master is elected." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:99 +msgid "Tips and tricks" +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:101 +msgid "If a transaction is rolled back, it does not mean the ROLLBACK message reached the replicas. It still can happen that the master node suddenly dies, so the transaction will be committed by the new master. Your application logic should be ready for that." +msgstr "" + +#: ../../doc/how-to/replication/repl_sync.rst:106 +msgid "Synchronous transactions are better to use with full mesh. Then the replicas can talk to each other in case of the master node's death and still confirm some pending transactions." +msgstr "" diff --git a/locale/en/how-to/sql/improving_mysql.pot b/locale/en/how-to/sql/improving_mysql.pot new file mode 100644 index 0000000000..5acdad0108 --- /dev/null +++ b/locale/en/how-to/sql/improving_mysql.pot @@ -0,0 +1,425 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 21:18+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/sql/improving_mysql.rst:4 +msgid "Improving MySQL with Tarantool" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:6 +msgid "Replicating MySQL is one of the Tarantool’s killer functions. It allows you to keep your existing MySQL database while at the same time accelerating it and scaling it out horizontally. Even if you aren’t interested in extensive expansion, replacing existing replicas with Tarantool can save you money, because Tarantool is more efficient per core than MySQL. To read a testimonial of a company that implemented Tarantool replication on a large scale, see `the following article `_." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:14 +msgid "If you run into any trouble with regards to the basics of Tarantool, see the :ref:`Getting started guide ` or the :ref:`Data model description `. A helpful log for troubleshooting during this tutorial is ``replicatord.log`` in ``/var/log``. You can also have a look at the instance’s log ``example.log`` in ``/var/log/tarantool``." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:19 +msgid "The tutorial is intended for **CentOS 7.5** and **MySQL 5.7**. The tutorial requires that ``systemd`` and MySQL are installed." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:25 +msgid "Setting up MySQL" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:27 +msgid "In this section, you configure MySQL and create a database." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:29 +msgid "First, install the necessary packages in CentOS:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:31 +msgid "$ yum -y install git ncurses-devel cmake gcc-c++ boost boost-devel wget unzip nano bzip2 mysql-devel mysql-lib" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:35 +msgid "Clone the Tarantool-MySQL replication package from GitHub:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:37 +msgid "$ git clone https://github.com/tarantool/mysql-tarantool-replication.git" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:41 +msgid "Build the replicator with ``cmake``:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:43 +msgid "$ cd mysql-tarantool-replication\n" +"$ git submodule update --init --recursive\n" +"$ cmake .\n" +"$ make" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:50 +msgid "The replicator will run as a ``systemd`` daemon called ``replicatord``, so, edit its ``systemd`` service file (``replicatord.service``) in the ``mysql-tarantool-replication`` repository:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:54 +msgid "$ nano replicatord.service" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:58 +msgid "The following line should be changed:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:60 +msgid "ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.cfg" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:64 +msgid "To change it, replace the ``.cfg`` extension with ``.yml``:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:66 +msgid "ExecStart=/usr/local/sbin/replicatord -c /usr/local/etc/replicatord.yml" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:70 +msgid "Next, copy the files from the ``replicatord`` repository to other necessary locations:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:72 +msgid "$ cp replicatord /usr/local/sbin/replicatord\n" +"$ cp replicatord.service /etc/systemd/system" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:77 +msgid "Enter MySQL console and create a sample database (depending on your existing installation, you may be a user other than root):" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:80 +msgid "mysql -u root -p\n" +"CREATE DATABASE menagerie;\n" +"QUIT" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:86 +msgid "Get some sample data from MySQL. The data will be pulled into the root directory. After that, install it from the terminal." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:89 +msgid "cd\n" +"wget http://downloads.mysql.com/docs/menagerie-db.zip\n" +"unzip menagerie-db.zip\n" +"cd menagerie-db\n" +"mysql -u root -p menagerie < cr_pet_tbl.sql\n" +"mysql -u root -p menagerie < load_pet_tbl.sql\n" +"mysql menagerie -u root -p < ins_puff_rec.sql\n" +"mysql menagerie -u root -p < cr_event_tbl.sql" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:100 +msgid "Enter MySQL console and massage the data for use with the Tarantool replicator. In this step, you:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:103 +msgid "add an ID" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:104 +msgid "change a field name to avoid conflict" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:105 +msgid "cut down the number of fields" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:107 +msgid "With real data, this is the step that involves the most tweaking." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:109 +msgid "mysql -u root -p\n" +"USE menagerie;\n" +"ALTER TABLE pet ADD id INT PRIMARY KEY AUTO_INCREMENT FIRST;\n" +"ALTER TABLE pet CHANGE COLUMN 'name' 'name2' VARCHAR(255);\n" +"ALTER TABLE pet DROP sex, DROP birth, DROP death;\n" +"QUIT" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:118 +msgid "The sample data is set up. Edit MySQL configuration file to use it with the replicator:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:121 +msgid "$ cd\n" +"$ nano /etc/my.cnf" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:126 +msgid "Note that your ``my.cnf`` for MySQL could be in a slightly different location. Set:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:129 +msgid "[mysqld]\n" +"binlog_format = ROW\n" +"server_id = 1\n" +"log-bin = mysql-bin\n" +"interactive_timeout = 3600\n" +"wait_timeout = 3600\n" +"max_allowed_packet = 32M\n" +"socket = /var/lib/mysql/mysql.sock\n" +"bind-address = 127.0.0.1\n" +"\n" +"[client]\n" +"socket = /var/lib/mysql/mysql.sock" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:144 +msgid "After exiting ``nano``, restart ``mysqld``:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:146 +msgid "$ systemctl restart mysqld" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:153 +msgid "Installing and configuring Tarantool" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:155 +msgid "In this section, you install Tarantool and set up spaces for replication." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:157 +msgid "Go to the `Download page `_ and follow the installation instructions." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:160 +msgid "Install the :ref:`tt CLI ` utility." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:162 +msgid "Create a new tt environment in the current directory using the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:164 +msgid "In the ``/etc/tarantool/instances.available/mysql`` directory, create the ``tt`` instance configuration files:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:166 +msgid "``config.yaml`` -- specifies the following configuration" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:168 +msgid "app:\n" +" file: 'myapp.lua'\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +"" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:172 +msgid "``instances.yml`` -- specifies instances to run in the current environment" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:174 +msgid "instance001:\n" +"" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:178 +msgid "``myapp.lua`` -- contains a Lua script with an application to load" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:180 +msgid "box.schema.user.grant('guest', 'read,write,execute', 'universe')\n" +"\n" +"local function bootstrap()\n" +" if not box.space.mysqldaemon then\n" +" s = box.schema.space.create('mysqldaemon')\n" +" s:create_index('primary',\n" +" { type = 'tree', parts = { 1, 'unsigned' }, if_not_exists = true })\n" +" end\n" +" if not box.space.mysqldata then\n" +" t = box.schema.space.create('mysqldata')\n" +" t:create_index('primary',\n" +" { type = 'tree', parts = { 1, 'unsigned' }, if_not_exists = true })\n" +" end\n" +"end\n" +"bootstrap()\n" +"" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:185 +msgid "For details, see the :ref:`Configuration ` section." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:187 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create a symlink (``mysql``) to the directory from the previous step:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:190 +msgid "$ ln -s /etc/tarantool/instances.available/mysql mysql" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:194 +msgid "Next, start up the Lua program with ``tt``, the Tarantool command-line utility:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:197 +msgid "$ tt start mysql" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:201 +#: ../../doc/how-to/sql/improving_mysql.rst:269 +msgid "Enter the Tarantool instance:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:203 +#: ../../doc/how-to/sql/improving_mysql.rst:271 +#: ../../doc/how-to/sql/improving_mysql.rst:312 +msgid "$ tt connect mysql:instance001" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:207 +msgid "Check that the target spaces were successfully created:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:209 +msgid "mysql:instance001> box.space._space:select()" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:213 +msgid "At the bottom, you will see ``mysqldaemon`` and ``mysqldata`` spaces. Then exit with \"CTRL+C\"." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:218 +msgid "Setting up the replicator" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:220 +msgid "MySQL and Tarantool are now set up. You can proceed to configure the replicator." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:222 +msgid "Edit the ``replicatord.yml`` file in the main ``tarantool-mysql-replication`` directory:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:224 +msgid "nano replicatord.yml" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:228 +msgid "Change the entire file as follows. Don't forget to add your MySQL password and set the appropriate user:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:231 +msgid "mysql:\n" +" host: 127.0.0.1\n" +" port: 3306\n" +" user: root\n" +" password:\n" +" connect_retry: 15 # seconds\n" +"\n" +"tarantool:\n" +" host: 127.0.0.1:3301\n" +" binlog_pos_space: 512\n" +" binlog_pos_key: 0\n" +" connect_retry: 15 # seconds\n" +" sync_retry: 1000 # milliseconds\n" +"\n" +"mappings:\n" +" - database: menagerie\n" +" table: pet\n" +" columns: [ id, name2, owner, species ]\n" +" space: 513\n" +" key_fields: [ 0 ]\n" +" # insert_call: function_name\n" +" # update_call: function_name\n" +" # delete_call: function_name" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:257 +msgid "Copy ``replicatord.yml`` to the location where ``systemd`` looks for it:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:259 +msgid "$ cp replicatord.yml /usr/local/etc/replicatord.yml" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:263 +msgid "Next, start up the replicator:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:265 +msgid "$ systemctl start replicatord" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:275 +msgid "Do a select on the ``mysqldata`` space. The replicated content from MySQL looks the following way:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:277 +msgid "mysql:instance001> box.space.mysqldata:select()\n" +"---\n" +"- - [1, 'Fluffy', 'Harold', 'cat']\n" +" - [2, 'Claws', 'Gwen', 'cat']\n" +" - [3, 'Buffy', 'Harold', 'dog']\n" +" - [4, 'Fang', 'Benny', 'dog']\n" +" - [5, 'Bowser', 'Diane', 'dog']\n" +" - [6, 'Chirpy', 'Gwen', 'bird']\n" +" - [7, 'Whistler', 'Gwen', 'bird']\n" +" - [8, 'Slim', 'Benny', 'snake']\n" +" - [9, 'Puffball', 'Diane', 'hamster']" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:294 +msgid "Testing the replication" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:296 +msgid "In this section, you enter a record into MySQL and check that the record is replicated to Tarantool. To do this:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:299 +msgid "Exit the Tarantool instance with ``CTRL-D``." +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:301 +msgid "Insert a record into MySQL:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:303 +msgid "mysql -u root -p\n" +"USE menagerie;\n" +"INSERT INTO pet(name2, owner, species) VALUES ('Spot', 'Brad', 'dog');\n" +"QUIT" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:310 +msgid "In the terminal, enter the Tarantool instance:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:316 +msgid "To see the replicated data in Tarantool, run the following command:" +msgstr "" + +#: ../../doc/how-to/sql/improving_mysql.rst:318 +msgid "mysql:instance001> box.space.mysqldata:select()" +msgstr "" diff --git a/locale/en/how-to/sql/index.pot b/locale/en/how-to/sql/index.pot new file mode 100644 index 0000000000..252e63ce5d --- /dev/null +++ b/locale/en/how-to/sql/index.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/sql/index.rst:2 +msgid "SQL guides" +msgstr "" + +#: ../../doc/how-to/sql/index.rst:4 +msgid "This section contains hands-on SQL guides. You might also want to read the in-depth :ref:`SQL reference `." +msgstr "" diff --git a/locale/en/how-to/sql/sql_beginners_guide.pot b/locale/en/how-to/sql/sql_beginners_guide.pot new file mode 100644 index 0000000000..d561b3ad5b --- /dev/null +++ b/locale/en/how-to/sql/sql_beginners_guide.pot @@ -0,0 +1,942 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:4 +msgid "SQL beginners' guide" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:6 +msgid "The Beginners' Guide describes how users can start up with SQL with Tarantool, and necessary concepts." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:8 +msgid "The SQL Beginners' Guide is about databases in general, and about the relationship between Tarantool's NoSQL and SQL products. Most of the matters in the Beginners' Guide will already be familiar to people who have used relational databases before." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:15 +msgid "Sample table" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:17 +msgid "In football training camp it is traditional for the trainer to begin by showing a football and saying \"this is a football\". In that spirit, this is a table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:20 +msgid "TABLE\n" +" [1] [2] [3]\n" +" +-----------------+----------------+----------------+\n" +" Row#1 | Row#1,Column#1 | Row#1,Column#2 | Row#1,Column#3 |\n" +" +-----------------+----------------+----------------+\n" +" Row#2 | Row#2,Column#1 | Row#2,Column#2 | Row#2,Column#3 |\n" +" +-----------------+----------------+----------------+\n" +" Row#3 | Row#3,Column#1 | Row#3,Column#2 | Row#3,Column#3 |\n" +" +-----------------+----------------+----------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:32 +msgid "But the labels are misleading -- one usually doesn't identify rows and columns by their ordinal positions, one prefers to pick out specific items by their contents. In that spirit, this is a table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:35 +#: ../../doc/how-to/sql/sql_beginners_guide.rst:698 +msgid "MODULES\n" +"\n" +"+-----------------+------+---------------------+\n" +"| NAME | SIZE | PURPOSE |\n" +"+-----------------+------+---------------------+\n" +"| box | 1432 | Database Management |\n" +"| clock | 188 | Seconds |\n" +"| crypto | 4 | Cryptography |\n" +"+-----------------+------+---------------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:47 +msgid "So one does not use longitude/latitude navigation by talking about \"Row#2 Column #2\", one uses the contents of the Name column and the name of the Size column by talking about \"the size, where the name is 'clock'\". To be more exact, this is what one says:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:52 +#: ../../doc/how-to/sql/sql_beginners_guide.rst:331 +#: ../../doc/how-to/sql/sql_beginners_guide.rst:386 +msgid "SELECT size FROM modules WHERE name = 'clock';" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:56 +msgid "If you're familiar with Tarantool's architecture -- and ideally you read about that before coming to this chapter -- then you know that there is a NoSQL way to get the same thing:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:60 +msgid "box.space.MODULES:select()[2][2]" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:64 +msgid "Well, you can do that. One of the advantages of Tarantool is that if you can get data via an SQL statement, then you can get the same data via a NoSQL request. But the reverse is not true, because not all NoSQL tuple sets are definable as SQL tables. These restrictions apply for SQL that do not apply for NoSQL: |br| 1. Every column must have a name. |br| 2. Every column should have a scalar type (Tarantool is relaxed about which particular scalar type you can have, but there is no way to index and search arrays, tables within tables, or what MessagePack calls \"maps\".)" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:73 +msgid "Tarantool/NoSQL's \"format\" clause causes the same restrictions." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:75 +msgid "So an SQL \"table\" is a NoSQL \"tuple set with format restrictions\", an SQL \"row\" is a NoSQL \"tuple\", an SQL \"column\" is a NoSQL \"list of fields within a tuple set\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:81 +msgid "Creating a table" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:83 +msgid "This is how to create the modules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:85 +msgid "CREATE TABLE modules (name STRING, size INTEGER, purpose STRING, PRIMARY KEY (name));" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:89 +msgid "The words that are IN CAPITAL LETTERS are \"keywords\" (although it is only a convention in this manual that keywords are in capital letters, in practice many programmers prefer to avoid shouting). A keyword has meaning for the SQL parser so many keywords are reserved, they cannot be used as names unless they are enclosed inside quotation marks." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:94 +msgid "The word \"modules\" is a \"table name\", and the words \"name\" and \"size\" and \"purpose\" are \"column names\". All tables and all columns must have names." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:97 +msgid "The words \"STRING\" and \"INTEGER\" are \"data types\". STRING means \"the contents should be characters, the length is indefinite, the equivalent NoSQL type is 'string''\". INTEGER means \"the contents should be numbers without decimal points, the equivalent NoSQL type is 'integer'\". Tarantool supports other data types but this section's example table has data types from the two main groups, namely, data types for numbers and data types for strings." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:103 +msgid "The final clause, PRIMARY KEY (name), means that the name column is the main column used to identify the row." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:108 +msgid "Nulls" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:110 +msgid "Frequently it is necessary, at least temporarily, that a column value should be NULL. Typical situations are: the value is unknown, or the value is not applicable. For example, you might make a module as a placeholder but you don't want to say its size or purpose. If such things are possible, the column is \"nullable\". The example table's name column cannot contain nulls, and it could be defined explicitly as \"name STRING NOT NULL\", but in this case that's unnecessary -- a column defined as PRIMARY KEY is automatically NOT NULL." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:117 +msgid "Is a NULL in SQL the same thing as a nil in Lua? No, but it is close enough that there will be confusion. When nil means \"unknown\" or \"inapplicable\", yes. But when nil means \"nonexistent\" or \"type is nil\", no. NULL is a value, it has a data type because it is inside a column which is defined with that data type." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:126 +msgid "Creating an index" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:128 +msgid "This is how to create indexes for the modules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:130 +msgid "CREATE INDEX size ON modules (size);\n" +"CREATE UNIQUE INDEX purpose ON modules (purpose);" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:135 +msgid "There is no need to create an index on the name column, because Tarantool creates an index automatically when it sees a PRIMARY KEY clause in the CREATE TABLE statement. In fact there is no need to create indexes on the size or purpose columns either -- if indexes don't exist, then it is still possible to use the columns for searches. Typically people create non-primary indexes, also called secondary indexes, when it becomes clear that the table will grow large and searches will be frequent, because searching with an index is generally much faster than searching without an index." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:143 +msgid "Another use for indexes is to enforce uniqueness. When an index is created with CREATE UNIQUE INDEX for the purpose column, it is not possible to have duplicate values in that column." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:150 +msgid "Data change" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:152 +msgid "Putting data into a table is called \"inserting\". Changing data is called \"updating\". Removing data is called \"deleting\". Together, the three SQL statements INSERT plus UPDATE plus DELETE are the three main \"data-change\" statements." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:157 +msgid "This is how to insert, update, and delete a row in the modules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:159 +msgid "INSERT INTO modules VALUES ('json', 14, 'format functions for JSON');\n" +"UPDATE modules SET size = 15 WHERE name = 'json';\n" +"DELETE FROM modules WHERE name = 'json';" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:165 +msgid "The corresponding non-SQL Tarantool requests would be:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:167 +msgid "box.space.MODULES:insert{'json', 14, 'format functions for JSON'}\n" +"box.space.MODULES:update('json', {{'=', 2, 15}})\n" +"box.space.MODULES:delete{'json'}" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:173 +msgid "This is how one would populate the table with the values that was shown earlier:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:175 +msgid "INSERT INTO modules VALUES ('box', 1432, 'Database Management');\n" +"INSERT INTO modules VALUES ('clock', 188, 'Seconds');\n" +"INSERT INTO modules VALUES ('crypto', 4, 'Cryptography');" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:184 +msgid "Constraints" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:186 +msgid "Some data-change statements are illegal due to something in the table's definition. This is called \"constraining what can be done\". Some types of constraints have already been shown ..." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:189 +msgid "NOT NULL -- if a column is defined with a NOT NULL clause, it is illegal to put NULL into it. A primary-key column is automatically NOT NULL." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:192 +msgid "UNIQUE -- if a column has a UNIQUE index, it is illegal to put a duplicate into it. A primary-key column automatically has a UNIQUE index." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:195 +msgid "data domain -- if a column is defined as having data type INTEGER, it is illegal to put a non-number into it. More generally, if a value doesn't correspond to the data type of the definition, it is illegal. Some database management systems (DBMSs) are very forgiving and will try to make allowances for bad values rather than reject them; Tarantool is a bit more strict than those DBMSs." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:200 +msgid "Now, here are other types of constraints ..." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:202 +msgid "CHECK -- a table description can have a clause \"CHECK (conditional expression)\". For example, if the CREATE TABLE modules statement looked like this:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:205 +msgid "CREATE TABLE modules (name STRING,\n" +" size INTEGER,\n" +" purpose STRING,\n" +" PRIMARY KEY (name),\n" +" CHECK (size > 0));" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:213 +msgid "then this INSERT statement would be illegal: |br| ``INSERT INTO modules VALUES ('box', 0, 'The Database Kernel');`` |br| because there is a CHECK constraint saying that the second column, the size column, cannot contain a value which is less than or equal to zero. Try this instead: |br| ``INSERT INTO modules VALUES ('box', 1, 'The Database Kernel');``" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:219 +msgid "FOREIGN KEY -- a table description can have a clause \"FOREIGN KEY (column-list) REFERENCES table (column-list)\". For example, if there is a new table \"submodules\" which in a way depends on the modules table, it can be defined like this:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:224 +msgid "CREATE TABLE submodules (name STRING,\n" +" module_name STRING,\n" +" size INTEGER,\n" +" purpose STRING,\n" +" PRIMARY KEY (name),\n" +" FOREIGN KEY (module_name) REFERENCES\n" +" modules (name));" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:234 +msgid "Now try to insert a new row into this submodules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:236 +msgid "INSERT INTO submodules VALUES\n" +" ('space', 'Box', 10000, 'insert etc.');" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:241 +msgid "The insert will fail because the second column (module_name) refers to the name column in the modules table, and the name column in the modules table does not contain 'Box'. However, it does contain 'box'. By default searches in Tarantool's SQL use a binary collation. This will work:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:247 +msgid "INSERT INTO submodules\n" +" VALUES ('space', 'box', 10000, 'insert etc.');" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:252 +msgid "Now try to delete the corresponding row from the modules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:254 +msgid "DELETE FROM modules WHERE name = 'box';" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:258 +msgid "The delete will fail because the second column (module_name) in the submodules table refers to the name column in the modules table, and the name column in the modules table would not contain 'box' if the delete succeeded. So the FOREIGN KEY constraint affects both the table which contains the FOREIGN KEY clause and the table that the FOREIGN KEY clause refers to." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:264 +msgid "The constraints in a table's definition -- NOT NULL, UNIQUE, data domain, CHECK, and FOREIGN KEY -- are guarantors of the database's integrity. It is important that they are fixed and well-defined parts of the definition, and hard to bypass with SQL. This is often seen as a difference between SQL and NoSQL -- SQL emphasizes law and order, NoSQL emphasizes freedom and making your own rules." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:274 +msgid "Table relationships" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:276 +msgid "Think about the two tables that have been discussed so far:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:278 +msgid "CREATE TABLE modules (name STRING,\n" +" size INTEGER,\n" +" purpose STRING,\n" +" PRIMARY KEY (name),\n" +" CHECK (size > 0));\n" +"\n" +"CREATE TABLE submodules (name STRING,\n" +" module_name STRING,\n" +" size INTEGER,\n" +" purpose STRING,\n" +" PRIMARY KEY (name),\n" +" FOREIGN KEY (module_name) REFERENCES\n" +" modules (name));" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:300 +msgid "Because of the FOREIGN KEYS clause in the submodules table, there is clearly a many-to-one relationship: |br| submodules -->> modules |br| that is, every submodules row must refer to one (and only one) modules row, while every modules row can be referred to in zero or more submodules rows." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:305 +msgid "Table relationships are important, but beware: do not trust anyone who tells you that databases made with SQL are relational \"because there are relationships between tables\". That is wrong, as will be clear in the discussion about what makes a database relational, later." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:313 +msgid "Selecting with WHERE" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:317 +msgid "By default, Tarantool prohibits ``SELECT`` queries that scan table rows instead of using indexes to avoid unwanted heavy load. For the purposes of this tutorial, allow SQL scan queries in Tarantool by running the command:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:321 +msgid "SET SESSION \"sql_seq_scan\" = true;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:325 +msgid "Alternatively, you can allow a specific query to perform a table scan by adding the ``SEQSCAN`` keyword before the table name. Learn more about using ``SEQSCAN`` in SQL scan queries in the :ref:`SQL FROM clause description `." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:329 +msgid "We gave a simple example of a SELECT statement earlier:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:335 +msgid "The clause \"WHERE name = 'clock'\" is legal in other statements -- it is in examples with UPDATE and DELETE -- but here the only examples will be with SELECT." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:338 +msgid "The first variation is that the WHERE clause does not have to be specified at all, it is optional. So this statement would return all rows:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:341 +msgid "SELECT size FROM modules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:345 +msgid "The second variation is that the comparison operator does not have to be '=', it can be anything that makes sense: '>' or '>=' or '<' or '<=', or 'LIKE' which is an operator that works with strings that may contain wildcard characters '_' meaning 'match any one character' or '%' meaning 'match any zero or one or many characters'. These are legal statements which return all rows:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:352 +msgid "SELECT size FROM modules WHERE name >= '';\n" +"SELECT size FROM modules WHERE name LIKE '%';" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:357 +msgid "The third variation is that IS [NOT] NULL is a special condition. Remembering that the NULL value can mean \"it is unknown what the value should be\", and supposing that in some row the size is NULL, then the condition \"size > 10\" is not certainly true and it is not certainly false, so it is evaluated as \"unknown\". Ordinarily the application of a WHERE clause filters out both false and unknown results. So when searching for NULL, say IS NULL; when searching anything that is not NULL, say IS NOT NULL. This statement will return all rows because (due to the definition) there are no NULLs in the name column:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:367 +msgid "SELECT size FROM modules WHERE name IS NOT NULL;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:371 +msgid "The fourth variation is that conditions can be combined with AND / OR, and negated with NOT." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:373 +msgid "So this statement would return all rows (the first condition is false but the second condition is true, and OR means \"return true if either condition is true\"):" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:376 +msgid "SELECT size\n" +"FROM modules\n" +"WHERE name = 'wombat' OR size IS NOT NULL;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:382 +msgid "**Selecting with a select list**" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:384 +msgid "Yet again, here is a simple example of a SELECT statement:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:390 +msgid "The words between SELECT and FROM are the select list. In this case, the select list is just one word: size. Formally it means that the desire is to return the size values, and technically the name for picking a particular column is called \"projection\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:395 +msgid "The first variation is that one can specify any column in any order:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:397 +msgid "SELECT name, purpose, size FROM modules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:401 +msgid "The second variation is that one can specify an expression, it does not have to be a column name, it does not even have to include a column name. The common expression operators for numbers are the arithmetic operators ``+ - / *``; the common expression operator for strings is the concatenation operator ||. For example this statement will return 8, 'XY':" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:407 +msgid "SELECT size * 2, 'X' || 'Y' FROM modules WHERE size = 4;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:411 +msgid "The third variation is that one can add a clause [AS name] after every expression, so that in the return the column titles will make sense. This is especially important when a title might otherwise be ambiguous or meaningless. For example this statement will return 8, 'XY' as before" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:416 +msgid "SELECT size * 2 AS double_size, 'X' || 'Y' AS concatenated_literals FROM modules\n" +" WHERE size = 4;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:421 +msgid "but displayed as a table the result will look like" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:423 +msgid "+----------------+------------------------+\n" +"| DOUBLE_SIZE | CONCATENATED_LITERALS |\n" +"+----------------+------------------------+\n" +"| 8 | XY |\n" +"+----------------+------------------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:431 +msgid "**Selecting with a select list with asterisk**" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:433 +msgid "Instead of listing columns in a select list, one can just say ``'*'``. For example" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:435 +msgid "SELECT * FROM modules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:439 +msgid "This is the same thing as" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:441 +msgid "SELECT name, size, purpose FROM modules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:445 +msgid "Selecting with ``\"*\"`` saves time for the writer, but it is unclear to a reader who has not memorized what the column names are. Also it is unstable, because there is a way to change a table's definition (the ALTER statement, which is an advanced topic). Nevertheless, although it might be bad to use it for production, it is handy to use it for introduction, so ``\"*\"`` will appear in some following examples." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:455 +msgid "Select with subqueries" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:457 +msgid "Remember that there is a modules table and there is a submodules table. Suppose that there is a desire to list the submodules that refer to modules for which the purpose is X. That is, this involves a search of one table using a value in another table. This can be done by enclosing \"(SELECT ...)\" within the WHERE clause. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:462 +msgid "SELECT name FROM submodules\n" +"WHERE module_name =\n" +" (SELECT name FROM modules WHERE purpose LIKE '%Database%');" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:468 +msgid "Subqueries are also useful in the select list, when one wishes to combine information from more than one table. For example this statement will display submodules rows but will include values that come from the modules table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:472 +msgid "SELECT name AS submodules_name,\n" +" (SELECT purpose FROM modules\n" +" WHERE modules.name = submodules.module_name)\n" +" AS modules_purpose,\n" +" purpose AS submodules_purpose\n" +"FROM submodules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:481 +msgid "Whoa. What are \"modules.name\" and \"submodules.name\"? Whenever you see \"x . y\" you are looking at a \"qualified column name\", and the first part is a table identifier, the second part is a column identifier. It is always legal to use qualified column names, but until now it has not been necessary. Now it is necessary, or at least it is a good idea, because both tables have a column named \"name\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:487 +#: ../../doc/how-to/sql/sql_beginners_guide.rst:720 +#: ../../doc/how-to/sql/sql_beginners_guide.rst:741 +msgid "The result will look like this:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:489 +msgid "+-------------------+------------------------+--------------------+\n" +"| SUBMODULES_NAME | MODULES_PURPOSE | SUBMODULES_PURPOSE |\n" +"+-------------------+------------------------+--------------------+\n" +"| space | Database Management | insert etc. |\n" +"+-------------------+------------------------+--------------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:497 +msgid "Perhaps you have read somewhere that SQL stands for \"Structured Query Language\". That is not true any more. But it is true that the query syntax allows for a structural component, namely the subquery, and that was the original idea. However, there is a different way to combine tables -- with joins instead of subqueries." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:506 +msgid "Select with Cartesian join" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:508 +msgid "Until now only \"FROM modules\" or \"FROM submodules\" was used in SELECT statements. What if there was more than one table in the FROM clause? For example" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:511 +msgid "SELECT * FROM modules, submodules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:515 +msgid "or" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:517 +msgid "SELECT * FROM modules JOIN submodules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:521 +msgid "That is legal. Usually it is not what you want, but it is a learning aid. The result will be:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:523 +msgid "{ columns from modules table } { columns from submodules table }\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+\n" +"| NAME | SIZE | PURPOSE | NAME | MODULE_NAME | SIZE | PURPOSE |\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+\n" +"| box | 1432 | Database Management | space | box | 10000 | insert etc. |\n" +"| clock | 188 | Seconds | space | box | 10000 | insert etc. |\n" +"| crypto | 4 | Cryptography | space | box | 10000 | insert etc. |\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:534 +msgid "It is not an error. The meaning of this type of join is \"combine every row in table-1 with every row in table-2\". It did not specify what the relationship should be, so the result has everything, even when the submodule has nothing to do with the module." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:538 +msgid "It is handy to look at the above result, called a \"Cartesian join\" result, to see what would really be desirable. Probably for this case the row that actually makes sense is the one where the modules.name = submodules.module_name, and it's better to make that clear in both the select list and the WHERE clause, thus:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:542 +msgid "SELECT modules.name AS modules_name,\n" +" modules.size AS modules_size,\n" +" modules.purpose AS modules_purpose,\n" +" submodules.name,\n" +" module_name,\n" +" submodules.size,\n" +" submodules.purpose\n" +"FROM modules, submodules\n" +"WHERE modules.name = submodules.module_name;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:554 +msgid "The result will be:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:556 +msgid "+----------+-----------+------------+--------+---------+-------+-------------+\n" +"| MODULES_ | MODULES_ | MODULES_ | NAME | MODULE_ | SIZE | PURPOSE |\n" +"| NAME | SIZE | PURPOSE | | NAME | | |\n" +"+----------+-----------+--------- --+--------+---------+-------+-------------+\n" +"| box | 1432 | Database | space | box | 10000 | insert etc. |\n" +"| | | Management | | | | |\n" +"+----------+-----------+------------+--------+---------+-------+-------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:566 +msgid "In other words, you can specify a Cartesian join in the FROM clause, then you can filter out the irrelevant rows in the WHERE clause, and then you can rename columns in the select list. This is fine, and every SQL DBMS supports this. But it is worrisome that the number of rows in a Cartesian join is always (number of rows in first table multiplied by number of rows in second table), which means that conceptually you are often filtering in a large set of rows." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:574 +msgid "It is good to start by looking at Cartesian joins because they show the concept. Many people, though, prefer to use different syntaxes for joins because they look better or clearer. So now those alternatives will be shown." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:581 +msgid "Select with join with ON clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:583 +msgid "The ON clause would have the same comparisons as the WHERE clause that was illustrated for the previous section, but the use of different syntax would be making it clear \"this is for the sake of the join\". Readers can see at a glance that it is, in concept at least, an initial step before the result rows are filtered. For example this" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:589 +msgid "SELECT * FROM modules JOIN submodules\n" +" ON (modules.name = submodules.module_name);" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:594 +msgid "is the same as" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:596 +msgid "SELECT * FROM modules, submodules\n" +" WHERE modules.name = submodules.module_name;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:604 +msgid "Select with join with USING clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:606 +msgid "The USING clause would take advantage of names that are held in common between the two tables, with the assumption that the intent is to match those columns with '=' comparisons. For example," +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:609 +msgid "SELECT * FROM modules JOIN submodules USING (name);" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:613 +msgid "has the same effect as" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:615 +msgid "SELECT * FROM modules JOIN submodules WHERE modules.name = submodules.name;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:619 +msgid "If the table had been created with a plan in advance to use USING clauses, that would save time. But that did not happen. So, although the above example \"works\", the results will not be sensible." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:626 +msgid "Select with natural join" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:628 +msgid "A natural join would take advantage of names that are held in common between the two tables, and would do the filtering automatically based on that knowledge, and throw away duplicate columns." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:631 +msgid "If the table had been created with a plan in advance to use natural joins, that would be very handy. But that did not happen. So, although the following example \"works\", the results won't be sensible." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:634 +msgid "SELECT * FROM modules NATURAL JOIN submodules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:638 +msgid "Result: nothing, because modules.name does not match submodules.name, and so on And even if there had been a result, it would only have included four columns: name, module_name, size, purpose." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:645 +msgid "Select with left join" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:647 +msgid "Now what if there is a desire to join modules to submodules, but it's necessary to be sure that all the modules are found? In other words, suppose the requirement is to get modules even if the condition submodules.module_name = modules.name is not true, because the module has no submodules." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:652 +msgid "When that is the requirement, the type of join is an \"outer join\" (as opposed to the type that has been used so far which is an \"inner join\"). Specifically the format will be LEFT [OUTER] JOIN because the main table, modules, is on the left. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:656 +msgid "SELECT *\n" +"FROM modules LEFT JOIN submodules\n" +"ON modules.name = submodules.module_name;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:662 +msgid "which returns:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:664 +msgid "{ columns from modules table } { columns from submodules table }\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+\n" +"| NAME | SIZE | PURPOSE | NAME | MODULE_NAME | SIZE | PURPOSE |\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+\n" +"| box | 1432 | Database Management | space | box | 10000 | insert etc. |\n" +"| clock | 188 | Seconds | NULL | NULL | NULL | NULL |\n" +"| crypto | 4 | Cryptography | NULL | NULL | NULL | NULL |\n" +"+--------+------+---------------------+-------+-------------+-------+-------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:675 +msgid "Thus, for the submodules of the clock module and the submodules of the crypto module -- which do not exist -- there are NULLs in every column." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:681 +msgid "Select with functions" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:683 +msgid "A function can take any expression, including an expression that contains another function, and return a scalar value. There are many such functions. Here will be a description of only one, SUBSTR, which returns a substring of a string." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:687 +msgid "Format: :samp:`SUBSTR({input-string}, {start-with} [, {length}])`" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:689 +msgid "Description: SUBSTR takes input-string, eliminates any characters before start-with, eliminates any characters after (start-with plus length), and returns the result." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:692 +msgid "Example: ``SUBSTR('abcdef', 2, 3)`` returns 'bcd'." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:694 +msgid "Select with aggregation, GROUP BY, and HAVING" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:696 +msgid "Remember that the modules table looks like this:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:711 +msgid "Suppose that there is no need to know all the individual size values, all that is important is their aggregation, that is, take the attributes of the collection. SQL allows aggregation functions including: AVG (average), SUM, MIN (minimum), MAX (maximum), and COUNT. For example" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:716 +msgid "SELECT AVG(size), SUM(size), MIN(size), MAX(size), COUNT(size) FROM modules;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:722 +msgid "+-----------+-----------+-----------+-----------+-----------+\n" +"| COLUMN_1 | COLUMN_2 | COLUMN_3 | COLUMN_4 | COLUMN_5 |\n" +"+-----------+-----------+-----------+-----------+-----------|\n" +"| 541 | 1624 | 4 | 1432 | 3 |\n" +"+-----------+-----------+-----------+-----------+-----------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:730 +msgid "Suppose that the requirement is aggregations, but aggregations of rows that have some common characteristic. Supposing further, the rows should be divided into two groups, the ones whose names begin with 'b' and the ones whose names begin with 'c'. This can be done by adding a clause [GROUP BY expression]. For example," +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:735 +msgid "SELECT SUBSTR(name, 1, 1), AVG(size), SUM(size), MIN(size), MAX(size), COUNT(size)\n" +"FROM modules\n" +"GROUP BY SUBSTR(name, 1, 1);" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:743 +msgid "+------------+--------------+-----------+-----------+-----------+-------------+\n" +"| COLUMN_1 | COLUMN_2 | COLUMN_3 | COLUMN_4 | COLUMN_5 | COLUMN_6 |\n" +"+------------+--------------+-----------+-----------+-----------+-------------+\n" +"| b | 1432 | 1432 | 1432 | 1432 | 1 |\n" +"| c | 96 | 192 | 4 | 188 | 2 |\n" +"+------------+--------------+-----------+-----------+-----------+-------------+" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:756 +msgid "Select with common table expression" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:758 +msgid "It is possible to define a temporary (viewed) table within a statement, usually within a SELECT statement, using a WITH clause. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:761 +msgid "WITH tmp_table AS (SELECT x1 FROM t1) SELECT * FROM tmp_table;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:768 +msgid "Select with order, limit, and offset clauses" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:770 +msgid "So far, tor every search in the modules table, the rows have come out in alphabetical order by name: 'box', then 'clock', then 'crypto'. However, to really be sure about the order, or to ask for a different order, it is necessary to be explicit and add a clause: ``ORDER BY column-name [ASC|DESC]``. (ASC stands for ASCending, DESC stands for DESCending.) For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:778 +msgid "SELECT * FROM modules ORDER BY name DESC;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:782 +msgid "The result will be the usual rows, in descending alphabetical order: 'crypto' then 'clock' then 'box'." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:784 +msgid "After the ORDER BY clause there can be a clause LIMIT n, where n is the maximum number of rows to retrieve. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:786 +msgid "SELECT * FROM modules ORDER BY name DESC LIMIT 2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:790 +msgid "The result will be the first two rows, 'crypto' and 'clock'." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:792 +msgid "After the ORDER BY clause and the LIMIT clause there can be a clause OFFSET n, where n is the row to start with. The first offset is 0. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:795 +msgid "SELECT * FROM modules ORDER BY name DESC LIMIT 2 OFFSET 2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:799 +msgid "The result will be the third row, 'box'." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:804 +msgid "Views" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:806 +msgid "A view is a canned SELECT. If you have a complex SELECT that you want to run frequently, create a view and then do a simple SELECT on the view. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:808 +msgid "CREATE VIEW v AS SELECT size, (size *5) AS size_times_5\n" +"FROM modules\n" +"GROUP BY size, name\n" +"ORDER BY size_times_5;\n" +"SELECT * FROM v;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:819 +msgid "Transactions" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:821 +msgid "Tarantool has a \"Write Ahead Log\" (WAL). Effects of data-change statements are logged before they are permanently stored on disk. This is a reason that, although entire databases can be stored in temporary memory, they are not vulnerable in case of power failure." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:826 +msgid "Tarantool supports commits and rollbacks. In effect, asking for a commit means asking for all the recent data-change statements, since a transaction began, to become permanent. In effect, asking for a rollback means asking for all the recent data-change statements, since a transaction began, to be cancelled." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:832 +msgid "For example, consider these statements:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:834 +msgid "CREATE TABLE things (remark STRING, PRIMARY KEY (remark));\n" +"START TRANSACTION;\n" +"INSERT INTO things VALUES ('A');\n" +"COMMIT;\n" +"START TRANSACTION;\n" +"INSERT INTO things VALUES ('B');\n" +"ROLLBACK;\n" +"SELECT * FROM things;" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:845 +msgid "The result will be: one row, containing 'A'. The ROLLBACK cancelled the second INSERT statement, but did not cancel the first one, because it had already been committed." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:848 +msgid "Ordinarily every statement is automatically committed." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:850 +msgid "After START TRANSACTION, statements are not automatically committed -- Tarantool considers that a transaction is now \"active\", until the transaction ends with a COMMIT statement or a ROLLBACK statement. While a transaction is active, all statements are legal except another START TRANSACTION." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:857 +msgid "Implementing Tarantool's SQL On Top of NoSQL" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:859 +msgid "Tarantool's SQL data is the same as Tarantool's NoSQL data. When you create a table or an index with SQL, you are creating a space or an index in NoSQL. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:862 +msgid "CREATE TABLE things (remark STRING, PRIMARY KEY (remark));\n" +"INSERT INTO things VALUES ('X');" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:867 +msgid "is somewhat similar to" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:869 +msgid "box.schema.space.create('THINGS',\n" +"{\n" +" format = {\n" +" [1] = {[\"name\"] = \"REMARK\", [\"type\"] = \"string\"}\n" +" }\n" +"})\n" +"box.space.THINGS:create_index('pk_unnamed_THINGS_1',{unique=true,parts={1,'string'}})\n" +"box.space.THINGS:insert{'X'}" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:880 +msgid "Therefore you can take advantage of Tarantool's NoSQL features even though your primary language is SQL. Here are some possibilities." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:883 +msgid "(1) NoSQL applications written in one of the connector languages may be slightly faster than SQL applications because SQL statements may require more parsing and may be translated to NoSQL requests." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:886 +msgid "(2) You can write stored procedures in Lua, combining Lua loop-control and Lua library-access statements with SQL statements. These routines are executed on the server, which is the principal advantage of pure-SQL stored procedures." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:889 +msgid "(3) There are some options that are implemented in NoSQL that are not (yet) implemented in SQL. For example you can use NoSQL to change an index option, and to deny access to users named 'guest'." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:892 +msgid "(4) System spaces such as _space and _index can be accessed with SQL SELECT statements. This is not quite the same as an information_schema, but it does mean that you can use SQL to access the database's metadata catalog." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:896 +msgid "Fields in NoSQL spaces can be accessed with SQL if and only if they are scalar and are defined in format clauses. Indexes of NoSQL spaces will be used with SQL if and only if they are TREE indexes." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:902 +msgid "Relational databases" +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:904 +msgid "Edgar F. Codd, the person most responsible for researching and explaining relational database concepts, listed the main criteria as (`Codd's 12 rules `_)." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:908 +msgid "Although Tarantool is not advertised as \"relational\", Tarantool comes with a claim that it complies with these rules, with the following caveats and exceptions ..." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:911 +msgid "The rules state that all data must be viewable as relations. A Tarantool SQL table is a relation. However, it is possible to have duplicate values in SQL tables and it is possible to have an implicit ordering. Those characteristics are not allowed for true relations." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:916 +msgid "The rules state that there must be a dynamic online catalog. Tarantool has one but some metadata is missing from it." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:918 +msgid "The rules state that the data language must support authorization. Tarantool's SQL does not. Authorization occurs via NoSQL requests." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:921 +msgid "The rules require that data must be physically independent (from underlying storage changes) and logically independent (from application program changes). So far there is not enough experience to make this guarantee." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:925 +msgid "The rules require certain types of updatable views. Tarantool's views are not updatable." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:927 +msgid "The rules state that it should be impossible to use a low-level language to bypass integrity as defined in the relational-level language. In Tarantool's case, this is not true, for example one can execute a request with Tarantool's NoSQL to violate a foreign-key constraint that was defined with Tarantool's SQL." +msgstr "" + +#: ../../doc/how-to/sql/sql_beginners_guide.rst:932 +msgid "To learn more about SQL in Tarantool, check the :ref:`reference `." +msgstr "" diff --git a/locale/en/how-to/sql/sql_tutorial.pot b/locale/en/how-to/sql/sql_tutorial.pot new file mode 100644 index 0000000000..8271dfc12e --- /dev/null +++ b/locale/en/how-to/sql/sql_tutorial.pot @@ -0,0 +1,1027 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 21:18+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/sql/sql_tutorial.rst:4 +msgid "SQL tutorial" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:6 +msgid "This tutorial is a demonstration of the support for SQL in Tarantool. It includes the functionality that you'd encounter in an \"SQL-101\" course." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:12 +msgid "Prerequisites" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:14 +msgid "Before starting this tutorial:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:16 +msgid "Install the :ref:`tt CLI ` utility." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:18 +msgid "Create a tt environment in the current directory using the :ref:`tt init ` command." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:20 +msgid "Inside the ``instances.enabled`` directory of the created tt environment, create the ``sql_tutorial`` directory." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:22 +msgid "Inside ``instances.enabled/sql_tutorial``, create the ``instances.yml`` and ``config.yaml`` files:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:24 +msgid "``instances.yml`` specifies instances to run in the current environment:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:26 +msgid "instance001:\n" +"" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:30 +msgid "``config.yaml`` contains basic :ref:`configuration `:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:32 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:36 +msgid "Read more: :ref:`Starting instances using the tt utility `." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:41 +msgid "Create a table and execute SQL statements" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:44 +msgid "Start Tarantool" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:46 +msgid "After configuration, start a Tarantool instance from the tt environment directory using the following command:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:48 +msgid "$ tt start sql_tutorial" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:52 +msgid "After that, connect to the instance:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:54 +msgid "$ tt connect sql_tutorial:instance001" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:58 +msgid "This command opens an interactive Tarantool console. Now you can start working with the database." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:62 +msgid "Switch to the SQL language" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:64 +msgid "A feature of the client console program is that you can switch languages and specify the end-of-statement delimiter." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:67 +msgid "Run the following commands to set the :ref:`console input ` language to SQL and use semicolon as a delimiter:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:70 +msgid "sql_tutorial:instance001> \\set language sql\n" +"sql_tutorial:instance001> \\set delimiter ;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:77 +msgid "CREATE, INSERT, UPDATE, SELECT" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:79 +msgid "To get started, enter these SQL statements:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:81 +msgid "CREATE TABLE table1 (column1 INTEGER PRIMARY KEY, column2 VARCHAR(100));\n" +"INSERT INTO table1 VALUES (1, 'A');\n" +"UPDATE table1 SET column2 = 'B';\n" +"SELECT * FROM table1 WHERE column1 = 1;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:88 +msgid "The result of the ``SELECT`` statement looks like this:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:90 +msgid "sql_tutorial:instance001> SELECT * FROM table1 WHERE column1 = 1;\n" +"---\n" +"- metadata:\n" +" - name: COLUMN1\n" +" type: integer\n" +" - name: COLUMN2\n" +" type: string\n" +" rows:\n" +" - [1, 'B']\n" +"..." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:103 +msgid "The result includes:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:105 +msgid "metadata: the names and data types of each column" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:106 +msgid "result rows" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:108 +msgid "For conciseness, metadata is skipped in query results in this tutorial. Only the result rows are shown." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:112 +msgid "CREATE TABLE" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:114 +msgid "Here is ``CREATE TABLE`` with more details:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:116 +msgid "There are multiple columns, with different data types." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:117 +msgid "There is a ``PRIMARY KEY`` (unique and not-null) for two of the columns." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:119 +msgid "Create another table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:121 +msgid "CREATE TABLE table2 (column1 INTEGER,\n" +" column2 VARCHAR(100),\n" +" column3 SCALAR,\n" +" column4 DOUBLE,\n" +" PRIMARY KEY (column1, column2));" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:129 +msgid "The result is: ``row_count: 1``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:132 +msgid "INSERT" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:134 +msgid "Put four rows in the table (``table2``):" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:136 +msgid "The INTEGER and DOUBLE columns get numbers" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:137 +msgid "The VARCHAR and SCALAR columns get strings (the SCALAR strings are expressed as hexadecimals)" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:140 +msgid "INSERT INTO table2 VALUES (1, 'AB', X'4142', 5.5);\n" +"INSERT INTO table2 VALUES (1, 'CD', X'2020', 1E4);\n" +"INSERT INTO table2 VALUES (2, 'AB', X'2020', 12.34567);\n" +"INSERT INTO table2 VALUES (-1000, '', X'', 0.0);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:147 +msgid "Then try to put another row:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:149 +msgid "INSERT INTO table2 VALUES (1, 'AB', X'A5', -5.5);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:153 +msgid "This ``INSERT`` fails because of a primary-key violation: the row with the primary key ``1, 'AB'`` already exists." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:157 +msgid "The SEQSCAN keyword" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:159 +msgid "Sequential scan is the scan through all the table rows instead of using indexes. In Tarantool, ``SELECT`` SQL queries that perform sequential scans are prohibited by default. For example, this query leads to the error ``Scanning is not allowed for 'table2'``:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:163 +msgid "SELECT * FROM table2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:167 +msgid "To execute a scan query, put the ``SEQSCAN`` keyword before the table name:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:169 +msgid "SELECT * FROM SEQSCAN table2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:173 +msgid "Try to execute these queries that use indexed ``column1`` in filters:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:175 +msgid "SELECT * FROM table2 WHERE column1 = 1;\n" +"SELECT * FROM table2 WHERE column1 + 1 = 2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:180 +#: ../../doc/how-to/sql/sql_tutorial.rst:218 +#: ../../doc/how-to/sql/sql_tutorial.rst:276 +#: ../../doc/how-to/sql/sql_tutorial.rst:343 +#: ../../doc/how-to/sql/sql_tutorial.rst:388 +#: ../../doc/how-to/sql/sql_tutorial.rst:477 +#: ../../doc/how-to/sql/sql_tutorial.rst:555 +#: ../../doc/how-to/sql/sql_tutorial.rst:578 +#: ../../doc/how-to/sql/sql_tutorial.rst:610 +#: ../../doc/how-to/sql/sql_tutorial.rst:633 +#: ../../doc/how-to/sql/sql_tutorial.rst:702 +#: ../../doc/how-to/sql/sql_tutorial.rst:731 +#: ../../doc/how-to/sql/sql_tutorial.rst:796 +msgid "The result is:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:182 +msgid "The first query returns rows:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:184 +msgid "- [1, 'AB', 'AB', 10.5]\n" +"- [1, 'CD', ' ', 10005]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:189 +msgid "The second query fails with the error ``Scanning is not allowed for 'TABLE2'``. Although ``column1`` is indexed, the expression ``column1 + 1`` is not calculated from the index, which makes this ``SELECT`` a scan query." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:195 +msgid "To enable SQL scan queries without ``SEQSCAN`` for the current session, run this command:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:198 +msgid "SET SESSION \"sql_seq_scan\" = true;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:203 +msgid "Learn more about using ``SEQSCAN`` in the :ref:`SQL FROM clause description `." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:206 +msgid "SELECT with ORDER BY clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:208 +msgid "Retrieve the 4 rows in the table, in descending order by ``column2``, then (where the ``column2`` values are the same) in ascending order by ``column4``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:211 +msgid "``*`` is short for \"all columns\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:213 +msgid "SELECT * FROM SEQSCAN table2 ORDER BY column2 DESC, column4 ASC;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:220 +msgid "- - [1, 'CD', ' ', 10000]\n" +" - [1, 'AB', 'AB', 5.5]\n" +" - [2, 'AB', ' ', 12.34567]\n" +" - [-1000, '', '', 0]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:228 +msgid "SELECT with WHERE clauses" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:230 +msgid "Retrieve some of what you inserted:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:232 +msgid "The first statement uses the ``LIKE`` comparison operator which is asking for \"first character must be 'A', the next characters can be anything.\"" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:235 +msgid "The second statement uses logical operators and parentheses, so the ``AND`` expressions must be true, or the ``OR`` expression must be true. Notice the columns don't have to be indexed." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:238 +msgid "SELECT column1, column2, column1 * column4 FROM SEQSCAN table2 WHERE column2\n" +"LIKE 'A%';\n" +"SELECT column1, column2, column3, column4 FROM SEQSCAN table2\n" +" WHERE (column1 < 2 AND column4 < 10)\n" +" OR column3 = X'2020';" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:246 +msgid "The first result is:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:248 +msgid "- - [1, 'AB', 5.5]\n" +" - [2, 'AB', 24.69134]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:253 +msgid "The second result is:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:255 +msgid "- - [-1000, '', '', 0]\n" +" - [1, 'AB', 'AB', 5.5]\n" +" - [1, 'CD', ' ', 10000]\n" +" - [2, 'AB', ' ', 12.34567]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:263 +msgid "SELECT with GROUP BY and aggregate functions" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:265 +msgid "Retrieve with grouping." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:267 +msgid "The rows that have the same values for ``column2`` are grouped and are aggregated -- summed, counted, averaged -- for ``column4``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:270 +msgid "SELECT column2, SUM(column4), COUNT(column4), AVG(column4)\n" +"FROM SEQSCAN table2\n" +"GROUP BY column2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:278 +msgid "- - ['', 0, 1, 0]\n" +" - ['AB', 17.84567, 2, 8.922835]\n" +" - ['CD', 10000, 1, 10000]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:287 +msgid "Complications and complex SELECTs" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:290 +msgid "NULLs" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:292 +msgid "Insert rows that contain ``NULL`` values." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:294 +msgid "``NULL`` is not the same as Lua ``nil``; it commonly is used in SQL for unknown or not-applicable." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:297 +msgid "INSERT INTO table2 VALUES (1, NULL, X'4142', 5.5);\n" +"INSERT INTO table2 VALUES (0, '!!@', NULL, NULL);\n" +"INSERT INTO table2 VALUES (0, '!!!', X'00', NULL);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:303 +msgid "The results are:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:305 +msgid "The first ``INSERT`` fails because ``NULL`` is not permitted for a column that was defined with a ``PRIMARY KEY`` clause." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:309 +msgid "The other ``INSERT`` statements succeed." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:312 +msgid "Indexes" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:314 +msgid "Create a new index on ``column4``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:316 +msgid "There already is an index for the primary key. Indexes are useful for making queries faster. In this case, the index also acts as a constraint, because it prevents two rows from having the same values in ``column4``. However, it is not an error that ``column4`` has multiple occurrences of NULLs." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:321 +msgid "CREATE UNIQUE INDEX i ON table2 (column4);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:325 +msgid "The result is: ``rowcount: 1``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:328 +msgid "Create a subset table" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:330 +msgid "Create a table ``table3``, which contains a subset of the ``table2`` columns and a subset of the ``table2`` rows." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:333 +msgid "You can do this by combining ``INSERT`` with ``SELECT``. Then select everything from the result table." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:336 +msgid "CREATE TABLE table3 (column1 INTEGER, column2 VARCHAR(100), PRIMARY KEY\n" +"(column2));\n" +"INSERT INTO table3 SELECT column1, column2 FROM SEQSCAN table2 WHERE column1 <> 2;\n" +"SELECT * FROM SEQSCAN table3;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:345 +msgid "- - [-1000, '']\n" +" - [0, '!!!']\n" +" - [0, '!!@']\n" +" - [1, 'AB']\n" +" - [1, 'CD']" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:354 +msgid "SELECT with a subquery" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:356 +msgid "A subquery is a query within a query." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:358 +msgid "Find all the rows in ``table2`` whose ``(column1, column2)`` values are not present in ``table3``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:361 +msgid "SELECT * FROM SEQSCAN table2 WHERE (column1, column2) NOT IN (SELECT column1,\n" +"column2 FROM SEQSCAN table3);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:366 +msgid "The result is the single row that was excluded when inserting the rows with the ``INSERT ... SELECT`` statement:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:369 +msgid "- - [2, 'AB', ' ', 12.34567]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:374 +msgid "SELECT with a join" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:376 +msgid "A join is a combination of two tables. There is more than one way to do them in Tarantool, for example, \"Cartesian joins\" or \"left outer joins\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:379 +msgid "This example shows the most typical case, where column values from one table match column values from another table." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:382 +msgid "SELECT * FROM SEQSCAN table2, table3\n" +" WHERE table2.column1 = table3.column1 AND table2.column2 = table3.column2\n" +" ORDER BY table2.column4;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:390 +msgid "- - [0, '!!!', \"\\0\", null, 0, '!!!']\n" +" - [0, '!!@', null, null, 0, '!!@']\n" +" - [-1000, '', '', 0, -1000, '']\n" +" - [1, 'AB', 'AB', 5.5, 1, 'AB']\n" +" - [1, 'CD', ' ', 10000, 1, 'CD']" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:401 +msgid "Constraints and foreign keys" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:404 +msgid "CREATE TABLE with a CHECK clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:406 +msgid "Create a table that includes a constraint -- there must not be any rows containing ``13`` in ``column2``. After that, try to insert the following row:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:409 +msgid "CREATE TABLE table4 (column1 INTEGER PRIMARY KEY, column2 INTEGER, CHECK\n" +"(column2 <> 13));\n" +"INSERT INTO table4 VALUES (12, 13);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:415 +msgid "Result: the insert fails, as it should, with the message ``Check constraint 'ck_unnamed_TABLE4_1' failed for tuple``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:419 +msgid "CREATE TABLE with a FOREIGN KEY clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:421 +msgid "Create a table that includes a constraint: there must not be any rows containing values that do not appear in ``table2``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:424 +msgid "CREATE TABLE table5 (column1 INTEGER, column2 VARCHAR(100),\n" +" PRIMARY KEY (column1),\n" +" FOREIGN KEY (column1, column2) REFERENCES table2 (column1, column2));\n" +"INSERT INTO table5 VALUES (2,'AB');\n" +"INSERT INTO table5 VALUES (3,'AB');" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:432 +#: ../../doc/how-to/sql/sql_tutorial.rst:527 +msgid "Result:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:434 +msgid "The first ``INSERT`` statement succeeds because ``table3`` contains a row with ``[2, 'AB', ' ', 12.34567]``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:437 +msgid "The second ``INSERT`` statement, correctly, fails with the message ``Foreign key constraint ''fk_unnamed_TABLE5_1'' failed: foreign tuple was not found``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:441 +msgid "UPDATE" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:443 +msgid "Due to earlier ``INSERT`` statements, these values are in ``column4`` of ``table2``: ``{0, NULL, NULL, 5.5, 10000, 12.34567}``. Add ``5`` to each of these values except ``0``. Adding ``5`` to ``NULL`` results in NULL, as SQL arithmetic requires. Use ``SELECT`` to see what happened to ``column4``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:448 +msgid "UPDATE table2 SET column4 = column4 + 5 WHERE column4 <> 0;\n" +"SELECT column4 FROM SEQSCAN table2 ORDER BY column4;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:453 +msgid "The result is: ``{NULL, NULL, 0, 10.5, 17.34567, 10005}``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:456 +msgid "DELETE" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:458 +msgid "Due to earlier ``INSERT`` statements, there are 6 rows in ``table2``:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:460 +msgid "- - [-1000, '', '', 0]\n" +" - [0, '!!!', \"\\0\", null]\n" +" - [0, '!!@', null, null]\n" +" - [1, 'AB', 'AB', 10.5]\n" +" - [1, 'CD', ' ', 10005]\n" +" - [2, 'AB', ' ', 17.34567]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:469 +msgid "Try to delete the last and first of these rows:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:471 +msgid "DELETE FROM table2 WHERE column1 = 2;\n" +"DELETE FROM table2 WHERE column1 = -1000;\n" +"SELECT COUNT(column1) FROM SEQSCAN table2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:479 +msgid "The first ``DELETE`` statement causes an error because there's a foreign-key constraint." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:482 +msgid "The second ``DELETE`` statement succeeds." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:484 +msgid "The ``SELECT`` statement shows that there are 5 rows remaining." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:487 +msgid "ALTER TABLE with a FOREIGN KEY clause" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:489 +msgid "Create another constraint that there must not be any rows in ``table1`` containing values that do not appear in ``table5``. This was impossible during the ``table1`` creation because at that time ``table5`` did not exist. You can add constraints to existing tables with the ``ALTER TABLE`` statement." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:494 +msgid "ALTER TABLE table1 ADD CONSTRAINT c\n" +" FOREIGN KEY (column1) REFERENCES table5 (column1);\n" +"DELETE FROM table1;\n" +"ALTER TABLE table1 ADD CONSTRAINT c\n" +" FOREIGN KEY (column1) REFERENCES table5 (column1);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:502 +msgid "Result: the ``ALTER TABLE`` statement fails the first time because there is a row in ``table1``, and ``ADD CONSTRAINT`` requires that the table be empty. After the row is deleted, the ``ALTER TABLE`` statement completes successfully. Now there is a chain of references, from ``table1`` to ``table5`` and from ``table5`` to ``table2``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:509 +msgid "Triggers" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:511 +msgid "The idea of a trigger is: if a change (``INSERT`` or ``UPDATE`` or ``DELETE``) happens, then a further action -- perhaps another ``INSERT`` or ``UPDATE`` or ``DELETE`` -- will happen." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:515 +msgid "Set up the following trigger: when a update to ``table3`` is done, do an update to ``table2``. Specify this as ``FOR EACH ROW``, so that the trigger activates 5 times (since there are 5 rows in ``table3``)." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:519 +msgid "SELECT column4 FROM table2 WHERE column1 = 2;\n" +"CREATE TRIGGER tr AFTER UPDATE ON table3 FOR EACH ROW\n" +"BEGIN UPDATE table2 SET column4 = column4 + 1 WHERE column1 = 2; END;\n" +"UPDATE table3 SET column2 = column2;\n" +"SELECT column4 FROM table2 WHERE column1 = 2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:529 +msgid "The first ``SELECT`` shows that the original value of ``column4`` in ``table2`` where ``column1 = 2`` was: 17.34567." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:531 +msgid "The second ``SELECT`` returns:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:533 +msgid "- - [22.34567]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:540 +msgid "Operators and functions" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:543 +msgid "String operations" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:545 +msgid "You can manipulate string data (usually defined with ``CHAR`` or ``VARCHAR`` data types) in many ways. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:548 +msgid "concatenate strings with the ``||`` operator" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:549 +msgid "extract substrings with the ``SUBSTR`` function" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:551 +msgid "SELECT column2, column2 || column2, SUBSTR(column2, 2, 1) FROM SEQSCAN table2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:557 +msgid "- - ['!!!', '!!!!!!', '!']\n" +" - ['!!@', '!!@!!@', '!']\n" +" - ['AB', 'ABAB', 'B']\n" +" - ['CD', 'CDCD', 'D']\n" +" - ['AB', 'ABAB', 'B']" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:566 +msgid "Number operations" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:568 +msgid "You can also manipulate number data (usually defined with ``INTEGER`` or ``DOUBLE`` data types) in many ways. For example:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:571 +msgid "shift left with the ``<<`` operator" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:572 +msgid "get modulo with the ``%`` operator" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:574 +msgid "SELECT column1, column1 << 1, column1 << 2, column1 % 2 FROM SEQSCAN table2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:580 +msgid "- - [0, 0, 0, 0]\n" +" - [0, 0, 0, 0]\n" +" - [1, 2, 4, 1]\n" +" - [1, 2, 4, 1]\n" +" - [2, 4, 8, 0]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:589 +msgid "Ranges and limits" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:591 +msgid "Tarantool can handle:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:593 +msgid "integers anywhere in the 4-byte integer range" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:594 +msgid "approximate-numerics anywhere in the 8-byte IEEE floating point range" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:595 +msgid "any Unicode characters, with UTF-8 encoding and a choice of collations" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:597 +msgid "Insert such values in a new table and see what happens when you select them with arithmetic on a number column and ordering by a string column." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:600 +msgid "CREATE TABLE t6 (column1 INTEGER, column2 VARCHAR(10), column4 DOUBLE,\n" +"PRIMARY KEY (column1));\n" +"INSERT INTO t6 VALUES (-1234567890, 'АБВГД', 123456.123456);\n" +"INSERT INTO t6 VALUES (+1234567890, 'GD', 1e30);\n" +"INSERT INTO t6 VALUES (10, 'FADEW?', 0.000001);\n" +"INSERT INTO t6 VALUES (5, 'ABCDEFG', NULL);\n" +"SELECT column1 + 1, column2, column4 * 2 FROM SEQSCAN t6 ORDER BY column2;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:612 +msgid "- - [6, 'ABCDEFG', null]\n" +" - [11, 'FADEW?', 2e-06]\n" +" - [1234567891, 'GD', 2e+30]\n" +" - [-1234567889, 'АБВГД', 246912.246912]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:620 +msgid "Views" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:622 +msgid "A view (or *viewed table*), is virtual, meaning that its rows aren't physically in the database, their values are calculated from other tables." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:625 +msgid "Create a view ``v3`` based on ``table3`` and select from it:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:627 +msgid "CREATE VIEW v3 AS SELECT SUBSTR(column2,1,2), column4 FROM SEQSCAN t6\n" +"WHERE column4 >= 0;\n" +"SELECT * FROM v3;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:635 +#: ../../doc/how-to/sql/sql_tutorial.rst:658 +msgid "- - ['АБ', 123456.123456]\n" +" - ['FA', 1e-06]\n" +" - ['GD', 1e+30]" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:642 +msgid "Common table expressions" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:644 +msgid "By putting ``WITH`` + ``SELECT`` in front of a ``SELECT``, you can make a temporary view that lasts for the duration of the statement." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:647 +msgid "Create such a view and select from it:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:649 +msgid "WITH cte AS (\n" +" SELECT SUBSTR(column2,1,2), column4 FROM SEQSCAN t6\n" +" WHERE column4 >= 0)\n" +"SELECT * FROM cte;" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:656 +msgid "The result is the same as the ``CREATE VIEW`` result:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:665 +msgid "VALUES" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:667 +msgid "Tarantool can handle statements like ``SELECT 55;`` (select without ``FROM``) like some other popular DBMSs. But it also handles the more standard statement ``VALUES (expression [, expression ...]);``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:671 +msgid "SELECT 55 * 55, 'The rain in Spain';\n" +"VALUES (55 * 55, 'The rain in Spain');" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:676 +msgid "The result of both these statements is:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:678 +msgid "- - [3025, 'The rain in Spain']" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:683 +msgid "Metadata" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:685 +msgid "To find out the internal structure of the Tarantool database with SQL, select from the Tarantool system tables ``_space``, ``_index``, and ``_trigger``:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:688 +msgid "SELECT * FROM SEQSCAN \"_space\";\n" +"SELECT * FROM SEQSCAN \"_index\";\n" +"SELECT * FROM SEQSCAN \"_trigger\";" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:694 +msgid "Actually, these statements select from NoSQL \"system spaces\"." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:696 +msgid "Select from ``_space`` by a table name:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:698 +msgid "SELECT \"id\", \"name\", \"owner\", \"engine\" FROM \"_space\" WHERE \"name\"='TABLE3';" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:704 +msgid "- - [517, 'TABLE3', 1, 'memtx']" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:711 +msgid "Using SQL from Lua" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:713 +msgid "You can execute SQL statements directly from the Lua code without switching to the SQL input." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:716 +msgid "Change the settings so that the console accepts statements written in Lua instead of statements written in SQL:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:719 +msgid "sql_tutorial:instance001> \\set language lua" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:724 +msgid "box.execute()" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:725 +msgid "You can invoke SQL statements using the Lua function ``box.execute(string)``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:727 +msgid "sql_tutorial:instance001> box.execute([[SELECT * FROM SEQSCAN table3;]]);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:733 +msgid "- - [-1000, '']\n" +" - [0, '!!!']\n" +" - [0, '!!@']\n" +" - [1, 'AB']\n" +" - [1, 'CD']\n" +"..." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:743 +msgid "Create a million-row table" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:745 +msgid "To see how the SQL in Tarantool scales, create a bigger table." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:747 +msgid "The following Lua code generates one million rows with random data and inserts them into a table. Copy this code into the Tarantool console and wait a bit:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:751 +msgid "box.execute(\"CREATE TABLE tester (s1 INT PRIMARY KEY, s2 VARCHAR(10))\");\n" +"\n" +"function string_function()\n" +" local random_number\n" +" local random_string\n" +" random_string = \"\"\n" +" for x = 1, 10, 1 do\n" +" random_number = math.random(65, 90)\n" +" random_string = random_string .. string.char(random_number)\n" +" end\n" +" return random_string\n" +"end;\n" +"\n" +"function main_function()\n" +" local string_value, t, sql_statement\n" +" for i = 1, 1000000, 1 do\n" +" string_value = string_function()\n" +" sql_statement = \"INSERT INTO tester VALUES (\" .. i .. \",'\" .. string_value .. \"')\"\n" +" box.execute(sql_statement)\n" +" end\n" +"end;\n" +"start_time = os.clock();\n" +"main_function();\n" +"end_time = os.clock();\n" +"print('insert done in ' .. end_time - start_time .. ' seconds');" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:779 +msgid "The result is: you now have a table with a million rows, with a message saying ``insert done in 88.570578 seconds``." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:784 +msgid "Select from a million-row table" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:786 +msgid "Check how ``SELECT`` works on the million-row table:" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:788 +msgid "the first query goes by an index because ``s1`` is the primary key" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:789 +msgid "the second query does not go by an index" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:791 +msgid "box.execute([[SELECT * FROM tester WHERE s1 = 73446;]]);\n" +"box.execute([[SELECT * FROM SEQSCAN tester WHERE s2 LIKE 'QFML%';]]);" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:798 +msgid "the first statement completes instantaneously" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:799 +msgid "the second statement completed noticeably slower" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:802 +msgid "Cleanup and exit" +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:804 +msgid "To cleanup all the objects created in this tutorial, switch to the SQL input language again. Then run the ``DROP`` statements for all created tables, views, and triggers." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:808 +msgid "These statements must be entered separately." +msgstr "" + +#: ../../doc/how-to/sql/sql_tutorial.rst:810 +msgid "sql_tutorial:instance001> \\set language sql\n" +"sql_tutorial:instance001> DROP TABLE tester;\n" +"sql_tutorial:instance001> DROP TABLE table1;\n" +"sql_tutorial:instance001> DROP VIEW v3;\n" +"sql_tutorial:instance001> DROP TRIGGER tr;\n" +"sql_tutorial:instance001> DROP TABLE table5;\n" +"sql_tutorial:instance001> DROP TABLE table4;\n" +"sql_tutorial:instance001> DROP TABLE table3;\n" +"sql_tutorial:instance001> DROP TABLE table2;\n" +"sql_tutorial:instance001> DROP TABLE t6;\n" +"sql_tutorial:instance001> \\set language lua\n" +"sql_tutorial:instance001> os.exit();" +msgstr "" diff --git a/locale/en/index.pot b/locale/en/index.pot new file mode 100644 index 0000000000..3685ae8a5e --- /dev/null +++ b/locale/en/index.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/index.rst:50 +msgid "CRUD operations" +msgstr "" + +#: ../../doc/index.rst:10 +msgid "Tarantool -- Documentation" +msgstr "" diff --git a/locale/en/overview.pot b/locale/en/overview.pot new file mode 100644 index 0000000000..729f52b8a9 --- /dev/null +++ b/locale/en/overview.pot @@ -0,0 +1,185 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/overview.rst:2 +msgid "Overview" +msgstr "" + +#: ../../doc/overview.rst:5 +msgid "What is Tarantool?" +msgstr "" + +#: ../../doc/overview.rst:7 +msgid "Tarantool combines an in-memory DBMS and a Lua server in a single platform providing ACID-compliant storage. It comes in two :ref:`editions `: Community and Enterprise. The :ref:`use cases ` for Tarantool vary from ultra-fast cache to product data marts and smart queue services." +msgstr "" + +#: ../../doc/overview.rst:13 +msgid "Here are some of Tarantool's key characteristics:" +msgstr "" + +#: ../../doc/overview.rst:15 +msgid "**Easy handling of OLTP workloads**: processes hundreds of thousands RPS" +msgstr "" + +#: ../../doc/overview.rst:17 +msgid "**Data integrity**: :ref:`write-ahead log (WAL) ` and :ref:`data snapshots `" +msgstr "" + +#: ../../doc/overview.rst:20 +msgid "**Cooperative multitasking**: transactions are performed in :ref:`lightweight coroutines ` with no interthread locking" +msgstr "" + +#: ../../doc/overview.rst:23 +msgid "**Advanced indexing**: :ref:`composite indexes `, :ref:`locale support `, indexing by :ref:`nested fields and arrays `" +msgstr "" + +#: ../../doc/overview.rst:27 +msgid "**Compute close to data**: :ref:`Lua server ` and Just-In-Time compiler on board" +msgstr "" + +#: ../../doc/overview.rst:30 +msgid "**Durable distributed storage**: multiple failover modes and :ref:`RAFT-based synchronous replication ` available" +msgstr "" + +#: ../../doc/overview.rst:34 +msgid "Tarantool allows executing code alongside data, which helps increase the speed of operations. Developers can :ref:`implement any business logic with Lua `, and a single Tarantool instance can also receive :ref:`SQL requests `." +msgstr "" + +#: ../../doc/overview.rst:38 +msgid "Tarantool has a variety of compatible `modules `__ (Lua rocks). You can pick the ones that you need and install them manually." +msgstr "" + +#: ../../doc/overview.rst:41 +msgid "Tarantool runs on Linux (x86_64, aarch64), Mac OS X (x86_64, M1), and FreeBSD (x86_64)." +msgstr "" + +#: ../../doc/overview.rst:43 +msgid "You can use Tarantool with a programming language you're familiar with. For this purpose, a number of :ref:`connectors ` are provided." +msgstr "" + +#: ../../doc/overview.rst:49 +msgid "Editions" +msgstr "" + +#: ../../doc/overview.rst:51 +msgid "Tarantool comes in two editions: the open-source **Community Edition (CE)** and the commercial **Enterprise Edition (EE)**." +msgstr "" + +#: ../../doc/overview.rst:54 +msgid "**Tarantool Community Edition** lets you develop applications and speed up a system in operation. It features :ref:`synchronous replication `, affords easy :ref:`scalability `, and includes tools to develop efficient :ref:`applications `. The `Tarantool community `__ helps with any practical questions regarding the Community Edition." +msgstr "" + +#: ../../doc/overview.rst:60 +msgid "**Tarantool Enterprise Edition** `provides advanced tools `__ for administration, deployment, and security management, along with premium support services. This edition includes all the Community Edition features and is more predictable in terms of solution cost and maintenance. The Enterprise Edition is shipped as an SDK and includes a number of closed-source modules. See the :ref:`Tarantool Enterprise Edition ` documentation." +msgstr "" + +#: ../../doc/overview.rst:70 +msgid "Use cases" +msgstr "" + +#: ../../doc/overview.rst:73 +msgid "Fast first-class storage" +msgstr "" + +#: ../../doc/overview.rst:75 +msgid "Primary storage" +msgstr "" + +#: ../../doc/overview.rst:77 +msgid "No secondary storage required" +msgstr "" + +#: ../../doc/overview.rst:79 +msgid "Tolerance to high write loads" +msgstr "" + +#: ../../doc/overview.rst:80 +msgid "Support of relational approaches" +msgstr "" + +#: ../../doc/overview.rst:81 +msgid "Composite secondary indexes" +msgstr "" + +#: ../../doc/overview.rst:83 +msgid "Data access, data slices" +msgstr "" + +#: ../../doc/overview.rst:85 +msgid "Predictable request latency" +msgstr "" + +#: ../../doc/overview.rst:88 +msgid "Advanced cache" +msgstr "" + +#: ../../doc/overview.rst:90 +msgid "Write-behind caching" +msgstr "" + +#: ../../doc/overview.rst:91 +msgid "Secondary index support" +msgstr "" + +#: ../../doc/overview.rst:92 +msgid "Complex invalidation algorithm support" +msgstr "" + +#: ../../doc/overview.rst:95 +msgid "Smart queue" +msgstr "" + +#: ../../doc/overview.rst:97 +msgid "Support of various identification techniques" +msgstr "" + +#: ../../doc/overview.rst:98 +msgid "Advanced task lifecycle management" +msgstr "" + +#: ../../doc/overview.rst:100 +msgid "Task scheduling" +msgstr "" + +#: ../../doc/overview.rst:101 +msgid "Archiving of completed tasks" +msgstr "" + +#: ../../doc/overview.rst:104 +msgid "Data-centric applications" +msgstr "" + +#: ../../doc/overview.rst:106 +msgid "Arbitrary data flows from many sources" +msgstr "" + +#: ../../doc/overview.rst:107 +msgid "Incoming data processing" +msgstr "" + +#: ../../doc/overview.rst:108 +msgid "Storage" +msgstr "" + +#: ../../doc/overview.rst:109 +msgid "Background cycle processing" +msgstr "" + +#: ../../doc/overview.rst:111 +msgid "Scheduling support" +msgstr "" diff --git a/locale/en/overview_index.pot b/locale/en/overview_index.pot new file mode 100644 index 0000000000..b0b276d98d --- /dev/null +++ b/locale/en/overview_index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/overview_index.rst:6 +msgid "Overview" +msgstr "" diff --git a/locale/en/pdf_toc.pot b/locale/en/pdf_toc.pot new file mode 100644 index 0000000000..5191a17e2c --- /dev/null +++ b/locale/en/pdf_toc.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/pdf_toc.rst:9 +msgid "CRUD operations" +msgstr "" diff --git a/locale/en/platform/app/c_tutorial.pot b/locale/en/platform/app/c_tutorial.pot new file mode 100644 index 0000000000..735f2ea9db --- /dev/null +++ b/locale/en/platform/app/c_tutorial.pot @@ -0,0 +1,639 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/c_tutorial.rst:2 +msgid "C tutorial" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:7 +msgid "C stored procedures" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:9 +msgid "Tarantool can call C code with :ref:`modules `, or with :ref:`ffi `, or with C stored procedures. This tutorial only is about the third option, C stored procedures. In fact the routines are always \"C functions\" but the phrase \"stored procedure\" is commonly used for historical reasons." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:16 +msgid "In this tutorial, which can be followed by anyone with a Tarantool development package and a C compiler, there are five tasks:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:19 +msgid ":ref:`easy.c ` -- prints \"hello world\";" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:20 +msgid ":ref:`harder.c ` -- decodes a passed parameter value;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:21 +msgid ":ref:`hardest.c ` -- uses the C API to do a DBMS insert;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:22 +msgid ":ref:`read.c ` -- uses the C API to do a DBMS select;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:23 +msgid ":ref:`write.c ` -- uses the C API to do a DBMS replace." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:25 +msgid "After following the instructions, and seeing that the results are what is described here, users should feel confident about writing their own stored procedures." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:30 +msgid "Preparation" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:32 +msgid "Check that these items exist on the computer:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:34 +msgid "Tarantool 2.1 or later" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:35 +msgid "A gcc compiler, any modern version should work" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:36 +msgid "``module.h`` and files #included in it" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:37 +msgid "``msgpuck.h``" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:38 +msgid "``libmsgpuck.a`` (only for some recent msgpuck versions)" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:40 +msgid "The ``module.h`` file will exist if Tarantool was installed from source. Otherwise Tarantool's \"developer\" package must be installed. For example on Ubuntu say:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:44 +msgid "$ sudo apt-get install tarantool-dev" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:48 +msgid "or on Fedora say:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:50 +msgid "$ dnf -y install tarantool-devel" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:54 +msgid "The ``msgpuck.h`` file will exist if Tarantool was installed from source. Otherwise the \"msgpuck\" package must be installed from `https://github.com/tarantool/msgpuck `_." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:58 +msgid "Both ``module.h`` and ``msgpuck.h`` must be on the include path for the C compiler to see them. For example, if ``module.h`` address is ``/usr/local/include/tarantool/module.h``, and ``msgpuck.h`` address is ``/usr/local/include/msgpuck/msgpuck.h``, and they are not currently on the include path, say:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:64 +msgid "$ export CPATH=/usr/local/include/tarantool:/usr/local/include/msgpuck" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:68 +msgid "The ``libmsgpuck.a`` static library is necessary with msgpuck versions produced after February 2017. If and only if you encounter linking problems when using the gcc statements in the examples for this tutorial, you should put ``libmsgpuck.a`` on the path (``libmsgpuck.a`` is produced from both msgpuck and Tarantool source downloads so it should be easy to find). For example, instead of \":code:`gcc -shared -o harder.so -fPIC harder.c`\" for the second example below, you will need to say \":code:`gcc -shared -o harder.so -fPIC harder.c libmsgpuck.a`\"." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:77 +msgid "Requests will be done using Tarantool as a :ref:`client `. Start Tarantool, and enter these requests." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:81 +msgid "box.cfg{listen=3306}\n" +"box.schema.space.create('capi_test')\n" +"box.space.capi_test:create_index('primary')\n" +"net_box = require('net.box')\n" +"capi_connection = net_box:new(3306)" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:89 +msgid "In plainer language: create a space named ``capi_test``, and make a connection to self named ``capi_connection``." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:92 +msgid "Leave the client running. It will be necessary to enter more requests later." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:97 +msgid "easy.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:99 +msgid "Start another shell. Change directory (``cd``) so that it is the same as the directory that the client is running on." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:102 +msgid "Create a file. Name it ``easy.c``. Put these six lines in it." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:104 +msgid "#include \"module.h\"\n" +"int easy(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" printf(\"hello world\\n\");\n" +" return 0;\n" +"}\n" +"int easy2(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" printf(\"hello world -- easy2\\n\");\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:119 +msgid "Compile the program, producing a library file named ``easy.so``:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:121 +msgid "$ gcc -shared -o easy.so -fPIC easy.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:125 +#: ../../doc/how-to/app/c_tutorial.rst:214 +#: ../../doc/how-to/app/c_tutorial.rst:302 +#: ../../doc/how-to/app/c_tutorial.rst:406 +#: ../../doc/how-to/app/c_tutorial.rst:488 +msgid "Now go back to the client and execute these requests:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:127 +msgid "box.schema.func.create('easy', {language = 'C'})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'easy')\n" +"capi_connection:call('easy')" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:133 +msgid "If these requests appear unfamiliar, re-read the descriptions of :doc:`/reference/reference_lua/box_schema/func_create`, :doc:`/reference/reference_lua/box_schema/user_grant` and :ref:`conn:call() `." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:139 +msgid "The function that matters is ``capi_connection:call('easy')``." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:141 +msgid "Its first job is to find the 'easy' function, which should be easy because by default Tarantool looks on the current directory for a file named ``easy.so``." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:145 +msgid "Its second job is to call the 'easy' function. Since the ``easy()`` function in ``easy.c`` begins with ``printf(\"hello world\\n\")``, the words \"hello world\" will appear on the screen." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:149 +msgid "Its third job is to check that the call was successful. Since the ``easy()`` function in ``easy.c`` ends with :code:`return 0`, there is no error message to display and the request is over." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:153 +#: ../../doc/how-to/app/c_tutorial.rst:331 +msgid "The result should look like this:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:155 +msgid "tarantool> capi_connection:call('easy')\n" +"hello world\n" +"---\n" +"- []\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:163 +msgid "Now let's call the other function in easy.c -- ``easy2()``. This is almost the same as the ``easy()`` function, but there's a detail: when the file name is not the same as the function name, then we have to specify :samp:`{file-name}.{function-name}`." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:169 +msgid "box.schema.func.create('easy.easy2', {language = 'C'})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'easy.easy2')\n" +"capi_connection:call('easy.easy2')" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:175 +msgid "... and this time the result will be \"hello world -- easy2\"." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:177 +msgid "Conclusion: calling a C function is easy." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:182 +msgid "harder.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:184 +msgid "Go back to the shell where the ``easy.c`` program was created." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:186 +msgid "Create a file. Name it ``harder.c``. Put these 17 lines in it:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:188 +msgid "#include \"module.h\"\n" +"#include \"msgpuck.h\"\n" +"int harder(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" uint32_t arg_count = mp_decode_array(&args);\n" +" printf(\"arg_count = %d\\n\", arg_count);\n" +" uint32_t field_count = mp_decode_array(&args);\n" +" printf(\"field_count = %d\\n\", field_count);\n" +" uint32_t val;\n" +" int i;\n" +" for (i = 0; i < field_count; ++i)\n" +" {\n" +" val = mp_decode_uint(&args);\n" +" printf(\"val=%d.\\n\", val);\n" +" }\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:208 +msgid "Compile the program, producing a library file named ``harder.so``:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:210 +msgid "$ gcc -shared -o harder.so -fPIC harder.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:216 +msgid "box.schema.func.create('harder', {language = 'C'})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'harder')\n" +"passable_table = {}\n" +"table.insert(passable_table, 1)\n" +"table.insert(passable_table, 2)\n" +"table.insert(passable_table, 3)\n" +"capi_connection:call('harder', {passable_table})" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:226 +msgid "This time the call is passing a Lua table (``passable_table``) to the ``harder()`` function. The ``harder()`` function will see it, it's in the :code:`char *args` parameter." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:230 +msgid "At this point the ``harder()`` function will start using functions defined in `msgpuck.h `_. The routines that begin with \"mp\" are msgpuck functions that handle data formatted according to the `MsgPack `_ specification. Passes and returns are always done with this format so one must become acquainted with msgpuck to become proficient with the C API." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:238 +msgid "For now, though, it's enough to know that ``mp_decode_array()`` returns the number of elements in an array, and ``mp_decode_uint`` returns an unsigned integer, from :code:`args`. And there's a side effect: when the decoding finishes, :code:`args` has changed and is now pointing to the next element." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:244 +msgid "Therefore the first displayed line will be \"arg_count = 1\" because there was only one item passed: ``passable_table``. |br| The second displayed line will be \"field_count = 3\" because there are three items in the table. |br| The next three lines will be \"1\" and \"2\" and \"3\" because those are the values in the items in the table." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:251 +msgid "And now the screen looks like this:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:253 +msgid "tarantool> capi_connection:call('harder', passable_table)\n" +"arg_count = 1\n" +"field_count = 3\n" +"val=1.\n" +"val=2.\n" +"val=3.\n" +"---\n" +"- []\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:265 +msgid "Conclusion: decoding parameter values passed to a C function is not easy at first, but there are routines to do the job, and they're documented, and there aren't very many of them." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:273 +msgid "hardest.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:275 +msgid "Go back to the shell where the ``easy.c`` and the ``harder.c`` programs were created." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:278 +msgid "Create a file. Name it ``hardest.c``. Put these 13 lines in it:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:280 +msgid "#include \"module.h\"\n" +"#include \"msgpuck.h\"\n" +"int hardest(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" uint32_t space_id = box_space_id_by_name(\"capi_test\", strlen(\"capi_test\"));\n" +" char tuple[1024]; /* Must be big enough for mp_encode results */\n" +" char *tuple_pointer = tuple;\n" +" tuple_pointer = mp_encode_array(tuple_pointer, 2);\n" +" tuple_pointer = mp_encode_uint(tuple_pointer, 10000);\n" +" tuple_pointer = mp_encode_str(tuple_pointer, \"String 2\", 8);\n" +" int n = box_insert(space_id, tuple, tuple_pointer, NULL);\n" +" return n;\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:296 +msgid "Compile the program, producing a library file named ``hardest.so``:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:298 +msgid "$ gcc -shared -o hardest.so -fPIC hardest.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:304 +msgid "box.schema.func.create('hardest', {language = \"C\"})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'hardest')\n" +"box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')\n" +"capi_connection:call('hardest')" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:311 +msgid "This time the C function is doing three things:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:313 +msgid "finding the numeric identifier of the ``capi_test`` space by calling ``box_space_id_by_name()``;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:315 +msgid "formatting a tuple using more ``msgpuck.h`` functions;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:316 +msgid "inserting a tuple using ``box_insert()``." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:320 +msgid "``char tuple[1024];`` is used here as just a quick way of saying \"allocate more than enough bytes\". For serious programs the developer must be careful to allow enough space for all the bytes that the ``mp_encode`` routines will use up." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:325 +msgid "Now, still on the client, execute this request:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:327 +msgid "box.space.capi_test:select()" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:333 +msgid "tarantool> box.space.capi_test:select()\n" +"---\n" +"- - [10000, 'String 2']\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:340 +msgid "This proves that the ``hardest()`` function succeeded, but where did :ref:`box_space_id_by_name() ` and :ref:`box_insert() ` come from? Answer: the :ref:`C API `." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:348 +msgid "read.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:350 +msgid "Go back to the shell where the ``easy.c`` and the ``harder.c`` and the ``hardest.c`` programs were created." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:353 +msgid "Create a file. Name it ``read.c``. Put these 43 lines in it:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:355 +msgid "#include \"module.h\"\n" +"#include \n" +"int read(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" char tuple_buf[1024]; /* where the raw MsgPack tuple will be stored */\n" +" uint32_t space_id = box_space_id_by_name(\"capi_test\", strlen(\"capi_test\"));\n" +" uint32_t index_id = 0; /* The number of the space's first index */\n" +" uint32_t key = 10000; /* The key value that box_insert() used */\n" +" mp_encode_array(tuple_buf, 0); /* clear */\n" +" box_tuple_format_t *fmt = box_tuple_format_default();\n" +" box_tuple_t *tuple = NULL;\n" +" char key_buf[16]; /* Pass key_buf = encoded key = 1000 */\n" +" char *key_end = key_buf;\n" +" key_end = mp_encode_array(key_end, 1);\n" +" key_end = mp_encode_uint(key_end, key);\n" +" assert(key_end <= key_buf + sizeof(key_buf));\n" +" /* Get the tuple. There's no box_select() but there's this. */\n" +" int r = box_index_get(space_id, index_id, key_buf, key_end, &tuple);\n" +" assert(r == 0);\n" +" assert(tuple != NULL);\n" +" /* Get each field of the tuple + display what you get. */\n" +" int field_no; /* The first field number is 0. */\n" +" for (field_no = 0; field_no < 2; ++field_no)\n" +" {\n" +" const char *field = box_tuple_field(tuple, field_no);\n" +" assert(field != NULL);\n" +" assert(mp_typeof(*field) == MP_STR || mp_typeof(*field) == MP_UINT);\n" +" if (mp_typeof(*field) == MP_UINT)\n" +" {\n" +" uint32_t uint_value = mp_decode_uint(&field);\n" +" printf(\"uint value=%u.\\n\", uint_value);\n" +" }\n" +" else /* if (mp_typeof(*field) == MP_STR) */\n" +" {\n" +" const char *str_value;\n" +" uint32_t str_value_length;\n" +" str_value = mp_decode_str(&field, &str_value_length);\n" +" printf(\"string value=%.*s.\\n\", str_value_length, str_value);\n" +" }\n" +" }\n" +" return 0;\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:400 +msgid "Compile the program, producing a library file named ``read.so``:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:402 +msgid "$ gcc -shared -o read.so -fPIC read.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:408 +msgid "box.schema.func.create('read', {language = \"C\"})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'read')\n" +"box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')\n" +"capi_connection:call('read')" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:415 +msgid "This time the C function is doing four things:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:417 +#: ../../doc/how-to/app/c_tutorial.rst:499 +msgid "once again, finding the numeric identifier of the ``capi_test`` space by calling ``box_space_id_by_name()``;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:419 +msgid "formatting a search key = 10000 using more ``msgpuck.h`` functions;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:420 +msgid "getting a tuple using ``box_index_get()``;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:421 +msgid "going through the tuple's fields with ``box_tuple_get()`` and then decoding each field depending on its type. In this case, since what we are getting is the tuple that we inserted with ``hardest.c``, we know in advance that the type is either MP_UINT or MP_STR; however, it's very common to have a case statement here with one option for each possible type." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:428 +msgid "The result of ``capi_connection:call('read')`` should look like this:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:430 +msgid "tarantool> capi_connection:call('read')\n" +"uint value=10000.\n" +"string value=String 2.\n" +"---\n" +"- []\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:439 +msgid "This proves that the ``read()`` function succeeded. Once again the important functions that start with `box` -- :ref:`box_index_get() ` and :ref:`box_tuple_field() ` -- came from the :ref:`C API `." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:448 +msgid "write.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:450 +msgid "Go back to the shell where the programs ``easy.c``, ``harder.c``, ``hardest.c`` and ``read.c`` were created." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:453 +msgid "Create a file. Name it ``write.c``. Put these 24 lines in it:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:455 +msgid "#include \"module.h\"\n" +"#include \n" +"int write(box_function_ctx_t *ctx, const char *args, const char *args_end)\n" +"{\n" +" static const char *space = \"capi_test\";\n" +" char tuple_buf[1024]; /* Must be big enough for mp_encode results */\n" +" uint32_t space_id = box_space_id_by_name(space, strlen(space));\n" +" if (space_id == BOX_ID_NIL) {\n" +" return box_error_set(__FILE__, __LINE__, ER_PROC_C,\n" +" \"Can't find space %s\", \"capi_test\");\n" +" }\n" +" char *tuple_end = tuple_buf;\n" +" tuple_end = mp_encode_array(tuple_end, 2);\n" +" tuple_end = mp_encode_uint(tuple_end, 1);\n" +" tuple_end = mp_encode_uint(tuple_end, 22);\n" +" box_txn_begin();\n" +" if (box_replace(space_id, tuple_buf, tuple_end, NULL) != 0)\n" +" return -1;\n" +" box_txn_commit();\n" +" fiber_sleep(0.001);\n" +" struct tuple *tuple = box_tuple_new(box_tuple_format_default(),\n" +" tuple_buf, tuple_end);\n" +" return box_return_tuple(ctx, tuple);\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:482 +msgid "Compile the program, producing a library file named ``write.so``:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:484 +msgid "$ gcc -shared -o write.so -fPIC write.c" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:490 +msgid "box.schema.func.create('write', {language = \"C\"})\n" +"box.schema.user.grant('guest', 'execute', 'function', 'write')\n" +"box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')\n" +"capi_connection:call('write')" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:497 +msgid "This time the C function is doing six things:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:501 +msgid "making a new tuple;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:502 +msgid "starting a transaction;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:503 +msgid "replacing a tuple in ``box.space.capi_test``" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:504 +msgid "ending a transaction;" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:505 +msgid "the final line is a replacement for the loop in ``read.c`` -- instead of getting each field and printing it, use the ``box_return_tuple(...)`` function to return the entire tuple to the caller and let the caller display it." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:510 +msgid "The result of ``capi_connection:call('write')`` should look like this:" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:512 +msgid "tarantool> capi_connection:call('write')\n" +"---\n" +"- [[1, 22]]\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:519 +msgid "This proves that the ``write()`` function succeeded. Once again the important functions that start with `box` -- :ref:`box_txn_begin() `, :ref:`box_txn_commit() ` and :ref:`box_return_tuple() ` -- came from the :ref:`C API `." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:526 +msgid "Conclusion: the long description of the whole C API is there for a good reason. All of the functions in it can be called from C functions which are called from Lua. So C \"stored procedures\" have full access to the database." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:533 +msgid "Cleaning up" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:535 +msgid "Get rid of each of the function tuples with :doc:`/reference/reference_lua/box_schema/func_drop`." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:537 +msgid "Get rid of the ``capi_test`` space with :ref:`box.schema.capi_test:drop() `." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:539 +msgid "Remove the ``.c`` and ``.so`` files that were created for this tutorial." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:543 +msgid "An example in the test suite" +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:545 +msgid "Download the source code of Tarantool. Look in a subdirectory :code:`test/box`. Notice that there is a file named :code:`tuple_bench.test.lua` and another file named :code:`tuple_bench.c`. Examine the Lua file and observe that it is calling a function in the C file, using the same techniques that this tutorial has shown." +msgstr "" + +#: ../../doc/how-to/app/c_tutorial.rst:552 +msgid "Conclusion: parts of the standard test suite use C stored procedures, and they must work, because releases don't happen if Tarantool doesn't pass the tests." +msgstr "" diff --git a/locale/en/platform/app/cookbook.pot b/locale/en/platform/app/cookbook.pot new file mode 100644 index 0000000000..1a65d3afeb --- /dev/null +++ b/locale/en/platform/app/cookbook.pot @@ -0,0 +1,881 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/cookbook.rst:5 +msgid "Lua cookbook recipes" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:7 +msgid "Here are contributions of Lua programs for some frequent or tricky situations." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:9 +msgid "You can execute any of these programs by copying the code into a ``.lua`` file, and then entering :samp:`chmod +x ./{program-name}.lua` and :samp:`./{program-name}.lua` on the terminal." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:13 +msgid "The first line is a \"hashbang\":" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:15 +msgid "#!/usr/bin/env tarantool" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:19 +msgid "This runs Tarantool Lua application server, which should be on the execution path." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:22 +msgid "This section contains the following recipes:" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:27 +msgid "Use freely." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:29 +msgid "See more recipes on `Tarantool GitHub `__." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:35 +msgid "hello_world.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:37 +msgid "The standard example of a simple program." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:39 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"print('Hello, World!')" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:49 +msgid "console_start.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:51 +msgid "Use :doc:`box.once() ` to initialize a database (creating spaces) if this is the first time the server has been run. Then use :ref:`console.start() ` to start interactive mode." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:55 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"-- Configure database\n" +"box.cfg {\n" +" listen = 3313\n" +"}\n" +"\n" +"box.once(\"bootstrap\", function()\n" +" box.schema.space.create('tweedledum')\n" +" box.space.tweedledum:create_index('primary',\n" +" { type = 'TREE', parts = {1, 'unsigned'}})\n" +"end)\n" +"\n" +"require('console').start()" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:76 +msgid "fio_read.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:78 +msgid "Use the :ref:`fio module ` to open, read, and close a file." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:80 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local fio = require('fio')\n" +"local errno = require('errno')\n" +"local f = fio.open('/tmp/xxxx.txt', {'O_RDONLY' })\n" +"if not f then\n" +" error(\"Failed to open file: \"..errno.strerror())\n" +"end\n" +"local data = f:read(4096)\n" +"f:close()\n" +"print(data)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:98 +msgid "fio_write.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:100 +msgid "Use the :ref:`fio module ` to open, write, and close a file." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:102 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local fio = require('fio')\n" +"local errno = require('errno')\n" +"local f = fio.open('/tmp/xxxx.txt', {'O_CREAT', 'O_WRONLY', 'O_APPEND'},\n" +" tonumber('0666', 8))\n" +"if not f then\n" +" error(\"Failed to open file: \"..errno.strerror())\n" +"end\n" +"f:write(\"Hello\\n\");\n" +"f:close()" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:120 +msgid "ffi_printf.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:122 +msgid "Use the `LuaJIT ffi library `_ to call a C built-in function: printf(). (For help understanding ffi, see the `FFI tutorial `_.)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:125 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local ffi = require('ffi')\n" +"ffi.cdef[[\n" +" int printf(const char *format, ...);\n" +"]]\n" +"\n" +"ffi.C.printf(\"Hello, %s\\n\", os.getenv(\"USER\"));" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:140 +msgid "ffi_gettimeofday.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:142 +msgid "Use the `LuaJIT ffi library `_ to call a C function: gettimeofday(). This delivers time with millisecond precision, unlike the time function in Tarantool's :ref:`clock module `." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:146 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local ffi = require('ffi')\n" +"ffi.cdef[[\n" +" typedef long time_t;\n" +" typedef struct timeval {\n" +" time_t tv_sec;\n" +" time_t tv_usec;\n" +"} timeval;\n" +" int gettimeofday(struct timeval *t, void *tzp);\n" +"]]\n" +"\n" +"local timeval_buf = ffi.new(\"timeval\")\n" +"local now = function()\n" +" ffi.C.gettimeofday(timeval_buf, nil)\n" +" return tonumber(timeval_buf.tv_sec * 1000 + (timeval_buf.tv_usec / 1000))\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:170 +msgid "ffi_zlib.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:172 +msgid "Use the `LuaJIT ffi library `_ to call a C library function. (For help understanding ffi, see the `FFI tutorial `_.)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:175 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local ffi = require(\"ffi\")\n" +"ffi.cdef[[\n" +" unsigned long compressBound(unsigned long sourceLen);\n" +" int compress2(uint8_t *dest, unsigned long *destLen,\n" +" const uint8_t *source, unsigned long sourceLen, int level);\n" +" int uncompress(uint8_t *dest, unsigned long *destLen,\n" +" const uint8_t *source, unsigned long sourceLen);\n" +"]]\n" +"local zlib = ffi.load(ffi.os == \"Windows\" and \"zlib1\" or \"z\")\n" +"\n" +"-- Lua wrapper for compress2()\n" +"local function compress(txt)\n" +" local n = zlib.compressBound(#txt)\n" +" local buf = ffi.new(\"uint8_t[?]\", n)\n" +" local buflen = ffi.new(\"unsigned long[1]\", n)\n" +" local res = zlib.compress2(buf, buflen, txt, #txt, 9)\n" +" assert(res == 0)\n" +" return ffi.string(buf, buflen[0])\n" +"end\n" +"\n" +"-- Lua wrapper for uncompress\n" +"local function uncompress(comp, n)\n" +" local buf = ffi.new(\"uint8_t[?]\", n)\n" +" local buflen = ffi.new(\"unsigned long[1]\", n)\n" +" local res = zlib.uncompress(buf, buflen, comp, #comp)\n" +" assert(res == 0)\n" +" return ffi.string(buf, buflen[0])\n" +"end\n" +"\n" +"-- Simple test code.\n" +"local txt = string.rep(\"abcd\", 1000)\n" +"print(\"Uncompressed size: \", #txt)\n" +"local c = compress(txt)\n" +"print(\"Compressed size: \", #c)\n" +"local txt2 = uncompress(c, #txt)\n" +"assert(txt2 == txt)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:220 +msgid "ffi_meta.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:222 +msgid "Use the `LuaJIT ffi library `_ to access a C object via a metamethod (a method which is defined with a metatable)." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:226 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local ffi = require(\"ffi\")\n" +"ffi.cdef[[\n" +"typedef struct { double x, y; } point_t;\n" +"]]\n" +"\n" +"local point\n" +"local mt = {\n" +" __add = function(a, b) return point(a.x+b.x, a.y+b.y) end,\n" +" __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end,\n" +" __index = {\n" +" area = function(a) return a.x*a.x + a.y*a.y end,\n" +" },\n" +"}\n" +"point = ffi.metatype(\"point_t\", mt)\n" +"\n" +"local a = point(3, 4)\n" +"print(a.x, a.y) --> 3 4\n" +"print(#a) --> 5\n" +"print(a:area()) --> 25\n" +"local b = a + point(0.5, 8)\n" +"print(#b) --> 12.5" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:256 +msgid "ffi_varbinary_insert.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:258 +msgid "Use the `LuaJIT ffi library `_ to insert a tuple which has a VARBINARY field." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:261 +msgid "Note that it is allowed only inside a memtx transaction: when ``box_insert()`` does not yield." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:264 +msgid "Lua does not have direct support for VARBINARY, so using C is one way to put in data which in MessagePack is stored as bin (MP_BIN). If the tuple is retrieved later, field \"b\" will have type = 'cdata'." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:268 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"-- box.cfg{} should be here\n" +"\n" +"s = box.schema.space.create('withdata')\n" +"s:format({{\"b\", \"varbinary\"}})\n" +"s:create_index('pk', {parts = {1, \"varbinary\"}})\n" +"\n" +"buffer = require('buffer')\n" +"ffi = require('ffi')\n" +"\n" +"function varbinary_insert(space, bytes)\n" +" local tmpbuf = buffer.ibuf()\n" +" local p = tmpbuf:alloc(3 + #bytes)\n" +" p[0] = 0x91 -- MsgPack code for \"array-1\"\n" +" p[1] = 0xC4 -- MsgPack code for \"bin-8\" so up to 256 bytes\n" +" p[2] = #bytes\n" +" for i, c in pairs(bytes) do p[i + 3 - 1] = c end\n" +" ffi.cdef[[int box_insert(uint32_t space_id,\n" +" const char *tuple,\n" +" const char *tuple_end,\n" +" box_tuple_t **result);]]\n" +" ffi.C.box_insert(space.id, tmpbuf.rpos, tmpbuf.wpos, nil)\n" +" tmpbuf:recycle()\n" +"end\n" +"\n" +"varbinary_insert(s, {0xDE, 0xAD, 0xBE, 0xAF})\n" +"varbinary_insert(s, {0xFE, 0xED, 0xFA, 0xCE})\n" +"\n" +"-- if successful, Tarantool enters the event loop now" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:306 +msgid "print_arrays.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:308 +msgid "Create Lua tables, and print them. Notice that for the 'array' table the iterator function is ``ipairs()``, while for the 'map' table the iterator function is pairs(). (``ipairs()`` is faster than ``pairs()``, but ``pairs()`` is recommended for map-like tables or mixed tables.) The display will look like: \"1 Apple | 2 Orange | 3 Grapefruit | 4 Banana | k3 v3 | k1 v1 | k2 v2\"." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:316 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"array = { 'Apple', 'Orange', 'Grapefruit', 'Banana'}\n" +"for k, v in ipairs(array) do print(k, v) end\n" +"\n" +"map = { k1 = 'v1', k2 = 'v2', k3 = 'v3' }\n" +"for k, v in pairs(map) do print(k, v) end" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:330 +msgid "count_array.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:332 +msgid "Use the '#' operator to get the number of items in an array-like Lua table. This operation has O(log(N)) complexity." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:335 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"array = { 1, 2, 3}\n" +"print(#array)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:346 +msgid "count_array_with_nils.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:348 +msgid "Missing elements in arrays, which Lua treats as \"nil\"s, cause the simple \"#\" operator to deliver improper results. The \"print(#t)\" instruction will print \"4\"; the \"print(counter)\" instruction will print \"3\"; the \"print(max)\" instruction will print \"10\". Other table functions, such as :ref:`table.sort() `, will also misbehave when \"nils\" are present." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:356 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local t = {}\n" +"t[1] = 1\n" +"t[4] = 4\n" +"t[10] = 10\n" +"print(#t)\n" +"local counter = 0\n" +"for k,v in pairs(t) do counter = counter + 1 end\n" +"print(counter)\n" +"local max = 0\n" +"for k,v in pairs(t) do if k > max then max = k end end\n" +"print(max)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:376 +msgid "count_array_with_nulls.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:378 +msgid "Use explicit ``NULL`` values to avoid the problems caused by Lua's nil == missing value behavior. Although :code:`json.NULL == nil` is :code:`true`, all the print instructions in this program will print the correct value: 10." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:383 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local json = require('json')\n" +"local t = {}\n" +"t[1] = 1; t[2] = json.NULL; t[3]= json.NULL;\n" +"t[4] = 4; t[5] = json.NULL; t[6]= json.NULL;\n" +"t[6] = 4; t[7] = json.NULL; t[8]= json.NULL;\n" +"t[9] = json.NULL\n" +"t[10] = 10\n" +"print(#t)\n" +"local counter = 0\n" +"for k,v in pairs(t) do counter = counter + 1 end\n" +"print(counter)\n" +"local max = 0\n" +"for k,v in pairs(t) do if k > max then max = k end end\n" +"print(max)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:406 +msgid "count_map.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:408 +msgid "Get the number of elements in a map-like table." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:410 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local map = { a = 10, b = 15, c = 20 }\n" +"local size = 0\n" +"for _ in pairs(map) do size = size + 1; end\n" +"print(size)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:423 +msgid "swap.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:425 +msgid "Use a Lua peculiarity to swap two variables without needing a third variable." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:427 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local x = 1\n" +"local y = 2\n" +"x, y = y, x\n" +"print(x, y)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:440 +msgid "class.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:442 +msgid "Create a class, create a metatable for the class, create an instance of the class. Another illustration is at `http://lua-users.org/wiki/LuaClassesWithMetatable `_." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:446 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"-- define class objects\n" +"local myclass_somemethod = function(self)\n" +" print('test 1', self.data)\n" +"end\n" +"\n" +"local myclass_someothermethod = function(self)\n" +" print('test 2', self.data)\n" +"end\n" +"\n" +"local myclass_tostring = function(self)\n" +" return 'MyClass <'..self.data..'>'\n" +"end\n" +"\n" +"local myclass_mt = {\n" +" __tostring = myclass_tostring;\n" +" __index = {\n" +" somemethod = myclass_somemethod;\n" +" someothermethod = myclass_someothermethod;\n" +" }\n" +"}\n" +"\n" +"-- create a new object of myclass\n" +"local object = setmetatable({ data = 'data'}, myclass_mt)\n" +"print(object:somemethod())\n" +"print(object.data)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:480 +msgid "garbage.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:482 +msgid "Activate the `Lua garbage collector `_ with the `collectgarbage function `_." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:485 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"collectgarbage('collect')" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:495 +msgid "fiber_producer_and_consumer.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:497 +msgid "Start one fiber for producer and one fiber for consumer. Use :ref:`fiber.channel() ` to exchange data and synchronize. One can tweak the channel size (:code:`ch_size` in the program code) to control the number of simultaneous tasks waiting for processing." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:502 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local fiber = require('fiber')\n" +"local function consumer_loop(ch, i)\n" +" -- initialize consumer synchronously or raise an error()\n" +" fiber.sleep(0) -- allow fiber.create() to continue\n" +" while true do\n" +" local data = ch:get()\n" +" if data == nil then\n" +" break\n" +" end\n" +" print('consumed', i, data)\n" +" fiber.sleep(math.random()) -- simulate some work\n" +" end\n" +"end\n" +"\n" +"local function producer_loop(ch, i)\n" +" -- initialize consumer synchronously or raise an error()\n" +" fiber.sleep(0) -- allow fiber.create() to continue\n" +" while true do\n" +" local data = math.random()\n" +" ch:put(data)\n" +" print('produced', i, data)\n" +" end\n" +"end\n" +"\n" +"local function start()\n" +" local consumer_n = 5\n" +" local producer_n = 3\n" +"\n" +" -- Create a channel\n" +" local ch_size = math.max(consumer_n, producer_n)\n" +" local ch = fiber.channel(ch_size)\n" +"\n" +" -- Start consumers\n" +" for i=1, consumer_n,1 do\n" +" fiber.create(consumer_loop, ch, i)\n" +" end\n" +"\n" +" -- Start producers\n" +" for i=1, producer_n,1 do\n" +" fiber.create(producer_loop, ch, i)\n" +" end\n" +"end\n" +"\n" +"start()\n" +"print('started')" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:556 +msgid "socket_tcpconnect.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:558 +msgid "Use :ref:`socket.tcp_connect() ` to connect to a remote host via TCP. Display the connection details and the result of a GET request." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:562 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local s = require('socket').tcp_connect('google.com', 80)\n" +"print(s:peer().host)\n" +"print(s:peer().family)\n" +"print(s:peer().type)\n" +"print(s:peer().protocol)\n" +"print(s:peer().port)\n" +"print(s:write(\"GET / HTTP/1.0\\r\\n\\r\\n\"))\n" +"print(s:read('\\r\\n'))\n" +"print(s:read('\\r\\n'))" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:580 +msgid "socket_tcp_echo.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:582 +msgid "Use :ref:`socket.tcp_connect() ` to set up a simple TCP server, by creating a function that handles requests and echos them, and passing the function to :ref:`socket.tcp_server() `. This program has been used to test with 100,000 clients, with each client getting a separate fiber." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:590 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local function handler(s, peer)\n" +" s:write(\"Welcome to test server, \" .. peer.host ..\"\\n\")\n" +" while true do\n" +" local line = s:read('\\n')\n" +" if line == nil then\n" +" break -- error or eof\n" +" end\n" +" if not s:write(\"pong: \"..line) then\n" +" break -- error or eof\n" +" end\n" +" end\n" +"end\n" +"\n" +"local server, addr = require('socket').tcp_server('localhost', 3311, handler)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:613 +msgid "getaddrinfo.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:615 +msgid "Use :ref:`socket.getaddrinfo() ` to perform non-blocking DNS resolution, getting both the AF_INET6 and AF_INET information for 'google.com'. This technique is not always necessary for tcp connections because :ref:`socket.tcp_connect() ` performs `socket.getaddrinfo` under the hood, before trying to connect to the first available address." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:623 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local s = require('socket').getaddrinfo('google.com', 'http', { type = 'SOCK_STREAM' })\n" +"print('host=',s[1].host)\n" +"print('family=',s[1].family)\n" +"print('type=',s[1].type)\n" +"print('protocol=',s[1].protocol)\n" +"print('port=',s[1].port)\n" +"print('host=',s[2].host)\n" +"print('family=',s[2].family)\n" +"print('type=',s[2].type)\n" +"print('protocol=',s[2].protocol)\n" +"print('port=',s[2].port)" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:643 +msgid "socket_udp_echo.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:645 +msgid "Tarantool does not currently have a `udp_server` function, therefore socket_udp_echo.lua is more complicated than socket_tcp_echo.lua. It can be implemented with sockets and fibers." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:650 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local socket = require('socket')\n" +"local errno = require('errno')\n" +"local fiber = require('fiber')\n" +"\n" +"local function udp_server_loop(s, handler)\n" +" fiber.name(\"udp_server\")\n" +" while true do\n" +" -- try to read a datagram first\n" +" local msg, peer = s:recvfrom()\n" +" if msg == \"\" then\n" +" -- socket was closed via s:close()\n" +" break\n" +" elseif msg ~= nil then\n" +" -- got a new datagram\n" +" handler(s, peer, msg)\n" +" else\n" +" if s:errno() == errno.EAGAIN or s:errno() == errno.EINTR then\n" +" -- socket is not ready\n" +" s:readable() -- yield, epoll will wake us when new data arrives\n" +" else\n" +" -- socket error\n" +" local msg = s:error()\n" +" s:close() -- save resources and don't wait GC\n" +" error(\"Socket error: \" .. msg)\n" +" end\n" +" end\n" +" end\n" +"end\n" +"\n" +"local function udp_server(host, port, handler)\n" +" local s = socket('AF_INET', 'SOCK_DGRAM', 0)\n" +" if not s then\n" +" return nil -- check errno:strerror()\n" +" end\n" +" if not s:bind(host, port) then\n" +" local e = s:errno() -- save errno\n" +" s:close()\n" +" errno(e) -- restore errno\n" +" return nil -- check errno:strerror()\n" +" end\n" +"\n" +" fiber.create(udp_server_loop, s, handler) -- start a new background fiber\n" +" return s\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:699 +msgid "A function for a client that connects to this server could look something like this ..." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:702 +msgid "local function handler(s, peer, msg)\n" +" -- You don't have to wait until socket is ready to send UDP\n" +" -- s:writable()\n" +" s:sendto(peer.host, peer.port, \"Pong: \" .. msg)\n" +"end\n" +"\n" +"local server = udp_server('127.0.0.1', 3548, handler)\n" +"if not server then\n" +" error('Failed to bind: ' .. errno.strerror())\n" +"end\n" +"\n" +"print('Started')\n" +"\n" +"require('console').start()" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:723 +msgid "http_get.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:725 +msgid "Use the :ref:`http module ` to get data via HTTP." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:728 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local http_client = require('http.client')\n" +"local json = require('json')\n" +"local r = http_client.get('https://api.frankfurter.app/latest?to=USD%2CRUB')\n" +"if r.status ~= 200 then\n" +" print('Failed to get currency ', r.reason)\n" +" return\n" +"end\n" +"local data = json.decode(r.body)\n" +"print(data.base, 'rate of', data.date, 'is', data.rates.RUB, 'RUB or', data.rates.USD, 'USD')" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:746 +msgid "http_send.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:748 +msgid "Use the :ref:`http module ` to send data via HTTP." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:751 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local http_client = require('http.client')\n" +"local json = require('json')\n" +"local data = json.encode({ Key = 'Value'})\n" +"local headers = { Token = 'xxxx', ['X-Secret-Value'] = '42' }\n" +"local r = http_client.post('http://localhost:8081', data, { headers = headers})\n" +"if r.status == 200 then\n" +" print 'Success'\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:768 +msgid "http_server.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:770 +msgid "Use the `http`_ `rock`_ (which must first be installed) to turn Tarantool into a web server." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:773 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local function handler(self)\n" +" return self:render{ json = { ['Your-IP-Is'] = self.peer.host } }\n" +"end\n" +"\n" +"local server = require('http.server').new(nil, 8080, {charset = \"utf8\"}) -- listen *:8080\n" +"server:route({ path = '/' }, handler)\n" +"server:start()\n" +"-- connect to localhost:8080 and see json" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:790 +msgid "http_generate_html.lua" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:792 +msgid "Use the `http `_ `rock` (which must first be installed) to generate HTML pages from templates. The `http `_ `rock `_ has a fairly simple template engine which allows execution of regular Lua code inside text blocks (like PHP). Therefore there is no need to learn new languages in order to write templates." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:799 +msgid "#!/usr/bin/env tarantool\n" +"\n" +"local function handler(self)\n" +"local fruits = {'Apple', 'Orange', 'Grapefruit', 'Banana'}\n" +" return self:render{ fruits = fruits }\n" +"end\n" +"\n" +"local server = require('http.server').new(nil, 8080, {charset = \"utf8\"}) -- nil means '*'\n" +"server:route({ path = '/', file = 'index.html.lua' }, handler)\n" +"server:start()" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:812 +msgid "An \"HTML\" file for this server, including Lua, could look like this (it would produce \"1 Apple | 2 Orange | 3 Grapefruit | 4 Banana\"). Create a ``templates`` directory and put this file in it:" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:816 +msgid "\n" +"\n" +" \n" +" % for i,v in pairs(fruits) do\n" +" \n" +" \n" +" \n" +" \n" +" % end\n" +"
<%= i %><%= v %>
\n" +"\n" +"" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:835 +msgid "select_all.go" +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:837 +msgid "In Go, there is no one-liner to select all tuples from a Tarantool space. Yet you can use a script like this one. Call it on the instance you want to connect to." +msgstr "" + +#: ../../doc/how-to/app/cookbook.rst:841 +msgid "package main\n" +"\n" +"import (\n" +" \"fmt\"\n" +" \"log\"\n" +"\n" +" \"github.com/tarantool/go-tarantool\"\n" +")\n" +"\n" +"/*\n" +"box.cfg{listen = 3301}\n" +"box.schema.user.passwd('pass')\n" +"\n" +"s = box.schema.space.create('tester')\n" +"s:format({\n" +" {name = 'id', type = 'unsigned'},\n" +" {name = 'band_name', type = 'string'},\n" +" {name = 'year', type = 'unsigned'}\n" +"})\n" +"s:create_index('primary', { type = 'hash', parts = {'id'} })\n" +"s:create_index('scanner', { type = 'tree', parts = {'id', 'band_name'} })\n" +"\n" +"s:insert{1, 'Roxette', 1986}\n" +"s:insert{2, 'Scorpions', 2015}\n" +"s:insert{3, 'Ace of Base', 1993}\n" +"*/\n" +"\n" +"func main() {\n" +" conn, err := tarantool.Connect(\"127.0.0.1:3301\", tarantool.Opts{\n" +" User: \"admin\",\n" +" Pass: \"pass\",\n" +" })\n" +"\n" +" if err != nil {\n" +" log.Fatalf(\"Connection refused\")\n" +" }\n" +" defer conn.Close()\n" +"\n" +" spaceName := \"tester\"\n" +" indexName := \"scanner\"\n" +" idFn := conn.Schema.Spaces[spaceName].Fields[\"id\"].Id\n" +" bandNameFn := conn.Schema.Spaces[spaceName].Fields[\"band_name\"].Id\n" +"\n" +" var tuplesPerRequest uint32 = 2\n" +" cursor := []interface{}{}\n" +"\n" +" for {\n" +" resp, err := conn.Select(spaceName, indexName, 0, tuplesPerRequest, tarantool.IterGt, cursor)\n" +" if err != nil {\n" +" log.Fatalf(\"Failed to select: %s\", err)\n" +" }\n" +"\n" +" if resp.Code != tarantool.OkCode {\n" +" log.Fatalf(\"Select failed: %s\", resp.Error)\n" +" }\n" +"\n" +" if len(resp.Data) == 0 {\n" +" break\n" +" }\n" +"\n" +" fmt.Println(\"Iteration\")\n" +"\n" +" tuples := resp.Tuples()\n" +" for _, tuple := range tuples {\n" +" fmt.Printf(\"\\t%v\\n\", tuple)\n" +" }\n" +"\n" +" lastTuple := tuples[len(tuples)-1]\n" +" cursor = []interface{}{lastTuple[idFn], lastTuple[bandNameFn]}\n" +" }\n" +"}\n" +"" +msgstr "" diff --git a/locale/en/platform/app/creating_app.pot b/locale/en/platform/app/creating_app.pot new file mode 100644 index 0000000000..ec431cab87 --- /dev/null +++ b/locale/en/platform/app/creating_app.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app.rst:7 +msgid "Creating an application" +msgstr "" + +#: ../../doc/how-to/app/creating_app.rst:9 +msgid "Further we walk you through key programming practices that will give you a good start in writing Lua applications for Tarantool. We will implement a real microservice based on Tarantool! It is a backend for a simplified version of `Pokémon Go `_, a location-based augmented reality game launched in mid-2016." +msgstr "" + +#: ../../doc/how-to/app/creating_app.rst:16 +msgid "In this game, players use the GPS capability of a mobile device to locate, catch, battle, and train virtual monsters called \"pokémon\" that appear on the screen as if they were in the same real-world location as the player." +msgstr "" + +#: ../../doc/how-to/app/creating_app.rst:21 +msgid "To stay within the walk-through format, let's narrow the original gameplay as follows. We have a map with pokémon spawn locations. Next, we have multiple players who can send catch-a-pokémon requests to the server (which runs our Tarantool microservice). The server responds whether the pokémon is caught or not, increases the player's pokémon counter if yes, and triggers the respawn-a-pokémon method that spawns a new pokémon at the same location in a while." +msgstr "" + +#: ../../doc/how-to/app/creating_app.rst:30 +msgid "We leave client-side applications outside the scope of this story. However, we promise a mini-demo in the end to simulate real users and give us some fun." +msgstr "" + +#: ../../doc/how-to/app/creating_app.rst:37 +msgid "Follow these topics to implement our application:" +msgstr "" diff --git a/locale/en/platform/app/creating_app/GIS.pot b/locale/en/platform/app/creating_app/GIS.pot new file mode 100644 index 0000000000..5feeb91a3d --- /dev/null +++ b/locale/en/platform/app/creating_app/GIS.pot @@ -0,0 +1,127 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/GIS.rst:4 +msgid "GIS" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:6 +msgid "Now let's discuss ``catch()``, which is the main method in our gaming logic." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:8 +msgid "Here we receive the player's coordinates and the target pokémon's ID number, and we need to answer whether the player has actually caught the pokémon or not (remember that each pokémon has a chance to escape)." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:12 +msgid "First thing, we validate the received player data against its :ref:`Avro schema `. And we check whether such a pokémon exists in our database and is displayed on the map (the pokémon must have the active status):" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:17 +msgid "catch = function(self, pokemon_id, player)\n" +" -- check player data\n" +" local ok, tuple = self.player_model.flatten(player)\n" +" if not ok then\n" +" return false\n" +" end\n" +" -- get pokemon data\n" +" local p_tuple = box.space.pokemons:get(pokemon_id)\n" +" if p_tuple == nil then\n" +" return false\n" +" end\n" +" local ok, pokemon = self.pokemon_model.unflatten(p_tuple)\n" +" if not ok then\n" +" return false\n" +" end\n" +" if pokemon.status ~= self.state.ACTIVE then\n" +" return false\n" +" end\n" +" -- more catch logic to follow\n" +" <...>\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:41 +msgid "Next, we calculate the answer: caught or not." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:43 +msgid "To work with geographical coordinates, we use Tarantool `gis `_ module." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:46 +msgid "To keep things simple, we don't load any specific map, assuming that we deal with a world map. And we do not validate incoming coordinates, assuming again that all received locations are within the planet Earth." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:50 +msgid "We use two geo-specific variables:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:52 +msgid "``wgs84``, which stands for the latest revision of the World Geodetic System standard, `WGS84 `_. Basically, it comprises a standard coordinate system for the Earth and represents the Earth as an ellipsoid." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:56 +msgid "``nationalmap``, which stands for the `US National Atlas Equal Area `_. This is a projected coordinates system based on WGS84. It gives us a zero base for location projection and allows positioning our players and pokémons in meters." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:61 +msgid "Both these systems are listed in the EPSG Geodetic Parameter Registry, where each system has a unique number. In our code, we assign these listing numbers to respective variables:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:65 +msgid "wgs84 = 4326,\n" +"nationalmap = 2163," +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:70 +msgid "For our game logic, we need one more variable, ``catch_distance``, which defines how close a player must get to a pokémon before trying to catch it. Let's set the distance to 100 meters." +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:74 +msgid "catch_distance = 100," +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:78 +msgid "Now we're ready to calculate the answer. We need to project the current location of both player (``p_pos``) and pokémon (``m_pos``) on the map, check whether the player is close enough to the pokémon (using ``catch_distance``), and calculate whether the player has caught the pokémon (here we generate some random value and let the pokémon escape if the random value happens to be less than 100 minus pokémon's chance value):" +msgstr "" + +#: ../../doc/how-to/app/creating_app/GIS.rst:85 +msgid "-- project locations\n" +"local m_pos = gis.Point(\n" +" {pokemon.location.x, pokemon.location.y}, self.wgs84\n" +"):transform(self.nationalmap)\n" +"local p_pos = gis.Point(\n" +" {player.location.x, player.location.y}, self.wgs84\n" +"):transform(self.nationalmap)\n" +"\n" +"-- check catch distance condition\n" +"if p_pos:distance(m_pos) > self.catch_distance then\n" +" return false\n" +"end\n" +"-- try to catch pokemon\n" +"local caught = math.random(100) >= 100 - pokemon.chance\n" +"if caught then\n" +" -- update and notify on success\n" +" box.space.pokemons:update(\n" +" pokemon_id, {{'=', self.STATUS, self.state.CAUGHT}}\n" +" )\n" +" self:notify(player, pokemon)\n" +"end\n" +"return caught" +msgstr "" diff --git a/locale/en/platform/app/creating_app/avro_schemas.pot b/locale/en/platform/app/creating_app/avro_schemas.pot new file mode 100644 index 0000000000..ff7b1f50df --- /dev/null +++ b/locale/en/platform/app/creating_app/avro_schemas.pot @@ -0,0 +1,196 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:4 +msgid "Avro schemas" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:6 +msgid "To store JSON data as tuples, we will apply a savvy practice which reduces data footprint and ensures all stored documents are valid. We will use Tarantool module `avro-schema `_ which checks the schema of a JSON document and converts it to a Tarantool tuple. The tuple will contain only field values, and thus take a lot less space than the original document. In avro-schema terms, converting JSON documents to tuples is \"flattening\", and restoring the original documents is \"unflattening\"." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:14 +msgid "First you need to :ref:`install ` the module with ``tt rocks install avro-schema``." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:17 +msgid "Further usage is quite straightforward:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:19 +msgid "For each entity, we need to define a schema in `Apache Avro schema `_ syntax, where we list the entity's fields with their names and `Avro data types `_." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:23 +msgid "At initialization, we call ``avro-schema.create()`` that creates objects in memory for all schema entities, and ``compile()`` that generates flatten/unflatten methods for each entity." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:26 +msgid "Further on, we just call flatten/unflatten methods for a respective entity on receiving/sending the entity's data." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:29 +msgid "Here's what our schema definitions for the player and pokémon entities look like:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:31 +msgid "local schema = {\n" +" player = {\n" +" type=\"record\",\n" +" name=\"player_schema\",\n" +" fields={\n" +" {name=\"id\", type=\"long\"},\n" +" {name=\"name\", type=\"string\"},\n" +" {\n" +" name=\"location\",\n" +" type= {\n" +" type=\"record\",\n" +" name=\"player_location\",\n" +" fields={\n" +" {name=\"x\", type=\"double\"},\n" +" {name=\"y\", type=\"double\"}\n" +" }\n" +" }\n" +" }\n" +" }\n" +" },\n" +" pokemon = {\n" +" type=\"record\",\n" +" name=\"pokemon_schema\",\n" +" fields={\n" +" {name=\"id\", type=\"long\"},\n" +" {name=\"status\", type=\"string\"},\n" +" {name=\"name\", type=\"string\"},\n" +" {name=\"chance\", type=\"double\"},\n" +" {\n" +" name=\"location\",\n" +" type= {\n" +" type=\"record\",\n" +" name=\"pokemon_location\",\n" +" fields={\n" +" {name=\"x\", type=\"double\"},\n" +" {name=\"y\", type=\"double\"}\n" +" }\n" +" }\n" +" }\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:76 +msgid "And here's how we create and compile our entities at initialization:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:78 +msgid "-- load avro-schema module with require()\n" +"local avro = require('avro_schema')\n" +"\n" +"-- create models\n" +"local ok_m, pokemon = avro.create(schema.pokemon)\n" +"local ok_p, player = avro.create(schema.player)\n" +"if ok_m and ok_p then\n" +" -- compile models\n" +" local ok_cm, compiled_pokemon = avro.compile(pokemon)\n" +" local ok_cp, compiled_player = avro.compile(player)\n" +" if ok_cm and ok_cp then\n" +" -- start the game\n" +" <...>\n" +" else\n" +" log.error('Schema compilation failed')\n" +" end\n" +"else\n" +" log.info('Schema creation failed')\n" +"end\n" +"return false" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:101 +msgid "As for the map entity, it would be an overkill to introduce a schema for it, because we have only one map in the game, it has very few fields, and -- which is most important -- we use the map only inside our logic, never exposing it to external users." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:109 +msgid "Next, we need methods to implement the game logic. To simulate object-oriented programming in our Lua code, let's store all Lua functions and shared variables in a single local variable (let's name it as ``game``). This will allow us to address functions or variables from within our module as ``self.func_name`` or ``self.var_name``. Like this:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:115 +msgid "local game = {\n" +" -- a local variable\n" +" num_players = 0,\n" +"\n" +" -- a method that prints a local variable\n" +" hello = function(self)\n" +" print('Hello! Your player number is ' .. self.num_players .. '.')\n" +" end,\n" +"\n" +" -- a method that calls another method and returns a local variable\n" +" sign_in = function(self)\n" +" self.num_players = self.num_players + 1\n" +" self:hello()\n" +" return self.num_players\n" +" end\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:134 +msgid "In OOP terms, we can now regard local variables inside ``game`` as object fields, and local functions as object methods." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:139 +msgid "In this manual, Lua examples use **local** variables. Use **global** variables with caution, since the module’s users may be unaware of them." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:142 +msgid "To enable/disable the use of undeclared global variables in your Lua code, use Tarantool's :ref:`strict ` module." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:145 +msgid "So, our game module will have the following methods:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:147 +msgid "``catch()`` to calculate whether the pokémon was caught (besides the coordinates of both the player and pokémon, this method will apply a probability factor, so not every pokémon within the player's reach will be caught);" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:151 +msgid "``respawn()`` to add missing pokémons to the map, say, every 60 seconds (we assume that a frightened pokémon runs away, so we remove a pokémon from the map on any catch attempt and add it back to the map in a while);" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:154 +msgid "``notify()`` to log information about caught pokémons (like \"Player 1 caught pokémon A\");" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:156 +msgid "``start()`` to initialize the game (it will create database spaces, create and compile avro schemas, and launch ``respawn()``)." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:159 +msgid "Besides, it would be convenient to have methods for working with Tarantool storage. For example:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:162 +msgid "``add_pokemon()`` to add a pokémon to the database, and" +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:163 +msgid "``map()`` to populate the map with all pokémons stored in Tarantool." +msgstr "" + +#: ../../doc/how-to/app/creating_app/avro_schemas.rst:165 +msgid "We'll need these two methods primarily when initializing our game, but we can also call them later, for example to test our code." +msgstr "" diff --git a/locale/en/platform/app/creating_app/bootstrapping_a_database.pot b/locale/en/platform/app/creating_app/bootstrapping_a_database.pot new file mode 100644 index 0000000000..3210975621 --- /dev/null +++ b/locale/en/platform/app/creating_app/bootstrapping_a_database.pot @@ -0,0 +1,83 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:4 +msgid "Bootstrapping a database" +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:6 +msgid "Let's discuss game initialization. In ``start()`` method, we need to populate Tarantool spaces with pokémon data. Why not keep all game data in memory? Why use a database? The answer is: :ref:`persistence `. Without a database, we risk losing data on power outage, for example. But if we store our data in an in-memory database, Tarantool takes care to persist it on disk whenever it's changed. This gives us one more benefit: quick startup in case of failure. Tarantool has a :ref:`smart algorithm ` that quickly loads all data from disk into memory on startup, so the warm-up takes little time." +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:16 +msgid "We'll be using functions from Tarantool built-in :ref:`box ` module:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:18 +msgid "``box.schema.create_space('pokemons')`` to create a space named ``pokemon`` for storing information about pokémons (we don't create a similar space for players, because we intend to only send/receive player information via API calls, so we needn't store it);" +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:22 +msgid "``box.space.pokemons:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}})`` to create a primary HASH index by pokémon ID;" +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:24 +msgid "``box.space.pokemons:create_index('status', {type = 'tree', parts = {2, 'str'}})`` to create a secondary TREE index by pokémon status." +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:27 +msgid "Notice the ``parts =`` argument in the index specification. The pokémon ID is the first field in a Tarantool tuple since it’s the first member of the respective Avro type. So does the pokémon status. The actual JSON document may have ID or status fields at any position of the JSON map." +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:32 +msgid "The implementation of ``start()`` method looks like this:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/bootstrapping_a_database.rst:34 +msgid "-- create game object\n" +"start = function(self)\n" +" -- create spaces and indexes\n" +" box.once('init', function()\n" +" box.schema.create_space('pokemons')\n" +" box.space.pokemons:create_index(\n" +" \"primary\", {type = 'hash', parts = {1, 'unsigned'}}\n" +" )\n" +" box.space.pokemons:create_index(\n" +" \"status\", {type = \"tree\", parts = {2, 'str'}}\n" +" )\n" +" end)\n" +"\n" +" -- create models\n" +" local ok_m, pokemon = avro.create(schema.pokemon)\n" +" local ok_p, player = avro.create(schema.player)\n" +" if ok_m and ok_p then\n" +" -- compile models\n" +" local ok_cm, compiled_pokemon = avro.compile(pokemon)\n" +" local ok_cp, compiled_player = avro.compile(player)\n" +" if ok_cm and ok_cp then\n" +" -- start the game\n" +" <...>\n" +" else\n" +" log.error('Schema compilation failed')\n" +" end\n" +" else\n" +" log.info('Schema creation failed')\n" +" end\n" +" return false\n" +"end" +msgstr "" diff --git a/locale/en/platform/app/creating_app/fibers.pot b/locale/en/platform/app/creating_app/fibers.pot new file mode 100644 index 0000000000..55eba2182c --- /dev/null +++ b/locale/en/platform/app/creating_app/fibers.pot @@ -0,0 +1,73 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/fibers.rst:4 +msgid "Fibers, yields and cooperative multitasking" +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:6 +msgid "But wait! If we launch it as shown above -- ``self.respawn()`` -- the function will be executed only once, just like all the other methods. But we need to execute ``respawn()`` every 60 seconds. Creating a :ref:`fiber ` is the Tarantool way of making application logic work in the background at all times." +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:12 +msgid "A **fiber** is a set of instructions that are executed with :ref:`cooperative multitasking `: the instructions contain :ref:`yield ` signals, upon which control is passed to another fiber." +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:16 +msgid "Let's launch ``respawn()`` in a fiber to make it work in the background all the time. To do so, we'll need to amend ``respawn()``:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:19 +msgid "respawn = function(self)\n" +" -- let's give our fiber a name;\n" +" -- this will produce neat output in fiber.info()\n" +" fiber.name('Respawn fiber')\n" +" while true do\n" +" for _, tuple in box.space.pokemons.index.status:pairs(\n" +" self.state.CAUGHT) do\n" +" box.space.pokemons:update(\n" +" tuple[self.ID],\n" +" {{'=', self.STATUS, self.state.ACTIVE}}\n" +" )\n" +" end\n" +" fiber.sleep(self.respawn_time)\n" +" end\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:37 +msgid "and call it as a fiber in ``start()``:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/fibers.rst:39 +msgid "start = function(self)\n" +" -- create spaces and indexes\n" +" <...>\n" +" -- create models\n" +" <...>\n" +" -- compile models\n" +" <...>\n" +" -- start the game\n" +" self.pokemon_model = compiled_pokemon\n" +" self.player_model = compiled_player\n" +" fiber.create(self.respawn, self)\n" +" log.info('Started')\n" +" -- errors if schema creation or compilation fails\n" +" <...>\n" +"end" +msgstr "" diff --git a/locale/en/platform/app/creating_app/index_iterators.pot b/locale/en/platform/app/creating_app/index_iterators.pot new file mode 100644 index 0000000000..ed037d66e8 --- /dev/null +++ b/locale/en/platform/app/creating_app/index_iterators.pot @@ -0,0 +1,88 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:4 +msgid "Index iterators" +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:6 +msgid "By our gameplay, all caught pokémons are returned back to the map. We do this for all pokémons on the map every 60 seconds using ``respawn()`` method. We iterate through pokémons by status using Tarantool index iterator function :doc:`/reference/reference_lua/box_index/pairs` and reset the statuses of all \"caught\" pokémons back to \"active\" using ``box.space.pokemons:update()``." +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:12 +msgid "respawn = function(self)\n" +" fiber.name('Respawn fiber')\n" +" for _, tuple in box.space.pokemons.index.status:pairs(\n" +" self.state.CAUGHT) do\n" +" box.space.pokemons:update(\n" +" tuple[self.ID],\n" +" {{'=', self.STATUS, self.state.ACTIVE}}\n" +" )\n" +" end\n" +" end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:25 +msgid "For readability, we introduce named fields:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:27 +msgid "ID = 1, STATUS = 2," +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:30 +msgid "The complete implementation of ``start()`` now looks like this:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/index_iterators.rst:32 +msgid "-- create game object\n" +"start = function(self)\n" +" -- create spaces and indexes\n" +" box.once('init', function()\n" +" box.schema.create_space('pokemons')\n" +" box.space.pokemons:create_index(\n" +" \"primary\", {type = 'hash', parts = {1, 'unsigned'}}\n" +" )\n" +" box.space.pokemons:create_index(\n" +" \"status\", {type = \"tree\", parts = {2, 'str'}}\n" +" )\n" +" end)\n" +"\n" +" -- create models\n" +" local ok_m, pokemon = avro.create(schema.pokemon)\n" +" local ok_p, player = avro.create(schema.player)\n" +" if ok_m and ok_p then\n" +" -- compile models\n" +" local ok_cm, compiled_pokemon = avro.compile(pokemon)\n" +" local ok_cp, compiled_player = avro.compile(player)\n" +" if ok_cm and ok_cp then\n" +" -- start the game\n" +" self.pokemon_model = compiled_pokemon\n" +" self.player_model = compiled_player\n" +" self.respawn()\n" +" log.info('Started')\n" +" return true\n" +" else\n" +" log.error('Schema compilation failed')\n" +" end\n" +" else\n" +" log.info('Schema creation failed')\n" +" end\n" +" return false\n" +"end" +msgstr "" diff --git a/locale/en/platform/app/creating_app/logging.pot b/locale/en/platform/app/creating_app/logging.pot new file mode 100644 index 0000000000..22a7023242 --- /dev/null +++ b/locale/en/platform/app/creating_app/logging.pot @@ -0,0 +1,83 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/logging.rst:4 +msgid "Logging" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:6 +msgid "One more helpful function that we used in ``start()`` was ``log.infо()`` from Tarantool :ref:`log ` module. We also need this function in ``notify()`` to add a record to the log file on every successful catch:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:10 +msgid "-- event notification\n" +"notify = function(self, player, pokemon)\n" +" log.info(\"Player '%s' caught '%s'\", player.name, pokemon.name)\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:17 +msgid "We use default Tarantool :ref:`log settings `, so we'll see the log output in console when we launch our application in script mode." +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:23 +msgid "Great! We've discussed all programming practices used in our Lua module (see `pokemon.lua `_)." +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:26 +msgid "Now let's prepare the test environment. As planned, we write a Lua application (see `game.lua `_) to initialize Tarantool's database module, initialize our game, call the game loop and simulate a couple of player requests." +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:31 +msgid "To launch our microservice, we put both the ``pokemon.lua`` module and the ``game.lua`` application in the current directory, install all external modules, and launch the Tarantool instance running our ``game.lua`` application (this example is for Ubuntu):" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:36 +msgid "$ ls\n" +"game.lua pokemon.lua\n" +"$ sudo apt-get install tarantool-gis\n" +"$ sudo apt-get install tarantool-avro-schema\n" +"$ tarantool game.lua" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:44 +msgid "Tarantool starts and initializes the database. Then Tarantool executes the demo logic from ``game.lua``: adds a pokémon named Pikachu (its chance to be caught is very high, 99.1), displays the current map (it contains one active pokémon, Pikachu) and processes catch requests from two players. Player1 is located just near the lonely Pikachu pokémon and Player2 is located far away from it. As expected, the catch results in this output are \"true\" for Player1 and \"false\" for Player2. Finally, Tarantool displays the current map which is empty, because Pikachu is caught and temporarily inactive:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/logging.rst:53 +msgid "$ tarantool game.lua\n" +"2017-01-09 20:19:24.605 [6282] main/101/game.lua C> version 1.7.3-43-gf5fa1e1\n" +"2017-01-09 20:19:24.605 [6282] main/101/game.lua C> log level 5\n" +"2017-01-09 20:19:24.605 [6282] main/101/game.lua I> mapping 1073741824 bytes for tuple arena...\n" +"2017-01-09 20:19:24.609 [6282] main/101/game.lua I> initializing an empty data directory\n" +"2017-01-09 20:19:24.634 [6282] snapshot/101/main I> saving snapshot `./00000000000000000000.snap.inprogress'\n" +"2017-01-09 20:19:24.635 [6282] snapshot/101/main I> done\n" +"2017-01-09 20:19:24.641 [6282] main/101/game.lua I> ready to accept requests\n" +"2017-01-09 20:19:24.786 [6282] main/101/game.lua I> Started\n" +"---\n" +"- {'id': 1, 'status': 'active', 'location': {'y': 2, 'x': 1}, 'name': 'Pikachu', 'chance': 99.1}\n" +"...\n" +"\n" +"2017-01-09 20:19:24.789 [6282] main/101/game.lua I> Player 'Player1' caught 'Pikachu'\n" +"true\n" +"false\n" +"--- []\n" +"...\n" +"\n" +"2017-01-09 20:19:24.789 [6282] main C> entering the event loop" +msgstr "" diff --git a/locale/en/platform/app/creating_app/modules_rocks_and_applications.pot b/locale/en/platform/app/creating_app/modules_rocks_and_applications.pot new file mode 100644 index 0000000000..f38aaa42f6 --- /dev/null +++ b/locale/en/platform/app/creating_app/modules_rocks_and_applications.pot @@ -0,0 +1,103 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:4 +msgid "Modules, rocks and applications" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:6 +msgid "To make our game logic available to other developers and Lua applications, let's put it into a Lua module." +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:9 +msgid "A **module** (called \"rock\" in Lua) is an optional library which enhances Tarantool functionality. So, we can install our logic as a module in Tarantool and use it from any Tarantool application or module. Like applications, modules in Tarantool can be written in Lua (rocks), C or C++." +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:14 +msgid "Modules are good for two things:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:16 +msgid "easier **code management** (reuse, packaging, versioning), and" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:17 +msgid "hot **code reload** without restarting the Tarantool instance." +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:19 +msgid "Technically, a module is a file with source code that exports its functions in an API. For example, here is a Lua module named ``mymodule.lua`` that exports one function named ``myfun``:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:23 +msgid "local exports = {}\n" +"exports.myfun = function(input_string)\n" +" print('Hello', input_string)\n" +"end\n" +"return exports" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:31 +msgid "To launch the function ``myfun()`` -- from another module, from a Lua application, or from Tarantool itself, -- we need to save this module as a file, then load this module with the ``require()`` directive and call the exported function." +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:35 +msgid "For example, here's a Lua application that uses ``myfun()`` function from ``mymodule.lua`` module:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:38 +msgid "-- loading the module\n" +"local mymodule = require('mymodule')\n" +"\n" +"-- calling myfun() from within test() function\n" +"local test = function()\n" +" mymodule.myfun()\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:48 +msgid "A thing to remember here is that the ``require()`` directive takes load paths to Lua modules from the ``package.path`` variable. This is a semicolon-separated string, where a question mark is used to interpolate the module name. By default, this variable contains system-wide Lua paths and the working directory. But if we put our modules inside a specific folder (e.g. ``scripts/``), we need to add this folder to ``package.path`` before any calls to ``require()``:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:55 +msgid "package.path = 'scripts/?.lua;' .. package.path" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:59 +msgid "For our microservice, a simple and convenient solution would be to put all methods in a Lua module (say ``pokemon.lua``) and to write a Lua application (say ``game.lua``) that initializes the gaming environment and starts the game loop." +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:67 +msgid "Now let's get down to implementation details. In our game, we need three entities:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:69 +msgid "**map**, which is an array of pokémons with coordinates of respawn locations; in this version of the game, let a location be a rectangle identified with two points, upper-left and lower-right;" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:72 +msgid "**player**, which has an ID, a name, and coordinates of the player's location point;" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:74 +msgid "**pokémon**, which has the same fields as the player, plus a status (active/inactive, that is present on the map or not) and a catch probability (well, let's give our pokémons a chance to escape :-) )" +msgstr "" + +#: ../../doc/how-to/app/creating_app/modules_rocks_and_applications.rst:78 +msgid "We'll store these entities as tuples in Tarantool spaces. But to deliver our backend application as a microservice, the good practice would be to send/receive our data in the universal JSON format, thus using Tarantool as a document storage." +msgstr "" diff --git a/locale/en/platform/app/creating_app/nginx.pot b/locale/en/platform/app/creating_app/nginx.pot new file mode 100644 index 0000000000..b84153ae05 --- /dev/null +++ b/locale/en/platform/app/creating_app/nginx.pot @@ -0,0 +1,99 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/nginx.rst:4 +msgid "nginx" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:6 +msgid "In the real life, this microservice would work over HTTP. Let's add `nginx `_ web server to our environment and make a similar demo. But how do we make Tarantool methods callable via REST API? We use nginx with `Tarantool nginx upstream `_ module and create one more Lua script (`app.lua `_) that exports three of our game methods -- ``add_pokemon()``, ``map()`` and ``catch()`` -- as REST endpoints of the nginx upstream module:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:15 +msgid "local game = require('pokemon')\n" +"box.cfg{listen=3301}\n" +"game:start()\n" +"\n" +"-- add, map and catch functions exposed to REST API\n" +"function add(request, pokemon)\n" +" return {\n" +" result=game:add_pokemon(pokemon)\n" +" }\n" +"end\n" +"\n" +"function map(request)\n" +" return {\n" +" map=game:map()\n" +" }\n" +"end\n" +"\n" +"function catch(request, pid, player)\n" +" local id = tonumber(pid)\n" +" if id == nil then\n" +" return {result=false}\n" +" end\n" +" return {\n" +" result=game:catch(id, player)\n" +" }\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:44 +msgid "An easy way to configure and launch nginx would be to create a Docker container based on a `Docker image `_ with nginx and the upstream module already installed (see `http/Dockerfile `_). We take a standard `nginx.conf `_, where we define an upstream with our Tarantool backend running (this is another Docker container, see details below):" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:53 +msgid "upstream tnt {\n" +" server pserver:3301 max_fails=1 fail_timeout=60s;\n" +" keepalive 250000;\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:60 +msgid "and add some Tarantool-specific parameters (see descriptions in the upstream module's `README `_ file):" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:64 +msgid "server {\n" +" server_name tnt_test;\n" +"\n" +" listen 80 default deferred reuseport so_keepalive=on backlog=65535;\n" +"\n" +" location = / {\n" +" root /usr/local/nginx/html;\n" +" }\n" +"\n" +" location /api {\n" +" # answers check infinity timeout\n" +" tnt_read_timeout 60m;\n" +" if ( $request_method = GET ) {\n" +" tnt_method \"map\";\n" +" }\n" +" tnt_http_rest_methods get;\n" +" tnt_http_methods all;\n" +" tnt_multireturn_skip_count 2;\n" +" tnt_pure_result on;\n" +" tnt_pass_http_request on parse_args;\n" +" tnt_pass tnt;\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/creating_app/nginx.rst:90 +msgid "Likewise, we put Tarantool server and all our game logic in a second Docker container based on the `official Tarantool 1.9 image `_ (see `src/Dockerfile `_) and set the container's default command to ``tarantool app.lua``. This is the backend." +msgstr "" diff --git a/locale/en/platform/app/creating_app/non-blockng_io.pot b/locale/en/platform/app/creating_app/non-blockng_io.pot new file mode 100644 index 0000000000..e33307a3e6 --- /dev/null +++ b/locale/en/platform/app/creating_app/non-blockng_io.pot @@ -0,0 +1,146 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:4 +msgid "Non-blocking IO" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:6 +msgid "To test the REST API, we create a new script (`client.lua `_), which is similar to our ``game.lua`` application, but makes HTTP POST and GET requests rather than calling Lua functions:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:11 +msgid "local http = require('curl').http()\n" +"local json = require('json')\n" +"local URI = os.getenv('SERVER_URI')\n" +"local fiber = require('fiber')\n" +"\n" +"local player1 = {\n" +" name=\"Player1\",\n" +" id=1,\n" +" location = {\n" +" x=1.0001,\n" +" y=2.0003\n" +" }\n" +"}\n" +"local player2 = {\n" +" name=\"Player2\",\n" +" id=2,\n" +" location = {\n" +" x=30.123,\n" +" y=40.456\n" +" }\n" +"}\n" +"\n" +"local pokemon = {\n" +" name=\"Pikachu\",\n" +" chance=99.1,\n" +" id=1,\n" +" status=\"active\",\n" +" location = {\n" +" x=1,\n" +" y=2\n" +" }\n" +"}\n" +"\n" +"function request(method, body, id)\n" +" local resp = http:request(\n" +" method, URI, body\n" +" )\n" +" if id ~= nil then\n" +" print(string.format('Player %d result: %s',\n" +" id, resp.body))\n" +" else\n" +" print(resp.body)\n" +" end\n" +"end\n" +"\n" +"local players = {}\n" +"function catch(player)\n" +" fiber.sleep(math.random(5))\n" +" print('Catch pokemon by player ' .. tostring(player.id))\n" +" request(\n" +" 'POST', '{\"method\": \"catch\",\n" +" \"params\": [1, '..json.encode(player)..']}',\n" +" tostring(player.id)\n" +" )\n" +" table.insert(players, player.id)\n" +"end\n" +"\n" +"print('Create pokemon')\n" +"request('POST', '{\"method\": \"add\",\n" +" \"params\": ['..json.encode(pokemon)..']}')\n" +"request('GET', '')\n" +"\n" +"fiber.create(catch, player1)\n" +"fiber.create(catch, player2)\n" +"\n" +"-- wait for players\n" +"while #players ~= 2 do\n" +" fiber.sleep(0.001)\n" +"end\n" +"\n" +"request('GET', '')\n" +"os.exit()" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:86 +msgid "When you run this script, you’ll notice that both players have equal chances to make the first attempt at catching the pokémon. In a classical Lua script, a networked call blocks the script until it’s finished, so the first catch attempt can only be done by the player who entered the game first. In Tarantool, both players play concurrently, since all modules are integrated with Tarantool :ref:`cooperative multitasking ` and use non-blocking I/O." +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:94 +msgid "Indeed, when Player1 makes its first REST call, the script doesn’t block. The fiber running ``catch()`` function on behalf of Player1 issues a non-blocking call to the operating system and yields control to the next fiber, which happens to be the fiber of Player2. Player2’s fiber does the same. When the network response is received, Player1's fiber is activated by Tarantool cooperative scheduler, and resumes its work. All Tarantool :ref:`modules ` use non-blocking I/O and are integrated with Tarantool cooperative scheduler. For module developers, Tarantool provides an :ref:`API `." +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:103 +msgid "For our HTTP test, we create a third container based on the `official Tarantool 1.9 image `_ (see `client/Dockerfile `_) and set the container's default command to ``tarantool client.lua``." +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:111 +msgid "To run this test locally, download our `pokemon `_ project from GitHub and say:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:114 +msgid "$ docker-compose build\n" +"$ docker-compose up" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:119 +msgid "Docker Compose builds and runs all the three containers: ``pserver`` (Tarantool backend), ``phttp`` (nginx) and ``pclient`` (demo client). You can see log messages from all these containers in the console, pclient saying that it made an HTTP request to create a pokémon, made two catch requests, requested the map (empty since the pokémon is caught and temporarily inactive) and exited:" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:125 +msgid "pclient_1 | Create pokemon\n" +"<...>\n" +"pclient_1 | {\"result\":true}\n" +"pclient_1 | {\"map\":[{\"id\":1,\"status\":\"active\",\"location\":{\"y\":2,\"x\":1},\"name\":\"Pikachu\",\"chance\":99.100000}]}\n" +"pclient_1 | Catch pokemon by player 2\n" +"pclient_1 | Catch pokemon by player 1\n" +"pclient_1 | Player 1 result: {\"result\":true}\n" +"pclient_1 | Player 2 result: {\"result\":false}\n" +"pclient_1 | {\"map\":[]}\n" +"pokemon_pclient_1 exited with code 0" +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:138 +msgid "Congratulations! Here's the end point of our walk-through. As further reading, see more about :ref:`installing ` and :ref:`contributing ` a module." +msgstr "" + +#: ../../doc/how-to/app/creating_app/non-blockng_io.rst:142 +msgid "See also reference on :ref:`Tarantool modules ` and :ref:`C API `, and don't miss our :ref:`Lua cookbook recipes `." +msgstr "" diff --git a/locale/en/platform/app/index.pot b/locale/en/platform/app/index.pot new file mode 100644 index 0000000000..4665985635 --- /dev/null +++ b/locale/en/platform/app/index.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/index.rst:4 +msgid "Developing applications with Tarantool" +msgstr "" + +#: ../../doc/how-to/app/index.rst:6 +msgid "Using Tarantool as an application server, you can write your own applications. Tarantool’s native language for writing applications is `Lua `_, so a typical application would be a file that contains your Lua script. But you can also write applications in C or C++." +msgstr "" diff --git a/locale/en/platform/app/launching_app.pot b/locale/en/platform/app/launching_app.pot new file mode 100644 index 0000000000..52703e1beb --- /dev/null +++ b/locale/en/platform/app/launching_app.pot @@ -0,0 +1,245 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/launching_app.rst:5 +msgid "Launching an application" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:7 +msgid "Using Tarantool as an application server, you can write your own applications. Tarantool’s native language for writing applications is `Lua `_, so a typical application would be a file that contains your Lua script. But you can also write applications in C or C++." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:15 +msgid "If you're new to Lua, we recommend going over the interactive Tarantool tutorial before proceeding with this chapter. To launch the tutorial, say ``tutorial()`` in Tarantool console:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:19 +msgid "tarantool> tutorial()\n" +"---\n" +"- |\n" +" Tutorial -- Screen #1 -- Hello, Moon\n" +" ====================================\n" +"\n" +" Welcome to the Tarantool tutorial.\n" +" It will introduce you to Tarantool’s Lua application server\n" +" and database server, which is what’s running what you’re seeing.\n" +" This is INTERACTIVE -- you’re expected to enter requests\n" +" based on the suggestions or examples in the screen’s text.\n" +" <...>" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:34 +msgid "Let's create and launch our first Lua application for Tarantool. Here's a simplest Lua application, the good old \"Hello, world!\":" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:37 +msgid "#!/usr/bin/env tarantool\n" +"print('Hello, world!')" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:42 +msgid "We save it in a file. Let it be ``myapp.lua`` in the current directory." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:44 +msgid "Now let's discuss how we can launch our application with Tarantool." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:50 +msgid "Launching in Docker" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:52 +msgid "If we run Tarantool in a :ref:`Docker container `, the following command will start Tarantool without any application:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:55 +msgid "$ # create a temporary container and run it in interactive mode\n" +"$ docker run --rm -t -i tarantool/tarantool:latest" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:60 +msgid "To run Tarantool with our application, we can say:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:62 +msgid "$ # create a temporary container and\n" +"$ # launch Tarantool with our application\n" +"$ docker run --rm -t -i \\\n" +" -v `pwd`/myapp.lua:/opt/tarantool/myapp.lua \\\n" +" -v /data/dir/on/host:/var/lib/tarantool \\\n" +" tarantool/tarantool:latest tarantool /opt/tarantool/myapp.lua" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:71 +msgid "Here two resources on the host get mounted in the container:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:73 +msgid "our application file (myapp.lua) and" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:74 +msgid "Tarantool data directory (``/data/dir/on/host``)." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:76 +msgid "By convention, the directory for Tarantool application code inside a container is ``/opt/tarantool``, and the directory for data is ``/var/lib/tarantool``." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:83 +msgid "Launching a binary program" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:85 +msgid "If we run Tarantool from a :ref:`package ` or from a :ref:`source build `, we can launch our application:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:89 +msgid "in the script mode," +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:90 +msgid "as a server application, or" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:91 +msgid "as a daemon service." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:93 +msgid "The simplest way is to pass the filename to Tarantool at start:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:95 +#: ../../doc/how-to/app/launching_app.rst:186 +msgid "$ tarantool myapp.lua\n" +"Hello, world!\n" +"$" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:101 +msgid "Tarantool starts, executes our script in the **script mode** and exits." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:103 +msgid "Now let’s turn this script into a **server application**. We use :doc:`box.cfg ` from Tarantool’s built-in Lua module to:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:107 +msgid "launch the database (a database has a persistent on-disk state, which needs to be restored after we start an application) and" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:109 +msgid "configure Tarantool as a server that accepts requests over a TCP port." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:111 +msgid "We also add some simple database logic, using :doc:`space.create() ` and :ref:`create_index() ` to create a space with a primary index. We use the function :doc:`box.once() ` to make sure that our logic will be executed only once when the database is initialized for the first time, so we don't try to create an existing space or index on each invocation of the script:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:119 +msgid "#!/usr/bin/env tarantool\n" +"-- Configure database\n" +"box.cfg {\n" +" listen = 3301\n" +"}\n" +"box.once(\"bootstrap\", function()\n" +" box.schema.space.create('tweedledum')\n" +" box.space.tweedledum:create_index('primary',\n" +" { type = 'TREE', parts = {1, 'unsigned'}})\n" +"end)" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:132 +msgid "Now we launch our application in the same manner as before:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:134 +msgid "$ tarantool myapp.lua\n" +"Hello, world!\n" +"2017-08-11 16:07:14.250 [41436] main/101/myapp.lua C> version 2.1.0-429-g4e5231702\n" +"2017-08-11 16:07:14.250 [41436] main/101/myapp.lua C> log level 5\n" +"2017-08-11 16:07:14.251 [41436] main/101/myapp.lua I> mapping 1073741824 bytes for tuple arena...\n" +"2017-08-11 16:07:14.255 [41436] main/101/myapp.lua I> recovery start\n" +"2017-08-11 16:07:14.255 [41436] main/101/myapp.lua I> recovering from `./00000000000000000000.snap'\n" +"2017-08-11 16:07:14.271 [41436] main/101/myapp.lua I> recover from `./00000000000000000000.xlog'\n" +"2017-08-11 16:07:14.271 [41436] main/101/myapp.lua I> done `./00000000000000000000.xlog'\n" +"2017-08-11 16:07:14.272 [41436] main/102/hot_standby I> recover from `./00000000000000000000.xlog'\n" +"2017-08-11 16:07:14.274 [41436] iproto/102/iproto I> binary: started\n" +"2017-08-11 16:07:14.275 [41436] iproto/102/iproto I> binary: bound to [::]:3301\n" +"2017-08-11 16:07:14.275 [41436] main/101/myapp.lua I> done `./00000000000000000000.xlog'\n" +"2017-08-11 16:07:14.278 [41436] main/101/myapp.lua I> ready to accept requests" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:151 +msgid "This time, Tarantool executes our script and keeps working as a server, accepting TCP requests on port 3301. We can see Tarantool in the current session’s process list:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:155 +msgid "$ ps | grep \"tarantool\"\n" +" PID TTY TIME CMD\n" +"41608 ttys001 0:00.47 tarantool myapp.lua " +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:161 +msgid "But the Tarantool instance will stop if we close the current terminal window. To detach Tarantool and our application from the terminal window, we can launch it in the **daemon mode**. To do so, we add some parameters to ``box.cfg{}``:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:165 +msgid ":ref:`background ` = ``true`` that actually tells Tarantool to work as a daemon service," +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:167 +msgid ":ref:`log ` = ``'dir-name'`` that tells the Tarantool daemon where to store its log file (other log settings are available in Tarantool :ref:`log ` module), and" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:170 +msgid ":ref:`pid_file ` = ``'file-name'`` that tells the Tarantool daemon where to store its pid file." +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:173 +msgid "For example:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:175 +msgid "box.cfg {\n" +" listen = 3301,\n" +" background = true,\n" +" log = '1.log',\n" +" pid_file = '1.pid'\n" +"}" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:184 +msgid "We launch our application in the same manner as before:" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:192 +msgid "Tarantool executes our script, gets detached from the current shell session (you won't see it with ``ps | grep \"tarantool\"``) and continues working in the background as a daemon attached to the global session (with SID = 0):" +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:196 +msgid "$ ps -ef | grep \"tarantool\"\n" +" PID SID TIME CMD\n" +"42178 0 0:00.72 tarantool myapp.lua " +msgstr "" + +#: ../../doc/how-to/app/launching_app.rst:202 +msgid "Now that we have discussed how to create and launch a Lua application for Tarantool, let's dive deeper into programming practices." +msgstr "" diff --git a/locale/en/platform/app/lua_tutorials.pot b/locale/en/platform/app/lua_tutorials.pot new file mode 100644 index 0000000000..6b61a10493 --- /dev/null +++ b/locale/en/platform/app/lua_tutorials.pot @@ -0,0 +1,738 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/lua_tutorials.rst:5 +msgid "Lua tutorials" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:11 +msgid "First steps" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:13 +msgid "If you're new to Lua, we recommend going over the interactive Tarantool tutorial. To launch the tutorial, run the ``tutorial()`` command in the Tarantool console:" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:16 +msgid "tarantool> tutorial()\n" +"---\n" +"- |\n" +" Tutorial -- Screen #1 -- Hello, Moon\n" +" ====================================\n" +"\n" +" Welcome to the Tarantool tutorial.\n" +" It will introduce you to Tarantool’s Lua application server\n" +" and database server, which is what’s running what you’re seeing.\n" +" This is INTERACTIVE -- you’re expected to enter requests\n" +" based on the suggestions or examples in the screen’s text.\n" +" <...>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:35 +msgid "Insert one million tuples with a Lua stored procedure" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:37 +msgid "This is an exercise assignment: “Insert one million tuples. Each tuple should have a constantly-increasing numeric primary-key field and a random alphabetic 10-character string field.”" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:41 +msgid "The purpose of the exercise is to show what Lua functions look like inside Tarantool. It will be necessary to employ the Lua math library, the Lua string library, the Tarantool box library, the Tarantool box.tuple library, loops, and concatenations. It should be easy to follow even for a person who has not used either Lua or Tarantool before. The only requirement is a knowledge of how other programming languages work and a memory of the first two chapters of this manual. But for better understanding, follow the comments and the links, which point to the Lua manual or to elsewhere in this Tarantool manual. To further enhance learning, type the statements in with the tarantool client while reading along." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:53 +msgid "Configure" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:55 +msgid "We are going to use the Tarantool sandbox that was created for our :ref:`\"Getting started\" exercises `. So there is a single space, and a numeric primary key, and a running Tarantool server instance which also serves as a client." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:62 +msgid "Delimiter" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:64 +msgid "In earlier versions of Tarantool, multi-line functions had to be enclosed within \"delimiters\". They are no longer necessary, and so they will not be used in this tutorial. However, they are still supported. Users who wish to use delimiters, or users of older versions of Tarantool, should check the syntax description for :ref:`declaring a delimiter ` before proceeding." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:73 +msgid "Create a function that returns a string" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:75 +msgid "We will start by making a function that returns a fixed string, “Hello world”." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:77 +msgid "function string_function()\n" +" return \"hello world\"\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:83 +msgid "The word \"``function``\" is a Lua keyword -- we're about to go into Lua. The function name is string_function. The function has one executable statement, ``return \"hello world\"``. The string \"hello world\" is enclosed in double quotes here, although Lua doesn't care -- one could use single quotes instead. The word \"``end``\" means “this is the end of the Lua function declaration.” To confirm that the function works, we can say" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:90 +msgid "string_function()" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:94 +msgid "Sending ``function-name()`` means “invoke the Lua function.” The effect is that the string which the function returns will end up on the screen." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:97 +msgid "For more about Lua strings see Lua manual `chapter 2.4 \"Strings\"`_ . For more about functions see Lua manual `chapter 5 \"Functions\"`_." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:103 +#: ../../doc/how-to/app/lua_tutorials.rst:147 +#: ../../doc/how-to/app/lua_tutorials.rst:198 +#: ../../doc/how-to/app/lua_tutorials.rst:254 +#: ../../doc/how-to/app/lua_tutorials.rst:300 +#: ../../doc/how-to/app/lua_tutorials.rst:360 +#: ../../doc/how-to/app/lua_tutorials.rst:453 +msgid "The screen now looks like this:" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:105 +msgid "tarantool> function string_function()\n" +" > return \"hello world\"\n" +" > end\n" +"---\n" +"...\n" +"tarantool> string_function()\n" +"---\n" +"- hello world\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:120 +msgid "Create a function that calls another function and sets a variable" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:122 +msgid "Now that ``string_function`` exists, we can invoke it from another function." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:125 +msgid "function main_function()\n" +" local string_value\n" +" string_value = string_function()\n" +" return string_value\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:133 +msgid "We begin by declaring a variable \"``string_value``\". The word \"``local``\" means that string_value appears only in ``main_function``. If we didn't use \"``local``\" then ``string_value`` would be visible everywhere - even by other users using other clients connected to this server instance! Sometimes that's a very desirable feature for inter-client communication, but not this time." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:139 +msgid "Then we assign a value to ``string_value``, namely, the result of ``string_function()``. Soon we will invoke ``main_function()`` to check that it got the value." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:143 +msgid "For more about Lua variables see Lua manual `chapter 4.2 \"Local Variables and Blocks\"`_ ." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:149 +msgid "tarantool> function main_function()\n" +" > local string_value\n" +" > string_value = string_function()\n" +" > return string_value\n" +" > end\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"- hello world\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:166 +msgid "Modify the function so it returns a one-letter random string" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:168 +msgid "Now that it's a bit clearer how to make a variable, we can change ``string_function()`` so that, instead of returning a fixed literal \"Hello world\", it returns a random letter between 'A' and 'Z'." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:172 +msgid "function string_function()\n" +" local random_number\n" +" local random_string\n" +" random_number = math.random(65, 90)\n" +" random_string = string.char(random_number)\n" +" return random_string\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:182 +msgid "It is not necessary to destroy the old ``string_function()`` contents, they're simply overwritten. The first assignment invokes a random-number function in Lua's math library; the parameters mean “the number must be an integer between 65 and 90.” The second assignment invokes an integer-to-character function in Lua's string library; the parameter is the code point of the character. Luckily the ASCII value of 'A' is 65 and the ASCII value of 'Z' is 90 so the result will always be a letter between A and Z." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:190 +msgid "For more about Lua math-library functions see Lua users \"`Math Library Tutorial `_\". For more about Lua string-library functions see Lua users \"`String Library Tutorial `_\" ." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:195 +msgid "Once again the ``string_function()`` can be invoked from main_function() which can be invoked with ``main_function()``." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:200 +msgid "tarantool> function string_function()\n" +" > local random_number\n" +" > local random_string\n" +" > random_number = math.random(65, 90)\n" +" > random_string = string.char(random_number)\n" +" > return random_string\n" +" > end\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"- C\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:217 +msgid "... Well, actually it won't always look like this because ``math.random()`` produces random numbers. But for the illustration purposes it won't matter what the random string values are." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:223 +msgid "Modify the function so it returns a ten-letter random string" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:225 +msgid "Now that it's clear how to produce one-letter random strings, we can reach our goal of producing a ten-letter string by concatenating ten one-letter strings, in a loop." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:229 +msgid "function string_function()\n" +" local random_number\n" +" local random_string\n" +" random_string = \"\"\n" +" for x = 1,10,1 do\n" +" random_number = math.random(65, 90)\n" +" random_string = random_string .. string.char(random_number)\n" +" end\n" +" return random_string\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:242 +msgid "The words \"for x = 1,10,1\" mean “start with x equals 1, loop until x equals 10, increment x by 1 for each iteration.” The symbol \"..\" means \"concatenate\", that is, add the string on the right of the \"..\" sign to the string on the left of the \"..\" sign. Since we start by saying that random_string is \"\" (a blank string), the end result is that random_string has 10 random letters. Once again the ``string_function()`` can be invoked from ``main_function()`` which can be invoked with ``main_function()``." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:250 +msgid "For more about Lua loops see Lua manual `chapter 4.3.4 \"Numeric for\"`_." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:256 +msgid "tarantool> function string_function()\n" +" > local random_number\n" +" > local random_string\n" +" > random_string = \"\"\n" +" > for x = 1,10,1 do\n" +" > random_number = math.random(65, 90)\n" +" > random_string = random_string .. string.char(random_number)\n" +" > end\n" +" > return random_string\n" +" > end\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"- 'ZUDJBHKEFM'\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:278 +msgid "Make a tuple out of a number and a string" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:280 +msgid "Now that it's clear how to make a 10-letter random string, it's possible to make a tuple that contains a number and a 10-letter random string, by invoking a function in Tarantool's library of Lua functions." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:284 +msgid "function main_function()\n" +" local string_value, t\n" +" string_value = string_function()\n" +" t = box.tuple.new({1, string_value})\n" +" return t\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:293 +msgid "Once this is done, t will be the value of a new tuple which has two fields. The first field is numeric: 1. The second field is a random string. Once again the ``string_function()`` can be invoked from ``main_function()`` which can be invoked with ``main_function()``." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:298 +msgid "For more about Tarantool tuples see Tarantool manual section :ref:`Submodule box.tuple `." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:302 +msgid "tarantool> function main_function()\n" +" > local string_value, t\n" +" > string_value = string_function()\n" +" > t = box.tuple.new({1, string_value})\n" +" > return t\n" +" > end\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"- [1, 'PNPZPCOOKA']\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:320 +msgid "Modify main_function to insert a tuple into the database" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:322 +msgid "Now that it's clear how to make a tuple that contains a number and a 10-letter random string, the only trick remaining is putting that tuple into tester. Remember that tester is the first space that was defined in the sandbox, so it's like a database table." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:327 +msgid "function main_function()\n" +" local string_value, t\n" +" string_value = string_function()\n" +" t = box.tuple.new({1,string_value})\n" +" box.space.tester:replace(t)\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:336 +msgid "The new line here is ``box.space.tester:replace(t)``. The name contains 'tester' because the insertion is going to be to tester. The second parameter is the tuple value. To be perfectly correct we could have said ``box.space.tester:insert(t)`` here, rather than ``box.space.tester:replace(t)``, but \"replace\" means “insert even if there is already a tuple whose primary-key value is a duplicate”, and that makes it easier to re-run the exercise even if the sandbox database isn't empty. Once this is done, tester will contain a tuple with two fields. The first field will be 1. The second field will be a random 10-letter string. Once again the ``string_function(``) can be invoked from ``main_function()`` which can be invoked with ``main_function()``. But ``main_function()`` won't tell the whole story, because it does not return t, it only puts t into the database. To confirm that something got inserted, we'll use a SELECT request." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:350 +msgid "main_function()\n" +"box.space.tester:select{1}" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:355 +msgid "For more about Tarantool insert and replace calls, see Tarantool manual section :ref:`Submodule box.space `, :ref:`space_object:insert() `, and :ref:`space_object:replace() `." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:362 +msgid "tarantool> function main_function()\n" +" > local string_value, t\n" +" > string_value = string_function()\n" +" > t = box.tuple.new({1,string_value})\n" +" > box.space.tester:replace(t)\n" +" > end\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"...\n" +"tarantool> box.space.tester:select{1}\n" +"---\n" +"- - [1, 'EUJYVEECIL']\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:383 +msgid "Modify main_function to insert a million tuples into the database" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:385 +msgid "Now that it's clear how to insert one tuple into the database, it's no big deal to figure out how to scale up: instead of inserting with a literal value = 1 for the primary key, insert with a variable value = between 1 and 1 million, in a loop. Since we already saw how to loop, that's a simple thing. The only extra wrinkle that we add here is a timing function." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:391 +msgid "function main_function()\n" +" local string_value, t\n" +" for i = 1,1000000,1 do\n" +" string_value = string_function()\n" +" t = box.tuple.new({i,string_value})\n" +" box.space.tester:replace(t)\n" +" end\n" +"end\n" +"start_time = os.clock()\n" +"main_function()\n" +"end_time = os.clock()\n" +"'insert done in ' .. end_time - start_time .. ' seconds'" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:406 +msgid "The standard Lua function `os.clock() `_ will return the number of CPU seconds since the start. Therefore, by getting start_time = number of seconds just before the inserting, and then getting end_time = number of seconds just after the inserting, we can calculate (end_time - start_time) = elapsed time in seconds. We will display that value by putting it in a request without any assignments, which causes Tarantool to send the value to the client, which prints it. (Lua's answer to the C ``printf()`` function, which is ``print()``, will also work.)" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:416 +msgid "For more on Lua ``os.clock()`` see Lua manual `chapter 22.1 \"Date and Time\"`_. For more on Lua print() see Lua manual `chapter 5 \"Functions\"`_." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:422 +msgid "Since this is the grand finale, we will redo the final versions of all the necessary requests: the request that created ``string_function()``, the request that created ``main_function()``, and the request that invokes ``main_function()``." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:427 +msgid "function string_function()\n" +" local random_number\n" +" local random_string\n" +" random_string = \"\"\n" +" for x = 1,10,1 do\n" +" random_number = math.random(65, 90)\n" +" random_string = random_string .. string.char(random_number)\n" +" end\n" +" return random_string\n" +"end\n" +"\n" +"function main_function()\n" +" local string_value, t\n" +" for i = 1,1000000,1 do\n" +" string_value = string_function()\n" +" t = box.tuple.new({i,string_value})\n" +" box.space.tester:replace(t)\n" +" end\n" +"end\n" +"start_time = os.clock()\n" +"main_function()\n" +"end_time = os.clock()\n" +"'insert done in ' .. end_time - start_time .. ' seconds'" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:455 +msgid "tarantool> function string_function()\n" +" > local random_number\n" +" > local random_string\n" +" > random_string = \"\"\n" +" > for x = 1,10,1 do\n" +" > random_number = math.random(65, 90)\n" +" > random_string = random_string .. string.char(random_number)\n" +" > end\n" +" > return random_string\n" +" > end\n" +"---\n" +"...\n" +"tarantool> function main_function()\n" +" > local string_value, t\n" +" > for i = 1,1000000,1 do\n" +" > string_value = string_function()\n" +" > t = box.tuple.new({i,string_value})\n" +" > box.space.tester:replace(t)\n" +" > end\n" +" > end\n" +"---\n" +"...\n" +"tarantool> start_time = os.clock()\n" +"---\n" +"...\n" +"tarantool> main_function()\n" +"---\n" +"...\n" +"tarantool> end_time = os.clock()\n" +"---\n" +"...\n" +"tarantool> 'insert done in ' .. end_time - start_time .. ' seconds'\n" +"---\n" +"- insert done in 37.62 seconds\n" +"...\n" +"tarantool>" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:494 +msgid "What has been shown is that Lua functions are quite expressive (in fact one can do more with Tarantool's Lua stored procedures than one can do with stored procedures in some SQL DBMSs), and that it's straightforward to combine Lua-library functions and Tarantool-library functions." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:499 +msgid "What has also been shown is that inserting a million tuples took 37 seconds. The host computer was a Linux laptop. By changing :ref:`wal_mode ` to 'none' before running the test, one can reduce the elapsed time to 4 seconds." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:507 +msgid "Sum a JSON field for all tuples" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:509 +msgid "This is an exercise assignment: “Assume that inside every tuple there is a string formatted as JSON. Inside that string there is a JSON numeric field. For each tuple, find the numeric field's value and add it to a 'sum' variable. At end, return the 'sum' variable.” The purpose of the exercise is to get experience in one way to read and process tuples." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:515 +msgid "json = require('json')\n" +"function sum_json_field(field_name)\n" +" local v, t, sum, field_value, is_valid_json, lua_table\n" +" sum = 0\n" +" for v, t in box.space.tester:pairs() do\n" +" is_valid_json, lua_table = pcall(json.decode, t[2])\n" +" if is_valid_json then\n" +" field_value = lua_table[field_name]\n" +" if type(field_value) == \"number\" then sum = sum + field_value end\n" +" end\n" +" end\n" +" return sum\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:532 +msgid "**LINE 3: WHY \"LOCAL\".** This line declares all the variables that will be used in the function. Actually it's not necessary to declare all variables at the start, and in a long function it would be better to declare variables just before using them. In fact it's not even necessary to declare variables at all, but an undeclared variable is \"global\". That's not desirable for any of the variables that are declared in line 1, because all of them are for use only within the function." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:539 +msgid "**LINE 5: WHY \"PAIRS()\".** Our job is to go through all the rows and there are two ways to do it: with :ref:`box.space.space_object:pairs() ` or with ``variable = select(...)`` followed by :samp:`for i, {n}, 1 do {some-function}(variable[i]) end`. We preferred ``pairs()`` for this example." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:544 +msgid "**LINE 5: START THE MAIN LOOP.** Everything inside this \"``for``\" loop will be repeated as long as there is another index key. A tuple is fetched and can be referenced with variable :code:`t`." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:548 +msgid "**LINE 6: WHY \"PCALL\".** If we simply said ``lua_table = json.decode(t[2]))``, then the function would abort with an error if it encountered something wrong with the JSON string - a missing colon, for example. By putting the function inside \"``pcall``\" (`protected call `_), we're saying: we want to intercept that sort of error, so if there's a problem just set ``is_valid_json = false`` and we will know what to do about it later." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:555 +msgid "**LINE 6: MEANING.** The function is :ref:`json.decode ` which means decode a JSON string, and the parameter is t[2] which is a reference to a JSON string. There's a bit of hard coding here, we're assuming that the second field in the tuple is where the JSON string was inserted. For example, we're assuming a tuple looks like" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:608 +msgid "field[1]: 444\n" +"field[2]: '{\"Hello\": \"world\", \"Quantity\": 15}'" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:566 +msgid "meaning that the tuple's first field, the primary key field, is a number while the tuple's second field, the JSON string, is a string. Thus the entire statement means \"decode ``t[2]`` (the tuple's second field) as a JSON string; if there's an error set ``is_valid_json = false``; if there's no error set ``is_valid_json = true`` and set ``lua_table =`` a Lua table which has the decoded string\"." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:572 +msgid "**LINE 8.** At last we are ready to get the JSON field value from the Lua table that came from the JSON string. The value in field_name, which is the parameter for the whole function, must be a name of a JSON field. For example, inside the JSON string ``'{\"Hello\": \"world\", \"Quantity\": 15}'``, there are two JSON fields: \"Hello\" and \"Quantity\". If the whole function is invoked with ``sum_json_field(\"Quantity\")``, then ``field_value = lua_table[field_name]`` is effectively the same as ``field_value = lua_table[\"Quantity\"]`` or even ``field_value = lua_table.Quantity``. Those are just three different ways of saying: for the Quantity field in the Lua table, get the value and put it in variable :code:`field_value`." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:582 +msgid "**LINE 9: WHY \"IF\".** Suppose that the JSON string is well formed but the JSON field is not a number, or is missing. In that case, the function would be aborted when there was an attempt to add it to the sum. By first checking ``type(field_value) == \"number\"``, we avoid that abortion. Anyone who knows that the database is in perfect shape can skip this kind of thing." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:588 +msgid "And the function is complete. Time to test it. Starting with an empty database, defined the same way as the sandbox database in our :ref:`\"Getting started\" exercises `," +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:592 +msgid "-- if tester is left over from some previous test, destroy it\n" +"box.space.tester:drop()\n" +"box.schema.space.create('tester')\n" +"box.space.tester:create_index('primary', {parts = {1, 'unsigned'}})" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:599 +msgid "then add some tuples where the first field is a number and the second field is a string." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:602 +msgid "box.space.tester:insert{444, '{\"Item\": \"widget\", \"Quantity\": 15}'}\n" +"box.space.tester:insert{445, '{\"Item\": \"widget\", \"Quantity\": 7}'}\n" +"box.space.tester:insert{446, '{\"Item\": \"golf club\", \"Quantity\": \"sunshine\"}'}\n" +"box.space.tester:insert{447, '{\"Item\": \"waffle iron\", \"Quantit\": 3}'}" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:609 +msgid "Since this is a test, there are deliberate errors. The \"golf club\" and the \"waffle iron\" do not have numeric Quantity fields, so must be ignored. Therefore the real sum of the Quantity field in the JSON strings should be: 15 + 7 = 22." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:614 +msgid "Invoke the function with ``sum_json_field(\"Quantity\")``." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:616 +msgid "tarantool> sum_json_field(\"Quantity\")\n" +"---\n" +"- 22\n" +"..." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:623 +msgid "It works. We'll just leave, as exercises for future improvement, the possibility that the \"hard coding\" assumptions could be removed, that there might have to be an overflow check if some field values are huge, and that the function should contain a :ref:`yield ` instruction if the count of tuples is huge." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:632 +msgid "Indexed pattern search" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:634 +msgid "Here is a generic function which takes a field identifier and a search pattern, and returns all tuples that match. |br| * The field must be the first field of a TREE index. |br| * The function will use `Lua pattern matching `_, which allows \"magic characters\" in regular expressions. |br| * The initial characters in the pattern, as far as the first magic character, will be used as an index search key. For each tuple that is found via the index, there will be a match of the whole pattern. |br| * To be :ref:`cooperative `, the function should yield after every 10 tuples, unless there is a reason to delay yielding. |br| With this function, we can take advantage of Tarantool's indexes for speed, and take advantage of Lua's pattern matching for flexibility. It does everything that an SQL :ref:`LIKE ` search can do, and far more." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:652 +msgid "Read the following Lua code to see how it works. The comments that begin with \"SEE NOTE ...\" refer to long explanations that follow the code." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:656 +msgid "function indexed_pattern_search(space_name, field_no, pattern)\n" +" -- SEE NOTE #1 \"FIND AN APPROPRIATE INDEX\"\n" +" if (box.space[space_name] == nil) then\n" +" print(\"Error: Failed to find the specified space\")\n" +" return nil\n" +" end\n" +" local index_no = -1\n" +" for i=0,box.schema.INDEX_MAX,1 do\n" +" if (box.space[space_name].index[i] == nil) then break end\n" +" if (box.space[space_name].index[i].type == \"TREE\"\n" +" and box.space[space_name].index[i].parts[1].fieldno == field_no\n" +" and (box.space[space_name].index[i].parts[1].type == \"scalar\"\n" +" or box.space[space_name].index[i].parts[1].type == \"string\")) then\n" +" index_no = i\n" +" break\n" +" end\n" +" end\n" +" if (index_no == -1) then\n" +" print(\"Error: Failed to find an appropriate index\")\n" +" return nil\n" +" end\n" +" -- SEE NOTE #2 \"DERIVE INDEX SEARCH KEY FROM PATTERN\"\n" +" local index_search_key = \"\"\n" +" local index_search_key_length = 0\n" +" local last_character = \"\"\n" +" local c = \"\"\n" +" local c2 = \"\"\n" +" for i=1,string.len(pattern),1 do\n" +" c = string.sub(pattern, i, i)\n" +" if (last_character ~= \"%\") then\n" +" if (c == '^' or c == \"$\" or c == \"(\" or c == \")\" or c == \".\"\n" +" or c == \"[\" or c == \"]\" or c == \"*\" or c == \"+\"\n" +" or c == \"-\" or c == \"?\") then\n" +" break\n" +" end\n" +" if (c == \"%\") then\n" +" c2 = string.sub(pattern, i + 1, i + 1)\n" +" if (string.match(c2, \"%p\") == nil) then break end\n" +" index_search_key = index_search_key .. c2\n" +" else\n" +" index_search_key = index_search_key .. c\n" +" end\n" +" end\n" +" last_character = c\n" +" end\n" +" index_search_key_length = string.len(index_search_key)\n" +" if (index_search_key_length < 3) then\n" +" print(\"Error: index search key \" .. index_search_key .. \" is too short\")\n" +" return nil\n" +" end\n" +" -- SEE NOTE #3 \"OUTER LOOP: INITIATE\"\n" +" local result_set = {}\n" +" local number_of_tuples_in_result_set = 0\n" +" local previous_tuple_field = \"\"\n" +" while true do\n" +" local number_of_tuples_since_last_yield = 0\n" +" local is_time_for_a_yield = false\n" +" -- SEE NOTE #4 \"INNER LOOP: ITERATOR\"\n" +" for _,tuple in box.space[space_name].index[index_no]:\n" +" pairs(index_search_key,{iterator = box.index.GE}) do\n" +" -- SEE NOTE #5 \"INNER LOOP: BREAK IF INDEX KEY IS TOO GREAT\"\n" +" if (string.sub(tuple[field_no], 1, index_search_key_length)\n" +" > index_search_key) then\n" +" break\n" +" end\n" +" -- SEE NOTE #6 \"INNER LOOP: BREAK AFTER EVERY 10 TUPLES -- MAYBE\"\n" +" number_of_tuples_since_last_yield = number_of_tuples_since_last_yield + 1\n" +" if (number_of_tuples_since_last_yield >= 10\n" +" and tuple[field_no] ~= previous_tuple_field) then\n" +" index_search_key = tuple[field_no]\n" +" is_time_for_a_yield = true\n" +" break\n" +" end\n" +" previous_tuple_field = tuple[field_no]\n" +" -- SEE NOTE #7 \"INNER LOOP: ADD TO RESULT SET IF PATTERN MATCHES\"\n" +" if (string.match(tuple[field_no], pattern) ~= nil) then\n" +" number_of_tuples_in_result_set = number_of_tuples_in_result_set + 1\n" +" result_set[number_of_tuples_in_result_set] = tuple\n" +" end\n" +" end\n" +" -- SEE NOTE #8 \"OUTER LOOP: BREAK, OR YIELD AND CONTINUE\"\n" +" if (is_time_for_a_yield ~= true) then\n" +" break\n" +" end\n" +" require('fiber').yield()\n" +" end\n" +" return result_set\n" +"end" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:747 +msgid "NOTE #1 \"FIND AN APPROPRIATE INDEX\" |br| The caller has passed space_name (a string) and field_no (a number). The requirements are: |br| (a) index type must be \"TREE\" because for other index types (HASH, BITSET, RTREE) a search with :ref:`iterator=GE ` will not return strings in order by string value; |br| (b) field_no must be the first index part; |br| (c) the field must contain strings, because for other data types (such as \"unsigned\") pattern searches are not possible; |br| If these requirements are not met by any index, then print an error message and return nil." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:759 +msgid "NOTE #2 \"DERIVE INDEX SEARCH KEY FROM PATTERN\" |br| The caller has passed pattern (a string). The index search key will be the characters in the pattern as far as the first magic character. Lua's magic characters are % ^ $ ( ) . [ ] * + - ?. For example, if the pattern is \"ABC.E\", the period is a magic character and therefore the index search key will be \"ABC\". But there is a complication ... If we see \"%\" followed by a punctuation character, that punctuation character is \"escaped\" so remove the \"%\" when making the index search key. For example, if the pattern is \"AB%$E\", the dollar sign is escaped and therefore the index search key will be \"AB$E\". Finally there is a check that the index search key length must be at least three -- this is an arbitrary number, and in fact zero would be okay, but short index search keys will cause long search times." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:776 +msgid "NOTE #3 -- \"OUTER LOOP: INITIATE\" |br| The function's job is to return a result set, just as `box.space...select ` would. We will fill it within an outer loop that contains an inner loop. The outer loop's job is to execute the inner loop, and possibly :ref:`yield `, until the search ends. The inner loop's job is to find tuples via the index, and put them in the result set if they match the pattern." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:785 +msgid "NOTE #4 \"INNER LOOP: ITERATOR\" |br| The for loop here is using pairs(), see the :doc:`explanation of what index iterators are `. Within the inner loop, there will be a local variable named \"tuple\" which contains the latest tuple found via the index search key." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:792 +msgid "NOTE #5 \"INNER LOOP: BREAK IF INDEX KEY IS TOO GREAT\" |br| The iterator is GE (Greater or Equal), and we must be more specific: if the search index key has N characters, then the leftmost N characters of the result's index field must not be greater than the search index key. For example, if the search index key is 'ABC', then 'ABCDE' is a potential match, but 'ABD' is a signal that no more matches are possible." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:801 +msgid "NOTE #6 \"INNER LOOP: BREAK AFTER EVERY 10 TUPLES -- MAYBE\" |br| This chunk of code is for cooperative multitasking. The number 10 is arbitrary, and usually a larger number would be okay. The simple rule would be \"after checking 10 tuples, yield, and then resume the search (that is, do the inner loop again) starting after the last value that was found\". However, if the index is non-unique or if there is more than one field in the index, then we might have duplicates -- for example {\"ABC\",1}, {\"ABC\", 2}, {\"ABC\", 3}\" -- and it would be difficult to decide which \"ABC\" tuple to resume with. Therefore, if the result's index field is the same as the previous result's index field, there is no break." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:814 +msgid "NOTE #7 \"INNER LOOP: ADD TO RESULT SET IF PATTERN MATCHES\" |br| Compare the result's index field to the entire pattern. For example, suppose that the caller passed pattern \"ABC.E\" and there is an indexed field containing \"ABCDE\". Therefore the initial index search key is \"ABC\". Therefore a tuple containing an indexed field with \"ABCDE\" will be found by the iterator, because \"ABCDE\" > \"ABC\". In that case string.match will return a value which is not nil. Therefore this tuple can be added to the result set." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:824 +msgid "NOTE #8 \"OUTER LOOP: BREAK, OR YIELD AND CONTINUE\" |br| There are three conditions which will cause a break from the inner loop: (1) the for loop ends naturally because there are no more index keys which are greater than or equal to the index search key, (2) the index key is too great as described in NOTE #5, (3) it is time for a yield as described in NOTE #6. If condition (1) or condition (2) is true, then there is nothing more to do, the outer loop ends too. If and only if condition (3) is true, the outer loop must yield and then continue. If it does continue, then the inner loop -- the iterator search -- will happen again with a new value for the index search key." +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:837 +msgid "EXAMPLE:" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:839 +msgid "Start Tarantool, cut and paste the code for function ``indexed_pattern_search()``, and try the following:" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:890 +msgid "box.space.t:drop()\n" +"box.schema.space.create('t')\n" +"box.space.t:create_index('primary',{})\n" +"box.space.t:create_index('secondary',{unique=false,parts={2,'string',3,'string'}})\n" +"box.space.t:insert{1,'A','a'}\n" +"box.space.t:insert{2,'AB',''}\n" +"box.space.t:insert{3,'ABC','a'}\n" +"box.space.t:insert{4,'ABCD',''}\n" +"box.space.t:insert{5,'ABCDE','a'}\n" +"box.space.t:insert{6,'ABCDE',''}\n" +"box.space.t:insert{7,'ABCDEF','a'}\n" +"box.space.t:insert{8,'ABCDF',''}\n" +"indexed_pattern_search(\"t\", 2, \"ABC.E.\")" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:859 +msgid "The result will be:" +msgstr "" + +#: ../../doc/how-to/app/lua_tutorials.rst:861 +msgid "tarantool> indexed_pattern_search(\"t\", 2, \"ABC.E.\")\n" +"---\n" +"- - [7, 'ABCDEF', 'a']\n" +"..." +msgstr "" diff --git a/locale/en/platform/app/using_ide.pot b/locale/en/platform/app/using_ide.pot new file mode 100644 index 0000000000..02880baf25 --- /dev/null +++ b/locale/en/platform/app/using_ide.pot @@ -0,0 +1,113 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/app/using_ide.rst:5 +msgid "Developing with an IDE" +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:7 +msgid "You can use IntelliJ IDEA as an IDE to develop and debug Lua applications for Tarantool." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:10 +msgid "Download and install the IDE from the `official web-site `_." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:13 +msgid "JetBrains provides specialized editions for particular languages: IntelliJ IDEA (Java), PHPStorm (PHP), PyCharm (Python), RubyMine (Ruby), CLion (C/C++), WebStorm (Web) and others. So, download a version that suits your primary programming language." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:18 +msgid "Tarantool integration is supported for all editions." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:20 +msgid "Configure the IDE:" +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:22 +msgid "Start IntelliJ IDEA." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:23 +msgid "Click ``Configure`` button and select ``Plugins``." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:30 +msgid "Click ``Browse repositories``." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:37 +msgid "Install ``EmmyLua`` plugin." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:41 +msgid "Please don’t be confused with ``Lua`` plugin, which is less powerful than ``EmmyLua``." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:49 +msgid "Restart IntelliJ IDEA." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:50 +msgid "Click ``Configure``, select ``Project Defaults`` and then ``Run Configurations``." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:58 +msgid "Find ``Lua Application`` in the sidebar at the left." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:60 +msgid "In ``Program``, type a path to an installed ``tarantool`` binary." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:62 +msgid "By default, this is ``tarantool`` or ``/usr/bin/tarantool`` on most platforms." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:65 +msgid "If you installed ``tarantool`` from sources to a custom directory, please specify the proper path here." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:73 +msgid "Now IntelliJ IDEA is ready to use with Tarantool." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:75 +msgid "Create a new Lua project." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:82 +msgid "Add a new Lua file, for example ``init.lua``." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:89 +msgid "Write your code, save the file." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:91 +msgid "To run you application, click ``Run -> Run`` in the main menu and select your source file in the list." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:99 +msgid "Or click ``Run -> Debug`` to start debugging." +msgstr "" + +#: ../../doc/how-to/app/using_ide.rst:103 +msgid "To use Lua debugger, please upgrade Tarantool to version 1.7.5-29-gbb6170e4b or later." +msgstr "" diff --git a/locale/en/platform/atomic.pot b/locale/en/platform/atomic.pot new file mode 100644 index 0000000000..9261c71c6d --- /dev/null +++ b/locale/en/platform/atomic.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/atomic.rst:7 +msgid "Transactions" +msgstr "" + +#: ../../doc/concepts/atomic.rst:9 +msgid "Transactions allow users to perform multiple operations atomically." +msgstr "" + +#: ../../doc/concepts/atomic.rst:11 +msgid "For more information on how transactions work in Tarantool, see the following sections:" +msgstr "" diff --git a/locale/en/platform/atomic/thread_model.pot b/locale/en/platform/atomic/thread_model.pot new file mode 100644 index 0000000000..b58679cae0 --- /dev/null +++ b/locale/en/platform/atomic/thread_model.pot @@ -0,0 +1,93 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/atomic/thread_model.rst:4 +msgid "Thread model" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:9 +msgid "Main threads" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:11 +msgid "The thread model assumes that a :ref:`query ` received by Tarantool via network is processed with three operating system **threads**:" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:14 +msgid "The **network thread** (or :ref:`threads `) on the server side receives the query, parses the statement, checks if it is correct, and then transforms it into a special structure -- a message containing an executable statement and its options." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:19 +msgid "The network thread sends this message to the instance's **transaction processor thread** (*TX thread*) via a lock-free message bus. Lua programs are executed directly in the transaction processor thread, and do not need to be parsed and prepared." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:24 +msgid "The TX thread either uses a space index to find and update the tuple, or executes a stored function that performs a data operation." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:27 +msgid "The execution of the operation results in a message to the :ref:`write-ahead logging (WAL) ` thread used to commit the transaction and the fiber executing the transaction is suspended. When the transaction results in a COMMIT or ROLLBACK, the following actions are taken:" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:32 +msgid "The WAL thread responds with a message to the TX thread." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:34 +msgid "The fiber executing the transaction is resumed to process the result of the transaction." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:36 +msgid "The result of the fiber execution is passed to the network thread, and the network thread returns the result to the client." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:42 +msgid "There is only one TX thread in Tarantool. Some users are used to the idea that there can be multiple threads working on the database. For example, thread #1 reads a row #x while thread #2 writes a row #y. With Tarantool this does not happen. Only the TX thread can access the database, and there is only one TX thread for each Tarantool instance." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:50 +msgid "The TX thread can handle many :ref:`fibers ` -- a set of computer instructions that can contain \"**yield**\" signals. The TX thread executes all computer instructions up to a yield signal, and then switches to execute the instructions of another fiber." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:56 +msgid ":ref:`Yields ` must happen, otherwise the TX thread would be permanently stuck on the same fiber." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:63 +msgid "Supplementary threads" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:65 +msgid "There are also several supplementary threads that serve additional capabilities:" +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:67 +msgid "For :ref:`replication `, Tarantool creates a separate thread for each connected replica. This thread reads a write-ahead log and sends it to the replica, following its position in the log. Separate threads are required because each replica can point to a different position in the log and can run at different speeds." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:71 +msgid "There is a thread pool for ad hoc asynchronous tasks, such as a DNS resolver or :ref:`fsync `." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:74 +msgid "There are OpenMP threads used to parallelize sorting (hence, to parallelize building :ref:`indexes `). For example, this is applicable when Tarantool is restoring from a :ref:`snapshot ` with a large amount of data and needs to sort a secondary index if it is ordered by something other than the primary order." +msgstr "" + +#: ../../doc/concepts/atomic/thread_model.rst:82 +msgid "The maximum number of OpenMP threads can be controlled by the ``OMP_NUM_THREADS`` environment variable." +msgstr "" diff --git a/locale/en/platform/atomic/transaction_model.pot b/locale/en/platform/atomic/transaction_model.pot new file mode 100644 index 0000000000..6ba46fab6e --- /dev/null +++ b/locale/en/platform/atomic/transaction_model.pot @@ -0,0 +1,174 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/atomic/transaction_model.rst:4 +msgid "Transaction model" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:11 +msgid "The transaction model of Tarantool corresponds to the properties ACID (atomicity, consistency, isolation, durability)." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:15 +msgid "Tarantool has two modes of transaction behavior:" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:17 +msgid ":ref:`Default ` -- suitable for fast monopolistic atomic transactions" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:19 +msgid ":ref:`MVCC ` -- designed for long-running concurrent transactions" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:22 +msgid "Each transaction in Tarantool is executed in a single fiber on a single thread, sees a consistent database state and commits all changes atomically." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:25 +msgid "All transaction changes are written to the WAL (:ref:`Write Ahead Log `) in a single batch in a specific order at the time of the :doc:`commit `. If needed, transaction changes can also be rolled back -- :doc:`completely ` or to a specified :doc:`savepoint `." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:32 +msgid "Therefore, every transaction in Tarantool has the highest `transaction isolation level `_ -- *serializable*." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:38 +msgid "Isolation level" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:40 +msgid "By :ref:`default `, the isolation level of Tarantool is *serializable*. The exception is a failure during writing to the WAL, which can occur, for example, when the disk space is over. In this case, the isolation level of the concurrent read transaction would be ``read-committed``." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:44 +msgid "The :ref:`MVСС mode ` provides several options that enable you to tune the visibility behavior during transaction execution." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:51 +msgid "Read-committed" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:53 +msgid "The ``read-committed`` isolation level makes visible all transactions that started commit (:ref:`box.commit() ` was called)." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:55 +msgid "*Write transactions with reads*" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:57 +msgid "Manual usage of ``read-committed`` for write transactions with reads is completely safe, as this transaction will eventually result in a commit. If a previous transactions fails, this transaction will inevitably fail as well due to the *serializable* isolation level." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:60 +#: ../../doc/concepts/atomic/transaction_model.rst:74 +msgid "*Read transactions*" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:62 +msgid "Manual usage of ``read-committed`` for read transactions may be unsafe, as it may lead to phantom reads." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:68 +msgid "Read-confirmed" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:70 +msgid "The ``read-confirmed`` isolation level makes visible all transactions that finished the commit (:ref:`box.commit() ` was returned). This means that new data is already on disk or even on other replicas." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:76 +msgid "The use of ``read-confirmed`` is safe for read transactions given that data is on disk (for asynchronous replication) or even in other replicas (for synchronous replication)." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:80 +msgid "*Write transactions*" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:82 +msgid "To achieve *serializable*, any write transaction should read all data that has already been committed. Otherwise, it may conflict when it reaches its commit." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:90 +msgid "Linearizable read" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:92 +msgid "Linearizability of read operations implies that if a response for a write request arrived earlier than a read request was made, this read request should return the results of the write request. When called with ``linearizable``, :ref:`box.begin() ` yields until the instance receives enough data from remote peers to be sure that the transaction is linearizable." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:95 +msgid "Linearizable transactions may only perform requests to the following memtx space types:" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:97 +msgid ":ref:`synchronous `" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:98 +msgid "local (:doc:`created ` with ``is_local = true``)" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:99 +msgid "temporary (:doc:`created ` with ``temporary = true``)" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:101 +msgid "A linearizable transaction can fail with an error in the following cases:" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:103 +msgid "If the node can't contact enough remote peers to determine which data is committed." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:104 +msgid "If the data isn't received during the ``timeout`` specified in ``box.begin()``." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:108 +msgid "To start a linearizable transaction, the node should be the replication source for at least ``N - Q + 1`` remote replicas. Here ``N`` is the count of registered nodes in the cluster and ``Q`` is :ref:`replication_synchro_quorum `. So, for example, you can't perform a linearizable transaction on anonymous replicas because they can't be the source of replication for other nodes." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:116 +msgid "Best-effort (default)" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:118 +msgid "To minimize the possibility of conflicts, MVCC uses what is called ``best-effort`` visibility:" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:120 +msgid "for write transactions, MVCC chooses :ref:`read-committed `" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:121 +msgid "for read transactions, MVCC chooses :ref:`read-confirmed `" +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:123 +msgid "This inevitably leads to the *serializable* isolation level. Since there is no option for MVCC to analyze the whole transaction to make a decision, it makes the choice on the first operation." +msgstr "" + +#: ../../doc/concepts/atomic/transaction_model.rst:129 +msgid "If the *serializable* isolation level becomes unreachable, the transaction is marked as \"conflicted\" and rolled back." +msgstr "" diff --git a/locale/en/platform/atomic/txn_mode_default.pot b/locale/en/platform/atomic/txn_mode_default.pot new file mode 100644 index 0000000000..c611fd3282 --- /dev/null +++ b/locale/en/platform/atomic/txn_mode_default.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:4 +msgid "Transaction mode: default" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:6 +msgid "By default, Tarantool does not allow :ref:`\"yielding\" ` inside a :ref:`memtx ` transaction and the :ref:`transaction manager ` is disabled. This allows fast atomic transactions without conflicts, but brings some limitations:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:10 +msgid "You cannot use :ref:`interactive transactions `." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:12 +msgid "Any fiber yield leads to the abort of a transaction." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:14 +msgid "All changes are made immediately, but in the event of a yield or error, the transaction is rolled back, including the return of the previous data." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:18 +msgid "To learn how to enable yielding inside a :ref:`memtx ` transaction, see :ref:`Transaction mode: MVCC `." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:20 +msgid "To switch back to the default mode, disable the transaction manager:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_default.rst:22 +msgid "box.cfg { memtx_use_mvcc_engine = false }" +msgstr "" diff --git a/locale/en/platform/atomic/txn_mode_mvcc.pot b/locale/en/platform/atomic/txn_mode_mvcc.pot new file mode 100644 index 0000000000..800b5275fc --- /dev/null +++ b/locale/en/platform/atomic/txn_mode_mvcc.pot @@ -0,0 +1,318 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:4 +msgid "Transaction mode: MVCC" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:6 +msgid "Since version :doc:`2.6.1 `, Tarantool has another transaction behavior mode that allows :ref:`\"yielding\" ` inside a :ref:`memtx ` transaction. This is controlled by the *transaction manager*." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:12 +msgid "This mode allows concurrent transactions but may cause conflicts. You can use this mode on the :ref:`memtx ` storage engine. The :ref:`vinyl ` storage engine also supports MVCC mode, but has a different implementation." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:19 +msgid "Currently, you cannot use several different storage engines within one transaction." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:24 +msgid "Transaction manager" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:26 +msgid "The transaction manager is designed to isolate concurrent transactions and provides a *serializable* `transaction isolation level `_. It consists of two parts:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:31 +msgid "*MVCC* -- multi version concurrency control engine, which stores all change actions of all transactions. It also creates the transaction view of the database state and a read view (a fixed state of the database that is never changed by other transactions) when necessary." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:36 +msgid "*Conflict manager* -- a manager that tracks changes to transactions and determines their correctness in the serialization order. The conflict manager declares transactions to be in conflict or sends transactions to read views when necessary." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:40 +msgid "Since version :doc:`2.10.1 `, the conflict manager detects conflicts right after the first one of several conflicting transactions is committed. After this moment, any CRUD operations in the conflicted transaction will result in errors until the transaction is rolled back." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:45 +msgid "The transaction manager also provides a non-classical *snapshot* isolation level -- this snapshot is not necessarily tied to the start time of the transaction, like the classical snapshot where a transaction can get a consistent snapshot of the database. The conflict manager decides if and when each transaction gets which snapshot. This avoids some conflicts compared to the classic snapshot isolation approach." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:52 +msgid "Currently, the :ref:`isolation level ` of BITSET and RTREE indexes in MVCC transaction mode is *read-committed* (not *serializable*, as stated). If a transaction uses these indexes, it can read committed or confirmed data (depending on the isolation level). However, the indexes are subject to different anomalies that can make them unserializable." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:60 +msgid "Enabling the transaction manager" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:62 +msgid "By default, the transaction manager is disabled. Use the :ref:`memtx_use_mvcc_engine ` option to enable it via ``box.cfg``." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:65 +msgid "box.cfg{memtx_use_mvcc_engine = true}" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:73 +msgid "Setting the transaction isolation level" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:75 +msgid "The transaction manager has the following options for the :ref:`transaction isolation level `:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:77 +msgid "``best-effort`` (default)" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:79 +msgid "``read-committed``" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:81 +msgid "``read-confirmed``" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:83 +msgid "``linearizable`` (only for a specific transaction)" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:85 +msgid "Using ``best-effort`` as the default option allows MVCC to consider the actions of transactions independently and determine the best :ref:`isolation level ` for them. It increases the probability of successful completion of the transaction and helps to avoid possible conflicts." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:89 +msgid "To set another default isolation level, for example, ``read-committed``, use the following command:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:91 +msgid "box.cfg { txn_isolation = 'read-committed' }" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:95 +msgid "Note that the ``linearizable`` isolation level can't be set as default and can be used for a specific transaction only. You can set an isolation level for a specific transaction in its ``box.begin()`` call:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:98 +msgid "box.begin({ tnx_isolation = 'best-effort' })" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:102 +msgid "In this case, you can also use the ``default`` option. It sets the transaction's isolation level to the one set in ``box.cfg``." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:107 +msgid "For autocommit transactions (actions with a statement without explicit ``box.begin/box.commit`` calls) there is a rule:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:110 +msgid "Read-only transactions (for example, ``select``) are performed with ``read-confirmed``." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:111 +msgid "All other transactions (for example, ``replace``) are performed with ``read-committed``." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:113 +msgid "You can also set the isolation level in the net.box :ref:`stream:begin() ` method and :ref:`IPROTO_BEGIN ` binary protocol request." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:116 +msgid "Choosing the better option depends on whether you have conflicts or not. If you have many conflicts, you should set a different option or use the :ref:`default transaction mode `." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:123 +msgid "Examples with MVCC enabled and disabled" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:125 +msgid "Create a file ``init.lua``, containing the following:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:127 +msgid "fiber = require 'fiber'\n" +"\n" +"box.cfg{ listen = '127.0.0.1:3301', memtx_use_mvcc_engine = false }\n" +"box.schema.user.grant('guest', 'super', nil, nil, {if_not_exists = true})\n" +"\n" +"tickets = box.schema.create_space('tickets', { if_not_exists = true })\n" +"tickets:format({\n" +" { name = \"id\", type = \"number\" },\n" +" { name = \"place\", type = \"number\" },\n" +"})\n" +"tickets:create_index('primary', {\n" +" parts = { 'id' },\n" +" if_not_exists = true\n" +"})" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:144 +msgid "Connect to the instance using the :ref:`tt connect ` command:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:146 +msgid "tt connect 127.0.0.1:3301" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:150 +msgid "Then try to execute the transaction with yield inside:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:152 +msgid "box.atomic(function() tickets:replace{1, 429} fiber.yield() tickets:replace{2, 429} end)" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:157 +msgid "You will receive an error message:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:159 +msgid "---\n" +"- error: Transaction has been aborted by a fiber yield\n" +"..." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:165 +msgid "Also, if you leave a transaction open while returning from a request, you will get an error message:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:167 +msgid "127.0.0.1:3301> box.begin()\n" +" ⨯ Failed to execute command: Transaction is active at return from function" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:172 +msgid "Change ``memtx_use_mvcc_engine`` to ``true``, restart Tarantool, and try again:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:174 +msgid "127.0.0.1:3301> box.atomic(function() tickets:replace{1, 429} fiber.yield() tickets:replace{2, 429} end)\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:180 +msgid "Now check if this transaction was successful:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:182 +msgid "127.0.0.1:3301> box.space.tickets:select({}, {limit = 10})\n" +"---\n" +"- - [1, 429]\n" +" - [2, 429]\n" +"..." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:194 +msgid "Streams and interactive transactions" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:196 +msgid "Since :tarantool-release:`2.10.0`, IPROTO implements streams and interactive transactions that can be used when :ref:`memtx_use_mvcc_engine ` is enabled on the server." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:204 +msgid "Stream" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:206 +msgid "A *stream* supports multiplexing several transactions over one connection. Each stream has its own identifier, which is unique within the connection. All requests with the same non-zero stream ID belong to the same stream. All requests in a stream are executed strictly sequentially. This allows the implementation of :ref:`interactive transactions `. If the stream ID of a request is ``0``, it does not belong to any stream and is processed in the old way." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:215 +msgid "In :doc:`net.box `, a stream is an object above the connection that has the same methods but allows sequential execution of requests. The ID is automatically generated on the client side. If a user writes their own connector and wants to use streams, they must transmit the ``stream_id`` over the :ref:`IPROTO protocol `." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:221 +msgid "Unlike a thread, which involves multitasking and execution within a program, a stream transfers data via the protocol between a client and a server." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:228 +msgid "Interactive transaction" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:230 +msgid "An *interactive transaction* is one that does not need to be sent in a single request. There are multiple ways to begin, commit, and roll back a transaction, and they can be mixed. You can use :ref:`stream:begin() `, :ref:`stream:commit() `, :ref:`stream:rollback() ` or the appropriate stream methods -- ``call``, ``eval``, or ``execute`` -- using the SQL transaction syntax." +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:237 +msgid "Let’s create a Lua client (``client.lua``) and run it with Tarantool:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:239 +msgid "local net_box = require 'net.box'\n" +"local conn = net_box.connect('127.0.0.1:3301')\n" +"local conn_tickets = conn.space.tickets\n" +"local yaml = require 'yaml'\n" +"\n" +"local stream = conn:new_stream()\n" +"local stream_tickets = stream.space.tickets\n" +"\n" +"-- Begin transaction over an iproto stream:\n" +"stream:begin()\n" +"print(\"Replaced in a stream\\n\".. yaml.encode( stream_tickets:replace({1, 768}) ))\n" +"\n" +"-- Empty select, the transaction was not committed.\n" +"-- You can't see it from the requests that do not belong to the\n" +"-- transaction.\n" +"print(\"Selected from outside of transaction\\n\".. yaml.encode(conn_tickets:select({}, {limit = 10}) ))\n" +"\n" +"-- Select returns the previously inserted tuple\n" +"-- because this select belongs to the transaction:\n" +"print(\"Selected from within transaction\\n\".. yaml.encode(stream_tickets:select({}, {limit = 10}) ))\n" +"\n" +"-- Commit transaction:\n" +"stream:commit()\n" +"\n" +"-- Now this select also returns the tuple because the transaction has been committed:\n" +"print(\"Selected again from outside of transaction\\n\".. yaml.encode(conn_tickets:select({}, {limit = 10}) ))\n" +"\n" +"os.exit()" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:270 +msgid "Then call it and see the following output:" +msgstr "" + +#: ../../doc/concepts/atomic/txn_mode_mvcc.rst:272 +msgid "Replaced in a stream\n" +"--- [1, 768]\n" +"...\n" +"\n" +"Selected from outside of transaction\n" +"---\n" +"- [1, 429]\n" +"- [2, 429]\n" +"...\n" +"\n" +"Selected from within transaction\n" +"---\n" +"- [1, 768]\n" +"- [2, 429]\n" +"...\n" +"\n" +"Selected again from outside of transaction\n" +"---\n" +"- [1, 768]\n" +"- [2, 429]\n" +"...```" +msgstr "" diff --git a/locale/en/platform/concepts.pot b/locale/en/platform/concepts.pot new file mode 100644 index 0000000000..5cc812b66c --- /dev/null +++ b/locale/en/platform/concepts.pot @@ -0,0 +1,157 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/index.rst:6 +msgid "Concepts" +msgstr "" + +#: ../../doc/concepts/index.rst:9 +msgid "Data model" +msgstr "" + +#: ../../doc/concepts/index.rst:11 +msgid "Tarantool is a NoSQL database. It stores data in :ref:`spaces `, which can be thought of as tables in a relational database, and :ref:`tuples `, which are analogous to rows. There are six basic :ref:`data operations ` in Tarantool." +msgstr "" + +#: ../../doc/concepts/index.rst:15 +msgid "The platform allows :ref:`describing the data schema ` but does not require it." +msgstr "" + +#: ../../doc/concepts/index.rst:17 +msgid "Tarantool supports highly customizable :ref:`indexes ` of various types." +msgstr "" + +#: ../../doc/concepts/index.rst:19 +msgid "To ensure :ref:`data persistence ` and recover quickly in case of failure, Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots." +msgstr "" + +#: ../../doc/concepts/index.rst:22 +msgid "For details, check the :ref:`Data model ` page." +msgstr "" + +#: ../../doc/concepts/index.rst:25 +msgid "Fibers and cooperative multitasking" +msgstr "" + +#: ../../doc/concepts/index.rst:27 +msgid "Tarantool executes code in :ref:`fibers ` that are managed via :ref:`cooperative multitasking `. Learn more about Tarantool's :ref:`thread model `." +msgstr "" + +#: ../../doc/concepts/index.rst:31 +msgid "For details, check the page :ref:`Fibers, yields, and cooperative multitasking `." +msgstr "" + +#: ../../doc/concepts/index.rst:34 +msgid "Transactions" +msgstr "" + +#: ../../doc/concepts/index.rst:36 +msgid "Tarantool's ACID-compliant :ref:`transaction model ` lets the user choose between two modes of transactions." +msgstr "" + +#: ../../doc/concepts/index.rst:39 +msgid "The :ref:`default mode ` allows for fast monopolistic atomic transactions. It doesn't support interactive transactions, and in case of an error, all transaction changes are rolled back." +msgstr "" + +#: ../../doc/concepts/index.rst:42 +msgid "The :ref:`MVCC mode ` relies on a multi-version concurrency control engine that allows yielding within a longer transaction. This mode only works with the default in-memory :ref:`memtx ` storage engine." +msgstr "" + +#: ../../doc/concepts/index.rst:46 +msgid "For details, check the :ref:`Transactions ` page." +msgstr "" + +#: ../../doc/concepts/index.rst:51 +msgid "Application server" +msgstr "" + +#: ../../doc/concepts/index.rst:53 +msgid "Using Tarantool as an application server, you can write applications in Lua, C, or C++. You can also create reusable :ref:`modules `." +msgstr "" + +#: ../../doc/concepts/index.rst:56 +msgid "To increase the speed of code execution, Tarantool has a Lua Just-In-Time compiler (LuaJIT) on board. LuaJIT compiles hot paths in the code -- paths that are used many times -- thus making the application work faster. To enable developers to work with LuaJIT, Tarantool provides tools like the :ref:`memory profiler ` and the :ref:`getmetrics ` module." +msgstr "" + +#: ../../doc/concepts/index.rst:62 +msgid "For details on Tarantool's modular structure, check the :ref:`Modules ` page." +msgstr "" + +#: ../../doc/concepts/index.rst:64 +msgid "To learn how to use Tarantool as an application server, refer to the :ref:`guides ` in the How-to section." +msgstr "" + +#: ../../doc/concepts/index.rst:67 +msgid "Sharding" +msgstr "" + +#: ../../doc/concepts/index.rst:69 +msgid "Tarantool implements database sharding via the ``vshard`` module. For details, go to the :ref:`Sharding ` page." +msgstr "" + +#: ../../doc/concepts/index.rst:73 +msgid "Triggers" +msgstr "" + +#: ../../doc/concepts/index.rst:75 +msgid "Tarantool allows specifying callback functions that run upon certain database events. They can be useful for resolving replication conflicts. For details, go to the :ref:`Triggers ` page." +msgstr "" + +#: ../../doc/concepts/index.rst:80 +msgid "Replication" +msgstr "" + +#: ../../doc/concepts/index.rst:82 +msgid "Replication allows keeping the data in copies of the same database for better reliability." +msgstr "" + +#: ../../doc/concepts/index.rst:84 +msgid "Several Tarantool instances can be organized in a replica set. They communicate and transfer data via the :ref:`iproto ` binary protocol. Learn more about Tarantool's :ref:`replication architecture `." +msgstr "" + +#: ../../doc/concepts/index.rst:88 +msgid "By default, replication in Tarantool is asynchronous. A transaction committed locally on the master node may not get replicated onto other instances before the client receives a success response. Thus, if the master reports success and then dies, the client might not see the result of the transaction." +msgstr "" + +#: ../../doc/concepts/index.rst:93 +msgid "With :ref:`synchronous replication `, transactions on the master node are not considered committed or successful before they are replicated onto a number of instances. This is slower, but more reliable. Synchronous replication in Tarantool is based on an :ref:`implementation of the RAFT algorithm `." +msgstr "" + +#: ../../doc/concepts/index.rst:97 +msgid "For details, check the :ref:`Replication ` section." +msgstr "" + +#: ../../doc/concepts/index.rst:100 +msgid "Storage engines" +msgstr "" + +#: ../../doc/concepts/index.rst:102 +msgid "A storage engine is a set of low-level routines that store and retrieve values. Tarantool offers a choice of two storage engines:" +msgstr "" + +#: ../../doc/concepts/index.rst:105 +msgid ":ref:`memtx ` is the in-memory storage engine used by default." +msgstr "" + +#: ../../doc/concepts/index.rst:106 +msgid ":ref:`vinyl ` is the on-disk storage engine." +msgstr "" + +#: ../../doc/concepts/index.rst:108 +msgid "For details, check the :ref:`Storage engines ` section." +msgstr "" diff --git a/locale/en/platform/data_model/index.pot b/locale/en/platform/data_model/index.pot new file mode 100644 index 0000000000..9ea0889796 --- /dev/null +++ b/locale/en/platform/data_model/index.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/index.rst:4 +msgid "Data model" +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:6 +msgid "If you tried to create a database as suggested in our :ref:`basic tutorial `, then your test database now looks like this:" +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:12 +msgid "Tarantool stores data in :ref:`spaces `, which can be thought of as tables in a relational database. Every record or row in a space is called a :ref:`tuple `. A tuple may have any number of fields, and the fields may be of different :ref:`types `." +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:16 +msgid "String data in fields are compared based on the specified :ref:`collation ` rules. The user can provide hard limits for data values through :ref:`constraints ` and link related spaces with :ref:`foreign keys `." +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:20 +msgid "Tarantool supports highly customizable :ref:`indexes ` of various types. In particular, indexes can be defined with generators like :ref:`sequences `." +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:23 +msgid "There are six basic :ref:`data operations ` in Tarantool: SELECT, INSERT, UPDATE, UPSERT, REPLACE, and DELETE. A number of :ref:`complexity factors ` affects the resource usage of each function." +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:27 +msgid "Tarantool allows :ref:`describing the data schema ` but does not require it. The user can :ref:`migrate a schema ` without migrating the data." +msgstr "" + +#: ../../doc/concepts/data_model/index.rst:30 +msgid "To ensure :ref:`data persistence ` and recover quickly in case of failure, Tarantool uses mechanisms like the write-ahead log (WAL) and snapshots." +msgstr "" diff --git a/locale/en/platform/data_model/indexes.pot b/locale/en/platform/data_model/indexes.pot new file mode 100644 index 0000000000..01c3a1a9df --- /dev/null +++ b/locale/en/platform/data_model/indexes.pot @@ -0,0 +1,696 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/indexes.rst:5 +msgid "Indexes" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:8 +msgid "Basics" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:10 +msgid "An **index** is a special data structure that stores a group of key values and pointers. It is used for efficient manipulations with data." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:13 +msgid "As with spaces, you should specify the index **name** and let Tarantool come up with a unique **numeric identifier** (\"index id\")." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:16 +msgid "An index always has a **type**. The default index type is :ref:`TREE `. TREE indexes are provided by all Tarantool engines, can index unique and non-unique values, support partial key searches, comparisons, and ordered results. Additionally, the memtx engine supports :ref:`HASH `, :ref:`RTREE ` and :ref:`BITSET ` indexes." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:22 +msgid "An index may be **multi-part**, that is, you can declare that an index key value is composed of two or more fields in the tuple, in any order. For example, for an ordinary TREE index, the maximum number of parts is 255." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:26 +msgid "An index may be **unique**, that is, you can declare that it would be illegal to have the same key value twice." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:29 +msgid "The first index defined on a space is called the **primary key index**, and it must be unique. All other indexes are called **secondary indexes**, and they may be non-unique." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:33 +msgid "Indexes have certain limitations. See details on page :doc:`Limitations `." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:36 +msgid "To create a generator for indexes, you can use a sequence object. Learn how to do it in the :ref:`tutorial `." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:42 +msgid "Indexed field types" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:44 +msgid "Not to be confused with :ref:`index types ` -- the types of the data structure that is an index. See more about index types :ref:`below `." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:47 +msgid "Indexes restrict values that Tarantool can store with MsgPack. This is why, for example, ``'unsigned'`` and ``'integer'`` are different field types, although in MsgPack they are both stored as integer values. An ``'unsigned'`` index contains only *non-negative* integer values, while an ``‘integer’`` index contains *any* integer values." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:53 +msgid "The default field type is ``'unsigned'`` and the default index type is TREE. Although ``'nil'`` is not a legal indexed field type, indexes may contain `nil` :ref:`as a non-default option `." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:57 +msgid "To learn more about field types, check the :ref:`Field type details ` section." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:66 +msgid "Field type name string" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:67 +msgid "Field type" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:68 +msgid "Index type" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:69 +msgid "``'boolean'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:70 +#: ../../doc/concepts/data_model/indexes.rst:71 +msgid ":ref:`boolean `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:72 +msgid "``'integer'`` (may also be called ``'int'``)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:73 +msgid ":ref:`integer `, which may include unsigned values" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:74 +#: ../../doc/concepts/data_model/indexes.rst:80 +#: ../../doc/concepts/data_model/indexes.rst:85 +#: ../../doc/concepts/data_model/indexes.rst:88 +#: ../../doc/concepts/data_model/indexes.rst:97 +#: ../../doc/concepts/data_model/indexes.rst:120 +msgid "TREE or HASH" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:75 +msgid "``'unsigned'`` (may also be called ``'uint'`` or ``'num'``, but ``'num'`` is deprecated)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:76 +msgid ":ref:`unsigned `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:77 +#: ../../doc/concepts/data_model/indexes.rst:91 +msgid "TREE, BITSET, or HASH" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:78 +msgid "``'double'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:79 +msgid ":ref:`double `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:81 +msgid "``'number'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:82 +msgid ":ref:`number `, which may include :ref:`integer `, :ref:`double `, or :ref:`decimal ` values" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:86 +msgid "``'decimal'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:87 +msgid ":ref:`decimal `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:89 +msgid "``'string'`` (may also be called ``'str'``)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:90 +msgid ":ref:`string `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:92 +msgid "``'varbinary'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:93 +msgid ":ref:`varbinary `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:94 +msgid "TREE, HASH, or BITSET (since version :doc:`2.7.1 `)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:95 +msgid "``'uuid'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:96 +msgid ":ref:`uuid `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:98 +msgid "``datetime``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:99 +msgid ":ref:`datetime `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:100 +#: ../../doc/concepts/data_model/indexes.rst:138 +msgid "TREE" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:101 +msgid "``'array'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:102 +msgid ":ref:`array `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:103 +msgid ":ref:`RTREE `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:104 +msgid "``'scalar'``" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:105 +msgid "may include :ref:`nil `, :ref:`boolean `, :ref:`integer `, :ref:`unsigned `, :ref:`number `, :ref:`decimal `, :ref:`string `, :ref:`varbinary `, or :ref:`uuid ` values | |br| When a scalar field contains values of different underlying types, the key order is: nils, then booleans, then numbers, then strings, then varbinaries, then uuids." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:125 +msgid "Index types" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:127 +msgid "An index always has a **type**. Different types are intended for different usage scenarios." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:130 +msgid "We give an overview of index features in the following table:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:137 +msgid "Feature" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:139 +msgid "HASH" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:140 +msgid "RTREE" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:141 +msgid "BITSET" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:143 +msgid "unique" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:144 +#: ../../doc/concepts/data_model/indexes.rst:145 +#: ../../doc/concepts/data_model/indexes.rst:150 +#: ../../doc/concepts/data_model/indexes.rst:152 +#: ../../doc/concepts/data_model/indexes.rst:153 +#: ../../doc/concepts/data_model/indexes.rst:156 +#: ../../doc/concepts/data_model/indexes.rst:162 +#: ../../doc/concepts/data_model/indexes.rst:163 +#: ../../doc/concepts/data_model/indexes.rst:168 +#: ../../doc/concepts/data_model/indexes.rst:174 +#: ../../doc/concepts/data_model/indexes.rst:180 +#: ../../doc/concepts/data_model/indexes.rst:181 +#: ../../doc/concepts/data_model/indexes.rst:186 +#: ../../doc/concepts/data_model/indexes.rst:192 +msgid "\\+" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:146 +#: ../../doc/concepts/data_model/indexes.rst:147 +#: ../../doc/concepts/data_model/indexes.rst:151 +#: ../../doc/concepts/data_model/indexes.rst:157 +#: ../../doc/concepts/data_model/indexes.rst:158 +#: ../../doc/concepts/data_model/indexes.rst:159 +#: ../../doc/concepts/data_model/indexes.rst:164 +#: ../../doc/concepts/data_model/indexes.rst:165 +#: ../../doc/concepts/data_model/indexes.rst:169 +#: ../../doc/concepts/data_model/indexes.rst:170 +#: ../../doc/concepts/data_model/indexes.rst:171 +#: ../../doc/concepts/data_model/indexes.rst:175 +#: ../../doc/concepts/data_model/indexes.rst:176 +#: ../../doc/concepts/data_model/indexes.rst:177 +#: ../../doc/concepts/data_model/indexes.rst:182 +#: ../../doc/concepts/data_model/indexes.rst:183 +#: ../../doc/concepts/data_model/indexes.rst:187 +#: ../../doc/concepts/data_model/indexes.rst:188 +#: ../../doc/concepts/data_model/indexes.rst:189 +#: ../../doc/concepts/data_model/indexes.rst:193 +#: ../../doc/concepts/data_model/indexes.rst:194 +#: ../../doc/concepts/data_model/indexes.rst:195 +msgid "\\-" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:149 +msgid "non-unique" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:155 +msgid ":ref:`is_nullable `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:161 +msgid "can be multi-part" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:167 +msgid ":ref:`multikey `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:173 +msgid ":ref:`partial-key search `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:179 +msgid "can be primary key" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:185 +msgid "``exclude_null`` (version 2.8+)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:191 +msgid "Pagination (the :ref:`after ` option)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:197 +msgid ":doc:`iterator types `" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:198 +msgid "ALL, EQ, REQ, GT, GE, LT, LE" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:199 +msgid "ALL, EQ" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:200 +msgid "ALL, EQ, GT, GE, LT, LE, OVERLAPS, NEIGHBOR" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:201 +msgid "ALL, EQ, BITS_ALL_SET, BITS_ANY_SET, BITS_ALL_NOT_SET" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:205 +msgid "In :doc:`2.11.0 `, the ``GT`` index type is deprecated for HASH indexes." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:210 +msgid "TREE indexes" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:212 +msgid "The default index type is 'TREE'. TREE indexes are provided by memtx and vinyl engines, can index unique and non-unique values, support partial key searches, comparisons and ordered results." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:216 +msgid "This is a universal type of indexes, for most cases it will be the best choice." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:218 +msgid "Additionally, memtx engine supports HASH, RTREE and BITSET indexes." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:223 +msgid "HASH indexes" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:225 +msgid "HASH indexes require unique fields and loses to TREE in almost all respects. So we do not recommend to use it in the applications. HASH is now present in Tarantool mainly because of backward compatibility." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:229 +msgid "Here are some tips. Do not use HASH index:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:231 +msgid "just if you want to" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:232 +msgid "if you think that HASH is faster with no performance metering" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:233 +msgid "if you want to iterate over the data" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:234 +msgid "for primary key" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:235 +msgid "as an only index" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:237 +msgid "Use HASH index:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:239 +msgid "if it is a secondary key" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:240 +msgid "if you 100% won't need to make it non-unique" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:241 +msgid "if you have taken measurements on your data and you see an accountable increase in performance" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:243 +msgid "if you save every byte on tuples (HASH is a little more compact)" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:248 +msgid "RTREE indexes" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:250 +msgid "RTREE is a multidimensional index supporting up to 20 dimensions. It is used especially for indexing spatial information, such as geographical objects. In :ref:`this example ` we demonstrate spatial searches via RTREE index." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:255 +msgid "RTREE index could not be primary, and could not be unique. The option list of this type of index may contain ``dimension`` and ``distance`` options. The ``parts`` definition must contain the one and only part with type ``array``. RTREE index can accept two types of ``distance`` functions: ``euclid`` and ``manhattan``." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:262 +msgid "Currently, the :ref:`isolation level ` of RTREE indexes in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). If a transaction uses these indexes, it can read committed or confirmed data (depending on the isolation level). However, the indexes are subject to different anomalies that can make them unserializable." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:267 +#: ../../doc/concepts/data_model/indexes.rst:450 +msgid "**Example 1:**" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:269 +msgid "my_space = box.schema.create_space(\"tester\")\n" +"my_space:format({ { type = 'number', name = 'id' }, { type = 'array', name = 'content' } })\n" +"hash_index = my_space:create_index('primary', { type = 'tree', parts = {'id'} })\n" +"rtree_index = my_space:create_index('spatial', { type = 'RTREE', unique = false, parts = {'content'} })" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:276 +msgid "Corresponding tuple field thus must be an array of 2 or 4 numbers. 2 numbers mean a point {x, y}; 4 numbers mean a rectangle {x1, y1, x2, y2}, where (x1, y1) and (x2, y2) - diagonal point of the rectangle." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:281 +msgid "my_space:insert{1, {1, 1}}\n" +"my_space:insert{2, {2, 2, 3, 3}}" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:286 +msgid "Selection results depend on a chosen iterator. The default EQ iterator searches for an exact rectangle, a point is treated as zero width and height rectangle:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:290 +msgid "tarantool> rtree_index:select{1, 1}\n" +"---\n" +"- - [1, [1, 1]]\n" +"...\n" +"\n" +"tarantool> rtree_index:select{1, 1, 1, 1}\n" +"---\n" +"- - [1, [1, 1]]\n" +"...\n" +"\n" +"tarantool> rtree_index:select{2, 2}\n" +"---\n" +"- []\n" +"...\n" +"\n" +"tarantool> rtree_index:select{2, 2, 3, 3}\n" +"---\n" +"- - [2, [2, 2, 3, 3]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:312 +msgid "Iterator ALL, which is the default when no key is specified, selects all tuples in arbitrary order:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:315 +msgid "tarantool> rtree_index:select{}\n" +"---\n" +"- - [1, [1, 1]]\n" +" - [2, [2, 2, 3, 3]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:323 +msgid "Iterator LE (less or equal) searches for tuples with their rectangles within a specified rectangle:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:326 +msgid "tarantool> rtree_index:select({1, 1, 2, 2}, {iterator='le'})\n" +"---\n" +"- - [1, [1, 1]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:333 +msgid "Iterator LT (less than, or strictly less) searches for tuples with their rectangles strictly within a specified rectangle:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:336 +msgid "tarantool> rtree_index:select({0, 0, 3, 3}, {iterator = 'lt'})\n" +"---\n" +"- - [1, [1, 1]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:343 +msgid "Iterator GE searches for tuples with a specified rectangle within their rectangles:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:345 +msgid "tarantool> rtree_index:select({1, 1}, {iterator = 'ge'})\n" +"---\n" +"- - [1, [1, 1]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:352 +msgid "Iterator GT searches for tuples with a specified rectangle strictly within their rectangles:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:354 +msgid "tarantool> rtree_index:select({2.1, 2.1, 2.9, 2.9}, {iterator = 'gt'})\n" +"---\n" +"- []\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:361 +msgid "Iterator OVERLAPS searches for tuples with their rectangles overlapping specified rectangle:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:363 +msgid "tarantool> rtree_index:select({0, 0, 10, 2}, {iterator='overlaps'})\n" +"---\n" +"- - [1, [1, 1]]\n" +" - [2, [2, 2, 3, 3]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:371 +msgid "Iterator NEIGHBOR searches for all tuples and orders them by distance to the specified point:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:373 +msgid "tarantool> for i=1,10 do\n" +" > for j=1,10 do\n" +" > my_space:insert{i*10+j, {i, j, i+1, j+1}}\n" +" > end\n" +" > end\n" +"---\n" +"...\n" +"\n" +"tarantool> rtree_index:select({1, 1}, {iterator = 'neighbor', limit = 5})\n" +"---\n" +"- - [11, [1, 1, 2, 2]]\n" +" - [12, [1, 2, 2, 3]]\n" +" - [21, [2, 1, 3, 2]]\n" +" - [22, [2, 2, 3, 3]]\n" +" - [31, [3, 1, 4, 2]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:392 +#: ../../doc/concepts/data_model/indexes.rst:499 +msgid "**Example 2:**" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:394 +msgid "3D, 4D and more dimensional RTREE indexes work in the same way as 2D except that user must specify more coordinates in requests. Here's short example of using 4D tree:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:398 +msgid "tarantool> my_space = box.schema.create_space(\"tester\")\n" +"tarantool> my_space:format{ { type = 'number', name = 'id' }, { type = 'array', name = 'content' } }\n" +"tarantool> primary_index = my_space:create_index('primary', { type = 'TREE', parts = {'id'} })\n" +"tarantool> rtree_index = my_space:create_index('spatial', { type = 'RTREE', unique = false, dimension = 4, parts = {'content'} })\n" +"tarantool> my_space:insert{1, {1, 2, 3, 4}} -- insert 4D point\n" +"tarantool> my_space:insert{2, {1, 1, 1, 1, 2, 2, 2, 2}} -- insert 4D box\n" +"\n" +"tarantool> rtree_index:select{1, 2, 3, 4} -- find exact point\n" +"---\n" +"- - [1, [1, 2, 3, 4]]\n" +"...\n" +"\n" +"tarantool> rtree_index:select({0, 0, 0, 0, 3, 3, 3, 3}, {iterator = 'LE'}) -- select from 4D box\n" +"---\n" +"- - [2, [1, 1, 1, 1, 2, 2, 2, 2]]\n" +"...\n" +"\n" +"tarantool> rtree_index:select({0, 0, 0, 0}, {iterator = 'neighbor'}) -- select neighbours\n" +"---\n" +"- - [2, [1, 1, 1, 1, 2, 2, 2, 2]]\n" +" - [1, [1, 2, 3, 4]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:425 +msgid "Keep in mind that select NEIGHBOR iterator with unset limits extracts the entire space in order of increasing distance. And there can be tons of data, and this can affect the performance." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:429 +msgid "And another frequent mistake is to specify iterator type without quotes, in such way: ``rtree_index:select(rect, {iterator = LE})``. This leads to silent EQ select, because ``LE`` is undefined variable and treated as nil, so iterator is unset and default used." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:437 +msgid "BITSET indexes" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:439 +msgid "Bitset is a bit mask. You should use it when you need to search by bit masks. This can be, for example, storing a vector of attributes and searching by these attributes." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:445 +msgid "Currently, the :ref:`isolation level ` of BITSET indexes in :ref:`MVCC transaction mode ` is *read-committed* (not *serializable*, as stated). If a transaction uses these indexes, it can read committed or confirmed data (depending on the isolation level). However, the indexes are subject to different anomalies that can make them unserializable." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:452 +msgid "The following script shows creating and searching with a BITSET index. Notice that BITSET cannot be unique, so first a primary-key index is created, and bit values are entered as hexadecimal literals for easier reading." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:456 +msgid "tarantool> my_space = box.schema.space.create('space_with_bitset')\n" +"tarantool> my_space:create_index('primary_index', {\n" +" > parts = {1, 'string'},\n" +" > unique = true,\n" +" > type = 'TREE'\n" +" > })\n" +"tarantool> my_space:create_index('bitset_index', {\n" +" > parts = {2, 'unsigned'},\n" +" > unique = false,\n" +" > type = 'BITSET'\n" +" > })\n" +"tarantool> my_space:insert{'Tuple with bit value = 01', 0x01}\n" +"tarantool> my_space:insert{'Tuple with bit value = 10', 0x02}\n" +"tarantool> my_space:insert{'Tuple with bit value = 11', 0x03}\n" +"tarantool> my_space.index.bitset_index:select(0x02, {\n" +" > iterator = box.index.EQ\n" +" > })\n" +"---\n" +"- - ['Tuple with bit value = 10', 2]\n" +"...\n" +"tarantool> my_space.index.bitset_index:select(0x02, {\n" +" > iterator = box.index.BITS_ANY_SET\n" +" > })\n" +"---\n" +"- - ['Tuple with bit value = 10', 2]\n" +" - ['Tuple with bit value = 11', 3]\n" +"...\n" +"tarantool> my_space.index.bitset_index:select(0x02, {\n" +" > iterator = box.index.BITS_ALL_SET\n" +" > })\n" +"---\n" +"- - ['Tuple with bit value = 10', 2]\n" +" - ['Tuple with bit value = 11', 3]\n" +"...\n" +"tarantool> my_space.index.bitset_index:select(0x02, {\n" +" > iterator = box.index.BITS_ALL_NOT_SET\n" +" > })\n" +"---\n" +"- - ['Tuple with bit value = 01', 1]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:501 +msgid "tarantool> box.schema.space.create('bitset_example')\n" +"tarantool> box.space.bitset_example:create_index('primary')\n" +"tarantool> box.space.bitset_example:create_index('bitset',{unique = false, type = 'BITSET', parts = {2,'unsigned'}})\n" +"tarantool> box.space.bitset_example:insert{1,1}\n" +"tarantool> box.space.bitset_example:insert{2,4}\n" +"tarantool> box.space.bitset_example:insert{3,7}\n" +"tarantool> box.space.bitset_example:insert{4,3}\n" +"tarantool> box.space.bitset_example.index.bitset:select(2, {iterator = 'BITS_ANY_SET'})" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:512 +msgid "The result will be:" +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:514 +msgid "---\n" +"- - [3, 7]\n" +" - [4, 3]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:521 +msgid "because (7 AND 2) is not equal to 0, and (3 AND 2) is not equal to 0." +msgstr "" + +#: ../../doc/concepts/data_model/indexes.rst:523 +msgid "Additionally, there exist :doc:`index iterator operations `. They can only be used with code in Lua and C/C++. Index iterators are for traversing indexes one key at a time, taking advantage of features that are specific to an index type. For example, they can be used for evaluating Boolean expressions when traversing BITSET indexes, or for going in descending order when traversing TREE indexes." +msgstr "" diff --git a/locale/en/platform/data_model/migrations.pot b/locale/en/platform/data_model/migrations.pot new file mode 100644 index 0000000000..642d51e8e7 --- /dev/null +++ b/locale/en/platform/data_model/migrations.pot @@ -0,0 +1,203 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/migrations.rst:4 +msgid "Migrations" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:6 +msgid "**Migration** refers to any change in a data schema: adding/removing a field, creating/dropping an index, changing a field format, etc." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:9 +msgid "In Tarantool, there are two types of schema migration that do not require data migration:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:12 +msgid "adding a field to the end of a space" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:14 +msgid "creating an index" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:18 +msgid "Check the :ref:`Upgrading space schema ` section. With the help of ``space:upgrade()``, you can enable compression and migrate, including already created tuples." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:24 +msgid "Adding a field to the end of a space" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:26 +msgid "You can add a field as follows:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:28 +msgid "local users = box.space.users\n" +"local fmt = users:format()\n" +"\n" +"table.insert(fmt, { name = 'age', type = 'number', is_nullable = true })\n" +"users:format(fmt)" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:36 +msgid "Note that the field must have the ``is_nullable`` parameter. Otherwise, an error will occur." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:39 +msgid "After creating a new field, you probably want to fill it with data. The `tarantool/moonwalker `_ module is useful for this task. The README file describes how to work with this module." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:45 +msgid "Creating an index" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:47 +msgid "Index creation is described in the :doc:`/reference/reference_lua/box_space/create_index` method." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:53 +msgid "Other types of migrations" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:55 +msgid "Other types of migrations are also allowed, but it would be more difficult to maintain data consistency." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:58 +msgid "Migrations are possible in two cases:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:60 +msgid "When Tarantool starts, and no client uses the database yet" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:62 +msgid "During request processing, when active clients are already using the database" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:64 +msgid "For the first case, it is enough to write and test the migration code. The most difficult task is to migrate data when there are active clients. You should keep it in mind when you initially design the data schema." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:68 +msgid "We identify the following problems if there are active clients:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:70 +msgid "Associated data can change atomically." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:72 +msgid "The system should be able to transfer data using both the new schema and the old one." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:74 +msgid "When data is being transferred to a new space, data access should consider that the data might be in one space or another." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:77 +msgid "Write requests must not interfere with the migration. A common approach is to write according to the new data schema." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:80 +msgid "These issues may or may not be relevant depending on your application and its availability requirements." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:84 +msgid "What you need to know when writing complex migrations" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:86 +msgid "Tarantool has a transaction mechanism. It is useful when writing a migration, because it allows you to work with the data atomically. But before using the transaction mechanism, you should explore its limitations." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:90 +msgid "For details, see the section about :doc:`transactions `." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:93 +msgid "How you can apply migration" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:95 +msgid "The migration code is executed on a running Tarantool instance. Important: no method guarantees you transactional application of migrations on the whole cluster." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:99 +msgid "**Method 1**: include migrations in the application code" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:101 +msgid "This is quite simple: when you reload the code, the data is migrated at the right moment, and the database schema is updated. However, this method may not work for everyone. You may not be able to restart Tarantool or update the code using the hot-reload mechanism." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:106 +msgid "**Method 2**: tarantool/migrations (only for a Tarantool Cartridge cluster)" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:108 +msgid "This method is described in the README file of the `tarantool/migrations `_ module." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:113 +msgid "There are also two other methods that we **do not recommend**, but you may find them useful for one reason or another." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:116 +msgid "**Method 3**: the :ref:`tt ` utility" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:118 +msgid "Connect to the necessary instance using ``tt connect``." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:120 +msgid "$ tt connect admin:password@localhost:3301" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:124 +msgid "If your migration is written in a Lua file, you can execute it using ``dofile()``. Call this function and specify the path to the migration file as the first argument. It looks like this:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:128 +msgid "tarantool> dofile('0001-delete-space.lua')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:134 +msgid "(or) Copy the migration script code, paste it into the console, and run it." +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:137 +msgid "You can also connect to the instance and execute the migration script in a single call:" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:139 +msgid "$ tt connect admin:password@localhost:3301 -f 0001-delete-space.lua" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:144 +msgid "**Method 4**: applying migration with Ansible" +msgstr "" + +#: ../../doc/concepts/data_model/migrations.rst:146 +msgid "If you use the `Ansible role `_ to deploy a Tarantool cluster, you can use ``eval``. You can find more information about it `in the Ansible role documentation `_." +msgstr "" diff --git a/locale/en/platform/data_model/operations.pot b/locale/en/platform/data_model/operations.pot new file mode 100644 index 0000000000..a34af90438 --- /dev/null +++ b/locale/en/platform/data_model/operations.pot @@ -0,0 +1,213 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/operations.rst:4 +msgid "Operations" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:9 +msgid "Data operations" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:11 +msgid "The basic data operations supported in Tarantool are:" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:13 +msgid "five data-manipulation operations (INSERT, UPDATE, UPSERT, DELETE, REPLACE), and" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:14 +msgid "one data-retrieval operation (SELECT)." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:16 +msgid "All of them are implemented as functions in :ref:`box.space ` submodule." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:18 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:20 +msgid ":ref:`INSERT `: Add a new tuple to space 'tester'." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:22 +msgid "The first field, field[1], will be 999 (MsgPack type is `integer`)." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:24 +msgid "The second field, field[2], will be 'Taranto' (MsgPack type is `string`)." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:26 +msgid "tarantool> box.space.tester:insert{999, 'Taranto'}" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:30 +msgid ":ref:`UPDATE `: Update the tuple, changing field field[2]." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:32 +msgid "The clause \"{999}\", which has the value to look up in the index of the tuple's primary-key field, is mandatory, because ``update()`` requests must always have a clause that specifies a unique key, which in this case is field[1]." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:36 +msgid "The clause \"{{'=', 2, 'Tarantino'}}\" specifies that assignment will happen to field[2] with the new value." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:39 +msgid "tarantool> box.space.tester:update({999}, {{'=', 2, 'Tarantino'}})" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:43 +msgid ":ref:`UPSERT `: Upsert the tuple, changing field field[2] again." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:46 +msgid "The syntax of ``upsert()`` is similar to the syntax of ``update()``. However, the execution logic of these two requests is different. UPSERT is either UPDATE or INSERT, depending on the database's state. Also, UPSERT execution is postponed until after transaction commit, so, unlike ``update()``, ``upsert()`` doesn't return data back." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:52 +msgid "tarantool> box.space.tester:upsert({999, 'Taranted'}, {{'=', 2, 'Tarantism'}})" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:56 +msgid ":ref:`REPLACE `: Replace the tuple, adding a new field." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:58 +msgid "This is also possible with the ``update()`` request, but the ``update()`` request is usually more complicated." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:61 +msgid "tarantool> box.space.tester:replace{999, 'Tarantella', 'Tarantula'}" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:65 +msgid ":ref:`SELECT `: Retrieve the tuple." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:67 +msgid "The clause \"{999}\" is still mandatory, although it does not have to mention the primary key." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:70 +msgid "tarantool> box.space.tester:select{999}" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:74 +msgid ":ref:`DELETE `: Delete the tuple." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:76 +msgid "In this example, we identify the primary-key field." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:78 +msgid "tarantool> box.space.tester:delete{999}" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:82 +msgid "Summarizing the examples:" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:84 +msgid "Functions ``insert`` and ``replace`` accept a tuple (where a primary key comes as part of the tuple)." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:86 +msgid "Function ``upsert`` accepts a tuple (where a primary key comes as part of the tuple), and also the update operations to execute." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:89 +msgid "Function ``delete`` accepts a full key of any unique index (primary or secondary)." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:91 +msgid "Function ``update`` accepts a full key of any unique index (primary or secondary), and also the operations to execute." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:94 +msgid "Function ``select`` accepts any key: primary/secondary, unique/non-unique, full/partial." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:97 +msgid "See reference on ``box.space`` for more :ref:`details on using data operations `." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:102 +msgid "Besides Lua, you can use :ref:`Perl, PHP, Python or other programming language connectors `. The client server protocol is open and documented. See this :ref:`annotated BNF `." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:110 +msgid "Complexity factors" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:112 +msgid "In reference for :ref:`box.space ` and :doc:`/reference/reference_lua/box_index` submodules, there are notes about which complexity factors might affect the resource usage of each function." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:123 +msgid "Complexity factor" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:124 +msgid "Effect" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:125 +msgid "Index size" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:126 +msgid "The number of index keys is the same as the number of tuples in the data set. For a TREE index, if there are more keys, then the lookup time will be greater, although, of course, the effect is not linear. For a HASH index, if there are more keys, then there is more RAM used, but the number of low-level steps tends to remain constant." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:133 +msgid "Index type" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:134 +msgid "Typically, a HASH index is faster than a TREE index if the number of tuples in the space is greater than one." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:137 +msgid "Number of indexes accessed" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:138 +msgid "Ordinarily, only one index is accessed to retrieve one tuple. But to update the tuple, there must be N accesses if the space has N different indexes. |br| Note regarding storage engine: Vinyl optimizes away such accesses if secondary index fields are unchanged by the update. So, this complexity factor applies only to memtx, since it always makes a full-tuple copy on every update." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:147 +msgid "Number of tuples accessed" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:148 +msgid "A few requests, for example, SELECT, can retrieve multiple tuples. This factor is usually less important than the others." +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:151 +msgid "WAL settings" +msgstr "" + +#: ../../doc/concepts/data_model/operations.rst:152 +msgid "The important setting for the write-ahead log is :ref:`wal_mode `. If the setting causes no writing or delayed writing, this factor is unimportant. If the setting causes every data-change request to wait for writing to finish on a slow device, this factor is more important than all the others." +msgstr "" diff --git a/locale/en/platform/data_model/persistence.pot b/locale/en/platform/data_model/persistence.pot new file mode 100644 index 0000000000..5c4050f349 --- /dev/null +++ b/locale/en/platform/data_model/persistence.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/persistence.rst:5 +msgid "Persistence" +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:7 +msgid "To ensure data persistence, Tarantool records updates to the database in the so-called :ref:`write-ahead log (WAL) ` files. When a power outage occurs or the Tarantool instance is killed incidentally, the in-memory database is lost. In such case, Tarantool restores the data from WAL files by reading them and redoing the requests. This is called the \"recovery process\". You can change the timing of the WAL writer or turn it off by setting the :ref:`wal_mode `." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:17 +msgid "Tarantool also maintains a set of :ref:`snapshot files `. These files contain an on-disk copy of the entire data set for a given moment. Instead of reading every WAL file since the databases were created, the recovery process can load the latest snapshot file and then read the WAL files, produced after the snapshot file was made. After creating a new snapshot, the earlier WAL files can be removed to free up space." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:24 +msgid "To force immediate creation of a snapshot file, use the :doc:`box.snapshot() ` function. To enable the automatic creation of snapshot files, use Tarantool's :ref:`checkpoint daemon `. The checkpoint daemon sets intervals for forced checkpoints. It makes sure that the states of both memtx and vinyl storage engines are synchronized and saved to disk, and automatically removes earlier WAL files." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:32 +msgid "Snapshot files can be created even if there is no WAL file." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:36 +msgid "The memtx engine makes only regular checkpoints with the interval set in :ref:`checkpoint daemon ` configuration." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:39 +msgid "The vinyl engine runs checkpointing in the background at all times." +msgstr "" + +#: ../../doc/concepts/data_model/persistence.rst:41 +msgid "See the :ref:`Internals ` section for more details about the WAL writer and the recovery process." +msgstr "" diff --git a/locale/en/platform/data_model/schema_desc.pot b/locale/en/platform/data_model/schema_desc.pot new file mode 100644 index 0000000000..7fbfee5eac --- /dev/null +++ b/locale/en/platform/data_model/schema_desc.pot @@ -0,0 +1,148 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/schema_desc.rst:4 +msgid "Data schema description" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:6 +msgid "In Tarantool, the use of a data schema is optional." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:8 +msgid "When creating a :term:`space `, you do not have to define a data schema. In this case, the tuples store random data. This rule does not apply to indexed fields. Such fields must contain data of the same type." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:12 +msgid "You can define a data schema when creating a space. Read more in the description of the :doc:`/reference/reference_lua/box_schema/space_create` function. If you have already created a space without specifying a data schema, you can do it later using :doc:`/reference/reference_lua/box_space/format`." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:17 +msgid "After the data schema is defined, all the data is validated by type. Before any insert or update, you will get an error if the data types do not match." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:20 +msgid "We recommend using a data schema because it helps avoid mistakes." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:22 +msgid "In Tarantool, you can define a data schema in two different ways." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:25 +msgid "Data schema description in a code file" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:27 +msgid "The code file is usually called ``init.lua`` and contains the following schema description:" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:29 +msgid "box.cfg()\n" +"\n" +"users = box.schema.create_space('users', { if_not_exists = true })\n" +"users:format({{ name = 'user_id', type = 'number'}, { name = 'fullname', type = 'string'}})\n" +"\n" +"users:create_index('pk', { parts = { { field = 'user_id', type = 'number'}}})" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:38 +msgid "This is quite simple: when you run tarantool, it executes this code and creates a data schema. To run this file, use:" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:41 +msgid "tarantool init.lua" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:45 +msgid "However, it may seem complicated if you do not plan to dive deep into the Lua language and its syntax." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:47 +msgid "Possible difficulty: the snippet above has a function call with a colon: ``users:format``. It is used to pass the ``users`` variable as the first argument of the ``format`` function. This is similar to ``self`` in object-based languages." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:52 +msgid "So it might be more convenient for you to describe the data schema with YAML." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:57 +msgid "Data schema description using the DDL module" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:59 +msgid "The `DDL module `_ allows you to describe a data schema in the YAML format in a declarative way." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:62 +msgid "The schema would look something like this:" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:64 +msgid "spaces:\n" +" users:\n" +" engine: memtx\n" +" is_local: false\n" +" temporary: false\n" +" format:\n" +" - {name: user_id, type: uuid, is_nullable: false}\n" +" - {name: fullname, type: string, is_nullable: false}\n" +" - {name: bucket_id, type: unsigned, is_nullable: false}\n" +" indexes:\n" +" - name: user_id\n" +" unique: true\n" +" parts: [{path: user_id, type: uuid, is_nullable: false}]\n" +" type: HASH\n" +" - name: bucket_id\n" +" unique: false\n" +" parts: [{path: bucket_id, type: unsigned, is_nullable: false}]\n" +" type: TREE\n" +" sharding_key: [user_id]\n" +" sharding_func: test_module.sharding_func" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:87 +msgid "This alternative is simpler to use, and you do not have to dive deep into Lua." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:89 +msgid "To use the DDL module, put the following Lua code into the file that you use to run Tarantool. This file is usually called ``init.lua``." +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:92 +msgid "local yaml = require('yaml')\n" +"local ddl = require('ddl')\n" +"\n" +"box.cfg{}\n" +"\n" +"local fh = io.open('ddl.yml', 'r')\n" +"local schema = yaml.decode(fh:read('*all'))\n" +"fh:close()\n" +"local ok, err = ddl.check_schema(schema)\n" +"if not ok then\n" +" print(err)\n" +"end\n" +"local ok, err = ddl.set_schema(schema)\n" +"if not ok then\n" +" print(err)\n" +"end" +msgstr "" + +#: ../../doc/concepts/data_model/schema_desc.rst:113 +msgid "It is forbidden to modify the data schema in DDL after it has been applied. For migration, there are different scenarios described in the :ref:`Migrations ` section." +msgstr "" diff --git a/locale/en/platform/data_model/value_store.pot b/locale/en/platform/data_model/value_store.pot new file mode 100644 index 0000000000..27be12dd26 --- /dev/null +++ b/locale/en/platform/data_model/value_store.pot @@ -0,0 +1,921 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/data_model/value_store.rst:2 +msgid "Data storage" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:7 +msgid "Tuples" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:9 +msgid "Tarantool operates data in the form of tuples." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:12 +#: ../../doc/concepts/data_model/value_store.rst:391 +msgid "tuple" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:14 +msgid "A tuple is a group of data values in Tarantool's memory. Think of it as a \"database record\" or a \"row\". The data values in the tuple are called :term:`fields `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:18 +msgid "When Tarantool returns a tuple value in the console, by default, it uses :ref:`YAML ` format, for example: ``[3, 'Ace of Base', 1993]``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:22 +msgid "Internally, Tarantool stores tuples as `MsgPack `_ arrays." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:24 +msgid "field" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:26 +msgid "Fields are distinct data values, contained in a tuple. They play the same role as \"row columns\" or \"record fields\" in relational databases, with a few improvements:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:30 +msgid "fields can be composite structures, such as arrays or maps," +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:31 +msgid "fields don't need to have names." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:33 +msgid "A given tuple may have any number of fields, and the fields may be of different :ref:`types `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:36 +msgid "The field's number is the identifier of the field. Numbers are counted from base 1 in Lua and other 1-based languages, or from base 0 in languages like PHP or C/C++. So, ``1`` or ``0`` can be used in some contexts to refer to the first field of a tuple." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:45 +msgid "Spaces" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:47 +msgid "Tarantool stores tuples in containers called spaces." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:50 +msgid "space" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:52 +msgid "In Tarantool, a space is a primary container that stores data. It is analogous to tables in relational databases. Spaces contain :term:`tuples ` -- the Tarantool name for database records. The number of tuples in a space is unlimited." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:58 +msgid "At least one space is required to store data with Tarantool. Each space has the following attributes:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:61 +msgid "a unique **name** specified by the user," +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:62 +msgid "a unique **numeric identifier** which can be specified by the user, but usually is assigned automatically by Tarantool," +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:64 +msgid "an **engine**: *memtx* (default) --- in-memory engine, fast but limited in size, or *vinyl* --- on-disk engine for huge data sets." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:67 +msgid "To be functional, a space also needs to have a :ref:`primary index `. It can also have secondary indexes." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:73 +msgid "Data types" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:75 +msgid "Tarantool is both a database manager and an application server. Therefore a developer often deals with two type sets: the types of the programming language (such as Lua) and the types of the Tarantool storage format (MsgPack)." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:83 +msgid "Lua versus MsgPack" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:91 +msgid "Scalar / compound" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:92 +msgid "MsgPack type" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:93 +msgid "Lua type" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:94 +msgid "Example value" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:95 +#: ../../doc/concepts/data_model/value_store.rst:99 +#: ../../doc/concepts/data_model/value_store.rst:103 +#: ../../doc/concepts/data_model/value_store.rst:107 +#: ../../doc/concepts/data_model/value_store.rst:111 +#: ../../doc/concepts/data_model/value_store.rst:115 +#: ../../doc/concepts/data_model/value_store.rst:119 +#: ../../doc/concepts/data_model/value_store.rst:123 +#: ../../doc/concepts/data_model/value_store.rst:127 +#: ../../doc/concepts/data_model/value_store.rst:131 +#: ../../doc/concepts/data_model/value_store.rst:135 +#: ../../doc/concepts/data_model/value_store.rst:139 +#: ../../doc/concepts/data_model/value_store.rst:401 +msgid "scalar" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:96 +#: ../../doc/concepts/data_model/value_store.rst:181 +msgid "nil" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:97 +#: ../../doc/concepts/data_model/value_store.rst:113 +#: ../../doc/concepts/data_model/value_store.rst:121 +#: ../../doc/concepts/data_model/value_store.rst:125 +#: ../../doc/concepts/data_model/value_store.rst:129 +#: ../../doc/concepts/data_model/value_store.rst:133 +#: ../../doc/concepts/data_model/value_store.rst:137 +#: ../../doc/concepts/data_model/value_store.rst:141 +msgid "`cdata`_" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:98 +msgid ":ref:`box.NULL `" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:100 +#: ../../doc/concepts/data_model/value_store.rst:195 +msgid "boolean" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:101 +msgid "`boolean`_" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:102 +msgid "``true``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:104 +#: ../../doc/concepts/data_model/value_store.rst:327 +msgid "string" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:105 +msgid "`string`_" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:106 +msgid "``'A B C'``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:108 +#: ../../doc/concepts/data_model/value_store.rst:112 +#: ../../doc/concepts/data_model/value_store.rst:204 +msgid "integer" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:109 +#: ../../doc/concepts/data_model/value_store.rst:117 +msgid "`number`_" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:110 +#: ../../doc/concepts/data_model/value_store.rst:114 +msgid "``12345``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:116 +#: ../../doc/concepts/data_model/value_store.rst:120 +msgid "float64 (double)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:118 +#: ../../doc/concepts/data_model/value_store.rst:122 +msgid "``1.2345``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:124 +msgid "binary" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:126 +msgid "``[!!binary 3t7e]``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:128 +msgid "ext (for Tarantool ``decimal``)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:130 +msgid "``1.2``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:132 +msgid "ext (for Tarantool ``datetime``)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:134 +msgid "``'2021-08-20T16:21:25.122999906 Europe/Berlin'``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:136 +msgid "ext (for Tarantool ``interval``)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:138 +msgid "``+1 months, 1 days``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:140 +msgid "ext (for Tarantool ``uuid``)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:142 +msgid "``12a34b5c-de67-8f90-123g-h4567ab8901``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:143 +#: ../../doc/concepts/data_model/value_store.rst:147 +#: ../../doc/concepts/data_model/value_store.rst:151 +msgid "compound" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:144 +msgid "map" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:145 +msgid "`table`_ (with string keys)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:146 +msgid "``{'a': 5, 'b': 6}``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:148 +#: ../../doc/concepts/data_model/value_store.rst:152 +#: ../../doc/concepts/data_model/value_store.rst:369 +msgid "array" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:149 +msgid "`table`_ (with integer keys)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:150 +msgid "``[1, 2, 3, 4, 5]``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:153 +msgid "tuple (`cdata`_)" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:154 +msgid "``[12345, 'A B C']``" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:164 +msgid "MsgPack values have variable lengths. So, for example, the smallest number requires only one byte, but the largest number requires nine bytes." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:170 +msgid "The Lua `nil `_ type is encoded as MsgPack ``nil`` but decoded as :ref:`msgpack.NULL `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:176 +msgid "Field type details" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:183 +msgid "In Lua, the nil type has only one possible value, also called ``nil``. Tarantool displays it as ``null`` when using the default :ref:`YAML ` format. Nil may be compared to values of any types with == (is-equal) or ~= (is-not-equal), but other comparison operations will not work. Nil may not be used in Lua tables; the workaround is to use :ref:`box.NULL ` because ``nil == box.NULL`` is true. **Example:** ``nil``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:197 +msgid "A boolean is either ``true`` or ``false``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:199 +msgid "**Example:** ``true``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:206 +msgid "The Tarantool integer type is for integers between -9223372036854775808 and 18446744073709551615, which is about 18 quintillion. This type corresponds to the number type in Lua and to the integer type in MsgPack." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:210 +msgid "**Example:** ``-2^63``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:215 +msgid "unsigned" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:217 +msgid "The Tarantool unsigned type is for integers between 0 and 18446744073709551615. So it is a subset of integer." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:220 +msgid "**Example:** ``123456``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:225 +msgid "double" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:227 +msgid "The double field type exists mainly to be equivalent to Tarantool/SQL's :ref:`DOUBLE data type `. In `msgpuck.h `_ (Tarantool's interface to MsgPack), the storage type is ``MP_DOUBLE`` and the size of the encoded value is always 9 bytes. In Lua, fields of the double type can only contain non-integer numeric values and cdata values with double floating-point numbers." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:235 +msgid "**Examples:** ``1.234``, ``-44``, ``1.447e+44``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:237 +msgid "To avoid using the wrong kind of values inadvertently, use ``ffi.cast()`` when searching or changing ``double`` fields. For example, instead of :samp:`{space_object}:insert`:code:`{`:samp:`{value}`:code:`}` use ``ffi = require('ffi') ...`` :samp:`{space_object}:insert`:code:`({ffi.cast('double',`:samp:`{value}`:code:`)})`." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:245 +msgid "**Example:**" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:247 +msgid "s = box.schema.space.create('s', {format = {{'d', 'double'}}})\n" +"s:create_index('ii')\n" +"s:insert({1.1})\n" +"ffi = require('ffi')\n" +"s:insert({ffi.cast('double', 1)})\n" +"s:insert({ffi.cast('double', tonumber('123'))})\n" +"s:select(1.1)\n" +"s:select({ffi.cast('double', 1)})" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:258 +msgid "Arithmetic with cdata ``double`` will not work reliably, so for Lua, it is better to use the ``number`` type. This warning does not apply for Tarantool/SQL because Tarantool/SQL does :ref:`implicit casting `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:267 +msgid "number" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:269 +msgid "The Tarantool number field may have both integer and floating-point values, although in Lua a ``number`` is a double-precision floating-point." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:273 +msgid "Tarantool will try to store a Lua number as floating-point if the value contains a decimal point or is very large (greater than 100 trillion = 1e14), otherwise Tarantool will store it as an integer. To ensure that even very large numbers are stored as integers, use the :ref:`tonumber64 ` function, or the LL (Long Long) suffix, or the ULL (Unsigned Long Long) suffix. Here are examples of numbers using regular notation, exponential notation, the ULL suffix and the ``tonumber64`` function: ``-55``, ``-2.7e+20``, ``100000000000000ULL``, ``tonumber64('18446744073709551615')``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:283 +msgid "You can also use the ``ffi`` module to specify a C type to cast the number to. In this case, the number will be stored as `cdata`_." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:289 +msgid "decimal" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:291 +msgid "The Tarantool decimal type is stored as a :ref:`MsgPack ext ` (Extension). Values with the decimal type are not floating-point values although they may contain decimal points. They are exact with up to 38 digits of precision." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:296 +msgid "**Example:** a value returned by a function in the :ref:`decimal ` module." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:301 +msgid "datetime" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:303 +msgid "Introduced in :tarantool-release:`2.10.0`. The Tarantool ``datetime`` type facilitates operations with date and time, accounting for leap years or the varying number of days in a month. It is stored as a :ref:`MsgPack ext ` (Extension). Operations with this data type use code from `c-dt `_, a third-party library." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:309 +msgid "For more information, see :doc:`Module datetime `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:314 +msgid "interval" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:316 +msgid "**Since:** :tarantool-release:`2.10.0`" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:318 +msgid "The Tarantool ``interval`` type represents periods of time. They can be added to or subtracted from ``datetime`` values or each other. Operations with this data type use code from `c-dt `_, a third-party library. The type is stored as a :ref:`MsgPack ext ` (Extension). For more information, see :doc:`Module datetime `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:329 +msgid "A string is a variable-length sequence of bytes, usually represented with alphanumeric characters inside single quotes. In both Lua and MsgPack, strings are treated as binary data, with no attempts to determine a string's character set or to perform any string conversion -- unless there is an optional :ref:`collation `. So, usually, string sorting and comparison are done byte-by-byte, without any special collation rules applied. For example, numbers are ordered by their point on the number line, so 2345 is greater than 500; meanwhile, strings are ordered by the encoding of the first byte, then the encoding of the second byte, and so on, so ``'2345'`` is less than ``'500'``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:340 +msgid "**Example:** ``'A, B, C'``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:345 +msgid "bin" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:347 +msgid "A bin (binary) value is not directly supported by Lua but there is a Tarantool type ``varbinary`` which is encoded as MsgPack binary. For an (advanced) example showing how to insert varbinary into a database, see the Cookbook Recipe for :ref:`ffi_varbinary_insert `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:352 +msgid "**Example:** ``\"\\65 \\66 \\67\"``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:357 +msgid "uuid" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:359 +msgid "The Tarantool uuid type is used for :ref:`Universally Unique Identifiers `. Since version :doc:`2.4.1 ` Tarantool stores ``uuid`` values as a :ref:`MsgPack ext ` (Extension)." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:364 +msgid "**Example:** ``64d22e4d-ac92-4a23-899a-e5934af5479``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:371 +msgid "An array is represented in Lua with ``{...}`` (`braces `_)." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:373 +msgid "**Examples:** lists of numbers representing points in geometric figures: ``{10, 11}``, ``{3, 5, 9, 10}``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:379 +msgid "table" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:381 +msgid "Lua tables with string keys are stored as MsgPack maps; Lua tables with integer keys starting with 1 are stored as MsgPack arrays. Nils may not be used in Lua tables; the workaround is to use :ref:`box.NULL `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:386 +msgid "**Example:** a ``box.space.tester:select()`` request will return a Lua table." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:393 +msgid "A tuple is a light reference to a MsgPack array stored in the database. It is a special type (cdata) to avoid conversion to a Lua table on retrieval. A few functions may return tables with multiple tuples. For tuple examples, see :ref:`box.tuple `." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:403 +msgid "Values in a scalar field can be boolean, integer, unsigned, double, number, decimal, string, uuid, or varbinary; but not array, map, or tuple." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:406 +msgid "**Examples:** ``true``, ``1``, ``'xxx'``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:411 +msgid "any" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:413 +msgid "Values in a field of this type can be boolean, integer, unsigned, double, number, decimal, string, uuid, varbinary, array, map, or tuple." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:416 +msgid "**Examples:** ``true``, ``1``, ``'xxx'``, ``{box.NULL, 0}``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:422 +msgid "Examples" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:424 +msgid "Examples of insert requests with different field types:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:426 +msgid "tarantool> box.space.K:insert{1,nil,true,'A B C',12345,1.2345}\n" +"---\n" +"- [1, null, true, 'A B C', 12345, 1.2345]\n" +"...\n" +"tarantool> box.space.K:insert{2,{['a']=5,['b']=6}}\n" +"---\n" +"- [2, {'a': 5, 'b': 6}]\n" +"...\n" +"tarantool> box.space.K:insert{3,{1,2,3,4,5}}\n" +"---\n" +"- [3, [1, 2, 3, 4, 5]]\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:442 +msgid "Indexed field types" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:444 +msgid "To learn more about what values can be stored in indexed fields, read the :ref:`Indexes ` section." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:450 +msgid "Collations" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:452 +msgid "By default, when Tarantool compares strings, it uses the so-called **binary collation**. It only considers the numeric value of each byte in a string. For example, the encoding of ``'A'`` (what used to be called the \"ASCII value\") is 65, the encoding of ``'B'`` is 66, and the encoding of ``'a'`` is 98. Therefore, if the string is encoded with ASCII or UTF-8, then ``'A' < 'B' < 'a'``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:459 +msgid "Binary collation is the best choice for fast deterministic simple maintenance and searching with Tarantool indexes." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:462 +msgid "But if you want the ordering that you see in phone books and dictionaries, then you need Tarantool's optional collations, such as ``unicode`` and ``unicode_ci``, which allow for ``'a' < 'A' < 'B'`` and ``'a' == 'A' < 'B'`` respectively." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:467 +msgid "**The unicode and unicode_ci optional collations** use the ordering according to the `Default Unicode Collation Element Table (DUCET) `_ and the rules described in `Unicode® Technical Standard #10 Unicode Collation Algorithm (UTS #10 UCA) `_. The only difference between the two collations is about `weights `_:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:474 +msgid "``unicode`` collation observes L1, L2, and L3 weights (strength = 'tertiary');" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:475 +msgid "``unicode_ci`` collation observes only L1 weights (strength = 'primary'), so for example ``'a' == 'A' == 'á' == 'Á'``." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:477 +msgid "As an example, take some Russian words:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:479 +msgid "'ЕЛЕ'\n" +"'елейный'\n" +"'ёлка'\n" +"'еловый'\n" +"'елозить'\n" +"'Ёлочка'\n" +"'ёлочный'\n" +"'ЕЛь'\n" +"'ель'" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:491 +msgid "...and show the difference in ordering and selecting by index:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:493 +msgid "with ``unicode`` collation:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:495 +msgid "tarantool> box.space.T:create_index('I', {parts = {{field = 1, type = 'str', collation='unicode'}}})\n" +"...\n" +"tarantool> box.space.T.index.I:select()\n" +"---\n" +"- - ['ЕЛЕ']\n" +" - ['елейный']\n" +" - ['ёлка']\n" +" - ['еловый']\n" +" - ['елозить']\n" +" - ['Ёлочка']\n" +" - ['ёлочный']\n" +" - ['ель']\n" +" - ['ЕЛь']\n" +"...\n" +"tarantool> box.space.T.index.I:select{'ЁлКа'}\n" +"---\n" +"- []\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:516 +msgid "with ``unicode_ci`` collation:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:518 +msgid "tarantool> box.space.T:create_index('I', {parts = {{field = 1, type ='str', collation='unicode_ci'}}})\n" +"...\n" +"tarantool> box.space.T.index.I:select()\n" +"---\n" +"- - ['ЕЛЕ']\n" +" - ['елейный']\n" +" - ['ёлка']\n" +" - ['еловый']\n" +" - ['елозить']\n" +" - ['Ёлочка']\n" +" - ['ёлочный']\n" +" - ['ЕЛь']\n" +"...\n" +"tarantool> box.space.T.index.I:select{'ЁлКа'}\n" +"---\n" +"- - ['ёлка']\n" +"..." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:539 +msgid "In all, collation involves much more than these simple examples of upper case / lower case and accented / unaccented equivalence in alphabets. We also consider variations of the same character, non-alphabetic writing systems, and special rules that apply for combinations of characters." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:544 +msgid "For English, Russian, and most other languages and use cases, use the \"unicode\" and \"unicode_ci\" collations. If you need Cyrillic letters 'Е' and 'Ё' to have the same level-1 weights, try the Kyrgyz collation." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:548 +msgid "**The tailored optional collations**: for other languages, Tarantool supplies tailored collations for every modern language that has more than a million native speakers, and for specialized situations such as the difference between dictionary order and telephone book order. Run ``box.space._collation:select()`` to see the complete list." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:554 +msgid "The tailored collation names have the form ``unicode_[language code]_[strength]``, where language code is a standard 2-character or 3-character language abbreviation, and strength is ``s1`` for \"primary strength\" (level-1 weights), ``s2`` for \"secondary\", ``s3`` for \"tertiary\". Tarantool uses the same language codes as the ones in the \"list of tailorable locales\" on man pages of `Ubuntu `_ and `Fedora `_. Charts explaining the precise differences from DUCET order are in the `Common Language Data Repository `_." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:568 +msgid "Constraints" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:570 +msgid "For better control over stored data, Tarantool supports **constraints** – user-defined limitations on the values of certain fields or entire tuples. Together with data types, constraints allow limiting the ranges of available field values both syntactically and semantically." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:574 +msgid "For example, the field ``age`` typically has the ``number`` type, so it cannot store strings or boolean values. However, it can still have values that don't make sense, such as negative numbers. This is where constraints come to help." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:581 +msgid "Constraint types" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:583 +msgid "There are two types of constraints in Tarantool:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:585 +msgid "*Field constraints* check that the value being assigned to a field satisfies a given condition. For example, ``age`` must be non-negative." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:588 +msgid "*Tuple constraints* check complex conditions that can involve all fields of a tuple. For example, a tuple contains a date in three fields: ``year``, ``month``, and ``day``. You can validate ``day`` values based on the ``month`` value (and even ``year`` if you consider leap years)." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:593 +msgid "Field constraints work faster, while tuple constraints allow implementing a wider range of limitations." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:599 +msgid "Constraint functions" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:601 +msgid "Constraints use stored Lua functions or :ref:`SQL expressions `, which must return ``true`` when the constraint is satisfied. Other return values (including ``nil``) and exceptions make the check fail and prevent tuple insertion or modification." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:605 +msgid "To create a constraint function, call :ref:`box.schema.func.create() ` with the function definition specified in the ``body`` attribute." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:607 +msgid "Constraint functions take two parameters:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:609 +msgid "The tuple and the constraint name for tuple constraints." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:611 +msgid "-- Define a tuple constraint function --\n" +"box.schema.func.create('check_person', {\n" +" language = 'LUA',\n" +" is_deterministic = true,\n" +" body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'\n" +"})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:618 +msgid "Tarantool doesn't check field names used in tuple constraint functions. If a field referenced in a tuple constraint gets renamed, this constraint will break and prevent further insertions and modifications in the space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:622 +msgid "The field value and the constraint name for field constraints." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:624 +msgid "-- Define a field constraint function --\n" +"box.schema.func.create('check_age', {\n" +" language = 'LUA',\n" +" is_deterministic = true,\n" +" body = 'function(f, c) return (f >= 0 and f < 150) end'\n" +"})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:632 +msgid "Creating constraints" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:634 +msgid "To create a constraint in a space, specify the corresponding function's name in the ``constraint`` parameter:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:637 +msgid "Tuple constraints: when creating or altering a space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:639 +msgid "-- Create a space with a tuple constraint --\n" +"customers = box.schema.space.create('customers', {constraint = 'check_person'})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:644 +msgid "Field constraints: when setting up the space format." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:646 +msgid "-- Specify format with a field constraint --\n" +"box.space.customers:format({\n" +" {name = 'id', type = 'number'},\n" +" {name = 'name', type = 'string'},\n" +" {name = 'age', type = 'number', constraint = 'check_age'},\n" +"})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:651 +msgid "In both cases, ``constraint`` can contain multiple function names passed as a tuple. Each constraint can have an optional name:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:654 +msgid "-- Create one more tuple constraint --\n" +"box.schema.func.create('another_constraint',\n" +" {language = 'LUA', is_deterministic = true, body = 'function(t, c) return true end'})\n" +"\n" +"-- Set two constraints with optional names --\n" +"box.space.customers:alter{\n" +" constraint = { check1 = 'check_person', check2 = 'another_constraint'}\n" +"}\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:661 +msgid "When adding a constraint to an existing space with data, Tarantool checks it against the stored data. If there are fields or tuples that don't satisfy the constraint, it won't be applied to the space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:669 +msgid "Foreign keys" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:671 +msgid "**Foreign keys** provide links between related fields, therefore maintaining the `referential integrity `_ of the database." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:675 +msgid "Fields can contain values that exist only in other fields. For example, a shop order always belongs to a customer. Hence, all values of the ``customer`` field of the ``orders`` space must also exist in the ``id`` field of the ``customers`` space. In this case, ``customers`` is a **parent space** for ``orders`` (its **child space**). When two spaces are linked with a foreign key, each time a tuple is inserted or modified in the child space, Tarantool checks that a corresponding value is present in the parent space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:688 +msgid "A foreign key can link a field to another field in the same space. In this case, the child field must be nullable. Otherwise, it is impossible to insert the first tuple in such a space because there is no parent tuple to which it can link." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:694 +msgid "Foreign key types" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:696 +msgid "There are two types of foreign keys in Tarantool:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:698 +msgid "*Field foreign keys* check that the value being assigned to a field is present in a particular field of another space. For example, the ``customer`` value in a tuple from the ``orders`` space must match an ``id`` stored in the ``customers`` space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:702 +msgid "*Tuple foreign keys* check that multiple fields of a tuple have a match in another space. For example, if the ``orders`` space has fields ``customer_id`` and ``customer_name``, a tuple foreign key can check that the ``customers`` space contains a tuple with both these values in the corresponding fields." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:707 +msgid "Field foreign keys work faster while tuple foreign keys allow implementing more strict references." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:711 +msgid "Creating foreign keys" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:716 +msgid "For each foreign key, there must exist a parent space index that includes all its fields." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:719 +msgid "To create a foreign key in a space, specify the parent space and linked fields in the ``foreign_key`` parameter. Parent spaces can be referenced by name or by id. When linking to the same space, the space can be omitted. Fields can be referenced by name or by number:" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:723 +msgid "Field foreign keys: when setting up the space format." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:725 +msgid "-- Create a space with a field foreign key --\n" +"box.schema.space.create('orders')\n" +"\n" +"box.space.orders:format({\n" +" {name = 'id', type = 'number'},\n" +" {name = 'customer_id', foreign_key = {space = 'customers', field = 'id'}},\n" +" {name = 'price_total', type = 'number'},\n" +"})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:730 +msgid "Tuple foreign keys: when creating or altering a space. Note that for foreign keys with multiple fields there must exist an index that includes all these fields." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:733 +msgid "-- Create a space with a tuple foreign key --\n" +"box.schema.space.create(\"orders\", {\n" +" foreign_key = {\n" +" space = 'customers',\n" +" field = {customer_id = 'id', customer_name = 'name'}\n" +" }\n" +"})\n" +"\n" +"box.space.orders:format({\n" +" {name = \"id\", type = \"number\"},\n" +" {name = \"customer_id\" },\n" +" {name = \"customer_name\"},\n" +" {name = \"price_total\", type = \"number\"},\n" +"})\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:740 +msgid "Type can be omitted for foreign key fields because it's defined in the parent space." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:743 +msgid "Foreign keys can have an optional name." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:745 +msgid "-- Set a foreign key with an optional name --\n" +"box.space.orders:alter{\n" +" foreign_key = {\n" +" customer = {\n" +" space = 'customers',\n" +" field = { customer_id = 'id', customer_name = 'name'}\n" +" }\n" +" }\n" +"}\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:750 +msgid "A space can have multiple tuple foreign keys. In this case, they all must have names." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:752 +msgid "-- Set two foreign keys: names are mandatory --\n" +"box.space.orders:alter{\n" +" foreign_key = {\n" +" customer = {\n" +" space = 'customers',\n" +" field = {customer_id = 'id', customer_name = 'name'}\n" +" },\n" +" item = {\n" +" space = 'items',\n" +" field = {item_id = 'id'}\n" +" }\n" +" }\n" +"}\n" +"" +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:757 +msgid "Tarantool performs integrity checks upon data modifications in parent spaces. If you try to remove a tuple referenced by a foreign key or an entire parent space, you will get an error." +msgstr "" + +#: ../../doc/concepts/data_model/value_store.rst:763 +msgid "Renaming parent spaces or referenced fields may break the corresponding foreign keys and prevent further insertions or modifications in the child spaces." +msgstr "" diff --git a/locale/en/platform/ddl_dml/crud.pot b/locale/en/platform/ddl_dml/crud.pot new file mode 100644 index 0000000000..9146ce8224 --- /dev/null +++ b/locale/en/platform/ddl_dml/crud.pot @@ -0,0 +1,586 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/db/crud.rst:4 +msgid "CRUD operation examples" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:11 +msgid "Using data operations" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:13 +msgid "This section shows basic usage scenarios and typical errors for each :ref:`data operation ` in Tarantool: :ref:`INSERT `, :ref:`DELETE `, :ref:`UPDATE `, :ref:`UPSERT `, :ref:`REPLACE `, and :ref:`SELECT `. Before trying out the examples, you need to bootstrap a Tarantool instance as shown below." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:23 +msgid "-- Create a space --\n" +"bands = box.schema.space.create('bands')\n" +"\n" +"-- Specify field names and types --\n" +"box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"\n" +"-- Create a primary index --\n" +"box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"\n" +"-- Create a unique secondary index --\n" +"box.space.bands:create_index('band', { parts = { 'band_name' } })\n" +"\n" +"-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })\n" +"\n" +"-- Create a multi-part index --\n" +"box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })\n" +"" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:33 +msgid "INSERT" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:35 +msgid "The :ref:`space_object.insert ` method accepts a well-formatted tuple." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:37 +msgid "-- Insert a tuple with a unique primary key --\n" +"tarantool> bands:insert{1, 'Scorpions', 1965}\n" +"---\n" +"- [1, 'Scorpions', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:46 +msgid "``insert`` also checks all the keys for duplicates." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:48 +msgid "-- Try to insert a tuple with a duplicate primary key --\n" +"tarantool> bands:insert{1, 'Scorpions', 1965}\n" +"---\n" +"- error: Duplicate key exists in unique index \"primary\" in space \"bands\" with old\n" +" tuple - [1, \"Scorpions\", 1965] and new tuple - [1, \"Scorpions\", 1965]\n" +"...\n" +"\n" +"-- Try to insert a tuple with a duplicate secondary key --\n" +"tarantool> bands:insert{2, 'Scorpions', 1965}\n" +"---\n" +"- error: Duplicate key exists in unique index \"band\" in space \"bands\" with old tuple\n" +" - [1, \"Scorpions\", 1965] and new tuple - [2, \"Scorpions\", 1965]\n" +"...\n" +"\n" +"-- Insert a second tuple with unique primary and secondary keys --\n" +"tarantool> bands:insert{2, 'Pink Floyd', 1965}\n" +"---\n" +"- [2, 'Pink Floyd', 1965]\n" +"...\n" +"\n" +"-- Delete all tuples --\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:79 +msgid "DELETE" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:81 +msgid ":ref:`space_object.delete ` allows you to delete a tuple identified by the primary key." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:83 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +"\n" +"-- Delete a tuple with an existing key --\n" +"tarantool> bands:delete{4}\n" +"---\n" +"- [4, 'The Beatles', 1960]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:103 +msgid "You can also use :ref:`index_object.delete ` to delete a tuple by the specified unique index." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:105 +msgid "-- Delete a tuple by the primary index --\n" +"tarantool> bands.index.primary:delete{3}\n" +"---\n" +"- [3, 'Ace of Base', 1987]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +"...\n" +"\n" +"-- Delete a tuple by a unique secondary index --\n" +"tarantool> bands.index.band:delete{'Scorpions'}\n" +"---\n" +"- [2, 'Scorpions', 1965]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +"...\n" +"\n" +"-- Try to delete a tuple by a non-unique secondary index --\n" +"tarantool> bands.index.year:delete(1986)\n" +"---\n" +"- error: Get() doesn't support partial keys and non-unique indexes\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +"...\n" +"\n" +"-- Try to delete a tuple by a partial key --\n" +"tarantool> bands.index.year_band:delete('Roxette')\n" +"---\n" +"- error: Invalid key part count in an exact match (expected 2, got 1)\n" +"...\n" +"\n" +"-- Delete a tuple by a full key --\n" +"tarantool> bands.index.year_band:delete{1986, 'Roxette'}\n" +"---\n" +"- [1, 'Roxette', 1986]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- []\n" +"...\n" +"\n" +"-- Delete all tuples --\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:164 +msgid "UPDATE" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:166 +msgid ":ref:`space_object.update ` allows you to update a tuple identified by the primary key. Similarly to ``delete``, the ``update`` method accepts a full key and also an operation to execute." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:169 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +"\n" +"-- Update a tuple with an existing key --\n" +"tarantool> bands:update({2}, {{'=', 2, 'Pink Floyd'}})\n" +"---\n" +"- [2, 'Pink Floyd', 1965]\n" +"...\n" +"\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Pink Floyd', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:192 +msgid ":ref:`index_object.update ` updates a tuple identified by the specified unique index." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:194 +msgid "-- Update a tuple by the primary index --\n" +"tarantool> bands.index.primary:update({2}, {{'=', 2, 'The Rolling Stones'}})\n" +"---\n" +"- [2, 'The Rolling Stones', 1965]\n" +"...\n" +"\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'The Rolling Stones', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"...\n" +"\n" +"-- Update a tuple by a unique secondary index --\n" +"tarantool> bands.index.band:update({'The Rolling Stones'}, {{'=', 2, 'The Doors'}})\n" +"---\n" +"- [2, 'The Doors', 1965]\n" +"...\n" +"\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'The Doors', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"...\n" +"\n" +"-- Try to update a tuple by a non-unique secondary index --\n" +"tarantool> bands.index.year:update({1965}, {{'=', 2, 'Scorpions'}})\n" +"---\n" +"- error: Get() doesn't support partial keys and non-unique indexes\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'The Doors', 1965]\n" +" - [3, 'Ace of Base', 1987]\n" +" - [4, 'The Beatles', 1960]\n" +"...\n" +"\n" +"-- Delete all tuples --\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:247 +msgid "UPSERT" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:249 +msgid ":ref:`space_object.upsert ` updates an existing tuple or inserts a new one:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:251 +msgid "If the existing tuple is found by the primary key, Tarantool applies the update operation to this tuple and ignores the new tuple." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:254 +msgid "If no existing tuple is found, Tarantool inserts the new tuple and ignores the update operation." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:257 +msgid "tarantool> bands:insert{1, 'Scorpions', 1965}\n" +"---\n" +"- [1, 'Scorpions', 1965]\n" +"...\n" +"-- As the first argument, upsert accepts a tuple, not a key --\n" +"tarantool> bands:upsert({2}, {{'=', 2, 'Pink Floyd'}})\n" +"---\n" +"- error: Tuple field 2 (band_name) required by space format is missing\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Scorpions', 1965]\n" +"...\n" +"tarantool> bands:delete(1)\n" +"---\n" +"- [1, 'Scorpions', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:277 +msgid "``upsert`` acts as ``insert`` when no existing tuple is found by the primary key." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:279 +msgid "tarantool> bands:upsert({1, 'Scorpions', 1965}, {{'=', 2, 'The Doors'}})\n" +"---\n" +"...\n" +"-- As you can see, {1, 'Scorpions', 1965} is inserted, --\n" +"-- and the update operation is not applied. --\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Scorpions', 1965]\n" +"...\n" +"\n" +"-- upsert with the same primary key but different values in other fields --\n" +"-- applies the update operation and ignores the new tuple. --\n" +"tarantool> bands:upsert({1, 'Scorpions', 1965}, {{'=', 2, 'The Doors'}})\n" +"---\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'The Doors', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:301 +msgid "``upsert`` searches for the existing tuple by the primary index, not by the secondary index. This can lead to a duplication error if the tuple violates a secondary index uniqueness." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:305 +msgid "tarantool> bands:upsert({2, 'The Doors', 1965}, {{'=', 2, 'Pink Floyd'}})\n" +"---\n" +"- error: Duplicate key exists in unique index \"band\" in space \"bands\" with old tuple\n" +" - [1, \"The Doors\", 1965] and new tuple - [2, \"The Doors\", 1965]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'The Doors', 1965]\n" +"...\n" +"\n" +"-- This works if uniqueness is preserved. --\n" +"tarantool> bands:upsert({2, 'The Beatles', 1960}, {{'=', 2, 'Pink Floyd'}})\n" +"---\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'The Doors', 1965]\n" +" - [2, 'The Beatles', 1960]\n" +"...\n" +"\n" +"-- Delete all tuples --\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:337 +msgid "REPLACE" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:339 +msgid ":ref:`space_object.replace ` accepts a well-formatted tuple and searches for the existing tuple by the primary key of the new tuple:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:342 +msgid "If the existing tuple is found, Tarantool deletes it and inserts the new tuple." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:343 +msgid "If no existing tuple is found, Tarantool inserts the new tuple." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:346 +msgid "tarantool> bands:replace{1, 'Scorpions', 1965}\n" +"---\n" +"- [1, 'Scorpions', 1965]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Scorpions', 1965]\n" +"...\n" +"tarantool> bands:replace{1, 'The Beatles', 1960}\n" +"---\n" +"- [1, 'The Beatles', 1960]\n" +"...\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'The Beatles', 1960]\n" +"...\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:368 +msgid "``replace`` can violate unique constraints, like ``upsert`` does." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:370 +msgid "tarantool> bands:insert{1, 'Scorpions', 1965}\n" +"- [1, 'Scorpions', 1965]\n" +"...\n" +"tarantool> bands:insert{2, 'The Beatles', 1960}\n" +"---\n" +"- [2, 'The Beatles', 1960]\n" +"...\n" +"tarantool> bands:replace{2, 'Scorpions', 1965}\n" +"---\n" +"- error: Duplicate key exists in unique index \"band\" in space \"bands\" with old tuple\n" +" - [1, \"Scorpions\", 1965] and new tuple - [2, \"Scorpions\", 1965]\n" +"...\n" +"tarantool> bands:truncate()\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:392 +msgid "SELECT" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:394 +msgid "The :ref:`space_object.select ` request searches for a tuple or a set of tuples in the given space by the primary key. To search by the specified index, use :ref:`index_object.select `. These methods work with any keys, including unique and non-unique, full and partial. If a key is partial, ``select`` searches by all keys where the prefix matches the specified key part." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:400 +msgid "tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'The Doors', 1965}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +"\n" +"tarantool> bands:select(1)\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +"...\n" +"\n" +"tarantool> bands:select()\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +" - [2, 'Scorpions', 1965]\n" +" - [3, 'The Doors', 1965]\n" +" - [4, 'The Beatles', 1960]\n" +"...\n" +"\n" +"tarantool> bands.index.primary:select(2)\n" +"---\n" +"- - [2, 'Scorpions', 1965]\n" +"...\n" +"\n" +"tarantool> bands.index.band:select('The Doors')\n" +"---\n" +"- - [3, 'The Doors', 1965]\n" +"...\n" +"\n" +"tarantool> bands.index.year:select(1965)\n" +"---\n" +"- - [2, 'Scorpions', 1965]\n" +" - [3, 'The Doors', 1965]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:440 +msgid "Using box.space functions to read _space tuples" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:442 +msgid "This example illustrates how to look at all the spaces, and for each display: approximately how many tuples it contains, and the first field of its first tuple. The function uses the Tarantool's ``box.space`` functions ``len()`` and ``pairs()``. The iteration through the spaces is coded as a scan of the ``_space`` system space, which contains metadata. The third field in ``_space`` contains the space name, so the key instruction ``space_name = v[3]`` means ``space_name`` is the ``space_name`` field in the tuple of ``_space`` that we've just fetched with ``pairs()``. The function returns a table:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:452 +msgid "function example()\n" +" local tuple_count, space_name, line\n" +" local ta = {}\n" +" for k, v in box.space._space:pairs() do\n" +" space_name = v[3]\n" +" if box.space[space_name].index[0] ~= nil then\n" +" tuple_count = '1 or more'\n" +" else\n" +" tuple_count = '0'\n" +" end\n" +" line = space_name .. ' tuple_count =' .. tuple_count\n" +" if tuple_count == '1 or more' then\n" +" for k1, v1 in box.space[space_name]:pairs() do\n" +" line = line .. '. first field in first tuple = ' .. v1[1]\n" +" break\n" +" end\n" +" end\n" +" table.insert(ta, line)\n" +" end\n" +" return ta\n" +"end" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:476 +msgid "The output below shows what happens if you invoke this function:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:478 +msgid "tarantool> example()\n" +"---\n" +"- - _schema tuple_count =1 or more. first field in first tuple = cluster\n" +" - _space tuple_count =1 or more. first field in first tuple = 272\n" +" - _vspace tuple_count =1 or more. first field in first tuple = 272\n" +" - _index tuple_count =1 or more. first field in first tuple = 272\n" +" - _vindex tuple_count =1 or more. first field in first tuple = 272\n" +" - _func tuple_count =1 or more. first field in first tuple = 1\n" +" - _vfunc tuple_count =1 or more. first field in first tuple = 1\n" +" - _user tuple_count =1 or more. first field in first tuple = 0\n" +" - _vuser tuple_count =1 or more. first field in first tuple = 0\n" +" - _priv tuple_count =1 or more. first field in first tuple = 1\n" +" - _vpriv tuple_count =1 or more. first field in first tuple = 1\n" +" - _cluster tuple_count =1 or more. first field in first tuple = 1\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:498 +msgid "Using box.space functions to organize a _space tuple" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:500 +msgid "This examples shows how to display field names and field types of a system space -- using metadata to find metadata." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:503 +msgid "To begin: how can one select the ``_space`` tuple that describes ``_space``?" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:505 +msgid "A simple way is to look at the constants in ``box.schema``, which shows that there is an item named SPACE_ID == 288, so these statements retrieve the correct tuple:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:509 +msgid "box.space._space:select{ 288 }\n" +"-- or --\n" +"box.space._space:select{ box.schema.SPACE_ID }" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:515 +msgid "Another way is to look at the tuples in ``box.space._index``, which shows that there is a secondary index named 'name' for a space number 288, so this statement also retrieve the correct tuple:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:519 +msgid "box.space._space.index.name:select{ '_space' }" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:523 +msgid "However, the retrieved tuple is not easy to read:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:525 +msgid "tarantool> box.space._space.index.name:select{'_space'}\n" +"---\n" +"- - [280, 1, '_space', 'memtx', 0, {}, [{'name': 'id', 'type': 'num'}, {'name': 'owner',\n" +" 'type': 'num'}, {'name': 'name', 'type': 'str'}, {'name': 'engine', 'type': 'str'},\n" +" {'name': 'field_count', 'type': 'num'}, {'name': 'flags', 'type': 'str'}, {\n" +" 'name': 'format', 'type': '*'}]]\n" +"..." +msgstr "" + +#: ../../doc/how-to/db/crud.rst:535 +msgid "It looks disorganized because field number 7 has been formatted with recommended names and data types. How can one get those specific sub-fields? Since it's visible that field number 7 is an array of maps, this `for` loop will do the organizing:" +msgstr "" + +#: ../../doc/how-to/db/crud.rst:540 +msgid "tarantool> do\n" +" > local tuple_of_space = box.space._space.index.name:get{'_space'}\n" +" > for _, field in ipairs(tuple_of_space[7]) do\n" +" > print(field.name .. ', ' .. field.type)\n" +" > end\n" +" > end\n" +"id, num\n" +"owner, num\n" +"name, str\n" +"engine, str\n" +"field_count, num\n" +"flags, str\n" +"format, *\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/platform/ddl_dml/index.pot b/locale/en/platform/ddl_dml/index.pot new file mode 100644 index 0000000000..0c9b6ea407 --- /dev/null +++ b/locale/en/platform/ddl_dml/index.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/db/index.rst:2 +msgid "Defining and manipulating data" +msgstr "" + +#: ../../doc/how-to/db/index.rst:4 +msgid "This section contains guides on performing data operations in Tarantool." +msgstr "" diff --git a/locale/en/platform/ddl_dml/indexes.pot b/locale/en/platform/ddl_dml/indexes.pot new file mode 100644 index 0000000000..f25e54d71e --- /dev/null +++ b/locale/en/platform/ddl_dml/indexes.pot @@ -0,0 +1,273 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/db/indexes.rst:4 +msgid "Using indexes" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:7 +msgid "Creating an index" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:9 +msgid "It is mandatory to create an index for a space before trying to insert tuples into the space, or select tuples from the space." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:12 +msgid "The simple :doc:`index-creation ` operation is:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:63 +msgid ":extsamp:`box.space.{**{space-name}**}:create_index('{*{index-name}*}')`" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:20 +msgid "This creates a unique :ref:`TREE ` index on the first field of all tuples (often called \"Field#1\"), which is assumed to be numeric." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:23 +msgid "A recommended design pattern for a data model is to base primary keys on the first fields of a tuple. This speeds up tuple comparison due to the specifics of data storage and the way comparisons are arranged in Tarantool." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:27 +msgid "The simple :doc:`SELECT ` request is:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:77 +msgid ":extsamp:`box.space.{**{space-name}**}:select({*{value}*})`" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:34 +msgid "This looks for a single tuple via the first index. Since the first index is always unique, the maximum number of returned tuples will be 1. You can call ``select()`` without arguments, and it will return all tuples. Be careful! Using ``select()`` for huge spaces hangs your instance." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:39 +msgid "An index definition may also include identifiers of tuple fields and their expected **types**. See allowed indexed field types in section :ref:`Details about indexed field types `:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:91 +msgid ":extsamp:`box.space.{**{space-name}**}:create_index({**{index-name}**}, {type = 'tree', parts = {{field = 1, type = 'unsigned'}}}`" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:48 +msgid "Space definitions and index definitions are stored permanently in Tarantool's system spaces :ref:`_space ` and :ref:`_index `." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:51 +#: ../../doc/how-to/db/indexes.rst:166 +msgid "Tip" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:54 +msgid "See full information about creating indexes, such as how to create a multikey index, an index using the ``path`` option, or how to create a functional index in our reference for :doc:`/reference/reference_lua/box_space/create_index`." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:62 +msgid "Index operations" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:64 +msgid "Index operations are automatic: if a data manipulation request changes a tuple, then it also changes the index keys defined for the tuple." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:67 +msgid "Create a sample space named ``bands``:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:69 +msgid "bands = box.schema.space.create('bands')\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:74 +msgid "Format the created space by specifying field names and types:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:76 +msgid "box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:81 +msgid "Create the **primary** index (named ``primary``):" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:83 +msgid "box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:88 +msgid "This index is based on the ``id`` field of each tuple." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:90 +msgid "Insert some :ref:`tuples ` into the space:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:92 +msgid "box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"box.space.bands:insert { 6, 'The Rolling Stones', 1962 }\n" +"box.space.bands:insert { 7, 'The Doors', 1965 }\n" +"box.space.bands:insert { 8, 'Nirvana', 1987 }\n" +"box.space.bands:insert { 9, 'Led Zeppelin', 1968 }\n" +"box.space.bands:insert { 10, 'Queen', 1970 }\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:97 +msgid "Create **secondary indexes**:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:99 +msgid "-- Create a unique secondary index --\n" +"box.space.bands:create_index('band', { parts = { 'band_name' } })\n" +"\n" +"-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:104 +msgid "Create a **multi-part index** with two parts:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:106 +msgid "box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:111 +msgid "There are the following SELECT variations:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:113 +msgid "The search can use **comparisons** other than equality:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:115 +msgid "-- Select maximum 3 tuples with the key value greater than 1965 --\n" +"select_greater = bands.index.year:select({ 1965 }, { iterator = 'GT', limit = 3 })\n" +"--[[\n" +"---\n" +"- - [9, 'Led Zeppelin', 1968]\n" +" - [10, 'Queen', 1970]\n" +" - [1, 'Roxette', 1986]\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:120 +msgid "The :ref:`comparison operators ` are:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:122 +msgid "``LT`` for \"less than\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:123 +msgid "``LE`` for \"less than or equal\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:124 +msgid "``GT`` for \"greater\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:125 +msgid "``GE`` for \"greater than or equal\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:126 +msgid "``EQ`` for \"equal\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:127 +msgid "``REQ`` for \"reversed equal\"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:129 +msgid "Value comparisons make sense if and only if the index type is TREE. The iterator types for other types of indexes are slightly different and work differently. See details in section :ref:`Iterator types `." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:133 +msgid "Note that we don't use the name of the index, which means we use primary index here." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:135 +msgid "This type of search may return more than one tuple. The tuples will be sorted in descending order by key if the comparison operator is LT or LE or REQ. Otherwise they will be sorted in ascending order." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:139 +msgid "The search can use a **secondary index**." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:141 +msgid "-- Select a tuple by the specified secondary key value --\n" +"select_secondary = bands.index.band:select { 'The Doors' }\n" +"--[[\n" +"---\n" +"- - [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:148 +msgid "**Partial key search:** The search may be for some key parts starting with the prefix of the key. Note that partial key searches are available only in TREE indexes." +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:152 +msgid "-- Select tuples by the specified partial key value --\n" +"select_multipart_partial = bands.index.year_band:select { 1965 }\n" +"--[[\n" +"---\n" +"- - [5, 'Pink Floyd', 1965]\n" +" - [2, 'Scorpions', 1965]\n" +" - [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:158 +msgid "The search can be for all fields, using a table as the value:" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:160 +msgid "-- Select a tuple by the specified multi-part secondary key value --\n" +"select_multipart = bands.index.year_band:select { 1960, 'The Beatles' }\n" +"--[[\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/indexes.rst:169 +msgid "You can also add, drop, or alter the definitions at runtime, with some restrictions. Read more about index operations in reference for :doc:`box.index submodule `." +msgstr "" diff --git a/locale/en/platform/ddl_dml/sequences.pot b/locale/en/platform/ddl_dml/sequences.pot new file mode 100644 index 0000000000..f8b6d7b9ea --- /dev/null +++ b/locale/en/platform/ddl_dml/sequences.pot @@ -0,0 +1,266 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/how-to/db/sequences.rst:4 +msgid "Using sequences" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:6 +msgid "A **sequence** is a generator of ordered integer values." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:8 +msgid "As with spaces and indexes, you should specify the sequence **name** and let Tarantool generate a unique numeric identifier (sequence ID)." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:11 +msgid "As well, you can specify several options when creating a new sequence. The options determine the values that are generated whenever the sequence is used." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:17 +msgid "Options for box.schema.sequence.create()" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:25 +msgid "Option name" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:26 +msgid "Type and meaning" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:27 +msgid "Default" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:28 +msgid "Examples" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:29 +msgid "``start``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:30 +msgid "Integer. The value to generate the first time a sequence is used" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:31 +#: ../../doc/how-to/db/sequences.rst:35 +#: ../../doc/how-to/db/sequences.rst:51 +msgid "1" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:32 +msgid "``start=0``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:33 +msgid "``min``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:34 +msgid "Integer. Values smaller than this cannot be generated" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:36 +msgid "``min=-1000``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:37 +msgid "``max``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:38 +msgid "Integer. Values larger than this cannot be generated" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:39 +msgid "9223372036854775807" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:40 +msgid "``max=0``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:41 +msgid "``cycle``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:42 +msgid "Boolean. Whether to start again when values cannot be generated" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:43 +msgid "false" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:44 +msgid "``cycle=true``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:45 +msgid "``cache``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:46 +msgid "Integer. The number of values to store in a cache" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:47 +msgid "0" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:48 +msgid "``cache=0``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:49 +msgid "``step``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:50 +msgid "Integer. What to add to the previous generated value, when generating a new value" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:52 +msgid "``step=-1``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:53 +msgid "``if_not_exists``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:54 +msgid "Boolean. If this is true and a sequence with this name exists already, ignore other options and use the existing values" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:56 +msgid "``false``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:57 +msgid "``if_not_exists=true``" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:60 +msgid "Once a sequence exists, it can be altered, dropped, reset, forced to generate the next value, or associated with an index." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:64 +msgid "Associating a sequence with an index" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:66 +msgid "First, create a sequence:" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:68 +msgid "-- Create a sequence --\n" +"box.schema.sequence.create('id_seq',{min=1000, start=1000})\n" +"--[[\n" +"---\n" +"- step: 1\n" +" id: 1\n" +" min: 1000\n" +" cache: 0\n" +" uid: 1\n" +" cycle: false\n" +" name: id_seq\n" +" start: 1000\n" +" max: 9223372036854775807\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:73 +msgid "The result shows that the new sequence has all default values, except for the two that were specified, ``min`` and ``start``." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:76 +msgid "Get the next value from the sequence by calling the ``next()`` function:" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:78 +msgid "-- Get the next item --\n" +"box.sequence.id_seq:next()\n" +"--[[\n" +"---\n" +"- 1000\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:83 +msgid "The result is the same as the start value. The next call increases the value by one (the default sequence step)." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:86 +msgid "Create a space and specify that its primary key should be generated from the sequence:" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:89 +msgid "-- Create a space --\n" +"box.schema.space.create('customers')\n" +"\n" +"-- Create an index that uses the sequence --\n" +"box.space.customers:create_index('primary',{ sequence = 'id_seq' })\n" +"--[[\n" +"---\n" +"- parts:\n" +" - type: unsigned\n" +" is_nullable: false\n" +" fieldno: 1\n" +" sequence_id: 1\n" +" id: 0\n" +" space_id: 513\n" +" unique: true\n" +" hint: true\n" +" type: TREE\n" +" name: primary\n" +" sequence_fieldno: 1\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:94 +msgid "Insert a tuple without specifying a value for the primary key:" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:96 +msgid "\n" +"-- Insert a tuple without the primary key value --\n" +"box.space.customers:insert{ nil, 'Adams' }\n" +"--[[\n" +"---\n" +"- [1001, 'Adams']\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:101 +msgid "The result is a new tuple where the first field is assigned the next value from the sequence. This arrangement, where the system automatically generates the values for a primary key, is sometimes called \"auto-incrementing\" or \"identity\"." +msgstr "" + +#: ../../doc/how-to/db/sequences.rst:106 +msgid "For syntax and implementation details, see the reference for :doc:`box.schema.sequence `." +msgstr "" diff --git a/locale/en/platform/engines/index.pot b/locale/en/platform/engines/index.pot new file mode 100644 index 0000000000..3bc54bdff9 --- /dev/null +++ b/locale/en/platform/engines/index.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/engines/index.rst:6 +msgid "Storage engines" +msgstr "" + +#: ../../doc/concepts/engines/index.rst:8 +msgid "A storage engine is a set of low-level routines which actually store and retrieve :term:`tuple ` values. Tarantool offers a choice of two storage engines:" +msgstr "" + +#: ../../doc/concepts/engines/index.rst:11 +msgid ":doc:`memtx ` is the in-memory storage engine used by default." +msgstr "" + +#: ../../doc/concepts/engines/index.rst:12 +msgid ":doc:`vinyl ` is the on-disk storage engine." +msgstr "" + +#: ../../doc/concepts/engines/index.rst:14 +msgid "All the details on the engines you can find in the dedicated sections:" +msgstr "" diff --git a/locale/en/platform/engines/memtx.pot b/locale/en/platform/engines/memtx.pot new file mode 100644 index 0000000000..a0bf49e14d --- /dev/null +++ b/locale/en/platform/engines/memtx.pot @@ -0,0 +1,201 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/engines/memtx.rst:4 +msgid "Storing data with memtx" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:6 +msgid "The ``memtx`` storage engine is used in Tarantool by default. It keeps all data in random-access memory (RAM), and therefore has very low read latency." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:8 +msgid "The obvious question here is: if all the data is stored in memory, how can you prevent the data loss in case of emergency such as outage or Tarantool instance failure?" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:11 +msgid "First of all, Tarantool persists all data changes by writing requests to the write-ahead log (WAL) that is stored on disk. Read more about that in the :ref:`memtx-persist` section. In case of a distributed application, there is an option of synchronous replication that ensures keeping the data consistent on a quorum of replicas. Although replication is not directly a storage engine topic, it is a part of the answer regarding data safety. Read more in the :ref:`memtx-replication` section." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:16 +msgid "In this chapter, the following topics are discussed in brief with the references to other chapters that explain the subject matter in details." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:25 +msgid "Memory model" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:27 +msgid "There is a fixed number of independent :ref:`execution threads `. The threads don't share state. Instead they exchange data using low-overhead message queues. While this approach limits the number of cores that the instance uses, it removes competition for the memory bus and ensures peak scalability of memory access and network throughput." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:32 +msgid "Only one thread, namely, the **transaction processor thread** (further, **TX thread**) can access the database, and there is only one TX thread for each Tarantool instance. In this thread, transactions are executed in a strictly consecutive order. Multi-statement transactions exist to provide isolation: each transaction sees a consistent database state and commits all its changes atomically. At commit time, a yield happens and all transaction changes are written to :ref:`WAL ` in a single batch. In case of errors during transaction execution, a transaction is rolled-back completely. Read more in the following sections: :ref:`transaction_model`, :ref:`txn_mode_transaction-manager`." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:42 +msgid "Within the TX thread, there is a memory area allocated for Tarantool to store data. It's called **Arena**." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:46 +msgid "Data is stored in :term:`spaces `. Spaces contain database records—:term:`tuples `. To access and manipulate the data stored in spaces and tuples, Tarantool builds :doc:`indexes `." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:49 +msgid "Special `allocators `__ manage memory allocations for spaces, tuples, and indexes within the Arena. The slab allocator is the main allocator used to store tuples. Tarantool has a built-in module called ``box.slab`` which provides the slab allocator statistics that can be used to monitor the total memory usage and memory fragmentation. For more details, see the ``box.slab`` module :doc:`reference `." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:57 +msgid "Also inside the TX thread, there is an event loop. Within the event loop, there are a number of :ref:`fibers `. Fibers are cooperative primitives that allow interaction with spaces, that is, reading and writing the data. Fibers can interact with the event loop and between each other directly or by using special primitives called channels. Due to the usage of fibers and :ref:`cooperative multitasking `, the ``memtx`` engine is lock-free in typical situations." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:64 +msgid "To interact with external users, there is a separate :ref:`network thread ` also called the **iproto thread**. The iproto thread receives a request from the network, parses and checks the statement, and transforms it into a special structure—a message containing an executable statement and its options. Then the iproto thread ships this message to the TX thread and runs the user's request in a separate fiber." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:74 +msgid "Data persistence" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:76 +msgid "To ensure :ref:`data persistence `, Tarantool does two things." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:78 +msgid "After executing data change requests in memory, Tarantool writes each such request to the :ref:`write-ahead log (WAL) ` files (``.xlog``) that are stored on disk. Tarantool does this via a separate thread called the **WAL thread**." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:83 +msgid "Tarantool periodically takes the entire :doc:`database snapshot ` and saves it on disk. It is necessary for accelerating instance's restart because when there are too many WAL files, it can be difficult for Tarantool to restart quickly." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:86 +msgid "To save a snapshot, there is a special fiber called the **snapshot daemon**. It reads the consistent content of the entire Arena and writes it on disk into a snapshot file (``.snap``). Due of the cooperative multitasking, Tarantool cannot write directly on disk because it is a locking operation. That is why Tarantool interacts with disk via a separate pool of threads from the :doc:`fio ` library." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:93 +msgid "So, even in emergency situations such as an outage or a Tarantool instance failure, when the in-memory database is lost, the data can be restored fully during Tarantool restart." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:96 +msgid "What happens during the restart:" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:98 +msgid "Tarantool finds the latest snapshot file and reads it." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:99 +msgid "Tarantool finds all the WAL files created after that snapshot and reads them as well." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:100 +msgid "When the snapshot and WAL files have been read, there is a fully recovered in-memory data set corresponding to the state when the Tarantool instance stopped." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:102 +msgid "While reading the snapshot and WAL files, Tarantool is building the primary indexes." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:103 +msgid "When all the data is in memory again, Tarantool is building the secondary indexes." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:104 +msgid "Tarantool runs the application." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:109 +msgid "Accessing data" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:111 +msgid "To access and manipulate the data stored in memory, Tarantool builds indexes. Indexes are also stored in memory within the Arena." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:114 +msgid "Tarantool supports a number of :ref:`index types ` intended for different usage scenarios. The possible types are TREE, HASH, BITSET, and RTREE." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:117 +msgid "Select query are possible against secondary index keys as well as primary keys. Indexes can have multi-part keys." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:120 +msgid "For detailed information about indexes, refer to the :doc:`/concepts/data_model/indexes` page." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:125 +msgid "Replicating data" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:127 +msgid "Although this topic is not directly related to the ``memtx`` engine, it completes the overall picture of how Tarantool works in case of a distributed application." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:129 +msgid "Replication allows multiple Tarantool instances to work on copies of the same database. The copies are kept in sync because each instance can communicate its changes to all the other instances. It is implemented via WAL replication." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:133 +msgid "To send data to a replica, Tarantool runs another thread called **relay**. Its purpose is to read the WAL files and send them to replicas. On a replica, the fiber called **applier** is run. It receives the changes from a remote node and applies them to the replica's Arena. All the changes are being written to WAL files via the replica's WAL thread as if they are done locally." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:140 +msgid "By default, :ref:`replication ` in Tarantool is asynchronous: if a transaction is committed locally on a master node, it does not mean it is replicated onto any replicas." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:144 +msgid ":ref:`Synchronous replication ` exists to solve this problem. Synchronous transactions are not considered committed and are not responded to a client until they are replicated onto some number of replicas." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:148 +msgid "For more information on replication, refer to the :ref:`corresponding chapter `." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:153 +msgid "Summary" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:155 +msgid "The main key points describing how the in-memory storage engine works can be summarized in the following way:" +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:157 +msgid "All data is in RAM." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:158 +msgid "Access to data is from one thread." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:159 +msgid "Tarantool writes all data change requests in WAL." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:160 +msgid "Data snapshots are taken periodically." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:161 +msgid "Indexes are build to access the data." +msgstr "" + +#: ../../doc/concepts/engines/memtx.rst:162 +msgid "WAL can be replicated." +msgstr "" diff --git a/locale/en/platform/engines/memtx_vinyl_diff.pot b/locale/en/platform/engines/memtx_vinyl_diff.pot new file mode 100644 index 0000000000..c18a90fa05 --- /dev/null +++ b/locale/en/platform/engines/memtx_vinyl_diff.pot @@ -0,0 +1,124 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:4 +msgid "Difference between memtx and vinyl storage engines" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:6 +msgid "The primary difference between memtx and vinyl is that memtx is an in-memory engine while vinyl is an on-disk engine. An in-memory storage engine is generally faster (each query is usually run under 1 ms), and the memtx engine is justifiably the default for Tarantool. But on-disk engine such as vinyl is preferable when the database is larger than the available memory, and adding more memory is not a realistic option." +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:19 +msgid "Option" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:19 +msgid "memtx" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:19 +msgid "vinyl" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:21 +msgid "Supported index type" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:21 +msgid "TREE, HASH, :ref:`RTREE ` or BITSET" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:21 +msgid "TREE" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:23 +msgid "Temporary spaces" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:23 +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:25 +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:27 +msgid "Supported" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:23 +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:25 +msgid "Not supported" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:25 +msgid ":ref:`random() ` function" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:27 +msgid ":ref:`alter() ` function" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:27 +msgid "Supported starting from the 1.10.2 release (the primary index cannot be modified)" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:30 +msgid ":ref:`len() ` function" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:30 +msgid "Returns the number of tuples in the space" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:30 +msgid "Returns the maximum approximate number of tuples in the space" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:33 +msgid ":ref:`count() ` function" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:33 +msgid "Takes a constant amount of time" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:33 +msgid "Takes a variable amount of time depending on a state of a DB" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:36 +msgid ":ref:`delete() ` function" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:36 +msgid "Returns the deleted tuple, if any" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:36 +msgid "Always returns nil" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:38 +msgid "yield" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:38 +msgid "Does not yield on the select requests unless the transaction is committed to WAL" +msgstr "" + +#: ../../doc/concepts/engines/memtx_vinyl_diff.rst:38 +msgid "Yields on the select requests or on its equivalents: get() or pairs()" +msgstr "" diff --git a/locale/en/platform/engines/vinyl.pot b/locale/en/platform/engines/vinyl.pot new file mode 100644 index 0000000000..c67fefe9d1 --- /dev/null +++ b/locale/en/platform/engines/vinyl.pot @@ -0,0 +1,568 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/engines/vinyl.rst:5 +msgid "Storing data with vinyl" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:7 +msgid "Tarantool is a transactional and persistent DBMS that maintains 100% of its data in RAM. The greatest advantages of in-memory databases are their speed and ease of use: they demonstrate consistently high performance, but you never need to tune them." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:12 +msgid "A few years ago we decided to extend the product by implementing a classical storage engine similar to those used by regular DBMSs: it uses RAM for caching, while the bulk of its data is stored on disk. We decided to make it possible to set a storage engine independently for each table in the database, which is the same way that MySQL approaches it, but we also wanted to support transactions from the very beginning." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:19 +msgid "The first question we needed to answer was whether to create our own storage engine or use an existing library. The open-source community offered a few viable solutions. The RocksDB library was the fastest growing open-source library and is currently one of the most prominent out there. There were also several lesser-known libraries to consider, such as WiredTiger, ForestDB, NestDB, and LMDB." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:26 +msgid "Nevertheless, after studying the source code of existing libraries and considering the pros and cons, we opted for our own storage engine. One reason is that the existing third-party libraries expected requests to come from multiple operating system threads and thus contained complex synchronization primitives for controlling parallel data access. If we had decided to embed one of these in Tarantool, we would have made our users bear the overhead of a multithreaded application without getting anything in return. The thing is, Tarantool has an actor-based architecture. The way it processes transactions in a dedicated thread allows it to do away with the unnecessary locks, interprocess communication, and other overhead that accounts for up to 80% of processor time in multithreaded DBMSs." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:41 +msgid "*The Tarantool process consists of a fixed number of \"actor\" threads*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:43 +msgid "If you design a database engine with cooperative multitasking in mind right from the start, it not only significantly speeds up the development process, but also allows the implementation of certain optimization tricks that would be too complex for multithreaded engines. In short, using a third-party solution wouldn’t have yielded the best result." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:53 +msgid "Algorithm" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:55 +msgid "Once the idea of using an existing library was off the table, we needed to pick an architecture to build upon. There are two competing approaches to on-disk data storage: the older one relies on B-trees and their variations; the newer one advocates the use of log-structured merge-trees, or \"LSM\" trees. MySQL, PostgreSQL, and Oracle use B-trees, while Cassandra, MongoDB, and CockroachDB have adopted LSM trees." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:62 +msgid "B-trees are considered better suited for reads and LSM trees—for writes. However, with SSDs becoming more widespread and the fact that SSDs have read throughput that’s several times greater than write throughput, the advantages of LSM trees in most scenarios was more obvious to us." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:67 +msgid "Before dissecting LSM trees in Tarantool, let’s take a look at how they work. To do that, we’ll begin by analyzing a regular B-tree and the issues it faces. A B-tree is a balanced tree made up of blocks, which contain sorted lists of key- value pairs. (Topics such as filling and balancing a B-tree or splitting and merging blocks are outside of the scope of this article and can easily be found on Wikipedia). As a result, we get a container sorted by key, where the smallest element is stored in the leftmost node and the largest one in the rightmost node. Let’s have a look at how insertions and searches in a B-tree happen." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:78 +msgid "*Classical B-tree*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:80 +msgid "If you need to find an element or check its membership, the search starts at the root, as usual. If the key is found in the root block, the search stops; otherwise, the search visits the rightmost block holding the largest element that’s not larger than the key being searched (recall that elements at each level are sorted). If the first level yields no results, the search proceeds to the next level. Finally, the search ends up in one of the leaves and probably locates the needed key. Blocks are stored and read into RAM one by one, meaning the algorithm reads :math:`logB(N)` blocks in a single search, where N is the number of elements in the B-tree. In the simplest case, writes are done similarly: the algorithm finds the block that holds the necessary element and updates (inserts) its value." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:92 +msgid "To better understand the data structure, let’s consider a practical example: say we have a B-tree with 100,000,000 nodes, a block size of 4096 bytes, and an element size of 100 bytes. Thus each block will hold up to 40 elements (all overhead considered), and the B-tree will consist of around 2,570,000 blocks and 5 levels: the first four will have a size of 256 Mb, while the last one will grow up to 10 Gb. Obviously, any modern computer will be able to store all of the levels except the last one in filesystem cache, so read requests will require just a single I/O operation." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:101 +msgid "But if we change our perspective —B-trees don’t look so good anymore. Suppose we need to update a single element. Since working with B-trees involves reading and writing whole blocks, we would have to read in one whole block, change our 100 bytes out of 4096, and then write the whole updated block to disk. In other words,we were forced to write 40 times more data than we actually modified!" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:108 +msgid "If you take into account the fact that an SSD block has a size of 64 Kb+ and not every modification changes a whole element, the extra disk workload can be greater still." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:113 +msgid "Authors of specialized literature and blogs dedicated to on-disk data storage have coined two terms for these phenomena: extra reads are referred to as \"read amplification\" and writes as \"write amplification\"." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:117 +msgid "The amplification factor (multiplication coefficient) is calculated as the ratio of the size of actual read (or written) data to the size of data needed (or actually changed). In our B-tree example, the amplification factor would be around 40 for both reads and writes." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:123 +msgid "The huge number of extra I/O operations associated with updating data is one of the main issues addressed by LSM trees. Let’s see how they work." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:127 +msgid "The key difference between LSM trees and regular B-trees is that LSM trees don’t just store data (keys and values), but also data operations: insertions and deletions." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:133 +#: ../../doc/concepts/engines/vinyl.rst:189 +#: ../../doc/concepts/engines/vinyl.rst:204 +#: ../../doc/concepts/engines/vinyl.rst:226 +#: ../../doc/concepts/engines/vinyl.rst:278 +#: ../../doc/concepts/engines/vinyl.rst:303 +#: ../../doc/concepts/engines/vinyl.rst:640 +#: ../../doc/concepts/engines/vinyl.rst:792 +msgid "|br|" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:135 +msgid "LSM tree:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:140 +msgid "Stores statements, not values:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:138 +msgid "REPLACE" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:139 +msgid "DELETE" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:140 +msgid "UPSERT" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:142 +msgid "Every statement is marked by LSN" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:143 +msgid "Append-only files, garbage is collected after a checkpoint" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:144 +msgid "Transactional log of all filesystem changes: vylog" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:146 +msgid "For example, an element corresponding to an insertion operation has, apart from a key and a value, an extra byte with an operation code (\"REPLACE\" in the image above). An element representing the deletion operation contains a key (since storing a value is unnecessary) and the corresponding operation code—\"DELETE\". Also, each LSM tree element has a log sequence number (LSN), which is the value of a monotonically increasing sequence that uniquely identifies each operation. The whole tree is first ordered by key in ascending order, and then, within a single key scope, by LSN in descending order." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:157 +msgid "*A single level of an LSM tree*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:163 +msgid "Filling an LSM tree" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:165 +msgid "Unlike a B-tree, which is stored completely on disk and can be partly cached in RAM, when using an LSM tree, memory is explicitly separated from disk right from the start. The issue of volatile memory and data persistence is beyond the scope of the storage algorithm and can be solved in various ways—for example, by logging changes." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:171 +msgid "The part of an LSM tree that’s stored in RAM is called L0 (level zero). The size of RAM is limited, so L0 is allocated a fixed amount of memory. For example, in Tarantool, the L0 size is controlled by the ``vinyl_memory`` parameter. Initially, when an LSM tree is empty, operations are written to L0. Recall that all elements are ordered by key in ascending order, and then within a single key scope, by LSN in descending order, so when a new value associated with a given key gets inserted, it’s easy to locate the older value and delete it. L0 can be structured as any container capable of storing a sorted sequence of elements. For example, in Tarantool, L0 is implemented as a B+*-tree. Lookups and insertions are standard operations for the data structure underlying L0, so I won’t dwell on those." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:183 +msgid "Sooner or later the number of elements in an LSM tree exceeds the L0 size and that’s when L0 gets written to a file on disk (called a \"run\") and then cleared for storing new elements. This operation is called a \"dump\"." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:191 +msgid "Dumps on disk form a sequence ordered by LSN: LSN ranges in different runs don’t overlap, and the leftmost runs (at the head of the sequence) hold newer operations. Think of these runs as a pyramid, with the newest ones closer to the top. As runs keep getting dumped, the pyramid grows higher. Note that newer runs may contain deletions or replacements for existing keys. To remove older data, it’s necessary to perform garbage collection (this process is sometimes called \"merge\" or \"compaction\") by combining several older runs into a new one. If two versions of the same key are encountered during a compaction, only the newer one is retained; however, if a key insertion is followed by a deletion, then both operations can be discarded." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:206 +msgid "The key choices determining an LSM tree’s efficiency are which runs to compact and when to compact them. Suppose an LSM tree stores a monotonically increasing sequence of keys (1, 2, 3, ...,) with no deletions. In this case, compacting runs would be useless: all of the elements are sorted, the tree doesn’t have any garbage, and the location of any key can unequivocally be determined. On the other hand, if an LSM tree contains many deletions, doing a compaction would free up some disk space. However, even if there are no deletions, but key ranges in different runs overlap a lot, compacting such runs could speed up lookups as there would be fewer runs to scan. In this case, it might make sense to compact runs after each dump. But keep in mind that a compaction causes all data stored on disk to be overwritten, so with few reads it’s recommended to perform it less often." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:219 +msgid "To ensure it’s optimally configurable for any of the scenarios above, an LSM tree organizes all runs into a pyramid: the newer the data operations, the higher up the pyramid they are located. During a compaction, the algorithm picks two or more neighboring runs of approximately equal size, if possible." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:228 +msgid "Multi-level compaction can span any number of levels" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:229 +msgid "A level can contain multiple runs" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:231 +msgid "All of the neighboring runs of approximately equal size constitute an LSM tree level on disk. The ratio of run sizes at different levels determines the pyramid’s proportions, which allows optimizing the tree for write-intensive or read-intensive scenarios." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:236 +msgid "Suppose the L0 size is 100 Mb, the ratio of run sizes at each level (the ``vinyl_run_size_ratio`` parameter) is 5, and there can be no more than 2 runs per level (the ``vinyl_run_count_per_level`` parameter). After the first 3 dumps, the disk will contain 3 runs of 100 Mb each—which constitute L1 (level one). Since 3 > 2, the runs will be compacted into a single 300 Mb run, with the older ones being deleted. After 2 more dumps, there will be another compaction, this time of 2 runs of 100 Mb each and the 300 Mb run, which will produce one 500 Mb run. It will be moved to L2 (recall that the run size ratio is 5), leaving L1 empty. The next 10 dumps will result in L2 having 3 runs of 500 Mb each, which will be compacted into a single 1500 Mb run. Over the course of 10 more dumps, the following will happen: 3 runs of 100 Mb each will be compacted twice, as will two 100 Mb runs and one 300 Mb run, which will yield 2 new 500 Mb runs in L2. Since L2 now has 3 runs, they will also be compacted: two 500 Mb runs and one 1500 Mb run will produce a 2500 Mb run that will be moved to L3, given its size." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:251 +msgid "This can go on infinitely, but if an LSM tree contains lots of deletions, the resulting compacted run can be moved not only down, but also up the pyramid due to its size being smaller than the sizes of the original runs that were compacted. In other words, it’s enough to logically track which level a certain run belongs to, based on the run size and the smallest and greatest LSN among all of its operations." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:262 +msgid "Controlling the form of an LSM tree" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:264 +msgid "If it’s necessary to reduce the number of runs for lookups, then the run size ratio can be increased, thus bringing the number of levels down. If, on the other hand, you need to minimize the compaction-related overhead, then the run size ratio can be decreased: the pyramid will grow higher, and even though runs will be compacted more often, they will be smaller, which will reduce the total amount of work done. In general, write amplification in an LSM tree is described by this formula: :math:`log_{x}(\\frac {N} {L0}) × x` or, alternatively, :math:`x × \\frac {ln (\\frac {N} {C0})} {ln(x)}`, where N is the total size of all tree elements, L0 is the level zero size, and x is the level size ratio (the ``level_size_ratio`` parameter). At :math:`\\frac {N} {C0}` = 40 (the disk-to- memory ratio), the plot would look something like this:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:280 +msgid "As for read amplification, it’s proportional to the number of levels. The lookup cost at each level is no greater than that for a B-tree. Getting back to the example of a tree with 100,000,000 elements: given 256 Mb of RAM and the default values of ``vinyl_run_size_ratio`` and ``vinyl_run_count_per_level``, write amplification would come out to about 13, while read amplification could be as high as 150. Let’s try to figure out why this happens." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:291 +msgid "Search" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:293 +msgid "When doing a lookup in an LSM tree, what we need to find is not the element itself, but the most recent operation associated with it. If it’s a deletion, then the tree doesn’t contain this element. If it’s an insertion, we need to grab the topmost value in the pyramid, and the search can be stopped after finding the first matching key. In the worst-case scenario, that is if the tree doesn’t hold the needed element, the algorithm will have to sequentially visit all of the levels, starting from L0." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:305 +msgid "Unfortunately, this scenario is quite common in real life. For example, when inserting a value into a tree, it’s necessary to make sure there are no duplicates among primary/unique keys. So to speed up membership checks, LSM trees use a probabilistic data structure called a \"Bloom filter\", which will be covered a bit later, in a section on how vinyl works under the hood." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:315 +msgid "Range searching" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:317 +msgid "In the case of a single-key search, the algorithm stops after encountering the first match. However, when searching within a certain key range (for example, looking for all the users with the last name \"Ivanov\"), it’s necessary to scan all tree levels." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:324 +msgid "*Searching within a range of [24,30)*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:326 +msgid "The required range is formed the same way as when compacting several runs: the algorithm picks the key with the largest LSN out of all the sources, ignoring the other associated operations, then moves on to the next key and repeats the procedure." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:335 +msgid "Deletion" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:337 +msgid "Why would one store deletions? And why doesn’t it lead to a tree overflow in the case of for i=1,10000000 put(i) delete(i) end?" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:340 +msgid "With regards to lookups, deletions signal the absence of a value being searched; with compactions, they clear the tree of \"garbage\" records with older LSNs." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:343 +msgid "While the data is in RAM only, there’s no need to store deletions. Similarly, you don’t need to keep them following a compaction if they affect, among other things, the lowest tree level, which contains the oldest dump. Indeed, if a value can’t be found at the lowest level, then it doesn’t exist in the tree." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:348 +msgid "We can't delete from append-only files" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:349 +msgid "Tombstones (delete markers) are inserted into L0 instead" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:353 +msgid "*Deletion, step 1: a tombstone is inserted into L0*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:357 +msgid "*Deletion, step 2: the tombstone passes through intermediate levels*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:361 +msgid "*Deletion, step 3: in the case of a major compaction, the tombstone is removed from the tree*" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:363 +msgid "If a deletion is known to come right after the insertion of a unique value, which is often the case when modifying a value in a secondary index, then the deletion can safely be filtered out while compacting intermediate tree levels. This optimization is implemented in vinyl." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:372 +msgid "Advantages of an LSM tree" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:374 +msgid "Apart from decreasing write amplification, the approach that involves periodically dumping level L0 and compacting levels L1-Lk has a few advantages over the approach to writes adopted by B-trees:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:378 +msgid "Dumps and compactions write relatively large files: typically, the L0 size is 50-100 Mb, which is thousands of times larger than the size of a B-tree block." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:381 +msgid "This large size allows efficiently compressing data before writing it. Tarantool compresses data automatically, which further decreases write amplification." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:384 +msgid "There is no fragmentation overhead, since there’s no padding/empty space between the elements inside a run." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:386 +msgid "All operations create new runs instead of modifying older data in place. This allows avoiding those nasty locks that everyone hates so much. Several operations can run in parallel without causing any conflicts. This also simplifies making backups and moving data to replicas." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:391 +msgid "Storing older versions of data allows for the efficient implementation of transaction support by using multiversion concurrency control." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:399 +msgid "Disadvantages of an LSM tree and how to deal with them" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:401 +msgid "One of the key advantages of the B-tree as a search data structure is its predictability: all operations take no longer than :math:`log_{B}(N)` to run. Conversely, in a classical LSM tree, both read and write speeds can differ by a factor of hundreds (best case scenario) or even thousands (worst case scenario). For example, adding just one element to L0 can cause it to overflow, which can trigger a chain reaction in levels L1, L2, and so on. Lookups may find the needed element in L0 or may need to scan all of the tree levels. It’s also necessary to optimize reads within a single level to achieve speeds comparable to those of a B-tree. Fortunately, most disadvantages can be mitigated or even eliminated with additional algorithms and data structures. Let’s take a closer look at these disadvantages and how they’re dealt with in Tarantool." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:417 +msgid "Unpredictable write speed" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:419 +msgid "In an LSM tree, insertions almost always affect L0 only. How do you avoid idle time when the memory area allocated for L0 is full?" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:422 +msgid "Clearing L0 involves two lengthy operations: writing to disk and memory deallocation. To avoid idle time while L0 is being dumped, Tarantool uses writeaheads. Suppose the L0 size is 256 Mb. The disk write speed is 10 Mbps. Then it would take 26 seconds to dump L0. The insertion speed is 10,000 RPS, with each key having a size of 100 bytes. While L0 is being dumped, it’s necessary to reserve 26 Mb of RAM, effectively slicing the L0 size down to 230 Mb." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:430 +msgid "Tarantool does all of these calculations automatically, constantly updating the rolling average of the DBMS workload and the histogram of the disk speed. This allows using L0 as efficiently as possible and it prevents write requests from timing out. But in the case of workload surges, some wait time is still possible. That’s why we also introduced an insertion timeout (the ``vinyl_timeout`` parameter), which is set to 60 seconds by default. The write operation itself is executed in dedicated threads. The number of these threads (4 by default) is controlled by the ``vinyl_write_threads`` parameter. The default value of 2 allows doing dumps and compactions in parallel, which is also necessary for ensuring system predictability." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:441 +msgid "In Tarantool, compactions are always performed independently of dumps, in a separate execution thread. This is made possible by the append-only nature of an LSM tree: after dumps runs are never changed, and compactions simply create new runs." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:446 +msgid "Delays can also be caused by L0 rotation and the deallocation of memory dumped to disk: during a dump, L0 memory is owned by two operating system threads, a transaction processing thread and a write thread. Even though no elements are being added to the rotated L0, it can still be used for lookups. To avoid read locks when doing lookups, the write thread doesn’t deallocate the dumped memory, instead delegating this task to the transaction processor thread. Following a dump, memory deallocation itself happens instantaneously: to achieve this, L0 uses a special allocator that deallocates all of the memory with a single operation." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:458 +msgid "anticipatory dump" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:459 +msgid "throttling" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:461 +msgid "The dump is performed from the so-called \"shadow\" L0 without blocking new insertions and lookups" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:468 +msgid "Unpredictable read speed" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:470 +msgid "Optimizing reads is the most difficult optimization task with regards to LSM trees. The main complexity factor here is the number of levels: any optimization causes not only much slower lookups, but also tends to require significantly larger RAM resources. Fortunately, the append-only nature of LSM trees allows us to address these problems in ways that would be nontrivial for traditional data structures." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:479 +msgid "page index" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:480 +msgid "bloom filters" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:481 +msgid "tuple range cache" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:482 +msgid "multi-level compaction" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:488 +msgid "Compression and page index" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:490 +msgid "In B-trees, data compression is either the hardest problem to crack or a great marketing tool—rather than something really useful. In LSM trees, compression works as follows:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:494 +msgid "During a dump or compaction all of the data within a single run is split into pages. The page size (in bytes) is controlled by the ``vinyl_page_size`` parameter and can be set separately for each index. A page doesn’t have to be exactly of ``vinyl_page_size`` size—depending on the data it holds, it can be a little bit smaller or larger. Because of this, pages never have any empty space inside." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:501 +msgid "Data is compressed by `Facebook’s streaming algorithm `_ called \"zstd\". The first key of each page, along with the page offset, is added to a \"page index\", which is a separate file that allows the quick retrieval of any page. After a dump or compaction, the page index of the created run is also written to disk." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:508 +msgid "All `.index` files are cached in RAM, which allows finding the necessary page with a single lookup in a `.run` file (in vinyl, this is the extension of files resulting from a dump or compaction). Since data within a page is sorted, after it’s read and decompressed, the needed key can be found using a regular binary search. Decompression and reads are handled by separate threads, and are controlled by the ``vinyl_read_threads`` parameter." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:515 +msgid "Tarantool uses a universal file format: for example, the format of a `.run` file is no different from that of an `.xlog` file (log file). This simplifies backup and recovery as well as the usage of external tools." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:523 +msgid "Bloom filters" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:525 +msgid "Even though using a page index enables scanning fewer pages per run when doing a lookup, it’s still necessary to traverse all of the tree levels. There’s a special case, which involves checking if particular data is absent when scanning all of the tree levels and it’s unavoidable: I’m talking about insertions into a unique index. If the data being inserted already exists, then inserting the same data into a unique index should lead to an error. The only way to throw an error in an LSM tree before a transaction is committed is to do a search before inserting the data. Such reads form a class of their own in the DBMS world and are called \"hidden\" or \"parasitic\" reads." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:535 +msgid "Another operation leading to hidden reads is updating a value in a field on which a secondary index is defined. Secondary keys are regular LSM trees that store differently ordered data. In most cases, in order not to have to store all of the data in all of the indexes, a value associated with a given key is kept in whole only in the primary index (any index that stores both a key and a value is called \"covering\" or \"clustered\"), whereas the secondary index only stores the fields on which a secondary index is defined, and the values of the fields that are part of the primary index. Thus, each time a change is made to a value in a field on which a secondary index is defined, it’s necessary to first remove the old key from the secondary index—and only then can the new key be inserted. At update time, the old value is unknown, and it is this value that needs to be read in from the primary key \"under the hood\"." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:548 +msgid "For example:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:550 +msgid "update t1 set city=’Moscow’ where id=1" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:554 +msgid "To minimize the number of disk reads, especially for nonexistent data, nearly all LSM trees use probabilistic data structures, and Tarantool is no exception. A classical Bloom filter is made up of several (usually 3-to-5) bit arrays. When data is written, several hash functions are calculated for each key in order to get corresponding array positions. The bits at these positions are then set to 1. Due to possible hash collisions, some bits might be set to 1 twice. We’re most interested in the bits that remain 0 after all keys have been added. When looking for an element within a run, the same hash functions are applied to produce bit positions in the arrays. If any of the bits at these positions is 0, then the element is definitely not in the run. The probability of a false positive in a Bloom filter is calculated using Bayes’ theorem: each hash function is an independent random variable, so the probability of a collision simultaneously occurring in all of the bit arrays is infinitesimal." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:568 +msgid "The key advantage of Bloom filters in Tarantool is that they’re easily configurable. The only parameter that can be specified separately for each index is called ``vinyl_bloom_fpr`` (FPR stands for \"false positive ratio\") and it has the default value of 0.05, which translates to a 5% FPR. Based on this parameter, Tarantool automatically creates Bloom filters of the optimal size for partial- key and full-key searches. The Bloom filters are stored in the `.index` file, along with the page index, and are cached in RAM." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:580 +msgid "Caching" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:582 +msgid "A lot of people think that caching is a silver bullet that can help with any performance issue. \"When in doubt, add more cache\". In vinyl, caching is viewed rather as a means of reducing the overall workload and consequently, of getting a more stable response time for those requests that don’t hit the cache. vinyl boasts a unique type of cache among transactional systems called a \"range tuple cache\". Unlike, say, RocksDB or MySQL, this cache doesn’t store pages, but rather ranges of index values obtained from disk, after having performed a compaction spanning all tree levels. This allows the use of caching for both single-key and key-range searches. Since this method of caching stores only hot data and not, say, pages (you may need only some data from a page), RAM is used in the most efficient way possible. The cache size is controlled by the ``vinyl_cache`` parameter." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:599 +msgid "Garbage collection control" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:601 +msgid "Chances are that by now you’ve started losing focus and need a well-deserved dopamine reward. Feel free to take a break, since working through the rest of the article is going to take some serious mental effort." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:605 +msgid "An LSM tree in vinyl is just a small piece of the puzzle. Even with a single table (or so-called \"space\"), vinyl creates and maintains several LSM trees, one for each index. But even a single index can be comprised of dozens of LSM trees. Let’s try to understand why this might be necessary." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:610 +msgid "Recall our example with a tree containing 100,000,000 records, 100 bytes each. As time passes, the lowest LSM level may end up holding a 10 Gb run. During compaction, a temporary run of approximately the same size will be created. Data at intermediate levels takes up some space as well, since the tree may store several operations associated with a single key. In total, storing 10 Gb of actual data may require up to 30 Gb of free space: 10 Gb for the last tree level, 10 Gb for a temporary run, and 10 Gb for the remaining data. But what if the data size is not 10 Gb, but 1 Tb? Requiring that the available disk space always be several times greater than the actual data size is financially unpractical, not to mention that it may take dozens of hours to create a 1 Tb run. And in the case of an emergency shutdown or system restart, the process would have to be started from scratch." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:623 +msgid "Here’s another scenario. Suppose the primary key is a monotonically increasing sequence—for example, a time series. In this case, most insertions will fall into the right part of the key range, so it wouldn’t make much sense to do a compaction just to append a few million more records to an already huge run." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:628 +msgid "But what if writes predominantly occur in a particular region of the key range, whereas most reads take place in a different region? How do you optimize the form of the LSM tree in this case? If it’s too high, read performance is impacted; if it’s too low—write speed is reduced." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:633 +msgid "Tarantool \"factorizes\" this problem by creating multiple LSM trees for each index. The approximate size of each subtree may be controlled by the :ref:`vinyl_range_size ` configuration parameter. We call such subtrees \"ranges\"." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:642 +msgid "Factorizing large LSM trees via ranging" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:644 +msgid "Ranges reflect a static layout of sorted runs" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:645 +msgid "Slices connect a sorted run into a range" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:649 +msgid "Initially, when the index has few elements, it consists of a single range. As more elements are added, its total size may exceed :ref:`the maximum range size `. In that case a special operation called \"split\" divides the tree into two equal parts. The tree is split at the middle element in the range of keys stored in the tree. For example, if the tree initially stores the full range of -inf…+inf, then after splitting it at the middle key X, we get two subtrees: one that stores the range of -inf...X, and the other storing the range of X…+inf. With this approach, we always know which subtree to use for writes and which one for reads. If the tree contained deletions and each of the neighboring ranges grew smaller as a result, the opposite operation called \"coalesce\" combines two neighboring trees into one." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:662 +msgid "Split and coalesce don’t entail a compaction, the creation of new runs, or other resource-intensive operations. An LSM tree is just a collection of runs. vinyl has a special metadata log that helps keep track of which run belongs to which subtree(s). This has the `.vylog` extension and its format is compatible with an .xlog file. Similarly to an `.xlog` file, the metadata log gets rotated at each checkpoint. To avoid the creation of extra runs with split and coalesce, we have also introduced an auxiliary entity called \"slice\". It’s a reference to a run containing a key range and it’s stored only in the metadata log. Once the reference counter drops to zero, the corresponding file gets removed. When it’s necessary to perform a split or to coalesce, Tarantool creates slice objects for each new tree, removes older slices, and writes these operations to the metadata log, which literally stores records that look like this: ```` or ````." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:676 +msgid "This way all of the heavy lifting associated with splitting a tree into two subtrees is postponed until a compaction and then is performed automatically. A huge advantage of dividing all of the keys into ranges is the ability to independently control the L0 size as well as the dump and compaction processes for each subtree, which makes these processes manageable and predictable. Having a separate metadata log also simplifies the implementation of both \"truncate\" and \"drop\". In vinyl, they’re processed instantly, since they only work with the metadata log, while garbage collection is done in the background." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:689 +msgid "Advanced features of vinyl" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:695 +msgid "Upsert" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:697 +msgid "In the previous sections, we mentioned only two operations stored by an LSM tree: deletion and replacement. Let’s take a look at how all of the other operations can be represented. An insertion can be represented via a replacement—you just need to make sure there are no other elements with the specified key. To perform an update, it’s necessary to read the older value from the tree, so it’s easier to represent this operation as a replacement as well—this speeds up future read requests by the key. Besides, an update must return the new value, so there’s no avoiding hidden reads." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:706 +msgid "In B-trees, the cost of hidden reads is negligible: to update a block, it first needs to be read from disk anyway. Creating a special update operation for an LSM tree that doesn’t cause any hidden reads is really tempting." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:711 +msgid "Such an operation must contain not only a default value to be inserted if a key has no value yet, but also a list of update operations to perform if a value does exist." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:715 +msgid "At transaction execution time, Tarantool just saves the operation in an LSM tree, then \"executes\" it later, during a compaction." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:719 +msgid "The upsert operation:" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:721 +msgid "space:upsert(tuple, {{operator, field, value}, ... })" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:725 +msgid "Non-reading update or insert" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:726 +msgid "Delayed execution" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:727 +msgid "Background upsert squashing prevents upserts from piling up" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:729 +msgid "Unfortunately, postponing the operation execution until a compaction doesn’t leave much leeway in terms of error handling. That’s why Tarantool tries to validate upserts as fully as possible before writing them to an LSM tree. However, some checks are only possible with older data on hand, for example when the update operation is trying to add a number to a string or to remove a field that doesn’t exist." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:736 +msgid "A semantically similar operation exists in many products including PostgreSQL and MongoDB. But anywhere you look, it’s just syntactic sugar that combines the update and replace operations without avoiding hidden reads. Most probably, the reason is that LSM trees as data storage structures are relatively new." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:742 +msgid "Even though an upsert is a very important optimization and implementing it cost us a lot of blood, sweat, and tears, we must admit that it has limited applicability. If a table contains secondary keys or triggers, hidden reads can’t be avoided. But if you have a scenario where secondary keys are not required and the update following the transaction completion will certainly not cause any errors, then the operation is for you." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:749 +msgid "I’d like to tell you a short story about an upsert. It takes place back when vinyl was only beginning to \"mature\" and we were using an upsert in production for the first time. We had what seemed like an ideal environment for it: we had tons of keys, the current time was being used as values; update operations were inserting keys or modifying the current time; and we had few reads. Load tests yielded great results." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:757 +msgid "Nevertheless, after a couple of days, the Tarantool process started eating up 100% of our CPU, and the system performance dropped close to zero." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:760 +msgid "We started digging into the issue and found out that the distribution of requests across keys was significantly different from what we had seen in the test environment. It was...well, quite nonuniform. Most keys were updated once or twice a day, so the database was idle for the most part, but there were much hotter keys with tens of thousands of updates per day. Tarantool handled those just fine. But in the case of lookups by key with tens of thousands of upserts, things quickly went downhill. To return the most recent value, Tarantool had to read and \"replay\" the whole history consisting of all of the upserts. When designing upserts, we had hoped this would happen automatically during a compaction, but the process never even got to that stage: the L0 size was more than enough, so there were no dumps." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:773 +msgid "We solved the problem by adding a background process that performed readaheads on any keys that had more than a few dozen upserts piled up, so all those upserts were squashed and substituted with the read value." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:782 +msgid "Secondary keys" +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:784 +msgid "Update is not the only operation where optimizing hidden reads is critical. Even the replace operation, given secondary keys, has to read the older value: it needs to be independently deleted from the secondary indexes, and inserting a new element might not do this, leaving some garbage behind." +msgstr "" + +#: ../../doc/concepts/engines/vinyl.rst:794 +msgid "If secondary indexes are not unique, then collecting \"garbage\" from them can be put off until a compaction, which is what we do in Tarantool. The append-only nature of LSM trees allowed us to implement full-blown serializable transactions in vinyl. Read-only requests use older versions of data without blocking any writes. The transaction manager itself is fairly simple for now: in classical terms, it implements the MVTO (multiversion timestamp ordering) class, whereby the winning transaction is the one that finished earlier. There are no locks and associated deadlocks. Strange as it may seem, this is a drawback rather than an advantage: with parallel execution, you can increase the number of successful transactions by simply holding some of them on lock when necessary. We’re planning to improve the transaction manager soon. In the current release, we focused on making the algorithm behave 100% correctly and predictably. For example, our transaction manager is one of the few on the NoSQL market that supports so-called \"gap locks\"." +msgstr "" diff --git a/locale/en/platform/replication/index.pot b/locale/en/platform/replication/index.pot new file mode 100644 index 0000000000..68cc57df78 --- /dev/null +++ b/locale/en/platform/replication/index.pot @@ -0,0 +1,33 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/replication/index.rst:7 +msgid "Replication" +msgstr "" + +#: ../../doc/concepts/replication/index.rst:9 +msgid "Replication allows multiple Tarantool instances to work on copies of the same databases. The databases are kept in sync because each instance can communicate its changes to all the other instances." +msgstr "" + +#: ../../doc/concepts/replication/index.rst:13 +msgid "This section includes the following topics:" +msgstr "" + +#: ../../doc/concepts/replication/index.rst:23 +msgid "For practical guides to replication, see :ref:`Replication tutorials `. You can learn about bootstrapping a replica set, adding instances to the replica set, or removing them." +msgstr "" diff --git a/locale/en/platform/replication/repl_architecture.pot b/locale/en/platform/replication/repl_architecture.pot new file mode 100644 index 0000000000..127d9eb8b9 --- /dev/null +++ b/locale/en/platform/replication/repl_architecture.pot @@ -0,0 +1,258 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/replication/repl_architecture.rst:4 +msgid "Replication architecture" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:9 +msgid "Replication mechanism" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:14 +msgid "Overview" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:16 +msgid "A pack of instances that operate on copies of the same databases makes up a **replica set**. Each instance in a replica set has a role: **master** or **replica**." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:19 +msgid "A replica gets all updates from the master by continuously fetching and applying its :ref:`write-ahead log (WAL) `. Each record in the WAL represents a single Tarantool data-change request such as :ref:`INSERT `, :ref:`UPDATE `, or :ref:`DELETE `, and is assigned a monotonically growing log sequence number (**LSN**). In essence, Tarantool replication is **row-based**: each data-change request is fully deterministic and operates on a single :ref:`tuple `. However, unlike a classical row-based log, which contains entire copies of the changed rows, Tarantool's WAL contains copies of the requests. For example, for UPDATE requests, Tarantool only stores the primary key of the row and the update operations to save space." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:32 +msgid ":ref:`WAL extensions ` available in Tarantool Enterprise Edition enable you to add auxiliary information to each write-ahead log record. This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:35 +msgid "The following are specifics of adding different types of information to the WAL:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:37 +msgid "Invocations of **stored programs** are not written to the WAL. Instead, records of the actual **data-change requests, performed by the Lua code**, are written to the WAL. This ensures that the possible non-determinism of Lua does not cause replication to go out of sync." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:41 +msgid "Data definition operations on **temporary spaces** (:doc:`created ` with ``temporary = true``), such as creating/dropping, adding indexes, and truncating, are written to the WAL, since information about temporary spaces is stored in non-temporary system spaces, such as :ref:`box.space._space `." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:43 +msgid "Data change operations on temporary spaces are not written to the WAL and are not replicated." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:47 +msgid "Data change operations on **replication-local** spaces (:doc:`created ` with ``is_local = true``) are written to the WAL but are not replicated." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:50 +msgid "To learn how to enable replication, check the :ref:`Bootstrapping a replica set ` guide." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:56 +msgid "Replication stages" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:58 +msgid "To create a valid initial state, to which WAL changes can be applied, every instance of a replica set requires a start set of :ref:`checkpoint files `, such as ``.snap`` files for memtx and ``.run`` files for vinyl. A replica goes through the following stages:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:62 +msgid "**Bootstrap** (optional)" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:64 +msgid "When an entire replica set is bootstrapped for the first time, there is no master that could provide the initial checkpoint. In such a case, replicas connect to each other and elect a master. The master creates the starting set of checkpoint files and distributes them to all the other replicas. This is called an **automatic bootstrap** of a replica set." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:69 +msgid "**Join**" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:71 +msgid "At this stage, a replica downloads the initial state from the master. The master register this replica in the :ref:`box.space._cluster ` space. If join fails with a non-critical :ref:`error `, for example, ``ER_READONLY``, ``ER_ACCESS_DENIED``, or a network-related issue, an instance tries to find a new master to join." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:77 +msgid "On subsequent connections, a replica downloads all changes happened after the latest local LSN (there can be many LSNs – each master has its own LSN)." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:79 +msgid "**Follow**" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:81 +msgid "At this stage, a replica fetches and applies updates from the master's write-ahead log." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:83 +msgid "You can use the :ref:`box.info.replication[n].upstream.status ` property to monitor the status of a replica." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:89 +msgid "Replica set and instance UUIDs" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:91 +msgid "Each replica set is identified by a globally unique identifier, called the **replica set UUID**. The identifier is created by the master, which creates the very first checkpoint and is part of the checkpoint file. It is stored in the :ref:`box.space._schema ` system space, for example:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:94 +msgid "tarantool> box.space._schema:select{'cluster'}\n" +"---\n" +"- - ['cluster', '6308acb9-9788-42fa-8101-2e0cb9d3c9a0']\n" +"..." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:103 +msgid "Additionally, each instance in a replica set is assigned its own UUID, when it joins the replica set. It is called an **instance UUID** and is a globally unique identifier. The instance UUID is checked to ensure that instances do not join a different replica set, e.g. because of a configuration error. A unique instance identifier is also necessary to apply rows originating from different masters only once, that is, to implement multi-master replication. This is why each row in the write-ahead log, in addition to its log sequence number, stores the instance identifier of the instance on which it was created. But using a UUID as such an identifier would take too much space in the write-ahead log, thus a shorter integer number is assigned to the instance when it joins a replica set. This number is then used to refer to the instance in the write-ahead log. It is called **instance ID**. All identifiers are stored in the system space :ref:`box.space._cluster `, for example:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:117 +msgid "tarantool> box.space._cluster:select{}\n" +"---\n" +"- - [1, '88580b5c-4474-43ab-bd2b-2409a9af80d2']\n" +"..." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:124 +msgid "Here the instance ID is ``1`` (unique within the replica set), and the instance UUID is ``88580b5c-4474-43ab-bd2b-2409a9af80d2`` (globally unique)." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:127 +msgid "Using instance IDs is also handy for tracking the state of the entire replica set. For example, :ref:`box.info.vclock ` describes the state of replication in regard to each connected peer." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:131 +msgid "tarantool> box.info.vclock\n" +"---\n" +"- {1: 827, 2: 584}\n" +"..." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:138 +msgid "Here ``vclock`` contains log sequence numbers (827 and 584) for instances with instance IDs ``1`` and ``2``." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:141 +msgid "If required, you can explicitly specify the instance and the replica set UUID values rather than letting Tarantool generate them. To learn more, see the :ref:`replicaset_uuid ` configuration parameter description." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:149 +msgid "Replication roles: master and replica" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:151 +msgid "The replication role (master or replica) is set by the :ref:`read_only ` configuration parameter. The recommended role is \"read_only\" (replica) for all but one instance in the replica set." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:155 +msgid "In a master-replica configuration, every change that happens on the master will be visible on the replicas, but not vice versa." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:161 +msgid "A simple two-instance replica set with the master on one machine and the replica on a different machine provides two benefits:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:164 +msgid "**failover**, because if the master goes down, then the replica can take over, and" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:166 +msgid "**load balancing**, because clients can connect to either the master or the replica for read requests." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:169 +msgid "In a **master-master** configuration (also called \"multi-master\"), every change that happens on either instance will be visible on the other one." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:175 +msgid "The failover benefit in this case is still present, and the load-balancing benefit is enhanced, because any instance can handle both read and write requests. Meanwhile, for multi-master configurations, it is necessary to understand the **replication guarantees** provided by the asynchronous protocol that Tarantool implements." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:181 +msgid "Tarantool multi-master replication guarantees that each change on each master is propagated to all instances and is applied only once. Changes from the same instance are applied in the same order as on the originating instance. Changes from different instances, however, can be mixed and applied in a different order on different instances. This may lead to replication going out of sync in certain cases." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:188 +msgid "For example, assuming the database is only appended to (i.e. it contains only insertions), a multi-master configuration is safe. If there are also deletions, but it is not mission critical that deletion happens in the same order on all replicas (e.g. the DELETE is used to prune expired data), a master-master configuration is also safe." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:194 +msgid "UPDATE operations, however, can easily go out of sync. For example, assignment and increment are not commutative and may yield different results if applied in a different order on different instances." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:198 +msgid "More generally, it is only safe to use Tarantool master-master replication if all database changes are **commutative**: the end result does not depend on the order in which the changes are applied. You can start learning more about conflict-free replicated data types `here `_." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:207 +msgid "Replication topologies: cascade, ring, and full mesh" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:209 +msgid "Replication topology is set by the :ref:`replication ` configuration parameter. The recommended topology is a **full mesh** because it makes potential failover easy." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:213 +msgid "Some database products offer **cascading replication** topologies: creating a replica on a replica. Tarantool does not recommend such a setup." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:219 +msgid "The problem with a cascading replica set is that some instances have no connection to other instances and may not receive changes from them. One essential change that must be propagated across all instances in a replica set is an entry in ``box.space._cluster`` system space with the replica set UUID. Without knowing the replica set UUID, a master refuses to accept connections from such instances when replication topology changes. Here is how this can happen:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:229 +msgid "We have a chain of three instances. Instance #1 contains entries for instances #1 and #2 in its ``_cluster`` space. Instances #2 and #3 contain entries for instances #1, #2, and #3 in their ``_cluster`` spaces." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:236 +msgid "Now instance #2 is faulty. Instance #3 tries connecting to instance #1 as its new master, but the master refuses the connection since it has no entry, for example, #3." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:240 +msgid "**Ring replication** topology is, however, supported:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:245 +msgid "So, if you need a cascading topology, you may first create a ring to ensure all instances know each other’s UUID, and then disconnect the chain in the place you desire." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:249 +msgid "A stock recommendation for a master-master replication topology, however, is a **full mesh**:" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:255 +msgid "You then can decide where to locate instances of the mesh -- within the same data center, or spread across a few data centers. Tarantool will automatically ensure that each row is applied only once on each instance. To remove a degraded instance from a mesh, simply change the ``replication`` configuration parameter." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:260 +msgid "This ensures full cluster availability in case of a local failure, e.g. one of the instances failing in one of the data centers, as well as in case of an entire data center failure." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:264 +msgid "The maximal number of replicas in a mesh is 32." +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:267 +msgid "Orphan status" +msgstr "" + +#: ../../doc/concepts/replication/repl_architecture.rst:269 +msgid "During ``box.cfg()``, an instance tries to join all nodes listed in :ref:`box.cfg.replication `. If the instance does not succeed in connecting to the required number of nodes (see :ref:`bootstrap_strategy `), it switches to the :ref:`orphan status `." +msgstr "" diff --git a/locale/en/platform/replication/repl_leader_elect.pot b/locale/en/platform/replication/repl_leader_elect.pot new file mode 100644 index 0000000000..bebb673099 --- /dev/null +++ b/locale/en/platform/replication/repl_leader_elect.pot @@ -0,0 +1,260 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:4 +msgid "Automated leader election" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:6 +msgid "Starting from version :doc:`2.6.1 `, Tarantool has the built-in functionality managing automated *leader election* in a replica set. This functionality increases the fault tolerance of the systems built on the base of Tarantool and decreases dependency on external tools for replica set management." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:13 +msgid "To learn how to configure and monitor automated leader elections, check :ref:`Managing leader elections `." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:16 +msgid "The following topics are described below:" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:25 +msgid "Leader election and synchronous replication" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:27 +msgid "Leader election and synchronous replication are implemented in Tarantool as a modification of the `Raft `__ algorithm. Raft is an algorithm of synchronous replication and automatic leader election. Its complete description can be found in the `corresponding document `_." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:33 +msgid "In Tarantool, :ref:`synchronous replication ` and leader election are supported as two separate subsystems. So it is possible to get synchronous replication but use an alternative algorithm for leader election. And vice versa -- elect a leader in the cluster but don't use synchronous spaces at all. Synchronous replication has a separate :ref:`documentation section `. Leader election is described below." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:44 +msgid "The system behavior can be specified exactly according to the Raft algorithm. To do this:" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:46 +msgid "Ensure that the user has only synchronous spaces." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:47 +msgid "Set the :ref:`replication.synchro_quorum ` option to ``N / 2 + 1``." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:48 +msgid "Set the :ref:`replication.synchro_timeout ` option to infinity." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:49 +msgid "In the :ref:`replication.election_fencing_mode ` option, select either the ``soft`` mode (the default) or the ``strict`` mode, which is more restrictive." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:55 +msgid "Leader election process" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:57 +msgid "Automated leader election in Tarantool helps guarantee that there is at most one leader at any given moment of time in a replica set. A *leader* is a writable node, and all other nodes are non-writable -- they accept read-only requests exclusively." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:62 +msgid "When :ref:`the election is enabled `, the life cycle of a replica set is divided into so-called *terms*. Each term is described by a monotonically growing number. After the first boot, each node has its term equal to 1. When a node sees that it is not a leader and there is no leader available for some time in the replica set, it increases the term and starts a new leader election round." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:69 +msgid "Leader election happens via votes. The node that started the election votes for itself and sends vote requests to other nodes. Upon receiving vote requests, a node votes for the first of them, and then cannot do anything in the same term but wait for a leader to be elected." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:74 +msgid "The node that collected a quorum of votes defined by the :ref:`replication.synchro_quorum ` parameter becomes the leader and notifies other nodes about that. Also, a split vote can happen when no nodes received a quorum of votes. In this case, after a random timeout, each node increases its term and starts a new election round if no new vote request with a greater term arrives during this time. Eventually, a leader is elected." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:83 +msgid "If any unfinalized synchronous transactions are left from the previous leader, the new leader finalizes them automatically." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:86 +msgid "All the non-leader nodes are called *followers*. The nodes that start a new election round are called *candidates*. The elected leader sends heartbeats to the non-leader nodes to let them know it is alive." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:90 +msgid "In case there are no heartbeats for the period of :ref:`replication.timeout ` * 4, a non-leader node starts a new election if the following conditions are met:" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:93 +msgid "The node has a quorum of connections to other cluster members." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:94 +msgid "None of these cluster members can see the leader node." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:98 +msgid "A cluster member considers the leader node to be alive if the member received heartbeats from the leader at least once during the ``replication.timeout * 4``, and there are no replication errors (the connection is not broken due to timeout or due to an error)." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:102 +msgid "Terms and votes are persisted by each instance to preserve certain Raft guarantees." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:104 +msgid "During the election, the nodes prefer to vote for those ones that have the newest data. So as if an old leader managed to send something before its death to a quorum of replicas, that data wouldn't be lost." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:108 +msgid "When election is enabled, there must be connections between each node pair so as it would be the full mesh topology. This is needed because election messages for voting and other internal things need a direct connection between the nodes." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:115 +msgid "In the classic Raft algorithm, a leader doesn't track its connectivity to the rest of the cluster. Once the leader is elected, it considers itself in the leader position until receiving a new term from another cluster node. This can lead to a split situation if the other nodes elect a new leader upon losing the connectivity to the previous one." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:119 +msgid "The issue is resolved in Tarantool version :doc:`2.10.0 ` by introducing the leader *fencing* mode. The mode can be switched by the :ref:`replication.election_fencing_mode ` configuration parameter. When the fencing is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than :ref:`replication.synchro_quorum ` of alive connections to the cluster nodes. The resigning leader receives the status of a follower in the current election term and becomes read-only. Leader *fencing* can be turned off by setting the :ref:`replication.election_fencing_mode ` configuration parameter to ``off``." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:126 +msgid "In ``soft`` mode, a connection is considered dead if there are no responses for :ref:`4 * replication.timeout ` seconds both on the current leader and the followers." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:129 +msgid "In ``strict`` mode, a connection is considered dead if there are no responses for :ref:`2 * replication.timeout ` seconds on the current leader and for :ref:`4 * replication.timeout ` seconds on the followers. This improves chances that there is only one leader at any time." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:134 +msgid "Fencing applies to the instances that have the :ref:`replication.election_mode ` set to \"candidate\" or \"manual\"." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:138 +msgid "There can still be a situation when a replica set has two leaders working independently (so-called *split-brain*). It can happen, for example, if a user mistakenly lowered the :ref:`replication.synchro_quorum ` below ``N / 2 + 1``. In this situation, to preserve the data integrity, if an instance detects the split-brain anomaly in the incoming replication data, it breaks the connection with the instance sending the data and writes the ``ER_SPLIT_BRAIN`` error in the log." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:143 +msgid "Eventually, there will be two sets of nodes with the diverged data, and any node from one set is disconnected from any node from the other set with the ``ER_SPLIT_BRAIN`` error." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:146 +msgid "Once noticing the error, a user can choose any representative from each of the sets and inspect the data on them. To correlate the data, the user should remove it from the nodes of one set, and reconnect them to the nodes from the other set that have the correct data." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:150 +msgid "Also, if election is enabled on the node, it doesn't replicate from any nodes except the newest leader. This is done to avoid the issue when a new leader is elected, but the old leader has somehow survived and tries to send more changes to the other nodes." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:155 +msgid "Term numbers also work as a kind of filter. For example, if election is enabled on two nodes and ``node1`` has the term number less than ``node2``, then ``node2`` doesn't accept any transactions from ``node1``." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:163 +msgid "Managing leader elections" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:168 +msgid "Configuration" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:170 +msgid "replication:\n" +" election_mode: \n" +" election_fencing_mode: \n" +" election_timeout: \n" +" timeout: \n" +" synchro_quorum: " +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:180 +msgid ":ref:`replication.election_mode ` -- specifies the role of a node in the leader election process." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:182 +msgid ":ref:`replication.election_fencing_mode ` -- specifies the :ref:`leader fencing mode `." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:183 +msgid ":ref:`replication.election_timeout ` -- specifies the timeout between election rounds if the previous round ended up with a split vote." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:185 +msgid ":ref:`replication.timeout ` -- a time interval (in seconds) used by a master to send heartbeat requests to a replica when there are no updates to send to this replica." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:186 +msgid ":ref:`replication.synchro_quorum ` -- a number of replicas that should confirm the receipt of a :ref:`synchronous ` transaction before it can finish its commit." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:188 +msgid "It is important to know that being a leader is not the only requirement for a node to be writable. The leader should also satisfy the following requirements:" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:191 +msgid "The :ref:`database.mode ` option is set to ``rw``." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:193 +msgid "The leader shouldn't be in the orphan state." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:195 +msgid "Nothing prevents you from setting the ``database.mode`` option to ``ro``, but the leader won't be writable then. The option doesn't affect the election process itself, so a read-only instance can still vote and become a leader." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:203 +msgid "Monitoring" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:205 +msgid "To monitor the current state of a node regarding the leader election, use the :doc:`box.info.election ` function." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:207 +msgid "**Example:**" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:209 +msgid "tarantool> box.info.election\n" +"---\n" +"- state: follower\n" +" vote: 0\n" +" leader: 0\n" +" term: 1\n" +"..." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:219 +msgid "The Raft-based election implementation logs all its actions with the ``RAFT:`` prefix. The actions are new Raft message handling, node state changing, voting, and term bumping." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:226 +msgid "Important notes" +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:228 +msgid "Leader election doesn't work correctly if the election quorum is set to less or equal than `` / 2``. In that case, a split vote can lead to a state when two leaders are elected at once." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:232 +msgid "For example, suppose there are five nodes. When the quorum is set to ``2``, ``node1`` and ``node2`` can both vote for ``node1``. ``node3`` and ``node4`` can both vote for ``node5``. In this case, ``node1`` and ``node5`` both win the election. When the quorum is set to the cluster majority, that is ``( / 2) + 1`` or greater, the split vote is impossible." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:238 +msgid "That should be considered when adding new nodes. If the majority value is changing, it's better to update the quorum on all the existing nodes before adding a new one." +msgstr "" + +#: ../../doc/concepts/replication/repl_leader_elect.rst:242 +msgid "Also, the automated leader election doesn't bring many benefits in terms of data safety when used *without* :ref:`synchronous replication `. If the replication is asynchronous and a new leader gets elected, the old leader is still active and considers itself the leader. In such case, nothing stops it from accepting requests from clients and making transactions. Non-synchronous transactions are successfully committed because they are not checked against the quorum of replicas. Synchronous transactions fail because they are not able to collect the quorum -- most of the replicas reject these old leader's transactions since it is not a leader anymore." +msgstr "" diff --git a/locale/en/platform/replication/repl_sync.pot b/locale/en/platform/replication/repl_sync.pot new file mode 100644 index 0000000000..78e15a2bdd --- /dev/null +++ b/locale/en/platform/replication/repl_sync.pot @@ -0,0 +1,89 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/replication/repl_sync.rst:4 +msgid "Synchronous replication" +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:7 +msgid "Overview" +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:9 +msgid "By default, replication in Tarantool is **asynchronous**: if a transaction is committed locally on a master node, it does not mean it is replicated onto any replicas. If a master responds success to a client and then dies, after failover to a replica, from the client's point of view the transaction will disappear." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:14 +msgid "**Synchronous** replication exists to solve this problem. Synchronous transactions are not considered committed and are not responded to a client until they are replicated onto some number of replicas." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:18 +msgid "To enable synchronous replication, use the :ref:`space_opts.is_sync ` option when creating or altering a space." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:21 +msgid "Synchronous and asynchronous transactions" +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:23 +msgid "A killer feature of Tarantool's synchronous replication is its being *per-space*. So, if you need it only rarely for some critical data changes, you won't pay for it in performance terms." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:27 +msgid "When there is more than one synchronous transaction, they all wait for being replicated. Moreover, if an asynchronous transaction appears, it will also be blocked by the existing synchronous transactions. This behavior is very similar to a regular queue of asynchronous transactions because all the transactions are committed in the same order as they make the :ref:`box.commit() ` call. So, here comes **the commit rule**: transactions are committed in the same order as they make the ``box.commit()`` call -- regardless of being synchronous or asynchronous." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:36 +msgid "If one of the waiting synchronous transactions times out and is rolled back, it will first roll back all the newer pending transactions. Again, just like how asynchronous transactions are rolled back when WAL write fails. So, here comes **the rollback rule:** transactions are always rolled back in the order reversed from the one they make the ``box.commit()`` call -- regardless of being synchronous or asynchronous." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:43 +msgid "One more important thing is that if an asynchronous transaction is blocked by a synchronous transaction, it does not become synchronous as well. This just means it will wait for the synchronous transaction to be committed. But once it is done, the asynchronous transaction will be committed immediately -- it won't wait for being replicated itself." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:51 +msgid "Be careful when using synchronous and asynchronous transactions together. Asynchronous transactions are considered committed even if there is no connection to other nodes. Therefore, an old leader node (:ref:`synchronous transaction queue owner `) might have some committed asynchronous transactions that no other replica set member has." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:56 +msgid "When the connection to such an old (previous) leader node is restored, it starts receiving data from the new leader. At the same time, other replica set members receive the data from the previous leader that they don't have yet. The data from the previous leader contains some committed asynchronous transactions. At this time, the integrity protection will throw the :ref:`ER_SPLIT_BRAIN ` error, which will force the user to rebootstrap the previous leader." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:64 +msgid "Limitations and known problems" +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:66 +msgid "Until version :doc:`2.5.2 `, there was no way to enable synchronous replication for existing spaces, but since 2.5.2 it can be enabled by :ref:`space_object:alter({is_sync = true}) `." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:71 +msgid "Synchronous transactions work only for master-slave topology. You can have multiple replicas, anonymous replicas, but only one node can make synchronous transactions." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:74 +msgid "Since Tarantool :doc:`2.10.0 `, anonymous replicas do not participate in the quorum." +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:77 +msgid "Leader election" +msgstr "" + +#: ../../doc/concepts/replication/repl_sync.rst:79 +msgid "Starting from version :doc:`2.6.1 `, Tarantool has the built-in functionality managing automated leader election in a replica set. For more information, refer to the :ref:`corresponding chapter `." +msgstr "" diff --git a/locale/en/platform/security/audit.pot b/locale/en/platform/security/audit.pot new file mode 100644 index 0000000000..876188658f --- /dev/null +++ b/locale/en/platform/security/audit.pot @@ -0,0 +1,224 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/audit.rst:2 +msgid "Security audit" +msgstr "" + +#: ../../doc/enterprise/audit.rst:4 +msgid "This document will help you audit the security of a Tarantool cluster. It explains certain security aspects, their rationale, and the ways to check them. For details on how to configure Tarantool Enterprise Edition and its infrastructure for each aspect, refer to the :doc:`security hardening guide `." +msgstr "" + +#: ../../doc/enterprise/audit.rst:10 +msgid "Encryption of external iproto traffic" +msgstr "" + +#: ../../doc/enterprise/audit.rst:12 +msgid "Tarantool uses the :doc:`iproto binary protocol ` for replicating data between instances and also in the connector libraries." +msgstr "" + +#: ../../doc/enterprise/audit.rst:16 +msgid "Since version 2.10.0, the Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over binary connections. For details on enabling SSL encryption, see the :ref:`enterprise-iproto-encryption` section of this document." +msgstr "" + +#: ../../doc/enterprise/audit.rst:19 +msgid "In case the built-in encryption is not enabled, we recommend using VPN to secure data exchange between data centers." +msgstr "" + +#: ../../doc/enterprise/audit.rst:22 +msgid "Closed iproto ports" +msgstr "" + +#: ../../doc/enterprise/audit.rst:24 +msgid "When a Tarantool cluster does not use iproto for external requests, connections to the iproto ports should be allowed only between Tarantool instances." +msgstr "" + +#: ../../doc/enterprise/audit.rst:27 +msgid "For more details on configuring ports for iproto, see the ``advertise_uri`` section in the Cartridge documentation." +msgstr "" + +#: ../../doc/enterprise/audit.rst:32 +msgid "HTTPS connection termination" +msgstr "" + +#: ../../doc/enterprise/audit.rst:34 +msgid "A Tarantool instance can accept HTTP connections from external services or access the administrative web UI. All such connections must go through an HTTPS-providing web server, running on the same host, such as nginx. This requirement is for both virtual and physical hosts. Running HTTP traffic through a few separate hosts with HTTPS termination is not sufficiently secure." +msgstr "" + +#: ../../doc/enterprise/audit.rst:44 +msgid "Closed HTTP ports" +msgstr "" + +#: ../../doc/enterprise/audit.rst:48 +msgid "Tarantool accepts HTTP connections on a specific port. It must be only available on the same host for nginx to connect to it." +msgstr "" + +#: ../../doc/enterprise/audit.rst:51 +msgid "Check that the configured HTTP port is closed and that the HTTPS port (``443`` by default) is open." +msgstr "" + +#: ../../doc/enterprise/audit.rst:55 +msgid "Restricted access to the administrative console" +msgstr "" + +#: ../../doc/enterprise/audit.rst:57 +msgid "The :doc:`console ` module provides a way to connect to a running instance and run custom Lua code. This can be useful for development and administration. The following code examples open connections on a TCP port and on a UNIX socket." +msgstr "" + +#: ../../doc/enterprise/audit.rst:62 +msgid "console.listen()\n" +"console.listen('/var/lib/tarantool/socket_name.sock')" +msgstr "" + +#: ../../doc/enterprise/audit.rst:67 +msgid "Opening an administrative console through a TCP port is always unsafe. Check that there are no calls like ``console.listen()`` in the code." +msgstr "" + +#: ../../doc/enterprise/audit.rst:71 +msgid "Connecting through a socket requires having the write permission on the ``/var/lib/tarantool`` directory. Check that write permission to this directory is limited to the ``tarantool`` user." +msgstr "" + +#: ../../doc/enterprise/audit.rst:76 +msgid "Limiting the guest user" +msgstr "" + +#: ../../doc/enterprise/audit.rst:78 +msgid "Connecting to the instance with ``tt connect`` or ``tarantoolctl connect`` without user credentials (under the ``guest`` user) must be disabled." +msgstr "" + +#: ../../doc/enterprise/audit.rst:81 +msgid "There are two ways to check this vulnerability:" +msgstr "" + +#: ../../doc/enterprise/audit.rst:83 +msgid "Check that the source code doesn't grant access to the ``guest`` user. The corresponding code can look like this:" +msgstr "" + +#: ../../doc/enterprise/audit.rst:86 +msgid "box.schema.user.grant('guest',\n" +" 'read,write',\n" +" 'universe',\n" +" nil, { if_not_exists = true }\n" +")" +msgstr "" + +#: ../../doc/enterprise/audit.rst:94 +msgid "Besides searching for the whole code pattern, search for any entries of ``'universe'``." +msgstr "" + +#: ../../doc/enterprise/audit.rst:97 +msgid "Try connecting with ``tt connect`` to each Tarantool node." +msgstr "" + +#: ../../doc/enterprise/audit.rst:99 +msgid "For more details, refer to the documentation on :ref:`access control `." +msgstr "" + +#: ../../doc/enterprise/audit.rst:103 +msgid "Authorization in the web UI" +msgstr "" + +#: ../../doc/enterprise/audit.rst:105 +msgid "Using the web interface must require logging in with a username and password." +msgstr "" + +#: ../../doc/enterprise/audit.rst:108 +msgid "Running under the tarantool user" +msgstr "" + +#: ../../doc/enterprise/audit.rst:110 +msgid "All Tarantool instances should be running under the ``tarantool`` user." +msgstr "" + +#: ../../doc/enterprise/audit.rst:113 +msgid "Limiting access to the tarantool user" +msgstr "" + +#: ../../doc/enterprise/audit.rst:115 +msgid "The ``tarantool`` user must be a non-privileged user without the ``sudo`` permission. Also, it must not have a password set to prevent logging in via SSH or ``su``." +msgstr "" + +#: ../../doc/enterprise/audit.rst:120 +msgid "Keeping two or more snapshots" +msgstr "" + +#: ../../doc/enterprise/audit.rst:122 +msgid "In order to have a reliable backup, a Tarantool instance must keep two or more latest snapshots. This should be checked on each Tarantool instance." +msgstr "" + +#: ../../doc/enterprise/audit.rst:126 +msgid "The :ref:`snapshot_count ` value determines the number of kept snapshots. Configuration values are primarily set in the configuration files but can be overridden with environment variables and command-line arguments. So, it's best to check both the values in the configuration files and the actual values using the console:" +msgstr "" + +#: ../../doc/enterprise/audit.rst:133 +msgid "tarantool> box.cfg.checkpoint_count\n" +"---\n" +"- 2" +msgstr "" + +#: ../../doc/enterprise/audit.rst:141 +msgid "Enabled write-ahead logging (WAL)" +msgstr "" + +#: ../../doc/enterprise/audit.rst:143 +msgid "Tarantool records all incoming data in the write-ahead log (WAL). The WAL must be enabled to ensure that data will be recovered in case of a possible instance restart." +msgstr "" + +#: ../../doc/enterprise/audit.rst:147 +msgid "Secure values of ``wal_mode`` are ``write`` and ``fsync``:" +msgstr "" + +#: ../../doc/enterprise/audit.rst:149 +msgid "tarantool> box.cfg.wal_mode\n" +"---\n" +"- write" +msgstr "" + +#: ../../doc/enterprise/audit.rst:155 +msgid "An exclusion from this requirement is when the instance is processing data, which can be freely rejected. For example, when Tarantool is used for caching. Then WAL can be disabled to reduce i/o load." +msgstr "" + +#: ../../doc/enterprise/audit.rst:160 +msgid "For more details, see the :ref:`wal_mode reference `." +msgstr "" + +#: ../../doc/enterprise/audit.rst:164 +msgid "The logging level is INFO or higher" +msgstr "" + +#: ../../doc/enterprise/audit.rst:166 +msgid "The logging level should be set to 5 (``INFO``), 6 (``VERBOSE``), or 7 (``DEBUG``). Application logs will then have enough information to research a possible security breach." +msgstr "" + +#: ../../doc/enterprise/audit.rst:169 +msgid "tarantool> box.cfg.log_level\n" +"---\n" +"- 5" +msgstr "" + +#: ../../doc/enterprise/audit.rst:175 +msgid "For a full list of logging levels, see the :ref:`log_level reference `." +msgstr "" + +#: ../../doc/enterprise/audit.rst:180 +msgid "Logging with journald" +msgstr "" + +#: ../../doc/enterprise/audit.rst:182 +msgid "Tarantool should use ``journald`` for logging." +msgstr "" diff --git a/locale/en/platform/security/audit_log.pot b/locale/en/platform/security/audit_log.pot new file mode 100644 index 0000000000..3281a7a8fa --- /dev/null +++ b/locale/en/platform/security/audit_log.pot @@ -0,0 +1,1042 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/audit_log.rst:4 +msgid "Audit module" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:6 +msgid "The audit module available in Tarantool Enterprise Edition writes messages that record Tarantool events in plain text, CSV, or JSON format." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:8 +msgid "It provides detailed reports of security-related activities and helps you find and fix breaches to protect your business. For example, you can see who created a new user and when:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:12 +msgid "{\n" +" \"time\": \"2022-04-07T13:39:36.046+0300\",\n" +" \"remote\": \"\",\n" +" \"session_type\": \"background\",\n" +" \"module\": \"tarantool\",\n" +" \"user\": \"admin\",\n" +" \"type\": \"user_create\",\n" +" \"tag\": \"\",\n" +" \"description\": \"Create user alice\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:25 +msgid "It is up to each company to decide exactly what activities to audit and what actions to take. System administrators, security engineers, and people in charge of the company may want to audit different events for different reasons. Tarantool provides such an option for each of them." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:32 +msgid "Audit log events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:34 +msgid "The Tarantool audit log module can record various events that you can monitor and decide whether you need to take actions:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:37 +msgid "Admin activity -- events related to actions performed by the administrator. For example, such logs record the creation of a user." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:40 +msgid "Access events -- events related to authorization and authentication of users. For example, such logs record failed attempts to access secure data." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:43 +msgid "Data access and modification -- events of data manipulation in the storage." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:45 +msgid "System events -- events related to modification or configuration of resources. For example, such logs record the replacement of a space." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:48 +msgid ":ref:`User-defined events `-- any events added manually using the audit module API." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:51 +msgid "The full list of available audit log events is provided in the table below:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:59 +msgid "Event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:60 +msgid "Type of event written to the audit log" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:61 +msgid "Example of an event description" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:62 +msgid "Audit log enabled for events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:63 +msgid "``audit_enable``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:65 +msgid ":ref:`User-defined events `" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:66 +msgid "``custom``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:68 +msgid "User authorized successfully" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:69 +msgid "``auth_ok``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:70 +msgid "``Authenticate user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:71 +msgid "User authorization failed" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:72 +msgid "``auth_fail``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:73 +msgid "``Failed to authenticate user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:74 +msgid "User logged out or quit the session" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:75 +msgid "``disconnect``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:76 +msgid "``Close connection``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:77 +msgid "User created" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:78 +msgid "``user_create``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:79 +msgid "``Create user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:80 +msgid "User dropped" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:81 +msgid "``user_drop``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:82 +msgid "``Drop user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:83 +msgid "Role created" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:84 +msgid "``role_create``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:85 +msgid "``Create role ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:86 +msgid "Role dropped" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:87 +msgid "``role_drop``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:88 +msgid "``Drop role ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:89 +msgid "User disabled" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:90 +msgid "``user_disable``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:91 +msgid "``Disable user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:92 +msgid "User enabled" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:93 +msgid "``user_enable``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:94 +msgid "``Enable user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:95 +msgid "User granted rights" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:96 +msgid "``user_grant_rights``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:97 +msgid "``Grant rights for to user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:98 +msgid "User revoked rights" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:99 +msgid "``user_revoke_rights``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:100 +msgid "``Revoke rights for from user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:101 +msgid "Role granted rights" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:102 +msgid "``role_grant_rights``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:103 +msgid "``Grant rights for to role ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:104 +msgid "Role revoked rights" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:105 +msgid "``role_revoke_rights``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:106 +msgid "``Revoke rights for from role ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:107 +msgid "User password changed" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:108 +msgid "``password_change``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:109 +msgid "``Change password for user ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:110 +msgid "Failed attempt to access secure data (personal records, details, geolocation, etc.)" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:111 +msgid "``access_denied``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:112 +msgid "`` denied to ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:113 +msgid "Expressions with arguments evaluated in a string" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:114 +msgid "``eval``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:115 +msgid "``Evaluate expression ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:116 +msgid "Function called with arguments" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:117 +msgid "``call``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:118 +msgid "``Call function with arguments ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:119 +msgid "Iterator key selected from ``space.index``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:120 +msgid "``space_select``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:121 +msgid "``Select from .``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:122 +msgid "Space created" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:123 +msgid "``space_create``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:124 +msgid "``Create space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:125 +msgid "Space altered" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:126 +msgid "``space_alter``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:127 +msgid "``Alter space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:128 +msgid "Space dropped" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:129 +msgid "``space_drop``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:130 +msgid "``Drop space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:131 +msgid "Tuple inserted into space" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:132 +msgid "``space_insert``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:133 +msgid "``Insert tuple into space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:134 +msgid "Tuple replaced in space" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:135 +msgid "``space_replace``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:136 +msgid "``Replace tuple with in space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:137 +msgid "Tuple deleted from space" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:138 +msgid "``space_delete``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:139 +msgid "``Delete tuple from space ``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:144 +msgid "The ``eval`` event displays data from the ``console`` module and the ``eval`` function of the ``net.box`` module. For more on how they work, see :ref:`Module console ` and :ref:`Module net.box -- eval `. To separate the data, specify ``console`` or ``binary`` in the session field." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:153 +msgid "Event groups" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:155 +msgid "You can simplify working with audit log events by using built-in event groups. For example, you can set to record only events related to the enabling of the audit log, or only events related to a space." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:159 +msgid "Tarantool provides the following event groups:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:161 +msgid "``all`` -- all :ref:`events `." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:165 +msgid "Events ``call`` and ``eval`` are included only into the ``all`` group." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:167 +msgid "``audit`` -- ``audit_enable`` event." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:169 +msgid "``auth`` -- authorization events: ``auth_ok``, ``auth_fail``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:171 +msgid "``priv`` -- events related to authentication, authorization, users, and roles: ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``, ``role_revoke_rights``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:175 +msgid "``ddl`` -- events of space creation, altering, and dropping: ``space_create``, ``space_alter``, ``space_drop``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:178 +msgid "``dml`` -- events of data modification in spaces: ``space_insert``, ``space_replace``, ``space_delete``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:181 +msgid "``data_operations`` -- events of data modification or selection from spaces: ``space_select``, ``space_insert``, ``space_replace``, ``space_delete``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:184 +msgid "``compatibility`` -- events available in Tarantool before the version 2.10.0. ``auth_ok``, ``auth_fail``, ``disconnect``, ``user_create``, ``user_drop``, ``role_create``, ``role_drop``, ``user_enable``, ``user_disable``, ``user_grant_rights``, ``user_revoke_rights``, ``role_grant_rights``. ``role_revoke_rights``, ``password_change``, ``access_denied``. This group enables the compatibility with earlier Tarantool versions." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:193 +msgid "Be careful when recording ``all`` and ``data_operations`` event groups. The more events you record, the slower the requests will be processed over time. It is recommended that you select only those groups whose events your company really needs to monitor and analyze." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:201 +msgid "Structure of audit log events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:203 +msgid "Each audit log event contains several fields to make it easy to filter and aggregate the resulting logs. They are described in the following table." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:212 +msgid "Field" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:213 +msgid "Description" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:214 +msgid "Example of a log field display" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:215 +msgid "``time``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:216 +msgid "Time of the event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:217 +msgid "2022-04-07T13:20:05.327+0300" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:218 +msgid "``remote``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:219 +msgid "Remote host that triggered the event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:220 +msgid "100.96.163.226:48722" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:221 +msgid "``session_type``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:222 +msgid "Session type" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:223 +msgid "console" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:224 +msgid "``module``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:225 +msgid "Audit log module. Set to ``tarantool`` for system events; can be overwritten for user-defined events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:227 +msgid "tarantool" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:228 +msgid "``user``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:229 +msgid "User who triggered the event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:230 +msgid "admin" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:231 +msgid "``type``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:232 +msgid "Audit event type" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:233 +msgid "access_denied" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:234 +msgid "``tag``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:235 +msgid "A text field that can be overwritten by the user" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:237 +msgid "``description``" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:238 +msgid "Human-readable event description" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:239 +msgid "Authenticate user Alice" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:243 +msgid "You can set all these parameters only once. Unlike many other parameters in ``box.cfg``, they cannot be changed." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:249 +msgid "Enable the Tarantool audit log" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:251 +msgid "By default, audit logging is disabled. To enable audit logging, define the logs location by setting the ``box.cfg.audit_log`` option. Tarantool can write audit logs to a file, to a pipe, or to the system logger." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:255 +msgid "To disable audit logging, set the ``audit_log`` option to ``nil``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:258 +msgid "Write to a file" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:260 +msgid "box.cfg{audit_log = 'audit_tarantool.log'}\n" +"-- or\n" +"box.cfg{audit_log = 'file:audit_tarantool.log'}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:266 +msgid "This opens the ``audit_tarantool.log`` file for output in the server’s default directory. If the ``audit_log`` string has no prefix or the prefix ``file:``, the string is interpreted as a file path." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:270 +msgid "Send to a pipe" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:272 +msgid "box.cfg{audit_log = '| cronolog audit_tarantool.log'}\n" +"-- or\n" +"box.cfg{audit_log = 'pipe: cronolog audit_tarantool.log'}'" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:278 +msgid "This starts the `cronolog `_ program when the server starts and sends all ``audit_log`` messages to cronolog's standard input (``stdin``). If the ``audit_log`` string starts with '|' or contains the prefix ``pipe:``, the string is interpreted as a Unix `pipeline `_." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:284 +msgid "Send to syslog" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:288 +msgid "Below is an example of writing audit logs to a directory shared with the system logs. Tarantool allows this option, but it is not recommended to do this to avoid difficulties when working with audit logs. System and audit logs should be written separately. To do this, create separate paths and specify them." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:293 +msgid "This example setting sends the audit log to syslog:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:295 +msgid "box.cfg{audit_log = 'syslog:identity=tarantool'}\n" +"-- or\n" +"box.cfg{audit_log = 'syslog:facility=user'}\n" +"-- or\n" +"box.cfg{audit_log = 'syslog:identity=tarantool,facility=user'}\n" +"-- or\n" +"box.cfg{audit_log = 'syslog:server=unix:/dev/log'}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:305 +msgid "If the ``audit_log`` string starts with \"syslog:\", it is interpreted as a message for the `syslogd `_ program, which normally runs in the background of any Unix-like platform. The setting can be 'syslog:', 'syslog:facility=...', 'syslog:identity=...', 'syslog:server=...' or a combination." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:310 +msgid "The ``syslog:identity`` setting is an arbitrary string that is placed at the beginning of all messages. The default value is ``tarantool``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:313 +msgid "The ``syslog:facility`` setting is currently ignored, but will be used in the future. The value must be one of the `syslog `_ keywords that tell ``syslogd`` where to send the message. The possible values are ``auth``, ``authpriv``, ``cron``, ``daemon``, ``ftp``, ``kern``, ``lpr``, ``mail``, ``news``, ``security``, ``syslog``, ``user``, ``uucp``, ``local0``, ``local1``, ``local2``, ``local3``, ``local4``, ``local5``, ``local6``, ``local7``. The default value is ``local7``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:321 +msgid "The ``syslog:server`` setting is the locator for the syslog server. It can be a Unix socket path starting with \"unix:\" or an ipv4 port number. The default socket value is ``/dev/log`` (on Linux) or ``/var/run/syslog`` (on Mac OS). The default port value is 514, which is the UDP port." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:326 +msgid "If you log to a file, Tarantool will reopen the audit log at `SIGHUP `_. If log is a program, its pid is stored in the ``audit_log.logger_pid`` variable. You need to send it a signal to rotate logs." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:330 +msgid "An example of a Tarantool audit log entry in the syslog:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:332 +msgid "{\n" +" \"__CURSOR\" : \"s=81564632436a4de590e80b89b0151148;i=11519;b=def80c1464fe49d1aac8a64895d6614d;m=8c825ebfc;t=5edb27a75f282;x=7eba320f7cc9ae4d\",\n" +" \"__REALTIME_TIMESTAMP\" : \"1668725698065026\",\n" +" \"__MONOTONIC_TIMESTAMP\" : \"37717666812\",\n" +" \"_BOOT_ID\" : \"def80c1464fe49d1aac8a64895d6614d\",\n" +" \"_UID\" : \"1003\",\n" +" \"_GID\" : \"1004\",\n" +" \"_COMM\" : \"tarantool\",\n" +" \"_EXE\" : \"/app/tarantool/dist/tdg-2.6.4.0.x86_64/tarantool\",\n" +" \"_CMDLINE\" : \"tarantool init.lua : core-03\",\n" +" \"_CAP_EFFECTIVE\" : \"0\",\n" +" \"_AUDIT_SESSION\" : \"1\",\n" +" \"_AUDIT_LOGINUID\" : \"1003\",\n" +" \"_SYSTEMD_CGROUP\" : \"/user.slice/user-1003.slice/user@1003.service/app.slice/app@core-03.service\",\n" +" \"_SYSTEMD_OWNER_UID\" : \"1003\",\n" +" \"_SYSTEMD_UNIT\" : \"user@1003.service\",\n" +" \"_SYSTEMD_USER_UNIT\" : \"app@core-03.service\",\n" +" \"_SYSTEMD_SLICE\" : \"user-1003.slice\",\n" +" \"_SYSTEMD_USER_SLICE\" : \"app.slice\",\n" +" \"_SYSTEMD_INVOCATION_ID\" : \"be368b4243d842ea8c06b010e0df62c2\",\n" +" \"_MACHINE_ID\" : \"2e2339725deb4bc198c54ff4a2e8d626\",\n" +" \"_HOSTNAME\" : \"vm-0.test.env\",\n" +" \"_TRANSPORT\" : \"syslog\",\n" +" \"PRIORITY\" : \"6\",\n" +" \"SYSLOG_FACILITY\" : \"23\",\n" +" \"SYSLOG_IDENTIFIER\" : \"tarantool\",\n" +" \"SYSLOG_PID\" : \"101562\",\n" +" \"_PID\" : \"101562\",\n" +" \"MESSAGE\" : \"remote: session_type:background module:common.admin.auth user: type:custom_tdg_audit tag:tdg_severity_INFO description:[119eae0e-a691-42cc-9b4c-f14c499e6726] subj: \\\"anonymous\\\", msg: \\\"Access granted to anonymous user\\\"\",\n" +" \"_SOURCE_REALTIME_TIMESTAMP\" : \"1668725698064202\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:369 +msgid "Select events to write to audit log" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:371 +msgid "Tarantool's extensive filtering options help you write only the events you need to the audit log." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:373 +msgid "To select events to write to audit log, use the ``box.cfg.audit_filter`` option. Its value can be a list of events and event groups. The default value for the ``box.cfg.audit_filter`` option is ``compatibility``, which enables logging of all events available before 2.10.0." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:378 +msgid "box.cfg{\n" +" audit_log = 'audit.log',\n" +" audit_filter = 'audit,auth,priv,password_change,access_denied'\n" +" }" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:388 +msgid "Customize your filters" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:390 +msgid "You can customize the filters and use different combinations of filters for your purposes." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:393 +msgid "Filter based on a specific event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:395 +msgid "You can set only certain events that you need to record." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:397 +msgid "For example, select ``password_change`` to monitor the users who have changed their passwords." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:399 +msgid "box.cfg{\n" +" audit_log = 'audit.log',\n" +" audit_filter = 'password_change'\n" +" }" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:407 +msgid "Filter based on a specific group" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:409 +msgid "You can set one of the groups of events that you need to record." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:411 +msgid "For example, select ``compatibility`` to monitor only events of user authorization, granted privileges, disconnection, user password change, and denied access." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:414 +msgid "box.cfg{\n" +" audit_log = 'audit.log',\n" +" audit_filter = 'compatibility'\n" +" }" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:422 +msgid "Filter based on multiple groups" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:424 +msgid "You can specify multiple groups depending on the purpose." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:426 +msgid "For example, select ``auth`` and ``priv`` to see only events related to authorization and granted privileges." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:428 +msgid "box.cfg{\n" +" audit_log = 'audit.log',\n" +" audit_filter = 'auth,priv'\n" +" }" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:436 +msgid "Filter based on a group and a specific event" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:438 +msgid "You can specify a group and a certain event depending on the purpose." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:440 +msgid "For example, you can select ``priv`` and ``disconnect`` to see only events related to granted privileges and disconnect events." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:443 +msgid "box.cfg{\n" +" audit_log = 'audit.log',\n" +" audit_filter = 'priv,disconnect'\n" +" }" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:451 +#: ../../doc/enterprise/audit_log.rst:569 +#: ../../doc/enterprise/audit_log.rst:604 +msgid "Example" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:453 +msgid "Run the command to filter:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:455 +msgid "local audit = require('audit')\n" +"\n" +"box.cfg{audit_log = 'audit.log', audit_filter = 'custom,user_create', audit_format = 'csv'}\n" +"-- The Tarantool audit module writes the event because a filter is set for it\n" +"box.schema.user.create('alice')\n" +"-- The Tarantool audit module will not write the event because no filter is set for it\n" +"box.schema.user.drop('alice')" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:468 +msgid "Configure a blocking mode" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:470 +msgid "By default, the ``audit_nonblock`` option is set to ``true`` and Tarantool will not block during logging if the system is not ready to write, dropping the message instead. Using this value may improve logging performance at the cost of losing some log messages. This option only has an effect if the output goes to ``syslog:`` or ``pipe:``. Setting ``audit_nonblock`` to ``true`` is not allowed if the output is to a file. In this case, set ``audit_nonblock`` to ``false``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:480 +msgid "Configure the format of audit log events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:482 +msgid "You can choose the format of audit log events -- plain text, CSV or JSON format." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:484 +msgid "Plain text is used by default. This human-readable format can be efficiently compressed. The JSON format is more convenient to receive log events, analyze them and integrate them with other systems if needed. Using the CSV format allows you to view audit log events in tabular form." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:488 +msgid "Use these commands to configure the format of audit log events in Tarantool." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:491 +msgid "Plain text" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:493 +msgid "box.cfg{audit_log = 'audit.log', audit_format = 'plain'}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:497 +#: ../../doc/enterprise/audit_log.rst:517 +#: ../../doc/enterprise/audit_log.rst:539 +msgid "Example:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:499 +msgid "remote:\n" +"session_type:background\n" +"module:common.admin.auth\n" +"user: type:custom_tdg_audit\n" +"tag:tdg_severity_INFO\n" +"description:[5e35b406-4274-4903-857b-c80115275940]\n" +"subj: \"anonymous\",\n" +"msg: \"Access granted to anonymous user\"" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:511 +msgid "JSON format" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:513 +msgid "box.cfg{audit_log = 'audit.log', audit_format = 'json'}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:519 +msgid "{\n" +" \"time\": \"2022-11-17T21:55:49.880+0300\",\n" +" \"remote\": \"\",\n" +" \"session_type\": \"background\",\n" +" \"module\": \"common.admin.auth\",\n" +" \"user\": \"\",\n" +" \"type\": \"custom_tdg_audit\",\n" +" \"tag\": \"tdg_severity_INFO\",\n" +" \"description\": \"[c26cd11a-3342-4ce6-8f0b-a4b222268b9d] subj: \\\"anonymous\\\", msg: \\\"Access granted to anonymous user\\\"\"\n" +"}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:533 +msgid "CSV format" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:535 +msgid "box.cfg{audit_log = 'audit.log', audit_format = 'csv'}" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:541 +msgid "2022-11-17T21:58:03.131+0300,,background,common.admin.auth,,,custom_tdg_audit,tdg_severity_INFO,\"[b3dfe2a3-ec29-4e61-b747-eb2332c83b2e] subj: \"\"anonymous\"\", msg: \"\"Access granted to anonymous user\"\"\"" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:548 +msgid "Create user-defined events" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:550 +msgid "Tarantool provides an API for writing user-defined audit log events." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:552 +msgid "To add a new event, use the ``audit.log()`` function that takes one of the following values:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:554 +msgid "Message string. Printed to the audit log with type ``message``. Example: ``audit.log('Hello, World!')``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:556 +msgid "Format string and arguments. Passed to string format and then output to the audit log with type message. Example: ``audit.log('Hello, %s!', 'World')``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:559 +msgid "Table with audit log field values. The table must contain at least one field -- description. Example: ``audit.log({type = 'custom_hello', description = 'Hello, World!'})``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:562 +msgid "Using the field ``audit.new()``, you can create a new log module that allows you to avoid passing all custom audit log fields each time ``audit.log()`` is called. It takes a table of audit log field values (same as ``audit.log()``). The ``type`` of the log module for writing user-defined events must either be ``message`` or have the ``custom_`` prefix." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:571 +msgid "local my_audit = audit.new({type = 'custom_hello', module = 'my_module'})\n" +"my_audit:log('Hello, Alice!')\n" +"my_audit:log({tag = 'admin', description = 'Hello, Bob!'})\n" +"\n" +"-- is equivalent to\n" +"audit.log({type = 'custom_hello', module = 'my_module',\n" +" description = 'Hello, Alice!' })\n" +"audit.log({type = 'custom_hello', module = 'my_module',\n" +" tag = 'admin', description = 'Hello, Bob!'})" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:584 +msgid "Some user-defined audit log fields (``time``, ``remote``, ``session_type``) are set in the same way as for a system event. If a field is not overwritten, it is set to the same value as for a system event." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:588 +msgid "Some audit log fields you can overwrite with ``audit.new()`` and ``audit.log()``:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:590 +msgid "type" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:591 +msgid "user" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:592 +msgid "module" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:593 +msgid "tag" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:594 +msgid "description" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:598 +msgid "To avoid confusion with system events, the value of the type field must either be ``message`` (default) or begin with ``custom_``. Otherwise you will get the error message. User-defined events are filtered out by default. To enable user-defined audit log events, you must add ``custom`` to ``box.cfg.audit_filter``." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:606 +msgid "local audit = require('audit')\n" +"\n" +"box.cfg{audit_log = 'audit.log', audit_filter = 'custom', audit_format = 'csv'}\n" +"audit.log('Hello, Alice!')\n" +"audit.log('Hello, %s!', 'Bob')\n" +"audit.log({type = 'custom_hello', description = 'Hello, Eve!'})\n" +"audit.log({type = 'custom_farewell', user = 'eve', module = 'custom', description = 'Farewell, Eve!'})\n" +"\n" +"local my_audit = audit.new({module = 'my_module', tag = 'default'})\n" +"my_audit:log({description = 'Message 1'})\n" +"my_audit:log({description = 'Message 2', tag = 'my_tag'})\n" +"my_audit:log({description = 'Message 3', module = 'other_module'})" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:624 +msgid "Use read commands" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:626 +msgid "To easily read the audit log events in the needed form, use the different commands:" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:628 +msgid "``cat`` -- prints one or more files" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:630 +msgid "``grep`` -- prints a specific text" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:632 +msgid "``head`` -- prints the first N lines of the file" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:634 +msgid "``tail`` -- prints the last N lines of the file" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:638 +msgid "These are the basic commands to help you read the logs. If necessary, you can use other commands." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:643 +msgid "Tips" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:646 +msgid "How many events can be recorded?" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:648 +msgid "If you write to a file, the size of the Tarantool audit module is limited by the disk space. If you write to a system logger, the size of the Tarantool audit module is limited by the system logger. If you write to a pipe, the size of the Tarantool audit module is limited by the system buffer if the ``audit_nonblock`` = ``false``; if ``audit_nonblock`` = ``true``, there is no limit. However, it is not recommended to use the entire memory, as this may cause performance degradation and even loss of some logs." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:656 +msgid "How often should audit logs be reviewed?" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:658 +msgid "Consider setting up a schedule in your company. It is recommended to review audit logs at least every 3 months." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:661 +msgid "How long should audit logs be stored?" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:663 +msgid "It is recommended to store audit logs for at least one year." +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:666 +msgid "What is the best way to process audit logs?" +msgstr "" + +#: ../../doc/enterprise/audit_log.rst:668 +msgid "It is recommended to use SIEM systems for this issue." +msgstr "" diff --git a/locale/en/platform/security/security.pot b/locale/en/platform/security/security.pot new file mode 100644 index 0000000000..7e0dcc3704 --- /dev/null +++ b/locale/en/platform/security/security.pot @@ -0,0 +1,1025 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/enterprise/security.rst:4 +msgid "Security hardening guide" +msgstr "" + +#: ../../doc/enterprise/security.rst:6 +msgid "This guide explains how to enhance security in your Tarantool Enterprise Edition's cluster using built-in features and provides general recommendations on security hardening. If you need to perform a security audit of a Tarantool Enterprise cluster, refer to the :doc:`security checklist `." +msgstr "" + +#: ../../doc/enterprise/security.rst:12 +msgid "Tarantool Enterprise Edition does not provide a dedicated API for security control. All the necessary configurations can be done via an administrative console or initialization code." +msgstr "" + +#: ../../doc/enterprise/security.rst:16 +msgid "Tarantool Enterprise Edition has the following built-in security features:" +msgstr "" + +#: ../../doc/enterprise/security.rst:18 +msgid ":ref:`authentication `" +msgstr "" + +#: ../../doc/enterprise/security.rst:19 +msgid ":ref:`access control `" +msgstr "" + +#: ../../doc/enterprise/security.rst:20 +msgid ":ref:`audit log `" +msgstr "" + +#: ../../doc/enterprise/security.rst:21 +msgid ":ref:`traffic encryption `" +msgstr "" + +#: ../../doc/enterprise/security.rst:27 +msgid "Authentication" +msgstr "" + +#: ../../doc/enterprise/security.rst:29 +msgid "Tarantool Enterprise Edition supports password-based authentication and allows for two types of connections:" +msgstr "" + +#: ../../doc/enterprise/security.rst:32 +msgid "Via an :doc:`administrative console `." +msgstr "" + +#: ../../doc/enterprise/security.rst:33 +msgid "Over a binary port for read and write operations and procedure invocation." +msgstr "" + +#: ../../doc/enterprise/security.rst:35 +msgid "For more information on authentication and connection types, see the :doc:`Security ` section of the Tarantool manual." +msgstr "" + +#: ../../doc/enterprise/security.rst:38 +msgid "In addition, Tarantool provides the following functionality:" +msgstr "" + +#: ../../doc/enterprise/security.rst:40 +msgid ":ref:`Sessions ` -- states which associate connections with users and make Tarantool API available to them after authentication." +msgstr "" + +#: ../../doc/enterprise/security.rst:43 +msgid "Authentication :ref:`triggers `, which execute actions on authentication events." +msgstr "" + +#: ../../doc/enterprise/security.rst:45 +msgid "Third-party (external) authentication protocols and services such as LDAP or Active Directory -- supported in the web interface, but unavailable on the binary-protocol level." +msgstr "" + +#: ../../doc/enterprise/security.rst:52 +msgid "Access control" +msgstr "" + +#: ../../doc/enterprise/security.rst:54 +msgid "Tarantool Enterprise Edition provides the means for administrators to prevent unauthorized access to the database and to certain functions." +msgstr "" + +#: ../../doc/enterprise/security.rst:57 +msgid "Tarantool recognizes:" +msgstr "" + +#: ../../doc/enterprise/security.rst:59 +msgid "different users (guests and administrators)" +msgstr "" + +#: ../../doc/enterprise/security.rst:60 +msgid "privileges associated with users" +msgstr "" + +#: ../../doc/enterprise/security.rst:61 +msgid "roles (containers for privileges) granted to users" +msgstr "" + +#: ../../doc/enterprise/security.rst:63 +msgid "The following system spaces are used to store users and privileges:" +msgstr "" + +#: ../../doc/enterprise/security.rst:65 +msgid "The ``_user`` space to store usernames and hashed passwords for authentication." +msgstr "" + +#: ../../doc/enterprise/security.rst:66 +msgid "The ``_priv`` space to store privileges for access control." +msgstr "" + +#: ../../doc/enterprise/security.rst:68 +msgid "For more information, see the :ref:`Access control ` section." +msgstr "" + +#: ../../doc/enterprise/security.rst:71 +msgid "Users who create **objects** (spaces, indexes, users, roles, sequences, and functions) in the database become their **owners** and automatically acquire privileges for what they create. For more information, see the :ref:`Owners and privileges ` section." +msgstr "" + +#: ../../doc/enterprise/security.rst:80 +msgid "Authentication restrictions" +msgstr "" + +#: ../../doc/enterprise/security.rst:82 +msgid "Tarantool Enterprise Edition provides the ability to apply additional restrictions for user authentication. For example, you can specify the minimum time between authentication attempts or disable access for guest users." +msgstr "" + +#: ../../doc/enterprise/security.rst:86 +#: ../../doc/enterprise/security.rst:145 +msgid "The following :doc:`configuration options ` are available:" +msgstr "" + +#: ../../doc/enterprise/security.rst:88 +msgid ":ref:`auth_delay `" +msgstr "" + +#: ../../doc/enterprise/security.rst:89 +msgid ":ref:`disable_guest `" +msgstr "" + +#: ../../doc/enterprise/security.rst:96 +msgid "Specifies a period of time (in seconds) that a specific user should wait for the next attempt after failed authentication." +msgstr "" + +#: ../../doc/enterprise/security.rst:99 +msgid "With the configuration below, Tarantool refuses the authentication attempt if the previous attempt was less than 5 seconds ago." +msgstr "" + +#: ../../doc/enterprise/security.rst:102 +msgid "box.cfg{ auth_delay = 5 }" +msgstr "" + +#: ../../doc/enterprise/security.rst:107 +#: ../../doc/enterprise/security.rst:124 +#: ../../doc/enterprise/security.rst:167 +#: ../../doc/enterprise/security.rst:180 +#: ../../doc/enterprise/security.rst:193 +#: ../../doc/enterprise/security.rst:206 +#: ../../doc/enterprise/security.rst:219 +#: ../../doc/enterprise/security.rst:244 +#: ../../doc/enterprise/security.rst:263 +#: ../../doc/enterprise/security.rst:301 +msgid "Since version: 2.11" +msgstr "" + +#: ../../doc/enterprise/security.rst:108 +msgid "Type: number" +msgstr "" + +#: ../../doc/enterprise/security.rst:109 +#: ../../doc/enterprise/security.rst:169 +#: ../../doc/enterprise/security.rst:246 +#: ../../doc/enterprise/security.rst:265 +msgid "Default: 0" +msgstr "" + +#: ../../doc/enterprise/security.rst:110 +msgid "Environment variable: TT_AUTH_DELAY" +msgstr "" + +#: ../../doc/enterprise/security.rst:111 +#: ../../doc/enterprise/security.rst:128 +#: ../../doc/enterprise/security.rst:171 +#: ../../doc/enterprise/security.rst:184 +#: ../../doc/enterprise/security.rst:197 +#: ../../doc/enterprise/security.rst:210 +#: ../../doc/enterprise/security.rst:223 +#: ../../doc/enterprise/security.rst:248 +#: ../../doc/enterprise/security.rst:267 +#: ../../doc/enterprise/security.rst:306 +msgid "Dynamic: **yes**" +msgstr "" + +#: ../../doc/enterprise/security.rst:118 +msgid "If **true**, disables access over remote connections from unauthenticated or :ref:`guest access ` users. This option affects both :doc:`net.box ` and :ref:`replication ` connections." +msgstr "" + +#: ../../doc/enterprise/security.rst:125 +#: ../../doc/enterprise/security.rst:181 +#: ../../doc/enterprise/security.rst:194 +#: ../../doc/enterprise/security.rst:207 +#: ../../doc/enterprise/security.rst:220 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/enterprise/security.rst:126 +#: ../../doc/enterprise/security.rst:182 +#: ../../doc/enterprise/security.rst:195 +#: ../../doc/enterprise/security.rst:208 +#: ../../doc/enterprise/security.rst:221 +msgid "Default: false" +msgstr "" + +#: ../../doc/enterprise/security.rst:127 +msgid "Environment variable: TT_DISABLE_GUEST" +msgstr "" + +#: ../../doc/enterprise/security.rst:135 +msgid "Password policy" +msgstr "" + +#: ../../doc/enterprise/security.rst:137 +msgid "A password policy allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. When you create a new user with :doc:`box.schema.user.create ` or update the password of an existing user with :doc:`box.schema.user.passwd `, the password is checked against the configured password policy settings." +msgstr "" + +#: ../../doc/enterprise/security.rst:147 +msgid ":ref:`password_min_length `" +msgstr "" + +#: ../../doc/enterprise/security.rst:148 +msgid ":ref:`password_enforce_uppercase `" +msgstr "" + +#: ../../doc/enterprise/security.rst:149 +msgid ":ref:`password_enforce_lowercase `" +msgstr "" + +#: ../../doc/enterprise/security.rst:150 +msgid ":ref:`password_enforce_digits `" +msgstr "" + +#: ../../doc/enterprise/security.rst:151 +msgid ":ref:`password_enforce_specialchars `" +msgstr "" + +#: ../../doc/enterprise/security.rst:152 +msgid ":ref:`password_lifetime_days `" +msgstr "" + +#: ../../doc/enterprise/security.rst:153 +msgid ":ref:`password_history_length `" +msgstr "" + +#: ../../doc/enterprise/security.rst:159 +msgid "Specifies the minimum number of characters for a password." +msgstr "" + +#: ../../doc/enterprise/security.rst:161 +msgid "The following example shows how to set the minimum password length to 10." +msgstr "" + +#: ../../doc/enterprise/security.rst:163 +msgid "box.cfg{ password_min_length = 10 }" +msgstr "" + +#: ../../doc/enterprise/security.rst:168 +#: ../../doc/enterprise/security.rst:245 +#: ../../doc/enterprise/security.rst:264 +msgid "Type: integer" +msgstr "" + +#: ../../doc/enterprise/security.rst:170 +msgid "Environment variable: TT_PASSWORD_MIN_LENGTH" +msgstr "" + +#: ../../doc/enterprise/security.rst:178 +msgid "If **true**, a password should contain uppercase letters (A-Z)." +msgstr "" + +#: ../../doc/enterprise/security.rst:183 +msgid "Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE" +msgstr "" + +#: ../../doc/enterprise/security.rst:191 +msgid "If **true**, a password should contain lowercase letters (a-z)." +msgstr "" + +#: ../../doc/enterprise/security.rst:196 +msgid "Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE" +msgstr "" + +#: ../../doc/enterprise/security.rst:204 +msgid "If **true**, a password should contain digits (0-9)." +msgstr "" + +#: ../../doc/enterprise/security.rst:209 +msgid "Environment variable: TT_PASSWORD_ENFORCE_DIGITS" +msgstr "" + +#: ../../doc/enterprise/security.rst:217 +msgid "If **true**, a password should contain at least one special character (such as ``&|?!@$``)." +msgstr "" + +#: ../../doc/enterprise/security.rst:222 +msgid "Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS" +msgstr "" + +#: ../../doc/enterprise/security.rst:230 +msgid "Specifies the maximum period of time (in days) a user can use the same password. When this period ends, a user gets the \"Password expired\" error on a login attempt. To restore access for such users, use :doc:`box.schema.user.passwd `." +msgstr "" + +#: ../../doc/enterprise/security.rst:236 +msgid "The default 0 value means that a password never expires." +msgstr "" + +#: ../../doc/enterprise/security.rst:238 +msgid "The example below shows how to set a maximum password age to 365 days." +msgstr "" + +#: ../../doc/enterprise/security.rst:240 +msgid "box.cfg{ password_lifetime_days = 365 }" +msgstr "" + +#: ../../doc/enterprise/security.rst:247 +msgid "Environment variable: TT_PASSWORD_LIFETIME_DAYS" +msgstr "" + +#: ../../doc/enterprise/security.rst:255 +msgid "Specifies the number of unique new user passwords before an old password can be reused." +msgstr "" + +#: ../../doc/enterprise/security.rst:257 +msgid "In the example below, a new password should differ from the last three passwords." +msgstr "" + +#: ../../doc/enterprise/security.rst:259 +msgid "box.cfg{ password_history_length = 3 }" +msgstr "" + +#: ../../doc/enterprise/security.rst:266 +msgid "Environment variable: TT_PASSWORD_HISTORY_LENGTH" +msgstr "" + +#: ../../doc/enterprise/security.rst:270 +msgid "Tarantool uses the ``auth_history`` field in the :doc:`box.space._user ` system space to store user passwords." +msgstr "" + +#: ../../doc/enterprise/security.rst:280 +msgid "Authentication protocol" +msgstr "" + +#: ../../doc/enterprise/security.rst:282 +msgid "By default, Tarantool uses the `CHAP `_ protocol to authenticate users and applies ``SHA-1`` hashing to :ref:`passwords `. Note that CHAP stores password hashes in the ``_user`` space unsalted. If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table `_." +msgstr "" + +#: ../../doc/enterprise/security.rst:289 +msgid "In the Enterprise Edition, you can enable `PAP `_ authentication with the ``SHA256`` hashing algorithm. For PAP, a password is salted with a user-unique salt before saving it in the database, which keeps the database protected from cracking using a rainbow table." +msgstr "" + +#: ../../doc/enterprise/security.rst:295 +msgid "To enable PAP, specify the ``box.cfg.auth_type`` option as follows:" +msgstr "" + +#: ../../doc/enterprise/security.rst:297 +msgid "box.cfg{ auth_type = 'pap-sha256' }" +msgstr "" + +#: ../../doc/enterprise/security.rst:302 +msgid "Type: string" +msgstr "" + +#: ../../doc/enterprise/security.rst:303 +msgid "Default value: 'chap-sha1'" +msgstr "" + +#: ../../doc/enterprise/security.rst:304 +msgid "Possible values: 'chap-sha1', 'pap-sha256'" +msgstr "" + +#: ../../doc/enterprise/security.rst:305 +msgid "Environment variable: TT_AUTH_TYPE" +msgstr "" + +#: ../../doc/enterprise/security.rst:308 +msgid "For new users, the :doc:`box.schema.user.create ` method will generate authentication data using ``PAP-SHA256``. For existing users, you need to reset a password using :doc:`box.schema.user.passwd ` to use the new authentication protocol." +msgstr "" + +#: ../../doc/enterprise/security.rst:316 +msgid "Given that ``PAP`` transmits a password as plain text, Tarantool requires configuring :ref:`SSL/TLS ` for a connection." +msgstr "" + +#: ../../doc/enterprise/security.rst:320 +msgid "The examples below show how to specify the authentication protocol on the client side:" +msgstr "" + +#: ../../doc/enterprise/security.rst:322 +msgid "For :doc:`net.box `, you can specify the authentication protocol using the ``auth_type`` URI parameter or the corresponding connection option:" +msgstr "" + +#: ../../doc/enterprise/security.rst:326 +msgid "-- URI parameters\n" +"conn = require('net.box').connect(\n" +" 'username:password@localhost:3301?auth_type=pap-sha256')\n" +"\n" +"-- URI parameters table\n" +"conn = require('net.box').connect({\n" +" uri = 'username:password@localhost:3301',\n" +" params = {auth_type = 'pap-sha256'},\n" +"})\n" +"\n" +"-- Connection options\n" +"conn = require('net.box').connect('localhost:3301', {\n" +" user = 'username',\n" +" password = 'password',\n" +" auth_type = 'pap-sha256',\n" +"})" +msgstr "" + +#: ../../doc/enterprise/security.rst:345 +msgid "For :ref:`replication configuration `, the authentication protocol can be specified in URI parameters:" +msgstr "" + +#: ../../doc/enterprise/security.rst:348 +msgid "-- URI parameters\n" +"box.cfg{\n" +" replication = {\n" +" 'replicator:password@localhost:3301?auth_type=pap-sha256',\n" +" },\n" +"}\n" +"\n" +"-- URI parameters table\n" +"box.cfg{\n" +" replication = {\n" +" {\n" +" uri = 'replicator:password@localhost:3301',\n" +" params = {auth_type = 'pap-sha256'},\n" +" },\n" +" },\n" +"}" +msgstr "" + +#: ../../doc/enterprise/security.rst:367 +msgid "If the authentication protocol isn't specified explicitly on the client side, the client uses the protocol configured on the server via ``box.cfg.auth_type``." +msgstr "" + +#: ../../doc/enterprise/security.rst:376 +msgid "Audit log" +msgstr "" + +#: ../../doc/enterprise/security.rst:378 +msgid "Tarantool Enterprise Edition has a built-in audit log that records events such as:" +msgstr "" + +#: ../../doc/enterprise/security.rst:380 +msgid "authentication successes and failures" +msgstr "" + +#: ../../doc/enterprise/security.rst:381 +msgid "connection closures" +msgstr "" + +#: ../../doc/enterprise/security.rst:382 +msgid "creation, removal, enabling, and disabling of users" +msgstr "" + +#: ../../doc/enterprise/security.rst:383 +msgid "changes of passwords, privileges, and roles" +msgstr "" + +#: ../../doc/enterprise/security.rst:384 +msgid "denials of access to database objects" +msgstr "" + +#: ../../doc/enterprise/security.rst:386 +msgid "The audit log contains:" +msgstr "" + +#: ../../doc/enterprise/security.rst:388 +msgid "timestamps" +msgstr "" + +#: ../../doc/enterprise/security.rst:389 +msgid "usernames of users who performed actions" +msgstr "" + +#: ../../doc/enterprise/security.rst:390 +msgid "event types (e.g. ``user_create``, ``user_enable``, ``disconnect``, etc)" +msgstr "" + +#: ../../doc/enterprise/security.rst:391 +msgid "descriptions" +msgstr "" + +#: ../../doc/enterprise/security.rst:393 +msgid "You can configure the following audit log parameters:" +msgstr "" + +#: ../../doc/enterprise/security.rst:395 +msgid "``audit_log = `` which is similar to the :ref:`log ` parameter. This parameter tells Tarantool to record audit events to a specific file." +msgstr "" + +#: ../../doc/enterprise/security.rst:398 +msgid "``audit_nonblock`` which is similar to the :ref:`log_nonblock ` parameter." +msgstr "" + +#: ../../doc/enterprise/security.rst:402 +msgid "For more information on logging, see the following:" +msgstr "" + +#: ../../doc/enterprise/security.rst:404 +msgid "the :doc:`Logs ` section" +msgstr "" + +#: ../../doc/enterprise/security.rst:405 +msgid "the :ref:`Logging ` section in the configuration reference" +msgstr "" + +#: ../../doc/enterprise/security.rst:406 +msgid "the :ref:`Tarantool audit module ` topic" +msgstr "" + +#: ../../doc/enterprise/security.rst:408 +msgid "Access permissions to audit log files can be set up as to any other Unix file system object -- via ``chmod``." +msgstr "" + +#: ../../doc/enterprise/security.rst:414 +msgid "Traffic encryption" +msgstr "" + +#: ../../doc/enterprise/security.rst:416 +msgid "Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over :ref:`binary connections `, that is, between Tarantool instances in a cluster or connecting to an instance via connectors using :doc:`net.box `." +msgstr "" + +#: ../../doc/enterprise/security.rst:419 +msgid "Tarantool uses the OpenSSL library that is included in the delivery package. Please note that SSL connections use only TLSv1.2." +msgstr "" + +#: ../../doc/enterprise/security.rst:425 +msgid "Configuration" +msgstr "" + +#: ../../doc/enterprise/security.rst:427 +msgid "To configure traffic encryption, you need to set the special :ref:`URI parameters ` for a particular connection. The parameters can be set for the following ``box.cfg`` options and ``nex.box`` method:" +msgstr "" + +#: ../../doc/enterprise/security.rst:430 +msgid ":ref:`box.cfg.listen ` -- on the server side." +msgstr "" + +#: ../../doc/enterprise/security.rst:431 +msgid ":ref:`box.cfg.replication `--on the client side." +msgstr "" + +#: ../../doc/enterprise/security.rst:432 +msgid ":ref:`net_box_object.connect() `--on the client side." +msgstr "" + +#: ../../doc/enterprise/security.rst:434 +msgid "Below is the list of the parameters. In the :ref:`next section `, you can find details and examples on what should be configured on both the server side and the client side." +msgstr "" + +#: ../../doc/enterprise/security.rst:437 +msgid "``transport`` -- enables SSL encryption for a connection if set to ``ssl``. The default value is ``plain``, which means the encryption is off. If the parameter is not set, the encryption is off too. Other encryption-related parameters can be used only if the ``transport = 'ssl'`` is set." +msgstr "" + +#: ../../doc/enterprise/security.rst:441 +msgid "Example:" +msgstr "" + +#: ../../doc/enterprise/security.rst:443 +msgid "c = require('net.box').connect({\n" +" uri = 'localhost:3301',\n" +" params = {transport = 'ssl'}\n" +"})" +msgstr "" + +#: ../../doc/enterprise/security.rst:450 +msgid "``ssl_key_file`` -- a path to a private SSL key file. Mandatory for a server. For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter." +msgstr "" + +#: ../../doc/enterprise/security.rst:455 +msgid "``ssl_cert_file`` -- a path to an SSL certificate file. Mandatory for a server. For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional." +msgstr "" + +#: ../../doc/enterprise/security.rst:459 +msgid "``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. Optional. If not set, the peer won't be checked for authenticity." +msgstr "" + +#: ../../doc/enterprise/security.rst:461 +msgid "Both a server and a client can use the ``ssl_ca_file`` parameter:" +msgstr "" + +#: ../../doc/enterprise/security.rst:463 +msgid "If it's on the server side, the server verifies the client." +msgstr "" + +#: ../../doc/enterprise/security.rst:464 +msgid "If it's on the client side, the client verifies the server." +msgstr "" + +#: ../../doc/enterprise/security.rst:465 +msgid "If both sides have the CA files, the sever and the client verify each other." +msgstr "" + +#: ../../doc/enterprise/security.rst:467 +msgid "``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use. See the :ref:`enterprise-iproto-encryption-ciphers` section for details. Optional. Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found." +msgstr "" + +#: ../../doc/enterprise/security.rst:470 +msgid "``ssl_password`` -- a password for an encrypted private SSL key. Optional. Alternatively, the password can be provided in ``ssl_password_file``." +msgstr "" + +#: ../../doc/enterprise/security.rst:473 +msgid "``ssl_password_file`` -- a text file with one or more passwords for encrypted private SSL keys (each on a separate line). Optional. Alternatively, the password can be provided in ``ssl_password``." +msgstr "" + +#: ../../doc/enterprise/security.rst:476 +msgid "Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order:" +msgstr "" + +#: ../../doc/enterprise/security.rst:478 +msgid "If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it." +msgstr "" + +#: ../../doc/enterprise/security.rst:479 +msgid "If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` one by one in the order they are written." +msgstr "" + +#: ../../doc/enterprise/security.rst:481 +msgid "If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, or none of them is provided, Tarantool treats the private key as unencrypted." +msgstr "" + +#: ../../doc/enterprise/security.rst:484 +msgid "Configuration example:" +msgstr "" + +#: ../../doc/enterprise/security.rst:486 +msgid "box.cfg{ listen = {\n" +" uri = 'localhost:3301',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file',\n" +" ssl_ciphers = 'HIGH:!aNULL',\n" +" ssl_password = 'topsecret'\n" +" }\n" +"}}" +msgstr "" + +#: ../../doc/enterprise/security.rst:502 +msgid "Supported ciphers" +msgstr "" + +#: ../../doc/enterprise/security.rst:504 +msgid "Tarantool Enterprise supports the following cipher suites:" +msgstr "" + +#: ../../doc/enterprise/security.rst:506 +msgid "ECDHE-ECDSA-AES256-GCM-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:507 +msgid "ECDHE-RSA-AES256-GCM-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:508 +msgid "DHE-RSA-AES256-GCM-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:509 +msgid "ECDHE-ECDSA-CHACHA20-POLY1305" +msgstr "" + +#: ../../doc/enterprise/security.rst:510 +msgid "ECDHE-RSA-CHACHA20-POLY1305" +msgstr "" + +#: ../../doc/enterprise/security.rst:511 +msgid "DHE-RSA-CHACHA20-POLY1305" +msgstr "" + +#: ../../doc/enterprise/security.rst:512 +msgid "ECDHE-ECDSA-AES128-GCM-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:513 +msgid "ECDHE-RSA-AES128-GCM-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:514 +msgid "DHE-RSA-AES128-GCM-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:515 +msgid "ECDHE-ECDSA-AES256-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:516 +msgid "ECDHE-RSA-AES256-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:517 +msgid "DHE-RSA-AES256-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:518 +msgid "ECDHE-ECDSA-AES128-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:519 +msgid "ECDHE-RSA-AES128-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:520 +msgid "DHE-RSA-AES128-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:521 +msgid "ECDHE-ECDSA-AES256-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:522 +msgid "ECDHE-RSA-AES256-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:523 +msgid "DHE-RSA-AES256-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:524 +msgid "ECDHE-ECDSA-AES128-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:525 +msgid "ECDHE-RSA-AES128-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:526 +msgid "DHE-RSA-AES128-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:527 +msgid "AES256-GCM-SHA384" +msgstr "" + +#: ../../doc/enterprise/security.rst:528 +msgid "AES128-GCM-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:529 +msgid "AES256-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:530 +msgid "AES128-SHA256" +msgstr "" + +#: ../../doc/enterprise/security.rst:531 +msgid "AES256-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:532 +msgid "AES128-SHA" +msgstr "" + +#: ../../doc/enterprise/security.rst:533 +msgid "GOST2012-GOST8912-GOST8912" +msgstr "" + +#: ../../doc/enterprise/security.rst:534 +msgid "GOST2001-GOST89-GOST89" +msgstr "" + +#: ../../doc/enterprise/security.rst:536 +msgid "Tarantool Enterprise static build has the embeded engine to support the GOST cryptographic algorithms. If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ``ssl_ciphers`` parameter, for example:" +msgstr "" + +#: ../../doc/enterprise/security.rst:539 +msgid "box.cfg{ listen = {\n" +" uri = 'localhost:3301',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file',\n" +" ssl_ciphers = 'GOST2012-GOST8912-GOST8912'\n" +" }\n" +"}}" +msgstr "" + +#: ../../doc/enterprise/security.rst:551 +msgid "For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__." +msgstr "" + +#: ../../doc/enterprise/security.rst:554 +msgid "Using environment variables" +msgstr "" + +#: ../../doc/enterprise/security.rst:556 +msgid "The URI parameters for traffic encryption can also be set via environment variables. For example:" +msgstr "" + +#: ../../doc/enterprise/security.rst:558 +msgid "export TT_LISTEN=\"localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file\"" +msgstr "" + +#: ../../doc/enterprise/security.rst:562 +msgid "For details, refer to the Tarantool :ref:`configuration reference `." +msgstr "" + +#: ../../doc/enterprise/security.rst:567 +msgid "Server-client configuration details" +msgstr "" + +#: ../../doc/enterprise/security.rst:569 +msgid "When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. Below you can find the summary on the options and parameters to be used and :ref:`examples of configuration `." +msgstr "" + +#: ../../doc/enterprise/security.rst:572 +msgid "**Server side**" +msgstr "" + +#: ../../doc/enterprise/security.rst:574 +msgid "Is configured via the ``box.cfg.listen`` option." +msgstr "" + +#: ../../doc/enterprise/security.rst:575 +msgid "Mandatory URI parameters: ``transport``, ``ssl_key_file`` and ``ssl_cert_file``." +msgstr "" + +#: ../../doc/enterprise/security.rst:576 +msgid "Optional URI parameters: ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file``." +msgstr "" + +#: ../../doc/enterprise/security.rst:579 +msgid "**Client side**" +msgstr "" + +#: ../../doc/enterprise/security.rst:581 +msgid "Is configured via the ``box.cfg.replication`` option (see :ref:`details `) or ``net_box_object.connect()``." +msgstr "" + +#: ../../doc/enterprise/security.rst:583 +msgid "Parameters:" +msgstr "" + +#: ../../doc/enterprise/security.rst:585 +msgid "If the server side has only the ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` parameters set, on the client side, you need to specify only ``transport = ssl`` as the mandatory parameter. All other URI parameters are optional." +msgstr "" + +#: ../../doc/enterprise/security.rst:589 +msgid "If the server side also has the ``ssl_ca_file`` parameter set, on the client side, you need to specify ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` as the mandatory parameters. Other parameters -- ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file`` -- are optional." +msgstr "" + +#: ../../doc/enterprise/security.rst:596 +msgid "Configuration examples" +msgstr "" + +#: ../../doc/enterprise/security.rst:598 +msgid "Suppose, there is a :ref:`master-replica ` set with two Tarantool instances:" +msgstr "" + +#: ../../doc/enterprise/security.rst:600 +#: ../../doc/enterprise/security.rst:609 +#: ../../doc/enterprise/security.rst:642 +msgid "127.0.0.1:3301 -- master (server)" +msgstr "" + +#: ../../doc/enterprise/security.rst:601 +msgid "127.0.0.1:3302 -- replica (client)." +msgstr "" + +#: ../../doc/enterprise/security.rst:603 +msgid "Examples below show the configuration related to connection encryption for two cases: when the trusted certificate authorities (CA) file is not set on the server side and when it does. Only mandatory URI parameters are mentioned in these examples." +msgstr "" + +#: ../../doc/enterprise/security.rst:607 +msgid "**Without CA**" +msgstr "" + +#: ../../doc/enterprise/security.rst:611 +msgid "box.cfg{\n" +" listen = {\n" +" uri = '127.0.0.1:3301',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file'\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/security.rst:624 +#: ../../doc/enterprise/security.rst:658 +msgid "127.0.0.1:3302 -- replica (client)" +msgstr "" + +#: ../../doc/enterprise/security.rst:626 +msgid "box.cfg{\n" +" listen = {\n" +" uri = '127.0.0.1:3302',\n" +" params = {transport = 'ssl'}\n" +" },\n" +" replication = {\n" +" uri = 'username:password@127.0.0.1:3301',\n" +" params = {transport = 'ssl'}\n" +" },\n" +" read_only = true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/security.rst:640 +msgid "**With CA**" +msgstr "" + +#: ../../doc/enterprise/security.rst:644 +msgid "box.cfg{\n" +" listen = {\n" +" uri = '127.0.0.1:3301',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file',\n" +" ssl_ca_file = '/path_to_ca_file'\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/enterprise/security.rst:660 +msgid "box.cfg{\n" +" listen = {\n" +" uri = '127.0.0.1:3302',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file'\n" +" }\n" +" },\n" +" replication = {\n" +" uri = 'username:password@127.0.0.1:3301',\n" +" params = {\n" +" transport = 'ssl',\n" +" ssl_key_file = '/path_to_key_file',\n" +" ssl_cert_file = '/path_to_cert_file'\n" +" }\n" +" },\n" +" read_only = true\n" +"}" +msgstr "" + +#: ../../doc/enterprise/security.rst:685 +msgid "Recommendations on security hardening" +msgstr "" + +#: ../../doc/enterprise/security.rst:687 +msgid "This section lists recommendations that can help you harden the cluster's security." +msgstr "" + +#: ../../doc/enterprise/security.rst:692 +msgid "Encrypting traffic" +msgstr "" + +#: ../../doc/enterprise/security.rst:694 +msgid "Since version 2.10.0, Tarantool Enterprise Edition has built-in support for using SSL to encrypt the client-server communications over binary connections, that is, between Tarantool instances in a cluster. For details on enabling SSL encryption, see the :ref:`enterprise-iproto-encryption` section of this guide." +msgstr "" + +#: ../../doc/enterprise/security.rst:697 +msgid "In case the built-in encryption is not set for particular connections, consider the following security recommendations:" +msgstr "" + +#: ../../doc/enterprise/security.rst:699 +msgid "setting up connection tunneling, or" +msgstr "" + +#: ../../doc/enterprise/security.rst:700 +msgid "encrypting the actual data stored in the database." +msgstr "" + +#: ../../doc/enterprise/security.rst:702 +msgid "For more information on data encryption, see the :doc:`crypto module reference `." +msgstr "" + +#: ../../doc/enterprise/security.rst:705 +msgid "The `HTTP server module `_ provided by rocks does not support the HTTPS protocol. To set up a secure connection for a client (e.g., REST service), consider hiding the Tarantool instance (router if it is a cluster of instances) behind an Nginx server and setting up an SSL certificate for it." +msgstr "" + +#: ../../doc/enterprise/security.rst:711 +msgid "To make sure that no information can be intercepted 'from the wild', run nginx on the same physical server as the instance and set up their communication over a Unix socket. For more information, see the :doc:`socket module reference `." +msgstr "" + +#: ../../doc/enterprise/security.rst:719 +msgid "Firewall configuration" +msgstr "" + +#: ../../doc/enterprise/security.rst:721 +msgid "To protect the cluster from any unwanted network activity 'from the wild', configure the firewall on each server to allow traffic on ports listed in :ref:`Network requirements `." +msgstr "" + +#: ../../doc/enterprise/security.rst:725 +msgid "If you are using static IP addresses, whitelist them, again, on each server as the cluster has a full mesh network topology. Consider blacklisting all the other addresses on all servers except the router (running behind the Nginx server)." +msgstr "" + +#: ../../doc/enterprise/security.rst:729 +msgid "Tarantool Enterprise does not provide defense against DoS or DDoS attacks. Consider using third-party software instead." +msgstr "" + +#: ../../doc/enterprise/security.rst:735 +msgid "Data integrity" +msgstr "" + +#: ../../doc/enterprise/security.rst:737 +msgid "Tarantool Enterprise Edition does not keep checksums or provide the means to control data integrity. However, it ensures data persistence using a write-ahead log, regularly snapshots the entire data set to disk, and checks the data format whenever it reads the data back from the disk. For more information, see the :ref:`Data persistence ` section." +msgstr "" diff --git a/locale/en/platform/sharding/index.pot b/locale/en/platform/sharding/index.pot new file mode 100644 index 0000000000..82a899bcfe --- /dev/null +++ b/locale/en/platform/sharding/index.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/sharding/index.rst:5 +msgid "Sharding" +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:7 +msgid "Scaling databases in a growing project is often considered one of the most challenging issues. Once a single server cannot withstand the load, scaling methods should be applied." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:11 +msgid "**Sharding** is a database architecture that allows for `horizontal scaling `_, which implies that a dataset is partitioned and distributed over multiple servers." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:15 +msgid "With Tarantool's `vshard `_ module, the tuples of a dataset are distributed across multiple nodes, with a Tarantool database server instance on each node. Each instance handles only a subset of the total data, so larger loads can be handled by simply adding more servers. The initial dataset is partitioned into multiple parts, so each part is stored on a separate server." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:22 +msgid "The ``vshard`` module is based on the concept of :ref:`virtual buckets `, where a tuple set is partitioned into a large number of abstract virtual nodes (**virtual buckets**, further just **buckets**) rather than into a smaller number of physical nodes." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:27 +msgid "The dataset is partitioned using **sharding keys** (bucket id numbers). Hashing a sharding key into a large number of buckets allows seamlessly changing the number of servers in the cluster. The **rebalancing mechanism** distributes buckets evenly among all shards in case some servers were added or removed." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:32 +msgid "The buckets have **states**, so it is easy to monitor the server states. For example, a server instance is active and available for all types of requests, or a failover occurred and the instance accepts only read requests." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:36 +msgid "The ``vshard`` module provides router and storage API (public and internal) for sharding-aware applications." +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:38 +msgid "Check out the :ref:`quick start guide ` or learn more about :ref:`how sharding works ` in Tarantool:" +msgstr "" + +#: ../../doc/concepts/sharding/index.rst:46 +msgid "You can also find out more about :ref:`sharding administration ` or dive into the ``vshard`` configuration and API :ref:`reference `." +msgstr "" diff --git a/locale/en/platform/sharding/vshard_admin.pot b/locale/en/platform/sharding/vshard_admin.pot new file mode 100644 index 0000000000..2f31412e93 --- /dev/null +++ b/locale/en/platform/sharding/vshard_admin.pot @@ -0,0 +1,686 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/book/admin/vshard_admin.rst:4 +msgid "Sharding with vshard" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:6 +msgid "Sharding in Tarantool is implemented in the ``vshard`` module. For a quick start with ``vshard``, refer to the :ref:`guide `." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:12 +msgid "Installation" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:14 +msgid "The ``vshard`` module is distributed separately from the main Tarantool package. To install the module, execute the following command:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:17 +msgid "$ tt rocks install vshard" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:23 +msgid "The ``vshard`` module requires Tarantool of the version 1.10.1 or higher, :ref:`Tarantool development package `, ``git``, ``cmake`` and ``gcc`` packages installed." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:30 +msgid "Configuration" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:32 +msgid "Any viable sharded cluster consists of:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:34 +msgid "one or more replica sets, each containing two or more :ref:`storage ` instances," +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:36 +msgid "one or more :ref:`router ` instances." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:38 +msgid "The number of ``storage`` instances in a replica set defines the redundancy factor of the data. The recommended value is 3 or more. The number of ``router`` instances is not limited, because routers are completely stateless. We recommend increasing the number of routers when an existing ``router`` instance becomes CPU or I/O bound." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:43 +msgid "``vshard`` supports multiple ``router`` instances on a single Tarantool instance. Each ``router`` can be connected to any ``vshard`` cluster. Multiple ``router`` instances can be connected to the same cluster." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:47 +msgid "As the ``router`` and ``storage`` applications perform completely different sets of functions, they should be deployed to different Tarantool instances. Although it is technically possible to place the router application on every ``storage`` node, this approach is highly discouraged and should be avoided on production deployments." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:52 +msgid "All ``storage`` instances can be deployed using identical instance (configuration) files." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:55 +msgid "All ``router`` instances can also be deployed using identical instance (configuration) files." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:58 +msgid "All cluster nodes must share a common topology. An administrator must ensure that the configurations are identical. We suggest using a configuration management tool like Ansible or Puppet to deploy the cluster." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:62 +msgid "Sharding is not integrated into any system for centralized configuration management. It is expected that the application itself is responsible for interacting with such a system and passing the sharding parameters." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:66 +msgid "The configuration example of a simple sharded cluster is available :ref:`here `." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:72 +msgid "Replica weights" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:74 +msgid "The ``router`` sends all read-write requests to the master instance only. Setting replica weights allows sending read-only requests not only to the master instance, but to any available replica that is the 'nearest' to the ``router``. Weights are used to define distances between replicas within a replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:79 +msgid "Weights can be used, for example, to define the physical distance between the ``router`` and each replica in each replica set. In this case read requests are sent to the nearest replica (with the lowest weight)." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:83 +msgid "Setting weights can also help to define the most powerful replicas: the ones that can process the largest number of requests per second." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:86 +msgid "The idea is to specify the zone for every ``router`` and every replica, therefore filling a matrix of relative zone weights. This approach allows setting different weights in different zones for the same replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:90 +msgid "To set weights, use the zone attribute for each replica during configuration:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:92 +msgid "local cfg = {\n" +" sharding = {\n" +" ['...replicaset_uuid...'] = {\n" +" replicas = {\n" +" ['...replica_uuid...'] = {\n" +" ...,\n" +" zone = \n" +" }\n" +" }\n" +" }\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:107 +msgid "Then, specify relative weights for each zone pair in the ``weights`` parameter of ``vshard.router.cfg``. For example:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:110 +msgid "weights = {\n" +" [1] = {\n" +" [2] = 1, -- Routers of the 1st zone see the weight of the 2nd zone as 1.\n" +" [3] = 2, -- Routers of the 1st zone see the weight of the 3rd zone as 2.\n" +" [4] = 3, -- ...\n" +" },\n" +" [2] = {\n" +" [1] = 10,\n" +" [2] = 0,\n" +" [3] = 10,\n" +" [4] = 20,\n" +" },\n" +" [3] = {\n" +" [1] = 100,\n" +" [2] = 200, -- Routers of the 3rd zone see the weight of the 2nd zone as 200.\n" +" -- Mind that it is not equal to the weight of the 2nd zone visible\n" +" -- from the 1st zone (= 1).\n" +" [4] = 1000,\n" +" }\n" +"}\n" +"\n" +"local cfg = vshard.router.cfg({weights = weights, sharding = ...})" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:138 +msgid "Replica set weights" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:140 +msgid "A replica set weight is not the same as the replica weight. The weight of a replica set defines the capacity of the replica set: the larger the weight, the more buckets the replica set can store. The total size of all sharded spaces in the replica set is also its capacity metric." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:145 +msgid "You can consider replica set weights as the relative amount of data within a replica set. For example, if ``replicaset_1 = 100``, and ``replicaset_2 = 200``, the second replica set stores twice as many buckets as the first one. By default, all weights of all replica sets are equal." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:150 +msgid "You can use weights, for example, to store the prevailing amount of data on a replica set with more memory space." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:156 +msgid "Rebalancing process" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:158 +msgid "There is an **etalon number** of buckets for a replica set. (Etalon in this context means \"ideal\".) If there is no deviation from this number in the whole replica set, then the buckets are distributed evenly." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:163 +msgid "The etalon number is calculated automatically considering the number of buckets in the cluster and weights of the replica sets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:166 +msgid "Rebalancing starts if the **disbalance threshold of a replica set** exceeds the disbalance threshold :ref:`specified in the configuration `." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:170 +msgid "The disbalance threshold of a replica set is calculated as follows:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:172 +msgid "|etalon_bucket_number - real_bucket_number| / etalon_bucket_number * 100" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:176 +msgid "For example: The user specified the number of buckets is 3000, and weights of 3 replica sets are 1, 0.5, and 1.5. The resulting etalon numbers of buckets for the replica sets are: 1st replica set – 1000, 2nd replica set – 500, 3rd replica set – 1500." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:181 +msgid "This approach allows assigning a zero weight to a replica set, which initiates migration of its buckets to the remaining cluster nodes. It also allows adding a new zero-load replica set, which initiates migration of the buckets from the loaded replica sets to the zero-load replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:188 +msgid "A new zero-load replica set should be assigned a weight for rebalancing to start." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:190 +msgid "When a new shard is added, the configuration can be updated dynamically:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:192 +msgid "The configuration should be updated on all the ``routers`` first, and then on all the ``storages``." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:194 +msgid "The new shard becomes available for rebalancing in the ``storage`` layer." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:195 +msgid "As a result of rebalancing, buckets are migrated to the new shard." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:196 +msgid "If a migrated bucket is requested, ``router`` receives an error code containing information about the new location of the bucket." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:199 +msgid "At this time, the new shard is already present in the ``router``'s pool of connections, so redirection is transparent for the application." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:205 +msgid "Parallel rebalancing" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:207 +msgid "Originally, ``vshard`` had quite a simple ``rebalancer`` – one process on one node that calculated *routes* which should send buckets, how many, and to whom. The nodes applied these routes one by one sequentially." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:212 +msgid "Unfortunately, such a simple schema worked not fast enough, especially for Vinyl, where costs of reading disk were comparable with network costs. In fact, with Vinyl the ``rebalancer`` routes applier was sleeping most of the time." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:217 +msgid "Now each node can send multiple buckets in parallel in a round-robin manner to multiple destinations, or to just one." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:220 +msgid "To set the degree of parallelism, a new option was added -- :ref:`rebalancer_max_sending `. You can specify it in a storage configuration in the root table:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:224 +msgid "cfg.rebalancer_max_sending = 5\n" +"vshard.storage.cfg(cfg, box.info.uuid)" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:229 +msgid "In routers, this option is ignored." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:233 +msgid "Specifying ``cfg.rebalancer_max_sending = N`` probably won't give N times speed up. It depends on network, disk, number of other fibers in the system." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:236 +msgid "**Example #1:**" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:238 +msgid "You have 10 replica sets and a new one is added. Now all the 10 replica sets will try to send buckets to the new one." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:241 +msgid "Assume that each replica set can send up to 5 buckets at once. In that case, the new replica set will experience a rather big load of 50 buckets being downloaded at once. If the node needs to do some other work, perhaps such a big load is undesirable. Also too many parallel buckets can cause timeouts in the rebalancing process itself." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:248 +msgid "To fix the problem, you can set a lower value for ``rebalancer_max_sending`` for old replica sets, or decrease ``rebalancer_max_receiving`` for the new one. In the latter case some workers on old nodes will be throttled, and you will see that in the logs." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:253 +msgid "``rebalancer_max_sending`` is important, if you have restrictions for the maximal number of buckets that can be read-only at once in the cluster. As you remember, when a bucket is being sent, it does not accept new write requests." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:258 +msgid "**Example #2:**" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:260 +msgid "You have 100000 buckets and each bucket stores ~0.001% of your data. The cluster has 10 replica sets. And you never can afford > 0.1% of data locked on write. Then you should not set ``rebalancer_max_sending`` > 10 on these nodes. It guarantees that the rebalancer won't send more than 100 buckets at once in the whole cluster." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:267 +msgid "If ``max_sending`` is too high and ``max_receiving`` is too low, then some buckets will try to get relocated – and will fail with that. This problem will consume network resources and time. It is important to configure these parameters to not conflict with each other." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:275 +msgid "Replica set lock and bucket pin" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:277 +msgid "A replica set lock makes a replica set invisible to the ``rebalancer``: a locked replica set can neither receive new buckets nor migrate its own buckets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:280 +msgid "A bucket pin blocks a specific bucket from migrating: a pinned bucket stays on the replica set to which it is pinned, until it is unpinned." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:283 +msgid "Pinning all replica set buckets is not equivalent to locking a replica set. Even if you pin all buckets, a non-locked replica set can still receive new buckets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:286 +msgid "Replica set lock is helpful, for example, to separate a replica set from production replica sets for testing, or to preserve some application metadata that must not be sharded for a while. A bucket pin is used for similar cases but in a smaller scope." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:291 +msgid "By both locking a replica set and pinning all buckets, one can isolate an entire replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:294 +msgid "Locked replica sets and pinned buckets affect the rebalancing algorithm as the ``rebalancer`` must ignore locked replica sets and consider pinned buckets when attempting to reach the best possible balance." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:298 +msgid "The issue is not trivial as a user can pin too many buckets to a replica set, so a perfect balance becomes unreachable. For example, consider the following cluster (assume all replica set weights are equal to 1)." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:302 +msgid "The initial configuration:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:304 +msgid "rs1: bucket_count = 150\n" +"rs2: bucket_count = 150, pinned_count = 120" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:309 +msgid "Adding a new replica set:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:311 +msgid "rs1: bucket_count = 150\n" +"rs2: bucket_count = 150, pinned_count = 120\n" +"rs3: bucket_count = 0" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:317 +msgid "The perfect balance would be ``100 - 100 - 100``, which is impossible since the ``rs2`` replica set has 120 pinned buckets. The best possible balance here is the following:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:321 +msgid "rs1: bucket_count = 90\n" +"rs2: bucket_count = 120, pinned_count 120\n" +"rs3: bucket_count = 90" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:327 +msgid "The ``rebalancer`` moved as many buckets as possible from ``rs2`` to decrease the disbalance. At the same time it respected equal weights of ``rs1`` and ``rs3``." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:330 +msgid "The algorithms for implementing locks and pins are completely different, although they look similar in terms of functionality." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:336 +msgid "Replica set lock and rebalancing" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:338 +msgid "Locked replica sets simply do not participate in rebalancing. This means that even if the actual total number of buckets is not equal to the etalon number, the disbalance cannot be fixed due to the lock. When the rebalancer detects that one of the replica sets is locked, it recalculates the etalon number of buckets of the non-locked replica sets as if the locked replica set and its buckets did not exist at all." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:348 +msgid "Bucket pin and rebalancing" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:350 +msgid "Rebalancing replica sets with pinned buckets requires a more complex algorithm. Here ``pinned_count[o]`` is the number of pinned buckets, and ``etalon_count`` is the etalon number of buckets for a replica set:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:354 +msgid "The ``rebalancer`` calculates the etalon number of buckets as if all buckets were not pinned. Then the rebalancer checks each replica set and compares the etalon number of buckets with the number of pinned buckets in a replica set. If ``pinned_count < etalon_count``, non-locked replica sets (at this point all locked replica sets already are filtered out) with pinned buckets can receive new buckets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:360 +msgid "If ``pinned_count > etalon_count``, the disbalance cannot be fixed, as the ``rebalancer`` cannot move pinned buckets out of this replica set. In such a case the etalon number is updated and set equal to the number of pinned buckets. The replica sets with ``pinned_count > etalon_count`` are not processed by the ``rebalancer``, and the number of pinned buckets is subtracted from the total number of buckets. The rebalancer tries to move out as many buckets as possible from such replica sets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:367 +msgid "This procedure is restarted from step 1 for replica sets with ``pinned_count >= etalon_count`` until ``pinned_count <= etalon_count`` on all replica sets. The procedure is also restarted when the total number of buckets is changed." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:372 +msgid "Here is the pseudocode for the algorithm:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:374 +msgid "function cluster_calculate_perfect_balance(replicasets, bucket_count)\n" +" -- rebalance the buckets using weights of the still viable replica sets --\n" +"end;\n" +"\n" +"cluster = ;\n" +"bucket_count = ;\n" +"can_reach_balance = false\n" +"while not can_reach_balance do\n" +" can_reach_balance = true\n" +" cluster_calculate_perfect_balance(cluster, bucket_count);\n" +" foreach replicaset in cluster do\n" +" if replicaset.perfect_bucket_count <\n" +" replicaset.pinned_bucket_count then\n" +" can_reach_balance = false\n" +" bucket_count -= replicaset.pinned_bucket_count;\n" +" replicaset.perfect_bucket_count =\n" +" replicaset.pinned_bucket_count;\n" +" end;\n" +" end;\n" +"end;\n" +"cluster_calculate_perfect_balance(cluster, bucket_count);" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:398 +msgid "The complexity of the algorithm is ``O(N^2)``, where N is the number of replica sets. On each step, the algorithm either finishes the calculation, or ignores at least one new replica set overloaded with the pinned buckets, and updates the etalon number of buckets on other replica sets." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:406 +msgid "Bucket ref" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:408 +msgid "Bucket ref is an in-memory counter that is similar to the :ref:`bucket pin `, but has the following differences:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:411 +msgid "Bucket ref is not persistent. Refs are intended for forbidding bucket transfer during request execution, but on restart all requests are dropped." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:414 +msgid "There are two types of bucket refs: read-only (RO) and read-write (RW)." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:416 +msgid "If a bucket has RW refs, it cannot be moved. However, when the rebalancer needs it to be sent, it locks the bucket for new write requests, waits until all current requests are finished, and then sends the bucket." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:420 +msgid "If a bucket has RO refs, it can be sent, but cannot be dropped. Such a bucket can even enter GARBAGE or SENT state, but its data is kept until the last reader is gone." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:424 +msgid "A single bucket can have both RO and RW refs." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:426 +msgid "Bucket ref is countable." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:428 +msgid "The :ref:`vshard.storage.bucket_ref/unref()` methods are called automatically when :ref:`vshard.router.call() ` or :ref:`vshard.storage.call() ` is used. For raw API like ``r = vshard.router.route() r:callro/callrw`` you should explicitly call the ``bucket_ref()`` method inside the function. Also, make sure that you call ``bucket_unref()`` after ``bucket_ref()``, otherwise the bucket cannot be moved from the storage until the instance restart." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:436 +msgid "To see how many refs there are for a bucket, use :ref:`vshard.storage.buckets_info([bucket_id]) ` (the ``bucket_id`` parameter is optional)." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:440 +msgid "For example:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:442 +msgid "vshard.storage.buckets_info(1)\n" +"---\n" +"- 1:\n" +" status: active\n" +" ref_rw: 1\n" +" ref_ro: 1\n" +" ro_lock: true\n" +" rw_lock: true\n" +" id: 1" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:457 +msgid "Defining spaces" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:459 +msgid "Database Schema is stored on ``storages``, while ``routers`` know nothing about spaces and tuples." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:462 +msgid "Spaces should be defined within a storage application using ``box.once()``. For example:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:465 +msgid "box.once(\"testapp:schema:1\", function()\n" +" local customer = box.schema.space.create('customer')\n" +" customer:format({\n" +" {'customer_id', 'unsigned'},\n" +" {'bucket_id', 'unsigned'},\n" +" {'name', 'string'},\n" +" })\n" +" customer:create_index('customer_id', {parts = {'customer_id'}})\n" +" customer:create_index('bucket_id', {parts = {'bucket_id'}, unique = false})\n" +"\n" +" local account = box.schema.space.create('account')\n" +" account:format({\n" +" {'account_id', 'unsigned'},\n" +" {'customer_id', 'unsigned'},\n" +" {'bucket_id', 'unsigned'},\n" +" {'balance', 'unsigned'},\n" +" {'name', 'string'},\n" +" })\n" +" account:create_index('account_id', {parts = {'account_id'}})\n" +" account:create_index('customer_id', {parts = {'customer_id'}, unique = false})\n" +" account:create_index('bucket_id', {parts = {'bucket_id'}, unique = false})\n" +" box.snapshot()\n" +"\n" +" box.schema.func.create('customer_lookup')\n" +" box.schema.role.grant('public', 'execute', 'function', 'customer_lookup')\n" +" box.schema.func.create('customer_add')\n" +"end)" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:497 +msgid "Every space you plan to shard must have a field with :ref:`bucket id ` numbers, indexed by the :ref:`shard index `." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:504 +msgid "Adding data" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:506 +msgid "All DML operations with data should be performed via ``router``. The only operation supported by ``router`` is `CALL` via ``bucket_id``:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:509 +msgid "result = vshard.router.call(bucket_id, mode, func, args)" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:513 +msgid "``vshard.router.call()`` routes ``result = func(unpack(args))`` call to a shard which serves ``bucket_id``." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:516 +msgid "``bucket_id`` is just a regular number in the range ``1..``:ref:`bucket_count`. This number can be assigned in an arbitrary way by the client application. A sharded Tarantool cluster uses this number as an opaque unique identifier to distribute data across replica sets. It is guaranteed that all records with the same ``bucket_id`` will be stored on the same replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:526 +msgid "Bootstrapping and restarting a storage" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:528 +msgid "If a replica set master fails, it is recommended to:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:530 +msgid "Switch one of the replicas into the master mode. This allows the new master to process all the incoming requests." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:532 +msgid "Update the configuration of all the cluster members. This forwards all the requests to the new master." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:535 +msgid "Monitoring the master and switching the instance modes can be handled by any external utility." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:538 +msgid "To perform a scheduled downtime of a replica set master, it is recommended to:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:540 +msgid "Update the configuration of the master and wait for the replicas to get into sync. All the requests then are forwarded to a new master." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:542 +msgid "Switch another instance into the master mode." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:543 +#: ../../doc/book/admin/vshard_admin.rst:549 +msgid "Update the configuration of all the nodes." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:544 +msgid "Shut down the old master." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:546 +msgid "To perform a scheduled downtime of a replica set, it is recommended to:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:548 +msgid "Migrate all the buckets to the other cluster storages." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:550 +msgid "Shut down the replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:552 +msgid "In case a whole replica set fails, some part of the dataset becomes inaccessible. Meanwhile, the ``router`` tries to reconnect to the master of the failed replica set. This way, once the replica set is up and running again, the cluster is automatically restored." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:560 +msgid "Fibers" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:562 +msgid "Searches for buckets, buckets recovery, and buckets rebalancing are performed automatically and do not require manual intervention." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:565 +msgid "Technically, there are multiple fibers responsible for different types of operations:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:568 +msgid "a **discovery** fiber on the ``router`` searches for buckets in the background" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:569 +msgid "a **failover** fiber on the ``router`` maintains replica connections" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:570 +msgid "a **garbage collector** fiber on each master ``storage`` removes the contents of buckets that were moved" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:572 +msgid "a **bucket recovery** fiber on each master ``storage`` recovers buckets in the SENDING and RECEIVING states in case of reboot" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:574 +msgid "a **rebalancer** on a single master ``storage`` among all replica sets executes the rebalancing process." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:577 +msgid "See the :ref:`Rebalancing process ` and :ref:`Migration of buckets ` sections for details." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:583 +msgid "Garbage collector" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:585 +msgid "A **garbage collector** fiber runs in the background on the master storages of each replica set. It starts deleting the contents of the bucket in the GARBAGE state part by part. Once the bucket is empty, its record is deleted from the ``_bucket`` system space." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:593 +msgid "Bucket recovery" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:595 +msgid "A **bucket recovery** fiber runs on the master storages. It helps to recover buckets in the SENDING and RECEIVING states in case of reboot." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:598 +msgid "Buckets in the SENDING state are recovered as follows:" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:600 +msgid "The system first searches for buckets in the SENDING state." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:601 +msgid "If such a bucket is found, the system sends a request to the destination replica set." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:603 +msgid "If the bucket on the destination replica set is ACTIVE, the original bucket is deleted from the source node." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:606 +msgid "Buckets in the RECEIVING state are deleted without extra checks." +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:611 +msgid "Failover" +msgstr "" + +#: ../../doc/book/admin/vshard_admin.rst:613 +msgid "A **failover** fiber runs on every ``router``. If a master of a replica set becomes unavailable, the failover fiber redirects read requests to the replicas. Write requests are rejected with an error until the master becomes available." +msgstr "" diff --git a/locale/en/platform/sharding/vshard_architecture.pot b/locale/en/platform/sharding/vshard_architecture.pot new file mode 100644 index 0000000000..eaecd80b62 --- /dev/null +++ b/locale/en/platform/sharding/vshard_architecture.pot @@ -0,0 +1,528 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:4 +msgid "Architecture" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:11 +msgid "Consider a distributed Tarantool cluster that consists of subclusters called **shards**, each storing some part of data. Each shard, in its turn, constitutes a **replica set** consisting of several **replicas**, one of which serves as a master node that processes all read and write requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:16 +msgid "The whole dataset is logically partitioned into a predefined number of :ref:`virtual buckets ` (further just **buckets**), each assigned a unique number ranging from 1 to N, where N is the total number of buckets. The number of buckets is specifically chosen to be several orders of magnitude larger than the potential number of cluster nodes, even given future cluster scaling. For example, with M projected nodes the dataset may be split into 100 * M or even 1,000 * M buckets. Care should be taken when picking the number of buckets: if too large, it may require extra memory for storing the routing information; if too small, it may decrease the granularity of rebalancing." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:27 +msgid "Each shard stores a unique subset of buckets, which means that a bucket cannot belong to several shards at once, as illustrated below:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:33 +msgid "This shard-to-bucket mapping is stored in a table in one of Tarantool’s system spaces, with each shard holding only a specific part of the mapping that covers those buckets that were assigned to this shard." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:37 +msgid "Apart from the mapping table, the **bucket id** is also stored in a special field of every tuple of every table participating in sharding." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:40 +msgid "Once a shard receives any request (except for SELECT) from an application, this shard checks the bucket id specified in the request against the table of bucket ids that belong to a given node. If the specified bucket id is invalid, the request gets terminated with the following error: “wrong bucket”. Otherwise the request is executed, and all the data created in the process is assigned the bucket id specified in the request. Note that the request should only modify the data that has the same bucket id as the request itself." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:49 +msgid "Storing bucket ids both in the data itself and the mapping table ensures data consistency regardless of the application logic and makes rebalancing transparent for the application. Storing the mapping table in a system space ensures sharding is performed consistently in case of a failover, as all the replicas in a shard share a common table state." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:58 +msgid "Virtual buckets" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:60 +msgid "The sharded dataset is partitioned into a large number of abstract nodes called **virtual buckets** (further just **buckets**)." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:63 +msgid "The dataset is partitioned using the sharding key (or **bucket id**, in Tarantool terminology). Bucket id is a number from 1 to N, where N is the total number of buckets." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:70 +msgid "Each replica set stores a unique subset of buckets. One bucket cannot belong to multiple replica sets at a time." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:73 +msgid "The total number of buckets is determined by the administrator who sets up the initial cluster configuration." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:76 +msgid "Every space you plan to shard must have a numeric field containing bucket id-s. This field must comply with the following requirements:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:79 +msgid "The field's data type can be: unsigned, number or integer." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:80 +msgid "The field must be not nullable." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:81 +msgid "The field must be indexed by the :ref:`shard_index `. The default name for this index is ``bucket_id``." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:84 +msgid "See the :ref:`configuration example `." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:89 +msgid "Structure" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:91 +msgid "A sharded cluster in Tarantool consists of:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:93 +msgid "storages," +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:94 +msgid "routers," +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:95 +msgid "and a rebalancer." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:103 +msgid "Storage" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:105 +msgid "**Storage** is a node storing a subset of the dataset. Multiple replicated (for redundancy) storages comprise a **replica set** (also called **shard**)." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:108 +msgid "Each storage in a replica set has a role, **master** or **replica**. A master processes read and write requests. A replica processes read requests but cannot process write requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:118 +msgid "Router" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:120 +msgid "**Router** is a standalone software component that routes read and write requests from the client application to shards." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:123 +msgid "All requests from the application come to the sharded cluster through a ``router``. The ``router`` keeps the topology of a sharded cluster transparent for the application, thus keeping the application unaware of:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:127 +msgid "the number and location of shards," +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:128 +msgid "data rebalancing process," +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:129 +msgid "the fact and the process of a failover that occurred after a replica's failure." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:131 +msgid "A router can also calculate a bucket id on its own provided that the application clearly defines rules for calculating a bucket id based on the request data. To do it, a router needs to be aware of the data schema." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:135 +msgid "The ``router`` does not have a persistent state, nor does it store the cluster topology or balance the data. The ``router`` is a standalone software component that can run in the storage layer or application layer depending on the application features." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:139 +msgid "A router maintains a constant pool of connections to all the storages that is created at startup. Creating it this way helps avoid configuration errors. Once a pool is created, a router caches the current state of the ``_vbucket`` table to speed up the routing. In case a bucket id is moved to another storage as a result of data rebalancing, or one of the shards fails over to a replica, a router updates the routing table in a way that's transparent for the application." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:146 +msgid "Sharding is not integrated into any centralized configuration storage system. It is assumed that the application itself handles all the interactions with such systems and passes sharding parameters. That said, the configuration can be changed dynamically - for example, when adding or deleting one or several shards:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:151 +msgid "To add a new shard to the cluster, a system administrator first changes the configuration of all the routers and then the configuration of all the storages." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:153 +msgid "The new shard becomes available to the storage layer for rebalancing." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:154 +msgid "As a result of rebalancing, one of the vbuckets is moved to the new shard." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:155 +msgid "When trying to access the vbucket, a router receives a special error code that specifies the new vbucket location." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:159 +msgid "CRUD (create, read, update, delete) operations" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:161 +msgid "CRUD operations can be:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:163 +msgid "executed in a stored procedure inside a storage, or" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:164 +msgid "initialized by the application." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:166 +msgid "In any case, the application must include the operation bucket id in a request. When executing an INSERT request, the operation bucket id is stored in a newly created tuple. In other cases, it is checked if the specified operation bucket id matches the bucket id of a tuple being modified." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:172 +msgid "SELECT requests" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:174 +msgid "Since a storage is not aware of the mapping between a bucket id and a primary key, all the SELECT requests executed in stored procedures inside a storage are only executed locally. Those SELECT requests that were initialized by the application are forwarded to a router. Then, if the application has passed a bucket id, a router uses it for shard calculation." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:181 +msgid "Calling stored procedures" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:183 +msgid "There are several ways of calling stored procedures in cluster replica sets. Stored procedures can be called:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:186 +msgid "on a specific vbucket located in a replica set (in this case, it is necessary to differentiate between read and write procedures, as write procedures are not applicable to vbuckets that are being migrated), or" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:189 +msgid "without specifying any particular vbucket." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:191 +msgid "All the routing validity checks performed for sharded DML operations hold true for vbucket-bound stored procedures as well." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:197 +msgid "Rebalancer" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:199 +msgid "**Rebalancer** is a background rebalancing process that ensures an even distribution of buckets across the shards. During rebalancing, buckets are being migrated among replica sets." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:203 +msgid "The rebalancer \"wakes up\" periodically and redistributes data from the most loaded nodes to less loaded nodes. Rebalancing starts if the **replicaset disbalance** of a replica set exceeds a disbalance threshold specified in the configuration." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:207 +msgid "The replicaset disbalance is calculated as follows:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:209 +msgid "|etalon_bucket_number - real_bucket_number| / etalon_bucket_number * 100" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:216 +msgid "Migration of buckets" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:218 +msgid "A replica set from which the bucket is being migrated is called a **source** ; a target replica set to which the bucket is being migrated is called a **destination**." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:221 +msgid "A **replica set lock** makes a replica set invisible to the rebalancer. A locked replica set can neither receive new buckets nor migrate its own buckets." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:224 +msgid "While a bucket is being migrated, it can have different states:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:226 +msgid "ACTIVE – the bucket is available for read and write requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:227 +msgid "PINNED – the bucket is locked for migrating to another replica set. Otherwise pinned buckets are similar to buckets in the ACTIVE state." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:229 +msgid "SENDING – the bucket is currently being copied to the destination replica set; read requests to the source replica set are still processed." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:231 +msgid "RECEIVING – the bucket is currently being filled; all requests to it are rejected." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:232 +msgid "SENT – the bucket was migrated to the destination replica set. The `router` uses the SENT state to calculate the new location of the bucket. A bucket in the SENT state goes to the GARBAGE state automatically after BUCKET_SENT_GARBAGE_DELAY seconds, which by default is :ref:`0.5 seconds `." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:236 +msgid "GARBAGE – the bucket was already migrated to the destination replica set during rebalancing; or the bucket was initially in the RECEIVING state, but some error occurred during the migration." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:240 +msgid "Buckets in the GARBAGE state are deleted by the garbage collector." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:245 +msgid "Migration is performed as follows:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:247 +msgid "At the destination replica set, a new bucket is created and assigned the RECEIVING state, the data copying starts, and the bucket rejects all requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:249 +msgid "The source bucket in the source replica set is assigned the SENDING state, and the bucket continues to process read requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:251 +msgid "Once the data is copied, the bucket on the source replica set is assigned the SENT and it starts rejecting all requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:253 +msgid "The bucket on the destination replica set is assigned the ACTIVE state and starts accepting all requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:258 +msgid "There is a specific error ``vshard.error.code.TRANSFER_IS_IN_PROGRESS`` that returns in case a request tries to perform an action not applicable to a bucket which is being relocated. You need to retry the request in this case." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:265 +msgid "The _bucket system space" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:267 +msgid "The ``_bucket`` system space of each replica set stores the ids of buckets present in the replica set. The space contains the following fields:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:270 +msgid "``bucket`` – bucket id" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:271 +msgid "``status`` – state of the bucket" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:272 +msgid "``destination`` – UUID of the destination replica set" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:274 +msgid "An example of ``_bucket.select{}``:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:276 +msgid "---\n" +"- - [1, ACTIVE, abfe2ef6-9d11-4756-b668-7f5bc5108e2a]\n" +" - [2, SENT, 19f83dcb-9a01-45bc-a0cf-b0c5060ff82c]\n" +"..." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:283 +msgid "Once the bucket is migrated, the destination replica set identified by UUID is filled in the table. While the bucket is still located on the source replica set, the value of the destination replica set UUID is equal to ``NULL``." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:290 +msgid "The routing table" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:292 +msgid "А routing table on the ``router`` stores the map of all bucket ids to replica sets. It ensures the consistency of sharding in case of failover." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:295 +msgid "The ``router`` keeps a persistent pool of connections to all the storages that are created at startup. This helps prevent configuration errors. Once the connection pool is created, the ``router`` caches the current state of the routing table in order to speed up routing. If a bucket migrated to another ``storage`` after rebalancing, or a failover occurred and caused one of the shards switching to another replica, the ``discovery fiber`` on the ``router`` updates the routing table automatically." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:302 +msgid "As the bucket id is explicitly indicated both in the data and in the mapping table on the ``router``, the data is consistent regardless of the application logic. It also makes rebalancing transparent for the application." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:309 +msgid "Processing requests" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:311 +msgid "Requests to the database can be performed by the application or using stored procedures. Either way, the bucket id should be explicitly specified in the request." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:314 +msgid "All requests are forwarded to the ``router`` first. The only operation supported by the ``router`` is ``call``. The operation is performed via the ``vshard.router.call()`` function:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:318 +msgid "result = vshard.router.call(, , , {}, {})" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:322 +msgid "Requests are processed as follows:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:324 +msgid "The ``router`` uses the bucket id to search for a replica set with the corresponding bucket in the routing table." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:327 +msgid "If the map of the bucket id to the replica set is not known to the ``router`` (the discovery fiber hasn’t filled the table yet), the ``router`` makes requests to all ``storages`` to find out where the bucket is located." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:330 +msgid "Once the bucket is located, the shard checks:" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:332 +msgid "whether the bucket is stored in the ``_bucket`` system space of the replica set;" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:333 +msgid "whether the bucket is ACTIVE or PINNED (for a read request, it can also be SENDING)." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:335 +msgid "If all the checks succeed, the request is executed. Otherwise, it is terminated with the error: ``“wrong bucket”``." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:341 +msgid "Glossary" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:346 +msgid "**Vertical scaling**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:348 +msgid "Adding more power to a single server: using a more powerful CPU, adding more capacity to RAM, adding more storage space, etc." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:352 +msgid "**Horizontal scaling**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:354 +msgid "Adding more servers to the pool of resources, then partitioning and distributing a dataset across the servers." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:358 +msgid "**Sharding**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:360 +msgid "A database architecture that allows partitioning a dataset using a sharding key and distributing a dataset across multiple servers. Sharding is a special case of horizontal scaling." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:365 +msgid "**Node**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:367 +msgid "A virtual or physical server instance." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:370 +msgid "**Cluster**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:372 +msgid "A set of nodes that make up a single group." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:375 +msgid "**Storage**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:377 +msgid "A node storing a subset of a dataset." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:380 +msgid "**Replica set**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:382 +msgid "A set of storage nodes storing copies of a dataset. Each storage in a replica set has a role, master or replica." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:386 +msgid "**Master**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:388 +msgid "A storage in a replica set processing read and write requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:391 +msgid "**Replica**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:393 +msgid "A storage in a replica set processing only read requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:396 +msgid "**Read requests**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:398 +msgid "Read-only requests, that is, select requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:401 +msgid "**Write requests**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:403 +msgid "Data-change operations, that is create, read, update, delete requests." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:406 +msgid "**Buckets (virtual buckets)**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:408 +msgid "The abstract virtual nodes into which the dataset is partitioned by the sharding key (bucket id)." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:412 +msgid "**Bucket id**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:414 +msgid "A sharding key defining which bucket belongs to which replica set. A bucket id may be calculated from a :ref:`hash key `." +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:418 +msgid "**Router**" +msgstr "" + +#: ../../doc/concepts/sharding/vshard_architecture.rst:420 +msgid "A proxy server responsible for routing requests from an application to nodes in a cluster." +msgstr "" diff --git a/locale/en/platform/triggers.pot b/locale/en/platform/triggers.pot new file mode 100644 index 0000000000..1899e15de0 --- /dev/null +++ b/locale/en/platform/triggers.pot @@ -0,0 +1,141 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/concepts/triggers.rst:7 +msgid "Triggers" +msgstr "" + +#: ../../doc/concepts/triggers.rst:9 +msgid "**Triggers**, also known as **callbacks**, are functions which the server executes when certain events happen." +msgstr "" + +#: ../../doc/concepts/triggers.rst:12 +msgid "To associate an event with a callback, pass the callback to the corresponding :samp:`on_{event}` function:" +msgstr "" + +#: ../../doc/concepts/triggers.rst:15 +msgid ":doc:`/reference/reference_lua/box_session/on_connect` or :doc:`/reference/reference_lua/box_session/on_disconnect`," +msgstr "" + +#: ../../doc/concepts/triggers.rst:17 +msgid ":doc:`/reference/reference_lua/box_session/on_auth`," +msgstr "" + +#: ../../doc/concepts/triggers.rst:18 +msgid ":doc:`/reference/reference_lua/box_space/on_replace` or :doc:`/reference/reference_lua/box_space/before_replace`," +msgstr "" + +#: ../../doc/concepts/triggers.rst:20 +msgid ":doc:`/reference/reference_lua/box_txn_management/on_commit` or :doc:`/reference/reference_lua/box_txn_management/on_rollback`," +msgstr "" + +#: ../../doc/concepts/triggers.rst:22 +msgid ":ref:`net.box.on_connect() ` or :ref:`net.box.on_disconnect() `," +msgstr "" + +#: ../../doc/concepts/triggers.rst:24 +msgid ":ref:`net.box.on_schema_reload() `," +msgstr "" + +#: ../../doc/concepts/triggers.rst:25 +msgid ":doc:`/reference/reference_lua/box_ctl/on_schema_init` or :doc:`/reference/reference_lua/box_ctl/on_shutdown`," +msgstr "" + +#: ../../doc/concepts/triggers.rst:27 +msgid ":ref:`swim_object:on_member_event() `," +msgstr "" + +#: ../../doc/concepts/triggers.rst:28 +msgid ":doc:`/reference/reference_lua/box_session/on_access_denied`." +msgstr "" + +#: ../../doc/concepts/triggers.rst:30 +msgid "Then the server will store the callback function and call it when the corresponding event happens." +msgstr "" + +#: ../../doc/concepts/triggers.rst:33 +msgid "All triggers have the following characteristics:" +msgstr "" + +#: ../../doc/concepts/triggers.rst:35 +msgid "Triggers are defined only by the :ref:`'admin' user `." +msgstr "" + +#: ../../doc/concepts/triggers.rst:37 +msgid "Triggers are stored in the Tarantool instance's memory, not in the database. Therefore triggers disappear when the instance is shut down. To make them permanent, put function definitions and trigger settings into Tarantool's :ref:`initialization script `." +msgstr "" + +#: ../../doc/concepts/triggers.rst:42 +msgid "Triggers have low overhead. If a trigger is not defined, then the overhead is minimal: merely a pointer dereference and check. If a trigger is defined, then its overhead is equivalent to the overhead of calling a function." +msgstr "" + +#: ../../doc/concepts/triggers.rst:46 +msgid "There can be multiple triggers for one event. In this case, triggers are executed in the reverse order that they were defined in." +msgstr "" + +#: ../../doc/concepts/triggers.rst:49 +msgid "Triggers must work within the event context, that is, operate variables passed as the trigger function arguments. Triggers should not affect the global state of the program or change things unrelated to the event. If a trigger performs such calls as, for example, `os.exit() `_ or :doc:`/reference/reference_lua/box_txn_management/rollback`, the result of its execution is undefined." +msgstr "" + +#: ../../doc/concepts/triggers.rst:56 +msgid "Triggers are replaceable. The request to \"redefine a trigger\" implies passing a new trigger function and an old trigger function to one of the :samp:`on_{event}` functions." +msgstr "" + +#: ../../doc/concepts/triggers.rst:60 +msgid "The :samp:`on_{event}` functions all have parameters which are function pointers, and they all return function pointers. Remember that a Lua function definition such as ``function f() x = x + 1 end`` is the same as ``f = function () x = x + 1 end`` - in both cases ``f`` gets a function pointer. And ``trigger = box.session.on_connect(f)`` is the same as ``trigger = box.session.on_connect(function () x = x + 1 end)`` - in both cases ``trigger`` gets the function pointer which was passed." +msgstr "" + +#: ../../doc/concepts/triggers.rst:68 +msgid "You can call any :samp:`on_{event}` function with no arguments to get a list of its triggers. For example, use ``box.session.on_connect()`` to return a table of all connect-trigger functions." +msgstr "" + +#: ../../doc/concepts/triggers.rst:72 +msgid "Triggers can be useful in solving problems with replication. See details in :ref:`Resolving replication conflicts `." +msgstr "" + +#: ../../doc/concepts/triggers.rst:75 +msgid "**Example:**" +msgstr "" + +#: ../../doc/concepts/triggers.rst:77 +msgid "Here we log connect and disconnect events into Tarantool server log." +msgstr "" + +#: ../../doc/concepts/triggers.rst:79 +msgid "log = require('log')\n" +"\n" +"function on_connect_impl()\n" +" log.info(\"connected \"..box.session.peer()..\", sid \"..box.session.id())\n" +"end\n" +"\n" +"function on_disconnect_impl()\n" +" log.info(\"disconnected, sid \"..box.session.id())\n" +"end\n" +"\n" +"function on_auth_impl(user)\n" +" log.info(\"authenticated sid \"..box.session.id()..\" as \"..user)\n" +"end\n" +"\n" +"function on_connect() pcall(on_connect_impl) end\n" +"function on_disconnect() pcall(on_disconnect_impl) end\n" +"function on_auth(user) pcall(on_auth_impl, user) end\n" +"\n" +"box.session.on_connect(on_connect)\n" +"box.session.on_disconnect(on_disconnect)\n" +"box.session.on_auth(on_auth)" +msgstr "" diff --git a/locale/en/reference/configuration/configuration_reference.pot b/locale/en/reference/configuration/configuration_reference.pot new file mode 100644 index 0000000000..4cf885d52f --- /dev/null +++ b/locale/en/reference/configuration/configuration_reference.pot @@ -0,0 +1,1611 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-26 10:36+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/configuration/configuration_reference.rst:4 +msgid "Configuration reference" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:9 +msgid "This topic describes all :ref:`configuration parameters ` provided by Tarantool." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:11 +msgid "Most of the configuration options described in this reference can be applied to a specific instance, replica set, group, or to all instances globally. To do so, you need to define the required option at the :ref:`specified level `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:18 +msgid "config" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:20 +msgid "The ``config`` section defines various parameters related to centralized configuration." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:24 +msgid "``config`` can be defined in the global :ref:`scope ` only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:26 +msgid ":ref:`config.reload `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:27 +msgid ":ref:`config.etcd.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:33 +#: ../../doc/reference/configuration/configuration_reference.rst:80 +#: ../../doc/reference/configuration/configuration_reference.rst:96 +#: ../../doc/reference/configuration/configuration_reference.rst:113 +#: ../../doc/reference/configuration/configuration_reference.rst:126 +#: ../../doc/reference/configuration/configuration_reference.rst:140 +#: ../../doc/reference/configuration/configuration_reference.rst:154 +#: ../../doc/reference/configuration/configuration_reference.rst:168 +#: ../../doc/reference/configuration/configuration_reference.rst:182 +#: ../../doc/reference/configuration/configuration_reference.rst:196 +#: ../../doc/reference/configuration/configuration_reference.rst:210 +#: ../../doc/reference/configuration/configuration_reference.rst:223 +msgid "**Since:** :doc:`3.0.0 `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:35 +msgid "Specify how the configuration is reloaded. This option accepts the following values:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:38 +msgid "``auto``: configuration is reloaded automatically when it is changed." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:39 +msgid "``manual``: configuration should be reloaded manually. In this case, you can reload the configuration in the application code using :ref:`config:reload() `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:41 +msgid "See also: :ref:`Reloading configuration `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:44 +#: ../../doc/reference/configuration/configuration_reference.rst:105 +#: ../../doc/reference/configuration/configuration_reference.rst:118 +#: ../../doc/reference/configuration/configuration_reference.rst:131 +#: ../../doc/reference/configuration/configuration_reference.rst:145 +#: ../../doc/reference/configuration/configuration_reference.rst:159 +#: ../../doc/reference/configuration/configuration_reference.rst:173 +#: ../../doc/reference/configuration/configuration_reference.rst:228 +#: ../../doc/reference/configuration/configuration_reference.rst:407 +#: ../../doc/reference/configuration/configuration_reference.rst:435 +#: ../../doc/reference/configuration/configuration_reference.rst:452 +#: ../../doc/reference/configuration/configuration_reference.rst:464 +#: ../../doc/reference/configuration/configuration_reference.rst:559 +#: ../../doc/reference/configuration/configuration_reference.rst:629 +#: ../../doc/reference/configuration/configuration_reference.rst:640 +#: ../../doc/reference/configuration/configuration_reference.rst:652 +#: ../../doc/reference/configuration/configuration_reference.rst:788 +#: ../../doc/reference/configuration/configuration_reference.rst:797 +#: ../../doc/reference/configuration/configuration_reference.rst:806 +#: ../../doc/reference/configuration/configuration_reference.rst:815 +#: ../../doc/reference/configuration/configuration_reference.rst:824 +#: ../../doc/reference/configuration/configuration_reference.rst:833 +#: ../../doc/reference/configuration/configuration_reference.rst:842 +#: ../../doc/reference/configuration/configuration_reference.rst:1052 +#: ../../doc/reference/configuration/configuration_reference.rst:1095 +#: ../../doc/reference/configuration/configuration_reference.rst:1151 +#: ../../doc/reference/configuration/configuration_reference.rst:1214 +msgid "Type: string" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:45 +msgid "Possible values: 'auto', 'manual'" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:46 +msgid "Default: 'auto'" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:47 +msgid "Environment variable: TT_CONFIG_RELOAD" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:54 +msgid "config.etcd.*" +msgstr "" + +#: ../../doc/concepts/configuration/configuration_etcd.rst:3 +msgid "Enterprise Edition" +msgstr "" + +#: ../../doc/concepts/configuration/configuration_etcd.rst:6 +msgid "Storing configuration in etcd is supported by the `Enterprise Edition `_ only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:60 +msgid "This section describes options related to :ref:`storing configuration in etcd `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:62 +msgid ":ref:`config.etcd.endpoints `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:63 +msgid ":ref:`config.etcd.prefix `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:64 +msgid ":ref:`config.etcd.username `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:65 +msgid ":ref:`config.etcd.password `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:66 +msgid ":ref:`config.etcd.ssl.ca_file `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:67 +msgid ":ref:`config.etcd.ssl.ca_path `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:68 +msgid ":ref:`config.etcd.ssl.ssl_key `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:69 +msgid ":ref:`config.etcd.ssl.verify_host `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:70 +msgid ":ref:`config.etcd.ssl.verify_peer `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:71 +msgid ":ref:`config.etcd.http.request.timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:72 +msgid ":ref:`config.etcd.http.request.unix_socket `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:82 +msgid "The list of endpoints used to access an etcd server." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:84 +#: ../../doc/reference/configuration/configuration_reference.rst:102 +msgid "See also: :ref:`Local etcd configuration `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:87 +#: ../../doc/reference/configuration/configuration_reference.rst:698 +#: ../../doc/reference/configuration/configuration_reference.rst:1241 +msgid "Type: array" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:88 +#: ../../doc/reference/configuration/configuration_reference.rst:106 +#: ../../doc/reference/configuration/configuration_reference.rst:119 +#: ../../doc/reference/configuration/configuration_reference.rst:132 +#: ../../doc/reference/configuration/configuration_reference.rst:146 +#: ../../doc/reference/configuration/configuration_reference.rst:160 +#: ../../doc/reference/configuration/configuration_reference.rst:174 +#: ../../doc/reference/configuration/configuration_reference.rst:188 +#: ../../doc/reference/configuration/configuration_reference.rst:202 +#: ../../doc/reference/configuration/configuration_reference.rst:216 +#: ../../doc/reference/configuration/configuration_reference.rst:229 +#: ../../doc/reference/configuration/configuration_reference.rst:257 +#: ../../doc/reference/configuration/configuration_reference.rst:266 +#: ../../doc/reference/configuration/configuration_reference.rst:630 +#: ../../doc/reference/configuration/configuration_reference.rst:641 +#: ../../doc/reference/configuration/configuration_reference.rst:653 +#: ../../doc/reference/configuration/configuration_reference.rst:699 +#: ../../doc/reference/configuration/configuration_reference.rst:789 +#: ../../doc/reference/configuration/configuration_reference.rst:798 +#: ../../doc/reference/configuration/configuration_reference.rst:807 +#: ../../doc/reference/configuration/configuration_reference.rst:816 +#: ../../doc/reference/configuration/configuration_reference.rst:825 +#: ../../doc/reference/configuration/configuration_reference.rst:834 +#: ../../doc/reference/configuration/configuration_reference.rst:843 +msgid "Default: nil" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:89 +msgid "Environment variable: TT_CONFIG_ETCD_ENDPOINTS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:98 +msgid "A key prefix used to search a configuration on an etcd server. Tarantool searches keys by the following path: ``/config/*``. Note that ```` should start with a slash (``/``)." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:107 +msgid "Environment variable: TT_CONFIG_ETCD_PREFIX" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:115 +msgid "A username used for authentication." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:120 +msgid "Environment variable: TT_CONFIG_ETCD_USERNAME" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:128 +msgid "A password used for authentication." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:133 +msgid "Environment variable: TT_CONFIG_ETCD_PASSWORD" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:142 +msgid "A path to a trusted certificate authorities (CA) file." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:147 +msgid "Environment variable: TT_CONFIG_ETCD_SSL_CA_FILE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:156 +msgid "A path to a directory holding certificates to verify the peer with." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:161 +msgid "Environment variable: TT_CONFIG_ETCD_SSL_CA_PATH" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:170 +msgid "A path to a private SSL key file." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:175 +msgid "Environment variable: TT_CONFIG_ETCD_SSL_SSL_KEY" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:184 +msgid "Enable verification of the certificate's name (CN) against the specified host." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:187 +#: ../../doc/reference/configuration/configuration_reference.rst:201 +#: ../../doc/reference/configuration/configuration_reference.rst:376 +#: ../../doc/reference/configuration/configuration_reference.rst:491 +#: ../../doc/reference/configuration/configuration_reference.rst:1027 +#: ../../doc/reference/configuration/configuration_reference.rst:1259 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:189 +msgid "Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_HOST" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:198 +msgid "Enable verification of the peer's SSL certificate." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:203 +msgid "Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_PEER" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:212 +msgid "A time period required to process an HTTP request to an etcd server: from sending a request to receiving a response." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:215 +#: ../../doc/reference/configuration/configuration_reference.rst:479 +#: ../../doc/reference/configuration/configuration_reference.rst:1070 +#: ../../doc/reference/configuration/configuration_reference.rst:1120 +#: ../../doc/reference/configuration/configuration_reference.rst:1277 +#: ../../doc/reference/configuration/configuration_reference.rst:1292 +#: ../../doc/reference/configuration/configuration_reference.rst:1336 +#: ../../doc/reference/configuration/configuration_reference.rst:1369 +msgid "Type: number" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:217 +msgid "Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:225 +msgid "A Unix domain socket used to connect to an etcd server." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:230 +msgid "Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_UNIX_SOCKET" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:238 +msgid "credentials" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:244 +msgid "``credentials`` can be defined in any :ref:`scope `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:247 +msgid ":ref:`credentials.roles.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:248 +msgid ":ref:`credentials.users.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:249 +msgid ":ref:`.privileges.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:256 +#: ../../doc/reference/configuration/configuration_reference.rst:265 +#: ../../doc/reference/configuration/configuration_reference.rst:584 +#: ../../doc/reference/configuration/configuration_reference.rst:609 +msgid "Type: map" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:258 +msgid "Environment variable: TT_CREDENTIALS_ROLES" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:267 +msgid "Environment variable: TT_CREDENTIALS_USERS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:274 +msgid "credentials.roles.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:285 +#: ../../doc/reference/configuration/configuration_reference.rst:308 +msgid "See :ref:`privileges `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:291 +msgid "credentials.users.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:314 +msgid ".privileges.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:356 +msgid "database" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:358 +msgid "The ``database`` section defines database-specific configuration parameters, such as an instance's read-write mode or transaction isolation level." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:362 +msgid "``database`` can be defined in any :ref:`scope `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:364 +msgid ":ref:`database.hot_standby `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:365 +msgid ":ref:`database.instance_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:366 +msgid ":ref:`database.mode `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:367 +msgid ":ref:`database.replicaset_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:368 +msgid ":ref:`database.txn_isolation `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:369 +msgid ":ref:`database.txn_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:370 +msgid ":ref:`database.use_mvcc_engine `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:377 +#: ../../doc/reference/configuration/configuration_reference.rst:492 +#: ../../doc/reference/configuration/configuration_reference.rst:1260 +msgid "Default: false" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:378 +msgid "Environment variable: TT_DATABASE_HOT_STANDBY" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:385 +msgid "An :ref:`instance UUID `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:387 +msgid "By default, instance UUIDs are generated automatically. ``database.instance_uuid`` can be used to specify an instance identifier manually." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:390 +msgid "UUIDs should follow these rules:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:392 +msgid "The values must be true unique identifiers, not shared by other instances or replica sets within the common infrastructure." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:395 +msgid "The values must be used consistently, not changed after the initial setup. The initial values are stored in :ref:`snapshot files ` and are checked whenever the system is restarted." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:401 +msgid "The values must comply with `RFC 4122 `_. The `nil UUID `_ is not allowed." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:404 +msgid "See also: :ref:`database.replicaset_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:408 +#: ../../doc/reference/configuration/configuration_reference.rst:453 +#: ../../doc/reference/configuration/configuration_reference.rst:560 +#: ../../doc/reference/configuration/configuration_reference.rst:1242 +msgid "Default: :ref:`box.NULL `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:409 +msgid "Environment variable: TT_DATABASE_INSTANCE_UUID" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:416 +msgid "An instance's operating mode. This option is in effect if :ref:`replication.failover ` is set to ``off``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:419 +msgid "The following modes are available:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:421 +msgid "``rw``: an instance is in read-write mode." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:422 +msgid "``ro``: an instance is in read-only mode." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:424 +msgid "If not specified explicitly, the default value depends on the number of instances in a replica set. For a single instance, the ``rw`` mode is used, while for multiple instances, the ``ro`` mode is used." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:426 +#: ../../doc/reference/configuration/configuration_reference.rst:571 +#: ../../doc/reference/configuration/configuration_reference.rst:595 +#: ../../doc/reference/configuration/configuration_reference.rst:685 +#: ../../doc/reference/configuration/configuration_reference.rst:919 +#: ../../doc/reference/configuration/configuration_reference.rst:935 +#: ../../doc/reference/configuration/configuration_reference.rst:1200 +#: ../../doc/reference/configuration/configuration_reference.rst:1228 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:428 +msgid "You can set the ``database.mode`` option to ``rw`` on all instances in a replica set to make a :ref:`master-master ` configuration. In this case, ``replication.failover`` should be set to ``off``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:431 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: off\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" database:\n" +" mode: rw\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +"\n" +"# Load sample data\n" +"app:\n" +" file: 'myapp.lua'" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:436 +msgid "Default: :ref:`box.NULL ` (the actual default value depends on the number of instances in a replica set)" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:437 +msgid "Environment variable: TT_DATABASE_MODE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:444 +msgid "A :ref:`replica set UUID `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:446 +msgid "By default, replica set UUIDs are generated automatically. ``database.replicaset_uuid`` can be used to specify a replica set identifier manually." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:449 +msgid "See also: :ref:`database.instance_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:454 +msgid "Environment variable: TT_DATABASE_REPLICASET_UUID" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:461 +msgid "A transaction :ref:`isolation level `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:465 +msgid "Default: ``best-effort``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:466 +msgid "Possible values: ``best-effort``, ``read-committed``, ``read-confirmed``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:467 +msgid "Environment variable: TT_DATABASE_TXN_ISOLATION" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:474 +msgid "A timeout (in seconds) after which the transaction is rolled back." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:476 +msgid "See also: :ref:`box.begin() `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:480 +msgid "Default: 3153600000 (~100 years)" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:481 +msgid "Environment variable: TT_DATABASE_TXN_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:488 +msgid "Whether the :ref:`transactional manager ` is enabled." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:493 +msgid "Environment variable: TT_DATABASE_USE_MVCC_ENGINE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:502 +msgid "iproto" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:504 +msgid "The ``iproto`` section is used to configure parameters related to communicating to and between cluster instances." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:508 +msgid "``iproto`` can be defined in any :ref:`scope `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:511 +msgid ":ref:`iproto.advertise.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:513 +msgid ":ref:`iproto.advertise.client `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:514 +msgid ":ref:`iproto.advertise.peer `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:515 +msgid ":ref:`iproto.advertise.sharding `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:516 +msgid ":ref:`iproto.advertise.\\.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:518 +msgid ":ref:`iproto.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:520 +msgid ":ref:`iproto.listen `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:521 +msgid ":ref:`iproto.net_msg_max `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:522 +msgid ":ref:`iproto.readahead `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:523 +msgid ":ref:`iproto.threads `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:525 +msgid ":ref:`.params.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:532 +msgid "iproto.advertise.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:539 +msgid "An URI used to advertise the current instance to clients." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:541 +msgid "The ``iproto.advertise.client`` option accepts an URI in the following formats:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:543 +msgid "An address: ``host:port``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:545 +msgid "A Unix domain socket: ``unix/:``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:547 +msgid "Note that this option doesn't allow to set a username and password. If a remote client needs this information, it should be delivered outside of the cluster configuration." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:554 +#: ../../doc/reference/configuration/configuration_reference.rst:5 +msgid "The host value cannot be ``0.0.0.0``/``[::]`` and the port value cannot be ``0``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:561 +msgid "Environment variable: TT_IPROTO_ADVERTISE_CLIENT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:567 +msgid "An URI used to advertise the current instance to other cluster members." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:569 +msgid "The ``iproto.advertise.peer`` option accepts an URI in the format described in :ref:`iproto_advertise.\\.* `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:573 +#: ../../doc/reference/configuration/configuration_reference.rst:597 +#: ../../doc/reference/configuration/configuration_reference.rst:1202 +#: ../../doc/reference/configuration/configuration_reference.rst:1230 +msgid "In the example below, the following configuration options are specified:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:575 +#: ../../doc/reference/configuration/configuration_reference.rst:1204 +#: ../../doc/reference/configuration/configuration_reference.rst:1232 +msgid "In the :ref:`credentials ` section, the ``replicator`` user with the ``replication`` role is created." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:576 +msgid "``iproto.advertise.peer`` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` using the ``replicator`` user." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:578 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: election\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:585 +#: ../../doc/reference/configuration/configuration_reference.rst:610 +msgid "Environment variable: see :ref:`iproto.advertise.\\.* `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:591 +msgid "An advertise URI used by a router and rebalancer." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:593 +msgid "The ``iproto.advertise.sharding`` option accepts an URI in the format described in :ref:`iproto_advertise.\\.* `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:599 +msgid "In the :ref:`credentials ` section, the ``replicator`` and ``storage`` users are created." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:600 +msgid "``iproto.advertise.peer`` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` with the ``replicator`` user." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:601 +msgid "``iproto.advertise.sharding`` specifies that a router should connect to storages using an address defined in :ref:`iproto.listen ` with the ``storage`` user." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:603 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +" storage:\n" +" password: 'secret'\n" +" roles: [sharding]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +" sharding:\n" +" login: storage\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:616 +msgid "iproto.advertise..*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:622 +msgid "An URI used to advertise the current instance." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:631 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_URI, TT_IPROTO_ADVERTISE_SHARDING_URI" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:637 +msgid "A username that should be used to connect to the current instance." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:642 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_LOGIN, TT_IPROTO_ADVERTISE_SHARDING_LOGIN" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:648 +msgid "A password for the specified user. If a password is missing, it is taken from :ref:`credentials ` for the specified username." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:654 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PASSWORD" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:660 +msgid "Additional parameters required for connecting to the current instance. These parameters are described in :ref:`.params.* `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:668 +msgid "iproto.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:674 +msgid "An array of URIs used to listen for incoming requests. If required, you can enable SSL for specific URIs by providing additional parameters (:ref:`.params.* `)." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:677 +msgid "These URIs are used for different purposes, for example:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:679 +msgid "Communicating between replica set peers or cluster members." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:680 +msgid "Remote administration using :ref:`tt connect `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:681 +msgid "Connecting to an instance using :ref:`connectors ` for different languages." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:683 +msgid "To grant the specified privileges for connecting to an instance, use the :ref:`credentials ` configuration section." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:687 +msgid "In the example below, ``iproto.listen`` is set explicitly for each instance in a cluster:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:689 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:695 +msgid "See also: :ref:`Connection settings `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:700 +msgid "Environment variable: TT_IPROTO_LISTEN" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:707 +msgid "To handle messages, Tarantool allocates :ref:`fibers `. To prevent fiber overhead from affecting the whole system, Tarantool restricts how many messages the fibers handle, so that some pending requests are blocked." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:712 +msgid "On powerful systems, increase ``net_msg_max``, and the scheduler starts processing pending requests immediately." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:715 +msgid "On weaker systems, decrease ``net_msg_max``, and the overhead may decrease. Although this may take some time because the scheduler must wait until already-running requests finish." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:719 +msgid "When ``net_msg_max`` is reached, Tarantool suspends processing of incoming packages until it has processed earlier messages. This is not a direct restriction of the number of fibers that handle network messages, rather it is a system-wide restriction of channel bandwidth. This in turn restricts the number of incoming network messages that the :ref:`transaction processor thread ` handles, and therefore indirectly affects the fibers that handle network messages." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:732 +msgid "The number of fibers is smaller than the number of messages because messages can be released as soon as they are delivered, while incoming requests might not be processed until some time after delivery." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:736 +#: ../../doc/reference/configuration/configuration_reference.rst:755 +#: ../../doc/reference/configuration/configuration_reference.rst:773 +#: ../../doc/reference/configuration/configuration_reference.rst:1352 +msgid "Type: integer" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:737 +msgid "Default: 768" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:738 +msgid "Environment variable: TT_IPROTO_NET_MSG_MAX" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:745 +msgid "The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes, and the more requests can be read from the operating system buffer in a single system call." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:750 +msgid "The recommendation is to make sure that the buffer can contain at least a few dozen requests. Therefore, if a typical tuple in a request is large, e.g. a few kilobytes or even megabytes, the read-ahead buffer size should be increased. If batched request processing is not used, it’s prudent to leave this setting at its default." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:756 +msgid "Default: 16320" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:757 +msgid "Environment variable: TT_IPROTO_READAHEAD" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:764 +msgid "The number of :ref:`network threads `. There can be unusual workloads where the network thread is 100% loaded and the transaction processor thread is not, so the network thread is a bottleneck. In that case, set ``iproto_threads`` to 2 or more. The operating system kernel determines which connection goes to which thread." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:774 +#: ../../doc/reference/configuration/configuration_reference.rst:1353 +#: ../../doc/reference/configuration/configuration_reference.rst:1370 +msgid "Default: 1" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:775 +msgid "Environment variable: TT_IPROTO_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:781 +msgid ".params.*" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:790 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_TRANSPORT, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_TRANSPORT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:799 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CA_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CA_FILE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:808 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CERT_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CERT_FILE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:817 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_CIPHERS, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_CIPHERS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:826 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_KEY_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_KEY_FILE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:835 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:844 +msgid "Environment variable: TT_IPROTO_ADVERTISE_PEER_PARAMS_SSL_PASSWORD_FILE, TT_IPROTO_ADVERTISE_SHARDING_PARAMS_SSL_PASSWORD_FILE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:853 +msgid "groups" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:855 +msgid "The ``groups`` section provides the ability to define the :ref:`full topology of a Tarantool cluster `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:859 +msgid "``groups`` can be defined in the global :ref:`scope ` only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:861 +msgid ":ref:`groups.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:862 +msgid ":ref:`groups.\\.replicasets `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:863 +msgid ":ref:`groups.\\.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:869 +msgid "A group name." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:876 +msgid "Replica sets that belong to this group. See :ref:`replicasets `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:883 +msgid "Any configuration parameter that can be defined in the group :ref:`scope `. For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the group level are applied to all instances in this group." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:891 +msgid "replicasets" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:895 +msgid "``replicasets`` can be defined in the group :ref:`scope ` only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:897 +msgid ":ref:`replicasets.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:898 +msgid ":ref:`replicasets.\\.leader `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:899 +msgid ":ref:`replicasets.\\.bootstrap_leader `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:900 +msgid ":ref:`replicasets.\\.instances `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:901 +msgid ":ref:`replicasets.\\.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:907 +msgid "A replica set name." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:914 +msgid "A replica set leader. This option can be used to set a replica set leader when ``manual`` :ref:`replication.failover ` is used." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:917 +msgid "To perform :ref:`controlled failover `, ``.leader`` can be temporarily removed or set to ``null``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:921 +msgid "replication:\n" +" failover: manual\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:932 +msgid "A bootstrap leader for a replica set. To specify a bootstrap leader manually, you need to set :ref:`replication.bootstrap_strategy ` to ``config``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:937 +msgid "groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" replication:\n" +" bootstrap_strategy: config\n" +" bootstrap_leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:948 +msgid "Instances that belong to this replica set. See :ref:`instances `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:955 +msgid "Any configuration parameter that can be defined in the replica set :ref:`scope `. For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the replica set level are applied to all instances in this replica set." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:963 +msgid "instances" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:967 +msgid "``instances`` can be defined in the replica set :ref:`scope ` only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:969 +msgid ":ref:`instances.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:970 +msgid ":ref:`instances.\\.\\ `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:976 +msgid "An instance name." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:983 +msgid "Any configuration parameter that can be defined in the instance :ref:`scope `. For example, :ref:`iproto ` and :ref:`database ` configuration parameters defined at the instance level are applied to this instance only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1002 +msgid "replication" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1004 +msgid "The ``replication`` section defines configuration parameters related to :ref:`replication `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1006 +msgid ":ref:`replication.anon `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1007 +msgid ":ref:`replication.bootstrap_strategy `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1008 +msgid ":ref:`replication.connect_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1009 +msgid ":ref:`replication.election_mode `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1010 +msgid ":ref:`replication.election_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1011 +msgid ":ref:`replication.election_fencing_mode `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1012 +msgid ":ref:`replication.failover `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1013 +msgid ":ref:`replication.peers `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1014 +msgid ":ref:`replication.skip_conflict `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1015 +msgid ":ref:`replication.sync_lag `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1016 +msgid ":ref:`replication.sync_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1017 +msgid ":ref:`replication.synchro_quorum `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1018 +msgid ":ref:`replication.synchro_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1019 +msgid ":ref:`replication.threads `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1020 +msgid ":ref:`replication.timeout `" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1028 +msgid "Default: ``false``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1029 +msgid "Environment variable: TT_REPLICATION_ANON" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1036 +msgid "Specifies a strategy used to bootstrap a :ref:`replica set `. The following strategies are available:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1039 +msgid "``auto``: a node doesn't boot if half or more of the other nodes in a replica set are not connected. For example, if a replica set contains 2 or 3 nodes, a node requires 2 connected instances. In the case of 4 or 5 nodes, at least 3 connected instances are required. Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1044 +msgid "``config``: use the specified node to bootstrap a replica set. To specify the bootstrap leader, use the :ref:`.bootstrap_leader ` option." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1047 +msgid "``supervised``: a bootstrap leader isn't chosen automatically but should be appointed using :ref:`box.ctl.make_bootstrap_leader() ` on the desired node." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1049 +msgid "``legacy`` (deprecated since :doc:`2.11.0 `): a node requires the :ref:`replication_connect_quorum ` number of other nodes to be connected. This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1053 +msgid "Default: ``auto``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1054 +msgid "Environment variable: TT_REPLICATION_BOOTSTRAP_STRATEGY" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1061 +msgid "A timeout (in seconds) a replica waits when trying to connect to a master in a cluster. See :ref:`orphan status ` for details." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1064 +msgid "This parameter is different from :ref:`replication.timeout `, which a master uses to disconnect a replica when the master receives no acknowledgments of heartbeat messages." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1071 +msgid "Default: 30" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1072 +msgid "Environment variable: TT_REPLICATION_CONNECT_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1079 +msgid "A role of a replica set node in the :ref:`leader election process `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1081 +msgid "The possible values are:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1083 +msgid "``off``: a node doesn't participate in the election activities." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1085 +msgid "``voter``: a node can participate in the election process but can't be a leader." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1087 +msgid "``candidate``: a node should be able to become a leader." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1089 +msgid "``manual``: allow to control which instance is the leader explicitly instead of relying on automated leader election. By default, the instance acts like a voter -- it is read-only and may vote for other candidate instances. Once :ref:`box.ctl.promote() ` is called, the instance becomes a candidate and starts a new election round. If the instance wins the elections, it becomes a leader but won't participate in any new elections." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1096 +msgid "Default: :ref:`box.NULL ` (the actual default value depends on :ref:`replication.failover `)" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1097 +msgid "Environment variable: TT_REPLICATION_ELECTION_MODE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1104 +msgid "Specifies the timeout (in seconds) between election rounds in the :ref:`leader election process ` if the previous round ended up with a split vote." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1108 +msgid "It is quite big, and for most of the cases, it can be lowered to 300-400 ms." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1111 +msgid "To avoid the split vote repeat, the timeout is randomized on each node during every new election, from 100% to 110% of the original timeout value. For example, if the timeout is 300 ms and there are 3 nodes started the election simultaneously in the same term, they can set their election timeouts to 300, 310, and 320 respectively, or to 305, 302, and 324, and so on. In that way, the votes will never be split because the election on different nodes won't be restarted simultaneously." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1121 +#: ../../doc/reference/configuration/configuration_reference.rst:1337 +msgid "Default: 5" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1122 +msgid "Environment variable: TT_REPLICATION_ELECTION_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1129 +msgid "Specifies the :ref:`leader fencing mode ` that affects the leader election process. When the parameter is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than :ref:`replication.synchro_quorum ` of alive connections to the cluster nodes. The resigning leader receives the status of a follower in the current election term and becomes read-only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1137 +msgid "In ``soft`` mode, a connection is considered dead if there are no responses for :ref:`4 * replication.timeout ` seconds both on the current leader and the followers." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1140 +msgid "In ``strict`` mode, a connection is considered dead if there are no responses for :ref:`2 * replication.timeout ` seconds on the current leader and :ref:`4 * replication.timeout ` seconds on the followers. This improves the chances that there is only one leader at any time." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1146 +msgid "Fencing applies to the instances that have the :ref:`replication.election_mode ` set to ``candidate`` or ``manual``. To turn off leader fencing, set ``election_fencing_mode`` to ``off``." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1152 +msgid "Default: ``soft``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1153 +msgid "Possible values: ``off``, ``soft``, ``strict``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1154 +msgid "Environment variable: TT_REPLICATION_ELECTION_FENCING_MODE" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1161 +msgid "A failover mode used to take over a master role when the current master instance fails. The following modes are available:" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1164 +msgid "``off``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1166 +msgid "Leadership in a replica set is controlled using the :ref:`database.mode ` option. In this case, you can set the ``database.mode`` option to ``rw`` on all instances in a replica set to make a :ref:`master-master ` configuration." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1169 +msgid "The default ``database.mode`` is determined as follows: ``rw`` if there is one instance in a replica set; ``ro`` if there are several instances." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1171 +msgid "``manual``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1173 +msgid "Leadership in a replica set is controlled using the :ref:`.leader ` option. In this case, a :ref:`master-master ` configuration is forbidden." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1176 +msgid "In the ``manual`` mode, the :ref:`database.mode ` option cannot be set explicitly. The leader is configured in the read-write mode, all the other instances are read-only." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1179 +msgid "``election``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1181 +msgid ":ref:`Automated leader election ` is used to control leadership in a replica set." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1183 +msgid "In the ``election`` mode, :ref:`database.mode ` and :ref:`.leader ` shouldn't be set explicitly." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1185 +msgid "``supervised`` (`Enterprise Edition `_ only)" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1187 +msgid "Leadership in a replica set is controlled using an external failover agent." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1189 +msgid "In the ``supervised`` mode, :ref:`database.mode ` and :ref:`.leader ` shouldn't be set explicitly." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1194 +msgid "See also: :ref:`Replication tutorials `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1198 +msgid "``replication.failover`` can be defined in the global, group, and replica set :ref:`scope `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1205 +msgid ":ref:`iproto.advertise.peer ` specifies that other instances should connect to an address defined in :ref:`iproto.listen ` using the ``replicator`` user." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1206 +msgid "``replication.failover`` specifies that a master instance should be set manually." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1207 +msgid ":ref:`.leader ` sets ``instance001`` as a replica set leader." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1209 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"iproto:\n" +" advertise:\n" +" peer:\n" +" login: replicator\n" +"\n" +"replication:\n" +" failover: manual\n" +"\n" +"groups:\n" +" group001:\n" +" replicasets:\n" +" replicaset001:\n" +" leader: instance001\n" +" instances:\n" +" instance001:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3301'\n" +" instance002:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3302'\n" +" instance003:\n" +" iproto:\n" +" listen:\n" +" - uri: '127.0.0.1:3303'\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1215 +msgid "Default: ``off``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1216 +msgid "Environment variable: TT_REPLICATION_FAILOVER" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1223 +msgid "URIs of instances that constitute a replica set. These URIs are used by an instance to connect to another instance as a replica." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1226 +msgid "Alternatively, you can use :ref:`iproto.advertise.peer ` to specify a URI used to advertise the current instance to other cluster members." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1233 +msgid "``replication.peers`` specifies URIs of replica set instances." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1235 +msgid "credentials:\n" +" users:\n" +" replicator:\n" +" password: 'topsecret'\n" +" roles: [replication]\n" +"\n" +"replication:\n" +" peers:\n" +" - replicator:topsecret@127.0.0.1:3301\n" +" - replicator:topsecret@127.0.0.1:3302\n" +" - replicator:topsecret@127.0.0.1:3303\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1243 +msgid "Environment variable: TT_REPLICATION_PEERS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1250 +msgid "By default, if a replica adds a unique key that another replica has added, replication :ref:`stops ` with the ``ER_TUPLE_FOUND`` :ref:`error `. If ``replication.skip_conflict`` is set to ``true``, such errors are ignored." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1257 +msgid "Instead of saving the broken transaction to the write-ahead log, it is written as ``NOP`` (No operation)." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1261 +msgid "Environment variable: TT_REPLICATION_SKIP_CONFLICT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1268 +msgid "The maximum delay (in seconds) between the time when data is written to the master and the time when it is written to a replica. If ``replication.sync_lag`` is set to ``nil`` or 365 * 100 * 86400 (``TIMEOUT_INFINITY``), a replica is always considered to be \"synced\"." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1274 +msgid "This parameter is ignored during bootstrap. See :ref:`orphan status ` for details." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1278 +msgid "Default: 10" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1279 +msgid "Environment variable: TT_REPLICATION_SYNC_LAG" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1286 +msgid "The timeout (in seconds) that a node waits when trying to sync with other nodes in a replica set after connecting or during a :ref:`configuration update `. This could fail indefinitely if :ref:`replication.sync_lag ` is smaller than network latency, or if the replica cannot keep pace with master updates. If ``replication.sync_timeout`` expires, the replica enters :ref:`orphan status `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1293 +msgid "Default: 0" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1294 +msgid "Environment variable: TT_REPLICATION_SYNC_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1301 +msgid "A number of replicas that should confirm the receipt of a :ref:`synchronous ` transaction before it can finish its commit." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1303 +msgid "This option supports dynamic evaluation of the quorum number. For example, the default value is ``N / 2 + 1`` where ``N`` is the current number of replicas registered in a cluster. Once any replicas are added or removed, the expression is re-evaluated automatically." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1307 +msgid "Note that the default value (``at least 50% of the cluster size + 1``) guarantees data reliability. Using a value less than the canonical one might lead to unexpected results, including a :ref:`split-brain `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1311 +msgid "``replication.synchro_quorum`` is not used on replicas. If the master fails, the pending synchronous transactions will be kept waiting on the replicas until a new master is elected." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1316 +msgid "``replication.synchro_quorum`` does not account for anonymous replicas." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1318 +msgid "Type: string, number" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1319 +msgid "Default: ``N / 2 + 1``" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1320 +msgid "Environment variable: TT_REPLICATION_SYNCHRO_QUORUM" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1327 +msgid "For :ref:`synchronous replication ` only. Specify how many seconds to wait for a synchronous transaction quorum replication until it is declared failed and is rolled back." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1331 +msgid "It is not used on replicas, so if the master fails, the pending synchronous transactions will be kept waiting on the replicas until a new master is elected." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1338 +msgid "Environment variable: TT_REPLICATION_SYNCHRO_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1345 +msgid "The number of threads spawned to decode the incoming replication data." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1347 +msgid "In most cases, one thread is enough for all incoming data. Possible values range from 1 to 1000. If there are multiple replication threads, connections to serve are distributed evenly between the threads." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1354 +msgid "Environment variable: TT_REPLICATION_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1361 +msgid "A time interval (in seconds) used by a master to send heartbeat requests to a replica when there are no updates to send to this replica. For each request, a replica should return a heartbeat acknowledgment." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1364 +msgid "If a master or replica gets no heartbeat message for ``4 * replication.timeout`` seconds, a connection is dropped and a replica tries to reconnect to the master." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1366 +msgid "See also: :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/configuration/configuration_reference.rst:1371 +msgid "Environment variable: TT_REPLICATION_TIMEOUT" +msgstr "" diff --git a/locale/en/reference/configuration/index.pot b/locale/en/reference/configuration/index.pot new file mode 100644 index 0000000000..46fd22fd2e --- /dev/null +++ b/locale/en/reference/configuration/index.pot @@ -0,0 +1,2617 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/configuration/index.rst:5 +msgid "Configuration reference (box.cfg)" +msgstr "" + +#: ../../doc/concepts/configuration/configuration_code.rst:5 +msgid "Starting with the 3.0 version, the recommended way of configuring Tarantool is using a :ref:`configuration file `. Configuring Tarantool in code is considered a legacy approach." +msgstr "" + +#: ../../doc/reference/configuration/index.rst:12 +msgid "This topic describes all configuration parameters that can be specified :ref:`in code ` using the ``box.cfg`` API." +msgstr "" + +#: ../../doc/reference/configuration/index.rst:20 +msgid "Basic parameters" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:1 +msgid ":ref:`background `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:2 +msgid ":ref:`custom_proc_title `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:3 +msgid ":ref:`listen `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:4 +msgid ":ref:`memtx_dir `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:5 +msgid ":ref:`pid_file `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:6 +msgid ":ref:`read_only `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:7 +msgid ":ref:`sql_cache_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:8 +msgid ":ref:`vinyl_dir `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:9 +msgid ":ref:`vinyl_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:10 +msgid ":ref:`username `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:11 +msgid ":ref:`wal_dir `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:12 +msgid ":ref:`work_dir `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:13 +msgid ":ref:`worker_pool_threads `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:14 +msgid ":ref:`strip_core `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:15 +msgid ":ref:`memtx_use_mvcc_engine `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:21 +msgid "Since version 1.6.2. Run the server as a background task. The :ref:`log ` and :ref:`pid_file ` parameters must be non-null for this to work." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:26 +#: ../../doc/reference/configuration/cfg_basic.rst:136 +#: ../../doc/reference/configuration/cfg_basic.rst:285 +#: ../../doc/reference/configuration/cfg_basic.rst:297 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:24 +#: ../../doc/reference/configuration/cfg_hot_standby.rst:48 +#: ../../doc/reference/configuration/cfg_replication.rst:203 +#: ../../doc/reference/configuration/cfg_replication.rst:296 +#: ../../doc/reference/configuration/cfg_logging.rst:151 +#: ../../doc/reference/configuration/cfg_feedback.rst:23 +#: ../../doc/reference/configuration/cfg_deprecated.rst:26 +#: ../../doc/reference/configuration/cfg_deprecated.rst:56 +#: ../../doc/reference/configuration/cfg_deprecated.rst:67 +#: ../../doc/reference/configuration/cfg_deprecated.rst:163 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:27 +#: ../../doc/reference/configuration/cfg_basic.rst:137 +#: ../../doc/reference/configuration/cfg_basic.rst:298 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:25 +#: ../../doc/reference/configuration/cfg_hot_standby.rst:49 +#: ../../doc/reference/configuration/cfg_replication.rst:204 +#: ../../doc/reference/configuration/cfg_replication.rst:297 +#: ../../doc/reference/configuration/cfg_deprecated.rst:27 +msgid "Default: false" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:28 +msgid "Environment variable: TT_BACKGROUND" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:29 +#: ../../doc/reference/configuration/cfg_basic.rst:107 +#: ../../doc/reference/configuration/cfg_basic.rst:120 +#: ../../doc/reference/configuration/cfg_basic.rst:185 +#: ../../doc/reference/configuration/cfg_basic.rst:215 +#: ../../doc/reference/configuration/cfg_basic.rst:231 +#: ../../doc/reference/configuration/cfg_basic.rst:258 +#: ../../doc/reference/configuration/cfg_basic.rst:288 +#: ../../doc/reference/configuration/cfg_basic.rst:300 +#: ../../doc/reference/configuration/cfg_storage.rst:64 +#: ../../doc/reference/configuration/cfg_storage.rst:100 +#: ../../doc/reference/configuration/cfg_storage.rst:121 +#: ../../doc/reference/configuration/cfg_storage.rst:137 +#: ../../doc/reference/configuration/cfg_storage.rst:164 +#: ../../doc/reference/configuration/cfg_storage.rst:189 +#: ../../doc/reference/configuration/cfg_storage.rst:215 +#: ../../doc/reference/configuration/cfg_storage.rst:230 +#: ../../doc/reference/configuration/cfg_storage.rst:244 +#: ../../doc/reference/configuration/cfg_storage.rst:257 +#: ../../doc/reference/configuration/cfg_storage.rst:270 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:27 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:41 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:79 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:93 +#: ../../doc/reference/configuration/cfg_hot_standby.rst:51 +#: ../../doc/reference/configuration/cfg_replication.rst:422 +#: ../../doc/reference/configuration/cfg_replication.rst:446 +#: ../../doc/reference/configuration/cfg_networking.rst:94 +#: ../../doc/reference/configuration/cfg_logging.rst:126 +#: ../../doc/reference/configuration/cfg_logging.rst:154 +#: ../../doc/reference/configuration/cfg_deprecated.rst:28 +#: ../../doc/reference/configuration/cfg_deprecated.rst:58 +#: ../../doc/reference/configuration/cfg_deprecated.rst:96 +msgid "Dynamic: no" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:35 +msgid "Since version 1.6.7. Add the given string to the server's process title (what’s shown in the COMMAND column for ``ps -ef`` and ``top -c`` commands)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:40 +msgid "For example, ordinarily :samp:`ps -ef` shows the Tarantool server process thus:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:43 +msgid "$ ps -ef | grep tarantool\n" +"1000 14939 14188 1 10:53 pts/2 00:00:13 tarantool " +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:48 +msgid "But if the configuration parameters include ``custom_proc_title='sessions'`` then the output looks like:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:51 +msgid "$ ps -ef | grep tarantool\n" +"1000 14939 14188 1 10:53 pts/2 00:00:16 tarantool : sessions" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:56 +#: ../../doc/reference/configuration/cfg_basic.rst:104 +#: ../../doc/reference/configuration/cfg_basic.rst:117 +#: ../../doc/reference/configuration/cfg_basic.rst:182 +#: ../../doc/reference/configuration/cfg_basic.rst:212 +#: ../../doc/reference/configuration/cfg_basic.rst:228 +#: ../../doc/reference/configuration/cfg_basic.rst:255 +#: ../../doc/reference/configuration/cfg_storage.rst:81 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:76 +#: ../../doc/reference/configuration/cfg_replication.rst:57 +#: ../../doc/reference/configuration/cfg_replication.rst:227 +#: ../../doc/reference/configuration/cfg_replication.rst:419 +#: ../../doc/reference/configuration/cfg_replication.rst:443 +#: ../../doc/reference/configuration/cfg_replication.rst:576 +#: ../../doc/reference/configuration/cfg_replication.rst:641 +#: ../../doc/reference/configuration/cfg_logging.rst:123 +#: ../../doc/reference/configuration/cfg_logging.rst:207 +#: ../../doc/reference/configuration/cfg_feedback.rst:35 +msgid "Type: string" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:57 +#: ../../doc/reference/configuration/cfg_basic.rst:91 +#: ../../doc/reference/configuration/cfg_basic.rst:118 +#: ../../doc/reference/configuration/cfg_basic.rst:213 +#: ../../doc/reference/configuration/cfg_basic.rst:256 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:59 +#: ../../doc/reference/configuration/cfg_replication.rst:58 +#: ../../doc/reference/configuration/cfg_replication.rst:273 +#: ../../doc/reference/configuration/cfg_replication.rst:420 +#: ../../doc/reference/configuration/cfg_replication.rst:444 +#: ../../doc/reference/configuration/cfg_networking.rst:17 +#: ../../doc/reference/configuration/cfg_logging.rst:124 +msgid "Default: null" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:58 +msgid "Environment variable: TT_CUSTOM_PROC_TITLE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:59 +#: ../../doc/reference/configuration/cfg_basic.rst:93 +#: ../../doc/reference/configuration/cfg_basic.rst:139 +#: ../../doc/reference/configuration/cfg_basic.rst:171 +#: ../../doc/reference/configuration/cfg_basic.rst:204 +#: ../../doc/reference/configuration/cfg_basic.rst:274 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:73 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:103 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:136 +#: ../../doc/reference/configuration/cfg_deprecated.rst:69 +#: ../../doc/reference/configuration/cfg_deprecated.rst:166 +msgid "Dynamic: yes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:65 +msgid "Since version 1.6.4." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:67 +msgid "The read/write data port number or :ref:`URI ` (Universal Resource Identifier) string. Has no default value, so **must be specified** if connections occur from the remote clients that don't use the :ref:`\"admin port\" `. Connections made with :samp:`listen = {URI}` are called \"binary port\" or \"binary protocol\" connections." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:74 +msgid "A typical value is 3301." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:76 +msgid "box.cfg { listen = 3301 }\n" +"\n" +"box.cfg { listen = \"127.0.0.1:3301\" }" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:84 +msgid "A replica also binds to this port, and accepts connections, but these connections can only serve reads until the replica becomes a master." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:87 +msgid "Starting from version 2.10.0, you can specify :ref:`several URIs `, and the port number is always stored as an integer value." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:90 +msgid "Type: integer or string" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:92 +msgid "Environment variable: TT_LISTEN" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:99 +msgid "Since version 1.7.4. A directory where memtx stores snapshot (.snap) files. Can be relative to :ref:`work_dir `. If not specified, defaults to ``work_dir``. See also :ref:`wal_dir `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:105 +#: ../../doc/reference/configuration/cfg_basic.rst:183 +#: ../../doc/reference/configuration/cfg_basic.rst:229 +msgid "Default: \".\"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:106 +msgid "Environment variable: TT_MEMTX_DIR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:113 +msgid "Since version 1.4.9. Store the process id in this file. Can be relative to :ref:`work_dir `. A typical value is “:file:`tarantool.pid`”." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:119 +msgid "Environment variable: TT_PID_FILE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:126 +msgid "Since version 1.7.1. Say ``box.cfg{read_only=true...}`` to put the server instance in read-only mode. After this, any requests that try to change persistent data will fail with error :errcode:`ER_READONLY`. Read-only mode should be used for master-replica :ref:`replication `. Read-only mode does not affect data-change requests for spaces defined as :doc:`temporary `. Although read-only mode prevents the server from writing to the :ref:`WAL `, it does not prevent writing diagnostics with the :ref:`log module `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:138 +msgid "Environment variable: TT_READ_ONLY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:141 +msgid "Setting ``read_only == true`` affects spaces differently depending on the :ref:`options ` that were used during :doc:`box.schema.space.create `, as summarized by this chart:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:149 +msgid "Option" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:149 +msgid "Can be created?" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:149 +msgid "Can be written to?" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:149 +msgid "Is replicated?" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:149 +msgid "Is persistent?" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:151 +msgid "(default)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:151 +#: ../../doc/reference/configuration/cfg_basic.rst:151 +#: ../../doc/reference/configuration/cfg_basic.rst:153 +#: ../../doc/reference/configuration/cfg_basic.rst:153 +#: ../../doc/reference/configuration/cfg_basic.rst:153 +#: ../../doc/reference/configuration/cfg_basic.rst:155 +#: ../../doc/reference/configuration/cfg_basic.rst:155 +msgid "no" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:151 +#: ../../doc/reference/configuration/cfg_basic.rst:151 +#: ../../doc/reference/configuration/cfg_basic.rst:153 +#: ../../doc/reference/configuration/cfg_basic.rst:155 +#: ../../doc/reference/configuration/cfg_basic.rst:155 +msgid "yes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:153 +msgid "temporary" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:155 +msgid "is_local" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:162 +msgid "Since version 2.3.1. The maximum number of bytes in the cache for :ref:`SQL prepared statements `. (The number of bytes that are actually used can be seen with :ref:`box.info.sql().cache.size `.)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:168 +#: ../../doc/reference/configuration/cfg_storage.rst:118 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:111 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:136 +#: ../../doc/reference/configuration/cfg_replication.rst:488 +#: ../../doc/reference/configuration/cfg_replication.rst:506 +#: ../../doc/reference/configuration/cfg_replication.rst:526 +#: ../../doc/reference/configuration/cfg_replication.rst:607 +msgid "Type: number" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:169 +msgid "Default: 5242880" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:170 +msgid "Environment variable: TT_SQL_CACHE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:177 +msgid "Since version 1.7.1. A directory where vinyl files or subdirectories will be stored. Can be relative to :ref:`work_dir `. If not specified, defaults to ``work_dir``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:184 +msgid "Environment variable: TT_VINYL_DIR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:191 +msgid "Since version 1.7.5. The vinyl storage engine has a scheduler which does compaction. When vinyl is low on available memory, the compaction scheduler may be unable to keep up with incoming update requests. In that situation, queries may time out after ``vinyl_timeout`` seconds. This should rarely occur, since normally vinyl would throttle inserts when it is running low on compaction bandwidth. Compaction can also be ordered manually with :doc:`/reference/reference_lua/box_index/compact`." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:201 +#: ../../doc/reference/configuration/cfg_storage.rst:32 +#: ../../doc/reference/configuration/cfg_storage.rst:97 +#: ../../doc/reference/configuration/cfg_storage.rst:134 +#: ../../doc/reference/configuration/cfg_storage.rst:241 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:58 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:90 +#: ../../doc/reference/configuration/cfg_replication.rst:247 +#: ../../doc/reference/configuration/cfg_replication.rst:327 +#: ../../doc/reference/configuration/cfg_replication.rst:345 +#: ../../doc/reference/configuration/cfg_networking.rst:16 +#: ../../doc/reference/configuration/cfg_logging.rst:165 +#: ../../doc/reference/configuration/cfg_feedback.rst:46 +#: ../../doc/reference/configuration/cfg_deprecated.rst:94 +msgid "Type: float" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:202 +msgid "Default: 60" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:203 +msgid "Environment variable: TT_VINYL_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:210 +msgid "Since version 1.4.9. UNIX user name to switch to after start." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:214 +msgid "Environment variable: TT_USERNAME" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:221 +msgid "Since version 1.6.2. A directory where write-ahead log (.xlog) files are stored. Can be relative to :ref:`work_dir `. Sometimes ``wal_dir`` and :ref:`memtx_dir ` are specified with different values, so that write-ahead log files and snapshot files can be stored on different disks. If not specified, defaults to ``work_dir``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:230 +msgid "Environment variable: TT_WAL_DIR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:237 +msgid "Since version 1.4.9. A directory where database working files will be stored. The server instance switches to ``work_dir`` with :manpage:`chdir(2)` after start. Can be relative to the current directory. If not specified, defaults to the current directory. Other directory parameters may be relative to ``work_dir``, for example:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:244 +msgid "box.cfg{\n" +" work_dir = '/home/user/A',\n" +" wal_dir = 'B',\n" +" memtx_dir = 'C'\n" +"}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:252 +msgid "will put xlog files in ``/home/user/A/B``, snapshot files in ``/home/user/A/C``, and all other files or subdirectories in ``/home/user/A``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:257 +msgid "Environment variable: TT_WORK_DIR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:265 +msgid "Since version 1.7.5. The maximum number of threads to use during execution of certain internal processes (currently :ref:`socket.getaddrinfo() ` and :ref:`coio_call() `)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:271 +#: ../../doc/reference/configuration/cfg_storage.rst:47 +#: ../../doc/reference/configuration/cfg_storage.rst:61 +#: ../../doc/reference/configuration/cfg_storage.rst:147 +#: ../../doc/reference/configuration/cfg_storage.rst:161 +#: ../../doc/reference/configuration/cfg_storage.rst:172 +#: ../../doc/reference/configuration/cfg_storage.rst:186 +#: ../../doc/reference/configuration/cfg_storage.rst:212 +#: ../../doc/reference/configuration/cfg_storage.rst:227 +#: ../../doc/reference/configuration/cfg_storage.rst:254 +#: ../../doc/reference/configuration/cfg_storage.rst:267 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:70 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:100 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:133 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:38 +#: ../../doc/reference/configuration/cfg_replication.rst:272 +#: ../../doc/reference/configuration/cfg_replication.rst:369 +#: ../../doc/reference/configuration/cfg_networking.rst:53 +#: ../../doc/reference/configuration/cfg_networking.rst:72 +#: ../../doc/reference/configuration/cfg_networking.rst:91 +#: ../../doc/reference/configuration/cfg_logging.rst:34 +msgid "Type: integer" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:272 +#: ../../doc/reference/configuration/cfg_storage.rst:268 +msgid "Default: 4" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:273 +msgid "Environment variable: TT_WORKER_POOL_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:280 +msgid "Since version 2.2.2. Whether coredump files should include memory allocated for tuples. (This can be large if Tarantool runs under heavy load.) Setting to ``true`` means \"do not include\". In an older version of Tarantool the default value of this parameter was ``false``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:286 +#: ../../doc/reference/configuration/cfg_feedback.rst:24 +#: ../../doc/reference/configuration/cfg_deprecated.rst:57 +#: ../../doc/reference/configuration/cfg_deprecated.rst:68 +#: ../../doc/reference/configuration/cfg_deprecated.rst:164 +msgid "Default: true" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:287 +msgid "Environment variable: TT_STRIP_CORE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:294 +msgid "Since version :doc:`2.6.1 `. Enables :ref:`transactional manager ` if set to ``true``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_basic.rst:299 +msgid "Environment variable: TT_MEMTX_USE_MVCC_ENGINE" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:25 +msgid "Configuring the storage" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:1 +msgid ":ref:`memtx_memory `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:2 +msgid ":ref:`memtx_max_tuple_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:3 +msgid ":ref:`memtx_min_tuple_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:4 +msgid ":ref:`memtx_allocator `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:5 +msgid ":ref:`slab_alloc_factor `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:6 +msgid ":ref:`slab_alloc_granularity `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:7 +msgid ":ref:`vinyl_bloom_fpr `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:8 +msgid ":ref:`vinyl_cache `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:9 +msgid ":ref:`vinyl_max_tuple_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:10 +msgid ":ref:`vinyl_memory `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:11 +msgid ":ref:`vinyl_page_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:12 +msgid ":ref:`vinyl_range_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:13 +msgid ":ref:`vinyl_run_count_per_level `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:14 +msgid ":ref:`vinyl_run_size_ratio `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:15 +msgid ":ref:`vinyl_read_threads `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:16 +msgid ":ref:`vinyl_write_threads `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:22 +msgid "Since version 1.7.4. How much memory Tarantool allocates to actually store tuples. When the limit is reached, :ref:`INSERT ` or :ref:`UPDATE ` requests begin failing with error :errcode:`ER_MEMORY_ISSUE`. The server does not go beyond the ``memtx_memory`` limit to allocate tuples, but there is additional memory used to store indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than the ``memtx_memory`` limit." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:33 +msgid "Default: 256 * 1024 * 1024 = 268435456 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:34 +msgid "Minimum: 33554432 bytes (32 MB)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:35 +msgid "Environment variable: TT_MEMTX_MEMORY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:36 +#: ../../doc/reference/configuration/cfg_storage.rst:175 +msgid "Dynamic: **yes** but it cannot be decreased" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:42 +msgid "Since version 1.7.4. Size of the largest allocation unit, for the memtx storage engine. It can be increased if it is necessary to store large tuples. See also: :ref:`vinyl_max_tuple_size `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:48 +#: ../../doc/reference/configuration/cfg_storage.rst:162 +msgid "Default: 1024 * 1024 = 1048576 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:49 +msgid "Environment variable: TT_MEMTX_MAX_TUPLE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:50 +#: ../../doc/reference/configuration/cfg_storage.rst:150 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:61 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:114 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:139 +#: ../../doc/reference/configuration/cfg_replication.rst:60 +#: ../../doc/reference/configuration/cfg_replication.rst:206 +#: ../../doc/reference/configuration/cfg_replication.rst:230 +#: ../../doc/reference/configuration/cfg_replication.rst:250 +#: ../../doc/reference/configuration/cfg_replication.rst:275 +#: ../../doc/reference/configuration/cfg_replication.rst:299 +#: ../../doc/reference/configuration/cfg_replication.rst:330 +#: ../../doc/reference/configuration/cfg_replication.rst:348 +#: ../../doc/reference/configuration/cfg_replication.rst:372 +#: ../../doc/reference/configuration/cfg_replication.rst:491 +#: ../../doc/reference/configuration/cfg_replication.rst:509 +#: ../../doc/reference/configuration/cfg_replication.rst:579 +#: ../../doc/reference/configuration/cfg_replication.rst:610 +#: ../../doc/reference/configuration/cfg_replication.rst:644 +#: ../../doc/reference/configuration/cfg_networking.rst:19 +#: ../../doc/reference/configuration/cfg_networking.rst:56 +#: ../../doc/reference/configuration/cfg_networking.rst:75 +#: ../../doc/reference/configuration/cfg_logging.rst:37 +#: ../../doc/reference/configuration/cfg_logging.rst:168 +#: ../../doc/reference/configuration/cfg_logging.rst:210 +#: ../../doc/reference/configuration/cfg_logging.rst:234 +#: ../../doc/reference/configuration/cfg_feedback.rst:26 +#: ../../doc/reference/configuration/cfg_feedback.rst:38 +#: ../../doc/reference/configuration/cfg_feedback.rst:49 +msgid "Dynamic: **yes**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:56 +msgid "Since version 1.7.4. Size of the smallest allocation unit. It can be decreased if most of the tuples are very small. The value must be between 8 and 1048280 inclusive." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:62 +msgid "Default: 16 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:63 +msgid "Environment variable: TT_MEMTX_MIN_TUPLE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:70 +msgid "Since version :doc:`2.10.0 `. Specifies the allocator used for memtx tuples. The possible values are ``system`` and ``small``:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:74 +msgid "``system`` is based on the ``malloc`` function. This allocator allocates memory as needed, checking that the quota is not exceeded." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:77 +msgid "``small`` is a special `slab allocator `_. Note that this allocator is prone to unresolvable fragmentation on specific workloads, so you can switch to ``system`` in such cases." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:82 +msgid "Default: 'small'" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:83 +msgid "Environment variable: TT_MEMTX_ALLOCATOR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:84 +msgid "Dynamic: No" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:90 +msgid "The multiplier for computing the sizes of memory chunks that tuples are stored in. A lower value may result in less wasted memory depending on the total amount of memory available and the distribution of item sizes. Allowed values range from 1 to 2." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:95 +msgid "See also: :ref:`slab_alloc_granularity `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:98 +msgid "Default: 1.05" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:99 +msgid "Environment variable: TT_SLAB_ALLOC_FACTOR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:106 +msgid "Since version :doc:`2.8.1 `. Specifies the granularity (in bytes) of memory allocation in the :ref:`small allocator `. The value of ``slab_alloc_granularity`` should be a power of two and should be greater than or equal to 4. Below are few recommendations on how to adjust the ``slab_alloc_granularity`` value:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:111 +msgid "To store small tuples of approximately the same size, set ``slab_alloc_granularity`` to 4 bytes to save memory." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:113 +msgid "To store tuples of different sizes, you can increase the ``slab_alloc_granularity`` value. This results in allocating tuples from the same ``mempool``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:116 +msgid "See also: :ref:`slab_alloc_factor `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:119 +msgid "Default: 8 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:120 +msgid "Environment variable: TT_SLAB_ALLOC_GRANULARITY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:127 +msgid "Since version 1.7.4. Bloom filter false positive rate -- the suitable probability of the `bloom filter `_ to give a wrong result. The ``vinyl_bloom_fpr`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:135 +msgid "Default: 0.05" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:136 +msgid "Environment variable: TT_VINYL_BLOOM_FPR" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:143 +msgid "Since version 1.7.4. The cache size for the vinyl storage engine. The cache can be resized dynamically." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:148 +#: ../../doc/reference/configuration/cfg_storage.rst:173 +msgid "Default: 128 * 1024 * 1024 = 134217728 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:149 +msgid "Environment variable: TT_VINYL_CACHE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:156 +msgid "Since version 1.7.5. Size of the largest allocation unit, for the vinyl storage engine. It can be increased if it is necessary to store large tuples. See also: :ref:`memtx_max_tuple_size `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:163 +msgid "Environment variable: TT_VINYL_MAX_TUPLE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:170 +msgid "Since version 1.7.4. The maximum number of in-memory bytes that vinyl uses." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:174 +msgid "Environment variable: TT_VINYL_MEMORY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:181 +msgid "Since version 1.7.4. Page size. Page is a read/write unit for vinyl disk operations. The ``vinyl_page_size`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:187 +msgid "Default: 8 * 1024 = 8192 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:188 +msgid "Environment variable: TT_VINYL_PAGE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:195 +msgid "Since version 1.7.4. The default maximum range size for a vinyl index, in bytes. The maximum range size affects the decision whether to :ref:`split ` a range." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:200 +msgid "If ``vinyl_range_size`` is not nil and not 0, then it is used as the default value for the ``range_size`` option in the :ref:`Options for space_object:create_index() ` chart." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:205 +msgid "If ``vinyl_range_size`` is nil or 0, and ``range_size`` is not specified when the index is created, then Tarantool sets a value later depending on performance considerations. To see the actual value, use :doc:`index_object:stat().range_size `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:210 +msgid "In Tarantool versions prior to 1.10.2, ``vinyl_range_size`` default value was 1073741824." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:213 +#: ../../doc/reference/configuration/cfg_logging.rst:152 +msgid "Default: nil" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:214 +msgid "Environment variable: TT_VINYL_RANGE_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:221 +msgid "Since version 1.7.4. The maximal number of runs per level in vinyl LSM tree. If this number is exceeded, a new level is created. The ``vinyl_run_count_per_level`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:228 +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:101 +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:91 +msgid "Default: 2" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:229 +msgid "Environment variable: TT_VINYL_RUN_COUNT_PER_LEVEL" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:236 +msgid "Since version 1.7.4. Ratio between the sizes of different levels in the LSM tree. The ``vinyl_run_size_ratio`` setting is a default value for one of the options in the :ref:`Options for space_object:create_index() ` chart." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:242 +msgid "Default: 3.5" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:243 +msgid "Environment variable: TT_VINYL_RUN_SIZE_RATIO" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:250 +msgid "Since version 1.7.5. The maximum number of read threads that vinyl can use for some concurrent operations, such as I/O and compression." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:255 +#: ../../doc/reference/configuration/cfg_replication.rst:370 +#: ../../doc/reference/configuration/cfg_replication.rst:527 +#: ../../doc/reference/configuration/cfg_networking.rst:92 +msgid "Default: 1" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:256 +msgid "Environment variable: TT_VINYL_READ_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:263 +msgid "Since version 1.7.5. The maximum number of write threads that vinyl can use for some concurrent operations, such as I/O and compression." +msgstr "" + +#: ../../doc/reference/configuration/cfg_storage.rst:269 +msgid "Environment variable: TT_VINYL_WRITE_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:32 +msgid "Checkpoint daemon" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:1 +msgid ":ref:`checkpoint_count `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:2 +msgid ":ref:`checkpoint_interval `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:3 +msgid ":ref:`checkpoint_wal_threshold `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:5 +msgid "The checkpoint daemon is a fiber which is constantly running. At intervals, it may make new :ref:`snapshot (.snap) files ` and then may delete old snapshot files." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:9 +msgid "The :ref:`checkpoint_interval ` and :ref:`checkpoint_count ` configuration settings determine how long the intervals are, and how many snapshots should exist before deletions occur." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:16 +msgid "**Tarantool garbage collector**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:18 +msgid "The checkpoint daemon may activate the Tarantool garbage collector which deletes old files. This garbage collector is distinct from the `Lua garbage collector `_ which is for Lua objects, and distinct from a Tarantool garbage collector which specializes in :ref:`handling shard buckets `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:25 +msgid "If the checkpoint daemon deletes an old snapshot file, then the Tarantool garbage collector will also delete any :ref:`write-ahead log (.xlog) ` files which are older than the snapshot file and which contain information that is present in the snapshot file. It will also delete obsolete vinyl ``.run`` files." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:31 +msgid "The checkpoint daemon and the Tarantool garbage collector will not delete a file if:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:33 +msgid "a **backup** is ongoing and the file has not been backed up (see :ref:`\"Hot backup\" `), or" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:36 +msgid "**replication** is ongoing and the file has not been relayed to a replica (see :ref:`\"Replication architecture\" `)," +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:39 +msgid "a replica is connecting, or" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:41 +msgid "a replica has fallen behind. The progress of each replica is tracked; if a replica's position is far from being up to date, then the server stops to give it a chance to catch up. If an administrator concludes that a replica is permanently down, then the correct procedure is to restart the server, or (preferably) :ref:`remove the replica from the cluster `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:53 +msgid "Since version 1.7.4. The interval between actions by the checkpoint daemon, in seconds. If ``checkpoint_interval`` is set to a value greater than zero, and there is activity which causes change to a database, then the checkpoint daemon will call :doc:`box.snapshot() ` every ``checkpoint_interval`` seconds, creating a new snapshot file each time. If ``checkpoint_interval`` is set to zero, then the checkpoint daemon is disabled." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:61 +msgid "For example:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:63 +msgid "box.cfg{checkpoint_interval=60}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:67 +msgid "will cause the checkpoint daemon to create a new database snapshot once per minute, if there is activity." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:71 +msgid "Default: 3600 (one hour)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:72 +msgid "Environment variable: TT_CHECKPOINT_INTERVAL" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:79 +msgid "Since version 1.7.4. The maximum number of snapshots that may exist on the :ref:`memtx_dir ` directory before the checkpoint daemon will delete old snapshots. If ``checkpoint_count`` equals zero, then the checkpoint daemon does not delete old snapshots. For example:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:85 +msgid "box.cfg{\n" +" checkpoint_interval = 3600,\n" +" checkpoint_count = 10\n" +"}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:92 +msgid "will cause the checkpoint daemon to create a new snapshot each hour until it has created ten snapshots. After that, it will delete the oldest snapshot (and any associated write-ahead-log files) after creating a new one." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:96 +msgid "Remember that, as noted earlier, snapshots will not be deleted if replication is ongoing and the file has not been relayed to a replica. Therefore ``checkpoint_count`` has no effect unless all replicas are alive." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:102 +msgid "Environment variable: TT_CHECKPOINT_COUNT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:109 +msgid "Since version 2.1.2. The threshold for the total size in bytes of all WAL files created since the last checkpoint. Once the configured threshold is exceeded, the WAL thread notifies the checkpoint daemon that it must make a new checkpoint and delete old WAL files." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:114 +msgid "This parameter enables administrators to handle a problem that could occur with calculating how much disk space to allocate for a partition containing WAL files." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:118 +msgid "For example, suppose :ref:`checkpoint_interval ` = 2 and :ref:`checkpoint_count ` = 5 and the average amount that Tarantool writes between each checkpoint interval = 1 GB. Then one could calculate that the necessary amount is (2*5*1) 10GB. But this calculation would be wrong if, instead of writing 1 GB during one checkpoint interval, Tarantool encounters an unusual spike and tries to write 11 GB, causing an operating-system ENOSPC (\"no space\") error. By setting ``checkpoint_wal_threshold`` to a lower value, say 9 GB, an administrator could prevent the error." +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:134 +msgid "Default: 10^18 (a large number so in effect there is no limit by default)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_snapshot_daemon.rst:135 +msgid "Environment variable: TT_CHECKPOINT_WAL_THRESHOLD" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:37 +msgid "Binary logging and snapshots" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:1 +msgid ":ref:`force_recovery `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:2 +msgid ":ref:`wal_max_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:3 +msgid ":ref:`snap_io_rate_limit `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:4 +msgid ":ref:`wal_mode `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:5 +msgid ":ref:`wal_dir_rescan_delay `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:6 +msgid ":ref:`wal_queue_max_size `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:7 +msgid ":ref:`wal_cleanup_delay `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:13 +msgid "Since version 1.7.4. If ``force_recovery`` equals true, Tarantool tries to continue if there is an error while reading a :ref:`snapshot file` (at server instance start) or a :ref:`write-ahead log file` (at server instance start or when applying an update at a replica): skips invalid records, reads as much data as possible and lets the process finish with a warning. Users can prevent the error from recurring by writing to the database and executing :doc:`box.snapshot() `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:22 +msgid "Otherwise, Tarantool aborts recovery if there is an error while reading." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:26 +msgid "Environment variable: TT_FORCE_RECOVERY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:33 +msgid "Since version 1.7.4. The maximum number of bytes in a single write-ahead log file. When a request would cause an .xlog file to become larger than ``wal_max_size``, Tarantool creates another WAL file." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:39 +msgid "Default: 268435456 (256 * 1024 * 1024) bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:40 +msgid "Environment variable: TT_WAL_MAX_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:47 +msgid "Since version 1.4.9. Reduce the throttling effect of :doc:`box.snapshot() ` on INSERT/UPDATE/DELETE performance by setting a limit on how many megabytes per second it can write to disk. The same can be achieved by splitting :ref:`wal_dir ` and :ref:`memtx_dir ` locations and moving snapshots to a separate disk. The limit also affects what :ref:`box.stat.vinyl().regulator ` may show for the write rate of dumps to .run and .index files." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:60 +msgid "Environment variable: TT_SNAP_IO_RATE_LIMIT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:67 +msgid "Since version 1.6.2. Specify fiber-WAL-disk synchronization mode as:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:69 +msgid "``none``: write-ahead log is not maintained. A node with ``wal_mode = none`` can't be replication master;" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:71 +msgid "``write``: :ref:`fibers ` wait for their data to be written to the write-ahead log (no :manpage:`fsync(2)`);" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:73 +msgid "``fsync``: fibers wait for their data, :manpage:`fsync(2)` follows each :manpage:`write(2)`;" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:77 +msgid "Default: \"write\"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:78 +msgid "Environment variable: TT_WAL_MODE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:85 +msgid "Since version 1.6.2. Number of seconds between periodic scans of the write-ahead-log file directory, when checking for changes to write-ahead-log files for the sake of :ref:`replication ` or :ref:`hot standby `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:92 +msgid "Environment variable: TT_WAL_DIR_RESCAN_DELAY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:99 +msgid "Since version :doc:`2.8.1 `. The size of the queue (in bytes) used by a :ref:`replica ` to submit new transactions to a :ref:`write-ahead log` (WAL). This option helps limit the rate at which a replica submits transactions to the WAL. Limiting the queue size might be useful when a replica is trying to sync with a master and reads new transactions faster than writing them to the WAL." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:108 +msgid "You might consider increasing the ``wal_queue_max_size`` value in case of large tuples (approximately one megabyte or larger)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:112 +msgid "Default: 16777216 bytes" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:113 +msgid "Environment variable: TT_WAL_QUEUE_MAX_SIZE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:120 +msgid "Since version :doc:`2.6.3 `. The delay (in seconds) used to prevent the :ref:`Tarantool garbage collector ` from immediately removing :ref:`write-ahead log` files after a node restart. This delay eliminates possible erroneous situations when the master deletes WALs needed by :ref:`replicas ` after restart. As a consequence, replicas sync with the master faster after its restart and don't need to download all the data again." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:128 +msgid "Once all the nodes in the replica set are up and running, automatic cleanup is started again even if ``wal_cleanup_delay`` has not expired." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:133 +msgid "The ``wal_cleanup_delay`` option has no effect on nodes running as :ref:`anonymous replicas`." +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:137 +msgid "Default: 14400 seconds" +msgstr "" + +#: ../../doc/reference/configuration/cfg_binary_logging_snapshots.rst:138 +msgid "Environment variable: TT_WAL_CLEANUP_DELAY" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:44 +msgid "Hot standby" +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:3 +msgid "Since version 1.7.4. Whether to start the server in **hot standby** mode." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:5 +msgid "Hot standby is a feature which provides a simple form of failover without :ref:`replication `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:8 +msgid "The expectation is that there will be two instances of the server using the same configuration. The first one to start will be the \"primary\" instance. The second one to start will be the \"standby\" instance." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:12 +msgid "To initiate the standby instance, start a second instance of the Tarantool server on the same computer with the same :doc:`box.cfg ` configuration settings -- including the same directories and same non-null URIs -- and with the additional configuration setting ``hot_standby = true``. Expect to see a notification ending with the words ``I> Entering hot standby mode``. This is fine. It means that the standby instance is ready to take over if the primary instance goes down." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:22 +msgid "The standby instance will initialize and will try to take a lock on :ref:`wal_dir `, but will fail because the primary instance has made a lock on ``wal_dir``. So the standby instance goes into a loop, reading the write ahead log which the primary instance is writing (so the two instances are always in sync), and trying to take the lock. If the primary instance goes down for any reason, the lock will be released. In this case, the standby instance will succeed in taking the lock, will connect on the :ref:`listen ` address and will become the primary instance. Expect to see a notification ending with the words ``I> ready to accept requests``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:35 +msgid "Thus there is no noticeable downtime if the primary instance goes down." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:37 +msgid "Hot standby feature has no effect:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:39 +msgid "if :ref:`wal_dir_rescan_delay = a large number ` (on Mac OS and FreeBSD); on these platforms, it is designed so that the loop repeats every ``wal_dir_rescan_delay`` seconds." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:43 +msgid "if :ref:`wal_mode = 'none' `; it is designed to work with ``wal_mode = 'write'`` or ``wal_mode = 'fsync'``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:45 +msgid "for spaces created with :doc:`engine = 'vinyl' `; it is designed to work for spaces created with ``engine = 'memtx'``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_hot_standby.rst:50 +msgid "Environment variable: TT_HOT_STANDBY" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:49 +msgid "Replication" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:1 +msgid ":ref:`replication `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:2 +msgid ":ref:`replication_anon `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:3 +msgid ":ref:`bootstrap_strategy `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:4 +msgid ":ref:`replication_connect_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:5 +msgid ":ref:`replication_connect_quorum `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:6 +msgid ":ref:`replication_skip_conflict `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:7 +msgid ":ref:`replication_sync_lag `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:8 +msgid ":ref:`replication_sync_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:9 +msgid ":ref:`replication_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:10 +msgid ":ref:`replicaset_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:11 +msgid ":ref:`instance_uuid `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:12 +msgid ":ref:`replication_synchro_quorum `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:13 +msgid ":ref:`replication_synchro_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:14 +msgid ":ref:`replication_threads `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:15 +msgid ":ref:`election_mode `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:16 +msgid ":ref:`election_timeout `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:17 +msgid ":ref:`election_fencing_mode `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:23 +msgid "Since version 1.7.4. If ``replication`` is not an empty string, the instance is considered to be a Tarantool :ref:`replica `. The replica will try to connect to the master specified in ``replication`` with a :ref:`URI ` (Universal Resource Identifier), for example:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:29 +msgid ":samp:`{konstantin}:{secret_password}@{tarantool.org}:{3301}`" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:31 +msgid "If there is more than one replication source in a replica set, specify an array of URIs, for example (replace 'uri' and 'uri2' in this example with valid URIs):" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:35 +msgid ":extsamp:`box.cfg{ replication = { {*{'uri1'}*}, {*{'uri2'}*} } }`" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:39 +msgid "Starting from version 2.10.0, there is a number of other ways for specifying several URIs. See :ref:`syntax examples `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:41 +msgid "If one of the URIs is \"self\" -- that is, if one of the URIs is for the instance where ``box.cfg{}`` is being executed -- then it is ignored. Thus, it is possible to use the same ``replication`` specification on multiple server instances, as shown in :ref:`these examples `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:47 +msgid "The default user name is 'guest'." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:49 +msgid "A read-only replica does not accept data-change requests on the :ref:`listen ` port." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:52 +msgid "The ``replication`` parameter is dynamic, that is, to enter master mode, simply set ``replication`` to an empty string and issue:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:55 +msgid ":extsamp:`box.cfg{ replication = {*{new-value}*} }`" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:59 +msgid "Environment variable: TT_REPLICATION" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:66 +msgid "Since version 2.3.1. A Tarantool replica can be anonymous. This type of replica is read-only (but you still can write to temporary and replica-local spaces), and it isn't present in the ``_cluster`` table." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:71 +msgid "Since an anonymous replica isn't registered in the ``_cluster`` table, there is no limitation for anonymous replicas count in a replica set: you can have as many of them as you want." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:75 +msgid "In order to make a replica anonymous, pass the option ``replication_anon=true`` to ``box.cfg`` and set ``read_only`` to ``true``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:79 +msgid "Let's go through anonymous replica bootstrap. Suppose we have got a master configured with" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:82 +msgid "box.cfg{listen=3301}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:86 +msgid "and created a local space called \"loc\":" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:88 +msgid "box.schema.space.create('loc', {is_local=true})\n" +"box.space.loc:create_index(\"pk\")" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:93 +msgid "Now, to configure an anonymous replica, we need to issue ``box.cfg``, as usual." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:96 +msgid "box.cfg{replication_anon=true, read_only=true, replication=3301}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:100 +msgid "As mentioned above, ``replication_anon`` may be set to ``true`` only together with ``read_only``. The instance will fetch the master's snapshot and start following its changes. It will receive no id, so its id value will remain zero." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:105 +msgid "tarantool> box.info.id\n" +"---\n" +"- 0\n" +"...\n" +"tarantool> box.info.replication\n" +"---\n" +"- 1:\n" +" id: 1\n" +" uuid: 3c84f8d9-e34d-4651-969c-3d0ed214c60f\n" +" lsn: 4\n" +" upstream:\n" +" status: follow\n" +" idle: 0.6912029999985\n" +" peer:\n" +" lag: 0.00014615058898926\n" +"..." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:124 +msgid "Now we can use the replica. For example, we can do inserts into the local space:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:127 +msgid "tarantool> for i = 1,10 do\n" +" > box.space.loc:insert{i}\n" +" > end\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:135 +msgid "Note that while the instance is anonymous, it will increase the 0-th component of its ``vclock``:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:138 +msgid "tarantool> box.info.vclock\n" +"---\n" +"- {0: 10, 1: 4}\n" +"..." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:145 +msgid "Let's now promote the anonymous replica to a regular one:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:147 +msgid "tarantool> box.cfg{replication_anon=false}\n" +"2019-12-13 20:34:37.423 [71329] main I> assigned id 2 to replica 6a9c2ed2-b9e1-4c57-a0e8-51a46def7661\n" +"2019-12-13 20:34:37.424 [71329] main/102/interactive I> set 'replication_anon' configuration option to false\n" +"---\n" +"...\n" +"\n" +"tarantool> 2019-12-13 20:34:37.424 [71329] main/117/applier/ I> subscribed\n" +"2019-12-13 20:34:37.424 [71329] main/117/applier/ I> remote vclock {1: 5} local vclock {0: 10, 1: 5}\n" +"2019-12-13 20:34:37.425 [71329] main/118/applierw/ C> leaving orphan mode" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:159 +msgid "The replica has just received an id equal to 2. We can make it read-write now." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:161 +msgid "tarantool> box.cfg{read_only=false}\n" +"2019-12-13 20:35:46.392 [71329] main/102/interactive I> set 'read_only' configuration option to false\n" +"---\n" +"...\n" +"\n" +"tarantool> box.schema.space.create('test')\n" +"---\n" +"- engine: memtx\n" +"before_replace: 'function: 0x01109f9dc8'\n" +"on_replace: 'function: 0x01109f9d90'\n" +"ck_constraint: []\n" +"field_count: 0\n" +"temporary: false\n" +"index: []\n" +"is_local: false\n" +"enabled: false\n" +"name: test\n" +"id: 513\n" +"- created\n" +"...\n" +"\n" +"tarantool> box.info.vclock\n" +"---\n" +"- {0: 10, 1: 5, 2: 2}\n" +"..." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:189 +msgid "Now the replica tracks its changes in the 2nd ``vclock`` component, as expected. It can also become a replication master from now on." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:193 +msgid "Notes:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:195 +msgid "You cannot replicate from an anonymous instance." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:196 +msgid "To promote an anonymous instance to a regular one, first start it as anonymous, and only then issue ``box.cfg{replication_anon=false}``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:199 +msgid "In order for the deanonymization to succeed, the instance must replicate from some read-write instance, otherwise it cannot be added to the ``_cluster`` table." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:205 +msgid "Environment variable: TT_REPLICATION_ANON" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:213 +msgid "Since :doc:`2.11.0 `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:215 +msgid "Specifies a strategy used to bootstrap a :ref:`replica set `. The following strategies are available:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:218 +msgid "``auto``: a node doesn't boot if a half or more of other nodes in a replica set are not connected. For example, if the :ref:`replication ` parameter contains 2 or 3 nodes, a node requires 2 connected instances. In the case of 4 or 5 nodes, at least 3 connected instances are required. Moreover, a bootstrap leader fails to boot unless every connected node has chosen it as a bootstrap leader." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:224 +msgid "``legacy`` (deprecated since :doc:`2.11.0 `): a node requires the :ref:`replication_connect_quorum ` number of other nodes to be connected. This option is added to keep the compatibility with the current versions of Cartridge and might be removed in the future." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:228 +msgid "Default: auto" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:229 +msgid "Environment variable: TT_BOOTSTRAP_STRATEGY" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:237 +msgid "Since version 1.9.0. The number of seconds that a replica will wait when trying to connect to a master in a cluster. See :ref:`orphan status ` for details." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:242 +msgid "This parameter is different from :ref:`replication_timeout `, which a master uses to disconnect a replica when the master receives no acknowledgments of heartbeat messages." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:248 +msgid "Default: 30" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:249 +msgid "Environment variable: TT_REPLICATION_CONNECT_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:256 +msgid "Deprecated since :doc:`2.11.0 `. This option is in effect if :ref:`bootstrap_strategy ` is set to ``legacy``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:259 +msgid "Specifies the number of nodes to be up and running to start a replica set. This parameter has effect during :ref:`bootstrap ` or :ref:`configuration update `. Setting ``replication_connect_quorum`` to ``0`` makes Tarantool require no immediate reconnect only in case of recovery. See :ref:`Orphan status ` for details." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:266 +#: ../../doc/reference/configuration/cfg_replication.rst:290 +#: ../../doc/reference/configuration/cfg_replication.rst:413 +#: ../../doc/reference/configuration/cfg_replication.rst:437 +msgid "Example:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:268 +msgid "box.cfg { replication_connect_quorum = 2 }" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:274 +msgid "Environment variable: TT_REPLICATION_CONNECT_QUORUM" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:281 +msgid "Since version 1.10.1. By default, if a replica adds a unique key that another replica has added, replication :ref:`stops ` with error = ER_TUPLE_FOUND." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:286 +msgid "However, by specifying ``replication_skip_conflict = true``, users can state that such errors may be ignored. So instead of saving the broken transaction to the xlog, it will be written there as ``NOP`` (No operation)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:292 +msgid "box.cfg{replication_skip_conflict=true}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:298 +msgid "Environment variable: TT_REPLICATION_SKIP_CONFLICT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:304 +msgid "``replication_skip_conflict = true`` is recommended to be used only for manual replication recovery." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:311 +msgid "Since version 1.9.0. The maximum :ref:`lag ` allowed for a replica. When a replica :ref:`syncs ` (gets updates from a master), it may not catch up completely. The number of seconds that the replica is behind the master is called the \"lag\". Syncing is considered to be complete when the replica's lag is less than or equal to ``replication_sync_lag``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:319 +msgid "If a user sets ``replication_sync_lag`` to nil or to 365 * 100 * 86400 (TIMEOUT_INFINITY), then lag does not matter -- the replica is always considered to be \"synced\". Also, the lag is ignored (assumed to be infinite) in case the master is running Tarantool older than 1.7.7, which does not send :ref:`heartbeat messages `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:324 +msgid "This parameter is ignored during bootstrap. See :ref:`orphan status ` for details." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:328 +msgid "Default: 10" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:329 +msgid "Environment variable: TT_REPLICATION_SYNC_LAG" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:336 +msgid "Since version 1.10.2. The number of seconds that a node waits when trying to sync with other nodes in a replica set (see :ref:`bootstrap_strategy `), after connecting or during :ref:`configuration update `. This could fail indefinitely if ``replication_sync_lag`` is smaller than network latency, or if the replica cannot keep pace with master updates. If ``replication_sync_timeout`` expires, the replica enters :ref:`orphan status `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:346 +msgid "Default: 300" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:347 +msgid "Environment variable: TT_REPLICATION_SYNC_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:352 +msgid "The default ``replication_sync_timeout`` value is going to be changed in future versions from ``300`` to ``0``. You can learn the reasoning behind this decision from the :ref:`Default value for replication_sync_timeout ` topic, which also describes how to try the new behavior in the current version." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:359 +msgid "Since version 1.7.5. If the master has no updates to send to the replicas, it sends heartbeat messages every ``replication_timeout`` seconds, and each replica sends an ACK packet back." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:363 +msgid "Both master and replicas are programmed to drop the connection if they get no response in four ``replication_timeout`` periods. If the connection is dropped, a replica tries to reconnect to the master." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:367 +msgid "See more in :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:371 +msgid "Environment variable: TT_REPLICATION_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:378 +msgid "Since version 1.9.0. As described in section :ref:`\"Replication architecture\" `, each replica set is identified by a `universally unique identifier `_ called **replica set UUID**, and each instance is identified by an **instance UUID**." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:385 +msgid "Ordinarily it is sufficient to let the system generate and format the UUID strings which will be permanently stored." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:388 +msgid "However, some administrators may prefer to store Tarantool configuration information in a central repository, for example `Apache ZooKeeper `_. Such administrators can assign their own UUID values for either -- or both -- instances (:ref:`instance_uuid `) and replica set (``replicaset_uuid``), when starting up for the first time." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:395 +msgid "General rules:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:397 +msgid "The values must be true unique identifiers, not shared by other instances or replica sets within the common infrastructure." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:400 +msgid "The values must be used consistently, not changed after initial setup (the initial values are stored in :ref:`snapshot files ` and are checked whenever the system is restarted)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:404 +msgid "The values must comply with `RFC 4122 `_. The `nil UUID `_ is not allowed." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:408 +msgid "The UUID format includes sixteen octets represented as 32 hexadecimal (base 16) digits, displayed in five groups separated by hyphens, in the form ``8-4-4-4-12`` for a total of 36 characters (32 alphanumeric characters and four hyphens)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:415 +msgid "box.cfg{replicaset_uuid='7b853d13-508b-4b8e-82e6-806f088ea6e9'}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:421 +msgid "Environment variable: TT_REPLICASET_UUID" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:428 +msgid "Since version 1.9.0. For replication administration purposes, it is possible to set the `universally unique identifiers `_ of the instance (``instance_uuid``) and the replica set (``replicaset_uuid``), instead of having the system generate the values." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:434 +msgid "See the description of :ref:`replicaset_uuid ` parameter for details." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:439 +msgid "box.cfg{instance_uuid='037fec43-18a9-4e12-a684-a42b716fcd02'}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:445 +msgid "Environment variable: TT_INSTANCE_UUID" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:452 +msgid "Since version :doc:`2.5.1 `. For :ref:`synchronous replication ` only. This option tells how many replicas should confirm the receipt of a synchronous transaction before it can finish its commit." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:457 +msgid "Since version :doc:`2.5.3 `, the option supports dynamic evaluation of the quorum number. That is, the number of quorum can be specified not as a constant number, but as a function instead. In this case, the option returns the formula evaluated. The result is treated as an integer number. Once any replicas are added or removed, the expression is re-evaluated automatically." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:464 +msgid "For example," +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:466 +msgid "box.cfg{replication_synchro_quorum = \"N / 2 + 1\"}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:470 +msgid "Where `N` is a current number of registered replicas in a cluster." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:472 +msgid "Keep in mind that the example above represents a canonical quorum definition. The formula ``at least 50% of the cluster size + 1`` guarantees data reliability. Using a value less than the canonical one might lead to unexpected results, including a :ref:`split-brain `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:477 +msgid "Since version :doc:`2.10.0 `, this option does not account for anonymous replicas." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:480 +msgid "The default value for this parameter is ``N / 2 + 1``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:482 +#: ../../doc/reference/configuration/cfg_replication.rst:502 +msgid "It is not used on replicas, so if the master dies, the pending synchronous transactions will be kept waiting on the replicas until a new master is elected." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:485 +msgid "If the value for this option is set to ``1``, the synchronous transactions work like asynchronous when not configured. `1` means that successful WAL write to the master is enough to commit." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:489 +msgid "Default: N / 2 + 1 (before version :doc:`2.10.0 `, the default value was 1)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:490 +msgid "Environment variable: TT_REPLICATION_SYNCHRO_QUORUM" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:497 +msgid "Since version :doc:`2.5.1 `. For :ref:`synchronous replication ` only. Tells how many seconds to wait for a synchronous transaction quorum replication until it is declared failed and is rolled back." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:507 +#: ../../doc/reference/configuration/cfg_replication.rst:608 +#: ../../doc/reference/configuration/cfg_logging.rst:35 +msgid "Default: 5" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:508 +msgid "Environment variable: TT_REPLICATION_SYNCHRO_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:515 +msgid "Since version :doc:`2.10.0 `. The number of threads spawned to decode the incoming replication data." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:518 +msgid "The default value is `1`. It means that a single separate thread handles all the incoming replication streams. In most cases, one thread is enough for all incoming data. Therefore, it is likely that the user will not need to set this configuration option." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:523 +msgid "Possible values range from 1 to 1000. If there are multiple replication threads, connections to serve are distributed evenly between the threads." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:528 +msgid "Possible values: from 1 to 1000" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:529 +msgid "Environment variable: TT_REPLICATION_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:530 +msgid "Dynamic: **no**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:536 +msgid "Since version :doc:`2.6.1 `. Specifies the role of a replica set node in the :ref:`leader election process `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:540 +msgid "Possible values:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:542 +msgid "off" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:543 +msgid "voter" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:544 +msgid "candidate" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:545 +msgid "manual." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:547 +msgid "Participation of a replica set node in the automated leader election can be turned on and off by this option." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:550 +msgid "The default value is ``off``. All nodes that have values other than ``off`` run the Raft state machine internally talking to other nodes according to the Raft leader election protocol. When the option is ``off``, the node accepts Raft messages from other nodes, but it doesn't participate in the election activities, and this doesn't affect the node's state. So, for example, if a node is not a leader but it has ``election_mode = 'off'``, it is writable anyway." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:558 +msgid "You can control which nodes can become a leader. If you want a node to participate in the election process but don't want that it becomes a leaders, set the ``election_mode`` option to ``voter``. In this case, the election works as usual, this particular node will vote for other nodes, but won't become a leader." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:564 +msgid "If the node should be able to become a leader, use ``election_mode = 'candidate'``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:566 +msgid "Since version :doc:`2.8.2 `, the manual election mode is introduced. It may be used when a user wants to control which instance is the leader explicitly instead of relying on the Raft election algorithm." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:570 +msgid "When an instance is configured with the ``election_mode='manual'``, it behaves as follows:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:572 +msgid "By default, the instance acts like a voter -- it is read-only and may vote for other instances that are candidates." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:573 +msgid "Once :ref:`box.ctl.promote() ` is called, the instance becomes a candidate and starts a new election round. If the instance wins the elections, it becomes a leader, but won't participate in any new elections." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:577 +msgid "Default: 'off'" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:578 +msgid "Environment variable: TT_ELECTION_MODE" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:585 +msgid "Since version :doc:`2.6.1 `. Specifies the timeout between election rounds in the :ref:`leader election process ` if the previous round ended up with a split-vote." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:590 +msgid "In the :ref:`leader election process `, there can be an election timeout for the case of a split-vote. The timeout can be configured using this option; the default value is 5 seconds." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:595 +msgid "It is quite big, and for most of the cases it can be freely lowered to 300-400 ms. It can be a floating point value (300 ms would be ``box.cfg{election_timeout = 0.3}``)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:599 +msgid "To avoid the split vote repeat, the timeout is randomized on each node during every new election, from 100% to 110% of the original timeout value. For example, if the timeout is 300 ms and there are 3 nodes started the election simultaneously in the same term, they can set their election timeouts to 300, 310, and 320 respectively, or to 305, 302, and 324, and so on. In that way, the votes will never be split because the election on different nodes won't be restarted simultaneously." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:609 +msgid "Environment variable: TT_ELECTION_TIMEOUT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:616 +msgid "Since version :doc:`2.11.0 `. In earlier Tarantool versions, use :ref:`election_fencing_enabled ` instead." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:619 +msgid "Specifies the :ref:`leader fencing mode ` that affects the leader election process. When the parameter is set to ``soft`` or ``strict``, the leader resigns its leadership if it has less than :ref:`replication_synchro_quorum ` of alive connections to the cluster nodes. The resigning leader receives the status of a :ref:`follower ` in the current election term and becomes read-only." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:628 +msgid "In ``soft`` mode, a connection is considered dead if there are no responses for :ref:`4*replication_timeout ` seconds both on the current leader and the followers." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:631 +msgid "In ``strict`` mode, a connection is considered dead if there are no responses for :ref:`2*replication_timeout ` seconds on the current leader and :ref:`4*replication_timeout ` seconds on the followers. This improves chances that there is only one leader at any time." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:637 +msgid "Fencing applies to the instances that have the :ref:`election_mode ` set to ``candidate`` or ``manual``. To turn off :ref:`leader fencing `, set ``election_fencing_mode`` to ``off``." +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:642 +msgid "Default: 'soft'" +msgstr "" + +#: ../../doc/reference/configuration/cfg_replication.rst:643 +msgid "Environment variable: TT_ELECTION_FENCING_MODE" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:54 +msgid "Networking" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:1 +msgid ":ref:`io_collect_interval `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:2 +msgid ":ref:`net_msg_max `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:3 +msgid ":ref:`readahead `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:4 +msgid ":ref:`iproto_threads `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:10 +msgid "Since version 1.4.9. The instance will sleep for io_collect_interval seconds between iterations of the event loop. Can be used to reduce CPU load in deployments in which the number of client connections is large, but requests are not so frequent (for example, each connection issues just a handful of requests per second)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:18 +msgid "Environment variable: TT_IO_COLLECT_INTERVAL" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:25 +msgid "Since version 1.10.1. To handle messages, Tarantool allocates fibers. To prevent fiber overhead from affecting the whole system, Tarantool restricts how many messages the fibers handle, so that some pending requests are blocked." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:30 +msgid "On powerful systems, increase ``net_msg_max`` and the scheduler will immediately start processing pending requests." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:33 +msgid "On weaker systems, decrease ``net_msg_max`` and the overhead may decrease although this may take some time because the scheduler must wait until already-running requests finish." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:37 +msgid "When ``net_msg_max`` is reached, Tarantool suspends processing of incoming packages until it has processed earlier messages. This is not a direct restriction of the number of fibers that handle network messages, rather it is a system-wide restriction of channel bandwidth. This in turn causes restriction of the number of incoming network messages that the :ref:`transaction processor thread ` handles, and therefore indirectly affects the fibers that handle network messages. (The number of fibers is smaller than the number of messages because messages can be released as soon as they are delivered, while incoming requests might not be processed until some time after delivery.)" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:51 +msgid "On typical systems, the default value (768) is correct." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:54 +msgid "Default: 768" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:55 +msgid "Environment variable: TT_NET_MSG_MAX" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:62 +msgid "Since version 1.6.2. The size of the read-ahead buffer associated with a client connection. The larger the buffer, the more memory an active connection consumes and the more requests can be read from the operating system buffer in a single system call. The rule of thumb is to make sure the buffer can contain at least a few dozen requests. Therefore, if a typical tuple in a request is large, e.g. a few kilobytes or even megabytes, the read-ahead buffer size should be increased. If batched request processing is not used, it’s prudent to leave this setting at its default." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:73 +msgid "Default: 16320" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:74 +msgid "Environment variable: TT_READAHEAD" +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:81 +msgid "Since version :doc:`2.8.1 `. The number of :ref:`network threads `. There can be unusual workloads where the network thread is 100% loaded and the transaction processor thread is not, so the network thread is a bottleneck. In that case set ``iproto_threads`` to 2 or more. The operating system kernel will determine which connection goes to which thread." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:89 +msgid "On typical systems, the default value (1) is correct." +msgstr "" + +#: ../../doc/reference/configuration/cfg_networking.rst:93 +msgid "Environment variable: TT_IPROTO_THREADS" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:59 +msgid "Logging" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:3 +msgid "This section provides information on how to configure options related to logging. You can also use the :ref:`log module ` to configure logging in your application." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:7 +msgid ":ref:`log_level `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:8 +msgid ":ref:`log `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:9 +msgid ":ref:`log_nonblock `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:10 +msgid ":ref:`too_long_threshold `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:11 +msgid ":ref:`log_format `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:12 +msgid ":ref:`log_modules `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:18 +msgid "Since version 1.6.2. Specifies the level of detail the :ref:`log ` has. There are seven levels:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:21 +msgid "1 – ``SYSERROR``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:22 +msgid "2 – ``ERROR``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:23 +msgid "3 – ``CRITICAL``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:24 +msgid "4 – ``WARNING``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:25 +msgid "5 – ``INFO``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:26 +msgid "6 – ``VERBOSE``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:27 +msgid "7 – ``DEBUG``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:29 +msgid "By setting ``log_level``, you can enable logging of all events with severities above or equal to the given level. Tarantool prints logs to the standard error stream by default. This can be changed with the :ref:`log ` configuration parameter." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:36 +msgid "Environment variable: TT_LOG_LEVEL" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:40 +msgid "Prior to Tarantool 1.7.5 there were only six levels and ``DEBUG`` was level 6. Starting with Tarantool 1.7.5, ``VERBOSE`` is level 6 and ``DEBUG`` is level 7. ``VERBOSE`` is a new level for monitoring repetitive events which would cause too much log writing if ``INFO`` were used instead." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:49 +msgid "Since version 1.7.4. By default, Tarantool sends the log to the standard error stream (``stderr``). If ``log`` is specified, Tarantool can send the log to a:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:53 +msgid "file" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:55 +msgid "pipe" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:57 +msgid "system logger" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:59 +msgid "Example 1: sending the log to the ``tarantool.log`` file." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:61 +msgid "box.cfg{log = 'tarantool.log'}\n" +"-- or\n" +"box.cfg{log = 'file:tarantool.log'}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:67 +msgid "This opens the file ``tarantool.log`` for output on the server's default directory. If the ``log`` string has no prefix or has the prefix \"file:\", then the string is interpreted as a file path." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:71 +msgid "Example 2: sending the log to a pipe." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:73 +msgid "box.cfg{log = '| cronolog tarantool.log'}\n" +"-- or\n" +"box.cfg{log = 'pipe: cronolog tarantool.log'}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:79 +msgid "This starts the program `cronolog `_ when the server starts, and sends all log messages to the standard input (``stdin``) of ``cronolog``. If the ``log`` string begins with '|' or has the prefix \"pipe:\", then the string is interpreted as a Unix `pipeline `_." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:85 +msgid "Example 3: sending the log to syslog." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:87 +msgid "box.cfg{log = 'syslog:identity=tarantool'}\n" +"-- or\n" +"box.cfg{log = 'syslog:facility=user'}\n" +"-- or\n" +"box.cfg{log = 'syslog:identity=tarantool,facility=user'}\n" +"-- or\n" +"box.cfg{log = 'syslog:server=unix:/dev/log'}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:97 +msgid "If the ``log`` string begins with \"syslog:\", then it is interpreted as a message for the `syslogd `_ program, which normally is running in the background on any Unix-like platform. The setting can be ``syslog:``, ``syslog:facility=...``, ``syslog:identity=...``, ``syslog:server=...``, or a combination." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:104 +msgid "The ``syslog:identity`` setting is an arbitrary string, which is placed at the beginning of all messages. The default value is \"tarantool\"." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:107 +msgid "The ``syslog:facility`` setting is currently ignored but will be used in the future. The value must be one of the `syslog `_ keywords, which tell syslogd where the message should go. The possible values are: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0, local1, local2, local3, local4, local5, local6, local7. The default value is: local7." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:114 +msgid "The ``syslog:server`` setting is the locator for the syslog server. It can be a Unix socket path beginning with \"unix:\", or an ipv4 port number. The default socket value is: ``dev/log`` (on Linux) or ``/var/run/syslog`` (on macOS). The default port value is: 514, the UDP port." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:119 +msgid "When logging to a file, Tarantool reopens the log on `SIGHUP `_. When log is a program, its PID is saved in the :ref:`log.pid ` variable. You need to send it a signal to rotate logs." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:125 +msgid "Environment variable: TT_LOG" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:132 +msgid "Since version 1.7.4. If ``log_nonblock`` equals **true**, Tarantool does not block during logging when the system is not ready for writing, and drops the message instead. If :ref:`log_level ` is high, and many messages go to the log, setting ``log_nonblock`` to **true** may improve logging performance at the cost of some log messages getting lost." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:139 +msgid "This parameter has effect only if :ref:`log ` is configured to send logs to a pipe or system logger. The default ``log_nonblock`` value is **nil**, which means that blocking behavior corresponds to the logger type:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:144 +msgid "**false** for ``stderr`` and file loggers." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:146 +msgid "**true** for a pipe and system logger." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:148 +msgid "This is a behavior change: in earlier versions of the Tarantool server, the default value was **true**." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:153 +msgid "Environment variable: TT_LOG_NONBLOCK" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:160 +msgid "Since version 1.6.2. If processing a request takes longer than the given value (in seconds), warn about it in the log. Has effect only if :ref:`log_level ` is greater than or equal to 4 (WARNING)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:166 +msgid "Default: 0.5" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:167 +msgid "Environment variable: TT_TOO_LONG_THRESHOLD" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:174 +msgid "Since version 1.7.6. Log entries have two possible formats:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:176 +msgid "'plain' (the default), or" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:177 +msgid "'json' (with more detail and with JSON labels)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:179 +msgid "Here is what a log entry looks like if ``box.cfg{log_format='plain'}``:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:181 +msgid "2017-10-16 11:36:01.508 [18081] main/101/interactive I> set 'log_format' configuration option to \"plain\"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:185 +msgid "Here is what a log entry looks like if ``box.cfg{log_format='json'}``:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:187 +msgid "{\"time\": \"2017-10-16T11:36:17.996-0600\",\n" +"\"level\": \"INFO\",\n" +"\"message\": \"set 'log_format' configuration option to \\\"json\\\"\",\n" +"\"pid\": 18081,|\n" +"\"cord_name\": \"main\",\n" +"\"fiber_id\": 101,\n" +"\"fiber_name\": \"interactive\",\n" +"\"file\": \"builtin\\/box\\/load_cfg.lua\",\n" +"\"line\": 317}" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:199 +msgid "The ``log_format='plain'`` entry has a time value, process ID, cord name, :ref:`fiber_id `, :ref:`fiber_name `, :ref:`log level `, and message." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:204 +msgid "The ``log_format='json'`` entry has the same fields along with their labels, and in addition has the file name and line number of the Tarantool source." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:208 +msgid "Default: 'plain'" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:209 +msgid "Environment variable: TT_LOG_FORMAT" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:217 +msgid "Since version :doc:`2.11.0 `. Configure the specified log levels (:ref:`log_level `) for different modules." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:220 +msgid "You can specify a logging level for the following module types:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:222 +msgid "Modules (files) that use the default logger. Example: :ref:`Set log levels for files that use the default logger `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:225 +msgid "Modules that use custom loggers created using the :ref:`log.new() ` function. Example: :ref:`Set log levels for modules that use custom loggers `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:228 +msgid "The ``tarantool`` module that enables you to configure the logging level for Tarantool core messages. Specifically, it configures the logging level for messages logged from non-Lua code, including C modules. Example: :ref:`Set a log level for C modules `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:231 +msgid "Type: table" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:232 +msgid "Default: blank" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:233 +msgid "Environment variable: TT_LOG_MODULES" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:240 +msgid "**Example 1: Set log levels for files that use the default logger**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:242 +msgid "Suppose you have two identical modules placed by the following paths: ``test/logging/module1.lua`` and ``test/logging/module2.lua``. These modules use the default logger and look as follows:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:245 +msgid "return {\n" +" say_hello = function()\n" +" local log = require('log')\n" +" log.info('Info message from module1')\n" +" end\n" +"}\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:249 +msgid "To load these modules in your application, you need to add the corresponding ``require`` directives:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:251 +msgid "module1 = require('test.logging.module1')\n" +"module2 = require('test.logging.module2')\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:256 +msgid "To configure logging levels, you need to provide module names corresponding to paths to these modules. In the example below, the ``box_cfg`` variable contains logging settings that can be passed to the ``box.cfg()`` function:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:259 +msgid "box_cfg = { log_modules = {\n" +" ['test.logging.module1'] = 'verbose',\n" +" ['test.logging.module2'] = 'error' }\n" +"}\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:264 +msgid "Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1.say_hello()`` shows a message but ``module2.say_hello()`` is swallowed:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:266 +msgid "-- Prints 'info' messages --\n" +"module1.say_hello()\n" +"--[[\n" +"[92617] main/103/interactive/test.logging.module1 I> Info message from module1\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Swallows 'info' messages --\n" +"module2.say_hello()\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:273 +msgid "**Example 2: Set log levels for modules that use custom loggers**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:275 +msgid "In the example below, the ``box_cfg`` variable contains logging settings that can be passed to the ``box.cfg()`` function. This example shows how to set the ``verbose`` level for ``module1`` and the ``error`` level for ``module2``:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:278 +msgid "box_cfg = { log_level = 'warn',\n" +" log_modules = {\n" +" module1 = 'verbose',\n" +" module2 = 'error' }\n" +"}\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:283 +msgid "To create custom loggers, call the :ref:`log.new() ` function:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:285 +msgid "-- Creates new loggers --\n" +"module1_log = require('log').new('module1')\n" +"module2_log = require('log').new('module2')\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:290 +msgid "Given that ``module1`` has the ``verbose`` logging level and ``module2`` has the ``error`` level, calling ``module1_log.info()`` shows a message but ``module2_log.info()`` is swallowed:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:292 +msgid "-- Prints 'info' messages --\n" +"module1_log.info('Info message from module1')\n" +"--[[\n" +"[16300] main/103/interactive/module1 I> Info message from module1\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Swallows 'debug' messages --\n" +"module1_log.debug('Debug message from module1')\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Swallows 'info' messages --\n" +"module2_log.info('Info message from module2')\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:299 +msgid "**Example 3: Set a log level for C modules**" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:301 +msgid "In the example below, the ``box_cfg`` variable contains logging settings that can be passed to the ``box.cfg()`` function. This example shows how to set the ``info`` level for the ``tarantool`` module:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:304 +msgid "box_cfg = { log_level = 'warn',\n" +" log_modules = { tarantool = 'info' } }\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:309 +msgid "The specified level affects messages logged from C modules:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:311 +msgid "ffi = require('ffi')\n" +"\n" +"-- Prints 'info' messages --\n" +"ffi.C._say(ffi.C.S_INFO, nil, 0, nil, 'Info message from C module')\n" +"--[[\n" +"[6024] main/103/interactive I> Info message from C module\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Swallows 'debug' messages --\n" +"ffi.C._say(ffi.C.S_DEBUG, nil, 0, nil, 'Debug message from C module')\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:316 +msgid "The example above uses the `LuaJIT ffi library `_ to call C functions provided by the ``say`` module." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:323 +msgid "Logging example" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:325 +msgid "This example illustrates how \"rotation\" works, that is, what happens when the server instance is writing to a log and signals are used when archiving it." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:328 +msgid "Start with two terminal shells: Terminal #1 and Terminal #2." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:330 +msgid "In Terminal #1, start an interactive Tarantool session. Then, use the ``log`` property to send logs to `Log_file` and call ``log.info`` to put a message in the log file." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:334 +msgid "box.cfg{log='Log_file'}\n" +"log = require('log')\n" +"log.info('Log Line #1')" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:340 +msgid "In Terminal #2, use the ``mv`` command to rename the log file to `Log_file.bak`." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:2112 +msgid "mv Log_file Log_file.bak" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:347 +msgid "As a result, the next log message will go to `Log_file.bak`." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:349 +msgid "Go back to Terminal #1 and put a message \"Log Line #2\" in the log file." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:351 +msgid "log.info('Log Line #2')" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:355 +msgid "In Terminal #2, use ``ps`` to find the process ID of the Tarantool instance." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:2127 +msgid "ps -A | grep tarantool" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:362 +msgid "In Terminal #2, execute ``kill -HUP`` to send a SIGHUP signal to the Tarantool instance. Tarantool will open `Log_file` again, and the next log message will go to `Log_file`." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:2135 +msgid "kill -HUP *process_id*" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:370 +msgid "The same effect could be accomplished by calling :ref:`log.rotate `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:372 +msgid "In Terminal #1, put a message \"Log Line #3\" in the log file." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:374 +msgid "log.info('Log Line #3')" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:378 +msgid "In Terminal #2, use ``less`` to examine files. `Log_file.bak` will have the following lines ..." +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:2151 +msgid "2015-11-30 15:13:06.373 [27469] main/101/interactive I> Log Line #1`\n" +"2015-11-30 15:14:25.973 [27469] main/101/interactive I> Log Line #2`" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:387 +msgid "... and `Log_file` will look like this:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_logging.rst:2159 +msgid "log file has been reopened\n" +"2015-11-30 15:15:32.629 [27469] main/101/interactive I> Log Line #3" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:64 +msgid "Feedback" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:3 +msgid ":ref:`feedback_enabled `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:4 +msgid ":ref:`feedback_host `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:5 +msgid ":ref:`feedback_interval `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:7 +msgid "By default, a Tarantool daemon sends a small packet once per hour, to ``https://feedback.tarantool.io``. The packet contains three values from :ref:`box.info `: ``box.info.version``, ``box.info.uuid``, and ``box.info.cluster_uuid``. By changing the feedback configuration parameters, users can adjust or turn off this feature." +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:18 +msgid "Since version 1.10.1. Whether to send feedback." +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:20 +msgid "If this is set to ``true``, feedback will be sent as described above. If this is set to ``false``, no feedback will be sent." +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:25 +msgid "Environment variable: TT_FEEDBACK_ENABLED" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:32 +msgid "Since version 1.10.1. The address to which the packet is sent. Usually the recipient is Tarantool, but it can be any URL." +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:36 +msgid "Default: ``https://feedback.tarantool.io``" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:37 +msgid "Environment variable: TT_FEEDBACK_HOST" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:44 +msgid "Since version 1.10.1. The number of seconds between sendings, usually 3600 (1 hour)." +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:47 +msgid "Default: 3600" +msgstr "" + +#: ../../doc/reference/configuration/cfg_feedback.rst:48 +msgid "Environment variable: TT_FEEDBACK_INTERVAL" +msgstr "" + +#: ../../doc/reference/configuration/index.rst:69 +msgid "Deprecated parameters" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:3 +msgid "These parameters are deprecated since Tarantool version 1.7.4:" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:5 +msgid ":ref:`coredump `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:6 +msgid ":ref:`logger `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:7 +msgid ":ref:`logger_nonblock `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:8 +msgid ":ref:`panic_on_snap_error `," +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:9 +msgid ":ref:`panic_on_wal_error `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:10 +msgid ":ref:`replication_source `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:11 +msgid ":ref:`slab_alloc_arena `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:12 +msgid ":ref:`slab_alloc_maximal `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:13 +msgid ":ref:`slab_alloc_minimal `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:14 +msgid ":ref:`snap_dir `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:15 +msgid ":ref:`snapshot_count `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:16 +msgid ":ref:`snapshot_period `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:17 +msgid ":ref:`rows_per_wal `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:18 +msgid ":ref:`election_fencing_enabled `" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:24 +msgid "**Deprecated**, do not use." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:34 +msgid "**Deprecated** in favor of :ref:`log `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:42 +msgid "**Deprecated** in favor of :ref:`log_nonblock `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:50 +#: ../../doc/reference/configuration/cfg_deprecated.rst:64 +msgid "**Deprecated** in favor of :ref:`force_recovery `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:53 +msgid "If there is an error while reading a snapshot file (at server instance start), abort." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:75 +msgid "**Deprecated** in favor of :ref:`replication `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:84 +msgid "**Deprecated** in favor of :ref:`memtx_memory `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:87 +msgid "How much memory Tarantool allocates to actually store tuples, **in gigabytes**. When the limit is reached, INSERT or UPDATE requests begin failing with error :errcode:`ER_MEMORY_ISSUE`. While the server does not go beyond the defined limit to allocate tuples, there is additional memory used to store indexes and connection information. Depending on actual configuration and workload, Tarantool can consume up to 20% more than the limit set here." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:95 +msgid "Default: 1.0" +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:102 +msgid "**Deprecated** in favor of :ref:`memtx_max_tuple_size `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:111 +msgid "**Deprecated** in favor of :ref:`memtx_min_tuple_size `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:120 +msgid "**Deprecated** in favor of :ref:`memtx_dir `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:128 +msgid "**Deprecated** in favor of :ref:`checkpoint_interval `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:137 +msgid "**Deprecated** in favor of :ref:`checkpoint_count `. The parameter was only renamed, while the type, values and semantics remained intact." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:146 +msgid "**Deprecated** in favor of :ref:`wal_max_size `. The parameter does not allow to properly limit size of WAL logs." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:154 +msgid "**Deprecated** in Tarantool v2.11 in favor of :ref:`election_fencing_mode `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:157 +msgid "The parameter does not allow using the ``strict`` fencing mode. Setting to ``true`` is equivalent to setting the ``soft`` :ref:`election_fencing_mode `. Setting to ``false`` is equivalent to setting the ``off`` :ref:`election_fencing_mode `." +msgstr "" + +#: ../../doc/reference/configuration/cfg_deprecated.rst:165 +msgid "Environment variable: TT_ELECTION_FENCING_ENABLED" +msgstr "" diff --git a/locale/en/reference/index.pot b/locale/en/reference/index.pot new file mode 100644 index 0000000000..0e601ea6bd --- /dev/null +++ b/locale/en/reference/index.pot @@ -0,0 +1,21 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/index.rst:8 +msgid "Reference" +msgstr "" diff --git a/locale/en/reference/lua_tips.pot b/locale/en/reference/lua_tips.pot new file mode 100644 index 0000000000..4616ebd04d --- /dev/null +++ b/locale/en/reference/lua_tips.pot @@ -0,0 +1,136 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/lua_tips.rst:5 +msgid "Tips on Lua syntax" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:7 +msgid "The Lua syntax for :ref:`data-manipulation functions ` can vary. Here are examples of the variations with ``select()`` requests. The same rules exist for the other data-manipulation functions." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:11 +msgid "Every one of the examples does the same thing: select a tuple set from a space named 'tester' where the primary-key field value equals 1. For these examples, we assume that the numeric id of 'tester' is 512, which happens to be the case in our sandbox example only." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:20 +msgid "Object reference variations" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:22 +msgid "First, there are three **object reference variations**:" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:24 +msgid "-- #1 module . submodule . name\n" +"tarantool> box.space.tester:select{1}\n" +"-- #2 replace name with a literal in square brackets\n" +"tarantool> box.space['tester']:select{1}\n" +"-- #3 use a variable for the entire object reference\n" +"tarantool> s = box.space.tester\n" +"tarantool> s:select{1}" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:34 +msgid "Examples in this manual usually have the \":samp:`box.space.{tester}:`\" form (#1). However, this is a matter of user preference and all the variations exist in the wild." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:38 +msgid "Also, descriptions in this manual use the syntax \"``space_object:``\" for references to objects which are spaces, and \"``index_object:``\" for references to objects which are indexes (for example :samp:`box.space.{tester}.index.{primary}:`)." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:47 +msgid "Parameter variations" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:49 +msgid "Then, there are seven **parameter variations**:" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:51 +msgid "-- #1\n" +"tarantool> box.space.tester:select{1}\n" +"-- #2\n" +"tarantool> box.space.tester:select({1})\n" +"-- #3\n" +"tarantool> box.space.tester:select(1)\n" +"-- #4\n" +"tarantool> box.space.tester.select(box.space.tester,1)\n" +"-- #5\n" +"tarantool> box.space.tester:select({1},{iterator='EQ'})\n" +"-- #6\n" +"tarantool> variable = 1\n" +"tarantool> box.space.tester:select{variable}\n" +"-- #7\n" +"tarantool> variable = {1}\n" +"tarantool> box.space.tester:select(variable)" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:70 +msgid "Lua allows to omit parentheses ``()`` when invoking a function if its only argument is a Lua table, and we use it sometimes in our examples. This is why ``select{1}`` is equivalent to ``select({1})``. Literal values such as ``1`` (a scalar value) or ``{1}`` (a Lua table value) may be replaced by variable names, as in examples #6 and #7." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:76 +msgid "Although there are special cases where braces can be omitted, they are preferable because they signal \"Lua table\". Examples and descriptions in this manual have the ``{1}`` form. However, this too is a matter of user preference and all the variations exist in the wild." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:85 +msgid "Rules for object names" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:87 +msgid "Database objects have loose **rules for names**: the maximum length is 65000 bytes (not characters), and almost any legal Unicode character is allowed, including spaces, ideograms and punctuation." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:92 +msgid "In those cases, to prevent confusion with Lua operators and separators, object references should have the literal-in-square-brackets form (#2), or the variable form (#3). For example:" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:96 +msgid "tarantool> box.space['1*A']:select{1}\n" +"tarantool> s = box.space['1*A !@$%^&*()_+12345678901234567890']\n" +"tarantool> s:select{1}" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:102 +msgid "Disallowed:" +msgstr "" + +#: ../../doc/reference/lua_tips.rst:104 +msgid "characters which are unassigned code points," +msgstr "" + +#: ../../doc/reference/lua_tips.rst:105 +msgid "line and paragraph separators," +msgstr "" + +#: ../../doc/reference/lua_tips.rst:106 +msgid "control characters," +msgstr "" + +#: ../../doc/reference/lua_tips.rst:107 +msgid "the replacement character (U+FFFD)." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:109 +msgid "Not recommended: characters which cannot be displayed." +msgstr "" + +#: ../../doc/reference/lua_tips.rst:111 +msgid "Names are \"case sensitive\", so 'A' and 'a' are not the same." +msgstr "" diff --git a/locale/en/reference/reference_lua/box.pot b/locale/en/reference/reference_lua/box.pot new file mode 100644 index 0000000000..19e9a460db --- /dev/null +++ b/locale/en/reference/reference_lua/box.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box.rst:5 +msgid "Module box" +msgstr "" + +#: ../../doc/reference/reference_lua/box.rst:7 +msgid "As well as executing Lua chunks or defining your own functions, you can exploit Tarantool's storage functionality with the ``box`` module and its submodules." +msgstr "" + +#: ../../doc/reference/reference_lua/box.rst:10 +msgid "Every submodule contains one or more Lua functions. A few submodules contain members as well as functions. The functions allow data definition (create alter drop), data manipulation (insert delete update upsert select replace), and introspection (inspecting contents of spaces, accessing server configuration)." +msgstr "" + +#: ../../doc/reference/reference_lua/box.rst:15 +msgid "To catch errors that functions in ``box`` submodules may throw, use :ref:`pcall `." +msgstr "" + +#: ../../doc/reference/reference_lua/box.rst:17 +msgid "The contents of the ``box`` module can be inspected at runtime with ``box``, with no arguments. The ``box`` module contains:" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_backup.pot b/locale/en/reference/reference_lua/box_backup.pot new file mode 100644 index 0000000000..85ebdfa346 --- /dev/null +++ b/locale/en/reference/reference_lua/box_backup.pot @@ -0,0 +1,53 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_backup.rst:3 +msgid "Submodule box.backup" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:5 +msgid "The box.backup submodule contains two functions that are helpful for :ref:`backup ` in certain situations." +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:8 +msgid "Below is a list of all ``box.backup`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:19 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:20 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:22 +msgid ":doc:`./box_backup/start`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:23 +msgid "Ask server to suspend activities before the removal of outdated backups" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:25 +msgid ":doc:`./box_backup/stop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup.rst:26 +msgid "Inform server that normal operations may resume" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_backup/start.pot b/locale/en/reference/reference_lua/box_backup/start.pot new file mode 100644 index 0000000000..e278b73073 --- /dev/null +++ b/locale/en/reference/reference_lua/box_backup/start.pot @@ -0,0 +1,55 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:5 +msgid "box.backup.start()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:9 +msgid "Informs the server that activities related to the removal of outdated backups must be suspended." +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:12 +msgid "To guarantee an opportunity to copy these files, Tarantool will not delete them. But there will be no read-only mode and checkpoints will continue by schedule as usual." +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:16 +msgid "optional argument starting with Tarantool 1.10.1 that indicates the checkpoint to use relative to the latest checkpoint. For example ``n = 0`` means “backup will be based on the latest checkpoint”, ``n = 1`` means \"backup will be based on the first checkpoint before the latest checkpoint (counting backwards)\", and so on. The default value for n is zero." +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:23 +msgid "**Return:** a table with the names of snapshot and vinyl files that should be copied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/start.rst:28 +msgid "tarantool> box.backup.start()\n" +"---\n" +"- - ./00000000000000000015.snap\n" +" - ./00000000000000000000.vylog\n" +" - ./513/0/00000000000000000002.index\n" +" - ./513/0/00000000000000000002.run\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_backup/stop.pot b/locale/en/reference/reference_lua/box_backup/stop.pot new file mode 100644 index 0000000000..6d89d41619 --- /dev/null +++ b/locale/en/reference/reference_lua/box_backup/stop.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_backup/stop.rst:5 +msgid "box.backup.stop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_backup/stop.rst:9 +msgid "Informs the server that normal operations may resume." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_cfg.pot b/locale/en/reference/reference_lua/box_cfg.pot new file mode 100644 index 0000000000..f30b3742a4 --- /dev/null +++ b/locale/en/reference/reference_lua/box_cfg.pot @@ -0,0 +1,130 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_cfg.rst:5 +msgid "Submodule box.cfg" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:9 +msgid "The ``box.cfg`` submodule is used for specifying :ref:`server configuration parameters `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:12 +msgid "To view the current configuration, say ``box.cfg`` without braces:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:14 +msgid "tarantool> box.cfg\n" +"---\n" +"- checkpoint_count: 2\n" +" too_long_threshold: 0.5\n" +" slab_alloc_factor: 1.05\n" +" memtx_max_tuple_size: 1048576\n" +" background: false\n" +" <...>\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:26 +msgid "To set particular parameters, use the following syntax: ``box.cfg{key = value [, key = value ...]}`` (further referred to as ``box.cfg{...}`` for short). For example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:29 +msgid "tarantool> box.cfg{listen = 3301}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:33 +msgid "Parameters that are not specified in the ``box.cfg{...}`` call explicitly will be set to the :ref:`default values`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:36 +msgid "If you say ``box.cfg{}`` with no parameters, Tarantool applies the following default settings to all the parameters:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:41 +msgid "tarantool> box.cfg{}\n" +"tarantool> box.cfg -- sorted in the alphabetic order\n" +"---\n" +"- background = false\n" +" checkpoint_count = 2\n" +" checkpoint_interval = 3600\n" +" checkpoint_wal_threshold = 1000000000000000000\n" +" coredump = false\n" +" custom_proc_title = nil\n" +" feedback_enabled = true\n" +" feedback_host = 'https://feedback.tarantool.io'\n" +" feedback_interval = 3600\n" +" force_recovery = false\n" +" hot_standby = false\n" +" instance_uuid = nil -- generated automatically\n" +" io_collect_interval = nil\n" +" iproto_threads = 1\n" +" listen = nil\n" +" log = nil\n" +" log_format = plain\n" +" log_level = 5\n" +" log_nonblock = true\n" +" memtx_dir = '.'\n" +" memtx_max_tuple_size = 1024 * 1024\n" +" memtx_memory = 256 * 1024 *1024\n" +" memtx_min_tuple_size = 16\n" +" net_msg_max = 768\n" +" pid_file = nil\n" +" readahead = 16320\n" +" read_only = false\n" +" replicaset_uuid = nil -- generated automatically\n" +" replication = nil\n" +" replication_anon = false\n" +" replication_connect_timeout = 30\n" +" replication_skip_conflict = false\n" +" replication_sync_lag = 10\n" +" replication_sync_timeout = 300\n" +" replication_timeout = 1\n" +" slab_alloc_factor = 1.05\n" +" snap_io_rate_limit = nil\n" +" sql_cache_size = 5242880\n" +" strip_core = true\n" +" too_long_threshold = 0.5\n" +" username = nil\n" +" vinyl_bloom_fpr = 0.05\n" +" vinyl_cache = 128 * 1024 * 1024\n" +" vinyl_dir = '.'\n" +" vinyl_max_tuple_size = 1024 * 1024* 1024 * 1024\n" +" vinyl_memory = 128 * 1024 * 1024\n" +" vinyl_page_size = 8 * 1024\n" +" vinyl_range_size = nil\n" +" vinyl_read_threads = 1\n" +" vinyl_run_count_per_level = 2\n" +" vinyl_run_size_ratio = 3.5\n" +" vinyl_timeout = 60\n" +" vinyl_write_threads = 4\n" +" wal_dir = '.'\n" +" wal_dir_rescan_delay = 2\n" +" wal_max_size = 256 * 1024 * 1024\n" +" wal_mode = 'write'\n" +" worker_pool_threads = 4\n" +" work_dir = nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:106 +msgid "The first call to ``box.cfg{...}`` (with or without parameters) initiates Tarantool's database module :ref:`box `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_cfg.rst:109 +msgid "``box.cfg{...}`` is also the command that reloads :ref:`persistent data files ` into RAM upon restart once we have data." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl.pot b/locale/en/reference/reference_lua/box_ctl.pot new file mode 100644 index 0000000000..d9fed7d81d --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl.pot @@ -0,0 +1,129 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-11 13:03+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl.rst:5 +msgid "Submodule box.ctl" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:7 +msgid "The ``wait_ro`` (wait until read-only) and ``wait_rw`` (wait until read-write) functions are useful during server initialization. To see whether a function is already in read-only or read-write mode, check :ref:`box.info.ro `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:11 +msgid "A particular use is for :doc:`box.once() `. For example, when a replica is initializing, it may call a ``box.once()`` function while the server is still in read-only mode, and fail to make changes that are necessary only once before the replica is fully initialized. This could cause conflicts between a master and a replica if the master is in read-write mode and the replica is in read-only mode. Waiting until \"read only mode = false\" solves this problem." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:21 +msgid "Below is a list of all ``box.ctl`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:32 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:33 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:35 +msgid ":doc:`./box_ctl/wait_ro`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:36 +msgid "Wait until ``box.info.ro`` is true" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:38 +msgid ":doc:`./box_ctl/wait_rw`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:39 +msgid "Wait until ``box.info.ro`` is false" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:41 +msgid ":doc:`./box_ctl/on_schema_init`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:42 +msgid "Create a \"schema_init trigger\"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:44 +msgid ":doc:`./box_ctl/on_shutdown`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:45 +msgid "Create a \"shutdown trigger\"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:47 +msgid ":doc:`./box_ctl/on_recovery_state`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:48 +msgid "Create a trigger executed on different stages of a node recovery or initial configuration" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:50 +msgid ":doc:`./box_ctl/on_election`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:51 +msgid "Create a :ref:`trigger ` executed every time the current state of a replica set node in regard to :ref:`leader election ` changes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:53 +msgid ":doc:`./box_ctl/set_on_shutdown_timeout`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:54 +msgid "Set a timeout in seconds for the ``on_shutdown`` trigger" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:56 +msgid ":doc:`./box_ctl/is_recovery_finished`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:57 +msgid "Check if recovery has finished" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:59 +msgid ":doc:`./box_ctl/promote`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:60 +msgid "Wait, then choose replication leader" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:62 +msgid ":doc:`./box_ctl/demote`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:63 +msgid "Revoke the leader role from the instance" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:65 +msgid ":doc:`./box_ctl/make_bootstrap_leader`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl.rst:66 +msgid "Make the instance a bootstrap leader of a replica set" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/demote.pot b/locale/en/reference/reference_lua/box_ctl/demote.pot new file mode 100644 index 0000000000..155482cff8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/demote.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:4 +msgid "box.ctl.demote()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:8 +msgid "Since version :doc:`2.10.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:10 +msgid "Revoke the leader role from the instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:12 +msgid "On :ref:`synchronous transaction queue owner `, the function works in the following way:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:14 +msgid "If :ref:`box.cfg.election_mode ` is ``off``, the function writes a ``DEMOTE`` request to WAL. The ``DEMOTE`` request clears the ownership of the synchronous transaction queue, while the ``PROMOTE`` request assigns it to a new instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:19 +msgid "If :ref:`box.cfg.election_mode ` is enabled in any mode, then the function makes the instance start a new term and give up the leader role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:22 +msgid "On instances that are not queue owners, the function does nothing and returns immediately." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:24 +msgid "Parameters: none" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/demote.rst:26 +msgid "nil" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/is_recovery_finished.pot b/locale/en/reference/reference_lua/box_ctl/is_recovery_finished.pot new file mode 100644 index 0000000000..9f52e4d68a --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/is_recovery_finished.pot @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:5 +msgid "box.ctl.is_recovery_finished()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:11 +msgid "Since version :doc:`2.5.3 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:13 +msgid "Check whether the :ref:`recovery process ` has finished. Until it has finished, space changes such as ``insert`` or ``update`` are not possible." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:16 +msgid "``true`` if recovery has finished, otherwise ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/is_recovery_finished.rst:17 +msgid "boolean" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/make_bootstrap_leader.pot b/locale/en/reference/reference_lua/box_ctl/make_bootstrap_leader.pot new file mode 100644 index 0000000000..2aeddea890 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/make_bootstrap_leader.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-11 13:03+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/make_bootstrap_leader.rst:4 +msgid "box.ctl.make_bootstrap_leader()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/make_bootstrap_leader.rst:8 +msgid "**Since:** :doc:`3.0.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/make_bootstrap_leader.rst:10 +msgid "Make the instance a bootstrap leader of a replica set." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/make_bootstrap_leader.rst:12 +msgid "To be able to make the instance a bootstrap leader manually, the :ref:`replication.bootstrap_strategy ` configuration option should be set to ``supervised``. In this case, the instances do not choose a bootstrap leader automatically but wait for it to be appointed manually. Configuration fails if no bootstrap leader is appointed during a :ref:`replication.connect_timeout `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/make_bootstrap_leader.rst:18 +msgid "When a new instance joins a replica set configured with the ``supervised`` bootstrap strategy, this instance doesn't choose the bootstrap leader automatically but joins to the instance on which ``box.ctl.make_bootstrap_leader()`` was executed last time." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/on_election.pot b/locale/en/reference/reference_lua/box_ctl/on_election.pot new file mode 100644 index 0000000000..e9ba17bac3 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/on_election.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:5 +msgid "box.ctl.on_election()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:11 +msgid "**Since:** :doc:`2.10.0 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:13 +msgid "Create a :ref:`trigger ` executed every time the current state of a replica set node in regard to :ref:`leader election ` changes. The current state is available in the :ref:`box.info.election ` table." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:17 +msgid "The trigger doesn't accept any parameters. You can see the changes in ``box.info.election`` and :ref:`box.info.synchro `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:21 +msgid "a trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_election.rst:23 +msgid "``nil`` or a function pointer" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/on_recovery_state.pot b/locale/en/reference/reference_lua/box_ctl/on_recovery_state.pot new file mode 100644 index 0000000000..6c7747a1fd --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/on_recovery_state.pot @@ -0,0 +1,90 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:5 +msgid "box.ctl.on_recovery_state()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:11 +msgid "**Since:** :doc:`2.11.0 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:13 +msgid "Create a :ref:`trigger ` executed on different stages of a node :ref:`recovery ` or initial configuration. Note that you need to set the ``box.ctl.on_recovery_state`` trigger before the initial :ref:`box.cfg ` call." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:16 +msgid "a trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:18 +msgid "``nil`` or a function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:20 +msgid "A registered trigger function is run on each of the supported recovery state and receives the state name as a parameter:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:23 +msgid "``snapshot_recovered``: the node has recovered the snapshot files." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:24 +msgid "``wal_recovered``: the node has recovered the WAL files." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:25 +msgid "``indexes_built``: the node has built secondary indexes for memtx spaces. This stage might come before any actual data is recovered. This means that the indexes are available right after the first tuple is recovered." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:28 +msgid "``synced``: the node has synced with enough remote peers. This means that the node changes the state from :ref:`orphan ` to ``running``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:31 +msgid "All these states are passed during the initial ``box.cfg`` call when recovering from the snapshot and WAL files. Note that the ``synced`` state might be reached after the initial ``box.cfg`` call finishes. For example, if :ref:`replication_sync_timeout ` is set to 0, the node finishes ``box.cfg`` without reaching ``synced`` and stays ``orphan``. Once the node is synced with enough remote peers, the ``synced`` state is reached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:40 +msgid "When bootstrapping a fresh cluster with no data, all the instances in this cluster execute triggers on the same stages for consistency. For example, ``snapshot_recovered`` and ``wal_recovered`` run when the node finishes a cluster's bootstrap or finishes joining to an existing cluster." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:46 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:48 +msgid "The example below shows how to :ref:`log ` a specified message when each state is reached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_recovery_state.rst:50 +msgid "local log = require('log')\n" +"local log_recovery_state = function(state)\n" +" log.info(state .. ' state reached')\n" +"end\n" +"box.ctl.on_recovery_state(log_recovery_state)\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/on_schema_init.pot b/locale/en/reference/reference_lua/box_ctl/on_schema_init.pot new file mode 100644 index 0000000000..5fb8990003 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/on_schema_init.pot @@ -0,0 +1,79 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:5 +msgid "box.ctl.on_schema_init()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:11 +msgid "Create a \"schema_init :ref:`trigger `\". The ``trigger-function`` will be executed when :ref:`box.cfg{} ` happens for the first time. That is, the ``schema_init`` trigger is called before the server's configuration and recovery begins, and therefore ``box.ctl.on_schema_init`` must be called before ``box.cfg`` is called." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:18 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:20 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:23 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:25 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:28 +msgid "A common use is: make a ``schema_init`` trigger function which creates a ``before_replace`` trigger function on a system space. Thus, since system spaces are created when the server starts, the ``before_replace`` triggers will be activated for each tuple in each system space. For example, such a trigger could change the storage engine of a given space, or make a given space :ref:`replica-local ` while a replica is being bootstrapped. Making such a change after ``box.cfg`` is not reliable because other connections might use the database before the change is made." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:38 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:40 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:42 +msgid "Suppose that, before the server is fully up and ready for connections, you want to make sure that the engine of space ``space_name`` is vinyl. So you want to make a trigger that will be activated when a tuple is inserted in the ``_space`` system space. In this case you could end up with a master that has space-name with ``engine='memtx'`` and a replica that has space_name with ``engine='vinyl'``, with the same contents." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_schema_init.rst:51 +msgid "function function_for_before_replace(old, new)\n" +" if old == nil and new ~= nil and new[3] == 'space_name' and new[4] ~= 'vinyl' then\n" +" return new:update{{'=', 4, 'vinyl'}}\n" +" end\n" +"end\n" +"\n" +"box.ctl.on_schema_init(function()\n" +" box.space._space:before_replace(function_for_before_replace)\n" +"end)\n" +"\n" +"box.cfg{replication='master_uri', ...}" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/on_shutdown.pot b/locale/en/reference/reference_lua/box_ctl/on_shutdown.pot new file mode 100644 index 0000000000..27c9626e71 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/on_shutdown.pot @@ -0,0 +1,53 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:5 +msgid "box.ctl.on_shutdown()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:11 +msgid "Create a \"shutdown :ref:`trigger `\". The ``trigger-function`` will be executed whenever :ref:`os.exit() ` happens, or when the server is shut down after receiving a SIGTERM or SIGINT or SIGHUP signal (but not after SIGSEGV or SIGABORT or any signal that causes immediate program termination)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:18 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:20 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:23 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:25 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/on_shutdown.rst:28 +msgid "If you want to set a timeout for this trigger, use the :ref:`set_on_shutdown_timeout ` function." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/promote.pot b/locale/en/reference/reference_lua/box_ctl/promote.pot new file mode 100644 index 0000000000..7057283197 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/promote.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:4 +msgid "box.ctl.promote()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:8 +msgid "Since version :doc:`2.6.2 `. Renamed in release :doc:`2.6.3 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:11 +msgid "Wait, then choose new replication leader." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:13 +msgid "For :ref:`synchronous transactions ` it is possible that a new leader will be chosen but the transactions of the old leader have not been completed. Therefore to finalize the transaction, the function ``box.ctl.promote()`` should be called, as mentioned in the notes for :ref:`leader election `. The old name for this function is ``box.ctl.clear_synchro_queue()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:21 +msgid "The :ref:`election state ` should change to ``leader``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:23 +msgid "Parameters: none" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/promote.rst:25 +msgid "nil or function pointer" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/set_on_shutdown_timeout.pot b/locale/en/reference/reference_lua/box_ctl/set_on_shutdown_timeout.pot new file mode 100644 index 0000000000..b7afef1af4 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/set_on_shutdown_timeout.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:5 +msgid "box.ctl.set_on_shutdown_timeout()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:11 +msgid "Set a timeout for the :ref:`on_shutdown ` trigger. If the timeout has expired, the server stops immediately regardless of whether any ``on_shutdown`` triggers are left unexecuted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:15 +msgid "time to wait for the trigger to be completed. The default value is 3 seconds." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst:17 +msgid "nil" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/wait_ro.pot b/locale/en/reference/reference_lua/box_ctl/wait_ro.pot new file mode 100644 index 0000000000..72f1b93d2e --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/wait_ro.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:5 +msgid "box.ctl.wait_ro()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:11 +msgid "Wait until ``box.info.ro`` is true." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:13 +msgid "maximum number of seconds to wait" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:14 +msgid "nil, or error may be thrown due to timeout or fiber cancellation" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:16 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_ro.rst:18 +msgid "tarantool> box.info().ro\n" +"---\n" +"- false\n" +"...\n" +"\n" +"tarantool> n = box.ctl.wait_ro(0.1)\n" +"---\n" +"- error: timed out\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_ctl/wait_rw.pot b/locale/en/reference/reference_lua/box_ctl/wait_rw.pot new file mode 100644 index 0000000000..876b4e2e27 --- /dev/null +++ b/locale/en/reference/reference_lua/box_ctl/wait_rw.pot @@ -0,0 +1,51 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:5 +msgid "box.ctl.wait_rw()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:11 +msgid "Wait until ``box.info.ro`` is false." +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:13 +msgid "maximum number of seconds to wait" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:14 +msgid "nil, or error may be thrown due to timeout or fiber cancellation" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:17 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_ctl/wait_rw.rst:19 +msgid "tarantool> box.ctl.wait_rw(0.1)\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error.pot b/locale/en/reference/reference_lua/box_error.pot new file mode 100644 index 0000000000..ea35180d04 --- /dev/null +++ b/locale/en/reference/reference_lua/box_error.pot @@ -0,0 +1,466 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error.rst:4 +msgid "Submodule box.error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:6 +msgid "The ``box.error`` submodule can be used to work with errors in your application. For example, you can get the information about the last error raised by Tarantool or raise custom errors manually." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:10 +msgid "The difference between raising an error using ``box.error`` and a Lua's built-in `error `_ function is that when the error reaches the client, its error code is preserved. In contrast, a Lua error would always be presented to the client as :errcode:`ER_PROC_LUA`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:18 +msgid "To learn how to handle errors in your application, see the :ref:`Handling errors ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:24 +msgid "Creating an error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:26 +msgid "You can create an error object using the :ref:`box.error.new() ` function. The created object can be passed to :ref:`box.error() ` to raise the error. You can also raise the error using :ref:`error_object:raise() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:30 +msgid "The example below shows how to create and raise the error with the specified code and reason." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:32 +msgid "local custom_error = box.error.new({ code = 500,\n" +" reason = 'Internal server error' })\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:38 +msgid "``box.error.new()`` provides different overloads for creating an error object with different parameters. These overloads are similar to the ``box.error()`` overloads described in the :ref:`next section `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:45 +msgid "Raising an error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:47 +msgid "To raise an error, call the :ref:`box.error() ` function. This function can accept the specified error parameters or an error object :ref:`created using box.error.new() `. In both cases, you can use ``box.error()`` to raise the following error types:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:51 +msgid "A custom error with the specified reason, code, and type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:52 +msgid "A predefined Tarantool error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:58 +msgid "Custom error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:60 +msgid "The following ``box.error()`` overloads are available for raising a custom error:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:62 +msgid ":ref:`box.error({ reason = string[, code = number, type = string] }) ` accepts a Lua table containing the error reason, code, and type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:63 +msgid ":ref:`box.error(type, reason[, args]) ` accepts the error type, its reason, and optional arguments passed to a reason's string." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:67 +msgid "The same overloads are available for :ref:`box.error.new() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:73 +msgid "box.error({ reason = string[, ...] })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:75 +msgid "In the example below, ``box.error()`` accepts a Lua table with the specified error code and reason:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:77 +msgid "box.error { code = 500,\n" +" reason = 'Custom server error' }\n" +"--[[\n" +"---\n" +"- error: Custom server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:83 +msgid "The next example shows how to specify a custom error type:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:85 +msgid "box.error { code = 500,\n" +" reason = 'Internal server error',\n" +" type = 'CustomInternalError' }\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:91 +msgid "When a custom type is specified, it is returned in the :ref:`error_object.type ` attribute. When it is not specified, ``error_object.type`` returns one of the built-in errors, such as ``ClientError`` or ``OutOfMemory``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:98 +msgid "box.error(type, reason[, ...])" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:100 +msgid "This example shows how to raise an error with the type and reason specified in the ``box.error()`` arguments:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:102 +msgid "box.error('CustomConnectionError', 'cannot connect to the given port')\n" +"--[[\n" +"---\n" +"- error: cannot connect to the given port\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:108 +msgid "You can also use a format string to compose an error reason:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:110 +msgid "box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080)\n" +"--[[\n" +"---\n" +"- error: client cannot connect to the port 8080\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:121 +msgid "Tarantool error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:123 +msgid "The :ref:`box.error(code[, ...]) ` overload raises a predefined :ref:`Tarantool error ` specified by its identifier. The error code defines the error message format and the number of required arguments. In the example below, no arguments are passed for the ``box.error.READONLY`` error code:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:128 +msgid "box.error(box.error.READONLY)\n" +"--[[\n" +"---\n" +"- error: Can't modify data on a read-only instance\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:134 +msgid "For the ``box.error.NO_SUCH_USER`` error code, you need to pass one argument:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:136 +msgid "box.error(box.error.NO_SUCH_USER, 'John')\n" +"--[[\n" +"---\n" +"- error: User 'John' is not found\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:142 +msgid "``box.error.CREATE_SPACE`` requires two arguments:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:144 +msgid "box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists')\n" +"--[[\n" +"---\n" +"- error: 'Failed to create space ''my_space'': the space already exists'\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:154 +msgid "Getting the last error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:156 +msgid "To get the last raised error, call :ref:`box.error.last() `:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:158 +msgid "box.error.last()\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:167 +msgid "Obtaining error details" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:169 +msgid "To get error details, call the :ref:`error_object.unpack() `. Error details may include an error code, type, message, and trace." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:172 +msgid "box.error.last():unpack()\n" +"--[[\n" +"---\n" +"- code: 500\n" +" base_type: CustomError\n" +" type: CustomInternalError\n" +" custom_type: CustomInternalError\n" +" message: Internal server error\n" +" trace:\n" +" - file: '[string \"custom_error = box.error.new({ code = 500,...\"]'\n" +" line: 1\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:181 +msgid "Setting the last error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:183 +msgid "You can set the last error explicitly by calling :ref:`box.error.set() `:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:185 +msgid "-- Create two errors --\n" +"local error1 = box.error.new({ code = 500, reason = 'Custom error 1' })\n" +"local error2 = box.error.new({ code = 505, reason = 'Custom error 2' })\n" +"\n" +"-- Raise the first error --\n" +"box.error(error1)\n" +"--[[\n" +"---\n" +"- error: Custom error 1\n" +"...\n" +"--]]\n" +"\n" +"-- Get the last error --\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- Custom error 1\n" +"...\n" +"--]]\n" +"\n" +"-- Set the second error as the last error --\n" +"box.error.set(error2)\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Get the last error --\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- Custom error 2\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:194 +msgid "Error lists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:196 +msgid ":ref:`error_object ` provides the API for organizing errors into lists. To set and get the previous error, use the :ref:`error_object:set_prev() ` method and :ref:`error_object.prev ` attribute." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:199 +msgid "local base_server_error = box.error.new({ code = 500,\n" +" reason = 'Base server error',\n" +" type = 'BaseServerError' })\n" +"local storage_server_error = box.error.new({ code = 507,\n" +" reason = 'Not enough storage',\n" +" type = 'StorageServerError' })\n" +"\n" +"base_server_error:set_prev(storage_server_error)\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"box.error(base_server_error)\n" +"--[[\n" +"---\n" +"- error: Base server error\n" +"...\n" +"--]]\n" +"\n" +"box.error.last().prev:unpack()\n" +"--[[\n" +"---\n" +"- code: 507\n" +" base_type: CustomError\n" +" type: StorageServerError\n" +" custom_type: StorageServerError\n" +" message: Not enough storage\n" +" trace:\n" +" - file: '[string \"storage_server_error = box.error.new({ code =...\"]'\n" +" line: 1\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:205 +msgid "Cycles are not allowed for error lists:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:207 +msgid "storage_server_error:set_prev(base_server_error)\n" +"--[[\n" +"---\n" +"- error: 'builtin/error.lua:120: Cycles are not allowed'\n" +"...\n" +"--]]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:216 +msgid "Setting the previous error does not erase its own previous members:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:218 +msgid "-- e1 -> e2 -> e3 -> e4\n" +"e1:set_prev(e2)\n" +"e2:set_prev(e3)\n" +"e3:set_prev(e4)\n" +"e2:set_prev(e5)\n" +"-- Now there are two lists: e1 -> e2 -> e5 and e3 -> e4" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:227 +msgid "IPROTO also supports stacked diagnostics. See details in :ref:`MessagePack extensions -- The ERROR type `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:233 +msgid "Clearing errors" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:235 +msgid "To clear the errors, call :ref:`box.error.clear() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:237 +msgid "box.error.clear()\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- null\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:248 +msgid "API Reference" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:250 +msgid "Below is a list of ``box.error`` functions and related objects." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:261 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:262 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:264 +msgid ":doc:`./box_error/error`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:265 +msgid "Raise the last error or the error defined by the specified parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:267 +msgid ":doc:`./box_error/last`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:268 +msgid "Get the last raised error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:270 +msgid ":doc:`./box_error/clear`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:271 +msgid "Clear the errors" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:273 +msgid ":doc:`./box_error/new`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:274 +msgid "Create the error but do not raise it" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:276 +msgid ":doc:`./box_error/set`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:277 +msgid "Set the specified error as the last system error explicitly" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:279 +msgid ":doc:`./box_error/error_object`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error.rst:280 +msgid "An object that defines an error" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/clear.pot b/locale/en/reference/reference_lua/box_error/clear.pot new file mode 100644 index 0000000000..b5ba9e2521 --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/clear.pot @@ -0,0 +1,44 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/clear.rst:5 +msgid "box.error.clear()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/clear.rst:9 +msgid "Clear the errors." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/clear.rst:11 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/clear.rst:13 +msgid "box.error.clear()\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- null\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/error.pot b/locale/en/reference/reference_lua/box_error/error.pot new file mode 100644 index 0000000000..9b01209274 --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/error.pot @@ -0,0 +1,200 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/error.rst:4 +msgid "box.error()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:10 +msgid "Raise the last error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:12 +msgid "**See also:** :ref:`box.error.last() `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:18 +msgid "Raise the error defined by :ref:`error_object `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:0 +#: ../../doc/reference/reference_lua/box_error/error.rst:0 +#: ../../doc/reference/reference_lua/box_error/error.rst:0 +#: ../../doc/reference/reference_lua/box_error/error.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:20 +msgid "an error object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:22 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:24 +msgid "local custom_error = box.error.new({ code = 500,\n" +" reason = 'Internal server error' })\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:34 +msgid "Raise the error defined by the specified parameters." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:36 +#: ../../doc/reference/reference_lua/box_error/error.rst:63 +msgid "an error description" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:37 +msgid "(optional) a numeric code for this error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:38 +msgid "(optional) an error type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:40 +msgid "**Example 1**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:42 +msgid "box.error { code = 500,\n" +" reason = 'Custom server error' }\n" +"--[[\n" +"---\n" +"- error: Custom server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:48 +msgid "**Example 2: custom type**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:50 +msgid "box.error { code = 500,\n" +" reason = 'Internal server error',\n" +" type = 'CustomInternalError' }\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:60 +msgid "Raise the error defined by the specified type and description." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:62 +msgid "an error type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:64 +#: ../../doc/reference/reference_lua/box_error/error.rst:91 +msgid "description arguments" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:66 +msgid "**Example 1: without arguments**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:68 +msgid "box.error('CustomConnectionError', 'cannot connect to the given port')\n" +"--[[\n" +"---\n" +"- error: cannot connect to the given port\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:74 +msgid "**Example 2: with arguments**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:76 +msgid "box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080)\n" +"--[[\n" +"---\n" +"- error: client cannot connect to the port 8080\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:86 +msgid "Raise a predefined :ref:`Tarantool error ` specified by its identifier. You can see all Tarantool errors in the `errcode.h `_ file." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:90 +msgid "a pre-defined error identifier; Lua constants that correspond to those Tarantool errors are defined as members of ``box.error``, for example, ``box.error.NO_SUCH_USER == 45``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:93 +msgid "**Example 1: no arguments**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:95 +msgid "box.error(box.error.READONLY)\n" +"--[[\n" +"---\n" +"- error: Can't modify data on a read-only instance\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:101 +msgid "**Example 2: one argument**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:103 +msgid "box.error(box.error.NO_SUCH_USER, 'John')\n" +"--[[\n" +"---\n" +"- error: User 'John' is not found\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:109 +msgid "**Example 3: two arguments**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error.rst:111 +msgid "box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists')\n" +"--[[\n" +"---\n" +"- error: 'Failed to create space ''my_space'': the space already exists'\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/error_object.pot b/locale/en/reference/reference_lua/box_error/error_object.pot new file mode 100644 index 0000000000..07f883cbe5 --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/error_object.pot @@ -0,0 +1,214 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:5 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:61 +msgid "error_object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:9 +msgid "An object that defines an error. ``error_object`` is returned by the following methods:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:12 +msgid ":ref:`box.error.new() `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:13 +msgid ":ref:`box.error.last() `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:19 +msgid "Get error details that may include an error code, type, message, and trace." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:21 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:23 +msgid "box.error.last():unpack()\n" +"--[[\n" +"---\n" +"- code: 500\n" +" base_type: CustomError\n" +" type: CustomInternalError\n" +" custom_type: CustomInternalError\n" +" message: Internal server error\n" +" trace:\n" +" - file: '[string \"custom_error = box.error.new({ code = 500,...\"]'\n" +" line: 1\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:31 +msgid "Depending on the error type, error details may include other attributes, such as :ref:`errno ` or :ref:`reason `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:37 +msgid "Raise the current error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:39 +msgid "**See also:** :ref:`Raising an error `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:45 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:57 +msgid "**Since:** :doc:`2.4.1 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:47 +msgid "Set the previous error for the current one." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:49 +msgid "an error object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:51 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:63 +msgid "**See also:** :ref:`Error lists `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:59 +msgid "Get the previous error for the current one." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:69 +msgid "The error code. This attribute may return a :ref:`custom error ` code or a :ref:`Tarantool error ` code." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:72 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:107 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:153 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:173 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:78 +msgid "The error type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:80 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:90 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:131 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:142 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:82 +msgid "**See also:** :ref:`Custom error `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:88 +msgid "The error message." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:96 +msgid "The error trace." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:98 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:104 +msgid "If the error is a system error (for example, a socket or file IO failure), returns a C standard error number." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:113 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:137 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:148 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:159 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:168 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:179 +#: ../../doc/reference/reference_lua/box_error/error_object.rst:188 +msgid "**Since:** :doc:`2.10.0 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:115 +msgid "Returns the :ref:`box.info.ro_reason ` value at the moment of throwing the ``box.error.READONLY`` error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:117 +msgid "The following values may be returned:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:119 +msgid "``election`` if the instance has :ref:`box.cfg.election_mode ` set to a value other than ``off`` and this instance is not a leader. In this case, ``error_object`` may include the following attributes: ``state``, ``leader_id``, ``leader_uuid``, and ``term``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:121 +msgid "``synchro`` if the synchronous queue has an owner that is not the given instance. This error usually happens if :ref:`synchronous replication ` is used and another instance is called :ref:`box.ctl.promote() `. In this case, ``error_object`` may include the ``queue_owner_id``, ``queue_owner_uuid``, and ``term`` attributes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:124 +msgid "``config`` if the :ref:`box.cfg.read_only ` is set to ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:125 +msgid "``orphan`` if the instance is in the :ref:`orphan ` state." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:129 +msgid "If multiple reasons are true at the same time, then only one is returned in the following order of preference: ``election``, ``synchro``, ``config``, ``orphan``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:139 +msgid "For the ``box.error.READONLY`` error, returns the current state of a replica set node in regards to leader election (see :ref:`box.info.election.state `). This attribute presents if the :ref:`error reason ` is ``election``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:150 +msgid "For the ``box.error.READONLY`` error, returns a numeric identifier (:ref:`box.info.id `) of the replica set leader. This attribute may present if the :ref:`error reason ` is ``election``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:161 +msgid "For the ``box.error.READONLY`` error, returns a globally unique identifier (:ref:`box.info.uuid `) of the replica set leader. This attribute may present if the :ref:`error reason ` is ``election``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:170 +msgid "For the ``box.error.READONLY`` error, returns a numeric identifier (:ref:`box.info.id `) of the synchronous queue owner. This attribute may present if the :ref:`error reason ` is ``synchro``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:181 +msgid "For the ``box.error.READONLY`` error, returns a globally unique identifier (:ref:`box.info.uuid `) of the synchronous queue owner. This attribute may present if the :ref:`error reason ` is ``synchro``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/error_object.rst:190 +msgid "For the ``box.error.READONLY`` error, returns the current election term (see :ref:`box.info.election.term `). This attribute may present if the :ref:`error reason ` is ``election`` or ``synchro``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/last.pot b/locale/en/reference/reference_lua/box_error/last.pot new file mode 100644 index 0000000000..bf4d59732e --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/last.pot @@ -0,0 +1,51 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/last.rst:5 +msgid "box.error.last()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:9 +msgid "Get the last raised error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:11 +msgid "an :ref:`error_object ` representing the last error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:15 +msgid "box.error.last()\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/last.rst:21 +msgid "**See also:** :ref:`error_object:unpack() `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/new.pot b/locale/en/reference/reference_lua/box_error/new.pot new file mode 100644 index 0000000000..0530fb0afd --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/new.pot @@ -0,0 +1,148 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/new.rst:5 +msgid "box.error.new()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:11 +msgid "Create an error object with the specified parameters." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:0 +#: ../../doc/reference/reference_lua/box_error/new.rst:0 +#: ../../doc/reference/reference_lua/box_error/new.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:13 +#: ../../doc/reference/reference_lua/box_error/new.rst:40 +msgid "an error description" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:14 +msgid "(optional) a numeric code for this error" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:15 +msgid "(optional) an error type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:17 +msgid "**Example 1**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:19 +msgid "local custom_error = box.error.new({ code = 500,\n" +" reason = 'Internal server error' })\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:25 +msgid "**Example 2: custom type**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:27 +msgid "local custom_error = box.error.new({ code = 500,\n" +" reason = 'Internal server error',\n" +" type = 'CustomInternalError' })\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:37 +msgid "Create an error object with the specified type and description." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:39 +msgid "an error type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:41 +#: ../../doc/reference/reference_lua/box_error/new.rst:60 +msgid "description arguments" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:43 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:45 +msgid "local custom_error = box.error.new('CustomInternalError', 'Internal server error')\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: Internal server error\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:55 +msgid "Create a predefined :ref:`Tarantool error ` specified by its identifier. You can see all Tarantool errors in the `errcode.h `_ file." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:59 +msgid "a pre-defined error identifier; Lua constants that correspond to those Tarantool errors are defined as members of ``box.error``, for example, ``box.error.NO_SUCH_USER == 45``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:62 +msgid "**Example 1: one argument**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:64 +msgid "local custom_error = box.error.new(box.error.NO_SUCH_USER, 'John')\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: User 'John' is not found\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:70 +msgid "**Example 2: two arguments**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/new.rst:72 +msgid "local custom_error = box.error.new(box.error.CREATE_SPACE, 'my_space', 'the space already exists')\n" +"\n" +"box.error(custom_error)\n" +"--[[\n" +"---\n" +"- error: 'Failed to create space ''my_space'': the space already exists'\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_error/set.pot b/locale/en/reference/reference_lua/box_error/set.pot new file mode 100644 index 0000000000..2dacf43e66 --- /dev/null +++ b/locale/en/reference/reference_lua/box_error/set.pot @@ -0,0 +1,79 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_error/set.rst:5 +msgid "box.error.set()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:9 +msgid "**Since:** :doc:`2.4.1 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:11 +msgid "Set the specified error as the last system error explicitly. This error is returned by :doc:`/reference/reference_lua/box_error/last`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:14 +msgid "an error object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:16 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_error/set.rst:18 +msgid "-- Create two errors --\n" +"local error1 = box.error.new({ code = 500, reason = 'Custom error 1' })\n" +"local error2 = box.error.new({ code = 505, reason = 'Custom error 2' })\n" +"\n" +"-- Raise the first error --\n" +"box.error(error1)\n" +"--[[\n" +"---\n" +"- error: Custom error 1\n" +"...\n" +"--]]\n" +"\n" +"-- Get the last error --\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- Custom error 1\n" +"...\n" +"--]]\n" +"\n" +"-- Set the second error as the last error --\n" +"box.error.set(error2)\n" +"--[[\n" +"---\n" +"...\n" +"--]]\n" +"\n" +"-- Get the last error --\n" +"box.error.last()\n" +"--[[\n" +"---\n" +"- Custom error 2\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_events.pot b/locale/en/reference/reference_lua/box_events.pot new file mode 100644 index 0000000000..34f617f15b --- /dev/null +++ b/locale/en/reference/reference_lua/box_events.pot @@ -0,0 +1,113 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_events.rst:4 +msgid "Event watchers" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:6 +msgid "Since :doc:`2.10.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:8 +msgid "The ``box`` module contains some features related to event subscriptions, also known as :term:`watchers `. The subscriptions are used to inform the client about server-side :term:`events `. Each event subscription is defined by a certain key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:13 +msgid "Event" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:16 +msgid "An event is a state change or a system update that triggers the action of other systems. To read more about built-in events in Tarantool, check the :doc:`system events ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:19 +msgid "State" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:21 +msgid "A state is an internally stored key-value pair. The key is a string. The value is an arbitrary type that can be encoded as MsgPack. To update a state, use the ``box.broadcast()`` function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:25 +msgid "Watcher" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:27 +msgid "A watcher is a :doc:`callback ` that is invoked when a state change occurs. To register a local watcher, use the ``box.watch()`` function. To create a remote watcher, use the ``watch()`` function from the ``net.box`` module. Note that it is possible to register more than one watcher for the same key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:33 +msgid "How a watcher works" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:35 +msgid "First, you register a watcher. After that, the watcher callback is invoked for the first time. In this case, the callback is triggered whether or not the key has already been broadcast. All subsequent invocations are triggered with :doc:`box.broadcast() ` called on the remote host. If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once, after the registration of the watcher." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:43 +msgid "The watcher callback takes two arguments. The first argument is the name of the key for which it was registered. The second one contains current key data. The callback is always invoked in a new fiber. It means that it is allowed to yield in it. A watcher callback is never executed in parallel with itself. If the key is updated while the watcher callback is running, the callback will be invoked again with the new value as soon as it returns." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:51 +msgid "``box.watch`` and ``box.broadcast`` functions can be used before :doc:`box.cfg `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:53 +msgid "Below is a list of all functions and pages related to watchers or events." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:64 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:65 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:67 +msgid ":doc:`./box_events/watch`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:68 +msgid "Create a local watcher." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:70 +msgid ":ref:`conn:watch() `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:71 +msgid "Create a watcher for the remote host." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:73 +msgid ":doc:`./box_events/broadcast`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:74 +msgid "Update a state." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:76 +msgid ":ref:`Built-in events `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events.rst:77 +msgid "Predefined events in Tarantool" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_events/broadcast.pot b/locale/en/reference/reference_lua/box_events/broadcast.pot new file mode 100644 index 0000000000..934041c0c2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_events/broadcast.pot @@ -0,0 +1,66 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:5 +msgid "box.broadcast()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:9 +msgid "Update the value of a particular key and notify all key watchers of the update." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:11 +msgid "key name of the event to subscribe to" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:12 +msgid "any data that can be encoded in MsgPack" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:14 +msgid "none" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:16 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:18 +msgid "The value can't be encoded as MsgPack." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:19 +msgid "The key refers to a ``box.`` system event" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/broadcast.rst:23 +msgid "-- Broadcast value 42 for the 'foo' key.\n" +"box.broadcast('foo', 42)" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_events/system_events.pot b/locale/en/reference/reference_lua/box_events/system_events.pot new file mode 100644 index 0000000000..8245acab3d --- /dev/null +++ b/locale/en/reference/reference_lua/box_events/system_events.pot @@ -0,0 +1,208 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:4 +msgid "System events" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:6 +msgid "Since :doc:`2.10.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:8 +msgid "Predefined events have a special naming schema -- theirs names always start with the reserved ``box.`` prefix. It means that you cannot create new events with it." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:11 +msgid "The system processes the following events:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:13 +msgid "``box.id``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:14 +msgid "``box.status``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:15 +msgid "``box.election``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:16 +msgid "``box.schema``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:17 +msgid "``box.shutdown``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:19 +msgid "In response to each event, the server sends back certain ``IPROTO`` fields." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:21 +msgid "The events are available from the beginning as non-:ref:`MP_NIL `. If a watcher subscribes to a system event before it has been broadcast, it receives an empty table for the event value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:25 +msgid "The event is generated when there is a change in any of the values listed in the event. For example, see the parameters in the ``box.id`` event below -- ``id``, ``instance_uuid``, and ``replicaset_uuid``. Suppose the ``ìd`` value (``box.info.id``) has changed. This triggers the ``box.info`` event, which states that the value of ``box.info.id`` has changed, while ``box.info.uuid`` and ``box.info.cluster.uuid`` remain the same." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:32 +msgid "box.id" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:34 +msgid "Contains :ref:`identification ` of the instance. Value changes are rare." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:37 +msgid "``id``: the numeric instance ID is unknown before the registration. For anonymous replicas, the value is ``0`` until they are officially registered." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:40 +msgid "``instance_uuid``: the UUID of the instance never changes after the first :doc:`box.cfg `. The value is unknown before the ``box.cfg`` call." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:44 +msgid "``replicaset_uuid``: the value is unknown until the instance joins a replicaset or boots a new one." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:46 +msgid "-- box.id value\n" +"{\n" +"MP_STR “id”: MP_UINT; box.info.id,\n" +"MP_STR “instance_uuid”: MP_UUID; box.info.uuid,\n" +"MP_STR “replicaset_uuid”: MP_UUID box.info.cluster.uuid,\n" +"}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:56 +msgid "box.status" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:58 +msgid "Contains generic information about the instance status." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:60 +#: ../../doc/reference/reference_lua/box_events/system_events.rst:80 +msgid "``is_ro``: :ref:`indicates the read-only mode ` or the ``orphan`` status." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:61 +msgid "``is_ro_cfg``: indicates the :ref:`read_only ` mode for the instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:62 +msgid "``status``: shows the status of an instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:64 +msgid "{\n" +"MP_STR “is_ro”: MP_BOOL box.info.ro,\n" +"MP_STR “is_ro_cfg”: MP_BOOL box.cfg.read_only,\n" +"MP_STR “status”: MP_STR box.info.status,\n" +"}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:73 +msgid "box.election" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:75 +msgid "Contains fields of :doc:`box.info.election ` that are necessary to find out the most recent writable leader." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:78 +msgid "``term``: shows the current election term." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:79 +msgid "``role``: indicates the election state of the node -- ``leader``, ``follower``, or ``candidate``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:81 +msgid "``leader``: shows the leader node ID in the current term." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:83 +msgid "{\n" +"MP_STR “term”: MP_UINT box.info.election.term,\n" +"MP_STR “role”: MP_STR box.info.election.state,\n" +"MP_STR “is_ro”: MP_BOOL box.info.ro,\n" +"MP_STR “leader”: MP_UINT box.info.election.leader,\n" +"}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:93 +msgid "box.schema" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:95 +msgid "Contains schema-related data." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:97 +msgid "``version``: shows the schema version." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:99 +msgid "{\n" +"MP_STR “version”: MP_UINT schema_version,\n" +"}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:108 +msgid "box.shutdown" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:110 +msgid "Contains a boolean value which indicates whether there is an active shutdown request." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:112 +msgid "The event is generated when the server receives a shutdown request (``os.exit()`` command or :ref:`SIGTERM ` signal)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:115 +msgid "The ``box.shutdown`` event is applied for the graceful shutdown protocol. It is a feature which is available since :doc:`2.10.0 `. This protocol is supposed to be used with connectors to signal a client about the upcoming server shutdown and close active connections without broken requests. For more information, refer to the :ref:`graceful shutdown protocol ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:122 +msgid "Usage example" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:124 +msgid "local conn = net.box.connect(URI)\n" +"local log = require('log')\n" +"-- Subscribe to updates of key 'box.id'\n" +"local w = conn:watch('box.id', function(key, value)\n" +" assert(key == 'box.id')\n" +" log.info(\"The box.id value is '%s'\", value)\n" +"end)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:134 +msgid "If you want to unregister the watcher when it's no longer needed, use the following command:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/system_events.rst:136 +msgid "w:unregister()" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_events/watch.pot b/locale/en/reference/reference_lua/box_events/watch.pot new file mode 100644 index 0000000000..f0fb16ef80 --- /dev/null +++ b/locale/en/reference/reference_lua/box_events/watch.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:5 +msgid "box.watch()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:9 +msgid "Subscribe to events broadcast by a local host." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:11 +msgid "key name of the event to subscribe to" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:12 +msgid "callback to invoke when the key value is updated" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:14 +msgid "a watcher handle. The handle consists of one method -- ``unregister()``, which unregisters the watcher." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:16 +msgid "To read more about watchers, see the :ref:`Functions for watchers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:20 +msgid "Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction. In this case, the watcher remains registered. It is okay to discard the result of ``watch`` function if the watcher will never be unregistered." +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:24 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:26 +msgid "-- Broadcast value 42 for the 'foo' key.\n" +"box.broadcast('foo', 42)\n" +"\n" +"local log = require('log')\n" +"-- Subscribe to updates of the 'foo' key.\n" +"local w = box.watch('foo', function(key, value)\n" +" assert(key == 'foo')\n" +" log.info(\"The box.id value is '%d'\", value)\n" +"end)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:38 +msgid "If you don't need the watcher anymore, you can unregister it using the command below:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_events/watch.rst:40 +msgid "w:unregister()" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index.pot b/locale/en/reference/reference_lua/box_index.pot new file mode 100644 index 0000000000..b877eeab88 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index.pot @@ -0,0 +1,213 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index.rst:5 +msgid "Submodule box.index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:7 +msgid "The ``box.index`` submodule provides read-only access for index definitions and index keys. Indexes are contained in :samp:`box.space.{space-name}.index` array within each space object. They provide an API for ordered iteration over tuples. This API is a direct binding to corresponding methods of index objects of type ``box.index`` in the storage engine." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:13 +msgid "Below is a list of all ``box.index`` functions and members." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:24 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:25 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:27 +msgid ":doc:`./box_index/examples`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:28 +msgid "Some useful examples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:30 +msgid ":doc:`./box_space/create_index`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:31 +msgid "Create an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:33 +msgid ":doc:`./box_index/unique`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:34 +msgid "Flag, true if an index is unique" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:36 +msgid ":doc:`./box_index/type`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:37 +msgid "Index type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:39 +msgid ":doc:`./box_index/parts`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:40 +msgid "Array of index key fields" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:42 +msgid ":doc:`./box_index/pairs`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:43 +msgid "Prepare for iterating" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:45 +msgid ":doc:`./box_index/select`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:46 +msgid "Select one or more tuples via index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:48 +msgid ":doc:`./box_index/get`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:49 +msgid "Select a tuple via index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:51 +msgid ":doc:`./box_index/min`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:52 +msgid "Find the minimum value in index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:54 +msgid ":doc:`./box_index/max`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:55 +msgid "Find the maximum value in index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:57 +msgid ":doc:`./box_index/random`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:58 +msgid "Find a random value in index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:60 +msgid ":doc:`./box_index/count`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:61 +msgid "Count tuples matching key value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:63 +msgid ":doc:`./box_index/update`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:64 +msgid "Update a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:66 +msgid ":doc:`./box_index/delete`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:67 +msgid "Delete a tuple by key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:69 +msgid ":doc:`./box_index/alter`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:70 +msgid "Alter an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:72 +msgid ":doc:`./box_index/drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:73 +msgid "Drop an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:75 +msgid ":doc:`./box_index/rename`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:76 +msgid "Rename an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:78 +msgid ":doc:`./box_index/bsize`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:79 +msgid "Get count of bytes for an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:81 +msgid ":doc:`./box_index/stat`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:82 +msgid "Get statistics for an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:84 +msgid ":doc:`./box_index/compact`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:85 +msgid "Remove unused index space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:87 +msgid ":doc:`./box_index/tuple_pos`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:88 +msgid "Return a tuple's position for an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:90 +msgid ":doc:`./box_index/user_defined`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index.rst:91 +msgid "Any function / method that any user wants to add" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/alter.pot b/locale/en/reference/reference_lua/box_index/alter.pot new file mode 100644 index 0000000000..4f9e9f2a31 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/alter.pot @@ -0,0 +1,111 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:5 +msgid "index_object:alter()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:11 +msgid "Alter an index. It is legal in some circumstances to change one or more of the index characteristics, for example its type, its sequence options, its parts, and whether it is unique. Usually this causes rebuilding of the space, except for the simple case where a part's ``is_nullable`` flag is changed from ``false`` to ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:18 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:20 +msgid "index options (see :ref:`index_opts `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:22 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:24 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:26 +msgid "index does not exist" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:27 +msgid "the primary-key index cannot be changed to ``{unique = false}``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:31 +msgid "Vinyl does not support ``alter()`` of a primary-key index unless the space is empty." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:33 +msgid "**Example 1:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:35 +msgid "You can add and remove fields that make up a primary index:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:37 +msgid "tarantool> s = box.schema.create_space('test')\n" +"---\n" +"...\n" +"tarantool> i = s:create_index('i', {parts = {{field = 1, type = 'unsigned'}}})\n" +"---\n" +"...\n" +"tarantool> s:insert({1, 2})\n" +"---\n" +"- [1, 2]\n" +"...\n" +"tarantool> i:select()\n" +"---\n" +"- - [1, 2]\n" +"...\n" +"tarantool> i:alter({parts = {{field = 1, type = 'unsigned'}, {field = 2, type = 'unsigned'}}})\n" +"---\n" +"...\n" +"tarantool> s:insert({1, 't'})\n" +"---\n" +"- error: 'Tuple field 2 type does not match one required by operation: expected unsigned'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:61 +msgid "**Example 2:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:63 +msgid "You can change index options for both memtx and vinyl spaces:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/alter.rst:65 +msgid "tarantool> box.space.space55.index.primary:alter({type = 'HASH'})\n" +"---\n" +"...\n" +"\n" +"tarantool> box.space.vinyl_space.index.i:alter({page_size=4096})\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/bsize.pot b/locale/en/reference/reference_lua/box_index/bsize.pot new file mode 100644 index 0000000000..635b9763a6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/bsize.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:5 +msgid "index_object:bsize()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:11 +msgid "Return the total number of bytes taken by the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:13 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:16 +msgid "number of bytes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/bsize.rst:17 +msgid "number" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/compact.pot b/locale/en/reference/reference_lua/box_index/compact.pot new file mode 100644 index 0000000000..188937900b --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/compact.pot @@ -0,0 +1,33 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/compact.rst:5 +msgid "index_object:compact()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/compact.rst:11 +msgid "Remove unused index space. For the memtx storage engine this method does nothing; ``index_object:compact()`` is only for the vinyl storage engine. For example, with vinyl, if a tuple is deleted, the space is not immediately reclaimed. There is a scheduler for reclaiming space automatically based on factors such as lsm shape and amplification as discussed in the section :ref:`Storing data with vinyl `, so calling ``index_object:compact()`` manually is not always necessary." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/compact.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/compact.rst:20 +msgid "nil (Tarantool returns without waiting for compaction to complete)" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/count.pot b/locale/en/reference/reference_lua/box_index/count.pot new file mode 100644 index 0000000000..a28ecc632f --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/count.pot @@ -0,0 +1,96 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/count.rst:5 +msgid "index_object:count()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:11 +msgid "Iterate over an index, counting the number of tuples which match the key-value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:14 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:16 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:17 +msgid "comparison method" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:19 +msgid "the number of matching tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:20 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:22 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:24 +msgid "Below are few examples of using ``count``. To try out these examples, you need to bootstrap a Tarantool database as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/count.rst:28 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"box.space.bands:insert { 6, 'The Rolling Stones', 1962 }\n" +"box.space.bands:insert { 7, 'The Doors', 1965 }\n" +"box.space.bands:insert { 8, 'Nirvana', 1987 }\n" +"box.space.bands:insert { 9, 'Led Zeppelin', 1968 }\n" +"box.space.bands:insert { 10, 'Queen', 1970 }\n" +"\n" +"-- Count the number of tuples that match the full key value\n" +"count = box.space.bands.index.year:count(1965)\n" +"--[[\n" +"---\n" +"- 3\n" +"...\n" +"--]]\n" +"\n" +"-- Count the number of tuples that match the partial key value\n" +"count_partial = box.space.bands.index.year_band:count(1965)\n" +"--[[\n" +"---\n" +"- 3\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/delete.pot b/locale/en/reference/reference_lua/box_index/delete.pot new file mode 100644 index 0000000000..0d686647b9 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/delete.pot @@ -0,0 +1,61 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:5 +msgid "index_object:delete()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:11 +msgid "Delete a tuple identified by a key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:13 +msgid "Same as :ref:`box.space...delete() `, but key is searched in this index instead of in the primary-key index. This index ought to be unique." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:17 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:19 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:21 +msgid "the deleted tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:22 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/delete.rst:24 +msgid "**Note regarding storage engine:** vinyl will return `nil`, rather than the deleted tuple." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/drop.pot b/locale/en/reference/reference_lua/box_index/drop.pot new file mode 100644 index 0000000000..9829517f53 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/drop.pot @@ -0,0 +1,63 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:5 +msgid "index_object:drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:11 +msgid "Drop an index. Dropping a primary-key index has a side effect: all tuples are deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:14 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:17 +msgid "nil." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:19 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:21 +msgid "index does not exist," +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:22 +msgid "a primary-key index cannot be dropped while a secondary-key index exists." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:25 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/drop.rst:27 +msgid "tarantool> box.space.space55.index.primary:drop()\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/examples.pot b/locale/en/reference/reference_lua/box_index/examples.pot new file mode 100644 index 0000000000..c3b6c9bbf0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/examples.pot @@ -0,0 +1,290 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:5 +msgid "Examples for `box.index`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:9 +msgid "Example showing use of the box functions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:11 +msgid "This example will work with the sandbox configuration described in the preface. That is, there is a space named tester with a numeric primary key. The example function will:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:15 +msgid "select a tuple whose key value is 1000;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:16 +msgid "raise an error if the tuple already exists and already has 3 fields;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:19 +msgid "Insert or replace the tuple with:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:18 +msgid "field[1] = 1000" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:19 +msgid "field[2] = a uuid" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:20 +msgid "field[3] = number of seconds since 1970-01-01;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:21 +msgid "Get field[3] from what was replaced;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:22 +msgid "Format the value from field[3] as yyyy-mm-dd hh:mm:ss.ffff;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:23 +msgid "Return the formatted value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:25 +msgid "The function uses Tarantool box functions :ref:`box.space...select `, :ref:`box.space...replace `, :ref:`fiber.time `, :ref:`uuid.str `. The function uses Lua functions `os.date() `_ and `string.sub() `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:32 +msgid "function example()\n" +" local a, b, c, table_of_selected_tuples, d\n" +" local replaced_tuple, time_field\n" +" local formatted_time_field\n" +" local fiber = require('fiber')\n" +" table_of_selected_tuples = box.space.tester:select{1000}\n" +" if table_of_selected_tuples ~= nil then\n" +" if table_of_selected_tuples[1] ~= nil then\n" +" if #table_of_selected_tuples[1] == 3 then\n" +" box.error({code=1, reason='This tuple already has 3 fields'})\n" +" end\n" +" end\n" +" end\n" +" replaced_tuple = box.space.tester:replace\n" +" {1000, require('uuid').str(), tostring(fiber.time())}\n" +" time_field = tonumber(replaced_tuple[3])\n" +" formatted_time_field = os.date(\"%Y-%m-%d %H:%M:%S\", time_field)\n" +" c = time_field % 1\n" +" d = string.sub(c, 3, 6)\n" +" formatted_time_field = formatted_time_field .. '.' .. d\n" +" return formatted_time_field\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:57 +msgid "... And here is what happens when one invokes the function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:59 +msgid "tarantool> box.space.tester:delete(1000)\n" +"---\n" +"- [1000, '264ee2da03634f24972be76c43808254', '1391037015.6809']\n" +"...\n" +"tarantool> example(1000)\n" +"---\n" +"- 2014-01-29 16:11:51.1582\n" +"...\n" +"tarantool> example(1000)\n" +"---\n" +"- error: 'This tuple already has 3 fields'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:78 +msgid "Example showing a user-defined iterator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:80 +msgid "Here is an example that shows how to build one's own iterator. The ``paged_iter`` function is an \"iterator function\", which will only be understood by programmers who have read the Lua manual section `Iterators and Closures `_. It does paginated retrievals, that is, it returns 10 tuples at a time from a table named \"t\", whose primary key was defined with ``create_index('primary',{parts={1,'string'}})``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:87 +msgid "function paged_iter(search_key, tuples_per_page)\n" +" local iterator_string = \"GE\"\n" +" return function ()\n" +" local page = box.space.t.index[0]:select(search_key,\n" +" {iterator = iterator_string, limit=tuples_per_page})\n" +" if #page == 0 then return nil end\n" +" search_key = page[#page][1]\n" +" iterator_string = \"GT\"\n" +" return page\n" +" end\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:101 +msgid "Programmers who use ``paged_iter`` do not need to know why it works, they only need to know that, if they call it within a loop, they will get 10 tuples at a time until there are no more tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:105 +msgid "In this example the tuples are merely printed, a page at a time. But it should be simple to change the functionality, for example by yielding after each retrieval, or by breaking when the tuples fail to match some additional criteria." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:110 +msgid "for page in paged_iter(\"X\", 10) do\n" +" print(\"New Page. Number Of Tuples = \" .. #page)\n" +" for i = 1, #page, 1 do\n" +" print(page[i])\n" +" end\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:123 +msgid "Example showing submodule `box.index` with index type = RTREE for spatial searches" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:125 +msgid "This submodule may be used for spatial searches if the index type is RTREE. There are operations for searching *rectangles* (geometric objects with 4 corners and 4 sides) and *boxes* (geometric objects with more than 4 corners and more than 4 sides, sometimes called hyperrectangles). This manual uses the term *rectangle-or-box* for the whole class of objects that includes both rectangles and boxes. Only rectangles will be illustrated." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:133 +msgid "Rectangles are described according to their X-axis (horizontal axis) and Y-axis (vertical axis) coordinates in a grid of arbitrary size. Here is a picture of four rectangles on a grid with 11 horizontal points and 11 vertical points:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:137 +msgid " X AXIS\n" +" 1 2 3 4 5 6 7 8 9 10 11\n" +" 1\n" +" 2 #-------+ <-Rectangle#1\n" +"Y AXIS 3 | |\n" +" 4 +-------#\n" +" 5 #-----------------------+ <-Rectangle#2\n" +" 6 | |\n" +" 7 | #---+ | <-Rectangle#3\n" +" 8 | | | |\n" +" 9 | +---# |\n" +" 10 +-----------------------#\n" +" 11 # <-Rectangle#4" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:153 +msgid "The rectangles are defined according to this scheme: {X-axis coordinate of top left, Y-axis coordinate of top left, X-axis coordinate of bottom right, Y-axis coordinate of bottom right} -- or more succinctly: {x1,y1,x2,y2}. So in the picture ... Rectangle#1 starts at position 1 on the X axis and position 2 on the Y axis, and ends at position 3 on the X axis and position 4 on the Y axis, so its coordinates are {1,2,3,4}. Rectangle#2's coordinates are {3,5,9,10}. Rectangle#3's coordinates are {4,7,5,9}. And finally Rectangle#4's coordinates are {10,11,10,11}. Rectangle#4 is actually a \"point\" since it has zero width and zero height, so it could have been described with only two digits: {10,11}." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:163 +msgid "Some relationships between the rectangles are: \"Rectangle#1's nearest neighbor is Rectangle#2\", and \"Rectangle#3 is entirely inside Rectangle#2\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:166 +msgid "Now let us create a space and add an RTREE index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:168 +msgid "tarantool> s = box.schema.space.create('rectangles')\n" +"tarantool> i = s:create_index('primary', {\n" +" > type = 'HASH',\n" +" > parts = {1, 'unsigned'}\n" +" > })\n" +"tarantool> r = s:create_index('rtree', {\n" +" > type = 'RTREE',\n" +" > unique = false,\n" +" > parts = {2, 'ARRAY'}\n" +" > })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:181 +msgid "Field#1 doesn't matter, we just make it because we need a primary-key index. (RTREE indexes cannot be unique and therefore cannot be primary-key indexes.) The second field must be an \"array\", which means its values must represent {x,y} points or {x1,y1,x2,y2} rectangles. Now let us populate the table by inserting two tuples, containing the coordinates of Rectangle#2 and Rectangle#4." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:187 +msgid "tarantool> s:insert{1, {3, 5, 9, 10}}\n" +"tarantool> s:insert{2, {10, 11}}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:192 +msgid "And now, following the description of `RTREE iterator types`_, we can search the rectangles with these requests:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:197 +msgid "tarantool> r:select({10, 11, 10, 11}, {iterator = 'EQ'})\n" +"---\n" +"- - [2, [10, 11]]\n" +"...\n" +"tarantool> r:select({4, 7, 5, 9}, {iterator = 'GT'})\n" +"---\n" +"- - [1, [3, 5, 9, 10]]\n" +"...\n" +"tarantool> r:select({1, 2, 3, 4}, {iterator = 'NEIGHBOR'})\n" +"---\n" +"- - [1, [3, 5, 9, 10]]\n" +" - [2, [10, 11]]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:213 +msgid "Request#1 returns 1 tuple because the point {10,11} is the same as the rectangle {10,11,10,11} (\"Rectangle#4\" in the picture). Request#2 returns 1 tuple because the rectangle {4,7,5,9}, which was \"Rectangle#3\" in the picture, is entirely within{3,5,9,10} which was Rectangle#2. Request#3 returns 2 tuples, because the NEIGHBOR iterator always returns all tuples, and the first returned tuple will be {3,5,9,10} (\"Rectangle#2\" in the picture) because it is the closest neighbor of {1,2,3,4} (\"Rectangle#1\" in the picture)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:221 +msgid "Now let us create a space and index for cuboids, which are rectangle-or-boxes that have 6 corners and 6 sides." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:224 +msgid "tarantool> s = box.schema.space.create('R')\n" +"tarantool> i = s:create_index('primary', {parts = {1, 'unsigned'}})\n" +"tarantool> r = s:create_index('S', {\n" +" > type = 'RTREE',\n" +" > unique = false,\n" +" > dimension = 3,\n" +" > parts = {2, 'ARRAY'}\n" +" > })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:235 +msgid "The additional option here is ``dimension=3``. The default dimension is 2, which is why it didn't need to be specified for the examples of rectangle. The maximum dimension is 20. Now for insertions and selections there will usually be 6 coordinates. For example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:240 +msgid "tarantool> s:insert{1, {0, 3, 0, 3, 0, 3}}\n" +"tarantool> r:select({1, 2, 1, 2, 1, 2}, {iterator = box.index.GT})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:245 +msgid "Now let us create a space and index for Manhattan-style spatial objects, which are rectangle-or-boxes that have a different way to calculate neighbors." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:248 +msgid "tarantool> s = box.schema.space.create('R')\n" +"tarantool> i = s:create_index('primary', {parts = {1, 'unsigned'}})\n" +"tarantool> r = s:create_index('S', {\n" +" > type = 'RTREE',\n" +" > unique = false,\n" +" > distance = 'manhattan',\n" +" > parts = {2, 'ARRAY'}\n" +" > })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:259 +msgid "The additional option here is ``distance='manhattan'``. The default distance calculator is 'euclid', which is the straightforward as-the-crow-flies method. The optional distance calculator is 'manhattan', which can be a more appropriate method if one is following the lines of a grid rather than traveling in a straight line." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:265 +msgid "tarantool> s:insert{1, {0, 3, 0, 3}}\n" +"tarantool> r:select({1, 2, 1, 2}, {iterator = box.index.NEIGHBOR})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/examples.rst:270 +msgid "More examples of spatial searching are online in the file `R tree index quick start and usage `_." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/get.pot b/locale/en/reference/reference_lua/box_index/get.pot new file mode 100644 index 0000000000..26fd9c144b --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/get.pot @@ -0,0 +1,84 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/get.rst:5 +msgid "index_object:get()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:11 +msgid "Search for a tuple via the given index, as described in the :ref:`select ` topic." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:13 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:15 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:17 +msgid "the tuple whose index-key fields are equal to the passed key values." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:18 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:20 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:22 +msgid "no such index;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:23 +msgid "wrong type;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:24 +msgid "more than one tuple matches." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:26 +msgid "**Complexity factors:** Index size, Index type. See also :ref:`space_object:get() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:29 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/get.rst:31 +msgid "tarantool> box.space.tester.index.primary:get(2)\n" +"---\n" +"- [2, 'Music']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/max.pot b/locale/en/reference/reference_lua/box_index/max.pot new file mode 100644 index 0000000000..e4f90ed4d8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/max.pot @@ -0,0 +1,108 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/max.rst:4 +msgid "index_object:max()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:10 +msgid "Find the maximum value in the specified index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:12 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:14 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:16 +msgid "the tuple for the last key in the index. If the optional ``key`` value is supplied, returns the last key that is less than or equal to ``key``. Starting with :doc:`Tarantool 2.0.4 `, ``index_object:max(key)`` returns nothing if ``key`` doesn't match any value in the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:20 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:23 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:25 +msgid "Index is not of type 'TREE'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:26 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:29 +msgid "**Complexity factors:** index size, index type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:31 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:33 +msgid "Below are few examples of using ``max``. To try out these examples, you need to bootstrap a Tarantool database as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/max.rst:37 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"box.space.bands:insert { 6, 'The Rolling Stones', 1962 }\n" +"box.space.bands:insert { 7, 'The Doors', 1965 }\n" +"box.space.bands:insert { 8, 'Nirvana', 1987 }\n" +"box.space.bands:insert { 9, 'Led Zeppelin', 1968 }\n" +"box.space.bands:insert { 10, 'Queen', 1970 }\n" +"\n" +"-- Find the maximum value in the specified index\n" +"max = box.space.bands.index.year:max()\n" +"--[[\n" +"---\n" +"- [8, 'Nirvana', 1987]\n" +"...\n" +"--]]\n" +"\n" +"-- Find the maximum value that matches the partial key value\n" +"max_partial = box.space.bands.index.year_band:max(1965)\n" +"--[[\n" +"---\n" +"- [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/min.pot b/locale/en/reference/reference_lua/box_index/min.pot new file mode 100644 index 0000000000..7c2b10dff4 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/min.pot @@ -0,0 +1,108 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/min.rst:4 +msgid "index_object:min()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:10 +msgid "Find the minimum value in the specified index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:12 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:14 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:16 +msgid "the tuple for the first key in the index. If the optional ``key`` value is supplied, returns the first key that is greater than or equal to ``key``. Starting with :doc:`Tarantool 2.0.4 `, ``index_object:min(key)`` returns nothing if ``key`` doesn't match any value in the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:21 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:23 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:25 +msgid "Index is not of type 'TREE'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:26 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:29 +msgid "**Complexity factors:** Index size, Index type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:31 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:33 +msgid "Below are few examples of using ``min``. To try out these examples, you need to bootstrap a Tarantool database as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/min.rst:37 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"box.space.bands:insert { 6, 'The Rolling Stones', 1962 }\n" +"box.space.bands:insert { 7, 'The Doors', 1965 }\n" +"box.space.bands:insert { 8, 'Nirvana', 1987 }\n" +"box.space.bands:insert { 9, 'Led Zeppelin', 1968 }\n" +"box.space.bands:insert { 10, 'Queen', 1970 }\n" +"\n" +"-- Find the minimum value in the specified index\n" +"min = box.space.bands.index.year:min()\n" +"--[[\n" +"---\n" +"- [4, 'The Beatles', 1960]\n" +"...\n" +"--]]\n" +"\n" +"-- Find the minimum value that matches the partial key value\n" +"min_partial = box.space.bands.index.year_band:min(1965)\n" +"--[[\n" +"---\n" +"- [5, 'Pink Floyd', 1965]\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/pairs.pot b/locale/en/reference/reference_lua/box_index/pairs.pot new file mode 100644 index 0000000000..1d72399dd7 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/pairs.pot @@ -0,0 +1,439 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:6 +msgid "index_object:pairs()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:12 +msgid "Search for a tuple or a set of tuples via the given index, and allow iterating over one tuple at a time. To search by the primary index in the specified space, use the :ref:`box_space-pairs` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:16 +msgid "The :samp:`{key}` parameter specifies what must match within the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:20 +msgid ":samp:`{key}` is only used to find the first match. Do not assume all matched tuples will contain the key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:23 +msgid "The :samp:`{iterator}` parameter specifies the rule for matching and ordering. Different index types support different iterators. For example, a TREE index maintains a strict order of keys and can return all tuples in ascending or descending order, starting from the specified key. Other index types, however, do not support ordering." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:29 +msgid "To understand consistency of tuples returned by an iterator, it's essential to know the principles of the Tarantool transaction processing subsystem. An iterator in Tarantool does not own a consistent read view. Instead, each procedure is granted exclusive access to all tuples and spaces until there is a \"context switch\": which may happen due to :ref:`the implicit yield rules `, or by an explicit call to :ref:`fiber.yield `. When the execution flow returns to the yielded procedure, the data set could have changed significantly. Iteration, resumed after a yield point, does not preserve the read view, but continues with the new content of the database. The tutorial :ref:`Indexed pattern search ` shows one way that iterators and yields can be used together." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:43 +msgid "For information about iterators' internal structures, see the `\"Lua Functional library\" `_ documentation." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:47 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:49 +msgid "value to be matched against the index key, which may be multi-part." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:51 +msgid "as defined in tables below. The default iterator type is 'EQ'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:52 +msgid "a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``pairs`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:55 +msgid "The `iterator `_, which can be used in a ``for/end`` loop or with `totable() `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:59 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:61 +msgid "no such space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:62 +msgid "wrong type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:63 +msgid "selected iteration type is not supported for the index type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:64 +msgid "key is not supported for the iteration type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:65 +msgid "iterator position is invalid" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:67 +msgid "**Complexity factors:** Index size, Index type; Number of tuples accessed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:70 +msgid "A search-key-value can be a number (for example ``1234``), a string (for example ``'abcd'``), or a table of numbers and strings (for example ``{1234, 'abcd'}``). Each part of a key will be compared to each part of an index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:75 +msgid "The returned tuples will be in order by index key value, or by the hash of the index key value if index type = 'hash'. If the index is non-unique, then duplicates will be secondarily in order by primary key value. The order will be reversed if the iterator type is 'LT' or 'LE' or 'REQ'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:82 +msgid "**Iterator types for TREE indexes**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:93 +msgid "Iterator type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:93 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:192 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:215 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "Arguments" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:93 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:192 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:215 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "Description" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:95 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:199 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:221 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.EQ or 'EQ'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:95 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:101 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:106 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:113 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:120 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:124 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:130 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:199 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "search value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:95 +msgid "The comparison operator is '==' (equal to). If an index key is equal to a search value, it matches. Tuples are returned in ascending order by index key. This is the default." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:101 +msgid "box.index.REQ or 'REQ'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:101 +msgid "Matching is the same as for ``box.index.EQ``. Tuples are returned in descending order by index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:106 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.GT or 'GT'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:106 +msgid "The comparison operator is '>' (greater than). If an index key is greater than a search value, it matches. Tuples are returned in ascending order by index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:113 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.GE or 'GE'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:113 +msgid "The comparison operator is '>=' (greater than or equal to). If an index key is greater than or equal to a search value, it matches. Tuples are returned in ascending order by index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:120 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:217 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.ALL or 'ALL'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:120 +msgid "Same as box.index.GE." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:124 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.LT or 'LT'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:124 +msgid "The comparison operator is '<' (less than). If an index key is less than a search value, it matches. Tuples are returned in descending order by index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:130 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.LE or 'LE'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:130 +msgid "The comparison operator is '<=' (less than or equal to). If an index key is less than or equal to a search value, it matches. Tuples are returned in descending order by index key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:138 +msgid "Informally, we can state that searches with TREE indexes are generally what users will find is intuitive, provided that there are no nils and no missing parts. Formally, the logic is as follows. A search key has zero or more parts, for example {}, {1,2,3},{1,nil,3}. An index key has one or more parts, for example {1}, {1,2,3},{1,2,3}. A search key may contain nil (but not msgpack.NULL, which is the wrong type). An index key may not contain nil or msgpack.NULL, although a later version of Tarantool will have different rules -- the behavior of searches with nil is subject to change. Possible iterators are LT, LE, EQ, REQ, GE, GT. A search key is said to \"match\" an index key if the following statements, which are pseudocode for the comparison operation, return TRUE." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:199 +msgid "If (number-of-search-key-parts > number-of-index-key-parts) return ERROR\n" +"If (number-of-search-key-parts == 0) return TRUE\n" +"for (i = 1; ; ++i)\n" +"{\n" +" if (i > number-of-search-key-parts) OR (search-key-part[i] is nil)\n" +" {\n" +" if (iterator is LT or GT) return FALSE\n" +" return TRUE\n" +" }\n" +" if (type of search-key-part[i] is not compatible with type of index-key-part[i])\n" +" {\n" +" return ERROR\n" +" }\n" +" if (search-key-part[i] == index-key-part[i])\n" +" {\n" +" continue\n" +" }\n" +" if (search-key-part[i] > index-key-part[i])\n" +" {\n" +" if (iterator is EQ or REQ or LE or LT) return FALSE\n" +" return TRUE\n" +" }\n" +" if (search-key-part[i] < index-key-part[i])\n" +" {\n" +" if (iterator is EQ or REQ or GE or GT) return FALSE\n" +" return TRUE\n" +" }\n" +"}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:183 +msgid "**Iterator types for HASH indexes**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:192 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:215 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "Type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:194 +msgid "box.index.ALL" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:194 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:217 +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "none" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:194 +msgid "All index keys match. Tuples are returned in ascending order by hash of index key, which will appear to be random." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:199 +msgid "The comparison operator is '==' (equal to). If an index key is equal to a search value, it matches. The number of returned tuples will be 0 or 1. This is the default." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:206 +msgid "**Iterator types for BITSET indexes**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:217 +msgid "All index keys match. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:221 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:226 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:231 +#: ../../doc/reference/reference_lua/box_index/pairs.rst:236 +msgid "bitset value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:221 +msgid "If an index key is equal to a bitset value, it matches. Tuples are returned in their order within the space. This is the default." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:226 +msgid "box.index.BITS_ALL_SET" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:226 +msgid "If all of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:231 +msgid "box.index.BITS_ANY_SET" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:231 +msgid "If any of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:236 +msgid "box.index.BITS_ALL_NOT_SET" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:236 +msgid "If all of the bits which are 1 in the bitset value are 0 in the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:244 +msgid "**Iterator types for RTREE indexes**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "All keys match. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If all points of the rectangle-or-box defined by the search value are the same as the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space. \"Rectangle-or-box\" means \"rectangle-or-box as explained in section about :ref:`RTREE `\". This is the default." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If all points of the rectangle-or-box defined by the search value are within the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If all points of the rectangle-or-box defined by the search value are within, or at the side of, the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If all points of the rectangle-or-box defined by the index key are within the rectangle-or-box defined by the search key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If all points of the rectangle-or-box defined by the index key are within, or at the side of, the rectangle-or-box defined by the search key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.OVERLAPS or 'OVERLAPS'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If some points of the rectangle-or-box defined by the search value are within the rectangle-or-box defined by the index key, it matches. Tuples are returned in their order within the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "box.index.NEIGHBOR or 'NEIGHBOR'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/box_index_rtree.csv:1 +msgid "If some points of the rectangle-or-box defined by the defined by the key are within, or at the side of, defined by the index key, it matches. Tuples are returned in order: nearest neighbor first." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:259 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:261 +msgid "Below are few examples of using ``pairs`` with different parameters. To try out these examples, you need to bootstrap a Tarantool instance as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/pairs.rst:267 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +" bands:insert{5, 'Pink Floyd', 1965}\n" +" bands:insert{6, 'The Rolling Stones', 1962}\n" +" bands:insert{7, 'The Doors', 1965}\n" +" bands:insert{8, 'Nirvana', 1987}\n" +" bands:insert{9, 'Led Zeppelin', 1968}\n" +" bands:insert{10, 'Queen', 1970}\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples by the primary index --\n" +"tarantool> for _, tuple in bands.index.primary:pairs() do\n" +" print(tuple)\n" +" end\n" +"[1, 'Roxette', 1986]\n" +"[2, 'Scorpions', 1965]\n" +"[3, 'Ace of Base', 1987]\n" +"[4, 'The Beatles', 1960]\n" +"[5, 'Pink Floyd', 1965]\n" +"[6, 'The Rolling Stones', 1962]\n" +"[7, 'The Doors', 1965]\n" +"[8, 'Nirvana', 1987]\n" +"[9, 'Led Zeppelin', 1968]\n" +"[10, 'Queen', 1970]\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples whose secondary key values start with the specified string --\n" +"tarantool> for _, tuple in bands.index.band:pairs(\"The\", {iterator = \"GE\"}) do\n" +" if (string.sub(tuple[2], 1, 3) ~= \"The\") then break end\n" +" print(tuple)\n" +" end\n" +"[4, 'The Beatles', 1960]\n" +"[7, 'The Doors', 1965]\n" +"[6, 'The Rolling Stones', 1962]\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples whose secondary key values are between 1965 and 1970 --\n" +"tarantool> for _, tuple in bands.index.year:pairs(1965, {iterator = \"GE\"}) do\n" +" if (tuple[3] > 1970) then break end\n" +" print(tuple)\n" +" end\n" +"[2, 'Scorpions', 1965]\n" +"[5, 'Pink Floyd', 1965]\n" +"[7, 'The Doors', 1965]\n" +"[9, 'Led Zeppelin', 1968]\n" +"[10, 'Queen', 1970]\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples after the specified tuple --\n" +"tarantool> for _, tuple in bands.index.primary:pairs({}, {after={7, 'The Doors', 1965}}) do\n" +" print(tuple)\n" +" end\n" +"[8, 'Nirvana', 1987]\n" +"[9, 'Led Zeppelin', 1968]\n" +"[10, 'Queen', 1970]\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/parts.pot b/locale/en/reference/reference_lua/box_index/parts.pot new file mode 100644 index 0000000000..02377331d1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/parts.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/parts.rst:5 +msgid "index_object:parts" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/parts.rst:11 +msgid "The index's key parts." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/parts.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/parts.rst:13 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/parts.rst:15 +msgid "**See also:** :ref:`index_opts.parts `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/random.pot b/locale/en/reference/reference_lua/box_index/random.pot new file mode 100644 index 0000000000..a3cab54ced --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/random.pot @@ -0,0 +1,72 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/random.rst:5 +msgid "index_object:random()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:11 +msgid "Find a random value in the specified index. This method is useful when it's important to get insight into data distribution in an index without having to iterate over the entire data set." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:16 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:18 +msgid "an arbitrary non-negative integer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:20 +msgid "the tuple for the random key in the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:21 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:23 +msgid "**Complexity factors:** Index size, Index type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:25 +msgid "**Note regarding storage engine:** vinyl does not support ``random()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:27 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/random.rst:29 +msgid "tarantool> box.space.tester.index.secondary:random(1)\n" +"---\n" +"- ['Beta!', 66, 'This is the second tuple!']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/rename.pot b/locale/en/reference/reference_lua/box_index/rename.pot new file mode 100644 index 0000000000..4585e7ce42 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/rename.pot @@ -0,0 +1,63 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:5 +msgid "index_object:rename()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:11 +msgid "Rename an index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:13 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:15 +msgid "new name for index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:17 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:19 +msgid "**Possible errors:** index_object does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:23 +msgid "tarantool> box.space.space55.index.primary:rename('secondary')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/rename.rst:29 +msgid "**Complexity factors:** Index size, Index type, Number of tuples accessed." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/select.pot b/locale/en/reference/reference_lua/box_index/select.pot new file mode 100644 index 0000000000..670caafc53 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/select.pot @@ -0,0 +1,204 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/select.rst:5 +msgid "index_object:select()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:11 +msgid "Search for a tuple or a set of tuples by the current index. To search by the primary index in the specified space, use the :ref:`box_space-select` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:14 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:16 +msgid "a value to be matched against the index key, which may be multi-part." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:17 +msgid "none, any, or all of the following parameters: * ``iterator`` -- the :ref:`iterator type `. The default iterator type is 'EQ'. * ``limit`` -- the maximum number of tuples. * ``offset`` -- the number of tuples to skip (use this parameter carefully when scanning :ref:`large data sets `). * ``options.after`` -- a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``select`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple. * ``options.fetch_pos`` -- if **true**, the ``select`` method returns the position of the last selected tuple as the second value. .. NOTE:: The ``after`` and ``fetch_pos`` options are supported for the ``TREE`` :ref:`index ` only." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:17 +msgid "none, any, or all of the following parameters:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:19 +msgid "``iterator`` -- the :ref:`iterator type `. The default iterator type is 'EQ'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:20 +msgid "``limit`` -- the maximum number of tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:21 +msgid "``offset`` -- the number of tuples to skip (use this parameter carefully when scanning :ref:`large data sets `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:22 +msgid "``options.after`` -- a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``select`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:23 +msgid "``options.fetch_pos`` -- if **true**, the ``select`` method returns the position of the last selected tuple as the second value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:27 +msgid "The ``after`` and ``fetch_pos`` options are supported for the ``TREE`` :ref:`index ` only." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:33 +msgid "This function might return one or two values:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:35 +msgid "The tuples whose fields are equal to the fields of the passed key. If the number of passed fields is less than the number of fields in the current key, then only the passed fields are compared, so ``select{1,2}`` matches a tuple whose primary key is ``{1,2,3}``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:40 +msgid "(Optionally) If ``options.fetch_pos`` is set to **true**, returns a base64-encoded string representing the position of the last selected tuple as the second value. If no tuples are fetched, returns ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:45 +msgid "array of tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:46 +msgid "(Optionally) string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:52 +msgid "Use the ``offset`` option carefully when scanning large data sets as it linearly increases the number of scanned tuples and leads to a full space scan. Instead, you can use the ``after`` and ``fetch_pos`` options." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:58 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:60 +msgid "Below are few examples of using ``select`` with different parameters. To try out these examples, you need to bootstrap a Tarantool database as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:64 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:insert { 5, 'Pink Floyd', 1965 }\n" +"box.space.bands:insert { 6, 'The Rolling Stones', 1962 }\n" +"box.space.bands:insert { 7, 'The Doors', 1965 }\n" +"box.space.bands:insert { 8, 'Nirvana', 1987 }\n" +"box.space.bands:insert { 9, 'Led Zeppelin', 1968 }\n" +"box.space.bands:insert { 10, 'Queen', 1970 }\n" +"\n" +"-- Select a tuple by the specified primary key value --\n" +"select_primary = bands.index.primary:select { 1 }\n" +"--[[\n" +"---\n" +"- - [1, 'Roxette', 1986]\n" +"...\n" +"--]]\n" +"\n" +"-- Select a tuple by the specified secondary key value --\n" +"select_secondary = bands.index.band:select { 'The Doors' }\n" +"--[[\n" +"---\n" +"- - [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"\n" +"-- Select a tuple by the specified multi-part secondary key value --\n" +"select_multipart = bands.index.year_band:select { 1960, 'The Beatles' }\n" +"--[[\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +"...\n" +"--]]\n" +"\n" +"-- Select tuples by the specified partial key value --\n" +"select_multipart_partial = bands.index.year_band:select { 1965 }\n" +"--[[\n" +"---\n" +"- - [5, 'Pink Floyd', 1965]\n" +" - [2, 'Scorpions', 1965]\n" +" - [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"\n" +"-- Select maximum 3 tuples by the specified secondary index --\n" +"select_limit = bands.index.band:select({}, { limit = 3 })\n" +"--[[\n" +"---\n" +"- - [3, 'Ace of Base', 1987]\n" +" - [9, 'Led Zeppelin', 1968]\n" +" - [8, 'Nirvana', 1987]\n" +"...\n" +"--]]\n" +"\n" +"-- Select maximum 3 tuples with the key value greater than 1965 --\n" +"select_greater = bands.index.year:select({ 1965 }, { iterator = 'GT', limit = 3 })\n" +"--[[\n" +"---\n" +"- - [9, 'Led Zeppelin', 1968]\n" +" - [10, 'Queen', 1970]\n" +" - [1, 'Roxette', 1986]\n" +"...\n" +"--]]\n" +"\n" +"-- Select maximum 3 tuples after the specified tuple --\n" +"select_after_tuple = bands.index.primary:select({}, { after = { 4, 'The Beatles', 1960 }, limit = 3 })\n" +"--[[\n" +"---\n" +"- - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +" - [7, 'The Doors', 1965]\n" +"...\n" +"--]]\n" +"\n" +"-- Select first 3 tuples and fetch a last tuple's position --\n" +"result, position = bands.index.primary:select({}, { limit = 3, fetch_pos = true })\n" +"-- Then, pass this position as the 'after' parameter --\n" +"select_after_position = bands.index.primary:select({}, { limit = 3, after = position })\n" +"--[[\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +" - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +"...\n" +"--]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/select.rst:73 +msgid ":samp:`box.space.{space-name}.index.{index-name}:select(...)[1]`. can be replaced by :samp:`box.space.{space-name}.index.{index-name}:get(...)`. That is, ``get`` can be used as a convenient shorthand to get the first tuple in the tuple set that would be returned by ``select``. However, if there is more than one tuple in the tuple set, then ``get`` throws an error." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/stat.pot b/locale/en/reference/reference_lua/box_index/stat.pot new file mode 100644 index 0000000000..76ece8623f --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/stat.pot @@ -0,0 +1,109 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:5 +msgid "index_object:stat()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:11 +msgid "Return statistics about actions taken that affect the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:13 +msgid "This is for use with the vinyl engine." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:15 +msgid "Some detail items in the output from ``index_object:stat()`` are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:17 +msgid "``index_object:stat().latency`` -- timings subdivided by percentages;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:18 +msgid "``index_object:stat().bytes`` -- the number of bytes total;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:19 +msgid "``index_object:stat().disk.rows`` -- the approximate number of tuples in each range;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:20 +msgid "``index_object:stat().disk.statement`` -- counts of inserts|updates|upserts|deletes;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:21 +msgid "``index_object:stat().disk.compaction`` -- counts of compactions and their amounts;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:22 +msgid "``index_object:stat().disk.dump`` -- counts of dumps and their amounts;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:23 +msgid "``index_object:stat().disk.iterator.bloom`` -- counts of bloom filter hits|misses;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:24 +msgid "``index_object:stat().disk.pages`` -- the size in pages;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:25 +msgid "``index_object:stat().disk.last_level`` -- size of data in the last LSM tree level;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:26 +msgid "``index_object:stat().cache.evict`` -- number of evictions from the cache;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:27 +msgid "``index_object:stat().range_size`` -- maximum number of bytes in a range;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:28 +msgid "``index_object:stat().dumps_per_compaction`` -- average number of dumps required to trigger major compaction in any range of the LSM tree." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:30 +msgid "Summary index statistics are also available via :ref:`box.stat.vinyl() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:33 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:36 +msgid "statistics" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/stat.rst:37 +msgid "table" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/tuple_pos.pot b/locale/en/reference/reference_lua/box_index/tuple_pos.pot new file mode 100644 index 0000000000..ad0e8ffbc8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/tuple_pos.pot @@ -0,0 +1,97 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:5 +msgid "index_object:tuple_pos()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:11 +msgid "Return a tuple's position for an index. This value can be passed to the ``after`` option of the ``select`` and ``pairs`` methods:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:14 +msgid ":ref:`index_object:select ` and :ref:`space_object:select `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:15 +msgid ":ref:`index_object:pairs ` and :ref:`space_object:pairs `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:17 +msgid "Note that ``tuple_pos`` does not work with :ref:`functional ` and multikey indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:19 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:21 +msgid "a tuple whose position should be found" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:23 +msgid "a tuple's position in a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:24 +msgid "base64-encoded string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:27 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:29 +msgid "To try out this example, you need to bootstrap a Tarantool instance as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/tuple_pos.rst:32 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +" bands:insert{5, 'Pink Floyd', 1965}\n" +" bands:insert{6, 'The Rolling Stones', 1962}\n" +"---\n" +"...\n" +"\n" +"-- Get a tuple's position --\n" +"tarantool> position = bands.index.primary:tuple_pos({3, 'Ace of Base', 1987})\n" +"---\n" +"...\n" +"-- Pass the tuple's position as the 'after' parameter --\n" +"tarantool> bands:select({}, {limit = 3, after = position})\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +" - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/type.pot b/locale/en/reference/reference_lua/box_index/type.pot new file mode 100644 index 0000000000..32b09dd38d --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/type.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/type.rst:5 +msgid "index_object.type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/type.rst:11 +msgid "The :ref:`index type `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/type.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/type.rst:13 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/type.rst:15 +msgid "**See also:** :ref:`index_opts.type `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/unique.pot b/locale/en/reference/reference_lua/box_index/unique.pot new file mode 100644 index 0000000000..5f1896ead8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/unique.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/unique.rst:5 +msgid "index_object.unique" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/unique.rst:11 +msgid "``true`` if the index is unique, ``false`` if the index is not unique." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/unique.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/unique.rst:13 +msgid "boolean" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/unique.rst:15 +msgid "**See also:** :ref:`index_opts.unique `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/update.pot b/locale/en/reference/reference_lua/box_index/update.pot new file mode 100644 index 0000000000..72b5fca861 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/update.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/update.rst:5 +msgid "index_object:update()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:11 +msgid "Update a tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:13 +msgid "Same as :ref:`box.space...update() `, but key is searched in this index instead of primary key. This index should be unique." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:17 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:19 +msgid "values to be matched against the index key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:20 +msgid "operation type represented in string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:21 +msgid "what field the operation will apply to. The field number can be negative, meaning the position from the end of tuple. (#tuple + negative field number + 1)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:25 +msgid "what value will be applied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:27 +msgid "the updated tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:28 +msgid "nil if the key is not found" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:29 +msgid "tuple or nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/update.rst:31 +msgid "Since Tarantool 2.3 a tuple can also be updated via :ref:`JSON paths`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_index/user_defined.pot b/locale/en/reference/reference_lua/box_index/user_defined.pot new file mode 100644 index 0000000000..973486c697 --- /dev/null +++ b/locale/en/reference/reference_lua/box_index/user_defined.pot @@ -0,0 +1,113 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:5 +msgid "index_object extensions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:7 +msgid "You can extend ``index_object`` with custom functions as follows:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:9 +msgid "Create a Lua function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:10 +msgid "Add the function name to a predefined global variable, which has the ``table`` type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:11 +msgid "Call the function on the ``index_object``: ``index_object:function-name([parameters])``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:13 +msgid "There are three predefined global variables:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:15 +msgid "Adding to ``box_schema.index_mt`` makes the function available for all indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:16 +msgid "Adding to ``box_schema.memtx_index_mt`` makes the function available for all memtx indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:17 +msgid "Adding to ``box_schema.vinyl_index_mt`` makes the function available for all vinyl indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:19 +msgid "Alternatively, you can make a user-defined function available for only one index by calling ``getmetatable(index_object)`` and then adding the function name to the meta table." +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:24 +msgid "**Example 1:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:26 +msgid "The example below shows how to extend all memtx indexes with the custom function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:28 +msgid "box.schema.space.create('tester1', { engine = 'memtx' })\n" +"box.space.tester1:create_index('index1')\n" +"global_counter = 5\n" +"\n" +"-- Create a custom function.\n" +"function increase_global_counter()\n" +" global_counter = global_counter + 1\n" +"end\n" +"\n" +"-- Extend all memtx indexes with the created function.\n" +"box.schema.memtx_index_mt.increase_global_counter = increase_global_counter\n" +"\n" +"-- Call the 'increase_global_counter' function on 'index1'\n" +"-- to change the 'global_counter' value from 5 to 6.\n" +"box.space.tester1.index.index1:increase_global_counter()\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:33 +msgid "**Example 2:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:35 +msgid "The example below shows how to extend the specified index with the custom function with parameters:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_index/user_defined.rst:37 +msgid "box.schema.space.create('tester2', { engine = 'memtx', id = 1000 })\n" +"box.space.tester2:create_index('index2')\n" +"local_counter = 0\n" +"\n" +"-- Create a custom function.\n" +"function increase_local_counter(i_arg, param)\n" +" local_counter = local_counter + param + i_arg.space_id\n" +"end\n" +"\n" +"-- Extend only the 'index2' index with the created function.\n" +"box.schema.memtx_index_mt.increase_local_counter = increase_local_counter\n" +"meta = getmetatable(box.space.tester2.index.index2)\n" +"meta.increase_local_counter = increase_local_counter\n" +"\n" +"-- Call the 'increase_local_counter' function on 'index2'\n" +"-- to change the 'local_counter' value from 0 to 1005.\n" +"box.space.tester2.index.index2:increase_local_counter(5)\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info.pot b/locale/en/reference/reference_lua/box_info.pot new file mode 100644 index 0000000000..92241a9dbf --- /dev/null +++ b/locale/en/reference/reference_lua/box_info.pot @@ -0,0 +1,209 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info.rst:5 +msgid "Submodule box.info" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:9 +msgid "The ``box.info`` submodule provides access to information about server instance variables." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:12 +msgid "**cluster.uuid** is the UUID of the replica set. Every instance in a replica set will have the same ``cluster.uuid`` value. This value is also stored in :ref:`box.space._schema ` system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:16 +msgid "**gc()** returns the state of the :ref:`Tarantool garbage collector ` including the checkpoints and their consumers (users); see details :doc:`here `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:20 +msgid "**id** corresponds to :samp:`replication[{n}].id` (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:22 +msgid "**lsn** corresponds to :samp:`replication[{n}].lsn` (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:24 +msgid "**listen** returns a real address to which an instance was bound (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:26 +msgid "**memory()** returns the statistics about memory (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:28 +msgid "**pid** is the process ID. This value is also shown by :ref:`tarantool ` module and by the Linux command ``ps -A``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:31 +msgid "**ro** is ``true`` if the instance is in read-only mode (same as :ref:`read_only ` in ``box.cfg{}``), or if status is 'orphan'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:34 +msgid "**ro_reason** is ``nil`` if the instance is in writable mode. When the field is not ``nil``, it contains the reason why the instance is read-only. Possible error reasons: ``election``, ``synchro``, ``config``, and ``orphan`` (see :ref:`box.info.ro_reason ` for details)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:38 +msgid "**signature** is the sum of all ``lsn`` values from each :ref:`vector clock ` (**vclock**) for all instances in the replica set." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:40 +msgid "**sql().cache.size** is the number of bytes in the SQL prepared statement cache." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:41 +msgid "**sql().cache.stmt_count** is the number of statements in the SQL prepared statement cache." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:42 +msgid "**status** is the current state of the instance. It can be:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:44 +msgid "``running`` -- the instance is loaded," +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:45 +msgid "``loading`` -- the instance is either recovering xlogs/snapshots or bootstrapping," +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:46 +msgid "``orphan`` -- the instance has not (yet) succeeded in joining the required number of masters (see :ref:`orphan status `)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:48 +msgid "``hot_standby`` -- the instance is :ref:`standing by ` another instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:49 +msgid "**uptime** is the number of seconds since the instance started. This value can also be retrieved with :ref:`tarantool.uptime() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:52 +msgid "**uuid** corresponds to :samp:`replication[{n}].uuid` (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:54 +msgid "**vclock** is a table with the vclock values of all instances in a replica set which have made data changes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:55 +msgid "**version** is the Tarantool version. This value is also shown by :ref:`tarantool -V `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:57 +msgid "**vinyl()** returns runtime statistics for the vinyl storage engine. This function is deprecated, use :ref:`box.stat.vinyl() ` instead." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:60 +msgid "**election** shows the current state of a replica set node regarding leader election (see :doc:`here `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:63 +msgid "Below is a list of all ``box.info`` functions and members." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:74 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:75 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:77 +msgid ":doc:`./box_info/info`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:78 +msgid "Return all keys and values provided in the submodule" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:80 +msgid ":doc:`./box_info/gc`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:81 +msgid "Return info about garbage collector" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:83 +msgid ":doc:`./box_info/memory`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:84 +msgid "Return info about memory usage" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:86 +msgid ":doc:`./box_info/replication_anon`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:87 +msgid "List all the anonymous replicas following the instance" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:89 +msgid ":doc:`./box_info/replication`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:90 +msgid "Return statistics for all instances in the replica set" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:92 +msgid ":doc:`./box_info/listen`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:93 +msgid "Return a real address to which an instance was bound" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:95 +msgid ":doc:`./box_info/election`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:96 +msgid "Show the current state of a replica set node in regards to leader election" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:99 +msgid ":doc:`./box_info/synchro`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:100 +msgid "Show the current state of synchronous replication" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:102 +msgid ":doc:`./box_info/ro_reason`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:103 +msgid "Show the current mode of an instance (writable or read-only)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:105 +msgid ":doc:`./box_info/schema_version`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info.rst:106 +msgid "Show the database schema version" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/election.pot b/locale/en/reference/reference_lua/box_info/election.pot new file mode 100644 index 0000000000..9b0c80a97a --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/election.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-07 07:21+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/election.rst:5 +msgid "box.info.election" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:11 +msgid "Since version :doc:`2.6.1 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:13 +msgid "Show the current state of a replica set node in regards to :ref:`leader election `. The following information is provided:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:16 +msgid "``state`` -- the election state (mode) of the node. Possible values are ``leader``, ``follower``, or ``candidate``. For more details, refer to description of the :ref:`leader election process `. When :ref:`replication.failover ` is set to ``election``, the node is writable only in the ``leader`` state." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:20 +msgid "``term`` -- the current election term." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:22 +msgid "``vote`` -- the ID of a node the current node votes for. If the value is ``0``, it means the node hasn't voted in the current term yet." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:24 +msgid "``leader`` -- a leader node ID in the current term. If the value is ``0``, it means the node doesn't know which node is the leader in the current term." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:26 +msgid "``leader_name`` -- a leader name. Returns ``nil`` if there is no leader in a cluster or :ref:`box.NULL ` if a leader does not have a name. Since version :doc:`3.0.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:28 +msgid "``leader_idle`` -- time in seconds since the last interaction with the known leader. Since version :doc:`2.10.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:32 +msgid "IDs in the ``box.info.election`` output are the replica IDs visible in the ``box.info.id`` output on each node and in the ``_cluster`` space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:34 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:36 +msgid "auto_leader:instance001> box.info.election\n" +"---\n" +"- leader_idle: 0\n" +" leader_name: instance001\n" +" state: leader\n" +" vote: 2\n" +" term: 3\n" +" leader: 2\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/election.rst:48 +msgid "See also: :ref:`Master-replica: automated failover `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/gc.pot b/locale/en/reference/reference_lua/box_info/gc.pot new file mode 100644 index 0000000000..79ad62b2f1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/gc.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:5 +msgid "box.info.gc()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:11 +msgid "The **gc** function of ``box.info`` gives the ``admin`` user a picture of the factors that affect the :ref:`Tarantool garbage collector `. The garbage collector compares vclock (:ref:`vector clock `) values of users and checkpoints, so a look at ``box.info.gc()`` may show why the garbage collector has not removed old WAL files, or show what it may soon remove." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:18 +msgid "**gc().consumers** -- a list of users whose requests might affect the garbage collector." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:19 +msgid "**gc().checkpoints** -- a list of preserved checkpoints." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:20 +msgid "**gc().checkpoints[n].references** -- a list of references to a checkpoint." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:21 +msgid "**gc().checkpoints[n].vclock** -- a checkpoint's vclock value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:22 +msgid "**gc().checkpoints[n].signature** -- a sum of a checkpoint's vclock's components." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:23 +msgid "**gc().checkpoint_is_in_progress** -- true if a checkpoint is in progress, otherwise false" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:24 +msgid "**gc().vclock** -- the garbage collector's vclock." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/gc.rst:25 +msgid "**gc().signature** -- the sum of the garbage collector's checkpoint's components." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/info.pot b/locale/en/reference/reference_lua/box_info/info.pot new file mode 100644 index 0000000000..b0515977a0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/info.pot @@ -0,0 +1,78 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/info.rst:5 +msgid "box.info()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:11 +msgid "Since ``box.info`` contents are dynamic, it's not possible to iterate over keys with the Lua ``pairs()`` function. For this purpose, ``box.info()`` builds and returns a Lua table with all keys and values provided in the submodule." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:16 +msgid "keys and values in the submodule" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:17 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:21 +msgid "This example is for a master-replica set that contains one master instance and one replica instance. The request was issued at the replica instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/info.rst:24 +msgid "tarantool> box.info()\n" +"---\n" +"- version: 2.4.0-251-gc44ed3c08\n" +" id: 1\n" +" ro: false\n" +" uuid: 1738767b-afa3-4987-b485-c333cf83415b\n" +" package: Tarantool\n" +" cluster:\n" +" uuid: 40ee7f0f-7070-4650-8883-801e7014407c\n" +" listen: '[::1]:57122'\n" +" replication:\n" +" 1:\n" +" id: 1\n" +" uuid: 1738767b-afa3-4987-b485-c333cf83415b\n" +" lsn: 16\n" +" signature: 16\n" +" status: running\n" +" vinyl: []\n" +" uptime: 21\n" +" lsn: 16\n" +" sql: []\n" +" gc: []\n" +" pid: 20293\n" +" memory: []\n" +" vclock: {1: 16}\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/listen.pot b/locale/en/reference/reference_lua/box_info/listen.pot new file mode 100644 index 0000000000..965d367dda --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/listen.pot @@ -0,0 +1,59 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:5 +msgid "box.info.listen" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:11 +msgid "Since version :doc:`2.4.1 `. Return a real address to which an instance was bound. For example, if ``box.cfg{listen}`` was set with a zero port, ``box.info.listen`` will show a real port. The address is stored as a string:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:16 +msgid "unix/: for UNIX domain sockets" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:17 +msgid ": for IPv4" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:18 +msgid "[ip]: for IPv6" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:20 +msgid "If an instance does not listen to anything, ``box.info.listen`` is nil." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:22 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/listen.rst:24 +msgid "tarantool> box.cfg{listen=0}\n" +"---\n" +"...\n" +"tarantool> box.cfg.listen\n" +"---\n" +"- '0'\n" +"...\n" +"tarantool> box.info.listen\n" +"---\n" +"- 0.0.0.0:44149\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/memory.pot b/locale/en/reference/reference_lua/box_info/memory.pot new file mode 100644 index 0000000000..711b23a14f --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/memory.pot @@ -0,0 +1,69 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:5 +msgid "box.info.memory()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:11 +msgid "The **memory** function of ``box.info`` gives the ``admin`` user a picture of the whole Tarantool instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:16 +msgid "To get a picture of the vinyl subsystem, use :ref:`box.stat.vinyl() ` instead." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:19 +msgid "**memory().cache** -- number of bytes used for caching user data. The memtx storage engine does not require a cache, so in fact this is the number of bytes in the cache for the tuples stored for the vinyl storage engine." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:23 +msgid "**memory().data** -- number of bytes used for storing user data (the tuples) with the memtx engine and with level 0 of the vinyl engine, without taking memory fragmentation into account." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:26 +msgid "**memory().index** -- number of bytes used for indexing user data, including memtx and vinyl memory tree extents, the vinyl page index, and the vinyl bloom filters." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:29 +msgid "**memory().lua** -- number of bytes used for Lua runtime." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:30 +msgid "**memory().net** -- number of bytes used for network input/output buffers." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:31 +msgid "**memory().tx** -- number of bytes in use by active transactions. For the vinyl storage engine, this is the total size of all allocated objects (struct ``txv``, struct ``vy_tx``, struct ``vy_read_interval``) and tuples pinned for those objects." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:36 +msgid "An example with a minimum allocation while only the memtx storage engine is in use:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/memory.rst:39 +msgid "tarantool> box.info.memory()\n" +"---\n" +"- cache: 0\n" +" data: 6552\n" +" tx: 0\n" +" lua: 1315567\n" +" net: 98304\n" +" index: 1196032\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/replication.pot b/locale/en/reference/reference_lua/box_info/replication.pot new file mode 100644 index 0000000000..e0bdc6d934 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/replication.pot @@ -0,0 +1,149 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 17:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:5 +msgid "box.info.replication" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:11 +msgid "The **replication** section of ``box.info()`` is a table with statistics for all instances in the replica set that the current instance belongs to. To see the example, refer to :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:14 +msgid "In the following, *n* is the index number of one table item, for example, :samp:`replication[1]`, which has data about server instance number 1, which may or may not be the same as the current instance (the \"current instance\" is what is responding to ``box.info``)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:19 +msgid ":samp:`replication[{n}].id` is a short numeric identifier of instance *n* within the replica set. This value is stored in the :ref:`box.space._cluster ` system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:23 +msgid ":samp:`replication[{n}].uuid` is a globally unique identifier of instance *n*. This value is stored in the :ref:`box.space._cluster ` system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:26 +msgid ":samp:`replication[{n}].lsn` is the :ref:`log sequence number ` (LSN) for the latest entry in instance *n*'s :ref:`write-ahead log ` (WAL)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:30 +msgid ":samp:`replication[{n}].upstream` appears (is not ``nil``) if the current instance is following or intending to follow instance *n*, which ordinarily means :samp:`replication[{n}].upstream.status` = ``follow``, :samp:`replication[{n}].upstream.peer` = url of instance *n* which is being followed, :samp:`replication[{n}].lag and idle` = the instance's speed, described later. Another way to say this is: :samp:`replication[{n}].upstream` will appear when :samp:`replication[{n}].upstream.peer` is not of the current instance, and is not read-only, and was specified in ``box.cfg{replication={...}}``, so it is shown in :ref:`box.cfg.replication `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:41 +msgid ":samp:`replication[{n}].upstream.status` is the replication status of the connection with the instance *n*:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:44 +msgid "``connect``: an instance is connecting to the master." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:45 +msgid "``auth``: :ref:`authentication ` is being performed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:46 +msgid "``wait_snapshot``: an instance is receiving metadata from the master. If join fails with a non-critical :ref:`error ` at this stage (for example, ``ER_READONLY``, ``ER_ACCESS_DENIED``, or a network-related issue), an instance tries to find a new master to join." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:47 +msgid "``fetch_snapshot``: an instance is receiving data from the master's ``.snap`` files." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:48 +msgid "``final_join``: an instance is receiving new data added during ``fetch_snapshot``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:49 +msgid "``sync``: the master and replica are synchronizing to have the same data." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:50 +msgid "``follow``: the current instance's role is **replica**. This means that the instance is read-only or acts as a replica for this remote peer in :ref:`master-master ` configuration. The instance is receiving or able to receive data from the instance *n*'s (upstream) master." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:53 +msgid "``stopped``: replication is stopped due to a replication error (for example, :ref:`duplicate key `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:55 +msgid "``disconnected``: an instance is not connected to the replica set (for example, due to network issues, not replication errors)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:58 +msgid "Learn more from :ref:`Replication stages `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:62 +msgid ":samp:`replication[{n}].upstream.idle` is the time (in seconds) since the last event was received. This is the primary indicator of replication health. Learn more from :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:69 +msgid ":samp:`replication[{n}].upstream.peer` contains instance *n*'s :ref:`URI `, for example, 127.0.0.1:3302. Learn more from :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:75 +msgid ":samp:`replication[{n}].upstream.lag` is the time difference between the local time of instance *n*, recorded when the event was received, and the local time at another master recorded when the event was written to the :ref:`write-ahead log ` on that master. Learn more from :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:81 +msgid ":samp:`replication[{n}].upstream.message` contains an error message in case of a :ref:`degraded state `; otherwise, it is ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:84 +msgid ":samp:`replication[{n}].downstream` appears (is not ``nil``) with data about an instance that is following instance *n* or is intending to follow it, which ordinarily means :samp:`replication[{n}].downstream.status` = ``follow``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:89 +msgid ":samp:`replication[{n}].downstream.vclock` contains the :ref:`vector clock `, which is a table of '**id**, **lsn**' pairs, for example, :code:`vclock: {1: 3054773, 4: 8938827, 3: 285902018}`. (Notice that the table may have multiple pairs although ``vclock`` is a singular name)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:96 +msgid "Even if instance *n* is :ref:`removed `, its values will still appear here; however, its values will be overridden if an instance joins later with the same UUID. Vector clock pairs will only appear if ``lsn > 0``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:101 +msgid ":samp:`replication[{n}].downstream.vclock` may be the same as the current instance's vclock (``box.info.vclock``) because this is for all known vclock values of the cluster. A master will know what is in a replica's copy of vclock because, when the master makes a data change, it sends the change information to the replica (including the master's vector clock), and the replica replies with what is in its entire vector clock table." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:110 +msgid "A replica also sends its entire vector clock table in response to a master's heartbeat message, see the heartbeat-message examples in the section :ref:`Binary protocol -- replication `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:114 +msgid ":samp:`replication[{n}].downstream.idle` is the time (in seconds) since the last time that instance *n* sent events through the downstream replication." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:117 +msgid ":samp:`replication[{n}].downstream.status` is the replication status for downstream replications:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:120 +msgid "``stopped`` means that downstream replication has stopped," +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:121 +msgid "``follow`` means that downstream replication is in progress (instance *n* is ready to accept data from the master or is currently doing so)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:124 +msgid ":samp:`replication[{n}].downstream.lag` is the time difference between the local time at the master node, recorded when a particular transaction was written to the :ref:`write-ahead log `, and the local time recorded when it receives an acknowledgment for this transaction from a replica. Since version :doc:`2.10.0 `. See more in :ref:`Monitoring a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication.rst:131 +msgid ":samp:`replication[{n}].downstream.message` and :samp:`replication[{n}].downstream.system_message` will be ``nil`` unless a problem occurs with the connection. For example, if instance *n* goes down, then one may see ``status = 'stopped'``, ``message = 'unexpected EOF when reading from socket'``, and ``system_message = 'Broken pipe'``. See also :ref:`degraded state `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/replication_anon.pot b/locale/en/reference/reference_lua/box_info/replication_anon.pot new file mode 100644 index 0000000000..2ddc52e3a0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/replication_anon.pot @@ -0,0 +1,68 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:5 +msgid "box.info.replication_anon()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:11 +msgid "List all the :ref:`anonymous replicas ` following the instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:14 +msgid "The output is similar to the one produced by ``box.info.replication`` with an exception that anonymous replicas are indexed by their uuid strings rather than server ids, since server ids have no meaning for anonymous replicas." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:19 +msgid "Notice that when you issue a plain ``box.info.replication_anon``, the only info returned is the number of anonymous replicas following the current instance. In order to see the full stats, you have to call ``box.info.replication_anon()``. This is done to not overload the ``box.info`` output with excess info, since there may be lots of anonymous replicas." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:25 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:27 +msgid "tarantool> box.info.replication_anon\n" +"---\n" +"- count: 2\n" +"...\n" +"\n" +"tarantool> box.info.replication_anon()\n" +"---\n" +"- 3a6a2cfb-7e47-42f6-8309-7a25c37feea1:\n" +" id: 0\n" +" uuid: 3a6a2cfb-7e47-42f6-8309-7a25c37feea1\n" +" lsn: 0\n" +" downstream:\n" +" status: follow\n" +" idle: 0.76203499999974\n" +" vclock: {1: 1}\n" +" f58e4cb0-e0a8-42a1-b439-591dd36c8e5e:\n" +" id: 0\n" +" uuid: f58e4cb0-e0a8-42a1-b439-591dd36c8e5e\n" +" lsn: 0\n" +" downstream:\n" +" status: follow\n" +" idle: 0.0041349999992235\n" +" vclock: {1: 1}\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/replication_anon.rst:54 +msgid "Notice that anonymous replicas hide their ``lsn`` from the others, so an anonymous replica ``lsn`` will always be reported as zero, even if an anonymous replica performs some local space operations. To find out the ``lsn`` of a specific anonymous replica, you have to issue ``box.info.lsn`` on it." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/ro_reason.pot b/locale/en/reference/reference_lua/box_info/ro_reason.pot new file mode 100644 index 0000000000..10e99a20a2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/ro_reason.pot @@ -0,0 +1,64 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:5 +msgid "box.info.ro_reason" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:11 +msgid "Since :doc:`2.10.0 `. Show the current mode of an instance (writable or read-only). Contains ``nil`` if the instance is in writable mode. When the field is not ``nil``, reports the reason why the instance is read-only." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:16 +msgid "Possible error reasons:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:18 +msgid "``election`` -- the instance is not the leader. That is, ``box.cfg.election_mode`` is not ``off``. See :ref:`box.info.election ` for details." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:22 +msgid "``synchro`` -- the instance is not the owner of the synchronous transaction queue. For details, see :ref:`box.info.synchro `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:25 +msgid "``config`` -- the server instance is in read-only mode. That is, :ref:`box.cfg.read_only ` is ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:28 +msgid "``orphan`` -- the instance is in ``orphan`` state. For details, see :ref:`the orphan status page `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:31 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:33 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/ro_reason.rst:35 +msgid "tarantool> box.info.ro_reason\n" +"---\n" +"- null\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/schema_version.pot b/locale/en/reference/reference_lua/box_info/schema_version.pot new file mode 100644 index 0000000000..f0dd2bffa5 --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/schema_version.pot @@ -0,0 +1,48 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:4 +msgid "box.info.schema_version" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:10 +msgid "Since :doc:`2.11.0 `. Show the database schema version. A schema version is a number that indicates whether the :ref:`database schema ` is changed. For example, the ``schema_version`` value grows if a :ref:`space ` or :ref:`index ` is added or deleted, or a space, index, or field name is changed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:15 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:17 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:19 +msgid "tarantool> box.info.schema_version\n" +"---\n" +"- 84\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/schema_version.rst:26 +msgid "See also: :ref:`IPROTO_SCHEMA_VERSION `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_info/synchro.pot b/locale/en/reference/reference_lua/box_info/synchro.pot new file mode 100644 index 0000000000..0862e01b5b --- /dev/null +++ b/locale/en/reference/reference_lua/box_info/synchro.pot @@ -0,0 +1,170 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:5 +msgid "box.info.synchro" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:11 +msgid "Since version :doc:`2.8.1 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:13 +msgid "Show the current state of synchronous replication." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:15 +msgid "In :ref:`synchronous replication `, transaction is considered committed only after achieving the required quorum number. While transactions are collecting confirmations from remote nodes, these transactions are waiting in the queue." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:19 +msgid "The following information is provided:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:21 +msgid "``queue``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:23 +msgid "``owner`` (since version :doc:`2.10.0 `) -- ID of the replica that owns the synchronous transaction queue. Once an owner instance appears, all other instances become read-only. If the ``owner`` field is ``0``, then every instance may be writable, but they can't create any synchronous transactions. To claim or reclaim the queue, use :ref:`box.ctl.promote() ` on the instance that you want to promote. With elections enabled, an instance runs ``box.ctl.promote()`` command automatically after winning the elections. To clear the ownership, call :ref:`box.ctl.demote() ` on the synchronous queue owner." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:32 +msgid "``term`` (since version :doc:`2.10.0 `) -- current queue term. It contains the term of the last ``PROMOTE`` request. Usually, it is equal to :ref:`box.info.election.term `. However, the queue term value may be less than the election term. It can happen when a new round of elections has started, but no instance has been promoted yet." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:38 +msgid "``len`` -- the number of entries that are currently waiting in the queue." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:40 +msgid "``busy`` (since version :doc:`2.10.0 `) -- the boolean value is ``true`` when the instance is processing or writing some system request that modifies the queue (for example, ``PROMOTE``, ``CONFIRM``, or ``ROLLBACK``). Until the request is complete, any other incoming synchronous transactions and system requests will be delayed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:46 +msgid "``quorum`` -- the resulting value of the :ref:`replication_synchro_quorum ` configuration option. Since version :doc:`2.5.3 `, the option can be set as a dynamic formula. In this case, the value of the ``quorum`` member depends on the current number of replicas." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:51 +msgid "**Example 1:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:53 +msgid "In this example, the ``quorum`` field is equal to ``1``. That is, synchronous transactions work like asynchronous ones. `1` means that a successful WAL writing to the master is enough to commit." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:57 +msgid "tarantool> box.info.synchro\n" +"---\n" +"- queue:\n" +" owner: 1\n" +" term: 2\n" +" len: 0\n" +" busy: false\n" +" quorum: 1\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:69 +msgid "**Example 2:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:71 +msgid "First, set a quorum number and a timeout for synchronous replication using the following command:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:73 +msgid "tarantool> box.cfg{\n" +" > replication_synchro_quorum=2,\n" +" > replication_synchro_timeout=1000\n" +" > }" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:80 +msgid "Next, check the current state of synchronous replication:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:82 +msgid "tarantool> box.info.synchro\n" +"---\n" +"- queue:\n" +" owner: 1\n" +" term: 2\n" +" len: 0\n" +" busy: false\n" +" quorum: 2\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:94 +msgid "Create a space called ``sync`` and enable synchronous replication on this space. Then, create an index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:97 +msgid "tarantool> s = box.schema.space.create(\"sync\", {is_sync=true})\n" +"tarantool> _ = s:create_index('pk')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:102 +msgid "After that, use ``box.ctl.promote()`` function to claim a queue:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:104 +msgid "tarantool> box.ctl.promote()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:108 +msgid "Next, perform data manipulations:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:110 +msgid "tarantool> require('fiber').new(function() box.space.sync:replace{1} end)\n" +"---\n" +"- status: suspended\n" +" name: lua\n" +" id: 119\n" +"...\n" +"tarantool> require('fiber').new(function() box.space.sync:replace{1} end)\n" +"---\n" +"- status: suspended\n" +" name: lua\n" +" id: 120\n" +"...\n" +"tarantool> require('fiber').new(function() box.space.sync:replace{1} end)\n" +"---\n" +"- status: suspended\n" +" name: lua\n" +" id: 121\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:131 +msgid "If you call the ``box.info.synchro`` command again, you will see that now there are 3 transactions waiting in the queue:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_info/synchro.rst:134 +msgid "tarantool> box.info.synchro\n" +"---\n" +"- queue:\n" +" owner: 1\n" +" term: 2\n" +" len: 3\n" +" busy: false\n" +" quorum: 2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto.pot b/locale/en/reference/reference_lua/box_iproto.pot new file mode 100644 index 0000000000..69a1fa6db6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto.pot @@ -0,0 +1,254 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto.rst:4 +msgid "Submodule box.iproto" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:6 +msgid "Since :doc:`2.11.0 `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:8 +msgid "The ``box.iproto`` submodule provides the ability to work with the network subsystem of Tarantool. It allows you to extend the :ref:`IPROTO ` functionality from Lua. With this submodule, you can:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:12 +msgid ":ref:`parse unknown IPROTO request types `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:13 +msgid ":ref:`send arbitrary IPROTO packets `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:14 +msgid ":ref:`override the behavior ` of the existing and unknown request types in the binary protocol" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:16 +msgid "The submodule exports all IPROTO :ref:`constants ` and :ref:`features ` to Lua." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:21 +msgid "IPROTO constants" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:23 +msgid "IPROTO constants in the ``box.iproto`` namespace are written in uppercase letters without the ``IPROTO_`` prefix. The constants are divided into several groups:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:26 +msgid ":ref:`key `. Example: :ref:`IPROTO_SYNC `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:27 +msgid ":ref:`request type `. Example: :ref:`IPROTO_OK `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:28 +msgid ":ref:`flag `. Example: :ref:`IPROTO_COMMIT `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:29 +msgid ":ref:`ballot key `. Example: :ref:`IPROTO_FLAG_COMMIT `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:30 +msgid ":ref:`metadata key `. Example: :ref:`IPROTO_FIELD_IS_NULLABLE `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:31 +msgid ":ref:`RAFT key `. Example: :ref:`IPROTO_TERM `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:33 +msgid "Each group is located in the corresponding subnamespace without the prefix. For example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:36 +msgid "box.iproto.key.SYNC = 0x01\n" +"-- ...\n" +"box.iproto.type.SELECT = 1\n" +"-- ...\n" +"box.iproto.flag.COMMIT = 1\n" +"-- ...\n" +"box.iproto.ballot_key.VCLOCK = 2\n" +"-- ...\n" +"box.iproto.metadata_key.IS_NULLABLE = 3\n" +"-- ...\n" +"box.iproto.raft_key.TERM = 0\n" +"-- ..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:54 +msgid "IPROTO features" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:56 +msgid "The submodule exports:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:58 +msgid "the current IPROTO protocol version (:ref:`box.iproto.protocol_version `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:59 +msgid "the set of IPROTO protocol features supported by the server (:ref:`box.iproto.protocol_features `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:60 +msgid "IPROTO protocol features with the corresponding code (:ref:`box.iproto.feature `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:62 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:64 +msgid "The example converts the feature names from ``box.iproto.protocol_features`` set into codes:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:66 +msgid "-- Features supported by the server\n" +"box.iproto.protocol_features = {\n" +" streams = true,\n" +" transactions = true,\n" +" error_extension = true,\n" +" watchers = true,\n" +" pagination = true,\n" +"}\n" +"\n" +"-- Convert the feature names into codes\n" +"features = {}\n" +"for name in pairs(box.iproto.protocol_features) do\n" +" table.insert(features, box.iproto.feature[name])\n" +"end\n" +"return features -- [0, 1, 2, 3, 4]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:87 +msgid "Handling the unknown IPROTO request types" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:89 +msgid "Every IPROTO request has a static handler. That is, before version :doc:`2.11.0 `, any unknown request raised an error. Since :doc:`2.11.0 `, a new request type is introduced -- :ref:`IPROTO_UNKNOWN `. This type is used to override the handlers of the unknown IPROTO request types. For details, see :ref:`box.iproto.override() ` and :ref:`box_iproto_override ` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:98 +msgid "API reference" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:100 +msgid "The table lists all available functions and data of the submodule:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:111 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:112 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:114 +msgid ":doc:`./box_iproto/key`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:115 +msgid "Request keys" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:117 +msgid ":doc:`./box_iproto/request_type`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:118 +msgid "Request types" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:120 +msgid ":doc:`./box_iproto/flag`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:121 +msgid "Flags from the :ref:`IPROTO_FLAGS ` key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:123 +msgid ":doc:`./box_iproto/ballot`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:124 +msgid "Keys from the :ref:`IPROTO_BALLOT ` requests" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:126 +msgid ":doc:`./box_iproto/metadata`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:127 +msgid "Keys nested in the :ref:`IPROTO_METADATA ` key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:129 +msgid ":doc:`./box_iproto/raft`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:130 +msgid "Keys from the ``IPROTO_RAFT_`` requests" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:132 +msgid ":doc:`./box_iproto/protocol_version`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:133 +msgid "The current IPROTO protocol version" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:135 +msgid ":doc:`./box_iproto/protocol_features`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:136 +msgid "The set of supported IPROTO protocol features" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:138 +msgid ":doc:`./box_iproto/feature`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:139 +msgid "IPROTO protocol :ref:`features `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:141 +msgid ":doc:`./box_iproto/override`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:142 +msgid "Set a new IPROTO request handler callback for the given request type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:144 +msgid ":doc:`./box_iproto/send`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto.rst:145 +msgid "Send an IPROTO packet over the session's socket" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/ballot.pot b/locale/en/reference/reference_lua/box_iproto/ballot.pot new file mode 100644 index 0000000000..42d6e101de --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/ballot.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/ballot.rst:4 +msgid "box.iproto.ballot_key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/ballot.rst:10 +msgid "Contains the keys from the :ref:`IPROTO_BALLOT ` requests. Learn more: :ref:`IPROTO_BALLOT keys `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/ballot.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/ballot.rst:15 +msgid "tarantool> box.iproto.ballot_key.IS_RO_CFG\n" +"---\n" +"- 1\n" +"...\n" +"tarantool> box.iproto.ballot_key.VCLOCK\n" +"---\n" +"- 2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/feature.pot b/locale/en/reference/reference_lua/box_iproto/feature.pot new file mode 100644 index 0000000000..818b021b40 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/feature.pot @@ -0,0 +1,52 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:4 +msgid "box.iproto.feature" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:10 +msgid "Contains the IPROTO protocol features that are supported by the server. Each feature is mapped to its corresponding code. Learn more: :ref:`IPROTO_FEATURES `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:14 +msgid "The features in the namespace are written" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:16 +msgid "in lowercase letters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:17 +msgid "without the ``IPROTO_FEATURE_`` prefix" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:19 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/feature.rst:21 +msgid "tarantool> box.iproto.feature.streams\n" +"---\n" +"- 0\n" +"...\n" +"tarantool> box.iproto.feature.transactions\n" +"---\n" +"- 1\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/flag.pot b/locale/en/reference/reference_lua/box_iproto/flag.pot new file mode 100644 index 0000000000..5183f90da3 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/flag.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/flag.rst:4 +msgid "box.iproto.flag" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/flag.rst:10 +msgid "Contains the flags from the ``IPROTO_FLAGS`` key. Learn more: :ref:`IPROTO_FLAGS key `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/flag.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/flag.rst:15 +msgid "tarantool> box.iproto.flag.COMMIT\n" +"---\n" +"- 1\n" +"...\n" +"tarantool> box.iproto.flag.WAIT_SYNC\n" +"---\n" +"- 2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/key.pot b/locale/en/reference/reference_lua/box_iproto/key.pot new file mode 100644 index 0000000000..0ad3ecda8d --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/key.pot @@ -0,0 +1,36 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/key.rst:4 +msgid "box.iproto.key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/key.rst:10 +msgid "Contains all available request keys, except :ref:`raft `, :ref:`metadata `, and :ref:`ballot ` keys. Learn more: :ref:`Keys used in requests and responses `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/key.rst:14 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/key.rst:16 +msgid "tarantool> box.iproto.key.SYNC\n" +"---\n" +"- 1\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/metadata.pot b/locale/en/reference/reference_lua/box_iproto/metadata.pot new file mode 100644 index 0000000000..62a9bbd9c9 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/metadata.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/metadata.rst:4 +msgid "box.iproto.metadata_key" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/metadata.rst:10 +msgid "Contains the ``IPROTO_FIELD_*`` keys, which are nested in the :ref:`IPROTO_METADATA ` key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/metadata.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/metadata.rst:15 +msgid "tarantool> box.iproto.metadata_key.NAME\n" +"---\n" +"- 0\n" +"...\n" +"tarantool> box.iproto.metadata_key.TYPE\n" +"---\n" +"- 1\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/override.pot b/locale/en/reference/reference_lua/box_iproto/override.pot new file mode 100644 index 0000000000..0842dcc299 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/override.pot @@ -0,0 +1,147 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-06 10:08+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:4 +msgid "box.iproto.override()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:10 +msgid "Since version :doc:`2.11.0 `. Set a new IPROTO request handler callback for the given request type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:13 +msgid "a request type code. Possible values: * a type code from :ref:`box.iproto.type ` (except ``box.iproto.type.UNKNOWN``) -- override the existing request type handler. * ``box.iproto.type.UNKNOWN`` -- override the handler of unknown request types." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:13 +msgid "a request type code. Possible values:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:15 +msgid "a type code from :ref:`box.iproto.type ` (except ``box.iproto.type.UNKNOWN``) -- override the existing request type handler." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:18 +msgid "``box.iproto.type.UNKNOWN`` -- override the handler of unknown request types." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:20 +msgid "IPROTO request handler. The signature of a handler function: ``function(sid, header, body)``, where * ``header`` (userdata): a request header encoded as a :ref:`msgpack_object ` * ``body`` (userdata): a request body encoded as a :ref:`msgpack_object ` Returns ``true`` on success, otherwise ``false``. On ``false``, there is a fallback to the default handler. Also, you can indicate an error by throwing an exception. In this case, the return value is ``false``, but this does not always mean a failure. To reset the request handler, set the ``handler`` parameter to ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:20 +msgid "IPROTO request handler. The signature of a handler function: ``function(sid, header, body)``, where" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:23 +msgid "``header`` (userdata): a request header encoded as a :ref:`msgpack_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:24 +msgid "``body`` (userdata): a request body encoded as a :ref:`msgpack_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:26 +msgid "Returns ``true`` on success, otherwise ``false``. On ``false``, there is a fallback to the default handler. Also, you can indicate an error by throwing an exception. In this case, the return value is ``false``, but this does not always mean a failure." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:30 +msgid "To reset the request handler, set the ``handler`` parameter to ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:32 +msgid "none" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:34 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:36 +msgid "If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call. The following errors are returned to the client over IPROTO (see `src/lua/utils.h `__):" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:39 +msgid ":errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:40 +msgid "diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:42 +msgid "For details, see `src/box/errcode.h `__." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:46 +msgid "When using ``box.iproto.override()``, it is important that you follow the wire protocol. That is, the server response should match the return value types of the corresponding request type. Otherwise, it could lead to peer breakdown or undefined behavior." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:50 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:52 +msgid "Define a handler function for the ``box.iproto.type.SELECT`` request type:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:54 +msgid "local function iproto_select_handler_lua(header, body)\n" +" if body.space_id == 512 then\n" +" box.iproto.send(box.session.id(),\n" +" { request_type = box.iproto.type.OK,\n" +" sync = header.SYNC,\n" +" schema_version = box.info.schema_version },\n" +" { data = { 1, 2, 3 } })\n" +" return true\n" +" end\n" +" return false\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:68 +msgid "Override ``box.iproto.type.SELECT`` handler:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:70 +msgid "box.iproto.override(box.iproto.type.SELECT, iproto_select_handler_lua)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:74 +msgid "Reset ``box.iproto.type.SELECT`` handler:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:76 +msgid "box.iproto.override(box.iproto.type.SELECT, nil)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:80 +msgid "Override a handler function for the unknown request type:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/override.rst:82 +msgid "box.iproto.override(box.iproto.type.UNKNOWN, iproto_unknown_request_handler_lua)" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/protocol_features.pot b/locale/en/reference/reference_lua/box_iproto/protocol_features.pot new file mode 100644 index 0000000000..41cfae7208 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/protocol_features.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_features.rst:4 +msgid "box.iproto.protocol_features" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_features.rst:10 +msgid "The set of IPROTO protocol features supported by the server. Learn more: :ref:`net.box features `, `src/box/iproto_features.h `__, and `iproto_features_resolve() `__." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_features.rst:14 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_features.rst:16 +msgid "tarantool> box.iproto.protocol_features\n" +"---\n" +"- transactions: true\n" +" watchers: true\n" +" error_extension: true\n" +" streams: true\n" +" pagination: true\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/protocol_version.pot b/locale/en/reference/reference_lua/box_iproto/protocol_version.pot new file mode 100644 index 0000000000..454cfef1b2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/protocol_version.pot @@ -0,0 +1,36 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_version.rst:4 +msgid "box.iproto.protocol_version" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_version.rst:10 +msgid "The current IPROTO protocol version of the server. Learn more: :ref:`IPROTO_ID `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_version.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/protocol_version.rst:15 +msgid "tarantool> box.iproto.protocol_version\n" +"---\n" +"- 4\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/raft.pot b/locale/en/reference/reference_lua/box_iproto/raft.pot new file mode 100644 index 0000000000..0c0e9a7889 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/raft.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/raft.rst:4 +msgid "box.iproto.raft" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/raft.rst:10 +msgid "Contains the keys from the ``IPROTO_RAFT_*`` requests. Learn more: :ref:`Synchronous replication keys `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/raft.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/raft.rst:15 +msgid "tarantool> box.iproto.raft_key.TERM\n" +"---\n" +"- 0\n" +"...\n" +"tarantool> box.iproto.raft_key.VOTE\n" +"---\n" +"- 1\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/request_type.pot b/locale/en/reference/reference_lua/box_iproto/request_type.pot new file mode 100644 index 0000000000..384a718281 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/request_type.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/request_type.rst:4 +msgid "box.iproto.type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/request_type.rst:10 +msgid "Contains all available request types. Learn more about the requests: :ref:`Client-server requests and responses `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/request_type.rst:13 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/request_type.rst:15 +msgid "tarantool> box.iproto.type.UNKNOWN\n" +"---\n" +"- -1\n" +"...\n" +"tarantool> box.iproto.type.CHUNK\n" +"---\n" +"- 128\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_iproto/send.pot b/locale/en/reference/reference_lua/box_iproto/send.pot new file mode 100644 index 0000000000..ce8d12b7a6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_iproto/send.pot @@ -0,0 +1,132 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:4 +msgid "box.iproto.send()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:10 +msgid "Since version :doc:`2.11.0 `. Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header and body. The header and body contain exported IPROTO constants from the :ref:`box.iproto() ` submodule. Possible IPROTO constant formats:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:16 +msgid "a lowercase constant without the ``IPROTO_`` prefix (``schema_version``, ``request_type``)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:17 +msgid "a constant from the corresponding :ref:`box.iproto ` subnamespace (``box.iproto.SCHEMA_VERSION``, ``box.iproto.REQUEST_TYPE``)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:19 +msgid "The function works for binary sessions only. For details, see :ref:`box.session.type() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:21 +msgid "the IPROTO session identifier (see :ref:`box.session.id() `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:22 +msgid "a request header encoded as MsgPack" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:23 +msgid "a request body encoded as MsgPack" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:25 +msgid "0 on success, otherwise an error is raised" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:26 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:28 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:30 +msgid ":errcode:`ER_SESSION_CLOSED` -- the session is closed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:31 +msgid ":errcode:`ER_NO_SUCH_SESSION` -- the session does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:32 +msgid ":errcode:`ER_MEMORY_ISSUE` -- out-of-memory limit has been reached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:33 +msgid ":errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:35 +msgid "For details, see `src/box/errcode.h `__." +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:37 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:39 +msgid "Send a packet using Lua tables and string IPROTO constants as keys:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:41 +msgid "box.iproto.send(box.session.id(),\n" +" { request_type = box.iproto.type.OK,\n" +" sync = 10,\n" +" schema_version = box.info.schema_version },\n" +" { data = 1 })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:49 +msgid "Send a packet using Lua tables and numeric IPROTO constants:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:51 +msgid "box.iproto.send(box.session.id(),\n" +" { [box.iproto.key.REQUEST_TYPE] = box.iproto.type.OK,\n" +" [box.iproto.key.SYNC] = 10,\n" +" [box.iproto.key.SCHEMA_VERSION] = box.info.schema_version },\n" +" { [box.iproto.key.DATA] = 1 })" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:59 +msgid "Send a packet that contains only the header:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_iproto/send.rst:61 +msgid "box.iproto.send(box.session.id(),\n" +" { request_type = box.iproto.type.OK,\n" +" sync = 10,\n" +" schema_version = box.info.schema_version })" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_null.pot b/locale/en/reference/reference_lua/box_null.pot new file mode 100644 index 0000000000..07ef57a040 --- /dev/null +++ b/locale/en/reference/reference_lua/box_null.pot @@ -0,0 +1,169 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_null.rst:5 +msgid "Constant box.NULL" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:7 +msgid "There are some major problems with using Lua **nil** values in tables. For example: you can't correctly assess the length of a table that is not a sequence. (Learn more about data types in `Lua `__ and `LuaJIT `__.)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:12 +#: ../../doc/reference/reference_lua/box_null.rst:60 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:14 +msgid "tarantool> t = {0, nil, 1, 2, nil}\n" +"---\n" +"...\n" +"\n" +"tarantool> t\n" +"---\n" +"- - 0\n" +" - null\n" +" - 1\n" +" - 2\n" +"...\n" +"\n" +"tarantool> #t\n" +"---\n" +"- 4\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:33 +msgid "The console output of ``t`` processes **nil** values in the middle and at the end of the table differently. This is due to undefined behavior." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:38 +msgid "Trying to find the length for sparse arrays in LuaJIT leads to another scenario of `undefined behavior `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:42 +msgid "To avoid this problem, use Tarantool's ``box.NULL`` constant instead of **nil**. ``box.NULL`` is a placeholder for a **nil** value in tables to preserve a key without a value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:48 +msgid "Using box.NULL" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:50 +msgid "``box.NULL`` is a value of the `cdata `__ type representing a NULL pointer. It is similar to ``msgpack.NULL``, ``json.NULL`` and ``yaml.NULL``. So it is some not **nil** value, even if it is a pointer to NULL." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:54 +msgid "Use ``box.NULL`` only with capitalized NULL (``box.null`` is incorrect)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:58 +msgid "Technically speaking, ``box.NULL`` equals to ``ffi.cast('void *', 0)``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:62 +msgid "tarantool> t = {0, box.NULL, 1, 2, box.NULL}\n" +"---\n" +"...\n" +"\n" +"tarantool> t\n" +"---\n" +"- - 0\n" +" - null # cdata\n" +" - 1\n" +" - 2\n" +" - null # cdata\n" +"...\n" +"\n" +"tarantool> #t\n" +"---\n" +"- 5\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:84 +msgid "Notice that ``t[2]`` shows the same ``null`` output in both examples. However in this example ``t[2]`` and ``t[5]`` are of the cdata type, while in the previous example their type was **nil**." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:90 +msgid "Avoid using implicit comparisons with nullable values when using ``box.NULL``. Due to `Lua behavior `_, returning anything except **false** or **nil** from a condition expression is considered as **true**. And, as it was mentioned earlier, ``box.NULL`` is a pointer by design." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:96 +msgid "That is why the expression ``box.NULL`` will always be considered **true** in case it is used as a condition in a comparison. This means that the code" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:99 +msgid "``if box.NULL then func() end``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:101 +msgid "will always execute the function ``func()`` (because the condition ``box.NULL`` will always be neither **false** nor **nil**)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:106 +msgid "Distinction of nil and box.NULL" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:108 +msgid "Use the expression ``if x == nil`` to check if the ``x`` is either a **nil** or a ``box.NULL``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:111 +msgid "To check whether ``x`` is a **nil** but not a ``box.NULL``, use the following condition expression:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:114 +msgid "type(x) == 'nil'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:118 +msgid "If it's **true**, then ``x`` is a **nil**, but not a ``box.NULL``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:120 +msgid "You can use the following for ``box.NULL``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:122 +msgid "x == nil and type(x) == 'cdata'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:126 +msgid "If the expression above is **true**, then ``x`` is a ``box.NULL``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:130 +msgid "By converting data to different formats (JSON, YAML, msgpack), you shall expect that it is possible that **nil** in sparse arrays will be converted to ``box.NULL``. And it is worth mentioning that such conversion might be unexpected (for example: by sending data via :ref:`net.box ` or by obtaining data from :ref:`spaces ` etc.)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:136 +msgid "tarantool> type(({1, nil, 2})[2])\n" +"---\n" +"- nil\n" +"...\n" +"\n" +"tarantool> type(json.decode(json.encode({1, nil, 2}))[2])\n" +"---\n" +"- cdata\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_null.rst:148 +msgid "You must anticipate such behavior and use a proper condition expression. Use the explicit comparison ``x == nil`` for checking for NULL in nullable values. It will detect both **nil** and ``box.NULL``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_once.pot b/locale/en/reference/reference_lua/box_once.pot new file mode 100644 index 0000000000..9360182d59 --- /dev/null +++ b/locale/en/reference/reference_lua/box_once.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_once.rst:5 +msgid "Function box.once" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:9 +msgid "Execute a function, provided it has not been executed before. A passed value is checked to see whether the function has already been executed. If it has been executed before, nothing happens. If it has not been executed before, the function is invoked." +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:14 +msgid "See an example of using ``box.once()`` while :ref:`bootstrapping a replica set `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:17 +msgid "**Warning:** If an error occurs inside ``box.once()`` when initializing a database, you can re-execute the failed ``box.once()`` block without stopping the database. The solution is to delete the ``once`` object from the system space :ref:`_schema `. Say ``box.space._schema:select{}``, find your ``once`` object there and delete it. For example, re-executing a block with ``key='hello'`` :" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:24 +msgid "When ``box.once()`` is used for initialization, it may be useful to wait until the database is in an appropriate state (read-only or read-write). In that case, see the functions in the :doc:`/reference/reference_lua/box_ctl`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:28 +msgid "tarantool> box.space._schema:select{}\n" +"---\n" +"- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']\n" +" - ['max_id', 512]\n" +" - ['oncebye']\n" +" - ['oncehello']\n" +" - ['version', 1, 7, 2]\n" +"...\n" +"\n" +"tarantool> box.space._schema:delete('oncehello')\n" +"---\n" +"- ['oncehello']\n" +"...\n" +"\n" +"tarantool> box.once('hello', function() end)\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:48 +msgid "a value that will be checked" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:49 +msgid "a function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:50 +msgid "arguments that must be passed to function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_once.rst:54 +msgid "The parameter ``key`` will be stored in the :ref:`_schema ` system space after ``box.once()`` is called in order to prevent a double run. These keys are global per replica set. So a simultaneous call of ``box.once()`` with the same key on two instances of the same replica set may succeed on both of them, but it'll lead to a transaction conflict." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_read_view.pot b/locale/en/reference/reference_lua/box_read_view.pot new file mode 100644 index 0000000000..6d0c253c20 --- /dev/null +++ b/locale/en/reference/reference_lua/box_read_view.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_read_view.rst:3 +msgid "Submodule box.read_view" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view.rst:5 +msgid "The box.read_view submodule contains functions related to read views." +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view.rst:16 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view.rst:17 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view.rst:19 +msgid ":doc:`./box_read_view/list`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view.rst:20 +msgid "Return an array of all active database read views." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_read_view/list.pot b/locale/en/reference/reference_lua/box_read_view/list.pot new file mode 100644 index 0000000000..28d6d057be --- /dev/null +++ b/locale/en/reference/reference_lua/box_read_view/list.pot @@ -0,0 +1,65 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:5 +msgid "box.read_view.list()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:9 +msgid "Return an array of all active database read views. This array might include the following read view types:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:12 +msgid ":ref:`read views ` created by application code (Enterprise Edition only)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:14 +msgid "system read views (used, for example, to make a :ref:`checkpoint ` or join a new :ref:`replica `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:17 +msgid "Read views created by application code also have the ``space`` field. The field lists all spaces available in a read view, and may be used like a read view object returned by ``box.read_view.open()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:23 +msgid "``read_view.list()`` also contains read views created using the :ref:`C API ` (:ref:`box_raw_read_view_new() `). Note that you cannot access database spaces included in such views from Lua." +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:28 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_read_view/list.rst:30 +msgid "tarantool> box.read_view.list()\n" +"---\n" +"- - timestamp: 1138.98706933\n" +" signature: 47\n" +" is_system: false\n" +" status: open\n" +" vclock: &0 {1: 47}\n" +" name: read_view1\n" +" id: 1\n" +" - timestamp: 1172.202995842\n" +" signature: 49\n" +" is_system: false\n" +" status: open\n" +" vclock: &1 {1: 49}\n" +" name: read_view2\n" +" id: 2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema.pot b/locale/en/reference/reference_lua/box_schema.pot new file mode 100644 index 0000000000..86e3be0afd --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema.pot @@ -0,0 +1,221 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema.rst:5 +msgid "Submodule box.schema" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:9 +msgid "The ``box.schema`` submodule has data-definition functions for spaces, users, roles, function tuples, and sequences." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:12 +msgid "Below is a list of all ``box.schema`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:23 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:24 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:26 +msgid ":doc:`./box_schema/space_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:27 +msgid "Create a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:29 +msgid ":doc:`./box_schema/upgrade`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:30 +msgid "Upgrade a database" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:32 +msgid ":doc:`./box_schema/downgrade`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:33 +msgid "Downgrade a database" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:35 +msgid ":doc:`./box_schema/downgrade_issues`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:36 +msgid "List downgrade issues for the specified Tarantool version" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:38 +msgid ":doc:`./box_schema/downgrade_versions`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:39 +msgid "List Tarantool versions available for downgrade" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:41 +msgid ":doc:`./box_schema/user_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:42 +msgid "Create a user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:44 +msgid ":doc:`./box_schema/user_drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:45 +msgid "Drop a user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:47 +msgid ":doc:`./box_schema/user_exists`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:48 +msgid "Check if a user exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:50 +msgid ":doc:`./box_schema/user_grant`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:51 +msgid "Grant privileges to a user or a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:53 +msgid ":doc:`./box_schema/user_revoke`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:54 +msgid "Revoke privileges from a user or a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:56 +msgid ":doc:`./box_schema/user_password`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:57 +msgid "Get a hash of a user's password" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:59 +msgid ":doc:`./box_schema/user_passwd`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:60 +msgid "Associate a password with a user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:62 +msgid ":doc:`./box_schema/user_info`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:63 +msgid "Get a description of a user's privileges" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:65 +msgid ":doc:`./box_schema/role_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:66 +msgid "Create a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:68 +msgid ":doc:`./box_schema/role_drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:69 +msgid "Drop a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:71 +msgid ":doc:`./box_schema/role_exists`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:72 +msgid "Check if a role exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:74 +msgid ":doc:`./box_schema/role_grant`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:75 +msgid "Grant privileges to a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:77 +msgid ":doc:`./box_schema/role_revoke`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:78 +msgid "Revoke privileges from a role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:80 +msgid ":doc:`./box_schema/role_info`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:81 +msgid "Get a description of a role's privileges" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:83 +msgid ":doc:`./box_schema/func_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:84 +msgid "Create a function tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:86 +msgid ":doc:`./box_schema/func_drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:87 +msgid "Drop a function tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:89 +msgid ":doc:`./box_schema/func_exists`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:90 +msgid "Check if a function tuple exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:92 +msgid ":doc:`./box_schema/func_reload`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema.rst:93 +msgid "Reload a C module with all its functions, no restart" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/downgrade.pot b/locale/en/reference/reference_lua/box_schema/downgrade.pot new file mode 100644 index 0000000000..cef7a98b2f --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/downgrade.pot @@ -0,0 +1,59 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:4 +msgid "box.schema.downgrade()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:10 +msgid "Allows you to downgrade a database to the specified Tarantool version. This might be useful if you need to run a database on older Tarantool versions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:13 +msgid "To prepare a database for using it on an older Tarantool instance, call ``box.schema.downgrade`` and pass the desired Tarantool version:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:16 +msgid "tarantool> box.schema.downgrade('2.8.4')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:22 +msgid "The Tarantool's downgrade procedure is similar to the upgrade process that is described in the :ref:`Upgrades ` topic. You need to run ``box.schema.downgrade()`` only on master and execute `box.shapshot()` on every instance in a replica set before restart to an older version." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:25 +msgid "To see Tarantool versions available for downgrade, call :ref:`box.schema.downgrade_versions() `. The oldest release available for downgrade is ``2.8.2``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:27 +msgid "Note that the downgrade process might fail if the database enables specific features not supported in the target Tarantool version. You can see all such issues using the :ref:`box.schema.downgrade_issues() ` method, which accepts the target version. For example, ``downgrade`` to the ``2.8.4`` version fails if you use :ref:`tuple compression ` or field :ref:`constraints ` in your database:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:33 +msgid "tarantool> box.schema.downgrade_issues('2.8.4')\n" +"---\n" +"- - Tuple compression is found in space 'bands', field 'band_name'. It is supported\n" +" starting from version 2.10.0.\n" +" - Field constraint is found in space 'bands', field 'year'. It is supported starting\n" +" from version 2.10.0.\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade.rst:43 +msgid "See also: :ref:`box.schema.upgrade() `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/downgrade_issues.pot b/locale/en/reference/reference_lua/box_schema/downgrade_issues.pot new file mode 100644 index 0000000000..fdc30fcf48 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/downgrade_issues.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:4 +msgid "box.schema.downgrade_issues()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:10 +msgid "Return a list of downgrade issues for the specified Tarantool version. To learn how to downgrade a database to the specified Tarantool version, see :ref:`box.schema.downgrade() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:13 +msgid "a list of downgrade issues" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_issues.rst:14 +msgid "table" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/downgrade_versions.pot b/locale/en/reference/reference_lua/box_schema/downgrade_versions.pot new file mode 100644 index 0000000000..9fbbcb8c3a --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/downgrade_versions.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:4 +msgid "box.schema.downgrade_versions()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:10 +msgid "Return a list of Tarantool versions available for downgrade. To learn how to downgrade a database to the specified Tarantool version, see :ref:`box.schema.downgrade() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:13 +msgid "a list of Tarantool versions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/downgrade_versions.rst:14 +msgid "table" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/func_create.pot b/locale/en/reference/reference_lua/box_schema/func_create.pot new file mode 100644 index 0000000000..149800540a --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/func_create.pot @@ -0,0 +1,317 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-26 14:24+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:5 +msgid "box.schema.func.create()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:13 +msgid "Create a function. The created function can be used in different usage scenarios, for example, in :ref:`field or tuple constraints ` or :ref:`functional indexes `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:18 +msgid "Using the :ref:`body ` option, you can make a function *persistent*. In this case, the function is \"persistent\" because its definition is stored in a snapshot (the :ref:`box.space._func ` system space) and can be recovered if the server restarts." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:21 +msgid "a name of the function, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:23 +msgid "see :ref:`function_options `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:25 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:29 +msgid ":ref:`box.schema.user.grant() ` can be used to allow the specified user or role to execute the created function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:32 +msgid "**Example 1: a non-persistent Lua function**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:34 +msgid "The example below shows how to create a non-persistent Lua function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:36 +msgid "box.schema.func.create('calculate')\n" +"box.schema.func.create('calculate', {if_not_exists = false})\n" +"box.schema.func.create('calculate', {setuid = false})\n" +"box.schema.func.create('calculate', {language = 'LUA'})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:44 +msgid "**Example 2: a persistent Lua function**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:46 +msgid "The example below shows how to create a persistent Lua function, show its definition using ``box.func.{func-name}``, and call this function using ``box.func.{func-name}:call([parameters])``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:50 +msgid "tarantool> lua_code = [[function(a, b) return a + b end]]\n" +"tarantool> box.schema.func.create('sum', {body = lua_code})\n" +"\n" +"tarantool> box.func.sum\n" +"---\n" +"- is_sandboxed: false\n" +" is_deterministic: false\n" +" id: 2\n" +" setuid: false\n" +" body: function(a, b) return a + b end\n" +" name: sum\n" +" language: LUA\n" +"...\n" +"\n" +"tarantool> box.func.sum:call({1, 2})\n" +"---\n" +"- 3\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:71 +msgid "To call functions using ``net.box``, use :ref:`net_box:call() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:75 +msgid "**Example 3: a persistent SQL expression used in a tuple constraint**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:77 +msgid "The code snippet below defines a function that checks a tuple's data using the SQL expression:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:79 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:220 +msgid "box.schema.func.create('check_person', {\n" +" language = 'SQL_EXPR',\n" +" is_deterministic = true,\n" +" body = [[\"age\" > 21 AND \"name\" != 'Admin']]\n" +"})\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:85 +msgid "Then, this function is used to create a tuple :ref:`constraint `:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:87 +msgid "local customers = box.schema.space.create('customers', { constraint = 'check_person' })\n" +"customers:format({\n" +" { name = 'id', type = 'number' },\n" +" { name = 'name', type = 'string' },\n" +" { name = 'age', type = 'number' },\n" +"})\n" +"customers:create_index('primary', { parts = { 1 } })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:93 +msgid "On an attempt to insert a tuple that doesn't meet the required criteria, an error is raised:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:95 +msgid "customers:insert { 2, \"Bob\", 18 }\n" +"-- error: Check constraint 'check_person' failed for a tuple\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:104 +msgid "function_options" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:108 +msgid "A table containing options passed to the :ref:`box.schema.func.create(func-name [, function_options]) ` function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:114 +msgid "Specify whether there should be no error if the function already exists." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:116 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:128 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:182 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:191 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:201 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:252 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:117 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:129 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:183 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:192 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:202 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:253 +msgid "Default: ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:123 +msgid "Make Tarantool treat the function's caller as the function's creator, with full privileges. Note that ``setuid`` works only over :ref:`binary ports `. ``setuid`` doesn't work if you invoke a function using the :ref:`admin console ` or inside a Lua script." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:135 +msgid "Specify the function language. The possible values are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:138 +msgid "``LUA``: define a Lua function in the :ref:`body ` attribute." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:139 +msgid "``SQL_EXPR``: define an :ref:`SQL expression ` in the :ref:`body ` attribute. An SQL expression can only be used as a field or tuple :ref:`constraint `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:140 +msgid "``C``: import a C function using its name from a ``.so`` file. Learn how to call C code from Lua in the :ref:`C tutorial `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:144 +msgid "To reload a C module with all its functions without restarting the server, call :ref:`box.schema.func.reload() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:146 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:228 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:291 +msgid "Type: string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:147 +msgid "Default: ``LUA``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:153 +msgid "Whether the function should be executed in an isolated environment. This means that any operation that accesses the world outside the sandbox is forbidden or has no effect. Therefore, a sandboxed function can only use modules and functions that cannot affect isolation:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:158 +msgid "`assert `_, `assert `_, `error `_, `ipairs `_, `math.* `_, `next `_, `pairs `_, `pcall `_, `print `_, `select `_, `string.* `_, `table.* `_, `tonumber `_, `tostring `_, `type `_, `unpack `_, `xpcall `_, :ref:`utf8.* `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:177 +msgid "Also, a sandboxed function cannot refer to global variables -- they are treated as local variables because the sandbox is established with `setfenv `_. So, a sandboxed function is stateless and deterministic." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:189 +msgid "Specify whether a function should be deterministic." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:198 +msgid "If ``true`` is set in the function definition for a functional index, the function returns multiple keys. For details, see the :ref:`example `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:208 +msgid "Specify a function body. You can set a function's language using the :ref:`language ` attribute." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:211 +msgid "The code snippet below defines a :ref:`constraint ` function that checks a tuple's data using a Lua function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:213 +msgid "box.schema.func.create('check_person', {\n" +" language = 'LUA',\n" +" is_deterministic = true,\n" +" body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'\n" +"})\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:218 +msgid "In the following example, an SQL expression is used to check a tuple's data:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:226 +msgid "Example: :ref:`A persistent SQL expression used in a tuple constraint `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:229 +msgid "Default: ``nil``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:235 +msgid "**Since:** :doc:`2.10.0 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:237 +msgid "If set to ``true`` for a Lua function and the function is called via ``net.box`` (:ref:`conn:call() `) or by ``box.func.:call()``, the function arguments are passed being wrapped in a :ref:`MsgPack object `:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:240 +msgid "local msgpack = require('msgpack')\n" +"box.schema.func.create('my_func', {takes_raw_args = true})\n" +"local my_func = function(mp)\n" +" assert(msgpack.is_object(mp))\n" +" local args = mp:decode() -- array of arguments\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:249 +msgid "If a function forwards most of its arguments to another Tarantool instance or writes them to a database, the usage of this option can improve performance because it skips the MsgPack data decoding in Lua." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:260 +msgid "Specify the languages that can call the function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:262 +msgid "Example: ``exports = {'LUA', 'SQL'}``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:264 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:277 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:289 +msgid "See also: :ref:`Calling Lua routines from SQL `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:266 +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:279 +msgid "Type: table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:267 +msgid "Default: ``{'LUA'}``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:273 +msgid "Specify the Lua type names for each parameter of the function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:275 +msgid "Example: ``param_list = {'number', 'number'}``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:285 +msgid "Specify the Lua type name for a function's return value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_create.rst:287 +msgid "Example: ``returns = 'number'``" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/func_drop.pot b/locale/en/reference/reference_lua/box_schema/func_drop.pot new file mode 100644 index 0000000000..50eb31131c --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/func_drop.pot @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:5 +msgid "box.schema.func.drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:11 +msgid "Drop a function tuple. For explanation of how Tarantool maintains function data, see reference on :ref:`_func space `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:15 +msgid "the name of the function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:16 +msgid "``if_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the _func tuple does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_drop.rst:21 +msgid "box.schema.func.drop('calculate')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/func_exists.pot b/locale/en/reference/reference_lua/box_schema/func_exists.pot new file mode 100644 index 0000000000..425f57a2ea --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/func_exists.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:5 +msgid "box.schema.func.exists()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:11 +msgid "Return true if a function tuple exists; return false if a function tuple does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:14 +msgid "the name of the function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:15 +msgid "bool" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:17 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_exists.rst:19 +msgid "box.schema.func.exists('calculate')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/func_reload.pot b/locale/en/reference/reference_lua/box_schema/func_reload.pot new file mode 100644 index 0000000000..7f9e3ad34d --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/func_reload.pot @@ -0,0 +1,50 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:5 +msgid "box.schema.func.reload()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:11 +msgid "Reload a C module with all its functions without restarting the server." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:13 +msgid "Under the hood, Tarantool loads a new copy of the module (``*.so`` shared library) and starts routing all new request to the new version. The previous version remains active until all started calls are finished. All shared libraries are loaded with ``RTLD_LOCAL`` (see \"man 3 dlopen\"), therefore multiple copies can co-exist without any problems." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:21 +msgid "Reload will fail if a module was loaded from Lua script with `ffi.load() `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:24 +msgid "the name of the module to reload" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/func_reload.rst:28 +msgid "-- reload the entire module contents\n" +"box.schema.func.reload('module')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_create.pot b/locale/en/reference/reference_lua/box_schema/role_create.pot new file mode 100644 index 0000000000..5803ed201e --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_create.pot @@ -0,0 +1,54 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:5 +msgid "box.schema.role.create()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:11 +msgid "Create a role. For explanation of how Tarantool maintains role data, see section :ref:`Roles `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:15 +msgid "name of role, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:17 +msgid "``if_not_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the role already exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:21 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:23 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_create.rst:25 +msgid "box.schema.role.create('Accountant')\n" +"box.schema.role.create('Accountant', {if_not_exists = false})" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_drop.pot b/locale/en/reference/reference_lua/box_schema/role_drop.pot new file mode 100644 index 0000000000..bcdfb18e16 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_drop.pot @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:5 +msgid "box.schema.role.drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:11 +msgid "Drop a role. For explanation of how Tarantool maintains role data, see section :ref:`Roles `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:15 +msgid "the name of the role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:16 +msgid "``if_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the role does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_drop.rst:21 +msgid "box.schema.role.drop('Accountant')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_exists.pot b/locale/en/reference/reference_lua/box_schema/role_exists.pot new file mode 100644 index 0000000000..2487284588 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_exists.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:5 +msgid "box.schema.role.exists()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:11 +msgid "Return ``true`` if a role exists; return ``false`` if a role does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:13 +msgid "the name of the role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:14 +msgid "bool" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:16 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_exists.rst:18 +msgid "box.schema.role.exists('Accountant')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_grant.pot b/locale/en/reference/reference_lua/box_schema/role_grant.pot new file mode 100644 index 0000000000..be3b302f72 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_grant.pot @@ -0,0 +1,73 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:5 +msgid "box.schema.role.grant()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:13 +msgid "Grant :ref:`privileges ` to a role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:15 +msgid "the name of the role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:16 +msgid "'read' or 'write' or 'execute' or 'create' or 'alter' or 'drop' or a combination." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:18 +msgid "'space' or 'function' or 'sequence' or 'role'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:19 +msgid "the name of a function or space or sequence or role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:20 +msgid "``if_not_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the role already has the privilege." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:24 +msgid "The role must exist, and the object must exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:26 +msgid "**Variation:** instead of ``object-type, object-name`` say 'universe' which means 'all object-types and all objects'. In this case, object name is omitted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:29 +msgid "**Variation:** instead of ``privilege, object-type, object-name`` say ``role-name`` -- to grant a role to a role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:32 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_grant.rst:34 +msgid "box.schema.role.grant('Accountant', 'read', 'space', 'tester')\n" +"box.schema.role.grant('Accountant', 'execute', 'function', 'f')\n" +"box.schema.role.grant('Accountant', 'read,write', 'universe')\n" +"box.schema.role.grant('public', 'Accountant')\n" +"box.schema.role.grant('role1', 'role2', nil, nil, {if_not_exists=false})" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_info.pot b/locale/en/reference/reference_lua/box_schema/role_info.pot new file mode 100644 index 0000000000..68fef738a3 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_info.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:5 +msgid "box.schema.role.info()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:11 +msgid "Return a description of a role's privileges." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:13 +msgid "the name of the role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:15 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_info.rst:17 +msgid "box.schema.role.info('Accountant')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/role_revoke.pot b/locale/en/reference/reference_lua/box_schema/role_revoke.pot new file mode 100644 index 0000000000..b7acd9686d --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/role_revoke.pot @@ -0,0 +1,68 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:5 +msgid "box.schema.role.revoke()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:11 +msgid "Revoke :ref:`privileges ` from a role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:13 +msgid "the name of the role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:14 +msgid "'read' or 'write' or 'execute' or 'create' or 'alter' or 'drop' or a combination." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:16 +msgid "'space' or 'function' or 'sequence' or 'role'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:17 +msgid "the name of a function or space or sequence or role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:19 +msgid "The role must exist, and the object must exist, but it is not an error if the role does not have the privilege." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:22 +msgid "**Variation:** instead of ``object-type, object-name`` say 'universe' which means 'all object-types and all objects'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:25 +msgid "**Variation:** instead of ``privilege, object-type, object-name`` say ``role-name``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:28 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/role_revoke.rst:30 +msgid "box.schema.role.revoke('Accountant', 'read', 'space', 'tester')\n" +"box.schema.role.revoke('Accountant', 'execute', 'function', 'f')\n" +"box.schema.role.revoke('Accountant', 'read,write', 'universe')\n" +"box.schema.role.revoke('public', 'Accountant')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/space_create.pot b/locale/en/reference/reference_lua/box_schema/space_create.pot new file mode 100644 index 0000000000..00e4084f5a --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/space_create.pot @@ -0,0 +1,287 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-21 13:25+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:5 +msgid "box.schema.space.create()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:12 +msgid "Create a :ref:`space `. You can use either syntax. For example, ``s = box.schema.space.create('tester')`` has the same effect as ``s = box.schema.create_space('tester')``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:17 +msgid "There are :ref:`three syntax variations ` for object references targeting space objects, for example :samp:`box.schema.space.drop({space-id})` drops a space. However, the common approach is to use functions attached to the space objects, for example :ref:`space_object:drop() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:24 +msgid "After a space is created, usually the next step is to :ref:`create an index ` for it, and then it is available for insert, select, and all the other :ref:`box.space ` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:29 +msgid "name of space, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:31 +msgid "space options (see :ref:`space_opts `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:33 +msgid "space object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:34 +msgid "userdata" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:39 +msgid "space_opts" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:43 +msgid "Space options that include the space id, format, field count, constraints and foreign keys, and so on. These options are passed to the :ref:`box.schema.space.create() ` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:49 +msgid "These options are also passed to :doc:`/reference/reference_lua/box_space/alter`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:55 +msgid "Create a space only if a space with the same name does not exist already. Otherwise, do nothing but do not cause an error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:58 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:121 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:135 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:153 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:59 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:122 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:136 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:154 +msgid "Default: ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:65 +msgid "A :ref:`storage engine `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:67 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:98 +msgid "Type: string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:68 +msgid "Default: `memtx`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:69 +msgid "Possible values: ``memtx``, ``vinyl``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:75 +msgid "A unique numeric identifier of the space: users can refer to spaces with this id instead of the name." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:78 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:88 +msgid "Type: number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:79 +msgid "Default: last space's ID + 1" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:85 +msgid "A fixed count of :ref:`fields `. For example, if ``field_count=5``, it is illegal to insert a tuple with fewer than or more than 5 fields." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:89 +msgid "Default: ``0`` (not fixed)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:95 +msgid "The name of the user who is considered to be the space's :ref:`owner ` for authorization purposes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:99 +msgid "Default: current user's name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:105 +msgid "Field names and types. See the illustrations of format clauses in the :ref:`space_object:format() ` description and in the :ref:`box.space._space ` example. Optional and usually not specified." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:110 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:162 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:178 +msgid "Type: table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:111 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:163 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:179 +msgid "Default: blank" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:117 +msgid "Space contents are :ref:`replication-local `: changes are stored in the :ref:`write-ahead log ` of the local node but there is no :ref:`replication `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:128 +msgid "Space contents are temporary: changes are not stored in the :ref:`write-ahead log ` and there is no :ref:`replication `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:133 +msgid "Vinyl does not support temporary spaces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:143 +msgid "Any transaction doing a DML request on this space becomes :ref:`synchronous `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:145 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:165 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:181 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:205 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:160 +msgid "The :ref:`constraints ` that space tuples must satisfy." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:167 +msgid "-- Define a tuple constraint function --\n" +"box.schema.func.create('check_person', {\n" +" language = 'LUA',\n" +" is_deterministic = true,\n" +" body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'\n" +"})\n" +"\n" +"-- Create a space with a tuple constraint --\n" +"customers = box.schema.space.create('customers', {constraint = 'check_person'})\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:176 +msgid "The :ref:`foreign keys ` for space fields." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:183 +msgid "-- Create a space with a tuple foreign key --\n" +"box.schema.space.create(\"orders\", {\n" +" foreign_key = {\n" +" space = 'customers',\n" +" field = {customer_id = 'id', customer_name = 'name'}\n" +" }\n" +"})\n" +"\n" +"box.space.orders:format({\n" +" {name = \"id\", type = \"number\"},\n" +" {name = \"customer_id\" },\n" +" {name = \"customer_name\"},\n" +" {name = \"price_total\", type = \"number\"},\n" +"})\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:188 +msgid "Saying ``box.cfg{read_only=true...}`` during :ref:`configuration ` affects spaces differently depending on the options that were used during ``box.schema.space.create``, as summarized by this chart:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:195 +msgid "Option" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:195 +msgid "Can be created?" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:195 +msgid "Can be written to?" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:195 +msgid "Is replicated?" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:195 +msgid "Is persistent?" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:197 +msgid "(default)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:197 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:197 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:199 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:199 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:199 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:201 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:201 +msgid "no" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:197 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:197 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:199 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:201 +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:201 +msgid "yes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:199 +msgid "temporary" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:201 +msgid "is_local" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/space_create.rst:207 +msgid "tarantool> s = box.schema.space.create('space55')\n" +"---\n" +"...\n" +"tarantool> s = box.schema.space.create('space55', {\n" +" > id = 555,\n" +" > temporary = false\n" +" > })\n" +"---\n" +"- error: Space 'space55' already exists\n" +"...\n" +"tarantool> s = box.schema.space.create('space55', {\n" +" > if_not_exists = true\n" +" > })\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/upgrade.pot b/locale/en/reference/reference_lua/box_schema/upgrade.pot new file mode 100644 index 0000000000..92bea3b417 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/upgrade.pot @@ -0,0 +1,48 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:4 +msgid "box.schema.upgrade()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:10 +msgid "If you created a database with an older Tarantool version and have now installed a newer version, make the request ``box.schema.upgrade()``. This updates Tarantool system spaces to match the currently installed version of Tarantool. You can learn about the general upgrade process from the :ref:`Upgrades ` topic." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:15 +msgid "For example, here is what happens when you run ``box.schema.upgrade()`` with a database created with Tarantool version 1.6.4 to version 1.7.2 (only a small part of the output is shown):" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:19 +msgid "tarantool> box.schema.upgrade()\n" +"alter index primary on _space set options to {\"unique\":true}, parts to [[0,\"unsigned\"]]\n" +"alter space _schema set options to {}\n" +"create view _vindex...\n" +"grant read access to 'public' role for _vindex view\n" +"set schema version to 1.7.0\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:30 +msgid "You can also put the request ``box.schema.upgrade()`` inside a :doc:`box.once() ` function in your Tarantool :ref:`initialization file `. On startup, this will create new system spaces, update data type names (for example, ``num`` -> ``unsigned``, ``str`` -> ``string``) and options in Tarantool system spaces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/upgrade.rst:36 +msgid "See also: :ref:`box.schema.downgrade() `" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_create.pot b/locale/en/reference/reference_lua/box_schema/user_create.pot new file mode 100644 index 0000000000..24a0517348 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_create.pot @@ -0,0 +1,71 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:5 +msgid "box.schema.user.create()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:11 +msgid "Create a user. For explanation of how Tarantool maintains user data, see section :ref:`Users` and reference on :ref:`_user ` space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:16 +msgid "The possible options are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:18 +msgid "``if_not_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the user already exists," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:21 +msgid "``password`` (default = '') - string; the ``password`` = *password* specification is good because in a :ref:`URI ` (Uniform Resource Identifier) it is usually illegal to include a user-name without a password." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:28 +msgid "The maximum number of users is 32." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:30 +msgid "a user name, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:31 +msgid "``if_not_exists``, ``password``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:33 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:35 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_create.rst:37 +msgid "box.schema.user.create('testuser')\n" +"box.schema.user.create('testuser', {password = 'foobar'})\n" +"box.schema.user.create('testuser', {if_not_exists = false})" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_drop.pot b/locale/en/reference/reference_lua/box_schema/user_drop.pot new file mode 100644 index 0000000000..6f7f811166 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_drop.pot @@ -0,0 +1,46 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:5 +msgid "box.schema.user.drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:11 +msgid "Drop a user. For explanation of how Tarantool maintains user data, see section :ref:`Users ` and reference on :ref:`_user ` space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:16 +msgid "the name of the user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:17 +msgid "``if_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the user does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:20 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_drop.rst:22 +msgid "box.schema.user.drop('Lena')\n" +"box.schema.user.drop('Lena',{if_exists=false})" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_exists.pot b/locale/en/reference/reference_lua/box_schema/user_exists.pot new file mode 100644 index 0000000000..538ee057c1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_exists.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:5 +msgid "box.schema.user.exists()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:11 +msgid "Return ``true`` if a user exists; return ``false`` if a user does not exist. For explanation of how Tarantool maintains user data, see section :ref:`Users ` and reference on :ref:`_user ` space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:16 +msgid "the name of the user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:17 +msgid "bool" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_exists.rst:21 +msgid "box.schema.user.exists('Lena')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_grant.pot b/locale/en/reference/reference_lua/box_schema/user_grant.pot new file mode 100644 index 0000000000..ce9d439b86 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_grant.pot @@ -0,0 +1,94 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:5 +msgid "box.schema.user.grant()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:13 +msgid "Grant :ref:`privileges ` to a user or to another role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:16 +msgid "the name of a user to grant privileges to" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:17 +msgid "one or more privileges to grant to the user (for example, `read` or `read,write`)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:18 +msgid "a database object type to grant privileges to (for example, `space`, `role`, or `function`)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:19 +msgid "the name of a database object to grant privileges to" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:20 +msgid "the name of a role to grant to the user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:21 +msgid "``grantor``, ``if_not_exists``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:23 +msgid "If :samp:`'function','{object-name}'` is specified, then a _func tuple with that object-name must exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:26 +msgid "**Variation:** instead of ``object-type, object-name`` say 'universe' which means 'all object-types and all objects'. In this case, object name is omitted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:29 +msgid "**Variation:** instead of ``privilege, object-type, object-name`` say ``role-name`` (see section :ref:`Roles `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:32 +msgid "**Variation:** instead of :samp:`box.schema.user.grant('{user-name}','usage,session','universe',nil,` :code:`{if_not_exists=true})` say :samp:`box.schema.user.enable('{user-name}')`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:36 +msgid "The possible options are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:38 +msgid "``grantor`` = *grantor_name_or_id* -- string or number, for custom grantor," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:39 +msgid "``if_not_exists`` = ``true|false`` (default = ``false``) - boolean; ``true`` means there should be no error if the user already has the privilege." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:42 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_grant.rst:44 +msgid "box.schema.user.grant('Lena', 'read', 'space', 'tester')\n" +"box.schema.user.grant('Lena', 'execute', 'function', 'f')\n" +"box.schema.user.grant('Lena', 'read,write', 'universe')\n" +"box.schema.user.grant('Lena', 'Accountant')\n" +"box.schema.user.grant('Lena', 'read,write,execute', 'universe')\n" +"box.schema.user.grant('X', 'read', 'universe', nil, {if_not_exists=true})" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_info.pot b/locale/en/reference/reference_lua/box_schema/user_info.pot new file mode 100644 index 0000000000..12c97fac82 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_info.pot @@ -0,0 +1,46 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:5 +msgid "box.schema.user.info()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:11 +msgid "Return a description of a user's :ref:`privileges `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:13 +msgid "the name of the user. This is optional; if it is not supplied, then the information will be for the user who is currently logged in." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_info.rst:21 +msgid "tarantool> box.schema.user.info('admin')\n" +"---\n" +"- - - read,write,execute,session,usage,create,drop,alter,reference,trigger,insert,update,delete\n" +" - universe\n" +" -\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_passwd.pot b/locale/en/reference/reference_lua/box_schema/user_passwd.pot new file mode 100644 index 0000000000..e8259cada1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_passwd.pot @@ -0,0 +1,54 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:5 +msgid "box.schema.user.passwd()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:11 +msgid "Sets a password for a currently logged in or a specified user:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:13 +msgid "A currently logged in user can change their password using ``box.schema.user.passwd(new_password)``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:16 +msgid "An administrator can change the password of another user with ``box.schema.user.passwd(name, new_password)``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:19 +msgid "name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:20 +msgid "new_password" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:22 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_passwd.rst:24 +msgid "box.schema.user.passwd('foobar')\n" +"box.schema.user.passwd('testuser', 'foobar')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_password.pot b/locale/en/reference/reference_lua/box_schema/user_password.pot new file mode 100644 index 0000000000..6660166f16 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_password.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:5 +msgid "box.schema.user.password()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:11 +msgid "Return a hash of a user's password. For explanation of how Tarantool maintains passwords, see section :ref:`Passwords ` and reference on :ref:`_user ` space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:17 +msgid "If a non-'guest' user has no password, it’s **impossible** to connect to Tarantool using this user. The user is regarded as “internal” only, not usable from a remote connection. Such users can be useful if they have defined some procedures with the :doc:`SETUID ` option, on which privileges are granted to externally-connectable users. This way, external users cannot create/drop objects, they can only invoke procedures." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:26 +msgid "For the 'guest' user, it’s impossible to set a password: that would be misleading, since 'guest' is the default user on a newly-established connection over a :ref:`binary port `, and Tarantool does not require a password to establish a :ref:`binary connection `. It is, however, possible to change the current user to ‘guest’ by providing the :ref:`AUTH packet ` with no password at all or an empty password. This feature is useful for connection pools, which want to reuse a connection for a different user without re-establishing it." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:36 +msgid "password to be hashed" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:37 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:39 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_password.rst:41 +msgid "box.schema.user.password('foobar')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema/user_revoke.pot b/locale/en/reference/reference_lua/box_schema/user_revoke.pot new file mode 100644 index 0000000000..a8e78c4d47 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema/user_revoke.pot @@ -0,0 +1,76 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:5 +msgid "box.schema.user.revoke()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:13 +msgid "Revoke :ref:`privileges ` from a user or from another role." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:16 +msgid "the name of the user." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:17 +msgid "'read' or 'write' or 'execute' or 'create' or 'alter' or 'drop' or a combination." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:19 +msgid "'space' or 'function' or 'sequence'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:20 +msgid "the name of a function or space or sequence." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:21 +msgid "``if_exists``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:23 +msgid "The user must exist, and the object must exist, but if the option setting is ``{if_exists=true}`` then it is not an error if the user does not have the privilege." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:27 +msgid "**Variation:** instead of ``object-type, object-name`` say 'universe' which means 'all object-types and all objects'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:30 +msgid "**Variation:** instead of ``privilege, object-type, object-name`` say ``role-name`` (see section :ref:`Roles `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:33 +msgid "**Variation:** instead of :samp:`box.schema.user.revoke('{user-name}','usage,session','universe',nil,` :code:`{if_exists=true})` say :samp:`box.schema.user.disable('{user-name}')`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:37 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema/user_revoke.rst:39 +msgid "box.schema.user.revoke('Lena', 'read', 'space', 'tester')\n" +"box.schema.user.revoke('Lena', 'execute', 'function', 'f')\n" +"box.schema.user.revoke('Lena', 'read,write', 'universe')\n" +"box.schema.user.revoke('Lena', 'Accountant')" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence.pot b/locale/en/reference/reference_lua/box_schema_sequence.pot new file mode 100644 index 0000000000..bdabdb2a35 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence.pot @@ -0,0 +1,130 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:5 +msgid "Sequences" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:7 +msgid "An introduction to sequences is in the :ref:`Sequences ` section of the \"Data model\" chapter. Here are the details for each function and option." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:11 +msgid "All functions related to sequences require appropriate :ref:`privileges `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:14 +msgid "Below is a list of all ``box.schema.sequence`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:25 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:26 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:28 +msgid ":doc:`./box_schema_sequence/create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:29 +msgid "Create a new sequence generator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:31 +msgid ":doc:`./box_schema_sequence/next`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:32 +msgid "Generate and return the next value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:34 +msgid ":doc:`./box_schema_sequence/alter`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:35 +msgid "Change sequence options" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:37 +msgid ":doc:`./box_schema_sequence/reset`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:38 +msgid "Reset sequence state" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:40 +msgid ":doc:`./box_schema_sequence/set`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:41 +msgid "Set the new value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:43 +msgid ":doc:`./box_schema_sequence/current`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:44 +msgid "Return the last retrieved value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:46 +msgid ":doc:`./box_schema_sequence/drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:47 +msgid "Drop the sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:49 +msgid ":doc:`./box_schema_sequence/create_index`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:50 +msgid "Create an index with a sequence option" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:64 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:66 +msgid "Here is an example showing all sequence options and operations:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence.rst:68 +msgid "s = box.schema.sequence.create(\n" +" 'S2',\n" +" {start=100,\n" +" min=100,\n" +" max=200,\n" +" cache=100000,\n" +" cycle=false,\n" +" step=100\n" +" })\n" +"s:alter({step=6})\n" +"s:next()\n" +"s:reset()\n" +"s:set(150)\n" +"s:drop()" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/alter.pot b/locale/en/reference/reference_lua/box_schema_sequence/alter.pot new file mode 100644 index 0000000000..061a317c1f --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/alter.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:5 +msgid "sequence_object:alter()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:11 +msgid "The ``alter()`` function can be used to change any of the sequence's options. Requirements and restrictions are the same as for :doc:`/reference/reference_lua/box_schema_sequence/create`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:15 +msgid "Options:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:17 +msgid "``start`` -- the STARTS WITH value. Type = integer, Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:19 +msgid "``min`` -- the MINIMUM value. Type = integer, Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:21 +msgid "``max`` - the MAXIMUM value. Type = integer, Default = 9223372036854775807." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:23 +msgid "There is a rule: ``min`` <= ``start`` <= ``max``. For example it is illegal to say ``{start=0}`` because then the specified start value (0) would be less than the default min value (1)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:27 +msgid "There is a rule: ``min`` <= next-value <= ``max``. For example, if the next generated value would be 1000, but the maximum value is 999, then that would be considered \"overflow\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:32 +msgid "``cycle`` -- the CYCLE value. Type = bool. Default = false." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:34 +msgid "If the sequence generator's next value is an overflow number, it causes an error return -- unless ``cycle == true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:37 +msgid "But if ``cycle == true``, the count is started again, at the MINIMUM value or at the MAXIMUM value (not the STARTS WITH value)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:40 +msgid "``cache`` -- the CACHE value. Type = unsigned integer. Default = 0." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:42 +msgid "Currently Tarantool ignores this value, it is reserved for future use." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:44 +msgid "``step`` -- the INCREMENT BY value. Type = integer. Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/alter.rst:46 +msgid "Ordinarily this is what is added to the previous value." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/create.pot b/locale/en/reference/reference_lua/box_schema_sequence/create.pot new file mode 100644 index 0000000000..d52e71b3bf --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/create.pot @@ -0,0 +1,101 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:5 +msgid "box.schema.sequence.create()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:11 +msgid "Create a new sequence generator." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:13 +msgid "the name of the sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:15 +msgid "see a quick overview in the \"Options for ``box.schema.sequence.create()``\" :ref:`chart ` (in the :ref:`Sequences ` section of the \"Data model\" chapter), and see more details below." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:22 +msgid "a reference to a new sequence object." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:24 +msgid "Options:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:26 +msgid "``start`` -- the STARTS WITH value. Type = integer, Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:28 +msgid "``min`` -- the MINIMUM value. Type = integer, Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:30 +msgid "``max`` - the MAXIMUM value. Type = integer, Default = 9223372036854775807." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:32 +msgid "There is a rule: ``min`` <= ``start`` <= ``max``. For example it is illegal to say ``{start=0}`` because then the specified start value (0) would be less than the default min value (1)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:36 +msgid "There is a rule: ``min`` <= next-value <= ``max``. For example, if the next generated value would be 1000, but the maximum value is 999, then that would be considered \"overflow\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:41 +msgid "There is a rule: ``start`` and ``min`` and ``max`` must all be <= 9223372036854775807 which is 2^63 - 1 (not 2^64)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:44 +msgid "``cycle`` -- the CYCLE value. Type = bool. Default = false." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:46 +msgid "If the sequence generator's next value is an overflow number, it causes an error return -- unless ``cycle == true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:49 +msgid "But if ``cycle == true``, the count is started again, at the MINIMUM value or at the MAXIMUM value (not the STARTS WITH value)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:52 +msgid "``cache`` -- the CACHE value. Type = unsigned integer. Default = 0." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:54 +msgid "Currently Tarantool ignores this value, it is reserved for future use." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:56 +msgid "``step`` -- the INCREMENT BY value. Type = integer. Default = 1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create.rst:58 +msgid "Ordinarily this is what is added to the previous value." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/create_index.pot b/locale/en/reference/reference_lua/box_schema_sequence/create_index.pot new file mode 100644 index 0000000000..35a178e042 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/create_index.pot @@ -0,0 +1,99 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:5 +msgid "specifying a sequence in create_index()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:11 +msgid "You can use the :samp:`sequence={sequence-name}` (or :samp:`sequence={sequence-id}` or :samp:`sequence=true`) option when :ref:`creating ` or :doc:`altering ` a primary-key index. The sequence becomes associated with the index, so that the next ``insert()`` will put the next generated number into the primary-key field, if the field would otherwise be nil." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:19 +msgid "The syntax may be any of: |br| :samp:`sequence = {sequence identifier}` |br| or :code:`sequence = {id =` :samp:`{sequence identifier}` :code:`}` |br| or :code:`sequence = {field =` :samp:`{field number}` :code:`}` |br| or :code:`sequence = {id =` :samp:`{sequence identifier}` :code:`, field =` :samp:`{field number}` :code:`}` |br| or :code:`sequence = true` |br| or :code:`sequence = {}`. |br| The sequence identifier may be either a number (the sequence id) or a string (the sequence name). The field number may be the ordinal number of any field in the index; default = 1. Examples of all possibilities: ``sequence = 1`` or ``sequence = 'sequence_name'`` or ``sequence = {id = 1}`` or ``sequence = {id = 'sequence_name'}`` or ``sequence = {id = 1, field = 1}`` or ``sequence = {id = 'sequence_name', field = 1}`` or ``sequence = {field = 1}`` or ``sequence = true`` or ``sequence = {}``. Notice that the sequence identifier can be omitted, if it is omitted then a new sequence is created automatically with default name = :samp:`{space-name}_seq`. Notice that the field number does not have to be 1, that is, the sequence can be associated with any field in the primary-key index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:53 +msgid "For example, if 'Q' is a sequence and 'T' is a new space, then this will work:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:56 +msgid "tarantool> box.space.T:create_index('Q',{sequence='Q'})\n" +"---\n" +"- unique: true\n" +" parts:\n" +" - type: unsigned\n" +" is_nullable: false\n" +" fieldno: 1\n" +" sequence_id: 8\n" +" id: 0\n" +" space_id: 514\n" +" name: Q\n" +" type: TREE\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:72 +msgid "(Notice that the index now has a ``sequence_id`` field.)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:74 +msgid "And this will work:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:76 +msgid "tarantool> box.space.T:insert{box.NULL,0}\n" +"---\n" +"- [1, 0]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:85 +msgid "The index key type may be either 'integer' or 'unsigned'. If any of the sequence options is a negative number, then the index key type should be 'integer'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:89 +msgid "Users should not insert a value greater than 9223372036854775807, which is 2^63 - 1, in the indexed field. The sequence generator will ignore it." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:93 +msgid "A sequence cannot be dropped if it is associated with an index. However, :ref:`index_object:alter() ` can be used to say that a sequence is not associated with an index, for example ``box.space.T.index.I:alter({sequence=false})``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:99 +msgid "If a sequence was created automatically because the sequence identifier was omitted, then it will be dropped automatically if the index is altered so that ``sequence=false``, or if the index is dropped." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:104 +msgid "``index_object:alter()`` can also be used to associate a sequence with an existing index, with the same syntax for options." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:107 +msgid "When a sequence is used with an index based on a JSON path, inserted tuples must have all components of the path preceding the autoincrement field, and the autoincrement field. To achieve that use ``box.NULL`` rather than ``nil``. Example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/create_index.rst:112 +msgid "s = box.schema.space.create('test')\n" +"s:create_index('pk', {parts = {{'[1].a.b[1]', 'unsigned'}}, sequence = true})\n" +"s:replace{} -- error\n" +"s:replace{{c = {}}} -- error\n" +"s:replace{{a = {c = {}}}} -- error\n" +"s:replace{{a = {b = {}}}} -- error\n" +"s:replace{{a = {b = {nil}}}} -- error\n" +"s:replace{{a = {b = {box.NULL}}}} -- ok" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/current.pot b/locale/en/reference/reference_lua/box_schema_sequence/current.pot new file mode 100644 index 0000000000..7e9af4b964 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/current.pot @@ -0,0 +1,61 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/current.rst:5 +msgid "sequence_object:current()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/current.rst:11 +msgid "Since version :doc:`2.4.1 `. Return the last retrieved value of the specified sequence or throw an error if no value has been generated yet (``next()`` has not been called yet, or ``current()`` is called right after ``reset()`` is called)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/current.rst:16 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/current.rst:18 +msgid "tarantool> sq = box.schema.sequence.create('test')\n" +"---\n" +"...\n" +"tarantool> sq:current()\n" +"---\n" +"- error: Sequence 'test' is not started\n" +"...\n" +"tarantool> sq:next()\n" +"---\n" +"- 1\n" +"...\n" +"tarantool> sq:current()\n" +"---\n" +"- 1\n" +"...\n" +"tarantool> sq:set(42)\n" +"---\n" +"...\n" +"tarantool> sq:current()\n" +"---\n" +"- 42\n" +"...\n" +"tarantool> sq:reset()\n" +"---\n" +"...\n" +"tarantool> sq:current() -- error\n" +"---\n" +"- error: Sequence 'test' is not started\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/drop.pot b/locale/en/reference/reference_lua/box_schema_sequence/drop.pot new file mode 100644 index 0000000000..d690d18205 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/drop.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/drop.rst:5 +msgid "sequence_object:drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/drop.rst:11 +msgid "Drop an existing sequence." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/next.pot b/locale/en/reference/reference_lua/box_schema_sequence/next.pot new file mode 100644 index 0000000000..3fa516c9a7 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/next.pot @@ -0,0 +1,89 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:5 +msgid "sequence_object:next()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:11 +msgid "Generate the next value and return it." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:13 +msgid "The generation algorithm is simple:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:15 +msgid "If this is the first time, then return the STARTS WITH value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:16 +msgid "If the previous value plus the INCREMENT value is less than the MINIMUM value or greater than the MAXIMUM value, that is \"overflow\", so either raise an error (if ``cycle`` = ``false``) or return the MAXIMUM value (if ``cycle`` = ``true`` and ``step`` < 0) or return the MINIMUM value (if ``cycle`` = ``true`` and ``step`` > 0)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:22 +msgid "If there was no error, then save the returned result, it is now the \"previous value\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:25 +msgid "For example, suppose sequence 'S' has:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:27 +msgid "``min`` == -6," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:28 +msgid "``max`` == -1," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:29 +msgid "``step`` == -3," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:30 +msgid "``start`` = -2," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:31 +msgid "``cycle`` = true," +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:32 +msgid "previous value = -2." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:34 +msgid "Then ``box.sequence.S:next()`` returns -5 because -2 + (-3) == -5." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:36 +msgid "Then ``box.sequence.S:next()`` again returns -1 because -5 + (-3) < -6, which is overflow, causing cycle, and ``max`` == -1." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:39 +msgid "This function requires a :doc:`'write' privilege ` on the sequence." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:45 +msgid "This function should not be used in \"cross-engine\" transactions (transactions which use both the memtx and the vinyl storage engines)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/next.rst:48 +msgid "To see what the previous value was, without changing it, you can select from the :ref:`_sequence_data ` system space." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/reset.pot b/locale/en/reference/reference_lua/box_schema_sequence/reset.pot new file mode 100644 index 0000000000..aa0c770dc2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/reset.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/reset.rst:5 +msgid "sequence_object:reset()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/reset.rst:11 +msgid "Set the sequence back to its original state. The effect is that a subsequent ``next()`` will return the ``start`` value. This function requires a :doc:`'write' privilege ` on the sequence." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_schema_sequence/set.pot b/locale/en/reference/reference_lua/box_schema_sequence/set.pot new file mode 100644 index 0000000000..83e056f858 --- /dev/null +++ b/locale/en/reference/reference_lua/box_schema_sequence/set.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_schema_sequence/set.rst:5 +msgid "sequence_object:set()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_schema_sequence/set.rst:11 +msgid "Set the \"previous value\" to ``new-previous-value``. This function requires a :doc:`'write' privilege ` on the sequence." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session.pot b/locale/en/reference/reference_lua/box_session.pot new file mode 100644 index 0000000000..b40b8fc532 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session.pot @@ -0,0 +1,161 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session.rst:5 +msgid "Submodule box.session" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:7 +msgid "The ``box.session`` submodule allows querying the session state, writing to a session-specific temporary Lua table, or sending out-of-band messages, or setting up triggers which will fire when a session starts or ends." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:11 +msgid "A *session* is an object associated with each client connection." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:13 +msgid "Below is a list of all ``box.session`` functions and members." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:24 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:25 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:27 +msgid ":doc:`./box_session/id`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:28 +msgid "Get the current session's ID" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:30 +msgid ":doc:`./box_session/exists`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:31 +msgid "Check if a session exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:33 +msgid ":doc:`./box_session/peer`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:34 +msgid "Get the session peer's host address and port" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:36 +msgid ":doc:`./box_session/sync`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:37 +msgid "Get the sync integer constant" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:39 +msgid ":doc:`./box_session/user`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:40 +msgid "Get the current user's name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:42 +msgid ":doc:`./box_session/type`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:43 +msgid "Get the connection type or cause of action" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:45 +msgid ":doc:`./box_session/su`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:46 +msgid "Change the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:48 +msgid ":doc:`./box_session/uid`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:49 +msgid "Get the current user's ID" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:51 +msgid ":doc:`./box_session/euid`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:52 +msgid "Get the current effective user's ID" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:54 +msgid ":doc:`./box_session/storage`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:55 +msgid "Table with session-specific names and values" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:57 +msgid ":doc:`./box_session/on_connect`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:58 +msgid "Define a connect trigger" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:60 +msgid ":doc:`./box_session/on_disconnect`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:61 +msgid "Define a disconnect trigger" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:63 +msgid ":doc:`./box_session/on_auth`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:64 +msgid "Define an authentication trigger" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:66 +msgid ":doc:`./box_session/on_access_denied`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:67 +msgid "Define a trigger to report restricted actions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:69 +msgid ":doc:`./box_session/push`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session.rst:70 +msgid "Send an out-of-band message" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/euid.pot b/locale/en/reference/reference_lua/box_session/euid.pot new file mode 100644 index 0000000000..93eb680479 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/euid.pot @@ -0,0 +1,72 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:6 +msgid "box.session.euid()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:12 +msgid "the effective user ID of the :ref:`current user `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:14 +msgid "This is the same as :doc:`/reference/reference_lua/box_session/uid`, except in two cases:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:17 +msgid "The first case: if the call to ``box.session.euid()`` is within a function invoked by :doc:`box.session.su(user-name, function-to-execute) ` -- in that case, ``box.session.euid()`` returns the ID of the changed user (the user who is specified by the ``user-name`` parameter of the ``su`` function) but ``box.session.uid()`` returns the ID of the original user (the user who is calling the ``su`` function)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:25 +msgid "The second case: if the call to ``box.session.euid()`` is within a function specified with :doc:`box.schema.func.create(function-name, {setuid= true}) ` and the binary protocol is in use -- in that case, ``box.session.euid()`` returns the ID of the user who created \"function-name\" but ``box.session.uid()`` returns the ID of the the user who is calling \"function-name\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:33 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:35 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/euid.rst:37 +msgid "tarantool> box.session.su('admin')\n" +"---\n" +"...\n" +"tarantool> box.session.uid(), box.session.euid()\n" +"---\n" +"- 1\n" +"- 1\n" +"...\n" +"tarantool> function f() return {box.session.uid(),box.session.euid()} end\n" +"---\n" +"...\n" +"tarantool> box.session.su('guest', f)\n" +"---\n" +"- - 1\n" +" - 0\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/exists.pot b/locale/en/reference/reference_lua/box_session/exists.pot new file mode 100644 index 0000000000..21ac58f9ca --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/exists.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/exists.rst:6 +msgid "box.session.exists()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/exists.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/exists.rst:12 +msgid "true if the session exists, false if the session does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/exists.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/exists.rst:13 +msgid "boolean" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/id.pot b/locale/en/reference/reference_lua/box_session/id.pot new file mode 100644 index 0000000000..4424d77474 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/id.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-21 08:10+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/id.rst:5 +msgid "box.session.id()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/id.rst:11 +msgid "Return the unique identifier (ID) for the current session." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/id.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/id.rst:13 +msgid "the session identifier; 0 or -1 if there is no session" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/id.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/id.rst:14 +msgid "number" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/on_access_denied.pot b/locale/en/reference/reference_lua/box_session/on_access_denied.pot new file mode 100644 index 0000000000..d990bc7f97 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/on_access_denied.pot @@ -0,0 +1,87 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:6 +msgid "box.session.on_access_denied()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:12 +msgid "Define a trigger for reacting to user's attempts to execute actions that are not within the user's privileges." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:15 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:17 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:19 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:21 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:24 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:27 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:31 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:33 +msgid "For example, server administrator can log restricted actions like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:35 +msgid "tarantool> function on_access_denied(op, type, name)\n" +" > log.warn('User %s tried to %s %s %s without required privileges', box.session.user(), op, type, name)\n" +" > end\n" +"---\n" +"...\n" +"tarantool> box.session.on_access_denied(on_access_denied)\n" +"---\n" +"- 'function: 0x011b41af38'\n" +"...\n" +"tarantool> function test() print('you shall not pass') end\n" +"---\n" +"...\n" +"tarantool> box.schema.func.create('test')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_access_denied.rst:53 +msgid "Then, when some user without required privileges tries to call ``test()`` and gets the error, the server will execute this trigger and write to log **\"User *user_name* tried to Execute function test without required privileges\"**" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/on_auth.pot b/locale/en/reference/reference_lua/box_session/on_auth.pot new file mode 100644 index 0000000000..4d96583bb6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/on_auth.pot @@ -0,0 +1,158 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:6 +msgid "box.session.on_auth()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:12 +msgid "Define a trigger for execution during :ref:`authentication `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:15 +msgid "The ``on_auth`` trigger function is invoked in these circumstances:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:17 +msgid "The :ref:`console.connect ` function includes an authentication check for all users except 'guest'. For this case, the ``on_auth`` trigger function is invoked after the ``on_connect`` trigger function, if and only if the connection has succeeded so far." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:22 +msgid "The :ref:`binary protocol ` has a separate :ref:`authentication packet `. For this case, connection and authentication are considered to be separate steps." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:26 +msgid "Unlike other trigger types, ``on_auth`` trigger functions are invoked **before** the event. Therefore a trigger function like :code:`function auth_function () v = box.session.user(); end` will set :code:`v` to \"guest\", the user name before the authentication is done. To get the user name **after** the authentication is done, use the special syntax: :code:`function auth_function (user_name) v = user_name; end`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:33 +msgid "If the trigger fails by raising an error, the error is sent to the client and the connection is closed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:36 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:38 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:40 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:42 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:45 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:48 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:51 +msgid "**Example 1**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:53 +msgid "tarantool> function f ()\n" +" > x = x + 1\n" +" > end\n" +"tarantool> box.session.on_auth(f)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:60 +msgid "**Example 2**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:62 +msgid "This is a more complex example, with two server instances." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:64 +msgid "The first server instance listens on port 3301; its default user name is 'admin'. There are three ``on_auth`` triggers:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:68 +msgid "The first trigger has a function with no arguments, it can only look at ``box.session.user()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:70 +msgid "The second trigger has a function with a ``user_name`` argument, it can look at both of: ``box.session.user()`` and ``user_name``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:72 +msgid "The third trigger has a function with a ``user_name`` argument and a ``status`` argument, it can look at all three of: ``box.session.user()`` and ``user_name`` and ``status``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:77 +msgid "The second server instance will connect with :ref:`console.connect `, and then will cause a display of the variables that were set by the trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:82 +msgid "-- On the first server instance, which listens on port 3301\n" +"box.cfg{listen=3301}\n" +"function function1()\n" +" print('function 1, box.session.user()='..box.session.user())\n" +" end\n" +"function function2(user_name)\n" +" print('function 2, box.session.user()='..box.session.user())\n" +" print('function 2, user_name='..user_name)\n" +" end\n" +"function function3(user_name, status)\n" +" print('function 3, box.session.user()='..box.session.user())\n" +" print('function 3, user_name='..user_name)\n" +" if status == true then\n" +" print('function 3, status = true, authorization succeeded')\n" +" end\n" +" end\n" +"box.session.on_auth(function1)\n" +"box.session.on_auth(function2)\n" +"box.session.on_auth(function3)\n" +"box.schema.user.passwd('admin')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:105 +msgid "-- On the second server instance, that connects to port 3301\n" +"console = require('console')\n" +"console.connect('admin:admin@localhost:3301')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:111 +msgid "The result looks like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_auth.rst:113 +msgid "function 3, box.session.user()=guest\n" +"function 3, user_name=admin\n" +"function 3, status = true, authorization succeeded\n" +"function 2, box.session.user()=guest\n" +"function 2, user_name=admin\n" +"function 1, box.session.user()=guest" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/on_connect.pot b/locale/en/reference/reference_lua/box_session/on_connect.pot new file mode 100644 index 0000000000..dcd7d337e3 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/on_connect.pot @@ -0,0 +1,72 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:6 +msgid "box.session.on_connect()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:12 +msgid "Define a trigger for execution when a new session is created due to an event such as :ref:`console.connect `. The trigger function will be the first thing executed after a new session is created. If the trigger execution fails and raises an error, the error is sent to the client and the connection is closed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:18 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:20 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:22 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:24 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:27 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:30 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:33 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:35 +msgid "tarantool> function f ()\n" +" > x = x + 1\n" +" > end\n" +"tarantool> box.session.on_connect(f)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_connect.rst:44 +msgid "If a trigger always results in an error, it may become impossible to connect to a server to reset it." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/on_disconnect.pot b/locale/en/reference/reference_lua/box_session/on_disconnect.pot new file mode 100644 index 0000000000..2a1578a948 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/on_disconnect.pot @@ -0,0 +1,108 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:6 +msgid "box.session.on_disconnect()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:12 +msgid "Define a trigger for execution after a client has disconnected. If the trigger function causes an error, the error is logged but otherwise is ignored. The trigger is invoked while the session associated with the client still exists and can access session properties, such as :doc:`/reference/reference_lua/box_session/id`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:18 +msgid "Since version 1.10, the trigger function is invoked immediately after the disconnect, even if requests that were made during the session have not finished." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:22 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:24 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:26 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:28 +msgid "If the parameters are (nil, old-trigger-function), then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:31 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:34 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:37 +msgid "**Example #1**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:39 +msgid "tarantool> function f ()\n" +" > x = x + 1\n" +" > end\n" +"tarantool> box.session.on_disconnect(f)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:46 +msgid "**Example #2**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:48 +msgid "After the following series of requests, a Tarantool instance will write a message using the :ref:`log ` module whenever any user connects or disconnects." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:52 +msgid "function log_connect ()\n" +" local log = require('log')\n" +" local m = 'Connection. user=' .. box.session.user() .. ' id=' .. box.session.id()\n" +" log.info(m)\n" +"end\n" +"\n" +"function log_disconnect ()\n" +" local log = require('log')\n" +" local m = 'Disconnection. user=' .. box.session.user() .. ' id=' .. box.session.id()\n" +" log.info(m)\n" +"end\n" +"\n" +"box.session.on_connect(log_connect)\n" +"box.session.on_disconnect(log_disconnect)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:69 +msgid "Here is what might appear in the log file in a typical installation:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/on_disconnect.rst:71 +msgid "2014-12-15 13:21:34.444 [11360] main/103/iproto I>\n" +" Connection. user=guest id=3\n" +"2014-12-15 13:22:19.289 [11360] main/103/iproto I>\n" +" Disconnection. user=guest id=3" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/peer.pot b/locale/en/reference/reference_lua/box_session/peer.pot new file mode 100644 index 0000000000..6f7ed6ab52 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/peer.pot @@ -0,0 +1,45 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:6 +msgid "box.session.peer()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:12 +msgid "This function works only if there is a peer, that is, if a connection has been made to a separate Tarantool instance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:15 +msgid "The host address and port of the session peer, for example \"127.0.0.1:55457\". If the session exists but there is no connection to a separate instance, the return is null. The command is executed on the server instance, so the \"local name\" is the server instance's host and port, and the \"peer name\" is the client's host and port." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:23 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/peer.rst:25 +msgid "Possible errors: 'session.peer(): session does not exist'" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/push.pot b/locale/en/reference/reference_lua/box_session/push.pot new file mode 100644 index 0000000000..29931021ba --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/push.pot @@ -0,0 +1,154 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/push.rst:6 +msgid "box.session.push()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:13 +msgid "Generate an out-of-band message. By \"out-of-band\" we mean an extra message which supplements what is passed in a network via the usual channels. Although ``box.session.push()`` can be called at any time, in practice it is used with networks that are set up with :ref:`module net.box `, and it is invoked by the server (on the \"remote database system\" to use our terminology for net.box), and the client has options for getting such messages." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:22 +msgid "This function returns an error if the session is disconnected." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:24 +msgid "what to send" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:25 +msgid "an optional argument to indicate what the session is, as taken from an earlier call to :doc:`/reference/reference_lua/box_session/sync`. If it is omitted, the default is the current ``box.session.sync()`` value. In Tarantool version :doc:`2.4.2 `, ``sync`` is **deprecated** and its use will cause a warning. Since version 2.5.1, its use will cause an error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:33 +msgid "{nil, error} or true:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:35 +msgid "If the result is an error, then the first part of the return is ``nil`` and the second part is the error object." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:37 +msgid "If the result is not an error, then the return is the boolean value ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:38 +msgid "When the return is ``true``, the message has gone to the network buffer as a :ref:`packet ` with a different header code so the client can distinguish from an ordinary Okay response." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:43 +msgid "The server's sole job is to call ``box.session.push()``, there is no automatic mechanism for showing that the message was received." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:46 +msgid "The client's job is to check for such messages after it sends something to the server. The major client methods -- :ref:`conn:call `, :ref:`conn:eval `, :ref:`conn:select `, :ref:`conn:insert `, :ref:`conn:replace `, :ref:`conn:update `, :ref:`conn:upsert `, :ref:`delete ` -- may cause the server to send a message." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:54 +msgid "Situation 1: when the client calls synchronously with the default ``{async=false}`` option. There are two optional additional options: :samp:`on_push={function-name}`, and :samp:`on_push_ctx={function-argument}`. When the client receives an out-of-band message for the session, it invokes \"function-name(function-argument)\". For example, with options ``{on_push=table.insert, on_push_ctx=messages}``, the client will insert whatever it receives into a table named 'messages'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:62 +msgid "Situation 2: when the client calls asynchronously with the non-default ``{async=true}`` option. Here ``on_push`` and ``on_push_ctx`` are not allowed, but the messages can be seen by calling ``pairs()`` in a loop." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:66 +msgid "Situation 2 complication: ``pairs()`` is subject to timeout. So there is an optional argument = timeout per iteration. If timeout occurs before there is a new message or a final response, there is an error return. To check for an error one can use the first loop parameter (if the loop starts with \"for i, message in future:pairs()\" then the first loop parameter is i). If it is ``box.NULL`` then the second parameter (in our example, \"message\") is the error object." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:74 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/push.rst:76 +msgid "-- Make two shells. On Shell#1 set up a \"server\", and\n" +"-- in it have a function that includes box.session.push:\n" +"box.cfg{listen=3301}\n" +"box.schema.user.grant('guest','read,write,execute','universe')\n" +"x = 0\n" +"fiber = require('fiber')\n" +"function server_function() x=x+1; fiber.sleep(1); box.session.push(x); end\n" +"\n" +"-- On Shell#2 connect to this server as a \"client\" that\n" +"-- can handle Lua (such as another Tarantool server operating\n" +"-- as a client), and initialize a table where we'll get messages:\n" +"net_box = require('net.box')\n" +"conn = net_box.connect(3301)\n" +"messages_from_server = {}\n" +"\n" +"-- On Shell#2 remotely call the server function and receive\n" +"-- a SYNCHRONOUS out-of-band message:\n" +"conn:call('server_function', {},\n" +" {is_async = false,\n" +" on_push = table.insert,\n" +" on_push_ctx = messages_from_server})\n" +"messages_from_server\n" +"-- After a 1-second pause that is caused by the fiber.sleep()\n" +"-- request inside server_function, the result in the\n" +"-- messages_from_server table will be: 1. Like this:\n" +"-- tarantool> messages_from_server\n" +"-- ---\n" +"-- - - 1\n" +"-- ...\n" +"-- Good. That shows that box.session.push(x) worked,\n" +"-- because we know that x was 1.\n" +"\n" +"-- On Shell#2 remotely call the same server function and\n" +"-- get an ASYNCHRONOUS out-of-band message. For this we cannot\n" +"-- use on_push and on_push_ctx options, but we can use pairs():\n" +"future = conn:call('server_function', {}, {is_async = true})\n" +"messages = {}\n" +"keys = {}\n" +"for i, message in future:pairs() do\n" +" table.insert(messages, message) table.insert(keys, i) end\n" +"messages\n" +"future:wait_result(1000)\n" +"for i, message in future:pairs() do\n" +" table.insert(messages, message) table.insert(keys, i) end\n" +"messages\n" +"-- There is no pause because conn:call does not wait for\n" +"-- server_function to finish. The first time that we go through\n" +"-- the pairs() loop, we see the messages table is empty. Like this:\n" +"-- tarantool> messages\n" +"-- ---\n" +"-- - - 2\n" +"-- - []\n" +"-- ...\n" +"-- That is okay because the server hasn't yet called\n" +"-- box.session.push(). The second time that we go through\n" +"-- the pairs() loop, we see the value of x at the time of\n" +"-- the second call to box.session.push(). Like this:\n" +"-- tarantool> messages\n" +"-- ---\n" +"-- - - 2\n" +"-- - &0 []\n" +"-- - 2\n" +"-- - *0\n" +"-- ...\n" +"-- Good. That shows that the message was asynchronous, and\n" +"-- that box.session.push() did its job." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/storage.pot b/locale/en/reference/reference_lua/box_session/storage.pot new file mode 100644 index 0000000000..a9824a1a4a --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/storage.pot @@ -0,0 +1,54 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/storage.rst:6 +msgid "box.session.storage" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/storage.rst:12 +msgid "A Lua table that can hold arbitrary unordered session-specific names and values, which will last until the session ends. For example, this table could be useful to store current tasks when working with a `Tarantool queue manager `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/storage.rst:17 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/storage.rst:19 +msgid "tarantool> box.session.peer(box.session.id())\n" +"---\n" +"- 127.0.0.1:45129\n" +"...\n" +"tarantool> box.session.storage.random_memorandum = \"Don't forget the eggs\"\n" +"---\n" +"...\n" +"tarantool> box.session.storage.radius_of_mars = 3396\n" +"---\n" +"...\n" +"tarantool> m = ''\n" +"---\n" +"...\n" +"tarantool> for k, v in pairs(box.session.storage) do\n" +" > m = m .. k .. '='.. v .. ' '\n" +" > end\n" +"---\n" +"...\n" +"tarantool> m\n" +"---\n" +"- 'radius_of_mars=3396 random_memorandum=Don't forget the eggs. '\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/su.pot b/locale/en/reference/reference_lua/box_session/su.pot new file mode 100644 index 0000000000..0ff61d8dc2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/su.pot @@ -0,0 +1,62 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/su.rst:6 +msgid "box.session.su()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:12 +msgid "Change Tarantool's :ref:`current user ` -- this is analogous to the Unix command ``su``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:15 +msgid "Or, if function-to-execute is specified, change Tarantool's :ref:`current user ` temporarily while executing the function -- this is analogous to the Unix command ``sudo``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:20 +msgid "name of a target user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:21 +msgid "name of a function, or definition of a function. Additional parameters may be passed to ``box.session.su``, they will be interpreted as parameters of function-to-execute." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/su.rst:28 +msgid "tarantool> function f(a) return box.session.user() .. a end\n" +"---\n" +"...\n" +"\n" +"tarantool> box.session.su('guest', f, '-xxx')\n" +"---\n" +"- guest-xxx\n" +"...\n" +"\n" +"tarantool> box.session.su('guest',function(...) return ... end,1,2)\n" +"---\n" +"- 1\n" +"- 2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/sync.pot b/locale/en/reference/reference_lua/box_session/sync.pot new file mode 100644 index 0000000000..883194f1af --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/sync.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:6 +msgid "box.session.sync()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:12 +msgid "the value of the :code:`sync` integer constant used in the `binary protocol `_. This value becomes invalid when the session is disconnected." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:16 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/sync.rst:18 +msgid "This function is local for the request, i.e. not global for the session. If the connection behind the session is multiplexed, this function can be safely used inside the request processor." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/type.pot b/locale/en/reference/reference_lua/box_session/type.pot new file mode 100644 index 0000000000..b57ce59e49 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/type.pot @@ -0,0 +1,65 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/type.rst:6 +msgid "box.session.type()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:12 +msgid "the type of connection or cause of action." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:14 +msgid "string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:16 +msgid "Possible return values are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:18 +msgid "'binary' if the connection was done via the binary protocol, for example to a target made with :ref:`box.cfg{listen=...} `;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:21 +msgid "'console' if the connection was done via the administrative console, for example to a target made with :ref:`console.listen `;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:24 +msgid "'repl' if the connection was done directly, for example when :ref:`using Tarantool as a client `;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:26 +msgid "'applier' if the action is due to :ref:`replication `, regardless of how the connection was done;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:29 +msgid "'background' if the action is in a :ref:`background fiber `, regardless of whether the Tarantool server was :ref:`started in the background `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/type.rst:34 +msgid "``box.session.type()`` is useful for an :ref:`on_replace() ` trigger on a replica -- the value will be 'applier' if and only if the trigger was activated because of a request that was done on the master." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/uid.pot b/locale/en/reference/reference_lua/box_session/uid.pot new file mode 100644 index 0000000000..9f500c6841 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/uid.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:6 +msgid "box.session.uid()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:12 +msgid "the user ID of the :ref:`current user `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:14 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/uid.rst:16 +msgid "Every user has a unique name (seen with :doc:`/reference/reference_lua/box_session/user`) and a unique ID (seen with ``box.session.uid()``). The values are stored together in the ``_user`` space." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_session/user.pot b/locale/en/reference/reference_lua/box_session/user.pot new file mode 100644 index 0000000000..3d574972a3 --- /dev/null +++ b/locale/en/reference/reference_lua/box_session/user.pot @@ -0,0 +1,37 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_session/user.rst:6 +msgid "box.session.user()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/user.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/user.rst:12 +msgid "the name of the :ref:`current user `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/user.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_session/user.rst:14 +msgid "string" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_slab.pot b/locale/en/reference/reference_lua/box_slab.pot new file mode 100644 index 0000000000..1970eac222 --- /dev/null +++ b/locale/en/reference/reference_lua/box_slab.pot @@ -0,0 +1,61 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_slab.rst:5 +msgid "Submodule box.slab" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:7 +msgid "The ``box.slab`` submodule provides access to slab allocator statistics. The slab allocator is the main allocator used to store :ref:`tuples `. This can be used to monitor the total memory usage and memory fragmentation." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:11 +msgid "Below is a list of all ``box.slab`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:22 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:23 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:25 +msgid ":doc:`./box_slab/runtime_info`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:26 +msgid "Show a memory usage report for Lua runtime" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:28 +msgid ":doc:`./box_slab/slab_info`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:29 +msgid "Show an aggregated memory usage report for slab allocator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:31 +msgid ":doc:`./box_slab/slab_stats`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab.rst:32 +msgid "Show a detailed memory usage report for slab allocator" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_slab/runtime_info.pot b/locale/en/reference/reference_lua/box_slab/runtime_info.pot new file mode 100644 index 0000000000..caa1c652c9 --- /dev/null +++ b/locale/en/reference/reference_lua/box_slab/runtime_info.pot @@ -0,0 +1,70 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:5 +msgid "box.runtime.info()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:11 +msgid "Show runtime memory usage report in bytes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:13 +msgid "The runtime memory encompasses internal Lua memory as well as the runtime arena. The Lua memory stores Lua objects. The runtime arena stores Tarantool-specific objects -- for example, runtime tuples, network buffers and other objects associated with the application server subsystem." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:20 +msgid "``lua`` is the size of the Lua heap that is controlled by the Lua garbage collector." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:21 +msgid "``maxalloc`` is the maximum size of the runtime memory." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:22 +msgid "``used`` is the current number of bytes used by the runtime memory." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:24 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/runtime_info.rst:28 +msgid "tarantool> box.runtime.info()\n" +"---\n" +"- lua: 913710\n" +" maxalloc: 4398046510080\n" +" used: 12582912\n" +"...\n" +"tarantool> box.runtime.info().used\n" +"---\n" +"- used: 12582912\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_slab/slab_info.pot b/locale/en/reference/reference_lua/box_slab/slab_info.pot new file mode 100644 index 0000000000..b3cbc8bd9d --- /dev/null +++ b/locale/en/reference/reference_lua/box_slab/slab_info.pot @@ -0,0 +1,137 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:5 +msgid "box.slab.info()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:11 +msgid "Show an aggregated memory usage report (in bytes) for the slab allocator. This report is useful for assessing out-of-memory risks." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:14 +msgid "``box.slab.info`` gives a few ratios:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:16 +msgid "items_used_ratio" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:17 +msgid "arena_used_ratio" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:18 +msgid "quota_used_ratio" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:20 +msgid "Here are two possible cases for monitoring memtx memory usage:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:22 +msgid "**Case 1:** 0.5 < ``items_used_ratio`` < 0.9" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:27 +msgid "Apparently your memory is highly fragmented. Check how many slab classes you have by looking at ``box.slab.stats()`` and counting the number of different classes. If there are many slab classes (more than a few dozens), you may run out of memory even though memory utilization is not high. While each slab may have few items used, whenever a tuple of a size different from any existing slab class size is allocated, Tarantool may need to get a new slab from the slab arena, and since the arena has few empty slabs left, it will attempt to increase its quota usage, which, in turn, may end up with an out-of-memory error due to the low remaining quota." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:37 +msgid "**Case 2:** ``items_used_ratio`` > 0.9" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:42 +msgid "You are running out of memory. All memory utilization indicators are high. Your memory is not fragmented, but there are few reserves left on each slab allocator level. You should consider increasing Tarantool's memory limit (``box.cfg.memtx_memory``)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:47 +msgid "**To sum up:** your main out-of-memory indicator is ``quota_used_ratio``. However, there are lots of perfectly stable setups with a high ``quota_used_ratio``, so you only need to pay attention to it when both arena and item used ratio are also high." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:54 +msgid "``quota_size`` - memory limit for slab allocator (as configured in the :ref:`memtx_memory ` parameter, the default is 2^28 bytes = 268,435,456 bytes)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:57 +msgid "``quota_used`` - used by slab allocator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:58 +msgid "``items_size`` - allocated only for tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:59 +msgid "``items_used`` - used only for tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:60 +msgid "``arena_size`` - allocated for both tuples and indexes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:61 +msgid "``arena_used`` - used for both tuples and indexes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:62 +msgid "``items_used_ratio`` = ``items_used`` / ``items_size``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:63 +msgid "``quota_used_ratio`` = ``quota_used`` / ``quota_size``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:64 +msgid "``arena_used_ratio`` = ``arena_used`` / ``arena_size``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:66 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:68 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_info.rst:70 +msgid "tarantool> box.slab.info()\n" +"---\n" +"- items_size: 228128\n" +" items_used_ratio: 1.8%\n" +" quota_size: 1073741824\n" +" quota_used_ratio: 0.8%\n" +" arena_used_ratio: 43.2%\n" +" items_used: 4208\n" +" quota_used: 8388608\n" +" arena_size: 2325176\n" +" arena_used: 1003632\n" +"...\n" +"\n" +"tarantool> box.slab.info().arena_used\n" +"---\n" +"- 1003632\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_slab/slab_stats.pot b/locale/en/reference/reference_lua/box_slab/slab_stats.pot new file mode 100644 index 0000000000..ba6f81f1f2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_slab/slab_stats.pot @@ -0,0 +1,124 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:5 +msgid "box.slab.stats()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:11 +msgid "Show a detailed memory usage report (in bytes) for the slab allocator. The report is broken down into groups by *data item size* as well as by *slab size* (64-byte, 136-byte, etc). The report includes the memory allocated for storing both tuples and indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:18 +msgid "``mem_free`` is the allocated, but currently unused memory;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:19 +msgid "``mem_used`` is the memory used for storing data items (tuples and indexes);" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:20 +msgid "``item_count`` is the number of stored items;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:21 +msgid "``item_size`` is the size of each data item;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:22 +msgid "``slab_count`` is the number of slabs allocated;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:23 +msgid "``slab_size`` is the size of each allocated slab." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:25 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:27 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:29 +msgid "Here is a sample report for the first group:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:31 +msgid "tarantool> box.slab.stats()[1]\n" +"---\n" +"- mem_free: 16232\n" +" mem_used: 48\n" +" item_count: 2\n" +" item_size: 24\n" +" slab_count: 1\n" +" slab_size: 16384\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:43 +msgid "This report is saying that there are 2 data items (``item_count`` = 2) stored in one (``slab_count`` = 1) 24-byte slab (``item_size`` = 24), so ``mem_used`` = 2 * 24 = 48 bytes. Also, ``slab_size`` is 16384 bytes, of which 16384 - 48 = 16232 bytes are free (``mem_free``)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:48 +msgid "A complete report would show memory usage statistics for all groups:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:50 +msgid "tarantool> box.slab.stats()\n" +"---\n" +"- - mem_free: 16232\n" +" mem_used: 48\n" +" item_count: 2\n" +" item_size: 24\n" +" slab_count: 1\n" +" slab_size: 16384\n" +" - mem_free: 15720\n" +" mem_used: 560\n" +" item_count: 14\n" +" item_size: 40\n" +" slab_count: 1\n" +" slab_size: 16384\n" +" <...>\n" +" - mem_free: 32472\n" +" mem_used: 192\n" +" item_count: 1\n" +" item_size: 192\n" +" slab_count: 1\n" +" slab_size: 32768\n" +" - mem_free: 1097624\n" +" mem_used: 999424\n" +" item_count: 61\n" +" item_size: 16384\n" +" slab_count: 1\n" +" slab_size: 2097152\n" +" ..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_slab/slab_stats.rst:81 +msgid "The total ``mem_used`` for all groups in this report equals ``arena_used`` in :doc:`/reference/reference_lua/box_slab/slab_info` report." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_snapshot.pot b/locale/en/reference/reference_lua/box_snapshot.pot new file mode 100644 index 0000000000..269b537b8b --- /dev/null +++ b/locale/en/reference/reference_lua/box_snapshot.pot @@ -0,0 +1,84 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:5 +msgid "Function box.snapshot" +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:9 +msgid "**Memtx**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:11 +msgid "Take a snapshot of all data and store it in :ref:`memtx_dir `:samp:`/{}.snap`. To take a snapshot, Tarantool first enters the delayed garbage collection mode for all data. In this mode, the :ref:`Tarantool garbage collector ` will not remove files which were created before the snapshot started, it will not remove them until the snapshot has finished. To preserve consistency of the primary key, used to iterate over tuples, a copy-on-write technique is employed. If the master process changes part of a primary key, the corresponding process page is split, and the snapshot process obtains an old copy of the page. In effect, the snapshot process uses multi-version concurrency control in order to avoid copying changes which are superseded while it is running." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:25 +msgid "Since a snapshot is written sequentially, you can expect a very high write performance (averaging to 80MB/second on modern disks), which means an average database instance gets saved in a matter of minutes. You may restrict the speed by changing :ref:`snap_io_rate_limit `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:33 +msgid "As long as there are any changes to the parent index memory through concurrent updates, there are going to be page splits, and therefore you need to have some extra free memory to run this command. 10% of :ref:`memtx_memory ` is, on average, sufficient. This statement waits until a snapshot is taken and returns operation result." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:41 +msgid "**Change notice:** Prior to Tarantool version 1.6.6, the snapshot process caused a fork, which could cause occasional latency spikes. Starting with Tarantool version 1.6.6, the snapshot process creates a consistent read view and this view is written to the snapshot file by a separate thread (the \"Write Ahead Log\" thread)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:47 +msgid "Although ``box.snapshot()`` does not cause a fork, there is a separate fiber which may produce snapshots at regular intervals -- see the discussion of the :ref:`checkpoint daemon `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:51 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:53 +msgid "tarantool> box.info.version\n" +"---\n" +"- 1.7.0-1216-g73f7154\n" +"...\n" +"tarantool> box.snapshot()\n" +"---\n" +"- ok\n" +"...\n" +"tarantool> box.snapshot()\n" +"---\n" +"- error: can't save snapshot, errno 17 (File exists)\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:68 +msgid "Taking a snapshot does not cause the server to start a new write-ahead log. Once a snapshot is taken, old WALs can be deleted as long as all replicated data is up to date. But the WAL which was current at the time ``box.snapshot()`` started must be kept for recovery, since it still contains log records written after the start of ``box.snapshot()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:74 +msgid "An alternative way to save a snapshot is to send a SIGUSR1 signal to the instance. While this approach could be handy, it is not recommended for use in automation: a signal provides no way to find out whether the snapshot was taken successfully or not." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:79 +msgid "**Vinyl**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:81 +msgid "In vinyl, inserted data is stacked in memory until the limit, set in the :ref:`vinyl_memory ` parameter, is reached. Then vinyl automatically dumps it to the disc. ``box.snapshot()`` forces this dump in order to have the ability to recover from this checkpoint. The snapshot files are stored in :samp:`{space_id}/{index_id}/*.run`. Thus, strictly all the data that was written at the time of LSN of the checkpoint is in the ``*.run`` files on the disk, and all operations that happened after the checkpoint will be written in the ``*.xlog``. All dump files created by ``box.snapshot()`` are consistent and have the same LSN as checkpoint." +msgstr "" + +#: ../../doc/reference/reference_lua/box_snapshot.rst:91 +msgid "At the checkpoint vinyl also rotates the metadata log ``*.vylog``, containing data manipulation operations like \"create file\" and \"delete file\". It goes through the log, removes duplicating operations from the memory and creates a new ``*.vylog`` file, giving it the name according to the :ref:`vclock ` of the new checkpoint, with \"create\" operations only. This procedure cleans ``*.vylog`` and is useful for recovery because the name of the log is the same as the checkpoint signature." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space.pot b/locale/en/reference/reference_lua/box_space.pot new file mode 100644 index 0000000000..f7b7c4b161 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space.pot @@ -0,0 +1,429 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space.rst:7 +msgid "Submodule box.space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:9 +msgid "**CRUD operations** in Tarantool are implemented by the ``box.space`` submodule. 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." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:14 +msgid "Below is a list of all ``box.space`` functions and members." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:25 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:26 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:28 +msgid ":doc:`./box_schema/space_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:29 +msgid "Create a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:31 +msgid ":doc:`./box_space/alter`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:32 +msgid "Alter a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:34 +msgid ":doc:`./box_space/auto_increment`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:35 +msgid "Generate key + Insert a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:37 +msgid ":doc:`./box_space/bsize`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:38 +msgid "Get count of bytes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:40 +msgid ":doc:`./box_space/count`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:41 +#: ../../doc/reference/reference_lua/box_space.rst:65 +msgid "Get count of tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:43 +msgid ":doc:`./box_space/create_index`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:44 +msgid "Create an index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:46 +msgid ":doc:`./box_space/delete`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:47 +msgid "Delete a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:49 +msgid ":doc:`./box_space/drop`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:50 +msgid "Destroy a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:52 +msgid ":doc:`./box_space/format`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:53 +msgid "Declare field names and types" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:55 +msgid ":doc:`./box_space/frommap`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:56 +msgid "Convert from map to tuple or table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:58 +msgid ":doc:`./box_space/get`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:59 +msgid "Select a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:61 +msgid ":doc:`./box_space/insert`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:62 +msgid "Insert a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:64 +msgid ":doc:`./box_space/len`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:67 +msgid ":doc:`./box_space/on_replace`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:68 +msgid "Create a replace trigger with a function that cannot change the tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:70 +msgid ":doc:`./box_space/before_replace`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:71 +msgid "Create a replace trigger with a function that can change the tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:73 +msgid ":doc:`./box_space/pairs`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:74 +msgid "Prepare for iterating" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:76 +msgid ":doc:`./box_space/put`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:77 +#: ../../doc/reference/reference_lua/box_space.rst:83 +msgid "Insert or replace a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:79 +msgid ":doc:`./box_space/rename`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:80 +msgid "Rename a space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:82 +msgid ":doc:`./box_space/replace`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:85 +msgid ":doc:`./box_space/run_triggers`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:86 +msgid "Enable/disable a replace trigger" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:88 +msgid ":doc:`./box_space/select`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:89 +msgid "Select one or more tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:91 +msgid ":doc:`./box_space/truncate`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:92 +msgid "Delete all tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:94 +msgid ":doc:`./box_space/update`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:95 +#: ../../doc/reference/reference_lua/box_space.rst:98 +msgid "Update a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:97 +msgid ":doc:`./box_space/upsert`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:100 +msgid ":doc:`./box_space/user_defined`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:101 +msgid "Any function / method that any user wants to add" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:103 +msgid ":doc:`./box_space/create_check_constraint`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:104 +msgid "Create a check constraint" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:106 +msgid ":doc:`./box_space/enabled`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:107 +msgid "Flag, true if space is enabled" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:109 +msgid ":doc:`./box_space/field_count`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:110 +msgid "Required number of fields" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:112 +msgid ":doc:`./box_space/id`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:113 +msgid "Numeric identifier of space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:115 +msgid ":doc:`./box_space/index_data`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:116 +msgid "Container of space's indexes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:118 +msgid ":doc:`./box_space/_cluster`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:119 +msgid "(Metadata) List of replica sets" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:121 +msgid ":doc:`./box_space/_func`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:122 +msgid "(Metadata) List of function tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:124 +msgid ":doc:`./box_space/_index`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:125 +msgid "(Metadata) List of indexes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:127 +msgid ":doc:`./box_space/_vindex`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:128 +msgid "(Metadata) List of indexes accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:130 +msgid ":doc:`./box_space/_priv`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:131 +msgid "(Metadata) List of privileges" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:133 +msgid ":doc:`./box_space/_vpriv`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:134 +msgid "(Metadata) List of privileges accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:136 +msgid ":doc:`./box_space/_schema`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:137 +msgid "(Metadata) List of schemas" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:139 +msgid ":doc:`./box_space/_sequence`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:140 +#: ../../doc/reference/reference_lua/box_space.rst:143 +msgid "(Metadata) List of sequences" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:142 +msgid ":doc:`./box_space/_sequence_data`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:145 +msgid ":doc:`./box_space/_space`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:146 +msgid "(Metadata) List of spaces" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:148 +msgid ":doc:`./box_space/_vspace`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:149 +msgid "(Metadata) List of spaces accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:151 +msgid ":doc:`./box_space/_space_sequence`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:152 +msgid "(Metadata) List of connections between spaces and sequences" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:154 +msgid ":doc:`./box_space/_vspace_sequence`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:155 +msgid "(Metadata) List of connections between spaces and sequences accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:158 +msgid ":doc:`./box_space/_user`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:159 +msgid "(Metadata) List of users" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:161 +msgid ":doc:`./box_space/_vuser`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:162 +msgid "(Metadata) List of users accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:164 +msgid ":doc:`./box_space/_ck_constraint`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:165 +msgid "(Metadata) List of check constraints" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:167 +msgid ":doc:`./box_space/_collation`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:168 +msgid "(Metadata) List of collations" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:170 +msgid ":doc:`./box_space/_vcollation`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:171 +msgid "(Metadata) List of collations accessible for the current user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:173 +msgid ":doc:`./box_space/system_views`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:174 +msgid "(Metadata) Spaces whose names begin with _v" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:176 +msgid ":doc:`./box_space/_session_settings`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:177 +msgid "(Metadata) List of settings affecting behavior of the current session" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space.rst:179 +msgid "To see examples, visit the :ref:`how-to guide on CRUD operations `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_ck_constraint.pot b/locale/en/reference/reference_lua/box_space/_ck_constraint.pot new file mode 100644 index 0000000000..956a9a7b06 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_ck_constraint.pot @@ -0,0 +1,61 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:5 +msgid "box.space._ck_constraint" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:11 +msgid "``_ck_constraint`` is a system space where check constraints are stored." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:13 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:15 +msgid "the numeric id of the space (\"space_id\")," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:16 +msgid "the name," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:17 +msgid "whether the check is deferred (\"is_deferred\")," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:18 +msgid "the language of the expression, such as 'SQL'," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:19 +msgid "the expression (\"code\")" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_ck_constraint.rst:23 +msgid "tarantool> box.space._ck_constraint:select()\n" +"---\n" +"- - [527, 'c1', false, 'SQL', '\"f2\" > ''A''']\n" +" - [527, 'c2', false, 'SQL', '\"f2\" == UPPER(\"f3\") AND NOT \"f2\" LIKE ''__''']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_cluster.pot b/locale/en/reference/reference_lua/box_space/_cluster.pot new file mode 100644 index 0000000000..0074b55d27 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_cluster.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_cluster.rst:5 +msgid "box.space._cluster" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_cluster.rst:11 +msgid "``_cluster`` is a system space for support of the :ref:`replication feature `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_collation.pot b/locale/en/reference/reference_lua/box_space/_collation.pot new file mode 100644 index 0000000000..ff1491f3f1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_collation.pot @@ -0,0 +1,40 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_collation.rst:5 +msgid "box.space._collation" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_collation.rst:11 +msgid "``_collation`` is a system space with a list of :ref:`collations `. There are over 270 built-in collations and users may add more. Here is one example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_collation.rst:14 +msgid "tarantool> box.space._collation:select(239)\n" +"---\n" +"- - [239, 'unicode_uk_s2', 1, 'ICU', 'uk', {'strength': 'secondary'}]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_collation.rst:21 +msgid "Explanation of the fields in the example: id = 239 i.e. Tarantool's primary key is 239, name = 'unicode_uk_s2' i.e. according to Tarantool's naming convention this is a Unicode collation + it is for the uk locale + it has secondary strength, owner = 1 i.e. :ref:`the admin user `, type = 'ICU' i.e. the rules are according to `International Components for Unicode `_, locale = 'uk' i.e. `Ukrainian `_, opts = 'strength:secondary' i.e. with this collation comparisons use both primary and secondary `weights `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_collation.rst:30 +msgid "The :ref:`system space view ` for ``_collation`` is ``_vcollation``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_func.pot b/locale/en/reference/reference_lua/box_space/_func.pot new file mode 100644 index 0000000000..a272263e0f --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_func.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_func.rst:5 +msgid "box.space._func" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_func.rst:11 +msgid "A system space containing functions created using :ref:`box.schema.func.create() `. If a function's definition is specified in the :ref:`body ` option, this function is *persistent*. In this case, its definition is stored in a snapshot and can be recovered if the server restarts." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_func.rst:18 +msgid "The :ref:`system space view ` for ``_func`` is ``_vfunc``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_index.pot b/locale/en/reference/reference_lua/box_space/_index.pot new file mode 100644 index 0000000000..c4901bf7d6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_index.pot @@ -0,0 +1,78 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:5 +msgid "box.space._index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:11 +msgid "``_index`` is a system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:13 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:15 +msgid "``id`` (= id of space)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:16 +msgid "``iid`` (= index number within space)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:17 +msgid "``name``," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:18 +msgid "``type``," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:19 +msgid "``opts`` (e.g. unique option), [``tuple-field-no``, ``tuple-field-type`` ...]." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:21 +msgid "Here is what ``_index`` contains in a typical installation:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:23 +msgid "tarantool> box.space._index:select{}\n" +"---\n" +"- - [272, 0, 'primary', 'tree', {'unique': true}, [[0, 'string']]]\n" +" - [280, 0, 'primary', 'tree', {'unique': true}, [[0, 'unsigned']]]\n" +" - [280, 1, 'owner', 'tree', {'unique': false}, [[1, 'unsigned']]]\n" +" - [280, 2, 'name', 'tree', {'unique': true}, [[2, 'string']]]\n" +" - [281, 0, 'primary', 'tree', {'unique': true}, [[0, 'unsigned']]]\n" +" - [281, 1, 'owner', 'tree', {'unique': false}, [[1, 'unsigned']]]\n" +" - [281, 2, 'name', 'tree', {'unique': true}, [[2, 'string']]]\n" +" - [288, 0, 'primary', 'tree', {'unique': true}, [[0, 'unsigned'], [1, 'unsigned']]]\n" +" - [288, 2, 'name', 'tree', {'unique': true}, [[0, 'unsigned'], [2, 'string']]]\n" +" - [289, 0, 'primary', 'tree', {'unique': true}, [[0, 'unsigned'], [1, 'unsigned']]]\n" +" - [289, 2, 'name', 'tree', {'unique': true}, [[0, 'unsigned'], [2, 'string']]]\n" +" - [296, 0, 'primary', 'tree', {'unique': true}, [[0, 'unsigned']]]\n" +" - [296, 1, 'owner', 'tree', {'unique': false}, [[1, 'unsigned']]]\n" +" - [296, 2, 'name', 'tree', {'unique': true}, [[2, 'string']]]\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_index.rst:44 +msgid "The :ref:`system space view ` for ``_index`` is ``_vindex``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_priv.pot b/locale/en/reference/reference_lua/box_space/_priv.pot new file mode 100644 index 0000000000..2a89f4759c --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_priv.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:5 +msgid "box.space._priv" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:11 +msgid "``_priv`` is a system space where :ref:`privileges ` are stored." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:14 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:16 +msgid "the numeric id of the user who gave the privilege (\"grantor_id\")," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:17 +msgid "the numeric id of the user who received the privilege (\"grantee_id\")," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:18 +msgid "the type of object: 'space', 'index', 'function', 'sequence', 'user', 'role', or 'universe'," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:19 +msgid "the numeric id of the object," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:20 +msgid "the type of operation: \"read\" = 1, \"write\" = 2, \"execute\" = 4, \"create\" = 32, \"drop\" = 64, \"alter\" = 128, or a combination such as \"read,write,execute\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:24 +msgid "See :ref:`Access control ` for details about user privileges." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_priv.rst:26 +msgid "The :ref:`system space view ` for ``_priv`` is ``_vpriv``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_schema.pot b/locale/en/reference/reference_lua/box_space/_schema.pot new file mode 100644 index 0000000000..688e39a4a7 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_schema.pot @@ -0,0 +1,63 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:5 +msgid "box.space._schema" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:11 +msgid "``_schema`` is a system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:13 +msgid "This space contains the following tuples:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:15 +msgid "``version`` tuple with version information for this Tarantool instance," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:16 +msgid "``cluster`` tuple with the instance's replica set ID," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:17 +msgid "``max_id`` tuple with the maximal space ID," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:18 +msgid "``once...`` tuples that correspond to specific :doc:`box.once() ` blocks from the instance's :ref:`initialization file `. The first field in these tuples contains the ``key`` value from the corresponding ``box.once()`` block prefixed with 'once' (e.g. `oncehello`), so you can easily find a tuple that corresponds to a specific ``box.once()`` block." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:28 +msgid "Here is what ``_schema`` contains in a typical installation (notice the tuples for two ``box.once()`` blocks, ``'oncebye'`` and ``'oncehello'``):" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_schema.rst:31 +msgid "tarantool> box.space._schema:select{}\n" +"---\n" +"- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']\n" +" - ['max_id', 512]\n" +" - ['oncebye']\n" +" - ['oncehello']\n" +" - ['version', 1, 7, 2]" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_sequence.pot b/locale/en/reference/reference_lua/box_space/_sequence.pot new file mode 100644 index 0000000000..41994ba240 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_sequence.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_sequence.rst:5 +msgid "box.space._sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence.rst:11 +msgid "``_sequence`` is a system space for support of the :ref:`sequence feature `. It contains persistent information that was established by :doc:`/reference/reference_lua/box_schema_sequence/create` or :doc:`/reference/reference_lua/box_schema_sequence/alter`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence.rst:17 +msgid "The :ref:`system space view ` for ``_sequence`` is ``_vsequence``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_sequence_data.pot b/locale/en/reference/reference_lua/box_space/_sequence_data.pot new file mode 100644 index 0000000000..b966a47bbf --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_sequence_data.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:5 +msgid "box.space._sequence_data" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:11 +msgid "``_sequence_data`` is a system space for support of the :ref:`sequence feature `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:14 +msgid "Each tuple in ``_sequence_data`` contains two fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:16 +msgid "the id of the sequence, and" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:17 +msgid "the last value that the sequence generator returned (non-persistent information)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_sequence_data.rst:20 +msgid "There is no guarantee that this space will be updated immediately after every data-change request." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_session_settings.pot b/locale/en/reference/reference_lua/box_space/_session_settings.pot new file mode 100644 index 0000000000..373de11d70 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_session_settings.pot @@ -0,0 +1,73 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:5 +msgid "box.space._session_settings" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:11 +msgid "A temporary system space with settings that affect behavior, particularly SQL behavior, for the current session. It uses a special engine named 'service'. Every 'service' tuple is created on the fly, that is, new tuples are made every time ``_session_settings`` is accessed. Every settings tuple has two fields: ``name`` (the primary key) and ``value``. The tuples' names and default values are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:18 +msgid "``sql_default_engine``: default :ref:`storage engine ` for new SQL tables. Default: ``memtx``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:19 +msgid "``sql_full_column_names``: use full column names in :ref:`SQL result set metadata `. Default: ``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:21 +msgid "``sql_full_metadata``: whether :ref:`SQL result set metadata ` includes more than just name and type. Default:``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:23 +msgid "``sql_parser_debug``: show parser steps for following statements. Default: ``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:24 +msgid "``sql_recursive_triggers``: whether a triggered statement can activate a :ref:`trigger `. Default: ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:26 +msgid "``sql_reverse_unordered_selects``: return result rows in reverse order if there is no :ref:`ORDER BY clause `. Default: ``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:28 +msgid "``sql_select_debug``: show execution steps during :ref:`SELECT `. Default:``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:29 +msgid "``sql_seq_scan``: allow sequential scans in SQL :ref:`SELECT `. Default: ``true``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:30 +msgid "``sql_vdbe_debug``: for internal use. Default:``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:31 +msgid "``sql_defer_foreign_keys`` (removed in :doc:`2.11.0 `): whether foreign-key checks can wait till commit. Default: ``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:33 +msgid "``error_marshaling_enabled`` (removed in :doc:`2.10.0 `): whether :doc:`error objects ` have a special structure. Default: ``false``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_session_settings.rst:36 +msgid "Three requests are possible: :doc:`select `, :doc:`get ` and :doc:`update `. For example, after ``s = box.space._session_settings``, ``s:select('sql_default_engine')`` probably returns ``{'sql_default_engine', 'memtx'}``, and ``s:update('sql_default_engine', {{'=', 'value', 'vinyl'}})`` changes the default engine to 'vinyl'. |br| Updating ``sql_parser_debug`` or ``sql_select_debug`` or ``sql_vdbe_debug`` has no effect unless Tarantool was built with ``-DCMAKE_BUILD_TYPE=Debug``. To check if this is so, look at ``require('tarantool').build.target``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_space.pot b/locale/en/reference/reference_lua/box_space/_space.pot new file mode 100644 index 0000000000..7227969df1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_space.pot @@ -0,0 +1,140 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:4 +msgid "box.space._space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:10 +msgid "``_space`` is a system space. It contains all spaces hosted on the current Tarantool instance, both system ones and created by users." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:13 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:15 +msgid "``id``," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:16 +msgid "``owner`` (= id of user who owns the space)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:17 +msgid "``name``, ``engine``, ``field_count``," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:18 +msgid "``flags`` (e.g. temporary)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:19 +msgid "``format`` (as made by a :doc:`format clause `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:21 +msgid "These fields are established by :doc:`/reference/reference_lua/box_schema/space_create`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:23 +msgid "The :ref:`system space view ` for ``_space`` is ``_vspace``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:25 +msgid "**Example #1:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:27 +msgid "The following function will display every simple field in all tuples of ``_space``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:30 +msgid "function example()\n" +" local ta = {}\n" +" local i, line\n" +" for k, v in box.space._space:pairs() do\n" +" i = 1\n" +" line = ''\n" +" while i <= #v do\n" +" if type(v[i]) ~= 'table' then\n" +" line = line .. v[i] .. ' '\n" +" end\n" +" i = i + 1\n" +" end\n" +" table.insert(ta, line)\n" +" end\n" +" return ta\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:49 +msgid "Here is what ``example()`` returns in a typical installation:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:51 +msgid "tarantool> example()\n" +"---\n" +"- - '272 1 _schema memtx 0 '\n" +" - '280 1 _space memtx 0 '\n" +" - '281 1 _vspace sysview 0 '\n" +" - '288 1 _index memtx 0 '\n" +" - '296 1 _func memtx 0 '\n" +" - '304 1 _user memtx 0 '\n" +" - '305 1 _vuser sysview 0 '\n" +" - '312 1 _priv memtx 0 '\n" +" - '313 1 _vpriv sysview 0 '\n" +" - '320 1 _cluster memtx 0 '\n" +" - '512 1 tester memtx 0 '\n" +" - '513 1 origin vinyl 0 '\n" +" - '514 1 archive memtx 0 '\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:70 +msgid "**Example #2:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:72 +msgid "The following requests will create a space using ``box.schema.space.create()`` with a :doc:`format clause `, then retrieve the ``_space`` tuple for the new space. This illustrates the typical use of the ``format`` clause, it shows the recommended names and data types for the fields." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space.rst:78 +msgid "tarantool> box.schema.space.create('TM', {\n" +" > id = 12345,\n" +" > format = {\n" +" > [1] = {[\"name\"] = \"field_1\"},\n" +" > [2] = {[\"type\"] = \"unsigned\"}\n" +" > }\n" +" > })\n" +"---\n" +"- index: []\n" +" on_replace: 'function: 0x41c67338'\n" +" temporary: false\n" +" id: 12345\n" +" engine: memtx\n" +" enabled: false\n" +" name: TM\n" +" field_count: 0\n" +"- created\n" +"...\n" +"tarantool> box.space._space:select(12345)\n" +"---\n" +"- - [12345, 1, 'TM', 'memtx', 0, {}, [{'name': 'field_1'}, {'type': 'unsigned'}]]\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_space_sequence.pot b/locale/en/reference/reference_lua/box_space/_space_sequence.pot new file mode 100644 index 0000000000..bfac9432e6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_space_sequence.pot @@ -0,0 +1,83 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:4 +msgid "box.space._space_sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:10 +msgid "``_space_sequence`` is a system space. It contains connections between spaces and sequences." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:13 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:15 +msgid "``id`` (``unsigned``) -- space id" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:16 +msgid "``sequence_id`` (``unsigned``) -- id of the attached sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:17 +msgid "``is_generated`` (``boolean``) -- ``true`` if the sequence was created automatically via a ``space:create_index('pk', {sequence = true})`` call" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:19 +msgid "``field`` (``unsigned``) -- id of the space field to which the sequence is attached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:20 +msgid "``path`` (``string``) -- path to the data within the field that is set using the attached sequence." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:23 +msgid "The :ref:`system space view ` for ``_space_sequence`` is ``_vspace_sequence``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:27 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_space_sequence.rst:29 +msgid "-- Create a sequence --\n" +"box.schema.sequence.create('id_seq',{min=1000, start=1000})\n" +"-- Create a space --\n" +"box.schema.space.create('customers')\n" +"\n" +"-- Create an index that uses the sequence --\n" +"box.space.customers:create_index('primary',{ sequence = 'id_seq' })\n" +"\n" +"-- Create a space --\n" +"box.schema.space.create('orders')\n" +"\n" +"-- Create an index that uses an auto sequence --\n" +"box.space.orders:create_index( 'primary', { sequence = true })\n" +"\n" +"-- Check the connections between spaces and sequences\n" +"box.space._space_sequence:select{}\n" +"--[[\n" +"---\n" +"- - [512, 1, false, 0, '']\n" +" - [513, 2, true, 0, '']\n" +"...\n" +"--]]\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_user.pot b/locale/en/reference/reference_lua/box_space/_user.pot new file mode 100644 index 0000000000..22df81bd3c --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_user.pot @@ -0,0 +1,239 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:5 +msgid "box.space._user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:11 +msgid "``_user`` is a system space where user-names and password hashes are stored." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:13 +msgid "Tuples in this space contain the following fields:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:15 +msgid "a numeric id of the tuple (\"id\")" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:16 +msgid "a numeric id of the tuple’s creator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:17 +msgid "a name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:18 +msgid "a type: 'user' or 'role'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:19 +msgid "(optional) a password hash" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:20 +msgid "(optional) an array of previous authentication data" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:21 +msgid "(optional) a timestamp of the last password update" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:23 +msgid "There are five special tuples in the ``_user`` space: 'guest', 'admin', 'public', 'replication', and 'super'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:36 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:36 +msgid "ID" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:36 +msgid "Type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:36 +msgid "Description" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:38 +msgid "guest" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:38 +msgid "0" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:38 +#: ../../doc/reference/reference_lua/box_space/_user.rst:41 +msgid "user" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:38 +msgid "Default user when connecting remotely. Usually, an untrusted user with few privileges." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:41 +msgid "admin" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:41 +msgid "1" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:41 +msgid "Default user when using Tarantool as a console. Usually, an :ref:`administrative user ` with all privileges." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:46 +msgid "public" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:46 +msgid "2" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:46 +#: ../../doc/reference/reference_lua/box_space/_user.rst:54 +#: ../../doc/reference/reference_lua/box_space/_user.rst:58 +msgid "role" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:46 +msgid "Pre-defined :ref:`role `, automatically granted to new users when they are created with ``box.schema.user.create(user-name)``. Therefore a convenient way to grant 'read' on space 't' to every user that will ever exist is with ``box.schema.role.grant('public','read','space','t')``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:54 +msgid "replication" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:54 +msgid "3" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:54 +msgid "Pre-defined :ref:`role `, which the 'admin' user can grant to users who need to use :ref:`replication ` features." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:58 +msgid "super" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:58 +msgid "31" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:58 +msgid "Pre-defined :ref:`role `, which the 'admin' user can grant to users who need all privileges on all objects. The 'super' role has these privileges on 'universe': read, write, execute, create, drop, alter." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:66 +msgid "To select a tuple from the ``_user`` space, use ``box.space._user:select()``. In the example below, ``select`` is executed for a user with id = 0. This is the 'guest' user that has no password." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:70 +msgid "tarantool> box.space._user:select{0}\n" +"---\n" +"- - [0, 1, 'guest', 'user']\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:79 +msgid "To change tuples in the ``_user`` space, do not use ordinary ``box.space`` functions for insert, update, or delete. The ``_user`` space is special, so there are special functions that have appropriate error checking.\\" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:83 +msgid "To create a new user, use :doc:`/reference/reference_lua/box_schema/user_create`:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:85 +msgid "box.schema.user.create(*user-name*)\n" +"box.schema.user.create(*user-name*, {if_not_exists = true})\n" +"box.schema.user.create(*user-name*, {password = *password*})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:91 +msgid "To change the user's password, use :doc:`/reference/reference_lua/box_schema/user_passwd`:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:93 +msgid "-- To change the current user's password\n" +"box.schema.user.passwd(*password*)\n" +"\n" +"-- To change a different user's password\n" +"-- (usually only 'admin' can do it)\n" +"box.schema.user.passwd(*user-name*, *password*)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:102 +msgid "To drop a user, use :doc:`/reference/reference_lua/box_schema/user_drop`:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:104 +msgid "box.schema.user.drop(*user-name*)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:108 +msgid "To check whether a user exists, use :doc:`/reference/reference_lua/box_schema/user_exists`, which returns ``true`` or ``false``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:111 +msgid "box.schema.user.exists(*user-name*)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:115 +msgid "To find what privileges a user has, use :doc:`/reference/reference_lua/box_schema/user_info`:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:117 +msgid "box.schema.user.info(*user-name*)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:123 +msgid "The maximum number of users is 32." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:125 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:127 +msgid "Here is a session which creates a new user with a strong password, selects a tuple in the ``_user`` space, and then drops the user." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:130 +msgid "tarantool> box.schema.user.create('JeanMartin', {password = 'Iwtso_6_os$$'})\n" +"---\n" +"...\n" +"tarantool> box.space._user.index.name:select{'JeanMartin'}\n" +"---\n" +"- - [17, 1, 'JeanMartin', 'user', {'chap-sha1': 't3xjUpQdrt857O+YRvGbMY5py8Q='}]\n" +"...\n" +"tarantool> box.schema.user.drop('JeanMartin')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_user.rst:143 +msgid "The :ref:`system space view ` for ``_user`` is ``_vuser``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vcollation.pot b/locale/en/reference/reference_lua/box_space/_vcollation.pot new file mode 100644 index 0000000000..e5984b5d3a --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vcollation.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vcollation.rst:5 +msgid "box.space._vcollation" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vcollation.rst:11 +msgid "``_vcollation`` is the :ref:`system space view ` for :ref:`_collation `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vindex.pot b/locale/en/reference/reference_lua/box_space/_vindex.pot new file mode 100644 index 0000000000..e39434bf59 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vindex.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vindex.rst:5 +msgid "box.space._vindex" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vindex.rst:11 +msgid "``_vindex`` is the :ref:`system space view ` for :ref:`_index `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vpriv.pot b/locale/en/reference/reference_lua/box_space/_vpriv.pot new file mode 100644 index 0000000000..ce6b682226 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vpriv.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vpriv.rst:5 +msgid "box.space._vpriv" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vpriv.rst:11 +msgid "``_vpriv`` is the :ref:`system space view ` for :ref:`_priv `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vspace.pot b/locale/en/reference/reference_lua/box_space/_vspace.pot new file mode 100644 index 0000000000..fad91deafc --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vspace.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vspace.rst:4 +msgid "box.space._vspace" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vspace.rst:10 +msgid "``_vspace`` is the :ref:`system space view ` for :ref:`_space `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vspace_sequence.pot b/locale/en/reference/reference_lua/box_space/_vspace_sequence.pot new file mode 100644 index 0000000000..18c3372395 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vspace_sequence.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vspace_sequence.rst:4 +msgid "box.space._vspace_sequence" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vspace_sequence.rst:10 +msgid "``_vspace_sequence`` is the :ref:`system space view ` for :ref:`_space `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/_vuser.pot b/locale/en/reference/reference_lua/box_space/_vuser.pot new file mode 100644 index 0000000000..efe858dc0b --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/_vuser.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/_vuser.rst:5 +msgid "box.space._vuser" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/_vuser.rst:11 +msgid "``_vuser`` is the :ref:`system space view ` for :ref:`_user `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/alter.pot b/locale/en/reference/reference_lua/box_space/alter.pot new file mode 100644 index 0000000000..565311c862 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/alter.pot @@ -0,0 +1,65 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:5 +msgid "space_object:alter()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:11 +msgid "Since version :doc:`2.5.2 `. Alter an existing space. This method changes certain space parameters." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:14 +msgid "the space options such as ``field_count``, ``user``, ``format``, ``name``, and other. The full list of these options with descriptions parameters is provided in :doc:`/reference/reference_lua/box_schema/space_create`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:19 +msgid "nothing in case of success; an error when fails" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/alter.rst:23 +msgid "tarantool> s = box.schema.create_space('tester')\n" +"---\n" +"...\n" +"tarantool> format = {{name = 'field1', type = 'unsigned'}}\n" +"---\n" +"...\n" +"tarantool> s:alter({name = 'tester1', format = format})\n" +"---\n" +"...\n" +"tarantool> s.name\n" +"---\n" +"- tester1\n" +"...\n" +"tarantool> s:format()\n" +"---\n" +"- [{'name': 'field1', 'type': 'unsigned'}]\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/auto_increment.pot b/locale/en/reference/reference_lua/box_space/auto_increment.pot new file mode 100644 index 0000000000..3b4ca9f592 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/auto_increment.pot @@ -0,0 +1,88 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:5 +msgid "space_object:auto_increment()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:11 +msgid "Insert a new tuple using an auto-increment primary key. The space specified by space_object must have an :ref:`'unsigned' or 'integer' or 'number' ` primary key index of type ``TREE``. The primary-key field will be incremented before the insert." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:17 +msgid "Since version 1.7.5 this method is deprecated – it is better to use a :ref:`sequence `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:20 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:22 +msgid "tuple's fields, other than the primary-key field" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:25 +msgid "the inserted tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:26 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:28 +msgid "**Complexity factors:** Index size, Index type, Number of indexes accessed, :ref:`WAL settings `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:31 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:33 +msgid "index has wrong type;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:34 +msgid "primary-key indexed field is not a number." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:36 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/auto_increment.rst:38 +msgid "tarantool> box.space.tester:auto_increment{'Fld#1', 'Fld#2'}\n" +"---\n" +"- [1, 'Fld#1', 'Fld#2']\n" +"...\n" +"tarantool> box.space.tester:auto_increment{'Fld#3'}\n" +"---\n" +"- [2, 'Fld#3']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/before_replace.pot b/locale/en/reference/reference_lua/box_space/before_replace.pot new file mode 100644 index 0000000000..c3a40252d4 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/before_replace.pot @@ -0,0 +1,121 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:5 +msgid "space_object:before_replace()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:11 +msgid "Create a \"replace :ref:`trigger `\". The ``trigger-function`` will be executed whenever a ``replace()`` or ``insert()`` or ``update()`` or ``upsert()`` or ``delete()`` happens to a tuple in ````." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:16 +msgid "function which will become the trigger function; for the trigger function's optional parameters see the description of :doc:`on_replace `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:21 +msgid "existing trigger function which will be replaced by ``trigger-function``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:24 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:26 +msgid "If the parameters are ``(nil, old-trigger-function)``, then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:29 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:31 +msgid "If it is necessary to know whether the trigger activation happened due to replication or on a specific connection type, the function can refer to :doc:`/reference/reference_lua/box_session/type`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:35 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:38 +msgid "See also :doc:`/reference/reference_lua/box_space/on_replace`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:40 +msgid "Administrators can make replace triggers with ``on_replace()``, or make triggers with ``before_replace()``. If they make both types, then all ``before_replace`` triggers are executed before all ``on_replace`` triggers. The functions for both ``on_replace`` and ``before_replace`` triggers can make changes to the database, but only the functions for ``before_replace`` triggers can change the tuple that is being replaced." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:49 +msgid "Since a ``before_replace`` trigger function has the extra capability of making a change to the old tuple, it also can have extra overhead, to fetch the old tuple before making the change. Therefore an ``on_replace`` trigger is better if there is no need to change the old tuple. However, this only applies for the memtx engine -- for the vinyl engine, the fetch will happen for either kind of trigger. (With memtx the tuple data is stored along with the index key so no extra search is necessary; with vinyl that is not the case so the extra search is necessary.)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:61 +msgid "Where the extra capability is not needed, ``on_replace`` should be used instead of ``before_replace``. Usually ``before_replace`` is used only for certain replication scenarios -- it is useful for conflict resolution." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:66 +msgid "The value that a ``before_replace`` trigger function can return affects what will happen after the return. Specifically:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:69 +msgid "if there is no return value, then execution proceeds, inserting|replacing the new value;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:71 +msgid "if the value is nil, then the tuple will be deleted;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:72 +msgid "if the value is the same as the old parameter, then no ``on_replace`` function will be called and the data change will be skipped. The return value will be absent." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:76 +msgid "if the value is the same as the new parameter, then it's as if the ``before_replace`` function wasn't called;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:78 +msgid "if the value is some other tuple, then it is used for insert/replace." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:80 +msgid "However, if a trigger function returns an old tuple, or if a trigger function calls :doc:`run_triggers(false) `, that will not affect other triggers that are activated for the same insert | update | replace request." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:86 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:88 +msgid "The following are ``before_replace`` functions that have no return value, or that return nil, or the same as the old parameter, or the same as the new parameter, or something else." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/before_replace.rst:92 +msgid "function f1 (old, new) return end\n" +"function f2 (old, new) return nil end\n" +"function f3 (old, new) return old end\n" +"function f4 (old, new) return new end\n" +"function f5 (old, new) return box.tuple.new({new[1],'b'}) end" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/bsize.pot b/locale/en/reference/reference_lua/box_space/bsize.pot new file mode 100644 index 0000000000..e063bd71be --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/bsize.pot @@ -0,0 +1,48 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:5 +msgid "space_object:bsize()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:11 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:14 +msgid "Number of bytes in the space. This number, which is stored in Tarantool's internal memory, represents the total number of bytes in all tuples, not including index keys. For a measure of index size, see :doc:`/reference/reference_lua/box_index/bsize`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:20 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/bsize.rst:22 +msgid "tarantool> box.space.tester:bsize()\n" +"---\n" +"- 22\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/count.pot b/locale/en/reference/reference_lua/box_space/count.pot new file mode 100644 index 0000000000..d7fc82b34e --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/count.pot @@ -0,0 +1,68 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/count.rst:5 +msgid "space_object:count()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:11 +msgid "Return the number of tuples. If compared with :doc:`len() `, this method works slower because ``count()`` scans the entire space to count the tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:16 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:18 +msgid "primary-key field values, must be passed as a Lua table if key is multi-part" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:20 +msgid "comparison method" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:22 +msgid "Number of tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:24 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:26 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:29 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/count.rst:31 +msgid "tarantool> box.space.tester:count(2, {iterator='GE'})\n" +"---\n" +"- 1\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/create_check_constraint.pot b/locale/en/reference/reference_lua/box_space/create_check_constraint.pot new file mode 100644 index 0000000000..fe42066042 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/create_check_constraint.pot @@ -0,0 +1,112 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:5 +msgid "box.space.create_check_constraint()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:9 +msgid "This function was removed in :doc:`2.11.0 `. The check constraint mechanism is replaced with the new tuple constraints. Learn more about tuple constraints in :ref:`Constraints `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:18 +msgid "Create a check constraint. A check constraint is a requirement that must be met when a tuple is inserted or updated in a space. Check constraints created with ``space_object:create_check_constraint`` have the same effect as check constraints created with an SQL CHECK() clause in a :ref:`CREATE TABLE statement `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:25 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:27 +msgid "name of check constraint, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:29 +msgid "SQL code of an expression which must return a boolean result" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:31 +msgid "check constraint object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:32 +msgid "check_constraint_object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:34 +msgid "The space must be formatted with :doc:`/reference/reference_lua/box_space/format` so that the expression can contain field names. The space must be empty. The space must not be a system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:38 +msgid "The expression must return true or false and should be deterministic. The expression may be any SQL (not Lua) expression containing field names, built-in function names, literals, and operators. Not subqueries. If a field name contains lower case characters, it must be enclosed in \"double quotes\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:43 +msgid "Check constraints are checked before the request is performed, at the same time as Lua :doc:`before_replace triggers `. If there is more than one check constraint or before_replace trigger, then they are ordered according to time of creation. (This is a change from the earlier behavior of check constraints, which caused checking before the tuple was formed.)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:51 +msgid "Check constraints can be dropped with :samp:`{space_object}.ck_constraint.{check_constraint_name}:drop()`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:53 +msgid "Check constraints can be disabled with :samp:`{space_object}.ck_constraint.{check_constraint_name}:enable(false)` or :samp:`{check_constraint_object}:enable(false)`. Check constraints can be enabled with :samp:`{space_object}.ck_constraint.{check_constraint_name}:enable(true)` or :samp:`{check_constraint_object}:enable(true)`. By default a check constraint is 'enabled' which means that the check is performed whenever the request is performed, but can be changed to 'disabled' which means that the check is not performed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:61 +msgid "During the recovery process, for example when the Tarantool server is starting, the check is not performed unless :ref:`force_recovery ` is specified." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:66 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:68 +msgid "box.schema.space.create('t')\n" +"box.space.t:format({{name = 'f1', type = 'unsigned'},\n" +" {name = 'f2', type = 'string'},\n" +" {name = 'f3', type = 'string'}})\n" +"box.space.t:create_index('i')\n" +"box.space.t:create_check_constraint('c1', [[\"f2\" > 'A']])\n" +"box.space.t:create_check_constraint('c2',\n" +" [[\"f2\"=UPPER(\"f3\") AND NOT \"f2\" LIKE '__']])\n" +"-- This insert will fail, constraint c1 expression returns false\n" +"box.space.t:insert{1, 'A', 'A'}\n" +"-- This insert will fail, constraint c2 expression returns false\n" +"box.space.t:insert{1, 'B', 'c'}\n" +"-- This insert will succeed, both constraint expressions return true\n" +"box.space.t:insert{1, 'B', 'b'}\n" +"-- This update will fail, constraint c2 expression returns false\n" +"box.space.t:update(1, {{'=', 2, 'xx'}, {'=', 3, 'xx'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_check_constraint.rst:87 +msgid "A list of check constraints is in :doc:`/reference/reference_lua/box_space/_ck_constraint`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/create_index.pot b/locale/en/reference/reference_lua/box_space/create_index.pot new file mode 100644 index 0000000000..5f68ed4b0a --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/create_index.pot @@ -0,0 +1,816 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:4 +msgid "space_object:create_index()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:11 +msgid "Create an :ref:`index `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:13 +msgid "It is mandatory to create an index for a space before trying to insert 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." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:17 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:19 +msgid "name of index, which should conform to the :ref:`rules for object names `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:21 +msgid "index options (see :ref:`index_opts `)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:23 +msgid "index object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:24 +msgid "index_object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:26 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:28 +msgid "too many parts" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:29 +msgid "index '...' already exists" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:30 +msgid "primary key must be unique" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:32 +msgid "Building or rebuilding a large index will cause occasional :ref:`yields ` so that other requests will not be blocked. If the other requests cause an illegal situation such as a duplicate key in a unique index, building or rebuilding such index will fail." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:39 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:94 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:121 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:323 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:352 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:586 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:663 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:41 +msgid "-- Create a space --\n" +"bands = box.schema.space.create('bands')\n" +"\n" +"-- Specify field names and types --\n" +"box.space.bands:format({\n" +" { name = 'id', type = 'unsigned' },\n" +" { name = 'band_name', type = 'string' },\n" +" { name = 'year', type = 'unsigned' }\n" +"})\n" +"\n" +"-- Create a primary index --\n" +"box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"\n" +"-- Create a unique secondary index --\n" +"box.space.bands:create_index('band', { parts = { 'band_name' } })\n" +"\n" +"-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })\n" +"\n" +"-- Create a multi-part index --\n" +"box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:51 +msgid "index_opts" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:56 +msgid "Index options that include the index name, type, identifiers of key fields, and so on. These options are passed to the :ref:`space_object.create_index() ` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:61 +msgid "These options are also passed to :doc:`/reference/reference_lua/box_index/alter`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:67 +msgid "The :ref:`index type `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:69 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:172 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:193 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:307 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:320 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:396 +msgid "Type: string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:70 +msgid "Default: ``TREE``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:71 +msgid "Possible values: ``TREE``, ``HASH``, ``RTREE``, ``BITSET``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:78 +msgid "A unique numeric identifier of the index, which is generated automatically." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:80 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:162 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:219 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:231 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:243 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:255 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:267 +msgid "Type: number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:81 +msgid "Default: last index's ID + 1" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:88 +msgid "Specify whether an index may be unique. When ``true``, the index cannot contain the same key value twice." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:91 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:108 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:207 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:348 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:385 +msgid "Type: boolean" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:92 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:208 +msgid "Default: ``true``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:96 +msgid "-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:106 +msgid "Specify whether to swallow an error on an attempt to create an index with a duplicated name." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:109 +msgid "Default: ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:116 +msgid "Specify the index's key parts." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:118 +msgid "Type: a table of :ref:`key_part ` values" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:119 +msgid "Default: ``{1, ‘unsigned’}``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:123 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:442 +msgid "-- Create a primary index --\n" +"box.space.bands:create_index('primary', { parts = { 'id' } })\n" +"\n" +"-- Create a unique secondary index --\n" +"box.space.bands:create_index('band', { parts = { 'band_name' } })\n" +"\n" +"-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })\n" +"\n" +"-- Create a multi-part index --\n" +"box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:132 +msgid "**Alternative way to declare index parts**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:134 +msgid "Before version :doc:`2.7.1 `, if an index consisted of a single part and had some options like ``is_nullable`` or ``collation`` and its definition was written as" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:138 +msgid "my_space:create_index('one_part_idx', {parts = {1, 'unsigned', is_nullable=true}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:142 +msgid "(with the only brackets) then options were ignored by Tarantool." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:144 +msgid "Since version :doc:`2.7.1 ` it is allowed to omit extra braces in an index definition and use both ways:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:147 +msgid "-- with extra braces\n" +"my_space:create_index('one_part_idx', {parts = {{1, 'unsigned', is_nullable=true}}})\n" +"\n" +"-- without extra braces\n" +"my_space:create_index('one_part_idx', {parts = {1, 'unsigned', is_nullable=true}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:160 +msgid "The RTREE index dimension." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:163 +msgid "Default: 2" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:170 +msgid "The RTREE index distance type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:173 +msgid "Default: ``euclid``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:174 +msgid "Possible values: ``euclid``, ``manhattan``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:181 +msgid "Create a generator for indexes using a sequence object. Learn more from :ref:`specifying a sequence in create_index() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:184 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:294 +msgid "Type: string or number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:191 +msgid "Specify the identifier of the :ref:`functional index ` function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:200 +msgid "**Since:** :doc:`2.6.1 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:202 +msgid "Specify whether hint optimization is enabled for the TREE index:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:204 +msgid "If ``true``, the index works faster." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:205 +msgid "If ``false``, the index size is reduced by half." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:215 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:227 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:239 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:251 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:263 +msgid "**Vinyl only**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:217 +msgid "Specify the bloom filter's false positive rate." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:220 +msgid "Default: :ref:`vinyl_bloom_fpr `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:229 +msgid "Specify the size of a page used for read and write disk operations." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:232 +msgid "Default: :ref:`vinyl_page_size `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:241 +msgid "Specify the default maximum range size (in bytes) for a vinyl index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:244 +msgid "Default: :ref:`vinyl_range_size `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:253 +msgid "Specify the maximum number of runs per level in the LSM tree." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:256 +msgid "Default: :ref:`vinyl_run_count_per_level `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:265 +msgid "Specify the ratio between the sizes of different levels in the LSM tree." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:268 +msgid "Default: :ref:`vinyl_run_size_ratio `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:277 +msgid "key_part" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:281 +msgid "A descriptor of a single part in a multipart key. A table of parts is passed to the :ref:`index_opts.parts ` option." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:288 +msgid "Specify the field number or name." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:292 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:440 +msgid "To create a key part by a field name, you need to specify :ref:`space_object:format() ` first." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:296 +msgid "**Examples:** :ref:`Creating an index using field names and numbers `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:303 +msgid "Specify the field type. If the field type is specified in :ref:`space_object:format() `, ``key_part.type`` inherits this value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:308 +msgid "Default: ``scalar``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:309 +msgid "Possible values: listed in :ref:`Indexed field types `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:316 +msgid "Specify the :ref:`collation ` used to compare field values. If the field collation is specified in :ref:`space_object:format() `, ``key_part.collation`` inherits this value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:321 +msgid "Possible values: listed in the :ref:`box.space._collation ` system space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:325 +msgid "-- Create a space --\n" +"box.schema.space.create('tester')\n" +"\n" +"-- Use the 'unicode' collation --\n" +"box.space.tester:create_index('unicode', { parts = { { field = 1,\n" +" type = 'string',\n" +" collation = 'unicode' } } })\n" +"\n" +"-- Use the 'unicode_ci' collation --\n" +"box.space.tester:create_index('unicode_ci', { parts = { { field = 1,\n" +" type = 'string',\n" +" collation = 'unicode_ci' } } })\n" +"\n" +"-- Insert test data --\n" +"box.space.tester:insert { 'ЕЛЕ' }\n" +"box.space.tester:insert { 'елейный' }\n" +"box.space.tester:insert { 'ёлка' }\n" +"\n" +"-- Returns nil --\n" +"select_unicode = box.space.tester.index.unicode:select({ 'ЁлКа' })\n" +"-- Returns 'ёлка' --\n" +"select_unicode_ci = box.space.tester.index.unicode_ci:select({ 'ЁлКа' })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:334 +msgid "Specify whether ``nil`` (or its equivalent such as ``msgpack.NULL``) can be used as a field value. If the ``is_nullable`` option is specified in :ref:`space_object:format() `, ``key_part.is_nullable`` inherits this value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:338 +msgid "You can set this option to ``true`` if:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:340 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:376 +msgid "the index type is TREE" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:341 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:377 +msgid "the index is not the primary index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:343 +msgid "It is also legal to insert nothing at all when using trailing nullable fields. Within indexes, such null values are always treated as equal to other null values and are always treated as less than non-null values. Nulls may appear multiple times even in a unique index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:349 +#: ../../doc/reference/reference_lua/box_space/create_index.rst:386 +msgid "Default: false" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:354 +msgid "box.space.tester:create_index('I', {unique = true, parts = {{field = 2, type = 'number', is_nullable = true}}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:360 +msgid "It is legal to create multiple indexes for the same field with different ``is_nullable`` values or to call :doc:`/reference/reference_lua/box_space/format` with a different ``is_nullable`` value from what is used for an index. When there is a contradiction, the rule is: null is illegal unless ``is_nullable=true`` for every index and for the space format." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:371 +msgid "**Since:** :doc:`2.8.2 `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:373 +msgid "Specify whether an index can skip tuples with null at this key part. You can set this option to ``true`` if:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:379 +msgid "If ``exclude_null`` is set to ``true``, ``is_nullable`` is set to ``true`` automatically. Note that this option can be changed dynamically. In this case, the index is rebuilt." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:383 +msgid "Such indexes do not store filtered tuples at all, so indexing can be done faster." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:394 +msgid "Specify the path string for a map field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:398 +msgid "See the examples below:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:400 +msgid ":ref:`Creating an index using the path option for map fields `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:401 +msgid ":ref:`Creating a multikey index using the path option with [*] `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:427 +msgid "Examples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:432 +msgid "Creating an index using field names and numbers" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:435 +msgid "``create_index()`` can use field names or field numbers to define key parts." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:438 +msgid "**Example 1 (field names):**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:447 +msgid "**Example 2 (field numbers):**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:449 +msgid "-- Create a primary index --\n" +"box.space.bands:create_index('primary', { parts = { 1 } })\n" +"\n" +"-- Create a unique secondary index --\n" +"box.space.bands:create_index('band', { parts = { 2 } })\n" +"\n" +"-- Create a non-unique secondary index --\n" +"box.space.bands:create_index('year', { parts = { { 3 } }, unique = false })\n" +"\n" +"-- Create a multi-part index --\n" +"box.space.bands:create_index('year_band', { parts = { 3, 2 } })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:459 +msgid "Creating an index using the path option for map fields (JSON-path indexes)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:461 +msgid "To create an index for a field that is a map (a path string and a scalar value), specify the path string during index creation, like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:512 +msgid ":extsamp:`parts = {{*{field-number}*}, {*{'data-type'}*}, path = {*{'path-name'}*}}`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:469 +msgid "The index type must be TREE or HASH and the contents of the field must always be maps with the same path." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:472 +msgid "**Example 1 -- The simplest use of path:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:474 +msgid "box.schema.space.create('space1')\n" +"box.space.space1:create_index('primary', { parts = { { field = 1,\n" +" type = 'scalar',\n" +" path = 'age' } } })\n" +"box.space.space1:insert({ { age = 44 } })\n" +"box.space.space1:select(44)\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:479 +msgid "**Example 2 -- path plus format() plus JSON syntax to add clarity:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:481 +msgid "box.schema.space.create('space2')\n" +"box.space.space2:format({ { 'id', 'unsigned' }, { 'data', 'map' } })\n" +"box.space.space2:create_index('info', { parts = { { 'data.full_name[\"firstname\"]', 'str' },\n" +" { 'data.full_name[\"surname\"]', 'str' } } })\n" +"box.space.space2:insert({ 1, { full_name = { firstname = 'John', surname = 'Doe' } } })\n" +"box.space.space2:select { 'John' }\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:491 +msgid "Creating a multikey index using the path option with [*]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:493 +msgid "The string in a path option can contain ``[*]`` which is called **an array index placeholder**. Indexes defined with this are useful for JSON documents that all have the same structure." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:497 +msgid "For example, when creating an index on field#2 for a string document that will start with ``{'data': [{'name': '...'}, {'name': '...'}]``, the parts section in the ``create_index`` request could look like:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:501 +msgid "parts = {{field = 2, type = 'str', path = 'data[*].name'}}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:505 +msgid "Then tuples containing names can be retrieved quickly with ``index_object:select({key-value})``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:508 +msgid "A single field can have multiple keys, as in this example which retrieves the same tuple twice because there are two keys 'A' and 'B' which both match the request:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:512 +msgid "my_space = box.schema.space.create('json_documents')\n" +"my_space:create_index('primary')\n" +"multikey_index = my_space:create_index('multikey', {parts = {{field = 2, type = 'str', path = 'data[*].name'}}})\n" +"my_space:insert({1,\n" +" {data = {{name = 'A'},\n" +" {name = 'B'}},\n" +" extra_field = 1}})\n" +"multikey_index:select({''}, {iterator = 'GE'})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:523 +msgid "The result of the select request looks like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:525 +msgid "tarantool> multikey_index:select({''},{iterator='GE'})\n" +"---\n" +"- - [1, {'data': [{'name': 'A'}, {'name': 'B'}], 'extra_field': 1}]\n" +"- [1, {'data': [{'name': 'A'}, {'name': 'B'}], 'extra_field': 1}]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:533 +msgid "The following restrictions exist:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:535 +msgid "``[*]`` must be alone or must be at the end of a name in the path." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:536 +msgid "``[*]`` must not appear twice in the path." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:537 +msgid "If an index has a path with ``x[*]``, then no other index can have a path with x.component." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:539 +msgid "``[*]`` must not appear in the path of a primary key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:540 +msgid "If an index has ``unique=true`` and has a path with ``[*]``, then duplicate keys from different tuples are disallowed, but duplicate keys for the same tuple are allowed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:543 +msgid "The field's value must have the same structure as in the path definition, or be nil (nil is not indexed)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:545 +msgid "In a space with multikey indexes, any tuple cannot contain :ref:`more than ~8,000 elements ` indexed that way." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:551 +msgid "Creating a functional index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:553 +msgid "Functional indexes are indexes that call a user-defined function for forming the index key, rather than depending entirely on the Tarantool default formation. Functional indexes are useful for condensing or truncating or reversing or any other way that users want to customize the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:558 +msgid "There are several recommendations for building functional indexes:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:560 +msgid "The function definition must expect a tuple, which has the contents of fields at the time a data-change request happens, and must return a tuple, which has the contents that will be put in the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:564 +msgid "The ``create_index`` definition must include the specification of all key parts, and the custom function must return a table that has the same number of key parts with the same types." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:568 +msgid "The space must have a memtx engine." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:570 +msgid "The function must be persistent and deterministic (see :ref:`Creating a function with body `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:573 +msgid "The key parts must not depend on JSON paths." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:575 +msgid "The function must access key-part values by index, not by field name." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:577 +msgid "Functional indexes must not be primary-key indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:579 +msgid "Functional indexes cannot be altered and the function cannot be changed if it is used for an index, so the only way to change them is to drop the index and create it again." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:583 +msgid "Only :ref:`sandboxed ` functions are suitable for functional indexes." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:588 +msgid "A function could make a key using only the first letter of a string field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:590 +msgid "Create a space. The space needs a primary-key field, which is not the field that we will use for the functional index:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:593 +msgid "box.schema.space.create('tester')\n" +"box.space.tester:create_index('i', { parts = { { field = 1, type = 'string' } } })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:599 +msgid "Create a function. The function expects a tuple. In this example, it will work on tuple[2] because the key source is field number 2 in what we will insert. Use ``string.sub()`` from the ``string`` module to get the first character:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:603 +msgid "function_code = [[function(tuple) return {string.sub(tuple[2],1,1)} end]]\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:608 +msgid "Make the function persistent using the ``box.schema.func.create`` function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:610 +msgid "box.schema.func.create('my_func',\n" +" { body = function_code, is_deterministic = true, is_sandboxed = true })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:615 +msgid "Create a functional index. Specify the fields whose values will be passed to the function. Specify the function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:618 +msgid "box.space.tester:create_index('func_index', { parts = { { field = 1, type = 'string' } },\n" +" func = 'my_func' })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:623 +msgid "Insert a few tuples. Select using only the first letter, it will work because that is the key. Or, select using the same function as was used for insertion:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:627 +msgid "box.space.tester:insert({ 'a', 'wombat' })\n" +"box.space.tester:insert({ 'b', 'rabbit' })\n" +"box.space.tester.index.func_index:select('w')\n" +"box.space.tester.index.func_index:select(box.func.my_func:call({ { 'tester', 'wombat' } }))\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:633 +msgid "The results of the two ``select`` requests will look like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:635 +msgid "tarantool> box.space.tester.index.func_index:select('w')\n" +"---\n" +"- - ['a', 'wombat']\n" +"...\n" +"tarantool> box.space.tester.index.func_index:select(box.func.my_func:call({{'tester','wombat'}}));\n" +"---\n" +"- - ['a', 'wombat']\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:646 +msgid "Here is the full code of the example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:648 +msgid "box.schema.space.create('tester')\n" +"box.space.tester:create_index('i', { parts = { { field = 1, type = 'string' } } })\n" +"function_code = [[function(tuple) return {string.sub(tuple[2],1,1)} end]]\n" +"box.schema.func.create('my_func',\n" +" { body = function_code, is_deterministic = true, is_sandboxed = true })\n" +"box.space.tester:create_index('func_index', { parts = { { field = 1, type = 'string' } },\n" +" func = 'my_func' })\n" +"box.space.tester:insert({ 'a', 'wombat' })\n" +"box.space.tester:insert({ 'b', 'rabbit' })\n" +"box.space.tester.index.func_index:select('w')\n" +"box.space.tester.index.func_index:select(box.func.my_func:call({ { 'tester', 'wombat' } }))\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:656 +msgid "Functions for functional indexes can return **multiple keys**. Such functions are called \"multikey\" functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:659 +msgid "To create a multikey function, the options of ``box.schema.func.create()`` must include ``is_multikey = true``. The return value must be a table of tuples. If a multikey function returns N tuples, then N keys will be added to the index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/create_index.rst:665 +msgid "tester = box.schema.space.create('withdata')\n" +"tester:format({ { name = 'name', type = 'string' },\n" +" { name = 'address', type = 'string' } })\n" +"name_index = tester:create_index('name', { parts = { { field = 1, type = 'string' } } })\n" +"function_code = [[function(tuple)\n" +" local address = string.split(tuple[2])\n" +" local ret = {}\n" +" for _, v in pairs(address) do\n" +" table.insert(ret, {utf8.upper(v)})\n" +" end\n" +" return ret\n" +" end]]\n" +"box.schema.func.create('address',\n" +" { body = function_code,\n" +" is_deterministic = true,\n" +" is_sandboxed = true,\n" +" is_multikey = true })\n" +"addr_index = tester:create_index('addr', { unique = false,\n" +" func = 'address',\n" +" parts = { { field = 1, type = 'string',\n" +" collation = 'unicode_ci' } } })\n" +"tester:insert({ \"James\", \"SIS Building Lambeth London UK\" })\n" +"tester:insert({ \"Sherlock\", \"221B Baker St Marylebone London NW1 6XE UK\" })\n" +"addr_index:select('Uk')\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/delete.pot b/locale/en/reference/reference_lua/box_space/delete.pot new file mode 100644 index 0000000000..7a98df0b4b --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/delete.pot @@ -0,0 +1,92 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:5 +msgid "space_object:delete()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:11 +msgid "Delete a tuple identified by the primary key." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:13 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:15 +msgid "primary-key field values, must be passed as a Lua table if key is multi-part" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:18 +msgid "the deleted tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:19 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:21 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:23 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:26 +msgid "**Complexity factors:** Index size, Index type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:28 +msgid "**Note regarding storage engine:** vinyl will return ``nil``, rather than the deleted tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:31 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:33 +msgid "tarantool> box.space.tester:delete(1)\n" +"---\n" +"- [1, 'My first tuple']\n" +"...\n" +"tarantool> box.space.tester:delete(1)\n" +"---\n" +"...\n" +"tarantool> box.space.tester:delete('a')\n" +"---\n" +"- error: 'Supplied key type of part 0 does not match index part type:\n" +" expected unsigned'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/delete.rst:48 +msgid "For more usage scenarios and typical errors see :ref:`Example: using data operations ` further in this section." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/drop.pot b/locale/en/reference/reference_lua/box_space/drop.pot new file mode 100644 index 0000000000..3668409327 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/drop.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:5 +msgid "space_object:drop()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:11 +msgid "Drop a space. The method is performed in background and doesn't block consequent requests." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:14 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:17 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:19 +msgid "**Possible errors:** ``space_object`` does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:21 +msgid "**Complexity factors:** Index size, Index type, Number of indexes accessed, WAL settings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:24 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/drop.rst:26 +msgid "box.space.space_that_does_not_exist:drop()" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/enabled.pot b/locale/en/reference/reference_lua/box_space/enabled.pot new file mode 100644 index 0000000000..93aecb2188 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/enabled.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/enabled.rst:5 +msgid "space_object:enabled" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/enabled.rst:11 +msgid "Whether or not this space is enabled. The value is ``false`` if the space has no index." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/field_count.pot b/locale/en/reference/reference_lua/box_space/field_count.pot new file mode 100644 index 0000000000..d952fbe3cd --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/field_count.pot @@ -0,0 +1,48 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:5 +msgid "space_object:field_count" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:11 +msgid "The required field count for all tuples in this space. The field_count can be set initially with:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:14 +msgid "box.schema.space.create(..., {\n" +" ... ,\n" +" field_count = *field_count_value* ,\n" +" ...\n" +"})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:22 +msgid "The default value is ``0``, which means there is no required field count." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:24 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/field_count.rst:26 +msgid "tarantool> box.space.tester.field_count\n" +"---\n" +"- 0\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/format.pot b/locale/en/reference/reference_lua/box_space/format.pot new file mode 100644 index 0000000000..665be6ab90 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/format.pot @@ -0,0 +1,282 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/format.rst:5 +msgid "space_object:format()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:11 +msgid "Declare field names and :ref:`types `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:13 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:15 +msgid "a list of field names and types" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:17 +msgid "``nil``, unless format-clause is omitted" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:19 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:21 +msgid "``space_object`` does not exist" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:22 +msgid "field names are duplicated" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:23 +msgid "type is not legal" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:27 +msgid "If you need to make a schema migration, see section :ref:`Migrations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:29 +msgid "Ordinarily Tarantool allows unnamed untyped fields. But with ``format`` users can, for example, document that the Nth field is the surname field and must contain strings. It is also possible to specify a format clause in :doc:`box.schema.space.create() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:35 +msgid "The format clause contains, for each field, a definition within braces: ``{name='...',type='...'[,is_nullable=...]}``, where:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:38 +msgid "The ``name`` value may be any string, provided that two fields do not have the same name." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:40 +msgid "The ``type`` value may be any of allowed types: any | unsigned | string | integer | number | varbinary | boolean | double | decimal | uuid | array | map | scalar, but for creating an index use only :ref:`indexed fields `;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:44 +msgid "(Optional) The ``is_nullable`` boolean value specifies whether ``nil`` can be used as a field value. See also: :ref:`key_part.is_nullable `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:46 +msgid "(Optional) The ``collation`` string value specifies the :ref:`collation ` used to compare field values. See also: :ref:`key_part.collation `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:48 +msgid "(Optional) The ``constraint`` table specifies the :ref:`constraints ` that the field value must satisfy." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:49 +msgid "(Optional) The ``foreign_key`` table specifies the :ref:`foreign keys ` for the field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:51 +msgid "It is not legal for tuples to contain values that have the wrong type. The example below will cause an error:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:54 +msgid "--This example will cause an error.\n" +"box.space.tester:format({{' ',type='number'}})\n" +"box.space.tester:insert{'string-which-is-not-a-number'}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:60 +msgid "It is not legal for tuples to contain null values if ``is_nullable=false``, which is the default. The example below will cause an error:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:63 +msgid "--This example will cause an error.\n" +"box.space.tester:format({{' ',type='number',is_nullable=false}})\n" +"box.space.tester:insert{nil,2}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:70 +msgid "It is legal for tuples to have more fields than are described by a format clause. The way to constrain the number of fields is to specify a space's :doc:`field_count ` member." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:74 +msgid "It is legal for tuples to have fewer fields than are described by a format clause, if the omitted trailing fields are described with ``is_nullable=true``. For example, the request below will not cause a format-related error:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:78 +msgid "box.space.tester:format({{'a',type='number'},{'b',type='number',is_nullable=true}})\n" +"box.space.tester:insert{2}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:84 +msgid "It is legal to use ``format`` on a space that already has a format, thus replacing any previous definitions, provided that there is no conflict with existing data or index definitions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:88 +msgid "It is legal to use ``format`` to change the ``is_nullable`` flag. The example below will not cause an error -- and will not cause rebuilding of the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:92 +msgid "box.space.tester:format({{' ',type='scalar',is_nullable=false}})\n" +"box.space.tester:format({{' ',type='scalar',is_nullable=true}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:97 +msgid "But going the other way and changing ``is_nullable`` from ``true`` to ``false`` might cause rebuilding and might cause an error if there are existing tuples with nulls." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:102 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:104 +msgid "box.space.tester:format({{name='surname',type='string'},{name='IDX',type='array'}})\n" +"box.space.tester:format({{name='surname',type='string',is_nullable=true}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:110 +msgid "There are legal variations of the format clause:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:112 +msgid "omitting both 'name=' and 'type='," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:113 +msgid "omitting 'type=' alone," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:114 +msgid "adding extra braces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:116 +msgid "The following examples show all the variations, first for one field named 'x', second for two fields named 'x' and 'y'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:119 +msgid "box.space.tester:format({{name='x',type='scalar'}})\n" +"box.space.tester:format({{name='x',type='scalar'},{name='y',type='unsigned'}})\n" +"\n" +"box.space.tester:format({{'x'}})\n" +"box.space.tester:format({{'x'},{'y'}})\n" +"\n" +"-- types\n" +"box.space.tester:format({{name='x'}})\n" +"box.space.tester:format({{name='x'},{name='y'}})\n" +"\n" +"box.space.tester:format({{'x',type='scalar'}})\n" +"box.space.tester:format({{'x',type='scalar'},{'y',type='unsigned'}})\n" +"\n" +"box.space.tester:format({{'x','scalar'}})\n" +"box.space.tester:format({{'x','scalar'},{'y','unsigned'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:137 +msgid "The following example shows how to create a space, format it with all possible types, and insert into it." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:140 +msgid "tarantool> box.schema.space.create('t')\n" +"---\n" +"- engine: memtx\n" +" before_replace: 'function: 0x4019c488'\n" +" on_replace: 'function: 0x4019c460'\n" +" ck_constraint: []\n" +" field_count: 0\n" +" temporary: false\n" +" index: []\n" +" is_local: false\n" +" enabled: false\n" +" name: t\n" +" id: 534\n" +"- created\n" +"...\n" +"tarantool> ffi = require('ffi')\n" +"---\n" +"...\n" +"tarantool> decimal = require('decimal')\n" +"---\n" +"...\n" +"tarantool> uuid = require('uuid')\n" +"---\n" +"...\n" +"tarantool> box.space.t:format({{name = '1', type = 'any'},\n" +" > {name = '2', type = 'unsigned'},\n" +" > {name = '3', type = 'string'},\n" +" > {name = '4', type = 'number'},\n" +" > {name = '5', type = 'double'},\n" +" > {name = '6', type = 'integer'},\n" +" > {name = '7', type = 'boolean'},\n" +" > {name = '8', type = 'decimal'},\n" +" > {name = '9', type = 'uuid'},\n" +" > {name = 'a', type = 'scalar'},\n" +" > {name = 'b', type = 'array'},\n" +" > {name = 'c', type = 'map'}})\n" +"---\n" +"...\n" +"tarantool> box.space.t:create_index('i',{parts={2, type = 'unsigned'}})\n" +"---\n" +"- unique: true\n" +" parts:\n" +" - type: unsigned\n" +" is_nullable: false\n" +" fieldno: 2\n" +" id: 0\n" +" space_id: 534\n" +" type: TREE\n" +" name: i\n" +"...\n" +"tarantool> box.space.t:insert{{'a'}, -- any\n" +" > 1, -- unsigned\n" +" > 'W?', -- string\n" +" > 5.5, -- number\n" +" > ffi.cast('double', 1), -- double\n" +" > -0, -- integer\n" +" > true, -- boolean\n" +" > decimal.new(1.2), -- decimal\n" +" > uuid.new(), -- uuid\n" +" > true, -- scalar\n" +" > {{'a'}}, -- array\n" +" > {val=1}} -- map\n" +"---\n" +"- [['a'], 1, 'W?', 5.5, 1, 0, true, 1.2, 1f41e7b8-3191-483d-b46e-1aa6a4b14557, true, [['a']], {'val': 1}]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:208 +msgid "Names specified with the format clause can be used in :doc:`/reference/reference_lua/box_space/get` and in :doc:`/reference/reference_lua/box_space/create_index` and in :doc:`/reference/reference_lua/box_tuple/field_name` and in :doc:`/reference/reference_lua/box_tuple/field_path`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:214 +msgid "If the format clause is omitted, then the returned value is the table that was used in a previous :samp:`{space_object}:format({format-clause})` invocation. For example, after ``box.space.tester:format({{'x','scalar'}})``, ``box.space.tester:format()`` will return ``[{'name': 'x', 'type': 'scalar'}]``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:219 +msgid "Formatting or reformatting a large space will cause occasional :ref:`yields ` so that other requests will not be blocked. If the other requests cause an illegal situation such as a field value of the wrong type, the formatting or reformatting will fail." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/format.rst:226 +msgid "**Note regarding storage engine:** vinyl supports formatting of non-empty spaces. Primary index definition cannot be formatted." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/frommap.pot b/locale/en/reference/reference_lua/box_space/frommap.pot new file mode 100644 index 0000000000..5a23331cce --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/frommap.pot @@ -0,0 +1,87 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:5 +msgid "space_object:frommap()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:11 +msgid "Convert a map to a tuple instance or to a table. The map must consist of \"field name = value\" pairs. The field names and the value types must match names and types stated previously for the space, via :doc:`/reference/reference_lua/box_space/format`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:17 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:19 +msgid "a series of \"field = value\" pairs, in any order." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:20 +msgid "the only legal option is ``{table = true|false}``; |br| if the option is omitted or if ``{table = false}``, then return type will be 'cdata' (i.e. tuple); |br| if ``{table = true}``, then return type will be 'table'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:25 +msgid "a tuple instance or table." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:26 +msgid "tuple or table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:28 +msgid "**Possible errors:** ``space_object`` does not exist or has no format; \"unknown field\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:30 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/frommap.rst:32 +msgid "-- Create a format with two fields named 'a' and 'b'.\n" +"-- Create a space with that format.\n" +"-- Create a tuple based on a map consistent with that space.\n" +"-- Create a table based on a map consistent with that space.\n" +"tarantool> format1 = {{name='a',type='unsigned'},{name='b',type='scalar'}}\n" +"---\n" +"...\n" +"tarantool> s = box.schema.create_space('test', {format = format1})\n" +"---\n" +"...\n" +"tarantool> s:frommap({b = 'x', a = 123456})\n" +"---\n" +"- [123456, 'x']\n" +"...\n" +"tarantool> s:frommap({b = 'x', a = 123456}, {table = true})\n" +"---\n" +"- - 123456\n" +" - x\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/get.pot b/locale/en/reference/reference_lua/box_space/get.pot new file mode 100644 index 0000000000..ca2cf817a5 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/get.pot @@ -0,0 +1,103 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/get.rst:5 +msgid "space_object:get()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:11 +msgid "Search for a tuple in the given space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:13 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:15 +msgid "value to be matched against the index key, which may be multi-part." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:18 +msgid "the tuple whose index key matches ``key``, or ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:19 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:21 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:23 +msgid "``space_object`` does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:24 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:27 +msgid "**Complexity factors:** Index size, Index type, Number of indexes accessed, WAL settings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:30 +msgid "The ``box.space...select`` function returns a set of tuples as a Lua table; the ``box.space...get`` function returns at most a single tuple. And it is possible to get the first tuple in a space by appending ``[1]``. Therefore ``box.space.tester:get{1}`` has the same effect as ``box.space.tester:select{1}[1]``, if exactly one tuple is found." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:36 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:38 +msgid "box.space.tester:get{1}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:44 +msgid "**Using field names instead of field numbers:** `get()` can use field names described by the optional :doc:`/reference/reference_lua/box_space/format` clause. This is true because the object returned by ``get()`` can be used with most of the features described in the :doc:`/reference/reference_lua/box_tuple` description, including :doc:`/reference/reference_lua/box_tuple/field_name`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:50 +msgid "For example, we can format the `tester` space with a field named `x` and use the name `x` in the index definition:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:53 +msgid "box.space.tester:format({{name='x',type='scalar'}})\n" +"box.space.tester:create_index('I',{parts={'x'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:58 +msgid "Then, if ``get`` or ``select`` retrieves a single tuple, we can reference the field 'x' in the tuple by its name:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/get.rst:61 +msgid "box.space.tester:get{1}['x']\n" +"box.space.tester:select{1}[1]['x']" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/id.pot b/locale/en/reference/reference_lua/box_space/id.pot new file mode 100644 index 0000000000..da4a89258e --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/id.pot @@ -0,0 +1,36 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/id.rst:5 +msgid "space_object.id" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/id.rst:11 +msgid "Ordinal space number. Spaces can be referenced by either name or number. Thus, if space ``tester`` has ``id = 800``, then ``box.space.tester:insert{0}`` and ``box.space[800]:insert{0}`` are equivalent requests." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/id.rst:16 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/id.rst:18 +msgid "tarantool> box.space.tester.id\n" +"---\n" +"- 512\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/index_data.pot b/locale/en/reference/reference_lua/box_space/index_data.pot new file mode 100644 index 0000000000..b769b82fc2 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/index_data.pot @@ -0,0 +1,56 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:5 +msgid "space_object.index" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:11 +msgid "A container for all defined indexes. There is a Lua object of type :doc:`box.index ` with methods to search tuples and iterate over them in predefined order." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:15 +msgid "To reset, use :ref:`box.stat.reset() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:17 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/index_data.rst:21 +msgid "-- checking the number of indexes for space 'tester'\n" +"tarantool> local counter=0; for i=0,#box.space.tester.index do\n" +" if box.space.tester.index[i]~=nil then counter=counter+1 end\n" +" end; print(counter)\n" +"1\n" +"---\n" +"...\n" +"-- checking the type of index 'primary'\n" +"tarantool> box.space.tester.index.primary.type\n" +"---\n" +"- TREE\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/insert.pot b/locale/en/reference/reference_lua/box_space/insert.pot new file mode 100644 index 0000000000..be8e230602 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/insert.pot @@ -0,0 +1,80 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:5 +msgid "space_object:insert()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:11 +msgid "Insert a tuple into a space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:13 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:15 +msgid "tuple to be inserted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:17 +msgid "the inserted tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:18 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:20 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:22 +msgid ":errcode:`ER_TUPLE_FOUND` if a tuple with the same unique-key value already exists." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:24 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:27 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:29 +msgid "tarantool> box.space.tester:insert{5000,'tuple number five thousand'}\n" +"---\n" +"- [5000, 'tuple number five thousand']\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/insert.rst:36 +msgid "For more usage scenarios and typical errors see :ref:`Example: using data operations ` further in this section." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/len.pot b/locale/en/reference/reference_lua/box_space/len.pot new file mode 100644 index 0000000000..f65c1ab409 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/len.pot @@ -0,0 +1,64 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/len.rst:5 +msgid "space_object:len()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:11 +msgid "Return the number of tuples in the space. If compared with :doc:`count() `, this method works faster because ``len()`` does not scan the entire space to count the tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:16 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:19 +msgid "Number of tuples in the space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:21 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:23 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:26 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:28 +msgid "tarantool> box.space.tester:len()\n" +"---\n" +"- 2\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/len.rst:35 +msgid "**Note regarding storage engine:** vinyl supports ``len()`` but the result may be approximate. If an exact result is necessary then use :doc:`count() ` or :doc:`pairs():length() `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/on_replace.pot b/locale/en/reference/reference_lua/box_space/on_replace.pot new file mode 100644 index 0000000000..b2dff7734f --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/on_replace.pot @@ -0,0 +1,165 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:5 +msgid "space_object:on_replace()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:11 +msgid "Create a \"replace :ref:`trigger `\". The ``trigger-function`` will be executed whenever a ``replace()`` or ``insert()`` or ``update()`` or ``upsert()`` or ``delete()`` happens to a tuple in ````." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:16 +msgid "function which will become the trigger function; see Example 2 below for details about trigger function parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:20 +msgid "existing trigger function which will be replaced by ``trigger-function``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:23 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:25 +msgid "If the parameters are ``(nil, old-trigger-function)``, then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:28 +msgid "If both parameters are omitted, then the response is a list of existing trigger functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:31 +msgid "If it is necessary to know whether the trigger activation happened due to replication or on a specific connection type, the function can refer to :doc:`/reference/reference_lua/box_session/type`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:35 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:38 +msgid "See also :doc:`/reference/reference_lua/box_space/before_replace`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:40 +msgid "**Example 1:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:42 +msgid "tarantool> x = 0\n" +" > function f ()\n" +" > x = x + 1\n" +" > end\n" +"tarantool> box.space.my_space_name:on_replace(f)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:50 +msgid "**Example 2:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:52 +msgid "The ``trigger-function`` can have up to four parameters:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:54 +msgid "(tuple) old value which has the contents before the request started," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:55 +msgid "(tuple) new value which has the contents after the request ended," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:56 +msgid "(string) space name," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:57 +msgid "(string) type of request which is ``INSERT``, ``DELETE``, ``UPDATE``, or ``REPLACE``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:60 +msgid "For example, the following code causes ``nil`` and ``INSERT`` to be printed when the insert request is processed and causes ``[1, 'Hi']`` and ``DELETE`` to be printed when the delete request is processed:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:65 +msgid "box.schema.space.create('space_1')\n" +"box.space.space_1:create_index('space_1_index',{})\n" +"function on_replace_function (old, new, s, op) print(old) print(op) end\n" +"box.space.space_1:on_replace(on_replace_function)\n" +"box.space.space_1:insert{1,'Hi'}\n" +"box.space.space_1:delete{1}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:74 +msgid "**Example 3:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:76 +msgid "The following series of requests will create a space, create an index, create a function which increments a counter, create a trigger, do two inserts, drop the space, and display the counter value - which is 2, because the function is executed once after each insert." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:81 +msgid "tarantool> s = box.schema.space.create('space53')\n" +"tarantool> s:create_index('primary', {parts = {{field = 1, type = 'unsigned'}}})\n" +"tarantool> function replace_trigger()\n" +" > replace_counter = replace_counter + 1\n" +" > end\n" +"tarantool> s:on_replace(replace_trigger)\n" +"tarantool> replace_counter = 0\n" +"tarantool> t = s:insert{1, 'First replace'}\n" +"tarantool> t = s:insert{2, 'Second replace'}\n" +"tarantool> s:drop()\n" +"tarantool> replace_counter" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:97 +msgid "As everything executed inside triggers is already in a transaction, you shouldn't use in trigger-functions for ``on_replace`` and ``before_replace``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:101 +msgid "transactions," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:102 +msgid "yield-operations (:ref:`explicit ` or not)," +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:103 +msgid "actions that are not allowed to be used in transactions (see :ref:`rule #2 `)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:108 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/on_replace.rst:110 +msgid "tarantool> box.space.test:on_replace(fiber.yield)\n" +"tarantool> box.space.test:replace{1, 2, 3}\n" +"2020-02-02 21:22:03.073 [73185] main/102/init.lua txn.c:532 E> ER_TRANSACTION_YIELD: Transaction has been aborted by a fiber yield\n" +"---\n" +"- error: Transaction has been aborted by a fiber yield\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/pairs.pot b/locale/en/reference/reference_lua/box_space/pairs.pot new file mode 100644 index 0000000000..0b5a43d351 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/pairs.pot @@ -0,0 +1,144 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:5 +msgid "space_object:pairs()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:11 +msgid "Search for a tuple or a set of tuples in the given space, and allow iterating over one tuple at a time. To search by the specific index, use the :ref:`box_index-pairs` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:15 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:17 +msgid "value to be matched against the index key, which may be multi-part" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:19 +msgid "the :ref:`iterator type `. The default iterator type is 'EQ'" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:20 +msgid "a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``pairs`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:22 +msgid "The `iterator `_, which can be used in a ``for/end`` loop or with `totable() `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:26 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:28 +msgid "no such space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:29 +msgid "wrong type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:30 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:32 +msgid "iterator position is invalid" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:35 +msgid "**Complexity factors:** Index size, Index type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:37 +msgid "For information about iterators' internal structures, see the `\"Lua Functional library\" `_ documentation." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:42 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:44 +msgid "Below are few examples of using ``pairs`` with different parameters. To try out these examples, you need to bootstrap a Tarantool instance as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/pairs.rst:48 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +" bands:insert{5, 'Pink Floyd', 1965}\n" +" bands:insert{6, 'The Rolling Stones', 1962}\n" +" bands:insert{7, 'The Doors', 1965}\n" +" bands:insert{8, 'Nirvana', 1987}\n" +" bands:insert{9, 'Led Zeppelin', 1968}\n" +" bands:insert{10, 'Queen', 1970}\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples by the primary index --\n" +"tarantool> for _, tuple in bands:pairs() do\n" +" print(tuple)\n" +" end\n" +"[1, 'Roxette', 1986]\n" +"[2, 'Scorpions', 1965]\n" +"[3, 'Ace of Base', 1987]\n" +"[4, 'The Beatles', 1960]\n" +"[5, 'Pink Floyd', 1965]\n" +"[6, 'The Rolling Stones', 1962]\n" +"[7, 'The Doors', 1965]\n" +"[8, 'Nirvana', 1987]\n" +"[9, 'Led Zeppelin', 1968]\n" +"[10, 'Queen', 1970]\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples whose primary key values are between 3 and 6 --\n" +"tarantool> for _, tuple in bands:pairs(3, {iterator = \"GE\"}) do\n" +" if (tuple[1] > 6) then break end\n" +" print(tuple)\n" +" end\n" +"[3, 'Ace of Base', 1987]\n" +"[4, 'The Beatles', 1960]\n" +"[5, 'Pink Floyd', 1965]\n" +"[6, 'The Rolling Stones', 1962]\n" +"---\n" +"...\n" +"\n" +"-- Select all tuples after the specified tuple --\n" +"tarantool> for _, tuple in bands:pairs({}, {after={7, 'The Doors', 1965}}) do\n" +" print(tuple)\n" +" end\n" +"[8, 'Nirvana', 1987]\n" +"[9, 'Led Zeppelin', 1968]\n" +"[10, 'Queen', 1970]\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/put.pot b/locale/en/reference/reference_lua/box_space/put.pot new file mode 100644 index 0000000000..92952c41ef --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/put.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/put.rst:5 +msgid "space_object:put()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/put.rst:7 +msgid "See :doc:`/reference/reference_lua/box_space/replace`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/rename.pot b/locale/en/reference/reference_lua/box_space/rename.pot new file mode 100644 index 0000000000..4a8a7f4832 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/rename.pot @@ -0,0 +1,62 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:5 +msgid "space_object:rename()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:11 +msgid "Rename a space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:13 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:15 +msgid "new name for space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:17 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:19 +msgid "**Possible errors:** ``space_object`` does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:21 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/rename.rst:23 +msgid "tarantool> box.space.space55:rename('space56')\n" +"---\n" +"...\n" +"tarantool> box.space.space56:rename('space55')\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/replace.pot b/locale/en/reference/reference_lua/box_space/replace.pot new file mode 100644 index 0000000000..57b30bbe68 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/replace.pot @@ -0,0 +1,81 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:5 +msgid "space_object:replace() / put()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:12 +msgid "Insert a tuple into a space. If a tuple with the same primary key already exists, ``box.space...:replace()`` replaces the existing tuple with a new one. The syntax variants ``box.space...:replace()`` and ``box.space...:put()`` have the same effect; the latter is sometimes used to show that the effect is the converse of ``box.space...:get()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:18 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:20 +msgid "tuple to be inserted" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:22 +msgid "the inserted tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:23 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:25 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:27 +msgid ":errcode:`ER_TUPLE_FOUND` if a different tuple with the same unique-key value already exists. (This will only happen if there is a unique secondary index.)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:29 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:32 +msgid "**Complexity factors:** Index size, Index type, Number of indexes accessed, WAL settings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:35 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:37 +msgid "box.space.tester:replace{5000, 'tuple number five thousand'}" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/replace.rst:41 +msgid "For more usage scenarios and typical errors see :ref:`Example: using data operations ` further in this section." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/run_triggers.pot b/locale/en/reference/reference_lua/box_space/run_triggers.pot new file mode 100644 index 0000000000..ec28144922 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/run_triggers.pot @@ -0,0 +1,49 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:5 +msgid "space_object:run_triggers()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:11 +msgid "At the time that a :ref:`trigger ` is defined, it is automatically enabled - that is, it will be executed. :doc:`Replace ` triggers can be disabled with :samp:`box.space.{space-name}:run_triggers(false)` and re-enabled with :samp:`box.space.{space-name}:run_triggers(true)`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:17 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:21 +msgid "The following series of requests will associate an existing function named `F` with an existing space named `T`, associate the function a second time with the same space (so it will be called twice), disable all triggers of `T`, and delete each trigger by replacing with ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/run_triggers.rst:26 +msgid "tarantool> box.space.T:on_replace(F)\n" +"tarantool> box.space.T:on_replace(F)\n" +"tarantool> box.space.T:run_triggers(false)\n" +"tarantool> box.space.T:on_replace(nil, F)\n" +"tarantool> box.space.T:on_replace(nil, F)" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/select.pot b/locale/en/reference/reference_lua/box_space/select.pot new file mode 100644 index 0000000000..6f2ba1b6d8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/select.pot @@ -0,0 +1,187 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/select.rst:5 +msgid "space_object:select()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:11 +msgid "Search for a tuple or a set of tuples in the given space by the primary key. To search by the specific index, use the :doc:`/reference/reference_lua/box_index/select` method." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:16 +msgid "Note that this method doesn't yield. For details, see :ref:`Cooperative multitasking `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:18 +msgid "an :ref:`object reference `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:20 +msgid "a value to be matched against the index key, which may be multi-part." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:22 +msgid "none, any, or all of the same options that :doc:`/reference/reference_lua/box_index/select` allows: * ``options.iterator`` -- the :ref:`iterator type `. The default iterator type is 'EQ'. * ``options.limit`` -- the maximum number of tuples. * ``options.offset`` -- the number of tuples to skip. * ``options.after`` -- a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``select`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple. * ``options.fetch_pos`` -- if **true**, the ``select`` method returns the position of the last selected tuple as the second value. .. NOTE:: The ``after`` and ``fetch_pos`` options are supported for the ``TREE`` :ref:`index ` only." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:22 +msgid "none, any, or all of the same options that :doc:`/reference/reference_lua/box_index/select` allows:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:26 +msgid "``options.iterator`` -- the :ref:`iterator type `. The default iterator type is 'EQ'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:27 +msgid "``options.limit`` -- the maximum number of tuples." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:28 +msgid "``options.offset`` -- the number of tuples to skip." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:29 +msgid "``options.after`` -- a tuple or the position of a tuple (:ref:`tuple_pos `) after which ``select`` starts the search. You can pass an empty string or :ref:`box.NULL ` to this option to start the search from the first tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:30 +msgid "``options.fetch_pos`` -- if **true**, the ``select`` method returns the position of the last selected tuple as the second value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:34 +msgid "The ``after`` and ``fetch_pos`` options are supported for the ``TREE`` :ref:`index ` only." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:38 +msgid "This function might return one or two values:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:40 +msgid "The tuples whose primary-key fields are equal to the fields of the passed key. If the number of passed fields is less than the number of fields in the primary key, then only the passed fields are compared, so ``select{1,2}`` matches a tuple whose primary key is ``{1,2,3}``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:45 +msgid "(Optionally) If ``options.fetch_pos`` is set to **true**, returns a base64-encoded string representing the position of the last selected tuple as the second value. If no tuples are fetched, returns ``nil``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:50 +msgid "array of tuples" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:51 +msgid "(Optionally) string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:54 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:56 +msgid "no such space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:57 +msgid "wrong type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:58 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:60 +msgid "iterator position is invalid" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:63 +msgid "**Complexity factors:** Index size, Index type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:65 +msgid "**Examples:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:67 +msgid "Below are few examples of using ``select`` with different parameters. To try out these examples, you need to bootstrap a Tarantool instance as described in :ref:`Using data operations `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:71 +msgid "-- Insert test data --\n" +"tarantool> bands:insert{1, 'Roxette', 1986}\n" +" bands:insert{2, 'Scorpions', 1965}\n" +" bands:insert{3, 'Ace of Base', 1987}\n" +" bands:insert{4, 'The Beatles', 1960}\n" +" bands:insert{5, 'Pink Floyd', 1965}\n" +" bands:insert{6, 'The Rolling Stones', 1962}\n" +" bands:insert{7, 'The Doors', 1965}\n" +" bands:insert{8, 'Nirvana', 1987}\n" +" bands:insert{9, 'Led Zeppelin', 1968}\n" +" bands:insert{10, 'Queen', 1970}\n" +"---\n" +"...\n" +"\n" +"-- Select a tuple by the specified primary key --\n" +"tarantool> bands:select(4)\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +"...\n" +"\n" +"-- Select maximum 3 tuples with the primary key value greater than 3 --\n" +"tarantool> bands:select({3}, {iterator='GT', limit = 3})\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +" - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +"...\n" +"\n" +"-- Select maximum 3 tuples after the specified tuple --\n" +"tarantool> bands:select({}, {after = {4, 'The Beatles', 1960}, limit = 3})\n" +"---\n" +"- - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +" - [7, 'The Doors', 1965]\n" +"...\n" +"\n" +"-- Select first 3 tuples and fetch a last tuple's position --\n" +"tarantool> result, position = bands:select({}, {limit = 3, fetch_pos = true})\n" +"---\n" +"...\n" +"-- Then, pass this position as the 'after' parameter --\n" +"tarantool> bands:select({}, {limit = 3, after = position})\n" +"---\n" +"- - [4, 'The Beatles', 1960]\n" +" - [5, 'Pink Floyd', 1965]\n" +" - [6, 'The Rolling Stones', 1962]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/select.rst:123 +msgid "You can get a field from a tuple both by the field number and field name. See example: :ref:`using field names instead of field numbers `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/system_views.pot b/locale/en/reference/reference_lua/box_space/system_views.pot new file mode 100644 index 0000000000..99b6267885 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/system_views.pot @@ -0,0 +1,120 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:4 +msgid "System space views" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:6 +msgid "A system space view, also called a 'sysview', is a restricted read-only copy of a system space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:8 +msgid "The system space views and the system spaces that they are associated with are: |br| ``_vcollation``, a view of :ref:`_collation `, |br| ``_vfunc``, a view of :ref:`_func `, |br| ``_vindex``, a view of :ref:`_index `, |br| ``_vpriv``, a view of :ref:`_priv `, |br| ``_vsequence``, a view of :ref:`_sequence `, |br| ``_vspace``, a view of :ref:`_space `, |br| ``_vspace_sequence``, a view of :ref:`_space_sequence `, |br| ``_vuser``, a view of :ref:`_user `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:18 +msgid "The structure of a system space view's tuples is identical to the structure of the associated space's tuples. However, the privileges for a system space view are usually different. By default, ordinary users do not have any privileges for most system spaces, but have a 'read' privilege for system space views." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:23 +msgid "Typically this is the default situation: |br| * :ref:`The 'public' role ` has 'read' privilege on all system space views because that is the situation when the database is first created. |br| * All users have the 'public' role, because it is granted to them automatically during :ref:`box.schema.user.create() `. |br| * The system space view will contain the tuples in the associated system space, if and only if the user has a privilege for the object named in the tuple. |br| Unless administrators change the privileges, the effect is that non-administrator users cannot access the system space, but they can access the system space view, which shows only the objects that they can access." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:34 +msgid "For example, typically, the 'admin' user can do anything with ``_space`` and ``_vspace`` looks the same as ``_space``. But the 'guest' user can only read ``_vspace``, and ``_vspace`` contains fewer tuples than ``_space``. Therefore in most installations the 'guest' user should select from ``_vspace`` to get a list of spaces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:39 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:41 +msgid "This example shows the difference between ``_vuser`` and ``_user``. We have explained that: If the user has the full set of privileges (like 'admin'), the contents of ``_vuser`` match the contents of ``_user``. If the user has limited access, ``_vuser`` contains only tuples accessible to this user." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:47 +msgid "To see how ``_vuser`` works, :ref:`connect to a Tarantool database remotely ` via ``net.box`` and select all tuples from the ``_user`` space, both when the 'guest' user *is* and *is not* allowed to read from the database." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:53 +msgid "First, start Tarantool and grant read, write and execute privileges to the ``guest`` user:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:56 +msgid "tarantool> box.cfg{listen = 3301}\n" +"---\n" +"...\n" +"tarantool> box.schema.user.grant('guest', 'read,write,execute', 'universe')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:65 +msgid "Switch to the other terminal, connect to the Tarantool instance and select all tuples from the ``_user`` space:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:68 +msgid "tarantool> conn = require('net.box').connect(3301)\n" +"---\n" +"...\n" +"tarantool> conn.space._user:select{}\n" +"---\n" +"- - [0, 1, 'guest', 'user', {}]\n" +" - [1, 1, 'admin', 'user', {}]\n" +" - [2, 1, 'public', 'role', {}]\n" +" - [3, 1, 'replication', 'role', {}]\n" +" - [31, 1, 'super', 'role', {}]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:82 +msgid "This result contains the same set of users as if you made the request from your Tarantool instance as 'admin'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:85 +msgid "Switch to the first terminal and revoke the read privileges from the 'guest' user:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:87 +msgid "tarantool> box.schema.user.revoke('guest', 'read', 'universe')\n" +"---\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:93 +msgid "Switch to the other terminal, stop the session (to stop ``tarantool`` type Ctrl+C or Ctrl+D), start again, connect again, and repeat the ``conn.space._user:select{}`` request. The access is denied:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:97 +msgid "tarantool> conn.space._user:select{}\n" +"---\n" +"- error: Read access to space '_user' is denied for user 'guest'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:104 +msgid "However, if you select from ``_vuser`` instead, the users' data available for the 'guest' user is displayed:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/system_views.rst:107 +msgid "tarantool> conn.space._vuser:select{}\n" +"---\n" +"- - [0, 1, 'guest', 'user', {}]\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/truncate.pot b/locale/en/reference/reference_lua/box_space/truncate.pot new file mode 100644 index 0000000000..095becb4e4 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/truncate.pot @@ -0,0 +1,67 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:5 +msgid "space_object:truncate()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:11 +msgid "Deletes all tuples. The method is performed in background and doesn't block consequent requests." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:14 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:17 +msgid "**Complexity factors:** Index size, Index type, Number of tuples accessed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:19 +msgid "nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:21 +msgid "The ``truncate`` method can only be called by the user who created the space, or from within a ``setuid`` function created by the user who created the space. Read more about `setuid` functions in the reference for :doc:`/reference/reference_lua/box_schema/func_create`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:29 +msgid "Do not call this method within a transaction in Tarantool older than :tarantool-release:`2.10.0`. See :tarantool-issue:`6123` for details." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:32 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/truncate.rst:34 +msgid "tarantool> box.space.tester:truncate()\n" +"---\n" +"...\n" +"tarantool> box.space.tester:len()\n" +"---\n" +"- 0\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/update.pot b/locale/en/reference/reference_lua/box_space/update.pot new file mode 100644 index 0000000000..46018d5468 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/update.pot @@ -0,0 +1,205 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/update.rst:5 +msgid "space_object:update()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:11 +msgid "Update a tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:13 +msgid "The ``update`` function supports operations on fields — assignment, arithmetic (if the field is numeric), cutting and pasting fragments of a field, deleting or inserting a field. Multiple operations can be combined in a single update request, and in this case they are performed atomically and sequentially. Each operation requires specification of a field identifier, which is usually a number. When multiple operations are present, the field number for each operation is assumed to be relative to the most recent state of the tuple, that is, as if all previous operations in a multi-operation update have already been applied. In other words, it is always safe to merge multiple ``update`` invocations into a single invocation, with no change in semantics." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:25 +msgid "Possible operators are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:27 +msgid "``+`` for addition. values must be numeric, e.g. unsigned or decimal" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:28 +msgid "``-`` for subtraction. values must be numeric" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:29 +msgid "``&`` for bitwise AND. values must be unsigned numeric" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:30 +msgid "``|`` for bitwise OR. values must be unsigned numeric" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:31 +msgid "``^`` for bitwise :abbr:`XOR(exclusive OR)`. values must be unsigned numeric" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:33 +msgid "``:`` for string splice." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:34 +msgid "``!`` for insertion of a new field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:35 +msgid "``#`` for deletion." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:36 +msgid "``=`` for assignment." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:38 +msgid "Possible field_identifiers are:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:40 +msgid "Positive field number. The first field is 1, the second field is 2, and so on." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:42 +msgid "Negative field number. The last field is -1, the second-last field is -2, and so on. In other words: (#tuple + negative field number + 1)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:44 +msgid "Name. If the space was formatted with :doc:`/reference/reference_lua/box_space/format`, then this can be a string for the field 'name'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:48 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:50 +msgid "primary-key field values, must be passed as a Lua table if key is multi-part" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:52 +msgid "operation type represented in string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:53 +msgid "what field the operation will apply to." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:54 +msgid "what value will be applied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:56 +msgid "the updated tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:57 +msgid "nil if the key is not found" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:58 +msgid "tuple or nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:60 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:62 +msgid "It is illegal to modify a primary key field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:63 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:66 +msgid "**Complexity factors:** Index size, Index type, number of indexes accessed, WAL settings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:69 +msgid "Thus, in the instruction:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:71 +msgid "s:update(44, {{'+', 1, 55 }, {'=', 3, 'x'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:75 +msgid "the primary-key value is ``44``, the operators are ``'+'`` and ``'='`` meaning *add a value to a field and then assign a value to a field*, the first affected field is field ``1`` and the value which will be added to it is ``55``, the second affected field is field ``3`` and the value which will be assigned to it is ``'x'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:81 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:83 +msgid "Assume that initially there is a space named ``tester`` with a primary-key index whose type is ``unsigned``. There is one tuple, with ``field[1]`` = ``999`` and ``field[2]`` = ``'A'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:87 +msgid "In the update: |br| ``box.space.tester:update(999, {{'=', 2, 'B'}})`` |br| The first argument is ``tester``, that is, the affected space is ``tester``. The second argument is ``999``, that is, the affected tuple is identified by primary key value = 999. The third argument is ``=``, that is, there is one operation — *assignment to a field*. The fourth argument is ``2``, that is, the affected field is ``field[2]``. The fifth argument is ``'B'``, that is, ``field[2]`` contents change to ``'B'``. Therefore, after this update, ``field[1]`` = ``999`` and ``field[2]`` = ``'B'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:98 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'=', 2, 'B'}})`` |br| the arguments are the same, except that the key is passed as a Lua table (inside braces). This is unnecessary when the primary key has only one field, but would be necessary if the primary key had more than one field. Therefore, after this update, ``field[1]`` = ``999`` and ``field[2]`` = ``'B'`` (no change)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:105 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'=', 3, 1}})`` |br| the arguments are the same, except that the fourth argument is ``3``, that is, the affected field is ``field[3]``. It is okay that, until now, ``field[3]`` has not existed. It gets added. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``'B'``, ``field[3]`` = ``1``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:112 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'+', 3, 1}})`` |br| the arguments are the same, except that the third argument is ``'+'``, that is, the operation is addition rather than assignment. Since ``field[3]`` previously contained ``1``, this means we're adding ``1`` to ``1``. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``'B'``, ``field[3]`` = ``2``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:120 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})`` |br| the idea is to modify two fields at once. The formats are ``'|'`` and ``=``, that is, there are two operations, OR and assignment. The fourth and fifth arguments mean that ``field[3]`` gets OR'ed with ``1``. The seventh and eighth arguments mean that ``field[2]`` gets assigned ``'C'``. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``'C'``, ``field[3]`` = ``3``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:129 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'#', 2, 1}, {'-', 2, 3}})`` |br| The idea is to delete ``field[2]``, then subtract ``3`` from ``field[3]``. But after the delete, there is a renumbering, so ``field[3]`` becomes ``field[2]`` before we subtract ``3`` from it, and that's why the seventh argument is ``2``, not ``3``. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``0``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:137 +msgid "In the update: |br| ``box.space.tester:update({999}, {{'=', 2, 'XYZ'}})`` |br| we're making a long string so that splice will work in the next example. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``'XYZ'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:142 +msgid "In the update: |br| ``box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})`` |br| The third argument is ``':'``, that is, this is the example of splice. The fourth argument is ``2`` because the change will occur in ``field[2]``. The fifth argument is 2 because deletion will begin with the second byte. The sixth argument is 1 because the number of bytes to delete is 1. The seventh argument is ``'!!'``, because ``'!!'`` is to be added at this position. Therefore, after this update, ``field[1]`` = ``999``, ``field[2]`` = ``'X!!Z'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:151 +msgid "For more usage scenarios and typical errors see :ref:`Example: using data operations ` further in this section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/update.rst:155 +msgid "Since Tarantool 2.3 a tuple can also be updated via :ref:`JSON paths`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/upsert.pot b/locale/en/reference/reference_lua/box_space/upsert.pot new file mode 100644 index 0000000000..c20cd19790 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/upsert.pot @@ -0,0 +1,93 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:5 +msgid "space_object:upsert()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:11 +msgid "Update or insert a tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:13 +msgid "If there is an existing tuple which matches the key fields of ``tuple``, then the request has the same effect as :doc:`/reference/reference_lua/box_space/update` and the ``{{operator, field_identifier, value}, ...}`` parameter is used. If there is no existing tuple which matches the key fields of ``tuple``, then the request has the same effect as :doc:`/reference/reference_lua/box_space/insert` and the ``{tuple}`` parameter is used. However, unlike ``insert`` or ``update``, ``upsert`` will not read a tuple and perform error checks before returning -- this is a design feature which enhances throughput but requires more caution on the part of the user." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:25 +msgid "an :ref:`object reference `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:27 +msgid "default tuple to be inserted, if analogue isn't found" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:29 +msgid "operation type represented in string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:30 +msgid "what field the operation will apply to" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:31 +msgid "what value will be applied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:33 +msgid "null" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:35 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:37 +msgid "It is illegal to modify a primary-key field." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:38 +msgid "It is illegal to use upsert with a space that has a unique secondary index." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:40 +msgid ":errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the :ref:`MVCC transaction mode `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:43 +msgid "**Complexity factors:** Index size, Index type, number of indexes accessed, WAL settings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:46 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:48 +msgid "box.space.tester:upsert({12,'c'}, {{'=', 3, 'a'}, {'=', 4, 'b'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/upsert.rst:52 +msgid "For more usage scenarios and typical errors see :ref:`Example: using data operations ` further in this section." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_space/user_defined.pot b/locale/en/reference/reference_lua/box_space/user_defined.pot new file mode 100644 index 0000000000..a9f6349b35 --- /dev/null +++ b/locale/en/reference/reference_lua/box_space/user_defined.pot @@ -0,0 +1,60 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:5 +msgid "space_object extensions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:7 +msgid "You can extend ``space_object`` with custom functions as follows:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:9 +msgid "Create a Lua function." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:10 +msgid "Add the function name to a predefined global variable ``box.schema.space_mt``, which has the ``table`` type. Adding to ``box.schema.space_mt`` makes the function available for all spaces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:11 +msgid "Call the function on the ``space_object``: ``space_object:function-name([parameters])``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:13 +msgid "Alternatively, you can make a user-defined function available for only one space by calling ``getmetatable(space_object)`` and then adding the function name to the meta table." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:17 +msgid "See also: :doc:`/reference/reference_lua/box_index/user_defined`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_space/user_defined.rst:21 +msgid "-- Visible to any space, no parameters.\n" +"-- After these requests, the value of global_variable will be 6.\n" +"box.schema.space.create('t')\n" +"box.space.t:create_index('i')\n" +"global_variable = 5\n" +"function f(space_arg) global_variable = global_variable + 1 end\n" +"box.schema.space_mt.counter = f\n" +"box.space.t:counter()" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_sql.pot b/locale/en/reference/reference_lua/box_sql.pot new file mode 100644 index 0000000000..5aca1ef2c0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_sql.pot @@ -0,0 +1,77 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_sql.rst:5 +msgid "Functions for SQL" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:7 +msgid "The ``box`` module contains some functions related to SQL:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:9 +msgid "``box.schema.func.create`` -- for making Lua functions callable from SQL statements. See :ref:`Calling Lua routines from SQL ` in the :ref:`SQL Plus Lua ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:13 +msgid "``box.execute`` -- for making SQL statements callable from Lua functions. See the :ref:`SQL user guide `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:16 +msgid "``box.prepare`` and ``box.unprepare``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:18 +msgid "Some SQL statements are illustrated in the :ref:`SQL tutorial `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:20 +msgid "Below is a list of all SQL functions and members." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:31 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:32 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:34 +msgid ":doc:`./box_sql/execute`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:35 +msgid "Make Lua functions callable from SQL statements. See :ref:`Calling Lua routines from SQL ` in the :ref:`SQL Plus Lua ` section" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:39 +msgid ":doc:`./box_sql/prepare`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:40 +msgid "Make SQL statements callable from Lua functions. See the :ref:`SQL user guide `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:43 +msgid ":doc:`./box_sql/prepared_table`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql.rst:44 +msgid "Methods for prepared SQL statement" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_sql/execute.pot b/locale/en/reference/reference_lua/box_sql/execute.pot new file mode 100644 index 0000000000..9343c5c95a --- /dev/null +++ b/locale/en/reference/reference_lua/box_sql/execute.pot @@ -0,0 +1,187 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:5 +msgid "box.execute()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:9 +msgid "Execute the SQL statement contained in the ``sql-statement`` parameter." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:11 +msgid "statement, which should conform to :ref:`the rules for SQL grammar `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:13 +msgid "optional table for placeholders in the statement" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:15 +msgid "depends on statement" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:19 +msgid "There are two ways to pass extra parameters to ``box.execute()``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:21 +msgid "The first way, which is the preferred way, is to put placeholders in the string, and pass a second argument, an ``extra-parameters`` table. A placeholder is either a question mark \"?\", or a colon \":\" followed by a name. An extra parameter is any Lua expression." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:26 +msgid "If placeholders are question marks, then they are replaced by ``extra-parameters`` values in corresponding positions. That is, the first ``?`` is replaced by the first extra parameter, the second ``?`` is replaced by the second extra parameter, and so on." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:31 +msgid "If placeholders are ``:names``, then they are replaced by ``extra-parameters`` values with corresponding names." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:34 +msgid "For example, this request that contains literal values ``1`` and ``'x'``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:36 +msgid "box.execute([[INSERT INTO tt VALUES (1, 'x');]]);" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:40 +msgid "... is the same as the request below containing two question-mark placeholders (``?`` and ``?``) and a two-element ``extra-parameters`` table:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:43 +msgid "x = {1,'x'}\n" +"box.execute([[INSERT INTO tt VALUES (?, ?);]], x);" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:48 +msgid "... and is the same as this request containing two ``:name`` placeholders (``:a`` and ``:b``) and a two-element ``extra-parameters`` table with elements named \"a\" and \"b\":" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:52 +msgid "box.execute([[INSERT INTO tt VALUES (:a, :b);]], {{[':a']=1},{[':b']='x'}})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:57 +msgid "The second way is to concatenate strings. For example, the Lua script below inserts 10 rows with different primary-key values into table ``t``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:61 +msgid "for i=1,10,1 do\n" +" box.execute(\"insert into t values (\" .. i .. \")\")\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:67 +msgid "When creating SQL statements based on user input, application developers should beware of `SQL injection `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:70 +msgid "Since ``box.execute()`` is an invocation of a Lua function, it either causes an error message or returns a value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:73 +msgid "For some statements the returned value contains a field named ``rowcount``, for example:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:75 +msgid "tarantool> box.execute([[CREATE TABLE table1 (column1 INT PRIMARY key, column2 VARCHAR(10));]])\n" +"---\n" +"- rowcount: 1\n" +"...\n" +"tarantool> box.execute([[INSERT INTO table1 VALUES (55,'Hello SQL world!');]])\n" +"---\n" +"- rowcount: 1\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:86 +msgid "For statements that cause generation of values for PRIMARY KEY AUTOINCREMENT columns, there is a field named ``autoincrement_id``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:91 +msgid "For SELECT or PRAGMA statements, the returned value is a *result set*, containing a field named ``metadata`` (a table with column names and Tarantool/NoSQL type names) and a field named ``rows`` (a table with the contents of each row)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:96 +msgid "For example, for a statement ``SELECT \"x\" FROM t WHERE \"x\"=5;`` where ``\"x\"`` is an INTEGER column and there is one row, a display on the Tarantool client might look like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:100 +msgid "tarantool> box.execute([[SELECT \"x\" FROM t WHERE \"x\"=5;]])\n" +"---\n" +"- metadata:\n" +" - name: x\n" +" type: integer\n" +" rows:\n" +" - [5]\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:111 +msgid "For a look at raw format of SELECT results, see :ref:`Binary protocol -- responses for SQL `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:114 +msgid "The order of components within a map is not guaranteed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:118 +msgid "If ``sql_full_metadata`` in the :ref:`_session_settings ` system table is TRUE, then result set metadata may include these things in addition to ``name`` and ``type``:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:123 +msgid "``collation`` (present only if COLLATE clause is specified for a STRING) = :ref:`\"Collation\" `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:125 +msgid "``is_nullable`` (present only if the :ref:`select list ` specified a base table column and nothing else) = false if column was defined as :ref:`NOT NULL `, otherwise true. If this is not present, that implies that nullability is unknown." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:129 +msgid "``is_autoincrement`` (present only if the select list specified a base table column and nothing else) = true if column was defined as :ref:`PRIMARY KEY AUTOINCREMENT `, otherwise false." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:133 +msgid "``span`` (always present) = the original expression in a select list, which often is the same as ``name`` if the select list specifies a column name and nothing else, but otherwise differs, for example, after ``SELECT x+55 AS x FROM t;`` the ``name`` is X and the ``span`` is x+55. If ``span`` and ``name`` are the same then the content is MP_NIL." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:139 +msgid "Alternative: if you are using the Tarantool server as a client, you can switch languages as follows:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:142 +msgid "\\set language sql\n" +"\\set delimiter ;" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:147 +msgid "Afterwards, you can enter any SQL statement directly without needing ``box.execute()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/execute.rst:150 +msgid "There is also an ``execute()`` function available in :ref:`module net.box `. For example, you can execute ``conn:execute(sql-statement])`` after ``conn = net_box.connect(url-string)``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_sql/prepare.pot b/locale/en/reference/reference_lua/box_sql/prepare.pot new file mode 100644 index 0000000000..a05d1a2c05 --- /dev/null +++ b/locale/en/reference/reference_lua/box_sql/prepare.pot @@ -0,0 +1,93 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:5 +msgid "box.prepare()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:9 +msgid "Prepare the SQL statement contained in the sql-statement parameter. The syntax and requirements for ``box.prepare`` are the same as for :doc:`/reference/reference_lua/box_sql/execute`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:13 +msgid "statement, which should conform to :ref:`the rules for SQL grammar `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:16 +msgid "prepared_table, with id and methods and metadata" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:17 +msgid "table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:19 +msgid "``box.prepare`` compiles an SQL statement into byte code and saves the byte code in a cache. Since compiling takes a significant amount of time, preparing a statement will enhance performance if the statement is executed many times." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:23 +msgid "If ``box.prepare`` succeeds, prepared_table contains:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:25 +msgid "``stmt_id``: integer -- an identifier generated by a hash of the statement string" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:26 +msgid "``execute``: function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:27 +msgid "``params``: map [name : string, type : string] -- parameter descriptions" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:28 +msgid "``unprepare``: function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:29 +msgid "``metadata``: map [name : string, type : string] (This is present only for SELECT or PRAGMA statements and has the same contents as the :ref:`result set metadata ` for ``box.execute``)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:32 +msgid "``param_count``: integer -- number of parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:34 +msgid "This can be used by :ref:`prepared_table:execute() ` and by :ref:`prepared_table:unprepare() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:37 +msgid "The prepared statement cache (which is also called the prepared statement holder) is \"shared\", that is, there is one cache for all sessions. However, session X cannot execute a statement prepared by session Y. |br| For monitoring the cache, see :ref:`box.info().sql `. |br| For changing the cache, see :ref:`(Configuration reference) sql_cache_size `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepare.rst:43 +msgid "Prepared statements will \"expire\" (become invalid) if any database object is dropped or created or altered -- even if the object is not mentioned in the SQL statement, even if the create or drop or alter is rolled back, even if the create or drop or alter is done in a different session." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_sql/prepared_table.pot b/locale/en/reference/reference_lua/box_sql/prepared_table.pot new file mode 100644 index 0000000000..4c1ecaa810 --- /dev/null +++ b/locale/en/reference/reference_lua/box_sql/prepared_table.pot @@ -0,0 +1,74 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:4 +msgid "object prepared_table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:12 +msgid "Execute a statement that has been prepared with :doc:`/reference/reference_lua/box_sql/prepare`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:15 +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:58 +msgid "Parameter ``prepared_table`` should be the result from ``box.prepare()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:17 +msgid "Parameter ``extra-parameters`` should be an optional table to match :ref:`placeholders or named parameters ` in the statement." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:21 +msgid "There are two ways to execute: with the method or with the statement id. That is, :samp:`{prepared_table}:execute()` and :samp:`box.execute({prepared_table}.stmt_id)` do the same thing." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:25 +msgid "Example: here is a test. This function inserts a million rows in a table using a prepared INSERT statement." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:28 +msgid "function f()\n" +" local p, start_time\n" +" box.execute([[DROP TABLE IF EXISTS t;]])\n" +" box.execute([[CREATE TABLE t (s1 INTEGER PRIMARY KEY);]])\n" +" start_time = os.time()\n" +" p = box.prepare([[INSERT INTO t VALUES (?);]])\n" +" for i=1,1000000 do p:execute({i}) end\n" +" p:unprepare()\n" +" end_time = os.time()\n" +" box.execute([[COMMIT;]])\n" +" print(end_time - start_time) -- elapsed time\n" +"end\n" +"f()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:44 +msgid "Take note of the elapsed time. Now change the line with the loop to: |br| ``for i=1,1000000 do box.execute([[INSERT INTO t VALUES (?);]], {i}) end`` |br| Run the function again, and take note of the elapsed time again. The function which executes the prepared statement will be about 15% faster, though of course this will vary depending on Tarantool version and environment." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:55 +msgid "Undo the result of an earlier :doc:`/reference/reference_lua/box_sql/prepare` request. This is equivalent to standard-SQL DEALLOCATE PREPARE." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:60 +msgid "There are two ways to unprepare: with the method or with the statement id. That is, :samp:`{prepared_table}:unprepare()` and :samp:`box.unprepare({prepared_table}.stmt_id)` do the same thing." +msgstr "" + +#: ../../doc/reference/reference_lua/box_sql/prepared_table.rst:64 +msgid "Tarantool strongly recommends using ``unprepare`` as soon as the immediate objective (executing a prepared statement multiple times) is done, or whenever a prepared statement expires. There is no automatic eviction policy, although automatic ``unprepare`` will happen when the session disconnects (the session's prepared statements will be removed from the prepared-statement cache)." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_stat.pot b/locale/en/reference/reference_lua/box_stat.pot new file mode 100644 index 0000000000..74d35eb6e0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_stat.pot @@ -0,0 +1,69 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_stat.rst:5 +msgid "Submodule box.stat" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:7 +msgid "The ``box.stat`` submodule provides access to request and network statistics." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:9 +msgid "Below is a list of all ``box.stat`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:20 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:21 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:23 +msgid ":doc:`./box_stat/stat`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:24 +msgid "Show request statistics" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:26 +msgid ":doc:`./box_stat/net`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:27 +msgid "Show network activity" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:29 +msgid ":doc:`./box_stat/vinyl`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:30 +msgid "Show vinyl-storage-engine activity" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:32 +msgid ":doc:`./box_stat/reset`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat.rst:33 +msgid "Reset the statistics" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_stat/net.pot b/locale/en/reference/reference_lua/box_stat/net.pot new file mode 100644 index 0000000000..a2396144ae --- /dev/null +++ b/locale/en/reference/reference_lua/box_stat/net.pot @@ -0,0 +1,239 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:4 +msgid "box.stat.net()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:10 +msgid "Shows network activity: the number of bytes sent and received, the number of connections, streams, and requests (current, average, and total)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:0 +#: ../../doc/reference/reference_lua/box_stat/net.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:14 +msgid "in the tables that ``box.stat.net()`` returns:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:16 +msgid "``SENT.rps`` and ``RECEIVED.rps`` -- average number of bytes sent/received per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:18 +msgid "``SENT.total`` and ``RECEIVED.total`` -- total number of bytes sent/received since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:20 +msgid "``CONNECTIONS.current`` -- number of open connections" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:21 +msgid "``CONNECTIONS.rps`` -- average number of connections opened per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:22 +msgid "``CONNECTIONS.total`` -- total number of connections opened since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:23 +msgid "``REQUESTS.current`` -- number of requests in progress, which can be limited by :ref:`box.cfg.net_msg_max `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:25 +msgid "``REQUESTS.rps`` -- average number of requests processed per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:26 +msgid "``REQUESTS.total`` -- total number of requests processed since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:27 +msgid "``REQUESTS_IN_PROGRESS.current`` -- number of requests being currently processed by the :ref:`TX thread `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:28 +msgid "``REQUESTS_IN_PROGRESS.rps`` -- average number of requests processed by the TX thread per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:29 +msgid "``REQUESTS_IN_PROGRESS.total`` -- total number of requests processed by the TX thread since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:30 +msgid "``STREAMS.current`` -- number of active :ref:`streams `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:31 +msgid "``STREAMS.rps`` -- average number of streams opened per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:32 +msgid "``STREAMS.total`` -- total number of streams opened since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:33 +msgid "``REQUESTS_IN_STREAM_QUEUE.current`` -- number of requests waiting in stream queues" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:34 +msgid "``REQUESTS_IN_STREAM_QUEUE.rps`` -- average number of requests in stream queues per second in the last 5 seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:35 +msgid "``REQUESTS_IN_STREAM_QUEUE.total`` -- total number of requests placed in stream queues since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:38 +#: ../../doc/reference/reference_lua/box_stat/net.rst:87 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:40 +msgid "tarantool> box.stat.net() -- 5 tables\n" +"---\n" +"- CONNECTIONS:\n" +" current: 1\n" +" rps: 0\n" +" total: 1\n" +" REQUESTS:\n" +" current: 0\n" +" rps: 0\n" +" total: 8\n" +" REQUESTS_IN_PROGRESS:\n" +" current: 0\n" +" rps: 0\n" +" total: 7\n" +" SENT:\n" +" total: 19579\n" +" rps: 0\n" +" REQUESTS_IN_STREAM_QUEUE:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" STREAMS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" RECEIVED:\n" +" total: 197\n" +" rps\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:77 +msgid "Shows network activity per :ref:`network thread `: the number of bytes sent and received, the number of connections, streams, and requests (current, average, and total)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:81 +msgid "When called with an index (``box.stat.net.thread[1]``), shows network statistics for a single network thread." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:84 +msgid "Same network activity metrics as :ref:`box.stat.net() ` for each network thread" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:89 +msgid "tarantool> box.stat.net.thread() -- iproto_threads = 2\n" +"- - CONNECTIONS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" REQUESTS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" REQUESTS_IN_PROGRESS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" SENT:\n" +" total: 0\n" +" rps: 0\n" +" REQUESTS_IN_STREAM_QUEUE:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" STREAMS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" RECEIVED:\n" +" total: 0\n" +" rps: 0\n" +" - CONNECTIONS:\n" +" current: 1\n" +" rps: 0\n" +" total: 1\n" +" REQUESTS:\n" +" current: 0\n" +" rps: 0\n" +" total: 8\n" +" REQUESTS_IN_PROGRESS:\n" +" current: 0\n" +" rps: 0\n" +" total: 7\n" +" SENT:\n" +" total: 19579\n" +" rps: 0\n" +" REQUESTS_IN_STREAM_QUEUE:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" STREAMS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" RECEIVED:\n" +" total: 197\n" +" rps: 0\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/net.rst:146 +msgid "tarantool> box.stat.net.thread[1] -- first network thread\n" +"- - CONNECTIONS:\n" +" current: 1\n" +" rps: 0\n" +" total: 1\n" +" REQUESTS:\n" +" current: 0\n" +" rps: 0\n" +" total: 8\n" +" REQUESTS_IN_PROGRESS:\n" +" current: 0\n" +" rps: 0\n" +" total: 7\n" +" SENT:\n" +" total: 19579\n" +" rps: 0\n" +" REQUESTS_IN_STREAM_QUEUE:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" STREAMS:\n" +" current: 0\n" +" rps: 0\n" +" total: 0\n" +" RECEIVED:\n" +" total: 197\n" +" rps: 0\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_stat/reset.pot b/locale/en/reference/reference_lua/box_stat/reset.pot new file mode 100644 index 0000000000..bcf1db66d1 --- /dev/null +++ b/locale/en/reference/reference_lua/box_stat/reset.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_stat/reset.rst:4 +msgid "box.stat.reset()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/reset.rst:10 +msgid "Resets the statistics of ``box.stat()``, ``box.stat.net()``, ``box.stat.vinyl()``, and :ref:`box.space.index `." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_stat/stat.pot b/locale/en/reference/reference_lua/box_stat/stat.pot new file mode 100644 index 0000000000..7d2f78e80d --- /dev/null +++ b/locale/en/reference/reference_lua/box_stat/stat.pot @@ -0,0 +1,106 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:2 +msgid "box.stat()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:8 +msgid "Shows the total number of requests since startup and the average number of requests per second, broken down by request type." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:12 +msgid "in the tables that ``box.stat()`` returns:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:14 +msgid "``total``: total number of requests processed per second since the server started" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:15 +msgid "``rps``: average number of requests per second in the last 5 seconds." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:17 +msgid "``ERROR`` is the count of requests that resulted in an error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:19 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/stat.rst:21 +msgid "tarantool> box.stat() -- return 15 tables\n" +"---\n" +"- DELETE:\n" +" total: 0\n" +" rps: 0\n" +" COMMIT:\n" +" total: 0\n" +" rps: 0\n" +" SELECT:\n" +" total: 12\n" +" rps: 0\n" +" ROLLBACK:\n" +" total: 0\n" +" rps: 0\n" +" INSERT:\n" +" total: 6\n" +" rps: 0\n" +" EVAL:\n" +" total: 0\n" +" rps: 0\n" +" ERROR:\n" +" total: 0\n" +" rps: 0\n" +" CALL:\n" +" total: 0\n" +" rps: 0\n" +" BEGIN:\n" +" total: 0\n" +" rps: 0\n" +" PREPARE:\n" +" total: 0\n" +" rps: 0\n" +" REPLACE:\n" +" total: 0\n" +" rps: 0\n" +" UPSERT:\n" +" total: 0\n" +" rps: 0\n" +" AUTH:\n" +" total: 0\n" +" rps: 0\n" +" EXECUTE:\n" +" total: 0\n" +" rps: 0\n" +" UPDATE:\n" +" total: 2\n" +" rps: 0\n" +"...\n" +"\n" +"tarantool> box.stat().DELETE -- total + requests per second from one table\n" +"---\n" +"- total: 0\n" +" rps: 0\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_stat/vinyl.pot b/locale/en/reference/reference_lua/box_stat/vinyl.pot new file mode 100644 index 0000000000..705f0b3455 --- /dev/null +++ b/locale/en/reference/reference_lua/box_stat/vinyl.pot @@ -0,0 +1,176 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:4 +msgid "box.stat.vinyl()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:10 +msgid "Shows vinyl-storage-engine activity, for example ``box.stat.vinyl().tx`` has the number of commits and rollbacks." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:13 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:15 +msgid "tarantool> box.stat.vinyl().tx.commit -- one item of the vinyl table\n" +"---\n" +"- 1047632\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:25 +msgid "box.stat.vinyl().regulator" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:26 +msgid "The vinyl regulator decides when to take or delay actions for disk IO, grouping activity in batches so that it is consistent and efficient. The regulator is invoked by the vinyl scheduler, once per second, and updates related variables whenever it is invoked." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:32 +msgid "``box.stat.vinyl().regulator.dump_bandwidth`` is the estimated average rate at which dumps are done. Initially this will appear as 10485760 (10 megabytes per second). Only significant dumps (larger than one megabyte) are used for estimating." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:37 +msgid "``box.stat.vinyl().regulator.dump_watermark`` is the point when dumping must occur. The value is slightly smaller than the amount of memory that is allocated for vinyl trees, which is the :ref:`vinyl_memory ` parameter." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:43 +msgid "``box.stat.vinyl().regulator.write_rate`` is the actual average rate at which recent writes to disk are done. Averaging is done over a 5-second time window, so if there has been no activity for 5 seconds then ``regulator.write_rate = 0``. The ``write_rate`` may be slowed when a dump is in progress or when the user has set :ref:`snap_io_rate_limit `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:51 +msgid "``box.stat.vinyl().regulator.rate_limit`` is the write rate limit, in bytes per second, imposed on transactions by the regulator based on the observed dump/compaction performance." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:55 +msgid "``box.stat.vinyl().regulator.blocked_writers`` is the number of fibers currently blocked waiting for vinyl :ref:`L0 memory ` quota." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:63 +msgid "box.stat.vinyl().disk" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:64 +msgid "Since vinyl is an on-disk storage engine (unlike memtx which is an in-memory storage engine), it can handle large databases -- but if a database is larger than the amount of memory that is allocated for vinyl, then there will be more disk activity." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:70 +msgid "``box.stat.vinyl().disk.data`` and ``box.stat.vinyl().disk.index`` are the amount of data that has gone into files in a subdirectory of :ref:`vinyl_dir `, with names like ``{lsn}.run`` and ``{lsn}.index``. The size of the run will be related to the output of ``scheduler.dump_*``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:77 +msgid "``box.stat.vinyl().disk.data_compacted`` Sum size of data stored at the last LSM tree level, in bytes, without taking disk compression into account. It can be thought of as the size of disk space that the user data would occupy if there were no compression, indexing, or space increase caused by the LSM tree design." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:86 +msgid "box.stat.vinyl().memory" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:87 +msgid "Although the vinyl storage engine is not \"in-memory\", Tarantool does need to have memory for write buffers and for caches:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:90 +msgid "``box.stat.vinyl().memory.tuple_cache`` is the number of bytes that are being used for tuples (data)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:92 +msgid "``box.stat.vinyl().memory.tx`` is transactional memory. This will usually be 0." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:94 +msgid "``box.stat.vinyl().memory.level0`` is the \"level0\" memory area, sometimes abbreviated \"L0\", which is the area that vinyl can use for in-memory storage of an LSM tree." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:98 +msgid "Therefore we can say that \"L0 is becoming full\" when the amount in ``memory.level0`` is close to the maximum, which is :ref:`regulator.dump_watermark `. We can expect that \"L0 = 0\" immediately after a dump. ``box.stat.vinyl().memory.page_index`` and ``box.stat.vinyl().memory.bloom_filter`` have the current amount being used for index-related structures. The size is a function of the number and size of keys, plus :ref:`vinyl_page_size `, plus :ref:`vinyl_bloom_fpr `. This is not a count of bloom filter \"hits\" (the number of reads that could be avoided because the bloom filter predicts their presence in a run file) -- that statistic can be found with :doc:`/reference/reference_lua/box_index/stat`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:116 +msgid "box.stat.vinyl().tx" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:117 +msgid "This is about requests that affect transactional activity (\"tx\" is used here as an abbreviation for \"transaction\"):" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:120 +msgid "``box.stat.vinyl().tx.conflict`` counts conflicts that caused a transaction to roll back." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:122 +msgid "``box.stat.vinyl().tx.commit`` is the count of commits (successful transaction ends). It includes implicit commits, for example any insert causes a commit unless it is within a begin-end block." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:126 +msgid "``box.stat.vinyl().tx.rollback`` is the count of rollbacks (unsuccessful transaction ends). This is not merely a count of explicit :doc:`/reference/reference_lua/box_txn_management/rollback` requests -- it includes requests that ended in errors. For example, after an attempted insert request that causes a \"Duplicate key exists in unique index\" error, ``tx.rollback`` is incremented." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:134 +msgid "``box.stat.vinyl().tx.statements`` will usually be 0." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:136 +msgid "``box.stat.vinyl().tx.transactions`` is the number of transactions that are currently running." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:138 +msgid "``box.stat.vinyl().tx.gap_locks`` is the number of gap locks that are outstanding during execution of a request. For a low-level description of Tarantool's implementation of gap locking, see `Gap locks in Vinyl transaction manager `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:142 +msgid "``box.stat.vinyl().tx.read_views`` shows whether a transaction has entered a read-only state to avoid conflict temporarily. This will usually be 0." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:147 +msgid "box.stat.vinyl().scheduler" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:148 +msgid "This primarily has counters related to tasks that the scheduler has arranged for dumping or compaction: (most of these items are reset to 0 when the server restarts or when :ref:`box.stat.reset() ` occurs):" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:153 +msgid "``box.stat.vinyl().scheduler.compaction_*`` is the amount of data from recent changes that has been :doc:`compacted `. This is divided into ``scheduler.compaction_input`` (the amount that is being compacted), ``scheduler.compaction_queue`` (the amount that is waiting to be compacted), ``scheduler.compaction_time`` (total time spent by all worker threads performing compaction, in seconds), and ``scheduler.compaction_output`` (the amount that has been compacted, which is presumably smaller than ``scheduler.compaction_input``)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:163 +msgid "``box.stat.vinyl().scheduler.tasks_*`` is about dump/compaction tasks, in three categories, ``scheduler.tasks_inprogress`` (currently running), ``scheduler.tasks_completed`` (successfully completed) ``scheduler.tasks_failed`` (aborted due to errors)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:169 +msgid "``box.stat.vinyl().scheduler.dump_*`` has the amount of data from recent changes that has been dumped, including ``dump_time`` (total time spent by all worker threads performing dumps, in seconds), and ``dump_count`` (the count of completed dumps), ``dump_input`` and ``dump_output``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:175 +msgid "A \"dump\" is explained in section :ref:`Storing data with vinyl `:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:177 +msgid "Sooner or later the number of elements in an LSM tree exceeds the L0 size and that is when L0 gets written to a file on disk (called a 'run') and then cleared for storing new elements. This operation is called a 'dump'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:181 +msgid "Thus it can be predicted that a dump will occur if the size of L0 (which is :ref:`memory.level0 `) is approaching the maximum (which is :ref:`regulator.dump_watermark `) and a dump is not already in progress. In fact Tarantool will try to arrange a dump before this hard limit is reached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_stat/vinyl.rst:191 +msgid "A dump will also occur during a :doc:`snapshot ` operation." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple.pot b/locale/en/reference/reference_lua/box_tuple.pot new file mode 100644 index 0000000000..925eb7749c --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple.pot @@ -0,0 +1,213 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple.rst:5 +msgid "Submodule box.tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:7 +msgid "The ``box.tuple`` submodule provides read-only access for the ``tuple`` userdata type. It allows, for a single :ref:`tuple `: selective retrieval of the field contents, retrieval of information about size, iteration over all the fields, and conversion to a `Lua table `_." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:12 +msgid "Below is a list of all ``box.tuple`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:23 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:24 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:26 +msgid ":doc:`./box_tuple/new`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:27 +msgid "Create a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:29 +msgid ":doc:`./box_tuple/is`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:30 +msgid "Check whether a given object is a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:32 +msgid ":doc:`./box_tuple/count_fields`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:33 +msgid "Count tuple fields" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:35 +msgid ":doc:`./box_tuple/bsize`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:36 +msgid "Get count of bytes in a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:38 +msgid ":doc:`./box_tuple/field_number`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:39 +msgid "Get a tuple's field by specifying a number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:41 +msgid ":doc:`./box_tuple/field_name`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:42 +msgid "Get a tuple's field by specifying a name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:44 +msgid ":doc:`./box_tuple/field_path`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:45 +msgid "Get a tuple's fields or parts by specifying a path" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:47 +msgid ":doc:`./box_tuple/find`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:48 +msgid "Get the number of the first field/all fields matching the search value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:50 +msgid ":doc:`./box_tuple/next`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:51 +msgid "Get the next field value from tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:53 +msgid ":doc:`./box_tuple/pairs`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:54 +msgid "Prepare for iterating" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:56 +msgid ":doc:`./box_tuple/totable`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:57 +msgid "Get a tuple's fields as a table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:59 +msgid ":doc:`./box_tuple/tomap`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:60 +msgid "Get a tuple's fields as a table along with key:value pairs" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:62 +msgid ":doc:`./box_tuple/transform`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:63 +msgid "Remove (and replace) a tuple's fields" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:65 +msgid ":doc:`./box_tuple/unpack`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:66 +msgid "Get a tuple's fields" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:68 +msgid ":doc:`./box_tuple/update`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:69 +msgid "Update a tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:71 +msgid ":doc:`./box_tuple/upsert`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:72 +msgid "Update a tuple ignoring errors" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:96 +msgid "How to convert tuples to/from Lua tables" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:98 +msgid "This function will illustrate how to convert tuples to/from Lua tables and lists of scalars:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:101 +msgid "tuple = box.tuple.new({scalar1, scalar2, ... scalar_n}) -- scalars to tuple\n" +"lua_table = {tuple:unpack()} -- tuple to Lua table\n" +"lua_table = tuple:totable() -- tuple to Lua table\n" +"scalar1, scalar2, ... scalar_n = tuple:unpack() -- tuple to scalars\n" +"tuple = box.tuple.new(lua_table) -- Lua table to tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:109 +msgid "Then it will find the field that contains 'b', remove that field from the tuple, and display how many bytes remain in the tuple. The function uses Tarantool ``box.tuple`` functions ``new()``, ``unpack()``, ``find()``, ``transform()``, ``bsize()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:114 +msgid "function example()\n" +" local tuple1, tuple2, lua_table_1, scalar1, scalar2, scalar3, field_number\n" +" local luatable1 = {}\n" +" tuple1 = box.tuple.new({'a', 'b', 'c'})\n" +" luatable1 = tuple1:totable()\n" +" scalar1, scalar2, scalar3 = tuple1:unpack()\n" +" tuple2 = box.tuple.new(luatable1[1],luatable1[2],luatable1[3])\n" +" field_number = tuple2:find('b')\n" +" tuple2 = tuple2:transform(field_number, 1)\n" +" return 'tuple2 = ' , tuple2 , ' # of bytes = ' , tuple2:bsize()\n" +"end" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:128 +msgid "... And here is what happens when one invokes the function:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple.rst:130 +msgid "tarantool> example()\n" +"---\n" +"- tuple2 =\n" +"- ['a', 'c']\n" +"- ' # of bytes = '\n" +"- 5\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/bsize.pot b/locale/en/reference/reference_lua/box_tuple/bsize.pot new file mode 100644 index 0000000000..6f752ccc16 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/bsize.pot @@ -0,0 +1,59 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:6 +msgid "box.tuple.bsize()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:12 +msgid "If ``t`` is a tuple instance, ``t:bsize()`` will return the number of bytes in the tuple. With both the memtx storage engine and the vinyl storage engine the default maximum is one megabyte (:ref:`memtx_max_tuple_size ` or :ref:`vinyl_max_tuple_size `). Every field has one or more \"length\" bytes preceding the actual contents, so ``bsize()`` returns a value which is slightly greater than the sum of the lengths of the contents." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:21 +msgid "The value does not include the size of \"struct tuple\" (for the current size of this structure look in the `tuple.h `_ file in Tarantool's source code)." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:26 +msgid "number of bytes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:27 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:29 +msgid "In the following example, a tuple named ``t`` is created which has three fields, and for each field it takes one byte to store the length and three bytes to store the contents, and then there is one more byte to store a count of the number of fields, so ``bsize()`` returns ``3*(1+3)+1``. This is the same as the size of the string that :ref:`msgpack.encode({'aaa','bbb','ccc'}) ` would return." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/bsize.rst:37 +msgid "tarantool> t = box.tuple.new{'aaa', 'bbb', 'ccc'}\n" +"---\n" +"...\n" +"tarantool> t:bsize()\n" +"---\n" +"- 13\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/count_fields.pot b/locale/en/reference/reference_lua/box_tuple/count_fields.pot new file mode 100644 index 0000000000..8085127443 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/count_fields.pot @@ -0,0 +1,47 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:6 +msgid "#tuple_object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:12 +msgid "The ``#`` operator in Lua means \"return count of components\". So, if ``t`` is a tuple instance, ``#t`` will return the number of fields." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:15 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:17 +msgid "In the following example, a tuple named ``t`` is created and then the number of fields in ``t`` is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/count_fields.rst:20 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4'}\n" +"---\n" +"...\n" +"tarantool> #t\n" +"---\n" +"- 4\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/field_name.pot b/locale/en/reference/reference_lua/box_tuple/field_name.pot new file mode 100644 index 0000000000..d2ba07e75c --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/field_name.pot @@ -0,0 +1,74 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:6 +msgid "tuple_object[field-name]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:12 +msgid "If ``t`` is a tuple instance, ``t['field-name']`` will return the field named 'field-name' in the tuple. Fields have names if the tuple has been retrieved from a space that has an associated :ref:`format `. :samp:`t[{lua-variable-name}]` will do the same thing if ``lua-variable-name`` contains ``'field-name'``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:18 +msgid "There is a variation which the `Lua manual `_ calls \"syntactic sugar\": use ``t.field-name`` as an equivalent of ``t['field-name']``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:23 +msgid "field value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:24 +msgid "lua-value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:26 +msgid "In the following example, a tuple named ``t`` is returned from ``replace`` and then the second field in ``t`` named 'field2' is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_name.rst:29 +msgid "tarantool> format = {}\n" +"---\n" +"...\n" +"tarantool> format[1] = {name = 'field1', type = 'unsigned'}\n" +"---\n" +"...\n" +"tarantool> format[2] = {name = 'field2', type = 'string'}\n" +"---\n" +"...\n" +"tarantool> s = box.schema.space.create('test', {format = format})\n" +"---\n" +"...\n" +"tarantool> pk = s:create_index('pk')\n" +"---\n" +"...\n" +"tarantool> t = s:replace{1, 'Я'}\n" +"---\n" +"...\n" +"tarantool> t['field2']\n" +"---\n" +"- Я\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/field_number.pot b/locale/en/reference/reference_lua/box_tuple/field_number.pot new file mode 100644 index 0000000000..51ea39a0b0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/field_number.pot @@ -0,0 +1,55 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:6 +msgid "tuple_object[field-number]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:12 +msgid "If ``t`` is a tuple instance, ``t[field-number]`` will return the field numbered field-number in the tuple. The first field is ``t[1]``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:15 +msgid "field value." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:16 +msgid "lua-value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:18 +msgid "In the following example, a tuple named ``t`` is created and then the second field in ``t`` is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_number.rst:21 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4'}\n" +"---\n" +"...\n" +"tarantool> t[2]\n" +"---\n" +"- Fld#2\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/field_path.pot b/locale/en/reference/reference_lua/box_tuple/field_path.pot new file mode 100644 index 0000000000..627f56d33a --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/field_path.pot @@ -0,0 +1,69 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:6 +msgid "tuple_object[field-path]" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:12 +msgid "If ``t`` is a tuple instance, ``t['path']`` will return the field or subset of fields that are in ``path``. ``path`` must be a well formed JSON specification. ``path`` may contain field names if the tuple has been retrieved from a space that has an associated :ref:`format `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:17 +msgid "To prevent ambiguity, Tarantool first tries to interpret the request as :doc:`/reference/reference_lua/box_tuple/field_number` or :doc:`/reference/reference_lua/box_tuple/field_name`. If and only if that fails, Tarantool tries to interpret the request as ``tuple_object[field-path]``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:23 +msgid "The path must be a well formed JSON specification, but it may be preceded by '.'. The '.' is a signal that the path acts as a suffix for the tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:27 +msgid "The advantage of specifying a path is that Tarantool will use it to search through a tuple body and get only the tuple part, or parts, that are actually necessary." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:31 +msgid "In the following example, a tuple named ``t`` is returned from ``replace`` and then only the relevant part (in this case, matching a name) of a relevant field is returned. Namely: the second field, its third item, the value following 'key='." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/field_path.rst:36 +msgid "tarantool> format = {}\n" +"---\n" +"...\n" +"tarantool> format[1] = {name = 'field1', type = 'unsigned'}\n" +"---\n" +"...\n" +"tarantool> format[2] = {name = 'field2', type = 'array'}\n" +"---\n" +"...\n" +"tarantool> s = box.schema.space.create('test', {format = format})\n" +"---\n" +"...\n" +"tarantool> pk = s:create_index('pk')\n" +"---\n" +"...\n" +"tarantool> field2_value = {1, \"ABC\", {key=\"Hello\", value=\"world\"}}\n" +"---\n" +"...\n" +"tarantool> t = s:replace{1, field2_value}\n" +"---\n" +"...\n" +"tarantool> t[\"[2][3]['key']\"]\n" +"---\n" +"- Hello\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/find.pot b/locale/en/reference/reference_lua/box_tuple/find.pot new file mode 100644 index 0000000000..0a65547a01 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/find.pot @@ -0,0 +1,64 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:6 +msgid "tuple_object:find(), tuple_object:findall()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:13 +msgid "If ``t`` is a tuple instance, ``t:find(search-value)`` will return the number of the first field in ``t`` that matches the search value, and ``t:findall(search-value [, search-value ...])`` will return numbers of all fields in ``t`` that match the search value. Optionally one can put a numeric argument ``field-number`` before the search-value to indicate “start searching at field number ``field-number``.”" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:20 +msgid "the number of the field in the tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:21 +msgid "number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:23 +msgid "In the following example, a tuple named ``t`` is created and then: the number of the first field in ``t`` which matches 'a' is returned, then the numbers of all the fields in ``t`` which match 'a' are returned, then the numbers of all the fields in t which match 'a' and are at or after the second field are returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/find.rst:29 +msgid "tarantool> t = box.tuple.new{'a', 'b', 'c', 'a'}\n" +"---\n" +"...\n" +"tarantool> t:find('a')\n" +"---\n" +"- 1\n" +"...\n" +"tarantool> t:findall('a')\n" +"---\n" +"- 1\n" +"- 4\n" +"...\n" +"tarantool> t:findall(2, 'a')\n" +"---\n" +"- 4\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/is.pot b/locale/en/reference/reference_lua/box_tuple/is.pot new file mode 100644 index 0000000000..ecc52b65ac --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/is.pot @@ -0,0 +1,41 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:6 +msgid "box.tuple.is()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:12 +msgid "Since versions :doc:`2.2.3 `, :doc:`2.3.2 `, and :doc:`2.4.1 `. A function to check whether a given object is a tuple cdata object. Never raises nor returns an error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:17 +msgid "true or false" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/is.rst:18 +msgid "boolean" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/new.pot b/locale/en/reference/reference_lua/box_tuple/new.pot new file mode 100644 index 0000000000..dcbb3b7982 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/new.pot @@ -0,0 +1,74 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:5 +msgid "box.tuple.new()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:11 +msgid "Construct a new tuple from either a scalar or a Lua table. Alternatively, one can get new tuples from Tarantool's :ref:`select ` or :ref:`insert ` or :ref:`replace ` or :ref:`update ` requests, which can be regarded as statements that do ``new()`` implicitly." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:18 +msgid "the value that will become the tuple contents." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:20 +msgid "a new tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:21 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:23 +msgid "In the following example, ``x`` will be a new table object containing one tuple and ``t`` will be a new tuple object. Saying ``t`` returns the entire tuple ``t``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:27 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/new.rst:29 +msgid "tarantool> x = box.space.tester:insert{\n" +" > 33,\n" +" > tonumber('1'),\n" +" > tonumber64('2')\n" +" > }:totable()\n" +"---\n" +"...\n" +"tarantool> t = box.tuple.new{'abc', 'def', 'ghi', 'abc'}\n" +"---\n" +"...\n" +"tarantool> t\n" +"---\n" +"- ['abc', 'def', 'ghi', 'abc']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/next.pot b/locale/en/reference/reference_lua/box_tuple/next.pot new file mode 100644 index 0000000000..02c9fc8e84 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/next.pot @@ -0,0 +1,79 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:6 +msgid "tuple_object:next()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:12 +msgid "An analogue of the Lua ``next()`` function, but for a tuple object. When called without arguments, ``tuple:next()`` returns the first field from a tuple. Otherwise, it returns the field next to the indicated position." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:16 +msgid "However ``tuple:next()`` is not really efficient, and it is better to use :doc:`tuple:pairs()/ipairs() `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:20 +msgid "field number and field value" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:21 +msgid "number and field type" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/next.rst:23 +msgid "tarantool> tuple = box.tuple.new({5, 4, 3, 2, 0})\n" +"---\n" +"...\n" +"\n" +"tarantool> tuple:next()\n" +"---\n" +"- 1\n" +"- 5\n" +"...\n" +"\n" +"tarantool> tuple:next(1)\n" +"---\n" +"- 2\n" +"- 4\n" +"...\n" +"\n" +"tarantool> ctx, field = tuple:next()\n" +"---\n" +"...\n" +"\n" +"tarantool> while field do\n" +" > print(field)\n" +" > ctx, field = tuple:next(ctx)\n" +" > end\n" +"5\n" +"4\n" +"3\n" +"2\n" +"0\n" +"---\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/pairs.pot b/locale/en/reference/reference_lua/box_tuple/pairs.pot new file mode 100644 index 0000000000..eb33ddaa4e --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/pairs.pot @@ -0,0 +1,67 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:6 +msgid "tuple_object:pairs(), tuple_object:ipairs()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:13 +msgid "In Lua, `lua-table-value:pairs() `_ is a method which returns: ``function``, ``lua-table-value``, ``nil``. Tarantool has extended this so that ``tuple-value:pairs()`` returns: ``function``, ``tuple-value``, ``nil``. It is useful for Lua iterators, because Lua iterators traverse a value's components until an end marker is reached." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:20 +msgid "``tuple_object:ipairs()`` is the same as ``pairs()``, because tuple fields are always integers." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:23 +msgid "function, tuple-value, nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:24 +msgid "function, lua-value, nil" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:26 +msgid "In the following example, a tuple named ``t`` is created and then all its fields are selected using a Lua for-end loop." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/pairs.rst:29 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5'}\n" +"---\n" +"...\n" +"tarantool> tmp = ''\n" +"---\n" +"...\n" +"tarantool> for k, v in t:pairs() do\n" +" > tmp = tmp .. v\n" +" > end\n" +"---\n" +"...\n" +"tarantool> tmp\n" +"---\n" +"- Fld#1Fld#2Fld#3Fld#4Fld#5\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/tomap.pot b/locale/en/reference/reference_lua/box_tuple/tomap.pot new file mode 100644 index 0000000000..8fb0df3fbf --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/tomap.pot @@ -0,0 +1,98 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:6 +msgid "tuple_object:tomap()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:12 +msgid "A `Lua table `_ can have indexed values, also called key:value pairs. For example, here:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:16 +msgid "a = {}; a['field1'] = 10; a['field2'] = 20" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:20 +msgid "``a`` is a table with \"field1: 10\" and \"field2: 20\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:22 +msgid "The :doc:`/reference/reference_lua/box_tuple/totable` function only returns a table containing the values. But the ``tuple_object:tomap()`` function returns a table containing not only the values, but also the key:value pairs." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:27 +msgid "This only works if the tuple comes from a space that has been formatted with a :ref:`format clause `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:30 +msgid "the only possible option is ``names_only``. If ``names_only`` is false or omitted (default), then all the fields will appear twice, first with numeric headings and second with name headings. If ``names_only`` is true, then all the fields will appear only once, with name headings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:30 +msgid "the only possible option is ``names_only``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:32 +msgid "If ``names_only`` is false or omitted (default), then all the fields will appear twice, first with numeric headings and second with name headings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:37 +msgid "If ``names_only`` is true, then all the fields will appear only once, with name headings." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:41 +msgid "field-number:value pair(s) and key:value pair(s) from the tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:42 +msgid "lua-table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:44 +msgid "In the following example, a tuple named ``t1`` is returned from a space that has been formatted, then tables named ``t1map1`` and ``t1map2`` are produced from ``t1``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:48 +msgid "format = {{'field1', 'unsigned'}, {'field2', 'unsigned'}}\n" +"s = box.schema.space.create('test', {format = format})\n" +"s:create_index('pk',{parts={1,'unsigned',2,'unsigned'}})\n" +"t1 = s:insert{10, 20}\n" +"t1map = t1:tomap()\n" +"t1map_names_only = t1:tomap({names_only=true})" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:57 +msgid "``t1map`` will contain \"1: 10\", \"2: 20\", \"field1: 10\", \"field2: 20\"." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/tomap.rst:59 +msgid "``t1map_names_only`` will contain \"field1: 10\", \"field2: 20\"." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/totable.pot b/locale/en/reference/reference_lua/box_tuple/totable.pot new file mode 100644 index 0000000000..2a11e0fcf0 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/totable.pot @@ -0,0 +1,59 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:6 +msgid "tuple_object:totable()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:12 +msgid "If ``t`` is a tuple instance, ``t:totable()`` will return all fields, ``t:totable(1)`` will return all fields starting with field number 1, ``t:totable(1,5)`` will return all fields between field number 1 and field number 5." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:16 +msgid "It is preferable to use ``t:totable()`` rather than ``t:unpack()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:18 +msgid "field(s) from the tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:19 +msgid "lua-table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:21 +msgid "In the following example, a tuple named ``t`` is created, then all its fields are selected, then the result is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/totable.rst:24 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5'}\n" +"---\n" +"...\n" +"tarantool> t:totable()\n" +"---\n" +"- ['Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/transform.pot b/locale/en/reference/reference_lua/box_tuple/transform.pot new file mode 100644 index 0000000000..a8c79d3d07 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/transform.pot @@ -0,0 +1,64 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:6 +msgid "tuple_object:transform()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:12 +msgid "If ``t`` is a tuple instance, :samp:`t:transform({start-field-number},{fields-to-remove})` will return a tuple where, starting from field ``start-field-number``, a number of fields (``fields-to-remove``) are removed. Optionally one can add more arguments after ``fields-to-remove`` to indicate new values that will replace what was removed." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:19 +msgid "If the original tuple comes from a space that has been formatted with a :ref:`format clause `, the formatting will not be preserved for the result tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:23 +msgid "base 1, may be negative" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:26 +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:27 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:29 +msgid "In the following example, a tuple named ``t`` is created and then, starting from the second field, two fields are removed but one new one is added, then the result is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/transform.rst:33 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5'}\n" +"---\n" +"...\n" +"tarantool> t:transform(2, 2, 'x')\n" +"---\n" +"- ['Fld#1', 'x', 'Fld#4', 'Fld#5']\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/unpack.pot b/locale/en/reference/reference_lua/box_tuple/unpack.pot new file mode 100644 index 0000000000..2f342a2f4b --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/unpack.pot @@ -0,0 +1,59 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:6 +msgid "tuple_object:unpack()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:12 +msgid "If ``t`` is a tuple instance, ``t:unpack()`` will return all fields, ``t:unpack(1)`` will return all fields starting with field number 1, ``t:unpack(1,5)`` will return all fields between field number 1 and field number 5." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:16 +msgid "field(s) from the tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:17 +msgid "lua-value(s)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:19 +msgid "In the following example, a tuple named ``t`` is created and then all its fields are selected, then the result is returned." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/unpack.rst:22 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5'}\n" +"---\n" +"...\n" +"tarantool> t:unpack()\n" +"---\n" +"- Fld#1\n" +"- Fld#2\n" +"- Fld#3\n" +"- Fld#4\n" +"- Fld#5\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/update.pot b/locale/en/reference/reference_lua/box_tuple/update.pot new file mode 100644 index 0000000000..128529cd54 --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/update.pot @@ -0,0 +1,87 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:6 +msgid "tuple_object:update()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:12 +msgid "Update a tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:14 +msgid "This function updates a tuple which is not in a space. Compare the function :extsamp:`box.space.{*{space-name}*}:update({*{key}*}, {{{*{format}*}, {*{field_no}*}, {*{value}*}}, ...})` which updates a tuple in a space." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:18 +msgid "For details: see the description for ``operator``, ``field_no``, and ``value`` in the section :ref:`box.space.space-name:update{key, format, {field_number, value}...) `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:22 +msgid "If the original tuple comes from a space that has been formatted with a :ref:`format clause `, the formatting will be preserved for the result tuple." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:26 +msgid "operation type represented in string (e.g. '``=``' for 'assign new value')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:28 +msgid "what field the operation will apply to. The field number can be negative, meaning the position from the end of tuple. (#tuple + negative field number + 1)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:32 +msgid "what value will be applied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:34 +msgid "new tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:35 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:37 +msgid "In the following example, a tuple named ``t`` is created and then its second field is updated to equal 'B'." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:40 +msgid "tarantool> t = box.tuple.new{'Fld#1', 'Fld#2', 'Fld#3', 'Fld#4', 'Fld#5'}\n" +"---\n" +"...\n" +"tarantool> t:update({{'=', 2, 'B'}})\n" +"---\n" +"- ['Fld#1', 'B', 'Fld#3', 'Fld#4', 'Fld#5']\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/update.rst:50 +msgid "Since Tarantool 2.3 a tuple can also be updated via :ref:`JSON paths`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_tuple/upsert.pot b/locale/en/reference/reference_lua/box_tuple/upsert.pot new file mode 100644 index 0000000000..eda8ffb84e --- /dev/null +++ b/locale/en/reference/reference_lua/box_tuple/upsert.pot @@ -0,0 +1,96 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:6 +msgid "tuple_object:upsert()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:12 +msgid "The same as ``tuple_object:update()``, but ignores errors. In case of an error the tuple is left intact, but an error message is printed. Only client errors are ignored, such as a bad field type, or wrong field index/name. System errors, such as OOM, are not ignored and raised just like with a normal ``update()``. Note that only bad operations are ignored. All correct operations are applied." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:20 +msgid "operation type represented as a string (e.g. '``=``' for 'assign new value')" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:22 +msgid "the field to which the operation will be applied. The field number can be negative, meaning the position from the end of tuple. (#tuple + negative field number + 1)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:26 +msgid "the value which will be applied" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:28 +msgid "new tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:29 +msgid "tuple" +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:31 +msgid "See the following example where one operation is applied, and one is not." +msgstr "" + +#: ../../doc/reference/reference_lua/box_tuple/upsert.rst:33 +msgid "tarantool> t = box.tuple.new({1, 2, 3})\n" +"tarantool> t2 = t:upsert({{'=', 5, 100}})\n" +"UPSERT operation failed:\n" +"ER_NO_SUCH_FIELD_NO: Field 5 was not found in the tuple\n" +"---\n" +"...\n" +"\n" +"tarantool> t\n" +"---\n" +"- [1, 2, 3]\n" +"...\n" +"\n" +"tarantool> t2\n" +"---\n" +"- [1, 2, 3]\n" +"...\n" +"\n" +"tarantool> t2 = t:upsert({{'=', 5, 100}, {'+', 1, 3}})\n" +"UPSERT operation failed:\n" +"ER_NO_SUCH_FIELD_NO: Field 5 was not found in the tuple\n" +"---\n" +"...\n" +"\n" +"tarantool> t\n" +"---\n" +"- [1, 2, 3]\n" +"...\n" +"\n" +"tarantool> t2\n" +"---\n" +"- [4, 2, 3]\n" +"..." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management.pot b/locale/en/reference/reference_lua/box_txn_management.pot new file mode 100644 index 0000000000..a8d92ac807 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management.pot @@ -0,0 +1,137 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:5 +msgid "Functions for transaction management" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:7 +msgid "For general information and examples, see section :ref:`Transactions `." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:10 +msgid "Observe the following rules when working with transactions:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:12 +msgid "Rule #1" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:15 +msgid "The requests in a transaction must be sent to a server as a single block. It is not enough to enclose them between begin and commit or rollback. To ensure they are sent as a single block: put them in a function, or put them all on one line, or use a delimiter so that multi-line requests are handled together." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:21 +msgid "Rule #2" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:24 +msgid "All database operations in a transaction should use the same storage engine. It is not safe to access tuple sets that are defined with ``{engine='vinyl'}`` and also access tuple sets that are defined with ``{engine='memtx'}``, in the same transaction." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:29 +msgid "Rule #3" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:32 +msgid "Requests which cause changes to the data definition -- create, alter, drop, truncate -- are only allowed with Tarantool version 2.1 or later. Data-definition requests which change an index or change a format, such as :doc:`space_object:create_index() ` and :ref:`space_object:format() `, are not allowed inside transactions except as the first request after ``box.begin()``." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:43 +msgid "Below is a list of all functions for transaction management." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:54 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:55 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:57 +msgid ":doc:`./box_txn_management/begin`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:58 +msgid "Begin the transaction" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:60 +msgid ":doc:`./box_txn_management/commit`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:61 +msgid "End the transaction and save all changes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:63 +msgid ":doc:`./box_txn_management/rollback`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:64 +msgid "End the transaction and discard all changes" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:66 +msgid ":doc:`./box_txn_management/savepoint`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:67 +msgid "Get a savepoint descriptor" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:69 +msgid ":doc:`./box_txn_management/rollback_to_savepoint`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:70 +msgid "Do not end the transaction and discard all changes made after a savepoint" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:73 +msgid ":doc:`./box_txn_management/atomic`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:74 +msgid "Execute a function, treating it as a transaction" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:76 +msgid ":doc:`./box_txn_management/on_commit`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:77 +msgid "Define a trigger that will be activated by ``box.commit``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:79 +msgid ":doc:`./box_txn_management/on_rollback`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:80 +msgid "Define a trigger that will be activated by ``box.rollback``" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:82 +msgid ":doc:`./box_txn_management/is_in_txn`" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management.rst:83 +msgid "State whether a transaction is in progress" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/atomic.pot b/locale/en/reference/reference_lua/box_txn_management/atomic.pot new file mode 100644 index 0000000000..f9007b0dca --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/atomic.pot @@ -0,0 +1,109 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:5 +msgid "box.atomic()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:9 +msgid "Execute a function, acting as if the function starts with an implicit :doc:`/reference/reference_lua/box_txn_management/begin` and ends with an implicit :doc:`/reference/reference_lua/box_txn_management/commit` if successful, or ends with an implicit :doc:`/reference/reference_lua/box_txn_management/rollback` if there is an error." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:14 +msgid "(optional) transaction options: * ``txn_isolation`` -- the :ref:`transaction isolation level ` * ``timeout`` -- a timeout (in seconds), after which the transaction is rolled back" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:14 +msgid "(optional) transaction options:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:16 +msgid "``txn_isolation`` -- the :ref:`transaction isolation level `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:17 +msgid "``timeout`` -- a timeout (in seconds), after which the transaction is rolled back" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:19 +msgid "the function name" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:21 +msgid "(optional) arguments passed to the function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:23 +msgid "the result of the function passed to ``atomic()`` as an argument" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:25 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:27 +msgid "error and abort the transaction in case of a conflict." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:28 +msgid "error and abort the transaction if the timeout is exceeded." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:29 +msgid "error if the operation fails to write to disk." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:30 +msgid "error if for some reason memory cannot be allocated." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:33 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/atomic.rst:35 +msgid "-- Create an index with the specified sequence --\n" +"box.schema.sequence.create('id_sequence', { min = 1 })\n" +"box.space.bands:create_index('primary', { parts = { 'id' }, sequence = 'id_sequence' })\n" +"\n" +"-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Define a function --\n" +"local function insert_band(band_name, year)\n" +" box.space.bands:insert { nil, band_name, year }\n" +"end\n" +"\n" +"-- Begin and commit the transaction implicitly --\n" +"box.atomic(insert_band, 'The Beatles', 1960)\n" +"\n" +"-- Begin the transaction with the specified isolation level --\n" +"box.atomic({ txn_isolation = 'read-committed' },\n" +" insert_band, 'The Rolling Stones', 1962)\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/begin.pot b/locale/en/reference/reference_lua/box_txn_management/begin.pot new file mode 100644 index 0000000000..c6a051c476 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/begin.pot @@ -0,0 +1,85 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:4 +msgid "box.begin()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:8 +msgid "Begin the transaction. Disable :ref:`implicit yields ` until the transaction ends. Signal that writes to the :ref:`write-ahead log ` will be deferred until the transaction ends. In effect the fiber which executes ``box.begin()`` is starting an \"active multi-request transaction\", blocking all other fibers." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:15 +msgid "(optional) transaction options: * ``txn_isolation`` -- the :ref:`transaction isolation level ` * ``timeout`` -- a timeout (in seconds), after which the transaction is rolled back" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:15 +msgid "(optional) transaction options:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:17 +msgid "``txn_isolation`` -- the :ref:`transaction isolation level `" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:18 +msgid "``timeout`` -- a timeout (in seconds), after which the transaction is rolled back" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:20 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:22 +msgid "error if this operation is not permitted because there is already an active transaction." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:23 +msgid "error if for some reason memory cannot be allocated." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:24 +msgid "error and abort the transaction if the timeout is exceeded." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:26 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/begin.rst:28 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Begin and commit the transaction explicitly --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:replace { 1, 'Pink Floyd', 1965 }\n" +"box.commit()\n" +"\n" +"-- Begin the transaction with the specified isolation level --\n" +"box.begin({ txn_isolation = 'read-committed' })\n" +"box.space.bands:insert { 5, 'The Rolling Stones', 1962 }\n" +"box.space.bands:replace { 1, 'The Doors', 1965 }\n" +"box.commit()\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/commit.pot b/locale/en/reference/reference_lua/box_txn_management/commit.pot new file mode 100644 index 0000000000..ff892275c8 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/commit.pot @@ -0,0 +1,65 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:5 +msgid "box.commit()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:9 +msgid "End the transaction, and make all its data-change operations permanent." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:11 +msgid "**Possible errors:**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:13 +msgid "error and abort the transaction in case of a conflict." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:14 +msgid "error if the operation fails to write to disk." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:15 +msgid "error if for some reason memory cannot be allocated." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:17 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/commit.rst:19 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Begin and commit the transaction explicitly --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:replace { 1, 'Pink Floyd', 1965 }\n" +"box.commit()\n" +"\n" +"-- Begin the transaction with the specified isolation level --\n" +"box.begin({ txn_isolation = 'read-committed' })\n" +"box.space.bands:insert { 5, 'The Rolling Stones', 1962 }\n" +"box.space.bands:replace { 1, 'The Doors', 1965 }\n" +"box.commit()\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/is_in_txn.pot b/locale/en/reference/reference_lua/box_txn_management/is_in_txn.pot new file mode 100644 index 0000000000..62247b55b6 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/is_in_txn.pot @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/is_in_txn.rst:5 +msgid "box.is_in_txn()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/is_in_txn.rst:9 +msgid "If a transaction is in progress (for example the user has called :doc:`/reference/reference_lua/box_txn_management/begin` and has not yet called either :doc:`/reference/reference_lua/box_txn_management/commit` or :doc:`/reference/reference_lua/box_txn_management/rollback`, return ``true``. Otherwise return ``false``." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/on_commit.pot b/locale/en/reference/reference_lua/box_txn_management/on_commit.pot new file mode 100644 index 0000000000..d2ab517664 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/on_commit.pot @@ -0,0 +1,164 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:5 +msgid "box.on_commit()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:9 +msgid "Define a trigger for execution when a transaction ends due to an event such as :doc:`/reference/reference_lua/box_txn_management/commit`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:12 +msgid "The trigger function may take an iterator parameter, as described in an example for this section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:15 +msgid "The trigger function should not access any database spaces." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:17 +msgid "If the trigger execution fails and raises an error, the effect is severe and should be avoided -- use Lua's ``pcall()`` mechanism around code that might fail." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:21 +msgid "``box.on_commit()`` must be invoked within a transaction, and the trigger ceases to exist when the transaction ends." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:24 +msgid "function which will become the trigger function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:26 +msgid "existing trigger function which will be replaced by trigger-function" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:28 +msgid "nil or function pointer" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:30 +msgid "If the parameters are ``(nil, old-trigger-function)``, then the old trigger is deleted." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:33 +msgid "Details about trigger characteristics are in the :ref:`triggers ` section." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:36 +msgid "**Example 1**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:38 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Define a function called on commit --\n" +"function print_commit_result()\n" +" print('Commit happened')\n" +"end\n" +"\n" +"-- Commit the transaction --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.on_commit(print_commit_result)\n" +"box.commit()\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:43 +msgid "**Example 2**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:45 +msgid "The function parameter can be an iterator. The iterator goes through the effects of every request that changed a space during the transaction." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:49 +msgid "The iterator has:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:51 +msgid "an ordinal request number" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:52 +msgid "the old value of the tuple before the request (``nil`` for an ``insert`` request)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:54 +msgid "the new value of the tuple after the request (``nil`` for a ``delete`` request)" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:56 +msgid "the ID of the space" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:58 +msgid "The example below displays the effects of two ``replace`` requests:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:60 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Define a function called on commit --\n" +"function print_replace_details(iterator)\n" +" for request_number, old_tuple, new_tuple, space_id in iterator() do\n" +" print('request_number: ' .. tostring(request_number))\n" +" print('old_tuple: ' .. tostring(old_tuple))\n" +" print('new_tuple: ' .. tostring(new_tuple))\n" +" print('space_id: ' .. tostring(space_id))\n" +" end\n" +"end\n" +"\n" +"-- Commit the transaction --\n" +"box.begin()\n" +"box.space.bands:replace { 1, 'The Beatles', 1960 }\n" +"box.space.bands:replace { 2, 'The Rolling Stones', 1965 }\n" +"box.on_commit(print_replace_details)\n" +"box.commit()\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:65 +msgid "The output might look like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_commit.rst:67 +msgid "request_number: 1\n" +"old_tuple: [1, 'Roxette', 1986]\n" +"new_tuple: [1, 'The Beatles', 1960]\n" +"space_id: 512\n" +"request_number: 2\n" +"old_tuple: [2, 'Scorpions', 1965]\n" +"new_tuple: [2, 'The Rolling Stones', 1965]\n" +"space_id: 512" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/on_rollback.pot b/locale/en/reference/reference_lua/box_txn_management/on_rollback.pot new file mode 100644 index 0000000000..e52634f02f --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/on_rollback.pot @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/on_rollback.rst:5 +msgid "box.on_rollback()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_rollback.rst:9 +msgid "Define a trigger for execution when a transaction ends due to an event such as :doc:`/reference/reference_lua/box_txn_management/rollback`." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/on_rollback.rst:12 +msgid "The parameters and warnings are exactly the same as for :doc:`/reference/reference_lua/box_txn_management/on_commit`." +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/rollback.pot b/locale/en/reference/reference_lua/box_txn_management/rollback.pot new file mode 100644 index 0000000000..9eebfbef7e --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/rollback.pot @@ -0,0 +1,43 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback.rst:5 +msgid "box.rollback()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback.rst:9 +msgid "End the transaction, but cancel all its data-change operations. An explicit call to functions outside ``box.space`` that always yield, such as :ref:`fiber.sleep() ` or :ref:`fiber.yield() `, will have the same effect." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback.rst:14 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback.rst:16 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Rollback the transaction --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"box.space.bands:replace { 1, 'Pink Floyd', 1965 }\n" +"box.rollback()\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/rollback_to_savepoint.pot b/locale/en/reference/reference_lua/box_txn_management/rollback_to_savepoint.pot new file mode 100644 index 0000000000..5b5e6e0771 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/rollback_to_savepoint.pot @@ -0,0 +1,57 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:5 +msgid "box.rollback_to_savepoint()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:9 +msgid "Do not end the transaction, but cancel all its data-change and :ref:`box.savepoint() ` operations that were done after the specified savepoint." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:13 +msgid "error if the savepoint cannot be set in absence of active transaction." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:16 +msgid "**Possible errors:** error if the savepoint does not exist." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:18 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/rollback_to_savepoint.rst:20 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Rollback the transaction to a savepoint --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"save1 = box.savepoint()\n" +"box.space.bands:replace { 1, 'Pink Floyd', 1965 }\n" +"box.rollback_to_savepoint(save1)\n" +"box.commit()\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/box_txn_management/savepoint.pot b/locale/en/reference/reference_lua/box_txn_management/savepoint.pot new file mode 100644 index 0000000000..8508fa2859 --- /dev/null +++ b/locale/en/reference/reference_lua/box_txn_management/savepoint.pot @@ -0,0 +1,70 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:5 +msgid "box.savepoint()" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:9 +msgid "Return a descriptor of a savepoint (type = table), which can be used later by :doc:`box.rollback_to_savepoint(savepoint) `. Savepoints can only be created while a transaction is active, and they are destroyed when a transaction ends." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:0 +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:14 +msgid "savepoint table" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:15 +msgid "Lua object" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:17 +msgid "error if the savepoint cannot be set in absence of active transaction." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:20 +msgid "**Possible errors:** error if for some reason memory cannot be allocated." +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:22 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/box_txn_management/savepoint.rst:24 +msgid "-- Insert test data --\n" +"box.space.bands:insert { 1, 'Roxette', 1986 }\n" +"box.space.bands:insert { 2, 'Scorpions', 1965 }\n" +"box.space.bands:insert { 3, 'Ace of Base', 1987 }\n" +"\n" +"-- Rollback the transaction to a savepoint --\n" +"box.begin()\n" +"box.space.bands:insert { 4, 'The Beatles', 1960 }\n" +"save1 = box.savepoint()\n" +"box.space.bands:replace { 1, 'Pink Floyd', 1965 }\n" +"box.rollback_to_savepoint(save1)\n" +"box.commit()\n" +"" +msgstr "" diff --git a/locale/en/reference/reference_lua/buffer.pot b/locale/en/reference/reference_lua/buffer.pot new file mode 100644 index 0000000000..6f446681ee --- /dev/null +++ b/locale/en/reference/reference_lua/buffer.pot @@ -0,0 +1,253 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/buffer.rst:5 +msgid "Module buffer" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:7 +msgid "The ``buffer`` module returns a dynamically resizable buffer which is solely for optional use by methods of the :ref:`net.box module ` or the :ref:`msgpack module `." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:11 +msgid "Ordinarily the ``net.box`` methods return a Lua table. If a ``buffer`` option is used, then the ``net.box`` methods return a :ref:`raw MsgPack string `. This saves time on the server, if the client application has its own routine for decoding raw MsgPack strings." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:19 +msgid "The buffer uses four pointers to manage its capacity:" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:21 +msgid "``buf`` -- a pointer to the beginning of the buffer" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:22 +msgid "``rpos`` -- a pointer to the beginning of the range; available for reading data (\"read position\")" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:23 +msgid "``wpos`` -- a pointer to the end of the range; available for reading data, and to the beginning of the range for writing new data (\"write position\")" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:25 +msgid "``epos`` -- a pointer to the end of the range; available for writing new data (\"end position\")" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:31 +msgid "Create a new buffer." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:33 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:35 +msgid "In this example we will show that using buffer allows you to keep the data in the format that you get from the server. So if you get the data only for sending it somewhere else, buffer fastens this a lot." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:39 +msgid "box.cfg{listen = 3301}\n" +"buffer = require('buffer')\n" +"net_box = require('net.box')\n" +"msgpack = require('msgpack')\n" +"\n" +"box.schema.space.create('tester')\n" +"box.space.tester:create_index('primary')\n" +"box.space.tester:insert({1, 'ABCDE', 12345})\n" +"\n" +"box.schema.user.create('usr1', {password = 'pwd1'})\n" +"box.schema.user.grant('usr1', 'read,write,execute', 'space', 'tester')\n" +"\n" +"ibuf = buffer.ibuf()\n" +"\n" +"conn = net_box.connect('usr1:pwd1@localhost:3301')\n" +"conn.space.tester:select({}, {buffer=ibuf})\n" +"\n" +"msgpack.decode_unchecked(ibuf.rpos)" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:60 +#: ../../doc/reference/reference_lua/buffer.rst:228 +msgid "The result of the final request looks like this:" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:62 +#: ../../doc/reference/reference_lua/buffer.rst:196 +msgid "tarantool> msgpack.decode_unchecked(ibuf.rpos)\n" +"---\n" +"- {48: [['ABCDE', 12345]]}\n" +"- 'cdata: 0x7f97ba10c041'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:72 +msgid "Before Tarantool version 1.7.7, the function to use for this case is ``msgpack.ibuf_decode(ibuf.rpos)``. Starting with Tarantool version 1.7.7, ``ibuf_decode`` is deprecated." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:82 +msgid "Allocate ``size`` bytes for ``buffer_object``." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:84 +msgid "memory in bytes to allocate" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +#: ../../doc/reference/reference_lua/buffer.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:85 +msgid "``wpos``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:92 +msgid "Return the capacity of the ``buffer_object``." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:94 +msgid "``epos - buf``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:101 +msgid "Check if ``size`` bytes are available for reading in ``buffer_object``." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:103 +msgid "memory in bytes to check" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:104 +msgid "``rpos``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:111 +msgid "Return the size of the range occupied by data." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:113 +msgid "``rpos - buf``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:120 +msgid "Read ``size`` bytes from buffer." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:127 +msgid "Clear the memory slots allocated by ``buffer_object``." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:129 +msgid "tarantool> ibuf:recycle()\n" +"---\n" +"...\n" +"tarantool> ibuf.buf, ibuf.rpos, ibuf.wpos, ibuf.epos\n" +"---\n" +"- 'cdata: NULL'\n" +"- 'cdata: NULL'\n" +"- 'cdata: NULL'\n" +"- 'cdata: NULL'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:147 +msgid "Clear the memory slots used by ``buffer_object``. This method allows to keep the buffer but remove data from it. It is useful when you want to use the buffer further." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:151 +msgid "tarantool> ibuf:reset()\n" +"---\n" +"...\n" +"tarantool> ibuf.buf, ibuf.rpos, ibuf.wpos, ibuf.epos\n" +"---\n" +"- 'cdata: 0x010cc28030'\n" +"- 'cdata: 0x010cc28030'\n" +"- 'cdata: 0x010cc28030'\n" +"- 'cdata: 0x010cc2c000'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:169 +msgid "Reserve memory for ``buffer_object``. Check if there is enough memory to write ``size`` bytes after ``wpos``. If not, ``epos`` shifts until ``size`` bytes will be available." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:177 +msgid "Return a range, available for reading data." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:179 +msgid "``wpos - rpos``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:186 +msgid "Return a range for writing data." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:188 +msgid "``epos - wpos``" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:192 +msgid "**Module buffer and skip_header**" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:194 +msgid "The example in the previous section" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:204 +msgid "showed that, ordinarily, the response from net.box includes a header -- 48 (hexadecimal 30) that is the :ref:`key ` for IPROTO_DATA. But in some situations, for example when passing the buffer to a C function that expects a MsgPack byte array without a header, the header can be skipped. This is done by specifying ``skip_header=true`` as an option to :ref:`conn.space.space-name:select{...} ` or :ref:`conn.space.space-name:insert{...} ` or :ref:`conn.space.space-name:replace{...} ` or :ref:`conn.space.space-name:update{...} ` or :ref:`conn.space.space-name:upsert{...} ` or :ref:`conn.space.space-name:delete{...} `. The default is ``skip_header=false``." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:217 +msgid "Now here is the end of the same example, except that ``skip_header=true`` is used." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:219 +msgid "ibuf = buffer.ibuf()\n" +"\n" +"conn = net_box.connect('usr1:pwd1@localhost:3301')\n" +"conn.space.tester:select({}, {buffer=ibuf, skip_header=true})\n" +"\n" +"msgpack.decode_unchecked(ibuf.rpos)" +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:230 +msgid "tarantool> msgpack.decode_unchecked(ibuf.rpos)\n" +"---\n" +"- [['ABCDE', 12345]]\n" +"- 'cdata: 0x7f8fd102803f'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:238 +msgid "Notice that the IPROTO_DATA header (48) is gone." +msgstr "" + +#: ../../doc/reference/reference_lua/buffer.rst:240 +msgid "The result is still inside an array, as is clear from the fact that it is shown inside square brackets. It is possible to skip the array header too, with :ref:`msgpack.decode_array_header() `." +msgstr "" diff --git a/locale/en/reference/reference_lua/checks.pot b/locale/en/reference/reference_lua/checks.pot new file mode 100644 index 0000000000..4ac07dd217 --- /dev/null +++ b/locale/en/reference/reference_lua/checks.pot @@ -0,0 +1,828 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-12-26 14:24+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/checks.rst:4 +msgid "Module checks" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:6 +msgid "**Since:** :doc:`2.11.0 `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:8 +msgid "The ``checks`` module provides the ability to check the types of arguments passed to a Lua function. You need to call the :ref:`checks(type_1, ...) ` function inside the target Lua function and pass :ref:`one or more ` type qualifiers to check the corresponding argument types. There are two types of type qualifiers:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:12 +msgid "A :ref:`string type qualifier ` checks whether a function's argument conforms to the specified type. Example: ``'string'``." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:13 +msgid "A :ref:`table type qualifier ` checks whether the values of a table passed as an argument conform to the specified types. Example: ``{ 'string', 'number' }``." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:17 +msgid "For earlier versions, you can install the ``checks`` module from the `Tarantool rocks repository `_." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:22 +msgid "Loading checks" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:24 +msgid "In Tarantool :doc:`2.11.0 ` and later versions, the :ref:`checks API ` is available in a script without loading the module." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:26 +msgid "For earlier versions, you need to install the ``checks`` module from the Tarantool rocks repository and load the module using the ``require()`` directive:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:28 +msgid "local checks = require('checks')" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:36 +msgid "Number of arguments to check" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:38 +msgid "For each argument to check, you need to specify its own type qualifier in the :ref:`checks(type_1, ...) ` function." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:43 +msgid "One argument" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:45 +msgid "In the example below, the ``checks`` function accepts a ``string`` type qualifier to verify that only a string value can be passed to the ``greet`` function. Otherwise, an error is raised." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:48 +#: ../../doc/reference/reference_lua/checks.rst:109 +msgid "function greet(name)\n" +" checks('string')\n" +" return 'Hello, ' .. name\n" +"end\n" +"--[[\n" +"greet('John')\n" +"-- returns 'Hello, John'\n" +"\n" +"greet(123)\n" +"-- raises an error: bad argument #1 to nil (string expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:57 +msgid "Multiple arguments" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:59 +msgid "To check the types of several arguments, you need to pass the corresponding type qualifiers to the ``checks`` function. In the example below, both arguments should be string values." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:62 +msgid "function greet_fullname(firstname, lastname)\n" +" checks('string', 'string')\n" +" return 'Hello, ' .. firstname .. ' ' .. lastname\n" +"end\n" +"--[[\n" +"greet_fullname('John', 'Smith')\n" +"-- returns 'Hello, John Smith'\n" +"\n" +"greet_fullname('John', 1)\n" +"-- raises an error: bad argument #2 to nil (string expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:67 +#: ../../doc/reference/reference_lua/checks.rst:94 +msgid "To skip checking specific arguments, use the :ref:`? placeholder `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:73 +msgid "Variable number of arguments" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:75 +msgid "You can check the types of explicitly specified arguments for functions that accept a variable number of arguments." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:77 +msgid "function extra_arguments_num(a, b, ...)\n" +" checks('string', 'number')\n" +" return select('#', ...)\n" +"end\n" +"--[[\n" +"extra_arguments_num('a', 2, 'c')\n" +"-- returns 1\n" +"\n" +"extra_arguments_num('a', 'b', 'c')\n" +"-- raises an error: bad argument #1 to nil (string expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:87 +msgid "String type qualifier" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:89 +msgid "This section describes how to check a specific argument type using a string type qualifier:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:91 +msgid "The :ref:`Supported types ` section describes all the types supported by the ``checks`` module." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:92 +msgid "If required, you can make a :ref:`union type ` to allow an argument to accept several types." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:93 +msgid "You can make any of the supported types :ref:`optional `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:99 +msgid "Supported types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:104 +msgid "Lua types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:106 +msgid "A string type qualifier can accept any of the `Lua types `_, for example, ``string``, ``number``, ``table``, or ``nil``. In the example below, the ``checks`` function accepts ``string`` to validate that only a string value can be passed to the ``greet`` function." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:118 +msgid "Tarantool types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:120 +msgid "You can use :ref:`Tarantool-specific types ` in a string qualifier. The example below shows how to check that a function argument is a decimal value." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:123 +msgid "local decimal = require('decimal')\n" +"function sqrt(value)\n" +" checks('decimal')\n" +" return decimal.sqrt(value)\n" +"end\n" +"--[[\n" +"sqrt(decimal.new(16))\n" +"-- returns 4\n" +"\n" +"sqrt(16)\n" +"-- raises an error: bad argument #1 to nil (decimal expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:128 +msgid "This table lists all the checks available for Tarantool types:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:136 +msgid "Check" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:137 +msgid "Description" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:138 +msgid "See also" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:140 +msgid "``checks('datetime')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:141 +msgid "Check whether the specified value is :ref:`datetime_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:142 +msgid ":ref:`checkers.datetime(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:144 +msgid "``checks('decimal')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:145 +msgid "Check whether the specified value has the :ref:`decimal ` type" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:146 +msgid ":ref:`checkers.decimal(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:148 +msgid "``checks('error')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:149 +msgid "Check whether the specified value is :ref:`error_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:150 +msgid ":ref:`checkers.error(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:152 +msgid "``checks('int64')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:153 +msgid "Check whether the specified value is an ``int64`` value" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:154 +msgid ":ref:`checkers.int64(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:156 +msgid "``checks('interval')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:157 +msgid "Check whether the specified value is :ref:`interval_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:158 +msgid ":ref:`checkers.interval(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:160 +msgid "``checks('tuple')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:161 +msgid "Check whether the specified value is a :ref:`tuple `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:162 +msgid ":ref:`checkers.tuple(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:164 +msgid "``checks('uint64')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:165 +msgid "Check whether the specified value is a ``uint64`` value" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:166 +msgid ":ref:`checkers.uint64(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:168 +msgid "``checks('uuid')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:169 +msgid "Check whether the specified value is :ref:`uuid_object `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:170 +msgid ":ref:`checkers.uuid(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:172 +msgid "``checks('uuid_bin')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:173 +msgid "Check whether the specified value is :ref:`uuid ` represented by a 16-byte binary string" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:174 +msgid ":ref:`checkers.uuid_bin(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:176 +msgid "``checks('uuid_str')``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:177 +msgid "Check whether the specified value is :ref:`uuid ` represented by a 36-byte hexadecimal string" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:178 +msgid ":ref:`checkers.uuid_str(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:185 +msgid "Custom function" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:187 +msgid "A string type qualifier can accept the name of a custom function that performs arbitrary validations. To achieve this, create a function returning ``true`` if the value is valid and add this function to the :ref:`checkers ` table." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:190 +msgid "The example below shows how to use the ``positive`` function to check that an argument value is a positive number." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:192 +msgid "function checkers.positive(value)\n" +" return (type(value) == 'number') and (value > 0)\n" +"end\n" +"\n" +"function get_doubled_number(value)\n" +" checks('positive')\n" +" return value * 2\n" +"end\n" +"--[[\n" +"get_doubled_number(10)\n" +"-- returns 20\n" +"\n" +"get_doubled_number(-5)\n" +"-- raises an error: bad argument #1 to nil (positive expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:201 +msgid "Metatable type" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:203 +msgid "A string qualifier can accept a value stored in the ``__type`` field of the argument `metatable `_." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:205 +msgid "local blue = setmetatable({ 0, 0, 255 }, { __type = 'color' })\n" +"function get_blue_value(color)\n" +" checks('color')\n" +" return color[3]\n" +"end\n" +"--[[\n" +"get_blue_value(blue)\n" +"-- returns 255\n" +"\n" +"get_blue_value({0, 0, 255})\n" +"-- raises an error: bad argument #1 to nil (color expected, got table)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:214 +msgid "Union types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:216 +msgid "To allow an argument to accept several types (a union type), concatenate type names with a pipe (``|``). In the example below, the argument can be both a ``number`` and ``string`` value." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:219 +msgid "function get_argument_type(value)\n" +" checks('number|string')\n" +" return type(value)\n" +"end\n" +"--[[\n" +"get_argument_type(1)\n" +"-- returns 'number'\n" +"\n" +"get_argument_type('key1')\n" +"-- returns 'string'\n" +"\n" +"get_argument_type(true)\n" +"-- raises an error: bad argument #1 to nil (number|string expected, got boolean)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:229 +msgid "Optional types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:231 +msgid "To make any of the supported types optional, prefix its name with a question mark (``?``). In the example below, the ``name`` argument is optional. This means that the ``greet`` function can accept ``string`` and ``nil`` values." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:235 +msgid "function greet(name)\n" +" checks('?string')\n" +" if name ~= nil then\n" +" return 'Hello, ' .. name\n" +" else\n" +" return 'Hello from Tarantool'\n" +" end\n" +"end\n" +"--[[\n" +"greet('John')\n" +"-- returns 'Hello, John'\n" +"\n" +"greet()\n" +"-- returns 'Hello from Tarantool'\n" +"\n" +"greet(123)\n" +"-- raises an error: bad argument #1 to nil (string expected, got number)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:240 +msgid "As for a specific type, you can make a :ref:`union type ` value optional: ``?number|string``." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:246 +msgid "Skipping argument checking" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:248 +msgid "You can skip checking of the specified arguments using the question mark (``?``) placeholder. In this case, the argument can be any type." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:251 +msgid "function greet_fullname_any(firstname, lastname)\n" +" checks('string', '?')\n" +" return 'Hello, ' .. firstname .. ' ' .. tostring(lastname)\n" +"end\n" +"--[[\n" +"greet_fullname_any('John', 'Doe')\n" +"-- returns 'Hello, John Doe'\n" +"\n" +"greet_fullname_any('John', 1)\n" +"-- returns 'Hello, John 1'\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:262 +msgid "Table type qualifier" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:264 +msgid "A table type qualifier checks whether the values of a table passed as an argument conform to the specified types. In this case, the following checks are made:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:267 +msgid "The argument is checked to conform to the ``?table`` type, and its content is validated." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:268 +msgid "Table values are validated against the specified :ref:`string type qualifiers `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:269 +msgid "Table keys missing in ``checks`` are validated against the ``nil`` type." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:271 +msgid "The code below checks that the first and second table values have the ``string`` and ``number`` types." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:273 +msgid "function configure_connection(options)\n" +" checks({ 'string', 'number' })\n" +" local ip_address = options[1] or '127.0.0.1'\n" +" local port = options[2] or 3301\n" +" return ip_address .. ':' .. port\n" +"end\n" +"--[[\n" +"configure_connection({'0.0.0.0', 3303})\n" +"-- returns '0.0.0.0:3303'\n" +"\n" +"configure_connection({'0.0.0.0', '3303'})\n" +"-- raises an error: bad argument options[2] to nil (number expected, got string)\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:278 +msgid "In the next example, the same checks are made for the specified keys." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:280 +msgid "function configure_connection_opts(options)\n" +" checks({ ip_address = 'string', port = 'number' })\n" +" local ip_address = options.ip_address or '127.0.0.1'\n" +" local port = options.port or 3301\n" +" return ip_address .. ':' .. port\n" +"end\n" +"--[[\n" +"configure_connection_opts({ip_address = '0.0.0.0', port = 3303})\n" +"-- returns '0.0.0.0:3303'\n" +"\n" +"configure_connection_opts({ip_address = '0.0.0.0', port = '3303'})\n" +"-- raises an error: bad argument options.port to nil (number expected, got string)\n" +"\n" +"configure_connection_opts({login = 'testuser', ip_address = '0.0.0.0', port = 3303})\n" +"-- raises an error: unexpected argument options.login to nil\n" +"--]]\n" +"\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:287 +msgid "Table qualifiers can be nested and use tables, too." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:294 +msgid "API Reference" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:304 +msgid "**Members**" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:307 +msgid ":ref:`checks() `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:308 +msgid "When called inside a function, checks that the function's arguments conform to the specified types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:310 +msgid ":ref:`checkers `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:311 +msgid "A global variable that provides access to checkers for different types" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:317 +msgid "checks()" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:321 +msgid "When called inside a function, checks that the function's arguments conform to the specified types." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:323 +msgid "a :ref:`string ` or :ref:`table ` type qualifier used to check the argument type" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:324 +msgid "optional type qualifiers used to check the types of :ref:`other arguments `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:329 +msgid "checkers" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:331 +msgid "The ``checkers`` global variable provides access to checkers for different types. You can use this variable to add a :ref:`custom checker ` that performs arbitrary validations." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:336 +msgid "The ``checkers`` variable also provides access to checkers for Tarantool-specific types. These checkers can be used in a custom checker." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:343 +msgid "Check whether the specified value is :ref:`datetime_object `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:345 +#: ../../doc/reference/reference_lua/checks.rst:363 +#: ../../doc/reference/reference_lua/checks.rst:382 +#: ../../doc/reference/reference_lua/checks.rst:405 +#: ../../doc/reference/reference_lua/checks.rst:424 +#: ../../doc/reference/reference_lua/checks.rst:443 +#: ../../doc/reference/reference_lua/checks.rst:466 +#: ../../doc/reference/reference_lua/checks.rst:485 +#: ../../doc/reference/reference_lua/checks.rst:504 +#: ../../doc/reference/reference_lua/checks.rst:518 +msgid "the value to check the type for" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:347 +msgid "``true`` if the specified value is ``datetime_object``; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +#: ../../doc/reference/reference_lua/checks.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:348 +#: ../../doc/reference/reference_lua/checks.rst:366 +#: ../../doc/reference/reference_lua/checks.rst:385 +#: ../../doc/reference/reference_lua/checks.rst:408 +#: ../../doc/reference/reference_lua/checks.rst:427 +#: ../../doc/reference/reference_lua/checks.rst:446 +#: ../../doc/reference/reference_lua/checks.rst:469 +#: ../../doc/reference/reference_lua/checks.rst:488 +#: ../../doc/reference/reference_lua/checks.rst:507 +#: ../../doc/reference/reference_lua/checks.rst:521 +msgid "boolean" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:350 +#: ../../doc/reference/reference_lua/checks.rst:368 +#: ../../doc/reference/reference_lua/checks.rst:387 +#: ../../doc/reference/reference_lua/checks.rst:410 +#: ../../doc/reference/reference_lua/checks.rst:429 +#: ../../doc/reference/reference_lua/checks.rst:448 +#: ../../doc/reference/reference_lua/checks.rst:471 +#: ../../doc/reference/reference_lua/checks.rst:490 +msgid "**Example**" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:352 +#: ../../doc/reference/reference_lua/checks.rst:431 +msgid "local datetime = require('datetime')\n" +"local is_datetime = checkers.datetime(datetime.new { day = 1, month = 6, year = 2023 })\n" +"local is_interval = checkers.interval(datetime.interval.new { day = 1 })\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:361 +msgid "Check whether the specified value has the :ref:`decimal ` type." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:365 +msgid "``true`` if the specified value has the ``decimal`` type; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:370 +msgid "local decimal = require('decimal')\n" +"local is_decimal = checkers.decimal(decimal.new(16))\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:380 +msgid "Check whether the specified value is :ref:`error_object `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:384 +msgid "``true`` if the specified value is ``error_object``; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:389 +msgid "local server_error = box.error.new({ code = 500, reason = 'Server error' })\n" +"local is_error = checkers.error(server_error)\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:399 +msgid "Check whether the specified value is one of the following ``int64`` values:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:401 +msgid "a Lua number in a range from -2^53+1 to 2^53-1 (inclusive)" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:402 +msgid "Lua cdata ``ctype`` in a range from 0 to ``LLONG_MAX``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:403 +msgid "Lua cdata ``ctype``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:407 +msgid "``true`` if the specified value is an ``int64`` value; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:412 +#: ../../doc/reference/reference_lua/checks.rst:473 +msgid "local is_int64 = checkers.int64(-1024)\n" +"local is_uint64 = checkers.uint64(2048)\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:422 +msgid "Check whether the specified value is :ref:`interval_object `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:426 +msgid "``true`` if the specified value is ``interval_object``; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:441 +msgid "Check whether the specified value is a :ref:`tuple `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:445 +msgid "``true`` if the specified value is a tuple; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:450 +msgid "local is_tuple = checkers.tuple(box.tuple.new{1, 'The Beatles', 1960})\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:460 +msgid "Check whether the specified value is one of the following ``uint64`` values:" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:462 +msgid "a Lua number in a range from 0 to 2^53-1 (inclusive)" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:463 +msgid "Lua cdata ``ctype``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:464 +msgid "Lua cdata ``ctype`` in range from 0 to ``LLONG_MAX``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:468 +msgid "``true`` if the specified value is an ``uint64`` value; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:483 +msgid "Check whether the specified value is :ref:`uuid_object `." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:487 +msgid "``true`` if the specified value is ``uuid_object``; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:492 +msgid "local uuid = require('uuid')\n" +"local is_uuid = checkers.uuid(uuid())\n" +"local is_uuid_bin = checkers.uuid_bin(uuid.bin())\n" +"local is_uuid_str = checkers.uuid_str(uuid.str())\n" +"" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:502 +msgid "Check whether the specified value is :ref:`uuid ` represented by a 16-byte binary string." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:506 +msgid "``true`` if the specified value is ``uuid`` represented by a 16-byte binary string; otherwise, ``false``" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:509 +#: ../../doc/reference/reference_lua/checks.rst:523 +msgid "**See also:** :ref:`uuid(value) `" +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:516 +msgid "Check whether the specified value is :ref:`uuid ` represented by a 36-byte hexadecimal string." +msgstr "" + +#: ../../doc/reference/reference_lua/checks.rst:520 +msgid "``true`` if the specified value is ``uuid`` represented by a 36-byte hexadecimal string; otherwise, ``false``" +msgstr "" diff --git a/locale/en/reference/reference_lua/clock.pot b/locale/en/reference/reference_lua/clock.pot new file mode 100644 index 0000000000..63e0b25aa6 --- /dev/null +++ b/locale/en/reference/reference_lua/clock.pot @@ -0,0 +1,240 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/clock.rst:5 +msgid "Module clock" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:9 +msgid "Overview" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:11 +msgid "The ``clock`` module returns time values derived from the Posix / C CLOCK_GETTIME_ function or equivalent. Most functions in the module return a number of seconds; functions whose names end in \"64\" return a 64-bit number of nanoseconds." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:18 +msgid "Index" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:20 +msgid "Below is a list of all ``clock`` functions." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:28 +msgid "Name" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:28 +msgid "Use" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:30 +msgid ":ref:`clock.time() ` |br| :ref:`clock.realtime() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:31 +msgid "Get the wall clock time in seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:35 +msgid ":ref:`clock.time64() ` |br| :ref:`clock.realtime64() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:36 +msgid "Get the wall clock time in nanoseconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:40 +msgid ":ref:`clock.monotonic() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:40 +msgid "Get the monotonic time in seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:43 +msgid ":ref:`clock.monotonic64() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:43 +msgid "Get the monotonic time in nanoseconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:46 +msgid ":ref:`clock.proc() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:46 +msgid "Get the processor time in seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:49 +msgid ":ref:`clock.proc64() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:49 +msgid "Get the processor time in nanoseconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:52 +msgid ":ref:`clock.thread() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:52 +msgid "Get the thread time in seconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:55 +msgid ":ref:`clock.thread64() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:55 +msgid "Get the thread time in nanoseconds" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:58 +msgid ":ref:`clock.bench() `" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:58 +msgid "Measure the time a function takes within a processor" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:71 +msgid "The wall clock time. Derived from C function ``clock_gettime(CLOCK_REALTIME)``." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +msgid "return" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:73 +msgid "seconds or nanoseconds since epoch (1970-01-01 00:00:00), adjusted." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +#: ../../doc/reference/reference_lua/clock.rst:0 +msgid "rtype" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:74 +#: ../../doc/reference/reference_lua/clock.rst:99 +#: ../../doc/reference/reference_lua/clock.rst:120 +#: ../../doc/reference/reference_lua/clock.rst:141 +msgid "number or cdata (ctype)" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:76 +#: ../../doc/reference/reference_lua/clock.rst:101 +#: ../../doc/reference/reference_lua/clock.rst:122 +#: ../../doc/reference/reference_lua/clock.rst:143 +#: ../../doc/reference/reference_lua/clock.rst:165 +msgid "**Example:**" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:78 +msgid "-- This will print an approximate number of years since 1970.\n" +"clock = require('clock')\n" +"print(clock.time() / (365*24*60*60))" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:84 +msgid "See also :ref:`fiber.time64 ` and the standard Lua function `os.clock `_." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:92 +msgid "The monotonic time. Derived from C function ``clock_gettime(CLOCK_MONOTONIC)``. Monotonic time is similar to wall clock time but is not affected by changes to or from daylight saving time, or by changes done by a user. This is the best function to use with benchmarks that need to calculate elapsed time." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:98 +msgid "seconds or nanoseconds since the last time that the computer was booted." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:103 +msgid "-- This will print nanoseconds since the start.\n" +"clock = require('clock')\n" +"print(clock.monotonic64())" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:114 +msgid "The processor time. Derived from C function ``clock_gettime(CLOCK_PROCESS_CPUTIME_ID)``. This is the best function to use with benchmarks that need to calculate how much time has been spent within a CPU." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:119 +msgid "seconds or nanoseconds since processor start." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:124 +msgid "-- This will print nanoseconds in the CPU since the start.\n" +"clock = require('clock')\n" +"print(clock.proc64())" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:135 +msgid "The thread time. Derived from C function ``clock_gettime(CLOCK_THREAD_CPUTIME_ID)``. This is the best function to use with benchmarks that need to calculate how much time has been spent within a thread within a CPU." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:140 +msgid "seconds or nanoseconds since the transaction processor thread started." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:145 +msgid "-- This will print seconds in the thread since the start.\n" +"clock = require('clock')\n" +"print(clock.thread64())" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:155 +msgid "The time that a function takes within a processor. This function uses ``clock.proc()``, therefore it calculates elapsed CPU time. Therefore it is not useful for showing actual elapsed time." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:0 +msgid "Parameters" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:159 +msgid "function or function reference" +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:160 +msgid "whatever values are required by the function." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:162 +msgid "**table**. first element -- seconds of CPU time, second element -- whatever the function returns." +msgstr "" + +#: ../../doc/reference/reference_lua/clock.rst:167 +msgid "-- Benchmark a function which sleeps 10 seconds.\n" +"-- NB: bench() will not calculate sleep time.\n" +"-- So the returned value will be {a number less than 10, 88}.\n" +"clock = require('clock')\n" +"fiber = require('fiber')\n" +"function f(param)\n" +" fiber.sleep(param)\n" +" return 88\n" +"end\n" +"clock.bench(f, 10)" +msgstr "" diff --git a/locale/en/reference/reference_lua/compat.pot b/locale/en/reference/reference_lua/compat.pot new file mode 100644 index 0000000000..cb20003372 --- /dev/null +++ b/locale/en/reference/reference_lua/compat.pot @@ -0,0 +1,113 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/compat.rst:4 +msgid "Module compat" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:6 +msgid "Module ``compat`` is introduced since version 2.11.0-rc." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:9 +msgid "The usual way to handle compatibility problems is to introduce an option for a new behavior and leave the old one by default. It is not always the perfect way." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:12 +msgid "Sometimes developers want to keep the old behavior for existing applications and offer the new behavior by default for the new ones. For example, the old behavior is known to be problematic, or less safe, or it doesn't correspond to user expectations. In contrast, the user doesn't always read all the documentation and often assumes good defaults. It was decided to introduce a compatibility module to provide a direct way to deprecate unwanted behavior." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:17 +msgid "The ``compat`` module is basically a global table of options with additional verbose interface and helper functions. There are three stages of changing behavior:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:20 +msgid "Old behavior by default." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:21 +msgid "New behavior by default." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:22 +msgid "New behavior is frozen and the old behavior is removed." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:24 +msgid "During the first two stages, a user can toggle options via the interface and change the behavior according to one's needs. At the last stage, the old behavior is removed from the codebase, and the option is marked as obsolete. Because ``compat`` is a global instance, options can be hardcoded into it or added in runtime, for example, by external module." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:28 +msgid "Options are switched to the next stage in major releases. In this way, developers are able to adapt to the new standard behavior and test it before switching to the next release. If something is broken by a new Tarantool version, a developer can still have a way to fix it by a simple config change, that is, explicitly select the old behavior." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:31 +msgid "Consider example below:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:33 +msgid "The option ``json_esc_slash`` is introduced in the 2.11 minor release. Default is set to 'old', but a developer can utilize the new behavior or test the updated behavior by switching it manually to 'new'." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:35 +msgid "In release 3.0, the next major release, ``json_esc_slash`` default is switched to 'new'. Now, developers who don't manage to adapt to the new behavior, are able to switch the option to 'old' and fix their module in the future." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:38 +msgid "In release 4.0, ``json_esc_slash`` is marked as obsolete, and the old behavior is no longer accessible. Developers are forced to use the new behavior." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:41 +msgid "Basic usage" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:43 +msgid "If you want to explicitly secure every behavior in ``compat``, you can do it manually, and then call ``compat.dump()`` to get a Lua command that sets up the ``compat`` with all the options selected. You should place this commands at the beginning of code in your ``init.lua`` file. In this way, you are guaranteed to get the same behavior on any other Tarantool version. See a :doc:`tutorial on using compat <./compat/compat_tutorial>` for more examples." +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:48 +msgid "Options" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:50 +msgid "Below are the available ``compat`` options:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:52 +msgid ":doc:`json_escape_forward_slash <./compat/json_escape_forward_slash>`" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:53 +msgid ":doc:`yaml_pretty_multiline <./compat/yaml_pretty_multiline>`" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:54 +msgid ":doc:`fiber_channel_close_mode <./compat/fiber_channel_close_mode>`" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:55 +msgid ":doc:`box_cfg_replication_sync_timeout <./compat/box_cfg_replication_sync_timeout>`" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:56 +msgid ":doc:`sql_seq_scan_default <./compat/sql_seq_scan_default>`" +msgstr "" + +#: ../../doc/reference/reference_lua/compat.rst:57 +msgid ":doc:`fiber_slice_default <./compat/fiber_slice_default>`" +msgstr "" diff --git a/locale/en/reference/reference_lua/compat/box_cfg_replication_sync_timeout.pot b/locale/en/reference/reference_lua/compat/box_cfg_replication_sync_timeout.pot new file mode 100644 index 0000000000..bae41bc3bd --- /dev/null +++ b/locale/en/reference/reference_lua/compat/box_cfg_replication_sync_timeout.pot @@ -0,0 +1,100 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:4 +msgid "Default value for replication_sync_timeout" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:6 +msgid "Having a non-zero :ref:`replication_sync_timeout ` gives a user the false assumption that the ``box.cfg{replication = ...}`` call returns only when the configured node is synced with all the other nodes. This is mostly true for the big ``replication_sync_timeout`` values, but it is not 100% guaranteed. In other words, a user still has to check if the node is synced, or the sync just timed out. Besides, while ``replication_sync_timeout`` is ticking, you cannot reconfigure ``box`` with another ``box.cfg`` call, which hardens reconfiguration." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:11 +msgid "It is decided to set the ``replication_sync_timeout`` to zero by default." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:14 +msgid "Old and new behavior" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:16 +msgid "The ``compat`` module allows you to choose between" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:18 +msgid "the old behavior: ``box.cfg.replication_sync_timeout`` is 300 seconds by default" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:20 +msgid "and the new behavior:``box.cfg.replication_sync_timeout`` is 0 by default." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:22 +msgid "It is important to set the desired behavior before the initial ``box.cfg{}`` call to take effect for it." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:24 +msgid "tarantool> compat.box_cfg_replication_sync_timeout = 'new'\n" +"---\n" +"...\n" +"tarantool> box.cfg{}\n" +"---\n" +"...\n" +"tarantool> box.cfg.replication_sync_timeout\n" +"---\n" +"- 0\n" +"...\n" +"tarantool> compat.box_cfg_replication_sync_timeout = 'old'\n" +"---\n" +"- error: 'builtin/box/load_cfg.lua:253: The compat option ''box_cfg_replication_sync_timeout''\n" +" takes effect only before the initial box.cfg() call'\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:42 +msgid "A fresh Tarantool run:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:44 +msgid "tarantool> compat.box_cfg_replication_sync_timeout = 'old'\n" +"---\n" +"...\n" +"tarantool> box.cfg{}\n" +"---\n" +"...\n" +"tarantool> box.cfg.replication_sync_timeout\n" +"---\n" +"- 300\n" +"..." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:58 +msgid "Known compatibility issues" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:60 +msgid "At this point, no incompatible modules are known." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:63 +msgid "Detecting issues in your codebase" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/box_cfg_replication_sync_timeout.rst:65 +msgid "We expect issues with a user assuming that the node is not in the orphan state (``box.info.status ~= \"orphan\"``) after the ``box.cfg{replication=...}`` call returns. This is not true with the new behaviour. To simulate the old behavior, one may add a ``box.ctl.wait_rw()`` call after the ``box.cfg{}`` call. ``box.ctl.wait_rw()`` returns only when the node becomes writable, and hence is not an orphan." +msgstr "" diff --git a/locale/en/reference/reference_lua/compat/compat_tutorial.pot b/locale/en/reference/reference_lua/compat/compat_tutorial.pot new file mode 100644 index 0000000000..5de71e5097 --- /dev/null +++ b/locale/en/reference/reference_lua/compat/compat_tutorial.pot @@ -0,0 +1,315 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) +# This file is distributed under the same license as the Tarantool package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tarantool 3.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2023-11-17 14:22+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:4 +msgid "Tutorial: Module compat" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:6 +msgid "This tutorial covers the following ``compat`` module API and its usage:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:12 +msgid "Listing options" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:14 +msgid "The options list is serialized in the interactive console with additional details for user convenience:" +msgstr "" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:16 +msgid "All non-obsolete options in order new > old > default." +msgstr "" + +#: ../../doc/reference/reference_lua/compat/compat_tutorial.rst:18 +msgid "Serialization returns array-like table with tables ``{