# SQLAlchemy 2.0 Documentation and more

# SQLAlchemy 2.0 Documentation

# SQLAlchemy Documentation

Getting Started

New to SQLAlchemy?   Start here:

- **For Python Beginners:** [Installation Guide](https://docs.sqlalchemy.org/en/20/intro.html#installation) - basic guidance on installing with pip and similar
- **For Python Veterans:** [SQLAlchemy Overview](https://docs.sqlalchemy.org/en/20/intro.html) - brief architectural overview

Tutorials

New users of SQLAlchemy, as well as veterans of older SQLAlchemy
release series, should start with the
[SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html), which covers everything an Alchemist needs
to know when using the ORM or just Core.

- **For a quick glance:** [ORM Quick Start](https://docs.sqlalchemy.org/en/20/orm/quickstart.html) - a glimpse at what working with the ORM looks like
- **For all users:** [SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html) - In depth tutorial for Core and ORM

Migration Notes

Users coming from older versions of SQLAlchemy, especially those transitioning
from the 1.x style of working, will want to review this documentation.

- [Migrating to SQLAlchemy 2.0](https://docs.sqlalchemy.org/en/20/changelog/migration_20.html) - Complete background on migrating from 1.3 or 1.4 to 2.0
- [What’s New in SQLAlchemy 2.0?](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html) - New 2.0 features and behaviors beyond the 1.x migration
- [Changelog catalog](https://docs.sqlalchemy.org/en/20/changelog/index.html) - Detailed changelogs for all SQLAlchemy Versions

Reference and How To

**SQLAlchemy ORM** - Detailed guides and API reference for using the ORM

- **Mapping Classes:** [Mapping Python Classes](https://docs.sqlalchemy.org/en/20/orm/mapper_config.html) |
  [Relationship Configuration](https://docs.sqlalchemy.org/en/20/orm/relationships.html)
- **Using the ORM:** [Using the ORM Session](https://docs.sqlalchemy.org/en/20/orm/session.html) |
  [ORM Querying Guide](https://docs.sqlalchemy.org/en/20/orm/queryguide/index.html) |
  [Using AsyncIO](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
- **Configuration Extensions:** [Association Proxy](https://docs.sqlalchemy.org/en/20/orm/extensions/associationproxy.html) |
  [Hybrid Attributes](https://docs.sqlalchemy.org/en/20/orm/extensions/hybrid.html) |
  [Mutable Scalars](https://docs.sqlalchemy.org/en/20/orm/extensions/mutable.html) |
  [Automap](https://docs.sqlalchemy.org/en/20/orm/extensions/automap.html) |
  [All extensions](https://docs.sqlalchemy.org/en/20/orm/extensions/index.html)
- **Extending the ORM:** [ORM Events and Internals](https://docs.sqlalchemy.org/en/20/orm/extending.html)
- **Other:** [Introduction to Examples](https://docs.sqlalchemy.org/en/20/orm/examples.html)

**SQLAlchemy Core** - Detailed guides and API reference for working with Core

- **Engines, Connections, Pools:** [Engine Configuration](https://docs.sqlalchemy.org/en/20/core/engines.html) |
  [Connections, Transactions, Results](https://docs.sqlalchemy.org/en/20/core/connections.html) |
  [AsyncIO Support](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html) |
  [Connection Pooling](https://docs.sqlalchemy.org/en/20/core/pooling.html)
- **Schema Definition:** [Overview](https://docs.sqlalchemy.org/en/20/core/schema.html) |
  [Tables and Columns](https://docs.sqlalchemy.org/en/20/core/metadata.html) |
  [Database Introspection (Reflection)](https://docs.sqlalchemy.org/en/20/core/reflection.html) |
  [Insert/Update Defaults](https://docs.sqlalchemy.org/en/20/core/defaults.html) |
  [Constraints and Indexes](https://docs.sqlalchemy.org/en/20/core/constraints.html) |
  [Using Data Definition Language (DDL)](https://docs.sqlalchemy.org/en/20/core/ddl.html)
- **SQL Statements:** [SQL Expression Elements](https://docs.sqlalchemy.org/en/20/core/sqlelement.html) |
  [Operator Reference](https://docs.sqlalchemy.org/en/20/core/operators.html) |
  [SELECT and related constructs](https://docs.sqlalchemy.org/en/20/core/selectable.html) |
  [INSERT, UPDATE, DELETE](https://docs.sqlalchemy.org/en/20/core/dml.html) |
  [SQL Functions](https://docs.sqlalchemy.org/en/20/core/functions.html) |
  [Table of Contents](https://docs.sqlalchemy.org/en/20/core/expression_api.html)
- **Datatypes:** [Overview](https://docs.sqlalchemy.org/en/20/core/types.html) |
  [Building Custom Types](https://docs.sqlalchemy.org/en/20/core/custom_types.html#types-custom) |
  [Type API Reference](https://docs.sqlalchemy.org/en/20/core/type_api.html#types-api)
- **Core Basics:** [Overview](https://docs.sqlalchemy.org/en/20/core/api_basics.html) |
  [Runtime Inspection API](https://docs.sqlalchemy.org/en/20/core/inspection.html) |
  [Event System](https://docs.sqlalchemy.org/en/20/core/event.html) |
  [Core Event Interfaces](https://docs.sqlalchemy.org/en/20/core/events.html) |
  [Creating Custom SQL Constructs](https://docs.sqlalchemy.org/en/20/core/compiler.html)

Dialect Documentation

The **dialect** is the system SQLAlchemy uses to communicate with various types of DBAPIs and databases.
This section describes notes, options, and usage patterns regarding individual dialects.

[PostgreSQL](https://docs.sqlalchemy.org/en/20/dialects/postgresql.html) |
[MySQL and MariaDB](https://docs.sqlalchemy.org/en/20/dialects/mysql.html) |
[SQLite](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html) |
[Oracle Database](https://docs.sqlalchemy.org/en/20/dialects/oracle.html) |
[Microsoft SQL Server](https://docs.sqlalchemy.org/en/20/dialects/mssql.html)

[More Dialects …](https://docs.sqlalchemy.org/en/20/dialects/index.html)

Supplementary

- [Frequently Asked Questions](https://docs.sqlalchemy.org/en/20/faq/index.html) - A collection of common
  problems and solutions
- [Glossary](https://docs.sqlalchemy.org/en/20/glossary.html) - Definitions of terms used in SQLAlchemy
  documentation
- [Error Message Guide](https://docs.sqlalchemy.org/en/20/errors.html) - Explanations of many SQLAlchemy
  errors
- [Complete table of of contents](https://docs.sqlalchemy.org/en/20/contents.html) - Full list of available
  documentation
- [Index](https://docs.sqlalchemy.org/en/20/genindex.html) - Index for easy lookup of documentation topics

---

# SQLAlchemy 2.0 Documentation

# SQLAlchemy Documentation

Getting Started

New to SQLAlchemy?   Start here:

- **For Python Beginners:** [Installation Guide](https://docs.sqlalchemy.org/en/20/intro.html#installation) - basic guidance on installing with pip and similar
- **For Python Veterans:** [SQLAlchemy Overview](https://docs.sqlalchemy.org/en/20/intro.html) - brief architectural overview

Tutorials

New users of SQLAlchemy, as well as veterans of older SQLAlchemy
release series, should start with the
[SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html), which covers everything an Alchemist needs
to know when using the ORM or just Core.

- **For a quick glance:** [ORM Quick Start](https://docs.sqlalchemy.org/en/20/orm/quickstart.html) - a glimpse at what working with the ORM looks like
- **For all users:** [SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html) - In depth tutorial for Core and ORM

Migration Notes

Users coming from older versions of SQLAlchemy, especially those transitioning
from the 1.x style of working, will want to review this documentation.

- [Migrating to SQLAlchemy 2.0](https://docs.sqlalchemy.org/en/20/changelog/migration_20.html) - Complete background on migrating from 1.3 or 1.4 to 2.0
- [What’s New in SQLAlchemy 2.0?](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html) - New 2.0 features and behaviors beyond the 1.x migration
- [Changelog catalog](https://docs.sqlalchemy.org/en/20/changelog/index.html) - Detailed changelogs for all SQLAlchemy Versions

Reference and How To

**SQLAlchemy ORM** - Detailed guides and API reference for using the ORM

- **Mapping Classes:** [Mapping Python Classes](https://docs.sqlalchemy.org/en/20/orm/mapper_config.html) |
  [Relationship Configuration](https://docs.sqlalchemy.org/en/20/orm/relationships.html)
- **Using the ORM:** [Using the ORM Session](https://docs.sqlalchemy.org/en/20/orm/session.html) |
  [ORM Querying Guide](https://docs.sqlalchemy.org/en/20/orm/queryguide/index.html) |
  [Using AsyncIO](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
- **Configuration Extensions:** [Association Proxy](https://docs.sqlalchemy.org/en/20/orm/extensions/associationproxy.html) |
  [Hybrid Attributes](https://docs.sqlalchemy.org/en/20/orm/extensions/hybrid.html) |
  [Mutable Scalars](https://docs.sqlalchemy.org/en/20/orm/extensions/mutable.html) |
  [Automap](https://docs.sqlalchemy.org/en/20/orm/extensions/automap.html) |
  [All extensions](https://docs.sqlalchemy.org/en/20/orm/extensions/index.html)
- **Extending the ORM:** [ORM Events and Internals](https://docs.sqlalchemy.org/en/20/orm/extending.html)
- **Other:** [Introduction to Examples](https://docs.sqlalchemy.org/en/20/orm/examples.html)

**SQLAlchemy Core** - Detailed guides and API reference for working with Core

- **Engines, Connections, Pools:** [Engine Configuration](https://docs.sqlalchemy.org/en/20/core/engines.html) |
  [Connections, Transactions, Results](https://docs.sqlalchemy.org/en/20/core/connections.html) |
  [AsyncIO Support](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html) |
  [Connection Pooling](https://docs.sqlalchemy.org/en/20/core/pooling.html)
- **Schema Definition:** [Overview](https://docs.sqlalchemy.org/en/20/core/schema.html) |
  [Tables and Columns](https://docs.sqlalchemy.org/en/20/core/metadata.html) |
  [Database Introspection (Reflection)](https://docs.sqlalchemy.org/en/20/core/reflection.html) |
  [Insert/Update Defaults](https://docs.sqlalchemy.org/en/20/core/defaults.html) |
  [Constraints and Indexes](https://docs.sqlalchemy.org/en/20/core/constraints.html) |
  [Using Data Definition Language (DDL)](https://docs.sqlalchemy.org/en/20/core/ddl.html)
- **SQL Statements:** [SQL Expression Elements](https://docs.sqlalchemy.org/en/20/core/sqlelement.html) |
  [Operator Reference](https://docs.sqlalchemy.org/en/20/core/operators.html) |
  [SELECT and related constructs](https://docs.sqlalchemy.org/en/20/core/selectable.html) |
  [INSERT, UPDATE, DELETE](https://docs.sqlalchemy.org/en/20/core/dml.html) |
  [SQL Functions](https://docs.sqlalchemy.org/en/20/core/functions.html) |
  [Table of Contents](https://docs.sqlalchemy.org/en/20/core/expression_api.html)
- **Datatypes:** [Overview](https://docs.sqlalchemy.org/en/20/core/types.html) |
  [Building Custom Types](https://docs.sqlalchemy.org/en/20/core/custom_types.html#types-custom) |
  [Type API Reference](https://docs.sqlalchemy.org/en/20/core/type_api.html#types-api)
- **Core Basics:** [Overview](https://docs.sqlalchemy.org/en/20/core/api_basics.html) |
  [Runtime Inspection API](https://docs.sqlalchemy.org/en/20/core/inspection.html) |
  [Event System](https://docs.sqlalchemy.org/en/20/core/event.html) |
  [Core Event Interfaces](https://docs.sqlalchemy.org/en/20/core/events.html) |
  [Creating Custom SQL Constructs](https://docs.sqlalchemy.org/en/20/core/compiler.html)

Dialect Documentation

The **dialect** is the system SQLAlchemy uses to communicate with various types of DBAPIs and databases.
This section describes notes, options, and usage patterns regarding individual dialects.

[PostgreSQL](https://docs.sqlalchemy.org/en/20/dialects/postgresql.html) |
[MySQL and MariaDB](https://docs.sqlalchemy.org/en/20/dialects/mysql.html) |
[SQLite](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html) |
[Oracle Database](https://docs.sqlalchemy.org/en/20/dialects/oracle.html) |
[Microsoft SQL Server](https://docs.sqlalchemy.org/en/20/dialects/mssql.html)

[More Dialects …](https://docs.sqlalchemy.org/en/20/dialects/index.html)

Supplementary

- [Frequently Asked Questions](https://docs.sqlalchemy.org/en/20/faq/index.html) - A collection of common
  problems and solutions
- [Glossary](https://docs.sqlalchemy.org/en/20/glossary.html) - Definitions of terms used in SQLAlchemy
  documentation
- [Error Message Guide](https://docs.sqlalchemy.org/en/20/errors.html) - Explanations of many SQLAlchemy
  errors
- [Complete table of of contents](https://docs.sqlalchemy.org/en/20/contents.html) - Full list of available
  documentation
- [Index](https://docs.sqlalchemy.org/en/20/genindex.html) - Index for easy lookup of documentation topics

---

# SQLAlchemy 2.0 Documentation

# Overview

The SQLAlchemy SQL Toolkit and Object Relational Mapper
is a comprehensive set of tools for working with
databases and Python. It has several distinct areas of
functionality which can be used individually or combined
together. Its major components are illustrated below,
with component dependencies organized into layers:

 ![_images/sqla_arch_small.png](https://docs.sqlalchemy.org/en/20/_images/sqla_arch_small.png)

Above, the two most significant front-facing portions of
SQLAlchemy are the **Object Relational Mapper (ORM)** and the
**Core**.

Core contains the breadth of SQLAlchemy’s SQL and database
integration and description services, the most prominent part of this
being the **SQL Expression Language**.

The SQL Expression Language is a toolkit on its own, independent of the ORM
package, which provides a system of constructing SQL expressions represented by
composable objects, which can then be “executed” against a target database
within the scope of a specific transaction, returning a result set.
Inserts, updates and deletes (i.e. [DML](https://docs.sqlalchemy.org/en/20/glossary.html#term-DML)) are achieved by passing
SQL expression objects representing these statements along with dictionaries
that represent parameters to be used with each statement.

The ORM builds upon Core to provide a means of working with a domain object
model mapped to a database schema. When using the ORM, SQL statements are
constructed in mostly the same way as when using Core, however the task of DML,
which here refers to the persistence of business objects in a database, is
automated using a pattern called [unit of work](https://docs.sqlalchemy.org/en/20/glossary.html#term-unit-of-work), which translates changes
in state against mutable objects into INSERT, UPDATE and DELETE constructs
which are then invoked in terms of those objects. SELECT statements are also
augmented by ORM-specific automations and object-centric querying capabilities.

Whereas working with Core and the SQL Expression language presents a
schema-centric view of the database, along with a programming paradigm that is
oriented around immutability, the ORM builds on top of this a domain-centric
view of the database with a programming paradigm that is more explicitly
object-oriented and reliant upon mutability.  Since a relational database is
itself a mutable service, the difference is that Core/SQL Expression language
is command oriented whereas the ORM is state oriented.

## Documentation Overview

The documentation is separated into four sections:

- [SQLAlchemy Unified Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html#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 the 1.x series of
  SQLAlchemy, should start here.
- [SQLAlchemy ORM](https://docs.sqlalchemy.org/en/20/orm/index.html) - In this section, reference documentation for the ORM is
  presented.
- [SQLAlchemy Core](https://docs.sqlalchemy.org/en/20/core/index.html) - Here, reference documentation for
  everything else within Core is presented. SQLAlchemy engine, connection, and
  pooling services are also described here.
- [Dialects](https://docs.sqlalchemy.org/en/20/dialects/index.html) - Provides reference documentation
  for all [dialect](https://docs.sqlalchemy.org/en/20/glossary.html#term-dialect) implementations, including [DBAPI](https://docs.sqlalchemy.org/en/20/glossary.html#term-DBAPI) specifics.

## Code Examples

Working code examples, mostly regarding the ORM, are included in the
SQLAlchemy distribution. A description of all the included example
applications is at [ORM Examples](https://docs.sqlalchemy.org/en/20/orm/examples.html).

There is also a wide variety of examples involving both core SQLAlchemy
constructs as well as the ORM on the wiki.  See
[Theatrum Chemicum](https://www.sqlalchemy.org/trac/wiki/UsageRecipes).

## Installation Guide

### Supported Platforms

SQLAlchemy supports the following platforms:

- cPython 3.7 and higher
- Python-3 compatible versions of [PyPy](http://pypy.org/)

Changed in version 2.0: SQLAlchemy now targets Python 3.7 and above.

### AsyncIO Support

SQLAlchemy’s `asyncio` support depends upon the
[greenlet](https://pypi.org/project/greenlet/) project.    This dependency
will be installed by default on common machine platforms, however is not
supported on every architecture and also may not install by default on
less common architectures.  See the section [Asyncio Platform Installation Notes (Including Apple M1)](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#asyncio-install) for
additional details on ensuring asyncio support is present.

### Supported Installation Methods

SQLAlchemy installation is via standard Python methodologies that are
based on [setuptools](https://pypi.org/project/setuptools/), either
by referring to `setup.py` directly or by using
[pip](https://pypi.org/project/pip/) or other setuptools-compatible
approaches.

### Install via pip

When `pip` is available, the distribution can be
downloaded from PyPI and installed in one step:

```
pip install SQLAlchemy
```

This command will download the latest **released** version of SQLAlchemy from
the [Python Cheese Shop](https://pypi.org/project/SQLAlchemy) and install it
to your system. For most common platforms, a Python Wheel file will be
downloaded which provides native Cython / C extensions prebuilt.

In order to install the latest **prerelease** version, such as `2.0.0b1`,
pip requires that the `--pre` flag be used:

```
pip install --pre SQLAlchemy
```

Where above, if the most recent version is a prerelease, it will be installed
instead of the latest released version.

### Installing manually from the source distribution

When not installing from pip, the source distribution may be installed
using the `setup.py` script:

```
python setup.py install
```

The source install is platform agnostic and will install on any platform
regardless of whether or not Cython / C build tools are installed. As the next
section [Building the Cython Extensions](#c-extensions) details, `setup.py` will attempt to build using
Cython / C if possible but will fall back to a pure Python installation
otherwise.

### Building the Cython Extensions

SQLAlchemy includes [Cython](https://cython.org/) extensions which provide an extra speed boost
within various areas, with a current emphasis on the speed of Core result sets.

Changed in version 2.0: The SQLAlchemy C extensions have been rewritten
using Cython.

`setup.py` will automatically build the extensions if an appropriate platform
is detected, assuming the Cython package is installed.  A complete manual
build looks like:

```
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy

# install cython
pip install cython

# optionally build Cython extensions ahead of install
python setup.py build_ext

# run the install
python setup.py install
```

Source builds may also be performed using [PEP 517](https://peps.python.org/pep-0517/) techniques, such as
using [build](https://pypi.org/project/build/):

```
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy

# install build
pip install build

# build source / wheel dists
python -m build
```

If the build of the Cython extensions fails due to Cython not being installed,
a missing compiler or other issue, the setup process will output a warning
message and re-run the build without the Cython extensions upon completion,
reporting final status.

To run the build/install without even attempting to compile the Cython
extensions, the `DISABLE_SQLALCHEMY_CEXT` environment variable may be
specified. The use case for this is either for special testing circumstances,
or in the rare case of compatibility/build issues not overcome by the usual
“rebuild” mechanism:

```
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install
```

### Installing a Database API

SQLAlchemy is designed to operate with a [DBAPI](https://docs.sqlalchemy.org/en/20/glossary.html#term-DBAPI) implementation built for a
particular database, and includes support for the most popular databases.
The individual database sections in [Dialects](https://docs.sqlalchemy.org/en/20/dialects/index.html) enumerate
the available DBAPIs for each database, including external links.

### Checking the Installed SQLAlchemy Version

This documentation covers SQLAlchemy version 2.0. If you’re working on a
system that already has SQLAlchemy installed, check the version from your
Python prompt like this:

```
>>> import sqlalchemy
>>> sqlalchemy.__version__
2.0.0
```

### Next Steps

With SQLAlchemy installed, new and old users alike can
[Proceed to the SQLAlchemy Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html#unified-tutorial).

## 1.x to 2.0 Migration

Notes on the new API released in SQLAlchemy 2.0 is available here at [SQLAlchemy 2.0 - Major Migration Guide](https://docs.sqlalchemy.org/en/20/changelog/migration_20.html).

---

# SQLAlchemy 2.1 Documentation

Release: 2.1.0b1 beta release

        | Release Date: January 21, 2026

# SQLAlchemy 2.1 Documentation

[Contents](https://docs.sqlalchemy.org/en/20/contents.html) |
            [Index](https://docs.sqlalchemy.org/en/20/genindex.html)
            | [Download this Documentation](https://docs.sqlalchemy.org/21/sqlalchemy_21.zip)

[Home](https://docs.sqlalchemy.org/en/20/index.html)
        | [Download this Documentation](https://docs.sqlalchemy.org/21/sqlalchemy_21.zip)

# Page Not Found!

Can't find the page you're looking for.

        © [Copyright](https://docs.sqlalchemy.org/en/20/copyright.html) 2007-2026, the SQLAlchemy authors and contributors.

**flambé!** the dragon and **The Alchemist** image designs created and generously donated by [Rotem Yaari](https://github.com/vmalloc).

        Created using [Sphinx](https://www.sphinx-doc.org) 9.1.0.

    Documentation last generated: Thu 29 Jan 2026 03:02:00 PM  EST
