A wide array of documentation both official and non-official exists for SQLAlchemy. The following is a guide to the some of the best information available.

Reference Documentation

The SQLAlchemy Reference Documentation is by far the most important place for both the newest user and the veteran alchemist. The Reference Documentation represents an ongoing effort that rivals that of the SQLAlchemy project itself, and is constantly evolving to be ever more complete and navigable. The newest versions of the documentation will be the most up-to-date and accurate; features and behaviors that were only introduced in more recent versions should always be noted.

Architectural Documentation

A SQLAlchemy chapter was written for the book The Architecture of Open Source Applications in 2011. This chapter includes an in-depth introduction to the key concepts behind both the Core and ORM components of SQLAlchemy:

Citing SQLAlchemy

Please cite SQLalchemy if you use it in your research. You can cite the chapter from SQLAlchemy at Architecture of Open Source Applications as introduced in the previous section:

  • Michael Bayer. SQLAlchemy. In Amy Brown and Greg Wilson, editors, The Architecture of Open Source Applications Volume II: Structure, Scale, and a Few More Fearless Hacks 2012
Here is an example BibTeX entry:
  place={Mountain View},
  booktitle={The Architecture of Open Source Applications Volume II: Structure, Scale, and a Few More Fearless Hacks},
  author={Bayer, Michael},
  editor={Brown, Amy and Wilson, Greg},

Blog Posts


A wide variety of talks both by SQLAlchemy creators and users have been presented at many conferences worldwide. Here's only a choice few of them:

  • Building the App - presented at Pycon North America, 2014

    Author: Mike Bayer

    In this talk we'll illustrate a simple web application using SQLAlchemy, showing off the style of development that SQLAlchemy is most geared towards, the so-called "foundational" style which provides for development and maintainance of custom conventions which then service the needs of the model declarations and use case implementations.

  • SQLAlchemy and data access in Python - Recorded April 9, 2015

    Author: Michael Kennedy and Mike Bayer

    An interview with Mike Bayer in the Talk Python to me Podcast series. Discusses the history of the project and how it has evolved over time.

  • Introduction to SQLAlchemy Core - presented at Pycon North America, 2014

    Author: Jason Meyers

    This talk provides a broad-based introduction to SQLAlchemy Core library. It is focused on someone new to SQLAlchemy Core, who has experience with other database technologies such as Django or SQLAlchemy ORM. We'll cover the differences between the domain-centric models of those tools compared to the schema-centric model and how we can use that to deal with common and unusual data sources.

  • Sane Schema Migrations with Alembic and SQLAlchemy - presented at Pycon North America, 2014

    Author: Selena Deckelmann

    Working with developers on schema migrations is a perennial challenge for DBAs and developers. Devs tend to like a "set it and forget it" tool. This talk discusses the strategies used to move from a pure SQL and shell migration system to using SQLAlchemy and Alembic for maximum DBA and developer happiness.

  • Flexing SQLAlchemy's Relational Power - presented at Pycon US, 2012

    Author: Brandon Rhodes

    Too often, programmers use ORMs to hide from their database and avoid learning how it works. Instead, I encourage programmers to learn a bit of SQL and become familiar with the problems that database queries are designed to solve well. In this talk, I outline the basics of using SQLAlchemy to craft efficient queries and avoid several common database query anti-patterns.

  • The SQLAlchemy Session - In Depth - presented at Pycon Canada, 2012

    Author: Mike Bayer

    A detailed walkthrough of SQLAlchemy's Session, describing the rationale for its existence, its driving philosophies, and finally a walkthrough of Session lifecycle through the use of an animated diagram. We'll cover how the relational database refers to database rows within a transaction, and how the Session has over the years developed a tight, proxied integration with this lifecycle.

  • Hand Coded Applications with SQLAlchemy - presented at Pycon US, 2012

    Author: Mike Bayer

    This talk describes why SQLAlchemy has always been called a "toolkit", detailing the software construction mindset for which SQLAlchemy was designed to be used with. The talk refers to this as the "Hand Coded" approach, and has an emphasis on user-created patterns and conventions, along with explicit exposure of relational structures. This talk describes how SQLAlchemy abides by what has been described as the complimentarity principle of automation (not to be confused with the more common physics term), allowing the library's work to be exposed as a series of transparent automation tools, rather than as an opaque wall hiding the details.

  • SQLAlchemy - an Architectural Retrospective - presented at PyGotham 2011

    Author: Mike Bayer

    This talk walks through some highlights of SQLAlchemy internal design and methodology, based on the (now published) chapter for the "Architecture of Open Source Applications" book. We'll have a little bit of SQLAlchemy philosophy, an overview of the Core, and then a 500-ft view of how the ORM goes about things, with plenty of cool looking diagrams.


The most up-to-date and complete tutorials available for getting started with SQLAlchemy are: * the SQLAlchemy 1.4/2.0 Tutorial which is a full rewrite of the classic "1.x" SQLAlchemy tutorials; users starting with the latest SQLAlchemy releases should start here. * the Core and ORM tutorials are recommended for those using "1.x style" codebases. A few other online resources include:

  • SQLAlchemy 2.0 - The One-Point-Four-Ening 2021 - Python Web Conf 2021

    Author: Mike Bayer

    This is the newest version of the "getting started" tutorial that presents SQLAlchemy from the perspective of the new 2.0 series.

  • Introduction to SQLAlchemy - presented at many Pycon and other conferences

    Author: Mike Bayer

    This tutorial is the more "classic" tutorial that presents a fast paced but beginner-focused tutorial on what SQLAlchemy is all about. While the tutorial has evolved over the years and at this point is fairly fixed; see the newer "2.0" tutorial for a the latest version that is changed a bit more substantially.

  • Python SQLAlchemy Tutorial - on the Python Central website

    Author: Xiaonuo Gantan

    A series of beginner-focused SQLAlchemy tutorials covering a wide range of basic topics. While a lot of the information here is derived from the main documentation, the pace is slower and there are also details culled from other sources, including performance tips, comparison to other ORMs, and design philosophies. A very good effort by author Xiaonuo Gantan.

  • SQLAlchemy Tutorial - on the Zetcode tutorial website

    Author: Jan Bodnar

    This is a "nutshell" style tutorial that quickly introduces the major areas of SQLAlchemy using simple examples, covering raw SQL, schema concepts, SQL Expression language, and the ORM including querying and relationships.

  • SQLAlchemy + URL Dispatch Wiki Tutorial - Part of the Pylons Documentation

    Author: Chris McDonough

    This is the official tutorial for SQLAlchemy integration within the Pyramid Web Framework. The basic steps to integrate SQLAlchemy within a traditional web application are laid out here and are mostly in conformance with those guidelines referenced by SQLAlchemy's documentation.


SQLAlchemy is a recipe-focused library; while it includes a tremendous number of features, overall the emphasis is on that of creating a composable toolkit, so that users can build their own database interaction layers that suit them best. To help with this task, there's a huge number of "recipes", code examples geared towards specific use cases. These are currently split out among the SQLAlchemy reference documentation and the wiki: