Skip to content

Commit 4fd14d6

Browse files
p7novpatiencedaur
p7nov
and
patiencedaur
authored
Add tt cat, play, rocks documentation
Resolves #2998 Resolves #2560 Written by Pavel Semyonov, proofread by Patience Daur Co-authored-by: Patience Daur <[email protected]>
1 parent c85c94e commit 4fd14d6

File tree

4 files changed

+300
-4
lines changed

4 files changed

+300
-4
lines changed

‎doc/reference/tt_cli/cat.rst

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Printing the contents of .snap and .xlog files
2+
==============================================
3+
4+
.. code-block:: bash
5+
6+
tt cat FILE .. [flags]
7+
8+
``tt cat`` prints the contents of :ref:`snapshot <internals-snapshot>` (``.snap``) and
9+
:ref:`WAL <internals-wal>` (``.xlog``) files to stdout. A single call of ``tt cat`` can
10+
print the contents of multiple files.
11+
12+
13+
Flags
14+
-----
15+
16+
.. container:: table
17+
18+
.. list-table::
19+
:widths: 20 80
20+
:header-rows: 0
21+
22+
* - ``--format``
23+
- Output format: ``yaml`` (default), ``json``, or ``lua``
24+
* - ``--from``
25+
- Show operations starting from the given LSN
26+
* - ``--to``
27+
- Show operations up to the given LSN. Default: 18446744073709551615
28+
* - ``--replica``
29+
- Filter the output by replica ID. Can be passed more than once
30+
* - ``--space``
31+
- Filter the output by space ID. Can be passed more than once
32+
* - ``--show-system``
33+
- Show the contents of system spaces
34+
35+
Details
36+
-------
37+
38+
When calling ``tt cat`` with filters by LSN (``--from`` and ``--to`` flags) and
39+
replica ID (``--replica``), remember that LSNs differ across replicas.
40+
Thus, if you pass more than one replica ID via ``--from`` or ``--to``,
41+
the result may not reflect the actual sequence of operations.
42+
43+
Examples
44+
--------
45+
46+
* Output contents of ``00000000000000000000.xlog`` WAL file in the YAML format:
47+
48+
.. code-block:: bash
49+
50+
tt cat 00000000000000000000.xlog
51+
52+
* Output operations on spaces with ``space_id`` 512 and 513 from the
53+
``00000000000000000012.snap`` snapshot file in the JSON format:
54+
55+
.. code-block:: bash
56+
57+
tt cat 00000000000000000012.snap --space 512 --space 513 --format json
58+
59+
* Output operations on all spaces, including system spaces,
60+
from the ``00000000000000000000.xlog`` WAL file:
61+
62+
.. code-block:: bash
63+
64+
tt cat 00000000000000000000.xlog --show-system
65+
66+
* Output operations with LSNs between 100 and 500 on replica 1
67+
from the ``00000000000000000000.xlog`` WAL file:
68+
69+
.. code-block:: bash
70+
71+
tt cat 00000000000000000000.xlog --from 100 --to 500 --replica 1

‎doc/reference/tt_cli/commands.rst

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,11 @@ help for the given command.
3232
- Check an application file for syntax errors
3333
* - :doc:`connect <connect>`
3434
- Connect to a Tarantool instance
35-
* - ``rocks``
35+
* - :doc:`rocks <rocks>`
3636
- Use the LuaRocks package manager
37-
* - ``cat``
37+
* - :doc:`cat <cat>`
3838
- Print the contents of ``.snap`` or ``.xlog`` files into stdout
39-
* - ``play``
39+
* - :doc:`play <play>`
4040
- Play the contents of ``.snap`` or ``.xlog`` files to another Tarantool instance
4141

4242
.. toctree::
@@ -51,4 +51,7 @@ help for the given command.
5151
help <help>
5252
logrotate <logrotate>
5353
check <check>
54-
connect <connect>
54+
connect <connect>
55+
rocks <rocks>
56+
cat <cat>
57+
play <play>

