Flask#

Configuration#

Use sqlspec.config.FlaskConfig in extension_config["flask"]. These settings apply across adapters; no adapter-specific subtype is needed.

class sqlspec.config.FlaskConfig[source]

Bases: TypedDict

Configuration options for Flask SQLSpec extension.

All fields are optional with sensible defaults. Use in extension_config["flask"]:

connection_key: NotRequired[str]

auto-generated from session_key.

Type:

Key for storing connection in Flask g object. Default

session_key: NotRequired[str]

'db_session'.

Type:

Key for accessing session via plugin.get_session(). Default

commit_mode: NotRequired[Literal['manual', 'autocommit', 'autocommit_include_redirect']]

'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

Type:

Transaction commit mode. Default

extra_commit_statuses: NotRequired[set[int]]

None.

Type:

Additional HTTP status codes that trigger commit. Default

extra_rollback_statuses: NotRequired[set[int]]

None.

Type:

Additional HTTP status codes that trigger rollback. Default

disable_di: NotRequired[bool]

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.

Type:

Disable built-in dependency injection. Default

enable_sqlcommenter_middleware: NotRequired[bool]

True. When the driver's StatementConfig has enable_sqlcommenter=True, request attributes are populated automatically. Set to False to explicitly disable this behavior.

Type:

Control automatic SQLCommenter context population. Default

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.

__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.

Note

Imports flask components dynamically at runtime to avoid hard dependency.

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.

__post_init__()[source]#

Validate status configuration.

Return type:

None

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, enable_sqlcommenter_middleware=True)#