ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Уровень модели данных (ORM)

Tip

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

Note

ORM является асинхронным по умолчанию: Все методы CRUD (create / get / save / delete / create_table / операции QuerySet) являются async def, и их можно вызывать с помощью await в цикле событий — базовый драйвер — aiosqlite / aiomysql / asyncpg (в зависимости от хранилища), синхронный блокирующий код отсутствует. Синхронные get/set для хранилища ключ-значение — это совместимый слой, не имеющий отношения к ORM.

Начиная с версии 2.9.0, фреймворк включает декларативный уровень моделей данных: унаследовавшись от Model и объявив поля с помощью Field, вы получаете возможность автоматического создания таблиц и CRUD-операций. Модели строятся на базе встроенного хранилища — SQLite / MySQL / PostgreSQL определяются параметром ErisPulse.storage.backend, переключение хранилища не требует изменения кода моделей.

Декларация моделей

from ErisPulse.Core.Bases import Model, Field

class User(Model):
    id: int = Field(primary_key=True, autoincrement=True)
    name: str = Field(max_length=64)
    age: int = Field(default=0, ge=0, le=150)
    role: str = Field(default="user", choices=["user", "admin"])
    tags: list = Field(default_factory=list)          # JSON-столбец, автоматическая сериализация при чтении/записи
    bio: str = Field(default="", description={"i18n": "user.bio", "default": "Биография"})
  • Имя таблицы по умолчанию — snake_case от имени класса (UserProfile → user_profile), можно переопределить с помощью __tablename__ = "xxx"
  • Параметры ограничений Field идентичны параметрам декларативного класса конфигурации (choices / ge / le / max_length, description поддерживает словарь i18n); движок проверки и конфигурации совпадает

Параметры поля

Параметр Описание
default Значение по умолчанию (обязательно, если не указано и не автоинкремент → NOT NULL)
default_factory Фабрика для изменяемых значений по умолчанию (например, list)
primary_key Первичный ключ (если несколько — составной ключ, объединяется в PRIMARY KEY (a, b) на уровне таблицы)
autoincrement Автоинкрементный первичный ключ (является первичным ключом, значение автоматически возвращается после create; используется только для одного столбца, исключает составной ключ)
max_length Максимальная длина строки (генерирует VARCHAR(n), проверка при записи)
nullable Разрешить NULL (по умолчанию False)
index Создать обычный индекс
unique Уникальное ограничение
choices / ge / le Перечисление / диапазон значений (проверка при записи)
description Описание (словарь i18n, формат аналогичен классу конфигурации)
column_type Переопределить определение типа SQL-столбца
foreign_key Ограничение внешнего ключа на уровне столбца (в формате "таблица.столбец", генерирует REFERENCES)
on_delete Действие при удалении: CASCADE / SET NULL / RESTRICT / NO ACTION / SET DEFAULT
auto_now_add Автоматически записывать текущую метку времени (в секундах с начала эпохи) при вставке
auto_now Автоматически записывать текущую метку времени при вставке и при вызове save() (не срабатывает при пакетном обновлении QuerySet.update)

Составной ключ и совместная уникальность

Несколько полей с primary_key=True образуют составной ключ, get / save / delete определяются по всем столбцам первичного ключа; __unique_together__ объявляет группу совместной уникальности (может быть несколько групп):

class Membership(Model):
    __tablename__ = "memberships"
    __unique_together__ = (("user_id", "group_id"),)

    user_id: int = Field(primary_key=True)
    group_id: int = Field(primary_key=True)
    role: str = Field(default="member")

m = await Membership.get(user_id=1, group_id=2)
  • autoincrement и составной ключ исключают друг друга, при совместном использовании модель не будет создана
  • __unique_together__ реализуется с помощью уникального индекса (uq_ — префикс имени индекса): при создании таблицы индекс создается автоматически, для существующих таблиц create_table() автоматически добавляет индекс, без необходимости пересоздания
  • Модели с составным ключом пока не поддерживают сопоставление отношений (has-many / belongs-to), при попытке доступа будет явная ошибка

Создание таблицы и CRUD

await User.create_table()                      #幂等(IF NOT EXISTS)

user = await User.create(name="Alice", age=20) # Вставка (автоинкрементный первичный ключ автоматически возвращается)
got = await User.get(id=user.id)               # Поиск по значению

users = await User.where(User.age > 18).order_by("-age").limit(10).all()
first = await User.where(User.name == "Alice").first()
total = await User.count(User.age > 18)

user.age = 21
await user.save()                              # Обновление по первичному ключу (сначала проверка ограничений); если первичный ключ отсутствует, переходит в режим вставки (автоинкрементный ключ также возвращается в экземпляр)
await user.save(update_fields=["age"])         # Частичное обновление (белый список, остальные поля не записываются)
await user.delete()                            # Удаление по первичному ключу

user, created = await User.get_or_create({"age": 20}, name="Alice")      # Если найдено — вернуть; если нет — создать
user, created = await User.update_or_create({"age": 21}, name="Alice")   # Если найдено — обновить по defaults и сохранить; если нет — создать

await User.update_all(User.age > 18, role="adult")  # Пакетное обновление
await User.delete_all(User.age > 100)               # Пакетное удаление

Note

get_or_create / update_or_create при одновременном конкурентном доступе могут оба корутины попасть в ветку создания — уникальные ограничения (первичный ключ / unique / __unique_together__) приведут к тому, что последний получит StorageOperationError; при необходимости幂等ной семантики перехватите исключение и выполните повторный запрос.

Выражения запросов поддерживают > >= < <= == != и in_([...]), а также & (и) / | (или) для комбинации:

await User.where((User.age > 18) & User.name.in_(["Alice", "Bob"])).all()

Транзакции

ORM и хранилище фреймворка используют одну и ту же систему маршрутизации транзакций: если внутри storage.atransaction(), create / save / delete и запросы автоматически используют транзакцию, и все действия подчиняются единым commit или rollback, без независимого подтверждения.

async with storage.atransaction():
    await User.create(name="Alice")
    ...  # Если в блоке возникнет исключение, все вышеуказанные INSERT будут откатиться

Связь с декларативным классом конфигурации

Декларация модели и ConfigClass (@dataclass + field(metadata=...)) разделяют один и тот же底层 — словарь ограничений, движок проверки (validate_field_constraints), регистр типов (python_type_category); но базовые классы намеренно разделены: поля конфигурации — обычные значения (TOML-формат, однократная загрузка с горячим обновлением), поля модели — дескрипторы столбцов (доступ к классу = выражение запроса, доступ к экземпляру = значение строки). Одна и та же декларация, два разных базовых класса.

Когда использовать какой тип декларации

Аспект Поля конфигурации field(metadata=...) Поля модели Field()
Сценарий Параметры модуля (малое количество, человекочитаемые, нуждаются в горячем обновлении) Данные бизнес-объектов (много строк, программный доступ, нуждаются в запросах)
Формат хранения config.toml (сохранение комментариев,往返 TOML) Таблицы базы данных (автоматическое создание таблиц, SQL-диалекты)
Формат значения Обычные значения (прямой доступ через свойства dataclass) Дескрипторы (доступ к классу = выражение столбца, доступ к экземпляру = значение строки)
Ограничения metadata={"choices": ..., "min": ..., "max": ...} Field(choices=..., ge=..., le=..., max_length=...)
Общий底层 Движок проверки + словарь ограничений + регистр типов (одинаковые) Тот же

Эмпирическое правило: "как модуль работает" — используйте класс конфигурации, "какие данные создал пользователь" — используйте модель.

Ограничения и замечания

  • Хранилище определяется глобальной конфигурацией; модель может переопределить __storage__ для использования пользовательского экземпляра BaseStorage (для тестирования)
  • Поля list / dict (включая параметризованные типы, например list[int], dict[str, int]) хранятся в виде текста JSON, при чтении и записи автоматически сериализуются
  • При записи (create / save) автоматически выполняется проверка ограничений, при ошибке выбрасывается ValueError (локализованные сообщения)
  • Автоматическое миграция реализуется для сценариев добавления новых столбцов (см. ниже); изменения типа столбца и удаление столбцов требуют ручного вмешательства
  • При сбое подключения к хранилищу поведение соответствует слою хранилища: фреймворк не падает, после охлаждения автоматически переподключается

