module tarantool.mesh_connection
¶
This module provides API for interaction with Tarantool servers cluster.
- class tarantool.mesh_connection.MeshConnection(host=None, port=None, socket_fd=None, user=None, password=None, socket_timeout=None, reconnect_max_attempts=10, reconnect_delay=0.1, connect_now=True, encoding='utf-8', call_16=False, connection_timeout=None, transport='', ssl_key_file=None, ssl_cert_file=None, ssl_ca_file=None, ssl_ciphers=None, ssl_password=None, ssl_password_file=None, auth_type=None, addrs=None, strategy_class=<class 'tarantool.mesh_connection.RoundRobinStrategy'>, cluster_discovery_function=None, cluster_discovery_delay=60, fetch_schema=True)¶
Represents a connection to a cluster of Tarantool servers.
- Parameters:
host¶ – Refer to
host
. Value would be used to add one more server inaddrs
list.port¶ – Refer to
port
. Value would be used to add one more server inaddrs
list.socket_fd¶ – Refer to
socket_fd
. Value would be used to add one more server inaddrs
list.user¶ – Refer to
user
. Value would be used to add one more server inaddrs
list.password¶ – Refer to
password
. Value would be used to add one more server inaddrs
list.socket_timeout¶ – Refer to
socket_timeout
. Value would be used for the current active connection.reconnect_max_attempts¶ – Refer to
reconnect_max_attempts
. Value would be used for the current active connection.reconnect_delay¶ – Refer to
reconnect_delay
. Value would be used for the current active connection.connect_now¶ (
bool
, optional) – IfTrue
, connect to server on initialization. Otherwise, you have to callconnect()
manually after initialization.encoding¶ – Refer to
encoding
. Value would be used for the current active connection.call_16¶ – Refer to
call_16
. Value would be used for the current active connection.connection_timeout¶ – Refer to
connection_timeout
. Value would be used for the current active connection.transport¶ – Refer to
transport
. Value would be used to add one more server inaddrs
list.ssl_key_file¶ – Refer to
ssl_key_file
. Value would be used to add one more server inaddrs
list.ssl_cert_file¶ – Refer to
ssl_cert_file
. Value would be used to add one more server inaddrs
list.ssl_ca_file¶ – Refer to
ssl_ca_file
. Value would be used to add one more server inaddrs
list.ssl_ciphers¶ – Refer to
ssl_ciphers
. Value would be used to add one more server inaddrs
list.auth_type¶ – Refer to
auth_type
. Value would be used to add one more server inaddrs
list.strategy_class¶ (
object
, optional) – Strategy for choosing a server after the current server fails. Defaults to the round-robin strategy.cluster_discovery_function¶ (
str
orNone
, optional) –sets the name of the stored Lua function used to refresh the list of available nodes. The function takes no parameters and returns a list of strings in the format
'host:port'
. A generic function for getting the list of nodes looks like this:function get_cluster_nodes() return { '192.168.0.1:3301', '192.168.0.2:3302?transport=ssl&ssl_ca_file=/path/to/ca.cert', -- ... } end
You can put in this list whatever you need, depending on your cluster topology. Chances are you’ll want to derive the list of nodes from the nodes’ replication configuration. Here is an example:
local uri_lib = require('uri') function get_cluster_nodes() local nodes = {} local replicas = box.cfg.replication for i = 1, #replicas do local uri = uri_lib.parse(replicas[i]) if uri.host and uri.service then table.insert(nodes, uri.host .. ':' .. uri.service) end end -- if your replication config doesn't contain the current node, -- you have to add it manually like this: table.insert(nodes, '192.168.0.1:3301') return nodes end
cluster_discovery_delay¶ (
float
, optional) – Minimal time between address list refresh.fetch_schema¶ – Refer to
fetch_schema
.
- Raises:
ConfigurationError
,Connection
exceptions,connect
exceptions
- Error = <class 'tarantool.error.Error'>
DBAPI compatibility.
- Value:
- DatabaseError = <class 'tarantool.error.DatabaseError'>
DBAPI compatibility.
- Value:
- InterfaceError = <class 'tarantool.error.InterfaceError'>
DBAPI compatibility.
- Value:
- ConfigurationError = <class 'tarantool.error.ConfigurationError'>
DBAPI compatibility.
- Value:
- SchemaError = <class 'tarantool.error.SchemaError'>
DBAPI compatibility.
- Value:
- NetworkError = <class 'tarantool.error.NetworkError'>
DBAPI compatibility.
- Value:
- Warning = <class 'Warning'>
DBAPI compatibility.
- Value:
Warning
- DataError = <class 'tarantool.error.DataError'>
DBAPI compatibility.
- Value:
- OperationalError = <class 'tarantool.error.OperationalError'>
DBAPI compatibility.
- Value:
- IntegrityError = <class 'tarantool.error.IntegrityError'>
DBAPI compatibility.
- Value:
- InternalError = <class 'tarantool.error.InternalError'>
DBAPI compatibility.
- Value:
- ProgrammingError = <class 'tarantool.error.ProgrammingError'>
DBAPI compatibility.
- Value:
- NotSupportedError = <class 'tarantool.error.NotSupportedError'>
DBAPI compatibility.
- Value:
- exception CrudModuleError(_, error)¶
Exception raised for errors that are related to the operation result of crud module.
Sets fields with result and errors.
- Parameters:
args (
tuple
) – The tuple from the crud module with result and errors.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- authenticate(user, password)¶
Execute an AUTHENTICATE request: authenticate a connection. There is no need to call this method explicitly until you want to reauthenticate with different parameters.
- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- call(func_name, *args, on_push=None, on_push_ctx=None)¶
Execute a CALL request: call a stored Lua function.
- Parameters:
- Return type:
- Raise:
- close()¶
Close a connection to the server. The method is idempotent.
- connect()¶
Create a connection to some server in the cluster. Refresh addresses info after success. There is no need to call this method explicitly until you have set
connect_now=False
on initialization.- Raise:
AssertionError
,SchemaError
,NetworkError
,connect
exceptions
- crud_count(space_name: str, conditions: Optional[list] = None, opts: Optional[dict] = None) int ¶
Gets rows count through the crud.
- Parameters:
- Return type:
- Raise:
- crud_delete(space_name: str, key: int, opts: Optional[dict] = None) CrudResult ¶
Deletes row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_get(space_name: str, key: int, opts: Optional[dict] = None) CrudResult ¶
Gets row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_insert(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Inserts row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_insert_many(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Inserts batch rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_insert_object(space_name: str, values: dict, opts: Optional[dict] = None) CrudResult ¶
Inserts object row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_insert_object_many(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Inserts batch object rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_len(space_name: str, opts: Optional[dict] = None) int ¶
Gets the number of tuples in the space through the crud.
- Parameters:
- Return type:
- Raise:
- crud_max(space_name: str, index_name: str, opts: Optional[dict] = None) CrudResult ¶
Gets rows with maximum value in the specified index through the crud.
- Parameters:
- Return type:
- Raise:
- crud_min(space_name: str, index_name: str, opts: Optional[dict] = None) CrudResult ¶
Gets rows with minimum value in the specified index through the crud.
- Parameters:
- Return type:
- Raise:
- crud_replace(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Replaces row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_replace_many(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Replaces batch rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_replace_object(space_name: str, values: dict, opts: Optional[dict] = None) CrudResult ¶
Replaces object row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_replace_object_many(space_name: str, values: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Replaces batch object rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_select(space_name: str, conditions: Optional[list] = None, opts: Optional[dict] = None) CrudResult ¶
Selects rows through the crud.
- Parameters:
- Return type:
- Raise:
CrudModuleError
, :exc:`~tarantool.error.DatabaseError`select
- crud_stats(space_name: Optional[str] = None) CrudResult ¶
Gets statistics from the crud.
- Parameters:
- Return type:
- Raise:
- crud_storage_info(opts: Optional[dict] = None) dict ¶
Gets storages status through the crud.
- Parameters:
- Return type:
- Raise:
- crud_truncate(space_name: str, opts: Optional[dict] = None) bool ¶
Truncate rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_update(space_name: str, key: int, operations: Optional[list] = None, opts: Optional[dict] = None) CrudResult ¶
Updates row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_upsert(space_name: str, values: Union[tuple, list], operations: Optional[list] = None, opts: Optional[dict] = None) CrudResult ¶
Upserts row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_upsert_many(space_name: str, values_operation: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Upserts batch rows through the crud.
- Parameters:
- Return type:
- Raise:
- crud_upsert_object(space_name: str, values: dict, operations: Optional[list] = None, opts: Optional[dict] = None) CrudResult ¶
Upserts object row through the crud.
- Parameters:
- Return type:
- Raise:
- crud_upsert_object_many(space_name: str, values_operation: Union[tuple, list], opts: Optional[dict] = None) CrudResult ¶
Upserts batch object rows through the crud.
- Parameters:
- Return type:
- Raise:
- delete(space_name, key, *, index=0, on_push=None, on_push_ctx=None)¶
Execute a DELETE request: delete a tuple in the space.
- Parameters:
key¶ – Key of a tuple to be deleted.
index¶ (
str
orint
, optional) – Index name or index id. If you’re using a secondary index, it must be unique. Defaults to primary index.on_push¶ (
function
, optional) – Сallback for processing out-of-band messages.on_push_ctx¶ (optional) – Сontext for working with on_push callback.
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- eval(expr, *args, on_push=None, on_push_ctx=None)¶
Execute an EVAL request: evaluate a Lua expression.
- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- execute(query, params=None)¶
Execute an SQL request: see documentation for syntax reference.
The Tarantool binary protocol for SQL requests supports “qmark” and “named” param styles. A sequence of values can be used for “qmark” style. A mapping is used for “named” param style without the leading colon in the keys.
Example for “qmark” arguments:
args = ['email@example.com'] c.execute('select * from "users" where "email"=?', args)
Example for “named” arguments:
args = {'email': 'email@example.com'} c.execute('select * from "users" where "email"=:email', args)
- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- flush_schema()¶
Reload space and index schema.
- Raise:
- insert(space_name, values, *, on_push=None, on_push_ctx=None)¶
Execute an INSERT request: insert a tuple to the space. Throws an error if there is already a tuple with the same primary key.
- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- ping(notime=False)¶
Execute a PING request: send an empty request and receive an empty response from the server.
- Parameters:
notime¶ (
bool
, optional) – IfFalse
, returns response time. Otherwise, it returns'Success'
.- Returns:
Response time or
'Success'
.- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- replace(space_name, values, *, on_push=None, on_push_ctx=None)¶
Execute a REPLACE request: replace a tuple in the space. Doesn’t throw an error if there is no tuple with the specified primary key.
- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- select(space_name, key=None, *, offset=0, limit=4294967295, index=0, iterator=None, on_push=None, on_push_ctx=None)¶
Execute a SELECT request: select a tuple from the space.
- Parameters:
key¶ (optional) – Key of a tuple to be selected.
limit¶ (
str
orint
, optional) – Maximum number of tuples to select.index¶ – Index name or index id to select. Defaults to primary index.
iterator¶ –
Index iterator type.
Iterator types for TREE indexes:
Iterator type
Arguments
Description
'EQ'
search value
The comparison operator is ‘==’ (equal to). If an index key is equal to a search value, it matches. Tuples are returned in ascending order by index key. This is the default.
'REQ'
search value
Matching is the same as for
'EQ'
. Tuples are returned in descending order by index key.'GT'
search value
The comparison operator is ‘>’ (greater than). If an index key is greater than a search value, it matches. Tuples are returned in ascending order by index key.
'GE'
search value
The comparison operator is ‘>=’ (greater than or equal to). If an index key is greater than or equal to a search value, it matches. Tuples are returned in ascending order by index key.
'ALL'
search value
Same as
'GE'
'LT'
search value
The comparison operator is ‘<’ (less than). If an index key is less than a search value, it matches. Tuples are returned in descending order by index key.
'LE'
search value
The comparison operator is ‘<=’ (less than or equal to). If an index key is less than or equal to a search value, it matches. Tuples are returned in descending order by index key.
Iterator types for HASH indexes:
Type
Arguments
Description
'ALL'
none
All index keys match. Tuples are returned in ascending order by hash of index key, which will appear to be random.
'EQ'
search value
The comparison operator is ‘==’ (equal to). If an index key is equal to a search value, it matches. The number of returned tuples will be 0 or 1. This is the default.
'GT'
search value
The comparison operator is ‘>’ (greater than). If a hash of an index key is greater than a hash of a search value, it matches. Tuples are returned in ascending order by hash of index key, which will appear to be random. Provided that the space is not being updated, one can retrieve all the tuples in a space, N tuples at a time, by using
iterator='GT',limit=N
in each search, and using the last returned value from the previous result as the start search value for the next search.Iterator types for BITSET indexes:
Type
Arguments
Description
'ALL'
none
All index keys match. Tuples are returned in their order within the space.
'EQ'
bitset value
If an index key is equal to a bitset value, it matches. Tuples are returned in their order within the space. This is the default.
'BITS_ALL_SET'
bitset value
If all of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space.
'BITS_ANY_SET'
bitset value
If any of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space.
'BITS_ALL_NOT_SET'
bitset value
If all of the bits which are 1 in the bitset value are 0 in the index key, it matches. Tuples are returned in their order within the space.
on_push¶ (
function
, optional) – Сallback for processing out-of-band messages.on_push_ctx¶ (optional) – Сontext for working with on_push callback.
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- update(space_name, key, op_list, *, index=0, on_push=None, on_push_ctx=None)¶
Execute an UPDATE request: update a tuple in the space.
- Parameters:
key¶ – Key of a tuple to be updated.
The list of operations to update individual fields. Each operation is a
tuple
of three (or more) values:(operator, field_identifier, value)
.Possible operators are:
'+'
for addition. values must be numeric'-'
for subtraction. values must be numeric'&'
for bitwise AND. values must be unsigned numeric'|'
for bitwise OR. values must be unsigned numeric'^'
for bitwise XOR. values must be unsigned numeric':'
for string splice. you must provideoffset
,count
, andvalue
for this operation'!'
for insertion. provide any element to insert)'='
for assignment. (provide any element to assign)'#'
for deletion. provide count of fields to delete)
Possible field_identifiers are:
Positive field number. The first field is 1, the second field is 2, and so on.
Negative field number. The last field is -1, the second-last field is -2, and so on. In other words:
(#tuple + negative field number + 1)
.Name. If the space was formatted with
space_object:format()
, then this can be a string for the fieldname
(Since Tarantool 2.3.1).
Operation examples:
# 'ADD' 55 to the second field # Assign 'x' to the third field [('+', 2, 55), ('=', 3, 'x')] # 'OR' the third field with '1' # Cut three symbols, starting from the second, # and replace them with '!!' # Insert 'hello, world' field before the fifth element of the tuple [('|', 3, 1), (':', 2, 2, 3, '!!'), ('!', 5, 'hello, world')] # Delete two fields, starting with the second field [('#', 2, 2)]
index¶ (
str
orint
, optional) – Index name or index id. If you’re using a secondary index, it must be unique. Defaults to primary index.on_push¶ (
function
, optional) – Сallback for processing out-of-band messages.on_push_ctx¶ (optional) – Сontext for working with on_push callback.
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- upsert(space_name, tuple_value, op_list, *, index=0, on_push=None, on_push_ctx=None)¶
Execute an UPSERT request: upsert a tuple to the space.
If an existing tuple matches the key fields of
tuple_value
, then the request has the same effect as UPDATE and the[(field_1, symbol_1, arg_1), ...]
parameter is used.If there is no tuple matching the key fields of
tuple_value
, then the request has the same effect as INSERT and thetuple_value
parameter is used. However, unlike insert or update, upsert will neither read the tuple nor perform error checks before returning – this is a design feature which enhances throughput but requires more caution on the part of the user.- Parameters:
- Return type:
- Raise:
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
,NotSupportedError
- class tarantool.mesh_connection.RoundRobinStrategy(addrs)¶
Defines strategy to choose next pool server after fail.
- tarantool.mesh_connection.parse_uri(uri)¶
Parse URI received from cluster discovery function.
- tarantool.mesh_connection.prepare_address(address)¶
Validate address dictionary, fill with default values. For format refer to
addrs
.
- tarantool.mesh_connection.update_connection(conn, address)¶
Update connection info after rotation.
- Parameters:
conn¶ (
MeshConnection
) – Connection mesh to update.