Модуль net.box
The net.box
module contains connectors to remote database systems. One
variant is for connecting to MySQL or MariaDB or PostgreSQL
(see SQL DBMS modules reference). The other variant, which
is discussed in this section, is for connecting to Tarantool server instances via a
network.
Examples on GitHub: sample_db, net_box
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 Модуль net.box.
Примечание
This tutorial shows how to make CRUD requests to a single-instance Tarantool database. To make requests to a sharded Tarantool cluster with the CRUD module, use its API for CRUD operations.
This section describes the configuration of a sample database that allows remote connections:
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'
- The configuration contains one instance that listens for incoming requests on the
127.0.0.1:3301
address. sampleuser
has privileges to select and modify data in thebands
space and execute theget_bands_older_than
stored function. This user can be used to connect to the instance remotely.myapp.lua
defines the data model and a stored function.
The myapp.lua
file looks as follows:
-- 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
]]
})
You can find the full example on GitHub: sample_db.
To try out net.box
requests in the interactive console, start the sample_db application using tt start
:
$ tt start sample_db
Then, use the tt run -i command to start an interactive 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.
To load the net.box
module, use the require()
directive:
net_box = require('net.box')
--[[
---
...
]]
To create a connection, pass a database URI to the net_box.connect() method:
conn = net_box.connect('sampleuser:123456@127.0.0.1:3301')
--[[
---
...
]]
connection:ping() can be used to check the connection status:
conn:ping()
--[[
---
- true
...
]]
Then, you can get a space object and perform CRUD operations on it using conn.space.<space_name>
.
Примечание
Learn more about performing data operations from the Примеры CRUD-операций section.
In the example below, four tuples are inserted into the bands
space:
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]
...
]]
The example below shows how to get a tuple by the specified primary key value:
conn.space.bands:select({ 1 })
--[[
---
- - [1, 'Roxette', 1986]
...
]]
You can also get a tuple by the value of the specified index as follows:
conn.space.bands.index.band:select({ 'The Beatles' })
--[[
---
- - [4, 'The Beatles', 1960]
...
]]
space_object.update() updates a tuple identified by the primary key. This method accepts a full key and an operation to execute:
conn.space.bands:update({ 2 }, { { '=', 'band_name', 'Pink Floyd' } })
--[[
---
- [2, 'Pink Floyd', 1965]
...
]]
space_object.upsert() updates an existing tuple or inserts a new one. In the example below, a new tuple is inserted:
conn.space.bands:upsert({ 5, 'The Rolling Stones', 1962 }, { { '=', 'band_name', 'The Doors' } })
--[[
---
...
]]
In this example, space_object.replace() is used to delete the existing tuple and insert a new one:
conn.space.bands:replace({ 1, 'Queen', 1970 })
--[[
---
- [1, 'Queen', 1970]
...
]]
The space_object.delete() call in the example below deletes a tuple whose primary key value is 5
:
conn.space.bands:delete({ 5 })
--[[
---
- [5, 'The Rolling Stones', 1962]
...
]]
To execute a stored procedure, use the connection:call() method:
conn:call('get_bands_older_than', { 1966 })
-- ---
-- - [[2, 'Pink Floyd', 1965], [4, 'The Beatles', 1960]]
-- ...
The connection:close() method can be used to close the connection when it is no longer needed:
conn:close()
--[[
---
...
]]
Примечание
You can find the example with all the requests above on GitHub: net_box.
Можно вызвать следующие методы:
require('net.box')
– для получения объектаnet.box
(который называетсяnet_box
для примеров в данном разделе);net_box.connect()
– для подключения и получения объекта подключения (который называетсяconn
для примеров в данном разделе);- другие процедуры
net.box()
, передающиеconn:
для выполнения запросов в удаленной системе базы данных; conn:close
– для отключения.
Все методы net.box
безопасны для файберов, то есть можно безопасно обмениваться и использовать один и тот же объект подключения в нескольких файберах одновременно. Фактически так лучше всего работать в Tarantool. Когда несколько файберов используют одно соединение, все запросы передаются по одному сетевому сокету, но каждый файбер получает правильный ответ. Уменьшение количества активных сокетов снижает затрату ресурсов на системные вызовы и увеличивает общую производительность сервера. Однако, в некоторых случаях отдельного соединения недостаточно — например, когда необходимо отдавать приоритет разным запросам или использовать различные идентификаторы при аутентификации.
В большинстве методов net.box
можно использовать последний аргумент {options}
, который может быть следующим:
{timeout=...}
. Например, метод с последним аргументом{timeout=1.5}
остановится через 1,5 секунды на локальном узле, хотя это не гарантирует, что выполнение остановится на удаленном сервере.{buffer=...}
. Например, см. модуль buffer.{is_async=...}
. Например, метод с заключительным аргументом{is_async=true}
не будет ждать результата выполнения запроса. См. описание is_async.{on_push=... on_push_ctx=...}
. Для получения внеполосных сообщений. См. описание box.session.push().{return_raw=...}
(since version 2.10.0). If set totrue
, net.box returns response data wrapped in a MsgPack object instead of decoding it to Lua. The default value isfalse
. For an example, see option description below.
На диаграмме ниже представлены возможные состояния и варианты перехода из одного состояния в другое:
На этой диаграмме:
- Метод
net_box.connect()
запускает рабочий файбер, который устанавливает соединение и запускает рабочий процесс. - The state machine goes to the
initial
state. - Authentication and schema upload.
It is possible later on to re-enter the
fetch_schema
state fromactive
to trigger schema reload. - The state changes to the
graceful_shutdown
state when the state machine receives a box.shutdown event from the remote host (see conn:on_shutdown()). Once all pending requests are completed, the state machine switches to theerror
(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 thereconnect_after
option is set, instead of the ‘error’ state, the transport goes to theerror_reconnect
state. conn.close()
method sets the state toclosed
and kills the worker. If the transport is already in theerror
state,close()
does nothing.
Ниже приведен перечень всех функций модуля net.box
.
Имя | Назначение |
---|---|
net_box.connect() net_box.new() net_box.self |
Создание подключения |
conn:ping() | Выполнение команды проверки состояния PING |
conn:wait_connected() | Ожидание активности или закрытия подключения |
conn:is_connected() | Проверка активности или закрытия подключения |
conn:wait_state() | Ожидание нужного состояния |
conn:close() | Закрытие подключения |
conn.space.space-name:select{field-value} | Выбор одного или нескольких кортежей |
conn.space.space-name:get{field-value} | Выбор кортежа |
conn.space.space-name:insert{field-value} | Вставка кортежа |
conn.space.space-name:replace{field-value} | Вставка или замена кортежа |
conn.space.space-name:update{field-value} | Обновление кортежа |
conn.space.space-name:upsert{field-value} | Обновление кортежа |
conn.space.space-name:delete{field-value} | Удаление кортежа |
conn:eval() | Оценка и выполнение выражения в строке |
conn:call() | Вызов хранимой процедуры |
conn:watch() | Subscribe to events broadcast by a remote host |
conn:on_connect() | Определение триггера на подключение |
conn:on_disconnect() | Определение триггера на отключение |
conn:on_shutdown() | Define a shutdown trigger |
conn:on_schema_reload() | Определение триггера при изменении схемы |
conn:new_stream() | Create a stream |
stream:begin() | Begin a stream transaction |
stream:commit() | Commit a stream transaction |
stream:rollback() | Rollback a stream transaction |
-
net_box.
connect
(URI[, {option[s]}])¶ Создание нового подключения. Подключение устанавливается по требованию во время первого запроса. Можно повторно установить подключение автоматически после отключения (см. ниже опцию
reconnect_after
). Возвращается объектconn
, который поддерживает методы создания удаленных запросов, таких как select, update или delete.Параметры: - URI (
string
) – URI объекта подключения - options –
the supported options are shown below:
user/password
: two options to connect to a remote host other than through URI. For example, instead ofconnect('username:userpassword@localhost:3301')
you can writeconnect('localhost:3301', {user = 'username', password='userpassword'})
.wait_connected
: a connection timeout. By default, the connection is blocked until the connection is established, but if you specifywait_connected=false
, the connection returns immediately. If you specify this timeout, it will wait before returning (wait_connected=1.5
makes it wait at most 1.5 seconds).Примечание
Если присутствует
reconnect_after
,wait_connected
проигнорирует неустойчивые отказы. Ожидание заканчивается, когда подключение установлено или явным образом закрыто.reconnect_after
: a number of seconds to wait before reconnecting. The default value, as with the otherconnect
options, isnil
. Ifreconnect_after
is greater than zero, then anet.box
instance will attempt to reconnect if a connection is lost or a connection attempt fails. This makes transient network failures transparent to the application. Reconnection happens automatically in the background, so requests that initially fail due to connection drops fail, are transparently retried. The number of retries is unlimited, connection retries are made after any specified interval (for example,reconnect_after=5
means that reconnect attempts are made every 5 seconds). When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop.connect_timeout
: a number of seconds to wait before returning «error: Connection timed out».fetch_schema
: a boolean option that controls fetching schema changes from the server. Default:true
. If you don’t operate with remote spaces, for example, run onlycall
oreval
, setfetch_schema
tofalse
to avoid fetching schema changes which is not needed in this case.Важно
In connections with
fetch_schema == false
, remote spaces are unavailable and the on_schema_reload triggers don’t work.required_protocol_version
: a minimum version of the IPROTO protocol supported by the server. If the version of the IPROTO protocol supported by the server is lower than specified, the connection will fail with an error message. Withrequired_protocol_version = 1
, all connections fail where the IPROTO protocol version is lower than1
.required_protocol_features
: specified IPROTO protocol features supported by the server. You can specify one or morenet.box
features from the table below. If the server does not support the specified features, the connection will fail with an error message. Withrequired_protocol_features = {'transactions'}
, all connections fail where the server hastransactions: false
.
net.box feature Назначение IPROTO feature ID IPROTO versions supporting the feature streams
Requires streams support on the server IPROTO_FEATURE_STREAMS 1 and newer transactions
Requires transactions support on the server IPROTO_FEATURE_TRANSACTIONS 1 and newer error_extension
Requires support for MP_ERROR MsgPack extension on the server IPROTO_FEATURE_ERROR_EXTENSION 2 and newer watchers
Requires remote watchers support on the server IPROTO_FEATURE_WATCHERS 3 and newer To learn more about IPROTO features, see IPROTO_ID and the IPROTO_FEATURES key.
возвращает: объект подключения тип возвращаемого значения: пользовательские данные Примеры:
net_box = require('net.box') conn = net_box.connect('localhost:3301') conn = net_box.connect('127.0.0.1:3302', {wait_connected = false}) conn = net_box.connect('127.0.0.1:3304', {required_protocol_version = 4, required_protocol_features = {'transactions', 'streams'}, })
- URI (
-
net_box.
new
(URI[, {option[s]}])¶ new()
is a synonym forconnect()
. It is retained for backward compatibility. For more information, see the description of net_box.connect().
-
object
self
¶ Для локального Tarantool-сервера есть заданный объект всегда установленного подключения под названием
net_box.self
. Он создан с целью облегчить полиморфное использование API модуляnet_box
. Таким образом,conn = net_box.connect('localhost:3301')
можно заменить наconn = net_box.self
.Однако, есть важно отличие встроенного подключения от удаленного:
- With the embedded connection, requests which do not modify data do not yield. When using a remote connection, due to the implicit rules any request can yield, and the database state may have changed by the time it regains control.
- Не учитывается ни один параметр, передаваемый в запросе (
is_async
,on_push
,timeout
).
-
object
conn
¶ -
conn:
ping
([options])¶ Выполнение команды проверки состояния PING.
Параметры: - options (
table
) – поддерживается опцияtimeout=секунды
возвращает: true (правда), если выполнено, false (ложь) в случае ошибки
тип возвращаемого значения: boolean (логический)
Пример:
net_box.self:ping({timeout = 0.5})
- options (
-
conn:
wait_connected
([timeout])¶ Ожидание активности или закрытия подключения.
Параметры: - timeout (
number
) – в секундах
возвращает: true (правда) при подключении, false (ложь), если не выполнено.
тип возвращаемого значения: boolean (логический)
Пример:
net_box.self:wait_connected()
- timeout (
-
conn:
is_connected
()¶ Проверка активности или закрытия подключения.
возвращает: true (правда) при подключении, false (ложь), если не выполнено. тип возвращаемого значения: boolean (логический) Пример:
net_box.self:is_connected()
-
conn:
wait_state
(state[s][, timeout])¶ [с 1.7.2] Ожидание нужного состояния.
Параметры: - states (
string
) – необходимое состояние - timeout (
number
) – в секундах
возвращает: true (правда) при подключении, false (ложь) при окончании времени ожидания или закрытии подключения
тип возвращаемого значения: boolean (логический)
Примеры:
-- бесконечное ожидание состояния 'active': conn:wait_state('active') -- ожидание в течение максимум 1,5 секунд: conn:wait_state('active', 1.5) -- бесконечное ожидание состояния `active` или `fetch_schema`: conn:wait_state({active=true, fetch_schema=true})
- states (
-
conn:
close
()¶ Закрытие подключения.
Объекты подключения удаляются сборщиком мусора в Lua, как и любой другой Lua-объект, поэтому удалять их явным образом необязательно. Однако, поскольку close() представляет собой системный вызов, лучше всего закрыть соединение явным образом, когда оно больше не используется, с целью ускорения работы сборщика мусора.
Пример:
conn:close()
-
conn.space.<space-name>:select({field-value, ...} [, {options}])
conn.space.имя-спейса:select
({...})
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:select
{...}
(детали). В дополнение см. Модуль buffer и skip-header.Пример:
conn.space.testspace:select({1,'B'}, {timeout=1})
Примечание
Due to the implicit yield rules a local
box.space.space-name:select
{...}
does not yield, but a remoteconn.space.space-name:select
{...}
call does yield, so global variables or database tuples data may change when a remoteconn.space.space-name:select
{...}
occurs.
-
conn.space.<space-name>:get({field-value, ...} [, {options}])
conn.space.имя-спейса:get(...)
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:get(...)
(детали).Пример:
conn.space.testspace:get({1})
-
conn.space.<space-name>:insert({field-value, ...} [, {options}])
conn.space.имя-спейса:insert(...)
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:insert(...)
(детали). В дополнение см. Модуль buffer и skip-header.Пример:
conn.space.testspace:insert({2,3,4,5}, {timeout=1.1})
-
conn.space.<space-name>:replace({field-value, ...} [, {options}])
conn.space.имя-спейса:replace(...)
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:replace(...)
(детали). В дополнение см. Модуль buffer и skip-header.Пример:
conn.space.testspace:replace({5,6,7,8})
-
conn.space.<space-name>:update({field-value, ...} [, {options}])
conn.space.имя-спейса:update(...)
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:update(...)
.Пример:
conn.space.Q:update({1},{{'=',2,5}}, {timeout=0})
-
conn.space.<space-name>:upsert({field-value, ...} [, {options}])
conn.space.space-name:upsert(...)
is the remote-call equivalent of the local callbox.space.space-name:upsert(...)
. (see details). For an additional option see Module buffer and skip-header.
-
conn.space.<space-name>:delete({field-value, ...} [, {options}])
conn.space.имя-спейса:delete(...)
– это удаленный вызов, аналогичный локальному вызовуbox.space.имя-спейса:delete(...)
.(детали). В дополнение см. Модуль buffer и skip-header.
-
conn:
eval
(Lua-string[, {arguments}[, {options}]])¶ conn:eval(Lua-строка)
оценивает и выполняет выражение в Lua-строке, которое может представлять собой любое выражение или несколько выражений. Требуются права на выполнение; если у пользователя таких прав нет, администратор может их выдать с помощьюbox.schema.user.grant(имя-пользователя, 'execute', 'universe')
.Чтобы гарантировать, что
conn:eval
вернет то, что возвращает выражение на Lua, начните Lua-строку со слова «return» (вернуть).Примеры:
tarantool> --Lua-строка tarantool> conn:eval('function f5() return 5+5 end; return f5();') --- - 10 ... tarantool> --Lua-строка, {аргументы} tarantool> conn:eval('return ...', {1,2,{3,'x'}}) --- - 1 - 2 - [3, 'x'] ... tarantool> --Lua-строка, {аргументы}, {парметры} tarantool> conn:eval('return {nil,5}', {}, {timeout=0.1}) --- - [null, 5] ...
-
conn:
call
(function-name[, {arguments}[, {options}]])¶ conn:call('func', {'1', '2', '3'})
– это удаленный вызов, аналогичныйfunc('1', '2', '3')
. Таким образом,conn:call
представляет собой удаленный вызов хранимой процедуры.conn:call
возвращает то, что возвращает функция.Ограничение: вызванная функция не может вернуть функцию, например, если
func2
определяется какfunction func2 () return func end
, тоconn:call(func2)
вернет ошибку «error: unsupported Lua type „function“».Примеры:
tarantool> -- создание 2 функций с conn:eval() tarantool> conn:eval('function f1() return 5+5 end;') tarantool> conn:eval('function f2(x,y) return x,y end;') tarantool> -- вызов первой функции без параметров и опций tarantool> conn:call('f1') --- - 10 ... tarantool> -- вызов второй функции с двумя параметрами и одной опцией tarantool> conn:call('f2',{1,'B'},{timeout=99}) --- - 1 - B ...
-
conn:
watch
(key, func)¶ Subscribe to events broadcast by a remote host.
Параметры: - key (
string
) – a key name of an event to subscribe to - func (
function
) – a callback to invoke when the key value is updated
возвращает: a watcher handle. The handle consists of one method –
unregister()
, which unregisters the watcher.To read more about watchers, see the Functions for watchers section.
The method has the same syntax as the box.watch() function, which is used for subscribing to events locally.
Watchers survive reconnection (see the
reconnect_after
connection option). All registered watchers are automatically resubscribed when the connection is reestablished.If a remote host supports watchers, the
watchers
key will be set in the connectionpeer_protocol_features
. For details, check the net.box features table.Примечание
Keep in mind that garbage collection of a watcher handle doesn’t lead to the watcher’s destruction. In this case, the watcher remains registered. It is okay to discard the result of
watch
function if the watcher will never be unregistered.Example 1:
Server:
-- Broadcast value 42 for the 'foo' key. box.broadcast('foo', 42)
Client:
conn = net.box.connect(URI) local log = require('log') -- Subscribe to updates of the 'foo' key. w = conn:watch('foo', function(key, value) assert(key == 'foo') log.info("The box.id value is '%d'", value) end)
If you don’t need the watcher anymore, you can unregister it using the command below:
w:unregister()
Example 2:
The
net.box module
provides the ability to monitor updates of a configuration stored in a Tarantool-based configuration storage by watching path or prefix changes. In the example below, conn:watch() is used to monitor updates of a configuration stored by the/myapp/config/all
path:net_box = require('net.box') local conn = net_box.connect('127.0.0.1:4401') local log = require('log') conn:watch('config.storage:/myapp/config/all', function(key, value) log.info("Configuration stored by the '/myapp/config/all' key is changed") end)
You can find the full example here: config_storage.
- key (
-
conn:
request
(... {is_async=...})¶ {is_async=true|false}
– это опция, которую можно применить во всех запросахnet_box
, включаяconn:call
,conn:eval
и запросыconn.space.space-name
.По умолчанию,
is_async=false
, что означает, что запросы будут синхронными для файбера. Файбер блокируется в ожидании ответа на запрос или до истечения времени ожидания. До версии Tarantool 1.10 единственным способом выполнения асинхронных запросов было использование отдельных файберов.is_async=true
означает, что запросы будут асинхронными для файбера. Запрос вызывает передачу управления, но файбер не входит в режим ожидания. Сразу же возвращается результат, но это будет не результат запроса, а объект, который может использовать вызывающая программа для получения результат запроса.У такого сразу же возвращаемого объекта, который мы называем «future» (будущий), есть собственные методы:
future:is_ready()
вернет true (правда), если доступен результат запроса,future:result()
используется для получения результата запроса (возвращает ответ на запрос или nil в случае, если ответ еще не готов или произошла какая-либо ошибка),future:wait_result(timeout)
будет ждать, когда результат запроса будет доступен, а затем получит его или выдаст ошибку, если по истечении времени ожидания результат не получен.future:discard()
откажется от объекта.
В обычной ситуации пользователь введет команду
future=имя-запроса(...{is_async=true})
, а затем либо цикл с проверкойfuture:is_ready()
до тех пор, пока он не вернет true, и получением результата с помощьюrequest_result=future:result()
, либо же командуrequest_result=future:wait_result(...)
. Возможен вариант, когда клиент проверяет наличие внеполосных сообщений от сервера, вызывая в циклеpairs()
– см. box.session.push().Можно использовать
future:discard()
, чтобы соединение забыло об ответе – если получен ответ для отброшенного объекта, то он будет проигнорирован, так что размер таблицы запросов будет уменьшен, а другие запросы будут выполняться быстрее.Примеры:
-- Insert a tuple asynchronously -- tarantool> future = conn.space.bands:insert({10, 'Queen', 1970}, {is_async=true}) --- ... tarantool> future:is_ready() --- - true ... tarantool> future:result() --- - [10, 'Queen', 1970] ... -- Iterate through a space with 10 records to get data in chunks of 3 records -- tarantool> while true do future = conn.space.bands:select({}, {limit=3, after=position, fetch_pos=true, is_async=true}) result = future:wait_result() tuples = result[1] position = result[2] if position == nil then break end print('Chunk size: '..#tuples) end Chunk size: 3 Chunk size: 3 Chunk size: 3 Chunk size: 1 --- ...
Как правило,
{is_async=true}
используется только при большой загрузке (более 100 000 запросов в секунду) и большой задержке чтения (более 1 секунды), или же при необходимости отправки нескольких одновременных запросов, которые собирают ответы (что иногда называется «отображение-свертка»).Примечание
Хотя окончательный результат асинхронного запроса не отличается от результата синхронного запроса, у него другая структура: таблица, а не неупакованные значения.
-
conn:
request
(... {return_raw=...}) {return_raw=true}
is ignored for:- Methods that return
nil
:begin
,commit
,rollback
,upsert
,prepare
. index.count
(returns number).
For
execute
, the option is applied only to data (rows
). Metadata is decoded even if{return_raw=true}
.Пример:
local c = require('net.box').connect(uri) local mp = c.eval('eval ...', {1, 2, 3}, {return_raw = true}) mp:decode() -- {1, 2, 3}
The option can be useful if you want to pass a response through without decoding or with partial decoding. The usage of MsgPack object can reduce pressure on the Lua garbage collector.
- Methods that return
-
conn:
new_stream
()¶ Create a stream.
Пример:
-- Start a server to create a new stream local conn = net_box.connect('localhost:3301') local conn_space = conn.space.test local stream = conn:new_stream() local stream_space = stream.space.test
-
-
object
stream
¶ -
stream:
begin
([txn_isolation])¶ Begin a stream transaction. Instead of the direct method, you can also use the
call
,eval
or execute methods with SQL transaction.Параметры: - txn_isolation – transaction isolation level
-
stream:
commit
()¶ Commit a stream transaction. Instead of the direct method, you can also use the
call
,eval
or execute methods with SQL transaction.Примеры:
-- Begin stream transaction stream:begin() -- In the previously created ``accounts`` space with the primary key ``test``, modify the fields 2 and 3 stream.space.accounts:update(test_1, {{'-', 2, 370}, {'+', 3, 100}}) -- Commit stream transaction stream:commit()
-
stream:
rollback
()¶ Rollback a stream transaction. Instead of the direct method, you can also use the
call
,eval
or execute methods with SQL transaction.Пример:
-- Test rollback for memtx space space:replace({1}) -- Select return tuple that was previously inserted, because this select belongs to stream transaction space:select({}) stream:rollback() -- Select is empty, stream transaction rollback space:select({})
-
В модуле net.box
можно использовать следующие триггеры:
-
conn:
on_connect
([trigger-function[, old-trigger-function]])¶ Define a trigger for execution when a new connection is established, and authentication and schema fetch are completed due to an event such as
net_box.connect
.If a trigger function issues
net_box
requests, they must be asynchronous ({is_async = true}
). An attempt to wait for request completion withfuture:pairs()
orfuture:wait_result()
in the trigger function will result in an error.If the trigger execution fails and an exception happens, the connection’s state changes to „error“. In this case, the connection is terminated, regardless of the
reconnect_after
option’s value. Can be called as many times as reconnection happens, ifreconnect_after
is greater than zero.Параметры: - trigger-function (
function
) – the trigger function. Takes theconn
object as the first argument. - old-trigger-function (
function
) – an existing trigger function to replace withtrigger-function
возвращает: nil или указатель функции
- trigger-function (
-
conn:
on_disconnect
([trigger-function[, old-trigger-function]])¶ Определение триггера, исполняемого после закрытия соединения. Если функция с триггером вызывает ошибку, то ошибка записывается в журнал, в противном случае записей не будет. Выполнение прекращается после явного закрытия соединения или удаления сборщиком мусора в Lua.
Параметры: - trigger-function (
function
) – the trigger function. Takes theconn
object as the first argument - old-trigger-function (
function
) – an existing trigger function to replace withtrigger-function
возвращает: nil или указатель функции
- trigger-function (
-
conn:
on_shutdown
([trigger-function[, old-trigger-function]])¶ Define a trigger for shutdown when a box.shutdown event is received.
The trigger starts in a new fiber. While the
on_shutdown()
trigger is running, the connection stays active. It means that the trigger callback is allowed to send new requests.After the trigger return, the
net.box
connection goes to thegraceful_shutdown
state (check the state diagram for details). In this state, no new requests are allowed. The connection waits for all pending requests to be completed.Once all in-progress requests have been processed, the connection is closed. The state changes to
error
orerror_reconnect
(if thereconnect_after
option is defined).Servers that do not support the
box.shutdown
event or IPROTO_WATCH just close the connection abruptly. In this case, theon_shutdown()
trigger is not executed.Параметры: - trigger-function (
function
) – the trigger function. Takes theconn
object as the first argument - old-trigger-function (
function
) – an existing trigger function to replace withtrigger-function
возвращает: nil или указатель функции
- trigger-function (
-
conn:
on_schema_reload
([trigger-function[, old-trigger-function]])¶ Определение триггера, исполняемого во время выполнения определенной операции на удаленном сервере после обновления схемы. Другими словами, если запрос к серверу не выполняется из-за ошибки несовпадения версии схемы, происходит перезагрузка схемы.
If a trigger function issues
net_box
requests, they must be asynchronous ({is_async = true}
). An attempt to wait for request completion withfuture:pairs()
orfuture:wait_result()
in the trigger function will result in an error.Параметры: - trigger-function (
function
) – the trigger function. Takes theconn
object as the first argument - old-trigger-function (
function
) – an existing trigger function to replace withtrigger-function
возвращает: nil или указатель функции
Примечание
Если указаны параметры
(nil, old-trigger-function)
, старый триггер будет удален.Если не указан ни один параметр, ответом будет список существующих функций с триггером.
Find the detailed information about triggers in the triggers section.
- trigger-function (