API¶
Anything documented here is part of the public API that Flask-SQLAlchemy provides, unless otherwise indicated. Anything not documented here is considered internal or private and may change at any time.
- class flask_sqlalchemy_lite.SQLAlchemy(app=None, *, require_default_engine=True, engine_options=None, session_options=None)¶
Manage SQLAlchemy engines and sessions for Flask applications.
- Parameters:
app (App | None) – Call
init_app()
on this Flask application.require_default_engine (bool) – Whether to raise an error if a
"default"
engine is not configured.engine_options (dict[str, t.Any] | None) – Default arguments passed to
sqlalchemy.create_engine()
for each configured engine.session_options (dict[str, t.Any] | None) – Arguments to configure
sessionmaker
with.
- init_app(app)¶
Register the extension on an application, creating engines from its
config
.- Parameters:
app (App) – The application to register.
- Return type:
None
- get_engine(name='default')¶
Get a specific engine associated with the current application.
The
engine
attribute is a shortcut for calling this without an argument to get the default engine.
- property sessionmaker: sessionmaker[Session]¶
The session factory configured for the current application. This can be used to create sessions directly, but they will not be closed automatically at the end of the application context. Use
session
andget_session()
for that.This can also be used to update the session options after
init_app()
, by calling itsconfigure()
method.
- get_session(name='default')¶
Create a
sqlalchemy.orm.Session
that will be closed at the end of the application context. Repeated calls with the same name within the same application context will return the same session.The
session
attribute is a shortcut for calling this without an argument to get the default session.
- property session: Session¶
The default session for the current application context. It will be closed when the context ends.
- property async_engines: dict[str, AsyncEngine]¶
The async engines associated with the current application.
- get_async_engine(name='default')¶
Get a specific async engine associated with the current application.
The
async_engine
attribute is a shortcut for calling this without an argument to get the default engine.- Parameters:
name (str) – The name associated with the engine.
- Return type:
- property async_engine: AsyncEngine¶
The default async engine associated with the current application.
- property async_sessionmaker: async_sessionmaker[AsyncSession]¶
The async session factory configured for the current application. This can be used to create sessions directly, but they will not be closed automatically at the end of the application context. This is the preferred way to use async sessions, by directly creating and managing them.
async_session
andget_async_session()
are available to manage async sessions for the entire application context, but managing them directly with this is preferred.This can also be used to update the session options after
init_app()
, by calling itsconfigure()
method.
- get_async_session(name='default')¶
Create a
sqlalchemy.ext.asyncio.AsyncSession
that will be closed at the end of the application context. Repeated calls with the same name within the same application context will return the same session.The
async_session
attribute is a shortcut for calling this without an argument to get the default async session.Async sessions are not safe to use across concurrent tasks, as they represent unguarded mutable state. Use a separate named session for each task within a single application context, or use
async_sessionmaker
to directly control async session lifetime.- Parameters:
name (str) – A unique name for caching the session.
- Return type:
- property async_session: AsyncSession¶
The default async session for the current application context. It will be closed when the context ends.