Сообщения об ошибках¶

Ограничение QueuePool размером <x> переполнение <y> достигнуто, соединение прервано, таймаут <z>¶

Это, возможно, самая распространенная ошибка времени выполнения, поскольку она напрямую связана с превышением рабочей нагрузки приложения над настроенным пределом, который обычно применяется почти ко всем приложениям SQLAlchemy.

Ниже кратко описано, что означает эта ошибка, начиная с самых основных моментов, с которыми большинство пользователей SQLAlchemy уже должны быть знакомы.

• ** Объект SQLAlchemy Engine по умолчанию использует пул соединений** - Это означает, что при использовании ресурса соединения с базой данных 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:»), чтобы правильно освободить ресурс.

• Приложение пытается выполнить длительные транзакции - Транзакция базы данных - это очень дорогой ресурс, и ее никогда не следует оставлять без дела в ожидании какого-либо события. Если приложение ждет, пока пользователь нажмет на кнопку, или результат выйдет из давно запущенной очереди заданий, или держит открытым постоянное соединение с браузером, не держите транзакцию базы данных открытой все это время. Когда приложению необходимо работать с базой данных и взаимодействовать с событием, откройте в этот момент короткоживущую транзакцию, а затем закройте ее.

• Приложение находится в тупике - Также распространенная причина этой ошибки и более сложная для понимания, если приложение не может завершить использование соединения либо из-за тупика со стороны приложения, либо со стороны базы данных, приложение может использовать все доступные соединения, что приводит к тому, что дополнительные запросы получают эту ошибку. Причины возникновения тупиковых ситуаций включают:

  • Использование неявной системы async, такой как gevent или eventlet, без надлежащего monkeypatching всех библиотек сокетов и драйверов, или в которой есть ошибки, не полностью покрывающие все monkeypatched методы драйверов, или, реже, когда система async используется против нагрузок на CPU, и greenlet, использующие ресурсы базы данных, просто ждут слишком долго, чтобы их обслужить. Ни неявные, ни явные рамки программирования async обычно не нужны и не подходят для подавляющего большинства операций с реляционными базами данных; если приложение должно использовать систему async для некоторой области функциональности, лучше всего, чтобы бизнес-методы, ориентированные на базу данных, выполнялись в традиционных потоках, которые передают сообщения в асинхронную часть приложения.

  • Тупик на стороне базы данных, например, строки взаимно заблокированы

  • Ошибки потоков, например, мьютексы во взаимном тупике или обращение к уже заблокированному мьютексу в том же потоке

Помните, что альтернативой использованию пулинга является полное отключение пулинга. См. раздел Реализации коммутационных пулов для получения информации об этом. Однако обратите внимание, что когда возникает это сообщение об ошибке, это всегда связано с более серьезной проблемой в самом приложении; пул просто помогает быстрее выявить проблему.

Невозможно восстановить соединение, пока не будет откачена недействительная транзакция¶

Это состояние ошибки относится к случаю, когда соединение Connection было аннулировано либо из-за обнаружения разъединения базы данных, либо из-за явного вызова Connection.invalidate(), но все еще присутствует транзакция, инициированная методом Connection.begin(). Когда соединение аннулируется, любая транзакция Transaction, которая находилась в процессе выполнения, теперь находится в недействительном состоянии и должна быть явно откатана, чтобы удалить ее из Connection.

InterfaceError¶

Исключение, возникающее при ошибках, связанных с интерфейсом базы данных, а не с самой базой данных.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

InterfaceError иногда поднимается драйверами в контексте разрыва соединения с базой данных или невозможности подключения к базе данных. Советы о том, как с этим справиться, см. в разделе Работа с разъединениями.

DatabaseError¶

Исключение, возникающее при ошибках, связанных с самой базой данных, а не с интерфейсом или передаваемыми данными.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

DataError¶

Исключение, возникающее при ошибках, связанных с проблемами в обрабатываемых данных, таких как деление на ноль, выход числового значения за пределы диапазона и т.д.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

OperationalError¶

Исключение, возникающее при ошибках, которые связаны с работой базы данных и не обязательно находятся под контролем программиста, например, происходит неожиданное отключение, имя источника данных не найдено, транзакция не может быть обработана, во время обработки произошла ошибка выделения памяти и т.д.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

OperationalError - это наиболее распространенный (но не единственный) класс ошибок, используемый драйверами в контексте разрыва соединения с базой данных или невозможности подключения к базе данных. Советы о том, как с этим справиться, см. в разделе Работа с разъединениями.

IntegrityError¶

Исключение, возникающее при нарушении реляционной целостности базы данных, например, при неудачной проверке внешнего ключа.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

InternalError¶

Исключение, возникающее, когда база данных сталкивается с внутренней ошибкой, например, курсор больше не действителен, транзакция рассинхронизирована и т.д.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

InternalError иногда поднимается драйверами в контексте разрыва соединения с базой данных или невозможности подключения к базе данных. Советы о том, как с этим справиться, см. в разделе Работа с разъединениями.

ProgrammingError¶

