Flask¶

Flask extension providing request-scoped session management, automatic transaction handling, and async adapter support via the portal pattern.

Plugin¶

class sqlspec.extensions.flask.SQLSpecPlugin[source]¶

Bases: object

Flask extension for SQLSpec database integration.

Provides request-scoped session management, automatic transaction handling, and async adapter support via portal pattern.

Example

from flask import Flask from sqlspec import SQLSpec from sqlspec.adapters.sqlite import SqliteConfig from sqlspec.extensions.flask import SQLSpecPlugin

sqlspec = SQLSpec() config = SqliteConfig(

connection_config={“database”: “app.db”}, extension_config={

“flask”: {
“commit_mode”: “autocommit”, “session_key”: “db”

}

}

) sqlspec.add_config(config)

app = Flask(__name__) plugin = SQLSpecPlugin(sqlspec, app)

@app.route(“/users”) def list_users():

db = plugin.get_session() result = db.execute(“SELECT * FROM users”) return {“users”: result.all()}

__init__(sqlspec, app=None)[source]¶

Initialize Flask extension with SQLSpec instance.

Parameters:

sqlspec¶ (SQLSpec) – SQLSpec instance with registered configs.
app¶ (Flask | None) – Optional Flask application to initialize immediately.

init_app(app)[source]¶

Initialize Flask application with SQLSpec.

Validates configuration, creates portal if needed, creates pools, and registers hooks.

Parameters:: app¶ (Flask) – Flask application to initialize.
Raises:: ImproperConfigurationError – If extension already registered or keys not unique.
Return type:: None

get_session(key=None)[source]¶

Get or create database session for current request.

Sessions are cached per request for consistency.

Parameters:: key¶ (str | None) – Session key for multi-database configs. Defaults to first config if None.
Return type:: Any
Returns:: Database session (driver instance).

get_connection(key=None)[source]¶

Get database connection for current request.

Parameters:: key¶ (str | None) – Session key for multi-database configs. Defaults to first config if None.
Return type:: Any
Returns:: Raw database connection.

shutdown()[source]¶

Dispose connection pools and stop async portal.

Return type:: None

State¶

class sqlspec.extensions.flask.FlaskConfigState[source]¶

Bases: object

Internal state for each database configuration in Flask extension.

Holds configuration, state keys, commit settings, and transaction logic.

should_commit(status_code)[source]¶

Determine if HTTP status code should trigger commit.

Parameters:: status_code¶ (int) – HTTP response status code.
Return type:: bool
Returns:: True if status should trigger commit, False otherwise.

should_rollback(status_code)[source]¶

Determine if HTTP status code should trigger rollback.

In autocommit modes, anything that doesn’t commit should rollback.

Parameters:: status_code¶ (int) – HTTP response status code.
Return type:: bool
Returns:: True if status should trigger rollback, False otherwise.

__init__(config, connection_key, session_key, commit_mode, extra_commit_statuses, extra_rollback_statuses, is_async, disable_di, enable_correlation_middleware=False, correlation_header='x-request-id', correlation_headers=None, auto_trace_headers=True)¶