Flask Integration¶

sqlspec.extensions.flask provides SQLSpecPlugin for Flask applications, managing synchronous (and portal-bridged asynchronous) connection pools across Flask's application factory lifecycle (init_app), caching request-scoped sessions on flask.g, and finalizing transactions in teardown_appcontext.

Installation¶

uvpippdmpoetry

uv add "sqlspec[flask]"

pip install "sqlspec[flask]"

pdm add "sqlspec[flask]"

poetry add "sqlspec[flask]"

Application Factory Setup¶

Create a SQLSpecPlugin(spec) instance, initialize it inside your create_app factory with plugin.init_app(app), and retrieve the active request session via plugin.get_session():

docs/examples/frameworks/flask/basic_setup.py

from typing import Any

from flask import Flask

from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig, SqliteDriver
from sqlspec.extensions.flask import SQLSpecPlugin


def create_app(plugin: SQLSpecPlugin) -> Flask:
    """Create a Flask application initialized with SQLSpecPlugin."""
    app = Flask(__name__)
    plugin.init_app(app)

    @app.get("/health")
    def health() -> dict[str, Any]:
        db: SqliteDriver = plugin.get_session()
        return db.select_one("SELECT 1 AS ok")

    return app


spec = SQLSpec()
spec.add_config(SqliteConfig(connection_config={"database": ":memory:"}))
plugin = SQLSpecPlugin(spec)
app = create_app(plugin)

Calling plugin.get_session() multiple times within the same HTTP request returns the same flask.g-cached driver session.

Multi-Database Binds¶

Configure distinct session_key and optional connection_key values under extension_config["flask"] (FlaskConfig; when connection_key is omitted, SQLSpec derives an internal flask.g key automatically from session_key) and pass the key to plugin.get_session("<key>"):

docs/examples/frameworks/flask/multi_database.py

from typing import Any

from flask import Flask

from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig, SqliteDriver
from sqlspec.extensions.flask import SQLSpecPlugin


def create_app(plugin: SQLSpecPlugin) -> Flask:
    """Create a Flask application exposing a multi-database report endpoint."""
    app = Flask(__name__)
    plugin.init_app(app)

    @app.get("/report")
    def report() -> dict[str, list[dict[str, Any]]]:
        db: SqliteDriver = plugin.get_session("db")
        etl_db: SqliteDriver = plugin.get_session("etl_db")
        users = db.select("SELECT 1 AS id, 'Alice' AS name")
        metrics = etl_db.select("SELECT 'metric1' AS name, 100 AS value")
        return {"users": users, "metrics": metrics}

    return app


spec = SQLSpec()
spec.add_config(
    SqliteConfig(
        connection_config={"database": ":memory:"},
        extension_config={"flask": {"session_key": "db", "connection_key": "db_connection"}},
    )
)
spec.add_config(
    SqliteConfig(
        connection_config={"database": ":memory:"},
        extension_config={"flask": {"session_key": "etl_db", "connection_key": "etl_connection"}},
    )
)
plugin = SQLSpecPlugin(spec)
app = create_app(plugin)

Configuration Options¶

Key	Type	Default	Description
`connection_key`	`str`	-	Key for storing connection in Flask g object. Default: auto-generated from session_key.
`session_key`	`str`	`'db_session'`	Key for accessing session via plugin.get_session(). Default: 'db_session'.
`commit_mode`	`Literal['manual', 'autocommit', 'autocommit_include_redirect']`	`'manual'`	Transaction commit mode. Default: 'manual'. manual: No automatic commits, user handles explicitly; autocommit: Commits on 2xx status, rollback otherwise; autocommit_include_redirect: Commits on 2xx-3xx status, rollback otherwise
`extra_commit_statuses`	`set[int]`	`None`	Additional HTTP status codes that trigger commit. Default: None.
`extra_rollback_statuses`	`set[int]`	`None`	Additional HTTP status codes that trigger rollback. Default: None.
`disable_di`	`bool`	`False`	Disable built-in dependency injection. Default: False. When True, the Flask extension will not register request hooks for managing database connections and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution.
`enable_sqlcommenter_middleware`	`bool`	`True`	Control automatic SQLCommenter context population. Default: True. When the driver's :class:`~sqlspec.core.statement.StatementConfig` has `enable_sqlcommenter=True`, request attributes are populated automatically. Set to `False` to explicitly disable this behavior.
`enable_correlation_middleware`	`bool`	`True`	Enable request correlation ID middleware. Default: True
`correlation_header`	`str`	`X-Request-ID`	HTTP header to read the request correlation ID from when middleware is enabled. Default: `X-Request-ID`
`correlation_headers`	`tuple[str, ...] or list[str]`	-	Additional HTTP headers to read as correlation ID fallbacks.
`auto_trace_headers`	`bool`	`True`	Read standard trace context headers as correlation ID fallbacks. Default: True.

Set enable_correlation_middleware=False to stop this plugin from reading request IDs or adding them to response headers.

Recap¶