or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

development-tools.mdextension-setup.mdindex.mdmodels-tables.mdpagination.mdquery-interface.mdsession-management.md
tile.json

tessl/pypi-flask-sqlalchemy

Add SQLAlchemy support to your Flask application.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/flask-sqlalchemy@3.1.x

To install, run

npx @tessl/cli install tessl/pypi-flask-sqlalchemy@3.1.0

index.mddocs/

Flask-SQLAlchemy

Flask-SQLAlchemy is an extension for Flask that adds support for SQLAlchemy to your application. It aims to simplify using SQLAlchemy with Flask by providing useful defaults and extra helpers that make it easier to accomplish common database tasks.

Package Information

  • Package Name: Flask-SQLAlchemy
  • Language: Python
  • Installation: pip install Flask-SQLAlchemy

Core Imports

from flask_sqlalchemy import SQLAlchemy

Import specific components from submodules (optional):

from flask_sqlalchemy.pagination import Pagination
from flask_sqlalchemy.query import Query
from flask_sqlalchemy.record_queries import get_recorded_queries

Basic Usage

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///example.sqlite"

class Base(DeclarativeBase):
    pass

db = SQLAlchemy(app, model_class=Base)

class User(db.Model):
    id: Mapped[int] = mapped_column(db.Integer, primary_key=True)
    username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False)

with app.app_context():
    db.create_all()

    # Add and commit data
    db.session.add(User(username="example"))
    db.session.commit()

    # Query data
    users = db.session.execute(db.select(User)).scalars()

Architecture

Flask-SQLAlchemy follows a Flask extension pattern with several key components:

  • SQLAlchemy Extension: Main class that integrates SQLAlchemy with Flask applications
  • Model Base Classes: Declarative base classes with Flask-specific features like automatic table naming
  • Session Management: Flask application context-aware sessions with automatic cleanup
  • Query Interface: Enhanced query classes with Flask conveniences like get_or_404()
  • Pagination: Built-in pagination support for large result sets
  • Multiple Database Support: Bind key system for multiple databases

The extension provides seamless integration between Flask's application context system and SQLAlchemy's session management, ensuring proper database connection handling across request lifecycles.

Capabilities

Extension Setup and Configuration

Core extension class initialization, Flask app integration, and database configuration management. This includes setting up database URIs, engine options, and binding multiple databases.

class SQLAlchemy:
    Query: type[Query]  # The default query class used by Model.query
    
    def __init__(
        self,
        app: Flask | None = None,
        *,
        metadata: sa.MetaData | None = None,
        session_options: dict[str, Any] | None = None,
        query_class: type[Query] = Query,
        model_class: Any = Model,
        engine_options: dict[str, Any] | None = None,
        add_models_to_shell: bool = True,
        disable_autonaming: bool = False,
    ): ...
    
    def init_app(self, app: Flask) -> None: ...

Extension Setup

Database Models and Tables

Declarative model base classes with automatic table naming, bind key support, and Flask integration features. Includes table creation utilities and metadata management.

class Model:
    query_class: type[Query]
    query: Query
    
def should_set_tablename(cls: type) -> bool: ...
def camel_to_snake_case(name: str) -> str: ...

Models and Tables

Session and Database Operations

Session management with Flask application context integration, bind key resolution, and automatic session cleanup. Core database operations and transaction handling.

class Session(sa_orm.Session):
    def get_bind(
        self,
        mapper: Any | None = None,
        clause: Any | None = None,
        bind: sa.engine.Engine | sa.engine.Connection | None = None,
        **kwargs: Any,
    ) -> sa.engine.Engine | sa.engine.Connection: ...

Session Management

Query Interface and Conveniences

Enhanced query classes with Flask-specific convenience methods for common web patterns like 404 error handling and result processing.

class Query(sa_orm.Query):
    def get_or_404(self, ident: Any, description: str | None = None) -> Any: ...
    def first_or_404(self, description: str | None = None) -> Any: ...
    def one_or_404(self, description: str | None = None) -> Any: ...
    def paginate(*, page: int | None = None, per_page: int | None = None, **kwargs) -> Pagination: ...

Query Interface

Pagination

Built-in pagination support for both modern SQLAlchemy select statements and legacy Query objects, with request parameter integration and pagination widget helpers.

class Pagination:
    page: int
    per_page: int
    total: int | None
    items: list[Any]
    
    def prev(*, error_out: bool = False) -> Pagination: ...
    def next(*, error_out: bool = False) -> Pagination: ...
    def iter_pages(**kwargs) -> Iterator[int | None]: ...

Pagination

Development and Debugging

Optional features for development including query recording, modification tracking, and Flask shell integration for enhanced debugging capabilities.

def get_recorded_queries() -> list[_QueryInfo]: ...

models_committed: Signal
before_models_committed: Signal

Development Tools

Configuration

Flask-SQLAlchemy uses the following configuration variables:

  • SQLALCHEMY_DATABASE_URI: Default database connection URI
  • SQLALCHEMY_ENGINE_OPTIONS: Default engine configuration options
  • SQLALCHEMY_ECHO: Enable SQLAlchemy query logging
  • SQLALCHEMY_BINDS: Mapping of bind keys to database URIs/options
  • SQLALCHEMY_RECORD_QUERIES: Enable query recording functionality
  • SQLALCHEMY_TRACK_MODIFICATIONS: Enable model modification tracking

Types

from typing import Any, Mapping, TypeVar, Union, Type
import sqlalchemy as sa
import sqlalchemy.orm as sa_orm

# Type variables for model class customization
_FSA_MCT = TypeVar(
    "_FSA_MCT", 
    bound=Union[
        Type[Model],
        sa_orm.DeclarativeMeta, 
        Type[sa_orm.DeclarativeBase],
        Type[sa_orm.DeclarativeBaseNoMeta],
    ]
)
"""
Type variable for Flask-SQLAlchemy model class parameter.

Used in SQLAlchemy.__init__() to accept various model class types:
- Type[Model]: Flask-SQLAlchemy's default Model class
- sa_orm.DeclarativeMeta: SQLAlchemy 1.x declarative metaclass
- Type[sa_orm.DeclarativeBase]: SQLAlchemy 2.x declarative base
- Type[sa_orm.DeclarativeBaseNoMeta]: SQLAlchemy 2.x base without metaclass

This allows flexible model class customization while maintaining type safety.
"""

_O = TypeVar("_O", bound=object)
"""
Generic type variable for object returns.

Used in methods like get_or_404() to preserve the return type of the 
queried entity while ensuring type safety.
"""