Дополнительные техники стойкости¶

Случай 1: не первичный ключ, поддерживается RETURNING или эквивалент¶

В этом случае столбцы должны быть помечены как FetchedValue или с явным Column.server_default. Параметр mapper.eager_defaults может быть использован для указания того, что эти столбцы должны быть извлечены немедленно при INSERT и иногда UPDATE:

class MyModel(Base):
    __tablename__ = "my_table"

    id = Column(Integer, primary_key=True)
    timestamp = Column(DateTime(), server_default=func.now())

    # assume a database trigger populates a value into this column
    # during INSERT
    special_identifier = Column(String(50), server_default=FetchedValue())

    __mapper_args__ = {"eager_defaults": True}

Выше, оператор INSERT, который не указывает явных значений для «timestamp» или «special_identifier» на стороне клиента, будет включать столбцы «timestamp» и «special_identifier» в предложение RETURNING, чтобы они были доступны немедленно. В базе данных PostgreSQL INSERT для приведенной выше таблицы будет выглядеть следующим образом:

INSERT INTO my_table DEFAULT VALUES RETURNING my_table.id, my_table.timestamp, my_table.special_identifier

Случай 2: не первичный ключ, RETURNING или эквивалент не поддерживается или не нужен¶

Этот случай аналогичен случаю 1, за исключением того, что мы не указываем mapper.eager_defaults:

class MyModel(Base):
    __tablename__ = "my_table"

    id = Column(Integer, primary_key=True)
    timestamp = Column(DateTime(), server_default=func.now())

    # assume a database trigger populates a value into this column
    # during INSERT
    special_identifier = Column(String(50), server_default=FetchedValue())

После INSERT записи с вышеуказанным отображением столбцы «timestamp» и «special_identifier» останутся пустыми, и будут получены с помощью второго оператора SELECT при первом обращении к ним после промывки, например, если они помечены как «expired».

Если mapper.eager_defaults все еще используется, а внутренняя база данных не поддерживает RETURNING или его эквивалент, ORM будет выдавать этот оператор SELECT сразу после оператора INSERT. Это часто нежелательно, поскольку добавляет в процесс flush дополнительные операторы SELECT, которые могут быть не нужны. Использование приведенного выше отображения с флагом mapper.eager_defaults, установленным в True для MySQL, приводит к такому SQL после flush (за вычетом комментария, который служит только для пояснения):

INSERT INTO my_table () VALUES ()

-- when eager_defaults **is** used, but RETURNING is not supported
SELECT my_table.timestamp AS my_table_timestamp, my_table.special_identifier AS my_table_special_identifier
FROM my_table WHERE my_table.id = %s

Случай 3: поддерживается первичный ключ, RETURNING или эквивалент¶

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

Как упоминалось выше, для целочисленных столбцов «autoincrement», а также PostgreSQL SERIAL, эти типы обрабатываются автоматически Core; базы данных включают функции для получения «последнего вставленного id», где RETURNING не поддерживается, а где RETURNING поддерживается, SQLAlchemy будет использовать это.

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

Для явной последовательности, как мы используем в Oracle, это означает, что мы используем конструкцию Sequence:

class MyOracleModel(Base):
    __tablename__ = "my_table"

    id = Column(Integer, Sequence("my_sequence"), primary_key=True)
    data = Column(String(50))

INSERT для модели, как указано выше, в Oracle выглядит следующим образом:

INSERT INTO my_table (id, data) VALUES (my_sequence.nextval, :data) RETURNING my_table.id INTO :ret_0

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

Для типов данных, которые генерируют значения автоматически, или столбцов, которые заполняются триггером, мы используем FetchedValue. Ниже приведена модель, в которой в качестве первичного ключа используется столбец SQL Server TIMESTAMP, который генерирует значения автоматически:

class MyModel(Base):
    __tablename__ = "my_table"

    timestamp = Column(TIMESTAMP(), server_default=FetchedValue(), primary_key=True)

INSERT для вышеуказанной таблицы на SQL Server выглядит следующим образом:

INSERT INTO my_table OUTPUT inserted.timestamp DEFAULT VALUES

Случай 4: первичный ключ, RETURNING или эквивалент не поддерживается¶

В этой области мы генерируем строки для базы данных, таких как SQLite или MySQL, где некоторые средства генерации значения по умолчанию происходят на сервере, но находятся за пределами обычной процедуры автоинкремента базы данных. В этом случае мы должны убедиться, что SQLAlchemy может «предварительно выполнить» значение по умолчанию, что означает, что оно должно быть явным выражением SQL.

