12
The SQLAlchemy SQL Toolkit and Object Relational Mapper
13
is a comprehensive set of tools for working with
14
databases and Python. It has several distinct areas of
15
functionality which can be used individually or combined
16
together. Its major components are illustrated in below,
17
with component dependencies organized into layers:
19
.. image:: sqla_arch_small.png
21
Above, the two most significant front-facing portions of
22
SQLAlchemy are the **Object Relational Mapper** and the
23
**SQL Expression Language**. SQL Expressions can be used
24
independently of the ORM. When using the ORM, the SQL
25
Expression language remains part of the public facing API
26
as it is used within object-relational configurations and
31
Documentation Overview
32
======================
34
The documentation is separated into three sections: :ref:`orm_toplevel`,
35
:ref:`core_toplevel`, and :ref:`dialect_toplevel`.
37
In :ref:`orm_toplevel`, the Object Relational Mapper is introduced and fully
38
described. New users should begin with the :ref:`ormtutorial_toplevel`. If you
39
want to work with higher-level SQL which is constructed automatically for you,
40
as well as management of Python objects, proceed to this tutorial.
42
In :ref:`core_toplevel`, the breadth of SQLAlchemy's SQL and database
43
integration and description services are documented, the core of which is the
44
SQL Expression language. The SQL Expression Language is a toolkit all its own,
45
independent of the ORM package, which can be used to construct manipulable SQL
46
expressions which can be programmatically constructed, modified, and executed,
47
returning cursor-like result sets. In contrast to the ORM's domain-centric
48
mode of usage, the expression language provides a schema-centric usage
49
paradigm. New users should begin here with :ref:`sqlexpression_toplevel`.
50
SQLAlchemy engine, connection, and pooling services are also described in
53
In :ref:`dialect_toplevel`, reference documentation for all provided
54
database and DBAPI backends is provided.
59
Working code examples, mostly regarding the ORM, are included in the
60
SQLAlchemy distribution. A description of all the included example
61
applications is at :ref:`examples_toplevel`.
63
There is also a wide variety of examples involving both core SQLAlchemy
64
constructs as well as the ORM on the wiki. See
65
`Theatrum Chemicum <http://www.sqlalchemy.org/trac/wiki/UsageRecipes>`_.
75
SQLAlchemy has been tested against the following platforms:
77
* cPython since version 2.6, through the 2.xx series
78
* cPython version 3, throughout all 3.xx series
79
* `Pypy <http://pypy.org/>`_ 2.1 or greater
81
.. versionchanged:: 0.9
82
Python 2.6 is now the minimum Python version supported.
84
Supported Installation Methods
85
-------------------------------
87
SQLAlchemy supports installation using standard Python "distutils" or
88
"setuptools" methodologies. An overview of potential setups is as follows:
90
* **Plain Python Distutils** - SQLAlchemy can be installed with a clean
91
Python install using the services provided via `Python Distutils <http://docs.python.org/distutils/>`_,
92
using the ``setup.py`` script. The C extensions as well as Python 3 builds are supported.
93
* **Setuptools or Distribute** - When using `setuptools <http://pypi.python.org/pypi/setuptools/>`_,
94
SQLAlchemy can be installed via ``setup.py`` or ``easy_install``, and the C
95
extensions are supported.
96
* **pip** - `pip <http://pypi.python.org/pypi/pip/>`_ is an installer that
97
rides on top of ``setuptools`` or ``distribute``, replacing the usage
98
of ``easy_install``. It is often preferred for its simpler mode of usage.
100
Install via easy_install or pip
101
-------------------------------
103
When ``easy_install`` or ``pip`` is available, the distribution can be
104
downloaded from Pypi and installed in one step::
106
easy_install SQLAlchemy
110
pip install SQLAlchemy
112
This command will download the latest version of SQLAlchemy from the `Python
113
Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your system.
117
Beta releases of SQLAlchemy may not be present on Pypi, and may instead
118
require a direct download first.
120
Installing using setup.py
121
----------------------------------
123
Otherwise, you can install from the distribution using the ``setup.py`` script::
125
python setup.py install
127
Installing the C Extensions
128
----------------------------------
130
SQLAlchemy includes C extensions which provide an extra speed boost for
131
dealing with result sets. The extensions are supported on both the 2.xx
132
and 3.xx series of cPython.
134
.. versionchanged:: 0.9.0
136
The C extensions now compile on Python 3 as well as Python 2.
138
``setup.py`` will automatically build the extensions if an appropriate platform is
139
detected. If the build of the C extensions fails, due to missing compiler or
140
other issue, the setup process will output a warning message, and re-run the
141
build without the C extensions, upon completion reporting final status.
143
To run the build/install without even attempting to compile the C extensions,
144
the ``DISABLE_SQLALCHEMY_CEXT`` environment variable may be specified. The
145
use case for this is either for special testing circumstances, or in the rare
146
case of compatibility/build issues not overcome by the usual "rebuild"
149
# *** only in SQLAlchemy 0.9.4 / 0.8.6 or greater ***
150
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install
152
.. versionadded:: 0.9.4,0.8.6 Support for disabling the build of
153
C extensions using the ``DISABLE_SQLALCHEMY_CEXT`` environment variable
154
has been added. This allows control of C extension building whether or not
155
setuptools is available, and additionally works around the fact that
156
setuptools will possibly be **removing support** for command-line switches
157
such as ``--without-extensions`` in a future release.
159
For versions of SQLAlchemy prior to 0.9.4 or 0.8.6, the
160
``--without-cextensions`` option may be used to disable the attempt to build
161
C extensions, provided setupools is in use, and provided the ``Feature``
162
construct is supported by the installed version of setuptools::
164
python setup.py --without-cextensions install
168
pip install --global-option='--without-cextensions' SQLAlchemy
171
Installing on Python 3
172
----------------------------------
174
SQLAlchemy runs directly on Python 2 or Python 3, and can be installed in
175
either environment without any adjustments or code conversion.
177
.. versionchanged:: 0.9.0 Python 3 is now supported in place with no 2to3 step
181
Installing a Database API
182
----------------------------------
184
SQLAlchemy is designed to operate with a :term:`DBAPI` implementation built for a
185
particular database, and includes support for the most popular databases.
186
The individual database sections in :doc:`/dialects/index` enumerate
187
the available DBAPIs for each database, including external links.
189
Checking the Installed SQLAlchemy Version
190
------------------------------------------
192
This documentation covers SQLAlchemy version 0.9. If you're working on a
193
system that already has SQLAlchemy installed, check the version from your
194
Python prompt like this:
196
.. sourcecode:: python+sql
198
>>> import sqlalchemy
199
>>> sqlalchemy.__version__ # doctest: +SKIP
205
=====================
207
Notes on what's changed from 0.8 to 0.9 is available here at :doc:`changelog/migration_09`.
added
removed
doc/_sources/intro.txt
