SQLAlchemy

|PyPI| |Python| |Downloads|

.. |PyPI| image:: https://img.shields.io/pypi/v/sqlalchemy :target: https://pypi.org/project/sqlalchemy :alt: PyPI

.. |Python| image:: https://img.shields.io/pypi/pyversions/sqlalchemy :target: https://pypi.org/project/sqlalchemy :alt: PyPI - Python Version

.. |Downloads| image:: https://static.pepy.tech/badge/sqlalchemy/month :target: https://pepy.tech/project/sqlalchemy :alt: PyPI - Downloads

Python SQL 工具包与对象关系映射器

简介

SQLAlchemy 是 Python 的 SQL 工具包和对象关系映射器（ORM），为应用开发者提供了 SQL 的全部能力与灵活性。SQLAlchemy 提供了一套完整的企业级持久化模式，旨在实现高效且高性能的数据库访问，并以简洁、符合 Python 风格的领域语言呈现。

SQLAlchemy 的主要特性包括：

• 工业级 ORM，基于身份映射（identity map）、工作单元（unit of work）和数据映射器（data mapper）模式构建。这些模式允许通过声明式配置系统透明地持久化对象。领域模型可以自然地构建和操作，变更会自动与当前事务同步。
• 面向关系型查询系统，以对象模型的方式显式展现 SQL 的全部能力，包括连接、子查询、关联等几乎所有功能。使用 ORM 编写查询时，采用与编写 SQL 相同的关系组合技术。虽然可以随时直接使用原生 SQL，但几乎无需这样做。
• 全面而灵活的关联集合与对象预加载系统。集合在会话中缓存，可按需单独加载、通过连接一次性加载，或基于完整结果集按集合查询。
• 核心 SQL 构建系统与 DBAPI 交互层。SQLAlchemy Core 独立于 ORM，本身就是一个完整的数据库抽象层，包含可扩展的基于 Python 的 SQL 表达式语言、模式元数据、连接池、类型强制转换和自定义类型。
• 所有主键和外键约束均被视为复合且自然的。当然，代理整数主键仍是常态，但 SQLAlchemy 从不假设或硬编码这种模型。
• 数据库自省与生成。数据库模式可一步"反射"为表示数据库元数据的 Python 结构，这些结构又能重新生成 CREATE 语句——全部在 Core 中完成，独立于 ORM。

SQLAlchemy 的设计哲学：

• 当规模和性能愈发重要时，SQL 数据库越来越不像对象集合；当抽象愈发重要时，对象集合越来越不像表和行。SQLAlchemy 旨在兼顾这两项原则。
• ORM 不必隐藏"R"。关系型数据库提供的丰富、基于集合的功能应充分暴露。SQLAlchemy ORM 提供开放式模式，让开发者能在领域模型与关系模式间构建自定义中介层，使所谓的"对象关系阻抗"问题成为遥远的记忆。
• 开发者始终拥有对对象模型和关系模式的设计、结构及命名约定的全部决策权。SQLAlchemy 仅提供自动化执行这些决策的手段。
• 使用 SQLAlchemy 时，不存在"ORM 生成了糟糕查询"的情况——你完全掌控查询结构，包括连接组织方式、子查询与关联的使用、请求的列等。SQLAlchemy 的一切行为最终都源于开发者的主动决策。
• 如果问题不需要 ORM，就不要使用。SQLAlchemy 由 Core 和独立的 ORM 组件构成。Core 提供完整的 SQL 表达式语言，支持以 Python 风格构建直接渲染为目标数据库 SQL 字符串的 SQL 结构，返回本质上是增强型 DBAPI 游标的结果集。
• 事务应是常态。使用 SQLAlchemy ORM 时，只有调用 commit() 后数据才会永久存储。SQLAlchemy 鼓励应用建立明确界定操作序列开始与结束的机制。
• 永远不在 SQL 语句中直接渲染字面值。尽可能使用绑定参数，让查询优化器有效缓存查询计划，并使 SQL 注入攻击无从发生。

文档

最新文档位于：

https://www.sqlalchemy.org/docs/

安装 / 要求

完整安装文档见 安装指南。

获取帮助 / 开发 / 错误报告

请参阅 SQLAlchemy 社区指南。

行为准则

最重要的是，SQLAlchemy 极其重视用户与开发者之间礼貌、周到且富有建设性的交流。请查看我们现行的 行为准则。

许可证

SQLAlchemy 基于 MIT 许可证 <https://www.opensource.org/licenses/mit-license.php>_ 发布。