From: Mike Bayer Date: Sun, 21 Nov 2021 17:58:11 +0000 (-0500) Subject: provide space for new 2.0 changes not part of upgrade path X-Git-Tag: rel_2_0_0b1~640 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e04baa2953fb5d0d29f5dca01ea6882bf1fa1cd4;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git provide space for new 2.0 changes not part of upgrade path As we are going to be adding new improvements such as variant, cython, psycopg3, more RETURNING support, fast execution helpers, and probably a lot more, the 2.0 migration doc needs to also still have the "what's new in 2.0?" thing going on as well. Organize the document so it has space to introduce these sections, as well as the existing 1.4->2.0 migration sections. If the "What's New" document gets large, we will break up this page into two separate pages, it's already quite large, so the proposal would be the exising migration doc becomes a separate special migration document. Change-Id: I62496b30229806f4a82d1f92b3f4eda53e64df57 --- diff --git a/doc/build/changelog/index.rst b/doc/build/changelog/index.rst index 101585f158..2efd618dc8 100644 --- a/doc/build/changelog/index.rst +++ b/doc/build/changelog/index.rst @@ -9,14 +9,6 @@ within the main documentation. Current Migration Guide ----------------------- -.. toctree:: - :titlesonly: - - migration_20 - -SQLAlchemy 2.0 Overview and Status ----------------------------------- - .. toctree:: :titlesonly: @@ -51,6 +43,7 @@ Older Migration Guides .. toctree:: :titlesonly: + migration_14 migration_13 migration_12 migration_11 diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index afca522df3..b75cefb31e 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -1,11 +1,14 @@ .. _migration_20_toplevel: ============================= -Migrating to SQLAlchemy 2.0 +What's New in SQLAlchemy 2.0? ============================= .. admonition:: About this document + This document describes changes between SQLAlchemy version 1.4 + and SQLAlchemy version 2.0. + SQLAlchemy 2.0 presents a major shift for a wide variety of key SQLAlchemy usage patterns in both the Core and ORM components. The goal of this release is to make a slight readjustment in some of the most @@ -28,9 +31,64 @@ Migrating to SQLAlchemy 2.0 :class:`.orm.query.Query` and Declarative. It also hopes standardize some newer capabilities that have proven to be very effective. +The 1.4->2.0 Migration Path +=========================== + +The most prominent architectural features and API changes that are considered +to be "SQLAlchemy 2.0" were in fact released as fully available within the 1.4 +series, to provide for a clean upgrade path from the 1.x to the 2.x series +as well as to serve as a beta platform for the features themselves. These +changes include: + +* :ref:`New ORM statement paradigm ` +* :ref:`SQL caching throughout Core and ORM ` +* :ref:`New Declarative features, ORM integration ` +* :ref:`New Result object ` +* :ref:`select() / case() Accept Positional Expressions ` +* :ref:`asyncio support for Core and ORM ` + +The above bullets link to the description of these new paradigms as introduced +in SQLAlchemy 1.4. in the :ref:`migration_14_toplevel` document. + +For SQLAlchemy 2.0, all API features and behaviors +that were marked as :ref:`deprecated for 2.0 ` are +now finalized; in particular, major APIs that are **no longer present** +include: + +* :ref:`Bound MetaData and connectionless execution ` +* :ref:`Emulated autocommit on Connection ` +* :ref:`The Session.autocommit parameter / mode ` +* :ref:`List / keyword arguments to select() ` +* Python 2 support + +The above bullets refer to the most prominent fully backwards-incompatible +changes that are finalized in the 2.0 release. The migration path for +applications to accommodate for these changes as well as others is framed as +a transition path first into the 1.4 series of SQLAlchemy where the "future" +APIs are available to provide for the "2.0" way of working, and then to the +2.0 series where the no-longer-used APIs above and others are removed. + +The complete steps for this migration path are later in this document at +:ref:`migration_20_overview`. + +New Features and Improvements +============================= + +This section covers new features and improvements in SQLAlchemy 2.0 which +are not otherwise part of the major 1.4->2.0 migration path. + +Behavioral Changes +================== -Overview -======== +This section covers behavioral changes made in SQLAlchemy 2.0 which are +not otherwise part of the major 1.4->2.0 migration path; changes here are +not expected to have significant effects on backwards compatibility. + + +.. _migration_20_overview: + +1.x -> 2.x Migration Overview +============================= The SQLAlchemy 2.0 transition presents itself in the SQLAlchemy 1.4 release as a series of steps that allow an application of any size or complexity to be @@ -1966,6 +2024,7 @@ the :func:`_orm.selectinload` strategy presents a collection-oriented eager loader that is superior in most respects to :func:`_orm.joinedload` and should be preferred. +.. _migration_20_session_autocommit: Autocommit mode removed from Session; autobegin support added -------------------------------------------------------------