Flask Extension¶

from sqlspec.extensions.flask import FlaskConfigState, SQLSpecAsyncService, SQLSpecPlugin, SQLSpecSyncService

Flask WSGI extension managing flask.g request-scoped sessions, automatic commit/rollback teardown hooks, and background event-loop portal bridging for async adapters. See the Flask Integration Guide for usage examples.

Plugin & Configuration State¶

SQLSpecPlugin ¶

Flask extension for SQLSpec database integration.

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

init_app ¶

init_app(app)

Initialize Flask application with SQLSpec.

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

Parameters:

Name	Type	Description	Default
`app`	`Flask`	Flask application to initialize.	required

Raises:

Type	Description
`ImproperConfigurationError`	If extension already registered or keys not unique.

get_session ¶

get_session(key=None)

Get or create database session for current request.

Sessions are cached per request for consistency.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Session key for multi-database configs. Defaults to first config if None.	`None`

Returns:

Type	Description
`Any`	Database session (driver instance).

get_connection ¶

get_connection(key=None)

Get database connection for current request.

Note

Imports flask components dynamically at runtime to avoid hard dependency.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Session key for multi-database configs. Defaults to first config if None.	`None`

Returns:

Type	Description
`Any`	Raw database connection.

shutdown ¶

shutdown()

Dispose connection pools and stop async portal.

FlaskConfigState ¶

Internal state for each database configuration in Flask extension.

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

config ¶

config

connection_key ¶

connection_key

session_key ¶

session_key

commit_mode ¶

commit_mode

extra_commit_statuses ¶

extra_commit_statuses

extra_rollback_statuses ¶

extra_rollback_statuses

is_async ¶

is_async

disable_di ¶

disable_di

enable_correlation_middleware ¶

enable_correlation_middleware = False

correlation_header ¶

correlation_header = 'x-request-id'

correlation_headers ¶

correlation_headers = None

auto_trace_headers ¶

auto_trace_headers = True

enable_sqlcommenter_middleware ¶

enable_sqlcommenter_middleware = True

should_commit ¶

should_commit(status_code)

Determine if HTTP status code should trigger commit.

Parameters:

Name	Type	Description	Default
`status_code`	`int`	HTTP response status code.	required

Returns:

Type	Description
`bool`	True if status should trigger commit, False otherwise.

should_rollback ¶

should_rollback(status_code)

Determine if HTTP status code should trigger rollback.

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

Parameters:

Name	Type	Description	Default
`status_code`	`int`	HTTP response status code.	required

Returns:

Type	Description
`bool`	True if status should trigger rollback, False otherwise.