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

property engines: dict[str, Engine]

The engines associated with the current application.

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.

Parameters:

name (str) – The name associated with the engine.

Return type:

Engine

property engine: Engine

The default engine associated with the current application.

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 and get_session() for that.

This can also be used to update the session options after init_app(), by calling its configure() 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.

Parameters:

name (str) – A unique name for caching the session.

Return type:

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:

AsyncEngine

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 and get_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 its configure() 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:

AsyncSession

property async_session: AsyncSession

The default async session for the current application context. It will be closed when the context ends.