错误信息

优质

小牛编辑

151浏览

2023-12-01

本节列出了SQLAlchemy引发或发出的常见错误消息和警告的描述和背景。

sqlAlchemy通常会在特定于sqlAlchemy的异常类的上下文中引发错误。有关这些类的详细信息，请参见核心异常和 ORM例外 .

SQLAlchemy错误大致可以分为两类，即 programming-time error 以及 运行时错误 . 由于使用不正确的参数调用函数或方法，或从其他面向配置的方法（如无法解决的映射器配置）调用，会引发编程时间错误。编程时间错误通常是直接的和确定性的。另一方面，运行时错误表示当程序响应某些任意发生的条件（如数据库连接耗尽或发生某些与数据相关的问题）运行时发生的故障。运行时错误更可能出现在正在运行的应用程序的日志中，因为程序在响应加载和遇到的数据时遇到这些状态。

由于运行时错误不像程序运行时那样容易重现，并且经常在响应某些任意条件时发生，因此它们更难调试，也会影响已投入生产的程序。

在本节中，目标是尝试提供一些最常见的运行时错误以及编程时错误的背景。

旧API功能

在“传统”模式下创建的select（）构造；关键字参数等。

这个 select() 构造已从SQLAlChemy 1.4更新，以支持将成为中的标准的较新的调用样式 SQLAlchemy 2.0 。为了在过渡期间向后兼容，该构造既接受“遗留”样式的参数，也接受“新”样式的参数。

“新”样式的特征是列和表表达式按位置传递给 select() 仅构造；对象的任何其他修饰符都必须使用后续方法链接传递：

# this is the way to do it going forward
stmt = select(table1.c.myid).where(table1.c.myid == table2.c.otherid)

作为比较，a select() 在SQLAlchemy的遗留形式中，在 Select.where() 甚至添加了，希望：

# this is how it was documented in original SQLAlchemy versions
# many years ago
stmt = select([table1.c.myid], whereclause=table1.c.myid == table2.c.otherid)

甚至“whereclause”也会按位置传递：

# this is also how it was documented in original SQLAlchemy versions
# many years ago
stmt = select([table1.c.myid], table1.c.myid == table2.c.otherid)

几年来，附加的“whereclause”和其他被接受的参数已从大多数叙述性文档中删除，这导致了一种调用样式，最常见的是作为列表传递的列参数列表，但没有进一步的参数：

# this is how it's been documented since around version 1.0 or so
stmt = select([table1.c.myid]).where(table1.c.myid == table2.c.otherid)

文件位于 select（）不再接受各种构造函数参数，列按位置传递从以下方面描述此更改 2.0 Migration .

参见

select（）不再接受各种构造函数参数，列按位置传递

迁移到Alchemy

SQLAlchemy 2.0中的<some function>将不再<something>

SQLAlchemy 2.0预计将是核心组件和ORM组件中各种关键SQLAlchemy使用模式的重大转变。这个版本的目标是对SQLAlchemy早期以来的一些最基本的假设做一点小小的调整，并提供一个新的简化的使用模型，这个模型希望在核心和ORM组件之间更加简洁和一致，并且更加有能力。

介绍时间迁移到Alchemy ，SQLAlchemy 2.0项目包括一个全面的未来兼容性系统，该系统将集成到SQLAlchemy的1.4系列中，这样应用程序将有一个清晰、明确和增量的升级路径，以便将应用程序迁移到完全兼容2.0。这个 RemovedIn20Warning 弃用警告位于该系统的基础上，用于指导现有代码库中的哪些行为需要修改。有关如何启用此警告的概述，请参阅 SQLAlchemy 2.0弃用模式 .

参见

迁移到Alchemy -概述1.x系列的升级过程，以及sqlalchemy2.0的当前目标和进度。

SQLAlchemy 2.0弃用模式 -关于如何在SQLAlchemy 1.4中使用“2.0弃用模式”的具体指导原则。

已通过旧版绑定元数据找到绑定，但由于在此会话上设置了future=True，因此将忽略此绑定。

