Reference: The Database Object

The Database class is the main entry point for DuoORM. An instance of this class manages database connections, sessions, and serves as a factory for your db.Model base class.

db.Model base class

Each Database instance manufactures its own declarative base. Inherit all of your models from db.Model to keep metadata, engines, and helper methods scoped to that database.

duo_orm.db.Database

Database(
    db_url,
    *,
    derive_async=True,
    dialect=None,
    engine_kwargs=None
)

The main factory for creating a database connection and a model base class.

This class manages database connections and sessions. Its most important role is to create a pre-configured, database-aware Model base class that user models will inherit from. Each instance of Database creates its own isolated Model class, preventing conflicts when working with multiple databases in a single application.

Parameters:

Name	Type	Description	Default
db_url	str	The primary, synchronous database connection URL. Do not include a driver (e.g., +psycopg).	required
derive_async	bool	If True (default), an async URL is automatically derived from db_url by swapping the driver.	True
dialect	str	Expected dialect name (e.g., "postgresql", "mysql"). If provided, it must match the dialect parsed from db_url; otherwise an error is raised.	None
engine_kwargs	dict	Additional kwargs passed to both sync and async engines.	None

url property

url

The primary (synchronous) database URL.

sync_url property

sync_url

The fully-resolved synchronous database URL, including the driver.

async_url property

async_url

The fully-resolved asynchronous database URL, if configured.

metadata property

metadata

The MetaData object associated with this database instance's models.

transaction

transaction()

Provides a context-managed transactional scope for database operations.

This method is the heart of the Unit of Work pattern in DuoORM. It automatically detects if it's in a sync or async context and returns the appropriate context manager. All database operations within the with or async with block will share a single session.

The transaction is automatically committed if the block exits without an exception, and rolled back otherwise.

Returns:

Type	Description
ContextManager[Session] | AsyncContextManager[AsyncSession]	A synchronous or asynchronous context manager.

connect

connect()

Eagerly initialize engines to surface configuration errors early.

This method attempts to create the sync and async engines, which can help catch problems like invalid URLs or missing drivers at application startup instead of on the first query. It is safe to call multiple times.

disconnect

disconnect()

Disposes any initialized sync/async engines and resets cached factories.

This is a convenience for scripts/CLIs that want to release connections before process exit. It is safe to call multiple times; subsequent access to sync_engine/async_engine will recreate engines lazily.

create_all

create_all()

Create all tables bound to this Database (sync or async).

drop_all

drop_all()

Drop all tables bound to this Database (sync or async).

standalone_session async

standalone_session()

Provides a raw, unmanaged SQLAlchemy AsyncSession.

This is an "escape hatch" for advanced use cases that require direct control over the session, outside of DuoORM's managed context. You are responsible for committing or rolling back the session.

Yields:

Name	Type	Description
AsyncSession	AsyncIterator[AsyncSession]	A new, unmanaged SQLAlchemy AsyncSession.

sync_standalone_session

sync_standalone_session()

Provides a raw, unmanaged synchronous SQLAlchemy Session.

This is the synchronous version of standalone_session, intended for advanced use cases.

Yields:

Name	Type	Description
Session	Session	A new, unmanaged SQLAlchemy Session.

Async engines are optional

When you construct Database(..., derive_async=False), only the synchronous URL/engine is created. Async helpers (including db.async_engine, db.async_session_factory, and any async model methods) will raise in that configuration.