Overview
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 all 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. ) 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, 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 explcitly 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.
The documentation is separated into four sections:
- In this section, reference documentation for the ORM is presented; this section also includes the now-legacy Object Relational Tutorial (1.x API).
- Here, reference documentation for everything else within Core is presented; section also includes the legacy SQL Expression Language Tutorial (1.x API). SQLAlchemy engine, connection, and pooling services are also described here.
Working code examples, mostly regarding the ORM, are included in the SQLAlchemy distribution. A description of all the included example applications is at .
There is also a wide variety of examples involving both core SQLAlchemy constructs as well as the ORM on the wiki. See Theatrum Chemicum.
SQLAlchemy has been tested against the following platforms:
cPython 2.7
cPython 3.6 and higher
Changed in version 1.4: Within the Python 3 series, 3.6 is now the minimum Python 3 version supported.
See also
Supported Installation Methods
SQLAlchemy installation is via standard Python methodologies that are based on setuptools, either by referring to directly or by using or other setuptools-compatible approaches.
When pip
is available, the distribution can be downloaded from PyPI and installed in one step:
This command will download the latest released version of SQLAlchemy from the Python Cheese Shop and install it to your system.
In order to install the latest prerelease version, such as , pip requires that the --pre
flag be used:
Where above, if the most recent version is a prerelease, it will be installed instead 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 for dealing with result sets. The extensions are supported on both the 2.xx and 3.xx series of cPython.
setup.py
will automatically build the extensions if an appropriate platform is detected. If the build of the C extensions fails due to a 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, the 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:
Changed in version 1.1: The legacy --without-cextensions
flag has been removed from the installer as it relies on deprecated features of setuptools.
Installing a Database API
SQLAlchemy is designed to operate with a implementation built for a particular database, and includes support for the most popular databases. The individual database sections in Dialects enumerate the available DBAPIs for each database, including external links.
Notes on what’s changed from 1.3 to 1.4 is available here at .