Skip to content

Commit 3e233a7

Browse files
p7novp7nov
committed
Add tt console docs
1 parent 4cd1251 commit 3e233a7

File tree

3 files changed

+278
-2
lines changed

3 files changed

+278
-2
lines changed

‎doc/reference/tooling/tt_cli/connect.rst

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Connecting to a Tarantool instance
88
$ tt connect {URI|INSTANCE} [OPTION ...]
99
1010
11-
``tt connect`` connects to a Tarantool instance by its URI or name specified
12-
during its startup (``tt start``).
11+
``tt connect`` connects to a Tarantool instance by its URI or instance name specified
12+
in the current environment.
1313

1414
Options
1515
-------
@@ -28,6 +28,20 @@ Options
2828

2929
``-`` – read the script from stdin.
3030

31+
.. option:: -i, --interactive
32+
33+
Enter the interactive mode after evaluating the script passed in ``-f``/``--file``.
34+
35+
.. option:: -l LANGUAGE, --language LANGUAGE
36+
37+
The input language of the :ref:`tt interactive console <tt-interactive-console>`:
38+
``lua`` (default) or ``sql``.
39+
40+
.. option:: -x FORMAT, --outputformat FORMAT
41+
42+
The output format of the :ref:`tt interactive console <tt-interactive-console>`:
43+
``yaml`` (default), ``lua``, ``table``, ``ttable``.
44+
3145
Details
3246
-------
3347

‎doc/reference/tooling/tt_cli/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ concept explanation, and the ``tt`` command reference.
2727
global_options
2828
commands
2929
external_modules
30+
tt_interactive_console
3031

3132
.. _tt-cli-environments:
3233

