SQLAlchemy 1.4 / 2.0 Tutorial¶
About this document
The new SQLAlchemy Tutorial is now integrated between Core and ORM and
serves as a unified introduction to SQLAlchemy as a whole. In the new
2.0 style of working, fully available in the 1.4 release, the ORM now 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 SQLAlchemy 2.0 within the 1.4 transitional phase should check out the Migrating to SQLAlchemy 2.0 document as well.
For the newcomer, this document has a lot of detail, however by the end they will be considered an Alchemist.
SQLAlchemy is presented as two distinct APIs, one building on top of the other. These APIs are known as Core and ORM.
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.
Tutorial Overview¶
The tutorial will present both concepts in the natural order that they should be learned, first with a mostly-Core-centric approach and then spanning out into more ORM-centric concepts.
The major sections of this tutorial are as follows:
Establishing Connectivity - the Engine - all SQLAlchemy applications start with an
Engineobject; here’s how to create one.Working with Transactions and the DBAPI - the usage API of the
Engineand its related objectsConnectionandResultare presented here. This content is Core-centric however ORM users will want to be familiar with at least theResultobject.Working with Database Metadata - SQLAlchemy’s SQL abstractions as well as the ORM rely upon a system of defining database schema constructs as Python objects. This section introduces how to do that from both a Core and an ORM perspective.
Working with Data - here we learn how to create, select, update and delete data in the database. The so-called CRUD operations here are given in terms of SQLAlchemy Core with links out towards their ORM counterparts. The SELECT operation that is introduced in detail at Selecting Rows with Core or ORM applies equally well to Core and ORM.
Data Manipulation with the ORM covers the persistence framework of the ORM; basically the ORM-centric ways to insert, update and delete, as well as how to handle transactions.
Working with ORM Related Objects introduces the concept of the
relationship()construct and provides a brief overview of how it’s used, with links to deeper documentation.Further Reading lists a series of major top-level documentation sections which fully document the concepts introduced in this tutorial.
Version Check¶
This tutorial is written using a system called doctest. All of the code excerpts
written with a >>> are actually run as part of SQLAlchemy’s test suite, and
the reader is invited to work with the code examples given in real time with
their own Python interpreter.
If running the examples, it is advised that the reader performs a quick check to verify that we are on version 1.4 of SQLAlchemy:
>>> import sqlalchemy
>>> sqlalchemy.__version__
1.4.0A Note on the Future¶
This tutorial describes a new API that’s released in SQLAlchemy 1.4 known as 2.0 style. The purpose of the 2.0-style API is to provide forwards compatibility with SQLAlchemy 2.0, which is planned as the next generation of SQLAlchemy.
In order to provide the full 2.0 API, a new flag called future will be
used, which will be seen as the tutorial describes the Engine
and Session objects. These flags fully enable 2.0-compatibility
mode and allow the code in the tutorial to proceed fully. When using the
future flag with the create_engine() function, the object
returned is a subclass of sqlalchemy.engine.Engine described as
sqlalchemy.future.Engine. This tutorial will be referring to
sqlalchemy.future.Engine.