Zen

Source string Source string

213/10000 · 213
English Actions
Module net.box
Overview
The ``net.box`` module contains connectors to remote database systems. One variant, to be discussed later, is for connecting to MySQL or MariaDB or PostgreSQL (see :ref:`SQL DBMS modules <dbms_modules>` reference). The other variant, which is discussed in this section, is for connecting to Tarantool server instances via a network. For a quick start with ``net.box``, refer to the :ref:`tutorial <getting_started_net_box>`.
You can call the following methods:
``require('net.box')`` -- to get a ``net.box`` object (named ``net_box`` for examples in this section)
``net_box.connect()`` -- to connect and get a connection object (named ``conn`` for examples in this section)
other ``net.box()`` routines, passing ``conn:``, to execute requests on the remote database system
``conn:close`` -- to disconnect
All ``net.box`` methods are fiber-safe, that is, it is safe to share and use the same connection object across multiple concurrent fibers. In fact that is perhaps the best programming practice with Tarantool. When multiple fibers use the same connection, all requests are pipelined through the same network socket, but each fiber gets back a correct response. Reducing the number of active sockets lowers the overhead of system calls and increases the overall server performance. However for some cases a single connection is not enough -- for example, when it is necessary to prioritize requests or to use different authentication IDs.
Most ``net.box`` methods accept the last ``{options}`` argument, which can be:
``{timeout=...}``. For example, a method whose last argument is ``{timeout=1.5}`` will stop after 1.5 seconds on the local node, although this does not guarantee that execution will stop on the remote server node.
``{buffer=...}``. For an example, see the :ref:`buffer module <buffer-module>`.
``{is_async=...}``. For example, a method whose last argument is ``{is_async=true}`` will not wait for the result of a request. See the :ref:`is_async <net_box-is_async>` description.
``{on_push=... on_push_ctx=...}``. For receiving out-of-band messages. See the :doc:`/reference/reference_lua/box_session/push` description.
``{return_raw=...}`` (since version 2.10.0). If set to ``true``, net.box returns response data wrapped in a :ref:`MsgPack object <msgpack-object-info>` instead of decoding it to Lua. The default value is ``false``. For an example, see option description :ref:`below <net_box-return_raw>`.
The diagram below shows possible connection states and transitions:
net_states.png
On this diagram:
``net_box.connect()`` method spawns a worker fiber, which will establish the connection and start the state machine.
The state machine goes to the ``initial`` state.
Authentication and schema upload. It is possible later on to re-enter the ``fetch_schema`` state from ``active`` to trigger schema reload.
The state changes to the ``graceful_shutdown`` state when the state machine receives a :ref:`box.shutdown <system-events_box-shutdown>` event from the remote host (see :ref:`conn:on_shutdown() <net_box-on_shutdown>`). Once all pending requests are completed, the state machine switches to the ``error`` (``error_reconnect``) state.
The transport goes to the ``error`` state in case of an error. It can happen, for example, if the server closed the connection. If the ``reconnect_after`` option is set, instead of the ‘error’ state, the transport goes to the ``error_reconnect`` state.
``conn.close()`` method sets the state to ``closed`` and kills the worker. If the transport is already in the ``error`` state, ``close()`` does nothing.
Index
Below is a list of all ``net.box`` functions.

Loading…

User avatar None

New source string

testing_project / Documentation: reference/reference_lua/net_box — English

``{timeout=...}``. For example, a method whose last argument is ``{timeout=1.5}`` will stop after 1.5 seconds on the local node, although this does not guarantee that execution will stop on the remote server node.
a year ago
Browse all string changes

Things to check

Ellipsis

The string uses three dots (...) instead of an ellipsis character (…)

Reset

Glossary

English English
No related strings found in the glossary.

String information

Flags
read-only
String age
a year ago
Last updated
a year ago
Source string age
a year ago
Translation file
string 11