‎doc/reference/tt_cli/play.rst

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
Playing the contents of .snap and .xlog files to a Tarantool instance
2+
=====================================================================
3+
4+
.. code-block:: bash
5+
6+
tt play URI FILE .. [flags]
7+
8+
``tt play`` plays the contents of :ref:`snapshot <internals-snapshot>` (``.snap``) and
9+
:ref:`WAL <internals-wal>` (``.xlog``) files to another Tarantool instance.
10+
A single call of ``tt play`` can play multiple files.
11+
12+
Flags
13+
-----
14+
15+
.. container:: table
16+
17+
.. list-table::
18+
:widths: 20 80
19+
:header-rows: 0
20+
21+
* - ``--from``
22+
- Play operations starting from the given LSN
23+
* - ``--to``
24+
- Play operations up to the given LSN. Default: 18446744073709551615
25+
* - ``--replica``
26+
- Filter the operations by replica id. Can be passed more than once
27+
* - ``--space``
28+
- Filter the operations by space id. Can be passed more than once
29+
* - ``--show-system``
30+
- Play the operations on system spaces
31+
32+
Details
33+
-------
34+
35+
``tt play`` plays operations from ``.xlog`` and ``.snap`` files to the destination
36+
instance one by one. All data changes happen the same way as if they were performed
37+
on this instance. This means that:
38+
39+
* All affected spaces must exist on the destination instance. They must have the same structure
40+
and ``space_id`` as on the instance that created the snapshot or WAL file.
41+
42+
To play a snapshot or a WAL to a clean instance, include the operations on system spaces
43+
by adding the ``--show-system`` flag. With this flag, ``tt`` plays the operations that
44+
create and configure user-defined spaces.
45+
46+
* The operations' LSNs will change unless you play all operations that took place since the instance startup.
47+
48+
* Replica IDs will change in accordance with the destination instance configuration.
49+
50+
51+
When calling ``tt play`` with filters by LSN (``--from`` and ``--to`` flags) and
52+
replica ID (``--replica``), remember that LSNs differ across replicas.
53+
Thus, if you pass more than one replica ID via ``--from`` or ``--to``,
54+
the result may not reflect the actual sequence of operations.
55+
56+
Examples
57+
--------
58+
59+
* Play the contents of ``00000000000000000000.xlog`` to the instance on
60+
``192.168.10.10:3301``:
61+
62+
.. code-block:: bash
63+
64+
tt play 192.168.10.10:3301 00000000000000000000.xlog
65+
66+
* Play operations on spaces with ``space_id`` 512 and 513 from the
67+
``00000000000000000012.snap`` snapshot file:
68+
69+
.. code-block:: bash
70+
71+
tt play 192.168.10.10:3301 00000000000000000012.snap --space 512 --space 513
72+
73+
* Play the contents of ``00000000000000000000.xlog`` including operations on system spaces:
74+
75+
.. code-block:: bash
76+
77+
tt play 192.168.10.10:3301 00000000000000000000.xlog --show-system