Исключение, возникающее при ошибках программирования, например, таблица не найдена или уже существует, синтаксическая ошибка в SQL-запросе, неверно указано количество параметров и т.д.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

ProgrammingError иногда поднимается драйверами в контексте разрыва соединения с базой данных или невозможности подключения к базе данных. Советы о том, как с этим справиться, см. в разделе Работа с разъединениями.

NotSupportedError¶

Исключение, возникающее в случае использования метода или API базы данных, который не поддерживается базой данных, например, запрос .rollback() на соединении, которое не поддерживает транзакцию или транзакции отключены.

Эта ошибка имеет вид DBAPI Error и исходит от драйвера базы данных (DBAPI), а не от самой SQLAlchemy.

Объект не будет создавать ключ кэша, Последствия для производительности¶

SQLAlchemy начиная с версии 1.4 включает SQL compilation caching facility, который позволяет конструкциям Core и ORM SQL кэшировать их строковую форму вместе с другой структурной информацией, используемой для получения результатов из оператора, что позволяет пропустить относительно дорогостоящий процесс компиляции строки при следующем использовании структурно эквивалентной конструкции. Эта система полагается на функциональность, реализованную для всех конструкций SQL, включая такие объекты, как Column, select() и TypeEngine, чтобы создать ключ кэша, который полностью представляет их состояние в той степени, в которой оно влияет на процесс компиляции SQL.

Если предупреждения относятся к широко используемым объектам, таким как объекты Column, и показано, что они влияют на большинство используемых конструкций SQL (с использованием методов оценки, описанных в Оценка производительности кэша с помощью протоколирования) так, что кэширование обычно не включено для приложения, это негативно скажется на производительности и в некоторых случаях может привести к ухудшению производительности по сравнению с предыдущими версиями SQLAlchemy. Подробнее об этом говорится в FAQ по адресу Почему мое приложение работает медленно после обновления до 1.4 и/или 2.x?.

Компилятор StrSQLCompiler не может вывести элемент типа <тип элемента>¶

Эта ошибка обычно возникает при попытке структурировать конструкцию SQL-выражения, которая включает элементы, не являющиеся частью компиляции по умолчанию; в этом случае ошибка будет относиться к классу StrSQLCompiler. В менее распространенных случаях она также может возникнуть, когда неправильный тип SQL-выражения используется с определенным типом бэкенда базы данных; в этих случаях будут названы другие типы классов компилятора SQL, такие как SQLCompiler или sqlalchemy.dialects.postgresql.PGCompiler. Приведенное ниже руководство в большей степени относится к случаю использования «стрингизации», но описывает и общие предпосылки.

Обычно конструкцию Core SQL или объект ORM Query можно строчить напрямую, например, когда мы используем print():

>>> from sqlalchemy import column
>>> print(column("x") == 5)
x = :x_1

Когда приведенное выше выражение SQL строится, используется класс компилятора StrSQLCompiler, который представляет собой специальный компилятор операторов, вызываемый, когда конструкция строится без какой-либо информации, специфичной для диалекта.

Однако существует множество конструкций, специфичных для определенного диалекта базы данных, для которых StrSQLCompiler не знает, как превратить в строку, например, конструкция PostgreSQL «insert on conflict»:

>>> from sqlalchemy.dialects.postgresql import insert
>>> from sqlalchemy import table, column
>>> my_table = table("my_table", column("x"), column("y"))
>>> insert_stmt = insert(my_table).values(x="foo")
>>> insert_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["y"])
>>> print(insert_stmt)
Traceback (most recent call last):

...

sqlalchemy.exc.UnsupportedCompilationError:
Compiler <sqlalchemy.sql.compiler.StrSQLCompiler object at 0x7f04fc17e320>
can't render element of type
<class 'sqlalchemy.dialects.postgresql.dml.OnConflictDoNothing'>

Чтобы строчить конструкции, характерные для конкретного бэкенда, необходимо использовать метод ClauseElement.compile(), передавая либо Engine, либо Dialect объект, который вызовет нужный компилятор. Ниже мы используем диалект PostgreSQL:

>>> from sqlalchemy.dialects import postgresql
>>> print(insert_stmt.compile(dialect=postgresql.dialect()))
INSERT INTO my_table (x) VALUES (%(x)s) ON CONFLICT (y) DO NOTHING

Для объекта ORM Query к утверждению можно получить доступ, используя аксессор Query.statement:

statement = query.statement
print(statement.compile(dialect=postgresql.dialect()))

Дополнительную информацию о прямой структуризации / компиляции элементов SQL см. по ссылке FAQ ниже.

TypeError: <оператор> не поддерживается между экземплярами „ColumnProperty“ и <что-то>¶

Это часто происходит при попытке использовать объект column_property() или deferred() в контексте выражения SQL, обычно в декларативных выражениях типа:

class Bar(Base):
    __tablename__ = "bar"

    id = Column(Integer, primary_key=True)
    cprop = deferred(Column(Integer))

    __table_args__ = (CheckConstraint(cprop > 5),)