class MyModel(Base):
    __tablename__ = "my_table"

    timestamp = Column(DateTime(), default=func.now(), primary_key=True)

SELECT now() AS anon_1
INSERT INTO my_table (timestamp) VALUES (%s)
('2018-08-09 13:08:46',)

from sqlalchemy import cast, Binary


class MyModel(Base):
    __tablename__ = "my_table"

    timestamp = Column(TIMESTAMP(), default=cast(func.now(), Binary), primary_key=True)

SELECT CAST(now() AS BINARY) AS anon_1
INSERT INTO my_table (timestamp) VALUES (%s)
(b'2018-08-09 13:08:46',)

class MyModel(Base):
    __tablename__ = "my_table"

    timestamp = Column(
        DateTime,
        default=func.datetime("now", "localtime", type_=DateTime),
        primary_key=True,
    )

SELECT datetime(?, ?) AS datetime_1
('now', 'localtime')
INSERT INTO my_table (timestamp) VALUES (?)
('2018-10-02 13:37:33.000000',)

Примечания о нетерпеливой выборке вызываемых клиентом выражений SQL, используемых для INSERT или UPDATE¶

Предыдущие примеры показывают использование Column.server_default для создания таблиц, которые включают функции генерации по умолчанию в DDL.

SQLAlchemy также поддерживает не-DDL значения по умолчанию на стороне сервера, как документировано в Выражения SQL, вызываемые клиентом; эти «вызываемые клиентом SQL выражения» устанавливаются с помощью параметров Column.default и Column.onupdate.

Эти SQL-выражения в настоящее время подвержены тем же ограничениям в ORM, что и настоящие умолчания на стороне сервера; они не будут с нетерпением подбираться с RETURNING при использовании mapper.eager_defaults, если директива FetchedValue не связана с Column, даже если эти выражения не являются умолчаниями сервера DDL и активно отображаются самим SQLAlchemy. Это ограничение может быть устранено в будущих выпусках SQLAlchemy.

Конструкция FetchedValue может быть применена к Column.server_default или Column.server_onupdate одновременно с использованием SQL-выражения Column.default и Column.onupdate, как в примере ниже, где конструкция func.now() используется в качестве вызываемого клиентом SQL-выражения для Column.default и Column.onupdate. Для того чтобы поведение mapper.eager_defaults включало извлечение этих значений с использованием RETURNING, когда они доступны, Column.server_default и Column.server_onupdate используются вместе с FetchedValue для обеспечения того, что извлечение происходит:

class MyModel(Base):
    __tablename__ = "my_table"

    id = Column(Integer, primary_key=True)

    created = Column(DateTime(), default=func.now(), server_default=FetchedValue())
    updated = Column(
        DateTime(),
        onupdate=func.now(),
        server_default=FetchedValue(),
        server_onupdate=FetchedValue(),
    )

    __mapper_args__ = {"eager_defaults": True}

С отображением, подобным приведенному выше, SQL, созданный ORM для INSERT и UPDATE, будет включать created и updated в предложении RETURNING:

INSERT INTO my_table (created) VALUES (now()) RETURNING my_table.id, my_table.created, my_table.updated

UPDATE my_table SET updated=now() WHERE my_table.id = %(my_table_id)s RETURNING my_table.updated

Использование PostgreSQL ON CONFLICT с RETURNING для возврата upserted ORM объектов¶

Приведенный выше подход можно использовать и для INSERT с RETURNING. В качестве более продвинутого примера ниже показано, как использовать конструкцию PostgreSQL postgresql_insert_on_conflict для INSERT или UPDATE строк в базе данных, одновременно создавая эти объекты как экземпляры ORM:

from sqlalchemy.dialects.postgresql import insert

stmt = insert(User).values(
    [
        dict(name="sandy", fullname="Sandy Cheeks"),
        dict(name="squidward", fullname="Squidward Tentacles"),
        dict(name="spongebob", fullname="Spongebob Squarepants"),
    ]
)

stmt = stmt.on_conflict_do_update(
    index_elements=[User.name], set_=dict(fullname=stmt.excluded.fullname)
).returning(User)

orm_stmt = select(User).from_statement(stmt).execution_options(populate_existing=True)
for user in session.execute(
    orm_stmt,
).scalars():
    print("inserted or updated: %s" % user)

Для начала мы убедимся, что используем PostgreSQL-вариант конструкции insert(). Затем мы создадим многозначный оператор INSERT, где один оператор INSERT будет содержать несколько строк для вставки. В базе данных PostgreSQL этот синтаксис обеспечивает наиболее эффективное средство для одновременной отправки сотен строк для вставки.

