orionis.orm.query_builder.QueryBuilder

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class QueryBuilder(IQueryBuilder): (source)

Constructor: QueryBuilder(db_manager, connection_name)

View In Hierarchy

Entry point of the model-less query API, backing the DB facade.

Registered as a singleton, so it never keeps per-query state: every call returns a brand-new object and the connection scope is carried by value. Sharing mutable state here would leak one caller's target connection into every other concurrent request.

Method	`__init__`	Initialize the gateway with the connection manager to delegate to.
Method	`_resolve`	Resolve the connection a call targets.
Async Method	`beginTransaction`	Begin a transaction, or a savepoint when one is already active.
Async Method	`commit`	Commit the innermost active transaction or savepoint.
Method	`connection`	Return a gateway scoped to the connection with the given name.
Async Method	`execute`	Run a raw data-modifying statement and return the affected rows.
Method	`getDefaultName`	Return the name of the default connection.
Async Method	`rollback`	Roll back the innermost active transaction or savepoint.
Async Method	`select`	Run a raw SELECT statement and return its rows.
Method	`setDefaultName`	Change the connection used when none is specified.
Async Method	`statement`	Run a raw statement without inspecting its result.
Method	`table`	Build a fluent, model-less query over a plain table name.
Method	`transaction`	Return a transaction usable as an async context manager.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_connection_name`	Undocumented
Instance Variable	`_db_manager`	Undocumented

def __init__(self, db_manager: IConnectionManager, connection_name: str | None = None): (source) ¶

Initialize the gateway with the connection manager to delegate to.

Parameters
db_manager:`IConnectionManager`	Manager resolving named database connections.
connection_name:`str or None, optional`	Connection every query defaults to, or `None` for the configured default connection.

Returns
`None`	This method does not return a value.

def _resolve(self, name: str | None) -> IConnection: (source) ¶

Resolve the connection a call targets.

Parameters
name:`str or None`	Explicit connection name, or `None` to fall back to the connection this gateway is scoped to.

Returns
`IConnection`	Connection bound to its configuration.

Raises
`ConnectionNotFoundException`	If the connection is not declared in the configuration.

async def beginTransaction(self, name: str | None = None): (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.beginTransaction

Begin a transaction, or a savepoint when one is already active.

Parameters
name:`str or None, optional`	Named connection to start the transaction on, or `None` for the default connection.

Returns
`None`	This method does not return a value.

Raises
`TransactionException`	If the transaction cannot be started.

async def commit(self, name: str | None = None): (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.commit

Commit the innermost active transaction or savepoint.

Parameters
name:`str or None, optional`	Named connection to commit, or `None` for the default connection.

Returns
`None`	This method does not return a value.

Raises
`TransactionException`	If no transaction is active.

def connection(self, name: str | None = None) -> Self: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.connection

Return a gateway scoped to the connection with the given name.

A new gateway is returned instead of mutating this one: the service is a container singleton, so storing the name on it would silently retarget every other caller.

Parameters
name:`str or None, optional`	Connection name as declared in the database configuration, or `None` for the default connection.

Returns
`QueryBuilder`	Gateway bound to the requested connection.

async def execute(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> int: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.execute

Run a raw data-modifying statement and return the affected rows.

Parameters
sql:`str`	Raw SQL using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on; defaults to the connection this gateway is scoped to.

Returns
`int`	Number of affected rows.

Raises
`QueryException`	If the statement fails to execute.

def getDefaultName(self) -> str: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.getDefaultName

Return the name of the default connection.

Returns
`str`	Name of the connection used when none is specified.

async def rollback(self, name: str | None = None): (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.rollback

Roll back the innermost active transaction or savepoint.

Parameters
name:`str or None, optional`	Named connection to roll back, or `None` for the default connection.

Returns
`None`	This method does not return a value.

Raises
`TransactionException`	If no transaction is active.

async def select(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> list[dict[str, object]]: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.select

Run a raw SELECT statement and return its rows.

Parameters
sql:`str`	Raw SQL using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on; defaults to the connection this gateway is scoped to.

Returns
`list of dict`	One dictionary per row keyed by column name.

Raises
`QueryException`	If the statement fails to execute.

def setDefaultName(self, name: str): (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.setDefaultName

Change the connection used when none is specified.

Parameters
name:`str`	Connection name as declared in the database configuration.

Returns
`None`	This method does not return a value.

Raises
`ConnectionNotFoundException`	If the connection is not declared in the configuration.

async def statement(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> bool: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.statement

Run a raw statement without inspecting its result.

Parameters
sql:`str`	Raw SQL statement, typically DDL or a maintenance command.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on; defaults to the connection this gateway is scoped to.

Returns
`bool`	`True` when the statement executes without errors.

Raises
`QueryException`	If the statement fails to execute.

def table(self, name: str, *, alias: str | None = None, connection: str | None = None) -> IRawQueryBuilder: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.table

Build a fluent, model-less query over a plain table name.

A brand-new builder is created on every call so that concurrent callers sharing this gateway never mutate each other's query state.

Parameters
name:`str`	Logical table name, without the connection prefix.
alias:`str or None, optional`	Alias the table is referred to by inside the query.
connection:`str or None, optional`	Named connection to run the query against; defaults to the connection this gateway is scoped to.

Returns
`IRawQueryBuilder`	Fluent, model-less query builder over the table.

def transaction(self, name: str | None = None) -> ITransaction: (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.transaction

Return a transaction usable as an async context manager.

Parameters
name:`str or None, optional`	Named connection the transaction runs against, or `None` for the default connection.

Returns
`ITransaction`	Context manager committing on success and rolling back on error.

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.orm.contracts.query_builder.IQueryBuilder.__slots__

Undocumented

_connection_name: str | None = (source) ¶

Undocumented

_db_manager: IConnectionManager = (source) ¶

Undocumented