Выше, атрибут cprop используется в строке до того, как он был отображен, однако этот атрибут cprop не является Column, это ColumnProperty, который является промежуточным объектом и поэтому не имеет полной функциональности ни объекта Column, ни объекта InstrumentedAttribute, которые будут отображены на класс Bar после завершения декларативного процесса.

Хотя у ColumnProperty есть метод __clause_element__(), что позволяет ему работать в некоторых контекстах, ориентированных на столбцы, он не может работать в контексте открытого сравнения, как показано выше, поскольку у него нет метода Python __eq__(), который позволил бы ему интерпретировать сравнение с числом «5» как выражение SQL, а не как обычное сравнение Python.

Решением является прямой доступ к Column с помощью атрибута ColumnProperty.expression:

class Bar(Base):
    __tablename__ = "bar"

    id = Column(Integer, primary_key=True)
    cprop = deferred(Column(Integer))

    __table_args__ = (CheckConstraint(cprop.expression > 5),)

Требуется значение для параметра привязки <x> (в группе параметров <y>)¶

Эта ошибка возникает, когда оператор использует bindparam() либо неявно, либо явно и не предоставляет значения при выполнении оператора:

stmt = select(table.c.column).where(table.c.id == bindparam("my_param"))

result = conn.execute(stmt)

Выше не было указано значение для параметра «my_param». Правильным подходом является предоставление значения:

result = conn.execute(stmt, my_param=12)

Если сообщение имеет вид «требуется значение для параметра привязки <x> в группе параметров <y>», это сообщение относится к стилю выполнения «executemany». В этом случае оператор обычно представляет собой INSERT, UPDATE или DELETE и передается список параметров. В этом формате оператор может генерироваться динамически, чтобы включить позиции параметров для каждого параметра, указанного в списке аргументов, где он будет использовать первый набор параметров, чтобы определить, какими они должны быть.

Например, приведенный ниже оператор рассчитывается на основе первого набора параметров, чтобы потребовать параметры, «a», «b» и «c» - эти имена определяют окончательный строковый формат оператора, который будет использоваться для каждого набора параметров в списке. Поскольку вторая запись не содержит «b», генерируется такая ошибка:

m = MetaData()
t = Table(
    't', m,
    Column('a', Integer),
    Column('b', Integer),
    Column('c', Integer)
)

e.execute(
    t.insert(), [
        {"a": 1, "b": 2, "c": 3},
        {"a": 2, "c": 4},
        {"a": 3, "b": 4, "c": 5},
    ]
)

sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError)
A value is required for bind parameter 'b', in parameter group 1
[SQL: u'INSERT INTO t (a, b, c) VALUES (?, ?, ?)']
[parameters: [{'a': 1, 'c': 3, 'b': 2}, {'a': 2, 'c': 4}, {'a': 3, 'c': 5, 'b': 4}]]

Поскольку требуется «b», передайте его как None, чтобы INSERT можно было продолжить:

e.execute(
    t.insert(),
    [
        {"a": 1, "b": 2, "c": 3},
        {"a": 2, "b": None, "c": 4},
        {"a": 3, "b": 4, "c": 5},
    ],
)

Ожидался пункт FROM, а получился Select. Чтобы создать предложение FROM, используйте метод .subquery()¶

Это относится к изменению, внесенному в SQLAlchemy 1.4, когда оператор SELECT, сгенерированный такой функцией, как select(), но также включающий такие вещи, как союзы и текстовые выражения SELECT, больше не считается объектом FromClause и не может быть помещен непосредственно в предложение FROM другого оператора SELECT без предварительного обертывания в Subquery. Это серьезное концептуальное изменение в Core, и полное обоснование обсуждается в A SELECT statement is no longer implicitly considered to be a FROM clause.

Приведем пример:

m = MetaData()
t = Table("t", m, Column("a", Integer), Column("b", Integer), Column("c", Integer))
stmt = select(t)

Выше stmt представляет собой оператор SELECT. Ошибка возникает, когда мы хотим использовать stmt непосредственно как предложение FROM в другом SELECT, например, если мы попытаемся выбрать из него:

new_stmt_1 = select(stmt)

Или если бы мы хотели использовать его в предложении FROM, например, в JOIN:

new_stmt_2 = select(some_table).select_from(some_table.join(stmt))

В предыдущих версиях SQLAlchemy при использовании SELECT внутри другого SELECT получался безымянный подзапрос, заключенный в круглые скобки. В большинстве случаев такая форма SQL не очень полезна, поскольку такие базы данных, как MySQL и PostgreSQL, требуют, чтобы подзапросы в предложениях FROM имели именованные псевдонимы, что означает использование метода SelectBase.alias() или, начиная с версии 1.4, метода SelectBase.subquery(). В других базах данных подзапрос должен иметь имя, чтобы устранить любую двусмысленность в будущих ссылках на имена столбцов внутри подзапроса.

Помимо вышеуказанных практических причин, существует множество других, ориентированных на SQLAlchemy, причин, по которым вносится это изменение. Поэтому правильная форма двух вышеприведенных утверждений требует использования SelectBase.subquery():

