Модуль net.box¶
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 —
that variant is the subject of the SQL DBMS modules reference.
In this section the subject is the built-in variant, net.box
. This is for
connecting to tarantool servers via a network.
Call require('net.box')
to get a net.box
object, which will be called
net_box
for examples in this section. Call net_box.new()
to connect and
get a connection object, which will be called conn
for examples in this section.
Call the other net.box()
routines, passing conn:
, to execute requests on
the remote box. Call 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, it’s 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. There
are, however, cases when a single connection is not enough — for example when it’s
necessary to prioritize requests or to use different authentication ids.
-
net_box.
new
(URI[, {option[s]}])¶ Create a new connection. The connection is established on demand, at the time of the first request. It is re-established automatically after a disconnect. The returned
conn
object supports methods for making remote requests, such as select, update or delete.For the local tarantool server there is a pre-created always-established connection object named
net_box.self
. Its purpose is to make polymorphic use of thenet_box
API easier. Thereforeconn = net_box.new('localhost:3301')
can be replaced byconn = net_box.self
. However, there is an important difference between the embedded connection and a remote one. 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 database state may have changed by the time it regains control.Параметры: - URI (string) – the URI of the target for the connection
- options – a possible option is wait_connect
Return: conn object
Rtype: userdata
Example:
conn = net_box.new('localhost:3301') conn = net_box.new('127.0.0.1:3306', {wait_connect = false})
-
object
conn
¶ -
conn:
ping
()¶ Execute a PING command.
Return: true on success, false on error Rtype: boolean Example:
net_box.self:ping()
-
conn:
wait_connected
([timeout])¶ Wait for connection to be active or closed.
Параметры: - timeout (number) –
Return: true when connected, false on failure.
Rtype: boolean
Example:
net_box.self:wait_connected()
-
conn:
is_connected
()¶ Show whether connection is active or closed.
Return: true if connected, false on failure. Rtype: boolean Example:
net_box.self:is_connected()
-
conn:
close
()¶ Close a connection.
Connection objects are garbage collected just like any other objects in Lua, so an explicit destruction is not mandatory. However, since close() is a system call, it is good programming practice to close a connection explicitly when it is no longer needed, to avoid lengthy stalls of the garbage collector.
Example:
conn:close()
-
conn.space.<space-name>:select{field-value, ...}
conn.space.space-name:select
{...}
is the remote-call equivalent of the local callbox.space.space-name:select
{...}
.Примечание
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, ...}
conn.space.space-name:get(...)
is the remote-call equivalent of the local callbox.space.space-name:get(...)
.
-
conn.space.<space-name>:insert{field-value, ...}
conn.space.space-name:insert(...)
is the remote-call equivalent of the local callbox.space.space-name:insert(...)
.
-
conn.space.<space-name>:replace{field-value, ...}
conn.space.space-name:replace(...)
is the remote-call equivalent of the local callbox.space.space-name:replace(...)
.
-
conn.space.<space-name>:update{field-value, ...}
conn.space.space-name:update(...)
is the remote-call equivalent of the local callbox.space.space-name:update(...)
.
-
conn.space.<space-name>:upsert{field-value, ...}
conn.space.space-name:upsert(...)
is the remote-call equivalent of the local callbox.space.space-name:upsert(...)
.
-
conn.space.<space-name>:delete{field-value, ...}
conn.space.space-name:delete(...)
is the remote-call equivalent of the local callbox.space.space-name:delete(...)
.
-
conn:
call
(function-name[, arguments])¶ conn:call('func', '1', '2', '3')
is the remote-call equivalent offunc('1', '2', '3')
. That is,conn:call
is a remote stored-procedure call.Example:
conn:call('function5')
-
conn:
eval
(Lua-string)¶ conn:eval(Lua-string)
evaluates and executes the expression in Lua-string, which may be any statement or series of statements. An execute privilege is required; if the user does not have it, an administrator may grant it withbox.schema.user.grant(username, 'execute', 'universe')
.Example:
conn:eval('return 5+5')
-
conn:
timeout
(timeout)¶ timeout(...)
is a wrapper which sets a timeout for the request that follows it.Example:
conn:timeout(0.5).space.tester:update({1}, {{'=', 2, 15}})
All remote calls support execution timeouts. Using a wrapper object makes the remote connection API compatible with the local one, removing the need for a separate
timeout
argument, which the local version would ignore. Once a request is sent, it cannot be revoked from the remote server even if a timeout expires: the timeout expiration only aborts the wait for the remote server response, not the request itself.
-
Example showing use of most of the net.box methods¶
This example will work with the sandbox configuration described in the preface.
That is, there is a space named tester with a numeric primary key. Assume that
the database is nearly empty. Assume that the tarantool server is running on
localhost 127.0.0.1:3301
.
tarantool> net_box = require('net.box')
---
...
tarantool> function example()
> local conn, wtuple
> if net_box.self:ping() then
> table.insert(ta, 'self:ping() succeeded')
> table.insert(ta, ' (no surprise -- self connection is pre-established)')
> end
> if box.cfg.listen == '3301' then
> table.insert(ta,'The local server listen address = 3301')
> else
> table.insert(ta, 'The local server listen address is not 3301')
> table.insert(ta, '( (maybe box.cfg{...listen="3301"...} was not stated)')
> table.insert(ta, '( (so connect will fail)')
> end
> conn = net_box.new('127.0.0.1:3301')
> conn.space.tester:delete{800}
> table.insert(ta, 'conn delete done on tester.')
> conn.space.tester:insert{800, 'data'}
> table.insert(ta, 'conn insert done on tester, index 0')
> table.insert(ta, ' primary key value = 800.')
> wtuple = conn.space.tester:select{800}
> table.insert(ta, 'conn select done on tester, index 0')
> table.insert(ta, ' number of fields = ' .. #wtuple)
> conn.space.tester:delete{800}
> table.insert(ta, 'conn delete done on tester')
> conn.space.tester:replace{800, 'New data', 'Extra data'}
> table.insert(ta, 'conn:replace done on tester')
> conn:timeout(0.5).space.tester:update({800}, {{'=', 2, 'Fld#1'}})
> table.insert(ta, 'conn update done on tester')
> conn:close()
> table.insert(ta, 'conn close done')
> end
---
...
tarantool> ta = {}
---
...
tarantool> example()
---
...
tarantool> ta
---
- - self:ping() succeeded
- ' (no surprise -- self connection is pre-established)'
- The local server listen address = 3301
- conn delete done on tester.
- conn insert done on tester, index 0
- ' primary key value = 800.'
- conn select done on tester, index 0
- ' number of fields = 1'
- conn delete done on tester
- conn:replace done on tester
- conn update done on tester
- conn close done
...