From 2c0d535d90ba9558ebda259c327539dc3ceffb31 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova <73473519+xuniq@users.noreply.github.com> Date: Mon, 25 Dec 2023 14:47:35 +0300 Subject: [PATCH] Update the 'Creating your first Tarantool database' guide (#3927) Co-authored-by: Pavel Semyonov --- .../instances.enabled/create_db/config.yaml | 9 + .../instances.enabled/create_db/instances.yml | 1 + .../instances.enabled/create_db/myapp.lua | 29 ++ doc/how-to/getting_started_db.rst | 293 +++++++++++++++++- doc/how-to/using_docker.rst | 236 -------------- doc/how-to/using_package_manager.rst | 288 ----------------- .../configuration/configuration_reference.rst | 4 +- 7 files changed, 327 insertions(+), 533 deletions(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/create_db/instances.yml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/create_db/myapp.lua delete mode 100644 doc/how-to/using_docker.rst delete mode 100644 doc/how-to/using_package_manager.rst 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..69ccf58c8c --- /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' \ No newline at end of file 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/create_db/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/create_db/myapp.lua new file mode 100644 index 0000000000..2f3a9b253b --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/myapp.lua @@ -0,0 +1,29 @@ +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 + +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 + +function select_data() + box.space.bands:select { 3 } + box.space.bands.index.secondary:select{'Scorpions'} +end \ No newline at end of file diff --git a/doc/how-to/getting_started_db.rst b/doc/how-to/getting_started_db.rst index 5df67e117f..c9b3159eac 100644 --- a/doc/how-to/getting_started_db.rst +++ b/doc/how-to/getting_started_db.rst @@ -1,13 +1,292 @@ -.. _getting_started_db: +.. _getting_started_db: -================================================================================ Creating your first Tarantool database -================================================================================ +====================================== -First, let's install Tarantool, start it, and create a simple database. +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. -You can install Tarantool and work with it locally or in Docker. +Installing Tarantool +-------------------- -.. include:: using_docker.rst +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 `_. -.. include:: using_package_manager.rst +.. _getting_started_tt-cli: + +Installing tt CLI +----------------- + +Before starting this tutorial: + +#. Install the :ref:`tt CLI ` utility. + +#. 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 :ref:`configuration `, for example: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/config.yaml + :language: yaml + :dedent: + + The instance in the configuration accepts TCP requests on port ``3301``. + +Read more: :ref:`admin-instance_config-develop-app`. + +.. _getting_started_db-start: + +Starting Tarantool +------------------ + +First, start the Tarantool instance from the tt environment directory using +:ref:`tt start `: + +.. code-block:: console + + $ tt start create_db + +To check the running instances, use the :ref:`tt status ` command: + +.. code-block:: console + + $ tt status create_db + INSTANCE STATUS PID + create_db:instance001 RUNNING 54560 + +After that, connect to the instance with :ref:`tt connect `: + +.. code-block:: console + + $ tt connect create_db:instance001 + +This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt. +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 +------------------- + +To create a test database after installation: + +#. Create a :term:`space ` named ``bands``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 2 + :dedent: + +#. Format the created space by specifying :term:`field` names and :ref:`types `: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 3-7 + :dedent: + +#. Create the first :ref:`index ` named ``primary``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 8 + :dedent: + + 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 ` into the space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 14-16 + :dedent: + +#. Then select a tuple using the ``primary`` index: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 27 + :dedent: + +#. Add a secondary index based on the ``band_name`` field: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 9 + :dedent: + +#. Select tuples using the ``secondary`` index: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 28 + :dedent: + +#. To prepare for the example in the next section, grant read, write, and execute + privileges to the current user: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua + :language: lua + :lines: 10 + :dedent: + +#. The full example in the terminal looks like this: + + .. code-block:: tarantoolsession + + create_db:instance001> box.schema.space.create('bands') + --- + ... + create_db:instance001> box.space.bands:format({ + > {name = 'id', type = 'unsigned'}, + > {name = 'band_name', type = 'string'}, + > {name = 'year', type = 'unsigned'} + > }) + --- + ... + create_db:instance001> box.space.bands:create_index('primary', { parts = { 'id' } }) + --- + - unique: true + parts: + - type: unsigned + is_nullable: false + fieldno: 1 + id: 0 + space_id: 512 + name: primary + type: TREE + ... + 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] + ... + create_db:instance001> box.space.bands:select { 3 } + --- + - - [3, 'Ace of Base', 1987] + ... + 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 + ... + create_db:instance001> s.index.secondary:select{'Scorpions'} + --- + - - [2, 'Scorpions', 1965] + ... + create_db:instance001> box.schema.user.grant('guest', 'read,write,execute', 'universe') + --- + ... + +.. _connecting-remotely: + +Connecting remotely +------------------- + +In the configuration file (``config.yaml``), the instance listens on ``127.0.0.1:3301``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/config.yaml + :language: yaml + :start-at: instance001: + :end-at: 127.0.0.1:3301 + :dedent: + +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: + +* a listening address (for example, ``127.0.0.1:3301``) +* a listening port (for example, `3301`) + +The field can't contain parameters, login, or password. + +Learn more about the :ref:`connection parameters `. + +You can send requests to a Tarantool instance using: + +* ``telnet`` +* a :ref:`connector ` +* another instance of Tarantool (using the :ref:`console ` module) +* :ref:`tt ` administrative utility + +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. + +To start working, switch to another terminal and start another Tarantool instance: + +.. code-block:: console + + $ tarantool -i + +Use the :ref:`net.box ` module to connect to the remote Tarantool +instance that is listening on ``localhost:3301``: + +.. code-block:: tarantoolsession + + tarantool> net_box = require('net.box') + --- + ... + tarantool> conn = net_box.connect(3301) + --- + ... + +Then send a select request to ``instance001``: + +.. code-block:: tarantoolsession + + tarantool> conn.space.bands:select{2} + --- + - - [2, 'Scorpions', 1965] + ... + +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. + +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 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: + +.. code-block:: console + + $ tt stop create_db \ No newline at end of file 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/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 42aad8b5ae..43f02458b4 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -672,7 +672,7 @@ iproto.* .. confval:: iproto.listen An array of URIs used to listen for incoming requests. - In required, you can enable SSL for specific URIs by providing additional parameters (:ref:`.params.* `). + If required, you can enable SSL for specific URIs by providing additional parameters (:ref:`.params.* `). These URIs are used for different purposes, for example: @@ -775,7 +775,7 @@ iproto.* | Environment variable: TT_IPROTO_THREADS -.. _configuration_reference_iproto_uri_params: +.. _`configuration_reference_iproto_uri_params`: .params.* ~~~~~~~~~~~~~~