‎doc/reference/tooling/tt_cli/tt_interactive_console.rst

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
.. _tt-interactive-console:
2+
3+
tt interactive console
4+
======================
5+
6+
The ``tt`` utility features an command-line console that allows executing requests
7+
and Lua code interactively on the connected Tarantool instances.
8+
It is similar to the :ref:`Tarantool interactive console <interactive_console>` with
9+
one key difference: the ``tt`` console allows connecting to any available instance,
10+
both local and remote. Additionally, it offers more flexible output formatting capabilities.
11+
12+
.. _tt-interactive-console-enter:
13+
14+
Entering the console
15+
--------------------
16+
17+
To connect to a Tarantool instance using the ``tt`` console, run :ref:`tt connect <tt-connect>`.
18+
Specify the instance URI and connection options, such as the username and the password,
19+
in the corresponding options.
20+
21+
.. code-block:: console
22+
23+
$ tt connect 192.168.10.10:3301 -u myuser -p p4$$w0rD
24+
• Connecting to the instance...
25+
• Connected to 192.168.10.10:3301
26+
27+
192.168.10.10:3301>
28+
29+
When connecting to an instance from the same ``tt`` environment, you can use the
30+
``<application>:<instance>`` string instead of the URI:
31+
32+
.. code-block:: console
33+
34+
$ tt connect app:storage001
35+
• Connecting to the instance...
36+
• Connected to app:storage001
37+
38+
app:storage001>
39+
40+
To get the list of supported console commands, enter ``\help`` or ``?``.
41+
To quit the console, enter ``\quit`` or ``\q``.
42+
43+
.. _tt-interactive-console-input:
44+
45+
Console input
46+
-------------
47+
48+
Similarly to the :ref:`Tarantool interactive console <interactive_console>`, the
49+
``tt`` console can handle Lua or SQL input. The default is Lua. To change the input
50+
language, run ``\set language <language>``, for example:
51+
52+
.. code-block:: console
53+
54+
app:storage001> \set language sql
55+
app:storage001> select * from bands where id = 1
56+
---
57+
- metadata:
58+
- name: id
59+
type: unsigned
60+
- name: band_name
61+
type: string
62+
- name: year
63+
type: unsigned
64+
rows:
65+
- [1, 'Roxette', 1986]
66+
...
67+
68+
.. code-block:: console
69+
70+
app:storage001> \set language lua
71+
app:storage001> box.space.bands:select { 1 }
72+
---
73+
- - [1, 'Roxette', 1986]
74+
...
75+
76+
.. note::
77+
78+
You can also specify the input language in the ``tt connect`` call using the
79+
``-l``/``--language`` option:
80+
81+
.. code-block:: console
82+
83+
$ tt connect app:storage001 -l sql
84+
85+
For Lua input, the tab-based autocompletion works automatically for loaded modules.
86+
87+
.. _tt-interactive-console-output:
88+
89+
Console output
90+
--------------
91+
92+
By default, the ``tt`` console prints the output data in the YAML format, each
93+
tuple on the new line:
94+
95+
.. code-block:: console
96+
97+
app:storage001> box.space.bands:select { }
98+
---
99+
- - [1, 'Roxette', 1986]
100+
- [2, 'Scorpions', 1965]
101+
- [3, 'Ace of Base', 1987]
102+
...
103+
104+
You can switch to alternative output formats -- Lua or human-readable tables --
105+
using the ``\set output`` console command:
106+
107+
.. code-block:: console
108+
109+
app:storage001> \set output lua
110+
app:storage001> box.space.bands:select { }
111+
{{1, "Roxette", 1986}, {2, "Scorpions", 1965}, {3, "Ace of Base", 1987}};
112+
app:storage001> \set output table
113+
app:storage001> box.space.bands:select { }
114+
+------+-------------+------+
115+
| col1 | col2 | col3 |
116+
+------+-------------+------+
117+
| 1 | Roxette | 1986 |
118+
+------+-------------+------+
119+
| 2 | Scorpions | 1965 |
120+
+------+-------------+------+
121+
| 3 | Ace of Base | 1987 |
122+
+------+-------------+------+
123+
124+
The table output can be printed in the transposed format, where an object's fields
125+
are arranged in columns instead of rows:
126+
127+
.. code-block:: console
128+
129+
app:storage001> \set output ttable
130+
app:storage001> box.space.bands:select { }
131+
+------+---------+-----------+-------------+
132+
| col1 | 1 | 2 | 3 |
133+
+------+---------+-----------+-------------+
134+
| col2 | Roxette | Scorpions | Ace of Base |
135+
+------+---------+-----------+-------------+
136+
| col3 | 1986 | 1965 | 1987 |
137+
+------+---------+-----------+-------------+
138+
139+
.. note::
140+
141+
You can also specify the output format in the ``tt connect`` call using the
142+
``-x``/``--outputformat`` option:
143+
144+
.. code-block:: console
145+
146+
$ tt connect app:storage001 -x table
147+
148+
For ``table`` and ``ttable`` output, more customizations are possible with the
149+
following commands:
150+
151+
* ``\set table_format`` -- table format: default (pseudographics, or ASCII table), Markdown,
152+
or Jira-compatible format.
153+
* ``\set grahpics`` -- enable or disable graphics for table cells in the default format.
154+
* ``\set table_column_width`` -- maximum column width.
155+
156+
.. code-block:: console
157+
158+
app:storage001> \set table_format jira
159+
app:storage001> box.space.bands:select {}
160+
| col1 | 1 | 2 | 3 |
161+
| col2 | Roxette | Scorpions | Ace of Base |
162+
| col3 | 1986 | 1965 | 1987 |
163+
app:storage001> \set table_format default
164+
app:storage001> \set graphics false
165+
app:storage001> box.space.bands:select {}
166+
col1 1 2 3
167+
col2 Roxette Scorpions Ace of Base
168+
col3 1986 1965 1987
169+
170+
app:storage001> \set table_column_width 6
171+
app:storage001> box.space.bands:select {}
172+
col1 1 2 3
173+
col2 Roxett Scorpi Ace of
174+
+e +ons + Base
175+
col3 1986 1965 1987
176+
177+
178+
.. _tt-interactive-console-commands:
179+
180+
Commands
181+
--------
182+
183+
\\help, ?
184+
~~~~~~~~~
185+
186+
Show help on the ``tt`` console.
187+
188+
\\quit, \\q
189+
~~~~~~~~~~~
190+
191+
Quit the ``tt`` console.
192+
193+
\\shortcuts
194+
~~~~~~~~~~~
195+
196+
Show available keyboard shortcuts.
197+
198+
\\set language {lua|sql}
199+
~~~~~~~~~~~~~~~~~~~~~~~~
200+
201+
Set the input language.
202+
Possible values:
203+
204+
* ``lua`` (default)
205+
* ``sql``.
206+
207+
An analog of the :ref:`tt connect <tt-connect>` option ``-l``/``--language``
208+
209+
\\set output FORMAT, \\x{l|t|T|y}, \\x
210+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211+
212+
Set the output format.
213+
Possible ``FORMAT`` values:
214+
215+
* ``yaml`` (default) -- each output item is a YAML object. Example: ``[1, 'Roxette', 1986]``.
216+
Shorthand: ``\xy``.
217+
* ``lua`` -- each output tuple is a separate Lua table. Example: ``{{1, "Roxette", 1986}};``.
218+
Shorthand: ``\xl``.
219+
* ``table`` -- the output is a table where tuples are rows.
220+
Shorthand: ``\xt``.
221+
* ``ttable`` -- the output is a transposed table where tuples are columns.
222+
Shorthand: ``\xT``.
223+
224+
.. note::
225+
226+
The ``\x`` command switches the output format cyclically in the order
227+
``yaml`` > ``lua`` > ``table`` > ``ttable``.
228+
229+
The format of ``table`` and ``ttable`` output can be adjusted using the ``\set table_format``,
230+
``\set graphics`, and ``\set table_colum_width`` commands.
231+
232+
An analog of the :ref:`tt connect <tt-connect>` option ``-x``/``--outputformat``
233+
234+
\\set table_format
235+
~~~~~~~~~~~~~~~~~~
236+
237+
Set the table format if the output format is ``table`` or ``ttable``.
238+
Possible values:
239+
240+
* ``default`` -- a pseudographics (ASCII) table.
241+
* ``markdown`` -- a table in the Markdown format.
242+
* ``jira`` -- a Jira-compatible table.
243+
244+
\\set graphics {true|false}, \\x{g|G}
245+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246+
247+
Whether to print pseudographics for table cells if the output format is ``table`` or ``ttable``.
248+
Possible values: ``true`` (default) and ``false``.
249+
250+
The shorthands are:
251+
252+
* ``\xG`` for ``true``
253+
* ``\xg`` for ``false``
254+
255+
\\set table_colum_width WIDTH, \\xw WIDTH
256+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
257+
258+
Set maximum printed width of a table cell content. If the length exceeds this value,
259+
it continues on the next line starting from the `+` (plus) sign.
260+
261+
Shorthand: ``\xw``

0 commit comments

Comments
 (0)