module tarantool.dbapi
¶
Python DB API implementation, refer to PEP-249.
- class tarantool.dbapi.Connection(*args, **kwargs)¶
PEP-249 compatible
Connection
class wrapper.- Parameters:
args¶ (
tuple
) –Connection
args.kwargs¶ (
dict
) –Connection
kwargs.autocommit¶ (
bool
, optional) – Enable or disable autocommit. Defaults toTrue
.
- Raise:
Connection
exceptions
- exception ConfigurationError¶
Error of initialization with a user-provided configuration.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- 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.
- exception DataError(*args, extra_info=None)¶
Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception 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 Error¶
Base class for error exceptions.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception IntegrityError(*args, extra_info=None)¶
Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception InterfaceError¶
Exception raised for errors that are related to the database interface rather than the database itself.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception InternalError(*args, extra_info=None)¶
Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception NetworkError(*args, **kwargs)¶
Error related to network.
- Parameters:
args (
dict
, optional) – Exception arguments. If the first argument is a socket exception, it is wrapped.kwargs – Exception to wrap.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception NotSupportedError(*args, extra_info=None)¶
Exception raised in case a method or database API was used which is not supported by the database, e.g. requesting a .rollback() on a connection that does not support transactions or has transactions turned off.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception OperationalError(*args, extra_info=None)¶
Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception ProgrammingError(*args, extra_info=None)¶
Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.
- Parameters:
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception 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.
- exception Warning¶
Base class for warning categories.
- 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
- property autocommit¶
Autocommit state.
- 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 the connection.
- Raise:
- commit()¶
Commit any pending transaction to the database.
- Raise:
- 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:
- cursor()¶
Return a new Cursor object using the connection.
- Return type:
- Raise:
InterfaceError
,Cursor
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
,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
- rollback()¶
Not supported
Roll back pending transaction.
- Raise:
- 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.dbapi.Cursor(conn)¶
Represent a database cursor, which is used to manage the context of a fetch operation.
- Parameters:
conn¶ (
Connection
) – Connection to a Tarantool server.
- callproc(procname, *params)¶
Not supported
Call a stored database procedure with the given name. The sequence of parameters must contain one entry for each argument that the procedure expects. The result of the call is returned as a modified copy of the input sequence. The input parameters are left untouched, the output and input/output parameters replaced with possibly new values.
- Raises:
- close()¶
Close the cursor now (rather than whenever __del__ is called). The cursor will be unusable from this point forward;
InterfaceError
exception will be raised if any operation is attempted with the cursor.
- property description¶
Not implemented
Call a stored database procedure with the given name. The sequence of parameters must contain one entry for each argument that the procedure expects. The result of the call is returned as a modified copy of the input sequence. The input parameters are left untouched, the output and input/output parameters replaced with possibly new values.
- Raises:
- executemany(query, param_sets)¶
Execute several SQL requests with same query and different parameters. Refer to
execute()
.
- fetchall()¶
Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples). Note that the cursor’s arraysize attribute can affect the performance of this operation.
- Raise:
- fetchmany(size=None)¶
Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available.
- fetchone()¶
Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.
- Raise:
- property lastrowid¶
This read-only attribute provides the rowid of the last modified row (most databases return a rowid only when a single INSERT operation is performed).
- Type:
- property rowcount¶
This read-only attribute specifies the number of rows that the last
.execute*()
produced (for DQL statements like SELECT) or affected (for DML statements like UPDATE or INSERT).- Type:
- tarantool.dbapi.connect(dsn=None, host=None, port=None, user=None, password=None, **kwargs)¶
Constructor for creating a connection to the database.
- Parameters:
- Return type:
- Raise:
NotImplementedError
,Connection
exceptions