SQLAlchemy 2.0中删除了“绑定元数据”的概念。这是指 MetaData.bind 上的参数 MetaData 对象，该对象又允许像ORM这样的对象 Session 将特定映射类与 Engine . 在SQLAlchemy 2.0中 Session 必须链接到每个 Engine 直接。也就是说，不是实例化 Session 或 sessionmaker 没有任何参数，并将 Engine 与 MetaData ：：

engine = create_engine("sqlite://")
Session = sessionmaker()
metadata_obj = MetaData(bind=engine)
Base = declarative_base(metadata=metadata_obj)

class MyClass(Base):
    # ...


session = Session()
session.add(MyClass())
session.commit()

这个 Engine 必须直接与 sessionmaker 或 Session . 这个 MetaData 对象不应再与任何引擎关联：：

engine = create_engine("sqlite://")
Session = sessionmaker(engine)
Base = declarative_base()

class MyClass(Base):
    # ...


session = Session()
session.add(MyClass())
session.commit()

在SQLAlchemy 1.4中，这个 2.0 style 当 Session.future 标志已设置为 sessionmaker 或 Session .

对象正在沿着backref级联合并到会话中。

此消息指的是SQLAlChemy的“backref casade”行为，详情请参阅在backrefs上控制级联。这指的是将对象添加到 Session 因为该会话中已经存在的另一个对象与其相关联。由于这一行为被证明是更令人困惑而不是有帮助的， relationship.cascade_backrefs 和 backref.cascade_backrefs 添加了参数，可以将其设置为 False 要禁用它，在SQLAlChemy2.0中，“级联后向引用”行为将被完全禁用。

要设置 relationship.cascade_backrefs 至 False 在当前使用 relationship.backref 字符串参数，则必须使用 backref() 函数，以便 backref.cascade_backrefs 参数可以传递。

或者，整个“级联后向引用”行为可以通过使用 Session 在“将来”模式中，通过传递 True 对于 Session.future 参数。

参见

在backrefs上控制级联 -级联后向参照行为的完整描述

cascade_backrefs行为在2.0中不推荐删除 -SQLAlChemy 2.0更改的背景。

正在为RAW子句元素自动生成别名

1.4.26 新版功能.

此弃用警告指的是一种非常古老且可能不为人熟知的模式，该模式适用于旧版 Query.join() 方法以及 2.0 style Select.join() 方法，其中联接可以用 relationship() 但目标是 Table 或类映射到的其他核心可选对象，而不是ORM实体，如映射的类或 aliased() 构造：：

a1 = Address.__table__

q = s.query(User).\
    join(a1, User.addresses).\
    filter(Address.email_address == 'ed@foo.com').all()

上述模式还允许任意选择，如核心 Join 或 Alias 对象，但是不会自动调整此元素，这意味着需要直接引用Core元素：：

a1 = Address.__table__.alias()

q = s.query(User).\
    join(a1, User.addresses).\
    filter(a1.c.email_address == 'ed@foo.com').all()

指定联接目标的正确方法是始终使用映射的类本身或 aliased 对象，在后一种情况下，使用 PropComparator.of_type() 用于设置别名的修饰符：：

# normal join to relationship entity
q = s.query(User).\
    join(User.addresses).\
    filter(Address.email_address == 'ed@foo.com')

# name Address target explicitly, not necessary but legal
q = s.query(User).\
    join(Address, User.addresses).\
    filter(Address.email_address == 'ed@foo.com')

加入别名：：

from sqlalchemy.orm import aliased

a1 = aliased(Address)

# of_type() form; recommended
q = s.query(User).\
    join(User.addresses.of_type(a1)).\
    filter(a1.email_address == 'ed@foo.com')

# target, onclause form
q = s.query(User).\
    join(a1, User.addresses).\
    filter(a1.email_address == 'ed@foo.com')

由于表重叠，正在自动生成别名

1.4.26 新版功能.

查询时通常会生成此警告。 Select.join() 方法还是传统的 Query.join() 方法，其中的映射涉及联接表继承。问题是，当在共享公共基表的两个联接继承模型之间联接时，如果不将别名应用于一侧或另一侧，则无法在两个实体之间形成正确的SQL联接；SQLAlChemy将别名应用于联接的右侧。例如，给定一个联接继承映射，如下所示：：

class Employee(Base):
    __tablename__ = 'employee'
    id = Column(Integer, primary_key=True)
    manager_id = Column(ForeignKey("manager.id"))
    name = Column(String(50))
    type = Column(String(50))

    reports_to = relationship("Manager", foreign_keys=manager_id)

    __mapper_args__ = {
        'polymorphic_identity':'employee',
        'polymorphic_on':type,
    }

class Manager(Employee):
    __tablename__ = 'manager'
    id = Column(Integer, ForeignKey('employee.id'), primary_key=True)

    __mapper_args__ = {
        'polymorphic_identity':'manager',
        'inherit_condition': id == Employee.id
    }

上述映射包括 Employee 和 Manager 上课。因为这两个类都使用“Employee”数据库表，所以从SQL的角度来看，这是一个 self referential relationship 。如果我们想要从两个 Employee 和 Manager 使用联接建模时，在SQL级别，“Employee”表需要在查询中包括两次，这意味着它必须有别名。当我们使用SQLAlChemy ORM创建这样的联接时，我们会得到如下所示的SQL：

>>> stmt = select(Employee, Manager).join(Employee.reports_to)
>>> print(stmt)
SELECT employee.id, employee.manager_id, employee.name,
employee.type, manager_1.id AS id_1, employee_1.id AS id_2,
employee_1.manager_id AS manager_id_1, employee_1.name AS name_1,
employee_1.type AS type_1
FROM employee JOIN
(employee AS employee_1 JOIN manager AS manager_1 ON manager_1.id = employee_1.id)
ON manager_1.id = employee.manager_id

在上面，SQL从 employee 表，表示 Employee 查询中的实体。然后，它连接到的右嵌套连接 employee AS employee_1 JOIN manager AS manager_1 ，其中 employee 表被再次声明，但作为匿名别名除外 employee_1 。这是警告消息所指的“自动生成别名”。

当SQLAlChemy加载ORM行时，每个ORM行都包含 Employee 和一个 Manager 对象，ORM必须从上面的 employee_1 和 manager_1 表别名转换为无别名的 Manager 班级。此过程在内部很复杂，并不适合所有API功能，特别是在尝试使用诸如 contains_eager() 具有比此处显示的更深嵌套的查询。由于该模式对于更复杂的场景是不可靠的，并且涉及难以预测和遵循的隐式决策，因此发出警告，并且该模式可能被视为遗留功能。编写此查询的更好方法是使用适用于任何其他自引用关系的相同模式，即使用 aliased() 显式构造。对于联接继承和其他面向联接的映射，通常需要添加 aliased.flat 参数，该参数将允许通过将别名应用于联接中的各个表，而不是将联接嵌入到新子查询中，来为两个或多个表的联接设置别名：

>>> from sqlalchemy.orm import aliased
>>> manager_alias = aliased(Manager, flat=True)
>>> stmt = select(Employee, manager_alias).join(Employee.reports_to.of_type(manager_alias))
>>> print(stmt)
SELECT employee.id, employee.manager_id, employee.name,
employee.type, manager_1.id AS id_1, employee_1.id AS id_2,
employee_1.manager_id AS manager_id_1, employee_1.name AS name_1,
employee_1.type AS type_1
FROM employee JOIN
(employee AS employee_1 JOIN manager AS manager_1 ON manager_1.id = employee_1.id)
ON manager_1.id = employee.manager_id

如果我们想要使用 contains_eager() 要填充 reports_to 属性，我们引用别名：：

>>> stmt =select(Employee).join(
...     Employee.reports_to.of_type(manager_alias)
... ).options(
...     contains_eager(Employee.reports_to.of_type(manager_alias))
... )

而不使用显式 aliased() 对象，在某些更嵌套的情况下， contains_eager() 如果ORM在非常嵌套的上下文中是“自动别名”，则Option没有足够的上下文知道从哪里获取数据。因此，最好不要依赖此特性，而是尽可能地保持SQL结构的显式。

连接和事务

已达到队列池大小限制<x>溢出<y>，连接超时，超时<z>

