版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

概述¶ T0>

SQLAlchemy的SQL工具包和ORM是一套python数据库操作的综合工具包。它有多个不同领域的功能,可以单独使用或组合使用。其主要组件如下图所示,包含组件层次上的依赖关系。

http://sqlalchemy.readthedocs.io/en/latest/_images/sqla_arch_small.png

如上图所示,SQLAlchemy 最重要的两个部分是 ORMSQL 表达式语言SQL表达式可以独立于ORM使用。使用 ORM 时,SQL 表达式语言仍然是公开 API 的一部分,因为它在对象关系配置和查询中使用。

文档概述

文档分为三个部分: SQLAlchemy ORMSQLAlchemy 核心方言(Dialects).

SQLAlchemy ORM中, 对象关系映射被充分引入和描述。新用户可以从对象关系教程开始。如果你想要了解自动构建高级SQL以及管理Python对象,推荐阅读此教程。

SQLAlchemy Core 中,主要介绍了SQLAlchemy 的 SQL、数据库集成和描述服务, 这部分的核心是 SQL 表达语言。SQL 表达式是独立于 ORM 包的一套自成一体的工具集, 它可以用来创建易于使用的 SQ 表达式,该 SQL 表达式可通过编程创建、修改和执行,返回游标结果集。对比 ORM 使用域为中心的方式,表达语言提供模式为中心的架构。新用户请从 SQL 表达式教程开始。SQLAlchemy 引擎,链接和池服务同样在SQLAlchemy Core中有描述。

Dialects介绍了所有 SQLAlchemy 支持的数据库和 DBAPI 后端。

代码示例

主要关于ORM的工作代码示例包含在SQLAlchemy发行版中.所有包含的示例应用程序的描述在ORM Examples.中。

还有各种各样的示例涉及核心SQLAlchemy构造以及维基上的ORM, Theatrum Chemicum

安装指南

支持的平台

SQLAlchemy已经针对以下平台进行了测试:

  • cPython从2.6版开始,通过2.xx系列
  • cPython版本3,遍及所有3.xx系列
  • Pypy 2.1 or greater

在0.9版本中更改: Python 2.6现在是支持的最小Python版本。

目前不支持的平台包括Jython,IronPython。曾经已经支持 Jython,并且可能会在将来的版本中支持,这取决于Jython本身的状态。

支持的安装方法

SQLAlchemy安装是通过基于setuptools的标准Python方法,直接或通过使用pip或其他setuptools引用setup.py兼容的方法。

在版本1.1中更改: setup.py文件现在需要setuptools;简单distutils安装不再支持。

通过pip安装

pip可用时,分配可以从Pypi下载并安装在一个步骤中:

pip install SQLAlchemy

该命令将从Python Cheese Shop下载最新的发布的版本的SQLAlchemy,并将其安装到您的系统中。

为了安装最新的prerelease版本,比如1.1.0b1,pip要求使用--pre标志:

pip install --pre SQLAlchemy

在上面的情况下,如果最新版本是预发行版,则将被安装而不是最新发行的版本。

使用setup.py 进行安装

否则,您可以使用setup.py脚本从分发安装:

python setup.py install

安装C扩展

SQLAlchemy包含C扩展,它提供了额外的速度提升来处理结果集。这些扩展在cPython的2.xx和3.xx系列上都受支持。

setup.py will automatically build the extensions if an appropriate platform is detected. 如果C扩展的构建失败,由于缺少编译器或其他问题,安装过程将输出警告消息,并在完成报告最终状态时重新运行没有C扩展的构建。

要运行构建/安装,甚至不尝试编译C扩展,可以指定DISABLE_SQLALCHEMY_CEXT环境变量。这个用例或者是针对特殊的测试环境,或者是在通常的“重建”机制不能克服的罕见的兼容性/构建问题的情况下:

export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

在版本1.1中更改:遗留的--without-cextensions标志已从安装程序中删除,因为它依赖于setuptools的不推荐使用的功能。

在Python 3上安装

SQLAlchemy直接在Python 2或Python 3上运行,可以在任何环境下安装,无需任何调整或代码转换。

安装数据库API

SQLAlchemy被设计为与为特定数据库构建的DBAPI实现一起工作,并且包括对最流行的数据库的支持。Dialects枚举每个数据库的可用DBAPI,包括外部链接。

检查已安装的SQLAlchemy版本

本文档涵盖了SQLAlchemy版本1.1。如果您正在使用已安装SQLAlchemy的系统,请从您的Python提示符中检查版本,如下所示:

>>> import sqlalchemy
>>> sqlalchemy.__version__ # doctest: +SKIP
1.1.0

1.0到1.1迁移

有关从1.0更改为1.1的说明,请参阅What’s New in SQLAlchemy 1.1?