‎doc/reference/tt_cli/rocks.rst

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
Using the LuaRocks package manager
2+
==================================
3+
4+
.. code-block:: bash
5+
6+
tt rocks [FLAG ...] [VAR=VALUE] COMMAND [ARGUMENT]
7+
8+
``tt rocks`` provides means to manage Lua modules (rocks) via the
9+
`LuaRocks <https://luarocks.org/>`_ package manager. `tt` uses its own
10+
LuaRocks installation connected to the `Tarantool rocks repository <https://www.tarantool.io/en/download/rocks>`_.
11+
12+
Below are lists of supported LuaRocks flags and commands. For detailed information on
13+
their usage, refer to `LuaRocks documentation <https://github.com/luarocks/luarocks/wiki/Documentation>`_.
14+
15+
Flags
16+
-----
17+
18+
.. container:: table
19+
20+
.. list-table::
21+
:widths: 30 70
22+
:header-rows: 0
23+
24+
* - ``--dev``
25+
- Enable the sub-repositories in rocks servers
26+
for rockspecs of in-development versions
27+
* - ``--server=<server>``
28+
- Fetch rocks/rockspecs from this server
29+
(takes priority over config file)
30+
* - ``--only-server=<server>``
31+
- Fetch rocks/rockspecs from this server only
32+
(overrides any entries in the config file)
33+
* - ``--only-sources=<url>``
34+
- Restrict downloads to paths matching the given URL
35+
* - ``--lua-dir=<prefix>``
36+
- Specify which Lua installation to use
37+
* - ``--lua-version=<ver>``
38+
- Specify which Lua version to use
39+
* - ``--tree=<tree>``
40+
- Specify which tree to operate on
41+
* - ``--local``
42+
- Use the tree in the user's home directory.
43+
Call ``tt rocks help path`` to learn how to enable it
44+
* - ``--global``
45+
- Use the system tree when `local_by_default` is `true`
46+
* - ``--verbose``
47+
- Display verbose output for the command executed
48+
* - ``--timeout=<seconds>``
49+
- Timeout on network operations, in seconds.
50+
0 means no timeout (wait forever). Default: 30
51+
52+
Commands
53+
--------
54+
55+
.. container:: table
56+
57+
.. list-table::
58+
:widths: 20 80
59+
:header-rows: 0
60+
61+
* - ``build``
62+
- Build and compile a rock
63+
* - ``config``
64+
- Query information about the LuaRocks configuration
65+
* - ``doc``
66+
- Show documentation for an installed rock
67+
* - ``download``
68+
- Download a specific rock file from a rocks server
69+
* - ``help``
70+
- Help on commands. Type ``tt rocks help <command>`` for more
71+
* - ``init``
72+
- Initialize a directory for a Lua project using LuaRocks
73+
* - ``install``
74+
- Install a rock
75+
* - ``lint``
76+
- Check syntax of a rockspec
77+
* - ``list``
78+
- List the currently installed rocks
79+
* - ``make``
80+
- Compile package in the current directory using a rockspec
81+
* - ``make_manifest``
82+
- Compile a manifest file for a repository
83+
* - ``new_version``
84+
- Auto-write a rockspec for a new version of a rock
85+
* - ``pack``
86+
- Create a rock, packing sources or binaries
87+
* - ``purge``
88+
- Remove all installed rocks from a tree
89+
* - ``remove``
90+
- Uninstall a rock
91+
* - ``search``
92+
- Query the LuaRocks servers
93+
* - ``show``
94+
- Show information about an installed rock
95+
* - ``test``
96+
- Run the test suite in the current directory
97+
* - ``unpack``
98+
- Unpack the contents of a rock
99+
* - ``which``
100+
- Tell which file corresponds to a given module name
101+
* - ``write_rockspec``
102+
- Write a template for a rockspec file
103+
104+
Examples
105+
--------
106+
107+
* Install the rock ``queue`` from the Tarantool rocks repository:
108+
109+
.. code-block:: bash
110+
111+
tt rocks install queue
112+
113+
* Search for the rock ``queue`` in **both** the Tarantool rocks repository and
114+
the `default LuaRocks repository <https://luarocks.org>`_:
115+
116+
.. code-block:: bash
117+
118+
tt rocks search queue --server='https://luarocks.org'
119+
120+
* List the documentation files for the installed rock ``queue``:
121+
122+
.. code-block:: bash
123+
124+
tt rocks doc queue --list
125+
126+
Without the ``--list`` flag, this command displays documentation in the user's default browser.
127+
128+
* Create a ``*.rock`` file from the installed rock ``queue``:
129+
130+
.. code-block:: bash
131+
132+
tt rocks pack queue
133+
134+
* Unpack a ``*.rock`` file:
135+
136+
.. code-block:: bash
137+
138+
tt rocks unpack queue-scm-1.all.rock
139+
140+
* Remove the installed rock ``queue``:
141+
142+
.. code-block:: bash
143+
144+
tt rocks remove queue
145+

0 commit comments

Comments
 (0)