subq = stmt.subquery()

new_stmt_1 = select(subq)

new_stmt_2 = select(some_table).select_from(some_table.join(subq))

Для элемента raw clauseelement автоматически создается псевдоним¶

Это предупреждение об устаревании относится к очень старому и, вероятно, не очень известному шаблону, который применяется к унаследованному методу Query.join(), а также к методу 2.0 style Select.join(), где соединение может быть указано в терминах relationship(), но целью является Table или другой Core selectable, к которому сопоставлен класс, а не ORM-сущность, такая как сопоставленный класс или aliased() конструкция:

a1 = Address.__table__

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

Приведенный выше шаблон также позволяет произвольно выбирать, например, объект Core 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")

Псевдоним создается автоматически из-за перекрытия таблиц¶

Это предупреждение обычно выдается при запросе с использованием метода Select.join() или унаследованного метода Query.join() с отображениями, включающими объединенное наследование таблиц. Проблема заключается в том, что при соединении двух моделей наследования, имеющих общую базовую таблицу, правильное SQL JOIN между двумя сущностями не может быть сформировано без применения псевдонима к одной или другой стороне; 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 выбирает FROM таблицу employee, представляющую сущность Employee в запросе. Затем он присоединяется к право-вложенному соединению employee AS employee_1 JOIN manager AS manager_1, где снова указывается таблица employee, только в качестве анонимного псевдонима employee_1. Это и есть «автоматическое создание псевдонима», на которое ссылается предупреждающее сообщение.

Когда SQLAlchemy загружает строки 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 осуществляет «автоалиасинг» в очень вложенном контексте. Поэтому лучше не полагаться на эту возможность и вместо этого сделать конструкцию SQL как можно более явной.

Родительский экземпляр <x> не привязан к сессии; (ленивая загрузка/отложенная загрузка/обновление/и т.д.) операция не может быть выполнена¶

Это, вероятно, самое распространенное сообщение об ошибке при работе с ORM, и возникает оно в результате природы техники, широко используемой ORM, известной как lazy loading. Ленивая загрузка - это распространенный объектно-реляционный паттерн, при котором объект, сохраняемый ORM, поддерживает прокси к базе данных, так что при обращении к различным атрибутам объекта их значения могут быть получены из базы данных лениво. Преимуществом такого подхода является то, что объекты могут быть извлечены из базы данных без необходимости загрузки всех их атрибутов или связанных с ними данных сразу, а вместо этого только те данные, которые запрашиваются, могут быть доставлены в это время. Основной недостаток, по сути, является зеркальным отражением преимущества: если загружается множество объектов, для которых, как известно, во всех случаях требуется определенный набор данных, то загружать эти дополнительные данные по частям будет расточительно.

Еще одним недостатком ленивой загрузки, помимо обычных проблем эффективности, является то, что для продолжения ленивой загрузки объект должен оставаться связанным с сессией, чтобы можно было получить его состояние. Это сообщение об ошибке означает, что объект отсоединился от своего Session и его просят лениво загрузить данные из базы данных.

Наиболее распространенной причиной того, что объекты отделяются от своих Session, является закрытие сессии, обычно с помощью метода Session.close(). В дальнейшем к объектам будет осуществляться дальнейший доступ, очень часто в веб-приложениях, где они передаются серверному шаблонизатору и запрашиваются дополнительные атрибуты, которые он не может загрузить.

Устранение этой ошибки осуществляется с помощью следующих приемов:

• Постарайтесь не иметь отсоединенных объектов; не закрывайте сессию преждевременно - Часто приложения закрывают транзакцию перед передачей связанных с ней объектов другой системе, которая затем выходит из строя из-за этой ошибки. Иногда транзакцию не нужно закрывать так скоро; пример - веб-приложение закрывает транзакцию до того, как представление будет отображено. Это часто делается во имя «корректности», но может рассматриваться как неправильное применение «инкапсуляции», поскольку этот термин относится к организации кода, а не к фактическим действиям. Шаблон, использующий объект ORM, использует proxy pattern, который сохраняет логику базы данных инкапсулированной от вызывающей стороны. Если Session можно держать открытым до тех пор, пока не закончится жизнь объектов, это лучший подход.

• В противном случае загружайте все необходимое заранее - Очень часто невозможно держать транзакцию открытой, особенно в более сложных приложениях, которым необходимо передавать объекты другим системам, которые не могут работать в том же контексте, даже если они находятся в том же процессе. В этом случае приложение должно подготовиться к работе с объектами detached и попытаться использовать eager loading для обеспечения того, чтобы объекты имели все необходимое заранее.

