About this document

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 2.0 style of working, the ORM uses Core-style querying with the select() construct, and transactional semantics between Core connections and ORM sessions are equivalent. Take note of the blue border styles for each section, that will tell you how “ORM-ish” a particular topic is!

Users who are already familiar with SQLAlchemy, and especially those looking to migrate existing applications to work under the SQLAlchemy 2.0 series within the 1.4 transitional phase should check out the SQLAlchemy 2.0 - Major Migration Guide document as well.

For the newcomer, this document has a lot of detail, however by the end they will be considered an Alchemist.

SQLAlchemy Core is the foundational architecture for SQLAlchemy as a “database toolkit”. The library provides tools for managing connectivity to a database, interacting with database queries and results, and programmatic construction of SQL statements.

Sections that are primarily Core-only will not refer to the ORM. SQLAlchemy constructs used in these sections will be imported from the sqlalchemy namespace. As an additional indicator of subject classification, they will also include a dark blue border on the right. When using the ORM, these concepts are still in play but are less often explicit in user code. ORM users should read these sections, but not expect to be using these APIs directly for ORM-centric code.

SQLAlchemy ORM builds upon the Core to provide optional object relational mapping capabilities. The ORM provides an additional configuration layer allowing user-defined Python classes to be mapped to database tables and other constructs, as well as an object persistence mechanism known as the Session. It then extends the Core-level SQL Expression Language to allow SQL queries to be composed and invoked in terms of user-defined objects.

Sections that are primarily ORM-only should be titled to include the phrase “ORM”, so that it’s clear this is an ORM related topic. SQLAlchemy constructs used in these sections will be imported from the sqlalchemy.orm namespace. Finally, as an additional indicator of subject classification, they will also include a light blue border on the left. Core-only users can skip these.

Most sections in this tutorial discuss Core concepts that are also used explicitly with the ORM. SQLAlchemy 2.0 in particular features a much greater level of integration of Core API use within the ORM.

For each of these sections, there will be introductory text discussing the degree to which ORM users should expect to be using these programming patterns. SQLAlchemy constructs in these sections will be imported from the sqlalchemy namespace with some potential use of sqlalchemy.orm constructs at the same time. As an additional indicator of subject classification, these sections will also include both a thinner light border on the left, and a thicker dark border on the right. Core and ORM users should familiarize with concepts in these sections equally.