Автоматическая миграция (этап 2)

create_table() при наличии таблицы автоматически сравнивает существующие столбцы с полями модели: новые поля автоматически выполняют ALTER TABLE ADD COLUMN (удаляется ограничение NOT NULL, заполняются NULL), индекс для новых полей с index=True создается одновременно. Не требуется ручной миграционный скрипт.

# После выхода v1 модели эволюционируют: добавляются поля email / bio
class User(Model):
    __tablename__ = "orm_users"

    id: int = Field(primary_key=True, autoincrement=True)
    name: str = Field(max_length=64)
    age: int = Field(default=0)
    email: str = Field(default="")     # Новое: при следующем create_table() автоматически добавит столбец
    bio: str = Field(default="")

await User.create_table()              #幂等: только миграция новых столбцов

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

Внешние ключи (основа сопоставления отношений)

foreign_key="таблица.столбец" объявляет ограничение внешнего ключа на уровне столбца, DDL генерирует подфразу REFERENCES; on_delete объявляет действие при удалении (например, "CASCADE" — каскадное удаление связанных строк):

class Post(Model):
    __tablename__ = "posts"

    id: int = Field(primary_key=True, autoincrement=True)
    author: int = Field(foreign_key="orm_users.id", on_delete="CASCADE")

    content: str = Field(max_length=255)

Сопоставление отношений (relationship)

В теле класса модели объявляется relationship() в виде атрибута класса, направление определяется автоматически по месту объявления внешнего ключа:

from ErisPulse.Core.Bases import Model, Field, relationship

class User(Model):
    __tablename__ = "orm_users"

    id: int = Field(primary_key=True, autoincrement=True)
    name: str = Field(max_length=64)

    posts = relationship("Post", foreign_key="author")   # Внешний ключ в другой таблице → has-many

class Post(Model):
    __tablename__ = "posts"

    id: int = Field(primary_key=True, autoincrement=True)
    author: int = Field(foreign_key="orm_users.id")
    content: str = Field(max_length=255)

    writer = relationship("User", foreign_key="author")  # Внешний ключ в текущей таблице → belongs-to

has-many: Атрибут экземпляра возвращает набор запросов, доступны все возможности QuerySet, create автоматически возвращает первичный ключ текущей таблицы в столбец внешнего ключа другой таблицы:

alice = await User.get(name="Alice")

posts = await alice.posts.all()                          # Все статьи пользователя
latest = await alice.posts.order_by("-id").first()
total = await alice.posts.count()
hot = await alice.posts.where(Post.content != "").all()  # Дополнительные условия по столбцам другой таблицы
await alice.posts.delete()                               # Удалить только статьи пользователя

new_post = await alice.posts.create(content="hi")        # author автоматически = alice.id

belongs-to: Прямой await возвращает экземпляр другой модели (если нет соответствия или внешний ключ NULL — возвращает None):

post = await Post.get(id=1)
writer = await post.writer          # Экземпляр User или None
await writer.posts.count()          # Двусторонняя связь

Особенности:

  • related принимает строку с именем класса (ленивое разрешение по регистру моделей, порядок определения не имеет значения) или непосредственно модель
  • Запросы отношений и модели используют свои хранилища (не поддерживается JOIN между разными хранилищами — запросы отношений — это отдельные SQL-запросы)
  • Запросы отношений не кэшируются, каждый вызов — это немедленный запрос; для произвольных запросов можно использовать User.where(...)

Далее

Нужно сменить базу данных или развернуть в облаке

  • Хранилище — Настройка и переключение SQLite / MySQL / PostgreSQL, код моделей не требует изменений

Не нужно структуры таблиц, только несколько ключ-значений