Отсюда мы могли бы при желании добавить предложение RETURNING для создания массового INSERT. Однако, чтобы сделать пример еще более интересным, мы также добавим специфический для PostgreSQL синтаксис ON CONFLICT..DO UPDATE, чтобы строки, которые уже существуют на основе уникального критерия, были UPDATEd вместо этого. Мы предполагаем, что существует ограничение INDEX или UNIQUE на столбце name в таблице user_account выше, а затем укажем соответствующий критерий Insert.on_conflict_do_update(), который обновит столбец fullname для уже существующих строк.

Наконец, мы добавляем предложение Insert.returning(), как мы делали в предыдущем примере, и выбираем наши объекты User, используя тот же подход Select.from_statement(), что и ранее. Предположим, что в базе данных присутствует только строка для (1, "squidward", NULL); эта строка вызовет процедуру ON CONFLICT в нашем вышеприведенном операторе, другими словами, выполнит эквивалент оператора UPDATE. Две другие строки, (NULL, "sandy", "Sandy Cheeks") и (NULL, "spongebob", "Spongebob Squarepants"), еще не существуют в базе данных и будут вставлены с использованием обычной семантики INSERT; столбец первичного ключа id использует либо SERIAL, либо IDENTITY для автоматической генерации новых целочисленных значений.

Используя приведенную выше форму, мы видим SQL, выдаваемый базе данных PostgreSQL в виде:

INSERT INTO user_account (name, fullname)
VALUES (%(name_m0)s, %(fullname_m0)s), (%(name_m1)s, %(fullname_m1)s), (%(name_m2)s, %(fullname_m2)s)
ON CONFLICT (name) DO UPDATE SET fullname = excluded.fullname
RETURNING user_account.id, user_account.name, user_account.fullname
{'name_m0': 'sandy', 'fullname_m0': 'Sandy Cheeks', 'name_m1': 'squidward', 'fullname_m1': 'Squidward Tentacles', 'name_m2': 'spongebob', 'fullname_m2': 'Spongebob Squarepants'}
inserted or updated: User(id=2, name='sandy', fullname='Sandy Cheeks')
inserted or updated: User(id=3, name='squidward', fullname='Squidward Tentacles')
inserted or updated: User(id=1, name='spongebob', fullname='Spongebob Squarepants')

Выше мы также видим, что объекты INSERTed User имеют вновь созданное значение первичного ключа, как мы и ожидали от любого другого оператора INSERT, ориентированного на ORM.

Простые вертикальные перегородки¶

Вертикальное разделение размещает различные классы, иерархии классов или сопоставленные таблицы в нескольких базах данных, конфигурируя Session с аргументом Session.binds. Этот аргумент получает словарь, содержащий любую комбинацию ORM-сопоставленных классов, произвольных классов в сопоставленной иерархии (таких как декларативные базовые классы или миксины), Table объектов и Mapper объектов в качестве ключей, которые затем ссылаются обычно на Engine или менее типично Connection объекты в качестве целей. К словарю обращаются всякий раз, когда Session нужно выдать SQL от имени определенного вида сопоставленного класса, чтобы найти соответствующий источник подключения к базе данных:

engine1 = create_engine("postgresql://db1")
engine2 = create_engine("postgresql://db2")

Session = sessionmaker()

# bind User operations to engine 1, Account operations to engine 2
Session.configure(binds={User: engine1, Account: engine2})

session = Session()

Выше, SQL-операции против любого класса будут использовать Engine, связанный с этим классом. Функциональность является всеобъемлющей для операций чтения и записи; операция Query, направленная на объекты, сопоставленные с engine1 (определяется путем просмотра первого объекта в списке запрашиваемых элементов), будет использовать engine1 для выполнения запроса. Операция flush будет использовать обои движки на основе каждого класса, поскольку она очищает объекты типа User и Account.

В более распространенном случае обычно существуют базовые классы или классы-миксины, которые можно использовать для различения операций, предназначенных для разных соединений с базой данных. Аргумент Session.binds может содержать любой произвольный класс Python в качестве ключа, который будет использоваться, если окажется, что он находится в __mro__ (порядок разрешения методов Python) для определенного сопоставленного класса. Предположим, что две декларативные базы представляют два разных подключения к базе данных:

BaseA = declarative_base()

BaseB = declarative_base()

class User(BaseA):
    # ...

class Address(BaseA):
    # ...


class GameInfo(BaseB):
    # ...

class GameStats(BaseB):
    # ...


Session = sessionmaker()

# all User/Address operations will be on engine 1, all
# Game operations will be on engine 2
Session.configure(binds={BaseA:engine1, BaseB:engine2})

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

