Project Versions

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 in below,
with component dependencies organized into layers:

Above, the two most significant front-facing portions of
SQLAlchemy are the Object Relational Mapper and the
SQL Expression Language. SQL Expressions can be used
independently of the ORM. When using the ORM, the SQL
Expression language remains part of the public facing API
as it is used within object-relational configurations and
queries.

In SQLAlchemy ORM, the Object Relational Mapper is introduced and fully
described. New users should begin with the Object Relational Tutorial. If you
want to work with higher-level SQL which is constructed automatically for you,
as well as management of Python objects, proceed to this tutorial.

In SQLAlchemy Core, the breadth of SQLAlchemy’s SQL and database
integration and description services are documented, the core of which is the
SQL Expression language. The SQL Expression Language is a toolkit all its own,
independent of the ORM package, which can be used to construct manipulable SQL
expressions which can be programmatically constructed, modified, and executed,
returning cursor-like result sets. In contrast to the ORM’s domain-centric
mode of usage, the expression language provides a schema-centric usage
paradigm. New users should begin here with SQL Expression Language Tutorial.
SQLAlchemy engine, connection, and pooling services are also described in
SQLAlchemy Core.

In Dialects, reference documentation for all provided
database and DBAPI backends is provided.

SQLAlchemy supports installation using standard Python “distutils” or
“setuptools” methodologies. An overview of potential setups is as follows:

Plain Python Distutils - SQLAlchemy can be installed with a clean
Python install using the services provided via Python Distutils,
using the setup.py script. The C extensions as well as Python 3 builds are supported.

Standard Setuptools - When using setuptools,
SQLAlchemy can be installed via setup.py or easy_install, and the C
extensions are supported. setuptools is not supported on Python 3 at the time
of of this writing.

Distribute - With distribute,
SQLAlchemy can be installed via setup.py or easy_install, and the C
extensions as well as Python 3 builds are supported.

pip - pip is an installer that
rides on top of setuptools or distribute, replacing the usage
of easy_install. It is often preferred for its simpler mode of usage.

Note

It is strongly recommended that either setuptools or distribute be installed.
Python’s built-in distutils lacks many widely used installation features.

SQLAlchemy includes C extensions which provide an extra speed boost for
dealing with result sets. Currently, the extensions are only supported on the
2.xx series of cPython, not Python 3 or Pypy.

setup.py will automatically build the extensions if an appropriate platform is
detected. If the build of the C extensions fails, due to missing compiler or
other issue, the setup process will output a warning message, and re-run the
build without the C extensions, upon completion reporting final status.

To run the build/install without even attempting to compile the C extensions,
pass the flag --without-cextensions to the setup.py script:

python setup.py --without-cextensions install

Or with pip:

pip install --global-option='--without-cextensions' SQLAlchemy

Note

The --without-cextensions flag is available only if setuptools
or distribute is installed. It is not available on a plain Python distutils
installation. The library will still install without the C extensions if they
cannot be built, however.

SQLAlchemy ships as Python 2 code. For Python 3 usage, the setup.py script
will invoke the Python 2to3 tool on the build, plugging in an extra
“preprocessor” as well. The 2to3 step works with Python distutils
(part of the standard Python install) and Distribute - it will not
work with a non-Distribute setuptools installation.