orionis.database.Connection

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 Connection(IConnection): (source)

Constructor: Connection(name, config)

View In Hierarchy

Named database connection encapsulating the SQL engine.

The connection lazily builds its async engine from the Orionis configuration, compiles query plans through SQLCompiler, and exposes only framework-owned types: dictionaries, integers, and result entities. Transactions are task-local and support nesting through savepoints.

Method	`__init__`	Initialize the connection with its configuration.
Method	`_acquire`	Resolve the connection context to execute statements on.
Method	`_getEngine`	Build the async engine on first use and cache it.
Method	`_queryException`	Create a query exception without exposing SQL or bound values.
Async Method	`_releaseIfSettled`	Close the raw connection once every transaction level is settled.
Async Method	`_run`	Execute a statement translating engine errors into Orionis errors.
Method	`_transactionState`	Resolve the transaction owned by the current asyncio task.
Async Method	`begin`	Begin a transaction, or a savepoint when one is already active.
Async Method	`commit`	Commit the innermost active transaction or savepoint.
Async Method	`createTable`	Create the physical table described by the given definition.
Async Method	`delete`	Run a DELETE statement described by the given plan.
Async Method	`disconnect`	Dispose the underlying engine and release its pooled resources.
Async Method	`dropTable`	Drop the physical table with the given logical name.
Async Method	`execute`	Run a raw data-modifying SQL statement.
Method	`getName`	Return the configured name of this connection.
Async Method	`insert`	Run an INSERT statement described by the given plan.
Method	`inTransaction`	Report whether a transaction is active in the current task.
Async Method	`rollback`	Roll back the innermost active transaction or savepoint.
Async Method	`scalar`	Run a SELECT plan and return the first column of the first row.
Async Method	`select`	Run a SELECT query and return its rows as dictionaries.
Async Method	`statement`	Run a raw SQL statement without inspecting its result.
Method	`transaction`	Return a transaction usable as an async context manager.
Async Method	`update`	Run an UPDATE statement described by the given plan.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_compiler`	Undocumented
Instance Variable	`_config`	Undocumented
Instance Variable	`_engine`	Undocumented
Instance Variable	`_name`	Undocumented
Instance Variable	`_tx_state`	Undocumented

def __init__(self, name: str, config: dict[str, Any]): (source) ¶

Initialize the connection with its configuration.

Parameters
name:`str`	Connection name as registered in the manager.
config:`dict`	Driver configuration for the connection.

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

Raises
`UnsupportedDriverException`	If the configured driver has no registered dialect.

def _acquire(self) -> AbstractAsyncContextManager[AsyncConnection] | _TransactionState: (source) ¶

Resolve the connection context to execute statements on.

Inside a transaction the transactional connection is reused; otherwise an ephemeral autocommit connection is opened. The context manager is returned directly to the caller.

Returns
`AbstractAsyncContextManager`	Context manager yielding the connection to execute on.

def _getEngine(self) -> AsyncEngine: (source) ¶

Build the async engine on first use and cache it.

Returns
`AsyncEngine`	Configured engine for this connection.

Raises
`MissingDatabaseDependencyException`	If the async driver package is not installed.

def _queryException(self, error: SQLAlchemyError) -> QueryException: (source) ¶

Create a query exception without exposing SQL or bound values.

Parameters
error:`SQLAlchemyError`	Database error whose type identifies the failure.

Returns
`QueryException`	Sanitized exception identifying the connection and error type.

async def _releaseIfSettled(self, state: _TransactionState): (source) ¶

Close the raw connection once every transaction level is settled.

Parameters
state:`_TransactionState`	Transaction state to inspect and release.

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

async def _run(self, connection: AsyncConnection, statement: Any, parameters: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None) -> CursorResult[Any]: (source) ¶

Execute a statement translating engine errors into Orionis errors.

Parameters
connection:`AsyncConnection`	Raw connection to execute on.
statement:`Any`	Executable statement or textual clause.
parameters:`Mapping, Sequence of Mapping or None, optional`	Bound parameters for a statement or a batch of row mappings.

Returns
`CursorResult`	Raw execution result, consumed internally by callers.

Raises
`QueryException`	If the statement fails to execute.

def _transactionState(self) -> _TransactionState | None: (source) ¶

Resolve the transaction owned by the current asyncio task.

Returns
`_TransactionState \| None`	Result of the operation described above.

async def begin(self): (source) ¶

overrides orionis.database.contracts.IConnection.begin

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

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

Raises
`TransactionException`	If the transaction cannot be started.

async def commit(self): (source) ¶

overrides orionis.database.contracts.IConnection.commit

Commit the innermost active transaction or savepoint.

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

Raises
`TransactionException`	If no transaction is active or the commit fails.

async def createTable(self, table: TableDefinition, *, if_not_exists: bool = True) -> bool: (source) ¶

overrides orionis.database.contracts.IConnection.createTable

Create the physical table described by the given definition.

Parameters
table:`TableDefinition`	Table definition to materialize.
if_not_exists:`bool, optional`	Whether to guard the statement with `IF NOT EXISTS` so that an already existing table is silently kept.

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

Raises
`QueryException`	If the DDL statement fails to execute.

async def delete(self, plan: DeletePlan) -> int: (source) ¶

overrides orionis.database.contracts.IConnection.delete

Run a DELETE statement described by the given plan.

Parameters
plan:`DeletePlan`	Delete plan with filtering conditions.

Returns
`int`	Number of affected rows.

Raises
`QueryException`	If the statement fails to compile or execute.

async def disconnect(self): (source) ¶

overrides orionis.database.contracts.IConnection.disconnect

Dispose the underlying engine and release its pooled resources.

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

async def dropTable(self, name: str, schema: str | None = None, *, if_exists: bool = True) -> bool: (source) ¶

overrides orionis.database.contracts.IConnection.dropTable

Drop the physical table with the given logical name.

Parameters
name:`str`	Logical table name; the connection prefix is applied.
schema:`str or None, optional`	Database schema owning the table, or `None` for the default.
if_exists:`bool, optional`	Whether to guard the statement with `IF EXISTS` so that a missing table does not raise an error.

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

Raises
`QueryException`	If the DDL statement fails to execute.

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

overrides orionis.database.contracts.IConnection.execute

Run a raw data-modifying SQL statement.

Parameters
sql:`str`	Raw SQL using named `:param` placeholders.
bindings:`Mapping of str to Any, optional`	Bound parameters for the statement.

Returns
`int`	Number of affected rows.

Raises
`QueryException`	If the statement fails to execute. Driver messages and bound values are excluded because they may contain credentials.

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

overrides orionis.database.contracts.IConnection.getName

Return the configured name of this connection.

Returns
`str`	Connection name as registered in the manager.

async def insert(self, plan: InsertPlan) -> InsertResult: (source) ¶

overrides orionis.database.contracts.IConnection.insert

Run an INSERT statement described by the given plan.

Parameters
plan:`InsertPlan`	Insert plan with the target table and row values.

Returns
`InsertResult`	Result carrying the generated key and affected row count.

Raises
`QueryException`	If the statement fails to compile or execute.

def inTransaction(self) -> bool: (source) ¶

overrides orionis.database.contracts.IConnection.inTransaction

Report whether a transaction is active in the current task.

Returns
`bool`	`True` when at least one transaction level is open.

async def rollback(self): (source) ¶

overrides orionis.database.contracts.IConnection.rollback

Roll back the innermost active transaction or savepoint.

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

Raises
`TransactionException`	If no transaction is active or the rollback fails.

async def scalar(self, plan: SelectPlan) -> Any: (source) ¶

overrides orionis.database.contracts.IConnection.scalar

Run a SELECT plan and return the first column of the first row.

Parameters
plan:`SelectPlan`	Query plan, typically carrying an aggregate projection.

Returns
`Any`	Scalar value, or `None` when the query yields no rows.

Raises
`QueryException`	If the statement fails to compile or execute.

async def select(self, query: SelectPlan | str, bindings: Mapping[str, Any] | None = None) -> list[dict[str, Any]]: (source) ¶

overrides orionis.database.contracts.IConnection.select

Run a SELECT query and return its rows as dictionaries.

Parameters
query:`SelectPlan or str`	Compiled query plan, or a raw SQL string using named `:param` placeholders.
bindings:`Mapping of str to Any, optional`	Bound parameters for raw SQL strings.

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

Raises
`QueryException`	If the statement fails to compile or execute.

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

overrides orionis.database.contracts.IConnection.statement

Run a raw SQL statement without inspecting its result.

Intended for DDL and maintenance commands.

Parameters
sql:`str`	Raw SQL statement.
bindings:`Mapping of str to Any, optional`	Bound parameters for the statement.

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

Raises
`QueryException`	If the statement fails to execute.

def transaction(self) -> ITransaction: (source) ¶

overrides orionis.database.contracts.IConnection.transaction

Return a transaction usable as an async context manager.

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

async def update(self, plan: UpdatePlan) -> int: (source) ¶

overrides orionis.database.contracts.IConnection.update

Run an UPDATE statement described by the given plan.

Parameters
plan:`UpdatePlan`	Update plan with values and filtering conditions.

Returns
`int`	Number of affected rows.

Raises
`QueryException`	If the statement fails to compile or execute.

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

overrides orionis.database.contracts.IConnection.__slots__

Undocumented

_compiler = (source) ¶

Undocumented

_config = (source) ¶

Undocumented

_engine: AsyncEngine | None = (source) ¶

Undocumented

_name = (source) ¶

Undocumented

_tx_state: ContextVar[_TransactionState | None] = (source) ¶

Undocumented