Database

kwai.core.db

Package for all database related modules.

ORM (Object-relational mapping) software (like SQLAlchemy) is not used. Instead, the repository pattern is used. A repository is responsible for saving, creating, querying and deleting entities. sql-smith is used to build queries.

The DatabaseQuery class can be used to implement the Query interface.

kwai.core.db.database

Module for database classes/functions.

Database

Class for communicating with a database.

Attributes:

Name	Type	Description
_connection	Connection | None	A connection
_settings	DatabaseSettings	The settings for this database connection.

settings: DatabaseSettings property

Return the database settings.

This property is immutable: the returned value is a copy of the current settings.

check_connection() async

Check if the connection is set, if not it will try to connect.

close() async

Close the connection.

commit() async

Commit all changes.

create_query_factory() classmethod

Return a query factory for the current database engine.

The query factory is used to start creating a SELECT, INSERT, UPDATE or DELETE query.

Returns:

Type	Description
QueryFactory	The query factory from sql-smith. Currently, it returns a query factory for the mysql engine. In the future it can provide other engines.

delete(id_, table_name) async

Delete a row from the table using the id field.

Parameters:

Name	Type	Description	Default
id_	Any	The id of the row to delete.	required
table_name	str	The name of the table.	required

Raises:

Type	Description
QueryException	Raised when the query results in an error.

execute(query) async

Execute a query.

The last rowid from the cursor is returned when the query executed successfully. On insert, this can be used to determine the new id of a row.

Parameters:

Name	Type	Description	Default
query	AbstractQuery	The query to execute.	required

Returns:

Type	Description
int	When the query is an insert query, it will return the last rowid.
None	When there is no last rowid.

Raises:

Type	Description
QueryException	Raised when the query contains an error.

fetch(query) async

Execute a query and yields each row.

Parameters:

Name	Type	Description	Default
query	SelectQuery	The query to execute.	required

Yields:

Type	Description
Record	A row is a dictionary using the column names as key and the column values as value.

Raises:

Type	Description
QueryException	Raised when the query contains an error.

fetch_one(query) async

Execute a query and return the first row.

Parameters:

Name	Type	Description	Default
query	SelectQuery	The query to execute.	required

Returns:

Type	Description
Record	A row is a dictionary using the column names as key and the column values as value.
None	The query resulted in no rows found.

Raises:

Type	Description
QueryException	Raised when the query contains an error.

insert(table_name, *table_data) async

Insert one or more instances of a dataclass into the given table.

Parameters:

Name	Type	Description	Default
table_name	str	The name of the table	required
table_data	Any	One or more instances of a dataclass containing the values	()

Returns:

Type	Description
int	The last inserted id. When multiple inserts are performed, this will be the id of the last executed insert.

Raises:

Type	Description
QueryException	Raised when the query contains an error.

log_query(query)

Log a query.

Parameters:

Name	Type	Description	Default
query	str	The query to log.	required

setup() async

Set up the connection pool.

update(id_, table_name, table_data) async

Update a dataclass in the given table.

Parameters:

Name	Type	Description	Default
id_	Any	The id of the data to update.	required
table_name	str	The name of the table.	required
table_data	Any	The dataclass containing the data.	required

Raises:

Type	Description
QueryException	Raised when the query contains an error.

kwai.core.db.database_query

Module that implements a query for a database.

DatabaseQuery

Bases: Query

Creates a query using a database.

columns abstractmethod property

Returns the columns used in the query.

count_column: str property

The column used to count records.

count() async

Execute the query and counts the number of records.

The count_column is used as column for a distinct count.

fetch(limit=None, offset=None)

Fetch all records from this query.

fetch_one() async

Fetch only one record from this query.

init() abstractmethod

Override this method to create the base query.

kwai.core.db.exceptions

Module that defines all database related exceptions.

DatabaseException

Bases: Exception

Raised when a database error occurred.

QueryException

Bases: DatabaseException

Raised when the execution of a query failed.

sql: str property

Return the sql statement of the query.

kwai.core.db.table

Module for the table decorator.

Table

Bases: Generic[T]

Represent a table in the database.

With this class a table row can be transformed into a dataclass. It can also be used to generate columns or aliases for queries.

table_name: str property

Return the table name.

__call__(row, table_name=None)

Shortcut for map_row.

alias_name(column_name, table_name=None)

Return an alias for a column.

The alias will be the name of the table delimited with an underscore: _. By default, the table name associated with the Table instance will be used.

Parameters:

Name	Type	Description	Default
column_name	str	The name of the column	required
table_name	str | None	To differ from the current table name, use this table name.	None

Returns:

Type	Description
	The alias for the given column.

aliases(table_name=None)

Return aliases for all fields of the dataclass.

column(column_name)

Return column as

..

field(column_name)

Call sql-smith field with the given column.

short-cut for: field(table.table_name + '.' + column_name)

map_row(row, table_name=None)

Map the data of a row to the dataclass.

Only the fields that have the alias prefix for this table will be selected. This makes it possible to pass it a row that contains data from multiple tables (which can be the case with a join).