• А главное, установите expire_on_commit в False - При использовании отсоединенных объектов наиболее частой причиной того, что объекты нуждаются в повторной загрузке данных, является истечение срока их действия после последнего вызова Session.commit(). Это истечение не должно использоваться при работе с отсоединенными объектами; поэтому параметр Session.expire_on_commit должен быть установлен в False. Предотвращая истечение срока действия объектов вне транзакции, данные, которые были загружены, останутся в наличии и не будут подвергаться дополнительной ленивой загрузке при обращении к этим данным.

  Обратите также внимание, что метод Session.rollback() безоговорочно уничтожает все содержимое в Session и его также следует избегать в сценариях, не связанных с ошибками.

  См.также

  Техники загрузки отношений - подробная документация по нетерпеливой загрузке и другим техникам загрузки, ориентированным на отношения

  Совершение - фон для фиксации сессии

  Обновление / истечение срока действия - информация об истечении срока действия атрибута

Транзакция этого сеанса была откатана из-за предыдущего исключения во время flush¶

Процесс flush в Session, описанный в Промывка, откатит транзакцию базы данных, если возникнет ошибка, для поддержания внутренней согласованности. Однако, как только это происходит, транзакция сессии становится «неактивной» и должна быть явно откачена вызывающим приложением, точно так же, как если бы не произошел сбой, ее нужно было бы явно зафиксировать.

Это распространенная ошибка при использовании ORM и обычно относится к приложению, которое еще не имеет правильного «обрамления» вокруг своих операций Session. Более подробная информация описана в FAQ по адресу «Транзакция этого сеанса была откатана из-за предыдущего исключения во время промывки». (или аналогично).

Для отношения <relationship> каскад delete-orphan обычно настраивается только на стороне «один» отношения один-ко-многим, но не на стороне «многие» отношения многие-к-одному или многие-ко-многим.¶

Эта ошибка возникает, когда параметр «delete-orphan» cascade установлен для отношения «многие-к-одному» или «многие-ко-многим», например:

class A(Base):
    __tablename__ = "a"

    id = Column(Integer, primary_key=True)

    bs = relationship("B", back_populates="a")


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)
    a_id = Column(ForeignKey("a.id"))

    # this will emit the error message when the mapper
    # configuration step occurs
    a = relationship("A", back_populates="bs", cascade="all, delete-orphan")


configure_mappers()

Выше, параметр «delete-orphan» для B.a указывает на намерение, что когда каждый объект B, ссылающийся на определенный A, удаляется, то A также должен быть удален. То есть, это выражает, что «сирота», который удаляется, будет объектом A, и он становится «сиротой», когда каждый B, который ссылается на него, удаляется.

Каскадная модель «delete-orphan» не поддерживает эту функциональность. Рассмотрение «сирот» производится только с точки зрения удаления одного объекта, который затем будет ссылаться на ноль или более объектов, которые теперь «осиротеют» в результате этого единственного удаления, что приведет к тому, что эти объекты также будут удалены. Другими словами, он предназначен только для отслеживания создания «сирот» на основе удаления одного и только одного «родительского» объекта на каждого сироту, что является естественным случаем в отношениях «один ко многим», когда удаление объекта на стороне «один» приводит к последующему удалению связанных с ним объектов на стороне «многие».

Приведенное выше отображение для поддержки этой функциональности вместо этого поместило бы параметр каскада на сторону «один-ко-многим», что выглядит следующим образом:

class A(Base):
    __tablename__ = "a"

    id = Column(Integer, primary_key=True)

    bs = relationship("B", back_populates="a", cascade="all, delete-orphan")


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)
    a_id = Column(ForeignKey("a.id"))

    a = relationship("A", back_populates="bs")

Если выражено намерение, что при удалении объекта A все объекты B, на которые он ссылается, также удаляются.

Далее в сообщении об ошибке предлагается использовать флаг relationship.single_parent. Этот флаг может быть использован для того, чтобы гарантировать, что отношение, которое может иметь много объектов, ссылающихся на определенный объект, на самом деле будет иметь только один объект, ссылающийся на него в одно время. Он используется для унаследованных или других менее идеальных схем баз данных, где отношения внешних ключей предполагают наличие «многих» коллекций, однако на практике только один объект будет фактически ссылаться на данный целевой объект в одно и то же время. Этот нестандартный сценарий можно продемонстрировать в терминах приведенного выше примера следующим образом:

class A(Base):
    __tablename__ = "a"

    id = Column(Integer, primary_key=True)

    bs = relationship("B", back_populates="a")


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)
    a_id = Column(ForeignKey("a.id"))

    a = relationship(
        "A",
        back_populates="bs",
        single_parent=True,
        cascade="all, delete-orphan",
    )

Приведенная выше конфигурация установит валидатор, который будет следить за тем, чтобы только один B мог быть связан с A одновременно в рамках отношения B.a:

>>> b1 = B()
>>> b2 = B()
>>> a1 = A()
>>> b1.a = a1
>>> b2.a = a1
sqlalchemy.exc.InvalidRequestError: Instance <A at 0x7eff44359350> is
already associated with an instance of <class '__main__.B'> via its
B.a attribute, and is only allowed a single parent.

Обратите внимание, что этот валидатор имеет ограниченную область применения и не предотвратит создание нескольких «родителей» в другом направлении. Например, он не обнаружит одинаковые установки в терминах A.bs:

>>> a1.bs = [b1, b2]
>>> session.add_all([a1, b1, b2])
>>> session.commit()
INSERT INTO a DEFAULT VALUES
()
INSERT INTO b (a_id) VALUES (?)
(1,)
INSERT INTO b (a_id) VALUES (?)
(1,)

Однако в дальнейшем все пойдет не так, как ожидалось, поскольку каскад «delete-orphan» будет продолжать работать в терминах одного ведущего объекта, то есть если мы удалим любой из B объектов, то A будет удален. Другой B останется, и ORM обычно достаточно умна, чтобы установить атрибут внешнего ключа в NULL, но это обычно не то, что нужно:

>>> session.delete(b1)
>>> session.commit()
UPDATE b SET a_id=? WHERE b.id = ?
(None, 2)
DELETE FROM b WHERE b.id = ?
(1,)
DELETE FROM a WHERE a.id = ?
(1,)
COMMIT

Для всех вышеприведенных примеров аналогичная логика применима к вычислению отношений «многие-ко-многим»; если отношения «многие-ко-многим» устанавливают single_parent=True на одной стороне, эта сторона может использовать каскад «delete-orphan», однако это очень маловероятно, что кто-то действительно хочет этого, так как смысл отношений «многие-ко-многим» заключается в том, что может быть много объектов, ссылающихся на объект в любом направлении.

В целом, каскад «удаление-сирота» обычно применяется на «одной» стороне отношения «один-ко-многим» так, чтобы удалять объекты на «многих» сторонах, а не наоборот.

Экземпляр <instance> уже связан с экземпляром <instance> через его атрибут <attribute>, и ему разрешено иметь только одного родителя.¶

Эта ошибка возникает, когда используется флаг relationship.single_parent, и в качестве «родителя» объекта назначается сразу несколько объектов.

Учитывая следующее отображение:

class A(Base):
    __tablename__ = "a"

    id = Column(Integer, primary_key=True)


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)
    a_id = Column(ForeignKey("a.id"))

    a = relationship(
        "A",
        single_parent=True,
        cascade="all, delete-orphan",
    )

Намерение указывает, что не более одного объекта B может одновременно ссылаться на определенный объект A:

>>> b1 = B()
>>> b2 = B()
>>> a1 = A()
>>> b1.a = a1
>>> b2.a = a1
sqlalchemy.exc.InvalidRequestError: Instance <A at 0x7eff44359350> is
already associated with an instance of <class '__main__.B'> via its
B.a attribute, and is only allowed a single parent.

Когда эта ошибка возникает неожиданно, обычно это происходит потому, что флаг relationship.single_parent был применен в ответ на сообщение об ошибке, описанное в Для отношения <relationship> каскад delete-orphan обычно настраивается только на стороне «один» отношения один-ко-многим, но не на стороне «многие» отношения многие-к-одному или многие-ко-многим., и проблема на самом деле заключается в неправильном понимании настройки каскада «delete-orphan». Подробности см. в этом сообщении.

отношение X скопирует столбец Q в столбец P, что противоречит отношению(ям): „Y“¶

Это предупреждение относится к случаю, когда два или более отношения будут записывать данные в одни и те же столбцы на флеше, но ORM не имеет никаких средств для координации этих отношений вместе. В зависимости от специфики, решение может заключаться в том, что два отношения должны быть направлены друг к другу с помощью relationship.back_populates, или что одно или несколько отношений должны быть сконфигурированы с relationship.viewonly для предотвращения конфликтующих записей, или иногда, что конфигурация полностью преднамеренна и должна быть сконфигурирована relationship.overlaps, чтобы заглушить каждое предупреждение.

Для типичного примера, в котором отсутствует relationship.back_populates, учитывая следующее отображение:

class Parent(Base):
    __tablename__ = "parent"
    id = Column(Integer, primary_key=True)
    children = relationship("Child")


class Child(Base):
    __tablename__ = "child"
    id = Column(Integer, primary_key=True)
    parent_id = Column(ForeignKey("parent.id"))
    parent = relationship("Parent")

Приведенное выше отображение будет генерировать предупреждения:

SAWarning: relationship 'Child.parent' will copy column parent.id to column child.parent_id,
which conflicts with relationship(s): 'Parent.children' (copies parent.id to child.parent_id).

Отношения Child.parent и Parent.children находятся в конфликте. Решением является применение relationship.back_populates:

class Parent(Base):
    __tablename__ = "parent"
    id = Column(Integer, primary_key=True)
    children = relationship("Child", back_populates="parent")


class Child(Base):
    __tablename__ = "child"
    id = Column(Integer, primary_key=True)
    parent_id = Column(ForeignKey("parent.id"))
    parent = relationship("Parent", back_populates="children")

Для более настраиваемых отношений, где ситуация «перекрытия» может быть преднамеренной и не может быть разрешена, параметр relationship.overlaps может указывать имена отношений, для которых предупреждение не должно действовать. Обычно это происходит для двух или более отношений к одной и той же базовой таблице, которые включают пользовательские условия relationship.primaryjoin, ограничивающие связанные элементы в каждом случае:

class Parent(Base):
    __tablename__ = "parent"
    id = Column(Integer, primary_key=True)
    c1 = relationship(
        "Child",
        primaryjoin="and_(Parent.id == Child.parent_id, Child.flag == 0)",
        backref="parent",
        overlaps="c2, parent",
    )
    c2 = relationship(
        "Child",
        primaryjoin="and_(Parent.id == Child.parent_id, Child.flag == 1)",
        overlaps="c1, parent",
    )


class Child(Base):
    __tablename__ = "child"
    id = Column(Integer, primary_key=True)
    parent_id = Column(ForeignKey("parent.id"))

    flag = Column(Integer)

Выше, ORM будет знать, что перекрытие между Parent.c1, Parent.c2 и Child.parent является намеренным.

Объект не может быть преобразован в «постоянное» состояние, так как эта карта идентификации больше не действительна.¶

Это сообщение было добавлено, чтобы учесть случай, когда объект Result, который мог бы выдать объекты ORM, итерируется после того, как исходный Session был закрыт или иным образом был вызван его метод Session.expunge_all(). Когда Session изгоняет все объекты сразу, внутренний identity map, используемый этим Session, заменяется новым, а исходный отбрасывается. Непоглощенный и небуферизованный объект Result будет внутренне поддерживать ссылку на эту удаленную карту идентичности. Поэтому, когда Result будет потреблен, объекты, которые будут получены, не смогут быть связаны с этим Session. Такая схема предусмотрена, поскольку обычно не рекомендуется итерировать небуферизованный объект Result вне транзакционного контекста, в котором он был создан:

# context manager creates new Session
with Session(engine) as session_obj:
    result = sess.execute(select(User).where(User.id == 7))

# context manager is closed, so session_obj above is closed, identity
# map is replaced

# iterating the result object can't associate the object with the
# Session, raises this error.
user = result.first()

Приведенная выше ситуация обычно **не ** возникает при использовании расширения asyncio ORM, поскольку когда AsyncSession возвращает синхронизированный Result, результаты были предварительно забуферизированы во время выполнения оператора. Это сделано для того, чтобы вторичные нетерпеливые загрузчики могли вызываться без необходимости дополнительного вызова await.

Для предварительной буферизации результатов в описанной выше ситуации с помощью обычного Session так же, как это делает расширение asyncio, можно использовать опцию выполнения prebuffer_rows следующим образом:

# context manager creates new Session
with Session(engine) as session_obj:

    # result internally pre-fetches all objects
    result = sess.execute(
        select(User).where(User.id == 7), execution_options={"prebuffer_rows": True}
    )

# context manager is closed, so session_obj above is closed, identity
# map is replaced

# pre-buffered objects are returned
user = result.first()

# however they are detached from the session, which has been closed
assert inspect(user).detached
assert inspect(user).session is None

Выше, выбранные объекты ORM полностью генерируются внутри блока session_obj, ассоциируются с session_obj и буферизируются внутри объекта Result для итерации. За пределами блока session_obj закрывается и удаляет эти объекты ORM. Итерация объекта Result приведет к появлению этих ORM-объектов, однако, поскольку их исходный Session был исключен, они будут доставлены в состоянии detached.

AwaitRequired¶

Асинхронный режим SQLAlchemy требует использования асинхронного драйвера для подключения к базе данных. Эта ошибка обычно возникает при попытке использовать асинхронную версию SQLAlchemy с несовместимым DBAPI.

MissingGreenlet¶

Вызов async DBAPI был инициирован вне контекста спавна гринлета, обычно устанавливаемого прокси-классами SQLAlchemy AsyncIO. Обычно эта ошибка возникает, когда ввод-вывод был предпринят в неожиданном месте, без использования предоставленного async api. При использовании ORM это может быть связано с попыткой ленивой загрузки, которая не поддерживается при использовании SQLAlchemy с диалектами AsyncIO.

Осмотр не доступен¶

Использование функции inspect() непосредственно на объекте AsyncConnection или AsyncEngine в настоящее время не поддерживается, поскольку еще не существует ожидаемой формы объекта Inspector. Вместо этого объект используется путем его получения с помощью функции inspect() таким образом, что она ссылается на базовый атрибут AsyncConnection.sync_connection объекта AsyncConnection; затем объект Inspector используется в «синхронном» стиле вызова с помощью метода AsyncConnection.run_sync() вместе с пользовательской функцией, выполняющей нужные операции:

async def async_main():
    async with engine.connect() as conn:
        tables = await conn.run_sync(
            lambda sync_conn: inspect(sync_conn).get_table_names()
        )

Функция <somome function> в SQLAlchemy 2.0 больше не будет <something¶

SQLAlchemy 2.0 представляет собой значительные изменения для широкого спектра ключевых моделей использования SQLAlchemy в компонентах Core и ORM. Цель релиза 2.0 - внести небольшие изменения в некоторые из наиболее фундаментальных предположений SQLAlchemy с момента ее зарождения и предоставить новую оптимизированную модель использования, которая, как ожидается, будет значительно более минималистичной и последовательной между компонентами Core и ORM, а также более функциональной.