这可能是遇到的最常见的运行时错误，因为它直接涉及超过配置限制的应用程序的工作负载，该限制通常适用于几乎所有的SQLAlchemy应用程序。

以下几点总结了这个错误的含义，从大多数SQLAlchemy用户应该已经熟悉的最基本的点开始。

默认情况下，SQLAlchemy引擎对象使用连接池 -这意味着当使用SQL数据库连接资源时， Engine 对象，然后 releases 这个资源，数据库连接本身仍然连接到数据库，并返回到一个内部队列，在那里可以再次使用它。即使代码似乎正在结束与数据库的对话，在许多情况下，应用程序仍将保持固定数量的数据库连接，这些连接将一直保持到应用程序结束或池被显式释放为止。
由于池的原因，当应用程序使用SQL数据库连接时，通常从使用 Engine.connect() 或使用ORM进行查询时 Session ，此活动不一定在获取连接对象时建立到数据库的新连接；而是为连接查询连接池，该连接通常从要重新使用的池中检索现有连接。如果没有可用的连接，池将创建一个新的数据库连接，但前提是池没有超过配置的容量。
在大多数情况下使用的默认池被调用 QueuePool . 当您要求此池为您提供一个连接但没有可用的连接时，它将创建一个新连接。 如果播放中的连接总数小于配置的值 . 该值等于 池大小加上最大溢出 . 这意味着如果您将引擎配置为：
```
engine = create_engine("mysql://u:p@host/db", pool_size=10, max_overflow=20)
```
以上 Engine 将允许 最多30个连接 可随时使用，不包括与发动机分离或失效的连接。如果一个新连接的请求到达，并且应用程序的其他部分已经使用了30个连接，那么在超时并引发此错误消息之前，连接池将阻塞一段固定的时间。
为了允许同时使用更多的连接，可以使用 create_engine.pool_size 和 create_engine.max_overflow 传递到的参数 create_engine() 功能。等待连接可用的超时使用 create_engine.pool_timeout 参数。
可以通过设置将池配置为具有无限制的溢出 create_engine.max_overflow 到值“-1”。使用此设置，池仍将保持固定的连接池，但是它不会在请求新连接时阻塞；相反，如果没有可用的连接，它将无条件创建新连接。
但是，以这种方式运行时，如果应用程序出现问题，即它正在耗尽所有可用的连接资源，则它最终将达到数据库本身配置的可用连接限制，这将再次返回错误。更严重的是，当应用程序耗尽连接数据库时，它通常会导致大量资源在失败之前耗尽，并且还会干扰其他依赖于能够连接到数据库的应用程序和数据库状态机制。
考虑到上述情况，可以将连接池视为 连接用安全阀 对恶意应用程序提供关键的保护层，导致整个数据库对所有其他应用程序不可用。当收到此错误消息时，最好使用过多的连接来修复问题和/或适当地配置限制，而不是允许不受限制的溢出，这实际上并不能解决基础问题。

是什么导致应用程序用尽所有可用的连接？

