Python ROM SQLAlchemy Document

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 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 APIas it is used within object-relational configurations andqueries.

Documentation Overview(文档概览)

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

In SQLAlchemy ORM, the Object Relational Mapper is introduced and fullydescribed. New users should begin with the Object Relational Tutorial. 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 SQL Expression Language Tutorial.SQLAlchemy engine, connection, and pooling services are also described inSQLAlchemy Core.

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

Code Examples（代码样例）

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. SeeTheatrum Chemicum.

Installation Guide（安装指引）

Supported Platforms（支持平台）

SQLAlchemy has been tested against the following platforms:

• cPython since version 2.6, through the 2.xx series
• cPython version 3, throughout all 3.xx series
• Pypy 2.1 or greater

Changed in version 0.9: Python 2.6 is now the minimum Python version supported.

Platforms that don’t currently have support include Jython, 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 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 cleanPython install using the services provided via Python Distutils,using the setup.py script. The C extensions as well as Python 3 builds are supported.
• Setuptools or Distribute - When using setuptools,SQLAlchemy can be installed via setup.py or easy_install, and the Cextensions are supported.
• pip - pip is an installer thatrides on top of setuptools or distribute, replacing the usageof easy_install. It is often preferred for its simpler mode of usage.

Install via pip（通过PIP命令安装）

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

pip install SQLAlchemy

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

In order to install the latest prerelease version, such as 1.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 installedinstead of the latest released version.

Installing using setup.py（使用set.py来安装）

Otherwise, you can install from the distribution using the setup.py script:

python setup.py install

Installing the C Extensions（安装C拓展）

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.

Changed in version 0.9.0: The C extensions now compile on Python 3 as well as Python 2.

setup.py will automatically build the extensions if an appropriate platform isdetected. If the build of the C extensions fails, due to 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 DISABLE_SQLALCHEMY_CEXT 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:

# *** only in SQLAlchemy 0.9.4 / 0.8.6 or greater ***
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

New in version 0.9.4,0.8.6: Support for disabling the build ofC extensions using the DISABLE_SQLALCHEMY_CEXT environment variablehas been added. This allows control of C extension building whether or notsetuptools is available, and additionally works around the fact thatsetuptools will possibly be removing support for command-line switchessuch as --without-extensions in a future release.

For versions of SQLAlchemy prior to 0.9.4 or 0.8.6, the--without-cextensions option may be used to disable the attempt to buildC extensions, provided setupools is in use, and provided the Featureconstruct is supported by the installed version of setuptools:

python setup.py --without-cextensions install

Or with pip:

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

Installing on Python 3（在Python3上安装）

SQLAlchemy runs directly on Python 2 or Python 3, and can be installed ineither environment without any adjustments or code conversion.

Changed in version 0.9.0: Python 3 is now supported in place with no 2to3 steprequired.

Installing a Database API（安装数据库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 Dialects enumeratethe available DBAPIs for each database, including external links.

Checking the Installed SQLAlchemy Version

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

>>> import sqlalchemy
>>> sqlalchemy.__version__ 
1.0.0

0.9 to 1.0 Migration（版本升级）

Notes on what’s changed from 0.9 to 1.0 is available here at What’s New in SQLAlchemy 1.0?.

SQLALCHEMY教程：

http://www.codexiu.cn/python/SQLAlchemy%E5%9F%BA%E7%A1%80%E6%95%99%E7%A8%8B/532/