Представленный в Переход на SQLAlchemy 2.0, проект SQLAlchemy 2.0 включает в себя комплексную систему будущей совместимости, интегрированную в серию SQLAlchemy 1.4, благодаря которой приложения будут иметь четкий, однозначный и постепенный путь обновления, чтобы перевести приложения на полную совместимость с 2.0. Предупреждение об устаревании RemovedIn20Warning лежит в основе этой системы, чтобы предоставить рекомендации о том, какое поведение в существующей кодовой базе необходимо изменить. Обзор того, как включить это предупреждение, находится в SQLAlchemy 2.0 Deprecations Mode.

Объект объединяется в сессию по каскаду обратных ссылок¶

Это сообщение относится к поведению «каскада обратных ссылок» в SQLAlchemy, удаленному в версии 2.0. Это относится к действию, когда объект добавляется в Session в результате того, что другой объект, который уже присутствует в этой сессии, ассоциируется с ним. Поскольку было показано, что такое поведение больше запутывает, чем помогает, были добавлены параметры relationship.cascade_backrefs и backref.cascade_backrefs, которые можно установить в False, чтобы отключить его, а в SQLAlchemy 2.0 поведение «каскадных обратных ссылок» было полностью удалено.

Для старых версий SQLAlchemy, чтобы установить relationship.cascade_backrefs в False на обратную ссылку, которая в настоящее время настроена с помощью строкового параметра relationship.backref, обратная ссылка должна быть сначала объявлена с помощью функции backref(), чтобы можно было передать параметр backref.cascade_backrefs.

В качестве альтернативы, все поведение «каскадных обратных ссылок» можно отключить, используя Session в режиме «будущего», передавая True для параметра Session.future.

конструкция select(), созданная в «унаследованном» режиме; аргументы ключевых слов и т.д.¶

Конструкция select() была обновлена в SQLAlchemy 1.4 для поддержки нового стиля вызова, который является стандартным в SQLAlchemy 2.0. Для обратной совместимости в рамках серии 1.4 конструкция принимает аргументы как в «старом», так и в «новом» стиле.

Особенностью «нового» стиля является то, что выражения столбцов и таблиц передаются только позиционно в конструкцию select(); любые другие модификаторы объекта должны передаваться с помощью последующей цепочки методов:

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

Для сравнения, 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.

Привязка была найдена через унаследованные метаданные привязки, но поскольку для этой сессии установлено future=True, эта привязка игнорируется.¶

Концепция «связанных метаданных» присутствует вплоть до версии SQLAlchemy 1.4; начиная с версии 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.

Этот скомпилированный объект не привязан ни к одному движку или соединению¶

Эта ошибка связана с концепцией «связанных метаданных», которая является унаследованным шаблоном SQLAlchemy, присутствующим только в версиях 1.x. Проблема возникает, когда вызывается метод Executable.execute() непосредственно из объекта выражения Core, который не связан ни с каким Engine:

metadata_obj = MetaData()
table = Table("t", metadata_obj, Column("q", Integer))

stmt = select(table)
result = stmt.execute()  # <--- raises

Логика ожидает, что объект MetaData был связан с объектом Engine:

engine = create_engine("mysql+pymysql://user:pass@host/db")
metadata_obj = MetaData(bind=engine)

Там, где указано выше, любое утверждение, вытекающее из Table, которое в свою очередь вытекает из MetaData, будет неявно использовать данное Engine для вызова утверждения.

Обратите внимание, что концепция связанных метаданных отсутствует в SQLAlchemy 2.0. Правильный способ вызова утверждений - через метод Connection.execute() в Connection:

with engine.connect() as conn:
    result = conn.execute(stmt)

При использовании ORM аналогичная возможность доступна через Session:

result = session.execute(stmt)

Это соединение находится в неактивной транзакции. Пожалуйста, выполните полный откат(), прежде чем продолжить¶

Это состояние ошибки было добавлено в SQLAlchemy начиная с версии 1.4 и не относится к SQLAlchemy 2.0. Ошибка относится к состоянию, когда транзакция 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 - это «маркерная» транзакция, которая указывает на логическую вложенность транзакций внутри внешней транзакции; в то время как внутренняя транзакция может откатить всю транзакцию через свой метод rollback(), ее метод commit() не имеет никакого эффекта, кроме закрытия области действия самой «маркерной» транзакции. Вызов transaction2.rollback() имеет эффект деактивации транзакции1, что означает ее откат на уровне базы данных, однако она все еще присутствует, чтобы обеспечить последовательную схему вложенности транзакций.

Правильным решением является обеспечение отката внешней транзакции:

transaction1.rollback()

Этот шаблон не часто используется в Core. В ORM может возникнуть аналогичная проблема, которая является результатом «логической» структуры транзакций ORM; она описана в FAQ по адресу «Транзакция этого сеанса была откатана из-за предыдущего исключения во время промывки». (или аналогично).

Шаблон «субтранзакция» удален в SQLAlchemy 2.0, так что этот конкретный шаблон программирования больше не будет доступен, предотвращая появление этого сообщения об ошибке.