diff --git a/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md b/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md new file mode 100644 index 0000000000..0d73256667 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/README.md @@ -0,0 +1,11 @@ +# Creating your first Tarantool database + +A sample application created in the [Creating your first Tarantool database](https://www.tarantool.io/en/doc/latest/how-to/getting_started_db/) tutorial. + +## Running + +To start an instance, execute the following command in the [config](../../../config) directory: + +```console +$ tt start create_db +``` 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 index 69ccf58c8c..7aeaa6ed21 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/create_db/config.yaml @@ -6,4 +6,4 @@ groups: instance001: iproto: listen: - - uri: '127.0.0.1:3301' \ No newline at end of file + - uri: '127.0.0.1:3301' 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 deleted file mode 100644 index 2f3a9b253b..0000000000 --- a/doc/code_snippets/snippets/config/instances.enabled/create_db/myapp.lua +++ /dev/null @@ -1,29 +0,0 @@ -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/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md new file mode 100644 index 0000000000..3d071d0fda --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/README.md @@ -0,0 +1,11 @@ +# Connectors + +A sample application used to demonstrate how to connect to a database using connectors for different languages and execute requests for manipulating the data. + +## Running + +Start the application by executing the following command in the [connectors](../../../connectors) directory: + +```console +$ tt start sample_db +``` diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml new file mode 100644 index 0000000000..a4446cbca4 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml @@ -0,0 +1,22 @@ +credentials: + users: + sampleuser: + password: '123456' + privileges: + - permissions: [ read, write ] + spaces: [ bands ] + - permissions: [ execute ] + functions: [ get_bands_older_than ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + +app: + file: 'myapp.lua' diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua new file mode 100644 index 0000000000..5859c4be19 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua @@ -0,0 +1,23 @@ +-- Create a space -- +box.schema.space.create('bands') + +-- Specify field names and types -- +box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } +}) + +-- Create indexes -- +box.space.bands:create_index('primary', { parts = { 'id' } }) +box.space.bands:create_index('band', { parts = { 'band_name' } }) +box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } }) + +-- Create a stored function -- +box.schema.func.create('get_bands_older_than', { + body = [[ + function(year) + return box.space.bands.index.year_band:select({ year }, { iterator = 'LT', limit = 10 }) + end + ]] +}) diff --git a/doc/code_snippets/snippets/connectors/net_box/README.md b/doc/code_snippets/snippets/connectors/net_box/README.md new file mode 100644 index 0000000000..d9786d4940 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/net_box/README.md @@ -0,0 +1,16 @@ +# net.box + +A sample application containing `net.box` requests from the [Getting started with net.box](https://www.tarantool.io/en/doc/latest/how-to/getting_started_net_box/) tutorial. + + +## Running + +Before running this sample, start an application that allows remote connections to a sample database: [sample_db](../instances.enabled/sample_db). + +Then, start the interactive session by executing the following command in the [connectors](..) directory: + +```console +$ tt run -i net_box/myapp.lua +``` + +In the console, you can use the `conn` object to execute requests for manipulating the data. diff --git a/doc/code_snippets/snippets/connectors/net_box/myapp.lua b/doc/code_snippets/snippets/connectors/net_box/myapp.lua new file mode 100644 index 0000000000..f454a43d57 --- /dev/null +++ b/doc/code_snippets/snippets/connectors/net_box/myapp.lua @@ -0,0 +1,102 @@ +net_box = require('net.box') +--[[ +--- +... +]] + +conn = net_box.connect('sampleuser:123456@127.0.0.1:3301') +--[[ +--- +... +]] + +conn:ping() +--[[ +--- +- true +... +]] + +function net_box_data_operations() + -- Start net.box session + conn.space.bands:insert({ 1, 'Roxette', 1986 }) + --[[ + --- + - - [1, 'Roxette', 1986] + ... + ]] + conn.space.bands:insert({ 2, 'Scorpions', 1965 }) + --[[ + --- + - [2, 'Scorpions', 1965] + ... + ]] + conn.space.bands:insert({ 3, 'Ace of Base', 1987 }) + --[[ + --- + - [3, 'Ace of Base', 1987] + ... + ]] + conn.space.bands:insert({ 4, 'The Beatles', 1960 }) + --[[ + --- + - [4, 'The Beatles', 1960] + ... + ]] + + conn.space.bands:select({ 1 }) + --[[ + --- + - - [1, 'Roxette', 1986] + ... + ]] + + conn.space.bands.index.band:select({ 'The Beatles' }) + --[[ + --- + - - [4, 'The Beatles', 1960] + ... + ]] + + conn.space.bands:update({ 2 }, { { '=', 'band_name', 'Pink Floyd' } }) + --[[ + --- + - [2, 'Pink Floyd', 1965] + ... + ]] + + conn.space.bands:upsert({ 5, 'The Rolling Stones', 1962 }, { { '=', 'band_name', 'The Doors' } }) + --[[ + --- + ... + ]] + + conn.space.bands:replace({ 1, 'Queen', 1970 }) + --[[ + --- + - [1, 'Queen', 1970] + ... + ]] + + conn.space.bands:delete({ 5 }) + --[[ + --- + - [5, 'The Rolling Stones', 1962] + ... + ]] + + conn:call('get_bands_older_than', { 1966 }) + -- --- + -- - [[2, 'Pink Floyd', 1965], [4, 'The Beatles', 1960]] + -- ... + -- End net.box session +end + +function net_box_close_connection() + conn:close() + --[[ + --- + ... + ]] + -- Close net.box connection +end diff --git a/doc/code_snippets/snippets/connectors/tt.yaml b/doc/code_snippets/snippets/connectors/tt.yaml new file mode 100644 index 0000000000..e9cf7000cf --- /dev/null +++ b/doc/code_snippets/snippets/connectors/tt.yaml @@ -0,0 +1,54 @@ +modules: + # Directory where the external modules are stored. + directory: modules + +env: + # Restart instance on failure. + restart_on_failure: false + + # Directory that stores binary files. + bin_dir: bin + + # Directory that stores Tarantool header files. + inc_dir: include + + # Path to directory that stores all applications. + # The directory can also contain symbolic links to applications. + instances_enabled: instances.enabled + + # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application + # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl, + # snap) and multi-instance applications are not affected by this option. + tarantoolctl_layout: false + +app: + # Directory that stores various instance runtime + # artifacts like console socket, PID file, etc. + run_dir: var/run + + # Directory that stores log files. + log_dir: var/log + + # Directory where write-ahead log (.xlog) files are stored. + wal_dir: var/lib + + # Directory where memtx stores snapshot (.snap) files. + memtx_dir: var/lib + + # Directory where vinyl files or subdirectories will be stored. + vinyl_dir: var/lib + +# Path to file with credentials for downloading Tarantool Enterprise Edition. +# credential_path: /path/to/file +ee: + credential_path: + +templates: + # The path to templates search directory. + - path: templates + +repo: + # Directory where local rocks files could be found. + rocks: + # Directory that stores installation files. + distfiles: distfiles diff --git a/doc/how-to/getting_started_db.rst b/doc/how-to/getting_started_db.rst index 5949a2732d..1cc87ede52 100644 --- a/doc/how-to/getting_started_db.rst +++ b/doc/how-to/getting_started_db.rst @@ -3,26 +3,34 @@ Creating your first Tarantool 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. +**Example on GitHub**: `create_db `_ -Installing Tarantool --------------------- +In this tutorial, you create a Tarantool database, write data to it, and select data from this database. -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 `_. -.. _getting_started_tt-cli: +.. _getting_started_db_prerequisites: -Installing tt CLI ------------------ +Prerequisites +------------- Before starting this tutorial: -#. Install the :ref:`tt CLI ` utility. +* Install the :ref:`tt ` utility. +* Install `Tarantool `_. + + .. NOTE:: + + The tt utility provides the ability to install Tarantool software using the :ref:`tt install ` command. + + + +.. _getting_started_db_creating-app: + +Creating an application +----------------------- + +The :ref:`tt create ` command can be used to :ref:`create an application ` from a predefined or custom template. +In this tutorial, the application layout is prepared manually: #. Create a tt environment in the current directory using the :ref:`tt init ` command. @@ -36,160 +44,123 @@ Before starting this tutorial: :language: yaml :dedent: - * ``config.yaml`` contains basic :ref:`configuration `, for example: + * ``config.yaml`` contains basic instance :ref:`configuration `: .. 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 + The instance in the configuration accepts incoming requests on the ``3301`` port. - $ 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 +.. _getting_started_db_working_with_database: -After that, connect to the instance with :ref:`tt connect `: +Working with the database +------------------------- -.. code-block:: console +.. _getting_started_db-start: - $ tt connect create_db:instance001 +Starting an instance +~~~~~~~~~~~~~~~~~~~~ -This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt. -Now you can enter requests on the command line. +#. Start the Tarantool instance from the tt environment directory using :ref:`tt start `: -.. NOTE:: + .. code-block:: console - 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. + $ tt start create_db -.. _creating-db-locally: +#. To check the running instance, use the :ref:`tt status ` command: -Creating a database -------------------- + .. code-block:: console -To create a test database after installation: + $ tt status create_db + INSTANCE STATUS PID + create_db:instance001 RUNNING 54560 -#. Create a :term:`space ` named ``bands``: +#. Connect to the instance with :ref:`tt connect `: - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua - :language: lua - :lines: 2 - :dedent: + .. code-block:: console -#. Format the created space by specifying :term:`field` names and :ref:`types `: + $ tt connect create_db:instance001 + • Connecting to the instance... + • Connected to create_db:instance001 - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua - :language: lua - :lines: 3-7 - :dedent: + create_db:instance001> -#. Create the first :ref:`index ` named ``primary``: + This command opens an interactive Tarantool console with the ``create_db:instance001>`` prompt. + Now you can enter requests in the command line. - .. 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 `. +.. _creating-db-locally: -#. Insert three :term:`tuples ` into the space: +Creating a space +~~~~~~~~~~~~~~~~ - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua - :language: lua - :lines: 14-16 - :dedent: +#. Create a :term:`space ` named ``bands``: -#. Then select a tuple using the ``primary`` index: + .. code-block:: tarantoolsession - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua - :language: lua - :lines: 27 - :dedent: + create_db:instance001> box.schema.space.create('bands') + --- + - engine: memtx + before_replace: 'function: 0x010229d788' + field_count: 0 + is_sync: false + is_local: false + on_replace: 'function: 0x010229d750' + temporary: false + index: [] + type: normal + enabled: false + name: bands + id: 512 + - created + ... -#. Add a secondary index based on the ``band_name`` field: +#. 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: 9 - :dedent: + .. code-block:: tarantoolsession -#. Select tuples using the ``secondary`` index: + create_db:instance001> box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + --- + ... - .. 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: +.. _creating-db-indexes: - .. literalinclude:: /code_snippets/snippets/config/instances.enabled/create_db/myapp.lua - :language: lua - :lines: 10 - :dedent: +Creating indexes +~~~~~~~~~~~~~~~~ -#. The full example in the terminal looks like this: +#. Create the primary :ref:`index ` based on the ``id`` field: .. 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 + - fieldno: 1 + sort_order: asc + type: unsigned + exclude_null: false is_nullable: false - fieldno: 1 + hint: true id: 0 + type: TREE 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 the secondary index based on the ``band_name`` field: + + .. code-block:: tarantoolsession + create_db:instance001> box.space.bands:create_index('secondary', { parts = { 'band_name' } }) --- - unique: true @@ -205,86 +176,45 @@ To create a test database after installation: 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`) - -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 +.. _getting_started_db-start_writing_selecting_data: -Use the :ref:`net.box ` module to connect to the remote Tarantool -instance that is listening on ``localhost:3301``: +Writing and selecting data +~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: tarantoolsession - - tarantool> net_box = require('net.box') - --- - ... - tarantool> conn = net_box.connect(3301) - --- - ... +#. Insert three :term:`tuples ` into the space: -Then send a select request to ``instance001``: + .. code-block:: tarantoolsession -.. code-block:: tarantoolsession + 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] + ... - tarantool> conn.space.bands:select{2} - --- - - - [2, 'Scorpions', 1965] - ... +#. Select a tuple using the ``primary`` index: -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. + .. code-block:: tarantoolsession -You can repeat ``box.space...:insert{}`` and ``box.space...:select{}`` -(or ``conn.space...:insert{}`` and ``conn.space...:select{}``) -indefinitely, on either Tarantool instance. + create_db:instance001> box.space.bands:select { 3 } + --- + - - [3, 'Ace of Base', 1987] + ... -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: +#. Select tuples using the ``secondary`` index: -.. code-block:: console + .. code-block:: tarantoolsession - $ tt stop create_db \ No newline at end of file + create_db:instance001> box.space.bands.index.secondary:select{'Scorpions'} + --- + - - [2, 'Scorpions', 1965] + ... diff --git a/doc/how-to/getting_started_net_box.rst b/doc/how-to/getting_started_net_box.rst index 154892bce4..2bb229cec1 100644 --- a/doc/how-to/getting_started_net_box.rst +++ b/doc/how-to/getting_started_net_box.rst @@ -1,153 +1,221 @@ .. _getting_started_net_box: -Getting started with net.box -============================ +Connecting to a database using net.box +====================================== -The tutorial shows how to work with some common ``net.box`` methods. +**Examples on GitHub**: `sample_db `_, `net_box `_ -For more information about the ``net.box`` module, -check the :ref:`corresponding module reference `. +The tutorial shows how to use ``net.box`` to connect to a remote Tarantool instance, perform CRUD operations, and execute stored procedures. +For more information about the ``net.box`` module API, check :ref:`net_box-module`. -Sandbox configuration ---------------------- -The sandbox configuration for the tutorial assumes that: +.. _getting_started_net_box_sample_db: -* The Tarantool instance is running on ``localhost 127.0.0.1:3301``. -* There is a space named ``tester`` with a numeric primary key. -* The space contains a tuple with the key value = ``800``. -* The current user has read, write, and execute privileges. +Sample database configuration +----------------------------- -Use the commands below for a quick sandbox setup: +This section describes the :ref:`configuration ` of a sample database that allows remote connections: -.. code-block:: lua +.. literalinclude:: /code_snippets/snippets/connectors/instances.enabled/sample_db/config.yaml + :language: yaml + :dedent: - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) - t = s:insert({800, 'TEST'}) - box.schema.user.grant('guest', 'read,write,execute', 'universe') +- The configuration contains one instance that listens incoming requests on the ``127.0.0.1:3301`` address. +- ``sampleuser`` has :ref:`privileges ` to select and modify data in the ``bands`` space and execute the ``get_bands_older_than`` stored function. This user can be used to connect to the instance remotely. +- ``myapp.lua`` defines how data is stored in a database and includes a stored function. -Creating a net.box connection ------------------------------ +The ``myapp.lua`` file looks as follows: + +.. literalinclude:: /code_snippets/snippets/connectors/instances.enabled/sample_db/myapp.lua + :language: lua + :dedent: + +You can find the full example on GitHub: `sample_db `_. + + + + +.. _getting_started_net_box_interactive: + +Making net.box requests interactively +------------------------------------- -First, load the ``net.box`` module with the ``require('net.box')`` method: +To try out ``net.box`` requests in the interactive console, start the :ref:`sample_db ` application using ``tt start``: -.. code-block:: tarantoolsession +.. code-block:: console + + $ tt start sample_db + +Then, use the :ref:`tt run -i ` command to start an interactive console: + +.. code-block:: console + + $ tt run -i + Tarantool 3.0.0-entrypoint-1144-geaff238d9 + type 'help' for interactive help + tarantool> + +In the console, you can create a ``net.box`` connection and try out data operations. + + + +.. _getting_started_net_box_creating_connection: + +Creating a net.box connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - tarantool> net_box = require('net.box') +To load the ``net.box`` module, use the ``require()`` directive: -The next step is to create a new connection. -In ``net.box``, self-connection is pre-established. -That is, ``conn = net_box.connect('localhost:3301')`` command can be replaced with the ``conn = net_box.self`` object call: +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: net_box = require + :end-before: net_box.connect + :dedent: -.. code-block:: tarantoolsession +To create a connection, pass a database URI to the :ref:`net_box.connect() ` method: - tarantool> conn = net_box.self +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: net_box.connect + :end-before: conn:ping + :dedent: -Then, make a ping: +:ref:`connection:ping() ` can be used to check the connection status: -.. code-block:: tarantoolsession +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn:ping + :end-before: net_box_data_operations + :dedent: - tarantool> conn:ping() - --- - - true - ... + +.. _getting_started_net_box_using_data_operations: Using data operations ---------------------- +~~~~~~~~~~~~~~~~~~~~~ + +To get a space object and perform CRUD operations on it, use ``conn.space.``. + +.. NOTE:: + + Learn more about performing data operations from the :ref:`box_space_examples` section. + + +.. _getting_started_net_box_inserting_data: + +Inserting data +************** + +In the example below, four tuples are inserted into the ``bands`` space: + +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-after: Start net.box session + :end-before: conn.space.bands:select + :dedent: + -Select all tuples in the ``tester`` space where the key value is ``800``: -.. code-block:: tarantoolsession +.. _getting_started_net_box_querying_data: - tarantool> conn.space.tester:select{800} - --- - - - [800, 'TEST'] - ... +Querying data +************* -Insert two tuples into the space: +The example below shows how to get a tuple by the specified primary key value: -.. code-block:: tarantoolsession +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands:select + :end-before: conn.space.bands.index.band:select + :dedent: - tarantool> conn.space.tester:insert({700, 'TEST700'}) - --- - - [700, 'TEST700'] - ... - tarantool> conn.space.tester:insert({600, 'TEST600'}) - --- - - [600, 'TEST600'] - ... +You can also get a tuple by the value of the specified index as follows: -After the insert, there is one tuple where the key value is ``600``. -To select this tuple, you can use the ``get()`` method. -Unlike the ``select()`` command, ``get()`` returns only one tuple that satisfies the stated condition. +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands.index.band:select + :end-before: conn.space.bands:update + :dedent: -.. code-block:: tarantoolsession - tarantool> conn.space.tester:get({600}) - --- - - [600, 'TEST600'] - ... -To update the existing tuple, you can use either ``update()`` or ``upsert()``. -The ``update()`` method can be used for assignment, arithmetic (if the field is numeric), -cutting and pasting fragments of a field, and deleting or inserting a field. +.. _getting_started_net_box_updating_data: -In this tutorial, the ``update()`` command is used to update the tuple identified by primary key value = ``800``. -The operation assigns a new value to the second field in the tuple: +Updating data +************* -.. code-block:: tarantoolsession +:ref:`space_object.update() ` updates a tuple identified by the primary key. +This method accepts a full key and an operation to execute: - tarantool> conn.space.tester:update(800, {{'=', 2, 'TEST800'}}) - --- - - [800, 'TEST800'] - ... +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands:update + :end-before: conn.space.bands:upsert + :dedent: -As for the ``upsert`` function, if there is an existing tuple that matches the key field of tuple, then the command -has the same effect as ``update()``. -Otherwise, the effect is equal to the ``insert()`` method. +:ref:`space_object.upsert() ` updates an existing tuple or inserts a new one. +In the example below, a new tuple is inserted: -.. code-block:: tarantoolsession +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands:upsert + :end-before: conn.space.bands:replace + :dedent: - tarantool> conn.space.tester:upsert({500, 'TEST500'}, {{'=', 2, 'TEST'}}) -To delete a tuple where the key value is ``600``, run the ``delete()`` method below: +In this example, :ref:`space_object.replace() ` is used to delete the existing tuple and insert a new one: -.. code-block:: tarantoolsession +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands:replace + :end-before: conn.space.bands:delete + :dedent: - tarantool> conn.space.tester:delete{600} - --- - - [600, 'TEST600'] - ... -Then, replace the existing tuple with a new one: -.. code-block:: tarantoolsession - tarantool> conn.space.tester:replace{500, 'New data', 'Extra data'} - --- - - [500, 'New data', 'Extra data'] - ... +.. _getting_started_net_box_deleting_data: -Finally, select all tuples from the space: +Deleting data +************* -.. code-block:: tarantoolsession +The :ref:`space_object.delete() ` call in the example below deletes a tuple whose primary key value is ``5``: - tarantool> conn.space.tester:select{} - --- - - - [800, 'TEST800'] - - [500, 'New data', 'Extra data'] - - [700, 'TEST700'] - ... +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn.space.bands:delete + :end-before: conn:call + :dedent: + + + +.. _getting_started_net_box_stored_procedures: + +Executing stored procedures +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To execute a stored procedure, use the :ref:`connection:call() ` method: + +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn:call + :end-before: End net.box session + :dedent: + + +.. _getting_started_net_box_closing_connection: Closing the connection ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`connection:close() ` method can be used to close the connection when it is no longer needed: -In the end, close the connection when it is no longer needed: +.. literalinclude:: /code_snippets/snippets/connectors/net_box/myapp.lua + :language: lua + :start-at: conn:close() + :end-before: Close net.box connection + :dedent: -.. code-block:: tarantoolsession +.. NOTE:: - tarantool> conn:close() - --- - ... \ No newline at end of file + You can find the example with all the requests above on GitHub: `net_box `_. diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst index e8a1fb50c9..43a76fa933 100644 --- a/doc/how-to/index.rst +++ b/doc/how-to/index.rst @@ -17,12 +17,12 @@ If you are new to Tarantool, please see our :maxdepth: 2 Creating Tarantool database - getting_started_connectors db/index + replication/index + vshard_quick getting_started_tcm getting_started_net_box - vshard_quick + getting_started_connectors app/index - replication/index sql/index other/index