Our example above illustrated the execution of a textual SQL string, which
should be invoked by using the :func:`_expression.text` construct to indicate that
we'd like to use textual SQL. The :meth:`_engine.Connection.execute` method can of
-course accommodate more than that, including the variety of SQL expression
-constructs described in :ref:`sqlexpression_toplevel`.
+course accommodate more than that; see :ref:`tutorial_working_with_data`
+in the :ref:`unified_tutorial` for a tutorial.
Using Transactions
.. module:: sqlalchemy.sql.expression
-This section presents the API reference for the SQL Expression Language. For a full introduction to its usage,
-see :ref:`sqlexpression_toplevel`.
+This section presents the API reference for the SQL Expression Language.
+For an introduction, start with :ref:`tutorial_working_with_data`
+in the :ref:`unified_tutorial`.
.. toctree::
-.. _core_future_toplevel:
+:orphan:
SQLAlchemy 2.0 Future (Core)
============================
-This package includes a relatively small number of transitional elements
-to allow "2.0 mode" to take place within SQLAlchemy 1.4.
+.. admonition:: We're 2.0!
-In the 2.0 release of SQLAlchemy, the objects published here are the same
-:class:`_engine.Engine`, :class:`_engine.Connection` and
-:func:`_sa.create_engine` classes and functions that are
-used by default. The package is here for backwards compatibility with
-SQLAlchemy 1.4.
+ This page described the "future" mode provided in SQLAlchemy 1.4
+ for the purposes of 1.4 -> 2.0 transition. For 2.0, the "future"
+ parameter on :func:`_sa.create_engine` and :class:`_orm.Session`
+ continues to remain available for backwards-compatibility support, however
+ if specified must be left at the value of ``True``.
-The ``sqlalchemy.future`` package will be deprecated in a subsequent
-2.x release and eventually removed.
-
-.. seealso::
-
- :ref:`migration_20_toplevel` - Introduction to the 2.0 series of SQLAlchemy
+ .. seealso::
+ :ref:`migration_20_toplevel` - Introduction to the 2.0 series of SQLAlchemy
types
engines_connections
api_basics
- future
-.. toctree::
- :hidden:
-
- tutorial
-Selectables, Tables, FROM objects
+SELECT and Related Constructs
=================================
-The term "selectable" refers to any object that rows can be selected from;
-in SQLAlchemy, these objects descend from :class:`_expression.FromClause` and their
-distinguishing feature is their :attr:`_expression.FromClause.c` attribute, which is
-a namespace of all the columns contained within the FROM clause (these
-elements are themselves :class:`_expression.ColumnElement` subclasses).
+The term "selectable" refers to any object that represents database rows. In
+SQLAlchemy, these objects descend from :class:`_expression.Selectable`, the
+most prominent being :class:`_expression.Select`, which represents a SQL SELECT
+statement. A subset of :class:`_expression.Selectable` is
+:class:`_expression.FromClause`, which represents objects that can be within
+the FROM clause of a :class:`.Select` statement. A distinguishing feature of
+:class:`_expression.FromClause` is the :attr:`_expression.FromClause.c`
+attribute, which is a namespace of all the columns contained within the FROM
+clause (these elements are themselves :class:`_expression.ColumnElement`
+subclasses).
.. currentmodule:: sqlalchemy.sql.expression
-.. _sqlexpression_toplevel:
+:orphan:
=================================
SQL Expression Language Tutorial
The :class:`_query.Query` object, when asked to return a list of ORM-mapped objects,
will **deduplicate the objects based on primary key**. That is, if we
-for example use the ``User`` mapping described at :ref:`ormtutorial_toplevel`,
+for example use the ``User`` mapping described at :ref:`tutorial_orm_table_metadata`,
and we had a SQL query like the following::
q = session.query(User).outerjoin(User.addresses).filter(User.name == "jack")
throughout the 1.x series of SQLAlchemy and earlier (e.g. 1.3, 1.2, etc)
and the term "2.0 style" refers to the way an API will look in version
2.0. Version 1.4 implements nearly all of 2.0's API in so-called
- "transition mode".
+ "transition mode", while version 2.0 still maintains the legacy
+ :class:`_orm.Query` object to allow legacy code to remain largely
+ 2.0 compatible.
.. seealso::
.. container::
- The SQLAlchemy 2.0 series represents a major rework of the classic 1.x
- SQLAlchemy APIs that have evolved over more than 15 years. The new tutorial
- is recommended for all new users as well as veterans of older SQLAlchemy
- versions alike.
+ New users of SQLAlchemy, as well as veterans of older SQLAlchemy
+ release series, should start with the
+ :doc:`/tutorial/index`, which covers everything an Alchemist needs
+ to know when using the ORM or just Core.
* **For a quick glance:** :doc:`/orm/quickstart` - a glimpse at what working with the ORM looks like
- * **For all users:** :doc:`/tutorial/index` - SQLAlchemy 2.0's main tutorial, for complete learning
+ * **For all users:** :doc:`/tutorial/index` - In depth tutorial for Core and ORM
.. container:: left_right_container
.. container::
+ Users coming from older versions of SQLAlchemy, especially those transitioning
+ from the 1.x style of working, will want to review this documentation.
+
* :doc:`Migrating to SQLAlchemy 2.0 <changelog/migration_20>` - Complete background on migrating from 1.3 or 1.4 to 2.0
* :doc:`What's New in SQLAlchemy 2.0? <changelog/whatsnew_20>` - New 2.0 features and behaviors beyond the 1.x migration
* :doc:`Changelog catalog <changelog/index>` - Detailed changelogs for all SQLAlchemy Versions
.. rst-class:: h2
- Reference Documentation
+ Reference and How To
.. container:: orm
- **SQLAlchemy ORM**
+ **SQLAlchemy ORM** - Detailed guides and API reference for using the ORM
- * **ORM Configuration:**
- :doc:`Mapped Class Configuration <orm/mapper_config>` |
+ * **Mapping Classes:**
+ :doc:`Mapping Python Classes <orm/mapper_config>` |
:doc:`Relationship Configuration <orm/relationships>`
- * **ORM Usage:**
- :doc:`Session Usage and Guidelines <orm/session>` |
- :doc:`Querying Guide <orm/queryguide/index>` |
- :doc:`AsyncIO Support <orm/extensions/asyncio>`
+ * **Using the ORM:**
+ :doc:`Using the ORM Session <orm/session>` |
+ :doc:`ORM Querying Guide <orm/queryguide/index>` |
+ :doc:`Using AsyncIO <orm/extensions/asyncio>`
* **Configuration Extensions:**
- :doc:`Mypy integration <orm/extensions/mypy>` |
:doc:`Association Proxy <orm/extensions/associationproxy>` |
:doc:`Hybrid Attributes <orm/extensions/hybrid>` |
- :doc:`Automap <orm/extensions/automap>` |
:doc:`Mutable Scalars <orm/extensions/mutable>` |
+ :doc:`Automap <orm/extensions/automap>` |
:doc:`All extensions <orm/extensions/index>`
* **Extending the ORM:**
.. container:: core
- **SQLAlchemy Core**
+ **SQLAlchemy Core** - Detailed guides and API reference for working with Core
* **Engines, Connections, Pools:**
:doc:`Engine Configuration <core/engines>` |
:ref:`Constraints and Indexes <metadata_constraints_toplevel>` |
:ref:`Using Data Definition Language (DDL) <metadata_ddl_toplevel>`
- * **SQL Reference:**
- :doc:`SQL Expression API docs <core/expression_api>`
+ * **SQL Statements:**
+ :doc:`SQL Expression Elements <core/sqlelement>` |
+ :doc:`Operator Reference <core/operators>` |
+ :doc:`SELECT and related constructs <core/selectable>` |
+ :doc:`INSERT, UPDATE, DELETE <core/dml>` |
+ :doc:`SQL Functions <core/functions>` |
+ :doc:`Table of Contents <core/expression_api>`
+
+
* **Datatypes:**
:ref:`Overview <types_toplevel>` |
:ref:`Building Custom Types <types_custom>` |
- :ref:`API <types_api>`
+ :ref:`Type API Reference <types_api>`
* **Core Basics:**
:doc:`Overview <core/api_basics>` |
* :ref:`unified_tutorial` - this all-new tutorial for the 1.4/2.0 series of
SQLAlchemy introduces the entire library holistically, starting from a
description of Core and working more and more towards ORM-specific concepts.
- New users, as well as users coming from :term:`1.x style`, who wish to work
- in :term:`2.0 style` should start here.
+ New users, as well as users coming from the 1.x series of
+ SQLAlchemy, should start here.
* :ref:`orm_toplevel` - In this section, reference documentation for the ORM is
- presented; this section also includes the now-legacy
- :ref:`ormtutorial_toplevel`.
+ presented.
* :ref:`core_toplevel` - Here, reference documentation for
- everything else within Core is presented; section also includes the legacy
- :ref:`sqlexpression_toplevel`. SQLAlchemy engine, connection, and pooling
- services are also described here.
+ everything else within Core is presented. SQLAlchemy engine, connection, and
+ pooling services are also described here.
* :ref:`dialect_toplevel` - Provides reference documentation
for all :term:`dialect` implementations, including :term:`DBAPI` specifics.
Install via pip
---------------
-.. warning:: This section **does not apply until SQLAlchemy 2.0 is actually
- released**, which as of January 26, 2022 the library is **not released yet**.
- In the interim, these instructions **will not function** and will install
- the latest 1.4 release.
-
When ``pip`` is available, the distribution can be
downloaded from PyPI and installed in one step:
extensions/index
examples
-.. toctree::
- :hidden:
-
- tutorial
==========================
This section describes the :func:`relationship` function and in depth discussion
-of its usage. For an introduction to relationships, start with the
-:ref:`ormtutorial_toplevel` and head into :ref:`tutorial_orm_related_objects`.
+of its usage. For an introduction to relationships, start with
+:ref:`tutorial_orm_related_objects` in the :ref:`unified_tutorial`.
.. toctree::
:maxdepth: 3
The reason the :class:`_engine.Connection` is passed is that it is encouraged that
**simple SQL operations take place here**, directly on the :class:`_engine.Connection`,
such as incrementing counters or inserting extra rows within log tables.
-When dealing with the :class:`_engine.Connection`, it is expected that Core-level
-SQL operations will be used; e.g. those described in :ref:`sqlexpression_toplevel`.
There are also many per-object operations that don't need to be handled
within a flush event at all. The most common alternative is to simply
-.. _ormtutorial_toplevel:
+:orphan:
==========================
Object Relational Tutorial
-.. |tutorial_title| replace:: SQLAlchemy 2.0 Tutorial
+.. |tutorial_title| replace:: SQLAlchemy Unified Tutorial
.. |next| replace:: :doc:`engine`
.. footer_topic:: |tutorial_title|
.. rst-class:: orm_core
-========================
-SQLAlchemy 2.0 Tutorial
-========================
+============================
+SQLAlchemy Unified Tutorial
+============================
.. admonition:: About this document
- The SQLAlchemy Tutorial for version 2.0, first published as a preview
- within the 1.4 documentation, is integrated between the Core and ORM
+ The SQLAlchemy Unified Tutorial is integrated between the Core and ORM
components of SQLAlchemy and serves as a unified introduction to SQLAlchemy
as a whole. For users of SQLAlchemy within the 1.x series, in the
:term:`2.0 style` of working, the ORM uses Core-style querying with the
topic is!
Users who are already familiar with SQLAlchemy, and especially those
- looking to migrate existing applications to work under SQLAlchemy 2.0
- within the 1.4 transitional phase should check out the
+ looking to migrate existing applications to work under the SQLAlchemy 2.0
+ series within the 1.4 transitional phase should check out the
:ref:`migration_20_toplevel` document as well.
For the newcomer, this document has a **lot** of detail, however by the
"""Serializer/Deserializer objects for usage with SQLAlchemy query structures,
allowing "contextual" deserialization.
+.. legacy::
+
+ The serializer extension is **legacy** and should not be used for
+ new development.
+
Any SQLAlchemy query structure, either based on sqlalchemy.sql.*
or sqlalchemy.orm.* can be used. The mappers, Tables, Columns, Session
etc. which are referenced by the structure are not persisted in serialized
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
