module tarantool
¶
- class tarantool.Connection(host, port, user=None, password=None, socket_timeout=None, reconnect_max_attempts=10, reconnect_delay=0.1, connect_now=True, encoding='utf-8', use_list=True, call_16=False, connection_timeout=None, transport='', ssl_key_file=None, ssl_cert_file=None, ssl_ca_file=None, ssl_ciphers=None)¶
Represents a connection to the Tarantool server.
A connection object has methods to open and close a connection, check its status, call procedures and evaluate Lua code on server, make simple data manipulations and execute SQL queries.
- Parameters
host¶ (
str
orNone
) – Server hostname or IP address. UseNone
for Unix sockets.user¶ (
str
orNone
, optional) – User name for authentication on the Tarantool server.password¶ (
str
orNone
, optional) – User password for authentication on the Tarantool server.socket_timeout¶ (
float
orNone
, optional) – Timeout on blocking socket operations, in seconds (see socket.settimeout()).reconnect_max_attempts¶ (
int
, optional) – Count of maximum attempts to reconnect on API call if connection is lost.reconnect_delay¶ (
float
, optional) – Delay between attempts to reconnect on API call if connection is lost, in seconds.connect_now¶ (
bool
, optional) – IfTrue
, connect to server on initialization. Otherwise, you have to callconnect()
manually after initialization.encoding¶ (
str
orNone
, optional) –'utf-8'
orNone
. UseNone
to work with non-UTF8 strings.If
'utf-8'
, pack Unicode string (str
) to MessagePack string (mp_str) and unpack MessagePack string (mp_str) Unicode string (str
), packbytes
to MessagePack binary (mp_bin) and unpack MessagePack binary (mp_bin) tobytes
.If
None
, pack Unicode string (str
) andbytes
to MessagePack string (mp_str), unpack MessagePack string (mp_str) and MessagePack binary (mp_bin) tobytes
.use_list¶ (
bool
, optional) – IfTrue
, unpack MessagePack array (mp_array) tolist
. Otherwise, unpack totuple
.call_16¶ (
bool
, optional) – IfTrue
, enables compatibility mode with Tarantool 1.6 and older for call operations.connection_timeout¶ (
float
orNone
, optional) – Time to establish initial socket connection, in seconds.transport¶ (
str
, optional) –''
or'ssl'
. Set to'ssl'
to enable SSL encryption for a connection (requires Python >= 3.5).ssl_key_file¶ (
str
orNone
, optional) – Path to a private SSL key file. Mandatory, if the server uses a trusted certificate authorities (CA) file.ssl_cert_file¶ (
str
orNone
, optional) – Path to a SSL certificate file. Mandatory, if the server uses a trusted certificate authorities (CA) file.ssl_ca_file¶ (
str
orNone
, optional) – Path to a trusted certificate authority (CA) file.ssl_ciphers¶ (
str
orNone
, optional) – Colon-separated (:
) list of SSL cipher suites the connection can use.
- Raise
ConfigurationError
,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 'tarantool.error.Warning'>
DBAPI compatibility.
- Value
- 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
- 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 the host and port specified on initialization. There is no need to call this method explicitly until you have set
connect_now=False
on initialization.- 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
- 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
- join(server_uuid)¶
Execute a JOIN request: join a replicaset.
- Parameters
- Raise
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- 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
- 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
- subscribe(cluster_uuid, server_uuid, vclock=None)¶
Execute a SUBSCRIBE request: subscribe to a replicaset updates. Connection is closed after subscribing.
- Parameters
- Raise
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- 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
- 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
- class tarantool.MeshConnection(host=None, port=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, addrs=None, strategy_class=<class 'tarantool.mesh_connection.RoundRobinStrategy'>, cluster_discovery_function=None, cluster_discovery_delay=60)¶
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
host
. 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.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.
- 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 'tarantool.error.Warning'>
DBAPI compatibility.
- Value
- 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
- 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
- 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
- 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
- join(server_uuid)¶
Execute a JOIN request: join a replicaset.
- Parameters
- Raise
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- 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
- 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
- subscribe(cluster_uuid, server_uuid, vclock=None)¶
Execute a SUBSCRIBE request: subscribe to a replicaset updates. Connection is closed after subscribing.
- Parameters
- Raise
AssertionError
,DatabaseError
,SchemaError
,NetworkError
,SslError
- 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
- 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
- exception tarantool.Error
Base class for error exceptions.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception tarantool.DatabaseError(*args, extra_info=None)
Exception raised for errors that are related to the database.
- Parameters
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception tarantool.DatabaseError(*args, extra_info=None)
Exception raised for errors that are related to the database.
- Parameters
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception tarantool.NetworkError(orig_exception=None, *args, **kwargs)
Error related to network.
- Parameters
orig_exception (optional) – Exception to wrap.
args (
tuple
) – Wrapped exception arguments.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception tarantool.NetworkWarning
Warning related to network.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception tarantool.SchemaError(value)
Error related to extracting space and index schema.
- Parameters
value – Error value.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class tarantool.BoxError(type: Union[str, bytes], file: Union[str, bytes], line: int, message: Union[str, bytes], errno: int, errcode: int, fields: Optional[dict] = None, prev: Optional[List[BoxError]] = None)¶
Type representing Tarantool box.error object: a single MP_ERROR_STACK object with a link to the previous stack error.
- fields: Optional[dict] = None¶
Additional fields depending on error type. For example, if
type
is"AccessDeniedError"
, then it will include"object_type"
,"object_name"
,"access_type"
.
- class tarantool.ConnectionPool(addrs, user=None, password=None, socket_timeout=None, reconnect_max_attempts=0, reconnect_delay=0, connect_now=True, encoding='utf-8', call_16=False, connection_timeout=None, strategy_class=<class 'tarantool.connection_pool.RoundRobinStrategy'>, refresh_delay=1)¶
Represents the pool of connections to a cluster of Tarantool servers.
To work with
ConnectionPool
, box.info must be callable for the user on each server.ConnectionPool
is best suited to work with a single replicaset. Its API is the same as a single serverConnection
, but requests supportmode
parameter (atarantool.Mode
value) to choose between read-write and read-only pool instances:>>> resp = conn.select('demo', 'AAAA', mode=tarantool.Mode.PREFER_RO) >>> resp - ['AAAA', 'Alpha']
- Parameters
List of dictionaries describing server addresses:
{ "host': "str" or None, # mandatory "port": int or "str", # mandatory "transport": "str", # optional "ssl_key_file": "str", # optional "ssl_cert_file": "str", # optional "ssl_ca_file": "str", # optional "ssl_ciphers": "str" # optional }
Refer to corresponding
Connection
parameters.user¶ – Refer to
user
. The value is used for each connection in the pool.password¶ – Refer to
password
. The value is used for each connection in the pool.socket_timeout¶ – Refer to
socket_timeout
. The value is used for each connection in the pool.reconnect_max_attempts¶ – Refer to
reconnect_max_attempts
. The value is used for each connection in the pool. Be careful: it is internalConnection
reconnect unrelated to pool reconnect mechanisms.reconnect_delay¶ – Refer to
reconnect_delay
. The value is used for each connection in the pool. Be careful: it is internalConnection
reconnect unrelated to pool reconnect mechanisms.connect_now¶ (
bool
, optional) – IfTrue
, connect to all pool servers on initialization. Otherwise, you have to callconnect()
manually after initialization.encoding¶ – Refer to
encoding
. The value is used for each connection in the pool.call_16¶ – Refer to
call_16
. The value is used for each connection in the pool.connection_timeout¶ (
float
, optional) – Refer toconnection_timeout
. The value is used for each connection in the pool.strategy_class¶ (
StrategyInterface
, optional) – Strategy for choosing a server based on a request mode. Defaults to the round-robin strategy.refresh_delay¶ – Minimal time between pool server box.info.ro status background refreshes, in seconds.
- Raise
ConfigurationError
,Connection
exceptions
- call(func_name, *args, mode=None, on_push=None, on_push_ctx=None)¶
Execute a CALL request on the pool server: call a stored Lua function. Refer to
call()
.
- close()¶
Stop request processing, close each connection in the pool.
- connect()¶
Create a connection to each address specified on initialization and start background process threads for them. There is no need to call this method explicitly until you have set
connect_now=False
on initialization.If some connections have failed to connect successfully or provide box.info status (including the case when all of them have failed), no exceptions are raised. Attempts to reconnect and refresh the info would be processed in the background.
- delete(space_name, key, *, index=0, mode=Mode.RW, on_push=None, on_push_ctx=None)¶
Execute an DELETE request on the pool server: delete a tuple in the space. Refer to
delete()
.
- eval(expr, *args, mode=None, on_push=None, on_push_ctx=None)¶
Execute an EVAL request on the pool server: evaluate a Lua expression. Refer to
eval()
.
- execute(query, params=None, *, mode=None)¶
Execute an SQL request on the pool server. Refer to
execute()
.
- insert(space_name, values, *, mode=Mode.RW, on_push=None, on_push_ctx=None)¶
Execute an INSERT request on the pool server: insert a tuple to the space. Refer to
insert()
.
- is_closed()¶
Returns
False
if at least one connection is not closed and is ready to process requests. Otherwise, returnsTrue
.- Return type
- ping(notime=False, *, mode=None)¶
Execute a PING request on the pool server: send an empty request and receive an empty response from the server. Refer to
ping()
.
- replace(space_name, values, *, mode=Mode.RW, on_push=None, on_push_ctx=None)¶
Execute a REPLACE request on the pool server: replace a tuple in the space. Refer to
replace()
.
- select(space_name, key, *, offset=0, limit=4294967295, index=0, iterator=None, mode=Mode.ANY, on_push=None, on_push_ctx=None)¶
Execute a SELECT request on the pool server: update a tuple from the space. Refer to
select()
.- Parameters
- Return type
- Raise
select()
exceptions
- update(space_name, key, op_list, *, index=0, mode=Mode.RW, on_push=None, on_push_ctx=None)¶
Execute an UPDATE request on the pool server: update a tuple in the space. Refer to
update()
.
- class tarantool.Datetime(*, timestamp=None, year=None, month=None, day=None, hour=None, minute=None, sec=None, nsec=None, tzoffset=0, tz='', timestamp_since_utc_epoch=False)¶
Class representing Tarantool datetime info. Internals are based on
pandas.Timestamp
.You can create
Datetime
objects by using the same API as in Tarantool:dt1 = tarantool.Datetime(year=2022, month=8, day=31, hour=18, minute=7, sec=54, nsec=308543321) dt2 = tarantool.Datetime(timestamp=1661969274) dt3 = tarantool.Datetime(timestamp=1661969274, nsec=308543321)
Datetime
exposesyear
,month
,day
,hour
,minute
,sec
,nsec
,timestamp
andvalue
(integer epoch time with nanoseconds precision) properties if you need to convertDatetime
to any other kind of datetime object:pdt = pandas.Timestamp(year=dt.year, month=dt.month, day=dt.day, hour=dt.hour, minute=dt.minute, second=dt.sec, microsecond=(dt.nsec // 1000), nanosecond=(dt.nsec % 1000))
Use
tzoffset
parameter to set up offset timezone:dt = tarantool.Datetime(year=2022, month=8, day=31, hour=18, minute=7, sec=54, nsec=308543321, tzoffset=180)
You may use the
tzoffset
property to get the timezone offset of a datetime object.Use
tz
parameter to set up timezone name:dt = tarantool.Datetime(year=2022, month=8, day=31, hour=18, minute=7, sec=54, nsec=308543321, tz='Europe/Moscow')
If both
tz
andtzoffset
are specified,tz
is used.You may use the
tz
property to get the timezone name of a datetime object.- Parameters
timestamp¶ (
float
orint
, optional) – Timestamp since epoch. Cannot be provided together withyear
,month
,day
,hour
,minute
,sec
. Ifnsec
is provided, it must beint
. Refer totimestamp_since_utc_epoch
to clarify how timezone-aware datetime is computed from the timestamp.year¶ (
int
, optional) – Datetime year value. Must be a validpandas.Timestamp
year
parameter. Must be provided unless the object is built withdata
ortimestamp
.month¶ (
int
, optional) – Datetime month value. Must be a validpandas.Timestamp
month
parameter. Must be provided unless the object is built withdata
ortimestamp
.day¶ (
int
, optional) – Datetime day value. Must be a validpandas.Timestamp
day
parameter. Must be provided unless the object is built withdata
ortimestamp
.hour¶ (
int
, optional) – Datetime hour value. Must be a validpandas.Timestamp
hour
parameter.minute¶ (
int
, optional) – Datetime minute value. Must be a validpandas.Timestamp
minute
parameter.sec¶ (
int
, optional) – Datetime seconds value. Must be a validpandas.Timestamp
second
parameter.nsec¶ – Datetime nanoseconds value. Quotient of a division by 1000 (nanoseconds in microseconds) must be a valid
pandas.Timestamp
microsecond
parameter, remainder of a division by 1000 must be a validpandas.Timestamp
nanosecond
parameter.tzoffset¶ (
int
, optional) – Timezone offset. Ignored, if provided together withtz
.tz¶ (
str
, optional) – Timezone name from Olson timezone database.timestamp_since_utc_epoch¶ (
bool
, optional) –Parameter to set timestamp convertion behavior for timezone-aware datetimes.
If
False
(default), behaves similar to Tarantool datetime.new():>>> dt = tarantool.Datetime(timestamp=1640995200, timestamp_since_utc_epoch=False) >>> dt datetime: Timestamp('2022-01-01 00:00:00'), tz: "" >>> dt.timestamp 1640995200.0 >>> dt = tarantool.Datetime(timestamp=1640995200, tz='Europe/Moscow', ... timestamp_since_utc_epoch=False) >>> dt datetime: Timestamp('2022-01-01 00:00:00+0300', tz='Europe/Moscow'), tz: "Europe/Moscow" >>> dt.timestamp 1640984400.0
Thus, if
False
, datetime is computed from timestamp since epoch and then timezone is applied without any convertion. In that case,timestamp
won’t be equal to initializationtimestamp
for all timezones with non-zero offset.If
True
, behaves similar topandas.Timestamp
:>>> dt = tarantool.Datetime(timestamp=1640995200, timestamp_since_utc_epoch=True) >>> dt datetime: Timestamp('2022-01-01 00:00:00'), tz: "" >>> dt.timestamp 1640995200.0 >>> dt = tarantool.Datetime(timestamp=1640995200, tz='Europe/Moscow', ... timestamp_since_utc_epoch=True) >>> dt datetime: Timestamp('2022-01-01 03:00:00+0300', tz='Europe/Moscow'), tz: "Europe/Moscow" >>> dt.timestamp 1640995200.0
Thus, if
True
, datetime is computed in a way thattimestamp
will always be equal to initializationtimestamp
.
- Raise
ValueError
,MsgpackError
,pandas.Timestamp
exceptions
- class tarantool.Interval(*, year=0, month=0, week=0, day=0, hour=0, minute=0, sec=0, nsec=0, adjust=Adjust.NONE)¶
Class representing Tarantool datetime.interval info.
You can create
Interval
objects either from MessagePack data or by using the same API as in Tarantool:di = tarantool.Interval(year=-1, month=2, day=3, hour=4, minute=-5, sec=6, nsec=308543321, adjust=tarantool.IntervalAdjust.NONE)
Its attributes (same as in init API) are exposed, so you can use them if needed.
- Parameters
adjust¶ (
IntervalAdjust
, optional) – Interval adjustment rule. Refer to__add__()
.
- class tarantool.Mode(value)¶
Request mode.
- ANY = 1¶
Send a request to any server.
- PREFER_RO = 5¶
Send a request to RO server, if possible, RW server otherwise.
- PREFER_RW = 4¶
Send a request to RW server, if possible, RO server otherwise.
- RO = 3¶
Send a request to RO server.
- RW = 2¶
Send a request to RW server.
- class tarantool.Schema(con)¶
Contains Tarantool server spaces schema.
- Parameters
con¶ (
Connection
) – Related Tarantool server connection.
- fetch_index(space_object, index)¶
Fetch a single index space schema from the Tarantool server and build a schema object.
- Parameters
space¶ (
SchemaSpace
) – Space schema.
- Return type
- Raises
SchemaError
,fetch_index_from()
exceptions
- fetch_index_all()¶
Fetch all spaces indexes schema from the Tarantool server and build corresponding schema objects.
- Raises
fetch_index_from()
exceptions
- fetch_index_from(space, index)¶
Fetch space index schema from the Tarantool server.
- fetch_space(space)¶
Fetch a single space schema from the Tarantool server and build a schema object.
- Parameters
- Return type
- Raises
SchemaError
,fetch_space_from()
exceptions
- fetch_space_all()¶
Fetch all spaces schema from the Tarantool server and build corresponding schema objects.
- Raises
fetch_space_from()
exceptions
- fetch_space_from(space)¶
Fetch space schema from the Tarantool server.
- flush()¶
Clean existing schema data.
- get_field(space, field)¶
Get space field format info.
- Parameters
- Returns
Field format info.
- Return type
- Raises
SchemaError
,fetch_space()
exceptions
- get_index(space, index)¶
Get space index schema. If it exists in the local schema, return local data, otherwise fetch data from the Tarantool server.
- Parameters
- Return type
- Raises
fetch_index()
exceptions
- get_space(space)¶
Get space schema. If it exists in the local schema, return local data, otherwise fetch data from the Tarantool server.
- Parameters
- Return type
- Raises
fetch_space()
exceptions
- tarantool.connect(host='localhost', port=33013, user=None, password=None, encoding='utf-8', transport='', ssl_key_file=None, ssl_cert_file=None, ssl_ca_file=None, ssl_ciphers=None)¶
Create a connection to the Tarantool server.
- Parameters
ssl_key_file¶ – Refer to
ssl_key_file
.ssl_cert_file¶ – Refer to
ssl_cert_file
.ssl_ca_file¶ – Refer to
ssl_ca_file
.ssl_ciphers¶ – Refer to
ssl_ciphers
.
- Return type
- Raise
Connection
exceptions
- tarantool.connectmesh(addrs=({'host': 'localhost', 'port': 3301},), user=None, password=None, encoding='utf-8')¶
Create a connection to a cluster of Tarantool servers.
- Parameters
- Return type
- Raise
MeshConnection
exceptions