Что нового в SQLAlchemy 2.0?¶

Типизация выражений/выражений/наборов результатов SQL¶

В этом разделе представлены справочные материалы и примеры нового подхода SQLAlchemy к типизации выражений SQL, который распространяется от базовых конструкций ColumnElement через SQL-операторы и наборы результатов и переходит в сферу ORM-маппинга.

Декларативные модели ORM¶

В SQLAlchemy 1.4 впервые была реализована поддержка типизации в SQLAlchemy-родных ORM с использованием комбинации sqlalchemy2-stubs и Mypy Plugin. В SQLAlchemy 2.0 плагин Mypy остался доступным и был обновлен для работы с системой типизации SQLAlchemy 2.0. Однако теперь его следует считать устаревшим, так как теперь у приложений есть прямой путь к использованию новой поддержки типизации, не использующий плагины или заглушки.

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass

from sqlalchemy import Column
from sqlalchemy.orm import relationship
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user_account"

    id = Column(Integer, primary_key=True)
    name = Column(String(30), nullable=False)
    fullname = Column(String)
    addresses = relationship("Address", back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id = Column(Integer, primary_key=True)
    email_address = Column(String, nullable=False)
    user_id = Column(ForeignKey("user_account.id"), nullable=False)
    user = relationship("User", back_populates="addresses")

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user_account"

    id = mapped_column(Integer, primary_key=True)
    name = mapped_column(String(30), nullable=False)
    fullname = mapped_column(String)
    addresses = relationship("Address", back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id = mapped_column(Integer, primary_key=True)
    email_address = mapped_column(String, nullable=False)
    user_id = mapped_column(ForeignKey("user_account.id"), nullable=False)
    user = relationship("User", back_populates="addresses")

from typing import List
from typing import Optional
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user_account"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    name: Mapped[str] = mapped_column(String(30), nullable=False)
    fullname: Mapped[Optional[str]] = mapped_column(String)
    addresses: Mapped[List["Address"]] = relationship("Address", back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    email_address: Mapped[str] = mapped_column(String, nullable=False)
    user_id: Mapped[int] = mapped_column(ForeignKey("user_account.id"), nullable=False)
    user: Mapped["User"] = relationship("User", back_populates="addresses")

from typing import List
from typing import Optional
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user_account"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))
    fullname: Mapped[Optional[str]]
    addresses: Mapped[List["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id: Mapped[int] = mapped_column(primary_key=True)
    email_address: Mapped[str]
    user_id: Mapped[int] = mapped_column(ForeignKey("user_account.id"))
    user: Mapped["User"] = relationship(back_populates="addresses")

from typing_extensions import Annotated
from sqlalchemy.orm import DeclarativeBase

str50 = Annotated[str, 50]


# declarative base with a type-level override, using a type that is
# expected to be used in multiple places
class Base(DeclarativeBase):
    type_annotation_map = {
        str50: String(50),
    }

from typing_extensions import Annotated
from typing import List
from typing import Optional
from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship

# declarative base from previous example
str50 = Annotated[str, 50]


class Base(DeclarativeBase):
    type_annotation_map = {
        str50: String(50),
    }


# set up mapped_column() overrides, using whole column styles that are
# expected to be used in multiple places
intpk = Annotated[int, mapped_column(primary_key=True)]
user_fk = Annotated[int, mapped_column(ForeignKey("user_account.id"))]


class User(Base):
    __tablename__ = "user_account"

    id: Mapped[intpk]
    name: Mapped[str50]
    fullname: Mapped[Optional[str]]
    addresses: Mapped[List["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id: Mapped[intpk]
    email_address: Mapped[str50]
    user_id: Mapped[user_fk]
    user: Mapped["User"] = relationship(back_populates="addresses")

# (variable) stmt: Select[Tuple[int, str]]
stmt = select(User.id, User.name)

with Session(e) as sess:
    for row in sess.execute(stmt):
        # (variable) row: Row[Tuple[int, str]]
        print(row)

    # (variable) users: Sequence[User]
    users = sess.scalars(select(User)).all()

    # (variable) users_legacy: List[User]
    users_legacy = sess.query(User).all()

Использование унаследованных моделей Mypy-Typed¶

Приложения SQLAlchemy, использующие Mypy plugin с явными аннотациями, которые не используют Mapped в своих аннотациях, в новой системе подвержены ошибкам, поскольку такие аннотации помечаются как ошибочные при использовании таких конструкций, как relationship().

В разделе Миграция на 2.0 Шаг шестой - добавление __allow_unmapped__ в явно типизированные модели ORM показано, как временно запретить выдачу этих ошибок для унаследованной ORM-модели, использующей явные аннотации.

Встроенная поддержка классов данных, отображаемых как модели ORM¶

Новые декларативные возможности ORM, представленные выше в разделе Декларативные модели ORM, представили новую конструкцию mapped_column() и проиллюстрировали отображение, ориентированное на тип, с необязательным использованием PEP 593 Annotated. Мы можем сделать еще один шаг вперед, интегрировав отображение с Python dataclasses. Эта новая возможность стала возможной благодаря PEP 681, которая позволяет программам проверки типов распознавать классы, совместимые с dataclass, или полностью являющиеся dataclass, но объявленные с помощью альтернативных API.

При использовании функции dataclasses отображаемые классы получают метод __init__(), поддерживающий позиционные аргументы, а также настраиваемые значения по умолчанию для необязательных ключевых аргументов. Как уже упоминалось, классы данных также генерируют множество полезных методов, таких как __str__(), __eq__(). Такие методы сериализации классов данных, как dataclasses.asdict() и dataclasses.astuple(), также работают, но в настоящее время не учитывают самореферентные структуры, что делает их менее жизнеспособными для отображений, имеющих двунаправленные связи.

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

Для поддержки классов данных в соответствии с PEP 681 такие конструкции ORM, как mapped_column() и relationship(), принимают дополнительные PEP 681 аргументы init, default и default_factory, которые передаются в процессе создания класса данных. В настоящее время эти аргументы должны присутствовать в явной директиве в правой части, как и в случае с dataclasses.field(); в настоящее время они не могут быть локальными для конструкции Annotated в левой части. Для поддержки удобства использования Annotated при сохранении поддержки конфигурации классов данных, mapped_column() может объединять минимальный набор аргументов правой части с аргументами существующей конструкции mapped_column(), расположенной слева, внутри конструкции Annotated, что позволяет сохранить большую часть лаконичности, как будет показано ниже.

Для включения классов данных с использованием наследования классов мы используем миксин MappedAsDataclass либо непосредственно на каждом классе, либо на классе Base, как показано ниже, где мы дополнительно модифицируем пример отображения из «Шага 5» Декларативные модели ORM:

from typing_extensions import Annotated
from typing import List
from typing import Optional
from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import MappedAsDataclass
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(MappedAsDataclass, DeclarativeBase):
    """subclasses will be converted to dataclasses"""


intpk = Annotated[int, mapped_column(primary_key=True)]
str30 = Annotated[str, mapped_column(String(30))]
user_fk = Annotated[int, mapped_column(ForeignKey("user_account.id"))]


class User(Base):
    __tablename__ = "user_account"

    id: Mapped[intpk] = mapped_column(init=False)
    name: Mapped[str30]
    fullname: Mapped[Optional[str]] = mapped_column(default=None)
    addresses: Mapped[List["Address"]] = relationship(
        back_populates="user", default_factory=list
    )


class Address(Base):
    __tablename__ = "address"

    id: Mapped[intpk] = mapped_column(init=False)
    email_address: Mapped[str]
    user_id: Mapped[user_fk] = mapped_column(init=False)
    user: Mapped["User"] = relationship(back_populates="addresses", default=None)

Приведенное выше отображение использовало декоратор @dataclasses.dataclass непосредственно на каждом отображаемом классе одновременно с установкой декларативного отображения, внутренне устанавливая каждую директиву dataclasses.field(), как указано. <<<Конструкции User / Address могут быть созданы с использованием позиционных аргументов в соответствии с конфигурацией:

>>> u1 = User("username", fullname="full name", addresses=[Address("email@address")])
>>> u1
User(id=None, name='username', fullname='full name', addresses=[Address(id=None, email_address='email@address', user_id=None, user=...)])

Бенчмарки¶

SQLAlchemy включает в себя Performance Suite в каталоге examples/, где мы можем воспользоваться набором bulk_insert для бенчмарка INSERT’ов большого количества строк с использованием Core и ORM различными способами.

В приведенных ниже тестах мы вставляем 100 000 объектов, и во всех случаях в памяти находится 100 000 реальных объектов Python ORM, либо созданных заранее, либо сгенерированных на лету. Все базы данных, кроме SQLite, работают через локальное сетевое соединение, а не через localhost; это приводит к тому, что «более медленные» результаты оказываются чрезвычайно медленными.

К числу операций, которые улучшаются благодаря этой функции, относятся:

• единица работы прошивается для объектов, добавленных в сессию с помощью Session.add() и Session.add_all().

• Новая функция ORM Bulk Insert Statement, которая улучшает экспериментальную версию этой функции, впервые представленную в SQLAlchemy 1.4.

• «массовые» операции Session, описанные в Операции с сыпучими материалами, которые заменены упомянутой выше функцией ORM Bulk Insert.

Чтобы получить представление о масштабах этой операции, ниже приведены измерения производительности с использованием набора производительности test_flush_no_pk, который исторически представляет собой наихудшую задачу SQLAlchemy по выполнению INSERT, когда объекты, не имеющие значений первичных ключей, должны быть INSERT, а затем должны быть получены вновь созданные значения первичных ключей, чтобы объекты могли быть использованы для последующих операций flush, таких как создание внутри отношений, очистка моделей объединенного наследования и т.д.:

@Profiler.profile
def test_flush_no_pk(n):
    """INSERT statements via the ORM (batched with RETURNING if available),
    fetching generated row id"""
    session = Session(bind=engine)
    for chunk in range(0, n, 1000):
        session.add_all(
            [
                Customer(
                    name="customer name %d" % i,
                    description="customer description %d" % i,
                )
                for i in range(chunk, chunk + 1000)
            ]
        )
        session.flush()
    session.commit()

Этот тест может быть запущен из любого дерева исходных текстов SQLAlchemy следующим образом:

python -m examples.performance.bulk_inserts --test test_flush_no_pk

В таблице ниже приведены результаты измерений производительности последней версии SQLAlchemy серии 1.4 в сравнении с 2.0 при выполнении одного и того же теста:

Еще два драйвера не изменились в производительности: драйверы psycopg2, для которого в SQLAlchemy 1.4 уже был реализован быстрый executemany, и MySQL, который по-прежнему не предлагает поддержку RETURNING:

Краткое описание изменений¶

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

• RETURNING реализован для SQLite - #6195.

• RETURNING реализован для MariaDB - #7011.

• Исправить многорядный RETURNING для Oracle - #6245.

• сделать insert() executemany() поддерживающим RETURNING для как можно большего числа диалектов, обычно с помощью VALUES() - #6047.

• Выдавать предупреждение при использовании RETURNING w/ executemany для неподдерживающего бэкенда (в настоящее время ни один бэкенд RETURNING не имеет такого ограничения) - #7907.

• Параметр ORM Mapper.eager_defaults теперь устанавливает по умолчанию новую настройку "auto", которая будет автоматически включать «eager defaults» для операторов INSERT, если используемый бэкенд поддерживает RETURNING с «insertmanyvalues». Документацию см. в разделе Получение генерируемых сервером значений по умолчанию.

Объемная вставка с возвратом¶

Insert может быть передан в Session.execute(), с или без Insert.returning(), который при передаче с отдельным списком параметров вызовет тот же процесс, который ранее был реализован в Session.bulk_insert_mappings(), с дополнительными улучшениями. Это позволит оптимизировать пакетную обработку строк с использованием новой функции fast insertmany, а также добавить поддержку неоднородных наборов параметров и отображений нескольких таблиц, таких как наследование объединенных таблиц:

>>> users = session.scalars(
...     insert(User).returning(User),
...     [
...         {"name": "spongebob", "fullname": "Spongebob Squarepants"},
...         {"name": "sandy", "fullname": "Sandy Cheeks"},
...         {"name": "patrick", "fullname": "Patrick Star"},
...         {"name": "squidward", "fullname": "Squidward Tentacles"},
...         {"name": "ehkrabs", "fullname": "Eugene H. Krabs"},
...     ],
... )
>>> print(users.all())
[User(name='spongebob', fullname='Spongebob Squarepants'),
 User(name='sandy', fullname='Sandy Cheeks'),
 User(name='patrick', fullname='Patrick Star'),
 User(name='squidward', fullname='Squidward Tentacles'),
 User(name='ehkrabs', fullname='Eugene H. Krabs')]

RETURNING поддерживается для всех этих случаев, когда ORM будет строить полный набор результатов из нескольких вызовов оператора.

Массовое обновление¶

Аналогично методу Insert, передача конструкции Update вместе со списком параметров, включающим значения первичных ключей, в Session.execute() вызовет тот же процесс, который ранее поддерживался методом Session.bulk_update_mappings(). Однако эта функция не поддерживает RETURNING, так как использует SQL-оператор UPDATE, который вызывается с помощью DBAPI executemany:

>>> from sqlalchemy import update
>>> session.execute(
...     update(User),
...     [
...         {"id": 1, "fullname": "Spongebob Squarepants"},
...         {"id": 3, "fullname": "Patrick Star"},
...     ],
... )

INSERT / upsert … VALUES … ВОЗВРАТ¶

При использовании Insert с Insert.values() набор параметров может включать SQL-выражения. Кроме того, поддерживаются варианты upsert, например, для SQLite, PostgreSQL и MariaDB. Теперь эти операторы могут включать предложения Insert.returning() с выражениями столбцов или полными сущностями ORM:

>>> from sqlalchemy.dialects.sqlite import insert as sqlite_upsert
>>> stmt = sqlite_upsert(User).values(
...     [
...         {"name": "spongebob", "fullname": "Spongebob Squarepants"},
...         {"name": "sandy", "fullname": "Sandy Cheeks"},
...         {"name": "patrick", "fullname": "Patrick Star"},
...         {"name": "squidward", "fullname": "Squidward Tentacles"},
...         {"name": "ehkrabs", "fullname": "Eugene H. Krabs"},
...     ]
... )
>>> stmt = stmt.on_conflict_do_update(
...     index_elements=[User.name], set_=dict(fullname=stmt.excluded.fullname)
... )
>>> result = session.scalars(stmt.returning(User))
>>> print(result.all())
[User(name='spongebob', fullname='Spongebob Squarepants'),
User(name='sandy', fullname='Sandy Cheeks'),
User(name='patrick', fullname='Patrick Star'),
User(name='squidward', fullname='Squidward Tentacles'),
User(name='ehkrabs', fullname='Eugene H. Krabs')]

ORM UPDATE / DELETE с WHERE … RETURNING¶

В SQLAlchemy 1.4 также была реализована скромная поддержка функции RETURNING для использования с конструкциями update() и delete(), когда они используются вместе с Session.execute(). Теперь эта поддержка была усовершенствована и стала полностью собственной, включая то, что стратегия синхронизации fetch также может выполняться независимо от того, присутствует ли явное использование RETURNING или нет:

>>> from sqlalchemy import update
>>> stmt = (
...     update(User)
...     .where(User.name == "squidward")
...     .values(name="spongebob")
...     .returning(User)
... )
>>> result = session.scalars(stmt, execution_options={"synchronize_session": "fetch"})
>>> print(result.all())

Улучшено поведение synchronize_session для ORM UPDATE / DELETE¶

Стратегией по умолчанию для synchronize_session теперь является новое значение "auto". Эта стратегия будет пытаться использовать стратегию "evaluate", а затем автоматически возвращаться к стратегии "fetch". Для всех бэкендов, кроме MySQL / MariaDB, "fetch" использует RETURNING для получения идентификаторов первичного ключа UPDATE/DELETEd в рамках одного оператора, поэтому в целом более эффективна, чем предыдущие версии (в 1.4 RETURNING был доступен только для PostgreSQL, SQL Server).

Краткое описание изменений¶

Перечислены билеты для новых ORM DML с функциями RETURNING:

• преобразование insert() на уровне ORM для интерпретации values() в контексте ORM - #7864

• оценить возможность использования dml.returning(Entity) для доставки ORM-выражений, автоматического применения select().from_statement equiv - #7865

• учитывая вставку ORM, попытаться перенести массовые методы, re: inheritance - #8360.

Новый pep-484 / поддержка аннотированных отображений типов для динамических отношений¶

Несмотря на то, что в версии 2.0 «динамические» отношения являются наследием, поскольку ожидается, что эти паттерны будут иметь долгую жизнь, поддержка type annotated mapping для «динамических» отношений теперь добавлена так же, как и для нового подхода lazy="write_only", с помощью аннотации DynamicMapped:

from sqlalchemy.orm import DynamicMapped


class Base(DeclarativeBase):
    pass


class Account(Base):
    __tablename__ = "account"
    id: Mapped[int] = mapped_column(primary_key=True)
    identifier: Mapped[str]
    account_transactions: DynamicMapped["AccountTransaction"] = relationship(
        cascade="all, delete-orphan",
        passive_deletes=True,
        order_by="AccountTransaction.timestamp",
    )


class AccountTransaction(Base):
    __tablename__ = "account_transaction"
    id: Mapped[int] = mapped_column(primary_key=True)
    account_id: Mapped[int] = mapped_column(
        ForeignKey("account.id", ondelete="cascade")
    )
    description: Mapped[str]
    amount: Mapped[Decimal]
    timestamp: Mapped[datetime] = mapped_column(default=func.now())

Приведенное выше отображение позволяет получить коллекцию Account.account_transactions, которая типизирована как возвращающая тип коллекции AppenderQuery, включая тип ее элемента, например AppenderQuery[AccountTransaction]. Это позволяет при итерации и запросах получать объекты, типизированные как AccountTransaction.

#7123

Обзор производительности¶

В состав исходного дистрибутива входит скрипт test/perf/many_table_reflection.py, который тестирует как существующие, так и новые возможности отражения. Ограниченный набор его тестов может быть запущен на старых версиях SQLAlchemy, а здесь мы используем его для иллюстрации разницы в производительности при вызове metadata.reflect() для отражения 250 Table объектов одновременно через локальное сетевое соединение:

Поведенческие изменения для Inspector()¶

Для диалектов SQLAlchemy, входящих в состав SQLite, PostgreSQL, MySQL/MariaDB, Oracle и SQL Server, функции Inspector.has_table(), Inspector.has_sequence(), Inspector.has_index(), Inspector.get_table_names() и Inspector.get_sequence_names() теперь ведут себя последовательно в плане кэширования: они полностью кэшируют свой результат после первого вызова для конкретного объекта Inspector. Программы, создающие или сбрасывающие таблицы/последовательности при обращении к одному и тому же объекту Inspector, не будут получать обновленный статус после изменения состояния базы данных. При выполнении DDL-изменений следует использовать вызов Inspector.clear_cache() или новый Inspector. Ранее методы Inspector.has_table(), Inspector.has_sequence() не реализовывали кэширование и Inspector не поддерживали кэширование для этих методов, в то время как методы Inspector.get_table_names() и Inspector.get_sequence_names() поддерживали, что приводило к несогласованным результатам между этими двумя типами методов.

Поведение сторонних диалектов зависит от того, реализуют ли они декоратор «кэш отражений» для реализации этих методов на уровне диалекта.

Новые методы и усовершенствования для Inspector()¶

• добавлен метод Inspector.has_schema(), который возвращает, присутствует ли схема в целевой базе данных

• добавлен метод Inspector.has_index(), возвращающий, имеет ли таблица определенный индекс.

• Методы проверки, такие как Inspector.get_columns(), работающие с одной таблицей за раз, теперь должны последовательно вызывать NoSuchTableError, если таблица или представление не найдены; это изменение относится к отдельным диалектам, поэтому может не соответствовать существующим диалектам сторонних разработчиков.

• Разделена работа с «представлениями» и «материализованными представлениями», поскольку в реальных условиях эти две конструкции используют разные DDL для CREATE и DROP; это означает, что теперь существуют отдельные методы Inspector.get_view_names() и Inspector.get_materialized_view_names().

#4379

Новые режимы присоединения транзакций для Session¶

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

Основное улучшение, которое это дает, заключается в том, что рецепт, задокументированный в Присоединение сеанса к внешней транзакции (например, для тестовых наборов), который также изменился с SQLAlchemy 1.3 на 1.4, теперь упрощен и не требует явного использования обработчика событий или упоминания явной точки сохранения; используя join_transaction_mode="create_savepoint", Session никогда не будет влиять на состояние входящей транзакции, а будет создавать точку сохранения (т.е. «вложенную транзакцию») как свою корневую транзакцию.

Ниже приведена часть примера, приведенного в разделе Присоединение сеанса к внешней транзакции (например, для тестовых наборов); полный пример см. в этом разделе:

class SomeTest(TestCase):
    def setUp(self):
        # connect to the database
        self.connection = engine.connect()

        # begin a non-ORM transaction
        self.trans = self.connection.begin()

        # bind an individual Session to the connection, selecting
        # "create_savepoint" join_transaction_mode
        self.session = Session(
            bind=self.connection, join_transaction_mode="create_savepoint"
        )

    def tearDown(self):
        self.session.close()

        # rollback non-ORM transaction
        self.trans.rollback()

        # return connection to the Engine
        self.connection.close()

По умолчанию для Session.join_transaction_mode выбран режим "conditional_savepoint", который использует поведение "create_savepoint", если данный Connection сам уже находится в точке сохранения. Если данный Connection находится в транзакции, но не в точке сохранения, то Session будет распространять вызовы «отката», но не вызовы «фиксации», но не будет самостоятельно начинать новую точку сохранения. Такое поведение выбрано по умолчанию для максимальной совместимости со старыми версиями SQLAlchemy, а также для того, чтобы не начинать новый SAVEPOINT, если данный драйвер уже не использует SAVEPOINT, так как поддержка SAVEPOINT зависит не только от конкретного бэкенда и драйвера, но и от конфигурации.

Ниже приведен пример, который работал в SQLAlchemy 1.3, перестал работать в SQLAlchemy 1.4, а теперь восстановлен в SQLAlchemy 2.0:

engine = create_engine("...")

# setup outer connection with a transaction and a SAVEPOINT
conn = engine.connect()
trans = conn.begin()
nested = conn.begin_nested()

# bind a Session to that connection and operate upon it, including
# a commit
session = Session(conn)
session.connection()
session.commit()
session.close()

# assert both SAVEPOINT and transaction remain active
assert nested.is_active
nested.rollback()
trans.rollback()

В случае, описанном выше, Session присоединяется к Connection, на котором запущена точка сохранения; состояние этих двух единиц остается неизменным после того, как Session поработает с транзакцией. В SQLAlchemy 1.3 описанный выше случай работал, поскольку Session начинал «субтранзакцию» на Connection, что позволяло внешней точке сохранения/транзакции оставаться незатронутой для простых случаев, описанных выше. Поскольку субтранзакции были отменены в версии 1.4 и теперь удалены в версии 2.0, такое поведение стало недоступным. Новое поведение по умолчанию улучшает поведение «субтранзакций», используя вместо них реальный, второй SAVEPOINT, так что даже вызовы Session.rollback() не позволяют Session «вырваться» в инициированный извне SAVEPOINT или транзакцию.

Новый код, который присоединяет запущенную транзакцию Connection к Session, должен, однако, явно выбрать Session.join_transaction_mode, чтобы желаемое поведение было явно определено.

#9015

str(engine.url) по умолчанию обфусцирует пароль¶

Чтобы избежать утечки паролей баз данных, вызов str() на URL теперь по умолчанию включает функцию обфускации паролей. Ранее обфускация включалась при вызове __repr__(), но не __str__(). Это изменение повлияет на приложения и тестовые пакеты, которые пытаются вызвать create_engine(), получив строгированный URL от другого механизма, например:

>>> e1 = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
>>> e2 = create_engine(str(e1.url))

В приведенном выше движке e2 не будет правильного пароля, а будет обфусцированная строка "***".

Предпочтительным подходом для приведенного шаблона является передача объекта URL напрямую, нет необходимости в строковой обработке:

>>> e1 = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
>>> e2 = create_engine(e1.url)

В противном случае для строкового URL с паролем в открытом виде используйте метод URL.render_as_string(), передавая параметр URL.render_as_string.hide_password в виде False:

>>> e1 = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
>>> url_string = e1.url.render_as_string(hide_password=False)
>>> e2 = create_engine(url_string)

#8567

Более строгие правила замены столбцов в объектах Table с одинаковыми именами, ключами¶

Ужесточены правила добавления объектов Column к объектам Table, что позволило перевести некоторые предыдущие предупреждения об устаревании в исключения и предотвратить некоторые предыдущие сценарии, которые приводили к появлению дублирующихся столбцов в таблицах, когда Table.extend_existing устанавливался в True, как при программном построении Table, так и при операциях отражения.

• Ни при каких обстоятельствах объект Table не должен иметь два или более объектов Column с одинаковым именем, независимо от того, какой .key они имеют. Был выявлен и исправлен крайний случай, когда это все же было возможно.

• Добавление Column к Table, имеющему то же имя или ключ, что и существующий Column, всегда будет вызывать DuplicateColumnError (новый подкласс ArgumentError в версии 2.0.0b4), если нет дополнительных параметров; Table.append_column.replace_existing для Table.append_column() и Table.extend_existing для построения Table с тем же именем, что и существующий, с использованием или без использования отражения. Ранее для этого сценария действовало предупреждение об устаревании.

• Теперь при создании Table, включающего Table.extend_existing, выдается предупреждение о том, что входящий Column, не имеющий отдельного Column.key, полностью заменит существующий Column, имеющий ключ, что говорит о том, что операция выполняется не так, как задумано пользователем. Это может произойти, в частности, на этапе вторичного отражения, например, metadata.reflect(extend_existing=True). Для предотвращения этого в предупреждении предлагается установить параметр Table.autoload_replace в значение False. Ранее, в версии 1.4 и более ранних, входящий столбец добавлялся в дополнение к существующему столбцу. Это было ошибкой, а в версии 2.0 (начиная с 2.0.0b4) поведение изменилось, так как предыдущий ключ больше не будет присутствовать в коллекции столбцов, когда это произойдет.

#8925

Декларативный ORM применяет порядок столбцов по-разному; управление поведением с помощью sort_order¶

В Declarative изменена система, в которой отображаемые колонки, происходящие из миксинов или абстрактных базовых классов, сортируются вместе с колонками, находящимися в самом объявленном классе, и теперь сначала располагаются колонки из объявленного класса, а затем колонки миксинов. В настоящее время используется следующее отображение:

class Foo:
    col1 = mapped_column(Integer)
    col3 = mapped_column(Integer)


class Bar:
    col2 = mapped_column(Integer)
    col4 = mapped_column(Integer)


class Model(Base, Foo, Bar):
    id = mapped_column(Integer, primary_key=True)
    __tablename__ = "model"

Выдает CREATE TABLE, как показано ниже на 1.4:

CREATE TABLE model (
  col1 INTEGER,
  col3 INTEGER,
  col2 INTEGER,
  col4 INTEGER,
  id INTEGER NOT NULL,
  PRIMARY KEY (id)
)

В то время как на 2.0 он производит:

CREATE TABLE model (
  id INTEGER NOT NULL,
  col1 INTEGER,
  col3 INTEGER,
  col2 INTEGER,
  col4 INTEGER,
  PRIMARY KEY (id)
)

Для приведенного выше конкретного случая это можно рассматривать как улучшение, поскольку столбцы первичного ключа в Model теперь находятся там, где обычно предпочтительнее. Однако это не утешает приложение, которое определило модели наоборот, так как:

class Foo:
    id = mapped_column(Integer, primary_key=True)
    col1 = mapped_column(Integer)
    col3 = mapped_column(Integer)


class Model(Foo, Base):
    col2 = mapped_column(Integer)
    col4 = mapped_column(Integer)
    __tablename__ = "model"

Теперь вывод CREATE TABLE выглядит так:

CREATE TABLE model (
  col2 INTEGER,
  col4 INTEGER,
  id INTEGER NOT NULL,
  col1 INTEGER,
  col3 INTEGER,
  PRIMARY KEY (id)
)

Для решения этой проблемы в SQLAlchemy 2.0.4 введен новый параметр mapped_column(), называемый mapped_column.sort_order, который представляет собой целочисленное значение, по умолчанию равное 0, которое может быть установлено в положительное или отрицательное значение, чтобы столбцы располагались перед или после других столбцов, как в приведенном ниже примере:

class Foo:
    id = mapped_column(Integer, primary_key=True, sort_order=-10)
    col1 = mapped_column(Integer, sort_order=-1)
    col3 = mapped_column(Integer)


class Model(Foo, Base):
    col2 = mapped_column(Integer)
    col4 = mapped_column(Integer)
    __tablename__ = "model"

В приведенной выше модели «id» располагается перед всеми остальными, а «col1» - после «id»:

CREATE TABLE model (
  id INTEGER NOT NULL,
  col1 INTEGER,
  col2 INTEGER,
  col4 INTEGER,
  col3 INTEGER,
  PRIMARY KEY (id)
)

В будущих версиях SQLAlchemy может быть решено предоставить явную подсказку по упорядочиванию для конструкции mapped_column, поскольку такое упорядочивание является специфическим для ORM.

Конструкция Sequence возвращается к отсутствию явного значения «start» по умолчанию; влияет на MS SQL Server¶

До версии SQLAlchemy 1.4 конструкция Sequence выдавала только простой DDL CREATE SEQUENCE, если не были указаны дополнительные аргументы:

>>> # SQLAlchemy 1.3 (and 2.0)
>>> from sqlalchemy import Sequence
>>> from sqlalchemy.schema import CreateSequence
>>> print(CreateSequence(Sequence("my_seq")))
{printsql}CREATE SEQUENCE my_seq

Однако, поскольку была добавлена поддержка Sequence для MS SQL Server, где по умолчанию начальное значение неудобно установлено в -2**63, в версии 1.4 было принято решение по умолчанию выдавать в DDL начальное значение 1, если Sequence.start не предусмотрено иное:

>>> # SQLAlchemy 1.4 (only)
>>> from sqlalchemy import Sequence
>>> from sqlalchemy.schema import CreateSequence
>>> print(CreateSequence(Sequence("my_seq")))
{printsql}CREATE SEQUENCE my_seq START WITH 1

Это изменение привело к другим сложностям, в том числе к тому, что при включении параметра Sequence.min_value по умолчанию 1 фактически должно устанавливаться то, что указано в Sequence.min_value, иначе значение min_value, которое меньше значения start_value, может быть воспринято как противоречивое. Поскольку рассмотрение этого вопроса начало превращаться в кроличью нору с другими различными крайними случаями, мы решили вместо этого отменить это изменение и восстановить первоначальное поведение Sequence, которое заключается в том, чтобы не иметь никакого мнения и просто выдавать CREATE SEQUENCE, позволяя базе данных самой принимать решения о том, как различные параметры SEQUENCE должны взаимодействовать друг с другом.

Поэтому, чтобы гарантировать, что начальное значение равно 1 на всех бэкендах, начальное значение 1 может быть указано явно, как показано ниже:

>>> # All SQLAlchemy versions
>>> from sqlalchemy import Sequence
>>> from sqlalchemy.schema import CreateSequence
>>> print(CreateSequence(Sequence("my_seq", start=1)))
{printsql}CREATE SEQUENCE my_seq START WITH 1

Помимо всего прочего, для автогенерации целочисленных первичных ключей на современных бэкендах, включая PostgreSQL, Oracle, SQL Server, следует предпочесть конструкцию Identity, которая без изменений работает и в 1.4, и в 2.0.

#7211

«with_variant()» клонирует исходный TypeEngine, а не изменяет тип¶

Метод TypeEngine.with_variant(), используемый для применения альтернативных вариантов поведения базы данных к определенному типу, теперь возвращает копию исходного объекта TypeEngine с информацией о варианте, хранящейся внутри, а не оборачивает ее в класс Variant.

В то время как предыдущий подход Variant позволял сохранить все in-Python-поведения исходного типа с помощью динамических геттеров атрибутов, здесь улучшение заключается в том, что при обращении к варианту возвращаемый тип остается экземпляром исходного типа, что позволяет более гладко работать с программами проверки типов, такими как mypy и pylance. Ниже приведена программа:

import typing

from sqlalchemy import String
from sqlalchemy.dialects.mysql import VARCHAR

type_ = String(255).with_variant(VARCHAR(255, charset="utf8mb4"), "mysql", "mariadb")

if typing.TYPE_CHECKING:
    reveal_type(type_)

Теперь программа проверки типов, например, pyright, сообщит, что тип имеет вид:

info: Type of "type_" is "String"

Кроме того, как показано выше, для одного типа можно передавать несколько имен диалектов, в частности, это полезно для пары диалектов "mysql" и "mariadb", которые в SQLAlchemy 1.4 рассматриваются отдельно.

#6980

Оператор деления в Python выполняет истинное деление для всех бэкендов; добавлено деление на пол¶

Язык выражений Core теперь поддерживает как «истинное деление» (т.е. оператор / Python), так и «деление на пол» (т.е. оператор // Python), включая специфическое для бэкенда поведение для нормализации различных баз данных в этом отношении.

Дана операция «истинного деления» на два целочисленных значения:

expr = literal(5, Integer) / literal(10, Integer)

Например, оператор деления SQL в PostgreSQL при работе с целыми числами обычно работает как «деление на пол», то есть приведенный выше результат вернет целое число «0». Для этого и подобных бэкендов SQLAlchemy теперь отображает SQL в эквивалентной форме:

%(param_1)s / CAST(%(param_2)s AS NUMERIC)

С param_1=5, param_2=10, так что возвращаемое выражение будет иметь тип NUMERIC, обычно в виде значения Python decimal.Decimal("0.5").

Дана операция «поэтажного деления» над двумя целыми значениями:

expr = literal(5, Integer) // literal(10, Integer)

Оператор деления SQL в MySQL и Oracle, например, обычно работает как «истинное деление» при использовании с целыми числами, то есть приведенный выше результат вернет значение с плавающей точкой «0,5». Для этих и подобных им бэкендов SQLAlchemy теперь отображает SQL в эквивалентной форме:

FLOOR(%(param_1)s / %(param_2)s)

При param_1=5, param_2=10, так что возвращаемое выражение будет иметь тип INTEGER, как значение Python 0.

Обратное несовместимое изменение будет иметь место, если приложение, использующее PostgreSQL, SQL Server или SQLite, полагается на оператор Python «truediv», который во всех случаях возвращает целочисленное значение. Приложения, полагающиеся на такое поведение, должны вместо этого использовать для этих операций оператор Python «floor division» // или, для обратной совместимости при использовании предыдущей версии SQLAlchemy, функцию floor:

expr = func.floor(literal(5, Integer) / literal(10, Integer))

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

#4926

Проактивно поднимать сессию при обнаружении незаконного одновременного или реентерабельного доступа¶

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

Известна одна ошибка, возникающая при одновременном использовании Session в нескольких потоках, - AttributeError: 'NoneType' object has no attribute 'twophase', которая является совершенно загадочной. Эта ошибка возникает, когда поток вызывает Session.commit(), который внутренне вызывает метод SessionTransaction.close() для завершения транзакционного контекста, в то время, когда другой поток выполняет запрос из Session.execute(). Внутри Session.execute() внутренний метод, приобретающий соединение с базой данных для текущей транзакции, сначала утверждает, что сессия «активна», но после того, как это утверждение проходит, одновременный вызов Session.close() вмешивается в это состояние, что приводит к неопределенному состоянию, описанному выше.

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

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

Traceback (most recent call last):
File "/home/classic/dev/sqlalchemy/test3.py", line 30, in worker
    sess.execute(select(A)).all()
File "/home/classic/tmp/sqlalchemy/lib/sqlalchemy/orm/session.py", line 1691, in execute
    conn = self._connection_for_bind(bind)
File "/home/classic/tmp/sqlalchemy/lib/sqlalchemy/orm/session.py", line 1532, in _connection_for_bind
    return self._transaction._connection_for_bind(
File "/home/classic/tmp/sqlalchemy/lib/sqlalchemy/orm/session.py", line 754, in _connection_for_bind
    if self.session.twophase and self._parent is None:
AttributeError: 'NoneType' object has no attribute 'twophase'

Где метод _connection_for_bind() не может продолжить работу, поскольку одновременный доступ перевел его в недопустимое состояние. При использовании нового подхода вместо ошибки выбрасывается инициатор изменения состояния:

File "/home/classic/dev/sqlalchemy/lib/sqlalchemy/orm/session.py", line 1785, in close
   self._close_impl(invalidate=False)
File "/home/classic/dev/sqlalchemy/lib/sqlalchemy/orm/session.py", line 1827, in _close_impl
   transaction.close(invalidate)
File "<string>", line 2, in close
File "/home/classic/dev/sqlalchemy/lib/sqlalchemy/orm/session.py", line 506, in _go
   raise sa_exc.InvalidRequestError(
sqlalchemy.exc.InvalidRequestError: Method 'close()' can't be called here;
method '_connection_for_bind()' is already in progress and this would cause
an unexpected state change to symbol('CLOSED')

Проверки перехода состояния намеренно не используют явных блокировок для обнаружения активности параллельных потоков, а полагаются на простые операции проверки набора атрибутов/значений, которые неизбежно терпят неудачу при неожиданных параллельных изменениях. Это объясняется тем, что такой подход позволяет обнаружить неправомерные изменения состояния, происходящие полностью внутри одного потока, например, если обработчик событий, выполняющийся на событиях транзакций сессии, вызывает метод, изменяющий состояние, который не ожидается, или в asyncio, если конкретный Session был разделен между несколькими задачами asyncio, а также при использовании подходов к параллелизму в стиле патчей, таких как gevent.

#7433

Диалект SQLite использует QueuePool для файловых баз данных¶

Диалект SQLite теперь по умолчанию принимает значение QueuePool при использовании базы данных на основе файлов. Это устанавливается вместе с установкой параметра check_same_thread в значение False. Было замечено, что предыдущий подход, при котором по умолчанию устанавливалось значение NullPool, не удерживающее соединения с базой данных после их освобождения, действительно оказывал ощутимое негативное влияние на производительность. Как обычно, класс пула настраивается с помощью параметра create_engine.poolclass.

#7490

Новый тип Oracle FLOAT с двоичной точностью; десятичная точность напрямую не принимается¶

В диалект Oracle добавлен новый тип данных FLOAT, который сопровождается добавлением Double и специфических для баз данных типов DOUBLE, DOUBLE_PRECISION и REAL. Oracle FLOAT принимает так называемый параметр «двоичной точности», который, согласно документации Oracle, представляет собой стандартное значение «точности», деленное на 0.3103:

from sqlalchemy.dialects import oracle

Table("some_table", metadata, Column("value", oracle.FLOAT(126)))

Значение двоичной точности 126 является синонимом использования типа данных DOUBLE_PRECISION, а значение 63 эквивалентно использованию типа данных REAL. Другие значения точности специфичны для самого типа FLOAT.

Тип данных SQLAlchemy Float также принимает параметр «precision», но это десятичная точность, которая не принимается Oracle. Вместо того чтобы пытаться угадать преобразование, диалект Oracle теперь будет выдавать информационную ошибку, если Float используется со значением precision в бэкенде Oracle. Чтобы указать тип данных Float с явным значением точности для поддерживающих бэкендов и при этом поддерживать другие бэкенды, используйте метод TypeEngine.with_variant() следующим образом:

from sqlalchemy.types import Float
from sqlalchemy.dialects import oracle

Table(
    "some_table",
    metadata,
    Column("value", Float(5).with_variant(oracle.FLOAT(16), "oracle")),
)

Новая поддержка RANGE / MULTIRANGE и изменения для бэкендов PostgreSQL¶

Поддержка RANGE / MULTIRANGE полностью реализована для диалектов psycopg2, psycopg3 и asyncpg. Для поддержки используется новый объект Range, специфичный для SQLAlchemy, который не зависит от различных бэкендов и не требует использования импорта или шагов расширения, специфичных для бэкенда. Для поддержки многодиапазонности используются списки объектов Range.

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

В объекте Range также реализована поддержка сравнения, аналогичная той, что имеется в PostgreSQL. На данный момент реализованы методы Range.contains() и Range.contained_by(), которые работают так же, как и PostgreSQL @> и <@. В последующих выпусках может быть добавлена поддержка дополнительных операторов.

Информацию об использовании новой возможности см. в документации по адресу Типы диапазонов и мультидиапазонов.

#7156 #8706

Оператор match() в PostgreSQL использует plainto_tsquery(), а не to_tsquery()¶

Функция Operators.match() теперь выводит на бэкенд PostgreSQL не col @@ to_tsquery(), а col @@ plainto_tsquery(expr). Функция plainto_tsquery() принимает обычный текст, в то время как to_tsquery() принимает специализированные символы запроса, и поэтому менее совместима с другими бэкендами.

Все функции и операторы поиска PostgreSQL доступны через использование func для генерации специфических для PostgreSQL функций и Operators.bool_op() (boolean-typed версия Operators.op()) для генерации произвольных операторов, аналогично тому, как они доступны в предыдущих версиях. См. примеры в Полнотекстовый поиск.

Существующие проекты SQLAlchemy, использующие специфические для PG директивы в рамках Operators.match(), должны использовать непосредственно func.to_tsquery(). Чтобы отобразить SQL в том же виде, что и в версии 1.4, смотрите примечание к версии Простое сопоставление обычного текста с помощью match().

#7086