module tarantool.connection
¶
This module provides API for interaction with a Tarantool server.
- class tarantool.connection.Connection(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', 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, ssl_password=None, ssl_password_file=None, packer_factory=<function packer_factory>, unpacker_factory=<function unpacker_factory>, auth_type=None, fetch_schema=True, required_protocol_version=None, required_features=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.port¶ (
int
orstr
orNone
) – Server port, or Unix socket path.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 non-default
packer_factory
option is used,encoding
option value is ignored on encode until the factory explicitly uses its value. If non-defaultunpacker_factory
option is used,encoding
option value is ignored on decode until the factory explicitly uses its value.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
.If
True
, unpack MessagePack array (mp_array) tolist
. Otherwise, unpack totuple
.If non-default
unpacker_factory
option is used,use_list
option value is ignored on decode until the factory explicitly uses its value.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.ssl_password¶ (
str
orNone
, optional) – Password for decryptingssl_key_file
.ssl_password_file¶ (
str
orNone
, optional) – File with password for decryptingssl_key_file
. Connection tries every line from the file as a password.packer_factory¶ (callable[[
Connection
],Packer
], optional) – Request MessagePack packer factory. Supersedesencoding
. Seepacker_factory()
for example of a packer factory.unpacker_factory¶ (callable[[
Connection
],Unpacker
], optional) – Response MessagePack unpacker factory. Supersedesencoding
anduse_list
. Seeunpacker_factory()
for example of an unpacker factory.auth_type¶ (
None
orstr
, optional) – Authentication method:"chap-sha1"
(supported in Tarantool CE and EE) or"pap-sha256"
(supported in Tarantool EE,"ssl"
transport
must be used). If None, use authentication method provided by server in IPROTO_ID exchange. If server does not provide an authentication method, use"chap-sha1"
.fetch_schema¶ (
bool
, optional) – IfFalse
, schema is not loaded on connect and schema updates are not automatically loaded. As a result, these methods become unavailable:replace()
,insert()
,delete()
,upsert()
,update()
,select()
,space()
.required_protocol_version¶ (
int
orNone
, optional) – Minimal protocol version that should be supported by Tarantool server.required_features¶ (
list
orNone
, optional) – List of protocol features that should be supported by Tarantool server.
- 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 '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 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:
- 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.connection.ConnectionInterface¶
Represents a connection to single or multiple Tarantool servers.
Interface requires that 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.
- abstract crud_count(space_name, conditions=None, opts=None)¶
Reference implementation:
crud_count()
.
- abstract crud_delete(space_name, key, opts=None)¶
Reference implementation:
crud_delete()
.
- abstract crud_get(space_name, key, opts=None)¶
Reference implementation:
crud_get()
.
- abstract crud_insert(space_name, values, opts=None)¶
Reference implementation:
crud_insert()
.
- abstract crud_insert_many(space_name, values, opts=None)¶
Reference implementation:
crud_insert_many()
.
- abstract crud_insert_object(space_name, values, opts=None)¶
Reference implementation:
crud_insert_object()
.
- abstract crud_insert_object_many(space_name, values, opts=None)¶
Reference implementation:
crud_insert_object_many()
.
- abstract crud_len(space_name, opts=None)¶
Reference implementation:
crud_len()
.
- abstract crud_max(space_name, index_name, opts=None)¶
Reference implementation:
crud_max()
.
- abstract crud_min(space_name, index_name, opts=None)¶
Reference implementation:
crud_min()
.
- abstract crud_replace(space_name, values, opts=None)¶
Reference implementation:
crud_replace()
.
- abstract crud_replace_many(space_name, values, opts=None)¶
Reference implementation:
crud_replace_many()
.
- abstract crud_replace_object(space_name, values, opts=None)¶
Reference implementation:
crud_replace_object()
.
- abstract crud_replace_object_many(space_name, values, opts=None)¶
Reference implementation:
crud_replace_object_many()
.
- abstract crud_select(space_name: str, conditions=None, opts=None)¶
Reference implementation:
crud_select()
.
- abstract crud_stats(space_name=None)¶
Reference implementation:
crud_stats()
.
- abstract crud_storage_info(opts=None)¶
Reference implementation:
crud_storage_info()
.
- abstract crud_truncate(space_name, opts=None)¶
Reference implementation:
crud_truncate()
.
- abstract crud_unflatten_rows(rows, metadata)¶
Reference implementation:
crud_unflatten_rows()
.
- abstract crud_update(space_name, key, operations=None, opts=None)¶
Reference implementation:
crud_update()
.
- abstract crud_upsert(space_name, values, operations=None, opts=None)¶
Reference implementation:
crud_upsert()
.
- abstract crud_upsert_many(space_name, values_operation, opts=None)¶
Reference implementation:
crud_upsert_many()
.
- abstract crud_upsert_object(space_name, values, operations=None, opts=None)¶
Reference implementation:
crud_upsert_object()
.
- abstract crud_upsert_object_many(space_name, values_operation, opts=None)¶
Reference implementation:
crud_upsert_object_many()
.
- abstract delete(space_name, key, *, index=None, on_push=None, on_push_ctx=None)¶
Reference implementation:
delete()
.
- abstract insert(space_name, values, *, on_push=None, on_push_ctx=None)¶
Reference implementation:
insert()
.
- abstract is_closed()¶
Reference implementation
is_closed()
.
- abstract replace(space_name, values, *, on_push=None, on_push_ctx=None)¶
Reference implementation:
replace()
.
- abstract select(space_name, key, *, offset=None, limit=None, index=None, iterator=None, on_push=None, on_push_ctx=None)¶
Reference implementation:
select()
.