应用程序根据池的配置值部署了太多的并发请求，无法工作。 -这是最直接的原因。如果您有一个应用程序在一个线程池中运行，该线程池允许30个并发线程，每个线程使用一个连接，如果您的池没有配置为允许至少30个连接一次签出，那么一旦应用程序收到足够的并发请求，就会出现此错误。解决方案是提高池的限制或减少并发线程的数量。
应用程序没有返回到池的连接 -这是第二个最常见的原因，即应用程序正在使用连接池，但程序未能 release 这些连接，而不是让它们打开。连接池和ORM Session 一定要有这样的逻辑：当会话和/或连接对象被垃圾收集时，它会导致底层连接资源被释放，但是这种行为不能及时地释放资源。
出现这种情况的一个常见原因是应用程序使用ORM会话而不调用 Session.close() 在他们身上，涉及到那个会议的工作已经完成。解决方案是确保使用ORM或引擎绑定的ORM会话 Connection 如果使用core，则对象将在正在执行的工作结束时通过适当的 .close() 方法，或者使用一个可用的上下文管理器（例如“with：”语句）来正确释放资源。
The application is attempting to run long-running transactions -数据库事务是非常昂贵的资源，应该 永远不要在等待某个事件发生时处于空闲状态 . 如果应用程序正在等待用户按下按钮，或者结果从长时间运行的作业队列中出来，或者保持对浏览器的持久连接， 不要一直打开数据库事务 . 由于应用程序需要与数据库一起工作并与事件交互，因此在该点打开一个短期事务，然后关闭它。
应用程序死锁 -此外，此错误的一个常见原因是更难以理解，如果应用程序由于应用程序端死锁或数据库端死锁而无法完成连接的使用，则应用程序可以使用所有可用的连接，从而导致接收此错误的其他请求。僵局的原因包括：
- 使用隐式异步系统，如gevent或eventlet，而没有正确地对所有套接字库和驱动程序进行MonkeyPatching，或者在没有完全覆盖所有MonkeyPatching驱动程序方法方面存在缺陷，或者在异步系统用于CPU绑定的工作负载时不太常见，而使用数据库资源的greenlet只是在等待。太长时间不能照顾他们。隐式或显式异步编程框架对于绝大多数关系数据库操作都不是必需的或合适的；如果应用程序必须在某些功能领域使用异步系统，那么最好是在传统线程中运行面向数据库的业务方法，这些线程将消息传递给异步部分o。应用程序。
- 数据库端死锁，例如行相互死锁
- 线程错误，例如互斥锁中的互斥锁，或调用同一线程中已锁定的互斥锁

请记住，使用池的另一种选择是完全关闭池。见剖面图切换池实现作为背景。但是，请注意，当出现此错误消息时，总是由于应用程序本身存在更大的问题，池只是有助于更快地发现问题。

参见

连接池

使用引擎和接头

在回滚无效事务之前无法重新连接

此错误条件指的是 Connection 由于数据库断开连接检测或显式调用 Connection.invalidate() ，但仍存在由启动的事务 Connection.begin() 方法。当连接失效时，任何 Transaction 正在进行的进程现在处于无效状态，必须显式回滚才能将其从 Connection .

此连接处于非活动事务上。请在继续之前完全回滚（）。

从1.4版起，此错误条件已添加到sqlAlchemy中。错误指的是 Connection 使用类似于 Connection.begin() ，然后在该范围内创建另一个“标记”事务；然后使用 Transaction.rollback() 或关闭使用 Transaction.close() 但外部事务仍处于“非活动”状态，必须回滚。

图案如下：

engine = create_engine(...)

connection = engine.connect()
transaction1 = connection.begin()

# this is a "sub" or "marker" transaction, a logical nesting
# structure based on "real" transaction transaction1
transaction2 = connection.begin()
transaction2.rollback()

# transaction1 is still present and needs explicit rollback,
# so this will raise
connection.execute(text("select 1"))

上面， transaction2 是一个“marker”事务，它表示事务在外部事务中的逻辑嵌套；虽然内部事务可以通过其rollback（）方法回滚整个事务，但它的commit（）方法除了关闭“marker”事务本身的作用域外没有任何效果。号召 transaction2.rollback() 具有的效果 去激活 transaction1意味着它基本上是在数据库级别回滚的，但是为了适应一致的事务嵌套模式，它仍然存在。

正确的解决方案是确保外部事务也被回滚：

transaction1.rollback()

这种模式不常用于核心。在ORM中，类似的问题也可能发生，这是ORM的“逻辑”事务结构的产物；在 “由于在刷新过程中出现以前的异常，此会话的事务已回滚。”（或类似） .

在sqlalchemy2.0中将删除“subtransaction”模式，这样这个特定的编程模式将不再可用，并且这个错误消息也不再出现在Core中。

数据库应用程序接口错误

python数据库API（或dbapi）是一种数据库驱动程序规范，位于 Pep-249 . 此API指定了一组异常类，这些类可以适应数据库的所有故障模式。

SQLAlchemy不会直接生成这些异常。相反，它们是从数据库驱动程序截取的，并由SQLAlchemy提供的异常进行包装。 DBAPIError 但是，异常中的消息是 由驱动程序生成，而不是由sqlAlchemy生成 .