Module tarantool::net_box

The net_box module contains connector to remote Tarantool server instances via a network.

You can call the following methods:

• Conn::new() to connect and get a connection object (named conn for examples in this section),
• other net_box routines, to execute requests on the remote database system,
• conn.close() to disconnect.

All Conn 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 Conn methods allow a options argument. See Options structure docs for details.

The diagram below shows possible connection states and transitions:

connecting -> initial +-> active                                                                                    
                       \                                                                                            
                        +-> auth -> fetch_schema <-> active                                                         
                                                                                                                     
 (any state, on error) -> error_reconnect -> connecting -> ...                                                      
                                          \                                                                         
                                            -> [error]                                                              
 (any_state, but [error]) -> [closed]

On this diagram:

• The state machine starts in the initial state.
• Conn::new() method changes the state to connecting and spawns a worker fiber.
• If authentication and schema upload are required, it’s possible later on to re-enter the fetch_schema state from active if a request fails due to a schema version mismatch error, so schema reload is triggered.
• conn.close() method sets the state to closed and kills the worker. If the transport is already in the error state, close() does nothing.

See also:

• Lua reference: Module net.box

Structs

Conn	Connection to remote Tarantool server
ConnOptions	Connection options; see Conn::new()
Options	Most Conn methods allows to pass an options argument
RemoteIndex	Remote index (a group of key values and pointers)
RemoteIndexIterator	Remote index iterator. Can be used with for statement
RemoteSpace	Remote space

Traits

ConnTriggers

Provides triggers for connect, disconnect and schema reload events.