Overview

    The documentation is separated into three sections: ,SQLAlchemy Core, and .

    In SQLAlchemy ORM, the Object Relational Mapper is introduced and fullydescribed. New users should begin with the . If youwant 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 databaseintegration and description services are documented, the core of which is theSQL Expression language. The SQL Expression Language is a toolkit all its own,independent of the ORM package, which can be used to construct manipulable SQLexpressions which can be programmatically constructed, modified, and executed,returning cursor-like result sets. In contrast to the ORM’s domain-centricmode of usage, the expression language provides a schema-centric usageparadigm. New users should begin here with .SQLAlchemy engine, connection, and pooling services are also described inSQLAlchemy Core.

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

    Working code examples, mostly regarding the ORM, are included in theSQLAlchemy distribution. A description of all the included exampleapplications is at ORM Examples.

    There is also a wide variety of examples involving both core SQLAlchemyconstructs as well as the ORM on the wiki. See.

    SQLAlchemy has been tested against the following platforms:

    • cPython 2.7

    • PyPy 2.1 or greater

    Changed in version 1.2: Python 2.7 is now the minimum Python version supported.

    Changed in version 1.3: Within the Python 3 series, 3.4 is now the minimum Python 3 version supported.

    Platforms that don’t currently have support include Jython and IronPython.Jython has been supported in the past and may be supported in futurereleases as well, depending on the state of Jython itself.

    Supported Installation Methods

    SQLAlchemy installation is via standard Python methodologies that arebased on , eitherby referring to directly or by usingpip or other setuptools-compatibleapproaches.

    Changed in version 1.1: setuptools is now required by the setup.py file;plain distutils installs are no longer supported.

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

    This command will download the latest released version of SQLAlchemy from the and install it to your system.

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

    Installing using setup.py

    Otherwise, you can install from the distribution using the script:

    SQLAlchemy includes C extensions which provide an extra speed boost fordealing with result sets. The extensions are supported on both the 2.xxand 3.xx series of cPython.

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

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

    Changed in version 1.1: The legacy —without-cextensions flag has beenremoved from the installer as it relies on deprecated features ofsetuptools.

    Installing a Database API

    SQLAlchemy is designed to operate with a DBAPI implementation built for aparticular database, and includes support for the most popular databases.The individual database sections in enumeratethe available DBAPIs for each database, including external links.

    This documentation covers SQLAlchemy version 1.3. If you’re working on asystem that already has SQLAlchemy installed, check the version from yourPython prompt like this: