概述¶

SQLAlchemy SQL工具包和对象关系映射器是一套用于处理数据库和Python的综合工具。它有几个不同的功能领域,可以单独使用或组合在一起。其主要组件如下所示,组件依赖关系组织成层:

_images/sqla_arch_small.png

上面,SQLAlchemy的两个最重要的前向部分是 对象关系映射器 以及 SQL表达式语言 . SQL表达式可以独立于ORM使用。使用ORM时,SQL表达式语言仍然是面向公共的API的一部分,因为它在对象关系配置和查询中使用。

文档概述

文件分为三个部分: SqLalChany ORMSQLAlchemy Core方言 .

SqLalChany ORM 介绍并详细描述了对象关系映射器。新用户应以 对象关系教程 . 如果您想使用自动为您构建的高级SQL,以及管理Python对象,请继续本教程。

SQLAlchemy Core 对SQLAlchemy的SQL和数据库集成和描述服务的广度进行了记录,其核心是SQL表达式语言。SQL表达式语言是一个完全独立于ORM包的工具箱,它可以用来构造可操作的SQL表达式,可以通过编程方式构造、修改和执行这些表达式,并返回类似于光标的结果集。与ORM以域为中心的使用模式不同,表达式语言提供了以模式为中心的使用模式。新用户应该从这里开始 SQL表达式语言教程 . SQLAlchemy引擎、连接和池服务也在 SQLAlchemy Core .

方言 ,提供了所有提供的数据库和DBAPI后端的参考文档。

代码示例

工作代码示例(主要是关于ORM)包含在SQLAlchemy分发版中。所有包含的示例应用程序的说明位于 ORM实例 .

还有许多例子涉及核心的SQLAlchemy结构和wiki上的orm。见 Theatrum Chemicum .

安装指南

支持的平台

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

  • Cypthon 2.7

  • CPython 3.4及以上

  • PyPy 2.1或更大

在 1.2 版更改: python 2.7现在是支持的最低python版本。

在 1.3 版更改: 在python 3系列中,3.4现在是支持的最低python 3版本。

目前没有支持的平台包括Jython和Ironpython。Jython在过去得到了支持,在将来的版本中也可能得到支持,这取决于Jython本身的状态。

支持的安装方法

SQLAlchemy安装是通过基于 setuptools ,或者通过引用 setup.py 直接或通过使用 pip 或其他与设置工具兼容的方法。

在 1.1 版更改: setuptools现在是setup.py文件所必需的;不再支持纯distutils安装。

通过PIP安装

什么时候? pip 可以从pypi下载分发版并一步安装:

pip install SQLAlchemy

此命令将下载最新的 释放 SQLAlchemy的版本 Python Cheese Shop 并将其安装到您的系统中。

为了安装最新的 预缓解 版本,例如 1.3.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 如果检测到适当的平台,将自动生成扩展。如果由于缺少编译器或其他问题导致C扩展的生成失败,安装过程将输出一条警告消息,并在完成时重新运行不带C扩展的生成,报告最终状态。

要在不编译C扩展的情况下运行生成/安装,请 DISABLE_SQLALCHEMY_CEXT 可以指定环境变量。这种方法的用例要么是针对特殊的测试环境,要么是对于通常的“重建”机制无法克服的兼容性/构建问题的罕见情况:

export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

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

安装数据库API

SQLAlchemy的设计目的是使用 DBAPI 为特定数据库构建的实现,包括对最流行的数据库的支持。中的各个数据库部分 方言 为每个数据库枚举可用的DBAPI,包括外部链接。

检查已安装的SQLAlchemy版本

本文档涵盖SQLAlchemy 1.3版。如果您在一个已经安装了SQLAlchemy的系统上工作,请从python提示符检查版本,如下所示:

>>> import sqlalchemy
>>> sqlalchemy.__version__ 
1.3.0

1.2至1.3迁移

有关从1.2更改为1.3的说明,请访问 SQLAlchemy 1.3有什么新功能? .