Document refactor to emphasize 2.x, fix for bind key and metadata for 2.x

Author: pamelafox

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

docs/models.rst

@@ -4,35 +4,82 @@ Models and Tables
 Use the ``db.Model`` class to define models, or the ``db.Table`` class to create tables.
 Both handle Flask-SQLAlchemy's bind keys to associate with a specific engine.
 
+Initializing the Base Class
+---------------------------
 
-Defining Models
----------------
+``SQLAlchemy`` 2.x offers several possible base classes for your models:
+`DeclarativeBase`_ or `DeclarativeBaseNoMeta`_.
 
-See SQLAlchemy's `declarative documentation`_ for full information about defining model
-classes declaratively.
+Create a subclass of one of those classes:
 
-.. _declarative documentation: https://docs.sqlalchemy.org/orm/declarative_tables.html
+.. code-block:: python
 
-Subclass ``db.Model`` to create a model class. This is a SQLAlchemy declarative base
-class, it will take ``Column`` attributes and create a table. 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.
+    from flask import Flask
+    from flask_sqlalchemy import SQLAlchemy
+    from sqlalchemy.orm import DeclarativeBase
+
+    class Base(DeclarativeBase):
+      pass
+
+.. _DeclarativeBase: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBase
+.. _DeclarativeBaseNoMeta: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBaseNoMeta
+
+If desired, you can enable `SQLAlchemy's native support for data classes`_
+by adding `MappedAsDataclass` as an additional parent class.
 
 .. code-block:: python
 
-    import sqlalchemy as sa
+    from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
 
-    class User(db.Model):
-        id = sa.Column(sa.Integer, primary_key=True)
-        type = sa.Column(sa.String)
+    class Base(DeclarativeBase, MappedAsDataclass):
+      pass
+
+.. _SQLAlchemy's native support for data classes: https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#native-support-for-dataclasses-mapped-as-orm-models
+
+
+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
 
-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.
+    class Base(DeclarativeBase):
+        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"
+        })
 
-It's also possible to use the SQLAlchemy 2.x style of defining models,
-as long as you initialized the extension with an appropriate 2.x model base class
-(as described in the quickstart).
+.. _naming convention: https://docs.sqlalchemy.org/core/constraints.html#constraint-naming-conventions
+.. _Alembic: https://alembic.sqlalchemy.org/en/latest/naming.html
+
+
+Initialize the Extension
+------------------------
+
+Once you've defined a base class, create the ``db`` object using the ``SQLAlchemy`` constructor.
+
+.. code-block:: python
+
+    db = SQLAlchemy(model_class=Base)
+
+
+Defining Models
+---------------
+
+See SQLAlchemy's `declarative documentation`_ for full information about defining model
+classes declaratively.
+
+.. _declarative documentation: https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html
+
+Subclass ``db.Model`` to create a model class. 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.
 
 .. code-block:: python
 
@@ -43,6 +90,7 @@ as long as you initialized the extension with an appropriate 2.x model base clas
         username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False)
         email: Mapped[str] = mapped_column(db.String)
 
+
 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``.
@@ -59,7 +107,7 @@ Defining Tables
 See SQLAlchemy's `table documentation`_ for full information about defining table
 objects.
 
-.. _table documentation: https://docs.sqlalchemy.org/core/metadata.html
+.. _table documentation: https://docs.sqlalchemy.org/en/20/core/metadata.html
 
 Create instances of ``db.Table`` to define tables. The class takes a table name, then
 any columns and other table parts such as columns and constraints. Unlike plain

docs/quickstart.rst

@@ -21,11 +21,14 @@ Flask-SQLAlchemy is a wrapper around SQLAlchemy. You should follow the
 `SQLAlchemy Tutorial`_ to learn about how to use it, and consult its documentation
 for detailed information about its features. These docs show how to set up
 Flask-SQLAlchemy itself, not how to use SQLAlchemy. Flask-SQLAlchemy sets up the
-engine, declarative model class, and scoped session automatically, so you can skip those
+engine and scoped session automatically, so you can skip those
 parts of the SQLAlchemy tutorial.
 
-.. _SQLAlchemy Tutorial: https://docs.sqlalchemy.org/tutorial/index.html
+.. _SQLAlchemy Tutorial: https://docs.sqlalchemy.org/en/20/tutorial/index.html
 
+This guide assumes you are using SQLAlchemy 2.x, which has a new API for defining models
+and better support for Python type hints and data classes. If you are using SQLAlchemy 1.x,
+see :doc:`legacy-quickstart`.
 
 Installation
 ------------
@@ -44,30 +47,8 @@ Initialize the Extension
 ------------------------
 
 First create the ``db`` object using the ``SQLAlchemy`` constructor.
-The initialization step depends on which version of ``SQLAlchemy`` you're using.
-This extension supports both SQLAlchemy 1 and 2, but defaults to SQLAlchemy 1.
 
-.. _sqlalchemy1-initialization:
-
-Using the SQLAlchemy 1 API
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To use the SQLAlchemy 1.x API, you do not need to pass any arguments to the ``SQLAlchemy`` constructor.
-
-.. code-block:: python
-
-    from flask import Flask
-    from flask_sqlalchemy import SQLAlchemy
-    from sqlalchemy.orm import DeclarativeBase
-
-    db = SQLAlchemy()
-
-.. _sqlalchemy2-initialization:
-
-Using the SQLAlchemy 2 API
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To use the new SQLAlchemy 2.x API, pass a subclass of either `DeclarativeBase`_ or `DeclarativeBaseNoMeta`_
+Pass a subclass of either `DeclarativeBase`_ or `DeclarativeBaseNoMeta`_
 to the constructor.
 
 .. code-block:: python
@@ -81,21 +62,11 @@ to the constructor.
 
     db = SQLAlchemy(model_class=Base)
 
-If desired, you can enable `SQLAlchemy's native support for data classes`_
-by adding `MappedAsDataclass` as an additional parent class.
 
-.. code-block:: python
-
-    from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
-
-    class Base(DeclarativeBase, MappedAsDataclass):
-      pass
-
-    db = SQLAlchemy(model_class=Base)
+Learn more about customizing the base model class in :doc:`models`.
 
 .. _DeclarativeBase: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBase
 .. _DeclarativeBaseNoMeta: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBaseNoMeta
-.. _SQLAlchemy's native support for data classes: https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#native-support-for-dataclasses-mapped-as-orm-models
 
 About the ``SQLAlchemy`` object
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -134,34 +105,19 @@ keys are used.
 Define Models
 -------------
 
-Subclass ``db.Model`` to define a model class. The ``db`` object makes the names in
-``sqlalchemy`` and ``sqlalchemy.orm`` available for convenience, such as ``db.Column``.
+Subclass ``db.Model`` to define a model class.
 The model will generate a table name by converting the ``CamelCase`` class name to
 ``snake_case``.
 
-This example uses the SQLAlchemy 1.x style of defining models:
-
-.. 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)
-
-The table name ``"user"`` will automatically be assigned to the model's table.
-
-It's also possible to use the SQLAlchemy 2.x style of defining models,
-as long as you initialized the extension with an appropriate 2.x model base class
-as described in :ref:`sqlalchemy2-initialization`.
-
 .. code-block:: python
 
+    from sqlalchemy import Integer, String
     from sqlalchemy.orm import Mapped, mapped_column
 
     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)
-        email: Mapped[str] = mapped_column(db.String)
+        id: Mapped[int] = mapped_column(Integer, primary_key=True)
+        username: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+        email: Mapped[str] = mapped_column(String)
 
 
 See :doc:`models` for more information about defining and creating models and tables.