Database API

fastapi_restly.db.activate_savepoint_only_mode(make_session: async_sessionmaker[Any] | sessionmaker[Any]) → None

Intended for use in tests. Puts the session factory into savepoint-only mode so that no test data is ever committed to the database. Each test can roll back instantly by closing the session, leaving the database clean for the next test.

This is done with “create_savepoint” mode and a wrapper on engine.connect() that begins the outer transaction before the Session can use it. https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#session-external-transaction

fastapi_restly.db.configure(app: FastAPI | None = None, *, async_database_url: str | None = None, async_engine: AsyncEngine | None = None, async_make_session: async_sessionmaker[Any] | None = None, database_url: str | None = None, engine: Engine | None = None, make_session: sessionmaker[Any] | None = None, session_generator: Callable[[], AsyncIterator[AsyncSession]] | None = None, sync_session_generator: Callable[[], Iterator[Session]] | None = None, commit_session_on_response: bool | None = None, install_default_exception_handlers: bool = True) → None

Configure FastAPI-Restly. Call once at startup.

Pass async parameters (async_database_url, async_engine, or async_make_session) to enable async support, sync parameters (database_url, engine, or make_session) for sync support, or both if your application uses both.

Use session_generator / sync_session_generator to plug in a custom session factory instead of the built-in one.

By default, Restly commits built-in request sessions when an endpoint successfully produces a response. Set commit_session_on_response=False to own commit/rollback calls yourself. Leave it unset to keep the current default. Custom session generators always own their transaction lifecycle.

Pass your FastAPI app to install fastapi-restly’s default exception handlers (currently: a translator that turns SQLAlchemy IntegrityError into HTTP 409 Conflict). Set install_default_exception_handlers=False to opt out. If you do not pass app here, the handlers are registered the first time a view is mounted via fastapi_restly.include_view() instead.

fastapi_restly.db.deactivate_savepoint_only_mode(make_session: async_sessionmaker[Any] | sessionmaker[Any]) → None

Reverts the effect of activate_savepoint_only_mode. Restores the original engine.connect and disables savepoint-only mode.

fastapi_restly.db.get_async_engine() → AsyncEngine

Return the async engine registered via configure().

fastapi_restly.db.get_engine() → Engine

Return the sync engine registered via configure().

fastapi_restly.db.open_async_session() → AsyncIterator[AsyncSession]

Open an async database session for use outside of request context.

Example:

async with fr.open_async_session() as session:
    result = await session.execute(select(User))

fastapi_restly.db.open_session() → Iterator[Session]

Open a sync database session for use outside of request context.

Example:

with fr.open_session() as session:
    result = session.execute(select(User))