Engine
The Engine class wraps the database connection and dispatches to the correct backend (SQLite or PostgreSQL) based on the URL.
Constructor
from centaurodb import Engine
# In-memory SQLite (default)
engine = Engine()
engine = Engine(":memory:")
# File-based SQLite
engine = Engine("my.db")
engine = Engine("sqlite:///path/to/file.db")
# PostgreSQL
engine = Engine("postgresql://user:pass@localhost/db")
engine = Engine("postgres://user:pass@localhost/db")
| Parameter | Type | Default | Description |
|---|---|---|---|
url | str | ":memory:" | Connection URL or file path |
check_same_thread | bool | True | SQLite only. Set to False for async collections — see Async Support |
Engine(...) dispatches on the URL scheme: any prefix registered via register_backend routes to that backend, and a plain path with no recognized scheme falls back to SQLite. Constructing a subclass directly (e.g. SQLiteEngine(...)) bypasses dispatch.
Methods
| Method | Returns | Description |
|---|---|---|
execute(sql, params) | Cursor | Execute a SQL statement |
executemany(sql, params_seq) | Cursor | Execute a SQL statement with multiple parameter sets |
fetchone(sql, params) | Row or None | Execute and fetch one row |
fetchall(sql, params) | listRow | Execute and fetch all rows |
insert_returning_id(sql, params) | int | Execute an INSERT and return the new row id |
commit() | None | Commit the current transaction |
rollback() | None | Roll back the current transaction |
close() | None | Close the database connection |
sql_select(sql, params) | polars.DataFrame | Execute a SELECT and return a Polars DataFrame. Requires centaurodb[polars] |
sql_execute(sql, params) | int | Execute any SQL statement and return affected row count. Auto-commits |
async_safety
A read-only property describing whether the engine can be shared by async collections:
engine = Engine("my.db", check_same_thread=False)
print(engine.async_safety) # "serial"
| Value | Meaning |
|---|---|
"unsafe" | Must not be used from multiple threads — AsyncCollection refuses it with ThreadSafetyError |
"serial" | Safe across threads, but operations run one at a time on a single connection |
"concurrent" | Reserved for future pool-backed backends — nothing returns it today |
Per backend: SQLiteEngine reports "serial" when created with check_same_thread=False, otherwise "unsafe"; PostgresEngine reports "serial" (single synchronous connection). See Async Support for setup.
Backend subclasses
Engine is the dispatching front door; the actual work is done by backend subclasses:
from centaurodb.engine import SQLiteEngine, PostgresEngine
engine = SQLiteEngine("my.db", check_same_thread=False)
engine = PostgresEngine("postgresql://user:pass@localhost/db")
| Class | URL prefixes | Notes |
|---|---|---|
SQLiteEngine(url=":memory:", *, check_same_thread=True) | sqlite, plain paths | Default backend |
PostgresEngine(url="") | postgresql, postgres | Requires pip install centaurodb[postgres] |
register_backend
Register a custom backend class for a URL prefix. Not a top-level export — import it from centaurodb.engine:
from centaurodb.engine import register_backend
class DuckDBEngine(Engine):
...
register_backend("duckdb", DuckDBEngine)
engine = Engine("duckdb:///analytics.db") # dispatches to DuckDBEngine
| Parameter | Type | Description |
|---|---|---|
prefix | str | URL scheme to claim (e.g. "duckdb") |
engine_class | type[Engine] | The backend class to instantiate for that prefix |
Raises — ValueError if prefix is empty. TypeError if engine_class is not an Engine subclass.
Built-in registrations: sqlite → SQLiteEngine, postgresql / postgres → PostgresEngine.
sql_select
Execute a read-only SELECT (or WITH … SELECT) query and return the result as a Polars DataFrame. Only SELECT and WITH statements are accepted.
df = engine.sql_select("SELECT id, name FROM monitoring_objects")
print(df.shape) # (3, 2)
Requires the polars extra:
pip install centaurodb[polars]
Raises — ValueError if the statement is not a SELECT/WITH query. ImportError if polars is not installed.
sql_execute
Execute an arbitrary SQL statement (INSERT, UPDATE, DELETE, DDL) and return the number of affected rows. Commits the transaction on success.
n = engine.sql_execute(
"DELETE FROM monitoring_objects WHERE id = ?", (1,)
)
print(n) # 1
Context manager
Engine works as a context manager that auto-closes on exit:
with Engine("my.db") as engine:
coll = Collection(engine, "monitoring")
coll.write_object(obj)
# connection closed automatically
Raw connection
Access the underlying database connection for advanced use:
engine = Engine("my.db")
raw_conn = engine.raw # sqlite3.Connection or psycopg.Connection