Support the SQLAlchemy 2.0 DeclarativeBase models

CHANGES.rst

@@ -3,6 +3,8 @@ Version 3.1.0
 
 Unreleased
 
+-   Add support for the SQLAlchemy 2.x API via ``model_class`` parameter. :issue:`1140`
+-   Bump minimum version of SQLAlchemy to 2.0.16.
 -   Remove previously deprecated code.
 -   Pass extra keyword arguments from ``get_or_404`` to ``session.get``. :issue:`1149`
 

README.rst

@@ -29,14 +29,19 @@ A Simple Example
 
     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"
-    db = SQLAlchemy(app)
+
+    class Base(DeclarativeBase):
+      pass
+
+    db = SQLAlchemy(app, model_class=Base)
 
     class User(db.Model):
-        id = db.Column(db.Integer, primary_key=True)
-        username = db.Column(db.String, unique=True, nullable=False)
+        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()

docs/api.rst

@@ -32,6 +32,12 @@ Model
         If the ``__table__`` or ``__tablename__`` is set explicitly, that will be used
         instead.
 
+Metaclass mixins (SQLAlchemy 1.x)
+---------------------------------
+
+If your code uses the SQLAlchemy 1.x API (the default for code that doesn't specify a ``model_class``),
+then these mixins are automatically applied to the ``Model`` class.
+
 .. autoclass:: DefaultMeta
 
 .. autoclass:: BindMetaMixin

docs/config.rst

@@ -151,31 +151,6 @@ only need to use :data:`SQLALCHEMY_DATABASE_URI` and :data:`SQLALCHEMY_ENGINE_OP
     in that engine's options.
 
 
-Using custom MetaData and naming conventions
---------------------------------------------
-
-You can optionally construct the :class:`.SQLAlchemy` object with a custom
-:class:`~sqlalchemy.schema.MetaData` object. This allows you to specify a custom
-constraint `naming convention`_. This makes constraint names consistent and predictable,
-useful when using migrations, as described by `Alembic`_.
-
-.. code-block:: python
-
-    from sqlalchemy import MetaData
-    from flask_sqlalchemy import SQLAlchemy
-
-    db = SQLAlchemy(metadata=MetaData(naming_convention={
-        "ix": 'ix_%(column_0_label)s',
-        "uq": "uq_%(table_name)s_%(column_0_name)s",
-        "ck": "ck_%(table_name)s_%(constraint_name)s",
-        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
-        "pk": "pk_%(table_name)s"
-    }))
-
-.. _naming convention: https://docs.sqlalchemy.org/core/constraints.html#constraint-naming-conventions
-.. _Alembic: https://alembic.sqlalchemy.org/en/latest/naming.html
-
-
 Timeouts
 --------
 

docs/customizing.rst

@@ -21,29 +21,26 @@ joined-table inheritance.
 
 .. code-block:: python
 
-    from flask_sqlalchemy.model import Model
-    import sqlalchemy as sa
-    import sqlalchemy.orm
+    from sqlalchemy import Integer, String, ForeignKey
+    from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, declared_attr
 
-    class IdModel(Model):
-        @sa.orm.declared_attr
+    class Base(DeclarativeBase):
+        @declared_attr.cascading
+        @classmethod
         def id(cls):
             for base in cls.__mro__[1:-1]:
                 if getattr(base, "__table__", None) is not None:
-                    type = sa.ForeignKey(base.id)
-                    break
-            else:
-                type = sa.Integer
+                        return mapped_column(ForeignKey(base.id), primary_key=True)
+                else:
+                    return mapped_column(Integer, primary_key=True)
 
-            return sa.Column(type, primary_key=True)
-
-    db = SQLAlchemy(model_class=IdModel)
+    db = SQLAlchemy(app, model_class=Base)
 
     class User(db.Model):
-        name = db.Column(db.String)
+        name: Mapped[str] = mapped_column(String)
 
     class Employee(User):
-        title = db.Column(db.String)
+        title: Mapped[str] = mapped_column(String)
 
 
 Abstract Models and Mixins
@@ -56,28 +53,49 @@ they are created or updated.
 .. code-block:: python
 
     from datetime import datetime
+    from sqlalchemy import DateTime, Integer, String
+    from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, declared_attr
 
     class TimestampModel(db.Model):
         __abstract__ = True
-        created = db.Column(db.DateTime, nullable=False, default=datetime.utcnow)
-        updated = db.Column(db.DateTime, onupdate=datetime.utcnow)
+        created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+        updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 
     class Author(db.Model):
-        ...
+        id: Mapped[int] = mapped_column(Integer, primary_key=True)
+        username: Mapped[str] = mapped_column(String, unique=True, nullable=False)
 
     class Post(TimestampModel):
-        ...
+        id: Mapped[int] = mapped_column(Integer, primary_key=True)
+        title: Mapped[str] = mapped_column(String, nullable=False)
 
 This can also be done with a mixin class, inheriting from ``db.Model`` separately.
 
 .. code-block:: python
 
     class TimestampMixin:
-        created = db.Column(db.DateTime, nullable=False, default=datetime.utcnow)
-        updated = db.Column(db.DateTime, onupdate=datetime.utcnow)
+        created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+        updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 
     class Post(TimestampMixin, db.Model):
-        ...
+        id: Mapped[int] = mapped_column(Integer, primary_key=True)
+        title: Mapped[str] = mapped_column(String, nullable=False)
+
+
+Disabling Table Name Generation
+-------------------------------
+
+Some projects prefer to set each model's ``__tablename__`` manually rather than relying
+on Flask-SQLAlchemy's detection and generation. The simple way to achieve that is to
+set each ``__tablename__`` and not modify the base class. However, the table name
+generation can be disabled by setting `disable_autonaming=True` in the `SQLAlchemy` constructor.
+
+.. code-block:: python
+
+    class Base(sa_orm.DeclarativeBase):
+        pass
+
+    db = SQLAlchemy(app, model_class=Base, disable_autonaming=True)
 
 
 Session Class
@@ -158,73 +176,3 @@ To customize only ``session.query``, pass the ``query_cls`` key to the
 .. code-block:: python
 
     db = SQLAlchemy(session_options={"query_cls": GetOrQuery})
-
-
-Model Metaclass
----------------
-
-.. warning::
-    Metaclasses are an advanced topic, and you probably don't need to customize them to
-    achieve what you want. It is mainly documented here to show how to disable table
-    name generation.
-
-The model metaclass is responsible for setting up the SQLAlchemy internals when defining
-model subclasses. Flask-SQLAlchemy adds some extra behaviors through mixins; its default
-metaclass, :class:`~.DefaultMeta`, inherits them all.
-
--   :class:`.BindMetaMixin`: ``__bind_key__`` sets the bind to use for the model.
--   :class:`.NameMetaMixin`: If the model does not specify a ``__tablename__`` but does
-    specify a primary key, a name is automatically generated.
-
-You can add your own behaviors by defining your own metaclass and creating the
-declarative base yourself. Be sure to still inherit from the mixins you want (or just
-inherit from the default metaclass).
-
-Passing a declarative base class instead of a simple model base class to ``model_class``
-will cause Flask-SQLAlchemy to use this base instead of constructing one with the
-default metaclass.
-
-.. code-block:: python
-
-    from sqlalchemy.orm import declarative_base
-    from flask_sqlalchemy import SQLAlchemy
-    from flask_sqlalchemy.model import DefaultMeta, Model
-
-    class CustomMeta(DefaultMeta):
-        def __init__(cls, name, bases, d):
-            # custom class setup could go here
-
-            # be sure to call super
-            super(CustomMeta, cls).__init__(name, bases, d)
-
-        # custom class-only methods could go here
-
-    CustomModel = declarative_base(cls=Model, metaclass=CustomMeta, name="Model")
-    db = SQLAlchemy(model_class=CustomModel)
-
-You can also pass whatever other arguments you want to
-:func:`~sqlalchemy.orm.declarative_base` to customize the base class.
-
-
-Disabling Table Name Generation
-```````````````````````````````
-
-Some projects prefer to set each model's ``__tablename__`` manually rather than relying
-on Flask-SQLAlchemy's detection and generation. The simple way to achieve that is to
-set each ``__tablename__`` and not modify the base class. However, the table name
-generation can be disabled by defining a custom metaclass with only the
-``BindMetaMixin`` and not the ``NameMetaMixin``.
-
-.. code-block:: python
-
-    from sqlalchemy.orm import DeclarativeMeta, declarative_base
-    from flask_sqlalchemy.model import BindMetaMixin, Model
-
-    class NoNameMeta(BindMetaMixin, DeclarativeMeta):
-        pass
-
-    CustomModel = declarative_base(cls=Model, metaclass=NoNameMeta, name="Model")
-    db = SQLAlchemy(model_class=CustomModel)
-
-This creates a base that still supports the ``__bind_key__`` feature but does not
-generate table names.

docs/legacy-quickstart.rst

@@ -0,0 +1,95 @@
+
+:orphan:
+
+Legacy Quickstart
+======================
+
+.. warning::
+    This guide shows you how to initialize the extension and define models
+    when using the SQLAlchemy 1.x style of ORM model classes. We encourage you to
+    upgrade to `SQLAlchemy 2.x`_ to take advantage of the new typed model classes.
+
+.. _SQLAlchemy 2.x: https://docs.sqlalchemy.org/en/20/orm/quickstart.html
+
+Initialize the Extension
+------------------------
+
+First create the ``db`` object using the ``SQLAlchemy`` constructor.
+
+When using the SQLAlchemy 1.x API, you do not need to pass any arguments to the ``SQLAlchemy`` constructor.
+A declarative base class will be created behind the scenes for you.
+
+.. code-block:: python
+
+    from flask import Flask
+    from flask_sqlalchemy import SQLAlchemy
+    from sqlalchemy.orm import DeclarativeBase
+
+    db = SQLAlchemy()
+
+
+Using custom MetaData and naming conventions
+--------------------------------------------
+
+You can optionally construct the :class:`.SQLAlchemy` object with a custom
+:class:`~sqlalchemy.schema.MetaData` object. This allows you to specify a custom
+constraint `naming convention`_. This makes constraint names consistent and predictable,
+useful when using migrations, as described by `Alembic`_.
+
+.. code-block:: python
+
+    from sqlalchemy import MetaData
+    from flask_sqlalchemy import SQLAlchemy
+
+    db = SQLAlchemy(metadata=MetaData(naming_convention={
+        "ix": 'ix_%(column_0_label)s',
+        "uq": "uq_%(table_name)s_%(column_0_name)s",
+        "ck": "ck_%(table_name)s_%(constraint_name)s",
+        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+        "pk": "pk_%(table_name)s"
+    }))
+
+.. _naming convention: https://docs.sqlalchemy.org/core/constraints.html#constraint-naming-conventions
+.. _Alembic: https://alembic.sqlalchemy.org/en/latest/naming.html
+
+
+
+Define Models
+-------------
+
+Subclass ``db.Model`` to define a model class. This is a SQLAlchemy declarative base
+class, it will take ``Column`` attributes and create a table.
+
+.. code-block:: python
+
+    class User(db.Model):
+        id = db.Column(db.Integer, primary_key=True)
+        username = db.Column(db.String, unique=True, nullable=False)
+        email = db.Column(db.String)
+
+For convenience, the extension object provides access to names in the ``sqlalchemy`` and
+``sqlalchemy.orm`` modules. So you can use ``db.Column`` instead of importing and using
+``sqlalchemy.Column``, although the two are equivalent.
+
+Unlike plain SQLAlchemy, Flask-SQLAlchemy's model will automatically generate a table name
+if ``__tablename__`` is not set and a primary key column is defined.
+The table name ``"user"`` will automatically be assigned to the model's table.
+
+
+Create the Tables
+-----------------
+
+Defining a model does not create it in the database. Use :meth:`~.SQLAlchemy.create_all`
+to create the models and tables after defining them. If you define models in submodules,
+you must import them so that SQLAlchemy knows about them before calling ``create_all``.
+
+.. code-block:: python
+
+    with app.app_context():
+        db.create_all()
+
+Querying the Data
+-----------------
+
+You can query the data the same way regardless of SQLAlchemy version.
+See :doc:`queries` for more information about queries.