Skip to content

Update the description of box.space._schema #4570

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 11, 2024
+79 −40
Merged

Update the description of box.space._schema #4570

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d1234f5
Update _schema and box.once description
xuniq Oct 4, 2024
0fb0606
Fix link
xuniq Oct 11, 2024
2534ce2
Fix codeblock formatting
xuniq Oct 11, 2024
349658a
Apply suggestions from code review
xuniq Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 58 additions & 22 deletions doc/reference/reference_lua/box_once.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
.. _box-once:

-------------------------------------------------------------------------------
Function box.once
-------------------------------------------------------------------------------
Function box.once
=================

.. function:: box.once(key, function[, ...])

Expand All @@ -18,40 +17,77 @@
stopping the database. The solution is to delete the ``once`` object from
the system space :ref:`_schema <box_space-schema>`.
Say ``box.space._schema:select{}``, find your ``once`` object there and
delete it. For example, re-executing a block with ``key='hello'`` :
delete it.

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`.

.. code-block:: tarantoolsession
:param string key: a value that will be checked
:param function function: a function
:param ...: arguments that must be passed to the function

.. NOTE::

The parameter ``key`` will be stored in the :ref:`_schema <box_space-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.

tarantool> box.space._schema:select{}

**Example**

The example shows how to re-execute the ``box.once()`` block that contains the ``hello`` key.

First, check the ``_schema`` system space.
The ``_schema`` space in the example contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``:

.. code-block:: tarantoolsession

app:instance001> box.space._schema:select{}
---
- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
- ['max_id', 512]
- ['oncebye']
- - ['oncebye']
- ['oncehello']
- ['version', 1, 7, 2]
...
- ['replicaset_name', 'replicaset001']
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
- ['version', 3, 1, 0]

Delete the ``oncehello`` object:

.. code-block:: tarantoolsession

tarantool> box.space._schema:delete('oncehello')
app:instance001> box.space._schema:delete('oncehello')
Copy link
Contributor

@Gerold103 Gerold103 Oct 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not reviewing doc patches often, so I might be out of the context. Is it common for us to write the instance name like this now? Or is tarantool> more canonical?

Copy link
Contributor Author

@xuniq xuniq Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review!

We wrote the tarantool> prefix (and a few other variants) before version 3.0. In Tarantool 3.x, when connecting to an instance, the prefix is ​​displayed in the application_name:instance_name> format. It seems correct to write it this way: the users see this format in the docs, and they see the same format in the terminal (usage example: what's new 3.2.0). This way became widespread when executable examples appeared in the 3.x docs (example: GS). In these examples, the application_name:instance_name format makes it easier for the user to follow the guide steps.

Copy link
Contributor

@Totktonada Totktonada Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tarantool -i prompts with tarantool>.

{tarantoolctl,cartridge,tt} connect <..uri..> prompts with something like uri>.

cartridge enter,tt connect} <..instance name..> prompts with someting like instance name>. AFAIR, app:name is tt's (and cartridge-cli's) instance name format.

So developers likely frequently see tarantool>, but users likely see instance name> more often.

---
- ['oncehello']
...

tarantool> box.once('hello', function() end)
After that, check the ``_schema`` space again:

.. code-block:: tarantoolsession

app:instance001> box.space._schema:select{}
---
- - ['oncebye']
- ['replicaset_name', 'replicaset001']
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
- ['version', 3, 1, 0]
...

:param string key: a value that will be checked
:param function function: a function
:param ...: arguments that must be passed to function
To re-execute the function, call the ``box.once()`` method again:

.. NOTE::
.. code-block:: tarantoolsession

app:instance001> box.once('hello', function() end)
---
...

app:instance001> box.space._schema:select{}
---
- - ['oncebye']
- ['oncehello']
- ['replicaset_name', 'replicaset001']
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
- ['version', 3, 1, 0]
...

The parameter ``key`` will be stored in the :ref:`_schema <box_space-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.
39 changes: 21 additions & 18 deletions doc/reference/reference_lua/box_space/_schema.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
.. _box_space-schema:

===============================================================================
box.space._schema
===============================================================================
=================

.. module:: box.space

Expand All @@ -12,28 +11,32 @@ box.space._schema

This space contains the following tuples:

* ``version`` tuple with version information for this Tarantool instance,
* ``cluster`` tuple with the instance's replica set ID,
* ``max_id`` tuple with the maximal space ID,
* ``once...`` tuples that correspond to specific
:doc:`box.once() </reference/reference_lua/box_once>` blocks from the instance's
* ``version``: version information for this Tarantool instance.
* ``replicaset_name`` (since :doc:`3.0.0 <release/3.0.0>`): the name of the replica set to which this instance belongs.
* ``replicaset_uuid`` (since :doc:`3.0.0 <release/3.0.0>`): the instance's replica set UUID. In version :doc:`3.0.0 <release/3.0.0>`,
the field was renamed from ``cluster`` to ``replicaset_uuid``.
* ``max_id`` (deprecated since `2.11.1 <https://github.com/tarantool/tarantool/releases/tag/2.11.1>`__): the maximal space ID.
Use the :ref:`box.space._space.index[0]:max() <box_index-max>` function instead.
* ``once...``: tuples that correspond to specific
:ref:`box.once() <box-once>` blocks from the instance's
:ref:`initialization file <index-init_label>`.
The first field in these tuples contains the ``key`` value from the
corresponding ``box.once()`` block prefixed with 'once' (e.g. `oncehello`),
corresponding ``box.once()`` block prefixed with 'once' (for example, ``oncehello``),
so you can easily find a tuple that corresponds to a specific
``box.once()`` block.

**Example:**

Here is what ``_schema`` contains in a typical installation (notice the
tuples for two ``box.once()`` blocks, ``'oncebye'`` and ``'oncehello'``):
In the example, the ``_schema`` space contains two ``box.once`` objects -- ``oncebye`` and ``oncehello``.

.. code-block:: tarantoolsession
.. code-block:: tarantoolsession

app:instance001> box.space._schema:select{}
---
- - ['oncebye']
- ['oncehello']
- ['replicaset_name', 'replicaset001']
- ['replicaset_uuid', '72d2d9bf-5d9f-48c4-ba80-9d657e128fee']
- ['version', 3, 1, 0]
...

tarantool> box.space._schema:select{}
---
- - ['cluster', 'b4e15788-d962-4442-892e-d6c1dd5d13f2']
- ['max_id', 512]
- ['oncebye']
- ['oncehello']
- ['version', 1, 7, 2]
Loading