ORIONIS API REFERENCE

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.

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 supportsUniqueConstraints Report whether primary and unique keys reject duplicate values.
Method toSql Render a SELECT plan without executing it or opening a connection.
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__ Declare that this class introduces no additional instance slots.
@abstractmethod
async def begin(self): (source)

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

Returns
NoneNo return value.
Raises
orionis.database.TransactionExceptionIf the transaction cannot be started.
@abstractmethod
async def commit(self): (source)

Commit the innermost active transaction or savepoint.

Returns
NoneNo return value.
Raises
orionis.database.TransactionExceptionIf no transaction is active.
@abstractmethod
async def createTable(self, table: TableDefinition, *, if_not_exists: bool = True) -> bool: (source)

Create the physical table described by the given definition.

Parameters
table:orionis.orm.schema.TableDefinitionTable definition to materialize.
if_not_exists:bool, optionalWhether to guard the statement with IF NOT EXISTS so that an already existing table is silently kept.
Returns
boolTrue when the statement executes without errors.
Raises
orionis.database.QueryExceptionIf the DDL statement fails to execute.
@abstractmethod
async def delete(self, plan: DeletePlan) -> int: (source)

Run a DELETE statement described by the given plan.

Parameters
plan:orionis.orm.query.DeletePlanDelete plan with filtering conditions.
Returns
intNumber of affected rows.
Raises
orionis.database.QueryExceptionIf the statement fails to compile or execute.
@abstractmethod
async def disconnect(self): (source)

Dispose the underlying engine and release its pooled resources.

Returns
NoneNo return value.
@abstractmethod
async def dropTable(self, name: str, schema: str | None = None, *, if_exists: bool = True) -> bool: (source)

Drop the physical table with the given logical name.

Parameters
name:strLogical table name; the connection prefix is applied.
schema:str or None, optionalDatabase schema owning the table, or None for the default.
if_exists:bool, optionalWhether to guard the statement with IF EXISTS so that a missing table does not raise an error.
Returns
boolTrue when the statement executes without errors.
Raises
orionis.database.QueryExceptionIf the DDL statement fails to execute.
@abstractmethod
async def execute(self, sql: str, bindings: Mapping[str, Any] | None = None) -> int: (source)

Run a raw data-modifying SQL statement.

Parameters
sql:strRaw SQL using named :param placeholders.
bindings:collections.abc.Mapping of str to typing.Any, optionalBound parameters for the statement.
Returns
intNumber of affected rows.
Raises
orionis.database.QueryExceptionIf the statement fails to execute.
@abstractmethod
def getName(self) -> str: (source)

Return the configured name of this connection.

Returns
strConnection name as registered in the manager.
@abstractmethod
async def insert(self, plan: InsertPlan) -> InsertResult: (source)

Run an INSERT statement described by the given plan.

Parameters
plan:orionis.orm.query.InsertPlanInsert plan with the target table and row values.
Returns
orionis.database.entities.InsertResultResult carrying the generated key and affected row count.
Raises
orionis.database.QueryExceptionIf the statement fails to compile or execute.
@abstractmethod
def inTransaction(self) -> bool: (source)

Report whether a transaction is active in the current task.

Returns
boolTrue when at least one transaction level is open.
@abstractmethod
async def rollback(self): (source)

Roll back the innermost active transaction or savepoint.

Returns
NoneNo return value.
Raises
orionis.database.TransactionExceptionIf no transaction is active.
@abstractmethod
async def scalar(self, plan: SelectPlan) -> Any: (source)

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

Parameters
plan:orionis.orm.query.SelectPlanQuery plan, typically carrying an aggregate projection.
Returns
typing.AnyScalar value, or None when the query yields no rows.
Raises
orionis.database.QueryExceptionIf 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)

Run a SELECT query and return its rows as dictionaries.

Parameters
query:orionis.orm.query.SelectPlan or strCompiled query plan, or a raw SQL string using named :param placeholders.
bindings:collections.abc.Mapping of str to typing.Any, optionalBound parameters for raw SQL strings.
Returns
list of dictOne dictionary per row keyed by column name.
Raises
orionis.database.QueryExceptionIf the statement fails to compile or execute.
@abstractmethod
async def statement(self, sql: str, bindings: Mapping[str, Any] | None = None) -> bool: (source)

Run a raw SQL statement without inspecting its result.

Intended for DDL and maintenance commands.

Parameters
sql:strRaw SQL statement.
bindings:collections.abc.Mapping of str to typing.Any, optionalBound parameters for the statement.
Returns
boolTrue when the statement executes without errors.
Raises
orionis.database.QueryExceptionIf the statement fails to execute.
def supportsUniqueConstraints(self) -> bool: (source)

Report whether primary and unique keys reject duplicate values.

Custom connections retain the relational default. Backends whose keys are only informational must override this capability so consumers can reject operations that require a database-enforced unique claim.

Returns
boolWhether uniqueness is enforced by the database.
@abstractmethod
def toSql(self, plan: SelectPlan, *, literal_binds: bool = False) -> str: (source)

Render a SELECT plan without executing it or opening a connection.

Parameters
plan:orionis.orm.query.SelectPlanQuery plan to render with the configured connection dialect.
literal_binds:bool, optionalInclude values for debugging when their types support SQL literals. Literal output may expose sensitive information.
Returns
strSQL text with expanded placeholders or literal parameter values.
Raises
orionis.database.QueryExceptionIf the plan or a literal value cannot be compiled.
orionis.database.MissingDatabaseDependencyExceptionIf the configured SQL dialect is unavailable.
@abstractmethod
def transaction(self) -> ITransaction: (source)

Return a transaction usable as an async context manager.

Returns
orionis.database.contracts.ITransactionContext manager committing on success and rolling back on error.
@abstractmethod
async def update(self, plan: UpdatePlan) -> int: (source)

Run an UPDATE statement described by the given plan.

Parameters
plan:orionis.orm.query.UpdatePlanUpdate plan with values and filtering conditions.
Returns
intNumber of affected rows.
Raises
orionis.database.QueryExceptionIf the statement fails to compile or execute.
__slots__: tuple = (source)

Declare that this class introduces no additional instance slots.