Skip to content

Commit 2c0d535

Browse files
xuniqp7nov
xuniq
and
p7nov
authored
Update the 'Creating your first Tarantool database' guide (#3927)
Co-authored-by: Pavel Semyonov <[email protected]>
1 parent 67f2649 commit 2c0d535

File tree

7 files changed

+327
-533
lines changed

7 files changed

+327
-533
lines changed

‎doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
groups:
2+
group001:
3+
replicasets:
4+
replicaset001:
5+
instances:
6+
instance001:
7+
iproto:
8+
listen:
9+
- uri: '127.0.0.1:3301'

‎doc/code_snippets/snippets/config/instances.enabled/create_db/instances.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
instance001:

‎doc/code_snippets/snippets/config/instances.enabled/create_db/myapp.lua

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
function create_space()
2+
box.schema.space.create('bands')
3+
box.space.bands:format({
4+
{ name = 'id', type = 'unsigned' },
5+
{ name = 'band_name', type = 'string' },
6+
{ name = 'year', type = 'unsigned' }
7+
})
8+
box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } })
9+
box.space.bands:create_index('secondary', { type = "tree", parts = { 'band_name' } })
10+
box.schema.user.grant('guest', 'read,write,execute', 'universe')
11+
end
12+
13+
function load_data()
14+
box.space.bands:insert { 1, 'Roxette', 1986 }
15+
box.space.bands:insert { 2, 'Scorpions', 1965 }
16+
box.space.bands:insert { 3, 'Ace of Base', 1987 }
17+
box.space.bands:insert { 4, 'The Beatles', 1960 }
18+
box.space.bands:insert { 5, 'Pink Floyd', 1965 }
19+
box.space.bands:insert { 6, 'The Rolling Stones', 1962 }
20+
box.space.bands:insert { 7, 'The Doors', 1965 }
21+
box.space.bands:insert { 8, 'Nirvana', 1987 }
22+
box.space.bands:insert { 9, 'Led Zeppelin', 1968 }
23+
box.space.bands:insert { 10, 'Queen', 1970 }
24+
end
25+
26+
function select_data()
27+
box.space.bands:select { 3 }
28+
box.space.bands.index.secondary:select{'Scorpions'}
29+
end

‎doc/how-to/getting_started_db.rst

Lines changed: 286 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,292 @@
1-
.. _getting_started_db:
1+
.. _getting_started_db:
22

3-
================================================================================
43
Creating your first Tarantool database
5-
================================================================================
4+
======================================
65

7-
First, let's install Tarantool, start it, and create a simple database.
6+
In this tutorial, you connect to Tarantool instances using the :ref:`tt CLI <tt-installation>` utility,
7+
create a database, and establish a remote connection using the :ref:`net.box <net_box-module>` module.
88

9-
You can install Tarantool and work with it locally or in Docker.
9+
Installing Tarantool
10+
--------------------
1011

11-
.. include:: using_docker.rst
12+
For production purposes, we recommend that you install Tarantool via the
13+
`official package manager <https://www.tarantool.io/en/download/>`_.
14+
To download and install the package that's appropriate for your OS,
15+
start a shell (terminal) and enter the command-line instructions provided
16+
for your OS at Tarantool `download page <http://tarantool.org/download.html>`_.
1217

