Introduction

Support the compatibility between flask_sqlalchemy and flask_sqlalchemy_lite. It allows users to make minimal changes when they need to migrate from either one of these two packages to each other.

This package can be used in the following cases:

• Make the codes written by flask_sqlitealchemy_lite supports Python 3.7~3.8:

  The main motivation of this package is because flask_sqlalchemy_lite does not support python<=3.8. This package is designed for providing the similar usages when users have to make the flask_sqlalchemy_lite working with python<=3.8 by using flask_sqlalchemy. In this case, users can get rid of the difficulty of maintaining two sets of codes.

• Use flask_sqlalchemy APIs even if you are using flask_sqlalchemy_lite:

  Compared to flask_sqlalchemy_lite, the older package flask_sqlalchemy supports some extra functionalities. These functionalities are not supported in flask_sqlalchemy_lite because most of these functionalities are designed for old-style usages. However, if users need to migrate from flask_sqlalchemy to flask_sqlalchemy_lite but do not want to change many codes, using this package can be an option.

• Use sqlalchemy>=2.0.0 and sa.orm.DeclarativeBase even if you are using Python 3.7:

  The SQLAlchemy 2 coding styles supported by sa.orm.DeclarativeBase and sa.orm.Mapped are already available in Python 3.7. However, the newest version of flask_sqlalchemy for Python 3.7 is 3.0.5 which does not support DeclarativeBase features. This package provides a compatible version of flask_sqlalchemy that allows users to use DeclarativeBase when using Python 3.7.

Usage

Flask SQLAlchemy Lite

When you are using flask_sqlalchemy_lite, using the following codes will let your codes fall back to the compatible mode if flask_sqlalchemy_lite is not installed but flask_sqlalchemy is installed.

use_flask_sqlalchemy_lite_style.py

import sqlalchemy as sa
import sqlalchemy.orm as sa_orm
import flask_sqlalchemy_compat as fsc


class _Base(sa_orm.DeclarativeBase): ...


db, Base = fsc.get_flask_sqlalchemy_lite(_Base)


class NewModel(Base):
    __tablename__ = "new_model"

    id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)
    name: sa_orm.Mapped[str] = sa_orm.mapped_column()


if __name__ == "__main__":
    import os
    import flask

    app = flask.Flask(__name__, instance_path=os.path.abspath("./instance"))
    app.config.update({"SQLALCHEMY_ENGINES": {"default": "sqlite:///main.db"}})
    db.init_app(app)

    with app.app_context():
        Base.metadata.create_all(db.engine)

        db.session.add(NewModel(name="new"))
        db.session.commit()

        model = db.session.scalar(sa.select(NewModel))
        print(model.id, model.name) if model is not None else print("NOT FOUND.")

If you have not installed flask_sqlalchemy_lite but installed flask_sqlalchemy, the above example will still work.

Flask SQLAlchemy

Similarly, the following example is designed for the codes written with flask_sqlalchemy. The codes fall back to the compatible mode if flask-sqlalchemy is not installed but flask-sqlalchemy-lite is installed.

use_flask_sqlalchemy_style.py

import sqlalchemy as sa
import sqlalchemy.orm as sa_orm
import flask_sqlalchemy_compat as fsc


class _Base(sa_orm.DeclarativeBase): ...


db = fsc.get_flask_sqlalchemy(_Base)


class NewModel(db.Model):
    id: sa_orm.Mapped[int] = sa_orm.mapped_column(primary_key=True)
    name: sa_orm.Mapped[str] = sa_orm.mapped_column()


if __name__ == "__main__":
    import os
    import flask

    app = flask.Flask(__name__, instance_path=os.path.abspath("./instance"))
    app.config.update({"SQLALCHEMY_DATABASE_URI": "sqlite:///main.db"})
    db.init_app(app)

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

        # Indeed, flask_sqlalchemy has a type hint issue until `3.1.x`.
        # But it does not cause issues in run time. See
        # https://github.com/pallets-eco/flask-sqlalchemy/issues/1312
        db.session.add(NewModel(name="new"))
        db.session.commit()

        model = db.session.scalar(sa.select(NewModel))
        print(model.id, model.name) if model is not None else print("NOT FOUND.")

If you have not installed flask_sqlalchemy but installed flask_sqlalchemy_lite, the above example will still work.

Acknowledgements

• Pallets-Eco/Flask-SQLAlchemy-Lite: The new SQLAlchemy extension for Flask. It only supports Python>=3.9.
• Pallets-Eco/Flask-SQLAlchemy: The older SQLAlchemy extension for Flask.
• SQLAlchemy/SQLAlchemy: The SQL Toolkit and Object Relational Mapper (ORM).

Related materials

Changelog:

Changelog

License of this project:

MIT License

Guidelines for the contributions:

Contributing

Contributor covenant code of conduct:

Code of conduct

Security policy:

Security