Координация транзакций для сеанса с несколькими двигателями¶

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

Из-за ограниченной поддержки в DBAPIs, SQLAlchemy имеет ограниченную поддержку двухфазных транзакций между бэкендами. Как правило, она хорошо работает с бэкендом PostgreSQL и в меньшей степени с бэкендом MySQL. Тем не менее, Session полностью способен использовать преимущества двухфазной транзакции, если бэкенд поддерживает ее, путем установки флага Session.use_twophase в sessionmaker или Session. Пример смотрите в Включение двухфазной фиксации.

Нестандартные вертикальные перегородки¶

Более полное разделение на уровне классов на основе правил можно построить, переопределив метод Session.get_bind(). Ниже мы иллюстрируем пользовательский Session, который обеспечивает следующие правила:

1. Операции промывки, а также массовые операции «обновления» и «удаления» доставляются на движок с именем leader.

2. Все операции над объектами, подкласса MyOtherClass, происходят на движке other.

3. Операции чтения для всех остальных классов происходят на случайном выборе базы данных follower1 или follower2.

engines = {
    "leader": create_engine("sqlite:///leader.db"),
    "other": create_engine("sqlite:///other.db"),
    "follower1": create_engine("sqlite:///follower1.db"),
    "follower2": create_engine("sqlite:///follower2.db"),
}

from sqlalchemy.sql import Update, Delete
from sqlalchemy.orm import Session, sessionmaker
import random


class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None):
        if mapper and issubclass(mapper.class_, MyOtherClass):
            return engines["other"]
        elif self._flushing or isinstance(clause, (Update, Delete)):
            return engines["leader"]
        else:
            return engines[random.choice(["follower1", "follower2"])]

Приведенный выше класс Session подключается с помощью аргумента class_ к sessionmaker:

Session = sessionmaker(class_=RoutingSession)

Этот подход можно объединить с несколькими объектами MetaData, используя подход, подобный тому, что используется декларативное ключевое слово __abstract__, описанное в __abstract__.

Горизонтальные перегородки¶

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

Использование¶

Каждый из методов работает в контексте транзакции объекта Session, как и любой другой:

s = Session()
objects = [User(name="u1"), User(name="u2"), User(name="u3")]
s.bulk_save_objects(objects)

Для Session.bulk_insert_mappings() и Session.bulk_update_mappings() передаются словари:

s.bulk_insert_mappings(User, [dict(name="u1"), dict(name="u2"), dict(name="u3")])

Сравнение с основными конструкциями вставки/обновления¶

Методы bulk обеспечивают производительность, которая при определенных обстоятельствах может быть близка к производительности использования основных конструкций Insert и Update в контексте «executemany» (для описания «executemany» см. раздел Отправка нескольких параметров в учебнике по Core). Для достижения этого флаг Session.bulk_insert_mappings.return_defaults должен быть отключен, чтобы строки можно было объединять в пакет. Набор примеров в Производительность следует внимательно изучить, чтобы понять, насколько быстро можно добиться производительности пакетной обработки.

Совместимость с ORM / предостережения¶

Методы массовой вставки / обновления теряют значительную часть функциональности по сравнению с традиционным использованием ORM. Ниже приведен список функций, которые не доступны при использовании этих методов:

• устойчивость вдоль связей relationship()

• сортировка строк в порядке зависимости; строки вставляются или обновляются непосредственно в том порядке, в котором они передаются в методы

• Управление сессиями на данных объектах, включая прикрепление к сессии, управление картой идентификации.

• Функциональность, связанная с мутацией первичного ключа, каскад ON UPDATE - мутация столбцов первичного ключа не будет работать - поскольку исходное значение PK для каждой строки недоступно, поэтому критерии WHERE не могут быть сгенерированы.

• Вставка/обновление SQL-выражений (например, Встраивание выражений вставки/обновления SQL в промывку) - необходимость их оценки не позволит объединять операторы INSERT и UPDATE в один вызов executemany(), поскольку они изменяют SQL-компиляцию самого оператора.

• События ORM, такие как MapperEvents.before_insert() и т.д. Методы массовых сессий не имеют поддержки событий.

Особенности, которые в наличии включают:

• INSERTs и UPDATEs отображенных объектов

• Поддержка идентификаторов версий

• Многотабличные отображения, такие как объединенное наследование - однако, объект, который будет вставлен в несколько таблиц, должен либо заранее иметь полностью заполненные идентификаторы первичных ключей, либо должен быть использован флаг Session.bulk_save_objects.return_defaults, что значительно снизит преимущества в производительности