13-
.. include:: using_package_manager.rst
18+
.. _getting_started_tt-cli:
19+
20+
Installing tt CLI
21+
-----------------
22+
23+
Before starting this tutorial:
24+
25+
#. Install the :ref:`tt CLI <tt-installation>` utility.
26+
27+
#. Create a tt environment in the current directory using the :ref:`tt init <tt-init>` command.
28+
29+
#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``create_db`` directory.
30+
31+
#. Inside ``instances.enabled/create_db``, create the ``instances.yml`` and ``config.yaml`` files:
32+
33+
* ``instances.yml`` specifies instances to run in the current environment. In this example, there is one instance:
34+
35+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/instances.yml
36+
:language: yaml
37+
:dedent:
38+
39+
* ``config.yaml`` contains basic :ref:`configuration <configuration_file>`, for example:
40+
41+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/config.yaml
42+
:language: yaml
43+
:dedent:
44+
45+
The instance in the configuration accepts TCP requests on port ``3301``.
46+
47+
Read more: :ref:`admin-instance_config-develop-app`.
48+
49+
.. _getting_started_db-start:
50+
51+
Starting Tarantool
52+
------------------
53+
54+
First, start the Tarantool instance from the tt environment directory using
55+
:ref:`tt start <tt-start>`:
56+
57+
.. code-block:: console
58+
59+
$ tt start create_db
60+
61+
To check the running instances, use the :ref:`tt status <tt-status>` command:
62+
63+
.. code-block:: console
64+
65+
$ tt status create_db
66+
INSTANCE STATUS PID
67+
create_db:instance001 RUNNING 54560
68+
69+
After that, connect to the instance with :ref:`tt connect <tt-connect>`:
70+
71+
.. code-block:: console
72+
73+
$ tt connect create_db:instance001
74+
75+
This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt.
76+
Now you can enter requests on the command line.
77+
78+
.. NOTE::
79+
80+
On production machines, Tarantool's interactive mode is designed for system
81+
administration only. We use it for most examples in this manual
82+
because it is convenient for learning.
83+
84+
.. _creating-db-locally:
85+
86+
Creating a database
87+
-------------------
88+
89+
To create a test database after installation:
90+
91+
#. Create a :term:`space <space>` named ``bands``:
92+
93+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
94+
:language: lua
95+
:lines: 2
96+
:dedent:
97+
98+
#. Format the created space by specifying :term:`field` names and :ref:`types <index-box_data-types>`:
99+
100+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
101+
:language: lua
102+
:lines: 3-7
103+
:dedent:
104+
105+
#. Create the first :ref:`index <index-box_index>` named ``primary``:
106+
107+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
108+
:language: lua
109+
:lines: 8
110+
:dedent:
111+
112+
This is a primary index based on the ``id`` field of each tuple.
113+
``TREE`` is the most universal index type. To learn more, check the documentation on Tarantool :ref:`index types <index-types>`.
114+
115+
#. Insert three :term:`tuples <tuple>` into the space:
116+
117+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
118+
:language: lua
119+
:lines: 14-16
120+
:dedent:
121+
122+
#. Then select a tuple using the ``primary`` index:
123+
124+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
125+
:language: lua
126+
:lines: 27
127+
:dedent:
128+
129+
#. Add a secondary index based on the ``band_name`` field:
130+
131+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
132+
:language: lua
133+
:lines: 9
134+
:dedent:
135+
136+
#. Select tuples using the ``secondary`` index:
137+
138+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
139+
:language: lua
140+
:lines: 28
141+
:dedent:
142+
143+
#. To prepare for the example in the next section, grant read, write, and execute
144+
privileges to the current user:
145+
146+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua
147+
:language: lua
148+
:lines: 10
149+
:dedent:
150+
151+
#. The full example in the terminal looks like this:
152+
153+
.. code-block:: tarantoolsession
154+
155+
create_db:instance001> box.schema.space.create('bands')
156+
---
157+
...
158+
create_db:instance001> box.space.bands:format({
159+
> {name = 'id', type = 'unsigned'},
160+
> {name = 'band_name', type = 'string'},
161+
> {name = 'year', type = 'unsigned'}
162+
> })
163+
---
164+
...
165+
create_db:instance001> box.space.bands:create_index('primary', { parts = { 'id' } })
166+
---
167+
- unique: true
168+
parts:
169+
- type: unsigned
170+
is_nullable: false
171+
fieldno: 1
172+
id: 0
173+
space_id: 512
174+
name: primary
175+
type: TREE
176+
...
177+
create_db:instance001> box.space.bands:insert { 1, 'Roxette', 1986 }
178+
---
179+
- [1, 'Roxette', 1986]
180+
...
181+
create_db:instance001> box.space.bands:insert { 2, 'Scorpions', 1965 }
182+
---
183+
- [2, 'Scorpions', 1965]
184+
...
185+
create_db:instance001> box.space.bands:insert { 3, 'Ace of Base', 1987 }
186+
---
187+
- [3, 'Ace of Base', 1987]
188+
...
189+
create_db:instance001> box.space.bands:select { 3 }
190+
---
191+
- - [3, 'Ace of Base', 1987]
192+
...
193+
create_db:instance001> box.space.bands:create_index('secondary', { parts = { 'band_name' } })
194+
---
195+
- unique: true
196+
parts:
197+
- fieldno: 2
198+
sort_order: asc
199+
type: string
200+
exclude_null: false
201+
is_nullable: false
202+
hint: true
203+
id: 1
204+
type: TREE
205+
space_id: 512
206+
name: secondary
207+
...
208+
create_db:instance001> s.index.secondary:select{'Scorpions'}
209+
---
210+
- - [2, 'Scorpions', 1965]
211+
...
212+
create_db:instance001> box.schema.user.grant('guest', 'read,write,execute', 'universe')
213+
---
214+
...
215+
216+
.. _connecting-remotely:
217+
218+
Connecting remotely
219+
-------------------
220+
221+
In the configuration file (``config.yaml``), the instance listens on ``127.0.0.1:3301``:
222+
223+
.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/config.yaml
224+
:language: yaml
225+
:start-at: instance001:
226+
:end-at: 127.0.0.1:3301
227+
:dedent:
228+
229+
The :ref:`iproto.listen <configuration_reference_iproto_listen>` option is an array of URIs used to listen for incoming requests.
230+
Each record of the array contains a required :ref:`URI <index-uri>` (uniform resource identifier) field and an optional
231+
:ref:`params <configuration_reference_iproto_listen>` field.
232+
The ``iproto.listen.uri`` field may contain:
233+
234+
* a listening address (for example, ``127.0.0.1:3301``)
235+
* a listening port (for example, `3301`)
236+
237+
The field can't contain parameters, login, or password.
238+
239+
Learn more about the :ref:`connection parameters <configuration_options_connection>`.
240+
241+
You can send requests to a Tarantool instance using:
242+
243+
* ``telnet``
244+
* a :ref:`connector <index-box_connectors>`
245+
* another instance of Tarantool (using the :ref:`console <console-module>` module)
246+
* :ref:`tt <tt-cli>` administrative utility
247+
248+
In previous steps, the requests were sent using the tt utility.
249+
To connect from another Tarantool instance, start the ``tarantool`` executable
250+
with the ``-i`` option, which enables the interactive mode.
251+
252+
To start working, switch to another terminal and start another Tarantool instance:
253+
254+
.. code-block:: console
255+
256+
$ tarantool -i
257+
258+
Use the :ref:`net.box <net_box-module>` module to connect to the remote Tarantool
259+
instance that is listening on ``localhost:3301``:
260+
261+
.. code-block:: tarantoolsession
262+
263+
tarantool> net_box = require('net.box')
264+
---
265+
...
266+
tarantool> conn = net_box.connect(3301)
267+
---
268+
...
269+
270+
Then send a select request to ``instance001``:
271+
272+
.. code-block:: tarantoolsession
273+
274+
tarantool> conn.space.bands:select{2}
275+
---
276+
- - [2, 'Scorpions', 1965]
277+
...
278+
279+
This request is equivalent to the local request ``box.space.bands:select{2}``.
280+
The result in this case is one of the tuples that was inserted earlier.
281+
282+
You can repeat ``box.space...:insert{}`` and ``box.space...:select{}``
283+
(or ``conn.space...:insert{}`` and ``conn.space...:select{}``)
284+
indefinitely, on either Tarantool instance.
285+
286+
When the tutorial is over, you can use :ref:`box.space.s:drop() <box_space-drop>` to drop the space.
287+
To exit interactive console, enter ``Ctrl+D``.
288+
After that, to stop Tarantool instances, use the :ref:`tt stop <tt-stop>` command:
289+
290+
.. code-block:: console
291+
292+
$ tt stop create_db

0 commit comments

Comments
 (0)