orionis.database.contracts.IConnection

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

Known subclasses: orionis.database.Connection

View In Hierarchy

Contract for a single named database connection.

A connection encapsulates the SQL engine entirely: it accepts Orionis query plans or raw SQL strings and always returns plain Python values (dictionaries, integers, result entities). Engine objects never leak through this interface.

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

@abstractmethod

async def begin(self): (source) ¶

overridden in orionis.database.Connection

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.

@abstractmethod

async def commit(self): (source) ¶

overridden in orionis.database.Connection

Commit the innermost active transaction or savepoint.

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

Raises
`TransactionException`	If no transaction is active.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

async def disconnect(self): (source) ¶

overridden in orionis.database.Connection

Dispose the underlying engine and release its pooled resources.

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

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

Return the configured name of this connection.

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

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

Report whether a transaction is active in the current task.

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

@abstractmethod

async def rollback(self): (source) ¶

overridden in orionis.database.Connection

Roll back the innermost active transaction or savepoint.

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

Raises
`TransactionException`	If no transaction is active.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

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.

@abstractmethod

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

overridden in orionis.database.Connection

Return a transaction usable as an async context manager.

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

@abstractmethod

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

overridden in orionis.database.Connection

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 = (source) ¶

overridden in orionis.database.Connection

Undocumented