User Guide

The falcon_sqla session Manager can be used in two ways:

As a Falcon middleware component.
As a context manager to explicitly provide a database session.

Configuration

Create a SQLAlchemy engine.
Pass the engine to the Manager() initializer as its first parameter.
If using the manager as a middleware component, pass its middleware property to a falcon.App's middleware list:

engine = create_engine('dialect+driver://my/database')
manager = falcon_sqla.Manager(engine)

app = falcon.App(middleware=[manager.middleware])

# The database session will be available as req.context.session

Context Manager

A falcon_sqla.Manager can also explicitly provide a database session using the session_scope() context manager:

# Somewhere inside a responder
with self.manager.session_scope(req, resp) as session:
    # Use the session
    # <...>

session_scope() can also be used as a standalone session context outside of the request-response cycle:

with self.manager.session_scope() as session:
    # Use the session
    # <...>

Custom Vertical Partitioning

Simple random selection of read- and write- database replicas is supported out of the box. Use the add_engine() method to instruct the Manager to include the provided engines in the runtime bind selection logic:

manager = falcon_sqla.Manager(engine)

read_replica = create_engine('dialect+driver://my/database.replica')
manager.add_engine(read_replica, falcon_sqla.EngineRole.READ)

The Manager.get_bind() method can be overridden to implement custom engine selection logic for more complex use cases.

See also this SQLAlchemy recipe: Custom Vertical Partitioning.