summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMike Bayer <mike_mp@zzzcomputing.com>2021-11-21 12:58:11 -0500
committerMike Bayer <mike_mp@zzzcomputing.com>2021-11-21 12:58:11 -0500
commite04baa2953fb5d0d29f5dca01ea6882bf1fa1cd4 (patch)
treeb70a6ea753e2dd5511d3ebffade031d1dd8ed861
parent3085f28be58bf4e4a0318b932f1422c49e1af2f1 (diff)
downloadsqlalchemy-e04baa2953fb5d0d29f5dca01ea6882bf1fa1cd4.tar.gz
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
-rw-r--r--doc/build/changelog/index.rst9
-rw-r--r--doc/build/changelog/migration_20.rst65
2 files changed, 63 insertions, 11 deletions
diff --git a/doc/build/changelog/index.rst b/doc/build/changelog/index.rst
index 101585f15..2efd618dc 100644
--- a/doc/build/changelog/index.rst
+++ b/doc/build/changelog/index.rst
@@ -14,14 +14,6 @@ Current Migration Guide
migration_20
-SQLAlchemy 2.0 Overview and Status
-----------------------------------
-
-.. toctree::
- :titlesonly:
-
- migration_20
-
Change logs
-----------
@@ -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 afca522df..b75cefb31 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 <change_5159>`
+* :ref:`SQL caching throughout Core and ORM <change_4639>`
+* :ref:`New Declarative features, ORM integration <change_5508>`
+* :ref:`New Result object <change_result_14_core>`
+* :ref:`select() / case() Accept Positional Expressions <change_5284>`
+* :ref:`asyncio support for Core and ORM <change_3414>`
+
+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 <deprecation_20_mode>` are
+now finalized; in particular, major APIs that are **no longer present**
+include:
+
+* :ref:`Bound MetaData and connectionless execution <migration_20_implicit_execution>`
+* :ref:`Emulated autocommit on Connection <migration_20_autocommit>`
+* :ref:`The Session.autocommit parameter / mode <migration_20_session_autocommit>`
+* :ref:`List / keyword arguments to select() <migration_20_5284>`
+* 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
-------------------------------------------------------------